From ae4a337241e98d5ff01e70766db2bf251b9f360c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 2 Aug 2026 21:55:30 -0400
Subject: [PATCH 001/256] fix(api): migrate language listings to /v3/languages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GET /v2/languages and GET /v2/glossary-language-pairs are formally
deprecated (2026-05-18); /v3/languages serves both via the resource
parameter. One role-flagged list replaces the per-type and pairs
contracts: source/target lists derive from usable_as_source/
usable_as_target, and glossary pairs from the source×target
cross-product minus identity, which reproduces the v2 pair set exactly
(verified live, 992 pairs, zero difference). The v3 response no longer
reports formality support, so the [F] markers now come from a new
supportsFormality field in the language registry, seeded from the last
v2 target response. Command output is unchanged.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   4 +
 src/api/glossary-client.ts                    |  41 ++++--
 src/api/translation-client.ts                 |  37 ++++--
 src/data/language-registry.ts                 |  27 ++--
 tests/e2e/mock-deepl-server.cjs               |  30 ++---
 tests/helpers/nock-setup.ts                   |  16 +--
 .../deepl-client.integration.test.ts          |  49 +++----
 tests/unit/deepl-client.test.ts               | 124 ++++++++++++------
 tests/unit/glossary-client.test.ts            |  38 +++++-
 tests/unit/language-registry.test.ts          |  26 +++-
 tests/unit/translation-client.test.ts         |  18 ++-
 11 files changed, 269 insertions(+), 141 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 94829214..7c1c8637 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **cli**: `deepl correct` command (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`), but not `--style`/`--tone`, which the correct endpoint does not accept. Results are cached under a separate `correct:` namespace so corrections and rephrasings of the same text never collide.
 
+### Changed
+
+- **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers now come from the language registry since the v3 response no longer reports formality support.
+
 - **http**: `NO_PROXY` / `no_proxy` are honoured, with the standard semantics — `*` for everything, a leading dot or `*.` for subdomains, and an optional `host:port` that must agree. A corporate `HTTPS_PROXY` was previously applied to every request, including one aimed at localhost.
 - **auth**: `deepl auth set-key --no-verify` stores a key without validating it against the API. Validation ran before persisting, so on a network without proxy configuration both documented setup paths — `auth set-key` and `init` — failed and discarded the key; an unreachable API now also names `DEEPL_API_KEY` as the zero-network alternative.
 - **ci**: `npm run check-deps` fails the build when a package imported by `src/` is missing from `dependencies`, including one declared only under `devDependencies`. It runs in CI and in the publish job, and matches package names as quoted strings so indirect loads such as `requireModule('php-parser')` count as references.
diff --git a/src/api/glossary-client.ts b/src/api/glossary-client.ts
index 323d9862..fc7efbfd 100644
--- a/src/api/glossary-client.ts
+++ b/src/api/glossary-client.ts
@@ -2,11 +2,10 @@ import { HttpClient, DeepLClientOptions } from './http-client.js';
 import { Language, GlossaryInfo, GlossaryLanguagePair, normalizeGlossaryInfo, GlossaryApiResponse } from '../types/index.js';
 import { ValidationError } from '../utils/errors.js';
 
-interface DeepLGlossaryLanguagePairsResponse {
-  supported_languages: Array<{
-    source_lang: string;
-    target_lang: string;
-  }>;
+interface DeepLV3GlossaryLanguageResponse {
+  lang: string;
+  usable_as_source?: boolean;
+  usable_as_target?: boolean;
 }
 
 export class GlossaryClient extends HttpClient {
@@ -14,16 +13,36 @@ export class GlossaryClient extends HttpClient {
     super(apiKey, options);
   }
 
+  /**
+   * Lists glossary language pairs via GET /v3/languages?resource=glossary
+   * (the v2 pairs endpoint is deprecated). v3 returns one role-flagged
+   * language list instead of pairs; the source×target cross-product minus
+   * identity reproduces the v2 pair set exactly (verified live: 992 pairs,
+   * zero difference in either direction).
+   */
   async getGlossaryLanguages(): Promise<GlossaryLanguagePair[]> {
-    const response = await this.makeRequest<DeepLGlossaryLanguagePairsResponse>(
+    const response = await this.makeRequest<DeepLV3GlossaryLanguageResponse[]>(
       'GET',
-      '/v2/glossary-language-pairs'
+      '/v3/languages',
+      { resource: 'glossary' }
     );
 
-    return response.supported_languages.map((pair) => ({
-      sourceLang: this.normalizeLanguage(pair.source_lang),
-      targetLang: this.normalizeLanguage(pair.target_lang),
-    }));
+    const sources = response.filter((lang) => lang.usable_as_source);
+    const targets = response.filter((lang) => lang.usable_as_target);
+
+    const pairs: GlossaryLanguagePair[] = [];
+    for (const source of sources) {
+      for (const target of targets) {
+        if (source.lang === target.lang) {
+          continue;
+        }
+        pairs.push({
+          sourceLang: this.normalizeLanguage(source.lang),
+          targetLang: this.normalizeLanguage(target.lang),
+        });
+      }
+    }
+    return pairs;
   }
 
   async createGlossary(
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index 21a62601..aaa31a99 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -2,6 +2,7 @@ import { HttpClient, DeepLClientOptions } from './http-client.js';
 import { TranslationOptions, Language, TranslationMemory } from '../types/index.js';
 import { NetworkError } from '../utils/errors.js';
 import { normalizeFormality } from '../utils/formality.js';
+import { LANGUAGE_REGISTRY } from '../data/language-registry.js';
 import { Logger } from '../utils/logger.js';
 
 // DeepL's /v3/translation_memories endpoint paginates via `page` (0-indexed) and
@@ -43,10 +44,11 @@ interface DeepLUsageResponse {
   }>;
 }
 
-interface DeepLLanguageResponse {
-  language: string;
+interface DeepLV3LanguageResponse {
+  lang: string;
   name: string;
-  supports_formality?: boolean;
+  usable_as_source?: boolean;
+  usable_as_target?: boolean;
 }
 
 export interface TranslationResult {
@@ -273,21 +275,34 @@ export class TranslationClient extends HttpClient {
     }
   }
 
+  /**
+   * Lists languages via GET /v3/languages (v2 is deprecated). One response
+   * carries both roles as usable_as_source/usable_as_target flags, filtered
+   * here to preserve the per-type contract. The v3 response no longer reports
+   * formality support, so that comes from the static language registry.
+   */
   async getSupportedLanguages(
     type: 'source' | 'target'
   ): Promise<LanguageInfo[]> {
     try {
-      const response = await this.makeRequest<DeepLLanguageResponse[]>(
+      const response = await this.makeRequest<DeepLV3LanguageResponse[]>(
         'GET',
-        '/v2/languages',
-        { type }
+        '/v3/languages',
+        { resource: 'translate_text' }
       );
 
-      return response.map((lang) => ({
-        language: this.normalizeLanguage(lang.language),
-        name: lang.name,
-        ...(lang.supports_formality !== undefined && { supportsFormality: lang.supports_formality }),
-      }));
+      return response
+        .filter((lang) => (type === 'source' ? lang.usable_as_source : lang.usable_as_target))
+        .map((lang) => {
+          const code = this.normalizeLanguage(lang.lang);
+          return {
+            language: code,
+            name: lang.name,
+            ...(type === 'target' && {
+              supportsFormality: LANGUAGE_REGISTRY.get(code)?.supportsFormality ?? false,
+            }),
+          };
+        });
     } catch (error) {
       throw this.handleError(error);
     }
diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index 47296ec2..f74024f6 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -24,12 +24,17 @@ export type LanguageCategory = 'core' | 'regional' | 'extended';
  * @property category - Feature-availability tier
  * @property targetOnly - When true, the language can only be used as a translation target
  *   (not as a source). Applies to regional variants like 'en-gb' and 'pt-br'.
+ * @property supportsFormality - When true, the language supports the formality
+ *   parameter as a translation target. Static because GET /v3/languages does not
+ *   report formality support (the v2 endpoint did); values mirror the last
+ *   /v2/languages?type=target response (captured 2026-08-01).
  */
 export interface LanguageEntry {
   code: string;
   name: string;
   category: LanguageCategory;
   targetOnly?: boolean;
+  supportsFormality?: boolean;
 }
 
 const ENTRIES: LanguageEntry[] = [
@@ -38,27 +43,27 @@ const ENTRIES: LanguageEntry[] = [
   { code: 'bg', name: 'Bulgarian', category: 'core' },
   { code: 'cs', name: 'Czech', category: 'core' },
   { code: 'da', name: 'Danish', category: 'core' },
-  { code: 'de', name: 'German', category: 'core' },
+  { code: 'de', name: 'German', category: 'core', supportsFormality: true },
   { code: 'el', name: 'Greek', category: 'core' },
   { code: 'en', name: 'English', category: 'core' },
-  { code: 'es', name: 'Spanish', category: 'core' },
+  { code: 'es', name: 'Spanish', category: 'core', supportsFormality: true },
   { code: 'et', name: 'Estonian', category: 'core' },
   { code: 'fi', name: 'Finnish', category: 'core' },
-  { code: 'fr', name: 'French', category: 'core' },
+  { code: 'fr', name: 'French', category: 'core', supportsFormality: true },
   { code: 'he', name: 'Hebrew', category: 'core' },
   { code: 'hu', name: 'Hungarian', category: 'core' },
   { code: 'id', name: 'Indonesian', category: 'core' },
-  { code: 'it', name: 'Italian', category: 'core' },
-  { code: 'ja', name: 'Japanese', category: 'core' },
+  { code: 'it', name: 'Italian', category: 'core', supportsFormality: true },
+  { code: 'ja', name: 'Japanese', category: 'core', supportsFormality: true },
   { code: 'ko', name: 'Korean', category: 'core' },
   { code: 'lt', name: 'Lithuanian', category: 'core' },
   { code: 'lv', name: 'Latvian', category: 'core' },
   { code: 'nb', name: 'Norwegian Bokmål', category: 'core' },
-  { code: 'nl', name: 'Dutch', category: 'core' },
-  { code: 'pl', name: 'Polish', category: 'core' },
+  { code: 'nl', name: 'Dutch', category: 'core', supportsFormality: true },
+  { code: 'pl', name: 'Polish', category: 'core', supportsFormality: true },
   { code: 'pt', name: 'Portuguese', category: 'core' },
   { code: 'ro', name: 'Romanian', category: 'core' },
-  { code: 'ru', name: 'Russian', category: 'core' },
+  { code: 'ru', name: 'Russian', category: 'core', supportsFormality: true },
   { code: 'sk', name: 'Slovak', category: 'core' },
   { code: 'sl', name: 'Slovenian', category: 'core' },
   { code: 'sv', name: 'Swedish', category: 'core' },
@@ -70,9 +75,9 @@ const ENTRIES: LanguageEntry[] = [
   // Regional variants (target-only)
   { code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true },
   { code: 'en-us', name: 'English (American)', category: 'regional', targetOnly: true },
-  { code: 'es-419', name: 'Spanish (Latin America)', category: 'regional', targetOnly: true },
-  { code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true },
-  { code: 'pt-pt', name: 'Portuguese (European)', category: 'regional', targetOnly: true },
+  { code: 'es-419', name: 'Spanish (Latin America)', category: 'regional', targetOnly: true, supportsFormality: true },
+  { code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true, supportsFormality: true },
+  { code: 'pt-pt', name: 'Portuguese (European)', category: 'regional', targetOnly: true, supportsFormality: true },
   { code: 'zh-hans', name: 'Chinese (Simplified)', category: 'regional', targetOnly: true },
   { code: 'zh-hant', name: 'Chinese (Traditional)', category: 'regional', targetOnly: true },
 
diff --git a/tests/e2e/mock-deepl-server.cjs b/tests/e2e/mock-deepl-server.cjs
index 30ce5f26..5c96f69a 100644
--- a/tests/e2e/mock-deepl-server.cjs
+++ b/tests/e2e/mock-deepl-server.cjs
@@ -201,27 +201,15 @@ function handleRequest(req, res, body) {
     return;
   }
 
-  if (method === 'GET' && url.startsWith('/v2/languages')) {
-    const parsedUrl = new URL(url, 'http://127.0.0.1');
-    const type = parsedUrl.searchParams.get('type');
-
-    var languages;
-    if (type === 'source') {
-      languages = [
-        { language: 'EN', name: 'English' },
-        { language: 'DE', name: 'German' },
-        { language: 'FR', name: 'French' },
-        { language: 'ES', name: 'Spanish' },
-      ];
-    } else {
-      languages = [
-        { language: 'EN-US', name: 'English (American)', supports_formality: false },
-        { language: 'EN-GB', name: 'English (British)', supports_formality: false },
-        { language: 'DE', name: 'German', supports_formality: true },
-        { language: 'FR', name: 'French', supports_formality: true },
-        { language: 'ES', name: 'Spanish', supports_formality: true },
-      ];
-    }
+  if (method === 'GET' && url.startsWith('/v3/languages')) {
+    var languages = [
+      { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
+      { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+      { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
+      { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
+      { lang: 'en-us', name: 'English (American)', usable_as_source: false, usable_as_target: true },
+      { lang: 'en-gb', name: 'English (British)', usable_as_source: false, usable_as_target: true },
+    ];
 
     res.writeHead(200);
     res.end(JSON.stringify(languages));
diff --git a/tests/helpers/nock-setup.ts b/tests/helpers/nock-setup.ts
index 1f86ed13..509f2f1b 100644
--- a/tests/helpers/nock-setup.ts
+++ b/tests/helpers/nock-setup.ts
@@ -41,17 +41,17 @@ export function mockAuthError(scope: nock.Scope): nock.Scope {
 
 export function mockLanguagesResponse(
   scope: nock.Scope,
-  languages: Array<{ language: string; name: string; supports_formality?: boolean }> = [
-    { language: 'DE', name: 'German', supports_formality: true },
-    { language: 'EN', name: 'English', supports_formality: false },
-    { language: 'ES', name: 'Spanish', supports_formality: true },
-    { language: 'FR', name: 'French', supports_formality: true },
+  languages: Array<{ lang: string; name: string; usable_as_source?: boolean; usable_as_target?: boolean }> = [
+    { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+    { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
+    { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
+    { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
   ],
-  type: 'source' | 'target' = 'target',
+  resource: string = 'translate_text',
 ): nock.Scope {
   return scope
-    .get('/v2/languages')
-    .query({ type })
+    .get('/v3/languages')
+    .query({ resource })
     .reply(200, languages);
 }
 
diff --git a/tests/integration/deepl-client.integration.test.ts b/tests/integration/deepl-client.integration.test.ts
index 2b15bc15..581ceb7e 100644
--- a/tests/integration/deepl-client.integration.test.ts
+++ b/tests/integration/deepl-client.integration.test.ts
@@ -487,16 +487,17 @@ describe('DeepLClient Integration', () => {
   });
 
   describe('getSupportedLanguages()', () => {
-    it('should make correct HTTP GET request for source languages', async () => {
+    it('should make correct HTTP GET request and filter source languages', async () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
       const scope = nock(FREE_API_URL)
-        .get('/v2/languages')
-        .query({ type: 'source' })
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
         .reply(200, [
-          { language: 'EN', name: 'English' },
-          { language: 'DE', name: 'German' },
+          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+          { lang: 'en-gb', name: 'English (British)', usable_as_source: false, usable_as_target: true },
         ]);
 
       const result = await client.getSupportedLanguages('source');
@@ -508,23 +509,23 @@ describe('DeepLClient Integration', () => {
       expect(scope.isDone()).toBe(true);
     });
 
-    it('should make correct HTTP GET request for target languages', async () => {
+    it('should filter target languages from the same response shape', async () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
       const scope = nock(FREE_API_URL)
-        .get('/v2/languages')
-        .query({ type: 'target' })
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
         .reply(200, [
-          { language: 'ES', name: 'Spanish' },
-          { language: 'FR', name: 'French' },
+          { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
+          { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
         ]);
 
       const result = await client.getSupportedLanguages('target');
 
       expect(result).toEqual([
-        { language: 'es', name: 'Spanish' },
-        { language: 'fr', name: 'French' },
+        { language: 'es', name: 'Spanish', supportsFormality: true },
+        { language: 'fr', name: 'French', supportsFormality: true },
       ]);
       expect(scope.isDone()).toBe(true);
     });
@@ -534,25 +535,25 @@ describe('DeepLClient Integration', () => {
       clients.push(client);
 
       nock(FREE_API_URL)
-        .get('/v2/languages')
-        .query({ type: 'source' })
-        .reply(200, [{ language: 'EN-US', name: 'English (American)' }]);
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
+        .reply(200, [{ lang: 'EN-US', name: 'English (American)', usable_as_source: true }]);
 
       const result = await client.getSupportedLanguages('source');
 
       expect(result[0]?.language).toBe('en-us');
     });
 
-    it('should parse supports_formality for target languages', async () => {
+    it('should source formality support from the registry for targets', async () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
       nock(FREE_API_URL)
-        .get('/v2/languages')
-        .query({ type: 'target' })
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
         .reply(200, [
-          { language: 'DE', name: 'German', supports_formality: true },
-          { language: 'EN-US', name: 'English (American)', supports_formality: false },
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+          { lang: 'en-us', name: 'English (American)', usable_as_source: false, usable_as_target: true },
         ]);
 
       const result = await client.getSupportedLanguages('target');
@@ -561,14 +562,14 @@ describe('DeepLClient Integration', () => {
       expect(result[1]?.supportsFormality).toBe(false);
     });
 
-    it('should omit supportsFormality when not in response', async () => {
+    it('should omit supportsFormality for source languages', async () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
       nock(FREE_API_URL)
-        .get('/v2/languages')
-        .query({ type: 'source' })
-        .reply(200, [{ language: 'EN', name: 'English' }]);
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
+        .reply(200, [{ lang: 'en', name: 'English', usable_as_source: true }]);
 
       const result = await client.getSupportedLanguages('source');
 
diff --git a/tests/unit/deepl-client.test.ts b/tests/unit/deepl-client.test.ts
index cc66a25c..39939bb5 100644
--- a/tests/unit/deepl-client.test.ts
+++ b/tests/unit/deepl-client.test.ts
@@ -812,11 +812,12 @@ describe('DeepLClient', () => {
   describe('getSupportedLanguages()', () => {
     it('should return supported source languages', async () => {
       nock(baseUrl)
-        .get('/v2/languages')
-        .query({ type: 'source' })
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
         .reply(200, [
-          { language: 'EN', name: 'English' },
-          { language: 'ES', name: 'Spanish' },
+          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
+          { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
+          { lang: 'en-gb', name: 'English (British)', usable_as_source: false, usable_as_target: true },
         ]);
 
       const languages = await client.getSupportedLanguages('source');
@@ -824,15 +825,16 @@ describe('DeepLClient', () => {
       expect(languages).toHaveLength(2);
       expect(languages[0]?.language).toBe('en');
       expect(languages[0]?.name).toBe('English');
+      expect(languages[0]?.supportsFormality).toBeUndefined();
     });
 
     it('should return supported target languages', async () => {
       nock(baseUrl)
-        .get('/v2/languages')
-        .query({ type: 'target' })
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
         .reply(200, [
-          { language: 'ES', name: 'Spanish' },
-          { language: 'FR', name: 'French' },
+          { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
+          { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
         ]);
 
       const languages = await client.getSupportedLanguages('target');
@@ -841,10 +843,42 @@ describe('DeepLClient', () => {
       expect(languages[0]?.language).toBe('es');
     });
 
+    it('should exclude source-only languages from target results', async () => {
+      nock(baseUrl)
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
+        .reply(200, [
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+          { lang: 'xx', name: 'Source Only', usable_as_source: true, usable_as_target: false },
+        ]);
+
+      const languages = await client.getSupportedLanguages('target');
+
+      expect(languages).toHaveLength(1);
+      expect(languages[0]?.language).toBe('de');
+    });
+
+    it('should mark formality support on targets from the registry', async () => {
+      nock(baseUrl)
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
+        .reply(200, [
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+          { lang: 'ja', name: 'Japanese', usable_as_source: true, usable_as_target: true },
+          { lang: 'ko', name: 'Korean', usable_as_source: true, usable_as_target: true },
+        ]);
+
+      const languages = await client.getSupportedLanguages('target');
+
+      expect(languages.find(l => l.language === 'de')?.supportsFormality).toBe(true);
+      expect(languages.find(l => l.language === 'ja')?.supportsFormality).toBe(true);
+      expect(languages.find(l => l.language === 'ko')?.supportsFormality).toBe(false);
+    });
+
     it('should handle language API errors', async () => {
       nock(baseUrl)
-        .get('/v2/languages')
-        .query({ type: 'source' })
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
         .reply(500);
 
       await expect(
@@ -1891,50 +1925,59 @@ describe('DeepLClient', () => {
   });
 
   describe('getGlossaryLanguages()', () => {
-    it('should return supported glossary language pairs', async () => {
+    it('should derive pairs as the cross-product minus identity', async () => {
       nock(baseUrl)
-        .get('/v2/glossary-language-pairs')
-        .reply(200, {
-          supported_languages: [
-            { source_lang: 'en', target_lang: 'de' },
-            { source_lang: 'de', target_lang: 'en' },
-            { source_lang: 'en', target_lang: 'fr' },
-          ],
-        });
+        .get('/v3/languages')
+        .query({ resource: 'glossary' })
+        .reply(200, [
+          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+          { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
+        ]);
+
+      const pairs = await client.getGlossaryLanguages();
+
+      // 3 languages, both roles each: 3×3 minus 3 identity pairs
+      expect(pairs).toHaveLength(6);
+      expect(pairs).toContainEqual({ sourceLang: 'en', targetLang: 'de' });
+      expect(pairs).toContainEqual({ sourceLang: 'de', targetLang: 'en' });
+      expect(pairs).toContainEqual({ sourceLang: 'en', targetLang: 'fr' });
+      expect(pairs).not.toContainEqual({ sourceLang: 'en', targetLang: 'en' });
+    });
+
+    it('should respect role flags when building pairs', async () => {
+      nock(baseUrl)
+        .get('/v3/languages')
+        .query({ resource: 'glossary' })
+        .reply(200, [
+          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
+          { lang: 'xx', name: 'Target Only', usable_as_source: false, usable_as_target: true },
+        ]);
 
       const pairs = await client.getGlossaryLanguages();
 
-      expect(pairs).toHaveLength(3);
-      expect(pairs[0]?.sourceLang).toBe('en');
-      expect(pairs[0]?.targetLang).toBe('de');
-      expect(pairs[1]?.sourceLang).toBe('de');
-      expect(pairs[1]?.targetLang).toBe('en');
+      expect(pairs).toEqual([{ sourceLang: 'en', targetLang: 'xx' }]);
     });
 
     it('should normalize language codes to lowercase', async () => {
       nock(baseUrl)
-        .get('/v2/glossary-language-pairs')
-        .reply(200, {
-          supported_languages: [
-            { source_lang: 'EN', target_lang: 'DE' },
-            { source_lang: 'EN-US', target_lang: 'ES' },
-          ],
-        });
+        .get('/v3/languages')
+        .query({ resource: 'glossary' })
+        .reply(200, [
+          { lang: 'EN', name: 'English', usable_as_source: true, usable_as_target: false },
+          { lang: 'DE', name: 'German', usable_as_source: false, usable_as_target: true },
+        ]);
 
       const pairs = await client.getGlossaryLanguages();
 
-      expect(pairs[0]?.sourceLang).toBe('en');
-      expect(pairs[0]?.targetLang).toBe('de');
-      expect(pairs[1]?.sourceLang).toBe('en-us');
-      expect(pairs[1]?.targetLang).toBe('es');
+      expect(pairs).toEqual([{ sourceLang: 'en', targetLang: 'de' }]);
     });
 
     it('should handle empty response', async () => {
       nock(baseUrl)
-        .get('/v2/glossary-language-pairs')
-        .reply(200, {
-          supported_languages: [],
-        });
+        .get('/v3/languages')
+        .query({ resource: 'glossary' })
+        .reply(200, []);
 
       const pairs = await client.getGlossaryLanguages();
 
@@ -1943,7 +1986,8 @@ describe('DeepLClient', () => {
 
     it('should handle API errors', async () => {
       nock(baseUrl)
-        .get('/v2/glossary-language-pairs')
+        .get('/v3/languages')
+        .query({ resource: 'glossary' })
         .reply(403, {
           message: 'Authentication failed',
         });
diff --git a/tests/unit/glossary-client.test.ts b/tests/unit/glossary-client.test.ts
index af5ec197..a036daac 100644
--- a/tests/unit/glossary-client.test.ts
+++ b/tests/unit/glossary-client.test.ts
@@ -41,14 +41,13 @@ describe('GlossaryClient', () => {
   });
 
   describe('getGlossaryLanguages()', () => {
-    it('should return supported glossary language pairs', async () => {
+    it('should derive language pairs from the v3 role-flagged list', async () => {
       mockAxiosInstance.request.mockResolvedValue({
-        data: {
-          supported_languages: [
-            { source_lang: 'EN', target_lang: 'DE' },
-            { source_lang: 'EN', target_lang: 'FR' },
-          ],
-        },
+        data: [
+          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: false },
+          { lang: 'de', name: 'German', usable_as_source: false, usable_as_target: true },
+          { lang: 'fr', name: 'French', usable_as_source: false, usable_as_target: true },
+        ],
         status: 200,
         headers: {},
       });
@@ -59,6 +58,31 @@ describe('GlossaryClient', () => {
         { sourceLang: 'en', targetLang: 'de' },
         { sourceLang: 'en', targetLang: 'fr' },
       ]);
+      expect(mockAxiosInstance.request).toHaveBeenCalledWith(
+        expect.objectContaining({
+          method: 'GET',
+          url: '/v3/languages',
+          params: { resource: 'glossary' },
+        }),
+      );
+    });
+
+    it('should exclude identity pairs', async () => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: [
+          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+        ],
+        status: 200,
+        headers: {},
+      });
+
+      const result = await client.getGlossaryLanguages();
+
+      expect(result).toEqual([
+        { sourceLang: 'en', targetLang: 'de' },
+        { sourceLang: 'de', targetLang: 'en' },
+      ]);
     });
 
     it('should handle API errors', async () => {
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index 47624feb..3926add9 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -66,13 +66,13 @@ describe('Language Registry', () => {
   describe('specific language entries', () => {
     it('should include known core languages', () => {
       expect(LANGUAGE_REGISTRY.get('en')).toEqual({ code: 'en', name: 'English', category: 'core' });
-      expect(LANGUAGE_REGISTRY.get('de')).toEqual({ code: 'de', name: 'German', category: 'core' });
-      expect(LANGUAGE_REGISTRY.get('ja')).toEqual({ code: 'ja', name: 'Japanese', category: 'core' });
+      expect(LANGUAGE_REGISTRY.get('de')).toEqual({ code: 'de', name: 'German', category: 'core', supportsFormality: true });
+      expect(LANGUAGE_REGISTRY.get('ja')).toEqual({ code: 'ja', name: 'Japanese', category: 'core', supportsFormality: true });
     });
 
     it('should include known regional variants', () => {
       expect(LANGUAGE_REGISTRY.get('en-gb')).toEqual({ code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true });
-      expect(LANGUAGE_REGISTRY.get('pt-br')).toEqual({ code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true });
+      expect(LANGUAGE_REGISTRY.get('pt-br')).toEqual({ code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true, supportsFormality: true });
     });
 
     it('should include known extended languages', () => {
@@ -217,4 +217,24 @@ describe('Language Registry', () => {
       expect(codes.has('en-gb')).toBe(false);
     });
   });
+
+  describe('supportsFormality', () => {
+    it('should mark the formality-capable languages', () => {
+      for (const code of ['de', 'es', 'es-419', 'fr', 'it', 'ja', 'nl', 'pl', 'pt-br', 'pt-pt', 'ru']) {
+        expect(LANGUAGE_REGISTRY.get(code)?.supportsFormality).toBe(true);
+      }
+    });
+
+    it('should leave non-formality languages unmarked', () => {
+      for (const code of ['en', 'en-us', 'ko', 'zh', 'ar', 'ace']) {
+        expect(LANGUAGE_REGISTRY.get(code)?.supportsFormality).toBeUndefined();
+      }
+    });
+
+    it('should never mark an extended language', () => {
+      getExtendedLanguageCodes().forEach(code => {
+        expect(LANGUAGE_REGISTRY.get(code)?.supportsFormality).toBeUndefined();
+      });
+    });
+  });
 });
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index 3952e2e2..a6128519 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -328,8 +328,9 @@ describe('TranslationClient', () => {
     it('should return source languages', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [
-          { language: 'EN', name: 'English' },
-          { language: 'DE', name: 'German', supports_formality: true },
+          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+          { lang: 'en-gb', name: 'English (British)', usable_as_source: false, usable_as_target: true },
         ],
         status: 200,
         headers: {},
@@ -340,13 +341,19 @@ describe('TranslationClient', () => {
       expect(result).toHaveLength(2);
       expect(result[0]!.language).toBe('en');
       expect(result[0]!.name).toBe('English');
-      expect(result[1]!.supportsFormality).toBe(true);
+      expect(mockAxiosInstance.request).toHaveBeenCalledWith(
+        expect.objectContaining({
+          method: 'GET',
+          url: '/v3/languages',
+          params: { resource: 'translate_text' },
+        }),
+      );
     });
 
-    it('should return target languages', async () => {
+    it('should return target languages with registry-sourced formality', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [
-          { language: 'ES', name: 'Spanish', supports_formality: true },
+          { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
         ],
         status: 200,
         headers: {},
@@ -356,6 +363,7 @@ describe('TranslationClient', () => {
 
       expect(result).toHaveLength(1);
       expect(result[0]!.language).toBe('es');
+      expect(result[0]!.supportsFormality).toBe(true);
     });
   });
 

From e3520a5cffdfed865b2a31dbbeb004d2925c4f86 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 2 Aug 2026 22:43:43 -0400
Subject: [PATCH 002/256] feat(cli)!: remove retired enable_beta_languages flag
 and dead usage fields
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

BREAKING CHANGE: --enable-beta-languages is removed from translate. The
API deprecated the parameter with "has no effect" — beta languages are
part of the regular language set — so the flag had become a silent
no-op; scripts passing it now exit with an unknown-option error.

Also removes the always-zero speech_to_text_milliseconds_count/_limit
handling from GET /v2/usage: the dedicated Speech-to-Text section and
table row could only ever display zero. Voice usage stays visible in
the Product Breakdown, which reads the live per-product minutes data.
The Admin API's per-key speech_to_text_milliseconds usage limit is a
different, still-current field and is untouched.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  5 ++
 README.md                                     |  3 -
 docs/API.md                                   |  1 -
 examples/29-advanced-translate.sh             | 18 +----
 src/api/document-client.ts                    |  3 -
 src/api/translation-client.ts                 | 13 ----
 src/cli/commands/register-translate.ts        |  2 -
 .../translate/text-translation-handler.ts     |  3 -
 src/cli/commands/translate/types.ts           |  1 -
 src/cli/commands/usage.ts                     | 31 --------
 src/types/api.ts                              |  2 -
 .../cli-translate.integration.test.ts         | 23 ++----
 tests/unit/deepl-client-document.test.ts      | 30 +-------
 tests/unit/deepl-client.test.ts               | 75 ++-----------------
 tests/unit/translation-client.test.ts         |  4 -
 tests/unit/translation-service.test.ts        | 13 ----
 tests/unit/usage-command.test.ts              | 55 ++------------
 17 files changed, 27 insertions(+), 255 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7c1c8637..6b906e60 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers now come from the language registry since the v3 response no longer reports formality support.
 
+### Removed
+
+- **cli**: **BREAKING**: The `--enable-beta-languages` flag on `translate` is gone. The API deprecated the underlying `enable_beta_languages` parameter with "has no effect" — beta languages are simply part of the regular language set now — so the flag had become a silent no-op. Scripts passing it will exit with an unknown-option error; remove the flag.
+- **usage**: The dedicated "Speech-to-Text Usage" section (text output) and "Speech-to-text" row (table output) are gone, along with the `speechToTextMilliseconds*` fields they read. The API deprecated `speech_to_text_milliseconds_count`/`_limit` on `GET /v2/usage` ("Always returns 0"), so the section could only ever display zero. Voice usage remains visible in the Product Breakdown, which reads the live per-product minutes data. The Admin API's per-key `speech_to_text_milliseconds` usage limit is a different, still-current field and is unaffected.
+
 - **http**: `NO_PROXY` / `no_proxy` are honoured, with the standard semantics — `*` for everything, a leading dot or `*.` for subdomains, and an optional `host:port` that must agree. A corporate `HTTPS_PROXY` was previously applied to every request, including one aimed at localhost.
 - **auth**: `deepl auth set-key --no-verify` stores a key without validating it against the API. Validation ran before persisting, so on a network without proxy configuration both documented setup paths — `auth set-key` and `init` — failed and discarded the key; an unreachable API now also names `DEEPL_API_KEY` as the zero-network alternative.
 - **ci**: `npm run check-deps` fails the build when a package imported by `src/` is missing from `dependencies`, including one declared only under `devDependencies`. It runs in CI and in the publish job, and matches package names as quoted strings so indirect loads such as `requireModule('php-parser')` count as references.
diff --git a/README.md b/README.md
index c09aba58..4327076d 100644
--- a/README.md
+++ b/README.md
@@ -533,9 +533,6 @@ deepl translate "Cost analysis" --to es,fr,de --format table --show-billed-chara
 # Preview what would be translated without making API calls (file/directory mode)
 deepl translate ./docs --to es --dry-run
 
-# Include beta languages that are not yet stable
-deepl translate "Hello" --to my --enable-beta-languages
-
 # Specify tag handling version (v2 improves structure handling, requires --tag-handling)
 deepl translate page.html --to es --tag-handling html --tag-handling-version v2
 
diff --git a/docs/API.md b/docs/API.md
index b8995b50..cae4895a 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -256,7 +256,6 @@ Translate text directly, from stdin, from files, or entire directories. Supports
 - `--tm-threshold N` - Minimum match score 0–100 (default 75, requires `--translation-memory`). Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
 - `--custom-instruction INSTRUCTION` - Custom instruction for translation (repeatable, max 10, max 300 chars each). Forces `quality_optimized` model. Cannot be used with `latency_optimized`.
 - `--style-id UUID` - Style rule ID for translation (Pro API only). Forces `quality_optimized` model. Cannot be used with `latency_optimized`. Use `deepl style-rules list` to see available IDs.
-- `--enable-beta-languages` - Include beta languages that are not yet stable (forward-compatibility with new DeepL languages)
 - `--no-cache` - Bypass cache for this translation (useful for testing/forcing fresh translation)
 - `--dry-run` - Show what would be translated without performing the operation
 
diff --git a/examples/29-advanced-translate.sh b/examples/29-advanced-translate.sh
index 0b8777ee..4054c948 100755
--- a/examples/29-advanced-translate.sh
+++ b/examples/29-advanced-translate.sh
@@ -54,17 +54,11 @@ echo "  --tag-handling-version v2   Improved structure handling"
 echo "  (requires --tag-handling xml or --tag-handling html)"
 echo
 
-# Example 2: Beta languages
-echo "=== 2. Beta Languages ==="
+# Example 2: Listing languages
+echo "=== 2. Listing Languages ==="
 echo
 
-echo "Include beta languages that are not yet stable:"
-echo "  deepl translate 'Hello world' --to ar --enable-beta-languages"
-echo
-echo "Beta languages may have lower quality but provide forward-compatibility"
-echo "as DeepL adds support for new languages."
-echo
-echo "List available languages (including beta):"
+echo "List available languages:"
 echo "  deepl languages --source"
 echo "  deepl languages --target"
 echo
@@ -151,8 +145,7 @@ EOF
 echo "Combining multiple advanced flags:"
 echo "  deepl translate complex.html --to de \\"
 echo "    --tag-handling html --tag-handling-version v2 \\"
-echo "    --formality more --preserve-code \\"
-echo "    --enable-beta-languages"
+echo "    --formality more --preserve-code"
 echo
 deepl translate "$TEMP_DIR/complex.html" --to de --tag-handling html --tag-handling-version v2 --formality more --preserve-code --output "$TEMP_DIR/complex.de.html"
 echo
@@ -166,9 +159,6 @@ echo "Tag handling:"
 echo "  --tag-handling <xml|html>          Enable tag handling mode"
 echo "  --tag-handling-version <v1|v2>     Tag handling version (v2 = improved)"
 echo
-echo "Beta languages:"
-echo "  --enable-beta-languages            Include unstable/beta languages"
-echo
 echo "API endpoint:"
 echo "  --api-url <url>                    Custom API endpoint URL"
 echo
diff --git a/src/api/document-client.ts b/src/api/document-client.ts
index 6849094b..9e52804f 100644
--- a/src/api/document-client.ts
+++ b/src/api/document-client.ts
@@ -67,9 +67,6 @@ export class DocumentClient extends HttpClient {
           if (options.enableDocumentMinification) {
             formData.append('enable_document_minification', '1');
           }
-          if (options.enableBetaLanguages) {
-            formData.append('enable_beta_languages', '1');
-          }
 
           return {
             data: formData,
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index aaa31a99..97cb47d6 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -30,8 +30,6 @@ interface DeepLUsageResponse {
   api_key_unit_limit?: number;
   account_unit_count?: number;
   account_unit_limit?: number;
-  speech_to_text_milliseconds_count?: number;
-  speech_to_text_milliseconds_limit?: number;
   start_time?: string;
   end_time?: string;
   products?: Array<{
@@ -86,8 +84,6 @@ export interface UsageInfo {
   apiKeyUnitLimit?: number;
   accountUnitCount?: number;
   accountUnitLimit?: number;
-  speechToTextMillisecondsCount?: number;
-  speechToTextMillisecondsLimit?: number;
   startTime?: string;
   endTime?: string;
   products?: ProductUsage[];
@@ -201,12 +197,6 @@ export class TranslationClient extends HttpClient {
       if (response.end_time) {
         usage.endTime = response.end_time;
       }
-      if (response.speech_to_text_milliseconds_count !== undefined) {
-        usage.speechToTextMillisecondsCount = response.speech_to_text_milliseconds_count;
-      }
-      if (response.speech_to_text_milliseconds_limit !== undefined) {
-        usage.speechToTextMillisecondsLimit = response.speech_to_text_milliseconds_limit;
-      }
       if (response.api_key_unit_count !== undefined) {
         usage.apiKeyUnitCount = response.api_key_unit_count;
       }
@@ -387,9 +377,6 @@ export class TranslationClient extends HttpClient {
       params['tag_handling_version'] = options.tagHandlingVersion;
     }
 
-    if (options.enableBetaLanguages) {
-      params['enable_beta_languages'] = '1';
-    }
 
     return params;
   }
diff --git a/src/cli/commands/register-translate.ts b/src/cli/commands/register-translate.ts
index 9e0c56f4..da6c6c75 100644
--- a/src/cli/commands/register-translate.ts
+++ b/src/cli/commands/register-translate.ts
@@ -67,7 +67,6 @@ export function registerTranslate(
     .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json', 'table']).default('text'))
     .option('--show-billed-characters', 'Request and display actual billed character count for cost transparency')
     .optionsGroup('Advanced:')
-    .option('--enable-beta-languages', 'Include beta languages that are not yet stable (forward-compatibility)')
     .option('--no-cache', 'Bypass cache for this translation (useful for testing)')
     .option('--api-url <url>', 'Custom API endpoint (e.g., https://api-free.deepl.com/v2 or internal test URLs)')
     .addHelpText('after', `
@@ -109,7 +108,6 @@ Examples:
       tmThreshold?: number;
       customInstruction?: string[];
       styleId?: string;
-      enableBetaLanguages?: boolean;
       format?: string;
       apiUrl?: string;
       dryRun?: boolean;
diff --git a/src/cli/commands/translate/text-translation-handler.ts b/src/cli/commands/translate/text-translation-handler.ts
index 8597ccbe..0c36e9c1 100644
--- a/src/cli/commands/translate/text-translation-handler.ts
+++ b/src/cli/commands/translate/text-translation-handler.ts
@@ -137,9 +137,6 @@ export class TextTranslationHandler {
       translationOptions.tagHandlingVersion = options.tagHandlingVersion;
     }
 
-    if (options.enableBetaLanguages) {
-      translationOptions.enableBetaLanguages = true;
-    }
 
     const result = await this.ctx.translationService.translate(
       text,
diff --git a/src/cli/commands/translate/types.ts b/src/cli/commands/translate/types.ts
index 7f4f510d..ff2e8343 100644
--- a/src/cli/commands/translate/types.ts
+++ b/src/cli/commands/translate/types.ts
@@ -32,7 +32,6 @@ export interface TranslateOptions {
   tmThreshold?: number;
   customInstruction?: string[];
   styleId?: string;
-  enableBetaLanguages?: boolean;
   tagHandlingVersion?: string;
   cache?: boolean;
   format?: string;
diff --git a/src/cli/commands/usage.ts b/src/cli/commands/usage.ts
index 606bd8e9..dba29db0 100644
--- a/src/cli/commands/usage.ts
+++ b/src/cli/commands/usage.ts
@@ -103,27 +103,6 @@ export class UsageCommand {
       lines.push(`  Used: ${formatNumber(usage.apiKeyCharacterCount)} / ${limitStr}`);
     }
 
-    if (usage.speechToTextMillisecondsCount !== undefined) {
-      const sttCount = usage.speechToTextMillisecondsCount;
-      const sttLimit = usage.speechToTextMillisecondsLimit ?? 0;
-      const sttPercentage = sttLimit > 0
-        ? ((sttCount / sttLimit) * 100).toFixed(1)
-        : '0.0';
-      const sttRemaining = sttLimit - sttCount;
-      const isHighStt = sttLimit > 0 && (sttCount / sttLimit) > 0.8;
-
-      lines.push('');
-      lines.push(chalk.bold('Speech-to-Text Usage:'));
-      const sttColor = isHighStt ? chalk.yellow : chalk.green;
-      lines.push(`  Used: ${sttColor(this.formatMilliseconds(sttCount))} / ${this.formatMilliseconds(sttLimit)} (${sttColor(sttPercentage + '%')})`);
-      lines.push(`  Remaining: ${this.formatMilliseconds(sttRemaining)}`);
-
-      if (isHighStt) {
-        lines.push('');
-        lines.push(chalk.yellow('Warning: You are approaching your speech-to-text limit'));
-      }
-    }
-
     if (usage.products && usage.products.length > 0) {
       lines.push('');
       lines.push(chalk.bold('Product Breakdown:'));
@@ -207,16 +186,6 @@ export class UsageCommand {
       ]);
     }
 
-    if (usage.speechToTextMillisecondsCount !== undefined) {
-      const sttLimit = usage.speechToTextMillisecondsLimit ?? 0;
-      table.push([
-        'Speech-to-text',
-        this.formatMilliseconds(usage.speechToTextMillisecondsCount),
-        sttLimit === 0 ? 'unlimited' : this.formatMilliseconds(sttLimit),
-        pct(usage.speechToTextMillisecondsCount, sttLimit),
-      ]);
-    }
-
     let output = table.toString();
 
     if (usage.products && usage.products.length > 0) {
diff --git a/src/types/api.ts b/src/types/api.ts
index ce08378a..a69538c3 100644
--- a/src/types/api.ts
+++ b/src/types/api.ts
@@ -30,7 +30,6 @@ export interface TranslationOptions {
   customInstructions?: string[];
   styleId?: string;
   tagHandlingVersion?: 'v1' | 'v2';
-  enableBetaLanguages?: boolean;
 }
 
 export interface TranslationMemory {
@@ -134,7 +133,6 @@ export interface DocumentTranslationOptions {
   glossaryId?: string;
   outputFormat?: DocumentOutputFormat;
   enableDocumentMinification?: boolean;
-  enableBetaLanguages?: boolean;
 }
 
 // Glossary Types
diff --git a/tests/integration/cli-translate.integration.test.ts b/tests/integration/cli-translate.integration.test.ts
index af2217f4..33065663 100644
--- a/tests/integration/cli-translate.integration.test.ts
+++ b/tests/integration/cli-translate.integration.test.ts
@@ -718,13 +718,13 @@ describe('Translate CLI Integration', () => {
     });
   });
 
-  describe('--enable-beta-languages flag', () => {
-    it('should show --enable-beta-languages in help text', () => {
+  describe('--enable-beta-languages flag (removed)', () => {
+    it('should not appear in help text', () => {
       const result = translateHelp;
-      expect(result).toContain('--enable-beta-languages');
+      expect(result).not.toContain('--enable-beta-languages');
     });
 
-    it('should accept --enable-beta-languages flag', () => {
+    it('should be rejected as an unknown option', () => {
       expect.assertions(1);
       try {
         runCLI('deepl translate "Hello" --to es --enable-beta-languages', {
@@ -732,20 +732,7 @@ describe('Translate CLI Integration', () => {
         });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-
-    it('should accept --enable-beta-languages with other options', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl translate "Hello" --to es --enable-beta-languages --formality more',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
+        expect(output).toMatch(/unknown.*option/i);
       }
     });
   });
diff --git a/tests/unit/deepl-client-document.test.ts b/tests/unit/deepl-client-document.test.ts
index 64e6c17b..ed1c206a 100644
--- a/tests/unit/deepl-client-document.test.ts
+++ b/tests/unit/deepl-client-document.test.ts
@@ -178,35 +178,7 @@ describe('DeepLClient - Document Translation', () => {
       );
     });
 
-    it('should include enable_beta_languages parameter when enabled', async () => {
-      const mockResponse = {
-        data: {
-          document_id: 'doc-id',
-          document_key: 'doc-key',
-        },
-      };
-
-      mockAxiosInstance.request.mockResolvedValue(mockResponse);
-
-      const fileBuffer = Buffer.from('test content');
-      await client.uploadDocument(fileBuffer, {
-        targetLang: 'es',
-        filename: 'document.pdf',
-        enableBetaLanguages: true,
-      });
-
-      expect(mockAxiosInstance.request).toHaveBeenCalledWith(
-        expect.objectContaining({
-          method: 'POST',
-          url: '/v2/document',
-        })
-      );
-
-      const callArgs = mockAxiosInstance.request.mock.calls[0][0];
-      expect(callArgs.data).toBeDefined();
-    });
-
-    it('should NOT include enable_beta_languages parameter when not specified', async () => {
+    it('should never include the retired enable_beta_languages parameter', async () => {
       const mockResponse = {
         data: {
           document_id: 'doc-id',
diff --git a/tests/unit/deepl-client.test.ts b/tests/unit/deepl-client.test.ts
index 39939bb5..9a878472 100644
--- a/tests/unit/deepl-client.test.ts
+++ b/tests/unit/deepl-client.test.ts
@@ -328,30 +328,7 @@ describe('DeepLClient', () => {
       expect(nock.isDone()).toBe(true);
     });
 
-    it('should send enable_beta_languages parameter when enabled', async () => {
-      nock(baseUrl)
-        .post('/v2/translate', (body) => {
-           
-          return body.enable_beta_languages === '1';
-        })
-        .reply(200, {
-          translations: [
-            {
-              detected_source_language: 'EN',
-              text: 'Hola',
-            },
-          ],
-        });
-
-      await client.translate('Hello', {
-        targetLang: 'es',
-        enableBetaLanguages: true,
-      });
-
-      expect(nock.isDone()).toBe(true);
-    });
-
-    it('should not send enable_beta_languages when not requested', async () => {
+    it('should never send the retired enable_beta_languages parameter', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
            
@@ -756,21 +733,21 @@ describe('DeepLClient', () => {
       await expect(client.getUsage()).rejects.toThrow();
     });
 
-    it('should parse speech-to-text milliseconds fields', async () => {
+    it('should ignore the deprecated speech_to_text_milliseconds_* fields', async () => {
       nock(baseUrl)
         .get('/v2/usage')
         .reply(200, {
           character_count: 12345,
           character_limit: 500000,
-          speech_to_text_milliseconds_count: 120000,
-          speech_to_text_milliseconds_limit: 36000000,
+          speech_to_text_milliseconds_count: 0,
+          speech_to_text_milliseconds_limit: 0,
         });
 
       const usage = await client.getUsage();
 
       expect(usage.characterCount).toBe(12345);
-      expect(usage.speechToTextMillisecondsCount).toBe(120000);
-      expect(usage.speechToTextMillisecondsLimit).toBe(36000000);
+      expect(usage).not.toHaveProperty('speechToTextMillisecondsCount');
+      expect(usage).not.toHaveProperty('speechToTextMillisecondsLimit');
     });
 
     it('should parse products with billing_unit', async () => {
@@ -794,19 +771,6 @@ describe('DeepLClient', () => {
       expect(products[1]!.billingUnit).toBe('milliseconds');
     });
 
-    it('should omit speech-to-text fields when not present in response', async () => {
-      nock(baseUrl)
-        .get('/v2/usage')
-        .reply(200, {
-          character_count: 12345,
-          character_limit: 500000,
-        });
-
-      const usage = await client.getUsage();
-
-      expect(usage.speechToTextMillisecondsCount).toBeUndefined();
-      expect(usage.speechToTextMillisecondsLimit).toBeUndefined();
-    });
   });
 
   describe('getSupportedLanguages()', () => {
@@ -1895,33 +1859,6 @@ describe('DeepLClient', () => {
       // Note: In batch translation, billed_characters is for the entire batch,
       // not per translation. The API client returns it at the response level.
     });
-
-    it('should send enable_beta_languages in batch translation', async () => {
-      nock(baseUrl)
-        .post('/v2/translate', (body) => {
-           
-          return body.enable_beta_languages === '1';
-        })
-        .reply(200, {
-          translations: [
-            {
-              detected_source_language: 'EN',
-              text: 'Hola',
-            },
-            {
-              detected_source_language: 'EN',
-              text: 'Adiós',
-            },
-          ],
-        });
-
-      await client.translateBatch(['Hello', 'Goodbye'], {
-        targetLang: 'es',
-        enableBetaLanguages: true,
-      });
-
-      expect(nock.isDone()).toBe(true);
-    });
   });
 
   describe('getGlossaryLanguages()', () => {
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index a6128519..c6db35bf 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -270,8 +270,6 @@ describe('TranslationClient', () => {
           api_key_character_limit: 500,
           start_time: '2024-01-01',
           end_time: '2024-12-31',
-          speech_to_text_milliseconds_count: 5000,
-          speech_to_text_milliseconds_limit: 60000,
           api_key_unit_count: 10,
           api_key_unit_limit: 100,
           account_unit_count: 20,
@@ -287,8 +285,6 @@ describe('TranslationClient', () => {
       expect(result.apiKeyCharacterLimit).toBe(500);
       expect(result.startTime).toBe('2024-01-01');
       expect(result.endTime).toBe('2024-12-31');
-      expect(result.speechToTextMillisecondsCount).toBe(5000);
-      expect(result.speechToTextMillisecondsLimit).toBe(60000);
       expect(result.apiKeyUnitCount).toBe(10);
       expect(result.apiKeyUnitLimit).toBe(100);
       expect(result.accountUnitCount).toBe(20);
diff --git a/tests/unit/translation-service.test.ts b/tests/unit/translation-service.test.ts
index 9955861d..42da2158 100644
--- a/tests/unit/translation-service.test.ts
+++ b/tests/unit/translation-service.test.ts
@@ -197,19 +197,6 @@ describe('TranslationService', () => {
         tagHandling: 'xml',
       });
     });
-
-    it('should pass enableBetaLanguages to DeepL client', async () => {
-      mockDeepLClient.translate.mockResolvedValue({ text: 'Hola' });
-
-      await translationService.translate('Hello', {
-        targetLang: 'es',
-        enableBetaLanguages: true,
-      });
-
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith('Hello', expect.objectContaining({
-        enableBetaLanguages: true,
-      }));
-    });
   });
 
   describe('translateBatch()', () => {
diff --git a/tests/unit/usage-command.test.ts b/tests/unit/usage-command.test.ts
index 7ea05d53..02cec009 100644
--- a/tests/unit/usage-command.test.ts
+++ b/tests/unit/usage-command.test.ts
@@ -301,47 +301,7 @@ describe('UsageCommand', () => {
       expect(formatted).toContain('880,000');
     });
 
-    it('should display speech-to-text usage when available', () => {
-      const formatted = usageCommand.formatUsage({
-        characterCount: 2150000,
-        characterLimit: 20000000,
-        speechToTextMillisecondsCount: 3661000,
-        speechToTextMillisecondsLimit: 36000000,
-      });
-
-      expect(formatted).toContain('Speech-to-Text Usage:');
-      expect(formatted).toContain('1h 1m 1s');
-      expect(formatted).toContain('10h 0m 0s');
-      expect(formatted).toContain('10.2%');
-    });
-
-    it('should show warning for high speech-to-text usage', () => {
-      const formatted = usageCommand.formatUsage({
-        characterCount: 100,
-        characterLimit: 500000,
-        speechToTextMillisecondsCount: 30000000,
-        speechToTextMillisecondsLimit: 36000000,
-      });
-
-      expect(formatted).toContain('Speech-to-Text Usage:');
-      expect(formatted).toContain('83.3%');
-      expect(formatted).toContain('Warning: You are approaching your speech-to-text limit');
-    });
-
-    it('should format zero speech-to-text usage in seconds, not milliseconds', () => {
-      const formatted = usageCommand.formatUsage({
-        characterCount: 100,
-        characterLimit: 500000,
-        speechToTextMillisecondsCount: 0,
-        speechToTextMillisecondsLimit: 36000000,
-      });
-
-      expect(formatted).toContain('Speech-to-Text Usage:');
-      expect(formatted).toContain('0s');
-      expect(formatted).not.toContain('0ms');
-    });
-
-    it('should omit speech-to-text section when not available', () => {
+    it('should not render a dedicated speech-to-text section (voice usage lives in the product breakdown)', () => {
       const formatted = usageCommand.formatUsage({
         characterCount: 123456,
         characterLimit: 500000,
@@ -416,14 +376,12 @@ describe('UsageCommand', () => {
       expect(formatted).not.toContain('textTranslation');
     });
 
-    it('should display full Pro response with speech-to-text', () => {
+    it('should display full Pro response with voice usage in the product breakdown', () => {
       const formatted = usageCommand.formatUsage({
         characterCount: 2150000,
         characterLimit: 20000000,
         apiKeyCharacterCount: 1880000,
         apiKeyCharacterLimit: 0,
-        speechToTextMillisecondsCount: 120000,
-        speechToTextMillisecondsLimit: 36000000,
         startTime: '2025-04-24T14:58:02Z',
         endTime: '2025-05-24T14:58:02Z',
         products: [
@@ -433,7 +391,8 @@ describe('UsageCommand', () => {
       });
 
       expect(formatted).toContain('Character Usage:');
-      expect(formatted).toContain('Speech-to-Text Usage:');
+      expect(formatted).not.toContain('Speech-to-Text Usage:');
+      expect(formatted).toContain('speech_to_text: 2m 0s');
       expect(formatted).toContain('Billing Period:');
       expect(formatted).toContain('API Key Usage:');
       expect(formatted).toContain('Product Breakdown:');
@@ -465,7 +424,7 @@ describe('UsageCommand', () => {
       expect(result).toContain('—'); // pct() returns em-dash when limit=0
     });
 
-    it('should add API key, account-unit, and STT rows when those fields are present', () => {
+    it('should add API key and account-unit rows when those fields are present', () => {
       const result = usageCommand.formatUsageTable({
         characterCount: 100,
         characterLimit: 500,
@@ -473,12 +432,10 @@ describe('UsageCommand', () => {
         accountUnitLimit: 10,
         apiKeyUnitCount: 2,
         apiKeyUnitLimit: 4,
-        speechToTextMillisecondsCount: 60000,
-        speechToTextMillisecondsLimit: 600000,
       });
       expect(result).toContain('Account units');
       expect(result).toContain('API key units');
-      expect(result).toContain('Speech-to-text');
+      expect(result).not.toContain('Speech-to-text');
     });
 
     it('should append a Product Breakdown table when products are present', () => {

From d1c9a9e82320461adc8f0fd092895f4051b28059 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 2 Aug 2026 23:21:54 -0400
Subject: [PATCH 003/256] feat(api): send glossary_ids when a request names
 several glossaries

Add a shared normalizer that picks the glossary wire parameter: one ID goes
out as glossary_id, keeping the existing shape, and two to five as
glossary_ids. It rejects a sixth glossary and the glossary_id/glossary_ids
combination the API refuses, and never sorts the list, because the API applies
the last glossary that defines a conflicting source term.

The two endpoints need different encodings for the list, verified against the
live API. Form-urlencoded POST /v2/translate parses repeated glossary_ids
fields as an ordered list, so the existing array serialization is already
correct. Multipart POST /v2/document keeps only the first of several repeated
fields and silently applies that one glossary, so the document client
comma-joins the IDs; whitespace around the commas voids the parameter.
---
 src/api/document-client.ts            | 16 ++++-
 src/api/translation-client.ts         |  6 +-
 src/types/api.ts                      |  8 +++
 src/utils/glossary-params.ts          | 70 +++++++++++++++++++++
 tests/unit/document-client.test.ts    | 77 +++++++++++++++++++++++
 tests/unit/glossary-params.test.ts    | 88 +++++++++++++++++++++++++++
 tests/unit/translation-client.test.ts | 78 ++++++++++++++++++++++++
 7 files changed, 339 insertions(+), 4 deletions(-)
 create mode 100644 src/utils/glossary-params.ts
 create mode 100644 tests/unit/glossary-params.test.ts

diff --git a/src/api/document-client.ts b/src/api/document-client.ts
index 9e52804f..020084df 100644
--- a/src/api/document-client.ts
+++ b/src/api/document-client.ts
@@ -2,6 +2,10 @@ import { HttpClient, DeepLClientOptions } from './http-client.js';
 import { DocumentTranslationOptions, DocumentHandle, DocumentStatus } from '../types/index.js';
 import { ValidationError } from '../utils/errors.js';
 import { normalizeFormality } from '../utils/formality.js';
+import {
+  resolveGlossaryWireParams,
+  encodeGlossaryIdsForMultipart,
+} from '../utils/glossary-params.js';
 
 interface DeepLDocumentUploadResponse {
   document_id: string;
@@ -58,8 +62,16 @@ export class DocumentClient extends HttpClient {
           if (options.formality) {
             formData.append('formality', normalizeFormality(options.formality, 'text'));
           }
-          if (options.glossaryId) {
-            formData.append('glossary_id', options.glossaryId);
+          const glossaryParams = resolveGlossaryWireParams(options);
+          if (glossaryParams) {
+            if ('glossary_id' in glossaryParams) {
+              formData.append('glossary_id', glossaryParams.glossary_id);
+            } else {
+              formData.append(
+                'glossary_ids',
+                encodeGlossaryIdsForMultipart(glossaryParams.glossary_ids),
+              );
+            }
           }
           if (options.outputFormat) {
             formData.append('output_format', options.outputFormat);
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index 97cb47d6..c10ffa0e 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -2,6 +2,7 @@ import { HttpClient, DeepLClientOptions } from './http-client.js';
 import { TranslationOptions, Language, TranslationMemory } from '../types/index.js';
 import { NetworkError } from '../utils/errors.js';
 import { normalizeFormality } from '../utils/formality.js';
+import { resolveGlossaryWireParams } from '../utils/glossary-params.js';
 import { LANGUAGE_REGISTRY } from '../data/language-registry.js';
 import { Logger } from '../utils/logger.js';
 
@@ -315,8 +316,9 @@ export class TranslationClient extends HttpClient {
       params['formality'] = normalizeFormality(options.formality, 'text');
     }
 
-    if (options.glossaryId) {
-      params['glossary_id'] = options.glossaryId;
+    const glossaryParams = resolveGlossaryWireParams(options);
+    if (glossaryParams) {
+      Object.assign(params, glossaryParams);
     }
 
     if (options.translationMemoryId) {
diff --git a/src/types/api.ts b/src/types/api.ts
index a69538c3..747fc923 100644
--- a/src/types/api.ts
+++ b/src/types/api.ts
@@ -13,6 +13,12 @@ export interface TranslationOptions {
   sourceLang?: Language;
   targetLang: Language;
   glossaryId?: string;
+  /**
+   * Two to five glossaries applied to one request. Their entries are merged;
+   * when more than one defines the same source term the last one wins, so the
+   * order is significant. Mutually exclusive with `glossaryId`.
+   */
+  glossaryIds?: string[];
   translationMemoryId?: string;
   translationMemoryThreshold?: number;
   formality?: Formality;
@@ -131,6 +137,8 @@ export interface DocumentTranslationOptions {
   filename?: string;
   formality?: Formality;
   glossaryId?: string;
+  /** See `TranslationOptions.glossaryIds`. */
+  glossaryIds?: string[];
   outputFormat?: DocumentOutputFormat;
   enableDocumentMinification?: boolean;
 }
diff --git a/src/utils/glossary-params.ts b/src/utils/glossary-params.ts
new file mode 100644
index 00000000..ff86e062
--- /dev/null
+++ b/src/utils/glossary-params.ts
@@ -0,0 +1,70 @@
+import { ValidationError } from './errors.js';
+
+/** The API rejects requests naming more than five glossaries. */
+export const MAX_GLOSSARIES_PER_REQUEST = 5;
+
+export interface GlossarySelection {
+  glossaryId?: string;
+  glossaryIds?: string[];
+}
+
+export type GlossaryWireParams =
+  | { glossary_id: string }
+  | { glossary_ids: string[] };
+
+/**
+ * Pick the glossary parameter to send for a resolved glossary selection.
+ *
+ * A single glossary always goes out as `glossary_id`, even when it arrived via
+ * `glossaryIds`, so single-glossary requests keep the wire shape — and the
+ * cache keys — they had before `glossary_ids` existed. Two or more go out as
+ * `glossary_ids`, which the API refuses to accept alongside `glossary_id`.
+ *
+ * The list order is preserved and never sorted: when several glossaries define
+ * the same source term, the API applies the last one that names it.
+ */
+export function resolveGlossaryWireParams(
+  selection: GlossarySelection,
+): GlossaryWireParams | undefined {
+  const ids = selection.glossaryIds;
+
+  if (selection.glossaryId && ids && ids.length > 0) {
+    throw new ValidationError(
+      'Cannot combine glossaryId with glossaryIds',
+      'Pass every glossary through glossaryIds; a single entry is sent as glossary_id automatically.',
+    );
+  }
+
+  if (selection.glossaryId) {
+    return { glossary_id: selection.glossaryId };
+  }
+
+  if (!ids || ids.length === 0) {
+    return undefined;
+  }
+
+  if (ids.length > MAX_GLOSSARIES_PER_REQUEST) {
+    throw new ValidationError(
+      `A maximum of ${MAX_GLOSSARIES_PER_REQUEST} glossaries can be used per request, got ${ids.length}`,
+      'Merge entries into fewer glossaries, or pass fewer --glossary flags.',
+    );
+  }
+
+  const [only] = ids;
+  if (ids.length === 1 && only) {
+    return { glossary_id: only };
+  }
+
+  return { glossary_ids: ids };
+}
+
+/**
+ * Encode `glossary_ids` for multipart requests. Unlike form-urlencoded bodies,
+ * multipart uploads do not parse repeated `glossary_ids` fields as a list — the
+ * API keeps only the first and silently applies that one glossary — so the IDs
+ * travel as a single comma-joined value. Whitespace around the commas makes the
+ * API ignore the parameter outright.
+ */
+export function encodeGlossaryIdsForMultipart(ids: string[]): string {
+  return ids.join(',');
+}
diff --git a/tests/unit/document-client.test.ts b/tests/unit/document-client.test.ts
index d3b252f3..b9a51ea3 100644
--- a/tests/unit/document-client.test.ts
+++ b/tests/unit/document-client.test.ts
@@ -121,6 +121,83 @@ describe('DocumentClient', () => {
       expect(mockAxiosInstance.request).toHaveBeenCalled();
     });
 
+    describe('glossary params', () => {
+      const A = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+      const B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+
+      beforeEach(() => {
+        mockAxiosInstance.request.mockResolvedValue({
+          data: { document_id: 'doc-1', document_key: 'key-1' },
+          status: 200,
+          headers: {},
+        });
+      });
+
+      const getMultipartBody = (): string => {
+        const call = mockAxiosInstance.request.mock.calls[0]?.[0];
+        return (call?.data?.getBuffer?.() as Buffer | undefined)?.toString('utf8') ?? '';
+      };
+
+      const upload = async (options: Record<string, unknown>): Promise<void> => {
+        await client.uploadDocument(Buffer.from('content'), {
+          targetLang: 'de',
+          filename: 'doc.txt',
+          ...options,
+        } as any);
+      };
+
+      it('should send glossary_id for a single glossaryId', async () => {
+        await upload({ glossaryId: A });
+        const body = getMultipartBody();
+        expect(body).toContain('name="glossary_id"');
+        expect(body).toContain(A);
+        expect(body).not.toContain('name="glossary_ids"');
+      });
+
+      it('should send glossary_id when glossaryIds holds exactly one ID', async () => {
+        await upload({ glossaryIds: [A] });
+        const body = getMultipartBody();
+        expect(body).toContain('name="glossary_id"');
+        expect(body).not.toContain('name="glossary_ids"');
+      });
+
+      /**
+       * Multipart uploads keep only the first of several repeated fields, so the
+       * IDs must arrive comma-joined or every glossary after the first is
+       * silently dropped by the API.
+       */
+      it('should comma-join several glossary IDs into one glossary_ids field', async () => {
+        await upload({ glossaryIds: [A, B] });
+        const body = getMultipartBody();
+        expect(body).toContain('name="glossary_ids"');
+        expect(body).toContain(`${A},${B}`);
+        expect(body).not.toContain('name="glossary_id"\r\n');
+        expect(body.match(/name="glossary_ids"/g)).toHaveLength(1);
+      });
+
+      it('should not pad the joined IDs with whitespace, which voids the parameter', async () => {
+        await upload({ glossaryIds: [A, B] });
+        expect(getMultipartBody()).not.toContain(`${A}, ${B}`);
+      });
+
+      it('should keep the caller order, since the last glossary wins', async () => {
+        await upload({ glossaryIds: [B, A] });
+        expect(getMultipartBody()).toContain(`${B},${A}`);
+      });
+
+      it('should reject more than five glossaries before uploading', async () => {
+        await expect(
+          upload({ glossaryIds: [A, B, A, B, A, B] }),
+        ).rejects.toThrow(/maximum of 5 glossaries/);
+        expect(mockAxiosInstance.request).not.toHaveBeenCalled();
+      });
+
+      it('should reject glossaryId combined with glossaryIds', async () => {
+        await expect(upload({ glossaryId: A, glossaryIds: [B] })).rejects.toThrow(/Cannot combine/);
+        expect(mockAxiosInstance.request).not.toHaveBeenCalled();
+      });
+    });
+
     it('should handle API errors', async () => {
       const axiosError = {
         isAxiosError: true,
diff --git a/tests/unit/glossary-params.test.ts b/tests/unit/glossary-params.test.ts
new file mode 100644
index 00000000..5b7532d8
--- /dev/null
+++ b/tests/unit/glossary-params.test.ts
@@ -0,0 +1,88 @@
+/**
+ * Tests for glossary wire-parameter selection (glossary_id vs glossary_ids)
+ */
+
+import {
+  resolveGlossaryWireParams,
+  encodeGlossaryIdsForMultipart,
+  MAX_GLOSSARIES_PER_REQUEST,
+} from '../../src/utils/glossary-params.js';
+import { ValidationError } from '../../src/utils/errors.js';
+
+const A = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+const B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+const C = 'cccccccc-cccc-cccc-cccc-cccccccccccc';
+
+describe('resolveGlossaryWireParams', () => {
+  it('should return undefined when no glossary is selected', () => {
+    expect(resolveGlossaryWireParams({})).toBeUndefined();
+  });
+
+  it('should return undefined for an empty glossaryIds list', () => {
+    expect(resolveGlossaryWireParams({ glossaryIds: [] })).toBeUndefined();
+  });
+
+  it('should send a lone glossaryId as glossary_id', () => {
+    expect(resolveGlossaryWireParams({ glossaryId: A })).toEqual({ glossary_id: A });
+  });
+
+  it('should send a single-entry glossaryIds list as glossary_id', () => {
+    expect(resolveGlossaryWireParams({ glossaryIds: [A] })).toEqual({ glossary_id: A });
+  });
+
+  it('should send two or more IDs as glossary_ids', () => {
+    expect(resolveGlossaryWireParams({ glossaryIds: [A, B] })).toEqual({ glossary_ids: [A, B] });
+  });
+
+  it('should preserve the caller order, since the last glossary wins conflicts', () => {
+    expect(resolveGlossaryWireParams({ glossaryIds: [C, A, B] })).toEqual({
+      glossary_ids: [C, A, B],
+    });
+  });
+
+  it('should accept exactly the maximum number of glossaries', () => {
+    const ids = [A, B, C, A, B];
+    expect(ids).toHaveLength(MAX_GLOSSARIES_PER_REQUEST);
+    expect(resolveGlossaryWireParams({ glossaryIds: ids })).toEqual({ glossary_ids: ids });
+  });
+
+  it('should reject more than the maximum number of glossaries', () => {
+    expect.assertions(3);
+    const ids = [A, B, C, A, B, C];
+    expect(() => resolveGlossaryWireParams({ glossaryIds: ids })).toThrow(ValidationError);
+    try {
+      resolveGlossaryWireParams({ glossaryIds: ids });
+    } catch (error) {
+      expect((error as ValidationError).message).toContain('maximum of 5 glossaries');
+      expect((error as ValidationError).message).toContain('got 6');
+    }
+  });
+
+  it('should reject glossaryId combined with glossaryIds, which the API refuses', () => {
+    expect.assertions(2);
+    expect(() => resolveGlossaryWireParams({ glossaryId: A, glossaryIds: [B] })).toThrow(
+      ValidationError,
+    );
+    try {
+      resolveGlossaryWireParams({ glossaryId: A, glossaryIds: [B] });
+    } catch (error) {
+      expect((error as ValidationError).message).toContain('Cannot combine');
+    }
+  });
+
+  it('should ignore an empty glossaryIds list alongside glossaryId', () => {
+    expect(resolveGlossaryWireParams({ glossaryId: A, glossaryIds: [] })).toEqual({
+      glossary_id: A,
+    });
+  });
+});
+
+describe('encodeGlossaryIdsForMultipart', () => {
+  it('should join IDs with commas and no whitespace', () => {
+    expect(encodeGlossaryIdsForMultipart([A, B])).toBe(`${A},${B}`);
+  });
+
+  it('should preserve order', () => {
+    expect(encodeGlossaryIdsForMultipart([B, A])).toBe(`${B},${A}`);
+  });
+});
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index c6db35bf..083f2a47 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -244,6 +244,84 @@ describe('TranslationClient', () => {
     });
   });
 
+  describe('glossary params', () => {
+    const A = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+    const B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+    const C = 'cccccccc-cccc-cccc-cccc-cccccccccccc';
+
+    beforeEach(() => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: { translations: [{ text: 'Hola' }] },
+        status: 200,
+        headers: {},
+      });
+    });
+
+    const getRequestBody = (): string => {
+      const call = mockAxiosInstance.request.mock.calls[0]?.[0];
+      return (call?.data ?? '') as string;
+    };
+
+    it('should send glossary_id for a single glossaryId', async () => {
+      await client.translate('Hello', { targetLang: 'es', glossaryId: A });
+      const body = getRequestBody();
+      expect(body).toContain(`glossary_id=${A}`);
+      expect(body).not.toContain('glossary_ids');
+    });
+
+    it('should send glossary_id when glossaryIds holds exactly one ID', async () => {
+      await client.translate('Hello', { targetLang: 'es', glossaryIds: [A] });
+      const body = getRequestBody();
+      expect(body).toContain(`glossary_id=${A}`);
+      expect(body).not.toContain('glossary_ids');
+    });
+
+    it('should send repeated glossary_ids fields for several glossaries', async () => {
+      await client.translate('Hello', { targetLang: 'es', glossaryIds: [A, B, C] });
+      const body = getRequestBody();
+      expect(body).toContain(`glossary_ids=${A}`);
+      expect(body).toContain(`glossary_ids=${B}`);
+      expect(body).toContain(`glossary_ids=${C}`);
+      expect(body).not.toMatch(/(^|&)glossary_id=/);
+    });
+
+    it('should keep the caller order on the wire, since the last glossary wins', async () => {
+      await client.translate('Hello', { targetLang: 'es', glossaryIds: [C, A] });
+      expect(getRequestBody()).toContain(`glossary_ids=${C}&glossary_ids=${A}`);
+    });
+
+    it('should omit glossary params entirely when none are set', async () => {
+      await client.translate('Hello', { targetLang: 'es' });
+      expect(getRequestBody()).not.toContain('glossary');
+    });
+
+    it('should reject more than five glossaries before sending a request', async () => {
+      await expect(
+        client.translate('Hello', { targetLang: 'es', glossaryIds: [A, B, C, A, B, C] }),
+      ).rejects.toThrow(/maximum of 5 glossaries/);
+      expect(mockAxiosInstance.request).not.toHaveBeenCalled();
+    });
+
+    it('should reject glossaryId combined with glossaryIds', async () => {
+      await expect(
+        client.translate('Hello', { targetLang: 'es', glossaryId: A, glossaryIds: [B] }),
+      ).rejects.toThrow(/Cannot combine/);
+      expect(mockAxiosInstance.request).not.toHaveBeenCalled();
+    });
+
+    it('should apply the same shape to translateBatch', async () => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: { translations: [{ text: 'Hola' }, { text: 'Adios' }] },
+        status: 200,
+        headers: {},
+      });
+      await client.translateBatch(['Hello', 'Bye'], { targetLang: 'es', glossaryIds: [A, B] });
+      const body = getRequestBody();
+      expect(body).toContain(`glossary_ids=${A}`);
+      expect(body).toContain(`glossary_ids=${B}`);
+    });
+  });
+
   describe('getUsage()', () => {
     it('should return usage information', async () => {
       mockAxiosInstance.request.mockResolvedValue({

From be8bacb5dc8543386c592c2f25f909686776862d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 2 Aug 2026 23:22:00 -0400
Subject: [PATCH 004/256] fix(services): key the translation cache on the
 effective glossary parameter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

generateCacheKey hashed the raw options, so naming one glossary via glossaryIds
keyed differently from the identical request built with glossaryId, and an empty
glossaryIds list keyed differently from no glossary at all — in both cases the
same API request cached twice. Key on the normalized wire parameter instead.

glossaryIds is appended after the existing fields, per the fixed-order contract,
so keys for requests that do not use it are unchanged. It is hashed in the
caller's order rather than sorted: reordering the list changes which glossary
wins a conflicting term, and therefore the translation.
---
 src/services/translation.ts            | 13 ++++++-
 tests/unit/translation-service.test.ts | 51 ++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/src/services/translation.ts b/src/services/translation.ts
index feadb3a3..af8be411 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -12,6 +12,7 @@ import { Logger } from '../utils/logger.js';
 import { mapWithConcurrency, MULTI_TARGET_CONCURRENCY } from '../utils/concurrency.js';
 import { ValidationError } from '../utils/errors.js';
 import { errorMessage } from '../utils/error-message.js';
+import { resolveGlossaryWireParams } from '../utils/glossary-params.js';
 import { preserveCodeBlocks, preserveVariables, restorePlaceholders } from '../utils/text-preservation.js';
 
 export { MULTI_TARGET_CONCURRENCY };
@@ -390,8 +391,17 @@ export class TranslationService {
    * encodings of the same visible string produce distinct cache keys. This is
    * intentional — the API receives the un-normalized bytes, so the cache keys
    * on exactly what is sent.
+   *
+   * New fields are appended after the existing ones so that keys for requests
+   * not using them stay unchanged. `glossaryIds` is hashed in the caller's
+   * order rather than sorted, because reordering the list changes which
+   * glossary wins a conflicting term and therefore the translation itself.
    */
   private generateCacheKey(text: string, options: TranslationOptions): string {
+    // Keyed on the parameter the request will actually carry, so the two ways of
+    // naming one glossary share a key and an empty selection keys as no glossary
+    const glossary = resolveGlossaryWireParams(options);
+
     // Create a stable representation with deterministic property order
     // Property order matters because JSON.stringify() preserves insertion order
     const cacheData = {
@@ -399,7 +409,7 @@ export class TranslationService {
       targetLang: options.targetLang,    // 2. Target language
       sourceLang: options.sourceLang,    // 3. Source language (if specified)
       formality: options.formality,      // 4. Formality level
-      glossaryId: options.glossaryId,    // 5. Glossary ID
+      glossaryId: glossary && 'glossary_id' in glossary ? glossary.glossary_id : undefined, // 5. Glossary ID
       context: options.context,          // 6. Context hint
       modelType: options.modelType,      // 7. Model type affects output quality
       splitSentences: options.splitSentences, // 8. Sentence splitting behavior
@@ -407,6 +417,7 @@ export class TranslationService {
       tagHandlingVersion: options.tagHandlingVersion, // 10. Tag handling version
       customInstructions: options.customInstructions, // 11. Custom instructions
       styleId: options.styleId,          // 12. Style rules
+      glossaryIds: glossary && 'glossary_ids' in glossary ? glossary.glossary_ids : undefined, // 13. Multi-glossary selection (order-significant)
       // Note: preserveFormatting doesn't affect translation output, so not cached
     };
 
diff --git a/tests/unit/translation-service.test.ts b/tests/unit/translation-service.test.ts
index 42da2158..c80340bd 100644
--- a/tests/unit/translation-service.test.ts
+++ b/tests/unit/translation-service.test.ts
@@ -1156,6 +1156,57 @@ describe('TranslationService', () => {
       expect(key1).toBe(key2);
     });
 
+    describe('multi-glossary cache keys', () => {
+      const A = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+      const B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+
+      const keysFor = async (
+        optionSets: Array<Record<string, unknown>>,
+      ): Promise<string[]> => {
+        mockCacheService.get.mockReturnValue(null);
+        mockDeepLClient.translate.mockResolvedValue({ text: 'Hola' });
+        mockCacheService.set.mockClear();
+
+        for (const options of optionSets) {
+          await translationService.translate('Hello', { targetLang: 'es', ...options } as any);
+        }
+
+        return mockCacheService.set.mock.calls.map((call) => call[0]);
+      };
+
+      it('should key a single glossary the same whether it arrives as glossaryId or glossaryIds', async () => {
+        const [viaSingular, viaList] = await keysFor([
+          { glossaryId: A },
+          { glossaryIds: [A] },
+        ]);
+        expect(viaSingular).toBe(viaList);
+      });
+
+      it('should separate one glossary from two', async () => {
+        const [one, two] = await keysFor([{ glossaryIds: [A] }, { glossaryIds: [A, B] }]);
+        expect(one).not.toBe(two);
+      });
+
+      /** Reordering changes which glossary wins a conflicting term, so the keys must differ. */
+      it('should separate the two orderings of the same glossaries', async () => {
+        const [ab, ba] = await keysFor([{ glossaryIds: [A, B] }, { glossaryIds: [B, A] }]);
+        expect(ab).not.toBe(ba);
+      });
+
+      it('should reuse the key for an identical multi-glossary request', async () => {
+        const [first, second] = await keysFor([
+          { glossaryIds: [A, B] },
+          { glossaryIds: [A, B] },
+        ]);
+        expect(first).toBe(second);
+      });
+
+      it('should leave keys for glossary-free requests unchanged by the new field', async () => {
+        const [none, empty] = await keysFor([{}, { glossaryIds: [] }]);
+        expect(none).toBe(empty);
+      });
+    });
+
     it('should use cached result when options are provided in different order', async () => {
       // Set up cache to return a hit for the second call
       let callCount = 0;

From a268f7774a48d0be1491c356f0b64ee412762b24 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 2 Aug 2026 23:22:09 -0400
Subject: [PATCH 005/256] feat(cli): make translate --glossary repeatable, up
 to 5 glossaries

Each value still goes through the existing name-or-ID resolution, so names and
UUIDs can be mixed; they resolve sequentially to let the service's resolution
cache serve the later lookups. One glossary is passed on as glossaryId so the
request and its cache key are byte-identical to before, several as glossaryIds.

A sixth --glossary fails before any glossary lookup or translation request. The
dry-run summary lists every requested glossary in the order given, since the
last one wins a conflicting term.

watch and sync keep their single-glossary configuration.
---
 src/cli/commands/register-translate.ts        |  22 ++-
 .../translate/translation-options-factory.ts  |  17 ++-
 src/cli/commands/translate/types.ts           |   2 +-
 tests/e2e/cli-multi-glossary.e2e.test.ts      |  90 +++++++++++
 .../cli-translate.integration.test.ts         | 140 +++++++++++++++++-
 tests/unit/file-translation-handler.test.ts   |   8 +-
 tests/unit/text-translation-handler.test.ts   |   4 +-
 tests/unit/translate-command.test.ts          |  24 +--
 tests/unit/translate-utils.test.ts            |   6 +-
 .../unit/translation-options-factory.test.ts  |   8 +-
 10 files changed, 288 insertions(+), 33 deletions(-)
 create mode 100644 tests/e2e/cli-multi-glossary.e2e.test.ts

diff --git a/src/cli/commands/register-translate.ts b/src/cli/commands/register-translate.ts
index da6c6c75..9351bf83 100644
--- a/src/cli/commands/register-translate.ts
+++ b/src/cli/commands/register-translate.ts
@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
 import { createTranslateCommand, type ServiceDeps } from './service-factory.js';
+import { MAX_GLOSSARIES_PER_REQUEST } from '../../utils/glossary-params.js';
 
 export function registerTranslate(
   program: Command,
@@ -23,7 +24,11 @@ export function registerTranslate(
     .optionsGroup('Translation Quality:')
     .addOption(new Option('--formality <level>', 'Formality level (formal/informal are aliases for more/less)').choices(['default', 'more', 'less', 'prefer_more', 'prefer_less', 'formal', 'informal']))
     .option('--context <text>', 'Additional context to improve translation quality')
-    .option('--glossary <name-or-id>', 'Use glossary by name or ID')
+    .option(
+      '--glossary <name-or-id>',
+      `Use glossary by name or ID (repeatable, max ${MAX_GLOSSARIES_PER_REQUEST}; when several define the same term, the last one wins)`,
+      (val: string, prev: string[] | undefined) => (prev ?? []).concat([val]),
+    )
     .option(
       '--translation-memory <name-or-uuid>',
       'Use translation memory by name or UUID (forces quality_optimized model). Run "deepl tm list" to see available TMs.',
@@ -77,6 +82,7 @@ Examples:
   $ echo "Hello" | deepl translate --to ja
   $ deepl translate report.pdf --to de --output-format docx
   $ deepl translate "Hello" --to es --formality more --glossary my-glossary
+  $ deepl translate "Hello" --to es --glossary base-terms --glossary project-overrides
   $ deepl translate page.html --to fr --tag-handling html
   $ deepl translate "Hello" --to es --custom-instruction "Use informal language"
   $ deepl translate ./docs --to es --dry-run
@@ -103,7 +109,7 @@ Examples:
       recursive?: boolean;
       pattern?: string;
       concurrency?: number;
-      glossary?: string;
+      glossary?: string[];
       translationMemory?: string;
       tmThreshold?: number;
       customInstruction?: string[];
@@ -126,6 +132,13 @@ Examples:
           }
         }
 
+        if (options.glossary && options.glossary.length > MAX_GLOSSARIES_PER_REQUEST) {
+          throw new ValidationError(
+            `--glossary can be given at most ${MAX_GLOSSARIES_PER_REQUEST} times, got ${options.glossary.length}`,
+            'Merge entries into fewer glossaries, or drop some --glossary flags.',
+          );
+        }
+
         if (options.tmThreshold !== undefined && !options.translationMemory) {
           throw new ValidationError(
             '--tm-threshold requires --translation-memory',
@@ -183,8 +196,9 @@ Examples:
           if (options.from) {
             lines.push(chalk.yellow(`[dry-run] Source language: ${options.from}`));
           }
-          if (options.glossary) {
-            lines.push(chalk.yellow(`[dry-run] Glossary: ${options.glossary}`));
+          if (options.glossary && options.glossary.length > 0) {
+            const label = options.glossary.length > 1 ? 'Glossaries' : 'Glossary';
+            lines.push(chalk.yellow(`[dry-run] ${label}: ${options.glossary.join(', ')}`));
           }
           if (options.translationMemory) {
             lines.push(chalk.yellow(`[dry-run] Translation memory: ${options.translationMemory}`));
diff --git a/src/cli/commands/translate/translation-options-factory.ts b/src/cli/commands/translate/translation-options-factory.ts
index 14a42b91..b17e24d7 100644
--- a/src/cli/commands/translate/translation-options-factory.ts
+++ b/src/cli/commands/translate/translation-options-factory.ts
@@ -58,6 +58,7 @@ export interface SharedTmAndGlossaryDeps {
 export async function applySharedTmAndGlossary<
   T extends {
     glossaryId?: string;
+    glossaryIds?: string[];
     translationMemoryId?: string;
     translationMemoryThreshold?: number;
     modelType?: TranslationParams['modelType'];
@@ -67,8 +68,20 @@ export async function applySharedTmAndGlossary<
   options: TranslateOptions,
   deps: SharedTmAndGlossaryDeps,
 ): Promise<void> {
-  if (options.glossary) {
-    base.glossaryId = await resolveGlossaryId(deps.glossaryService, options.glossary);
+  if (options.glossary && options.glossary.length > 0) {
+    // Resolved sequentially so the service's resolution cache is populated
+    // before the next name-or-ID lookup needs the glossary list.
+    const ids: string[] = [];
+    for (const nameOrId of options.glossary) {
+      ids.push(await resolveGlossaryId(deps.glossaryService, nameOrId));
+    }
+
+    const [only] = ids;
+    if (ids.length === 1 && only) {
+      base.glossaryId = only;
+    } else {
+      base.glossaryIds = ids;
+    }
   }
 
   if (options.translationMemory) {
diff --git a/src/cli/commands/translate/types.ts b/src/cli/commands/translate/types.ts
index ff2e8343..ee098fbb 100644
--- a/src/cli/commands/translate/types.ts
+++ b/src/cli/commands/translate/types.ts
@@ -27,7 +27,7 @@ export interface TranslateOptions {
   recursive?: boolean;
   pattern?: string;
   concurrency?: number;
-  glossary?: string;
+  glossary?: string[];
   translationMemory?: string;
   tmThreshold?: number;
   customInstruction?: string[];
diff --git a/tests/e2e/cli-multi-glossary.e2e.test.ts b/tests/e2e/cli-multi-glossary.e2e.test.ts
new file mode 100644
index 00000000..42fa7f62
--- /dev/null
+++ b/tests/e2e/cli-multi-glossary.e2e.test.ts
@@ -0,0 +1,90 @@
+/**
+ * E2E Tests for repeating --glossary on `deepl translate`
+ * Covers flag repetition, the five-glossary cap, and dry-run reporting
+ */
+
+import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
+
+describe('translate --glossary repetition E2E', () => {
+  const testConfig = createTestConfigDir('e2e-multi-glossary');
+  const { runCLI, runCLIExpectError } = makeNodeRunCLI(testConfig.path);
+
+  afterAll(() => {
+    testConfig.cleanup();
+  });
+
+  describe('translate --help', () => {
+    it('should document that --glossary is repeatable', () => {
+      const output = runCLI('translate --help');
+
+      expect(output).toContain('--glossary');
+      expect(output).toMatch(/repeatable/i);
+    });
+
+    it('should document the five-glossary maximum', () => {
+      expect(runCLI('translate --help')).toMatch(/max 5/i);
+    });
+
+    it('should document that the last glossary wins a conflict', () => {
+      expect(runCLI('translate --help')).toMatch(/last one wins/i);
+    });
+  });
+
+  describe('the five-glossary cap', () => {
+    it('should reject a sixth --glossary with a clear message', () => {
+      const result = runCLIExpectError(
+        'translate "Hello" --to de --glossary a --glossary b --glossary c ' +
+          '--glossary d --glossary e --glossary f',
+      );
+
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toMatch(/at most 5 times/i);
+      expect(result.output).toContain('got 6');
+    });
+
+    it('should not reject exactly five glossaries during flag validation', () => {
+      const result = runCLIExpectError(
+        'translate "Hello" --to de --dry-run --glossary a --glossary b --glossary c ' +
+          '--glossary d --glossary e',
+      );
+
+      expect(result.status).toBe(0);
+      expect(result.output).not.toMatch(/at most 5 times/i);
+    });
+  });
+
+  describe('dry run', () => {
+    it('should list every requested glossary in order', () => {
+      const output = runCLI(
+        'translate "Hello" --to de --dry-run --glossary base-terms --glossary project-overrides',
+        { noColor: true },
+      );
+
+      expect(output).toContain('Glossaries: base-terms, project-overrides');
+    });
+
+    it('should keep the singular label for one glossary', () => {
+      const output = runCLI('translate "Hello" --to de --dry-run --glossary base-terms', {
+        noColor: true,
+      });
+
+      expect(output).toContain('Glossary: base-terms');
+      expect(output).not.toContain('Glossaries:');
+    });
+
+    it('should report no glossary line when none is given', () => {
+      const output = runCLI('translate "Hello" --to de --dry-run', { noColor: true });
+
+      expect(output).not.toMatch(/Glossar/i);
+    });
+  });
+
+  describe('argument handling', () => {
+    it('should require a value for each --glossary', () => {
+      const result = runCLIExpectError('translate "Hello" --to de --glossary');
+
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toMatch(/argument missing|option.*--glossary/i);
+    });
+  });
+});
diff --git a/tests/integration/cli-translate.integration.test.ts b/tests/integration/cli-translate.integration.test.ts
index 33065663..9e81d5a3 100644
--- a/tests/integration/cli-translate.integration.test.ts
+++ b/tests/integration/cli-translate.integration.test.ts
@@ -1238,7 +1238,7 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
       const options: TranslateOptions = {
         to: 'de',
         from: 'en',
-        glossary: 'my-glossary',
+        glossary: ['my-glossary'],
         translationMemory: 'my-tm',
         cache: false,
       };
@@ -1251,4 +1251,142 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
       expect(nock.isDone()).toBe(true);
     });
   });
+
+  describe('multiple glossaries on one call', () => {
+    const SECOND_GLOSSARY_UUID = 'ffffffff-eeee-dddd-cccc-bbbbbbbbbbbb';
+
+    const mockGlossaryList = (): nock.Scope =>
+      nock(DEEPL_FREE_API_URL)
+        .get('/v3/glossaries')
+        .reply(200, {
+          glossaries: [
+            {
+              glossary_id: GLOSSARY_UUID,
+              name: 'base-terms',
+              ready: true,
+              creation_time: '2026-04-19T00:00:00Z',
+              dictionaries: [{ source_lang: 'EN', target_lang: 'DE', entry_count: 1 }],
+            },
+            {
+              glossary_id: SECOND_GLOSSARY_UUID,
+              name: 'project-overrides',
+              ready: true,
+              creation_time: '2026-04-19T00:00:00Z',
+              dictionaries: [{ source_lang: 'EN', target_lang: 'DE', entry_count: 1 }],
+            },
+          ],
+        });
+
+    it('resolves each name and sends glossary_ids in the given order', async () => {
+      const glossaryListScope = mockGlossaryList();
+
+      const translateScope = nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate', (body: Record<string, unknown>) => {
+          expect(body['glossary_ids']).toEqual([GLOSSARY_UUID, SECOND_GLOSSARY_UUID]);
+          expect(body['glossary_id']).toBeUndefined();
+          return true;
+        })
+        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+
+      const options: TranslateOptions = {
+        to: 'de',
+        from: 'en',
+        glossary: ['base-terms', 'project-overrides'],
+        cache: false,
+      };
+
+      await handler.translateText('Hi', options);
+
+      expect(glossaryListScope.isDone()).toBe(true);
+      expect(translateScope.isDone()).toBe(true);
+      expect(nock.isDone()).toBe(true);
+    });
+
+    it('preserves the reversed order, which selects the other winning glossary', async () => {
+      const glossaryListScope = mockGlossaryList();
+
+      const translateScope = nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate', (body: Record<string, unknown>) => {
+          expect(body['glossary_ids']).toEqual([SECOND_GLOSSARY_UUID, GLOSSARY_UUID]);
+          return true;
+        })
+        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+
+      const options: TranslateOptions = {
+        to: 'de',
+        from: 'en',
+        glossary: ['project-overrides', 'base-terms'],
+        cache: false,
+      };
+
+      await handler.translateText('Hi', options);
+
+      expect(glossaryListScope.isDone()).toBe(true);
+      expect(translateScope.isDone()).toBe(true);
+      expect(nock.isDone()).toBe(true);
+    });
+
+    it('still sends singular glossary_id for one glossary', async () => {
+      const glossaryListScope = mockGlossaryList();
+
+      const translateScope = nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate', (body: Record<string, unknown>) => {
+          expect(body['glossary_id']).toBe(GLOSSARY_UUID);
+          expect(body['glossary_ids']).toBeUndefined();
+          return true;
+        })
+        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+
+      const options: TranslateOptions = {
+        to: 'de',
+        from: 'en',
+        glossary: ['base-terms'],
+        cache: false,
+      };
+
+      await handler.translateText('Hi', options);
+
+      expect(glossaryListScope.isDone()).toBe(true);
+      expect(translateScope.isDone()).toBe(true);
+      expect(nock.isDone()).toBe(true);
+    });
+
+    it('accepts a mix of names and UUIDs', async () => {
+      const glossaryListScope = mockGlossaryList();
+
+      const translateScope = nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate', (body: Record<string, unknown>) => {
+          expect(body['glossary_ids']).toEqual([SECOND_GLOSSARY_UUID, GLOSSARY_UUID]);
+          return true;
+        })
+        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+
+      const options: TranslateOptions = {
+        to: 'de',
+        from: 'en',
+        glossary: [SECOND_GLOSSARY_UUID, 'base-terms'],
+        cache: false,
+      };
+
+      await handler.translateText('Hi', options);
+
+      expect(glossaryListScope.isDone()).toBe(true);
+      expect(translateScope.isDone()).toBe(true);
+      expect(nock.isDone()).toBe(true);
+    });
+
+    it('fails when one of several glossary names does not exist', async () => {
+      const glossaryListScope = mockGlossaryList();
+
+      const options: TranslateOptions = {
+        to: 'de',
+        from: 'en',
+        glossary: ['base-terms', 'no-such-glossary'],
+        cache: false,
+      };
+
+      await expect(handler.translateText('Hi', options)).rejects.toThrow(/no-such-glossary/);
+      expect(glossaryListScope.isDone()).toBe(true);
+    });
+  });
 });
diff --git a/tests/unit/file-translation-handler.test.ts b/tests/unit/file-translation-handler.test.ts
index e1deb5cd..b222a2db 100644
--- a/tests/unit/file-translation-handler.test.ts
+++ b/tests/unit/file-translation-handler.test.ts
@@ -162,7 +162,7 @@ describe('FileTranslationHandler', () => {
 
       it('throws ValidationError for --glossary without --from in multi-target', async () => {
         const err = await handler
-          .translateFile('/tmp/file.txt', defaultOptions({ to: 'de,fr', output: '/tmp/out', glossary: 'my-glossary' }))
+          .translateFile('/tmp/file.txt', defaultOptions({ to: 'de,fr', output: '/tmp/out', glossary: ['my-glossary'] }))
           .catch(e => e);
         expect(err).toBeInstanceOf(ValidationError);
         expect((err as Error).message).toContain('Source language (--from) is required');
@@ -193,7 +193,7 @@ describe('FileTranslationHandler', () => {
 
         await handler.translateFile('/tmp/file.txt', defaultOptions({
           to: 'de,fr', output: '/tmp/out',
-          from: 'en', glossary: 'my-glossary',
+          from: 'en', glossary: ['my-glossary'],
         }));
 
         expect(mocks.glossaryService.resolveGlossaryId).toHaveBeenCalledTimes(1);
@@ -310,10 +310,10 @@ describe('FileTranslationHandler', () => {
       mocks.glossaryService.resolveGlossaryId.mockResolvedValue('glossary-123');
 
       await expect(
-        handler.translateFile('/tmp/file.txt', defaultOptions({ glossary: 'my-glossary' }))
+        handler.translateFile('/tmp/file.txt', defaultOptions({ glossary: ['my-glossary'] }))
       ).rejects.toThrow(ValidationError);
       await expect(
-        handler.translateFile('/tmp/file.txt', defaultOptions({ glossary: 'my-glossary' }))
+        handler.translateFile('/tmp/file.txt', defaultOptions({ glossary: ['my-glossary'] }))
       ).rejects.toThrow('Source language (--from) is required');
     });
 
diff --git a/tests/unit/text-translation-handler.test.ts b/tests/unit/text-translation-handler.test.ts
index 442fc72c..9261d418 100644
--- a/tests/unit/text-translation-handler.test.ts
+++ b/tests/unit/text-translation-handler.test.ts
@@ -250,10 +250,10 @@ describe('TextTranslationHandler', () => {
     it('should throw ValidationError for glossary without --from', async () => {
       mocks.glossaryService.resolveGlossaryId.mockResolvedValue('glossary-123');
       await expect(
-        handler.translateText('Hello', defaultOptions({ glossary: 'my-glossary' }))
+        handler.translateText('Hello', defaultOptions({ glossary: ['my-glossary'] }))
       ).rejects.toThrow(ValidationError);
       await expect(
-        handler.translateText('Hello', defaultOptions({ glossary: 'my-glossary' }))
+        handler.translateText('Hello', defaultOptions({ glossary: ['my-glossary'] }))
       ).rejects.toThrow('Source language (--from) is required');
     });
 
diff --git a/tests/unit/translate-command.test.ts b/tests/unit/translate-command.test.ts
index 28c70fa6..be69629e 100644
--- a/tests/unit/translate-command.test.ts
+++ b/tests/unit/translate-command.test.ts
@@ -1189,7 +1189,7 @@ describe('TranslateCommand', () => {
       const result = await translateCommand.translateText('Hello world', {
         to: 'de',
         from: 'en',
-        glossary: 'my-glossary',
+        glossary: ['my-glossary'],
       });
 
       expect(result).toBe('Hallo Welt');
@@ -1212,7 +1212,7 @@ describe('TranslateCommand', () => {
       const result = await translateCommand.translateText('Hello world', {
         to: 'fr',
         from: 'en',
-        glossary: '01234567-89ab-cdef-0123-456789abcdef',
+        glossary: ['01234567-89ab-cdef-0123-456789abcdef'],
       });
 
       expect(result).toBe('Bonjour le monde');
@@ -1228,7 +1228,7 @@ describe('TranslateCommand', () => {
       await expect(
         translateCommand.translateText('Hello world', {
           to: 'de',
-          glossary: 'my-glossary',
+          glossary: ['my-glossary'],
         })
       ).rejects.toThrow('Source language (--from) is required when using a glossary');
     });
@@ -1237,7 +1237,7 @@ describe('TranslateCommand', () => {
       await expect(
         translateCommand.translateText('Hello world', {
           to: 'de,fr',
-          glossary: 'my-glossary',
+          glossary: ['my-glossary'],
         })
       ).rejects.toThrow('Source language (--from) is required when using a glossary');
     });
@@ -1251,7 +1251,7 @@ describe('TranslateCommand', () => {
         translateCommand.translateText('Hello world', {
           to: 'de',
           from: 'en',
-          glossary: 'non-existent',
+          glossary: ['non-existent'],
         })
       ).rejects.toThrow('Glossary "non-existent" not found');
 
@@ -1269,7 +1269,7 @@ describe('TranslateCommand', () => {
       const result = await translateCommand.translateText('Hello', {
         to: 'de,fr',
         from: 'en',
-        glossary: 'tech-terms',
+        glossary: ['tech-terms'],
       });
 
       expect(result).toBe('[de] Hallo\n[fr] Bonjour');
@@ -1292,7 +1292,7 @@ describe('TranslateCommand', () => {
       const result = await translateCommand.translateText('Dear Sir or Madam', {
         to: 'de',
         from: 'en',
-        glossary: 'business-glossary',
+        glossary: ['business-glossary'],
         formality: 'more',
         context: 'Business letter opening',
       });
@@ -2098,7 +2098,7 @@ describe('TranslateCommand', () => {
       await expect(
         translateCommand.translateText('Hello', {
           to: 'sw',
-          glossary: 'my-glossary',
+          glossary: ['my-glossary'],
         })
       ).rejects.toThrow('do not support glossaries');
     });
@@ -3322,7 +3322,7 @@ describe('TranslateCommand', () => {
         to: 'es',
         from: 'en',
         output: '/out.txt',
-        glossary: 'my-glossary',
+        glossary: ['my-glossary'],
       });
 
       expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
@@ -3648,7 +3648,7 @@ describe('TranslateCommand', () => {
             to: 'es',
             output: '/output',
             splitSentences: 'on',
-            glossary: 'my-glossary',
+            glossary: ['my-glossary'],
             customInstruction: ['Be formal'],
             modelType: 'quality_optimized',
             context: 'technical docs',
@@ -3700,7 +3700,7 @@ describe('TranslateCommand', () => {
           tagHandling: 'xml',
           modelType: 'quality_optimized',
           customInstruction: ['Be formal'],
-          glossary: 'my-glossary',
+          glossary: ['my-glossary'],
           preserveCode: true,
         });
 
@@ -3783,7 +3783,7 @@ describe('TranslateCommand', () => {
     it('should not include glossaryId (resolved separately)', () => {
       const result = buildTranslationOptions({
         to: 'es',
-        glossary: 'my-glossary',
+        glossary: ['my-glossary'],
       });
       expect(result).not.toHaveProperty('glossaryId');
     });
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index 922fcf43..b342c963 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -161,10 +161,10 @@ describe('translate-utils', () => {
 
     it('should throw for extended language with glossary', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, glossary: 'my-glossary' })
+        validateExtendedLanguageConstraints('hi', { ...baseOptions, glossary: ['my-glossary'] })
       ).toThrow(ValidationError);
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, glossary: 'my-glossary' })
+        validateExtendedLanguageConstraints('hi', { ...baseOptions, glossary: ['my-glossary'] })
       ).toThrow(/do not support glossaries/);
     });
 
@@ -174,7 +174,7 @@ describe('translate-utils', () => {
           to: 'de',
           modelType: 'latency_optimized',
           formality: 'more',
-          glossary: 'some-glossary',
+          glossary: ['some-glossary'],
         })
       ).not.toThrow();
     });
diff --git a/tests/unit/translation-options-factory.test.ts b/tests/unit/translation-options-factory.test.ts
index f30b619d..c0f3dad7 100644
--- a/tests/unit/translation-options-factory.test.ts
+++ b/tests/unit/translation-options-factory.test.ts
@@ -22,7 +22,7 @@ describe('translation-options-factory', () => {
     });
 
     it('maps glossary into options.glossary but does NOT set glossaryId (resolution is async)', () => {
-      const result = buildBaseTranslationOptions({ to: 'de', glossary: 'my-glossary' });
+      const result = buildBaseTranslationOptions({ to: 'de', glossary: ['my-glossary'] });
       expect(result.glossaryId).toBeUndefined();
     });
 
@@ -82,7 +82,7 @@ describe('translation-options-factory', () => {
     it('resolves glossaryId when options.glossary is set', async () => {
       glossarySvc.resolveGlossaryId.mockResolvedValue('glos-123');
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de', glossary: 'my-glossary' }, {
+      await applySharedTmAndGlossary(base, { to: 'de', glossary: ['my-glossary'] }, {
         glossaryService: glossarySvc,
         translationService: translationSvc,
         targets: ['de'],
@@ -176,7 +176,7 @@ describe('translation-options-factory', () => {
         to: 'de',
         from: 'en',
         formality: 'less',
-        glossary: 'my-glossary',
+        glossary: ['my-glossary'],
         modelType: 'quality_optimized',
         preserveFormatting: true,
       };
@@ -209,7 +209,7 @@ describe('translation-options-factory', () => {
         to: 'de',
         from: 'en',
         formality: 'more',
-        glossary: 'my-glossary',
+        glossary: ['my-glossary'],
         translationMemory: 'my-tm',
         tmThreshold: 85,
         modelType: 'quality_optimized',

From e580119398c047aff48db85f8f460d1a3f7fa1f7 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 2 Aug 2026 23:22:15 -0400
Subject: [PATCH 006/256] docs: document repeatable --glossary and its
 precedence rule

Record the merge-with-last-wins semantics in API.md, the README feature list
and the CHANGELOG, including that reordering the flags is a different request
with its own cache entry.

Extend the glossary example with a second EN->DE glossary that redefines one
term, so running it prints the precedence in both directions.
---
 CHANGELOG.md              |  2 ++
 README.md                 |  6 ++++++
 docs/API.md               | 20 +++++++++++++++++++-
 examples/15-glossaries.sh | 28 +++++++++++++++++++++++++++-
 4 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b906e60..db37be6d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API, including the two encodings the endpoints require: repeated form fields for `POST /v2/translate`, and one comma-joined value for the multipart `POST /v2/document`, which keeps only the first of several repeated fields and would otherwise silently apply just one glossary.
+
 - **cli**: `deepl correct` command (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`), but not `--style`/`--tone`, which the correct endpoint does not accept. Results are cached under a separate `correct:` namespace so corrections and rephrasings of the same text never collide.
 
 ### Changed
diff --git a/README.md b/README.md
index 4327076d..aa0b3db9 100644
--- a/README.md
+++ b/README.md
@@ -1280,6 +1280,12 @@ authentication	Authentifizierung
 - **Smart defaults** - `--target` flag only required for multilingual glossaries
 - **Visual indicators** - 📖 for single-target, 📚 for multilingual glossaries
 - **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms
+- **Several glossaries at once** - Repeat `--glossary` on `translate` for up to 5 glossaries; entries are merged and the last glossary given wins any conflicting term
+
+```bash
+# Layer project overrides on top of shared base terminology
+deepl translate "Hello world" --to de --glossary base-terms --glossary project-overrides
+```
 
 ### Translation Memories
 
diff --git a/docs/API.md b/docs/API.md
index cae4895a..44463398 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -251,7 +251,7 @@ Translate text directly, from stdin, from files, or entire directories. Supports
 - `--non-splitting-tags TAGS` - Comma-separated XML tags that should not be used to split sentences (requires `--tag-handling xml`)
 - `--ignore-tags TAGS` - Comma-separated XML tags with content to ignore (requires `--tag-handling xml`)
 - `--tag-handling-version VERSION` - Tag handling version: `v1`, `v2`. v2 improves XML/HTML structure handling (requires `--tag-handling`)
-- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology
+- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. Repeatable, up to 5 per request; when several glossaries define the same source term, the last one given wins. Passing a 6th exits 6 (ValidationError).
 - `--translation-memory NAME-OR-UUID` - Use translation memory by name or UUID (forces `quality_optimized` model). Requires `--from` because TMs are pinned to a specific source→target language pair. Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
 - `--tm-threshold N` - Minimum match score 0–100 (default 75, requires `--translation-memory`). Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
 - `--custom-instruction INSTRUCTION` - Custom instruction for translation (repeatable, max 10, max 300 chars each). Forces `quality_optimized` model. Cannot be used with `latency_optimized`.
@@ -542,6 +542,24 @@ deepl translate "API documentation" --to es --glossary tech-terms
 deepl translate README.md --to fr --glossary abc-123-def-456 --output README.fr.md
 ```
 
+**Multiple glossaries on one request:**
+
+Repeat `--glossary` to apply up to 5 glossaries to a single request. Their entries are merged, so terms unique to each glossary all apply. When more than one glossary defines the same source term, the **last** `--glossary` on the command line wins — order is significant, and reordering the flags produces a different translation (and a separate cache entry). Names and UUIDs can be mixed; each value is resolved independently. A 6th `--glossary` exits 6 (ValidationError), and an unresolvable name exits 7 (ConfigError) without sending a translation request.
+
+```bash
+# Shared base terminology, overridden by project-specific terms
+deepl translate "Hello world" --to de --glossary base-terms --glossary project-overrides
+
+# Reversing the order makes base-terms win any conflicting entry
+deepl translate "Hello world" --to de --glossary project-overrides --glossary base-terms
+
+# Names and UUIDs can be mixed
+deepl translate README.md --to fr --output README.fr.md \
+  --glossary abc-123-def-456 --glossary house-style
+```
+
+A single `--glossary` is still sent as the API's `glossary_id`, so existing commands and their cached results are unaffected.
+
 **Translation memory usage:**
 
 Translation memories (TMs) are pinned to a source→target language pair, so `--from` is required. Passing `--translation-memory` forces `quality_optimized` model type; combining it with `--model-type latency_optimized` (or `prefer_quality_optimized`) exits 6 (ValidationError). TM files are authored and uploaded via the DeepL web UI; this CLI resolves the name-or-UUID against `GET /v3/translation_memories` and caches the resolution per run.
diff --git a/examples/15-glossaries.sh b/examples/15-glossaries.sh
index 5eb921c3..94f9600d 100755
--- a/examples/15-glossaries.sh
+++ b/examples/15-glossaries.sh
@@ -35,6 +35,13 @@ request	Anfrage
 response	Antwort
 EOF
 
+# Create an override glossary (EN → DE) that redefines one term from the tech
+# glossary, so the precedence between two glossaries is visible in the output
+cat > "$SAMPLE_DIR/override-glossary.tsv" << 'EOF'
+endpoint	Schnittstelle
+webhook	Webhook
+EOF
+
 # Create a business terminology glossary (EN → ES)
 cat > "$SAMPLE_DIR/business-glossary.tsv" << 'EOF'
 stakeholder	parte interesada
@@ -59,7 +66,7 @@ echo
 # from a clean slate.
 echo "0. Pre-run cleanup of any leftover demo glossaries"
 if command -v jq &>/dev/null; then
-  DEMO_NAMES='tech-terms-demo tech-terms-renamed tech-final business-terms-demo multi-demo'
+  DEMO_NAMES='tech-terms-demo tech-terms-renamed tech-final business-terms-demo multi-demo override-terms-demo'
   for name in $DEMO_NAMES; do
     deepl glossary list --format json 2>/dev/null \
       | jq -r --arg n "$name" '.[] | select(.name == $n) | .glossary_id' 2>/dev/null \
@@ -195,6 +202,22 @@ deepl translate "The API endpoint requires authentication." --from en --to de --
 
 echo
 
+echo "   Repeat --glossary to apply up to 5 glossaries to one request."
+echo "   Entries are merged; on a term both define, the LAST glossary wins."
+deepl glossary create override-terms-demo en de "$SAMPLE_DIR/override-glossary.tsv"
+
+echo
+echo "   Both glossaries, override last -> 'endpoint' becomes Schnittstelle:"
+deepl translate "The API endpoint requires authentication." --from en --to de \
+  --glossary tech-terms-renamed --glossary override-terms-demo
+
+echo
+echo "   Same two glossaries reversed -> 'endpoint' stays Endpunkt:"
+deepl translate "The API endpoint requires authentication." --from en --to de \
+  --glossary override-terms-demo --glossary tech-terms-renamed
+
+echo
+
 # ═══════════════════════════════════════════════════════
 # ADVANCED OPERATIONS
 # ═══════════════════════════════════════════════════════
@@ -231,6 +254,9 @@ deepl glossary delete tech-final --yes 2>/dev/null || echo "   (Already deleted)
 echo "   Deleting business-terms-demo..."
 deepl glossary delete business-terms-demo --yes 2>/dev/null || echo "   (Already deleted)"
 
+echo "   Deleting override-terms-demo..."
+deepl glossary delete override-terms-demo --yes 2>/dev/null || echo "   (Already deleted)"
+
 echo "   Deleting multi-demo..."
 deepl glossary delete multi-demo --yes 2>/dev/null || echo "   (Already deleted)"
 

From 4fbc80a4b81c2db7253c06b3c70c1798768eb69f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 06:44:53 -0400
Subject: [PATCH 007/256] feat(cli): apply --glossary to document translation

Document translation accepted --glossary and then discarded it: the handler
left glossary out of its supported set, so warnIgnoredOptions reported it as
unsupported and no glossary ever reached the API, even though POST /v2/document
supports them. Resolve the glossary in the document path and drop the warning.

Repeating the flag works here too, with the same last-one-wins precedence.
DocumentTranslationOptions and the document client already carried glossaryIds,
so no client change was needed.

--from is now required with a document glossary, because the API rejects the
request otherwise: "source_lang has to be specified in order to use a
glossary." Translation memories stay unsupported for documents, so the glossary
half of applySharedTmAndGlossary is extracted into applyGlossarySelection and
shared rather than pulling TM resolution into the document path.

The pre-existing test asserting that document mode warns about --glossary
encoded the old behavior and is replaced by one asserting it does not.
---
 .../translate/document-translation-handler.ts |  15 ++-
 .../translate/translation-options-factory.ts  |  52 +++++---
 .../e2e/cli-document-translation.e2e.test.ts  |  67 ++++++++++
 ...i-document-translation.integration.test.ts |  81 ++++++++++++
 .../unit/document-translation-handler.test.ts | 123 ++++++++++++++++++
 tests/unit/translate-command.test.ts          |  19 ++-
 6 files changed, 336 insertions(+), 21 deletions(-)

diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index 41ecbd5b..70116a36 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -4,7 +4,7 @@ import { ValidationError } from '../../../utils/errors.js';
 import type { DocumentTranslationOptions } from '../../../types/api.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
 import { warnIgnoredOptions, validateLanguageCodes } from './translate-utils.js';
-import { buildBaseTranslationOptions } from './translation-options-factory.js';
+import { buildBaseTranslationOptions, applyGlossarySelection } from './translation-options-factory.js';
 
 export class DocumentTranslationHandler {
   constructor(public ctx: HandlerContext) {}
@@ -16,15 +16,26 @@ export class DocumentTranslationHandler {
       );
     }
 
-    const supported = new Set(['from', 'formality', 'outputFormat', 'enableMinification']);
+    const supported = new Set(['from', 'formality', 'glossary', 'outputFormat', 'enableMinification']);
     warnIgnoredOptions('document', options, supported);
 
     validateLanguageCodes([options.to]);
 
+    // The API rejects a document glossary without source_lang: "source_lang has
+    // to be specified in order to use a glossary."
+    if (options.glossary && options.glossary.length > 0 && !options.from) {
+      throw new ValidationError(
+        'Source language (--from) is required when using a glossary',
+        'Example: deepl translate --from en --to es --glossary my-glossary report.pdf --output report.es.pdf'
+      );
+    }
+
     const outputPath = options.output!;
 
     const translationOptions = buildBaseTranslationOptions(options);
 
+    await applyGlossarySelection(translationOptions, options, this.ctx.glossaryService);
+
     if (options.outputFormat) {
       translationOptions.outputFormat = options.outputFormat;
     }
diff --git a/src/cli/commands/translate/translation-options-factory.ts b/src/cli/commands/translate/translation-options-factory.ts
index b17e24d7..4e353166 100644
--- a/src/cli/commands/translate/translation-options-factory.ts
+++ b/src/cli/commands/translate/translation-options-factory.ts
@@ -28,6 +28,42 @@ export function buildBaseTranslationOptions(options: TranslateOptions): Translat
   return buildBaseLegacy(options);
 }
 
+/**
+ * Resolve `--glossary` values to IDs and place them on `base`. One glossary is
+ * assigned to `glossaryId` so the request keeps the shape — and cache key — it
+ * had before multiple glossaries were supported; several go to `glossaryIds`,
+ * in the order given, because the API applies the last glossary that defines a
+ * conflicting term.
+ *
+ * Separate from `applySharedTmAndGlossary` because document translation
+ * supports glossaries but not translation memories.
+ */
+export async function applyGlossarySelection<
+  T extends { glossaryId?: string; glossaryIds?: string[] },
+>(
+  base: T,
+  options: TranslateOptions,
+  glossaryService: GlossaryService,
+): Promise<void> {
+  if (!options.glossary || options.glossary.length === 0) {
+    return;
+  }
+
+  // Resolved sequentially so the service's resolution cache is populated
+  // before the next name-or-ID lookup needs the glossary list.
+  const ids: string[] = [];
+  for (const nameOrId of options.glossary) {
+    ids.push(await resolveGlossaryId(glossaryService, nameOrId));
+  }
+
+  const [only] = ids;
+  if (ids.length === 1 && only) {
+    base.glossaryId = only;
+  } else {
+    base.glossaryIds = ids;
+  }
+}
+
 export interface SharedTmAndGlossaryDeps {
   glossaryService: GlossaryService;
   translationService: TranslationService;
@@ -68,21 +104,7 @@ export async function applySharedTmAndGlossary<
   options: TranslateOptions,
   deps: SharedTmAndGlossaryDeps,
 ): Promise<void> {
-  if (options.glossary && options.glossary.length > 0) {
-    // Resolved sequentially so the service's resolution cache is populated
-    // before the next name-or-ID lookup needs the glossary list.
-    const ids: string[] = [];
-    for (const nameOrId of options.glossary) {
-      ids.push(await resolveGlossaryId(deps.glossaryService, nameOrId));
-    }
-
-    const [only] = ids;
-    if (ids.length === 1 && only) {
-      base.glossaryId = only;
-    } else {
-      base.glossaryIds = ids;
-    }
-  }
+  await applyGlossarySelection(base, options, deps.glossaryService);
 
   if (options.translationMemory) {
     const cache = deps.tmCache ?? new Map<string, string>();
diff --git a/tests/e2e/cli-document-translation.e2e.test.ts b/tests/e2e/cli-document-translation.e2e.test.ts
index 17e9ff50..9ae90892 100644
--- a/tests/e2e/cli-document-translation.e2e.test.ts
+++ b/tests/e2e/cli-document-translation.e2e.test.ts
@@ -28,6 +28,73 @@ describe('Document Translation E2E', () => {
     );
   };
 
+  describe('--glossary on a document', () => {
+    // Handler-level validation runs after the API-key gate, so these need a key
+    // to be reachable. The dead endpoint keeps the run off the network for the
+    // cases that get past validation.
+    const DUMMY_KEY = 'e2e-doc-glossary-key:fx';
+    const DEAD_URL = 'http://127.0.0.1:9';
+
+    const pdfPath = (name: string): string => {
+      const file = path.join(testDir, `${name}.pdf`);
+      fs.writeFileSync(file, Buffer.from('%PDF-1.4 test content'));
+      return file;
+    };
+
+    const run = (args: string) =>
+      helpers.runCLIExpectError(args, { apiKey: DUMMY_KEY });
+
+    it('should require --from, which the API demands for a document glossary', () => {
+      const file = pdfPath('glossary-doc');
+      const out = path.join(testDir, 'glossary-doc.de.pdf');
+
+      const result = run(
+        `translate "${file}" --to de --output "${out}" --glossary my-glossary --api-url ${DEAD_URL}`,
+      );
+
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toContain('--from');
+      expect(result.output).toMatch(/glossary/i);
+    });
+
+    it('should no longer report --glossary as unsupported for documents', () => {
+      const file = pdfPath('glossary-doc2');
+      const out = path.join(testDir, 'glossary-doc.de2.pdf');
+
+      const result = run(
+        `translate "${file}" --from en --to de --output "${out}" --glossary my-glossary --api-url ${DEAD_URL}`,
+      );
+
+      expect(result.output).not.toMatch(/does not support/i);
+    });
+
+    it('should accept a repeated --glossary on a document', () => {
+      const file = pdfPath('glossary-doc3');
+      const out = path.join(testDir, 'glossary-doc.de3.pdf');
+
+      const result = run(
+        `translate "${file}" --from en --to de --output "${out}" ` +
+          `--glossary base-terms --glossary project-overrides --api-url ${DEAD_URL}`,
+      );
+
+      expect(result.output).not.toMatch(/unknown option/i);
+      expect(result.output).not.toMatch(/does not support/i);
+    });
+
+    it('should still reject a sixth --glossary on a document', () => {
+      const file = pdfPath('glossary-doc4');
+      const out = path.join(testDir, 'glossary-doc.de4.pdf');
+
+      const result = run(
+        `translate "${file}" --from en --to de --output "${out}" ` +
+          `--glossary a --glossary b --glossary c --glossary d --glossary e --glossary f`,
+      );
+
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toMatch(/at most 5 times/i);
+    });
+  });
+
   describe('--output-format flag', () => {
     it('should accept valid output formats', () => {
       // Create a test file
diff --git a/tests/integration/cli-document-translation.integration.test.ts b/tests/integration/cli-document-translation.integration.test.ts
index 9c477bd0..72689c9b 100644
--- a/tests/integration/cli-document-translation.integration.test.ts
+++ b/tests/integration/cli-document-translation.integration.test.ts
@@ -41,6 +41,87 @@ describe('Document Translation Integration', () => {
     nock.cleanAll();
   });
 
+  describe('Service-level: glossaries on the multipart upload', () => {
+    const A = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+    const B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+
+    /**
+     * Runs one upload and hands back the raw multipart body, so the encoding
+     * the API actually requires is asserted rather than assumed.
+     */
+    const uploadWith = async (
+      glossary: { glossaryId?: string; glossaryIds?: string[] },
+      label: string,
+    ): Promise<string> => {
+      const client = new DeepLClient(API_KEY, { maxRetries: 0 });
+      clients.push(client);
+      const service = new DocumentTranslationService(client);
+
+      const inputPath = path.join(testDir, `glossary-${label}.pdf`);
+      const outputPath = path.join(testDir, `glossary-${label}-out.pdf`);
+      fs.writeFileSync(inputPath, Buffer.from('%PDF-1.4 test content'));
+
+      let capturedBody = '';
+      nock(FREE_API_URL)
+        .post('/v2/document', (body: string) => {
+          capturedBody = body;
+          return true;
+        })
+        .reply(200, { document_id: `doc-${label}`, document_key: `key-${label}` });
+
+      nock(FREE_API_URL)
+        .post(`/v2/document/doc-${label}`)
+        .reply(200, { document_id: `doc-${label}`, status: 'done', billed_characters: 10 });
+
+      nock(FREE_API_URL)
+        .post(`/v2/document/doc-${label}/result`)
+        .reply(200, Buffer.from('%PDF-1.4 translated'));
+
+      await service.translateDocument(inputPath, outputPath, {
+        targetLang: 'de',
+        sourceLang: 'en',
+        ...glossary,
+      });
+
+      return capturedBody;
+    };
+
+    it('sends glossary_id for a single glossary', async () => {
+      const body = await uploadWith({ glossaryId: A }, 'single');
+
+      expect(body).toContain('name="glossary_id"');
+      expect(body).toContain(A);
+      expect(body).not.toContain('name="glossary_ids"');
+    });
+
+    /**
+     * Multipart uploads keep only the first of several repeated fields, so the
+     * IDs must arrive comma-joined with no whitespace or the API silently
+     * applies just one glossary.
+     */
+    it('comma-joins several glossaries into one glossary_ids field', async () => {
+      const body = await uploadWith({ glossaryIds: [A, B] }, 'multi');
+
+      expect(body).toContain('name="glossary_ids"');
+      expect(body).toContain(`${A},${B}`);
+      expect(body.match(/name="glossary_ids"/g)).toHaveLength(1);
+      expect(body).not.toContain(`${A}, ${B}`);
+    });
+
+    it('preserves the given order, which selects the winning glossary', async () => {
+      const body = await uploadWith({ glossaryIds: [B, A] }, 'reversed');
+
+      expect(body).toContain(`${B},${A}`);
+    });
+
+    it('sends no glossary field when none is selected', async () => {
+      const body = await uploadWith({}, 'none');
+
+      expect(body).not.toContain('name="glossary_id"');
+      expect(body).not.toContain('name="glossary_ids"');
+    });
+  });
+
   describe('Service-level: happy path (upload -> poll -> download)', () => {
     it('should complete the full document translation workflow', async () => {
       const client = new DeepLClient(API_KEY, { maxRetries: 0 });
diff --git a/tests/unit/document-translation-handler.test.ts b/tests/unit/document-translation-handler.test.ts
index 16331882..03b9fb73 100644
--- a/tests/unit/document-translation-handler.test.ts
+++ b/tests/unit/document-translation-handler.test.ts
@@ -103,6 +103,129 @@ describe('DocumentTranslationHandler', () => {
       expect(MockLogger.warn).toHaveBeenCalledWith(expect.stringContaining('document'));
     });
 
+    describe('glossaries', () => {
+      const A = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+      const B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+
+      const resolveTo = (mapping: Record<string, string>): void => {
+        mocks.glossaryService.resolveGlossaryId.mockImplementation(
+          async (nameOrId: string) => {
+            const id = mapping[nameOrId];
+            if (!id) throw new ValidationError(`Glossary "${nameOrId}" not found`);
+            return id;
+          },
+        );
+      };
+
+      it('should forward a single resolved glossary as glossaryId', async () => {
+        resolveTo({ 'base-terms': A });
+
+        await handler.translateDocument(
+          '/tmp/doc.pdf',
+          defaultOptions({ from: 'en', glossary: ['base-terms'] }),
+        );
+
+        expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalledWith(
+          '/tmp/doc.pdf',
+          '/tmp/output.pdf',
+          expect.objectContaining({ glossaryId: A }),
+          expect.any(Function),
+        );
+        const passed = mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
+        expect(passed?.glossaryIds).toBeUndefined();
+      });
+
+      it('should forward several resolved glossaries as glossaryIds in order', async () => {
+        resolveTo({ 'base-terms': A, 'project-overrides': B });
+
+        await handler.translateDocument(
+          '/tmp/doc.pdf',
+          defaultOptions({ from: 'en', glossary: ['base-terms', 'project-overrides'] }),
+        );
+
+        expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalledWith(
+          '/tmp/doc.pdf',
+          '/tmp/output.pdf',
+          expect.objectContaining({ glossaryIds: [A, B] }),
+          expect.any(Function),
+        );
+        const passed = mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
+        expect(passed?.glossaryId).toBeUndefined();
+      });
+
+      it('should preserve the reversed order, which changes the winning glossary', async () => {
+        resolveTo({ 'base-terms': A, 'project-overrides': B });
+
+        await handler.translateDocument(
+          '/tmp/doc.pdf',
+          defaultOptions({ from: 'en', glossary: ['project-overrides', 'base-terms'] }),
+        );
+
+        expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalledWith(
+          '/tmp/doc.pdf',
+          '/tmp/output.pdf',
+          expect.objectContaining({ glossaryIds: [B, A] }),
+          expect.any(Function),
+        );
+      });
+
+      it('should no longer warn that document mode ignores --glossary', async () => {
+        const { Logger: MockLogger } = jest.requireMock('../../src/utils/logger');
+        resolveTo({ 'base-terms': A });
+
+        await handler.translateDocument(
+          '/tmp/doc.pdf',
+          defaultOptions({ from: 'en', glossary: ['base-terms'] }),
+        );
+
+        const warnings = MockLogger.warn.mock.calls.map((call: unknown[]) => String(call[0]));
+        expect(warnings.some((w: string) => w.includes('--glossary'))).toBe(false);
+      });
+
+      /** The API rejects a document glossary without source_lang. */
+      it('should require --from when a glossary is given', async () => {
+        expect.assertions(3);
+        resolveTo({ 'base-terms': A });
+
+        await expect(
+          handler.translateDocument('/tmp/doc.pdf', defaultOptions({ glossary: ['base-terms'] })),
+        ).rejects.toThrow(ValidationError);
+        try {
+          await handler.translateDocument('/tmp/doc.pdf', defaultOptions({ glossary: ['base-terms'] }));
+        } catch (error) {
+          expect((error as ValidationError).message).toContain('--from');
+        }
+        expect(mocks.documentTranslationService.translateDocument).not.toHaveBeenCalled();
+      });
+
+      it('should not require --from when no glossary is given', async () => {
+        await handler.translateDocument('/tmp/doc.pdf', defaultOptions());
+
+        expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalled();
+      });
+
+      it('should fail without uploading when a glossary name does not resolve', async () => {
+        resolveTo({ 'base-terms': A });
+
+        await expect(
+          handler.translateDocument(
+            '/tmp/doc.pdf',
+            defaultOptions({ from: 'en', glossary: ['base-terms', 'no-such-glossary'] }),
+          ),
+        ).rejects.toThrow(/no-such-glossary/);
+        expect(mocks.documentTranslationService.translateDocument).not.toHaveBeenCalled();
+      });
+
+      it('should send no glossary params when the flag is absent', async () => {
+        await handler.translateDocument('/tmp/doc.pdf', defaultOptions({ from: 'en' }));
+
+        const passed = mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
+        expect(passed?.glossaryId).toBeUndefined();
+        expect(passed?.glossaryIds).toBeUndefined();
+        expect(mocks.glossaryService.resolveGlossaryId).not.toHaveBeenCalled();
+      });
+    });
+
     it('should pass outputFormat through', async () => {
       await handler.translateDocument('/tmp/doc.pdf', defaultOptions({ outputFormat: 'pdf' }));
 
diff --git a/tests/unit/translate-command.test.ts b/tests/unit/translate-command.test.ts
index be69629e..d8f4904f 100644
--- a/tests/unit/translate-command.test.ts
+++ b/tests/unit/translate-command.test.ts
@@ -3700,7 +3700,6 @@ describe('TranslateCommand', () => {
           tagHandling: 'xml',
           modelType: 'quality_optimized',
           customInstruction: ['Be formal'],
-          glossary: ['my-glossary'],
           preserveCode: true,
         });
 
@@ -3710,9 +3709,6 @@ describe('TranslateCommand', () => {
         expect(warnSpy).toHaveBeenCalledWith(
           expect.stringMatching(/--split-sentences/)
         );
-        expect(warnSpy).toHaveBeenCalledWith(
-          expect.stringMatching(/--glossary/)
-        );
         expect(warnSpy).toHaveBeenCalledWith(
           expect.stringMatching(/--preserve-code/)
         );
@@ -3730,6 +3726,21 @@ describe('TranslateCommand', () => {
 
         expect(warnSpy).not.toHaveBeenCalled();
       });
+
+      it('should not warn about --glossary, which document mode now supports', async () => {
+        (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValueOnce(
+          'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+        );
+
+        await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+          to: 'es',
+          output: '/output.pdf',
+          from: 'en',
+          glossary: ['my-glossary'],
+        });
+
+        expect(warnSpy).not.toHaveBeenCalled();
+      });
     });
 
     it('should not warn for undefined or false boolean options', async () => {

From 4e0ce43ba548a17b4a93636065cfb7c454323552 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 06:44:53 -0400
Subject: [PATCH 008/256] docs: document glossary support for document
 translation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Record the repeatable flag, the mandatory --from, and that translation
memories remain unsupported for documents.

Also note that glossary matching is context-dependent for documents exactly as
it is for text — a term applied in one sentence may be left alone in another,
and a bare word list often gets few terms applied. This was mistaken for a
document-specific defect while investigating, so it is written down.
---
 CHANGELOG.md | 2 ++
 docs/API.md  | 8 ++++++++
 2 files changed, 10 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index db37be6d..a29d6d41 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API). It was previously accepted and then silently discarded with a "document mode does not support --glossary" warning, even though `POST /v2/document` supports glossaries. Repeating the flag works here too, with the same last-one-wins precedence. `--from` is required, because the API rejects a document glossary without a source language; `--translation-memory` remains unsupported for documents. Note that glossary matching is context-dependent for documents exactly as it is for text — a term applied in one sentence may be left alone in another.
+
 - **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API, including the two encodings the endpoints require: repeated form fields for `POST /v2/translate`, and one comma-joined value for the multipart `POST /v2/document`, which keeps only the first of several repeated fields and would otherwise silently apply just one glossary.
 
 - **cli**: `deepl correct` command (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`), but not `--style`/`--tone`, which the correct endpoint does not accept. Results are cached under a separate `correct:` namespace so corrections and rephrasings of the same text never collide.
diff --git a/docs/API.md b/docs/API.md
index 44463398..32bfa9fa 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -410,6 +410,13 @@ deepl translate document.pdf --to es --output document.es.docx --output-format d
 # Enable document minification for smaller file size (PPTX/DOCX only)
 deepl translate presentation.pptx --to de --output presentation.de.pptx --enable-minification
 deepl translate report.docx --to fr --output report.fr.docx --enable-minification
+
+# Apply a glossary (--from is required for document glossaries)
+deepl translate report.docx --from en --to de --output report.de.docx --glossary tech-terms
+
+# Repeat --glossary for up to 5; the last one wins a conflicting term
+deepl translate report.docx --from en --to de --output report.de.docx \
+  --glossary base-terms --glossary project-overrides
 ```
 
 **Supported Document Formats:**
@@ -440,6 +447,7 @@ deepl translate report.docx --to fr --output report.fr.docx --enable-minificatio
 - Large documents may take several seconds to translate
 - Maximum file sizes: 30MB (document API, all formats), 100 KiB (cached text API)
 - **Document minification** (`--enable-minification`): Reduces file size for PPTX and DOCX files only. Useful for large presentations and documents.
+- **Glossaries**: `--glossary` applies to documents and is repeatable up to 5, with the same last-one-wins precedence as text translation. `--from` is required — the API rejects a document glossary without a source language ("source_lang has to be specified in order to use a glossary"). Glossary matching is context-dependent exactly as it is for text: a term may be applied in one sentence and left alone in another, and a bare newline-separated word list often gets few terms applied. `--translation-memory` remains unsupported for documents.
 
 **Directory translation:**
 

From 1733329255c29eeb48065efc69ef9336177c0553 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 06:58:52 -0400
Subject: [PATCH 009/256] fix(docs): add the required --from to every
 --glossary example

A glossary has always required --from on every path, but the flag was missing
from six documented invocations, so each would have exited 6 if a reader had
copied it. Two predate this work (the API.md glossary-usage block and the
inline help example) and the rest came in with the repeatable flag.

The Commander help for --glossary now states the --from requirement, following
the existing convention of --tm-threshold noting its own, and records that the
flag applies to documents as well.

Add the document glossary examples and feature note to the README, which the
earlier commits left covering only text translation.

Fold the glossary into the document handler's existing "only supported options
produce no warning" test instead of asserting it separately: glossary is now a
supported document option, so it belongs in that list, and a separate test
duplicated the handler suite's own coverage.
---
 README.md                              | 10 +++++++++-
 docs/API.md                            | 10 +++++-----
 src/cli/commands/register-translate.ts |  7 ++++---
 tests/unit/translate-command.test.ts   | 16 +++-------------
 4 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index aa0b3db9..0ea31262 100644
--- a/README.md
+++ b/README.md
@@ -377,6 +377,13 @@ deepl translate contract.pdf --to de --formality more --output contract.de.pdf
 # Specify source language
 deepl translate document.pdf --from en --to es --output document.es.pdf
 
+# Apply a glossary (--from is required whenever a glossary is used)
+deepl translate report.docx --from en --to de --glossary tech-terms --output report.de.docx
+
+# Repeat --glossary for up to 5; the last one wins a conflicting term
+deepl translate report.docx --from en --to de --output report.de.docx \
+  --glossary base-terms --glossary project-overrides
+
 # Convert PDF to DOCX during translation (ONLY supported conversion)
 deepl translate document.pdf --to es --output-format docx --output document.es.docx
 # Translates PDF to Spanish and converts to editable Word format
@@ -393,6 +400,7 @@ deepl translate document.pdf --to es --output-format docx --output document.es.d
 - ✅ **Progress Tracking** - Real-time status updates during translation
 - ✅ **Large Files** - Handles documents up to 30MB
 - ✅ **Cost Tracking** - Shows billed characters after translation
+- ✅ **Glossaries** - `--glossary` applies to documents too, repeatable up to 5 (requires `--from`). Translation memories are not supported for documents.
 - ✅ **Async Processing** - Documents are translated on DeepL servers with polling
 
 **Supported Formats:**
@@ -1284,7 +1292,7 @@ authentication	Authentifizierung
 
 ```bash
 # Layer project overrides on top of shared base terminology
-deepl translate "Hello world" --to de --glossary base-terms --glossary project-overrides
+deepl translate "Hello world" --from en --to de --glossary base-terms --glossary project-overrides
 ```
 
 ### Translation Memories
diff --git a/docs/API.md b/docs/API.md
index 32bfa9fa..966278d4 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -544,10 +544,10 @@ deepl translate complex.xml --to de --tag-handling xml \
 
 ```bash
 # Use glossary for consistent terminology
-deepl translate "API documentation" --to es --glossary tech-terms
+deepl translate "API documentation" --from en --to es --glossary tech-terms
 
 # Use glossary by ID
-deepl translate README.md --to fr --glossary abc-123-def-456 --output README.fr.md
+deepl translate README.md --from en --to fr --glossary abc-123-def-456 --output README.fr.md
 ```
 
 **Multiple glossaries on one request:**
@@ -556,13 +556,13 @@ Repeat `--glossary` to apply up to 5 glossaries to a single request. Their entri
 
 ```bash
 # Shared base terminology, overridden by project-specific terms
-deepl translate "Hello world" --to de --glossary base-terms --glossary project-overrides
+deepl translate "Hello world" --from en --to de --glossary base-terms --glossary project-overrides
 
 # Reversing the order makes base-terms win any conflicting entry
-deepl translate "Hello world" --to de --glossary project-overrides --glossary base-terms
+deepl translate "Hello world" --from en --to de --glossary project-overrides --glossary base-terms
 
 # Names and UUIDs can be mixed
-deepl translate README.md --to fr --output README.fr.md \
+deepl translate README.md --from en --to fr --output README.fr.md \
   --glossary abc-123-def-456 --glossary house-style
 ```
 
diff --git a/src/cli/commands/register-translate.ts b/src/cli/commands/register-translate.ts
index 9351bf83..e6210757 100644
--- a/src/cli/commands/register-translate.ts
+++ b/src/cli/commands/register-translate.ts
@@ -26,7 +26,7 @@ export function registerTranslate(
     .option('--context <text>', 'Additional context to improve translation quality')
     .option(
       '--glossary <name-or-id>',
-      `Use glossary by name or ID (repeatable, max ${MAX_GLOSSARIES_PER_REQUEST}; when several define the same term, the last one wins)`,
+      `Use glossary by name or ID (requires --from; repeatable, max ${MAX_GLOSSARIES_PER_REQUEST}; when several define the same term, the last one wins). Applies to text, files and documents.`,
       (val: string, prev: string[] | undefined) => (prev ?? []).concat([val]),
     )
     .option(
@@ -81,8 +81,9 @@ Examples:
   $ deepl translate ./docs --to de,es,fr --pattern "*.md"
   $ echo "Hello" | deepl translate --to ja
   $ deepl translate report.pdf --to de --output-format docx
-  $ deepl translate "Hello" --to es --formality more --glossary my-glossary
-  $ deepl translate "Hello" --to es --glossary base-terms --glossary project-overrides
+  $ deepl translate "Hello" --from en --to es --formality more --glossary my-glossary
+  $ deepl translate "Hello" --from en --to es --glossary base-terms --glossary project-overrides
+  $ deepl translate report.docx --from en --to de --glossary tech-terms --output report.de.docx
   $ deepl translate page.html --to fr --tag-handling html
   $ deepl translate "Hello" --to es --custom-instruction "Use informal language"
   $ deepl translate ./docs --to es --dry-run
diff --git a/tests/unit/translate-command.test.ts b/tests/unit/translate-command.test.ts
index d8f4904f..6256906c 100644
--- a/tests/unit/translate-command.test.ts
+++ b/tests/unit/translate-command.test.ts
@@ -3715,19 +3715,6 @@ describe('TranslateCommand', () => {
       });
 
       it('should not warn when only supported options are used in document mode', async () => {
-        await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
-          to: 'es',
-          output: '/output.pdf',
-          from: 'en',
-          formality: 'more',
-          outputFormat: 'docx',
-          enableMinification: true,
-        });
-
-        expect(warnSpy).not.toHaveBeenCalled();
-      });
-
-      it('should not warn about --glossary, which document mode now supports', async () => {
         (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValueOnce(
           'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
         );
@@ -3736,7 +3723,10 @@ describe('TranslateCommand', () => {
           to: 'es',
           output: '/output.pdf',
           from: 'en',
+          formality: 'more',
           glossary: ['my-glossary'],
+          outputFormat: 'docx',
+          enableMinification: true,
         });
 
         expect(warnSpy).not.toHaveBeenCalled();

From a79698829eb12f7127f96e23b0d09fc656db627e Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 07:05:46 -0400
Subject: [PATCH 010/256] docs(watch): note that --glossary needs --from

/v2/translate rejects a glossary without a source language ("Use of a glossary
requires the source_lang parameter to be specified"), and watch passes --from
straight through without checking it, so --glossary alone fails on every file
change. Say so in the watch option docs and its inline help.

sync needs no equivalent note: it has no --from, taking the source language
from the required source_locale field in .deepl-sync.yaml, so its requests
always carry one.
---
 README.md                          | 2 +-
 docs/API.md                        | 2 +-
 src/cli/commands/register-watch.ts | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 0ea31262..3a6fc3ed 100644
--- a/README.md
+++ b/README.md
@@ -1287,7 +1287,7 @@ authentication	Authentifizierung
 - **Direct updates** - v3 API uses PATCH endpoints for efficient updates (no delete+recreate)
 - **Smart defaults** - `--target` flag only required for multilingual glossaries
 - **Visual indicators** - 📖 for single-target, 📚 for multilingual glossaries
-- **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms
+- **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms (always alongside `--from`; the API rejects a glossary without a source language)
 - **Several glossaries at once** - Repeat `--glossary` on `translate` for up to 5 glossaries; entries are merged and the last glossary given wins any conflicting term
 
 ```bash
diff --git a/docs/API.md b/docs/API.md
index 966278d4..2d8e523e 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1102,7 +1102,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 - `--formality LEVEL` - Formality level: `default`, `more`, `less`, `prefer_more`, `prefer_less`, `formal`, `informal`
 - `--preserve-code` - Preserve code blocks
 - `--preserve-formatting` - Preserve line breaks and whitespace formatting
-- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology
+- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. Pass `--from` as well: the API refuses a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"), and `watch` does not check for it up front, so every file change fails on the API call instead. Unlike `translate`, `watch` takes a single glossary.
 
 **Git Integration:**
 
diff --git a/src/cli/commands/register-watch.ts b/src/cli/commands/register-watch.ts
index d358340d..2bedbca0 100644
--- a/src/cli/commands/register-watch.ts
+++ b/src/cli/commands/register-watch.ts
@@ -21,7 +21,7 @@ export function registerWatch(
     .option('-o, --output <path>', 'Output directory (default: <path>/translations or same dir for files)')
     .optionsGroup('Translation Quality:')
     .addOption(new Option('--formality <level>', 'Formality level').choices(['default', 'more', 'less', 'prefer_more', 'prefer_less', 'formal', 'informal']))
-    .option('--glossary <name-or-id>', 'Use glossary by name or ID')
+    .option('--glossary <name-or-id>', 'Use glossary by name or ID (pass --from as well; the API rejects a glossary without a source language)')
     .option('--preserve-code', 'Preserve code blocks and variables during translation')
     .option('--preserve-formatting', 'Preserve line breaks and whitespace formatting')
     .optionsGroup('Watch Behavior:')

From 00219e215d5b19594bc254310f0cb2a4ea0b48d5 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 08:34:31 -0400
Subject: [PATCH 011/256] fix(voice): fail when a session ends without a
 translation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A voice session that ended with the audio transcribed but no translation
for a requested target language resolved successfully, printing an empty
translation line and exiting 0. A script consuming the output saw success
with the translation missing.

Such a session now rejects with a VoiceError (exit 9) naming the
untranslated languages. Audio containing no speech concludes no source
text and is translated to nothing, which is legitimate, so the check
applies only when a source transcript exists.

The two frame shapes that reach the same place — a whitespace-only
translation and one that stayed tentative without ever concluding — count
as missing, because neither reaches the printed output.

Unit tests that emitted source frames with no target frame have gained one:
under this rule that shape is a failed session, not a valid one.
---
 CHANGELOG.md                            |   1 +
 docs/API.md                             |   3 +
 src/services/voice-stream-session.ts    |  28 +++++
 tests/unit/voice-service.test.ts        |  15 +++
 tests/unit/voice-stream-session.test.ts | 133 ++++++++++++++++++++++++
 5 files changed, 180 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a29d6d41..e47fc982 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -68,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **voice**: A session that ends with the audio transcribed but no translation for a requested `--to` language now fails with exit code 9 and names the languages, instead of printing an empty translation line and exiting 0. Silent partial output was the worse failure: a script consuming `deepl voice` output saw success with the translation missing. Audio containing no speech transcribes to nothing and translates to nothing, which is legitimate and still exits 0, so the check only applies when a source transcript exists. Whitespace-only and tentative-but-never-concluded translations count as missing, since neither reaches the printed output. Investigated as an intermittent (~1 in 4) empty translated line; the leading hypothesis was disproved with frame-level traces of live sessions — the server sends `end_of_stream` strictly after `end_of_target_transcript`, and the client only tears the socket down on `end_of_stream`, so there is no client-side teardown race. Reconnect was ruled out too: a socket dropped after end-of-source cannot be resumed (the API returns `410 Gone`) and already exited non-zero. The empty line did not reproduce in 64 live runs across pacing, burst, multi-target, and concurrency variations, so the trigger appears to be server-side and transient — which is exactly why the client needs to detect it rather than report success.
 - **formats**: TOML reconstruction escapes U+2028/U+2029 (Unicode line/paragraph separators) in double-quoted values, and literal-string values gaining one fall back to double quotes. Written raw, these characters broke the entry-line scan on the *next* sync (JavaScript's `.` excludes line terminators), which re-appended the key as a duplicate and made the third sync fail to parse the file at all — first sync fine, second silently corrupting, third crashing. Found by the property-based round-trip suite.
 - **formats**: `.properties` reconstruction escapes leading spaces in values (`\ `), which the value parser otherwise strips on the next read — a translation beginning with a space silently lost it on every subsequent sync. Leading tabs, trailing spaces, and newlines were already escaped correctly. Found by the property-based round-trip suite.
 - **sync**: `--auto-commit` now recognises its own translation output rather than only the files a given run wrote, which fixes two related problems. A translation left on disk by an earlier refused run was classed as an unrelated modification, so auto-commit refused forever and the user had to commit it by hand; it is now committed once the genuinely unrelated changes are dealt with. And in `--watch` mode, where the same path runs once per trigger, a trigger that translated nothing skipped the checks entirely and reported success while a commit was still owed. Staging is also driven by what is actually dirty, so a rewrite that produced identical bytes no longer attempts an empty commit. Ownership is derived from the lockfile's tracked source files, with each file matched to its own bucket so one bucket's `target_path_pattern` cannot claim another's output.
diff --git a/docs/API.md b/docs/API.md
index 2d8e523e..c195bf32 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -999,6 +999,8 @@ deepl voice [options] <file>
 
 > **Note:** All formality values (`default`, `formal`, `informal`, `more`, `less`, `prefer_more`, `prefer_less`) are accepted. The voice API natively uses `formal`/`informal` (in addition to `more`/`less`), while the translate API uses `prefer_more`/`prefer_less`.
 
+> **Note:** If the server ends the stream after transcribing the audio but without sending a translation for one of `--to`'s languages, the command fails with exit code 9 and names the languages, rather than printing an empty translation line and exiting 0. Audio containing no speech transcribes to nothing and is translated to nothing, which is not an error and still exits 0.
+
 #### Supported Audio Formats
 
 | Extension       | Content Type                          |
@@ -3277,6 +3279,7 @@ Voice API call failed for a reason other than authentication, rate limiting, or
 - `deepl voice` when the plan does not include the Voice API (pre-flight check in the voice client)
 - Voice streaming URL validation failures (`src/api/voice-client.ts`: non-`wss://` scheme, unparseable URL, disallowed host)
 - Voice session lifecycle errors (failed to open, unexpected close)
+- `deepl voice` when the stream ends with the source transcribed but no translation for a requested target language
 
 Remediation: confirm Pro/Enterprise plan, verify the session configuration, and retry.
 
diff --git a/src/services/voice-stream-session.ts b/src/services/voice-stream-session.ts
index abc9aff0..7d3f7786 100644
--- a/src/services/voice-stream-session.ts
+++ b/src/services/voice-stream-session.ts
@@ -136,6 +136,19 @@ export class VoiceStreamSession {
         this.ws.close();
         this.closeInput();
         this.finalizeTranscripts();
+
+        const untranslated = this.untranslatedTargets();
+        if (untranslated.length > 0) {
+          this.fail(
+            reject,
+            new VoiceError(
+              `Voice session ended without a translation for: ${untranslated.join(', ')}.`,
+              'The audio was transcribed but the server sent no translated text. Retry the request.',
+            ),
+          );
+          return;
+        }
+
         resolve({
           sessionId: this.session.session_id,
           source: this.sourceTranscript,
@@ -259,6 +272,21 @@ export class VoiceStreamSession {
     }
   }
 
+  /**
+   * Target languages the server ended the stream without translating. Audio
+   * that contained no speech concludes no source text either and is not
+   * treated as a failure; only a transcribed source with a missing
+   * translation is, since that output would otherwise look successful.
+   */
+  private untranslatedTargets(): string[] {
+    if (this.sourceTranscript.text.trim() === '') {
+      return [];
+    }
+    return Array.from(this.targetTranscripts.values())
+      .filter((transcript) => transcript.text.trim() === '')
+      .map((transcript) => transcript.lang);
+  }
+
   private finalizeTranscripts(): void {
     for (const [transcript, parts] of this.textParts) {
       transcript.text = parts.join(' ');
diff --git a/tests/unit/voice-service.test.ts b/tests/unit/voice-service.test.ts
index a004ed27..4af71fdf 100644
--- a/tests/unit/voice-service.test.ts
+++ b/tests/unit/voice-service.test.ts
@@ -338,6 +338,11 @@ describe('VoiceService', () => {
           concluded: [{ text: 'world', language: 'en', start_time: 0.5, end_time: 1 }],
           tentative: [],
         });
+        cb.onTargetTranscript?.({
+          language: 'de',
+          concluded: [{ text: 'Hallo Welt', start_time: 0, end_time: 1 }],
+          tentative: [],
+        });
         cb.onEndOfStream?.();
       });
 
@@ -367,6 +372,11 @@ describe('VoiceService', () => {
             tentative: [],
           });
         }
+        cb.onTargetTranscript?.({
+          language: 'de',
+          concluded: [{ text: 'Segmente', start_time: 0, end_time: 1 }],
+          tentative: [],
+        });
         cb.onEndOfStream?.();
       });
 
@@ -391,6 +401,11 @@ describe('VoiceService', () => {
           ],
           tentative: [],
         });
+        cb.onTargetTranscript?.({
+          language: 'de',
+          concluded: [{ text: 'Eins Zwei Drei', start_time: 0, end_time: 1.5 }],
+          tentative: [],
+        });
         cb.onEndOfStream?.();
       });
 
diff --git a/tests/unit/voice-stream-session.test.ts b/tests/unit/voice-stream-session.test.ts
index 0c6ea32e..cf451a5f 100644
--- a/tests/unit/voice-stream-session.test.ts
+++ b/tests/unit/voice-stream-session.test.ts
@@ -10,6 +10,7 @@ import { VoiceClient } from '../../src/api/voice-client.js';
 import { VoiceError } from '../../src/utils/errors.js';
 import type {
   VoiceSessionResponse,
+  VoiceSessionResult,
   VoiceTranslateOptions,
   VoiceStreamCallbacks,
 } from '../../src/types/voice.js';
@@ -602,6 +603,11 @@ describe('VoiceStreamSession', () => {
               concluded: [{ text: 'world', language: 'en', start_time: 0.5, end_time: 1 }],
               tentative: [],
             });
+            callbacks.onTargetTranscript?.({
+              language: 'de',
+              concluded: [{ text: 'Hallo Welt', start_time: 0, end_time: 1 }],
+              tentative: [],
+            });
             callbacks.onEndOfStream?.();
           });
         });
@@ -667,6 +673,11 @@ describe('VoiceStreamSession', () => {
               concluded: [{ text: 'Bonjour', language: 'fr', start_time: 0, end_time: 1 }],
               tentative: [],
             });
+            callbacks.onTargetTranscript?.({
+              language: 'de',
+              concluded: [{ text: 'Guten Tag', start_time: 0, end_time: 1 }],
+              tentative: [],
+            });
             callbacks.onEndOfStream?.();
           });
         });
@@ -680,6 +691,128 @@ describe('VoiceStreamSession', () => {
     });
   });
 
+  describe('incomplete translations', () => {
+    /** Drives a session to end_of_stream after emitting the given frames. */
+    function runWithFrames(
+      frames: (callbacks: VoiceStreamCallbacks) => void,
+      sessionOptions: VoiceTranslateOptions = options,
+      chunks: AsyncGenerator<Buffer> = emptyChunks(),
+    ): Promise<VoiceSessionResult> {
+      const EventEmitter = require('events');
+      const mockWs = new EventEmitter();
+      mockWs.readyState = 1;
+      mockWs.send = jest.fn();
+      mockWs.close = jest.fn();
+
+      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
+        process.nextTick(() => {
+          mockWs.emit('open');
+          process.nextTick(() => {
+            frames(callbacks);
+            callbacks.onEndOfStream?.();
+          });
+        });
+        return mockWs;
+      });
+
+      const streamSession = new VoiceStreamSession(mockClient, session, sessionOptions);
+      return streamSession.run(chunks);
+    }
+
+    it('should reject when the source was transcribed but a target produced no text', async () => {
+      await expect(
+        runWithFrames((callbacks) => {
+          callbacks.onSourceTranscript?.({
+            concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+            tentative: [],
+          });
+        }),
+      ).rejects.toThrow(VoiceError);
+    });
+
+    it('should name every target language that produced no text', async () => {
+      expect.assertions(3);
+      try {
+        await runWithFrames(
+          (callbacks) => {
+            callbacks.onSourceTranscript?.({
+              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+              tentative: [],
+            });
+            callbacks.onTargetTranscript?.({
+              language: 'fr',
+              concluded: [{ text: 'Bonjour', start_time: 0, end_time: 1 }],
+              tentative: [],
+            });
+          },
+          { targetLangs: ['de', 'fr', 'es'], chunkInterval: 0 },
+        );
+      } catch (error) {
+        expect((error as Error).message).toContain('de');
+        expect((error as Error).message).toContain('es');
+        expect((error as Error).message).not.toContain('fr');
+      }
+    });
+
+    it('should treat a whitespace-only translation as missing', async () => {
+      await expect(
+        runWithFrames((callbacks) => {
+          callbacks.onSourceTranscript?.({
+            concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+            tentative: [],
+          });
+          callbacks.onTargetTranscript?.({
+            language: 'de',
+            concluded: [{ text: '  ', start_time: 0, end_time: 1 }],
+            tentative: [],
+          });
+        }),
+      ).rejects.toThrow(VoiceError);
+    });
+
+    it('should reject when the only translated text stayed tentative', async () => {
+      await expect(
+        runWithFrames((callbacks) => {
+          callbacks.onSourceTranscript?.({
+            concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+            tentative: [],
+          });
+          callbacks.onTargetTranscript?.({
+            language: 'de',
+            concluded: [],
+            tentative: [{ text: 'Hallo', start_time: 0, end_time: 1 }],
+          });
+        }),
+      ).rejects.toThrow(VoiceError);
+    });
+
+    it('should resolve when the audio contained no speech at all', async () => {
+      const result = await runWithFrames(() => undefined);
+
+      expect(result.source.text).toBe('');
+      expect(result.targets[0]!.text).toBe('');
+    });
+
+    it('should close the input generator when rejecting', async () => {
+      const tracked = trackedChunks();
+
+      await expect(
+        runWithFrames(
+          (callbacks) => {
+            callbacks.onSourceTranscript?.({
+              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+              tentative: [],
+            });
+          },
+          options,
+          tracked.chunks,
+        ),
+      ).rejects.toThrow(VoiceError);
+
+      expect(tracked.closed()).toBe(true);
+    });
+  });
+
   describe('callback proxying', () => {
     it('should proxy all callback types', async () => {
       const EventEmitter = require('events');

From f5b5c5350fb9acbc938efc7c4eb49e3b8d56bbcb Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 08:47:43 -0400
Subject: [PATCH 012/256] fix(watch): require --from when --glossary is used

deepl watch --glossary X without --from started a watch session happily and
then failed on every single file change, surfacing a raw server message each
time. The API rejects any translation naming a glossary without a source
language ("Use of a glossary requires the source_lang parameter to be
specified"), which translate already guards against up front for text, files,
and documents.

watch now rejects the combination before the watcher starts, with the same
message the translate handlers use and a watch-shaped example, exiting 6 as
they do. The check runs before the glossary name is resolved, so it costs no
API call.

The option docs and inline help warned the reader that the check was missing;
they now describe the requirement instead.

sync needs no equivalent guard: it has no --from at all, taking the source
language from the required source_locale field in .deepl-sync.yaml, so its
requests always carry one.
---
 CHANGELOG.md                       |  1 +
 README.md                          |  2 +-
 docs/API.md                        |  2 +-
 src/cli/commands/register-watch.ts |  2 +-
 src/cli/commands/watch.ts          |  9 ++++
 tests/e2e/cli-watch.e2e.test.ts    | 61 +++++++++++++++++++++++++++
 tests/unit/watch-command.test.ts   | 68 ++++++++++++++++++++++++++++++
 7 files changed, 142 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e47fc982..813c8aea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -68,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: `--glossary` without `--from` now exits 6 before the watcher starts, instead of starting a session that fails on every single file change with a raw server message. The API rejects any translation naming a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"), which `translate` already guarded against up front for text, files, and documents; `watch` passed `--from` straight through. A long-running command is the worst place for this, since the operator saw the failure once per edit rather than once at launch. The check runs before the glossary name is resolved, so it costs no API call. `sync` needs no equivalent: it has no `--from` at all, taking the source language from the required `source_locale` field in `.deepl-sync.yaml`, so its requests always carry one.
 - **voice**: A session that ends with the audio transcribed but no translation for a requested `--to` language now fails with exit code 9 and names the languages, instead of printing an empty translation line and exiting 0. Silent partial output was the worse failure: a script consuming `deepl voice` output saw success with the translation missing. Audio containing no speech transcribes to nothing and translates to nothing, which is legitimate and still exits 0, so the check only applies when a source transcript exists. Whitespace-only and tentative-but-never-concluded translations count as missing, since neither reaches the printed output. Investigated as an intermittent (~1 in 4) empty translated line; the leading hypothesis was disproved with frame-level traces of live sessions — the server sends `end_of_stream` strictly after `end_of_target_transcript`, and the client only tears the socket down on `end_of_stream`, so there is no client-side teardown race. Reconnect was ruled out too: a socket dropped after end-of-source cannot be resumed (the API returns `410 Gone`) and already exited non-zero. The empty line did not reproduce in 64 live runs across pacing, burst, multi-target, and concurrency variations, so the trigger appears to be server-side and transient — which is exactly why the client needs to detect it rather than report success.
 - **formats**: TOML reconstruction escapes U+2028/U+2029 (Unicode line/paragraph separators) in double-quoted values, and literal-string values gaining one fall back to double quotes. Written raw, these characters broke the entry-line scan on the *next* sync (JavaScript's `.` excludes line terminators), which re-appended the key as a duplicate and made the third sync fail to parse the file at all — first sync fine, second silently corrupting, third crashing. Found by the property-based round-trip suite.
 - **formats**: `.properties` reconstruction escapes leading spaces in values (`\ `), which the value parser otherwise strips on the next read — a translation beginning with a space silently lost it on every subsequent sync. Leading tabs, trailing spaces, and newlines were already escaped correctly. Found by the property-based round-trip suite.
diff --git a/README.md b/README.md
index 3a6fc3ed..c4c5ba30 100644
--- a/README.md
+++ b/README.md
@@ -1287,7 +1287,7 @@ authentication	Authentifizierung
 - **Direct updates** - v3 API uses PATCH endpoints for efficient updates (no delete+recreate)
 - **Smart defaults** - `--target` flag only required for multilingual glossaries
 - **Visual indicators** - 📖 for single-target, 📚 for multilingual glossaries
-- **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms (always alongside `--from`; the API rejects a glossary without a source language)
+- **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms (`--from` is required alongside it; the API rejects a glossary without a source language)
 - **Several glossaries at once** - Repeat `--glossary` on `translate` for up to 5 glossaries; entries are merged and the last glossary given wins any conflicting term
 
 ```bash
diff --git a/docs/API.md b/docs/API.md
index c195bf32..97074b9f 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1104,7 +1104,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 - `--formality LEVEL` - Formality level: `default`, `more`, `less`, `prefer_more`, `prefer_less`, `formal`, `informal`
 - `--preserve-code` - Preserve code blocks
 - `--preserve-formatting` - Preserve line breaks and whitespace formatting
-- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. Pass `--from` as well: the API refuses a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"), and `watch` does not check for it up front, so every file change fails on the API call instead. Unlike `translate`, `watch` takes a single glossary.
+- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. `--from` is required, because the API refuses a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"); omitting it exits 6 before the watcher starts rather than failing on every file change. Unlike `translate`, `watch` takes a single glossary.
 
 **Git Integration:**
 
diff --git a/src/cli/commands/register-watch.ts b/src/cli/commands/register-watch.ts
index 2bedbca0..5c0b08b5 100644
--- a/src/cli/commands/register-watch.ts
+++ b/src/cli/commands/register-watch.ts
@@ -21,7 +21,7 @@ export function registerWatch(
     .option('-o, --output <path>', 'Output directory (default: <path>/translations or same dir for files)')
     .optionsGroup('Translation Quality:')
     .addOption(new Option('--formality <level>', 'Formality level').choices(['default', 'more', 'less', 'prefer_more', 'prefer_less', 'formal', 'informal']))
-    .option('--glossary <name-or-id>', 'Use glossary by name or ID (pass --from as well; the API rejects a glossary without a source language)')
+    .option('--glossary <name-or-id>', 'Use glossary by name or ID (requires --from; the API rejects a glossary without a source language)')
     .option('--preserve-code', 'Preserve code blocks and variables during translation')
     .option('--preserve-formatting', 'Preserve line breaks and whitespace formatting')
     .optionsGroup('Watch Behavior:')
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index eca83b7a..dc37d1c5 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -84,6 +84,15 @@ export class WatchCommand {
       );
     }
 
+    // The API rejects any translation naming a glossary without source_lang, so
+    // an unguarded watch session fails once per file change instead of at launch.
+    if (options.glossary && !options.from) {
+      throw new ValidationError(
+        'Source language (--from) is required when using a glossary',
+        'Example: deepl watch ./docs --from en --to es --glossary my-glossary'
+      );
+    }
+
     // Get git-staged files if requested
     let stagedFiles: Set<string> | undefined;
     if (options.gitStaged) {
diff --git a/tests/e2e/cli-watch.e2e.test.ts b/tests/e2e/cli-watch.e2e.test.ts
index 85cb71d6..989b709b 100644
--- a/tests/e2e/cli-watch.e2e.test.ts
+++ b/tests/e2e/cli-watch.e2e.test.ts
@@ -82,6 +82,67 @@ describe('Watch Command E2E', () => {
     });
   });
 
+  describe('watch --glossary without --from', () => {
+    /**
+     * The guard sits behind the API key gate, so a key must be present. The
+     * unreachable baseUrl proves the exit is the guard's own: any run that got
+     * as far as resolving the glossary name would fail on the network instead.
+     */
+    function deadUrlConfigDir(): string {
+      const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-config-'));
+      fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify({
+        auth: { apiKey: 'e2e-watch-glossary-key:fx' },
+        api: { baseUrl: 'http://127.0.0.1:9', usePro: false },
+        defaults: { formality: 'default', preserveFormatting: true },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        watch: { debounceMs: 500, autoCommit: false },
+      }, null, 2));
+      return configDir;
+    }
+
+    it('should exit 6 without starting a watcher', () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-e2e-'));
+      fs.writeFileSync(path.join(tmpDir, 'readme.md'), 'Hello world');
+      const configDir = deadUrlConfigDir();
+      const { runCLIExpectError } = makeNodeRunCLI(configDir);
+
+      try {
+        const { status, output } = runCLIExpectError(
+          `watch ${tmpDir} --to es --glossary my-glossary`,
+          { timeout: 20000 },
+        );
+
+        expect(status).toBe(6);
+        expect(output).toContain('Source language (--from) is required when using a glossary');
+        expect(output).not.toContain('Watching for changes');
+      } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        fs.rmSync(configDir, { recursive: true, force: true });
+      }
+    });
+
+    it('should get past the guard when --from is given', () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-e2e-'));
+      fs.writeFileSync(path.join(tmpDir, 'readme.md'), 'Hello world');
+      const configDir = deadUrlConfigDir();
+      const { runCLIExpectError } = makeNodeRunCLI(configDir);
+
+      try {
+        const { status, output } = runCLIExpectError(
+          `watch ${tmpDir} --from en --to es --glossary my-glossary`,
+          { timeout: 20000 },
+        );
+
+        expect(output).not.toContain('Source language (--from) is required');
+        expect(status).not.toBe(6);
+      } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        fs.rmSync(configDir, { recursive: true, force: true });
+      }
+    });
+  });
+
   describe('watch without required arguments', () => {
     it('should fail when no path is provided', () => {
       try {
diff --git a/tests/unit/watch-command.test.ts b/tests/unit/watch-command.test.ts
index a5375073..61c83693 100644
--- a/tests/unit/watch-command.test.ts
+++ b/tests/unit/watch-command.test.ts
@@ -8,6 +8,7 @@ import { WatchService } from '../../src/services/watch';
 import { FileTranslationService } from '../../src/services/file-translation';
 import { TranslationService } from '../../src/services/translation';
 import { GlossaryService } from '../../src/services/glossary';
+import { ValidationError } from '../../src/utils/errors';
 import {
   createMockTranslationService,
   createMockGlossaryService,
@@ -401,6 +402,73 @@ describe('WatchCommand', () => {
       ).rejects.toThrow('No target language specified.');
     });
 
+    describe('--glossary without --from', () => {
+      it('should reject before starting a watcher', async () => {
+        (fs.existsSync as jest.Mock).mockReturnValue(true);
+        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+
+        await expect(
+          watchCommand.watch('/some/file.md', {
+            to: 'es',
+            glossary: 'my-glossary',
+          })
+        ).rejects.toThrow('Source language (--from) is required when using a glossary');
+
+        expect(mockWatchService.watch).not.toHaveBeenCalled();
+      });
+
+      it('should reject with a ValidationError carrying a watch example', async () => {
+        expect.assertions(3);
+        (fs.existsSync as jest.Mock).mockReturnValue(true);
+        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+
+        try {
+          await watchCommand.watch('/some/file.md', {
+            to: 'es',
+            glossary: 'my-glossary',
+          });
+        } catch (error) {
+          expect(error).toBeInstanceOf(ValidationError);
+          expect((error as ValidationError).exitCode).toBe(6);
+          expect((error as ValidationError).suggestion).toContain('deepl watch');
+        }
+      });
+
+      it('should not resolve the glossary name, which would call the API', async () => {
+        (fs.existsSync as jest.Mock).mockReturnValue(true);
+        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+
+        await expect(
+          watchCommand.watch('/some/file.md', {
+            to: 'es',
+            glossary: 'my-glossary',
+          })
+        ).rejects.toThrow(ValidationError);
+
+        expect(mockGlossaryService.resolveGlossaryId).not.toHaveBeenCalled();
+      });
+
+      it('should accept --glossary when --from is provided', async () => {
+        expect.assertions(1);
+        (fs.existsSync as jest.Mock).mockReturnValue(true);
+        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+        mockGlossaryService.resolveGlossaryId.mockResolvedValue('resolved-id');
+        mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+
+        try {
+          await watchCommand.watch('/some/file.md', {
+            to: 'es',
+            from: 'en',
+            glossary: 'my-glossary',
+          });
+        } catch {
+          // Expected: the watcher is stubbed to throw once reached
+        }
+
+        expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+      });
+    });
+
     it('should display initial watch message with all options', async () => {
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });

From d15bc8992740967a359e2edacf303d09ba8243b1 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 09:15:38 -0400
Subject: [PATCH 013/256] refactor(cli): display language codes in lowercase
 everywhere
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Output mixed three casings: `deepl languages` printed lowercase from the
registry, `glossary show` and `tm list` uppercased at display time,
`translate`'s table uppercased the target language, and `write`/`correct` used
BCP-47 (en-GB, zh-Hans). Lowercase matches the CLI's own normalized form, the
registry, what `deepl languages` teaches users to type, and the wire format
/v3/languages moved to. Uppercase followed a v2-era docs convention that v3
abandons.

Display-time .toUpperCase() is removed from glossary.ts, tm.ts, and
formatters.ts. The v3 glossary and translation-memory endpoints already return
lowercase, so removal is sufficient — verified against the live API.

WRITE_LANGUAGES is lowercased, which changes what write/correct send as
target_lang, not just what they display. The Write API accepts any casing and
canonicalizes server-side: /v2/write/rephrase and /v2/write/correct return 200
for en-gb, zh-hans, and zh-HANS alike and echo back en-GB / zh-Hans. Since the
echoed value is the API's casing rather than ours, WriteImprovement's
targetLanguage is typed as the string it is instead of claiming to be one of
our codes.

Input remains case-insensitive everywhere, so no command line has to change.
Wire parameters that are not display are untouched: translate and the glossary
create endpoint still send uppercase as those endpoints document.

Parseable output shifts casing for scripts: `glossary show` reports
"Source language: en" and "en → es", `tm list` renders
"brand-terms (en → de, fr)", and `write --format json` reports
"language": "en-us".
---
 CHANGELOG.md                                  |   1 +
 README.md                                     |  60 ++++----
 docs/API.md                                   |  74 ++++-----
 examples/13-write.sh                          |  40 ++---
 examples/36-write-extended-languages.sh       |  10 +-
 examples/37-correct.sh                        |   4 +-
 src/api/write-client.ts                       |   2 +-
 src/cli/commands/glossary.ts                  |   6 +-
 src/cli/commands/register-write.ts            |   7 +-
 src/cli/commands/tm.ts                        |   4 +-
 src/types/api.ts                              |  13 +-
 src/utils/formatters.ts                       |   2 +-
 .../cli-correct.integration.test.ts           |  30 ++--
 .../integration/cli-write.integration.test.ts |  68 ++++-----
 .../deepl-client.integration.test.ts          |   8 +-
 tests/unit/deepl-client-lazy.test.ts          |   2 +-
 tests/unit/deepl-client.test.ts               |  36 ++---
 tests/unit/formatters.test.ts                 |  22 +--
 tests/unit/glossary-command.test.ts           |  10 +-
 tests/unit/register-correct.test.ts           |   2 +-
 tests/unit/register-write.test.ts             |  16 +-
 tests/unit/text-translation-handler.test.ts   |   4 +-
 tests/unit/tm-command.test.ts                 |   4 +-
 tests/unit/translate-command.test.ts          |   4 +-
 tests/unit/write-client.test.ts               |   8 +-
 tests/unit/write-command.test.ts              | 142 +++++++++---------
 tests/unit/write-service.test.ts              | 102 ++++++-------
 27 files changed, 342 insertions(+), 339 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 813c8aea..57518f0d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **cli**: **Language codes are displayed in lowercase everywhere.** Output previously mixed three casings: `deepl languages` printed lowercase from the registry, `glossary show` and `tm list` uppercased at display time, `translate`'s table uppercased the target language, and `write`/`correct` used BCP-47 (`en-GB`, `zh-Hans`). Lowercase matches the CLI's own normalized form, the registry, what `deepl languages` teaches users to type, and the wire format `/v3/languages` moved to; uppercase followed a v2-era docs convention that v3 abandons. **Scripts scraping these values will see a casing change** — `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"`. Input remains case-insensitive everywhere, so no command line has to change. `write`/`correct` also send the lowercase code as `target_lang`: the Write API accepts any casing and canonicalizes server-side (verified live on `/v2/write/rephrase` and `/v2/write/correct` — `en-gb`, `zh-hans`, and `zh-HANS` all return 200 and echo back `en-GB` / `zh-Hans`). Wire parameters that are not display are untouched: `translate` and the glossary create endpoint still send uppercase `target_lang`/`source_lang` as those endpoints document.
 - **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers now come from the language registry since the v3 response no longer reports formality support.
 
 ### Removed
diff --git a/README.md b/README.md
index c4c5ba30..fa928b15 100644
--- a/README.md
+++ b/README.md
@@ -592,87 +592,87 @@ See [examples/08-model-type-selection.sh](./examples/08-model-type-selection.sh)
 
 Improve your writing with AI-powered grammar, style, and tone suggestions using the **DeepL Write API**.
 
-The `--lang` flag is optional. If omitted, DeepL auto-detects the language and rephrases in the original language. Generic codes `en` and `pt` are also accepted (mapped to `en-US` and `pt-BR` respectively).
+The `--lang` flag is optional. If omitted, DeepL auto-detects the language and rephrases in the original language. Generic codes `en` and `pt` are also accepted (mapped to `en-us` and `pt-br` respectively).
 
 ```bash
 # Auto-detect language (--lang is optional)
 deepl write "This is a sentence."
 
 # Specify language explicitly
-deepl write "This is a sentence." --lang en-US
+deepl write "This is a sentence." --lang en-us
 
-# Use generic language code (en maps to en-US, pt maps to pt-BR)
+# Use generic language code (en maps to en-us, pt maps to pt-br)
 deepl write "This is a sentence." --lang en
 
 # Apply business writing style
-deepl write "We want to tell you about our new product." --lang en-US --style business
+deepl write "We want to tell you about our new product." --lang en-us --style business
 
 # Apply academic writing style
-deepl write "This shows that the method works." --lang en-US --style academic
+deepl write "This shows that the method works." --lang en-us --style academic
 
 # Apply casual tone
-deepl write "That is interesting." --lang en-US --style casual
+deepl write "That is interesting." --lang en-us --style casual
 
 # Use confident tone
-deepl write "I think this will work." --lang en-US --tone confident
+deepl write "I think this will work." --lang en-us --tone confident
 
 # Use diplomatic tone
-deepl write "Try something else." --lang en-US --tone diplomatic
+deepl write "Try something else." --lang en-us --tone diplomatic
 
 # Show all alternative improvements
 deepl write "This is good." --tone enthusiastic --alternatives
 
 # Improve files and save to output
-deepl write input.txt --lang en-US --output improved.txt
+deepl write input.txt --lang en-us --output improved.txt
 
 # Edit file in place
-deepl write document.md --lang en-US --in-place
+deepl write document.md --lang en-us --in-place
 
 # Interactive mode - choose from multiple style alternatives
 # Generates improvements with simple, business, academic, and casual styles
-deepl write "Text to improve." --lang en-US --interactive
+deepl write "Text to improve." --lang en-us --interactive
 
 # Interactive mode with file
-deepl write document.md --lang en-US --interactive --in-place
+deepl write document.md --lang en-us --interactive --in-place
 
 # Interactive mode with specific style (single option)
-deepl write "Text to improve." --lang en-US --style business --interactive
+deepl write "Text to improve." --lang en-us --style business --interactive
 
 # Check if text needs improvement (exit code 0 if no changes needed)
-deepl write document.md --lang en-US --check
+deepl write document.md --lang en-us --check
 
 # Auto-fix files in place
-deepl write document.md --lang en-US --fix
+deepl write document.md --lang en-us --fix
 
 # Auto-fix with backup
-deepl write document.md --lang en-US --fix --backup
+deepl write document.md --lang en-us --fix --backup
 
 # Show diff between original and improved
-deepl write file.txt --lang en-US --diff
+deepl write file.txt --lang en-us --diff
 
 # Show diff for plain text
-deepl write "This text could be better." --lang en-US --diff
+deepl write "This text could be better." --lang en-us --diff
 
 # Bypass cache for this request
-deepl write "Fresh improvement please." --lang en-US --no-cache
+deepl write "Fresh improvement please." --lang en-us --no-cache
 ```
 
 **Supported Languages:**
 
 - German (`de`)
 - English (`en`) - generic, defaults to American English
-- English - British (`en-GB`)
-- English - American (`en-US`)
+- English - British (`en-gb`)
+- English - American (`en-us`)
 - 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`)
+- Portuguese - Brazilian (`pt-br`)
+- Portuguese - European (`pt-pt`)
 - Chinese (`zh`) - generic, defaults to Simplified Chinese
-- Chinese - Simplified (`zh-Hans`)
+- Chinese - Simplified (`zh-hans`)
 
 **Writing Styles:**
 
@@ -1183,8 +1183,8 @@ DeepL glossaries ensure consistent terminology across translations. The v3 Gloss
 echo -e "API\tAPI\nREST\tREST\nauthentication\tAuthentifizierung" > glossary.tsv
 deepl glossary create tech-terms en de glossary.tsv
 # ✓ Glossary created: tech-terms (ID: abc123...)
-# Source language: EN
-# Target languages: DE
+# Source language: en
+# Target languages: de
 # Type: Single target
 # Total entries: 3
 
@@ -1282,8 +1282,8 @@ authentication	Authentifizierung
 
 **Key Features:**
 
-- **Single-target glossaries** - One source language → one target language (e.g., EN → DE)
-- **Multilingual glossaries** - One source language → multiple target languages (e.g., EN → ES, FR, DE)
+- **Single-target glossaries** - One source language → one target language (e.g., en → de)
+- **Multilingual glossaries** - One source language → multiple target languages (e.g., en → es, fr, de)
 - **Direct updates** - v3 API uses PATCH endpoints for efficient updates (no delete+recreate)
 - **Smart defaults** - `--target` flag only required for multilingual glossaries
 - **Visual indicators** - 📖 for single-target, 📚 for multilingual glossaries
@@ -1302,8 +1302,8 @@ Reuse approved translations from your account's translation memories. TMs are au
 ```bash
 # List translation memories on the account
 deepl tm list
-# brand-terms (EN → DE, FR, JA)
-# legal-phrases (EN → FR)
+# brand-terms (en → de, fr, ja)
+# legal-phrases (en → fr)
 
 # JSON output for scripting
 deepl tm list --format json
diff --git a/docs/API.md b/docs/API.md
index 97074b9f..6b3af157 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -711,7 +711,7 @@ Enhance text quality with AI-powered grammar checking, style improvement, and to
 
 **Language:**
 
-- `--lang, -l LANG` - Target language: `de`, `en`, `en-GB`, `en-US`, `es`, `fr`, `it`, `ja`, `ko`, `pt`, `pt-BR`, `pt-PT`, `zh`, `zh-Hans`. Optional — omit to auto-detect the language and rephrase in the original language.
+- `--lang, -l LANG` - Target language: `de`, `en`, `en-gb`, `en-us`, `es`, `fr`, `it`, `ja`, `ko`, `pt`, `pt-br`, `pt-pt`, `zh`, `zh-hans`. Optional — omit to auto-detect the language and rephrase in the original language.
 - `--to LANG` - Long-only alias of `--lang`. Accepts the same language values. Provided for muscle-memory consistency with `deepl translate --to`; the short form `-t` is intentionally **not** bound here (it would collide with `deepl translate -t, --to`). Specifying both `--to` and `--lang` with different values exits with a `ValidationError`.
 
 **Style Options (mutually exclusive with tone):**
@@ -738,9 +738,9 @@ Enhance text quality with AI-powered grammar checking, style improvement, and to
 
 | Target language | `--style` | `--tone` |
 |-----------------|:---------:|:--------:|
-| `en`, `en-GB`, `en-US`, `de` | ✓ | ✓ |
-| `es`, `fr`, `it`, `pt`, `pt-BR`, `pt-PT` | ✓ | ✓ |
-| `ja`, `ko`, `zh`, `zh-Hans` | — | — |
+| `en`, `en-gb`, `en-us`, `de` | ✓ | ✓ |
+| `es`, `fr`, `it`, `pt`, `pt-br`, `pt-pt` | ✓ | ✓ |
+| `ja`, `ko`, `zh`, `zh-hans` | — | — |
 
 When `--style` or `--tone` is set for a target language that does not support it, the server returns a 4xx; the CLI converts that response into a `ValidationError` (exit code 6) that names the unsupported combination and points back to this table.
 
@@ -764,18 +764,18 @@ When `--style` or `--tone` is set for a target language that does not support it
 
 - `de` - German
 - `en` - English (generic, defaults to American English)
-- `en-GB` - British English
-- `en-US` - American English
+- `en-gb` - British English
+- `en-us` - American English
 - `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
+- `pt-br` - Brazilian Portuguese
+- `pt-pt` - European Portuguese
 - `zh` - Chinese (generic, defaults to Simplified Chinese)
-- `zh-Hans` - Simplified Chinese
+- `zh-hans` - Simplified Chinese
 
 #### Examples
 
@@ -789,7 +789,7 @@ deepl write "Me and him went to store."
 **With explicit language:**
 
 ```bash
-deepl write "Me and him went to store." --lang en-US
+deepl write "Me and him went to store." --lang en-us
 # → "He and I went to the store."
 ```
 
@@ -797,11 +797,11 @@ deepl write "Me and him went to store." --lang en-US
 
 ```bash
 # Business style
-deepl write "We want to tell you about our product." --lang en-US --style business
+deepl write "We want to tell you about our product." --lang en-us --style business
 # → "We are pleased to inform you about our product."
 
 # Casual style
-deepl write "The analysis demonstrates significant findings." --lang en-US --style casual
+deepl write "The analysis demonstrates significant findings." --lang en-us --style casual
 # → "The analysis shows some pretty big findings."
 ```
 
@@ -809,67 +809,67 @@ deepl write "The analysis demonstrates significant findings." --lang en-US --sty
 
 ```bash
 # Confident tone
-deepl write "I think this might work." --lang en-US --tone confident
+deepl write "I think this might work." --lang en-us --tone confident
 # → "This will work."
 
 # Diplomatic tone
-deepl write "Your approach is wrong." --lang en-US --tone diplomatic
+deepl write "Your approach is wrong." --lang en-us --tone diplomatic
 # → "Perhaps we could consider an alternative approach."
 ```
 
 **Show alternatives:**
 
 ```bash
-deepl write "This is good." --lang en-US --alternatives
+deepl write "This is good." --lang en-us --alternatives
 ```
 
 **File operations:**
 
 ```bash
 # Improve file and save to new location
-deepl write document.txt --lang en-US --output improved.txt
+deepl write document.txt --lang en-us --output improved.txt
 
 # Edit file in place
-deepl write document.txt --lang en-US --in-place
+deepl write document.txt --lang en-us --in-place
 
 # Auto-fix with backup
-deepl write document.txt --lang en-US --fix --backup
+deepl write document.txt --lang en-us --fix --backup
 ```
 
 **Interactive mode:**
 
 ```bash
 # Choose from multiple alternatives interactively
-deepl write "Text to improve." --lang en-US --interactive
+deepl write "Text to improve." --lang en-us --interactive
 ```
 
 **Check mode:**
 
 ```bash
 # Check if file needs improvement (exit code 8 if changes needed)
-deepl write document.md --lang en-US --check
+deepl write document.md --lang en-us --check
 ```
 
 **Diff view:**
 
 ```bash
 # Show differences between original and improved
-deepl write file.txt --lang en-US --diff
+deepl write file.txt --lang en-us --diff
 ```
 
 **JSON output:**
 
 ```bash
 # Get machine-readable JSON output
-deepl write "This are good." --lang en-US --format json
-# {"original":"This are good.","improved":"This is good.","changes":1,"language":"en-US"}
+deepl write "This are good." --lang en-us --format json
+# {"original":"This are good.","improved":"This is good.","changes":1,"language":"en-us"}
 ```
 
 **Bypass cache:**
 
 ```bash
 # Force a fresh API call, skipping cached results
-deepl write "Improve this text." --lang en-US --no-cache
+deepl write "Improve this text." --lang en-us --no-cache
 ```
 
 ---
@@ -897,7 +897,7 @@ Fixes spelling and grammar only, avoiding the broader rewording that `deepl writ
 
 **Language:**
 
-- `--lang, -l LANG` - Target language: `de`, `en`, `en-GB`, `en-US`, `es`, `fr`, `it`, `ja`, `ko`, `pt`, `pt-BR`, `pt-PT`, `zh`, `zh-Hans`. Optional — omit to auto-detect the language and correct in the original language.
+- `--lang, -l LANG` - Target language: `de`, `en`, `en-gb`, `en-us`, `es`, `fr`, `it`, `ja`, `ko`, `pt`, `pt-br`, `pt-pt`, `zh`, `zh-hans`. Optional — omit to auto-detect the language and correct in the original language.
 - `--to LANG` - Long-only alias of `--lang`, as on `write`.
 
 **Output Modes:**
@@ -1685,8 +1685,8 @@ cache	caché
 # Create single-target glossary from TSV file
 deepl glossary create tech-terms en es glossary.tsv
 # ✓ Glossary created: tech-terms (ID: abc123...)
-# Source language: EN
-# Target languages: ES
+# Source language: en
+# Target languages: es
 # Type: Single target
 # Total entries: 3
 
@@ -1746,8 +1746,8 @@ Show glossary details including name, ID, languages, creation date, and entry co
 deepl glossary show tech-terms
 # Name: tech-terms
 # ID: abc123...
-# Source language: EN
-# Target languages: DE
+# Source language: en
+# Target languages: de
 # Type: Single target
 # Total entries: 3
 # Created: 2024-10-07T12:34:56.000Z
@@ -1756,15 +1756,15 @@ deepl glossary show tech-terms
 deepl glossary show multilingual-terms
 # Name: multilingual-terms
 # ID: def456...
-# Source language: EN
-# Target languages: ES, FR, DE
+# Source language: en
+# Target languages: es, fr, de
 # Type: Multilingual
 # Total entries: 15
 #
 # Language pairs:
-#   EN → ES: 5 entries
-#   EN → FR: 5 entries
-#   EN → DE: 5 entries
+#   en → es: 5 entries
+#   en → fr: 5 entries
+#   en → de: 5 entries
 # Created: 2024-10-08T10:00:00.000Z
 ```
 
@@ -2104,7 +2104,7 @@ List all translation memories on the account.
 
 **Output Format (text):**
 
-- Per-TM: `name (source → target[, target...])` — e.g. `brand-terms (EN → DE, FR, JA)`. Control chars and zero-width codepoints are stripped from the rendered name to prevent a malicious API-returned name from corrupting the terminal via ANSI escape sequences.
+- Per-TM: `name (source → target[, target...])` — e.g. `brand-terms (en → de, fr, ja)`. Control chars and zero-width codepoints are stripped from the rendered name to prevent a malicious API-returned name from corrupting the terminal via ANSI escape sequences.
 - Empty list: `No translation memories found`
 
 **Output Format (JSON):**
@@ -2115,8 +2115,8 @@ Raw `TranslationMemory[]` as returned by `GET /v3/translation_memories` — fiel
 
 ```bash
 deepl tm list
-# brand-terms (EN → DE, FR, JA)
-# legal-phrases (EN → FR)
+# brand-terms (en → de, fr, ja)
+# legal-phrases (en → fr)
 
 deepl tm list --format json | jq '.[] | select(.name == "brand-terms") | .translation_memory_id'
 # "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
diff --git a/examples/13-write.sh b/examples/13-write.sh
index 287ad185..16f627a9 100755
--- a/examples/13-write.sh
+++ b/examples/13-write.sh
@@ -19,52 +19,52 @@ echo
 
 # Basic text improvement
 echo "1. Basic text improvement:"
-deepl write "This is a sentence." --lang en-US
+deepl write "This is a sentence." --lang en-us
 echo
 
 # Business writing style
 echo "2. Business writing style:"
-deepl write "We want to tell you about our new product." --lang en-US --style business
+deepl write "We want to tell you about our new product." --lang en-us --style business
 echo
 
 # Academic writing style
 echo "3. Academic writing style:"
-deepl write "This shows that the method works." --lang en-US --style academic
+deepl write "This shows that the method works." --lang en-us --style academic
 echo
 
 # Casual writing style
 echo "4. Casual writing style:"
-deepl write "That is interesting." --lang en-US --style casual
+deepl write "That is interesting." --lang en-us --style casual
 echo
 
 # Simple writing style
 echo "5. Simple writing style:"
-deepl write "The implementation demonstrates efficacy." --lang en-US --style simple
+deepl write "The implementation demonstrates efficacy." --lang en-us --style simple
 echo
 
 # Enthusiastic tone
 echo "6. Enthusiastic tone:"
-deepl write "This is good." --lang en-US --tone enthusiastic
+deepl write "This is good." --lang en-us --tone enthusiastic
 echo
 
 # Friendly tone
 echo "7. Friendly tone:"
-deepl write "Hello." --lang en-US --tone friendly
+deepl write "Hello." --lang en-us --tone friendly
 echo
 
 # Confident tone
 echo "8. Confident tone:"
-deepl write "I think this will work." --lang en-US --tone confident
+deepl write "I think this will work." --lang en-us --tone confident
 echo
 
 # Diplomatic tone
 echo "9. Diplomatic tone:"
-deepl write "Try something else." --lang en-US --tone diplomatic
+deepl write "Try something else." --lang en-us --tone diplomatic
 echo
 
 # Show alternatives
 echo "10. Show all alternative improvements:"
-deepl write "This is a test." --lang en-US --alternatives
+deepl write "This is a test." --lang en-us --alternatives
 echo
 
 # Different languages
@@ -82,11 +82,11 @@ echo
 
 # Prefer styles (fallback if not supported)
 echo "14. Prefer business style (with fallback):"
-deepl write "We need to discuss this." --lang en-US --style prefer_business
+deepl write "We need to discuss this." --lang en-us --style prefer_business
 echo
 
 echo "15. Bypass cache (always call API):"
-deepl write "This is a sentence." --lang en-US --no-cache
+deepl write "This is a sentence." --lang en-us --no-cache
 echo
 
 # ═══════════════════════════════════════════════════════
@@ -97,11 +97,11 @@ DEMO_FILE="/tmp/deepl-write-demo.txt"
 echo "Their going to the store tommorow. The weather will be good, I think we should definately go." > "$DEMO_FILE"
 
 echo "16. Improve text from a file:"
-deepl write "$DEMO_FILE" --lang en-US
+deepl write "$DEMO_FILE" --lang en-us
 echo
 
 echo "17. Write improved text to output file:"
-deepl write "$DEMO_FILE" --output /tmp/deepl-write-improved.txt --lang en-US
+deepl write "$DEMO_FILE" --output /tmp/deepl-write-improved.txt --lang en-us
 echo "   Output saved to /tmp/deepl-write-improved.txt"
 cat /tmp/deepl-write-improved.txt
 echo
@@ -111,11 +111,11 @@ echo
 # ═══════════════════════════════════════════════════════
 
 echo "18. Check if text needs improvement (exit 0=clean, 8=changes needed):"
-deepl write "Their going to the store" --check --lang en-US || true
+deepl write "Their going to the store" --check --lang en-us || true
 echo
 
 echo "19. Check a file for improvements:"
-deepl write "$DEMO_FILE" --check --lang en-US || true
+deepl write "$DEMO_FILE" --check --lang en-us || true
 echo
 
 echo "20. Auto-fix a file in place:"
@@ -136,12 +136,12 @@ echo
 # ═══════════════════════════════════════════════════════
 
 echo "22. Show diff between original and improved text:"
-deepl write "Their going to the store tommorow." --diff --lang en-US
+deepl write "Their going to the store tommorow." --diff --lang en-us
 echo
 
 echo "23. Edit file in place:"
 echo "This text could be more better." > "$DEMO_FILE"
-deepl write "$DEMO_FILE" --in-place --lang en-US
+deepl write "$DEMO_FILE" --in-place --lang en-us
 echo "   Updated file content:"
 cat "$DEMO_FILE"
 echo
@@ -151,7 +151,7 @@ echo
 # ═══════════════════════════════════════════════════════
 
 echo "24. JSON output format:"
-deepl write "Their going to the store" --format json --lang en-US
+deepl write "Their going to the store" --format json --lang en-us
 echo
 
 # ═══════════════════════════════════════════════════════
@@ -160,7 +160,7 @@ echo
 
 # Note: --interactive requires a TTY (won't work in piped scripts)
 echo "25. Interactive mode (choose from multiple suggestions):"
-echo "   deepl write \"Their going to the store\" --interactive --lang en-US"
+echo "   deepl write \"Their going to the store\" --interactive --lang en-us"
 echo "   (Skipped in non-interactive script — try this manually)"
 echo
 
diff --git a/examples/36-write-extended-languages.sh b/examples/36-write-extended-languages.sh
index f01a74cf..a8a1b58c 100755
--- a/examples/36-write-extended-languages.sh
+++ b/examples/36-write-extended-languages.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # Example 36: Write — extended language coverage
-# Demonstrates JA/KO/ZH/zh-Hans target languages and
+# Demonstrates ja/ko/zh/zh-hans target languages and
 # tone / style applied to ES/IT/FR/PT variants.
 
 set -e
@@ -30,8 +30,8 @@ echo "3. Simplified Chinese target (zh)"
 deepl write "请改进这句话。" --lang zh
 echo
 
-echo "4. Simplified Chinese target (zh-Hans)"
-deepl write "请改进这句话。" --lang zh-Hans
+echo "4. Simplified Chinese target (zh-hans)"
+deepl write "请改进这句话。" --lang zh-hans
 echo
 
 # Tone / style on Romance variants
@@ -48,11 +48,11 @@ deepl write "Les résultats montrent une corrélation." --lang fr --style academ
 echo
 
 echo "8. Portuguese (Brazil) + friendly tone"
-deepl write "Podemos ajudar com isso." --lang pt-BR --tone friendly
+deepl write "Podemos ajudar com isso." --lang pt-br --tone friendly
 echo
 
 echo "9. Portuguese (Portugal) + confident tone"
-deepl write "Vamos entregar no prazo." --lang pt-PT --tone confident
+deepl write "Vamos entregar no prazo." --lang pt-pt --tone confident
 echo
 
 # Auto-detect round-trip for a CJK input
diff --git a/examples/37-correct.sh b/examples/37-correct.sh
index 667a8c93..93fb8acb 100755
--- a/examples/37-correct.sh
+++ b/examples/37-correct.sh
@@ -26,7 +26,7 @@ deepl correct "This is an test with some mistaks."
 echo
 
 echo "2. Explicit target language"
-deepl correct "Their going too the store." --lang en-US
+deepl correct "Their going too the store." --lang en-us
 echo
 
 echo "3. The c alias"
@@ -34,7 +34,7 @@ deepl c "I has a apple."
 echo
 
 echo "4. Diff view"
-deepl correct "This are a example sentence." --lang en-US --diff
+deepl correct "This are a example sentence." --lang en-us --diff
 echo
 
 echo "5. Check mode (exit 8 would mean corrections needed)"
diff --git a/src/api/write-client.ts b/src/api/write-client.ts
index ba708a80..43892fad 100644
--- a/src/api/write-client.ts
+++ b/src/api/write-client.ts
@@ -89,7 +89,7 @@ export class WriteClient extends HttpClient {
 
     return response.improvements.map(improvement => ({
       text: improvement.text,
-      targetLanguage: improvement.target_language as WriteImprovement['targetLanguage'],
+      targetLanguage: improvement.target_language,
       detectedSourceLanguage: improvement.detected_source_language,
     }));
   }
diff --git a/src/cli/commands/glossary.ts b/src/cli/commands/glossary.ts
index 910bf527..1490c502 100644
--- a/src/cli/commands/glossary.ts
+++ b/src/cli/commands/glossary.ts
@@ -241,8 +241,8 @@ export class GlossaryCommand {
     const lines = [
       `Name: ${sanitizeForTerminal(glossary.name)}`,
       `ID: ${glossary.glossary_id}`,
-      `Source language: ${glossary.source_lang.toUpperCase()}`,
-      `Target languages: ${glossary.target_langs.map(l => l.toUpperCase()).join(', ')}`,
+      `Source language: ${glossary.source_lang}`,
+      `Target languages: ${glossary.target_langs.join(', ')}`,
       `Type: ${multilingual ? 'Multilingual' : 'Single target'}`,
       `Total entries: ${totalEntries}`,
       `Created: ${createdStr}`,
@@ -251,7 +251,7 @@ export class GlossaryCommand {
     if (multilingual) {
       lines.push('\nLanguage pairs:');
       glossary.dictionaries.forEach(dict => {
-        lines.push(`  ${dict.source_lang.toUpperCase()} → ${dict.target_lang.toUpperCase()}: ${dict.entry_count} entries`);
+        lines.push(`  ${dict.source_lang} → ${dict.target_lang}: ${dict.entry_count} entries`);
       });
     }
 
diff --git a/src/cli/commands/register-write.ts b/src/cli/commands/register-write.ts
index 6d731cdc..e0adb500 100644
--- a/src/cli/commands/register-write.ts
+++ b/src/cli/commands/register-write.ts
@@ -9,10 +9,11 @@ import { isNoInput } from '../../utils/confirm.js';
 import { ValidationError } from '../../utils/errors.js';
 import { createWriteCommand, type ServiceDeps } from './service-factory.js';
 
-export const WRITE_LANGUAGES = ['de', 'en', 'en-GB', 'en-US', 'es', 'fr', 'it', 'ja', 'ko', 'pt', 'pt-BR', 'pt-PT', 'zh', 'zh-Hans'] as const;
+export const WRITE_LANGUAGES = ['de', 'en', 'en-gb', 'en-us', 'es', 'fr', 'it', 'ja', 'ko', 'pt', 'pt-br', 'pt-pt', 'zh', 'zh-hans'] as const;
 /**
- * Codes are accepted in any casing and normalized to the API's form, matching
- * `translate --to` and the lowercase codes `deepl languages` prints.
+ * Codes are accepted in any casing and normalized to lowercase, matching
+ * `translate --to` and the codes `deepl languages` prints. The Write API
+ * accepts any casing and echoes its own (`en-GB`, `zh-Hans`) regardless.
  */
 const WRITE_LANGUAGE_BY_LOWERCASE = new Map<string, WriteLanguage>(
   WRITE_LANGUAGES.map((language) => [language.toLowerCase(), language]),
diff --git a/src/cli/commands/tm.ts b/src/cli/commands/tm.ts
index 2b1dbcfa..d9d31a73 100644
--- a/src/cli/commands/tm.ts
+++ b/src/cli/commands/tm.ts
@@ -23,8 +23,8 @@ export class TmCommand {
     }
     return tms
       .map(tm => {
-        const src = tm.source_language.toUpperCase();
-        const targets = tm.target_languages.map(t => t.toUpperCase()).join(', ');
+        const src = tm.source_language;
+        const targets = tm.target_languages.join(', ');
         return `${sanitizeName(tm.name)} (${src} \u2192 ${targets})`;
       })
       .join('\n');
diff --git a/src/types/api.ts b/src/types/api.ts
index 747fc923..fbdf6eb1 100644
--- a/src/types/api.ts
+++ b/src/types/api.ts
@@ -48,18 +48,18 @@ export interface TranslationMemory {
 export type WriteLanguage =
   | 'de'
   | 'en'
-  | 'en-GB'
-  | 'en-US'
+  | 'en-gb'
+  | 'en-us'
   | 'es'
   | 'fr'
   | 'it'
   | 'ja'
   | 'ko'
   | 'pt'
-  | 'pt-BR'
-  | 'pt-PT'
+  | 'pt-br'
+  | 'pt-pt'
   | 'zh'
-  | 'zh-Hans';
+  | 'zh-hans';
 
 export type WritingStyle =
   | 'default'
@@ -95,7 +95,8 @@ export interface CorrectOptions {
 
 export interface WriteImprovement {
   text: string;
-  targetLanguage: WriteLanguage;
+  /** As echoed by the API, which uses its own casing (`en-GB`, `zh-Hans`). */
+  targetLanguage: string;
   detectedSourceLanguage?: string;
 }
 
diff --git a/src/utils/formatters.ts b/src/utils/formatters.ts
index eac6e94e..b64506a0 100644
--- a/src/utils/formatters.ts
+++ b/src/utils/formatters.ts
@@ -146,7 +146,7 @@ export function formatMultiTranslationTable(
 
   results.forEach((result) => {
     const row = [
-      result.targetLang.toUpperCase(),
+      result.targetLang,
       result.text,
     ];
 
diff --git a/tests/integration/cli-correct.integration.test.ts b/tests/integration/cli-correct.integration.test.ts
index 42126039..ab0046fe 100644
--- a/tests/integration/cli-correct.integration.test.ts
+++ b/tests/integration/cli-correct.integration.test.ts
@@ -45,7 +45,7 @@ describe('Correct Command Integration', () => {
       const scope = nock(FREE_API_URL)
         .post('/v2/write/correct', (body) => {
           expect(body.text).toBe('This is an test.');
-          expect(body.target_lang).toBe('en-US');
+          expect(body.target_lang).toBe('en-us');
           expect(body.writing_style).toBeUndefined();
           expect(body.tone).toBeUndefined();
           return true;
@@ -54,7 +54,7 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'This is a test.', target_language: 'en-US' }],
         });
 
-      const result = await writeService.correct('This is an test.', { targetLang: 'en-US' });
+      const result = await writeService.correct('This is an test.', { targetLang: 'en-us' });
 
       expect(result).toHaveLength(1);
       expect(result[0]?.text).toBe('This is a test.');
@@ -90,7 +90,7 @@ describe('Correct Command Integration', () => {
           ],
         });
 
-      const result = await writeService.correct('This is an test.', { targetLang: 'en-US' });
+      const result = await writeService.correct('This is an test.', { targetLang: 'en-us' });
 
       expect(result).toHaveLength(2);
       expect(result[0]?.text).toBe('This is a test.');
@@ -105,7 +105,7 @@ describe('Correct Command Integration', () => {
         });
 
       await expect(
-        writeService.correct('Perfect text.', { targetLang: 'en-US' })
+        writeService.correct('Perfect text.', { targetLang: 'en-us' })
       ).rejects.toThrow('No improvements returned');
     });
 
@@ -119,7 +119,7 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'This is a test.', target_language: 'en-US' }],
         });
 
-      await writeService.correct('This is an test.', { targetLang: 'en-US' });
+      await writeService.correct('This is an test.', { targetLang: 'en-us' });
 
       expect(rephraseScope.isDone()).toBe(false);
     });
@@ -132,7 +132,7 @@ describe('Correct Command Integration', () => {
         .reply(403, { message: 'Authorization failed' });
 
       await expect(
-        writeService.correct('Test', { targetLang: 'en-US' })
+        writeService.correct('Test', { targetLang: 'en-us' })
       ).rejects.toThrow(/auth|API key|forbidden/i);
     });
 
@@ -143,7 +143,7 @@ describe('Correct Command Integration', () => {
         .reply(429, { message: 'Too many requests' });
 
       await expect(
-        writeService.correct('Test', { targetLang: 'en-US' })
+        writeService.correct('Test', { targetLang: 'en-us' })
       ).rejects.toThrow(/rate|too many|limit/i);
     });
 
@@ -154,7 +154,7 @@ describe('Correct Command Integration', () => {
         .reply(503, { message: 'Service unavailable' });
 
       await expect(
-        writeService.correct('Test', { targetLang: 'en-US' })
+        writeService.correct('Test', { targetLang: 'en-us' })
       ).rejects.toThrow();
     });
 
@@ -177,8 +177,8 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'This is a test.', target_language: 'en-US' }],
         });
 
-      const first = await writeService.correct('This is an test.', { targetLang: 'en-US' });
-      const second = await writeService.correct('This is an test.', { targetLang: 'en-US' });
+      const first = await writeService.correct('This is an test.', { targetLang: 'en-us' });
+      const second = await writeService.correct('This is an test.', { targetLang: 'en-us' });
 
       expect(first).toEqual(second);
       expect(scope.isDone()).toBe(true);
@@ -199,8 +199,8 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'Rephrased.', target_language: 'en-US' }],
         });
 
-      const corrected = await writeService.correct('Same text.', { targetLang: 'en-US' });
-      const improved = await writeService.improve('Same text.', { targetLang: 'en-US' });
+      const corrected = await writeService.correct('Same text.', { targetLang: 'en-us' });
+      const improved = await writeService.improve('Same text.', { targetLang: 'en-us' });
 
       expect(corrected[0]?.text).toBe('Corrected.');
       expect(improved[0]?.text).toBe('Rephrased.');
@@ -216,8 +216,8 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'This is a test.', target_language: 'en-US' }],
         });
 
-      await writeService.correct('This is an test.', { targetLang: 'en-US' }, { skipCache: true });
-      await writeService.correct('This is an test.', { targetLang: 'en-US' }, { skipCache: true });
+      await writeService.correct('This is an test.', { targetLang: 'en-us' }, { skipCache: true });
+      await writeService.correct('This is an test.', { targetLang: 'en-us' }, { skipCache: true });
 
       expect(scope.isDone()).toBe(true);
     });
@@ -234,7 +234,7 @@ describe('Correct Command Integration', () => {
           ],
         });
 
-      const result = await writeService.getBestCorrection('Test', { targetLang: 'en-US' });
+      const result = await writeService.getBestCorrection('Test', { targetLang: 'en-us' });
 
       expect(result.text).toBe('Best correction.');
     });
diff --git a/tests/integration/cli-write.integration.test.ts b/tests/integration/cli-write.integration.test.ts
index b441a679..c873363d 100644
--- a/tests/integration/cli-write.integration.test.ts
+++ b/tests/integration/cli-write.integration.test.ts
@@ -46,14 +46,14 @@ describe('Write Command Integration', () => {
       const scope = nock(FREE_API_URL)
         .post('/v2/write/rephrase', (body) => {
           expect(body.text).toBe('Hello world');
-          expect(body.target_lang).toBe('en-US');
+          expect(body.target_lang).toBe('en-us');
           return true;
         })
         .reply(200, {
           improvements: [{ text: 'Hello, world!', target_language: 'en-US' }],
         });
 
-      const result = await writeService.improve('Hello world', { targetLang: 'en-US' });
+      const result = await writeService.improve('Hello world', { targetLang: 'en-us' });
 
       expect(result).toHaveLength(1);
       expect(result[0]?.text).toBe('Hello, world!');
@@ -71,7 +71,7 @@ describe('Write Command Integration', () => {
           ],
         });
 
-      const result = await writeService.improve('Hello world', { targetLang: 'en-US' });
+      const result = await writeService.improve('Hello world', { targetLang: 'en-us' });
 
       expect(result).toHaveLength(3);
       expect(result[0]?.text).toBe('Hello, world!');
@@ -87,7 +87,7 @@ describe('Write Command Integration', () => {
         });
 
       await expect(
-        writeService.improve('Perfect text', { targetLang: 'en-US' })
+        writeService.improve('Perfect text', { targetLang: 'en-us' })
       ).rejects.toThrow('No improvements returned');
     });
   });
@@ -115,14 +115,14 @@ describe('Write Command Integration', () => {
     it('should still accept explicit target_lang', async () => {
       const scope = nock(FREE_API_URL)
         .post('/v2/write/rephrase', (body) => {
-          expect(body.target_lang).toBe('en-GB');
+          expect(body.target_lang).toBe('en-gb');
           return true;
         })
         .reply(200, {
           improvements: [{ text: 'Hello, world!', target_language: 'en-GB' }],
         });
 
-      const result = await writeService.improve('Hello world', { targetLang: 'en-GB' });
+      const result = await writeService.improve('Hello world', { targetLang: 'en-gb' });
 
       expect(result[0]?.text).toBe('Hello, world!');
       expect(scope.isDone()).toBe(true);
@@ -167,7 +167,7 @@ describe('Write Command Integration', () => {
         });
 
       const result = await writeService.improve(input, {
-        targetLang: 'en-US',
+        targetLang: 'en-us',
         writingStyle,
       });
 
@@ -223,7 +223,7 @@ describe('Write Command Integration', () => {
         });
 
       const result = await writeService.improve(input, {
-        targetLang: 'en-US',
+        targetLang: 'en-us',
         tone: toneValue,
       });
 
@@ -258,7 +258,7 @@ describe('Write Command Integration', () => {
         expectedExact: undefined,
       },
       {
-        lang: 'en-GB',
+        lang: 'en-gb',
         label: 'British English',
         input: 'I want to buy this',
         output: 'I should like to purchase this item',
@@ -286,7 +286,7 @@ describe('Write Command Integration', () => {
         expectedExact: undefined,
       },
       {
-        lang: 'zh-Hans',
+        lang: 'zh-hans',
         label: 'Simplified Chinese',
         input: '我要买这个',
         output: '我想购买这个',
@@ -318,14 +318,14 @@ describe('Write Command Integration', () => {
       { lang: 'it', field: 'writing_style' as const, value: 'casual' },
       { lang: 'fr', field: 'writing_style' as const, value: 'academic' },
       { lang: 'pt', field: 'writing_style' as const, value: 'simple' },
-      { lang: 'pt-BR', field: 'writing_style' as const, value: 'business' },
-      { lang: 'pt-PT', field: 'writing_style' as const, value: 'casual' },
+      { lang: 'pt-br', field: 'writing_style' as const, value: 'business' },
+      { lang: 'pt-pt', field: 'writing_style' as const, value: 'casual' },
       { lang: 'es', field: 'tone' as const, value: 'friendly' },
       { lang: 'it', field: 'tone' as const, value: 'confident' },
       { lang: 'fr', field: 'tone' as const, value: 'diplomatic' },
       { lang: 'pt', field: 'tone' as const, value: 'enthusiastic' },
-      { lang: 'pt-BR', field: 'tone' as const, value: 'friendly' },
-      { lang: 'pt-PT', field: 'tone' as const, value: 'confident' },
+      { lang: 'pt-br', field: 'tone' as const, value: 'friendly' },
+      { lang: 'pt-pt', field: 'tone' as const, value: 'confident' },
     ])('should send $field=$value with target_lang=$lang', async ({ lang, field, value }) => {
       const targetLang = lang as WriteLanguage;
       const scope = nock(FREE_API_URL)
@@ -353,7 +353,7 @@ describe('Write Command Integration', () => {
 
   describe('improve() - Error Handling', () => {
     it('should throw error for empty text', async () => {
-      await expect(writeService.improve('', { targetLang: 'en-US' })).rejects.toThrow(
+      await expect(writeService.improve('', { targetLang: 'en-us' })).rejects.toThrow(
         'Text cannot be empty'
       );
     });
@@ -361,7 +361,7 @@ describe('Write Command Integration', () => {
     it('should throw error when both style and tone are specified', async () => {
       await expect(
         writeService.improve('Test', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'business',
           tone: 'friendly',
         })
@@ -372,7 +372,7 @@ describe('Write Command Integration', () => {
       nock(FREE_API_URL).post('/v2/write/rephrase').reply(403, { message: 'Invalid API key' });
 
       await expect(
-        writeService.improve('Test', { targetLang: 'en-US' })
+        writeService.improve('Test', { targetLang: 'en-us' })
       ).rejects.toThrow('Authentication failed');
     });
 
@@ -380,7 +380,7 @@ describe('Write Command Integration', () => {
       nock(FREE_API_URL).post('/v2/write/rephrase').reply(456, { message: 'Quota exceeded' });
 
       await expect(
-        writeService.improve('Test', { targetLang: 'en-US' })
+        writeService.improve('Test', { targetLang: 'en-us' })
       ).rejects.toThrow('Quota exceeded');
     });
 
@@ -391,7 +391,7 @@ describe('Write Command Integration', () => {
         .reply(429, { message: 'Too many requests' });
 
       await expect(
-        writeService.improve('Test', { targetLang: 'en-US' })
+        writeService.improve('Test', { targetLang: 'en-us' })
       ).rejects.toThrow('Rate limit exceeded');
     });
 
@@ -410,7 +410,7 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Improved text', target_language: 'en-US' }],
         });
 
-      await writeService.improve(longText, { targetLang: 'en-US' });
+      await writeService.improve(longText, { targetLang: 'en-us' });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -426,7 +426,7 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Improved text!', target_language: 'en-US' }],
         });
 
-      await writeService.improve(specialText, { targetLang: 'en-US' });
+      await writeService.improve(specialText, { targetLang: 'en-us' });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -442,7 +442,7 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Hello, 世界 🌍 café!', target_language: 'en-US' }],
         });
 
-      const result = await writeService.improve(unicodeText, { targetLang: 'en-US' });
+      const result = await writeService.improve(unicodeText, { targetLang: 'en-us' });
       expect(result[0]?.text).toContain('世界');
       expect(result[0]?.text).toContain('🌍');
       expect(scope.isDone()).toBe(true);
@@ -462,7 +462,7 @@ describe('Write Command Integration', () => {
           ],
         });
 
-      const result = await writeService.improve(multilineText, { targetLang: 'en-US' });
+      const result = await writeService.improve(multilineText, { targetLang: 'en-us' });
       expect(result[0]?.text).toContain('\n');
       expect(result[0]?.text.split('\n')).toHaveLength(3);
     });
@@ -480,7 +480,7 @@ describe('Write Command Integration', () => {
         });
 
       const result = await writeService.getBestImprovement('Test text', {
-        targetLang: 'en-US',
+        targetLang: 'en-us',
       });
 
       expect(result.text).toBe('First improvement');
@@ -494,7 +494,7 @@ describe('Write Command Integration', () => {
         });
 
       await expect(
-        writeService.getBestImprovement('Test', { targetLang: 'en-US' })
+        writeService.getBestImprovement('Test', { targetLang: 'en-us' })
       ).rejects.toThrow('No improvements returned');
     });
   });
@@ -516,7 +516,7 @@ describe('Write Command Integration', () => {
         });
 
       await writeService.improve('Utilize this', {
-        targetLang: 'en-US',
+        targetLang: 'en-us',
         writingStyle: 'prefer_simple',
       });
 
@@ -539,7 +539,7 @@ describe('Write Command Integration', () => {
         });
 
       await writeService.improve('This is good', {
-        targetLang: 'en-US',
+        targetLang: 'en-us',
         tone: 'prefer_enthusiastic',
       });
 
@@ -556,8 +556,8 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Improved!', target_language: 'en-US' }],
         });
 
-      const result1 = await writeService.improve('Test', { targetLang: 'en-US' });
-      const result2 = await writeService.improve('Test', { targetLang: 'en-US' });
+      const result1 = await writeService.improve('Test', { targetLang: 'en-us' });
+      const result2 = await writeService.improve('Test', { targetLang: 'en-us' });
 
       expect(result1).toEqual(result2);
       expect(scope.isDone()).toBe(true);
@@ -571,8 +571,8 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Improved!', target_language: 'en-US' }],
         });
 
-      await writeService.improve('Test', { targetLang: 'en-US' });
-      await writeService.improve('Test', { targetLang: 'en-US' }, { skipCache: true });
+      await writeService.improve('Test', { targetLang: 'en-us' });
+      await writeService.improve('Test', { targetLang: 'en-us' }, { skipCache: true });
 
       expect(nock.isDone()).toBe(true);
     });
@@ -590,8 +590,8 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Casual text', target_language: 'en-US' }],
         });
 
-      const business = await writeService.improve('Test', { targetLang: 'en-US', writingStyle: 'business' });
-      const casual = await writeService.improve('Test', { targetLang: 'en-US', writingStyle: 'casual' });
+      const business = await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'business' });
+      const casual = await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'casual' });
 
       expect(business[0]?.text).toBe('Business text');
       expect(casual[0]?.text).toBe('Casual text');
@@ -611,7 +611,7 @@ describe('Write Command Integration', () => {
         .replyWithError('Network error');
 
       await expect(
-        noRetryWriteService.improve('Test', { targetLang: 'en-US' })
+        noRetryWriteService.improve('Test', { targetLang: 'en-us' })
       ).rejects.toThrow();
 
       noRetryClient.destroy();
diff --git a/tests/integration/deepl-client.integration.test.ts b/tests/integration/deepl-client.integration.test.ts
index 581ceb7e..3dea8691 100644
--- a/tests/integration/deepl-client.integration.test.ts
+++ b/tests/integration/deepl-client.integration.test.ts
@@ -585,14 +585,14 @@ describe('DeepLClient Integration', () => {
       const scope = nock(FREE_API_URL)
         .post('/v2/write/rephrase', (body) => {
           expect(body.text).toBe('Hello world');
-          expect(body.target_lang).toBe('en-US');
+          expect(body.target_lang).toBe('en-us');
           return true;
         })
         .reply(200, {
           improvements: [{ text: 'Hello, world!', target_language: 'en-US' }],
         });
 
-      const result = await client.improveText('Hello world', { targetLang: 'en-US' });
+      const result = await client.improveText('Hello world', { targetLang: 'en-us' });
 
       expect(result[0]?.text).toBe('Hello, world!');
       expect(result[0]?.targetLanguage).toBe('en-US');
@@ -612,7 +612,7 @@ describe('DeepLClient Integration', () => {
           improvements: [{ text: 'Improved text', target_language: 'en-US' }],
         });
 
-      await client.improveText('Test', { targetLang: 'en-US', writingStyle: 'business' });
+      await client.improveText('Test', { targetLang: 'en-us', writingStyle: 'business' });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -629,7 +629,7 @@ describe('DeepLClient Integration', () => {
           improvements: [{ text: 'Improved text', target_language: 'en-US' }],
         });
 
-      await client.improveText('Test', { targetLang: 'en-US', tone: 'friendly' });
+      await client.improveText('Test', { targetLang: 'en-us', tone: 'friendly' });
       expect(scope.isDone()).toBe(true);
     });
 
diff --git a/tests/unit/deepl-client-lazy.test.ts b/tests/unit/deepl-client-lazy.test.ts
index 580391bc..2d10774e 100644
--- a/tests/unit/deepl-client-lazy.test.ts
+++ b/tests/unit/deepl-client-lazy.test.ts
@@ -97,7 +97,7 @@ describe('DeepLClient lazy sub-client construction', () => {
     nock(baseUrl).post('/v2/write/rephrase').reply(200, {
       improvements: [{ text: 'Improved.', target_language: 'en-US' }],
     });
-    await client.improveText('Test.', { targetLang: 'en-US' });
+    await client.improveText('Test.', { targetLang: 'en-us' });
 
     expect((client as any)._writeClient).not.toBeNull();
     expect((client as any)._translationClient).toBeUndefined();
diff --git a/tests/unit/deepl-client.test.ts b/tests/unit/deepl-client.test.ts
index 9a878472..9ffbbeb7 100644
--- a/tests/unit/deepl-client.test.ts
+++ b/tests/unit/deepl-client.test.ts
@@ -562,7 +562,7 @@ describe('DeepLClient', () => {
       {
         name: 'improveText()',
         path: '/v2/write/rephrase',
-        call: (c) => c.improveText('Test', { targetLang: 'en-US' }),
+        call: (c) => c.improveText('Test', { targetLang: 'en-us' }),
       },
     ];
 
@@ -1215,7 +1215,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('This is a sentence.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result).toHaveLength(1);
@@ -1230,7 +1230,7 @@ describe('DeepLClient', () => {
           .reply(200, { improvements: [] });
 
         await expect(
-          client.improveText('Test', { targetLang: 'en-US' })
+          client.improveText('Test', { targetLang: 'en-us' })
         ).rejects.toThrow('No improvements returned');
       });
     });
@@ -1252,7 +1252,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('This is a sentence.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'simple',
         });
 
@@ -1276,7 +1276,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('We want to tell you.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'business',
         });
 
@@ -1300,7 +1300,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('This shows it works.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'academic',
         });
 
@@ -1324,7 +1324,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('That is interesting.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'casual',
         });
 
@@ -1350,7 +1350,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('This is good.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'enthusiastic',
         });
 
@@ -1374,7 +1374,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('Hello.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'friendly',
         });
 
@@ -1398,7 +1398,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('I think this will work.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'confident',
         });
 
@@ -1422,7 +1422,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('Try something else.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'diplomatic',
         });
 
@@ -1448,7 +1448,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('Test text.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result[0]?.text).toBe('Improved text.');
@@ -1527,7 +1527,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('This is a sentence.', {
-          targetLang: 'en-GB',
+          targetLang: 'en-gb',
         });
 
         expect(result[0]?.targetLanguage).toBe('en-GB');
@@ -1550,7 +1550,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText(longText, {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result[0]?.text.length).toBeGreaterThan(0);
@@ -1569,7 +1569,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('Test: quotes & chars', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result[0]?.text).toContain('&');
@@ -1589,7 +1589,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('Para 1.\n\nPara 2.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result[0]?.text).toContain('\n\n');
@@ -1613,7 +1613,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('This is a sentence.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'prefer_simple',
         });
 
@@ -1637,7 +1637,7 @@ describe('DeepLClient', () => {
           });
 
         const result = await client.improveText('This is good.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'prefer_enthusiastic',
         });
 
diff --git a/tests/unit/formatters.test.ts b/tests/unit/formatters.test.ts
index a50445a0..9ebda438 100644
--- a/tests/unit/formatters.test.ts
+++ b/tests/unit/formatters.test.ts
@@ -151,11 +151,11 @@ describe('formatters', () => {
       expect(output).toContain('Characters');
 
       // Verify data rows
-      expect(output).toContain('ES');
+      expect(output).toContain('es');
       expect(output).toContain('Hola');
       expect(output).toContain('5');
 
-      expect(output).toContain('FR');
+      expect(output).toContain('fr');
       expect(output).toContain('Bonjour');
       expect(output).toContain('7');
     });
@@ -170,7 +170,7 @@ describe('formatters', () => {
 
       const output = formatMultiTranslationTable(results);
 
-      expect(output).toContain('ES');
+      expect(output).toContain('es');
       expect(output).toContain('Hola');
       // Should NOT contain Characters column when billedCharacters is missing
       expect(output).not.toContain('Characters');
@@ -187,7 +187,7 @@ describe('formatters', () => {
 
       const output = formatMultiTranslationTable(results);
 
-      expect(output).toContain('DE');
+      expect(output).toContain('de');
       expect(output).toContain('Dies ist ein sehr langer');
       expect(output).toContain('100');
     });
@@ -248,10 +248,10 @@ describe('formatters', () => {
       const output = formatMultiTranslationTable(results);
 
       // All languages present
-      expect(output).toContain('ES');
-      expect(output).toContain('FR');
-      expect(output).toContain('DE');
-      expect(output).toContain('JA');
+      expect(output).toContain('es');
+      expect(output).toContain('fr');
+      expect(output).toContain('de');
+      expect(output).toContain('ja');
 
       // All translations present
       expect(output).toContain('Hola');
@@ -304,7 +304,7 @@ describe('formatters', () => {
 
       expect(output).toContain('Language');
       expect(output).toContain('Translation');
-      expect(output).toContain('ES');
+      expect(output).toContain('es');
       expect(output).toContain('Hola');
       // eslint-disable-next-line no-control-regex
       const ansiRegex = /\x1b\[[0-9;]*m/;
@@ -431,14 +431,14 @@ describe('formatters', () => {
       const output = formatWriteJson(
         'This are good.',
         'This is good.',
-        'en-US'
+        'en-us'
       );
       const parsed = JSON.parse(output);
 
       expect(parsed.original).toBe('This are good.');
       expect(parsed.improved).toBe('This is good.');
       expect(parsed.changes).toBe(1);
-      expect(parsed.language).toBe('en-US');
+      expect(parsed.language).toBe('en-us');
     });
 
     it('should set changes to 0 when text is unchanged', () => {
diff --git a/tests/unit/glossary-command.test.ts b/tests/unit/glossary-command.test.ts
index 9a997af9..28d7eaca 100644
--- a/tests/unit/glossary-command.test.ts
+++ b/tests/unit/glossary-command.test.ts
@@ -437,8 +437,8 @@ describe('GlossaryCommand', () => {
 
       expect(result).toContain('Name: Tech Terms');
       expect(result).toContain('ID: 123-456-789');
-      expect(result).toContain('Source language: EN');
-      expect(result).toContain('Target languages: ES');
+      expect(result).toContain('Source language: en');
+      expect(result).toContain('Target languages: es');
       expect(result).toContain('Total entries: 10');
       expect(result).toContain('Type: Single target');
     });
@@ -459,12 +459,12 @@ describe('GlossaryCommand', () => {
       const result = glossaryCommand.formatGlossaryInfo(multilingualGlossary);
 
       expect(result).toContain('Name: Multi Terms');
-      expect(result).toContain('Target languages: ES, FR');
+      expect(result).toContain('Target languages: es, fr');
       expect(result).toContain('Type: Multilingual');
       expect(result).toContain('Total entries: 8');
       expect(result).toContain('Language pairs:');
-      expect(result).toContain('EN → ES: 5 entries');
-      expect(result).toContain('EN → FR: 3 entries');
+      expect(result).toContain('en → es: 5 entries');
+      expect(result).toContain('en → fr: 3 entries');
     });
 
     it('should include creation time as a locale-independent ISO timestamp', () => {
diff --git a/tests/unit/register-correct.test.ts b/tests/unit/register-correct.test.ts
index daf589ac..4a098310 100644
--- a/tests/unit/register-correct.test.ts
+++ b/tests/unit/register-correct.test.ts
@@ -128,7 +128,7 @@ describe('registerCorrect', () => {
       await program.parseAsync(['node', 'test', 'correct', 'Hello', '--lang', 'EN-us']);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'en-US' }),
+        expect.objectContaining({ lang: 'en-us' }),
       );
     });
 
diff --git a/tests/unit/register-write.test.ts b/tests/unit/register-write.test.ts
index ca0c55e4..4a1367f9 100644
--- a/tests/unit/register-write.test.ts
+++ b/tests/unit/register-write.test.ts
@@ -134,7 +134,7 @@ describe('registerWrite', () => {
       await program.parseAsync(['node', 'test', 'write', 'Hello', '-l', 'en-US']);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'en-US' }),
+        expect.objectContaining({ lang: 'en-us' }),
       );
     });
 
@@ -195,7 +195,7 @@ describe('registerWrite', () => {
       );
     });
 
-    it.each(['ja', 'ko', 'zh', 'zh-Hans'])('should accept new target language %s', async (lang) => {
+    it.each(['ja', 'ko', 'zh', 'zh-hans'])('should accept new target language %s', async (lang) => {
       mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
       mockWriteCommand.improve.mockResolvedValue('ok');
       await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', lang]);
@@ -210,11 +210,11 @@ describe('registerWrite', () => {
     // before validating, so write rejecting them made the CLI's own output
     // unusable with the command documented as consistent with translate.
     it.each([
-      ['en-us', 'en-US'],
-      ['en-US', 'en-US'],
-      ['EN-US', 'en-US'],
-      ['pt-br', 'pt-BR'],
-      ['zh-hans', 'zh-Hans'],
+      ['en-us', 'en-us'],
+      ['en-US', 'en-us'],
+      ['EN-US', 'en-us'],
+      ['pt-br', 'pt-br'],
+      ['zh-Hans', 'zh-hans'],
       ['DE', 'de'],
     ])('should accept --lang %s and normalize it to %s', async (input, canonical) => {
       mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
@@ -234,7 +234,7 @@ describe('registerWrite', () => {
       expect(handleError).not.toHaveBeenCalled();
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'pt-BR' }),
+        expect.objectContaining({ lang: 'pt-br' }),
       );
     });
 
diff --git a/tests/unit/text-translation-handler.test.ts b/tests/unit/text-translation-handler.test.ts
index 9261d418..a6de8a28 100644
--- a/tests/unit/text-translation-handler.test.ts
+++ b/tests/unit/text-translation-handler.test.ts
@@ -452,8 +452,8 @@ describe('TextTranslationHandler', () => {
           ]);
 
           const result = await handler.translateText('Hello', defaultOptions({ to: 'de,fr', format: 'table' }));
-          expect(result).toContain('DE');
-          expect(result).toContain('FR');
+          expect(result).toContain('de');
+          expect(result).toContain('fr');
         } finally {
           Object.defineProperty(process.stdout, 'isTTY', {
             value: originalIsTTY,
diff --git a/tests/unit/tm-command.test.ts b/tests/unit/tm-command.test.ts
index 32b017e3..4207e3c6 100644
--- a/tests/unit/tm-command.test.ts
+++ b/tests/unit/tm-command.test.ts
@@ -50,9 +50,9 @@ describe('TmCommand', () => {
       ];
       const out = tmCommand.formatList(tms);
       expect(out).toContain('brand-terms');
-      expect(out).toContain('EN \u2192 DE, FR');
+      expect(out).toContain('en \u2192 de, fr');
       expect(out).toContain('legal-phrases');
-      expect(out).toContain('EN \u2192 FR');
+      expect(out).toContain('en \u2192 fr');
     });
 
     it('strips ASCII control chars from the name column so a malicious TM cannot corrupt the terminal', () => {
diff --git a/tests/unit/translate-command.test.ts b/tests/unit/translate-command.test.ts
index 6256906c..34622332 100644
--- a/tests/unit/translate-command.test.ts
+++ b/tests/unit/translate-command.test.ts
@@ -2518,8 +2518,8 @@ describe('TranslateCommand', () => {
           format: 'table',
         });
 
-        expect(result).toContain('ES');
-        expect(result).toContain('FR');
+        expect(result).toContain('es');
+        expect(result).toContain('fr');
         expect(result).toContain('Hola');
         expect(result).toContain('Bonjour');
       } finally {
diff --git a/tests/unit/write-client.test.ts b/tests/unit/write-client.test.ts
index 4ba83421..6782958d 100644
--- a/tests/unit/write-client.test.ts
+++ b/tests/unit/write-client.test.ts
@@ -94,7 +94,7 @@ describe('WriteClient', () => {
         headers: {},
       });
 
-      await client.improveText('Test', { targetLang: 'en-GB' });
+      await client.improveText('Test', { targetLang: 'en-gb' });
 
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -282,7 +282,7 @@ describe('WriteClient', () => {
         headers: {},
       });
 
-      await client.correctText('Test', { targetLang: 'en-GB' });
+      await client.correctText('Test', { targetLang: 'en-gb' });
 
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -301,10 +301,10 @@ describe('WriteClient', () => {
         headers: {},
       });
 
-      await client.correctText('Test', { targetLang: 'en-US' });
+      await client.correctText('Test', { targetLang: 'en-us' });
 
       const body = mockAxiosInstance.request.mock.calls[0][0].data as string;
-      expect(body).toContain('target_lang=en-US');
+      expect(body).toContain('target_lang=en-us');
       expect(body).not.toContain('writing_style');
       expect(body).not.toContain('tone');
     });
diff --git a/tests/unit/write-command.test.ts b/tests/unit/write-command.test.ts
index bea18f6e..85d5734a 100644
--- a/tests/unit/write-command.test.ts
+++ b/tests/unit/write-command.test.ts
@@ -97,13 +97,13 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovements[0]!);
 
         const result = await writeCommand.improve('This is a sentence.', {
-          lang: 'en-US',
+          lang: 'en-us',
         });
 
         expect(result).toBe('This is a well-written sentence.');
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           'This is a sentence.',
-          { targetLang: 'en-US' },
+          { targetLang: 'en-us' },
           { skipCache: undefined }
         );
       });
@@ -114,7 +114,7 @@ describe('WriteCommand', () => {
         );
 
         await expect(
-          writeCommand.improve('', { lang: 'en-US' })
+          writeCommand.improve('', { lang: 'en-us' })
         ).rejects.toThrow('Text cannot be empty');
       });
 
@@ -142,14 +142,14 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improve('This is a sentence.', {
-          lang: 'en-US',
+          lang: 'en-us',
           style: 'simple',
         });
 
         expect(result).toBe('This is easy to read.');
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           'This is a sentence.',
-          { targetLang: 'en-US', writingStyle: 'simple' },
+          { targetLang: 'en-us', writingStyle: 'simple' },
           { skipCache: undefined }
         );
       });
@@ -163,14 +163,14 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improve('We want to tell you.', {
-          lang: 'en-US',
+          lang: 'en-us',
           style: 'business',
         });
 
         expect(result).toBe('We are pleased to inform you.');
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           'We want to tell you.',
-          { targetLang: 'en-US', writingStyle: 'business' },
+          { targetLang: 'en-us', writingStyle: 'business' },
           { skipCache: undefined }
         );
       });
@@ -184,14 +184,14 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improve('This shows it works.', {
-          lang: 'en-US',
+          lang: 'en-us',
           style: 'academic',
         });
 
         expect(result).toContain('demonstrates');
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           'This shows it works.',
-          { targetLang: 'en-US', writingStyle: 'academic' },
+          { targetLang: 'en-us', writingStyle: 'academic' },
           { skipCache: undefined }
         );
       });
@@ -205,14 +205,14 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improve('That is interesting.', {
-          lang: 'en-US',
+          lang: 'en-us',
           style: 'casual',
         });
 
         expect(result).toContain('cool');
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           'That is interesting.',
-          { targetLang: 'en-US', writingStyle: 'casual' },
+          { targetLang: 'en-us', writingStyle: 'casual' },
           { skipCache: undefined }
         );
       });
@@ -228,14 +228,14 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improve('This is good.', {
-          lang: 'en-US',
+          lang: 'en-us',
           tone: 'enthusiastic',
         });
 
         expect(result).toContain('fantastic');
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           'This is good.',
-          { targetLang: 'en-US', tone: 'enthusiastic' },
+          { targetLang: 'en-us', tone: 'enthusiastic' },
           { skipCache: undefined }
         );
       });
@@ -249,7 +249,7 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improve('Hello.', {
-          lang: 'en-US',
+          lang: 'en-us',
           tone: 'friendly',
         });
 
@@ -265,7 +265,7 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improve('I think this will work.', {
-          lang: 'en-US',
+          lang: 'en-us',
           tone: 'confident',
         });
 
@@ -281,7 +281,7 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improve('Try something else.', {
-          lang: 'en-US',
+          lang: 'en-us',
           tone: 'diplomatic',
         });
 
@@ -300,7 +300,7 @@ describe('WriteCommand', () => {
         mockWriteService.improve.mockResolvedValue(mockImprovements);
 
         const result = await writeCommand.improve('Test', {
-          lang: 'en-US',
+          lang: 'en-us',
           showAlternatives: true,
         });
 
@@ -309,7 +309,7 @@ describe('WriteCommand', () => {
         expect(result).toContain('Third improvement.');
         expect(mockWriteService.improve).toHaveBeenCalledWith(
           'Test',
-          { targetLang: 'en-US' },
+          { targetLang: 'en-us' },
           { skipCache: undefined }
         );
       });
@@ -323,7 +323,7 @@ describe('WriteCommand', () => {
         mockWriteService.improve.mockResolvedValue(mockImprovements);
 
         const result = await writeCommand.improve('Test', {
-          lang: 'en-US',
+          lang: 'en-us',
           showAlternatives: true,
         });
 
@@ -340,7 +340,7 @@ describe('WriteCommand', () => {
 
         await expect(
           writeCommand.improve('Test', {
-            lang: 'en-US',
+            lang: 'en-us',
             style: 'business',
             tone: 'enthusiastic',
           })
@@ -355,7 +355,7 @@ describe('WriteCommand', () => {
         );
 
         await expect(
-          writeCommand.improve('Test', { lang: 'en-US' })
+          writeCommand.improve('Test', { lang: 'en-us' })
         ).rejects.toThrow('Service error');
       });
 
@@ -365,7 +365,7 @@ describe('WriteCommand', () => {
         );
 
         await expect(
-          writeCommand.improve('Test', { lang: 'en-US' })
+          writeCommand.improve('Test', { lang: 'en-us' })
         ).rejects.toThrow('Authentication failed');
       });
 
@@ -375,24 +375,24 @@ describe('WriteCommand', () => {
         );
 
         await expect(
-          writeCommand.improve('Test', { lang: 'en-US' })
+          writeCommand.improve('Test', { lang: 'en-us' })
         ).rejects.toThrow('Quota exceeded');
       });
     });
 
     describe('supported languages', () => {
       it('should work with all supported Write languages', async () => {
-        const languages: Array<'de' | 'en' | 'en-GB' | 'en-US' | 'es' | 'fr' | 'it' | 'pt' | 'pt-BR' | 'pt-PT'> = [
+        const languages: Array<'de' | 'en' | 'en-gb' | 'en-us' | 'es' | 'fr' | 'it' | 'pt' | 'pt-br' | 'pt-pt'> = [
           'de',
           'en',
-          'en-GB',
-          'en-US',
+          'en-gb',
+          'en-us',
           'es',
           'fr',
           'it',
           'pt',
-          'pt-BR',
-          'pt-PT',
+          'pt-br',
+          'pt-pt',
         ];
 
         for (const lang of languages) {
@@ -427,26 +427,26 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improveFile(testFile, {
-          lang: 'en-US',
+          lang: 'en-us',
         });
 
         expect(result).toBe('This is improved content.');
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           'Original content',
-          { targetLang: 'en-US' },
+          { targetLang: 'en-us' },
           { skipCache: undefined }
         );
       });
 
       it('should throw error for non-existent file', async () => {
         await expect(
-          writeCommand.improveFile(join(testDir, 'nonexistent.txt'), { lang: 'en-US' })
+          writeCommand.improveFile(join(testDir, 'nonexistent.txt'), { lang: 'en-us' })
         ).rejects.toThrow('File not found');
       });
 
       it('should throw error for empty file path', async () => {
         await expect(
-          writeCommand.improveFile('', { lang: 'en-US' })
+          writeCommand.improveFile('', { lang: 'en-us' })
         ).rejects.toThrow('File path cannot be empty');
       });
     });
@@ -465,7 +465,7 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         await writeCommand.improveFile(inputFile, {
-          lang: 'en-US',
+          lang: 'en-us',
           outputFile,
         });
 
@@ -485,7 +485,7 @@ describe('WriteCommand', () => {
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
         const result = await writeCommand.improveFile(testFile, {
-          lang: 'en-US',
+          lang: 'en-us',
           inPlace: true,
         });
 
@@ -507,11 +507,11 @@ describe('WriteCommand', () => {
 
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
-        await writeCommand.improveFile(testFile, { lang: 'en-US' });
+        await writeCommand.improveFile(testFile, { lang: 'en-us' });
 
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           'Plain text content',
-          { targetLang: 'en-US' },
+          { targetLang: 'en-us' },
           { skipCache: undefined }
         );
       });
@@ -527,11 +527,11 @@ describe('WriteCommand', () => {
 
         mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
-        await writeCommand.improveFile(testFile, { lang: 'en-US' });
+        await writeCommand.improveFile(testFile, { lang: 'en-us' });
 
         expect(mockWriteService.getBestImprovement).toHaveBeenCalledWith(
           '# Original Heading',
-          { targetLang: 'en-US' },
+          { targetLang: 'en-us' },
           { skipCache: undefined }
         );
       });
@@ -588,7 +588,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.improveWithDiff(original, {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.original).toBe(original);
@@ -609,7 +609,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.improveFileWithDiff(testFile, {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.original).toBe('Original content');
@@ -628,7 +628,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.checkText('Original text.', {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.needsImprovement).toBe(true);
@@ -647,7 +647,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.checkText(text, {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.needsImprovement).toBe(false);
@@ -666,7 +666,7 @@ describe('WriteCommand', () => {
 
       const result = await writeCommand.checkText(
         'Line 1 original\nLine 2\nLine 3 original',
-        { lang: 'en-US' }
+        { lang: 'en-us' }
       );
 
       expect(result.needsImprovement).toBe(true);
@@ -687,7 +687,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.checkFile(testFile, {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.needsImprovement).toBe(true);
@@ -698,7 +698,7 @@ describe('WriteCommand', () => {
     it('should throw error for non-existent file', async () => {
       await expect(
         writeCommand.checkFile(join(testDir, 'nonexistent.txt'), {
-          lang: 'en-US',
+          lang: 'en-us',
         })
       ).rejects.toThrow('File not found');
     });
@@ -716,7 +716,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.checkFile(testFile, {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.needsImprovement).toBe(false);
@@ -738,7 +738,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.autoFixFile(testFile, {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.fixed).toBe(true);
@@ -764,7 +764,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.autoFixFile(testFile, {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.fixed).toBe(false);
@@ -788,7 +788,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
 
       const result = await writeCommand.autoFixFile(testFile, {
-        lang: 'en-US',
+        lang: 'en-us',
         createBackup: true,
       });
 
@@ -803,7 +803,7 @@ describe('WriteCommand', () => {
     it('should throw error for non-existent file', async () => {
       await expect(
         writeCommand.autoFixFile(join(testDir, 'nonexistent.txt'), {
-          lang: 'en-US',
+          lang: 'en-us',
         })
       ).rejects.toThrow('File not found');
     });
@@ -831,7 +831,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(1);
 
       const result = await writeCommand.improveInteractive('Original text.', {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       // Should call API 4 times (once for each style)
@@ -850,7 +850,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(-1); // -1 = keep original
 
       const result = await writeCommand.improveInteractive('Original text.', {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result).toBe('Original text.');
@@ -865,7 +865,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(0);
 
       const result = await writeCommand.improveInteractive('Original text.', {
-        lang: 'en-US',
+        lang: 'en-us',
         style: 'business',
       });
 
@@ -885,7 +885,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(0);
 
       const result = await writeCommand.improveInteractive('Original.', {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       // Should work and return a result
@@ -916,7 +916,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(1);
 
       const result = await writeCommand.improveFileInteractive(testFile, {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(result.selected).toBe('Business.');
@@ -934,7 +934,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(0);
 
       const result = await writeCommand.improveInteractive('Original.', {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       // Should still work with partial results
@@ -951,7 +951,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(0);
 
       await writeCommand.improveInteractive('Original.', {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(mockLogger.verbose).toHaveBeenCalledWith(
@@ -975,7 +975,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(0);
 
       await writeCommand.improveInteractive('Original.', {
-        lang: 'en-US',
+        lang: 'en-us',
       });
 
       expect(mockLogger.verbose).toHaveBeenCalledWith(
@@ -993,7 +993,7 @@ describe('WriteCommand', () => {
         .mockRejectedValueOnce(new Error('API error'));
 
       await expect(
-        writeCommand.improveInteractive('Original text.', { lang: 'en-US' })
+        writeCommand.improveInteractive('Original text.', { lang: 'en-us' })
       ).rejects.toThrow('No improvements could be generated');
     });
 
@@ -1006,14 +1006,14 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(0);
 
       const result = await writeCommand.improveInteractive('Original text.', {
-        lang: 'en-US',
+        lang: 'en-us',
         tone: 'enthusiastic',
       });
 
       expect(mockWriteService.improve).toHaveBeenCalledTimes(1);
       expect(mockWriteService.improve).toHaveBeenCalledWith(
         'Original text.',
-        { targetLang: 'en-US', tone: 'enthusiastic' },
+        { targetLang: 'en-us', tone: 'enthusiastic' },
         { skipCache: undefined }
       );
       expect(result).toBe('Enthusiastic improvement!');
@@ -1028,7 +1028,7 @@ describe('WriteCommand', () => {
       mockSelect.mockResolvedValue(-1);
 
       const result = await writeCommand.improveInteractive('Original text.', {
-        lang: 'en-US',
+        lang: 'en-us',
         tone: 'friendly',
       });
 
@@ -1050,31 +1050,31 @@ describe('WriteCommand', () => {
 
     it('should reject symlinks in improveFile()', async () => {
       await expect(
-        writeCommand.improveFile(symlinkPath, { lang: 'en-US' })
+        writeCommand.improveFile(symlinkPath, { lang: 'en-us' })
       ).rejects.toThrow('Symlinks are not supported for security reasons');
     });
 
     it('should reject symlinks in improveFileWithDiff()', async () => {
       await expect(
-        writeCommand.improveFileWithDiff(symlinkPath, { lang: 'en-US' })
+        writeCommand.improveFileWithDiff(symlinkPath, { lang: 'en-us' })
       ).rejects.toThrow('Symlinks are not supported for security reasons');
     });
 
     it('should reject symlinks in checkFile()', async () => {
       await expect(
-        writeCommand.checkFile(symlinkPath, { lang: 'en-US' })
+        writeCommand.checkFile(symlinkPath, { lang: 'en-us' })
       ).rejects.toThrow('Symlinks are not supported for security reasons');
     });
 
     it('should reject symlinks in autoFixFile()', async () => {
       await expect(
-        writeCommand.autoFixFile(symlinkPath, { lang: 'en-US' })
+        writeCommand.autoFixFile(symlinkPath, { lang: 'en-us' })
       ).rejects.toThrow('Symlinks are not supported for security reasons');
     });
 
     it('should reject symlinks in improveFileInteractive()', async () => {
       await expect(
-        writeCommand.improveFileInteractive(symlinkPath, { lang: 'en-US' })
+        writeCommand.improveFileInteractive(symlinkPath, { lang: 'en-us' })
       ).rejects.toThrow('Symlinks are not supported for security reasons');
     });
   });
@@ -1089,14 +1089,14 @@ describe('WriteCommand', () => {
       mockWriteService.getBestCorrection.mockResolvedValue(mockCorrection);
 
       const result = await writeCommand.improve('This is an test.', {
-        lang: 'en-US',
+        lang: 'en-us',
         correct: true,
       });
 
       expect(result).toBe('This is a test.');
       expect(mockWriteService.getBestCorrection).toHaveBeenCalledWith(
         'This is an test.',
-        { targetLang: 'en-US' },
+        { targetLang: 'en-us' },
         { skipCache: undefined }
       );
       expect(mockWriteService.getBestImprovement).not.toHaveBeenCalled();
@@ -1139,7 +1139,7 @@ describe('WriteCommand', () => {
       mockWriteService.getBestCorrection.mockResolvedValue(mockCorrection);
 
       const result = await writeCommand.checkText('This is an test.', {
-        lang: 'en-US',
+        lang: 'en-us',
         correct: true,
       });
 
@@ -1151,7 +1151,7 @@ describe('WriteCommand', () => {
     it('should not use the correct endpoint when correct is not set', async () => {
       mockWriteService.getBestImprovement.mockResolvedValue(mockCorrection);
 
-      await writeCommand.improve('Test', { lang: 'en-US' });
+      await writeCommand.improve('Test', { lang: 'en-us' });
 
       expect(mockWriteService.getBestCorrection).not.toHaveBeenCalled();
       expect(mockWriteService.correct).not.toHaveBeenCalled();
diff --git a/tests/unit/write-service.test.ts b/tests/unit/write-service.test.ts
index db1a92ef..34761b93 100644
--- a/tests/unit/write-service.test.ts
+++ b/tests/unit/write-service.test.ts
@@ -60,25 +60,25 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('This is a sentence.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result).toHaveLength(1);
         expect(result[0]?.text).toBe('This is a well-written sentence.');
         expect(mockClient.improveText).toHaveBeenCalledWith('This is a sentence.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
       });
 
       it('should throw error for empty text', async () => {
         await expect(
-          writeService.improve('', { targetLang: 'en-US' })
+          writeService.improve('', { targetLang: 'en-us' })
         ).rejects.toThrow('Text cannot be empty');
       });
 
       it('should throw error for whitespace-only text', async () => {
         await expect(
-          writeService.improve('   ', { targetLang: 'en-US' })
+          writeService.improve('   ', { targetLang: 'en-us' })
         ).rejects.toThrow('Text cannot be empty');
       });
 
@@ -111,13 +111,13 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('This is a sentence.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'simple',
         });
 
         expect(result[0]?.text).toBe('This is easy to read.');
         expect(mockClient.improveText).toHaveBeenCalledWith('This is a sentence.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'simple',
         });
       });
@@ -133,7 +133,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('We want to tell you.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'business',
         });
 
@@ -151,7 +151,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('This shows it works.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'academic',
         });
 
@@ -169,7 +169,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('That is interesting.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           writingStyle: 'casual',
         });
 
@@ -189,7 +189,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('This is good.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'enthusiastic',
         });
 
@@ -207,7 +207,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('Hello.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'friendly',
         });
 
@@ -225,7 +225,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('I think this will work.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'confident',
         });
 
@@ -243,7 +243,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('Try something else.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
           tone: 'diplomatic',
         });
 
@@ -255,7 +255,7 @@ describe('WriteService', () => {
       it('should throw error when both --style and --tone are specified', async () => {
         await expect(
           writeService.improve('Test', {
-            targetLang: 'en-US',
+            targetLang: 'en-us',
             writingStyle: 'business',
             tone: 'enthusiastic',
           })
@@ -273,7 +273,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('Test text.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result[0]?.text).toBe('Improved text.');
@@ -285,7 +285,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockRejectedValue(new Error('API error'));
 
         await expect(
-          writeService.improve('Test', { targetLang: 'en-US' })
+          writeService.improve('Test', { targetLang: 'en-us' })
         ).rejects.toThrow('API error');
       });
 
@@ -295,7 +295,7 @@ describe('WriteService', () => {
         );
 
         await expect(
-          writeService.improve('Test', { targetLang: 'en-US' })
+          writeService.improve('Test', { targetLang: 'en-us' })
         ).rejects.toThrow('Authentication failed');
       });
 
@@ -305,7 +305,7 @@ describe('WriteService', () => {
         );
 
         await expect(
-          writeService.improve('Test', { targetLang: 'en-US' })
+          writeService.improve('Test', { targetLang: 'en-us' })
         ).rejects.toThrow('Quota exceeded');
       });
 
@@ -315,7 +315,7 @@ describe('WriteService', () => {
         );
 
         await expect(
-          writeService.improve('Test', { targetLang: 'en-US' })
+          writeService.improve('Test', { targetLang: 'en-us' })
         ).rejects.toThrow('Rate limit exceeded');
       });
     });
@@ -333,7 +333,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve(longText, {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result[0]?.text.length).toBeGreaterThan(0);
@@ -350,7 +350,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('Test: quotes & chars', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result[0]?.text).toContain('&');
@@ -368,7 +368,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('Para 1.\n\nPara 2.', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result[0]?.text).toContain('\n\n');
@@ -389,7 +389,7 @@ describe('WriteService', () => {
         mockClient.improveText.mockResolvedValue(mockImprovements);
 
         const result = await writeService.improve('Test', {
-          targetLang: 'en-US',
+          targetLang: 'en-us',
         });
 
         expect(result).toHaveLength(2);
@@ -415,7 +415,7 @@ describe('WriteService', () => {
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
       const result = await writeService.getBestImprovement('Test', {
-        targetLang: 'en-US',
+        targetLang: 'en-us',
       });
 
       expect(result.text).toBe('Best improvement.');
@@ -425,7 +425,7 @@ describe('WriteService', () => {
       mockClient.improveText.mockResolvedValue([]);
 
       await expect(
-        writeService.getBestImprovement('Test', { targetLang: 'en-US' })
+        writeService.getBestImprovement('Test', { targetLang: 'en-us' })
       ).rejects.toThrow('No improvements available');
     });
   });
@@ -441,7 +441,7 @@ describe('WriteService', () => {
     it('should cache results after API call', async () => {
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      await writeService.improve('Test', { targetLang: 'en-US' });
+      await writeService.improve('Test', { targetLang: 'en-us' });
 
       expect(mockCacheService.set).toHaveBeenCalledTimes(1);
       expect(mockCacheService.set).toHaveBeenCalledWith(
@@ -453,7 +453,7 @@ describe('WriteService', () => {
     it('should return cached result on hit without calling API', async () => {
       mockCacheService.get.mockReturnValue(mockImprovements);
 
-      const result = await writeService.improve('Test', { targetLang: 'en-US' });
+      const result = await writeService.improve('Test', { targetLang: 'en-us' });
 
       expect(result).toEqual(mockImprovements);
       expect(mockClient.improveText).not.toHaveBeenCalled();
@@ -464,7 +464,7 @@ describe('WriteService', () => {
       mockConfigService.getValue.mockReturnValue(false);
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      await writeService.improve('Test', { targetLang: 'en-US' });
+      await writeService.improve('Test', { targetLang: 'en-us' });
 
       expect(mockCacheService.get).not.toHaveBeenCalled();
       expect(mockCacheService.set).not.toHaveBeenCalled();
@@ -474,7 +474,7 @@ describe('WriteService', () => {
     it('should skip cache when skipCache is true', async () => {
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      await writeService.improve('Test', { targetLang: 'en-US' }, { skipCache: true });
+      await writeService.improve('Test', { targetLang: 'en-us' }, { skipCache: true });
 
       expect(mockCacheService.get).not.toHaveBeenCalled();
       expect(mockCacheService.set).not.toHaveBeenCalled();
@@ -484,8 +484,8 @@ describe('WriteService', () => {
     it('should produce different cache keys for different options', async () => {
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      await writeService.improve('Test', { targetLang: 'en-US', writingStyle: 'business' });
-      await writeService.improve('Test', { targetLang: 'en-US', writingStyle: 'casual' });
+      await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'business' });
+      await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'casual' });
 
       const key1 = mockCacheService.set.mock.calls[0]![0];
       const key2 = mockCacheService.set.mock.calls[1]![0];
@@ -495,8 +495,8 @@ describe('WriteService', () => {
     it('should produce same cache key for same options (deterministic)', async () => {
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      await writeService.improve('Test', { targetLang: 'en-US', writingStyle: 'business' });
-      await writeService.improve('Test', { targetLang: 'en-US', writingStyle: 'business' });
+      await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'business' });
+      await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'business' });
 
       const key1 = mockCacheService.set.mock.calls[0]![0];
       const key2 = mockCacheService.set.mock.calls[1]![0];
@@ -506,7 +506,7 @@ describe('WriteService', () => {
     it('should benefit getBestImprovement from cache', async () => {
       mockCacheService.get.mockReturnValue(mockImprovements);
 
-      const result = await writeService.getBestImprovement('Test', { targetLang: 'en-US' });
+      const result = await writeService.getBestImprovement('Test', { targetLang: 'en-us' });
 
       expect(result.text).toBe('Improved text.');
       expect(mockClient.improveText).not.toHaveBeenCalled();
@@ -525,10 +525,10 @@ describe('WriteService', () => {
     it('should correct text via client.correctText', async () => {
       mockClient.correctText.mockResolvedValue(mockCorrections);
 
-      const result = await writeService.correct('This is an test.', { targetLang: 'en-US' });
+      const result = await writeService.correct('This is an test.', { targetLang: 'en-us' });
 
       expect(result).toEqual(mockCorrections);
-      expect(mockClient.correctText).toHaveBeenCalledWith('This is an test.', { targetLang: 'en-US' });
+      expect(mockClient.correctText).toHaveBeenCalledWith('This is an test.', { targetLang: 'en-us' });
       expect(mockClient.improveText).not.toHaveBeenCalled();
     });
 
@@ -541,7 +541,7 @@ describe('WriteService', () => {
     it('should cache results under the correct: prefix', async () => {
       mockClient.correctText.mockResolvedValue(mockCorrections);
 
-      await writeService.correct('Test', { targetLang: 'en-US' });
+      await writeService.correct('Test', { targetLang: 'en-us' });
 
       expect(mockCacheService.set).toHaveBeenCalledTimes(1);
       expect(mockCacheService.set).toHaveBeenCalledWith(
@@ -553,7 +553,7 @@ describe('WriteService', () => {
     it('should return cached result on hit without calling API', async () => {
       mockCacheService.get.mockReturnValue(mockCorrections);
 
-      const result = await writeService.correct('Test', { targetLang: 'en-US' });
+      const result = await writeService.correct('Test', { targetLang: 'en-us' });
 
       expect(result).toEqual(mockCorrections);
       expect(mockClient.correctText).not.toHaveBeenCalled();
@@ -563,7 +563,7 @@ describe('WriteService', () => {
     it('should skip cache when skipCache is true', async () => {
       mockClient.correctText.mockResolvedValue(mockCorrections);
 
-      await writeService.correct('Test', { targetLang: 'en-US' }, { skipCache: true });
+      await writeService.correct('Test', { targetLang: 'en-us' }, { skipCache: true });
 
       expect(mockCacheService.get).not.toHaveBeenCalled();
       expect(mockCacheService.set).not.toHaveBeenCalled();
@@ -574,8 +574,8 @@ describe('WriteService', () => {
       mockClient.correctText.mockResolvedValue(mockCorrections);
       mockClient.improveText.mockResolvedValue(mockCorrections);
 
-      await writeService.correct('Test', { targetLang: 'en-US' });
-      await writeService.improve('Test', { targetLang: 'en-US' });
+      await writeService.correct('Test', { targetLang: 'en-us' });
+      await writeService.improve('Test', { targetLang: 'en-us' });
 
       const correctKey = mockCacheService.set.mock.calls[0]![0];
       const writeKey = mockCacheService.set.mock.calls[1]![0];
@@ -585,8 +585,8 @@ describe('WriteService', () => {
     it('should produce deterministic cache keys', async () => {
       mockClient.correctText.mockResolvedValue(mockCorrections);
 
-      await writeService.correct('Test', { targetLang: 'en-US' });
-      await writeService.correct('Test', { targetLang: 'en-US' });
+      await writeService.correct('Test', { targetLang: 'en-us' });
+      await writeService.correct('Test', { targetLang: 'en-us' });
 
       const key1 = mockCacheService.set.mock.calls[0]![0];
       const key2 = mockCacheService.set.mock.calls[1]![0];
@@ -601,7 +601,7 @@ describe('WriteService', () => {
         { text: 'Second.', targetLanguage: 'en-US' },
       ]);
 
-      const result = await writeService.getBestCorrection('Test', { targetLang: 'en-US' });
+      const result = await writeService.getBestCorrection('Test', { targetLang: 'en-us' });
 
       expect(result.text).toBe('First.');
     });
@@ -611,24 +611,24 @@ describe('WriteService', () => {
       mockClient.correctText.mockResolvedValue([]);
 
       await expect(
-        writeService.getBestCorrection('Test', { targetLang: 'en-US' })
+        writeService.getBestCorrection('Test', { targetLang: 'en-us' })
       ).rejects.toThrow('No improvements available');
     });
   });
 
   describe('supported languages', () => {
     it('should work with all supported Write languages', async () => {
-      const languages: Array<'de' | 'en' | 'en-GB' | 'en-US' | 'es' | 'fr' | 'it' | 'pt' | 'pt-BR' | 'pt-PT'> = [
+      const languages: Array<'de' | 'en' | 'en-gb' | 'en-us' | 'es' | 'fr' | 'it' | 'pt' | 'pt-br' | 'pt-pt'> = [
         'de',
         'en',
-        'en-GB',
-        'en-US',
+        'en-gb',
+        'en-us',
         'es',
         'fr',
         'it',
         'pt',
-        'pt-BR',
-        'pt-PT',
+        'pt-br',
+        'pt-pt',
       ];
 
       for (const lang of languages) {
@@ -658,7 +658,7 @@ describe('WriteService', () => {
       ];
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      const result = await cachelessService.improve('Test', { targetLang: 'en-US' });
+      const result = await cachelessService.improve('Test', { targetLang: 'en-us' });
 
       expect(result).toHaveLength(1);
       expect(mockClient.improveText).toHaveBeenCalledTimes(1);

From fab33e6a18e092f993343d518e370a2c09bbc732 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 09:25:26 -0400
Subject: [PATCH 014/256] test(watch): recover the dropped fsevents add in the
 filesWatched test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"should track files added and removed while watching" timed out under load at
roughly 1 run in 20. The cause is not slowness: instrumenting the wait showed
every failure was the add phase with the counter still at 1, while successful
adds land in ~20ms and never approach the 5s budget. fsevents drops the
notification for a file created in the moment after 'ready' fires, while the
stream is still arming, and `ignoreInitial: true` means no rescan recovers it —
so the event never arrives at all.

The wait now re-touches the file every 500ms, which produces a fresh
notification once the stream is delivering. Measured over 200 iterations under
CPU contention: 0 failures, with 10 (5%) recovered by a nudge, matching the
4.5% failure rate seen before. Detection power is unchanged, since a watcher
that fails to count adds never reaches the expected value however often the
file is touched.

The timeout message also reports the count it last saw. "Timed out waiting for
condition" said nothing about whether the counter had stalled or overshot,
which is what made the diagnosis need a separate harness.
---
 .../integration/cli-watch.integration.test.ts | 32 +++++++++++++++----
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/tests/integration/cli-watch.integration.test.ts b/tests/integration/cli-watch.integration.test.ts
index 1e948c8a..d48661ed 100644
--- a/tests/integration/cli-watch.integration.test.ts
+++ b/tests/integration/cli-watch.integration.test.ts
@@ -226,13 +226,33 @@ describe('Watch Service Integration', () => {
   });
 
   describe('getStats()', () => {
-    const waitFor = async (condition: () => boolean, timeoutMs = 5000): Promise<void> => {
+    /**
+     * `nudge` re-touches the file being waited on. fsevents can drop the
+     * notification for a file created in the moment after 'ready' fires, while
+     * the stream is still arming: the event then never arrives at all rather
+     * than arriving late (observed adds land in ~20ms or not within 5s), and
+     * `ignoreInitial: true` means no rescan recovers it. Re-touching does not
+     * weaken the assertion — a watcher that fails to count adds never reaches
+     * the expected value however often the file is touched.
+     */
+    const waitForFilesWatched = async (
+      expected: number,
+      nudge?: () => void,
+      timeoutMs = 5000,
+    ): Promise<void> => {
       const start = Date.now();
-      while (!condition()) {
+      let lastNudge = start;
+      while (watchService.getStats().filesWatched !== expected) {
         if (Date.now() - start > timeoutMs) {
-          throw new Error('Timed out waiting for condition');
+          throw new Error(
+            `Timed out waiting for filesWatched === ${expected}, last saw ${watchService.getStats().filesWatched}`,
+          );
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25));
+        if (nudge && Date.now() - lastNudge > 500) {
+          lastNudge = Date.now();
+          nudge();
         }
-        await new Promise((resolve) => setTimeout(resolve, 10));
       }
     };
 
@@ -290,10 +310,10 @@ describe('Watch Service Integration', () => {
 
       const newFile = path.join(tmpDir, 'b.txt');
       fs.writeFileSync(newFile, 'World');
-      await waitFor(() => watchService.getStats().filesWatched === 2);
+      await waitForFilesWatched(2, () => fs.writeFileSync(newFile, 'World again'));
 
       fs.unlinkSync(newFile);
-      await waitFor(() => watchService.getStats().filesWatched === 1);
+      await waitForFilesWatched(1);
     });
 
     it('should increment error count on translation failure', async () => {

From 49f1f6cf0f7e52cee65af1bfb14a4029d537c3b2 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 11:01:53 -0400
Subject: [PATCH 015/256] fix(languages): source formality from the v3 features
 matrix

GET /v3/languages does report formality support -- as features.formality,
which is what v2's supports_formality became. The static supportsFormality
snapshot added alongside the v3 migration was therefore unnecessary, and it
had already drifted: live v3 reports formality for pt, the registry did not,
so `deepl languages --target` omitted [F] for Portuguese.

Formality now derives from features.formality presence, and the features
matrix is carried through on LanguageInfo for both roles. The 11-entry
snapshot and the supportsFormality field are removed from the registry;
category and targetOnly are untouched.

Verified live: `deepl languages --target` output is byte-identical to before
except pt, which now correctly shows [F].
---
 src/api/translation-client.ts                 | 24 +++++-
 src/data/language-registry.ts                 | 27 +++----
 .../deepl-client.integration.test.ts          | 48 ++++++++++--
 tests/unit/deepl-client.test.ts               | 26 ++++++-
 tests/unit/language-registry.test.ts          | 26 ++-----
 tests/unit/translation-client.test.ts         | 75 ++++++++++++++++++-
 6 files changed, 172 insertions(+), 54 deletions(-)

diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index c10ffa0e..67246e4f 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -3,7 +3,6 @@ import { TranslationOptions, Language, TranslationMemory } from '../types/index.
 import { NetworkError } from '../utils/errors.js';
 import { normalizeFormality } from '../utils/formality.js';
 import { resolveGlossaryWireParams } from '../utils/glossary-params.js';
-import { LANGUAGE_REGISTRY } from '../data/language-registry.js';
 import { Logger } from '../utils/logger.js';
 
 // DeepL's /v3/translation_memories endpoint paginates via `page` (0-indexed) and
@@ -46,8 +45,10 @@ interface DeepLUsageResponse {
 interface DeepLV3LanguageResponse {
   lang: string;
   name: string;
+  status?: string;
   usable_as_source?: boolean;
   usable_as_target?: boolean;
+  features?: LanguageFeatures;
 }
 
 export interface TranslationResult {
@@ -90,10 +91,24 @@ export interface UsageInfo {
   products?: ProductUsage[];
 }
 
+/**
+ * Per-feature support as reported by GET /v3/languages. A feature is supported
+ * when its key is present; `status` describes maturity, not availability.
+ * Known values are `stable`, `beta` and `early_access`, but the enum is open,
+ * so it stays a plain string.
+ */
+export interface LanguageFeature {
+  status: string;
+}
+
+/** Feature keys vary by `resource`, so the map is deliberately open-ended. */
+export type LanguageFeatures = Record<string, LanguageFeature>;
+
 export interface LanguageInfo {
   language: Language;
   name: string;
   supportsFormality?: boolean;
+  features?: LanguageFeatures;
 }
 
 export class TranslationClient extends HttpClient {
@@ -269,8 +284,8 @@ export class TranslationClient extends HttpClient {
   /**
    * Lists languages via GET /v3/languages (v2 is deprecated). One response
    * carries both roles as usable_as_source/usable_as_target flags, filtered
-   * here to preserve the per-type contract. The v3 response no longer reports
-   * formality support, so that comes from the static language registry.
+   * here to preserve the per-type contract. Formality support comes from the
+   * per-language features matrix, which is what v2's supports_formality became.
    */
   async getSupportedLanguages(
     type: 'source' | 'target'
@@ -290,8 +305,9 @@ export class TranslationClient extends HttpClient {
             language: code,
             name: lang.name,
             ...(type === 'target' && {
-              supportsFormality: LANGUAGE_REGISTRY.get(code)?.supportsFormality ?? false,
+              supportsFormality: lang.features?.['formality'] !== undefined,
             }),
+            ...(lang.features && { features: lang.features }),
           };
         });
     } catch (error) {
diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index f74024f6..47296ec2 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -24,17 +24,12 @@ export type LanguageCategory = 'core' | 'regional' | 'extended';
  * @property category - Feature-availability tier
  * @property targetOnly - When true, the language can only be used as a translation target
  *   (not as a source). Applies to regional variants like 'en-gb' and 'pt-br'.
- * @property supportsFormality - When true, the language supports the formality
- *   parameter as a translation target. Static because GET /v3/languages does not
- *   report formality support (the v2 endpoint did); values mirror the last
- *   /v2/languages?type=target response (captured 2026-08-01).
  */
 export interface LanguageEntry {
   code: string;
   name: string;
   category: LanguageCategory;
   targetOnly?: boolean;
-  supportsFormality?: boolean;
 }
 
 const ENTRIES: LanguageEntry[] = [
@@ -43,27 +38,27 @@ const ENTRIES: LanguageEntry[] = [
   { code: 'bg', name: 'Bulgarian', category: 'core' },
   { code: 'cs', name: 'Czech', category: 'core' },
   { code: 'da', name: 'Danish', category: 'core' },
-  { code: 'de', name: 'German', category: 'core', supportsFormality: true },
+  { code: 'de', name: 'German', category: 'core' },
   { code: 'el', name: 'Greek', category: 'core' },
   { code: 'en', name: 'English', category: 'core' },
-  { code: 'es', name: 'Spanish', category: 'core', supportsFormality: true },
+  { code: 'es', name: 'Spanish', category: 'core' },
   { code: 'et', name: 'Estonian', category: 'core' },
   { code: 'fi', name: 'Finnish', category: 'core' },
-  { code: 'fr', name: 'French', category: 'core', supportsFormality: true },
+  { code: 'fr', name: 'French', category: 'core' },
   { code: 'he', name: 'Hebrew', category: 'core' },
   { code: 'hu', name: 'Hungarian', category: 'core' },
   { code: 'id', name: 'Indonesian', category: 'core' },
-  { code: 'it', name: 'Italian', category: 'core', supportsFormality: true },
-  { code: 'ja', name: 'Japanese', category: 'core', supportsFormality: true },
+  { code: 'it', name: 'Italian', category: 'core' },
+  { code: 'ja', name: 'Japanese', category: 'core' },
   { code: 'ko', name: 'Korean', category: 'core' },
   { code: 'lt', name: 'Lithuanian', category: 'core' },
   { code: 'lv', name: 'Latvian', category: 'core' },
   { code: 'nb', name: 'Norwegian Bokmål', category: 'core' },
-  { code: 'nl', name: 'Dutch', category: 'core', supportsFormality: true },
-  { code: 'pl', name: 'Polish', category: 'core', supportsFormality: true },
+  { code: 'nl', name: 'Dutch', category: 'core' },
+  { code: 'pl', name: 'Polish', category: 'core' },
   { code: 'pt', name: 'Portuguese', category: 'core' },
   { code: 'ro', name: 'Romanian', category: 'core' },
-  { code: 'ru', name: 'Russian', category: 'core', supportsFormality: true },
+  { code: 'ru', name: 'Russian', category: 'core' },
   { code: 'sk', name: 'Slovak', category: 'core' },
   { code: 'sl', name: 'Slovenian', category: 'core' },
   { code: 'sv', name: 'Swedish', category: 'core' },
@@ -75,9 +70,9 @@ const ENTRIES: LanguageEntry[] = [
   // Regional variants (target-only)
   { code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true },
   { code: 'en-us', name: 'English (American)', category: 'regional', targetOnly: true },
-  { code: 'es-419', name: 'Spanish (Latin America)', category: 'regional', targetOnly: true, supportsFormality: true },
-  { code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true, supportsFormality: true },
-  { code: 'pt-pt', name: 'Portuguese (European)', category: 'regional', targetOnly: true, supportsFormality: true },
+  { code: 'es-419', name: 'Spanish (Latin America)', category: 'regional', targetOnly: true },
+  { code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true },
+  { code: 'pt-pt', name: 'Portuguese (European)', category: 'regional', targetOnly: true },
   { code: 'zh-hans', name: 'Chinese (Simplified)', category: 'regional', targetOnly: true },
   { code: 'zh-hant', name: 'Chinese (Traditional)', category: 'regional', targetOnly: true },
 
diff --git a/tests/integration/deepl-client.integration.test.ts b/tests/integration/deepl-client.integration.test.ts
index 3dea8691..e4ee5495 100644
--- a/tests/integration/deepl-client.integration.test.ts
+++ b/tests/integration/deepl-client.integration.test.ts
@@ -517,15 +517,37 @@ describe('DeepLClient Integration', () => {
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
-          { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
+          {
+            lang: 'es',
+            name: 'Spanish',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { formality: { status: 'stable' } },
+          },
+          {
+            lang: 'fr',
+            name: 'French',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { formality: { status: 'stable' } },
+          },
         ]);
 
       const result = await client.getSupportedLanguages('target');
 
       expect(result).toEqual([
-        { language: 'es', name: 'Spanish', supportsFormality: true },
-        { language: 'fr', name: 'French', supportsFormality: true },
+        {
+          language: 'es',
+          name: 'Spanish',
+          supportsFormality: true,
+          features: { formality: { status: 'stable' } },
+        },
+        {
+          language: 'fr',
+          name: 'French',
+          supportsFormality: true,
+          features: { formality: { status: 'stable' } },
+        },
       ]);
       expect(scope.isDone()).toBe(true);
     });
@@ -544,7 +566,7 @@ describe('DeepLClient Integration', () => {
       expect(result[0]?.language).toBe('en-us');
     });
 
-    it('should source formality support from the registry for targets', async () => {
+    it('should source formality support from the features matrix for targets', async () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
@@ -552,8 +574,20 @@ describe('DeepLClient Integration', () => {
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
-          { lang: 'en-us', name: 'English (American)', usable_as_source: false, usable_as_target: true },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { formality: { status: 'stable' }, glossary: { status: 'stable' } },
+          },
+          {
+            lang: 'en-us',
+            name: 'English (American)',
+            usable_as_source: false,
+            usable_as_target: true,
+            features: { glossary: { status: 'stable' } },
+          },
         ]);
 
       const result = await client.getSupportedLanguages('target');
diff --git a/tests/unit/deepl-client.test.ts b/tests/unit/deepl-client.test.ts
index 9ffbbeb7..044a0fb5 100644
--- a/tests/unit/deepl-client.test.ts
+++ b/tests/unit/deepl-client.test.ts
@@ -822,14 +822,32 @@ describe('DeepLClient', () => {
       expect(languages[0]?.language).toBe('de');
     });
 
-    it('should mark formality support on targets from the registry', async () => {
+    it('should mark formality support on targets from the features matrix', async () => {
       nock(baseUrl)
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
-          { lang: 'ja', name: 'Japanese', usable_as_source: true, usable_as_target: true },
-          { lang: 'ko', name: 'Korean', usable_as_source: true, usable_as_target: true },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { formality: { status: 'stable' } },
+          },
+          {
+            lang: 'ja',
+            name: 'Japanese',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { formality: { status: 'stable' } },
+          },
+          {
+            lang: 'ko',
+            name: 'Korean',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { glossary: { status: 'stable' } },
+          },
         ]);
 
       const languages = await client.getSupportedLanguages('target');
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index 3926add9..b7065dc7 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -66,13 +66,13 @@ describe('Language Registry', () => {
   describe('specific language entries', () => {
     it('should include known core languages', () => {
       expect(LANGUAGE_REGISTRY.get('en')).toEqual({ code: 'en', name: 'English', category: 'core' });
-      expect(LANGUAGE_REGISTRY.get('de')).toEqual({ code: 'de', name: 'German', category: 'core', supportsFormality: true });
-      expect(LANGUAGE_REGISTRY.get('ja')).toEqual({ code: 'ja', name: 'Japanese', category: 'core', supportsFormality: true });
+      expect(LANGUAGE_REGISTRY.get('de')).toEqual({ code: 'de', name: 'German', category: 'core' });
+      expect(LANGUAGE_REGISTRY.get('ja')).toEqual({ code: 'ja', name: 'Japanese', category: 'core' });
     });
 
     it('should include known regional variants', () => {
       expect(LANGUAGE_REGISTRY.get('en-gb')).toEqual({ code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true });
-      expect(LANGUAGE_REGISTRY.get('pt-br')).toEqual({ code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true, supportsFormality: true });
+      expect(LANGUAGE_REGISTRY.get('pt-br')).toEqual({ code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true });
     });
 
     it('should include known extended languages', () => {
@@ -218,22 +218,10 @@ describe('Language Registry', () => {
     });
   });
 
-  describe('supportsFormality', () => {
-    it('should mark the formality-capable languages', () => {
-      for (const code of ['de', 'es', 'es-419', 'fr', 'it', 'ja', 'nl', 'pl', 'pt-br', 'pt-pt', 'ru']) {
-        expect(LANGUAGE_REGISTRY.get(code)?.supportsFormality).toBe(true);
-      }
-    });
-
-    it('should leave non-formality languages unmarked', () => {
-      for (const code of ['en', 'en-us', 'ko', 'zh', 'ar', 'ace']) {
-        expect(LANGUAGE_REGISTRY.get(code)?.supportsFormality).toBeUndefined();
-      }
-    });
-
-    it('should never mark an extended language', () => {
-      getExtendedLanguageCodes().forEach(code => {
-        expect(LANGUAGE_REGISTRY.get(code)?.supportsFormality).toBeUndefined();
+  describe('formality support', () => {
+    it('should not carry formality data; GET /v3/languages reports it as features.formality', () => {
+      LANGUAGE_REGISTRY.forEach(entry => {
+        expect(entry).not.toHaveProperty('supportsFormality');
       });
     });
   });
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index 083f2a47..dd2d5334 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -424,10 +424,23 @@ describe('TranslationClient', () => {
       );
     });
 
-    it('should return target languages with registry-sourced formality', async () => {
+    it('should derive target formality from the features matrix', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [
-          { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
+          {
+            lang: 'es',
+            name: 'Spanish',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { formality: { status: 'stable' }, glossary: { status: 'stable' } },
+          },
+          {
+            lang: 'ko',
+            name: 'Korean',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { glossary: { status: 'stable' } },
+          },
         ],
         status: 200,
         headers: {},
@@ -435,9 +448,63 @@ describe('TranslationClient', () => {
 
       const result = await client.getSupportedLanguages('target');
 
-      expect(result).toHaveLength(1);
-      expect(result[0]!.language).toBe('es');
       expect(result[0]!.supportsFormality).toBe(true);
+      expect(result[1]!.supportsFormality).toBe(false);
+    });
+
+    it('should report formality for a language the static registry never flagged', async () => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: [
+          {
+            lang: 'pt',
+            name: 'Portuguese',
+            usable_as_source: true,
+            usable_as_target: true,
+            features: { formality: { status: 'stable' } },
+          },
+        ],
+        status: 200,
+        headers: {},
+      });
+
+      const result = await client.getSupportedLanguages('target');
+
+      expect(result[0]!.supportsFormality).toBe(true);
+    });
+
+    it('should pass the features matrix through for both roles', async () => {
+      const features = {
+        glossary: { status: 'stable' },
+        style_rules: { status: 'beta' },
+      };
+      mockAxiosInstance.request.mockResolvedValue({
+        data: [
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true, features },
+        ],
+        status: 200,
+        headers: {},
+      });
+
+      const source = await client.getSupportedLanguages('source');
+      const target = await client.getSupportedLanguages('target');
+
+      expect(source[0]!.features).toEqual(features);
+      expect(target[0]!.features).toEqual(features);
+    });
+
+    it('should omit features when the response carries none', async () => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: [
+          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+        ],
+        status: 200,
+        headers: {},
+      });
+
+      const result = await client.getSupportedLanguages('target');
+
+      expect(result[0]).not.toHaveProperty('features');
+      expect(result[0]!.supportsFormality).toBe(false);
     });
   });
 

From f6507b304a35bc81e30092836b0cce5ad3bc80c2 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 11:09:43 -0400
Subject: [PATCH 016/256] feat(languages): add --features to show per-language
 feature support

`deepl languages --features` surfaces the features matrix from
GET /v3/languages, so glossary, style-rules and translation-memory support
no longer has to be discovered by trial and error.

Which columns appear is derived from the response rather than a fixed list: a
feature gets a column when its value differs across the listed languages, and
is otherwise reported once as "All listed languages also support: ...". A
uniform column discriminates nothing, and deriving this from the data means a
newly reported feature appears without a code change. In practice tag_handling
suppresses in both listings and auto_detection only in the source listing,
where every language has it.

Support is key presence; `status` is maturity, so anything other than stable
renders verbatim (`glossary (beta)`) instead of collapsing to yes. --features
subsumes the [F] shorthand, so the marker and its legend are dropped when the
matrix is shown.

Default output is unchanged: text and table rendering are untouched without
the flag, and the matrix is stripped from --format json unless asked for.
Table output gains a seam (formatDisplayEntriesTable) matching the text path
so rendering can be tested without the registry merge.
---
 src/api/deepl-client.ts                |   4 +-
 src/cli/commands/languages.ts          | 215 ++++++++++++++++++++++---
 src/cli/commands/register-languages.ts |  44 +++--
 tests/unit/languages-command.test.ts   | 213 +++++++++++++++++++++++-
 tests/unit/register-languages.test.ts  | 123 +++++++++++++-
 5 files changed, 559 insertions(+), 40 deletions(-)

diff --git a/src/api/deepl-client.ts b/src/api/deepl-client.ts
index 90a3f784..31e77166 100644
--- a/src/api/deepl-client.ts
+++ b/src/api/deepl-client.ts
@@ -1,5 +1,5 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
-import { TranslationClient, TranslationResult, isTranslationResult, ProductUsage, UsageInfo, LanguageInfo } from './translation-client.js';
+import { TranslationClient, TranslationResult, isTranslationResult, ProductUsage, UsageInfo, LanguageInfo, LanguageFeature, LanguageFeatures } from './translation-client.js';
 import { GlossaryClient } from './glossary-client.js';
 import { DocumentClient } from './document-client.js';
 import { WriteClient } from './write-client.js';
@@ -31,7 +31,7 @@ import {
   AdminUsageReport,
 } from '../types/index.js';
 
-export { TranslationResult, isTranslationResult, ProductUsage, UsageInfo, LanguageInfo };
+export { TranslationResult, isTranslationResult, ProductUsage, UsageInfo, LanguageInfo, LanguageFeature, LanguageFeatures };
 
 export class DeepLClient {
   private readonly apiKey: string;
diff --git a/src/cli/commands/languages.ts b/src/cli/commands/languages.ts
index 7079fc02..48120dc8 100644
--- a/src/cli/commands/languages.ts
+++ b/src/cli/commands/languages.ts
@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import Table from 'cli-table3';
 import type { LanguagesService } from '../../services/languages.js';
-import { LanguageInfo } from '../../api/deepl-client.js';
+import { LanguageInfo, type LanguageFeatures } from '../../api/deepl-client.js';
 import {
   getSourceLanguages as getRegistrySourceLanguages,
   getTargetLanguages as getRegistryTargetLanguages,
@@ -13,6 +13,122 @@ export interface LanguageDisplayEntry {
   name: string;
   category: 'core' | 'regional' | 'extended';
   supportsFormality?: boolean;
+  features?: LanguageFeatures;
+}
+
+/** Display order for the feature keys /v3/languages is known to report. */
+const KNOWN_FEATURE_ORDER = [
+  'formality',
+  'glossary',
+  'style_rules',
+  'translation_memory',
+  'tag_handling',
+  'auto_detection',
+];
+
+const FEATURE_LABELS: Record<string, string> = {
+  formality: 'Formality',
+  glossary: 'Glossary',
+  style_rules: 'Style Rules',
+  translation_memory: 'Translation Memory',
+  tag_handling: 'Tag Handling',
+  auto_detection: 'Auto Detection',
+};
+
+function featureLabel(key: string): string {
+  return (
+    FEATURE_LABELS[key] ??
+    key
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ')
+  );
+}
+
+/**
+ * Cell text for one feature on one language. A feature is supported when the
+ * API reports the key at all; `status` describes maturity, so anything other
+ * than `stable` is shown verbatim rather than collapsed to yes.
+ */
+function featureCell(entry: LanguageDisplayEntry, key: string): string {
+  const feature = entry.features?.[key];
+  if (!feature) return '—';
+  return feature.status === 'stable' ? 'yes' : feature.status;
+}
+
+function sortFeatureKeys(keys: string[]): string[] {
+  return [...keys].sort((a, b) => {
+    const indexA = KNOWN_FEATURE_ORDER.indexOf(a);
+    const indexB = KNOWN_FEATURE_ORDER.indexOf(b);
+    if (indexA !== -1 && indexB !== -1) return indexA - indexB;
+    if (indexA !== -1) return -1;
+    if (indexB !== -1) return 1;
+    return a.localeCompare(b);
+  });
+}
+
+/**
+ * Splits the reported features into those worth a column and those every entry
+ * shares. A uniform feature discriminates nothing, so it is reported once as a
+ * note instead of repeated on every row. Deriving this from the response rather
+ * than a fixed list means a new API feature surfaces without a code change.
+ */
+export function partitionFeatureKeys(entries: LanguageDisplayEntry[]): {
+  columns: string[];
+  uniform: Array<{ key: string; cell: string }>;
+} {
+  if (entries.length === 0) return { columns: [], uniform: [] };
+
+  const allKeys = new Set<string>();
+  for (const entry of entries) {
+    for (const key of Object.keys(entry.features ?? {})) allKeys.add(key);
+  }
+
+  const columns: string[] = [];
+  const uniform: Array<{ key: string; cell: string }> = [];
+  for (const key of allKeys) {
+    const first = featureCell(entries[0]!, key);
+    if (entries.some(entry => featureCell(entry, key) !== first)) {
+      columns.push(key);
+    } else {
+      uniform.push({ key, cell: first });
+    }
+  }
+
+  return {
+    columns: sortFeatureKeys(columns),
+    uniform: sortFeatureKeys(uniform.map(u => u.key)).map(
+      key => uniform.find(u => u.key === key)!,
+    ),
+  };
+}
+
+function hasAnyFeatures(entries: LanguageDisplayEntry[]): boolean {
+  return entries.some(entry => Object.keys(entry.features ?? {}).length > 0);
+}
+
+/** Lowercased feature list for prose contexts, e.g. `glossary, style rules`. */
+function featureList(entry: LanguageDisplayEntry, keys: string[]): string {
+  const supported = keys
+    .filter(key => featureCell(entry, key) !== '—')
+    .map(key => {
+      const cell = featureCell(entry, key);
+      const label = featureLabel(key).toLowerCase();
+      return cell === 'yes' ? label : `${label} (${cell})`;
+    });
+  return supported.length > 0 ? supported.join(', ') : 'none';
+}
+
+function uniformNote(uniform: Array<{ key: string; cell: string }>): string | undefined {
+  const supported = uniform.filter(u => u.cell !== '—');
+  if (supported.length === 0) return undefined;
+  const list = supported
+    .map(u => {
+      const label = featureLabel(u.key).toLowerCase();
+      return u.cell === 'yes' ? label : `${label} (${u.cell})`;
+    })
+    .join(', ');
+  return `All listed languages also support: ${list}.`;
 }
 
 export class LanguagesCommand {
@@ -53,6 +169,7 @@ export class LanguagesCommand {
         name: apiLang?.name ?? entry.name,
         category: entry.category,
         ...(apiLang?.supportsFormality !== undefined && { supportsFormality: apiLang.supportsFormality }),
+        ...(apiLang?.features && { features: apiLang.features }),
       };
     });
   }
@@ -72,20 +189,31 @@ export class LanguagesCommand {
     }));
   }
 
-  formatLanguages(languages: LanguageInfo[], type: 'source' | 'target'): string {
+  formatLanguages(
+    languages: LanguageInfo[],
+    type: 'source' | 'target',
+    showFeatures = false
+  ): string {
     if (languages.length === 0 && !this.service.hasClient()) {
       const displayEntries = this.getRegistryLanguages(type);
-      return this.formatDisplayEntries(displayEntries, type);
+      return this.formatDisplayEntries(displayEntries, type, showFeatures);
     }
 
     const displayEntries = this.mergeWithRegistry(languages, type);
-    return this.formatDisplayEntries(displayEntries, type);
+    return this.formatDisplayEntries(displayEntries, type, showFeatures);
   }
 
-  formatDisplayEntries(entries: LanguageDisplayEntry[], type: 'source' | 'target'): string {
+  formatDisplayEntries(
+    entries: LanguageDisplayEntry[],
+    type: 'source' | 'target',
+    showFeatures = false
+  ): string {
     const lines: string[] = [];
     const header = type === 'source' ? 'Source Languages:' : 'Target Languages:';
-    const showFormality = type === 'target' && entries.some(e => e.supportsFormality !== undefined);
+    const renderFeatures = showFeatures && hasAnyFeatures(entries);
+    // Formality is one of the feature columns, so the [F] shorthand would say it twice.
+    const showFormality =
+      !renderFeatures && type === 'target' && entries.some(e => e.supportsFormality !== undefined);
 
     lines.push(chalk.bold(header));
 
@@ -99,11 +227,16 @@ export class LanguagesCommand {
 
     const allEntries = [...coreAndRegional, ...extended];
     const maxCodeLength = Math.max(...allEntries.map(e => e.code.length));
+    const { columns, uniform } = renderFeatures
+      ? partitionFeatureKeys(entries)
+      : { columns: [], uniform: [] };
+    const suffix = (entry: LanguageDisplayEntry): string =>
+      renderFeatures ? chalk.gray(` — ${featureList(entry, columns)}`) : '';
 
     coreAndRegional.forEach(entry => {
       const code = entry.code.padEnd(maxCodeLength + 2);
       const formalityMarker = showFormality && entry.supportsFormality ? chalk.green(' [F]') : '';
-      lines.push(`  ${chalk.cyan(code)} ${entry.name}${formalityMarker}`);
+      lines.push(`  ${chalk.cyan(code)} ${entry.name}${formalityMarker}${suffix(entry)}`);
     });
 
     if (extended.length > 0) {
@@ -111,7 +244,7 @@ export class LanguagesCommand {
       lines.push(chalk.gray('  Extended Languages (quality_optimized only, no formality/glossary):'));
       extended.forEach(entry => {
         const code = entry.code.padEnd(maxCodeLength + 2);
-        lines.push(`  ${chalk.gray(code)} ${chalk.gray(entry.name)}`);
+        lines.push(`  ${chalk.gray(code)} ${chalk.gray(entry.name)}${suffix(entry)}`);
       });
     }
 
@@ -120,32 +253,66 @@ export class LanguagesCommand {
       lines.push(chalk.gray('  [F] = supports formality parameter'));
     }
 
+    const note = renderFeatures ? uniformNote(uniform) : undefined;
+    if (note) {
+      lines.push('');
+      lines.push(chalk.gray(`  ${note}`));
+    }
+
     return lines.join('\n');
   }
 
-  formatAllLanguages(sourceLanguages: LanguageInfo[], targetLanguages: LanguageInfo[]): string {
-    const sourcePart = this.formatLanguages(sourceLanguages, 'source');
-    const targetPart = this.formatLanguages(targetLanguages, 'target');
+  formatAllLanguages(
+    sourceLanguages: LanguageInfo[],
+    targetLanguages: LanguageInfo[],
+    showFeatures = false
+  ): string {
+    const sourcePart = this.formatLanguages(sourceLanguages, 'source', showFeatures);
+    const targetPart = this.formatLanguages(targetLanguages, 'target', showFeatures);
 
     return `${sourcePart}\n\n${targetPart}`;
   }
 
   /** Format a single language list (source or target) as a cli-table3 table. */
-  formatLanguagesTable(languages: LanguageInfo[], type: 'source' | 'target'): string {
+  formatLanguagesTable(
+    languages: LanguageInfo[],
+    type: 'source' | 'target',
+    showFeatures = false
+  ): string {
     const entries = languages.length === 0 && !this.service.hasClient()
       ? this.getRegistryLanguages(type)
       : this.mergeWithRegistry(languages, type);
 
+    return this.formatDisplayEntriesTable(entries, type, showFeatures);
+  }
+
+  formatDisplayEntriesTable(
+    entries: LanguageDisplayEntry[],
+    type: 'source' | 'target',
+    showFeatures = false
+  ): string {
     const header = type === 'source' ? 'Source Languages' : 'Target Languages';
     if (entries.length === 0) {
       return `${header}: (no languages available)`;
     }
 
-    const showFormality = type === 'target' && entries.some(e => e.supportsFormality !== undefined);
-    const head = showFormality
-      ? ['Code', 'Name', 'Category', 'Formality']
-      : ['Code', 'Name', 'Category'];
-    const colWidths = showFormality ? [10, 30, 12, 13] : [10, 36, 12];
+    const renderFeatures = showFeatures && hasAnyFeatures(entries);
+    const { columns, uniform } = renderFeatures
+      ? partitionFeatureKeys(entries)
+      : { columns: [], uniform: [] };
+    const showFormality =
+      !renderFeatures && type === 'target' && entries.some(e => e.supportsFormality !== undefined);
+
+    const head = ['Code', 'Name', 'Category'];
+    const colWidths = [10, renderFeatures ? 24 : showFormality ? 30 : 36, 12];
+    if (showFormality) {
+      head.push('Formality');
+      colWidths.push(13);
+    }
+    for (const key of columns) {
+      head.push(featureLabel(key));
+      colWidths.push(13);
+    }
     const colorDisabled = !isColorEnabled();
 
     const table = new Table({
@@ -160,14 +327,22 @@ export class LanguagesCommand {
       if (showFormality) {
         row.push(entry.supportsFormality ? 'yes' : '—');
       }
+      for (const key of columns) {
+        row.push(featureCell(entry, key));
+      }
       table.push(row);
     }
 
-    return `${header}:\n${table.toString()}`;
+    const note = renderFeatures ? uniformNote(uniform) : undefined;
+    return `${header}:\n${table.toString()}${note ? `\n${note}` : ''}`;
   }
 
   /** Format both source and target language tables joined by a blank line. */
-  formatAllLanguagesTable(sourceLanguages: LanguageInfo[], targetLanguages: LanguageInfo[]): string {
-    return `${this.formatLanguagesTable(sourceLanguages, 'source')}\n\n${this.formatLanguagesTable(targetLanguages, 'target')}`;
+  formatAllLanguagesTable(
+    sourceLanguages: LanguageInfo[],
+    targetLanguages: LanguageInfo[],
+    showFeatures = false
+  ): string {
+    return `${this.formatLanguagesTable(sourceLanguages, 'source', showFeatures)}\n\n${this.formatLanguagesTable(targetLanguages, 'target', showFeatures)}`;
   }
 }
diff --git a/src/cli/commands/register-languages.ts b/src/cli/commands/register-languages.ts
index b7db4566..87c171fb 100644
--- a/src/cli/commands/register-languages.ts
+++ b/src/cli/commands/register-languages.ts
@@ -1,9 +1,23 @@
 import { Option, type Command } from 'commander';
 import chalk from 'chalk';
 import type { ConfigService } from '../../storage/config.js';
+import type { LanguageInfo } from '../../api/deepl-client.js';
 import { Logger } from '../../utils/logger.js';
 import { createLanguagesCommand, type CreateDeepLClient } from './service-factory.js';
 
+/**
+ * The features matrix rides along on every LanguageInfo, so it is stripped from
+ * JSON unless asked for; existing consumers keep the shape they were written to.
+ */
+function forJson(languages: LanguageInfo[], includeFeatures: boolean): unknown[] {
+  if (includeFeatures) return languages;
+  return languages.map(language => {
+    const copy = { ...language };
+    delete copy.features;
+    return copy;
+  });
+}
+
 export function registerLanguages(
   program: Command,
   deps: {
@@ -19,20 +33,24 @@ export function registerLanguages(
     .description('List supported source and target languages')
     .option('-s, --source', 'Show only source languages')
     .option('--target', 'Show only target languages')
+    .option('--features', 'Show per-language feature support (requires an API key)')
     .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json', 'table']).default('text'))
     .addHelpText('after', `
 Examples:
   $ deepl languages
   $ deepl languages --source
   $ deepl languages --target
+  $ deepl languages --features
+  $ deepl languages --target --features --format table
   $ deepl languages --format json
   $ deepl languages --format table
 `)
-    .action(async (options: { source?: boolean; target?: boolean; format?: string }) => {
+    .action(async (options: { source?: boolean; target?: boolean; features?: boolean; format?: string }) => {
       try {
         const apiKey = getConfigService().getValue<string>('auth.apiKey');
         const envKey = process.env['DEEPL_API_KEY'];
         const hasApiKey = !!(apiKey ?? envKey);
+        const showFeatures = !!options.features;
 
         let client = null;
         if (hasApiKey) {
@@ -40,6 +58,9 @@ Examples:
         } else {
           Logger.warn(chalk.yellow('Note: No API key configured. Showing local language registry only.'));
           Logger.warn(chalk.yellow('Run: deepl auth set-key <your-api-key> for API-verified names.\n'));
+          if (showFeatures) {
+            Logger.warn(chalk.yellow('Note: --features needs an API key; the local registry carries no feature data.\n'));
+          }
         }
 
         const languagesCommand = await createLanguagesCommand(client);
@@ -47,16 +68,19 @@ Examples:
         if (options.format === 'json') {
           if (options.source && !options.target) {
             const sourceLanguages = await languagesCommand.getSourceLanguages();
-            Logger.output(JSON.stringify(sourceLanguages, null, 2));
+            Logger.output(JSON.stringify(forJson(sourceLanguages, showFeatures), null, 2));
           } else if (options.target && !options.source) {
             const targetLanguages = await languagesCommand.getTargetLanguages();
-            Logger.output(JSON.stringify(targetLanguages, null, 2));
+            Logger.output(JSON.stringify(forJson(targetLanguages, showFeatures), null, 2));
           } else {
             const [sourceLanguages, targetLanguages] = await Promise.all([
               languagesCommand.getSourceLanguages(),
               languagesCommand.getTargetLanguages(),
             ]);
-            Logger.output(JSON.stringify({ source: sourceLanguages, target: targetLanguages }, null, 2));
+            Logger.output(JSON.stringify({
+              source: forJson(sourceLanguages, showFeatures),
+              target: forJson(targetLanguages, showFeatures),
+            }, null, 2));
           }
           return;
         }
@@ -71,21 +95,21 @@ Examples:
         if (options.source && !options.target) {
           const sourceLanguages = await languagesCommand.getSourceLanguages();
           output = wantTable
-            ? languagesCommand.formatLanguagesTable(sourceLanguages, 'source')
-            : languagesCommand.formatLanguages(sourceLanguages, 'source');
+            ? languagesCommand.formatLanguagesTable(sourceLanguages, 'source', showFeatures)
+            : languagesCommand.formatLanguages(sourceLanguages, 'source', showFeatures);
         } else if (options.target && !options.source) {
           const targetLanguages = await languagesCommand.getTargetLanguages();
           output = wantTable
-            ? languagesCommand.formatLanguagesTable(targetLanguages, 'target')
-            : languagesCommand.formatLanguages(targetLanguages, 'target');
+            ? languagesCommand.formatLanguagesTable(targetLanguages, 'target', showFeatures)
+            : languagesCommand.formatLanguages(targetLanguages, 'target', showFeatures);
         } else {
           const [sourceLanguages, targetLanguages] = await Promise.all([
             languagesCommand.getSourceLanguages(),
             languagesCommand.getTargetLanguages(),
           ]);
           output = wantTable
-            ? languagesCommand.formatAllLanguagesTable(sourceLanguages, targetLanguages)
-            : languagesCommand.formatAllLanguages(sourceLanguages, targetLanguages);
+            ? languagesCommand.formatAllLanguagesTable(sourceLanguages, targetLanguages, showFeatures)
+            : languagesCommand.formatAllLanguages(sourceLanguages, targetLanguages, showFeatures);
         }
 
         Logger.output(output);
diff --git a/tests/unit/languages-command.test.ts b/tests/unit/languages-command.test.ts
index 112df5d8..26c9003b 100644
--- a/tests/unit/languages-command.test.ts
+++ b/tests/unit/languages-command.test.ts
@@ -1,4 +1,8 @@
-import { LanguagesCommand } from '../../src/cli/commands/languages';
+import {
+  LanguagesCommand,
+  partitionFeatureKeys,
+  type LanguageDisplayEntry,
+} from '../../src/cli/commands/languages';
 import { LanguageInfo } from '../../src/api/deepl-client';
 import { createMockLanguagesService } from '../helpers/mock-factories';
 
@@ -403,4 +407,211 @@ describe('LanguagesCommand', () => {
       expect(result.split('\n\n').length).toBeGreaterThanOrEqual(2);
     });
   });
+
+  describe('partitionFeatureKeys()', () => {
+    const entry = (
+      code: string,
+      features?: Record<string, { status: string }>,
+    ): LanguageDisplayEntry => ({
+      code,
+      name: code.toUpperCase(),
+      category: 'core',
+      ...(features && { features }),
+    });
+
+    it('should keep a feature that discriminates between entries', () => {
+      const { columns } = partitionFeatureKeys([
+        entry('de', { glossary: { status: 'stable' } }),
+        entry('hi', {}),
+      ]);
+
+      expect(columns).toEqual(['glossary']);
+    });
+
+    it('should suppress a feature supported identically by every entry', () => {
+      const { columns, uniform } = partitionFeatureKeys([
+        entry('de', { tag_handling: { status: 'stable' } }),
+        entry('hi', { tag_handling: { status: 'stable' } }),
+      ]);
+
+      expect(columns).toEqual([]);
+      expect(uniform).toEqual([{ key: 'tag_handling', cell: 'yes' }]);
+    });
+
+    it('should order known features first and unknown features alphabetically after', () => {
+      const all = {
+        zebra_feature: { status: 'stable' },
+        translation_memory: { status: 'stable' },
+        alpha_feature: { status: 'stable' },
+        formality: { status: 'stable' },
+        glossary: { status: 'stable' },
+      };
+      const { columns } = partitionFeatureKeys([entry('de', all), entry('hi', {})]);
+
+      expect(columns).toEqual([
+        'formality',
+        'glossary',
+        'translation_memory',
+        'alpha_feature',
+        'zebra_feature',
+      ]);
+    });
+
+    it('should treat a differing status as discriminating', () => {
+      const { columns } = partitionFeatureKeys([
+        entry('de', { glossary: { status: 'stable' } }),
+        entry('th', { glossary: { status: 'beta' } }),
+      ]);
+
+      expect(columns).toEqual(['glossary']);
+    });
+
+    it('should return nothing for an empty entry list', () => {
+      expect(partitionFeatureKeys([])).toEqual({ columns: [], uniform: [] });
+    });
+  });
+
+  describe('feature display', () => {
+    // Asserted through the display-entry layer: formatLanguages() merges against
+    // the whole registry, so languages absent from the argument would report no
+    // features and make every column discriminating.
+    const displayEntries: LanguageDisplayEntry[] = [
+      {
+        code: 'de',
+        name: 'German',
+        category: 'core',
+        supportsFormality: true,
+        features: {
+          formality: { status: 'stable' },
+          glossary: { status: 'stable' },
+          style_rules: { status: 'stable' },
+          tag_handling: { status: 'stable' },
+        },
+      },
+      {
+        code: 'pt',
+        name: 'Portuguese',
+        category: 'core',
+        supportsFormality: true,
+        features: {
+          formality: { status: 'stable' },
+          glossary: { status: 'stable' },
+          tag_handling: { status: 'stable' },
+        },
+      },
+      {
+        code: 'hi',
+        name: 'Hindi',
+        category: 'extended',
+        supportsFormality: false,
+        features: { tag_handling: { status: 'stable' } },
+      },
+    ];
+
+    it('should list supported features per language in text output', () => {
+      const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
+      const de = formatted.split('\n').find(l => l.includes('German'));
+      const pt = formatted.split('\n').find(l => l.includes('Portuguese'));
+
+      expect(de).toContain('formality');
+      expect(de).toContain('style rules');
+      expect(pt).toContain('glossary');
+      expect(pt).not.toContain('style rules');
+    });
+
+    it('should note the features every listed language shares', () => {
+      const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
+
+      expect(formatted).toContain('All listed languages also support: tag handling.');
+    });
+
+    it('should mark a language with no supported features', () => {
+      const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
+      const hi = formatted.split('\n').find(l => l.includes('Hindi'));
+
+      expect(hi).toContain('none');
+    });
+
+    it('should render features for extended languages too', () => {
+      const entries: LanguageDisplayEntry[] = [
+        { code: 'de', name: 'German', category: 'core', features: {} },
+        {
+          code: 'th',
+          name: 'Thai',
+          category: 'extended',
+          features: { style_rules: { status: 'stable' } },
+        },
+      ];
+      const formatted = languagesCommand.formatDisplayEntries(entries, 'target', true);
+      const th = formatted.split('\n').find(l => l.includes('Thai'));
+
+      expect(th).toContain('style rules');
+    });
+
+    it('should drop the [F] marker and legend when features are shown', () => {
+      const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
+
+      expect(formatted).not.toContain('[F]');
+    });
+
+    it('should label a non-stable status instead of yes', () => {
+      const entries: LanguageDisplayEntry[] = [
+        { code: 'de', name: 'German', category: 'core', features: { glossary: { status: 'beta' } } },
+        { code: 'hi', name: 'Hindi', category: 'extended', features: {} },
+      ];
+      const formatted = languagesCommand.formatDisplayEntries(entries, 'target', true);
+      const de = formatted.split('\n').find(l => l.includes('German'));
+
+      expect(de).toContain('glossary (beta)');
+    });
+
+    it('should fall back to the default rendering when no entry reports features', () => {
+      const noFeatures: LanguageDisplayEntry[] = [
+        { code: 'de', name: 'German', category: 'core', supportsFormality: true },
+      ];
+      const withFlag = languagesCommand.formatDisplayEntries(noFeatures, 'target', true);
+      const without = languagesCommand.formatDisplayEntries(noFeatures, 'target');
+
+      expect(withFlag).toBe(without);
+    });
+
+    it('should leave default text output untouched when features are not requested', () => {
+      const withFlagOff = languagesCommand.formatDisplayEntries(displayEntries, 'target');
+
+      expect(withFlagOff).toContain('[F]');
+      expect(withFlagOff).not.toContain('tag handling');
+    });
+
+    it('should thread the flag through formatLanguages to the display layer', () => {
+      const apiLangs: LanguageInfo[] = [
+        {
+          language: 'de',
+          name: 'German',
+          supportsFormality: true,
+          features: { glossary: { status: 'stable' } },
+        },
+      ];
+      const formatted = languagesCommand.formatLanguages(apiLangs, 'target', true);
+      const de = formatted.split('\n').find(l => l.includes('German'));
+
+      expect(de).toContain('glossary');
+    });
+
+    it('should add a column per discriminating feature in table output', () => {
+      const table = languagesCommand.formatDisplayEntriesTable(displayEntries, 'target', true);
+
+      expect(table).toContain('Formality');
+      expect(table).toContain('Glossary');
+      expect(table).toContain('Style Rules');
+      expect(table).not.toContain('Tag Handling');
+      expect(table).toContain('All listed languages also support: tag handling.');
+    });
+
+    it('should not add feature columns to table output by default', () => {
+      const table = languagesCommand.formatDisplayEntriesTable(displayEntries, 'target');
+
+      expect(table).not.toContain('Glossary');
+      expect(table).toContain('Formality');
+    });
+  });
 });
diff --git a/tests/unit/register-languages.test.ts b/tests/unit/register-languages.test.ts
index 18c67b58..c8f20e5b 100644
--- a/tests/unit/register-languages.test.ts
+++ b/tests/unit/register-languages.test.ts
@@ -91,7 +91,7 @@ describe('registerLanguages', () => {
       mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('all languages');
       await program.parseAsync(['node', 'test', 'languages']);
       expect(createDeepLClient).toHaveBeenCalled();
-      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets);
+      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets, false);
       expect(Logger.output).toHaveBeenCalledWith('all languages');
     });
 
@@ -100,7 +100,7 @@ describe('registerLanguages', () => {
       mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
       mockLanguagesCommandInstance.formatLanguages.mockReturnValue('source list');
       await program.parseAsync(['node', 'test', 'languages', '--source']);
-      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(sources, 'source');
+      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(sources, 'source', false);
       expect(Logger.output).toHaveBeenCalledWith('source list');
     });
 
@@ -109,7 +109,7 @@ describe('registerLanguages', () => {
       mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
       mockLanguagesCommandInstance.formatLanguages.mockReturnValue('target list');
       await program.parseAsync(['node', 'test', 'languages', '--target']);
-      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(targets, 'target');
+      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(targets, 'target', false);
       expect(Logger.output).toHaveBeenCalledWith('target list');
     });
 
@@ -120,7 +120,7 @@ describe('registerLanguages', () => {
       mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
       mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('all');
       await program.parseAsync(['node', 'test', 'languages', '--source', '--target']);
-      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets);
+      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets, false);
     });
 
     it('should output JSON for source languages with --format json --source', async () => {
@@ -158,7 +158,7 @@ describe('registerLanguages', () => {
         await program.parseAsync(['node', 'test', 'languages', '--format', 'table']);
       });
 
-      expect(mockLanguagesCommandInstance.formatAllLanguagesTable).toHaveBeenCalledWith(sources, targets);
+      expect(mockLanguagesCommandInstance.formatAllLanguagesTable).toHaveBeenCalledWith(sources, targets, false);
       expect(mockLanguagesCommandInstance.formatAllLanguages).not.toHaveBeenCalled();
       expect(Logger.output).toHaveBeenCalledWith('all-languages-table');
       expect(Logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
@@ -173,7 +173,7 @@ describe('registerLanguages', () => {
         await program.parseAsync(['node', 'test', 'languages', '--source', '--format', 'table']);
       });
 
-      expect(mockLanguagesCommandInstance.formatLanguagesTable).toHaveBeenCalledWith(sources, 'source');
+      expect(mockLanguagesCommandInstance.formatLanguagesTable).toHaveBeenCalledWith(sources, 'source', false);
       expect(mockLanguagesCommandInstance.formatLanguages).not.toHaveBeenCalled();
     });
 
@@ -189,12 +189,101 @@ describe('registerLanguages', () => {
       });
 
       expect(mockLanguagesCommandInstance.formatAllLanguagesTable).not.toHaveBeenCalled();
-      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets);
+      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets, false);
       expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
       expect(Logger.output).toHaveBeenCalledWith('plain text');
     });
   });
 
+  describe('--features', () => {
+    beforeEach(() => {
+      mockGetValue.mockReturnValue('fake-key');
+    });
+
+    it('should request the feature matrix for the combined listing', async () => {
+      const sources = [{ language: 'en', name: 'English' }];
+      const targets = [{ language: 'de', name: 'German' }];
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+      mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('all');
+
+      await program.parseAsync(['node', 'test', 'languages', '--features']);
+
+      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets, true);
+    });
+
+    it('should request the feature matrix for a single-role listing', async () => {
+      const targets = [{ language: 'de', name: 'German' }];
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+      mockLanguagesCommandInstance.formatLanguages.mockReturnValue('target list');
+
+      await program.parseAsync(['node', 'test', 'languages', '--target', '--features']);
+
+      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(targets, 'target', true);
+    });
+
+    it('should request the feature matrix for table output', async () => {
+      const sources = [{ language: 'en', name: 'English' }];
+      const targets = [{ language: 'de', name: 'German' }];
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+
+      await withTTY(true, async () => {
+        await program.parseAsync(['node', 'test', 'languages', '--features', '--format', 'table']);
+      });
+
+      expect(mockLanguagesCommandInstance.formatAllLanguagesTable).toHaveBeenCalledWith(sources, targets, true);
+    });
+
+    it('should include features in JSON output when requested', async () => {
+      const targets = [
+        { language: 'de', name: 'German', features: { glossary: { status: 'stable' } } },
+      ];
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+
+      await program.parseAsync(['node', 'test', 'languages', '--target', '--features', '--format', 'json']);
+
+      expect(Logger.output).toHaveBeenCalledWith(JSON.stringify(targets, null, 2));
+    });
+
+    it('should strip features from JSON output when not requested', async () => {
+      const targets = [
+        { language: 'de', name: 'German', features: { glossary: { status: 'stable' } } },
+      ];
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+
+      await program.parseAsync(['node', 'test', 'languages', '--target', '--format', 'json']);
+
+      expect(Logger.output).toHaveBeenCalledWith(
+        JSON.stringify([{ language: 'de', name: 'German' }], null, 2),
+      );
+    });
+
+    it('should strip features from both roles of the combined JSON output', async () => {
+      const sources = [
+        { language: 'en', name: 'English', features: { glossary: { status: 'stable' } } },
+      ];
+      const targets = [
+        { language: 'de', name: 'German', features: { glossary: { status: 'stable' } } },
+      ];
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+
+      await program.parseAsync(['node', 'test', 'languages', '--format', 'json']);
+
+      expect(Logger.output).toHaveBeenCalledWith(
+        JSON.stringify(
+          {
+            source: [{ language: 'en', name: 'English' }],
+            target: [{ language: 'de', name: 'German' }],
+          },
+          null,
+          2,
+        ),
+      );
+    });
+  });
+
   describe('with API key from environment', () => {
     it('should create client when env key is set', async () => {
       process.env['DEEPL_API_KEY'] = 'env-key';
@@ -216,6 +305,26 @@ describe('registerLanguages', () => {
       expect(createDeepLClient).not.toHaveBeenCalled();
       expect(Logger.output).toHaveBeenCalledWith('local');
     });
+
+    it('should warn that --features needs an API key', async () => {
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue([]);
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue([]);
+      mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('local');
+
+      await program.parseAsync(['node', 'test', 'languages', '--features']);
+
+      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('--features needs an API key'));
+    });
+
+    it('should not mention --features when the flag is absent', async () => {
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue([]);
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue([]);
+      mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('local');
+
+      await program.parseAsync(['node', 'test', 'languages']);
+
+      expect(Logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('--features'));
+    });
   });
 
   describe('error handling', () => {

From ad28fe9e00282d98a4307228ed5cd99fa293d1f9 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 11:13:40 -0400
Subject: [PATCH 017/256] test(languages): cover --features end to end against
 the mock API

The languages e2e suite ran offline only, so nothing exercised the command
against a real /v3/languages response. It now spawns the mock server, whose
fixture gains a features object, and asserts the per-language feature list,
that --features replaces the [F] shorthand, and that the matrix reaches
--format json only when requested.

Column suppression stays a unit-level assertion: the row set is the whole
registry, so languages the mock does not return report no features and
nothing comes out uniform.
---
 tests/e2e/cli-languages.e2e.test.ts | 101 +++++++++++++++++++++++++++-
 tests/e2e/mock-deepl-server.cjs     |  51 ++++++++++++--
 2 files changed, 145 insertions(+), 7 deletions(-)

diff --git a/tests/e2e/cli-languages.e2e.test.ts b/tests/e2e/cli-languages.e2e.test.ts
index 70fcee12..4c2e71b8 100644
--- a/tests/e2e/cli-languages.e2e.test.ts
+++ b/tests/e2e/cli-languages.e2e.test.ts
@@ -6,7 +6,8 @@
  * Full API integration is tested separately in integration tests.
  */
 
-import { spawnSync } from 'child_process';
+import { spawn, spawnSync, ChildProcess } from 'child_process';
+import * as fs from 'fs';
 import * as path from 'path';
 import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
@@ -103,6 +104,104 @@ describe('Languages Command E2E', () => {
     });
   });
 
+  describe('languages --features (against the mock API)', () => {
+    const featuresConfig = createTestConfigDir('e2e-languages-features');
+    let mockServerProcess: ChildProcess | undefined;
+    let featuresRunCLI: (command: string) => string;
+
+    function startMockServer(): Promise<number> {
+      return new Promise((resolve, reject) => {
+        const serverScript = path.join(__dirname, 'mock-deepl-server.cjs');
+        const child = spawn('node', [serverScript], {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: { ...process.env },
+        });
+
+        mockServerProcess = child;
+        let output = '';
+
+        child.stdout.on('data', (data: Buffer) => {
+          output += data.toString();
+          const match = output.match(/PORT=(\d+)/);
+          if (match) {
+            resolve(parseInt(match[1]!, 10));
+          }
+        });
+
+        child.on('error', reject);
+        child.on('exit', code => {
+          if (code !== null && code !== 0) {
+            reject(new Error(`Mock server exited with code ${code}`));
+          }
+        });
+
+        setTimeout(() => reject(new Error('Mock server did not start within 15s')), 15000);
+      });
+    }
+
+    beforeAll(async () => {
+      const port = await startMockServer();
+      const config = {
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+      };
+      fs.writeFileSync(
+        path.join(featuresConfig.path, 'config.json'),
+        JSON.stringify(config, null, 2),
+      );
+      featuresRunCLI = makeNodeRunCLI(featuresConfig.path, { noColor: true, timeout: 15000 }).runCLI;
+    }, 30000);
+
+    afterAll(() => {
+      if (mockServerProcess) {
+        mockServerProcess.kill('SIGTERM');
+      }
+      featuresConfig.cleanup();
+    });
+
+    it('should list the features each language supports', () => {
+      const output = featuresRunCLI('languages --target --features');
+
+      const german = output.split('\n').find(line => line.includes('German'));
+      const english = output.split('\n').find(line => line.includes('English (British)'));
+
+      expect(german).toContain('formality');
+      expect(german).toContain('glossary');
+      expect(english).toContain('glossary');
+      expect(english).not.toContain('formality');
+    });
+
+    // Column suppression is asserted in the unit tests: the row set here is the
+    // whole registry, so the languages this mock does not return report no
+    // features and nothing comes out uniform.
+    it('should drop the [F] shorthand in favour of the matrix', () => {
+      const output = featuresRunCLI('languages --target --features');
+
+      expect(output).not.toContain('[F]');
+    });
+
+    it('should keep the [F] shorthand when features are not requested', () => {
+      const output = featuresRunCLI('languages --target');
+
+      expect(output).toContain('[F]');
+      expect(output).not.toContain('tag handling');
+    });
+
+    it('should include the matrix in JSON only when requested', () => {
+      const withFeatures = JSON.parse(featuresRunCLI('languages --target --features --format json'));
+      const without = JSON.parse(featuresRunCLI('languages --target --format json'));
+
+      expect(withFeatures.find((l: { language: string }) => l.language === 'de').features).toEqual({
+        formality: { status: 'stable' },
+        glossary: { status: 'stable' },
+        tag_handling: { status: 'stable' },
+      });
+      expect(without.find((l: { language: string }) => l.language === 'de')).not.toHaveProperty('features');
+    });
+  });
+
   describe('languages command structure', () => {
     it('should be registered as a command', () => {
       const helpOutput = runCLI('--help');
diff --git a/tests/e2e/mock-deepl-server.cjs b/tests/e2e/mock-deepl-server.cjs
index 5c96f69a..16da1074 100644
--- a/tests/e2e/mock-deepl-server.cjs
+++ b/tests/e2e/mock-deepl-server.cjs
@@ -202,13 +202,52 @@ function handleRequest(req, res, body) {
   }
 
   if (method === 'GET' && url.startsWith('/v3/languages')) {
+    // tag_handling is uniform so it exercises the suppression path; formality
+    // and glossary vary so they stay as columns.
+    var stable = { status: 'stable' };
     var languages = [
-      { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
-      { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
-      { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
-      { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
-      { lang: 'en-us', name: 'English (American)', usable_as_source: false, usable_as_target: true },
-      { lang: 'en-gb', name: 'English (British)', usable_as_source: false, usable_as_target: true },
+      {
+        lang: 'en',
+        name: 'English',
+        usable_as_source: true,
+        usable_as_target: true,
+        features: { glossary: stable, tag_handling: stable },
+      },
+      {
+        lang: 'de',
+        name: 'German',
+        usable_as_source: true,
+        usable_as_target: true,
+        features: { formality: stable, glossary: stable, tag_handling: stable },
+      },
+      {
+        lang: 'fr',
+        name: 'French',
+        usable_as_source: true,
+        usable_as_target: true,
+        features: { formality: stable, glossary: stable, tag_handling: stable },
+      },
+      {
+        lang: 'es',
+        name: 'Spanish',
+        usable_as_source: true,
+        usable_as_target: true,
+        features: { formality: stable, glossary: stable, tag_handling: stable },
+      },
+      {
+        lang: 'en-us',
+        name: 'English (American)',
+        usable_as_source: false,
+        usable_as_target: true,
+        features: { glossary: stable, tag_handling: stable },
+      },
+      {
+        lang: 'en-gb',
+        name: 'English (British)',
+        usable_as_source: false,
+        usable_as_target: true,
+        features: { glossary: stable, tag_handling: stable },
+      },
     ];
 
     res.writeHead(200);

From ac2e9a2d6eeafccc0741c0f2e2edfe7d5cd5d4cc Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 11:18:26 -0400
Subject: [PATCH 018/256] docs(languages): document --features and the
 formality fix

Covers the flag in API.md, README and the languages example, including the
data-driven column rule, the per-listing difference it produces, and that the
matrix is finer-grained than the core/regional/extended tiers. The example
gains a scriptable preflight snippet using --format json.

CHANGELOG records the feature under Added and the pt formality gap under
Fixed. Extends examples/24-languages.sh rather than adding a script, since
that example already covers the command.
---
 CHANGELOG.md             |  4 ++++
 README.md                | 18 ++++++++++++++++++
 docs/API.md              | 30 +++++++++++++++++++++++++++++-
 examples/24-languages.sh | 33 +++++++++++++++++++++++++++++++++
 4 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 57518f0d..01dd118f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API, including the two encodings the endpoints require: repeated form fields for `POST /v2/translate`, and one comma-joined value for the multipart `POST /v2/document`, which keeps only the first of several repeated fields and would otherwise silently apply just one glossary.
 
+- **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`, which the CLI previously discarded. Support no longer has to be discovered by making a request and reading the error. Which features get a column is derived from the response rather than a fixed list: a feature appears when its support differs across the languages listed, and one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row. That makes the columns differ between listings — `auto detection` appears under `--target`, where target-only variants lack it, but is uniform under `--source` — and means a newly reported feature shows up without a code change. Support is signalled by the API reporting a feature at all; `status` describes maturity, so anything short of generally available renders verbatim (`glossary (beta)`) rather than collapsing to `yes`. Works with `--format table` (one column per feature) and `--format json` (the raw matrix including each status, present only when `--features` is passed, so existing JSON consumers are unaffected). `--features` supersedes the `[F]` shorthand and replaces it when given. It needs an API key; without one the command warns and falls back to the registry, which carries no feature data. Note that the matrix is finer-grained than the core/regional/extended tiers: some extended languages support style rules and translation memory even though they support neither formality nor glossary.
+
 - **cli**: `deepl correct` command (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`), but not `--style`/`--tone`, which the correct endpoint does not accept. Results are cached under a separate `correct:` namespace so corrections and rephrasings of the same text never collide.
 
 ### Changed
@@ -69,6 +71,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **languages**: `deepl languages --target` marks Portuguese (`pt`) with `[F]`. Formality support is now read from `features.formality` on `GET /v3/languages` instead of a static table in the language registry. The v3 migration had assumed v3 stopped reporting formality, but the capability was only renamed — v2's `supports_formality` boolean became the presence of a `formality` key in the per-language features matrix — so the CLI was answering from an 11-entry snapshot of the final v2 response that had already drifted from the API. The snapshot and the registry's `supportsFormality` field are gone; the registry's `category` tiers are unaffected. Output is otherwise unchanged: the `[F]` set is identical apart from `pt`.
+
 - **watch**: `--glossary` without `--from` now exits 6 before the watcher starts, instead of starting a session that fails on every single file change with a raw server message. The API rejects any translation naming a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"), which `translate` already guarded against up front for text, files, and documents; `watch` passed `--from` straight through. A long-running command is the worst place for this, since the operator saw the failure once per edit rather than once at launch. The check runs before the glossary name is resolved, so it costs no API call. `sync` needs no equivalent: it has no `--from` at all, taking the source language from the required `source_locale` field in `.deepl-sync.yaml`, so its requests always carry one.
 - **voice**: A session that ends with the audio transcribed but no translation for a requested `--to` language now fails with exit code 9 and names the languages, instead of printing an empty translation line and exiting 0. Silent partial output was the worse failure: a script consuming `deepl voice` output saw success with the translation missing. Audio containing no speech transcribes to nothing and translates to nothing, which is legitimate and still exits 0, so the check only applies when a source transcript exists. Whitespace-only and tentative-but-never-concluded translations count as missing, since neither reaches the printed output. Investigated as an intermittent (~1 in 4) empty translated line; the leading hypothesis was disproved with frame-level traces of live sessions — the server sends `end_of_stream` strictly after `end_of_target_transcript`, and the client only tears the socket down on `end_of_stream`, so there is no client-side teardown race. Reconnect was ruled out too: a socket dropped after end-of-source cannot be resumed (the API returns `410 Gone`) and already exited non-zero. The empty line did not reproduce in 64 live runs across pacing, burst, multi-target, and concurrency variations, so the trigger appears to be server-side and transient — which is exactly why the client needs to detect it rather than report success.
 - **formats**: TOML reconstruction escapes U+2028/U+2029 (Unicode line/paragraph separators) in double-quoted values, and literal-string values gaining one fall back to double quotes. Written raw, these characters broke the entry-line scan on the *next* sync (JavaScript's `.` excludes line terminators), which re-appended the key as a duplicate and made the third sync fail to parse the file at all — first sync fine, second silently corrupting, third crashing. Found by the property-based round-trip suite.
diff --git a/README.md b/README.md
index fa928b15..915adff6 100644
--- a/README.md
+++ b/README.md
@@ -1044,6 +1044,22 @@ deepl languages --source
 # Show only target languages
 deepl languages --target
 
+# Show which features each language supports
+deepl languages --target --features
+# Target Languages:
+#   de        German — formality, glossary, style rules, translation memory, auto detection
+#   pt        Portuguese — formality, glossary, auto detection
+#   en-gb     English (British) — glossary, style rules, translation memory
+#   ...
+#   Extended Languages (quality_optimized only, no formality/glossary):
+#   th        Thai — style rules, translation memory, auto detection
+#   ...
+#
+#   All listed languages also support: tag handling.
+
+# The same matrix as columns
+deepl languages --target --features --format table
+
 # Works without API key (shows local registry data)
 deepl languages
 ```
@@ -1054,6 +1070,8 @@ deepl languages
 - **Regional** (7) — Target-only variants: `en-gb`, `en-us`, `es-419`, `pt-br`, `pt-pt`, `zh-hans`, `zh-hant`
 - **Extended** (82) — Only support `quality_optimized` model, no formality or glossary
 
+`--features` is finer-grained than these tiers — some extended languages do support style rules and translation memory. It needs an API key, since the local registry carries no feature data. A feature only gets its own column when support differs across the languages listed; one supported by all of them is summarised on the last line instead of repeated on every row.
+
 See [examples/24-languages.sh](./examples/24-languages.sh) for a complete example.
 
 #### Configure Defaults
diff --git a/docs/API.md b/docs/API.md
index 6b3af157..0f6cc15e 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -2362,6 +2362,7 @@ You can filter to show only source languages, only target languages, or both (de
 
 - `--source, -s` - Show only source languages
 - `--target` - Show only target languages
+- `--features` - Show which features each language supports (requires an API key; the local registry carries no feature data)
 - `--format FORMAT` - Output format: `text`, `json`, `table` (default: `text`). In non-TTY output, `table` falls back to `text` with a `WARN` line on stderr.
 
 #### Examples
@@ -2399,6 +2400,23 @@ deepl languages --source
 # Show only target languages
 deepl languages --target
 
+# Show which features each language supports
+deepl languages --target --features
+# Target Languages:
+#   de        German — formality, glossary, style rules, translation memory, auto detection
+#   pt        Portuguese — formality, glossary, auto detection
+#   en-gb     English (British) — glossary, style rules, translation memory
+#   ...
+#   Extended Languages (quality_optimized only, no formality/glossary):
+#   hi        Hindi — auto detection
+#   th        Thai — style rules, translation memory, auto detection
+#   ...
+#
+#   All listed languages also support: tag handling.
+
+# The same matrix as columns
+deepl languages --target --features --format table
+
 # Works without API key (shows local registry data)
 deepl languages
 # Note: No API key configured. Showing local language registry only.
@@ -2411,11 +2429,21 @@ deepl languages
 - Target languages that support the `--formality` parameter are marked with `[F]` (requires API key)
 - Language codes are left-aligned and padded for readability
 
+**Feature matrix (`--features`):**
+
+- Feature support comes from `GET /v3/languages`; a feature is supported when the API reports it for that language
+- Which features are shown is derived from the response, not a fixed list. A feature only appears when its support differs across the languages listed; one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row
+- Because of that, the columns differ between listings: `auto detection` appears under `--target` (target-only variants lack it) but is uniform under `--source`
+- A feature that is not yet generally available shows its status instead of `yes`, e.g. `glossary (beta)`
+- `--features` replaces the `[F]` shorthand, since formality is one of the reported features
+- `--format json` includes a raw `features` object with each feature's status, but only when `--features` is passed
+
 **Notes:**
 
 - Source and target language lists differ: 7 regional variants (en-gb, en-us, es-419, pt-br, pt-pt, zh-hans, zh-hant) are target-only
 - Extended languages (82 codes) only support `quality_optimized` model type and do not support formality or glossary features
-- Without an API key, the command shows all languages from the local registry with a warning
+- The extended tier is a coarser signal than the feature matrix: some extended languages do support style rules and translation memory even though they support neither formality nor glossary
+- Without an API key, the command shows all languages from the local registry with a warning; `--features` additionally warns that it needs a key
 
 ---
 
diff --git a/examples/24-languages.sh b/examples/24-languages.sh
index 6d403275..8f1d3280 100755
--- a/examples/24-languages.sh
+++ b/examples/24-languages.sh
@@ -57,6 +57,37 @@ echo "6. Target languages in JSON format:"
 deepl languages --target --format json | head -10
 echo
 
+# Example 7: Which features each language supports
+echo "7. Feature support per language"
+echo "   Columns only appear for features that differ between languages;"
+echo "   one supported by all of them is summarised on the last line."
+deepl languages --target --features | head -12
+echo
+
+echo "8. The same matrix as columns"
+deepl languages --target --features --format table | head -10
+echo
+
+# Example 9: Preflight a feature in a script
+echo "9. Checking feature support before using a flag"
+echo
+cat << 'EOF'
+# Bash snippet: only pass --glossary when the target supports glossaries.
+supports() {  # supports <lang> <feature>
+  deepl languages --target --features --format json \
+    | jq -e --arg l "$1" --arg f "$2" \
+        '.[] | select(.language == $l) | .features | has($f)' >/dev/null
+}
+
+if supports th glossary; then
+  deepl translate --to th --glossary my-terms "Hello"
+else
+  echo "Thai does not support glossaries; translating without one"
+  deepl translate --to th "Hello"
+fi
+EOF
+echo
+
 echo "=== Language listing example completed! ===="
 echo
 
@@ -64,6 +95,8 @@ echo "💡 Language categories:"
 echo "   - Core (32): Full support - formality, glossaries, all model types"
 echo "   - Regional (7): Target-only variants (en-us, en-gb, pt-br, etc.)"
 echo "   - Extended (82): quality_optimized only, no formality or glossaries"
+echo "   - --features is finer-grained than these tiers: some extended languages"
+echo "     do support style rules and translation memory"
 echo
 
 echo "📚 Language notes:"

From f21ab66a223e64af0f79b97759b3bc3b32bde09a Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 13:30:06 -0400
Subject: [PATCH 019/256] refactor(languages): generate the language list from
 the API

The list of supported languages was hand-maintained, so it could fall behind
the API silently -- and had: de-CH, de-DE, fr-CA and fr-FR were being served
by GET /v3/languages and accepted by the translate endpoint while absent here.
It was verified as an exact match on 2026-08-01 and was four codes short by
2026-08-03.

The data now lives in src/data/language-entries.ts, generated by
scripts/generate-language-registry.mjs from GET /v3/languages;
language-registry.ts keeps the lookup helpers. --check reports drift without
writing, wired up as npm run generate:languages / check:languages.

Tiers are derived rather than assigned: glossary support separates extended
from the rest, source usability separates core from regional. Against the live
response this reproduces the previously hand-assigned tiers exactly -- same
32/82 split, extended set byte-identical -- so the tiers can no longer disagree
with the API either. deriveLanguageEntry is exported because the display path
needs the same rule for codes the snapshot predates.

Regenerating brings the list to 125 languages (32 core, 11 regional, 82
extended) with API names verbatim, which is why de-de is "German" like de and
fr-fr is "French" like fr; the API reports them that way and the snapshot
mirrors it instead of inventing distinct names.
---
 package.json                           |   4 +-
 scripts/generate-language-registry.mjs | 113 +++++++++++++++
 src/data/language-entries.ts           | 146 +++++++++++++++++++
 src/data/language-registry.ts          | 189 ++++++++-----------------
 tests/unit/language-registry.test.ts   | 116 +++++++++++++--
 5 files changed, 427 insertions(+), 141 deletions(-)
 create mode 100644 scripts/generate-language-registry.mjs
 create mode 100644 src/data/language-entries.ts

diff --git a/package.json b/package.json
index 00144f7a..61ab9780 100644
--- a/package.json
+++ b/package.json
@@ -45,7 +45,9 @@
     "check-deps": "node scripts/check-dependencies.mjs",
     "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "generate:languages": "node scripts/generate-language-registry.mjs",
+    "check:languages": "node scripts/generate-language-registry.mjs --check"
   },
   "keywords": [
     "deepl",
diff --git a/scripts/generate-language-registry.mjs b/scripts/generate-language-registry.mjs
new file mode 100644
index 00000000..cb6348cd
--- /dev/null
+++ b/scripts/generate-language-registry.mjs
@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Regenerates src/data/language-entries.ts from GET /v3/languages.
+ *
+ * The language list used to be hand-maintained, which meant it could silently
+ * fall behind the API: four target languages DeepL had added (de-CH, de-DE,
+ * fr-CA, fr-FR) were missing, so the CLI rejected them locally even though the
+ * API accepted them. Generating the file keeps it an honest snapshot.
+ *
+ * Tiers are derived, not judged: the derivation lives in
+ * src/data/language-registry.ts and is imported from dist/ so the snapshot and
+ * the runtime fallback cannot disagree.
+ *
+ * Usage:
+ *   node scripts/generate-language-registry.mjs           # rewrite the file
+ *   node scripts/generate-language-registry.mjs --check    # exit 1 on drift
+ *
+ * Needs DEEPL_API_KEY and a current build (npm run build).
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import * as path from 'node:path';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const TARGET = path.join(ROOT, 'src', 'data', 'language-entries.ts');
+const DERIVATION = path.join(ROOT, 'dist', 'data', 'language-registry.js');
+
+const checkOnly = process.argv.includes('--check');
+
+function fail(message) {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+const apiKey = process.env['DEEPL_API_KEY'];
+if (!apiKey) {
+  fail('DEEPL_API_KEY is not set; the snapshot can only be generated from the live API.');
+}
+if (!existsSync(DERIVATION)) {
+  fail(`missing ${path.relative(ROOT, DERIVATION)}; run "npm run build" first.`);
+}
+
+const { deriveLanguageEntry } = await import(DERIVATION);
+
+const host = apiKey.endsWith(':fx') ? 'https://api-free.deepl.com' : 'https://api.deepl.com';
+const response = await fetch(`${host}/v3/languages?resource=translate_text`, {
+  headers: { Authorization: `DeepL-Auth-Key ${apiKey}` },
+});
+if (!response.ok) {
+  fail(`GET /v3/languages returned ${response.status} ${response.statusText}`);
+}
+
+const languages = await response.json();
+if (!Array.isArray(languages) || languages.length === 0) {
+  fail('GET /v3/languages returned no languages');
+}
+
+const entries = languages.map(deriveLanguageEntry);
+const byCode = (a, b) => a.code.localeCompare(b.code, 'en');
+const groups = [
+  ['core', 'Core languages (full feature support: formality, glossary, all model types)'],
+  ['regional', 'Regional variants (target-only)'],
+  ['extended', 'Extended languages (quality_optimized only, no formality/glossary)'],
+];
+
+function render(entry) {
+  const fields = [`code: '${entry.code}'`, `name: '${entry.name.replace(/'/g, "\\'")}'`];
+  fields.push(`category: '${entry.category}'`);
+  if (entry.targetOnly) fields.push('targetOnly: true');
+  return `  { ${fields.join(', ')} },`;
+}
+
+const body = groups
+  .map(([category, heading]) => {
+    const group = entries.filter(e => e.category === category).sort(byCode);
+    return [`  // ${heading}`, ...group.map(render)].join('\n');
+  })
+  .join('\n\n');
+
+const contents = `/**
+ * Supported DeepL languages, generated from GET /v3/languages.
+ *
+ * DO NOT EDIT BY HAND. Run "npm run generate:languages" to refresh, and
+ * "npm run check:languages" to detect drift. Tiers are derived by
+ * deriveLanguageEntry in ./language-registry.ts, not chosen here.
+ *
+ * The API is the authority on which languages exist; this snapshot exists so
+ * the CLI can list and validate languages without a network call or API key.
+ * It may therefore lag the API, which is why callers accept well-formed codes
+ * it does not contain rather than rejecting them.
+ */
+import type { LanguageEntry } from './language-registry.js';
+
+export const ENTRIES: LanguageEntry[] = [
+${body}
+];
+`;
+
+if (checkOnly) {
+  const current = existsSync(TARGET) ? readFileSync(TARGET, 'utf8') : '';
+  if (current === contents) {
+    console.log(`${entries.length} languages; snapshot is current.`);
+    process.exit(0);
+  }
+  console.error(
+    `error: ${path.relative(ROOT, TARGET)} is out of date with the API (${entries.length} languages upstream).\n` +
+      'Run: npm run generate:languages',
+  );
+  process.exit(1);
+}
+
+writeFileSync(TARGET, contents);
+const counts = groups.map(([c]) => `${c} ${entries.filter(e => e.category === c).length}`);
+console.log(`wrote ${path.relative(ROOT, TARGET)}: ${entries.length} languages (${counts.join(', ')})`);
diff --git a/src/data/language-entries.ts b/src/data/language-entries.ts
new file mode 100644
index 00000000..69de1c04
--- /dev/null
+++ b/src/data/language-entries.ts
@@ -0,0 +1,146 @@
+/**
+ * Supported DeepL languages, generated from GET /v3/languages.
+ *
+ * DO NOT EDIT BY HAND. Run "npm run generate:languages" to refresh, and
+ * "npm run check:languages" to detect drift. Tiers are derived by
+ * deriveLanguageEntry in ./language-registry.ts, not chosen here.
+ *
+ * The API is the authority on which languages exist; this snapshot exists so
+ * the CLI can list and validate languages without a network call or API key.
+ * It may therefore lag the API, which is why callers accept well-formed codes
+ * it does not contain rather than rejecting them.
+ */
+import type { LanguageEntry } from './language-registry.js';
+
+export const ENTRIES: LanguageEntry[] = [
+  // Core languages (full feature support: formality, glossary, all model types)
+  { code: 'ar', name: 'Arabic', category: 'core' },
+  { code: 'bg', name: 'Bulgarian', category: 'core' },
+  { code: 'cs', name: 'Czech', category: 'core' },
+  { code: 'da', name: 'Danish', category: 'core' },
+  { code: 'de', name: 'German', category: 'core' },
+  { code: 'el', name: 'Greek', category: 'core' },
+  { code: 'en', name: 'English', category: 'core' },
+  { code: 'es', name: 'Spanish', category: 'core' },
+  { code: 'et', name: 'Estonian', category: 'core' },
+  { code: 'fi', name: 'Finnish', category: 'core' },
+  { code: 'fr', name: 'French', category: 'core' },
+  { code: 'he', name: 'Hebrew', category: 'core' },
+  { code: 'hu', name: 'Hungarian', category: 'core' },
+  { code: 'id', name: 'Indonesian', category: 'core' },
+  { code: 'it', name: 'Italian', category: 'core' },
+  { code: 'ja', name: 'Japanese', category: 'core' },
+  { code: 'ko', name: 'Korean', category: 'core' },
+  { code: 'lt', name: 'Lithuanian', category: 'core' },
+  { code: 'lv', name: 'Latvian', category: 'core' },
+  { code: 'nb', name: 'Norwegian (bokmål)', category: 'core' },
+  { code: 'nl', name: 'Dutch', category: 'core' },
+  { code: 'pl', name: 'Polish', category: 'core' },
+  { code: 'pt', name: 'Portuguese', category: 'core' },
+  { code: 'ro', name: 'Romanian', category: 'core' },
+  { code: 'ru', name: 'Russian', category: 'core' },
+  { code: 'sk', name: 'Slovak', category: 'core' },
+  { code: 'sl', name: 'Slovenian', category: 'core' },
+  { code: 'sv', name: 'Swedish', category: 'core' },
+  { code: 'tr', name: 'Turkish', category: 'core' },
+  { code: 'uk', name: 'Ukrainian', category: 'core' },
+  { code: 'vi', name: 'Vietnamese', category: 'core' },
+  { code: 'zh', name: 'Chinese', category: 'core' },
+
+  // Regional variants (target-only)
+  { code: 'de-ch', name: 'German (Swiss)', category: 'regional', targetOnly: true },
+  { code: 'de-de', name: 'German', category: 'regional', targetOnly: true },
+  { code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true },
+  { code: 'en-us', name: 'English (American)', category: 'regional', targetOnly: true },
+  { code: 'es-419', name: 'Spanish (Latin American)', category: 'regional', targetOnly: true },
+  { code: 'fr-ca', name: 'French (Canadian)', category: 'regional', targetOnly: true },
+  { code: 'fr-fr', name: 'French', category: 'regional', targetOnly: true },
+  { code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true },
+  { code: 'pt-pt', name: 'Portuguese (European)', category: 'regional', targetOnly: true },
+  { code: 'zh-hans', name: 'Chinese (simplified)', category: 'regional', targetOnly: true },
+  { code: 'zh-hant', name: 'Chinese (traditional)', category: 'regional', targetOnly: true },
+
+  // Extended languages (quality_optimized only, no formality/glossary)
+  { code: 'ace', name: 'Acehnese', category: 'extended' },
+  { code: 'af', name: 'Afrikaans', category: 'extended' },
+  { code: 'an', name: 'Aragonese', category: 'extended' },
+  { code: 'as', name: 'Assamese', category: 'extended' },
+  { code: 'ay', name: 'Aymara', category: 'extended' },
+  { code: 'az', name: 'Azerbaijani', category: 'extended' },
+  { code: 'ba', name: 'Bashkir', category: 'extended' },
+  { code: 'be', name: 'Belarusian', category: 'extended' },
+  { code: 'bho', name: 'Bhojpuri', category: 'extended' },
+  { code: 'bn', name: 'Bengali', category: 'extended' },
+  { code: 'br', name: 'Breton', category: 'extended' },
+  { code: 'bs', name: 'Bosnian', category: 'extended' },
+  { code: 'ca', name: 'Catalan', category: 'extended' },
+  { code: 'ceb', name: 'Cebuano', category: 'extended' },
+  { code: 'ckb', name: 'Kurdish (Sorani)', category: 'extended' },
+  { code: 'cy', name: 'Welsh', category: 'extended' },
+  { code: 'eo', name: 'Esperanto', category: 'extended' },
+  { code: 'eu', name: 'Basque', category: 'extended' },
+  { code: 'fa', name: 'Persian', category: 'extended' },
+  { code: 'ga', name: 'Irish', category: 'extended' },
+  { code: 'gl', name: 'Galician', category: 'extended' },
+  { code: 'gn', name: 'Guarani', category: 'extended' },
+  { code: 'gom', name: 'Konkani', category: 'extended' },
+  { code: 'gu', name: 'Gujarati', category: 'extended' },
+  { code: 'ha', name: 'Hausa', category: 'extended' },
+  { code: 'hi', name: 'Hindi', category: 'extended' },
+  { code: 'hr', name: 'Croatian', category: 'extended' },
+  { code: 'ht', name: 'Haitian Creole', category: 'extended' },
+  { code: 'hy', name: 'Armenian', category: 'extended' },
+  { code: 'ig', name: 'Igbo', category: 'extended' },
+  { code: 'is', name: 'Icelandic', category: 'extended' },
+  { code: 'jv', name: 'Javanese', category: 'extended' },
+  { code: 'ka', name: 'Georgian', category: 'extended' },
+  { code: 'kk', name: 'Kazakh', category: 'extended' },
+  { code: 'kmr', name: 'Kurdish (Kurmanji)', category: 'extended' },
+  { code: 'ky', name: 'Kyrgyz', category: 'extended' },
+  { code: 'la', name: 'Latin', category: 'extended' },
+  { code: 'lb', name: 'Luxembourgish', category: 'extended' },
+  { code: 'lmo', name: 'Lombard', category: 'extended' },
+  { code: 'ln', name: 'Lingala', category: 'extended' },
+  { code: 'mai', name: 'Maithili', category: 'extended' },
+  { code: 'mg', name: 'Malagasy', category: 'extended' },
+  { code: 'mi', name: 'Maori', category: 'extended' },
+  { code: 'mk', name: 'Macedonian', category: 'extended' },
+  { code: 'ml', name: 'Malayalam', category: 'extended' },
+  { code: 'mn', name: 'Mongolian', category: 'extended' },
+  { code: 'mr', name: 'Marathi', category: 'extended' },
+  { code: 'ms', name: 'Malay', category: 'extended' },
+  { code: 'mt', name: 'Maltese', category: 'extended' },
+  { code: 'my', name: 'Burmese', category: 'extended' },
+  { code: 'ne', name: 'Nepali', category: 'extended' },
+  { code: 'oc', name: 'Occitan', category: 'extended' },
+  { code: 'om', name: 'Oromo', category: 'extended' },
+  { code: 'pa', name: 'Punjabi', category: 'extended' },
+  { code: 'pag', name: 'Pangasinan', category: 'extended' },
+  { code: 'pam', name: 'Kapampangan', category: 'extended' },
+  { code: 'prs', name: 'Dari', category: 'extended' },
+  { code: 'ps', name: 'Pashto', category: 'extended' },
+  { code: 'qu', name: 'Quechua', category: 'extended' },
+  { code: 'sa', name: 'Sanskrit', category: 'extended' },
+  { code: 'scn', name: 'Sicilian', category: 'extended' },
+  { code: 'sq', name: 'Albanian', category: 'extended' },
+  { code: 'sr', name: 'Serbian', category: 'extended' },
+  { code: 'st', name: 'Sesotho', category: 'extended' },
+  { code: 'su', name: 'Sundanese', category: 'extended' },
+  { code: 'sw', name: 'Swahili', category: 'extended' },
+  { code: 'ta', name: 'Tamil', category: 'extended' },
+  { code: 'te', name: 'Telugu', category: 'extended' },
+  { code: 'tg', name: 'Tajik', category: 'extended' },
+  { code: 'th', name: 'Thai', category: 'extended' },
+  { code: 'tk', name: 'Turkmen', category: 'extended' },
+  { code: 'tl', name: 'Tagalog', category: 'extended' },
+  { code: 'tn', name: 'Tswana', category: 'extended' },
+  { code: 'ts', name: 'Tsonga', category: 'extended' },
+  { code: 'tt', name: 'Tatar', category: 'extended' },
+  { code: 'ur', name: 'Urdu', category: 'extended' },
+  { code: 'uz', name: 'Uzbek', category: 'extended' },
+  { code: 'wo', name: 'Wolof', category: 'extended' },
+  { code: 'xh', name: 'Xhosa', category: 'extended' },
+  { code: 'yi', name: 'Yiddish', category: 'extended' },
+  { code: 'yue', name: 'Cantonese', category: 'extended' },
+  { code: 'zu', name: 'Zulu', category: 'extended' },
+];
diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index 47296ec2..3f2624dc 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -1,15 +1,21 @@
 /**
  * Language Registry
  *
- * Single source of truth for all DeepL-supported language codes, display names,
- * and feature categories. Every CLI component that needs to validate or display
- * language codes should import from this module rather than maintaining its own list.
+ * Lookup and classification helpers over the generated language snapshot in
+ * ./language-entries.ts. GET /v3/languages is the authority on which languages
+ * exist; the snapshot is a build artifact of it, so that listing and validating
+ * languages works without a network call or an API key.
+ *
+ * Because the snapshot can lag the API, callers that validate user input accept
+ * well-formed codes it does not contain (see looksLikeLanguageTag) instead of
+ * rejecting them.
  *
  * Languages are organized into three categories that determine feature availability:
  * - **core**: Full feature support (formality, glossary, all model types)
  * - **regional**: Target-only variants of core languages (e.g., en-gb, pt-br)
  * - **extended**: quality_optimized model only; no formality or glossary support
  */
+import { ENTRIES } from './language-entries.js';
 
 /**
  * Feature-availability tier for a language.
@@ -32,140 +38,59 @@ export interface LanguageEntry {
   targetOnly?: boolean;
 }
 
-const ENTRIES: LanguageEntry[] = [
-  // Core languages (full feature support: formality, glossary, all model types)
-  { code: 'ar', name: 'Arabic', category: 'core' },
-  { code: 'bg', name: 'Bulgarian', category: 'core' },
-  { code: 'cs', name: 'Czech', category: 'core' },
-  { code: 'da', name: 'Danish', category: 'core' },
-  { code: 'de', name: 'German', category: 'core' },
-  { code: 'el', name: 'Greek', category: 'core' },
-  { code: 'en', name: 'English', category: 'core' },
-  { code: 'es', name: 'Spanish', category: 'core' },
-  { code: 'et', name: 'Estonian', category: 'core' },
-  { code: 'fi', name: 'Finnish', category: 'core' },
-  { code: 'fr', name: 'French', category: 'core' },
-  { code: 'he', name: 'Hebrew', category: 'core' },
-  { code: 'hu', name: 'Hungarian', category: 'core' },
-  { code: 'id', name: 'Indonesian', category: 'core' },
-  { code: 'it', name: 'Italian', category: 'core' },
-  { code: 'ja', name: 'Japanese', category: 'core' },
-  { code: 'ko', name: 'Korean', category: 'core' },
-  { code: 'lt', name: 'Lithuanian', category: 'core' },
-  { code: 'lv', name: 'Latvian', category: 'core' },
-  { code: 'nb', name: 'Norwegian Bokmål', category: 'core' },
-  { code: 'nl', name: 'Dutch', category: 'core' },
-  { code: 'pl', name: 'Polish', category: 'core' },
-  { code: 'pt', name: 'Portuguese', category: 'core' },
-  { code: 'ro', name: 'Romanian', category: 'core' },
-  { code: 'ru', name: 'Russian', category: 'core' },
-  { code: 'sk', name: 'Slovak', category: 'core' },
-  { code: 'sl', name: 'Slovenian', category: 'core' },
-  { code: 'sv', name: 'Swedish', category: 'core' },
-  { code: 'tr', name: 'Turkish', category: 'core' },
-  { code: 'uk', name: 'Ukrainian', category: 'core' },
-  { code: 'vi', name: 'Vietnamese', category: 'core' },
-  { code: 'zh', name: 'Chinese', category: 'core' },
-
-  // Regional variants (target-only)
-  { code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true },
-  { code: 'en-us', name: 'English (American)', category: 'regional', targetOnly: true },
-  { code: 'es-419', name: 'Spanish (Latin America)', category: 'regional', targetOnly: true },
-  { code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true },
-  { code: 'pt-pt', name: 'Portuguese (European)', category: 'regional', targetOnly: true },
-  { code: 'zh-hans', name: 'Chinese (Simplified)', category: 'regional', targetOnly: true },
-  { code: 'zh-hant', name: 'Chinese (Traditional)', category: 'regional', targetOnly: true },
-
-  // Extended languages (quality_optimized only, no formality/glossary)
-  { code: 'ace', name: 'Acehnese', category: 'extended' },
-  { code: 'af', name: 'Afrikaans', category: 'extended' },
-  { code: 'an', name: 'Aragonese', category: 'extended' },
-  { code: 'as', name: 'Assamese', category: 'extended' },
-  { code: 'ay', name: 'Aymara', category: 'extended' },
-  { code: 'az', name: 'Azerbaijani', category: 'extended' },
-  { code: 'ba', name: 'Bashkir', category: 'extended' },
-  { code: 'be', name: 'Belarusian', category: 'extended' },
-  { code: 'bho', name: 'Bhojpuri', category: 'extended' },
-  { code: 'bn', name: 'Bengali', category: 'extended' },
-  { code: 'br', name: 'Breton', category: 'extended' },
-  { code: 'bs', name: 'Bosnian', category: 'extended' },
-  { code: 'ca', name: 'Catalan', category: 'extended' },
-  { code: 'ceb', name: 'Cebuano', category: 'extended' },
-  { code: 'ckb', name: 'Central Kurdish', category: 'extended' },
-  { code: 'cy', name: 'Welsh', category: 'extended' },
-  { code: 'eo', name: 'Esperanto', category: 'extended' },
-  { code: 'eu', name: 'Basque', category: 'extended' },
-  { code: 'fa', name: 'Persian', category: 'extended' },
-  { code: 'ga', name: 'Irish', category: 'extended' },
-  { code: 'gl', name: 'Galician', category: 'extended' },
-  { code: 'gn', name: 'Guarani', category: 'extended' },
-  { code: 'gom', name: 'Goan Konkani', category: 'extended' },
-  { code: 'gu', name: 'Gujarati', category: 'extended' },
-  { code: 'ha', name: 'Hausa', category: 'extended' },
-  { code: 'hi', name: 'Hindi', category: 'extended' },
-  { code: 'hr', name: 'Croatian', category: 'extended' },
-  { code: 'ht', name: 'Haitian Creole', category: 'extended' },
-  { code: 'hy', name: 'Armenian', category: 'extended' },
-  { code: 'ig', name: 'Igbo', category: 'extended' },
-  { code: 'is', name: 'Icelandic', category: 'extended' },
-  { code: 'jv', name: 'Javanese', category: 'extended' },
-  { code: 'ka', name: 'Georgian', category: 'extended' },
-  { code: 'kk', name: 'Kazakh', category: 'extended' },
-  { code: 'kmr', name: 'Northern Kurdish', category: 'extended' },
-  { code: 'ky', name: 'Kyrgyz', category: 'extended' },
-  { code: 'la', name: 'Latin', category: 'extended' },
-  { code: 'lb', name: 'Luxembourgish', category: 'extended' },
-  { code: 'lmo', name: 'Lombard', category: 'extended' },
-  { code: 'ln', name: 'Lingala', category: 'extended' },
-  { code: 'mai', name: 'Maithili', category: 'extended' },
-  { code: 'mg', name: 'Malagasy', category: 'extended' },
-  { code: 'mi', name: 'Maori', category: 'extended' },
-  { code: 'mk', name: 'Macedonian', category: 'extended' },
-  { code: 'ml', name: 'Malayalam', category: 'extended' },
-  { code: 'mn', name: 'Mongolian', category: 'extended' },
-  { code: 'mr', name: 'Marathi', category: 'extended' },
-  { code: 'ms', name: 'Malay', category: 'extended' },
-  { code: 'mt', name: 'Maltese', category: 'extended' },
-  { code: 'my', name: 'Myanmar (Burmese)', category: 'extended' },
-  { code: 'ne', name: 'Nepali', category: 'extended' },
-  { code: 'oc', name: 'Occitan', category: 'extended' },
-  { code: 'om', name: 'Oromo', category: 'extended' },
-  { code: 'pa', name: 'Punjabi', category: 'extended' },
-  { code: 'pag', name: 'Pangasinan', category: 'extended' },
-  { code: 'pam', name: 'Pampanga', category: 'extended' },
-  { code: 'prs', name: 'Dari', category: 'extended' },
-  { code: 'ps', name: 'Pashto', category: 'extended' },
-  { code: 'qu', name: 'Quechua', category: 'extended' },
-  { code: 'sa', name: 'Sanskrit', category: 'extended' },
-  { code: 'scn', name: 'Sicilian', category: 'extended' },
-  { code: 'sq', name: 'Albanian', category: 'extended' },
-  { code: 'sr', name: 'Serbian', category: 'extended' },
-  { code: 'st', name: 'Southern Sotho', category: 'extended' },
-  { code: 'su', name: 'Sundanese', category: 'extended' },
-  { code: 'sw', name: 'Swahili', category: 'extended' },
-  { code: 'ta', name: 'Tamil', category: 'extended' },
-  { code: 'te', name: 'Telugu', category: 'extended' },
-  { code: 'tg', name: 'Tajik', category: 'extended' },
-  { code: 'th', name: 'Thai', category: 'extended' },
-  { code: 'tk', name: 'Turkmen', category: 'extended' },
-  { code: 'tl', name: 'Tagalog', category: 'extended' },
-  { code: 'tn', name: 'Tswana', category: 'extended' },
-  { code: 'ts', name: 'Tsonga', category: 'extended' },
-  { code: 'tt', name: 'Tatar', category: 'extended' },
-  { code: 'ur', name: 'Urdu', category: 'extended' },
-  { code: 'uz', name: 'Uzbek', category: 'extended' },
-  { code: 'wo', name: 'Wolof', category: 'extended' },
-  { code: 'xh', name: 'Xhosa', category: 'extended' },
-  { code: 'yi', name: 'Yiddish', category: 'extended' },
-  { code: 'yue', name: 'Cantonese', category: 'extended' },
-  { code: 'zu', name: 'Zulu', category: 'extended' },
-];
-
 /** Read-only map of language code to its registry entry. Primary lookup structure. */
 export const LANGUAGE_REGISTRY: ReadonlyMap<string, LanguageEntry> = new Map(
   ENTRIES.map(entry => [entry.code, entry])
 );
 
+/** The fields of a GET /v3/languages entry the derivation below depends on. */
+export interface DerivableLanguage {
+  lang: string;
+  name: string;
+  usable_as_source?: boolean;
+  features?: Record<string, unknown>;
+}
+
+/**
+ * Derives a registry entry from one GET /v3/languages entry. The tiers are not
+ * a human judgement: glossary support separates extended from the rest, and
+ * source usability separates core from regional. Checked against the live
+ * response, this reproduces the hand-maintained tiers exactly.
+ *
+ * Shared with scripts/generate-language-registry.mjs so the snapshot and the
+ * runtime fallback for codes the snapshot predates cannot disagree.
+ */
+export function deriveLanguageEntry(language: DerivableLanguage): LanguageEntry {
+  const code = language.lang.toLowerCase();
+  const usableAsSource = language.usable_as_source !== false;
+  const supportsGlossary = language.features?.['glossary'] !== undefined;
+
+  const category: LanguageCategory = !supportsGlossary
+    ? 'extended'
+    : usableAsSource
+      ? 'core'
+      : 'regional';
+
+  return {
+    code,
+    name: language.name,
+    category,
+    ...(!usableAsSource && { targetOnly: true }),
+  };
+}
+
+/**
+ * Whether a code is shaped like a language tag DeepL might serve. Used where the
+ * API is the authority on what exists: a well-formed code the snapshot has not
+ * heard of is passed through for the API to accept or reject, while malformed
+ * input is still worth rejecting locally with a suggestion.
+ */
+const LANGUAGE_TAG = /^[a-z]{2,3}(-[a-z0-9]{2,4})?$/;
+
+export function looksLikeLanguageTag(code: string): boolean {
+  return LANGUAGE_TAG.test(code);
+}
+
 /** Check whether a language code is recognized by the registry. */
 export function isValidLanguage(code: string): boolean {
   return LANGUAGE_REGISTRY.has(code);
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index b7065dc7..8b2e9728 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -7,12 +7,14 @@ import {
   getTargetLanguages,
   getAllLanguageCodes,
   getExtendedLanguageCodes,
+  deriveLanguageEntry,
+  looksLikeLanguageTag,
 } from '../../src/data/language-registry';
 
 describe('Language Registry', () => {
   describe('LANGUAGE_REGISTRY', () => {
-    it('should contain 121 language entries', () => {
-      expect(LANGUAGE_REGISTRY.size).toBe(121);
+    it('should contain 125 language entries', () => {
+      expect(LANGUAGE_REGISTRY.size).toBe(125);
     });
 
     it('should have unique language codes', () => {
@@ -26,9 +28,9 @@ describe('Language Registry', () => {
       expect(core.length).toBe(32);
     });
 
-    it('should contain all 7 regional variants', () => {
+    it('should contain all 11 regional variants', () => {
       const regional = Array.from(LANGUAGE_REGISTRY.values()).filter(e => e.category === 'regional');
-      expect(regional.length).toBe(7);
+      expect(regional.length).toBe(11);
     });
 
     it('should contain all 82 extended languages', () => {
@@ -79,6 +81,18 @@ describe('Language Registry', () => {
       expect(LANGUAGE_REGISTRY.get('hi')).toEqual({ code: 'hi', name: 'Hindi', category: 'extended' });
       expect(LANGUAGE_REGISTRY.get('sw')).toEqual({ code: 'sw', name: 'Swahili', category: 'extended' });
     });
+
+    it('should include the regional variants of German and French', () => {
+      expect(LANGUAGE_REGISTRY.get('de-ch')).toEqual({ code: 'de-ch', name: 'German (Swiss)', category: 'regional', targetOnly: true });
+      expect(LANGUAGE_REGISTRY.get('fr-ca')).toEqual({ code: 'fr-ca', name: 'French (Canadian)', category: 'regional', targetOnly: true });
+    });
+
+    it('should carry the API name even where it duplicates a bare code', () => {
+      // The API calls both `de` and `de-DE` "German"; the snapshot mirrors it
+      // rather than inventing a disambiguated name.
+      expect(getLanguageName('de-de')).toBe('German');
+      expect(getLanguageName('fr-fr')).toBe('French');
+    });
   });
 
   describe('isValidLanguage()', () => {
@@ -163,14 +177,14 @@ describe('Language Registry', () => {
       expect(codes).toContain('sw');
     });
 
-    it('should return 114 languages (121 - 7 regional)', () => {
+    it('should return 114 languages (125 - 11 regional)', () => {
       expect(getSourceLanguages().length).toBe(114);
     });
   });
 
   describe('getTargetLanguages()', () => {
     it('should include all languages', () => {
-      expect(getTargetLanguages().length).toBe(121);
+      expect(getTargetLanguages().length).toBe(125);
     });
 
     it('should include regional variants', () => {
@@ -183,9 +197,9 @@ describe('Language Registry', () => {
   });
 
   describe('getAllLanguageCodes()', () => {
-    it('should return set of all 121 codes', () => {
+    it('should return set of all 125 codes', () => {
       const codes = getAllLanguageCodes();
-      expect(codes.size).toBe(121);
+      expect(codes.size).toBe(125);
     });
 
     it('should support has() lookups', () => {
@@ -218,6 +232,92 @@ describe('Language Registry', () => {
     });
   });
 
+  describe('deriveLanguageEntry()', () => {
+    const stable = { status: 'stable' };
+
+    it('should classify a source-usable language with glossary support as core', () => {
+      expect(
+        deriveLanguageEntry({
+          lang: 'de',
+          name: 'German',
+          usable_as_source: true,
+          features: { glossary: stable, formality: stable },
+        }),
+      ).toEqual({ code: 'de', name: 'German', category: 'core' });
+    });
+
+    it('should classify a target-only language with glossary support as regional', () => {
+      expect(
+        deriveLanguageEntry({
+          lang: 'de-CH',
+          name: 'German (Swiss)',
+          usable_as_source: false,
+          features: { glossary: stable, formality: stable },
+        }),
+      ).toEqual({ code: 'de-ch', name: 'German (Swiss)', category: 'regional', targetOnly: true });
+    });
+
+    it('should classify a language without glossary support as extended', () => {
+      expect(
+        deriveLanguageEntry({
+          lang: 'hi',
+          name: 'Hindi',
+          usable_as_source: true,
+          features: { tag_handling: stable },
+        }),
+      ).toEqual({ code: 'hi', name: 'Hindi', category: 'extended' });
+    });
+
+    it('should treat a missing features object as extended', () => {
+      expect(
+        deriveLanguageEntry({ lang: 'xx', name: 'Test', usable_as_source: true }).category,
+      ).toBe('extended');
+    });
+
+    it('should lowercase the code', () => {
+      expect(deriveLanguageEntry({ lang: 'ZH-Hans', name: 'Chinese' }).code).toBe('zh-hans');
+    });
+
+    it('should mark targetOnly whenever the language is not source-usable', () => {
+      expect(
+        deriveLanguageEntry({ lang: 'th', name: 'Thai', usable_as_source: false }).targetOnly,
+      ).toBe(true);
+      expect(
+        deriveLanguageEntry({ lang: 'th', name: 'Thai', usable_as_source: true }).targetOnly,
+      ).toBeUndefined();
+    });
+
+    it('should reproduce every entry currently in the snapshot', () => {
+      // The snapshot is generated by this derivation, so re-deriving an entry
+      // from the shape it came from must be a fixed point.
+      const de = LANGUAGE_REGISTRY.get('de')!;
+      expect(
+        deriveLanguageEntry({
+          lang: 'de',
+          name: de.name,
+          usable_as_source: true,
+          features: { glossary: { status: 'stable' } },
+        }),
+      ).toEqual(de);
+    });
+  });
+
+  describe('looksLikeLanguageTag()', () => {
+    it.each(['de', 'ace', 'de-ch', 'en-gb', 'es-419', 'zh-hans', 'bho'])(
+      'should accept the well-formed tag %s',
+      code => {
+        expect(looksLikeLanguageTag(code)).toBe(true);
+      },
+    );
+
+    it.each(['grman', 'g', '', 'de_CH', 'de-', '-de', 'de-ch-extra', 'DE'])(
+      'should reject the malformed tag %s',
+      code => {
+        expect(looksLikeLanguageTag(code)).toBe(false);
+      },
+    );
+  });
+
   describe('formality support', () => {
     it('should not carry formality data; GET /v3/languages reports it as features.formality', () => {
       LANGUAGE_REGISTRY.forEach(entry => {

From bdec6ff97b4f28610b7bd10a18b9b43d411ffa8d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 13:30:16 -0400
Subject: [PATCH 020/256] fix(languages): let the API decide which language
 codes exist

Regenerating the bundled list fixes today's four missing languages but not the
failure mode: a snapshot can always lag the API, and rejecting against it made
languages the API accepts unusable. `deepl translate --to de-CH` failed locally
with "Invalid target language code" while POST /v2/translate answered DE-CH
with 200 and a translation.

A well-formed language code the snapshot does not list is now sent to the API,
which accepts or rejects it authoritatively. Input that is not shaped like a
language tag is still rejected locally with the pointer to `deepl languages`,
so `--to grman` still fails fast without a request; the API answers those with
a plain 400 and no suggestion.

Applies to validateLanguageCodes, covering translate and sync, and to
ConfigService.validateLanguage, which would otherwise still reject de-ch in
config files.
---
 src/cli/commands/translate/translate-utils.ts | 25 +++++++++++++------
 src/storage/config.ts                         |  8 +++---
 tests/e2e/cli-success-paths.e2e.test.ts       | 16 ++++++++++++
 tests/unit/config-service.test.ts             |  7 ++++++
 tests/unit/translate-utils.test.ts            | 21 +++++++++++++---
 5 files changed, 64 insertions(+), 13 deletions(-)

diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index 3a541f23..6025a3fc 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -3,7 +3,11 @@ import * as path from 'path';
 import { Language, Formality } from '../../../types/index.js';
 import { ValidationError } from '../../../utils/errors.js';
 import { Logger } from '../../../utils/logger.js';
-import { getAllLanguageCodes, getExtendedLanguageCodes } from '../../../data/language-registry.js';
+import {
+  getAllLanguageCodes,
+  getExtendedLanguageCodes,
+  looksLikeLanguageTag,
+} from '../../../data/language-registry.js';
 import type { FileTranslationService } from '../../../services/file-translation.js';
 import type { GlossaryService } from '../../../services/glossary.js';
 import type { TranslateOptions, TranslationParams } from './types.js';
@@ -54,14 +58,21 @@ export function warnIgnoredOptions(mode: string, options: TranslateOptions, supp
   }
 }
 
+/**
+ * Rejects input that is not shaped like a language tag. Codes the bundled
+ * snapshot does not list are passed through: GET /v3/languages is the authority
+ * on which languages exist, and the snapshot can lag it, so rejecting here made
+ * languages the API accepts unusable. The API answers an unknown code with a
+ * 400 of its own.
+ */
 export function validateLanguageCodes(langCodes: string[]): void {
   for (const lang of langCodes) {
-    if (!VALID_LANGUAGES.has(lang)) {
-      throw new ValidationError(
-        `Invalid target language code: "${lang}".`,
-        'Run: deepl languages  to see all available languages'
-      );
-    }
+    if (VALID_LANGUAGES.has(lang)) continue;
+    if (looksLikeLanguageTag(lang)) continue;
+    throw new ValidationError(
+      `Invalid target language code: "${lang}".`,
+      'Run: deepl languages  to see all available languages'
+    );
   }
 }
 
diff --git a/src/storage/config.ts b/src/storage/config.ts
index 345d111b..69fee194 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { DeepLConfig, Formality, OutputFormat } from '../types/index.js';
 import { resolvePaths } from '../utils/paths.js';
-import { isValidLanguage } from '../data/language-registry.js';
+import { isValidLanguage, looksLikeLanguageTag } from '../data/language-registry.js';
 import { ConfigError } from '../utils/errors.js';
 import { validateApiUrl } from '../utils/validate-url.js';
 import { Logger } from '../utils/logger.js';
@@ -379,10 +379,12 @@ export class ConfigService {
   }
 
   /**
-   * Validate language code
+   * Validate language code. Codes the bundled snapshot does not list are
+   * accepted when they are shaped like a language tag, because GET /v3/languages
+   * is the authority on which languages exist and the snapshot can lag it.
    */
   private validateLanguage(lang: string, key?: string): void {
-    if (!isValidLanguage(lang)) {
+    if (!isValidLanguage(lang) && !looksLikeLanguageTag(lang)) {
       const context = key ? ` for "${key}"` : '';
       throw new ConfigError(`Invalid language code "${lang}"${context}. Run: deepl languages to see valid codes`);
     }
diff --git a/tests/e2e/cli-success-paths.e2e.test.ts b/tests/e2e/cli-success-paths.e2e.test.ts
index ef192098..7f907fc2 100644
--- a/tests/e2e/cli-success-paths.e2e.test.ts
+++ b/tests/e2e/cli-success-paths.e2e.test.ts
@@ -76,6 +76,7 @@ describe('CLI Success Paths E2E', () => {
   let runCLI: (command: string) => string;
   let runCLIAll: (command: string) => string;
   let runCLIPipe: (stdin: string, command: string) => string;
+  let runCLIExpectError: (command: string) => { status: number; output: string };
 
   beforeAll(async () => {
     testConfigDir = testConfig.path;
@@ -85,6 +86,7 @@ describe('CLI Success Paths E2E', () => {
     runCLI = (command: string) => helpers.runCLI(command);
     runCLIAll = (command: string) => helpers.runCLIAll(command);
     runCLIPipe = (stdin: string, command: string) => helpers.runCLIPipe(stdin, command);
+    runCLIExpectError = (command: string) => helpers.runCLIExpectError(command);
 
     mockPort = await startMockServer();
     baseUrl = `http://127.0.0.1:${mockPort}`;
@@ -121,6 +123,20 @@ describe('CLI Success Paths E2E', () => {
       expect(output.trim().split('\n')[0]).toBe('Traduceme');
     });
 
+    it('should send a well-formed target the bundled snapshot does not list', () => {
+      // The mock echoes "[TARGET] text", so reaching it at all proves the code
+      // was not rejected locally. GET /v3/languages is the authority on which
+      // languages exist, and the snapshot can lag it.
+      const output = runCLI('translate "Unmapped" --to xx-yy');
+      expect(output.trim().split('\n')[0]).toBe('[XX-YY] Unmapped');
+    });
+
+    it('should still reject a target that is not shaped like a language tag', () => {
+      const result = runCLIExpectError('translate "Hello" --to notalanguage');
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toMatch(/Invalid target language code: "notalanguage"/);
+    });
+
     it('should translate a file and write to output', () => {
       const inputFile = path.join(testDir, 'input.txt');
       const outputFile = path.join(testDir, 'output.txt');
diff --git a/tests/unit/config-service.test.ts b/tests/unit/config-service.test.ts
index 7f2c3b3d..fba66749 100644
--- a/tests/unit/config-service.test.ts
+++ b/tests/unit/config-service.test.ts
@@ -230,6 +230,13 @@ describe('ConfigService', () => {
       }).not.toThrow();
     });
 
+    it('should accept a well-formed code the bundled snapshot does not know', () => {
+      // The API decides what exists; the snapshot can lag it.
+      expect(() => {
+        configService.set('defaults.sourceLang', 'de-ch');
+      }).not.toThrow();
+    });
+
     it('should validate formality values', () => {
       expect(() => {
         configService.set('defaults.formality', 'invalid');
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index b342c963..3575a4c3 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -51,10 +51,11 @@ describe('translate-utils', () => {
 
   describe('constants', () => {
     it('VALID_LANGUAGES should contain all language codes', () => {
-      expect(VALID_LANGUAGES.size).toBe(121);
+      expect(VALID_LANGUAGES.size).toBe(125);
       expect(VALID_LANGUAGES.has('en')).toBe(true);
       expect(VALID_LANGUAGES.has('de')).toBe(true);
       expect(VALID_LANGUAGES.has('en-gb')).toBe(true);
+      expect(VALID_LANGUAGES.has('de-ch')).toBe(true);
       expect(VALID_LANGUAGES.has('hi')).toBe(true);
     });
 
@@ -104,14 +105,28 @@ describe('translate-utils', () => {
       expect(() => validateLanguageCodes([])).not.toThrow();
     });
 
-    it('should throw ValidationError for invalid language code', () => {
-      expect(() => validateLanguageCodes(['xx'])).toThrow(ValidationError);
+    it('should throw ValidationError for a malformed language code', () => {
+      expect(() => validateLanguageCodes(['not-a-language'])).toThrow(ValidationError);
     });
 
     it('should include the invalid code in the error message', () => {
       expect(() => validateLanguageCodes(['zzzz'])).toThrow(/Invalid target language code: "zzzz"/);
     });
 
+    it('should pass through a well-formed code the snapshot does not know', () => {
+      // The API is the authority on which languages exist, and the bundled
+      // snapshot can lag it. Rejecting locally made valid targets unusable.
+      expect(() => validateLanguageCodes(['xx'])).not.toThrow();
+      expect(() => validateLanguageCodes(['de-ch', 'fr-ca'])).not.toThrow();
+      expect(() => validateLanguageCodes(['abc-1234'])).not.toThrow();
+    });
+
+    it('should still reject input that is not shaped like a language tag', () => {
+      for (const code of ['g', 'grman', 'de_ch', 'de-', '../etc/passwd', 'de ch']) {
+        expect(() => validateLanguageCodes([code])).toThrow(ValidationError);
+      }
+    });
+
     it('should emit a concise message and point at `deepl languages` for the full list', () => {
       try {
         validateLanguageCodes(['invalid']);

From e890645ea10e674ebb2f1324037d20d6a65a8483 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 13:30:28 -0400
Subject: [PATCH 021/256] fix(languages): list languages the API offers but the
 snapshot predates

mergeWithRegistry iterated the bundled list and only took names from the API,
so a language the API served but the snapshot lacked was dropped from the
output entirely. That is why `deepl languages` could not show de-DE, and why
the "Run: deepl languages" suggestion on the rejection was a dead end -- the
command could not list the language it was telling the user to look for.

The row set is now the union of both, the API winning on name and features,
the snapshot supplying the tier. Snapshot entries the API omits are kept, so a
partial response never makes languages vanish. For codes the snapshot does not
know, the tier comes from the shared derivation; source usability is inferred
from the presence of a subtag rather than the role being listed, so the same
code is not tiered differently in the source and target listings.
---
 src/cli/commands/languages.ts                 | 37 +++++++++++-
 .../cli-languages.integration.test.ts         |  9 +++
 tests/unit/languages-command.test.ts          | 59 +++++++++++++++++++
 3 files changed, 103 insertions(+), 2 deletions(-)

diff --git a/src/cli/commands/languages.ts b/src/cli/commands/languages.ts
index 48120dc8..51003562 100644
--- a/src/cli/commands/languages.ts
+++ b/src/cli/commands/languages.ts
@@ -5,6 +5,7 @@ import { LanguageInfo, type LanguageFeatures } from '../../api/deepl-client.js';
 import {
   getSourceLanguages as getRegistrySourceLanguages,
   getTargetLanguages as getRegistryTargetLanguages,
+  deriveLanguageEntry,
 } from '../../data/language-registry.js';
 import { isColorEnabled } from '../../utils/formatters.js';
 
@@ -147,7 +148,13 @@ export class LanguagesCommand {
   }
 
   /**
-   * Merge API languages with registry data. API names take precedence.
+   * Merge API languages with the bundled snapshot. API names take precedence.
+   *
+   * The row set is the union of both: iterating only the snapshot meant a
+   * language the API offers but the snapshot predates was silently dropped from
+   * the listing, so `deepl languages` could not show what `translate` accepted.
+   * Snapshot entries the API omits are kept, so a partial response never makes
+   * languages disappear.
    */
   mergeWithRegistry(
     apiLanguages: LanguageInfo[],
@@ -162,7 +169,7 @@ export class LanguagesCommand {
       ? getRegistrySourceLanguages()
       : getRegistryTargetLanguages();
 
-    return registryEntries.map(entry => {
+    const merged = registryEntries.map(entry => {
       const apiLang = apiMap.get(entry.code);
       return {
         code: entry.code,
@@ -172,6 +179,32 @@ export class LanguagesCommand {
         ...(apiLang?.features && { features: apiLang.features }),
       };
     });
+
+    const known = new Set(registryEntries.map(entry => entry.code));
+    for (const lang of apiLanguages) {
+      const code = lang.language.toLowerCase();
+      if (known.has(code)) continue;
+      // LanguageInfo carries no usable_as_source, and deriving it from the role
+      // would tier the same code differently in each listing. A regional variant
+      // always carries a subtag, which is the stable signal available here; core
+      // and regional render in the same section anyway, and regenerating the
+      // snapshot replaces the guess with the API's own answer.
+      const { code: derivedCode, name, category } = deriveLanguageEntry({
+        lang: code,
+        name: lang.name,
+        usable_as_source: !code.includes('-'),
+        ...(lang.features && { features: lang.features }),
+      });
+      merged.push({
+        code: derivedCode,
+        name,
+        category,
+        ...(lang.supportsFormality !== undefined && { supportsFormality: lang.supportsFormality }),
+        ...(lang.features && { features: lang.features }),
+      });
+    }
+
+    return merged;
   }
 
   /**
diff --git a/tests/integration/cli-languages.integration.test.ts b/tests/integration/cli-languages.integration.test.ts
index f9181c0f..1a6b4a04 100644
--- a/tests/integration/cli-languages.integration.test.ts
+++ b/tests/integration/cli-languages.integration.test.ts
@@ -46,6 +46,15 @@ describe('Languages CLI Integration', () => {
       expect(output).toContain('Source Languages:');
       expect(output).toContain('Extended Languages');
     });
+
+    it('should list the regional variants the snapshot previously omitted', () => {
+      const output = runCLI('deepl languages --target', { apiKey: '' });
+
+      expect(output).toContain('German (Swiss)');
+      expect(output).toContain('French (Canadian)');
+      expect(output).toMatch(/^\s+de-ch\s/m);
+      expect(output).toMatch(/^\s+fr-fr\s/m);
+    });
   });
 
   describe('deepl languages command structure', () => {
diff --git a/tests/unit/languages-command.test.ts b/tests/unit/languages-command.test.ts
index 26c9003b..2ac3c977 100644
--- a/tests/unit/languages-command.test.ts
+++ b/tests/unit/languages-command.test.ts
@@ -408,6 +408,65 @@ describe('LanguagesCommand', () => {
     });
   });
 
+  describe('mergeWithRegistry() row set', () => {
+    it('should include a language the API reports but the snapshot does not', () => {
+      const apiLangs: LanguageInfo[] = [
+        {
+          language: 'xx-yy' as LanguageInfo['language'],
+          name: 'Testish (Regional)',
+          supportsFormality: true,
+          features: { glossary: { status: 'stable' } },
+        },
+      ];
+      const merged = languagesCommand.mergeWithRegistry(apiLangs, 'target');
+      const entry = merged.find(e => e.code === 'xx-yy');
+
+      expect(entry).toBeDefined();
+      expect(entry!.name).toBe('Testish (Regional)');
+    });
+
+    it('should derive the tier for a language the snapshot does not know', () => {
+      const apiLangs: LanguageInfo[] = [
+        {
+          language: 'xx' as LanguageInfo['language'],
+          name: 'Glossaryless',
+          features: { tag_handling: { status: 'stable' } },
+        },
+        {
+          language: 'yy' as LanguageInfo['language'],
+          name: 'Glossaried',
+          features: { glossary: { status: 'stable' } },
+        },
+      ];
+      const merged = languagesCommand.mergeWithRegistry(apiLangs, 'target');
+
+      expect(merged.find(e => e.code === 'xx')!.category).toBe('extended');
+      expect(merged.find(e => e.code === 'yy')!.category).toBe('core');
+    });
+
+    it('should keep snapshot languages the API omits', () => {
+      const merged = languagesCommand.mergeWithRegistry(
+        [{ language: 'de', name: 'German' }],
+        'target',
+      );
+
+      expect(merged.find(e => e.code === 'ja')).toBeDefined();
+      expect(merged.length).toBeGreaterThan(100);
+    });
+
+    it('should take the API list as given for the role being listed', () => {
+      // The client already filters by usable_as_source/usable_as_target, so the
+      // union trusts whichever list it is handed for that role.
+      const sourceMerged = languagesCommand.mergeWithRegistry(
+        [{ language: 'xx' as LanguageInfo['language'], name: 'Testish' }],
+        'source',
+      );
+
+      expect(sourceMerged.find(e => e.code === 'xx')).toBeDefined();
+      expect(sourceMerged.find(e => e.code === 'en-gb')).toBeUndefined();
+    });
+  });
+
   describe('partitionFeatureKeys()', () => {
     const entry = (
       code: string,

From 2e35795d662b3bcd59494d1e792ff8d673ea4eb0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 13:30:29 -0400
Subject: [PATCH 022/256] docs(languages): document API-as-authority and the
 125-language list

Counts move from 121 to 125 and regional from 7 to 11 across README, API.md
and the languages example. API.md and README gain a section on where the list
comes from: the API is authoritative, the bundled list is a generated snapshot
for offline use, well-formed unknown codes are passed to the API, and the
listing is the union of both. Also notes that the API gives a bare code and its
explicit-region variant the same name, so "German" appearing twice is expected.

CHANGELOG records the four unusable languages under Fixed and the shift of
authority under Changed. The release checklist gains the regeneration step,
since a stale snapshot no longer breaks translation but does go stale for
offline listing and the derived tiers.
---
 CHANGELOG.md             |  4 ++++
 CLAUDE.md                |  9 +++++----
 README.md                |  6 ++++--
 docs/API.md              | 14 +++++++++++---
 examples/24-languages.sh |  2 +-
 5 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 01dd118f..487bc120 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **languages**: **The DeepL API is now the authority on which languages exist, not the CLI's bundled list.** That list was hand-maintained, so it could silently fall behind the API and make languages the API accepts unusable — which is exactly what happened to `de-CH`, `de-DE`, `fr-CA` and `fr-FR` (see Fixed). Three changes remove the failure mode rather than just correcting the data. **Validation defers to the API:** a well-formed language code the bundled list does not contain is sent to the API, which accepts or rejects it authoritatively, instead of being rejected locally. Input that is not shaped like a language tag is still rejected immediately with a pointer to `deepl languages`, so typos like `--to grman` still fail fast without a request. This covers `translate`, `sync` and language values in the config file. **The listing is API-driven:** `deepl languages` renders the union of the API response and the bundled list, so a language DeepL offers can no longer be missing from the output. **The list is generated:** `npm run generate:languages` rewrites it from `GET /v3/languages` and `npm run check:languages` fails on drift, so it is a build artifact of the API rather than something maintained by hand. The core/regional/extended tiers are derived in the same pass — glossary support separates extended from the rest, source usability separates core from regional — which reproduces the previously hand-assigned tiers exactly, so the tiers can no longer disagree with the API either. No command line changes; `--to de` and every other existing code behave as before.
+
 - **cli**: **Language codes are displayed in lowercase everywhere.** Output previously mixed three casings: `deepl languages` printed lowercase from the registry, `glossary show` and `tm list` uppercased at display time, `translate`'s table uppercased the target language, and `write`/`correct` used BCP-47 (`en-GB`, `zh-Hans`). Lowercase matches the CLI's own normalized form, the registry, what `deepl languages` teaches users to type, and the wire format `/v3/languages` moved to; uppercase followed a v2-era docs convention that v3 abandons. **Scripts scraping these values will see a casing change** — `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"`. Input remains case-insensitive everywhere, so no command line has to change. `write`/`correct` also send the lowercase code as `target_lang`: the Write API accepts any casing and canonicalizes server-side (verified live on `/v2/write/rephrase` and `/v2/write/correct` — `en-gb`, `zh-hans`, and `zh-HANS` all return 200 and echo back `en-GB` / `zh-Hans`). Wire parameters that are not display are untouched: `translate` and the glossary create endpoint still send uppercase `target_lang`/`source_lang` as those endpoints document.
 - **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers now come from the language registry since the v3 response no longer reports formality support.
 
@@ -71,6 +73,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **languages**: **Four target languages the API accepts were unusable.** `de-CH` (Swiss German), `de-DE`, `fr-CA` (Canadian French) and `fr-FR` are returned by `GET /v3/languages` and accepted by the translate endpoint, but the CLI's bundled language list did not contain them, so `deepl translate --to de-CH` failed locally with `Invalid target language code` before any request was made — and the `deepl languages` the error suggested did not list them either, because the listing used the bundled list as its row set rather than the API response. Swiss German and Canadian French had no workaround; `de-DE`/`fr-FR` could be spelled `de`/`fr`. The list now contains all 125 languages the API serves (32 core, 11 regional, 82 extended). See the Changed entry below for why this class of divergence can no longer make a language unusable.
+
 - **languages**: `deepl languages --target` marks Portuguese (`pt`) with `[F]`. Formality support is now read from `features.formality` on `GET /v3/languages` instead of a static table in the language registry. The v3 migration had assumed v3 stopped reporting formality, but the capability was only renamed — v2's `supports_formality` boolean became the presence of a `formality` key in the per-language features matrix — so the CLI was answering from an 11-entry snapshot of the final v2 response that had already drifted from the API. The snapshot and the registry's `supportsFormality` field are gone; the registry's `category` tiers are unaffected. Output is otherwise unchanged: the `[F]` set is identical apart from `pt`.
 
 - **watch**: `--glossary` without `--from` now exits 6 before the watcher starts, instead of starting a session that fails on every single file change with a raw server message. The API rejects any translation naming a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"), which `translate` already guarded against up front for text, files, and documents; `watch` passed `--from` straight through. A long-running command is the worst place for this, since the operator saw the failure once per edit rather than once at launch. The check runs before the glossary name is resolved, so it costs no API call. `sync` needs no equivalent: it has no `--from` at all, taking the source language from the required `source_locale` field in `.deepl-sync.yaml`, so its requests always carry one.
diff --git a/CLAUDE.md b/CLAUDE.md
index d0fbecfb..3b5ed1cc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,10 +77,11 @@ Use **Semantic Versioning** with **Conventional Commits**:
 
 ### When Cutting a Release
 
-1. Move Unreleased items to `## [X.Y.Z] - YYYY-MM-DD`
-2. Set the version with `npm version X.Y.Z --no-git-tag-version` (updates `package.json` and the lockfile together; the release workflow refuses to publish if the tag and `package.json` disagree)
-3. Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z: <summary>"`
-4. Push: `git push && git push --tags`
+1. Refresh the bundled language list: `npm run generate:languages` (needs `DEEPL_API_KEY` and a current build). Commit it if it changed — `npm run check:languages` reports drift without writing. The list is a generated snapshot of `GET /v3/languages`; a stale one no longer breaks translation, since validation defers to the API, but `deepl languages` offline and the derived tiers do go stale
+2. Move Unreleased items to `## [X.Y.Z] - YYYY-MM-DD`
+3. Set the version with `npm version X.Y.Z --no-git-tag-version` (updates `package.json` and the lockfile together; the release workflow refuses to publish if the tag and `package.json` disagree)
+4. Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z: <summary>"`
+5. Push: `git push && git push --tags`
 
 ## Code Style
 
diff --git a/README.md b/README.md
index 915adff6..44207f30 100644
--- a/README.md
+++ b/README.md
@@ -1011,7 +1011,7 @@ deepl detect "Hola mundo" --format json
 
 #### Supported Languages
 
-List all 121 supported languages grouped by category:
+List all 125 supported languages grouped by category:
 
 ```bash
 # Show all supported languages (both source and target)
@@ -1067,11 +1067,13 @@ deepl languages
 **Note:** Languages are grouped into three categories:
 
 - **Core** (32) — Full feature support including formality and glossaries
-- **Regional** (7) — Target-only variants: `en-gb`, `en-us`, `es-419`, `pt-br`, `pt-pt`, `zh-hans`, `zh-hant`
+- **Regional** (11) — Target-only variants: `de-ch`, `de-de`, `en-gb`, `en-us`, `es-419`, `fr-ca`, `fr-fr`, `pt-br`, `pt-pt`, `zh-hans`, `zh-hant`
 - **Extended** (82) — Only support `quality_optimized` model, no formality or glossary
 
 `--features` is finer-grained than these tiers — some extended languages do support style rules and translation memory. It needs an API key, since the local registry carries no feature data. A feature only gets its own column when support differs across the languages listed; one supported by all of them is summarised on the last line instead of repeated on every row.
 
+**The API decides what exists.** `GET /v3/languages` is authoritative; the bundled list is a generated snapshot of it (`npm run generate:languages`) so that listing and validating languages works offline. Because a snapshot can lag the API, a well-formed language code it does not list is passed to the API rather than rejected locally — that is why `deepl translate --to de-CH` works even if your copy of the list predates Swiss German. Input that is not shaped like a language tag is still rejected immediately.
+
 See [examples/24-languages.sh](./examples/24-languages.sh) for a complete example.
 
 #### Configure Defaults
diff --git a/docs/API.md b/docs/API.md
index 0f6cc15e..0c9f3dbd 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -2354,7 +2354,7 @@ deepl languages [OPTIONS]
 
 #### Description
 
-Display all 121 supported languages grouped by category. Core and regional languages are shown first, followed by extended languages. When an API key is configured, language names are fetched from the DeepL API; otherwise, the local language registry is used.
+Display all 125 supported languages grouped by category. Core and regional languages are shown first, followed by extended languages. When an API key is configured, language names are fetched from the DeepL API; otherwise, the local language registry is used.
 
 You can filter to show only source languages, only target languages, or both (default).
 
@@ -2438,10 +2438,18 @@ deepl languages
 - `--features` replaces the `[F]` shorthand, since formality is one of the reported features
 - `--format json` includes a raw `features` object with each feature's status, but only when `--features` is passed
 
+**Where the language list comes from:**
+
+- `GET /v3/languages` is the authority on which languages exist. The CLI bundles a snapshot of it so that listing and validating languages works offline and without an API key
+- The snapshot is generated, not hand-maintained (`npm run generate:languages`; `npm run check:languages` reports drift). Tiers are derived from the response — glossary support separates extended from the rest, source usability separates core from regional — so they are not a separate judgement that can disagree with the API
+- Because the snapshot can lag the API, a **well-formed language code it does not list is accepted and sent to the API**, which accepts or rejects it authoritatively. Input that is not shaped like a language tag is still rejected locally, with a pointer to `deepl languages`. This applies to `translate`, `sync` and to language values in the config file
+- The listing itself is the union of the API response and the snapshot, so a language DeepL offers is never hidden even if the snapshot predates it
+
 **Notes:**
 
-- Source and target language lists differ: 7 regional variants (en-gb, en-us, es-419, pt-br, pt-pt, zh-hans, zh-hant) are target-only
+- Source and target language lists differ: 11 regional variants (de-ch, de-de, en-gb, en-us, es-419, fr-ca, fr-fr, pt-br, pt-pt, zh-hans, zh-hant) are target-only
 - Extended languages (82 codes) only support `quality_optimized` model type and do not support formality or glossary features
+- The API reports the same display name for a bare code and its explicit-region variant — both `de` and `de-de` are "German", both `fr` and `fr-fr` are "French". The CLI mirrors the API rather than inventing distinct names; the code column distinguishes them
 - The extended tier is a coarser signal than the feature matrix: some extended languages do support style rules and translation memory even though they support neither formality nor glossary
 - Without an API key, the command shows all languages from the local registry with a warning; `--features` additionally warns that it needs a key
 
@@ -2495,7 +2503,7 @@ echo "$LANG"  # es
 - Requires an API key (the detection uses a translate API call)
 - Each detection call consumes character quota (the text is translated to produce the detection)
 - Very short text (single characters or words) may produce unreliable detection results
-- Supports all 121 languages recognized by the DeepL API (core, regional, and extended)
+- Supports all 125 languages recognized by the DeepL API (core, regional, and extended)
 
 ---
 
diff --git a/examples/24-languages.sh b/examples/24-languages.sh
index 8f1d3280..cb44e25c 100755
--- a/examples/24-languages.sh
+++ b/examples/24-languages.sh
@@ -93,7 +93,7 @@ echo
 
 echo "💡 Language categories:"
 echo "   - Core (32): Full support - formality, glossaries, all model types"
-echo "   - Regional (7): Target-only variants (en-us, en-gb, pt-br, etc.)"
+echo "   - Regional (11): Target-only variants (en-us, en-gb, de-ch, fr-ca, pt-br, etc.)"
 echo "   - Extended (82): quality_optimized only, no formality or glossaries"
 echo "   - --features is finer-grained than these tiers: some extended languages"
 echo "     do support style rules and translation memory"

From 253ccd96911c7a3202f84c2862836ffd575cf057 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 13:40:50 -0400
Subject: [PATCH 023/256] test(languages): stop the regional-variant assertions
 depending on colour

The row assertions anchored on leading whitespace, but the code is chalk.cyan'd,
so wherever colour is forced on the line reads "  \e[36mde-ch    \e[39m German
(Swiss)" and the anchor lands on the escape sequence instead of the code. The
test passed in a NO_COLOR environment and failed in one with FORCE_COLOR set.

Passes noColor so the assertion sees the text it is written against, and
excludeApiKey so the graceful-degradation case reads the snapshot rather than
quietly calling the live API when a key happens to be configured. The rows now
assert code and name together, which also pins de-de and fr-fr carrying the
API's duplicate names.
---
 .../cli-languages.integration.test.ts          | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/tests/integration/cli-languages.integration.test.ts b/tests/integration/cli-languages.integration.test.ts
index 1a6b4a04..a23188c1 100644
--- a/tests/integration/cli-languages.integration.test.ts
+++ b/tests/integration/cli-languages.integration.test.ts
@@ -48,12 +48,18 @@ describe('Languages CLI Integration', () => {
     });
 
     it('should list the regional variants the snapshot previously omitted', () => {
-      const output = runCLI('deepl languages --target', { apiKey: '' });
-
-      expect(output).toContain('German (Swiss)');
-      expect(output).toContain('French (Canadian)');
-      expect(output).toMatch(/^\s+de-ch\s/m);
-      expect(output).toMatch(/^\s+fr-fr\s/m);
+      // noColor because the code is chalk.cyan'd, so anchoring on the row would
+      // otherwise trip over the escape sequence wherever colour is forced on;
+      // excludeApiKey to read the snapshot rather than the live API.
+      const output = runCLI('deepl languages --target', {
+        excludeApiKey: true,
+        noColor: true,
+      });
+
+      expect(output).toMatch(/^\s+de-ch\s+German \(Swiss\)$/m);
+      expect(output).toMatch(/^\s+fr-ca\s+French \(Canadian\)$/m);
+      expect(output).toMatch(/^\s+de-de\s+German$/m);
+      expect(output).toMatch(/^\s+fr-fr\s+French$/m);
     });
   });
 

From c955ca27b6a8737b4274f821e16e91b02c0d3b01 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 13:41:34 -0400
Subject: [PATCH 024/256] docs(changelog): note the ten display names the API
 differs on
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Generating the language list replaced ten hand-written names with the API's own
(Norwegian Bokmål -> Norwegian (bokmål), Chinese (Simplified) -> Chinese
(simplified), Central Kurdish -> Kurdish (Sorani), and seven more). Worth
recording because this changelog flags output that scripts may scrape, though
the effect is limited to the no-API-key path: with a key the API name already
won at display time, so keyed output is unchanged and offline output now agrees
with it.
---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 487bc120..1315a929 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **languages**: **The DeepL API is now the authority on which languages exist, not the CLI's bundled list.** That list was hand-maintained, so it could silently fall behind the API and make languages the API accepts unusable — which is exactly what happened to `de-CH`, `de-DE`, `fr-CA` and `fr-FR` (see Fixed). Three changes remove the failure mode rather than just correcting the data. **Validation defers to the API:** a well-formed language code the bundled list does not contain is sent to the API, which accepts or rejects it authoritatively, instead of being rejected locally. Input that is not shaped like a language tag is still rejected immediately with a pointer to `deepl languages`, so typos like `--to grman` still fail fast without a request. This covers `translate`, `sync` and language values in the config file. **The listing is API-driven:** `deepl languages` renders the union of the API response and the bundled list, so a language DeepL offers can no longer be missing from the output. **The list is generated:** `npm run generate:languages` rewrites it from `GET /v3/languages` and `npm run check:languages` fails on drift, so it is a build artifact of the API rather than something maintained by hand. The core/regional/extended tiers are derived in the same pass — glossary support separates extended from the rest, source usability separates core from regional — which reproduces the previously hand-assigned tiers exactly, so the tiers can no longer disagree with the API either. No command line changes; `--to de` and every other existing code behave as before.
 
+- **languages**: **Ten display names changed to match the API**, a consequence of generating the language list rather than hand-writing it: `ckb` Central Kurdish → Kurdish (Sorani), `es-419` Spanish (Latin America) → Spanish (Latin American), `gom` Goan Konkani → Konkani, `kmr` Northern Kurdish → Kurdish (Kurmanji), `my` Myanmar (Burmese) → Burmese, `nb` Norwegian Bokmål → Norwegian (bokmål), `pam` Pampanga → Kapampangan, `st` Southern Sotho → Sesotho, `zh-hans` Chinese (Simplified) → Chinese (simplified), `zh-hant` Chinese (Traditional) → Chinese (traditional). **Only offline output changes**: with an API key configured, `deepl languages` already took names from the API and was therefore already showing these, so this makes the no-API-key output consistent with the keyed output rather than changing what keyed users saw. Language codes are unaffected, so nothing that selects a language by code has to change; only output that scrapes display names.
+
 - **cli**: **Language codes are displayed in lowercase everywhere.** Output previously mixed three casings: `deepl languages` printed lowercase from the registry, `glossary show` and `tm list` uppercased at display time, `translate`'s table uppercased the target language, and `write`/`correct` used BCP-47 (`en-GB`, `zh-Hans`). Lowercase matches the CLI's own normalized form, the registry, what `deepl languages` teaches users to type, and the wire format `/v3/languages` moved to; uppercase followed a v2-era docs convention that v3 abandons. **Scripts scraping these values will see a casing change** — `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"`. Input remains case-insensitive everywhere, so no command line has to change. `write`/`correct` also send the lowercase code as `target_lang`: the Write API accepts any casing and canonicalizes server-side (verified live on `/v2/write/rephrase` and `/v2/write/correct` — `en-gb`, `zh-hans`, and `zh-HANS` all return 200 and echo back `en-GB` / `zh-Hans`). Wire parameters that are not display are untouched: `translate` and the glossary create endpoint still send uppercase `target_lang`/`source_lang` as those endpoints document.
 - **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers now come from the language registry since the v3 response no longer reports formality support.
 

From b69494a6e9eafb13ff970d83f150ca90b1e05185 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 14:07:10 -0400
Subject: [PATCH 025/256] feat(translate): preflight a named glossary against
 the requested pair
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Translation memories already refused a name that did not cover the requested
language pair, locally and before any request. Glossaries did not: the request
went out and the API answered "No dictionary found for language pair EN-DE in
glossary <uuid>", naming a UUID the user never typed.

resolveGlossaryId now takes the same optional `expected` pair that
resolveTranslationMemoryId does and reports what the glossary actually covers.
It costs no extra request, because resolving a name already fetches the
glossary list. Matching is per dictionary, so a glossary holding en→es and
de→fr is not read as covering en→fr, and every target of a multi-target
translation must be covered.

Two paths deliberately skip the check: a UUID is trusted and left to the API,
matching translation-memory behaviour and leaving an escape hatch if the check
is ever wrong; and a glossary the API reports with no dictionaries says nothing
about coverage, so it is not rejected on no evidence.

The pair is threaded from the text/file path via applySharedTmAndGlossary and
from the document path, both of which already require --from with --glossary.
Existing call-site assertions now pin the pair rather than just the name.
---
 CHANGELOG.md                                  |   2 +
 docs/API.md                                   |  14 +-
 .../translate/document-translation-handler.ts |   5 +-
 src/cli/commands/translate/translate-utils.ts |   8 +-
 .../translate/translation-options-factory.ts  |  11 +-
 src/services/glossary.ts                      |  43 +++++-
 tests/unit/file-translation-handler.test.ts   |   2 +-
 tests/unit/glossary-service.test.ts           | 126 ++++++++++++++++++
 tests/unit/translate-command.test.ts          |  12 +-
 tests/unit/translate-utils.test.ts            |  18 ++-
 .../unit/translation-options-factory.test.ts  |  17 ++-
 11 files changed, 239 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1315a929..85edea4f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **translate**: **A glossary referenced by name is checked against the requested language pair before any translation request.** Previously only translation memories did this; a glossary whose dictionaries did not cover the pair reached the API and came back as `No dictionary found for language pair EN-DE in glossary <uuid>`, naming a UUID the user never typed. It now fails locally, exit 7, naming what the glossary actually covers: `Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.` This costs no extra request, because the glossary list is already fetched to resolve the name. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr is not treated as covering en→fr, and when translating to several targets at once every one of them must be covered. Two deliberate exemptions: a glossary passed as a **UUID** is trusted and left to the API, matching how translation-memory resolution already behaves and giving an escape hatch if the check is ever wrong; and a glossary the API reports with no dictionaries is left alone, since that says nothing about coverage.
+
 - **languages**: **The DeepL API is now the authority on which languages exist, not the CLI's bundled list.** That list was hand-maintained, so it could silently fall behind the API and make languages the API accepts unusable — which is exactly what happened to `de-CH`, `de-DE`, `fr-CA` and `fr-FR` (see Fixed). Three changes remove the failure mode rather than just correcting the data. **Validation defers to the API:** a well-formed language code the bundled list does not contain is sent to the API, which accepts or rejects it authoritatively, instead of being rejected locally. Input that is not shaped like a language tag is still rejected immediately with a pointer to `deepl languages`, so typos like `--to grman` still fail fast without a request. This covers `translate`, `sync` and language values in the config file. **The listing is API-driven:** `deepl languages` renders the union of the API response and the bundled list, so a language DeepL offers can no longer be missing from the output. **The list is generated:** `npm run generate:languages` rewrites it from `GET /v3/languages` and `npm run check:languages` fails on drift, so it is a build artifact of the API rather than something maintained by hand. The core/regional/extended tiers are derived in the same pass — glossary support separates extended from the rest, source usability separates core from regional — which reproduces the previously hand-assigned tiers exactly, so the tiers can no longer disagree with the API either. No command line changes; `--to de` and every other existing code behave as before.
 
 - **languages**: **Ten display names changed to match the API**, a consequence of generating the language list rather than hand-writing it: `ckb` Central Kurdish → Kurdish (Sorani), `es-419` Spanish (Latin America) → Spanish (Latin American), `gom` Goan Konkani → Konkani, `kmr` Northern Kurdish → Kurdish (Kurmanji), `my` Myanmar (Burmese) → Burmese, `nb` Norwegian Bokmål → Norwegian (bokmål), `pam` Pampanga → Kapampangan, `st` Southern Sotho → Sesotho, `zh-hans` Chinese (Simplified) → Chinese (simplified), `zh-hant` Chinese (Traditional) → Chinese (traditional). **Only offline output changes**: with an API key configured, `deepl languages` already took names from the API and was therefore already showing these, so this makes the no-API-key output consistent with the keyed output rather than changing what keyed users saw. Language codes are unaffected, so nothing that selects a language by code has to change; only output that scrapes display names.
diff --git a/docs/API.md b/docs/API.md
index 0c9f3dbd..fa2d82f0 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -552,7 +552,7 @@ deepl translate README.md --from en --to fr --glossary abc-123-def-456 --output
 
 **Multiple glossaries on one request:**
 
-Repeat `--glossary` to apply up to 5 glossaries to a single request. Their entries are merged, so terms unique to each glossary all apply. When more than one glossary defines the same source term, the **last** `--glossary` on the command line wins — order is significant, and reordering the flags produces a different translation (and a separate cache entry). Names and UUIDs can be mixed; each value is resolved independently. A 6th `--glossary` exits 6 (ValidationError), and an unresolvable name exits 7 (ConfigError) without sending a translation request.
+Repeat `--glossary` to apply up to 5 glossaries to a single request. Their entries are merged, so terms unique to each glossary all apply. When more than one glossary defines the same source term, the **last** `--glossary` on the command line wins — order is significant, and reordering the flags produces a different translation (and a separate cache entry). Names and UUIDs can be mixed; each value is resolved independently. A 6th `--glossary` exits 6 (ValidationError). A name that cannot be resolved — unknown, ambiguous, or covering a different language pair than the one requested — exits 7 (ConfigError) without sending a translation request.
 
 ```bash
 # Shared base terminology, overridden by project-specific terms
@@ -587,7 +587,17 @@ deepl translate "Welcome to our product." --from en --to de \
 
 **Multi-target file translation with glossary / TM:**
 
-Both `--glossary` and `--translation-memory` apply to multi-target file translation (e.g. `--to en,fr,es`) and in that mode `--from` is required. Glossary name resolution works transparently across all target languages. Translation memory name resolution, however, requires a single TM that covers every requested target language pair — because each TM in DeepL is scoped to one source→target pair, using a TM name with differing multi-targets surfaces a `ConfigError` (exit 7). For multi-target TM use, pass the TM UUID directly.
+Both `--glossary` and `--translation-memory` apply to multi-target file translation (e.g. `--to en,fr,es`) and in that mode `--from` is required. Resolving either **by name** checks that the resource covers every requested language pair before any translation request goes out, and exits 7 (`ConfigError`) naming what it does cover if not:
+
+```bash
+deepl translate "hello" --from en --to de --glossary "EN-ES Test Glossary"
+# Error: Glossary "EN-ES Test Glossary" does not support the requested language pair
+# Suggestion: Glossary covers en→es; requested en→de.
+```
+
+A multilingual glossary satisfies this when it holds a dictionary for each requested pair; matching is per dictionary, so a glossary holding en→es and de→fr does not count as covering en→fr. Each translation memory in DeepL is scoped to one source→target pair, so a TM name with differing multi-targets cannot satisfy it at all — pass the TM UUID for multi-target TM use.
+
+Passing a **UUID** skips the check and lets the API decide, which is the escape hatch if the check is ever wrong: the API answers with `No dictionary found for language pair EN-DE in glossary <id>`.
 
 ```bash
 # Glossary across multiple targets (name resolution works for all targets)
diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index 70116a36..fa6be7b0 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -1,6 +1,7 @@
 import ora from 'ora';
 import { Logger } from '../../../utils/logger.js';
 import { ValidationError } from '../../../utils/errors.js';
+import type { Language } from '../../../types/index.js';
 import type { DocumentTranslationOptions } from '../../../types/api.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
 import { warnIgnoredOptions, validateLanguageCodes } from './translate-utils.js';
@@ -34,7 +35,9 @@ export class DocumentTranslationHandler {
 
     const translationOptions = buildBaseTranslationOptions(options);
 
-    await applyGlossarySelection(translationOptions, options, this.ctx.glossaryService);
+    await applyGlossarySelection(translationOptions, options, this.ctx.glossaryService, [
+      options.to as Language,
+    ]);
 
     if (options.outputFormat) {
       translationOptions.outputFormat = options.outputFormat;
diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index 6025a3fc..654b05ef 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -134,8 +134,12 @@ export function buildTranslationOptions(options: TranslateOptions): TranslationP
   return result;
 }
 
-export async function resolveGlossaryId(glossaryService: GlossaryService, nameOrId: string): Promise<string> {
-  return glossaryService.resolveGlossaryId(nameOrId);
+export async function resolveGlossaryId(
+  glossaryService: GlossaryService,
+  nameOrId: string,
+  expected?: { from: Language; targets: Language[] },
+): Promise<string> {
+  return glossaryService.resolveGlossaryId(nameOrId, expected);
 }
 
 export function isFilePath(input: string, cachedStats: fs.Stats | null | undefined, fileTranslationService: FileTranslationService): boolean {
diff --git a/src/cli/commands/translate/translation-options-factory.ts b/src/cli/commands/translate/translation-options-factory.ts
index 4e353166..1e59800e 100644
--- a/src/cli/commands/translate/translation-options-factory.ts
+++ b/src/cli/commands/translate/translation-options-factory.ts
@@ -44,16 +44,23 @@ export async function applyGlossarySelection<
   base: T,
   options: TranslateOptions,
   glossaryService: GlossaryService,
+  targets?: Language[],
 ): Promise<void> {
   if (!options.glossary || options.glossary.length === 0) {
     return;
   }
 
+  // --glossary already requires --from, so the pair is always known here.
+  const expected =
+    options.from && targets && targets.length > 0
+      ? { from: options.from as Language, targets }
+      : undefined;
+
   // Resolved sequentially so the service's resolution cache is populated
   // before the next name-or-ID lookup needs the glossary list.
   const ids: string[] = [];
   for (const nameOrId of options.glossary) {
-    ids.push(await resolveGlossaryId(glossaryService, nameOrId));
+    ids.push(await resolveGlossaryId(glossaryService, nameOrId, expected));
   }
 
   const [only] = ids;
@@ -104,7 +111,7 @@ export async function applySharedTmAndGlossary<
   options: TranslateOptions,
   deps: SharedTmAndGlossaryDeps,
 ): Promise<void> {
-  await applyGlossarySelection(base, options, deps.glossaryService);
+  await applyGlossarySelection(base, options, deps.glossaryService, deps.targets);
 
   if (options.translationMemory) {
     const cache = deps.tmCache ?? new Map<string, string>();
diff --git a/src/services/glossary.ts b/src/services/glossary.ts
index 98a1c244..135f8bae 100644
--- a/src/services/glossary.ts
+++ b/src/services/glossary.ts
@@ -160,12 +160,26 @@ export class GlossaryService {
   /**
    * Resolve a glossary name or ID to a glossary ID.
    * If the input is a UUID, returns it directly. Otherwise looks up by name.
+   *
+   * When `expected` is given, the resolved glossary's dictionaries must cover
+   * that language pair, which turns "No dictionary found for language pair
+   * EN-DE" from the API into a local error naming what the glossary does cover.
+   * Matching is per dictionary, so a glossary holding en→es and de→fr is not
+   * read as also covering en→fr. Free on this path because the list is already
+   * fetched to resolve the name; the UUID path trusts the caller and skips the
+   * check, as translation-memory resolution does.
    */
-  async resolveGlossaryId(nameOrId: string): Promise<string> {
+  async resolveGlossaryId(
+    nameOrId: string,
+    expected?: { from: Language; targets: Language[] },
+  ): Promise<string> {
     if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(nameOrId)) {
       return nameOrId;
     }
-    const cached = this.resolutionCache.get(nameOrId);
+    const cacheKey = expected
+      ? `${nameOrId}|${expected.from.toLowerCase()}|${expected.targets.map(t => t.toLowerCase()).join(',')}`
+      : nameOrId;
+    const cached = this.resolutionCache.get(cacheKey);
     if (cached !== undefined) {
       Logger.verbose(`[verbose] Glossary cache hit: "${nameOrId}" -> ${cached}`);
       return cached;
@@ -183,7 +197,30 @@ export class GlossaryService {
     if (!match) {
       throw new ConfigError(`Glossary "${sanitizeForError(nameOrId)}" not found`);
     }
-    this.resolutionCache.set(nameOrId, match.glossary_id);
+
+    // An empty dictionary list says nothing about coverage, so leave the
+    // judgement to the API rather than rejecting on no evidence.
+    if (expected && match.dictionaries.length > 0) {
+      const from = expected.from.toLowerCase();
+      const covered = (target: string): boolean =>
+        match.dictionaries.some(
+          d =>
+            d.source_lang.toLowerCase() === from &&
+            d.target_lang.toLowerCase() === target.toLowerCase(),
+        );
+      const missing = expected.targets.filter(target => !covered(target));
+      if (missing.length > 0) {
+        const pairs = match.dictionaries
+          .map(d => `${d.source_lang.toLowerCase()}→${d.target_lang.toLowerCase()}`)
+          .join(', ');
+        throw new ConfigError(
+          `Glossary "${sanitizeForError(nameOrId)}" does not support the requested language pair`,
+          `Glossary covers ${pairs}; requested ${from}→${missing.map(t => t.toLowerCase()).join(',')}.`,
+        );
+      }
+    }
+
+    this.resolutionCache.set(cacheKey, match.glossary_id);
     Logger.verbose(`[verbose] Resolved glossary "${nameOrId}" -> ${match.glossary_id}`);
     return match.glossary_id;
   }
diff --git a/tests/unit/file-translation-handler.test.ts b/tests/unit/file-translation-handler.test.ts
index b222a2db..9b9e393e 100644
--- a/tests/unit/file-translation-handler.test.ts
+++ b/tests/unit/file-translation-handler.test.ts
@@ -197,7 +197,7 @@ describe('FileTranslationHandler', () => {
         }));
 
         expect(mocks.glossaryService.resolveGlossaryId).toHaveBeenCalledTimes(1);
-        expect(mocks.glossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+        expect(mocks.glossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', { from: 'en', targets: ['de', 'fr'] });
         const call = mocks.fileTranslationService.translateFileToMultiple.mock.calls[0]!;
         expect(call[2]).toEqual(expect.objectContaining({ glossaryId: 'glossary-abc-123' }));
       });
diff --git a/tests/unit/glossary-service.test.ts b/tests/unit/glossary-service.test.ts
index 4b488b1f..73ad70ac 100644
--- a/tests/unit/glossary-service.test.ts
+++ b/tests/unit/glossary-service.test.ts
@@ -341,6 +341,132 @@ describe('GlossaryService', () => {
       expect(mockDeepLClient.listGlossaries).not.toHaveBeenCalled();
     });
 
+    describe('language-pair preflight', () => {
+      const listing = (dictionaries: Array<{ source_lang: string; target_lang: string }>) => [
+        {
+          glossary_id: 'found-glossary-id',
+          name: 'tech-terms',
+          source_lang: dictionaries[0]!.source_lang,
+          target_langs: dictionaries.map(d => d.target_lang),
+          dictionaries: dictionaries.map(d => ({ ...d, entry_count: 1 })),
+          creation_time: '2024-01-01T00:00:00Z',
+        },
+      ];
+
+      it('should resolve when a dictionary covers the requested pair', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'en', target_lang: 'es' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es'] }),
+        ).resolves.toBe('found-glossary-id');
+      });
+
+      it('should reject when no dictionary covers the requested target', async () => {
+        expect.assertions(2);
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'en', target_lang: 'es' }]) as never,
+        );
+
+        try {
+          await glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['de'] });
+        } catch (error) {
+          expect((error as Error).message).toContain('does not support the requested language pair');
+          expect((error as ConfigError).suggestion).toContain('en→es');
+        }
+      });
+
+      it('should reject when the source language does not match', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'en', target_lang: 'es' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'de', targets: ['es'] }),
+        ).rejects.toThrow('does not support the requested language pair');
+      });
+
+      it('should require every requested target to be covered', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([
+            { source_lang: 'en', target_lang: 'es' },
+            { source_lang: 'en', target_lang: 'fr' },
+          ]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es', 'fr'] }),
+        ).resolves.toBe('found-glossary-id');
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es', 'de'] }),
+        ).rejects.toThrow('does not support the requested language pair');
+      });
+
+      it('should match per dictionary rather than across derived source and target lists', async () => {
+        // en→es and de→fr must not be read as also covering en→fr.
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([
+            { source_lang: 'en', target_lang: 'es' },
+            { source_lang: 'de', target_lang: 'fr' },
+          ]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['fr'] }),
+        ).rejects.toThrow('does not support the requested language pair');
+      });
+
+      it('should compare languages case-insensitively', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'EN', target_lang: 'ES' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es'] }),
+        ).resolves.toBe('found-glossary-id');
+      });
+
+      it('should skip the check for a UUID, trusting the caller', async () => {
+        const uuid = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
+
+        await expect(
+          glossaryService.resolveGlossaryId(uuid, { from: 'en', targets: ['de'] }),
+        ).resolves.toBe(uuid);
+        expect(mockDeepLClient.listGlossaries).not.toHaveBeenCalled();
+      });
+
+      it('should skip the check when the glossary reports no dictionaries', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue([
+          {
+            glossary_id: 'empty-glossary-id',
+            name: 'tech-terms',
+            source_lang: 'en',
+            target_langs: [],
+            dictionaries: [],
+            creation_time: '2024-01-01T00:00:00Z',
+          },
+        ] as never);
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['de'] }),
+        ).resolves.toBe('empty-glossary-id');
+      });
+
+      it('should not let a cached resolution skip the check for a different pair', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'en', target_lang: 'es' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es'] }),
+        ).resolves.toBe('found-glossary-id');
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['de'] }),
+        ).rejects.toThrow('does not support the requested language pair');
+      });
+    });
+
     it('should emit a verbose log with resolved glossary name -> UUID after name lookup', async () => {
       mockDeepLClient.listGlossaries.mockResolvedValue([
         {
diff --git a/tests/unit/translate-command.test.ts b/tests/unit/translate-command.test.ts
index 34622332..0c9a6c73 100644
--- a/tests/unit/translate-command.test.ts
+++ b/tests/unit/translate-command.test.ts
@@ -1193,7 +1193,7 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('Hallo Welt');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', { from: 'en', targets: ['de'] });
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello world',
         { targetLang: 'de', sourceLang: 'en', glossaryId: 'glossary-123' },
@@ -1216,7 +1216,7 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('Bonjour le monde');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('01234567-89ab-cdef-0123-456789abcdef');
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('01234567-89ab-cdef-0123-456789abcdef', { from: 'en', targets: ['fr'] });
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello world',
         { targetLang: 'fr', sourceLang: 'en', glossaryId: '01234567-89ab-cdef-0123-456789abcdef' },
@@ -1255,7 +1255,7 @@ describe('TranslateCommand', () => {
         })
       ).rejects.toThrow('Glossary "non-existent" not found');
 
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('non-existent');
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('non-existent', { from: 'en', targets: ['de'] });
     });
 
     it('should translate to multiple languages with glossary', async () => {
@@ -1273,7 +1273,7 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('[de] Hallo\n[fr] Bonjour');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('tech-terms');
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('tech-terms', { from: 'en', targets: ['de', 'fr'] });
       expect(mockTranslationService.translateToMultiple).toHaveBeenCalledWith(
         'Hello',
         ['de', 'fr'],
@@ -1298,7 +1298,7 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('Sehr geehrte Damen und Herren');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('business-glossary');
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('business-glossary', { from: 'en', targets: ['de'] });
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Dear Sir or Madam',
         {
@@ -3325,7 +3325,7 @@ describe('TranslateCommand', () => {
         glossary: ['my-glossary'],
       });
 
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', { from: 'en', targets: ['es'] });
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello',
         expect.objectContaining({ glossaryId: 'glossary-file-123' }),
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index 3575a4c3..bb97d42b 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -589,7 +589,23 @@ describe('translate-utils', () => {
       const result = await resolveGlossaryId(mockGlossaryService, 'my-glossary');
 
       expect(result).toBe('glossary-123');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', undefined);
+    });
+
+    it('should forward the expected language pair for the preflight check', async () => {
+      const mockGlossaryService = {
+        resolveGlossaryId: jest.fn().mockResolvedValue('glossary-123'),
+      } as unknown as GlossaryService;
+
+      await resolveGlossaryId(mockGlossaryService, 'my-glossary', {
+        from: 'en',
+        targets: ['de'],
+      });
+
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+        from: 'en',
+        targets: ['de'],
+      });
     });
 
     it('should pass through errors from glossaryService', async () => {
diff --git a/tests/unit/translation-options-factory.test.ts b/tests/unit/translation-options-factory.test.ts
index c0f3dad7..c8bd1f5c 100644
--- a/tests/unit/translation-options-factory.test.ts
+++ b/tests/unit/translation-options-factory.test.ts
@@ -88,7 +88,22 @@ describe('translation-options-factory', () => {
         targets: ['de'],
       });
       expect(base['glossaryId']).toBe('glos-123');
-      expect(glossarySvc.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+      // No `from` in these options, so there is no pair to preflight against.
+      expect(glossarySvc.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', undefined);
+    });
+
+    it('passes the requested language pair when from and targets are known', async () => {
+      glossarySvc.resolveGlossaryId.mockResolvedValue('glos-123');
+      const base: Record<string, unknown> = { targetLang: 'de' };
+      await applySharedTmAndGlossary(base, { to: 'de,fr', from: 'en', glossary: ['my-glossary'] }, {
+        glossaryService: glossarySvc,
+        translationService: translationSvc,
+        targets: ['de', 'fr'],
+      });
+      expect(glossarySvc.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+        from: 'en',
+        targets: ['de', 'fr'],
+      });
     });
 
     it('skips glossary resolution when options.glossary is absent', async () => {

From 011ae192d2c7bbfd59f28995d252143c79f89b05 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 14:17:03 -0400
Subject: [PATCH 026/256] refactor(write): generate the Write target languages
 from the API

The Write API's 14 target languages were hand-maintained in two places -- the
WRITE_LANGUAGES array and a separate WriteLanguage union in types/api.ts --
either of which could fall behind GET /v3/languages?resource=write the way the
translation list silently went four codes stale.

The generator now emits both language lists, and check:languages names which
one drifted rather than reporting a misleading translate_text count. The type
is derived from the generated list via `as const`, so a language added upstream
widens it on regenerate instead of needing a second hand edit.

No behaviour change: the generated list is byte-identical to the hand-written
one, and write/correct still reject an unknown code locally while enumerating
every valid option. That strictness is deliberate and not what translate does
-- at 14 of 125 languages, naming the options beats a round trip.

The style/tone support table in API.md stays hand-maintained on purpose: it
records what the API accepts, and resource=write omits writing_style for en
even though --style --lang en works. Noted there so it is not "corrected"
against the metadata later.
---
 CHANGELOG.md                           |  2 +
 CLAUDE.md                              |  2 +-
 docs/API.md                            |  8 +++
 scripts/generate-language-registry.mjs | 75 +++++++++++++++++++++-----
 src/cli/commands/register-write.ts     |  9 +++-
 src/data/language-entries.ts           | 29 ++++++++++
 src/types/api.ts                       | 22 +++-----
 tests/unit/language-registry.test.ts   | 32 +++++++++++
 tests/unit/register-write.test.ts      | 30 +++++++++++
 9 files changed, 180 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 85edea4f..8da717e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **translate**: **A glossary referenced by name is checked against the requested language pair before any translation request.** Previously only translation memories did this; a glossary whose dictionaries did not cover the pair reached the API and came back as `No dictionary found for language pair EN-DE in glossary <uuid>`, naming a UUID the user never typed. It now fails locally, exit 7, naming what the glossary actually covers: `Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.` This costs no extra request, because the glossary list is already fetched to resolve the name. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr is not treated as covering en→fr, and when translating to several targets at once every one of them must be covered. Two deliberate exemptions: a glossary passed as a **UUID** is trusted and left to the API, matching how translation-memory resolution already behaves and giving an escape hatch if the check is ever wrong; and a glossary the API reports with no dictionaries is left alone, since that says nothing about coverage.
 
+- **write**: **The Write API's 14 target languages are generated rather than hand-maintained**, closing the last hand-kept language list. The list and the `WriteLanguage` type were two separate hand-edited copies of the same set, either of which could fall behind `GET /v3/languages?resource=write` — the same way the translation list silently went four codes stale. `npm run generate:languages` now emits both language lists and `npm run check:languages` reports which one drifted; the type is derived from the generated list, so a language added upstream widens it on regenerate instead of needing a second edit. No behaviour change: the generated list is byte-identical to what was there, and `write`/`correct` still **reject** a code outside it locally while naming every valid option, deliberately unlike `translate --to`, which passes well-formed unknown codes to the API. At 14 of 125 languages an enumerated error beats a round trip. Note the documented style/tone support table is unchanged and still maintained by hand, because it records what the API accepts rather than what its metadata claims: `resource=write` omits `writing_style` for `en`, but `--style` with `--lang en` works.
+
 - **languages**: **The DeepL API is now the authority on which languages exist, not the CLI's bundled list.** That list was hand-maintained, so it could silently fall behind the API and make languages the API accepts unusable — which is exactly what happened to `de-CH`, `de-DE`, `fr-CA` and `fr-FR` (see Fixed). Three changes remove the failure mode rather than just correcting the data. **Validation defers to the API:** a well-formed language code the bundled list does not contain is sent to the API, which accepts or rejects it authoritatively, instead of being rejected locally. Input that is not shaped like a language tag is still rejected immediately with a pointer to `deepl languages`, so typos like `--to grman` still fail fast without a request. This covers `translate`, `sync` and language values in the config file. **The listing is API-driven:** `deepl languages` renders the union of the API response and the bundled list, so a language DeepL offers can no longer be missing from the output. **The list is generated:** `npm run generate:languages` rewrites it from `GET /v3/languages` and `npm run check:languages` fails on drift, so it is a build artifact of the API rather than something maintained by hand. The core/regional/extended tiers are derived in the same pass — glossary support separates extended from the rest, source usability separates core from regional — which reproduces the previously hand-assigned tiers exactly, so the tiers can no longer disagree with the API either. No command line changes; `--to de` and every other existing code behave as before.
 
 - **languages**: **Ten display names changed to match the API**, a consequence of generating the language list rather than hand-writing it: `ckb` Central Kurdish → Kurdish (Sorani), `es-419` Spanish (Latin America) → Spanish (Latin American), `gom` Goan Konkani → Konkani, `kmr` Northern Kurdish → Kurdish (Kurmanji), `my` Myanmar (Burmese) → Burmese, `nb` Norwegian Bokmål → Norwegian (bokmål), `pam` Pampanga → Kapampangan, `st` Southern Sotho → Sesotho, `zh-hans` Chinese (Simplified) → Chinese (simplified), `zh-hant` Chinese (Traditional) → Chinese (traditional). **Only offline output changes**: with an API key configured, `deepl languages` already took names from the API and was therefore already showing these, so this makes the no-API-key output consistent with the keyed output rather than changing what keyed users saw. Language codes are unaffected, so nothing that selects a language by code has to change; only output that scrapes display names.
diff --git a/CLAUDE.md b/CLAUDE.md
index 3b5ed1cc..122bfc0a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,7 +77,7 @@ Use **Semantic Versioning** with **Conventional Commits**:
 
 ### When Cutting a Release
 
-1. Refresh the bundled language list: `npm run generate:languages` (needs `DEEPL_API_KEY` and a current build). Commit it if it changed — `npm run check:languages` reports drift without writing. The list is a generated snapshot of `GET /v3/languages`; a stale one no longer breaks translation, since validation defers to the API, but `deepl languages` offline and the derived tiers do go stale
+1. Refresh the bundled language lists: `npm run generate:languages` (needs `DEEPL_API_KEY` and a current build). Commit if changed — `npm run check:languages` reports which list drifted without writing. Both come from `GET /v3/languages`: the translation snapshot (`resource=translate_text`) and the Write target list (`resource=write`). A stale translation snapshot no longer breaks translation, since validation defers to the API, but `deepl languages` offline and the derived tiers do go stale. **A stale Write list does break `write`/`correct`**, which reject unknown codes locally — so this step matters most for that list
 2. Move Unreleased items to `## [X.Y.Z] - YYYY-MM-DD`
 3. Set the version with `npm version X.Y.Z --no-git-tag-version` (updates `package.json` and the lockfile together; the release workflow refuses to publish if the tag and `package.json` disagree)
 4. Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z: <summary>"`
diff --git a/docs/API.md b/docs/API.md
index fa2d82f0..21240ffa 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -754,6 +754,14 @@ Enhance text quality with AI-powered grammar checking, style improvement, and to
 
 When `--style` or `--tone` is set for a target language that does not support it, the server returns a 4xx; the CLI converts that response into a `ValidationError` (exit code 6) that names the unsupported combination and points back to this table.
 
+This table is maintained by hand and reflects what the API **accepts**, which is not always what its metadata reports: `GET /v3/languages?resource=write` omits `writing_style` for `en`, yet `--style` with `--lang en` succeeds and returns what `--lang en-us` returns. Do not narrow this table to the metadata without re-checking behaviour.
+
+**Where the target-language list comes from:**
+
+The 14 languages are generated from `GET /v3/languages?resource=write` into `src/data/language-entries.ts` by `npm run generate:languages`, alongside the translation list, and `npm run check:languages` reports drift in either. The `WriteLanguage` type is derived from that same list, so a language added upstream widens it on regenerate rather than needing a second hand edit.
+
+Unlike `translate --to`, which passes a well-formed unknown code to the API, `write` and `correct` **reject** a code outside this list locally (exit 6) and name every valid option. The set is small enough to enumerate, so that beats a round trip — the reasoning that makes permissiveness right for translation does not transfer to 14 of 125 languages.
+
 **Output Options:**
 
 - `--alternatives, -a` - Show all improvement alternatives
diff --git a/scripts/generate-language-registry.mjs b/scripts/generate-language-registry.mjs
index cb6348cd..ed1780a5 100644
--- a/scripts/generate-language-registry.mjs
+++ b/scripts/generate-language-registry.mjs
@@ -42,19 +42,32 @@ if (!existsSync(DERIVATION)) {
 const { deriveLanguageEntry } = await import(DERIVATION);
 
 const host = apiKey.endsWith(':fx') ? 'https://api-free.deepl.com' : 'https://api.deepl.com';
-const response = await fetch(`${host}/v3/languages?resource=translate_text`, {
-  headers: { Authorization: `DeepL-Auth-Key ${apiKey}` },
-});
-if (!response.ok) {
-  fail(`GET /v3/languages returned ${response.status} ${response.statusText}`);
-}
 
-const languages = await response.json();
-if (!Array.isArray(languages) || languages.length === 0) {
-  fail('GET /v3/languages returned no languages');
+async function fetchResource(resource) {
+  const response = await fetch(`${host}/v3/languages?resource=${resource}`, {
+    headers: { Authorization: `DeepL-Auth-Key ${apiKey}` },
+  });
+  if (!response.ok) {
+    fail(`GET /v3/languages?resource=${resource} returned ${response.status} ${response.statusText}`);
+  }
+  const languages = await response.json();
+  if (!Array.isArray(languages) || languages.length === 0) {
+    fail(`GET /v3/languages?resource=${resource} returned no languages`);
+  }
+  return languages;
 }
 
+const languages = await fetchResource('translate_text');
+const writeLanguages = await fetchResource('write');
+
 const entries = languages.map(deriveLanguageEntry);
+// The write endpoints take a target language only, so the list is filtered by
+// that role rather than run through deriveLanguageEntry -- write has no notion
+// of the core/regional/extended tiers.
+const writeTargets = writeLanguages
+  .filter(language => language.usable_as_target)
+  .map(language => language.lang.toLowerCase())
+  .sort((a, b) => a.localeCompare(b, 'en'));
 const byCode = (a, b) => a.code.localeCompare(b.code, 'en');
 const groups = [
   ['core', 'Core languages (full feature support: formality, glossary, all model types)'],
@@ -93,16 +106,51 @@ import type { LanguageEntry } from './language-registry.js';
 export const ENTRIES: LanguageEntry[] = [
 ${body}
 ];
+
+/**
+ * Target languages the Write API accepts, from resource=write.
+ *
+ * Unlike translation, \`write\` and \`correct\` reject a code outside this list
+ * locally rather than deferring to the API: the supported set is small enough
+ * to enumerate in the error, so naming the valid options beats a round trip.
+ * That makes keeping this generated the thing that stops it going stale.
+ *
+ * \`as const\` is load-bearing -- the WriteLanguage union in src/types/api.ts is
+ * derived from it, so adding a language upstream widens the type on regenerate
+ * instead of needing a second hand edit.
+ */
+export const WRITE_TARGET_LANGUAGES = [
+${writeTargets.map(code => `  '${code}',`).join('\n')}
+] as const;
 `;
 
 if (checkOnly) {
   const current = existsSync(TARGET) ? readFileSync(TARGET, 'utf8') : '';
   if (current === contents) {
-    console.log(`${entries.length} languages; snapshot is current.`);
+    console.log(
+      `${entries.length} languages, ${writeTargets.length} write targets; snapshot is current.`,
+    );
     process.exit(0);
   }
+  // Name which list moved: the two are generated from different resources, and
+  // "N languages upstream" is misleading when it is the write list that drifted.
+  const codesIn = (source, open, close) => {
+    const start = source.indexOf(open);
+    if (start === -1) return '';
+    const from = start + open.length;
+    const end = source.indexOf(close, from);
+    return (source.slice(from, end === -1 ? undefined : end).match(/'[a-z0-9-]+'/g) ?? []).join(',');
+  };
+  const blocks = [
+    ['translate_text', `${entries.length}`, 'export const ENTRIES', '\n];'],
+    ['write', `${writeTargets.length}`, 'export const WRITE_TARGET_LANGUAGES', '] as const;'],
+  ];
+  const drifted = blocks
+    .filter(([, , open, close]) => codesIn(current, open, close) !== codesIn(contents, open, close))
+    .map(([name, count]) => `${name} (${count} upstream)`);
+  const detail = drifted.length > 0 ? drifted.join(', ') : 'formatting only';
   console.error(
-    `error: ${path.relative(ROOT, TARGET)} is out of date with the API (${entries.length} languages upstream).\n` +
+    `error: ${path.relative(ROOT, TARGET)} is out of date with the API -- ${detail}.\n` +
       'Run: npm run generate:languages',
   );
   process.exit(1);
@@ -110,4 +158,7 @@ if (checkOnly) {
 
 writeFileSync(TARGET, contents);
 const counts = groups.map(([c]) => `${c} ${entries.filter(e => e.category === c).length}`);
-console.log(`wrote ${path.relative(ROOT, TARGET)}: ${entries.length} languages (${counts.join(', ')})`);
+console.log(
+  `wrote ${path.relative(ROOT, TARGET)}: ${entries.length} languages (${counts.join(', ')}), ` +
+    `${writeTargets.length} write targets`,
+);
diff --git a/src/cli/commands/register-write.ts b/src/cli/commands/register-write.ts
index e0adb500..dba9f177 100644
--- a/src/cli/commands/register-write.ts
+++ b/src/cli/commands/register-write.ts
@@ -3,13 +3,20 @@ import { existsSync } from 'fs';
 import { atomicWriteFile } from '../../utils/atomic-write.js';
 import chalk from 'chalk';
 import type { WriteLanguage, WritingStyle, WriteTone } from '../../types/index.js';
+import { WRITE_TARGET_LANGUAGES } from '../../data/language-entries.js';
 import { Logger } from '../../utils/logger.js';
 import { ExitCode } from '../../utils/exit-codes.js';
 import { isNoInput } from '../../utils/confirm.js';
 import { ValidationError } from '../../utils/errors.js';
 import { createWriteCommand, type ServiceDeps } from './service-factory.js';
 
-export const WRITE_LANGUAGES = ['de', 'en', 'en-gb', 'en-us', 'es', 'fr', 'it', 'ja', 'ko', 'pt', 'pt-br', 'pt-pt', 'zh', 'zh-hans'] as const;
+/**
+ * Generated from GET /v3/languages?resource=write, so it cannot drift from what
+ * the API accepts. Unlike `translate --to`, a code outside this list is rejected
+ * locally rather than deferred to the API: at 14 entries the error can name every
+ * valid option, which beats a round trip.
+ */
+export const WRITE_LANGUAGES = WRITE_TARGET_LANGUAGES;
 /**
  * Codes are accepted in any casing and normalized to lowercase, matching
  * `translate --to` and the codes `deepl languages` prints. The Write API
diff --git a/src/data/language-entries.ts b/src/data/language-entries.ts
index 69de1c04..08092444 100644
--- a/src/data/language-entries.ts
+++ b/src/data/language-entries.ts
@@ -144,3 +144,32 @@ export const ENTRIES: LanguageEntry[] = [
   { code: 'yue', name: 'Cantonese', category: 'extended' },
   { code: 'zu', name: 'Zulu', category: 'extended' },
 ];
+
+/**
+ * Target languages the Write API accepts, from resource=write.
+ *
+ * Unlike translation, `write` and `correct` reject a code outside this list
+ * locally rather than deferring to the API: the supported set is small enough
+ * to enumerate in the error, so naming the valid options beats a round trip.
+ * That makes keeping this generated the thing that stops it going stale.
+ *
+ * `as const` is load-bearing -- the WriteLanguage union in src/types/api.ts is
+ * derived from it, so adding a language upstream widens the type on regenerate
+ * instead of needing a second hand edit.
+ */
+export const WRITE_TARGET_LANGUAGES = [
+  'de',
+  'en',
+  'en-gb',
+  'en-us',
+  'es',
+  'fr',
+  'it',
+  'ja',
+  'ko',
+  'pt',
+  'pt-br',
+  'pt-pt',
+  'zh',
+  'zh-hans',
+] as const;
diff --git a/src/types/api.ts b/src/types/api.ts
index fbdf6eb1..5aae2431 100644
--- a/src/types/api.ts
+++ b/src/types/api.ts
@@ -3,6 +3,7 @@
  */
 
 import { Language, Formality } from './common';
+import { WRITE_TARGET_LANGUAGES } from '../data/language-entries.js';
 
 export type ModelType =
   | 'quality_optimized'
@@ -45,21 +46,12 @@ export interface TranslationMemory {
   target_languages: string[];
 }
 
-export type WriteLanguage =
-  | 'de'
-  | 'en'
-  | 'en-gb'
-  | 'en-us'
-  | 'es'
-  | 'fr'
-  | 'it'
-  | 'ja'
-  | 'ko'
-  | 'pt'
-  | 'pt-br'
-  | 'pt-pt'
-  | 'zh'
-  | 'zh-hans';
+/**
+ * Target languages the Write API accepts. Derived from the generated snapshot
+ * so that adding a language upstream widens this on `npm run generate:languages`
+ * rather than needing a second, hand-kept copy of the same list.
+ */
+export type WriteLanguage = (typeof WRITE_TARGET_LANGUAGES)[number];
 
 export type WritingStyle =
   | 'default'
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index 8b2e9728..77f220d5 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -10,6 +10,7 @@ import {
   deriveLanguageEntry,
   looksLikeLanguageTag,
 } from '../../src/data/language-registry';
+import { WRITE_TARGET_LANGUAGES } from '../../src/data/language-entries';
 
 describe('Language Registry', () => {
   describe('LANGUAGE_REGISTRY', () => {
@@ -232,6 +233,37 @@ describe('Language Registry', () => {
     });
   });
 
+  describe('WRITE_TARGET_LANGUAGES', () => {
+    it('should be non-empty', () => {
+      expect(WRITE_TARGET_LANGUAGES.length).toBeGreaterThan(0);
+    });
+
+    it('should be lowercase and sorted, matching how the generator emits it', () => {
+      const codes = [...WRITE_TARGET_LANGUAGES];
+      expect(codes).toEqual(codes.map(c => c.toLowerCase()));
+      expect(codes).toEqual([...codes].sort((a, b) => a.localeCompare(b, 'en')));
+    });
+
+    it('should have no duplicates', () => {
+      expect(new Set(WRITE_TARGET_LANGUAGES).size).toBe(WRITE_TARGET_LANGUAGES.length);
+    });
+
+    it('should only contain languages the translate snapshot also knows', () => {
+      // Both lists come from the same GET /v3/languages, so a write target the
+      // main snapshot has never heard of means one of them was generated stale.
+      for (const code of WRITE_TARGET_LANGUAGES) {
+        expect(isValidLanguage(code)).toBe(true);
+      }
+    });
+
+    it('should be a subset of the target languages', () => {
+      const targets = new Set(getTargetLanguages().map(e => e.code));
+      for (const code of WRITE_TARGET_LANGUAGES) {
+        expect(targets.has(code)).toBe(true);
+      }
+    });
+  });
+
   describe('deriveLanguageEntry()', () => {
     const stable = { status: 'stable' };
 
diff --git a/tests/unit/register-write.test.ts b/tests/unit/register-write.test.ts
index 4a1367f9..95b3f9b0 100644
--- a/tests/unit/register-write.test.ts
+++ b/tests/unit/register-write.test.ts
@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import { WRITE_TARGET_LANGUAGES } from '../../src/data/language-entries';
 
 jest.mock('chalk', () => {
   const passthrough = (s: string) => s;
@@ -195,6 +196,35 @@ describe('registerWrite', () => {
       );
     });
 
+    it('should reject a well-formed code the Write API does not support', async () => {
+      // Deliberately stricter than `translate --to`, which passes well-formed
+      // unknown codes to the API: the Write set is small enough to enumerate,
+      // so naming the valid options beats a round trip.
+      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'hi']);
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: expect.stringContaining('Invalid language code') }),
+      );
+      expect(mockWriteCommand.improve).not.toHaveBeenCalled();
+    });
+
+    it('should enumerate every supported language in the rejection', async () => {
+      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'xx']);
+      const error = handleError.mock.calls[0]?.[0] as Error;
+      for (const code of WRITE_TARGET_LANGUAGES) {
+        expect(error.message).toContain(code);
+      }
+    });
+
+    it('should accept every language in the generated list', async () => {
+      for (const code of WRITE_TARGET_LANGUAGES) {
+        jest.clearAllMocks();
+        mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
+        mockWriteCommand.improve.mockResolvedValue('ok');
+        await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', code]);
+        expect(handleError).not.toHaveBeenCalled();
+      }
+    });
+
     it.each(['ja', 'ko', 'zh', 'zh-hans'])('should accept new target language %s', async (lang) => {
       mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
       mockWriteCommand.improve.mockResolvedValue('ok');

From 2211352b11130ad07b6c4b33fb0e44e4a4fa1742 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 14:31:43 -0400
Subject: [PATCH 027/256] feat(translate): pin tag_handling_version to v2
 instead of the server default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The version was sent only when --tag-handling-version was passed, so every
other tag-handling request inherited the API's default. That default is
documented as moving from v1 to v2, which would have shifted output with no
CLI change to attribute it to — and would have gone undetected by the cache,
since a request omitting the version hashes identically either side of the
flip.

One resolver feeds both the wire parameter and cache key field 10, so they
cannot disagree. An explicitly named version always wins, including v1;
requests without tag handling send nothing and keep their keys.
---
 CHANGELOG.md                            |  2 ++
 README.md                               |  4 +--
 docs/API.md                             |  2 +-
 src/api/translation-client.ts           |  6 ++--
 src/services/translation.ts             |  8 +++++-
 src/utils/tag-handling-version.ts       | 38 +++++++++++++++++++++++++
 tests/unit/deepl-client.test.ts         | 37 ++++++++++++++++++++++++
 tests/unit/tag-handling-version.test.ts | 35 +++++++++++++++++++++++
 tests/unit/translation-service.test.ts  | 33 +++++++++++++++++++++
 9 files changed, 159 insertions(+), 6 deletions(-)
 create mode 100644 src/utils/tag-handling-version.ts
 create mode 100644 tests/unit/tag-handling-version.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8da717e0..79543c8a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **translate**: **`--tag-handling` requests now pin `tag_handling_version=v2`** instead of letting the API pick. The CLI previously sent the parameter only when `--tag-handling-version` was passed, so everyone else inherited the server default — which DeepL documents as moving from v1 (deprecation-bound) to v2 at an unannounced date. That flip would have changed tag-handling output with no CLI change to point at, and worse, would have gone unnoticed by the cache: a request that omits the version hashes identically before and after, so cached v1 output would have kept being served after the API started returning v2. Adopting v2 now makes that one output shift deliberate and dated, and DeepL's own docs recommend v2 for structure handling. **`--tag-handling xml`/`html` output may differ from previous releases**; pass `--tag-handling-version v1` to keep the old behaviour, which is still honoured and always wins over the default. Requests without `--tag-handling` send no version and keep their existing cache keys; tag-handling entries cached by earlier versions now miss rather than being served stale, so the first such translation after upgrading is refetched.
+
 - **translate**: **A glossary referenced by name is checked against the requested language pair before any translation request.** Previously only translation memories did this; a glossary whose dictionaries did not cover the pair reached the API and came back as `No dictionary found for language pair EN-DE in glossary <uuid>`, naming a UUID the user never typed. It now fails locally, exit 7, naming what the glossary actually covers: `Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.` This costs no extra request, because the glossary list is already fetched to resolve the name. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr is not treated as covering en→fr, and when translating to several targets at once every one of them must be covered. Two deliberate exemptions: a glossary passed as a **UUID** is trusted and left to the API, matching how translation-memory resolution already behaves and giving an escape hatch if the check is ever wrong; and a glossary the API reports with no dictionaries is left alone, since that says nothing about coverage.
 
 - **write**: **The Write API's 14 target languages are generated rather than hand-maintained**, closing the last hand-kept language list. The list and the `WriteLanguage` type were two separate hand-edited copies of the same set, either of which could fall behind `GET /v3/languages?resource=write` — the same way the translation list silently went four codes stale. `npm run generate:languages` now emits both language lists and `npm run check:languages` reports which one drifted; the type is derived from the generated list, so a language added upstream widens it on regenerate instead of needing a second edit. No behaviour change: the generated list is byte-identical to what was there, and `write`/`correct` still **reject** a code outside it locally while naming every valid option, deliberately unlike `translate --to`, which passes well-formed unknown codes to the API. At 14 of 125 languages an enumerated error beats a round trip. Note the documented style/tone support table is unchanged and still maintained by hand, because it records what the API accepts rather than what its metadata claims: `resource=write` omits `writing_style` for `en`, but `--style` with `--lang en` works.
diff --git a/README.md b/README.md
index 44207f30..1e1b61ea 100644
--- a/README.md
+++ b/README.md
@@ -541,8 +541,8 @@ deepl translate "Cost analysis" --to es,fr,de --format table --show-billed-chara
 # Preview what would be translated without making API calls (file/directory mode)
 deepl translate ./docs --to es --dry-run
 
-# Specify tag handling version (v2 improves structure handling, requires --tag-handling)
-deepl translate page.html --to es --tag-handling html --tag-handling-version v2
+# Tag handling pins v2 (better structure handling); opt back into v1 explicitly
+deepl translate page.html --to es --tag-handling html --tag-handling-version v1
 
 # Advanced XML/HTML tag handling (requires --tag-handling xml)
 # Control automatic XML structure detection
diff --git a/docs/API.md b/docs/API.md
index 21240ffa..f4992bac 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -250,7 +250,7 @@ Translate text directly, from stdin, from files, or entire directories. Supports
 - `--splitting-tags TAGS` - Comma-separated XML tags that split sentences (requires `--tag-handling xml`)
 - `--non-splitting-tags TAGS` - Comma-separated XML tags that should not be used to split sentences (requires `--tag-handling xml`)
 - `--ignore-tags TAGS` - Comma-separated XML tags with content to ignore (requires `--tag-handling xml`)
-- `--tag-handling-version VERSION` - Tag handling version: `v1`, `v2`. v2 improves XML/HTML structure handling (requires `--tag-handling`)
+- `--tag-handling-version VERSION` - Tag handling version: `v1`, `v2`. v2 improves XML/HTML structure handling (requires `--tag-handling`). **Defaults to `v2`**, sent explicitly on every `--tag-handling` request rather than left to the API's own default, which is documented as moving from v1 to v2 at some point — pinning keeps output from shifting on DeepL's timetable. Pass `--tag-handling-version v1` for the older behaviour, which DeepL documents as heading for deprecation
 - `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. Repeatable, up to 5 per request; when several glossaries define the same source term, the last one given wins. Passing a 6th exits 6 (ValidationError).
 - `--translation-memory NAME-OR-UUID` - Use translation memory by name or UUID (forces `quality_optimized` model). Requires `--from` because TMs are pinned to a specific source→target language pair. Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
 - `--tm-threshold N` - Minimum match score 0–100 (default 75, requires `--translation-memory`). Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index 67246e4f..0588491f 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -3,6 +3,7 @@ import { TranslationOptions, Language, TranslationMemory } from '../types/index.
 import { NetworkError } from '../utils/errors.js';
 import { normalizeFormality } from '../utils/formality.js';
 import { resolveGlossaryWireParams } from '../utils/glossary-params.js';
+import { resolveTagHandlingVersion } from '../utils/tag-handling-version.js';
 import { Logger } from '../utils/logger.js';
 
 // DeepL's /v3/translation_memories endpoint paginates via `page` (0-indexed) and
@@ -391,8 +392,9 @@ export class TranslationClient extends HttpClient {
       params['style_id'] = options.styleId;
     }
 
-    if (options.tagHandlingVersion) {
-      params['tag_handling_version'] = options.tagHandlingVersion;
+    const tagHandlingVersion = resolveTagHandlingVersion(options);
+    if (tagHandlingVersion) {
+      params['tag_handling_version'] = tagHandlingVersion;
     }
 
 
diff --git a/src/services/translation.ts b/src/services/translation.ts
index af8be411..70f7e905 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -13,6 +13,7 @@ import { mapWithConcurrency, MULTI_TARGET_CONCURRENCY } from '../utils/concurren
 import { ValidationError } from '../utils/errors.js';
 import { errorMessage } from '../utils/error-message.js';
 import { resolveGlossaryWireParams } from '../utils/glossary-params.js';
+import { resolveTagHandlingVersion } from '../utils/tag-handling-version.js';
 import { preserveCodeBlocks, preserveVariables, restorePlaceholders } from '../utils/text-preservation.js';
 
 export { MULTI_TARGET_CONCURRENCY };
@@ -396,6 +397,11 @@ export class TranslationService {
    * not using them stay unchanged. `glossaryIds` is hashed in the caller's
    * order rather than sorted, because reordering the list changes which
    * glossary wins a conflicting term and therefore the translation itself.
+   *
+   * `tagHandlingVersion` is resolved rather than read straight off the options,
+   * so it holds the version the request will actually carry. Leaving it unset
+   * would let the key stay stable across a change of the API's own default,
+   * serving entries the API would no longer produce.
    */
   private generateCacheKey(text: string, options: TranslationOptions): string {
     // Keyed on the parameter the request will actually carry, so the two ways of
@@ -414,7 +420,7 @@ export class TranslationService {
       modelType: options.modelType,      // 7. Model type affects output quality
       splitSentences: options.splitSentences, // 8. Sentence splitting behavior
       tagHandling: options.tagHandling,  // 9. HTML/XML processing
-      tagHandlingVersion: options.tagHandlingVersion, // 10. Tag handling version
+      tagHandlingVersion: resolveTagHandlingVersion(options), // 10. Tag handling version
       customInstructions: options.customInstructions, // 11. Custom instructions
       styleId: options.styleId,          // 12. Style rules
       glossaryIds: glossary && 'glossary_ids' in glossary ? glossary.glossary_ids : undefined, // 13. Multi-glossary selection (order-significant)
diff --git a/src/utils/tag-handling-version.ts b/src/utils/tag-handling-version.ts
new file mode 100644
index 00000000..4b60d089
--- /dev/null
+++ b/src/utils/tag-handling-version.ts
@@ -0,0 +1,38 @@
+/**
+ * The tag handling version the CLI pins when a tag-handling request does not
+ * name one. v2 is the version the API will eventually default to; v1, today's
+ * server-side default, is documented as heading for deprecation.
+ */
+export const DEFAULT_TAG_HANDLING_VERSION = 'v2';
+
+export interface TagHandlingSelection {
+  tagHandling?: 'xml' | 'html';
+  tagHandlingVersion?: 'v1' | 'v2';
+}
+
+/**
+ * Pick the `tag_handling_version` to send for a tag-handling request.
+ *
+ * The version is always sent explicitly once tag handling is on, rather than
+ * left to the server default. That default is scheduled to move from v1 to v2,
+ * which would change translation output on DeepL's timetable instead of ours —
+ * and would silently invalidate cached entries, because a request that omits
+ * the version hashes the same before and after the flip.
+ *
+ * A version the caller named always wins, including v1, so pinning stays an
+ * escape hatch rather than a lock-in. Requests without tag handling carry no
+ * version and keep the cache keys they had.
+ */
+export function resolveTagHandlingVersion(
+  selection: TagHandlingSelection,
+): 'v1' | 'v2' | undefined {
+  if (selection.tagHandlingVersion) {
+    return selection.tagHandlingVersion;
+  }
+
+  if (selection.tagHandling) {
+    return DEFAULT_TAG_HANDLING_VERSION;
+  }
+
+  return undefined;
+}
diff --git a/tests/unit/deepl-client.test.ts b/tests/unit/deepl-client.test.ts
index 044a0fb5..4d28befa 100644
--- a/tests/unit/deepl-client.test.ts
+++ b/tests/unit/deepl-client.test.ts
@@ -2146,6 +2146,43 @@ describe('DeepLClient', () => {
 
       expect(scope.isDone()).toBe(true);
     });
+
+    it('should pin tag_handling_version to v2 when tag_handling is set without a version', async () => {
+      const scope = nock(baseUrl)
+        .post('/v2/translate', (body: string) => {
+          const params = new URLSearchParams(body);
+          return params.get('tag_handling_version') === 'v2';
+        })
+        .reply(200, {
+          translations: [{ text: '<p>Hola</p>', detected_source_language: 'EN' }],
+        });
+
+      await client.translate('<p>Hello</p>', {
+        targetLang: 'es',
+        tagHandling: 'html',
+      });
+
+      expect(scope.isDone()).toBe(true);
+    });
+
+    it('should send an explicit v1 rather than the pinned default', async () => {
+      const scope = nock(baseUrl)
+        .post('/v2/translate', (body: string) => {
+          const params = new URLSearchParams(body);
+          return params.get('tag_handling_version') === 'v1';
+        })
+        .reply(200, {
+          translations: [{ text: '<p>Hola</p>', detected_source_language: 'EN' }],
+        });
+
+      await client.translate('<p>Hello</p>', {
+        targetLang: 'es',
+        tagHandling: 'xml',
+        tagHandlingVersion: 'v1',
+      });
+
+      expect(scope.isDone()).toBe(true);
+    });
   });
 
   describe('Admin API', () => {
diff --git a/tests/unit/tag-handling-version.test.ts b/tests/unit/tag-handling-version.test.ts
new file mode 100644
index 00000000..fe5a79b3
--- /dev/null
+++ b/tests/unit/tag-handling-version.test.ts
@@ -0,0 +1,35 @@
+/**
+ * Tests for tag_handling_version pinning
+ */
+
+import {
+  resolveTagHandlingVersion,
+  DEFAULT_TAG_HANDLING_VERSION,
+} from '../../src/utils/tag-handling-version.js';
+
+describe('resolveTagHandlingVersion', () => {
+  it('should pin v2 as the default', () => {
+    expect(DEFAULT_TAG_HANDLING_VERSION).toBe('v2');
+  });
+
+  it('should return undefined when tag handling is off', () => {
+    expect(resolveTagHandlingVersion({})).toBeUndefined();
+  });
+
+  it('should pin the default version when tag handling is on without a version', () => {
+    expect(resolveTagHandlingVersion({ tagHandling: 'xml' })).toBe('v2');
+    expect(resolveTagHandlingVersion({ tagHandling: 'html' })).toBe('v2');
+  });
+
+  it('should honour an explicit v1 over the pinned default', () => {
+    expect(resolveTagHandlingVersion({ tagHandling: 'xml', tagHandlingVersion: 'v1' })).toBe('v1');
+  });
+
+  it('should honour an explicit v2', () => {
+    expect(resolveTagHandlingVersion({ tagHandling: 'html', tagHandlingVersion: 'v2' })).toBe('v2');
+  });
+
+  it('should keep an explicit version that arrived without tag handling', () => {
+    expect(resolveTagHandlingVersion({ tagHandlingVersion: 'v1' })).toBe('v1');
+  });
+});
diff --git a/tests/unit/translation-service.test.ts b/tests/unit/translation-service.test.ts
index c80340bd..3d334989 100644
--- a/tests/unit/translation-service.test.ts
+++ b/tests/unit/translation-service.test.ts
@@ -1207,6 +1207,39 @@ describe('TranslationService', () => {
       });
     });
 
+    describe('tag handling version cache keys', () => {
+      const keysFor = async (
+        optionSets: Array<Record<string, unknown>>,
+      ): Promise<string[]> => {
+        mockCacheService.get.mockReturnValue(null);
+        mockDeepLClient.translate.mockResolvedValue({ text: 'Hola' });
+        mockCacheService.set.mockClear();
+
+        for (const options of optionSets) {
+          await translationService.translate('Hello', { targetLang: 'es', ...options } as any);
+        }
+
+        return mockCacheService.set.mock.calls.map((call) => call[0]);
+      };
+
+      /** Pinning makes these the same request, so they must share an entry. */
+      it('should key a bare tag-handling request the same as an explicit v2', async () => {
+        const [pinned, explicit] = await keysFor([
+          { tagHandling: 'xml' },
+          { tagHandling: 'xml', tagHandlingVersion: 'v2' },
+        ]);
+        expect(pinned).toBe(explicit);
+      });
+
+      it('should separate an explicit v1 from the pinned default', async () => {
+        const [v1, pinned] = await keysFor([
+          { tagHandling: 'xml', tagHandlingVersion: 'v1' },
+          { tagHandling: 'xml' },
+        ]);
+        expect(v1).not.toBe(pinned);
+      });
+    });
+
     it('should use cached result when options are provided in different order', async () => {
       // Set up cache to return a hit for the second call
       let callCount = 0;

From 7bbd58b1254b085de84402eb84a0f702b000477c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:08:41 -0400
Subject: [PATCH 028/256] fix(glossary): treat a base-language glossary as
 covering regional targets

The language-pair preflight compared the requested target verbatim against the
glossary's dictionaries, but dictionaries only ever name base languages while
--to accepts en-us, en-gb, pt-br and the rest. A de->en glossary therefore
failed locally for --to en-us, which the API accepts, making glossaries
unusable for the regional variants DeepL steers users towards.

Both sides now compare on their base language, so the check stays a nicer
error for pairs a glossary genuinely lacks without blocking valid work.
---
 src/data/language-registry.ts       | 10 +++++++++
 src/services/glossary.ts            | 11 +++++++--
 tests/unit/glossary-service.test.ts | 35 +++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index 3f2624dc..f5c5eb16 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -91,6 +91,16 @@ export function looksLikeLanguageTag(code: string): boolean {
   return LANGUAGE_TAG.test(code);
 }
 
+/**
+ * The base language of a code, dropping any regional subtag: `en-us` -> `en`.
+ * Used where one side of a comparison carries variants the other cannot, such as
+ * glossary dictionaries, which only ever name base languages while `--to`
+ * accepts `en-us`, `pt-br` and the rest.
+ */
+export function baseLanguage(code: string): string {
+  return code.toLowerCase().split('-')[0] ?? code.toLowerCase();
+}
+
 /** Check whether a language code is recognized by the registry. */
 export function isValidLanguage(code: string): boolean {
   return LANGUAGE_REGISTRY.has(code);
diff --git a/src/services/glossary.ts b/src/services/glossary.ts
index 135f8bae..9b7e5575 100644
--- a/src/services/glossary.ts
+++ b/src/services/glossary.ts
@@ -6,6 +6,7 @@
 import { DeepLClient } from '../api/deepl-client.js';
 import { GlossaryInfo, GlossaryLanguagePair, Language, isMultilingual } from '../types/index.js';
 import { Logger } from '../utils/logger.js';
+import { baseLanguage } from '../data/language-registry.js';
 import { ValidationError, ConfigError } from '../utils/errors.js';
 
 function sanitizeForError(input: string): string {
@@ -168,6 +169,12 @@ export class GlossaryService {
    * read as also covering en→fr. Free on this path because the list is already
    * fetched to resolve the name; the UUID path trusts the caller and skips the
    * check, as translation-memory resolution does.
+   *
+   * Both sides are compared on their base language, because dictionaries only
+   * ever name base languages while `--to` accepts regional variants: a de→en
+   * glossary has to count as covering de→en-us, which the API accepts. That
+   * makes the check deliberately permissive at the edges — a pair it lets
+   * through is still the API's to reject, which is the cheaper mistake.
    */
   async resolveGlossaryId(
     nameOrId: string,
@@ -205,8 +212,8 @@ export class GlossaryService {
       const covered = (target: string): boolean =>
         match.dictionaries.some(
           d =>
-            d.source_lang.toLowerCase() === from &&
-            d.target_lang.toLowerCase() === target.toLowerCase(),
+            baseLanguage(d.source_lang) === baseLanguage(from) &&
+            baseLanguage(d.target_lang) === baseLanguage(target),
         );
       const missing = expected.targets.filter(target => !covered(target));
       if (missing.length > 0) {
diff --git a/tests/unit/glossary-service.test.ts b/tests/unit/glossary-service.test.ts
index 73ad70ac..37783236 100644
--- a/tests/unit/glossary-service.test.ts
+++ b/tests/unit/glossary-service.test.ts
@@ -417,6 +417,41 @@ describe('GlossaryService', () => {
         ).rejects.toThrow('does not support the requested language pair');
       });
 
+      it('should treat a base-language dictionary as covering its regional variants', async () => {
+        // Glossary dictionaries carry base codes, while --to accepts regional
+        // variants, so de→en has to cover de→en-us or glossaries become
+        // unusable for the variants DeepL steers users towards.
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'de', target_lang: 'en' }]) as never,
+        );
+
+        for (const target of ['en-us', 'en-gb'] as const) {
+          await expect(
+            glossaryService.resolveGlossaryId('tech-terms', { from: 'de', targets: [target] }),
+          ).resolves.toBe('found-glossary-id');
+        }
+      });
+
+      it('should treat a regional --from as covered by a base-language dictionary', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'pt', target_lang: 'de' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'pt-br', targets: ['de'] }),
+        ).resolves.toBe('found-glossary-id');
+      });
+
+      it('should still reject a pair no dictionary covers even across regions', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'de', target_lang: 'en' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'de', targets: ['pt-br'] }),
+        ).rejects.toThrow('does not support the requested language pair');
+      });
+
       it('should compare languages case-insensitively', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
           listing([{ source_lang: 'EN', target_lang: 'ES' }]) as never,

From 5245ee5e053078ac1948d921ec414b7bd4f3f47e Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:08:50 -0400
Subject: [PATCH 029/256] fix(translate): honour --tag-handling-version outside
 text mode

buildTranslationOptions mapped tagHandling but not tagHandlingVersion, so only
the text handler carried the flag. That was harmless while no version was sent,
but since the CLI pins v2 whenever tag handling is on, a file or directory
translation asked for v1 silently got v2 -- with no warning, because single-file
mode does not run warnIgnoredOptions.

The flag is now mapped in the shared base mapping every handler uses, and its
validation moves with it so both paths reject the same input.
---
 src/cli/commands/translate/translate-utils.ts | 20 ++++++++++++++++++
 tests/unit/translate-utils.test.ts            | 21 +++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index 654b05ef..b387c420 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -117,6 +117,24 @@ export function validateXmlTags(tags: string[], paramName: string): void {
   }
 }
 
+/**
+ * Validate `--tag-handling-version` and return it. Shared so every handler maps
+ * the flag: since the CLI pins v2 whenever tag handling is on, a handler that
+ * dropped the flag would silently send v2 to a caller who asked for v1.
+ */
+export function validateTagHandlingVersion(
+  options: TranslateOptions,
+): TranslationParams['tagHandlingVersion'] {
+  if (!options.tagHandlingVersion) return undefined;
+  if (!options.tagHandling) {
+    throw new ValidationError('--tag-handling-version requires --tag-handling to be set (xml or html)');
+  }
+  if (options.tagHandlingVersion !== 'v1' && options.tagHandlingVersion !== 'v2') {
+    throw new ValidationError('--tag-handling-version must be "v1" or "v2"');
+  }
+  return options.tagHandlingVersion;
+}
+
 export function buildTranslationOptions(options: TranslateOptions): TranslationParams {
   const result: TranslationParams = {
     targetLang: options.to as Language,
@@ -127,6 +145,8 @@ export function buildTranslationOptions(options: TranslateOptions): TranslationP
   if (options.context) result.context = options.context;
   if (options.splitSentences) result.splitSentences = options.splitSentences as TranslationParams['splitSentences'];
   if (options.tagHandling) result.tagHandling = options.tagHandling as TranslationParams['tagHandling'];
+  const tagHandlingVersion = validateTagHandlingVersion(options);
+  if (tagHandlingVersion) result.tagHandlingVersion = tagHandlingVersion;
   if (options.modelType) result.modelType = options.modelType as TranslationParams['modelType'];
   if (options.preserveFormatting !== undefined) result.preserveFormatting = options.preserveFormatting;
   if (options.showBilledCharacters) result.showBilledCharacters = true;
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index bb97d42b..72458fbf 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -430,6 +430,27 @@ describe('translate-utils', () => {
       expect(result.modelType).toBe('quality_optimized');
     });
 
+    it('should map tagHandlingVersion so file and directory mode honour it too', () => {
+      const result = buildTranslationOptions({
+        to: 'de',
+        tagHandling: 'html',
+        tagHandlingVersion: 'v1',
+      });
+      expect(result.tagHandlingVersion).toBe('v1');
+    });
+
+    it('should reject tagHandlingVersion without tagHandling', () => {
+      expect(() => buildTranslationOptions({ to: 'de', tagHandlingVersion: 'v2' })).toThrow(
+        '--tag-handling-version requires --tag-handling',
+      );
+    });
+
+    it('should reject a tagHandlingVersion that is neither v1 nor v2', () => {
+      expect(() =>
+        buildTranslationOptions({ to: 'de', tagHandling: 'xml', tagHandlingVersion: 'v3' }),
+      ).toThrow('--tag-handling-version must be "v1" or "v2"');
+    });
+
     it('should map preserveFormatting when explicitly set', () => {
       const result = buildTranslationOptions({ to: 'de', preserveFormatting: true });
       expect(result.preserveFormatting).toBe(true);

From 34b947b8070f6516241c0047dc5ec89aaf3bc776 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:09:01 -0400
Subject: [PATCH 030/256] fix(glossary): resolve the source language from
 config before requiring --from

TranslationService merges defaults.sourceLang, so a glossary request supplies
source_lang whether or not --from was typed. Rejecting on a missing flag alone
broke watch sessions and translations that had been working from config.

The guard now resolves the effective source language onto `from`, which also
gives the document path -- which merges no defaults of its own -- and the
glossary preflight the pair they need. Two related holes close with it:

- `--glossary` was tested for bare truthiness, and `[]` is truthy, so a caller
  passing an empty selection got a spurious error
- watch --dry-run returned before the guard, reporting a command as runnable
  that fails on the first file change

Watch also passes the pair to resolveGlossaryId now, so a glossary that does
not cover it fails at launch rather than once per file change. The text
handler's duplicate tag-handling-version block goes with the shared mapping.
---
 src/cli/commands/register-watch.ts            | 11 ++++
 .../translate/document-translation-handler.ts | 12 ++---
 .../translate/file-translation-handler.ts     | 23 ++++----
 .../translate/text-translation-handler.ts     | 34 ++++--------
 src/cli/commands/watch.ts                     | 15 ++++--
 src/utils/glossary-params.ts                  | 38 ++++++++++++++
 tests/unit/glossary-params.test.ts            | 52 +++++++++++++++++++
 tests/unit/watch-command.test.ts              |  7 ++-
 8 files changed, 146 insertions(+), 46 deletions(-)

diff --git a/src/cli/commands/register-watch.ts b/src/cli/commands/register-watch.ts
index 5c0b08b5..406a50f0 100644
--- a/src/cli/commands/register-watch.ts
+++ b/src/cli/commands/register-watch.ts
@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
 import { createWatchCommand, type ServiceDeps } from './service-factory.js';
+import { applyGlossarySourceLang, hasGlossarySelection } from '../../utils/glossary-params.js';
 
 export function registerWatch(
   program: Command,
@@ -67,6 +68,16 @@ Examples:
           }
         }
 
+        // Resolved before --dry-run so a well-formed-looking command is not
+        // reported as runnable when it would fail on the first file change.
+        if (hasGlossarySelection(options)) {
+          applyGlossarySourceLang(
+            options,
+            deps.getConfigService().getValue<string>('defaults.sourceLang'),
+            'Example: deepl watch ./docs --from en --to es --glossary my-glossary',
+          );
+        }
+
         if (options.dryRun) {
           const targetLangs = options.to.split(',').map(l => l.trim()).filter(l => l.length > 0);
           const isDirectory = fs.existsSync(watchPath) && fs.statSync(watchPath).isDirectory();
diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index fa6be7b0..c14fe062 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -6,6 +6,7 @@ import type { DocumentTranslationOptions } from '../../../types/api.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
 import { warnIgnoredOptions, validateLanguageCodes } from './translate-utils.js';
 import { buildBaseTranslationOptions, applyGlossarySelection } from './translation-options-factory.js';
+import { applyGlossarySourceLang } from '../../../utils/glossary-params.js';
 
 export class DocumentTranslationHandler {
   constructor(public ctx: HandlerContext) {}
@@ -24,12 +25,11 @@ export class DocumentTranslationHandler {
 
     // The API rejects a document glossary without source_lang: "source_lang has
     // to be specified in order to use a glossary."
-    if (options.glossary && options.glossary.length > 0 && !options.from) {
-      throw new ValidationError(
-        'Source language (--from) is required when using a glossary',
-        'Example: deepl translate --from en --to es --glossary my-glossary report.pdf --output report.es.pdf'
-      );
-    }
+    applyGlossarySourceLang(
+      options,
+      this.ctx.config.getValue<string>('defaults.sourceLang'),
+      'Example: deepl translate --from en --to es --glossary my-glossary report.pdf --output report.es.pdf'
+    );
 
     const outputPath = options.output!;
 
diff --git a/src/cli/commands/translate/file-translation-handler.ts b/src/cli/commands/translate/file-translation-handler.ts
index e12aae17..64d4a885 100644
--- a/src/cli/commands/translate/file-translation-handler.ts
+++ b/src/cli/commands/translate/file-translation-handler.ts
@@ -14,6 +14,7 @@ import {
   SAFE_TEXT_SIZE_LIMIT,
 } from './translate-utils.js';
 import { buildBaseTranslationOptions, applySharedTmAndGlossary } from './translation-options-factory.js';
+import { applyGlossarySourceLang } from '../../../utils/glossary-params.js';
 import type { DocumentTranslationHandler } from './document-translation-handler.js';
 
 export class FileTranslationHandler {
@@ -36,12 +37,11 @@ export class FileTranslationHandler {
 
       const validTargetLangs = targetLangs as Language[];
 
-      if (options.glossary && !options.from) {
-        throw new ValidationError(
-          'Source language (--from) is required when using a glossary',
-          'Example: deepl translate --from en --to en,fr,es --glossary my-glossary file.txt'
-        );
-      }
+      applyGlossarySourceLang(
+        options,
+        this.ctx.config.getValue<string>('defaults.sourceLang'),
+        'Example: deepl translate --from en --to en,fr,es --glossary my-glossary file.txt'
+      );
 
       if (options.translationMemory) {
         if (!options.from) {
@@ -123,12 +123,11 @@ export class FileTranslationHandler {
   async translateTextFile(filePath: string, options: TranslateOptions): Promise<string> {
     validateLanguageCodes([options.to]);
 
-    if (options.glossary && !options.from) {
-      throw new ValidationError(
-        'Source language (--from) is required when using a glossary',
-        'Example: deepl translate --from en --to es --glossary my-glossary file.txt'
-      );
-    }
+    applyGlossarySourceLang(
+      options,
+      this.ctx.config.getValue<string>('defaults.sourceLang'),
+      'Example: deepl translate --from en --to es --glossary my-glossary file.txt'
+    );
 
     if (options.translationMemory) {
       if (!options.from) {
diff --git a/src/cli/commands/translate/text-translation-handler.ts b/src/cli/commands/translate/text-translation-handler.ts
index 0c36e9c1..d2cf8f61 100644
--- a/src/cli/commands/translate/text-translation-handler.ts
+++ b/src/cli/commands/translate/text-translation-handler.ts
@@ -12,6 +12,7 @@ import {
   MAX_CUSTOM_INSTRUCTION_CHARS,
 } from './translate-utils.js';
 import { buildBaseTranslationOptions, applySharedTmAndGlossary } from './translation-options-factory.js';
+import { applyGlossarySourceLang } from '../../../utils/glossary-params.js';
 
 export class TextTranslationHandler {
   constructor(public ctx: HandlerContext) {}
@@ -44,12 +45,11 @@ export class TextTranslationHandler {
     validateLanguageCodes([options.to]);
     validateExtendedLanguageConstraints(options.to, options);
 
-    if (options.glossary && !options.from) {
-      throw new ValidationError(
-        'Source language (--from) is required when using a glossary',
-        'Example: deepl translate --from en --to es --glossary my-glossary "Hello"'
-      );
-    }
+    applyGlossarySourceLang(
+      options,
+      this.ctx.config.getValue<string>('defaults.sourceLang'),
+      'Example: deepl translate --from en --to es --glossary my-glossary "Hello"'
+    );
 
     if (options.translationMemory) {
       if (!options.from) {
@@ -127,17 +127,6 @@ export class TextTranslationHandler {
       translationOptions.ignoreTags = tags;
     }
 
-    if (options.tagHandlingVersion) {
-      if (!options.tagHandling) {
-        throw new ValidationError('--tag-handling-version requires --tag-handling to be set (xml or html)');
-      }
-      if (options.tagHandlingVersion !== 'v1' && options.tagHandlingVersion !== 'v2') {
-        throw new ValidationError('--tag-handling-version must be "v1" or "v2"');
-      }
-      translationOptions.tagHandlingVersion = options.tagHandlingVersion;
-    }
-
-
     const result = await this.ctx.translationService.translate(
       text,
       translationOptions,
@@ -181,12 +170,11 @@ export class TextTranslationHandler {
     validateLanguageCodes(targetLangs);
     validateExtendedLanguageConstraints(options.to, options);
 
-    if (options.glossary && !options.from) {
-      throw new ValidationError(
-        'Source language (--from) is required when using a glossary',
-        'Example: deepl translate --from en --to es --glossary my-glossary "Hello"'
-      );
-    }
+    applyGlossarySourceLang(
+      options,
+      this.ctx.config.getValue<string>('defaults.sourceLang'),
+      'Example: deepl translate --from en --to es --glossary my-glossary "Hello"'
+    );
 
     if (options.translationMemory) {
       if (!options.from) {
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index dc37d1c5..e3c03cfa 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -40,8 +40,11 @@ export class WatchCommand {
     this.glossaryService = glossaryService;
   }
 
-  private async resolveGlossaryId(nameOrId: string): Promise<string> {
-    return this.glossaryService.resolveGlossaryId(nameOrId);
+  private async resolveGlossaryId(
+    nameOrId: string,
+    expected?: { from: Language; targets: Language[] },
+  ): Promise<string> {
+    return this.glossaryService.resolveGlossaryId(nameOrId, expected);
   }
 
   /**
@@ -104,10 +107,14 @@ export class WatchCommand {
       Logger.info(chalk.gray(`Git-staged files: ${stagedFiles.size}`));
     }
 
-    // Resolve glossary ID if provided
+    // Resolve glossary ID if provided. The pair is known at launch, so the
+    // coverage check happens here rather than once per file change.
     let glossaryId: string | undefined;
     if (options.glossary) {
-      glossaryId = await this.resolveGlossaryId(options.glossary);
+      glossaryId = await this.resolveGlossaryId(
+        options.glossary,
+        options.from ? { from: options.from as Language, targets: targetLangs } : undefined,
+      );
     }
 
     // Determine output directory
diff --git a/src/utils/glossary-params.ts b/src/utils/glossary-params.ts
index ff86e062..1046dec1 100644
--- a/src/utils/glossary-params.ts
+++ b/src/utils/glossary-params.ts
@@ -8,6 +8,44 @@ export interface GlossarySelection {
   glossaryIds?: string[];
 }
 
+/** A command's `--glossary`/`--from` pair, however that command spells them. */
+export interface GlossarySourceLangSelection {
+  glossary?: string | string[];
+  from?: string;
+}
+
+/** Whether `--glossary` names anything; `[]` is truthy but selects nothing. */
+export function hasGlossarySelection(selection: GlossarySourceLangSelection): boolean {
+  const { glossary } = selection;
+  return Array.isArray(glossary) ? glossary.length > 0 : !!glossary;
+}
+
+/**
+ * Settle the source language a glossary request will carry, filling `from` from
+ * the configured default when the flag is absent.
+ *
+ * The API rejects a glossary without `source_lang`, but `--from` is not the only
+ * way one is supplied: `TranslationService` merges `defaults.sourceLang`, so
+ * rejecting on a missing flag alone broke sessions that had been working from
+ * config. Resolving it onto `from` instead means every path sees the same
+ * answer, including the document path, which merges no defaults of its own, and
+ * the glossary preflight, which needs the pair to check coverage.
+ */
+export function applyGlossarySourceLang(
+  selection: GlossarySourceLangSelection,
+  configuredSourceLang: string | undefined,
+  example: string,
+): void {
+  if (!hasGlossarySelection(selection) || selection.from) {
+    return;
+  }
+  if (configuredSourceLang) {
+    selection.from = configuredSourceLang.toLowerCase();
+    return;
+  }
+  throw new ValidationError('Source language (--from) is required when using a glossary', example);
+}
+
 export type GlossaryWireParams =
   | { glossary_id: string }
   | { glossary_ids: string[] };
diff --git a/tests/unit/glossary-params.test.ts b/tests/unit/glossary-params.test.ts
index 5b7532d8..c2852b40 100644
--- a/tests/unit/glossary-params.test.ts
+++ b/tests/unit/glossary-params.test.ts
@@ -5,6 +5,8 @@
 import {
   resolveGlossaryWireParams,
   encodeGlossaryIdsForMultipart,
+  applyGlossarySourceLang,
+  hasGlossarySelection,
   MAX_GLOSSARIES_PER_REQUEST,
 } from '../../src/utils/glossary-params.js';
 import { ValidationError } from '../../src/utils/errors.js';
@@ -86,3 +88,53 @@ describe('encodeGlossaryIdsForMultipart', () => {
     expect(encodeGlossaryIdsForMultipart([B, A])).toBe(`${B},${A}`);
   });
 });
+
+describe('hasGlossarySelection', () => {
+  it('should treat an empty array as selecting nothing, unlike bare truthiness', () => {
+    expect(hasGlossarySelection({ glossary: [] })).toBe(false);
+  });
+
+  it('should recognize a string and a non-empty array', () => {
+    expect(hasGlossarySelection({ glossary: 'terms' })).toBe(true);
+    expect(hasGlossarySelection({ glossary: ['terms'] })).toBe(true);
+  });
+});
+
+describe('applyGlossarySourceLang', () => {
+  const example = 'Example: deepl translate --from en --to es --glossary g "Hello"';
+
+  it('should leave an explicit --from alone', () => {
+    const options = { glossary: ['terms'], from: 'de' };
+    applyGlossarySourceLang(options, 'en', example);
+    expect(options.from).toBe('de');
+  });
+
+  it('should fall back to the configured source language', () => {
+    // The request carries source_lang either way, so rejecting on a missing
+    // flag alone broke sessions that had been working from config.
+    const options: { glossary: string[]; from?: string } = { glossary: ['terms'] };
+    applyGlossarySourceLang(options, 'EN', example);
+    expect(options.from).toBe('en');
+  });
+
+  it('should throw only when neither the flag nor the config supplies one', () => {
+    expect(() => applyGlossarySourceLang({ glossary: ['terms'] }, undefined, example)).toThrow(
+      ValidationError,
+    );
+    expect(() => applyGlossarySourceLang({ glossary: ['terms'] }, undefined, example)).toThrow(
+      'Source language (--from) is required when using a glossary',
+    );
+  });
+
+  it('should do nothing when no glossary is selected', () => {
+    const options: { glossary?: string[]; from?: string } = { glossary: [] };
+    expect(() => applyGlossarySourceLang(options, undefined, example)).not.toThrow();
+    expect(options.from).toBeUndefined();
+  });
+
+  it('should accept a single-string glossary, as watch and sync spell it', () => {
+    const options: { glossary: string; from?: string } = { glossary: 'terms' };
+    applyGlossarySourceLang(options, 'en', example);
+    expect(options.from).toBe('en');
+  });
+});
diff --git a/tests/unit/watch-command.test.ts b/tests/unit/watch-command.test.ts
index 61c83693..c68068a5 100644
--- a/tests/unit/watch-command.test.ts
+++ b/tests/unit/watch-command.test.ts
@@ -465,7 +465,12 @@ describe('WatchCommand', () => {
           // Expected: the watcher is stubbed to throw once reached
         }
 
-        expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+        // The pair goes with it so coverage is checked at launch, not once per
+        // file change.
+        expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+          from: 'en',
+          targets: ['es'],
+        });
       });
     });
 

From 9dff6328eb93fad3f1da19db783c355356bc7516 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:16:18 -0400
Subject: [PATCH 031/256] fix(services): key the translation cache on every
 parameter that changes the text

The cache key carried tagHandling and the glossary selection but not the
translation memory, the XML tag parameters, or preserveFormatting -- so a plain
request and the same request with --translation-memory, a different
--ignore-tags, or --preserve-formatting collided and the cache served the wrong
translation while reporting cached: true.

preserveFormatting was excluded on the grounds that it does not affect output,
but preserve_formatting suppresses the sentence-boundary punctuation and case
correction, which shows up in the text.
---
 src/services/translation.ts            | 15 +++++-
 tests/unit/translation-service.test.ts | 71 ++++++++++++++++++++++++++
 2 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/src/services/translation.ts b/src/services/translation.ts
index 70f7e905..d9f8e0d3 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -402,6 +402,13 @@ export class TranslationService {
    * so it holds the version the request will actually carry. Leaving it unset
    * would let the key stay stable across a change of the API's own default,
    * serving entries the API would no longer produce.
+   *
+   * Every parameter that changes the returned text has to appear here or the
+   * cache serves the wrong translation: a plain request and the same request
+   * with a translation memory, different --ignore-tags, or --preserve-formatting
+   * are different requests. `preserveFormatting` is included because
+   * preserve_formatting suppresses the sentence-boundary punctuation and case
+   * correction, which shows up in the text.
    */
   private generateCacheKey(text: string, options: TranslationOptions): string {
     // Keyed on the parameter the request will actually carry, so the two ways of
@@ -424,7 +431,13 @@ export class TranslationService {
       customInstructions: options.customInstructions, // 11. Custom instructions
       styleId: options.styleId,          // 12. Style rules
       glossaryIds: glossary && 'glossary_ids' in glossary ? glossary.glossary_ids : undefined, // 13. Multi-glossary selection (order-significant)
-      // Note: preserveFormatting doesn't affect translation output, so not cached
+      translationMemoryId: options.translationMemoryId, // 14. Memory consulted for matches
+      translationMemoryThreshold: options.translationMemoryThreshold, // 15. Which matches it reuses
+      ignoreTags: options.ignoreTags,     // 16. Tags left untranslated
+      splittingTags: options.splittingTags, // 17. Tags that split sentences
+      nonSplittingTags: options.nonSplittingTags, // 18. Tags that do not
+      outlineDetection: options.outlineDetection, // 19. XML structure inference
+      preserveFormatting: options.preserveFormatting, // 20. Suppresses boundary correction
     };
 
     // Generate SHA-256 hash of the stable representation
diff --git a/tests/unit/translation-service.test.ts b/tests/unit/translation-service.test.ts
index 3d334989..615bedde 100644
--- a/tests/unit/translation-service.test.ts
+++ b/tests/unit/translation-service.test.ts
@@ -1240,6 +1240,77 @@ describe('TranslationService', () => {
       });
     });
 
+    describe('cache keys for parameters that change the translation', () => {
+      const keysFor = async (
+        optionSets: Array<Record<string, unknown>>,
+      ): Promise<string[]> => {
+        mockCacheService.get.mockReturnValue(null);
+        mockDeepLClient.translate.mockResolvedValue({ text: 'Hola' });
+        mockCacheService.set.mockClear();
+
+        for (const options of optionSets) {
+          await translationService.translate('Hello', { targetLang: 'es', ...options } as any);
+        }
+
+        return mockCacheService.set.mock.calls.map((call) => call[0]);
+      };
+
+      it('should separate a translation-memory request from one without', async () => {
+        const [none, withTm] = await keysFor([{}, { translationMemoryId: 'tm-1' }]);
+        expect(none).not.toBe(withTm);
+      });
+
+      it('should separate two translation memories', async () => {
+        const [one, two] = await keysFor([
+          { translationMemoryId: 'tm-1' },
+          { translationMemoryId: 'tm-2' },
+        ]);
+        expect(one).not.toBe(two);
+      });
+
+      it('should separate two match thresholds for the same memory', async () => {
+        const [low, high] = await keysFor([
+          { translationMemoryId: 'tm-1', translationMemoryThreshold: 20 },
+          { translationMemoryId: 'tm-1', translationMemoryThreshold: 80 },
+        ]);
+        expect(low).not.toBe(high);
+      });
+
+      it.each([
+        ['ignoreTags', ['b'], ['i']],
+        ['splittingTags', ['p'], ['div']],
+        ['nonSplittingTags', ['br'], ['span']],
+      ])('should separate two values of %s', async (field, first, second) => {
+        const [a, b] = await keysFor([
+          { tagHandling: 'xml', [field]: first },
+          { tagHandling: 'xml', [field]: second },
+        ]);
+        expect(a).not.toBe(b);
+      });
+
+      it('should separate outlineDetection=false from the default', async () => {
+        const [off, on] = await keysFor([
+          { tagHandling: 'xml', outlineDetection: false },
+          { tagHandling: 'xml' },
+        ]);
+        expect(off).not.toBe(on);
+      });
+
+      /** preserve_formatting suppresses sentence-boundary correction, so it shows up in the text. */
+      it('should separate the two preserveFormatting values', async () => {
+        const [off, on] = await keysFor([
+          { preserveFormatting: false },
+          { preserveFormatting: true },
+        ]);
+        expect(off).not.toBe(on);
+      });
+
+      it('should leave keys unchanged for requests using none of them', async () => {
+        const [plain, alsoPlain] = await keysFor([{}, {}]);
+        expect(plain).toBe(alsoPlain);
+      });
+    });
+
     it('should use cached result when options are provided in different order', async () => {
       // Set up cache to return a hit for the second call
       let callCount = 0;

From 2b22d12e916bf4ef77ea84b50da8ac3ad2637968 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:16:34 -0400
Subject: [PATCH 032/256] refactor(types)!: derive the Language union from the
 generated snapshot

The union was a fourth hand-maintained copy of the language list and had already
fallen four codes behind the snapshot it is supposed to describe: de-ch, de-de,
fr-ca and fr-fr -- the very codes the /v3/languages migration was written to
add. Neither generate:languages nor check:languages touched it, and it is
published, so `deepl config set defaults.targetLangs de-de` succeeded at runtime
while DeepLConfig could not type the config the CLI had just written.

ENTRIES is now generated `as const satisfies readonly LanguageEntry[]` and
Language derives from its codes, the same way WriteLanguage already derived from
WRITE_TARGET_LANGUAGES. Regenerating the snapshot widens both.

The registry's own lookups keep the interface rather than 125 literal types, and
the suite's tier counts are compared against the snapshot instead of written
out, so the documented release step no longer turns the suite red.
---
 src/data/language-entries.ts         |  8 ++-
 src/data/language-registry.ts        |  9 +++-
 src/types/common.ts                  | 34 ++++++------
 tests/unit/language-registry.test.ts | 77 +++++++++++++++++++++-------
 4 files changed, 88 insertions(+), 40 deletions(-)

diff --git a/src/data/language-entries.ts b/src/data/language-entries.ts
index 08092444..60db1bea 100644
--- a/src/data/language-entries.ts
+++ b/src/data/language-entries.ts
@@ -9,10 +9,14 @@
  * the CLI can list and validate languages without a network call or API key.
  * It may therefore lag the API, which is why callers accept well-formed codes
  * it does not contain rather than rejecting them.
+ *
+ * `as const` is load-bearing: the Language union in src/types/common.ts is
+ * derived from these codes, so a language added upstream widens the type on
+ * regenerate instead of needing a second hand-kept copy of the same list.
  */
 import type { LanguageEntry } from './language-registry.js';
 
-export const ENTRIES: LanguageEntry[] = [
+export const ENTRIES = [
   // Core languages (full feature support: formality, glossary, all model types)
   { code: 'ar', name: 'Arabic', category: 'core' },
   { code: 'bg', name: 'Bulgarian', category: 'core' },
@@ -143,7 +147,7 @@ export const ENTRIES: LanguageEntry[] = [
   { code: 'yi', name: 'Yiddish', category: 'extended' },
   { code: 'yue', name: 'Cantonese', category: 'extended' },
   { code: 'zu', name: 'Zulu', category: 'extended' },
-];
+] as const satisfies readonly LanguageEntry[];
 
 /**
  * Target languages the Write API accepts, from resource=write.
diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index f5c5eb16..5c09de67 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -15,7 +15,7 @@
  * - **regional**: Target-only variants of core languages (e.g., en-gb, pt-br)
  * - **extended**: quality_optimized model only; no formality or glossary support
  */
-import { ENTRIES } from './language-entries.js';
+import { ENTRIES as GENERATED_ENTRIES } from './language-entries.js';
 
 /**
  * Feature-availability tier for a language.
@@ -38,6 +38,13 @@ export interface LanguageEntry {
   targetOnly?: boolean;
 }
 
+/**
+ * The snapshot as plain entries. It is generated `as const` so the `Language`
+ * union can be derived from its codes; the lookups below want the interface, not
+ * 125 individual literal types.
+ */
+const ENTRIES: readonly LanguageEntry[] = GENERATED_ENTRIES;
+
 /** Read-only map of language code to its registry entry. Primary lookup structure. */
 export const LANGUAGE_REGISTRY: ReadonlyMap<string, LanguageEntry> = new Map(
   ENTRIES.map(entry => [entry.code, entry])
diff --git a/src/types/common.ts b/src/types/common.ts
index 261e8689..ffe3f10f 100644
--- a/src/types/common.ts
+++ b/src/types/common.ts
@@ -2,24 +2,22 @@
  * Common types used throughout the application
  */
 
-export type Language =
-  // Core languages (full feature support: formality, glossaries, all model types)
-  | 'ar' | 'bg' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'es' | 'et' | 'fi'
-  | 'fr' | 'he' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'nb'
-  | 'nl' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'sv' | 'tr' | 'uk'
-  | 'vi' | 'zh'
-  // Target-only regional variants
-  | 'en-gb' | 'en-us' | 'es-419' | 'pt-br' | 'pt-pt' | 'zh-hans' | 'zh-hant'
-  // Extended languages (quality_optimized only, no formality/glossary support)
-  | 'ace' | 'af' | 'an' | 'as' | 'ay' | 'az' | 'ba' | 'be' | 'bho' | 'bn'
-  | 'br' | 'bs' | 'ca' | 'ceb' | 'ckb' | 'cy' | 'eo' | 'eu' | 'fa' | 'ga'
-  | 'gl' | 'gn' | 'gom' | 'gu' | 'ha' | 'hi' | 'hr' | 'ht' | 'hy' | 'ig'
-  | 'is' | 'jv' | 'ka' | 'kk' | 'kmr' | 'ky' | 'la' | 'lb' | 'lmo' | 'ln'
-  | 'mai' | 'mg' | 'mi' | 'mk' | 'ml' | 'mn' | 'mr' | 'ms' | 'mt' | 'my'
-  | 'ne' | 'oc' | 'om' | 'pa' | 'pag' | 'pam' | 'prs' | 'ps' | 'qu' | 'sa'
-  | 'scn' | 'sq' | 'sr' | 'st' | 'su' | 'sw' | 'ta' | 'te' | 'tg' | 'th'
-  | 'tk' | 'tl' | 'tn' | 'ts' | 'tt' | 'ur' | 'uz' | 'wo' | 'xh' | 'yi'
-  | 'yue' | 'zu';
+import { ENTRIES } from '../data/language-entries.js';
+
+/**
+ * Every language code the bundled snapshot lists, which is generated from
+ * GET /v3/languages.
+ *
+ * Derived rather than hand-maintained: as a written-out union this was a fourth
+ * copy of the same list and had already fallen four codes behind the snapshot
+ * (de-ch, de-de, fr-ca, fr-fr), so the published typings could not describe a
+ * config the CLI itself accepts. Regenerating the snapshot now widens this too.
+ *
+ * The API remains the authority on which languages exist -- runtime validation
+ * accepts well-formed codes the snapshot predates, so this union is the set the
+ * CLI can name offline, not the set that works.
+ */
+export type Language = (typeof ENTRIES)[number]['code'];
 
 export type Formality =
   | 'default'
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index 77f220d5..6cf30469 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -10,12 +10,22 @@ import {
   deriveLanguageEntry,
   looksLikeLanguageTag,
 } from '../../src/data/language-registry';
-import { WRITE_TARGET_LANGUAGES } from '../../src/data/language-entries';
+import { ENTRIES, WRITE_TARGET_LANGUAGES } from '../../src/data/language-entries';
+import type { Language } from '../../src/types/common';
+
+/**
+ * Counts are compared against the snapshot rather than written out, so
+ * regenerating it -- the documented release step -- does not turn this suite red
+ * for a change it is supposed to accept. Drift from the API is checked by
+ * "npm run check:languages", which is where that belongs.
+ */
+const TIERS = ['core', 'regional', 'extended'] as const;
+const entriesIn = (category: string) => ENTRIES.filter(e => e.category === category);
 
 describe('Language Registry', () => {
   describe('LANGUAGE_REGISTRY', () => {
-    it('should contain 125 language entries', () => {
-      expect(LANGUAGE_REGISTRY.size).toBe(125);
+    it('should contain one entry per snapshot language', () => {
+      expect(LANGUAGE_REGISTRY.size).toBe(ENTRIES.length);
     });
 
     it('should have unique language codes', () => {
@@ -24,19 +34,27 @@ describe('Language Registry', () => {
       expect(unique.size).toBe(codes.length);
     });
 
-    it('should contain all 32 core languages', () => {
-      const core = Array.from(LANGUAGE_REGISTRY.values()).filter(e => e.category === 'core');
-      expect(core.length).toBe(32);
+    it.each(TIERS)('should contain every %s language from the snapshot', category => {
+      const inRegistry = Array.from(LANGUAGE_REGISTRY.values()).filter(
+        e => e.category === category,
+      );
+      expect(inRegistry.length).toBe(entriesIn(category).length);
+      expect(inRegistry.length).toBeGreaterThan(0);
     });
 
-    it('should contain all 11 regional variants', () => {
-      const regional = Array.from(LANGUAGE_REGISTRY.values()).filter(e => e.category === 'regional');
-      expect(regional.length).toBe(11);
+    it('should place every entry in exactly one known tier', () => {
+      expect(TIERS.map(entriesIn).reduce((sum, group) => sum + group.length, 0)).toBe(
+        ENTRIES.length,
+      );
     });
 
-    it('should contain all 82 extended languages', () => {
-      const extended = Array.from(LANGUAGE_REGISTRY.values()).filter(e => e.category === 'extended');
-      expect(extended.length).toBe(82);
+    /**
+     * Mirrors the generator's floor: the tiers come from the features matrix, so
+     * a matrix that stopped reporting `glossary` would retier every language as
+     * extended and make --formality and --glossary unusable everywhere.
+     */
+    it('should keep a plausible number of core languages', () => {
+      expect(entriesIn('core').length).toBeGreaterThanOrEqual(20);
     });
 
     it('should mark regional variants as targetOnly', () => {
@@ -178,14 +196,16 @@ describe('Language Registry', () => {
       expect(codes).toContain('sw');
     });
 
-    it('should return 114 languages (125 - 11 regional)', () => {
-      expect(getSourceLanguages().length).toBe(114);
+    it('should return every language that is not target-only', () => {
+      const targetOnly = ENTRIES.filter(e => 'targetOnly' in e && e.targetOnly).length;
+      expect(getSourceLanguages().length).toBe(ENTRIES.length - targetOnly);
+      expect(targetOnly).toBeGreaterThan(0);
     });
   });
 
   describe('getTargetLanguages()', () => {
     it('should include all languages', () => {
-      expect(getTargetLanguages().length).toBe(125);
+      expect(getTargetLanguages().length).toBe(ENTRIES.length);
     });
 
     it('should include regional variants', () => {
@@ -198,9 +218,9 @@ describe('Language Registry', () => {
   });
 
   describe('getAllLanguageCodes()', () => {
-    it('should return set of all 125 codes', () => {
+    it('should return a set of every snapshot code', () => {
       const codes = getAllLanguageCodes();
-      expect(codes.size).toBe(125);
+      expect(codes.size).toBe(ENTRIES.length);
     });
 
     it('should support has() lookups', () => {
@@ -213,9 +233,9 @@ describe('Language Registry', () => {
   });
 
   describe('getExtendedLanguageCodes()', () => {
-    it('should return set of 82 extended codes', () => {
+    it('should return a set of every extended code', () => {
       const codes = getExtendedLanguageCodes();
-      expect(codes.size).toBe(82);
+      expect(codes.size).toBe(entriesIn('extended').length);
     });
 
     it('should only contain extended language codes', () => {
@@ -334,6 +354,25 @@ describe('Language Registry', () => {
     });
   });
 
+  describe('Language union', () => {
+    /**
+     * Compile-time, not runtime: these assignments fail to build if the union
+     * goes back to being hand-written and falls behind the snapshot again, which
+     * is exactly how de-ch, de-de, fr-ca and fr-fr came to be missing from it.
+     */
+    it('should cover the regional variants a hand-written union had missed', () => {
+      const codes: Language[] = ['de-ch', 'de-de', 'fr-ca', 'fr-fr'];
+      codes.forEach(code => expect(isValidLanguage(code)).toBe(true));
+    });
+
+    it('should still exclude a code the snapshot does not list', () => {
+      // @ts-expect-error 'zz' is not a snapshot language; widening Language to
+      // string would make this directive unused and fail the build.
+      const unknown: Language = 'zz';
+      expect(isValidLanguage(unknown)).toBe(false);
+    });
+  });
+
   describe('looksLikeLanguageTag()', () => {
     it.each(['de', 'ace', 'de-ch', 'en-gb', 'es-419', 'zh-hans', 'bho'])(
       'should accept the well-formed tag %s',

From 3ce520b49afa66a85882bcb970ca81f1f77bd762 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:16:34 -0400
Subject: [PATCH 033/256] fix(scripts): guard the language generator against
 silent bad output

Three ways the generator could write a snapshot that breaks the CLI without
saying anything:

- an empty write list collapses the WriteLanguage union to never, so every
  --lang is rejected while the error names no valid option at all
- tiers come solely from features.glossary, so a matrix that stopped reporting
  it would retier all 125 languages as extended and make --formality and
  --glossary unusable everywhere
- --check compared quoted lowercase codes only, so the ten renamed display
  names of c955ca2 would have been reported as "formatting only"

Also fetches both resources together instead of failing fast on the first, so a
key that cannot read resource=write no longer blocks regenerating the
translation list it can read, and reports both failures at once. The rendering
is exported so the snapshot can be re-rendered from the data it already holds
when only the template changes.
---
 scripts/generate-language-registry.mjs | 228 ++++++++++++++++---------
 1 file changed, 143 insertions(+), 85 deletions(-)

diff --git a/scripts/generate-language-registry.mjs b/scripts/generate-language-registry.mjs
index ed1780a5..55314b4d 100644
--- a/scripts/generate-language-registry.mjs
+++ b/scripts/generate-language-registry.mjs
@@ -24,72 +24,47 @@ const ROOT = path.resolve(import.meta.dirname, '..');
 const TARGET = path.join(ROOT, 'src', 'data', 'language-entries.ts');
 const DERIVATION = path.join(ROOT, 'dist', 'data', 'language-registry.js');
 
-const checkOnly = process.argv.includes('--check');
+/**
+ * A tier count this far below the live shape means the derivation stopped
+ * working rather than that DeepL dropped languages -- most likely the features
+ * matrix stopped reporting `glossary`, which would silently retier all 125
+ * languages as extended and make --formality and --glossary unusable
+ * everywhere. Cheap floor, catches the whole failure class.
+ */
+const MIN_CORE_LANGUAGES = 20;
+
+const GROUPS = [
+  ['core', 'Core languages (full feature support: formality, glossary, all model types)'],
+  ['regional', 'Regional variants (target-only)'],
+  ['extended', 'Extended languages (quality_optimized only, no formality/glossary)'],
+];
 
 function fail(message) {
   console.error(`error: ${message}`);
   process.exit(1);
 }
 
-const apiKey = process.env['DEEPL_API_KEY'];
-if (!apiKey) {
-  fail('DEEPL_API_KEY is not set; the snapshot can only be generated from the live API.');
-}
-if (!existsSync(DERIVATION)) {
-  fail(`missing ${path.relative(ROOT, DERIVATION)}; run "npm run build" first.`);
-}
-
-const { deriveLanguageEntry } = await import(DERIVATION);
-
-const host = apiKey.endsWith(':fx') ? 'https://api-free.deepl.com' : 'https://api.deepl.com';
-
-async function fetchResource(resource) {
-  const response = await fetch(`${host}/v3/languages?resource=${resource}`, {
-    headers: { Authorization: `DeepL-Auth-Key ${apiKey}` },
-  });
-  if (!response.ok) {
-    fail(`GET /v3/languages?resource=${resource} returned ${response.status} ${response.statusText}`);
-  }
-  const languages = await response.json();
-  if (!Array.isArray(languages) || languages.length === 0) {
-    fail(`GET /v3/languages?resource=${resource} returned no languages`);
-  }
-  return languages;
-}
-
-const languages = await fetchResource('translate_text');
-const writeLanguages = await fetchResource('write');
-
-const entries = languages.map(deriveLanguageEntry);
-// The write endpoints take a target language only, so the list is filtered by
-// that role rather than run through deriveLanguageEntry -- write has no notion
-// of the core/regional/extended tiers.
-const writeTargets = writeLanguages
-  .filter(language => language.usable_as_target)
-  .map(language => language.lang.toLowerCase())
-  .sort((a, b) => a.localeCompare(b, 'en'));
 const byCode = (a, b) => a.code.localeCompare(b.code, 'en');
-const groups = [
-  ['core', 'Core languages (full feature support: formality, glossary, all model types)'],
-  ['regional', 'Regional variants (target-only)'],
-  ['extended', 'Extended languages (quality_optimized only, no formality/glossary)'],
-];
 
-function render(entry) {
+function renderEntry(entry) {
   const fields = [`code: '${entry.code}'`, `name: '${entry.name.replace(/'/g, "\\'")}'`];
   fields.push(`category: '${entry.category}'`);
   if (entry.targetOnly) fields.push('targetOnly: true');
   return `  { ${fields.join(', ')} },`;
 }
 
-const body = groups
-  .map(([category, heading]) => {
+/**
+ * Renders the whole file. Exported so the snapshot can be re-rendered from the
+ * data it already holds -- a formatting or type change to the template does not
+ * need a live API call to apply.
+ */
+export function renderRegistry(entries, writeTargets) {
+  const body = GROUPS.map(([category, heading]) => {
     const group = entries.filter(e => e.category === category).sort(byCode);
-    return [`  // ${heading}`, ...group.map(render)].join('\n');
-  })
-  .join('\n\n');
+    return [`  // ${heading}`, ...group.map(renderEntry)].join('\n');
+  }).join('\n\n');
 
-const contents = `/**
+  return `/**
  * Supported DeepL languages, generated from GET /v3/languages.
  *
  * DO NOT EDIT BY HAND. Run "npm run generate:languages" to refresh, and
@@ -100,12 +75,16 @@ const contents = `/**
  * the CLI can list and validate languages without a network call or API key.
  * It may therefore lag the API, which is why callers accept well-formed codes
  * it does not contain rather than rejecting them.
+ *
+ * \`as const\` is load-bearing: the Language union in src/types/common.ts is
+ * derived from these codes, so a language added upstream widens the type on
+ * regenerate instead of needing a second hand-kept copy of the same list.
  */
 import type { LanguageEntry } from './language-registry.js';
 
-export const ENTRIES: LanguageEntry[] = [
+export const ENTRIES = [
 ${body}
-];
+] as const satisfies readonly LanguageEntry[];
 
 /**
  * Target languages the Write API accepts, from resource=write.
@@ -123,42 +102,121 @@ export const WRITE_TARGET_LANGUAGES = [
 ${writeTargets.map(code => `  '${code}',`).join('\n')}
 ] as const;
 `;
+}
+
+async function main() {
+  const checkOnly = process.argv.includes('--check');
+
+  const apiKey = process.env['DEEPL_API_KEY'];
+  if (!apiKey) {
+    fail('DEEPL_API_KEY is not set; the snapshot can only be generated from the live API.');
+  }
+  if (!existsSync(DERIVATION)) {
+    fail(`missing ${path.relative(ROOT, DERIVATION)}; run "npm run build" first.`);
+  }
+
+  const { deriveLanguageEntry } = await import(DERIVATION);
+
+  const host = apiKey.endsWith(':fx') ? 'https://api-free.deepl.com' : 'https://api.deepl.com';
+
+  async function fetchResource(resource) {
+    const response = await fetch(`${host}/v3/languages?resource=${resource}`, {
+      headers: { Authorization: `DeepL-Auth-Key ${apiKey}` },
+    });
+    if (!response.ok) {
+      return {
+        resource,
+        error: `GET /v3/languages?resource=${resource} returned ${response.status} ${response.statusText}`,
+      };
+    }
+    const languages = await response.json();
+    if (!Array.isArray(languages) || languages.length === 0) {
+      return { resource, error: `GET /v3/languages?resource=${resource} returned no languages` };
+    }
+    return { resource, languages };
+  }
+
+  // Fetched together and reported together: failing fast on the first resource
+  // meant a key that cannot read resource=write blocked regenerating the
+  // translation list too, which it can read perfectly well.
+  const [translateResult, writeResult] = await Promise.all([
+    fetchResource('translate_text'),
+    fetchResource('write'),
+  ]);
+  const errors = [translateResult, writeResult].filter(r => r.error).map(r => r.error);
+  if (errors.length > 0) {
+    fail(errors.join('\n       '));
+  }
+
+  const entries = translateResult.languages.map(deriveLanguageEntry);
+  // The write endpoints take a target language only, so the list is filtered by
+  // that role rather than run through deriveLanguageEntry -- write has no notion
+  // of the core/regional/extended tiers.
+  const writeTargets = writeResult.languages
+    .filter(language => language.usable_as_target)
+    .map(language => language.lang.toLowerCase())
+    .sort((a, b) => a.localeCompare(b, 'en'));
+
+  const coreCount = entries.filter(e => e.category === 'core').length;
+  if (coreCount < MIN_CORE_LANGUAGES) {
+    fail(
+      `only ${coreCount} core languages derived (expected at least ${MIN_CORE_LANGUAGES}); ` +
+        'the features matrix probably stopped reporting "glossary". Refusing to write a ' +
+        'snapshot that would retier every language as extended.',
+    );
+  }
+  // An empty write list would collapse the WriteLanguage union to never, so
+  // every --lang would be rejected while naming no valid option at all.
+  if (writeTargets.length === 0) {
+    fail('no write target languages reported (expected usable_as_target on resource=write)');
+  }
 
-if (checkOnly) {
-  const current = existsSync(TARGET) ? readFileSync(TARGET, 'utf8') : '';
-  if (current === contents) {
-    console.log(
-      `${entries.length} languages, ${writeTargets.length} write targets; snapshot is current.`,
+  const contents = renderRegistry(entries, writeTargets);
+
+  if (checkOnly) {
+    const current = existsSync(TARGET) ? readFileSync(TARGET, 'utf8') : '';
+    if (current === contents) {
+      console.log(
+        `${entries.length} languages, ${writeTargets.length} write targets; snapshot is current.`,
+      );
+      process.exit(0);
+    }
+    // Name which list moved: the two are generated from different resources, and
+    // "N languages upstream" is misleading when it is the write list that drifted.
+    // Compared on the whole block rather than the codes alone, so a renamed
+    // display name is not reported as "formatting only".
+    const blockIn = (source, open, close) => {
+      const start = source.indexOf(open);
+      if (start === -1) return '';
+      const from = start + open.length;
+      const end = source.indexOf(close, from);
+      return source.slice(from, end === -1 ? undefined : end);
+    };
+    const blocks = [
+      ['translate_text', `${entries.length}`, 'export const ENTRIES', '\n] as const satisfies'],
+      ['write', `${writeTargets.length}`, 'export const WRITE_TARGET_LANGUAGES', '] as const;'],
+    ];
+    const drifted = blocks
+      .filter(([, , open, close]) => blockIn(current, open, close) !== blockIn(contents, open, close))
+      .map(([name, count]) => `${name} (${count} upstream)`);
+    const detail = drifted.length > 0 ? drifted.join(', ') : 'file header or formatting';
+    console.error(
+      `error: ${path.relative(ROOT, TARGET)} is out of date with the API -- ${detail}.\n` +
+        'Run: npm run generate:languages',
     );
-    process.exit(0);
+    process.exit(1);
   }
-  // Name which list moved: the two are generated from different resources, and
-  // "N languages upstream" is misleading when it is the write list that drifted.
-  const codesIn = (source, open, close) => {
-    const start = source.indexOf(open);
-    if (start === -1) return '';
-    const from = start + open.length;
-    const end = source.indexOf(close, from);
-    return (source.slice(from, end === -1 ? undefined : end).match(/'[a-z0-9-]+'/g) ?? []).join(',');
-  };
-  const blocks = [
-    ['translate_text', `${entries.length}`, 'export const ENTRIES', '\n];'],
-    ['write', `${writeTargets.length}`, 'export const WRITE_TARGET_LANGUAGES', '] as const;'],
-  ];
-  const drifted = blocks
-    .filter(([, , open, close]) => codesIn(current, open, close) !== codesIn(contents, open, close))
-    .map(([name, count]) => `${name} (${count} upstream)`);
-  const detail = drifted.length > 0 ? drifted.join(', ') : 'formatting only';
-  console.error(
-    `error: ${path.relative(ROOT, TARGET)} is out of date with the API -- ${detail}.\n` +
-      'Run: npm run generate:languages',
+
+  writeFileSync(TARGET, contents);
+  const counts = GROUPS.map(([c]) => `${c} ${entries.filter(e => e.category === c).length}`);
+  console.log(
+    `wrote ${path.relative(ROOT, TARGET)}: ${entries.length} languages (${counts.join(', ')}), ` +
+      `${writeTargets.length} write targets`,
   );
-  process.exit(1);
 }
 
-writeFileSync(TARGET, contents);
-const counts = groups.map(([c]) => `${c} ${entries.filter(e => e.category === c).length}`);
-console.log(
-  `wrote ${path.relative(ROOT, TARGET)}: ${entries.length} languages (${counts.join(', ')}), ` +
-    `${writeTargets.length} write targets`,
-);
+// Importable for re-rendering without touching the network; only the CLI entry
+// point fetches.
+if (process.argv[1] === import.meta.filename) {
+  await main();
+}

From 7798e9b8027911d50dca221d895f364e0f5115e0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:24:18 -0400
Subject: [PATCH 034/256] fix(languages): stop --features claiming knowledge it
 does not have

The listing keeps snapshot entries the API response omitted, so those rows had
no feature data -- and every one of them was rendered as the positive claim
"none". With a response covering a handful of languages, --features reported
over a hundred languages as supporting nothing. Those rows also made every
feature look non-uniform, so features shared by all the described languages
became columns of repeated values instead of the single footer note the feature
was built around.

A language the response did not describe now reads as unknown, only described
languages decide what varies, and the shared-feature note says "languages with
reported features" when some rows have none, so it does not speak for them.

Two smaller lies with it:

- a feature reported without a `status` rendered as literal "undefined"; the
  enum is open and an absent status still means the feature is there
- supportsFormality was asserted false for a language whose features the
  response never mentioned, turning on the "[F] = supports formality" legend
  with no [F] anywhere to explain it

Also fetches /v3/languages once per client: both roles are filtered out of the
same payload, so `deepl languages` was making the identical full-list request
twice.
---
 src/api/translation-client.ts         | 40 ++++++++++++---
 src/cli/commands/languages.ts         | 73 +++++++++++++++++++++------
 tests/e2e/cli-languages.e2e.test.ts   | 16 +++++-
 tests/unit/languages-command.test.ts  | 28 +++++++++-
 tests/unit/translation-client.test.ts | 19 ++++++-
 5 files changed, 148 insertions(+), 28 deletions(-)

diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index 0588491f..38a363bf 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -288,15 +288,35 @@ export class TranslationClient extends HttpClient {
    * here to preserve the per-type contract. Formality support comes from the
    * per-language features matrix, which is what v2's supports_formality became.
    */
+  /**
+   * The raw translate_text language list, fetched at most once per client.
+   *
+   * Both roles are filtered out of one payload, and the request does not vary by
+   * role, so `deepl languages` -- which asks for both -- was making the same
+   * full-list request twice. A failed fetch is not retained, so the next caller
+   * retries.
+   */
+  private translateLanguages?: Promise<DeepLV3LanguageResponse[]>;
+
+  private fetchTranslateLanguages(): Promise<DeepLV3LanguageResponse[]> {
+    if (!this.translateLanguages) {
+      this.translateLanguages = this.makeRequest<DeepLV3LanguageResponse[]>(
+        'GET',
+        '/v3/languages',
+        { resource: 'translate_text' }
+      ).catch((error: unknown) => {
+        delete this.translateLanguages;
+        throw error;
+      });
+    }
+    return this.translateLanguages;
+  }
+
   async getSupportedLanguages(
     type: 'source' | 'target'
   ): Promise<LanguageInfo[]> {
     try {
-      const response = await this.makeRequest<DeepLV3LanguageResponse[]>(
-        'GET',
-        '/v3/languages',
-        { resource: 'translate_text' }
-      );
+      const response = await this.fetchTranslateLanguages();
 
       return response
         .filter((lang) => (type === 'source' ? lang.usable_as_source : lang.usable_as_target))
@@ -305,9 +325,13 @@ export class TranslationClient extends HttpClient {
           return {
             language: code,
             name: lang.name,
-            ...(type === 'target' && {
-              supportsFormality: lang.features?.['formality'] !== undefined,
-            }),
+            // Only claimed when the response actually described this language's
+            // features: asserting false for a language it said nothing about
+            // turned the [F] legend on with no [F] anywhere to explain it.
+            ...(type === 'target' &&
+              lang.features && {
+                supportsFormality: lang.features['formality'] !== undefined,
+              }),
             ...(lang.features && { features: lang.features }),
           };
         });
diff --git a/src/cli/commands/languages.ts b/src/cli/commands/languages.ts
index 51003562..2a20079a 100644
--- a/src/cli/commands/languages.ts
+++ b/src/cli/commands/languages.ts
@@ -46,15 +46,33 @@ function featureLabel(key: string): string {
   );
 }
 
+/** Cell text for a language the response carried no feature data for at all. */
+const UNKNOWN_CELL = '?';
+
+/**
+ * Whether the response described this language's features at all. An empty
+ * matrix is data -- it says the language supports none of them -- while a
+ * missing one means the language never appeared in the response.
+ */
+function hasFeatureData(entry: LanguageDisplayEntry): boolean {
+  return entry.features !== undefined;
+}
+
 /**
  * Cell text for one feature on one language. A feature is supported when the
  * API reports the key at all; `status` describes maturity, so anything other
- * than `stable` is shown verbatim rather than collapsed to yes.
+ * than `stable` is shown verbatim rather than collapsed to yes. `status` is an
+ * open enum and may be absent, which still means the feature is there.
+ *
+ * A language the response omitted entirely reads as unknown rather than
+ * unsupported: the listing keeps snapshot entries the API did not mention, and
+ * claiming they support nothing would be inventing an answer.
  */
 function featureCell(entry: LanguageDisplayEntry, key: string): string {
+  if (!hasFeatureData(entry)) return UNKNOWN_CELL;
   const feature = entry.features?.[key];
   if (!feature) return '—';
-  return feature.status === 'stable' ? 'yes' : feature.status;
+  return !feature.status || feature.status === 'stable' ? 'yes' : feature.status;
 }
 
 function sortFeatureKeys(keys: string[]): string[] {
@@ -78,18 +96,22 @@ export function partitionFeatureKeys(entries: LanguageDisplayEntry[]): {
   columns: string[];
   uniform: Array<{ key: string; cell: string }>;
 } {
-  if (entries.length === 0) return { columns: [], uniform: [] };
+  // Only languages the response described can say whether a feature varies;
+  // including the rest made every feature look non-uniform, so a feature all of
+  // them share became a column of repeated values instead of one footer note.
+  const described = entries.filter(hasFeatureData);
+  if (described.length === 0) return { columns: [], uniform: [] };
 
   const allKeys = new Set<string>();
-  for (const entry of entries) {
+  for (const entry of described) {
     for (const key of Object.keys(entry.features ?? {})) allKeys.add(key);
   }
 
   const columns: string[] = [];
   const uniform: Array<{ key: string; cell: string }> = [];
   for (const key of allKeys) {
-    const first = featureCell(entries[0]!, key);
-    if (entries.some(entry => featureCell(entry, key) !== first)) {
+    const first = featureCell(described[0]!, key);
+    if (described.some(entry => featureCell(entry, key) !== first)) {
       columns.push(key);
     } else {
       uniform.push({ key, cell: first });
@@ -105,11 +127,18 @@ export function partitionFeatureKeys(entries: LanguageDisplayEntry[]): {
 }
 
 function hasAnyFeatures(entries: LanguageDisplayEntry[]): boolean {
-  return entries.some(entry => Object.keys(entry.features ?? {}).length > 0);
+  return entries.some(hasFeatureData);
 }
 
-/** Lowercased feature list for prose contexts, e.g. `glossary, style rules`. */
+/**
+ * Lowercased feature list for prose contexts, e.g. `glossary, style rules`.
+ * Empty when there is nothing per-language to say: with no discriminating
+ * features the footer note carries the answer, and annotating every row `none`
+ * would contradict it.
+ */
 function featureList(entry: LanguageDisplayEntry, keys: string[]): string {
+  if (!hasFeatureData(entry)) return 'no feature data';
+  if (keys.length === 0) return '';
   const supported = keys
     .filter(key => featureCell(entry, key) !== '—')
     .map(key => {
@@ -120,8 +149,16 @@ function featureList(entry: LanguageDisplayEntry, keys: string[]): string {
   return supported.length > 0 ? supported.join(', ') : 'none';
 }
 
-function uniformNote(uniform: Array<{ key: string; cell: string }>): string | undefined {
-  const supported = uniform.filter(u => u.cell !== '—');
+/**
+ * The one-line summary for features every language shares. Scoped to the
+ * languages the response described when some rows carry no data, since those
+ * rows are listed too and the note must not speak for them.
+ */
+function uniformNote(
+  uniform: Array<{ key: string; cell: string }>,
+  entries: LanguageDisplayEntry[],
+): string | undefined {
+  const supported = uniform.filter(u => u.cell !== '—' && u.cell !== UNKNOWN_CELL);
   if (supported.length === 0) return undefined;
   const list = supported
     .map(u => {
@@ -129,7 +166,10 @@ function uniformNote(uniform: Array<{ key: string; cell: string }>): string | un
       return u.cell === 'yes' ? label : `${label} (${u.cell})`;
     })
     .join(', ');
-  return `All listed languages also support: ${list}.`;
+  const subject = entries.every(hasFeatureData)
+    ? 'All listed languages'
+    : 'All languages with reported features';
+  return `${subject} also support: ${list}.`;
 }
 
 export class LanguagesCommand {
@@ -263,8 +303,11 @@ export class LanguagesCommand {
     const { columns, uniform } = renderFeatures
       ? partitionFeatureKeys(entries)
       : { columns: [], uniform: [] };
-    const suffix = (entry: LanguageDisplayEntry): string =>
-      renderFeatures ? chalk.gray(` — ${featureList(entry, columns)}`) : '';
+    const suffix = (entry: LanguageDisplayEntry): string => {
+      if (!renderFeatures) return '';
+      const list = featureList(entry, columns);
+      return list ? chalk.gray(` — ${list}`) : '';
+    };
 
     coreAndRegional.forEach(entry => {
       const code = entry.code.padEnd(maxCodeLength + 2);
@@ -286,7 +329,7 @@ export class LanguagesCommand {
       lines.push(chalk.gray('  [F] = supports formality parameter'));
     }
 
-    const note = renderFeatures ? uniformNote(uniform) : undefined;
+    const note = renderFeatures ? uniformNote(uniform, entries) : undefined;
     if (note) {
       lines.push('');
       lines.push(chalk.gray(`  ${note}`));
@@ -366,7 +409,7 @@ export class LanguagesCommand {
       table.push(row);
     }
 
-    const note = renderFeatures ? uniformNote(uniform) : undefined;
+    const note = renderFeatures ? uniformNote(uniform, entries) : undefined;
     return `${header}:\n${table.toString()}${note ? `\n${note}` : ''}`;
   }
 
diff --git a/tests/e2e/cli-languages.e2e.test.ts b/tests/e2e/cli-languages.e2e.test.ts
index 4c2e71b8..8283a661 100644
--- a/tests/e2e/cli-languages.e2e.test.ts
+++ b/tests/e2e/cli-languages.e2e.test.ts
@@ -167,10 +167,22 @@ describe('Languages Command E2E', () => {
       const german = output.split('\n').find(line => line.includes('German'));
       const english = output.split('\n').find(line => line.includes('English (British)'));
 
+      // formality is what varies across the languages the mock describes, so it
+      // is the per-row annotation; glossary is shared by all of them and is
+      // reported once at the end instead of on every row.
       expect(german).toContain('formality');
-      expect(german).toContain('glossary');
-      expect(english).toContain('glossary');
       expect(english).not.toContain('formality');
+      expect(output).toContain('glossary');
+    });
+
+    it('should scope the shared-feature note to the languages it has data for', () => {
+      const output = featuresRunCLI('languages --target --features');
+
+      // The listing also carries snapshot languages the mock never returned, so
+      // the note must not speak for them.
+      expect(output).toContain('All languages with reported features also support');
+      const zulu = output.split('\n').find(line => line.includes('Zulu'));
+      expect(zulu).toContain('no feature data');
     });
 
     // Column suppression is asserted in the unit tests: the row set here is the
diff --git a/tests/unit/languages-command.test.ts b/tests/unit/languages-command.test.ts
index 2ac3c977..e3115584 100644
--- a/tests/unit/languages-command.test.ts
+++ b/tests/unit/languages-command.test.ts
@@ -651,9 +651,33 @@ describe('LanguagesCommand', () => {
         },
       ];
       const formatted = languagesCommand.formatLanguages(apiLangs, 'target', true);
-      const de = formatted.split('\n').find(l => l.includes('German'));
 
-      expect(de).toContain('glossary');
+      // Reported once for the whole listing rather than per row: the languages
+      // the response omitted carry no feature data, so they cannot make glossary
+      // look like a discriminating column.
+      expect(formatted).toContain('glossary');
+    });
+
+    it('should report a language the response omitted as unknown, not as supporting nothing', () => {
+      const apiLangs: LanguageInfo[] = [
+        {
+          language: 'de',
+          name: 'German',
+          supportsFormality: true,
+          features: { glossary: { status: 'stable' }, formality: { status: 'stable' } },
+        },
+        {
+          language: 'pt',
+          name: 'Portuguese',
+          supportsFormality: true,
+          features: { glossary: { status: 'stable' } },
+        },
+      ];
+      const formatted = languagesCommand.formatLanguages(apiLangs, 'target', true);
+      const zulu = formatted.split('\n').find(l => l.includes('Zulu'));
+
+      expect(zulu).toContain('no feature data');
+      expect(zulu).not.toContain('none');
     });
 
     it('should add a column per discriminating feature in table output', () => {
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index dd2d5334..52f5cedc 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -503,8 +503,25 @@ describe('TranslationClient', () => {
 
       const result = await client.getSupportedLanguages('target');
 
+      // Formality support is left unstated rather than denied: a response that
+      // described no features is not evidence that formality is unavailable, and
+      // claiming false turned on the [F] legend with no [F] to explain.
       expect(result[0]).not.toHaveProperty('features');
-      expect(result[0]!.supportsFormality).toBe(false);
+      expect(result[0]!.supportsFormality).toBeUndefined();
+    });
+
+    it('should fetch the language list once for both roles', async () => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: [{ lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true }],
+        status: 200,
+        headers: {},
+      });
+
+      await client.getSupportedLanguages('source');
+      await client.getSupportedLanguages('target');
+
+      // The request does not vary by role -- both are filtered out of one payload.
+      expect(mockAxiosInstance.request).toHaveBeenCalledTimes(1);
     });
   });
 

From 49756349388251a837e0992ee9583eccb6373017 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:34:39 -0400
Subject: [PATCH 035/256] fix(voice): keep partial transcripts and match echoed
 languages case-insensitively

Failing a session that ends with a target untranslated was the right call, but
two things made it worse than the silence it replaced.

Target updates were matched against the exact requested spelling, and the
requested set uses casings like zh-HANS and en-GB. A server echoing another
canonicalization had its translation dropped by the existing `if (target)`
guard, and the new check then reported that target as missing -- turning a
cosmetic mismatch into a failed session. Lookups are keyed lowercase now.

A single missing target also discarded the source transcript and every
successful translation, after the audio had been transcribed and billed. The
failure now carries what did arrive, and the command prints it to stderr before
exiting non-zero, so nothing has to be re-streamed to see it.
---
 src/cli/commands/voice.ts               | 28 ++++++++++++
 src/services/voice-stream-session.ts    | 37 ++++++++++++----
 tests/unit/voice-stream-session.test.ts | 58 ++++++++++++++++++++++++-
 3 files changed, 114 insertions(+), 9 deletions(-)

diff --git a/src/cli/commands/voice.ts b/src/cli/commands/voice.ts
index 26246faf..f8cdfeca 100644
--- a/src/cli/commands/voice.ts
+++ b/src/cli/commands/voice.ts
@@ -17,6 +17,8 @@ import type {
   VoiceSourceMediaContentType,
 } from '../../types/index.js';
 import { ValidationError } from '../../utils/errors.js';
+import { Logger } from '../../utils/logger.js';
+import { VoicePartialResultError } from '../../services/voice-stream-session.js';
 
 const VALID_VOICE_TARGET_LANGS: ReadonlySet<string> = new Set<VoiceTargetLanguage>([
   'ar','bg','cs','da','de','el','en','en-GB','en-US','es','et','fi','fr',
@@ -83,6 +85,9 @@ export class VoiceCommand {
       }
 
       return this.formatResult(result, options.format);
+    } catch (error) {
+      this.reportPartialResult(error, translateOptions.targetLangs.length, isTTY);
+      throw error;
     } finally {
       process.removeListener('SIGINT', sigintHandler);
     }
@@ -108,6 +113,9 @@ export class VoiceCommand {
       }
 
       return this.formatResult(result, options.format);
+    } catch (error) {
+      this.reportPartialResult(error, translateOptions.targetLangs.length, isTTY);
+      throw error;
     } finally {
       process.removeListener('SIGINT', sigintHandler);
     }
@@ -252,6 +260,26 @@ export class VoiceCommand {
     readline.moveCursor(process.stdout, 0, -(lineCount - 1));
   }
 
+  /**
+   * Print what a failed session did produce. The audio is transcribed and billed
+   * before the missing translation is noticed, so discarding the transcripts
+   * would make the user re-stream and pay again to see them. Written to stderr so
+   * a partial result is never mistaken for the command's output.
+   */
+  private reportPartialResult(error: unknown, targetCount: number, isTTY: boolean): void {
+    if (!(error instanceof VoicePartialResultError)) {
+      return;
+    }
+    if (isTTY) {
+      this.clearTTYDisplay(targetCount);
+    }
+    const salvaged = this.formatResult(error.result);
+    if (salvaged.trim() !== '') {
+      Logger.warn(chalk.yellow('Partial result before the session failed:'));
+      Logger.warn(salvaged);
+    }
+  }
+
   private formatResult(result: VoiceSessionResult, format?: string): string {
     if (format === 'json') {
       return formatVoiceJson(result);
diff --git a/src/services/voice-stream-session.ts b/src/services/voice-stream-session.ts
index 7d3f7786..bb09a3e4 100644
--- a/src/services/voice-stream-session.ts
+++ b/src/services/voice-stream-session.ts
@@ -22,6 +22,21 @@ import type {
 
 const DEFAULT_MAX_RECONNECT_ATTEMPTS = 3;
 
+/**
+ * A session that ended with at least one target untranslated, carrying whatever
+ * did arrive. The audio has been transcribed and billed by this point, so the
+ * partial transcripts travel with the failure instead of being discarded.
+ */
+export class VoicePartialResultError extends VoiceError {
+  constructor(
+    message: string,
+    suggestion: string,
+    readonly result: VoiceSessionResult,
+  ) {
+    super(message, suggestion);
+  }
+}
+
 export class VoiceStreamSession {
   private readonly client: VoiceClient;
   private readonly session: VoiceSessionResponse;
@@ -61,7 +76,10 @@ export class VoiceStreamSession {
 
     for (const lang of options.targetLangs) {
       const transcript: VoiceTranscript = { lang, text: '', segments: [] };
-      this.targetTranscripts.set(lang, transcript);
+      // Keyed lowercase because the requested spellings (zh-HANS, en-GB) are not
+      // the only canonicalization the server might echo, and an unmatched update
+      // is dropped silently -- which then reads as a missing translation.
+      this.targetTranscripts.set(lang.toLowerCase(), transcript);
       this.textParts.set(transcript, []);
     }
   }
@@ -118,7 +136,7 @@ export class VoiceStreamSession {
         this.callbacks?.onSourceTranscript?.(update);
       },
       onTargetTranscript: (update: VoiceTargetTranscriptUpdate) => {
-        const target = this.targetTranscripts.get(update.language);
+        const target = this.targetTranscripts.get(update.language.toLowerCase());
         if (target) {
           this.accumulateTranscript(target, update.concluded);
         }
@@ -137,23 +155,26 @@ export class VoiceStreamSession {
         this.closeInput();
         this.finalizeTranscripts();
 
+        const result: VoiceSessionResult = {
+          sessionId: this.session.session_id,
+          source: this.sourceTranscript,
+          targets: Array.from(this.targetTranscripts.values()),
+        };
+
         const untranslated = this.untranslatedTargets();
         if (untranslated.length > 0) {
           this.fail(
             reject,
-            new VoiceError(
+            new VoicePartialResultError(
               `Voice session ended without a translation for: ${untranslated.join(', ')}.`,
               'The audio was transcribed but the server sent no translated text. Retry the request.',
+              result,
             ),
           );
           return;
         }
 
-        resolve({
-          sessionId: this.session.session_id,
-          source: this.sourceTranscript,
-          targets: Array.from(this.targetTranscripts.values()),
-        });
+        resolve(result);
       },
       onError: (error) => {
         this.callbacks?.onError?.(error);
diff --git a/tests/unit/voice-stream-session.test.ts b/tests/unit/voice-stream-session.test.ts
index cf451a5f..1e4b9cd4 100644
--- a/tests/unit/voice-stream-session.test.ts
+++ b/tests/unit/voice-stream-session.test.ts
@@ -5,7 +5,10 @@
  * and transcript accumulation directly on the extracted class.
  */
 
-import { VoiceStreamSession } from '../../src/services/voice-stream-session.js';
+import {
+  VoiceStreamSession,
+  VoicePartialResultError,
+} from '../../src/services/voice-stream-session.js';
 import { VoiceClient } from '../../src/api/voice-client.js';
 import { VoiceError } from '../../src/utils/errors.js';
 import type {
@@ -13,6 +16,7 @@ import type {
   VoiceSessionResult,
   VoiceTranslateOptions,
   VoiceStreamCallbacks,
+  VoiceTargetLanguage,
 } from '../../src/types/voice.js';
 import { createMockVoiceClient } from '../helpers/mock-factories';
 
@@ -793,6 +797,58 @@ describe('VoiceStreamSession', () => {
       expect(result.targets[0]!.text).toBe('');
     });
 
+    it('should match the echoed language regardless of casing', async () => {
+      // The requested set spells variants zh-HANS and en-GB; a server echoing
+      // another canonicalization used to have its translation dropped on the
+      // floor and then reported as missing.
+      const result = await runWithFrames(
+        (callbacks) => {
+          callbacks.onSourceTranscript?.({
+            concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+            tentative: [],
+          });
+          callbacks.onTargetTranscript?.({
+            // Cast because the union only spells the requested casing; the wire
+            // is not bound by it, which is the whole hazard here.
+            language: 'zh-Hans' as VoiceTargetLanguage,
+            concluded: [{ text: '你好', start_time: 0, end_time: 1 }],
+            tentative: [],
+          });
+        },
+        { targetLangs: ['zh-HANS'], chunkInterval: 0 },
+      );
+
+      expect(result.targets[0]!.text).toBe('你好');
+      expect(result.targets[0]!.lang).toBe('zh-HANS');
+    });
+
+    it('should carry the salvaged transcripts on the error', async () => {
+      expect.assertions(3);
+      try {
+        await runWithFrames(
+          (callbacks) => {
+            callbacks.onSourceTranscript?.({
+              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+              tentative: [],
+            });
+            callbacks.onTargetTranscript?.({
+              language: 'fr',
+              concluded: [{ text: 'Bonjour', start_time: 0, end_time: 1 }],
+              tentative: [],
+            });
+          },
+          { targetLangs: ['fr', 'de'], chunkInterval: 0 },
+        );
+      } catch (error) {
+        // The audio is billed either way, so what did arrive must not be thrown
+        // away with the failure.
+        const partial = (error as VoicePartialResultError).result;
+        expect(partial.source.text).toBe('Hello');
+        expect(partial.targets.find(t => t.lang === 'fr')?.text).toBe('Bonjour');
+        expect(partial.targets.find(t => t.lang === 'de')?.text).toBe('');
+      }
+    });
+
     it('should close the input generator when rejecting', async () => {
       const tracked = trackedChunks();
 

From 8c699a9473103b6c5fe288f896202214e57abf06 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:34:39 -0400
Subject: [PATCH 036/256] fix(usage): stop reporting API-key usage as the
 account total

Duration-billed products fell back to `apiKeyUnitCount` for the account column
because live responses omit `unit_count` for them -- so `deepl usage` printed
the same number twice, as though the key accounted for all voice usage on the
account. The account-wide figure the response does carry, `account_unit_count`,
was neither typed nor parsed.

It is parsed now, and when no account-wide figure is present the row says
"(API key)" rather than inventing a total.
---
 src/api/translation-client.ts    | 26 +++++++++++++++----------
 src/cli/commands/usage.ts        | 33 ++++++++++++++++++++++++--------
 tests/unit/usage-command.test.ts | 24 ++++++++++++++++++++++-
 3 files changed, 64 insertions(+), 19 deletions(-)

diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index 38a363bf..1d031cb9 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -38,6 +38,7 @@ interface DeepLUsageResponse {
     character_count: number;
     api_key_character_count: number;
     unit_count?: number;
+    account_unit_count?: number;
     api_key_unit_count?: number;
     billing_unit?: string;
   }>;
@@ -74,6 +75,12 @@ export interface ProductUsage {
   characterCount: number;
   apiKeyCharacterCount: number;
   unitCount?: number;
+  /**
+   * Account-wide units. What live responses actually carry for duration-billed
+   * products, where `unit_count` is absent -- so leaving it unparsed made the
+   * account total unreportable.
+   */
+  accountUnitCount?: number;
   apiKeyUnitCount?: number;
   billingUnit?: string;
 }
@@ -232,6 +239,7 @@ export class TranslationClient extends HttpClient {
           characterCount: p.character_count,
           apiKeyCharacterCount: p.api_key_character_count,
           ...(p.unit_count !== undefined && { unitCount: p.unit_count }),
+          ...(p.account_unit_count !== undefined && { accountUnitCount: p.account_unit_count }),
           ...(p.api_key_unit_count !== undefined && { apiKeyUnitCount: p.api_key_unit_count }),
           ...(p.billing_unit && { billingUnit: p.billing_unit }),
         }));
@@ -299,16 +307,14 @@ export class TranslationClient extends HttpClient {
   private translateLanguages?: Promise<DeepLV3LanguageResponse[]>;
 
   private fetchTranslateLanguages(): Promise<DeepLV3LanguageResponse[]> {
-    if (!this.translateLanguages) {
-      this.translateLanguages = this.makeRequest<DeepLV3LanguageResponse[]>(
-        'GET',
-        '/v3/languages',
-        { resource: 'translate_text' }
-      ).catch((error: unknown) => {
-        delete this.translateLanguages;
-        throw error;
-      });
-    }
+    this.translateLanguages ??= this.makeRequest<DeepLV3LanguageResponse[]>(
+      'GET',
+      '/v3/languages',
+      { resource: 'translate_text' }
+    ).catch((error: unknown) => {
+      delete this.translateLanguages;
+      throw error;
+    });
     return this.translateLanguages;
   }
 
diff --git a/src/cli/commands/usage.ts b/src/cli/commands/usage.ts
index dba29db0..53127626 100644
--- a/src/cli/commands/usage.ts
+++ b/src/cli/commands/usage.ts
@@ -21,12 +21,25 @@ function isDurationBilled(product: ProductUsage): boolean {
   return product.billingUnit !== undefined && DURATION_BILLING_UNITS.has(product.billingUnit);
 }
 
-/** Duration-billed usage in milliseconds: total and API-key-scoped amounts. */
-function productDurationsMs(product: ProductUsage): { used: number; apiKeyUsed: number } {
+/**
+ * Duration-billed usage in milliseconds: the account-wide amount where the
+ * response carries one, and the API-key-scoped amount.
+ *
+ * `accountUsed` stays undefined rather than falling back to the API-key figure:
+ * live responses omit `unit_count` for these products, so the fallback printed
+ * the key's own usage in the account column and the two were always equal.
+ */
+function productDurationsMs(product: ProductUsage): {
+  accountUsed: number | undefined;
+  apiKeyUsed: number;
+} {
   const scale = product.billingUnit === 'minutes' ? 60_000 : 1;
-  const used = product.unitCount ?? product.apiKeyUnitCount ?? product.characterCount;
+  const account = product.unitCount ?? product.accountUnitCount;
   const apiKeyUsed = product.apiKeyUnitCount ?? product.apiKeyCharacterCount;
-  return { used: used * scale, apiKeyUsed: apiKeyUsed * scale };
+  return {
+    accountUsed: account === undefined ? undefined : account * scale,
+    apiKeyUsed: apiKeyUsed * scale,
+  };
 }
 
 export class UsageCommand {
@@ -109,8 +122,12 @@ export class UsageCommand {
       for (const product of usage.products) {
         const name = productDisplayName(product.productType);
         if (isDurationBilled(product)) {
-          const { used, apiKeyUsed } = productDurationsMs(product);
-          lines.push(`  ${name}: ${this.formatMilliseconds(used)} (API key: ${this.formatMilliseconds(apiKeyUsed)})`);
+          const { accountUsed, apiKeyUsed } = productDurationsMs(product);
+          lines.push(
+            accountUsed === undefined
+              ? `  ${name}: ${this.formatMilliseconds(apiKeyUsed)} (API key)`
+              : `  ${name}: ${this.formatMilliseconds(accountUsed)} (API key: ${this.formatMilliseconds(apiKeyUsed)})`,
+          );
         } else if (product.unitCount !== undefined) {
           const apiKeyPart = product.apiKeyUnitCount !== undefined
             ? ` (API key: ${formatNumber(product.apiKeyUnitCount)} units)`
@@ -198,10 +215,10 @@ export class UsageCommand {
       for (const product of usage.products) {
         const name = productDisplayName(product.productType);
         if (isDurationBilled(product)) {
-          const { used, apiKeyUsed } = productDurationsMs(product);
+          const { accountUsed, apiKeyUsed } = productDurationsMs(product);
           productTable.push([
             name,
-            this.formatMilliseconds(used),
+            accountUsed === undefined ? '—' : this.formatMilliseconds(accountUsed),
             this.formatMilliseconds(apiKeyUsed),
           ]);
         } else if (product.unitCount !== undefined) {
diff --git a/tests/unit/usage-command.test.ts b/tests/unit/usage-command.test.ts
index 02cec009..59887458 100644
--- a/tests/unit/usage-command.test.ts
+++ b/tests/unit/usage-command.test.ts
@@ -340,10 +340,32 @@ describe('UsageCommand', () => {
         ],
       });
 
-      expect(formatted).toContain('speech_to_text: 24h 23m 0s (API key: 24h 23m 0s)');
+      // No account-wide figure in the response, so only the API key's own usage
+      // is reported. Printing it in both columns implied an account total the
+      // response never carried.
+      expect(formatted).toContain('speech_to_text: 24h 23m 0s (API key)');
       expect(formatted).not.toContain('speech_to_text: 0 characters');
     });
 
+    it('should report the account-wide duration when the response carries one', () => {
+      const formatted = usageCommand.formatUsage({
+        characterCount: 0,
+        characterLimit: 20000000,
+        products: [
+          {
+            productType: 'speechToText',
+            characterCount: 0,
+            apiKeyCharacterCount: 0,
+            accountUnitCount: 6000,
+            apiKeyUnitCount: 1463,
+            billingUnit: 'minutes',
+          },
+        ],
+      });
+
+      expect(formatted).toContain('speech_to_text: 100h 0m 0s (API key: 24h 23m 0s)');
+    });
+
     it('should prefer unitCount over apiKeyUnitCount for minutes-billed totals', () => {
       const formatted = usageCommand.formatUsage({
         characterCount: 0,

From a7bb0447414dcb72651dc0337286160deb77c095 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 17:34:47 -0400
Subject: [PATCH 037/256] fix(translate): stop repeating a doomed request and
 say when a code is deferred

Since validation defers unknown-but-well-formed codes to the API, a two-letter
typo now reaches it -- and a directory translation asked the same rejected
question once per batch, spending a round trip each time to be told the same
thing. An unsupported target_lang or source_lang is a property of the request,
not of one batch, so the remaining batches fail without being sent. Errors
specific to a batch still let the run continue.

Local validation also used to be the thing that pointed at `deepl languages`,
and deferring left the user with a bare "target_lang not supported" from the
server. A code the bundled snapshot does not list now says so up front, before
anything is sent or billed.
---
 src/cli/commands/translate/translate-utils.ts | 11 ++++-
 src/services/batch-translation.ts             | 17 +++++++
 src/utils/unrecoverable-request-error.ts      | 21 ++++++++
 tests/unit/services/batch-translation.test.ts | 48 +++++++++++++++++++
 tests/unit/translate-utils.test.ts            | 18 +++++++
 5 files changed, 114 insertions(+), 1 deletion(-)
 create mode 100644 src/utils/unrecoverable-request-error.ts

diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index b387c420..a24544ef 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -68,7 +68,16 @@ export function warnIgnoredOptions(mode: string, options: TranslateOptions, supp
 export function validateLanguageCodes(langCodes: string[]): void {
   for (const lang of langCodes) {
     if (VALID_LANGUAGES.has(lang)) continue;
-    if (looksLikeLanguageTag(lang)) continue;
+    if (looksLikeLanguageTag(lang)) {
+      // Said up front, before anything is sent or billed. Deferring to the API
+      // means a two-letter typo now comes back as a bare "target_lang not
+      // supported" from the server, which no longer points anywhere useful.
+      Logger.warn(
+        `Note: "${lang}" is not in the bundled language list; deferring to the API.\n` +
+          '      Run: deepl languages  to see the languages this build knows about.'
+      );
+      continue;
+    }
     throw new ValidationError(
       `Invalid target language code: "${lang}".`,
       'Run: deepl languages  to see all available languages'
diff --git a/src/services/batch-translation.ts b/src/services/batch-translation.ts
index 7dcbc535..b4a087f2 100644
--- a/src/services/batch-translation.ts
+++ b/src/services/batch-translation.ts
@@ -15,6 +15,7 @@ import { TranslationOptions } from '../types/index.js';
 import { safeReadFile } from '../utils/safe-read-file.js';
 import { Logger } from '../utils/logger.js';
 import { ValidationError } from '../utils/errors.js';
+import { isUnrecoverableRequestError } from '../utils/unrecoverable-request-error.js';
 import { errorMessage } from '../utils/error-message.js';
 
 interface BatchOptions {
@@ -220,6 +221,10 @@ export class BatchTranslationService {
     let completed = startCompleted;
     let currentBatch: FileEntry[] = [];
     let currentBytes = 0;
+    // Set once the API rejects the request itself (an unsupported target_lang,
+    // say). Every remaining batch would be told the same thing, so they are
+    // failed without spending the round trips.
+    let requestRejected: unknown;
 
     const flushBatch = async (): Promise<void> => {
       const batch = currentBatch;
@@ -229,6 +234,15 @@ export class BatchTranslationService {
         return;
       }
 
+      if (requestRejected !== undefined) {
+        for (const entry of batch) {
+          failed.push({ file: entry.file, error: errorMessage(requestRejected) });
+          completed++;
+          onProgress?.({ completed, total: totalFiles, current: entry.file });
+        }
+        return;
+      }
+
       if (batchOptions.abortSignal?.aborted) {
         for (const entry of batch) {
           completed++;
@@ -275,6 +289,9 @@ export class BatchTranslationService {
           onProgress?.({ completed, total: totalFiles, current: entry.file });
         }
       } catch (error) {
+        if (isUnrecoverableRequestError(error)) {
+          requestRejected = error;
+        }
         Logger.error(`Batch translation failed: ${errorMessage(error)}`);
         for (const entry of batch) {
           failed.push({
diff --git a/src/utils/unrecoverable-request-error.ts b/src/utils/unrecoverable-request-error.ts
new file mode 100644
index 00000000..5f7efb9d
--- /dev/null
+++ b/src/utils/unrecoverable-request-error.ts
@@ -0,0 +1,21 @@
+import { errorMessage } from './error-message.js';
+
+/**
+ * Whether an error means the request itself is wrong, not that this particular
+ * item failed.
+ *
+ * A rejected `target_lang` is the same rejection for every file and every target
+ * in the run, so retrying it per batch buys nothing: it just spends another round
+ * trip -- and bills the items that do succeed -- to be told the same thing again.
+ * Language validation defers to the API on codes the bundled snapshot predates,
+ * which is what makes this reachable from a plain typo.
+ */
+export function isUnrecoverableRequestError(error: unknown): boolean {
+  const message = errorMessage(error).toLowerCase();
+  return (
+    message.includes("value for 'target_lang' not supported") ||
+    message.includes("value for 'source_lang' not supported") ||
+    message.includes('target_lang not supported') ||
+    message.includes('source_lang not supported')
+  );
+}
diff --git a/tests/unit/services/batch-translation.test.ts b/tests/unit/services/batch-translation.test.ts
index d86cd5cc..bd3ebea3 100644
--- a/tests/unit/services/batch-translation.test.ts
+++ b/tests/unit/services/batch-translation.test.ts
@@ -502,6 +502,54 @@ describe('BatchTranslationService', () => {
       expect(secondCallTexts).toHaveLength(2);
     });
 
+    it('should stop requesting once the API rejects the target language', async () => {
+      const files: string[] = [];
+      for (let i = 0; i < 52; i++) {
+        const f = path.join(testDir, `reject${i}.txt`);
+        fs.writeFileSync(f, `Text ${i}`);
+        files.push(f);
+      }
+
+      mockTranslationService.translateBatch.mockRejectedValue(
+        new Error("API error: Value for 'target_lang' not supported."),
+      );
+
+      const result = await batchServiceWithTranslation.translateFiles(
+        files,
+        { targetLang: 'ex' as never },
+        { outputDir: testDir },
+      );
+
+      // The same rejection applies to every batch, so it is asked once rather
+      // than once per batch.
+      expect(mockTranslationService.translateBatch).toHaveBeenCalledTimes(1);
+      expect(result.failed).toHaveLength(52);
+      expect(result.successful).toHaveLength(0);
+    });
+
+    it('should keep going when a batch fails for a reason specific to it', async () => {
+      const files: string[] = [];
+      for (let i = 0; i < 52; i++) {
+        const f = path.join(testDir, `partial${i}.txt`);
+        fs.writeFileSync(f, `Text ${i}`);
+        files.push(f);
+      }
+
+      mockTranslationService.translateBatch
+        .mockRejectedValueOnce(new Error('Too many requests'))
+        .mockImplementation(async (texts) => texts.map(t => ({ text: `translated: ${t}` })));
+
+      const result = await batchServiceWithTranslation.translateFiles(
+        files,
+        { targetLang: 'es' },
+        { outputDir: testDir },
+      );
+
+      expect(mockTranslationService.translateBatch).toHaveBeenCalledTimes(2);
+      expect(result.successful).toHaveLength(2);
+      expect(result.failed).toHaveLength(50);
+    });
+
     it('should split batches when cumulative bytes exceed MAX_TEXT_BYTES', async () => {
       // Create two files that together exceed MAX_TEXT_BYTES
       const halfSize = Math.floor(MAX_TEXT_BYTES / 2) + 100;
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index 72458fbf..7288d64a 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -121,6 +121,24 @@ describe('translate-utils', () => {
       expect(() => validateLanguageCodes(['abc-1234'])).not.toThrow();
     });
 
+    it('should warn that an unknown code is being deferred to the API', () => {
+      mockedLoggerWarn.mockClear();
+      validateLanguageCodes(['ex']);
+
+      // Said before anything is sent: the API answers a typo with a bare
+      // "target_lang not supported" that points nowhere.
+      const warning = mockedLoggerWarn.mock.calls.map(call => String(call[0])).join('\n');
+      expect(warning).toContain('"ex" is not in the bundled language list');
+      expect(warning).toContain('deepl languages');
+    });
+
+    it('should not warn about a code the snapshot lists', () => {
+      mockedLoggerWarn.mockClear();
+      validateLanguageCodes(['de', 'en-gb']);
+
+      expect(mockedLoggerWarn).not.toHaveBeenCalled();
+    });
+
     it('should still reject input that is not shaped like a language tag', () => {
       for (const code of ['g', 'grman', 'de_ch', 'de-', '../etc/passwd', 'de ch']) {
         expect(() => validateLanguageCodes([code])).toThrow(ValidationError);

From cd7005aed4e92a37614bcd53ddbef8d8256ed4a4 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 18:00:08 -0400
Subject: [PATCH 038/256] fix(write): defer an unknown Write language to the
 API instead of rejecting it

The Write list is checked locally because it is small enough for the error to
name every option -- but it is still a generated snapshot, and nothing in CI
regenerates it. A language DeepL added was therefore unreachable until someone
ran generate:languages, with no flag or env var to get past it.

A code shaped like a language tag now goes to the API with a warning that still
names the bundled set, so the user gets more information than the old hard
failure gave, not less. Malformed input is still rejected locally.

The generated file is also added to .prettierignore: check:languages compares
raw text, so `npm run format` would have reported permanent drift.
---
 .prettierignore                    |  4 ++++
 src/cli/commands/register-write.ts | 24 ++++++++++++++++++------
 tests/unit/register-write.test.ts  | 30 +++++++++++++++++-------------
 3 files changed, 39 insertions(+), 19 deletions(-)

diff --git a/.prettierignore b/.prettierignore
index aa7de81f..f1d49a79 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -3,3 +3,7 @@ dist
 coverage
 *.log
 .DS_Store
+
+# Generated from GET /v3/languages; check:languages compares the raw text, so
+# reformatting it would report permanent drift.
+src/data/language-entries.ts
diff --git a/src/cli/commands/register-write.ts b/src/cli/commands/register-write.ts
index dba9f177..62ad3ad2 100644
--- a/src/cli/commands/register-write.ts
+++ b/src/cli/commands/register-write.ts
@@ -4,6 +4,7 @@ import { atomicWriteFile } from '../../utils/atomic-write.js';
 import chalk from 'chalk';
 import type { WriteLanguage, WritingStyle, WriteTone } from '../../types/index.js';
 import { WRITE_TARGET_LANGUAGES } from '../../data/language-entries.js';
+import { looksLikeLanguageTag } from '../../data/language-registry.js';
 import { Logger } from '../../utils/logger.js';
 import { ExitCode } from '../../utils/exit-codes.js';
 import { isNoInput } from '../../utils/confirm.js';
@@ -11,10 +12,11 @@ import { ValidationError } from '../../utils/errors.js';
 import { createWriteCommand, type ServiceDeps } from './service-factory.js';
 
 /**
- * Generated from GET /v3/languages?resource=write, so it cannot drift from what
- * the API accepts. Unlike `translate --to`, a code outside this list is rejected
- * locally rather than deferred to the API: at 14 entries the error can name every
- * valid option, which beats a round trip.
+ * Generated from GET /v3/languages?resource=write. Small enough that an error can
+ * name every option, which is why it is checked locally at all -- but it is still
+ * a snapshot, so an unrecognized code that is shaped like a language tag is
+ * deferred to the API with a warning rather than rejected. Rejecting outright
+ * made a language DeepL had added unreachable until someone regenerated the file.
  */
 export const WRITE_LANGUAGES = WRITE_TARGET_LANGUAGES;
 /**
@@ -84,10 +86,20 @@ export function createWriteAction(
 
       if (options.lang) {
         const canonical = WRITE_LANGUAGE_BY_LOWERCASE.get(options.lang.toLowerCase());
-        if (!canonical) {
+        if (canonical) {
+          options.lang = canonical;
+        } else if (looksLikeLanguageTag(options.lang.toLowerCase())) {
+          // The bundled list is a snapshot and can lag the API, and nothing in CI
+          // regenerates it, so a language DeepL has added must not be
+          // unreachable: a well-formed code goes to the API to accept or reject.
+          Logger.warn(
+            `Note: "${options.lang}" is not in the bundled Write language list; deferring to the API.\n` +
+              `      Bundled options: ${WRITE_LANGUAGES.join(', ')}`
+          );
+          options.lang = options.lang.toLowerCase();
+        } else {
           throw new ValidationError(`Invalid language code: ${options.lang}. Valid options: ${WRITE_LANGUAGES.join(', ')}`);
         }
-        options.lang = canonical;
       }
 
       if (options.style && !(WRITE_STYLES as readonly string[]).includes(options.style)) {
diff --git a/tests/unit/register-write.test.ts b/tests/unit/register-write.test.ts
index 95b3f9b0..f8fbccaf 100644
--- a/tests/unit/register-write.test.ts
+++ b/tests/unit/register-write.test.ts
@@ -189,26 +189,30 @@ describe('registerWrite', () => {
   });
 
   describe('validation', () => {
-    it('should reject invalid language code', async () => {
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'xx']);
+    it('should reject a code that is not shaped like a language tag', async () => {
+      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'de_ch']);
       expect(handleError).toHaveBeenCalledWith(
         expect.objectContaining({ message: expect.stringContaining('Invalid language code') }),
       );
     });
 
-    it('should reject a well-formed code the Write API does not support', async () => {
-      // Deliberately stricter than `translate --to`, which passes well-formed
-      // unknown codes to the API: the Write set is small enough to enumerate,
-      // so naming the valid options beats a round trip.
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'hi']);
-      expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('Invalid language code') }),
-      );
-      expect(mockWriteCommand.improve).not.toHaveBeenCalled();
+    it('should defer a well-formed code the bundled list does not have', async () => {
+      // The bundled list is a snapshot and nothing in CI regenerates it, so
+      // rejecting outright made a language DeepL had added unreachable. The
+      // request goes through with a warning that still names the bundled set.
+      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'xx']);
+
+      expect(handleError).not.toHaveBeenCalled();
+      expect(mockWriteCommand.improve).toHaveBeenCalled();
+      const warning = (Logger.warn as jest.Mock).mock.calls.map(c => String(c[0])).join('\n');
+      expect(warning).toContain('not in the bundled Write language list');
+      for (const code of WRITE_TARGET_LANGUAGES) {
+        expect(warning).toContain(code);
+      }
     });
 
-    it('should enumerate every supported language in the rejection', async () => {
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'xx']);
+    it('should enumerate every supported language when rejecting malformed input', async () => {
+      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'nope_nope']);
       const error = handleError.mock.calls[0]?.[0] as Error;
       for (const code of WRITE_TARGET_LANGUAGES) {
         expect(error.message).toContain(code);

From 8449319257854e8b026390a6be38c26bd2d8c262 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 18:00:08 -0400
Subject: [PATCH 039/256] fix(glossary): dedupe IDs, check coverage in sync,
 and validate before dry-run
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six smaller defects around the multi-glossary work:

- naming one glossary twice (or a name plus its own UUID) sent glossary_ids with
  a duplicate: it flipped the wire parameter away from glossary_id, minted a
  third cache key for an identical request, and spent two of the five slots
- sync resolved its glossary without the language pair, so a glossary that does
  not cover it failed once per file instead of at startup, as the sibling
  translation-memory resolution already avoided
- translate --dry-run reported a glossary command as runnable that the real run
  rejects for a missing --from
- the document path never ran the extended-tier constraint check, so a glossary
  with an extended target uploaded the file and let the API refuse it, while the
  text path said so locally
- `glossary info` printed raw dictionary languages under a normalized summary,
  so one glossary could show "EN → DE" beneath "Source language: en"
- a coverage error listed every dictionary of a multilingual glossary on one line

The glossary pair matrix also compares languages after normalization, so casing
differing between the two role lists can no longer emit a self-pair.
---
 src/cli/commands/glossary.ts                    |  4 +++-
 src/cli/commands/register-translate.ts          | 17 ++++++++++++++++-
 .../translate/document-translation-handler.ts   | 10 +++++++++-
 .../translate/translation-options-factory.ts    | 10 +++++++++-
 src/services/glossary.ts                        | 15 ++++++++++++---
 src/sync/sync-service.ts                        | 11 ++++++++++-
 tests/e2e/cli-multi-glossary.e2e.test.ts        | 17 ++++++++++++++---
 tests/unit/sync/sync-service.test.ts            |  7 ++++++-
 8 files changed, 79 insertions(+), 12 deletions(-)

diff --git a/src/cli/commands/glossary.ts b/src/cli/commands/glossary.ts
index 1490c502..fcf41191 100644
--- a/src/cli/commands/glossary.ts
+++ b/src/cli/commands/glossary.ts
@@ -251,7 +251,9 @@ export class GlossaryCommand {
     if (multilingual) {
       lines.push('\nLanguage pairs:');
       glossary.dictionaries.forEach(dict => {
-        lines.push(`  ${dict.source_lang} → ${dict.target_lang}: ${dict.entry_count} entries`);
+        // Lowercased like the summary above: normalizeGlossaryInfo only touches
+        // the top-level fields, so raw dictionaries printed EN -> DE under en.
+        lines.push(`  ${dict.source_lang.toLowerCase()} → ${dict.target_lang.toLowerCase()}: ${dict.entry_count} entries`);
       });
     }
 
diff --git a/src/cli/commands/register-translate.ts b/src/cli/commands/register-translate.ts
index e6210757..21f3e4b8 100644
--- a/src/cli/commands/register-translate.ts
+++ b/src/cli/commands/register-translate.ts
@@ -4,7 +4,11 @@ import chalk from 'chalk';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
 import { createTranslateCommand, type ServiceDeps } from './service-factory.js';
-import { MAX_GLOSSARIES_PER_REQUEST } from '../../utils/glossary-params.js';
+import {
+  MAX_GLOSSARIES_PER_REQUEST,
+  applyGlossarySourceLang,
+  hasGlossarySelection,
+} from '../../utils/glossary-params.js';
 
 export function registerTranslate(
   program: Command,
@@ -166,6 +170,17 @@ Examples:
           );
         }
 
+        // Checked before --dry-run reports the command as runnable. Glossary name
+        // resolution still needs the API and stays out of dry-run, but the
+        // requirement that a glossary carry a source language does not.
+        if (hasGlossarySelection(options)) {
+          applyGlossarySourceLang(
+            options,
+            deps.getConfigService().getValue<string>('defaults.sourceLang'),
+            'Example: deepl translate --from en --to es --glossary my-glossary "Hello"',
+          );
+        }
+
         if (options.dryRun) {
           const targetLangs = options.to!.split(',').map(l => l.trim());
           const lines: string[] = [
diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index c14fe062..0a3f0502 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -4,7 +4,11 @@ import { ValidationError } from '../../../utils/errors.js';
 import type { Language } from '../../../types/index.js';
 import type { DocumentTranslationOptions } from '../../../types/api.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
-import { warnIgnoredOptions, validateLanguageCodes } from './translate-utils.js';
+import {
+  warnIgnoredOptions,
+  validateLanguageCodes,
+  validateExtendedLanguageConstraints,
+} from './translate-utils.js';
 import { buildBaseTranslationOptions, applyGlossarySelection } from './translation-options-factory.js';
 import { applyGlossarySourceLang } from '../../../utils/glossary-params.js';
 
@@ -22,6 +26,10 @@ export class DocumentTranslationHandler {
     warnIgnoredOptions('document', options, supported);
 
     validateLanguageCodes([options.to]);
+    // Documents support glossaries now, which makes the extended-tier constraint
+    // reachable here: without this the upload happens and the API rejects it,
+    // while the text path says so locally.
+    validateExtendedLanguageConstraints(options.to, options);
 
     // The API rejects a document glossary without source_lang: "source_lang has
     // to be specified in order to use a glossary."
diff --git a/src/cli/commands/translate/translation-options-factory.ts b/src/cli/commands/translate/translation-options-factory.ts
index 1e59800e..5cd483f9 100644
--- a/src/cli/commands/translate/translation-options-factory.ts
+++ b/src/cli/commands/translate/translation-options-factory.ts
@@ -58,9 +58,17 @@ export async function applyGlossarySelection<
 
   // Resolved sequentially so the service's resolution cache is populated
   // before the next name-or-ID lookup needs the glossary list.
+  //
+  // Deduplicated after resolution, because a name and its own UUID resolve to
+  // the same glossary: naming one twice would otherwise flip the wire parameter
+  // from glossary_id to glossary_ids, mint a third cache key for an identical
+  // request, and spend two of the five slots the API allows.
   const ids: string[] = [];
   for (const nameOrId of options.glossary) {
-    ids.push(await resolveGlossaryId(glossaryService, nameOrId, expected));
+    const id = await resolveGlossaryId(glossaryService, nameOrId, expected);
+    if (!ids.includes(id)) {
+      ids.push(id);
+    }
   }
 
   const [only] = ids;
diff --git a/src/services/glossary.ts b/src/services/glossary.ts
index 9b7e5575..ff93a3e5 100644
--- a/src/services/glossary.ts
+++ b/src/services/glossary.ts
@@ -21,6 +21,9 @@ function hasSuspiciousChars(name: string): boolean {
 
 const LIST_CACHE_TTL_MS = 60_000;
 
+/** Language pairs to name in a coverage error before summarizing the rest. */
+const MAX_PAIRS_IN_SUGGESTION = 8;
+
 /**
  * Characters the glossary TSV wire format reserves as column and row
  * separators. A term containing one of them cannot survive the round trip:
@@ -217,9 +220,15 @@ export class GlossaryService {
         );
       const missing = expected.targets.filter(target => !covered(target));
       if (missing.length > 0) {
-        const pairs = match.dictionaries
-          .map(d => `${d.source_lang.toLowerCase()}→${d.target_lang.toLowerCase()}`)
-          .join(', ');
+        const allPairs = match.dictionaries.map(
+          d => `${d.source_lang.toLowerCase()}→${d.target_lang.toLowerCase()}`,
+        );
+        // A multilingual glossary can hold dozens of dictionaries, and the whole
+        // cross-product on one line stops being a suggestion.
+        const pairs =
+          allPairs.length > MAX_PAIRS_IN_SUGGESTION
+            ? `${allPairs.slice(0, MAX_PAIRS_IN_SUGGESTION).join(', ')} and ${allPairs.length - MAX_PAIRS_IN_SUGGESTION} more`
+            : allPairs.join(', ');
         throw new ConfigError(
           `Glossary "${sanitizeForError(nameOrId)}" does not support the requested language pair`,
           `Glossary covers ${pairs}; requested ${from}→${missing.map(t => t.toLowerCase()).join(',')}.`,
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index edfe3d6c..b08ea1a1 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -191,7 +191,16 @@ export class SyncService {
 
     let resolvedGlossaryId: string | undefined;
     if (config.translation?.glossary && config.translation.glossary !== 'auto' && !options?.dryRun) {
-      resolvedGlossaryId = await this.glossaryService.resolveGlossaryId(config.translation.glossary);
+      // The pair is known from the config, so a glossary that does not cover it
+      // fails here rather than once per file, as translation-memory resolution
+      // below already does.
+      const glossaryLocales = options?.localeFilter?.length
+        ? config.target_locales.filter(l => options.localeFilter!.includes(l))
+        : config.target_locales;
+      resolvedGlossaryId = await this.glossaryService.resolveGlossaryId(
+        config.translation.glossary,
+        { from: config.source_locale as Language, targets: glossaryLocales as Language[] },
+      );
     }
 
     let resolvedTmId: string | undefined;
diff --git a/tests/e2e/cli-multi-glossary.e2e.test.ts b/tests/e2e/cli-multi-glossary.e2e.test.ts
index 42fa7f62..8ae6e131 100644
--- a/tests/e2e/cli-multi-glossary.e2e.test.ts
+++ b/tests/e2e/cli-multi-glossary.e2e.test.ts
@@ -44,7 +44,7 @@ describe('translate --glossary repetition E2E', () => {
 
     it('should not reject exactly five glossaries during flag validation', () => {
       const result = runCLIExpectError(
-        'translate "Hello" --to de --dry-run --glossary a --glossary b --glossary c ' +
+        'translate "Hello" --from en --to de --dry-run --glossary a --glossary b --glossary c ' +
           '--glossary d --glossary e',
       );
 
@@ -56,7 +56,7 @@ describe('translate --glossary repetition E2E', () => {
   describe('dry run', () => {
     it('should list every requested glossary in order', () => {
       const output = runCLI(
-        'translate "Hello" --to de --dry-run --glossary base-terms --glossary project-overrides',
+        'translate "Hello" --from en --to de --dry-run --glossary base-terms --glossary project-overrides',
         { noColor: true },
       );
 
@@ -64,7 +64,7 @@ describe('translate --glossary repetition E2E', () => {
     });
 
     it('should keep the singular label for one glossary', () => {
-      const output = runCLI('translate "Hello" --to de --dry-run --glossary base-terms', {
+      const output = runCLI('translate "Hello" --from en --to de --dry-run --glossary base-terms', {
         noColor: true,
       });
 
@@ -77,6 +77,17 @@ describe('translate --glossary repetition E2E', () => {
 
       expect(output).not.toMatch(/Glossar/i);
     });
+
+    it('should not report a glossary command as runnable when --from is missing', () => {
+      // Dry run is where people check a command is well-formed, so it has to
+      // apply the same requirement the real run does.
+      const result = runCLIExpectError('translate "Hello" --to de --dry-run --glossary base-terms', {
+        excludeApiKey: true,
+      });
+
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toMatch(/Source language \(--from\) is required/i);
+    });
   });
 
   describe('argument handling', () => {
diff --git a/tests/unit/sync/sync-service.test.ts b/tests/unit/sync/sync-service.test.ts
index 7df0fc40..40699b4f 100644
--- a/tests/unit/sync/sync-service.test.ts
+++ b/tests/unit/sync/sync-service.test.ts
@@ -2424,7 +2424,12 @@ describe('SyncService', () => {
         translation: { glossary: 'my-glossary' },
       }));
 
-      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+      // With the configured pair, so a glossary that does not cover it fails here
+      // rather than once per file.
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+        from: 'en',
+        targets: ['de'],
+      });
     });
 
     it('should not resolve glossary during dryRun', async () => {

From 110a76717d55b8680f18aab6352d141c09858753 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 18:00:37 -0400
Subject: [PATCH 040/256] fix(config): normalize language codes and warn about
 ones the snapshot lacks

`config set defaults.sourceLang DE` was rejected while `translate --from DE`
works, because the translate paths lowercase the flag first and the fallback
pattern is lowercase-only -- so the one casing that is certainly valid was the
one class of input still refused. Values are lowercased before validating and
stored normalized.

A code the bundled snapshot does not list is still accepted, since the snapshot
can lag the API, but it now warns at the point of entry: a typo written to config
otherwise failed on every later command with nothing pointing back at the config
value that caused it.

Also documents the repeatable --glossary in the flag table, adds the required
--from to the last example that omitted it, and gives the api.ts import of
./common the extension its neighbour already had.
---
 docs/API.md              |  2 +-
 examples/24-languages.sh |  2 +-
 src/storage/config.ts    | 31 ++++++++++++++++++++++++++++++-
 src/types/api.ts         |  2 +-
 4 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index f4992bac..78a80023 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1005,7 +1005,7 @@ deepl voice [options] <file>
 | `--to <languages>`              | `-t`  | Target language(s), comma-separated, max 5 (required)                                          | -         |
 | `--from <language>`             | `-f`  | Source language (auto-detect if not specified)                                                 | auto      |
 | `--formality <level>`           |       | Formality level: `default`, `formal`, `more`, `informal`, `less`, `prefer_more`, `prefer_less` | `default` |
-| `--glossary <name-or-id>`       |       | Use glossary by name or ID                                                                     | -         |
+| `--glossary <name-or-id>`       |       | Use glossary by name or ID (requires `--from`; repeatable, max 5, last wins on conflicts)       | -         |
 | `--content-type <type>`         |       | Audio content type (auto-detected from file extension)                                         | auto      |
 | `--chunk-size <bytes>`          |       | Audio chunk size in bytes                                                                      | `6400`    |
 | `--chunk-interval <ms>`         |       | Interval between audio chunks in milliseconds                                                  | `200`     |
diff --git a/examples/24-languages.sh b/examples/24-languages.sh
index cb44e25c..3446d608 100755
--- a/examples/24-languages.sh
+++ b/examples/24-languages.sh
@@ -80,7 +80,7 @@ supports() {  # supports <lang> <feature>
 }
 
 if supports th glossary; then
-  deepl translate --to th --glossary my-terms "Hello"
+  deepl translate --from en --to th --glossary my-terms "Hello"
 else
   echo "Thai does not support glossaries; translating without one"
   deepl translate --to th "Hello"
diff --git a/src/storage/config.ts b/src/storage/config.ts
index 69fee194..b4d979e1 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -45,6 +45,21 @@ const DEFAULT_CACHE_SIZE = 1024 * 1024 * 1024; // 1GB
 const DEFAULT_CACHE_TTL = 30 * 24 * 60 * 60; // 30 days in seconds
 const DEFAULT_DEBOUNCE_MS = 500;
 
+/**
+ * Language values are stored lowercase, matching what `deepl languages` prints
+ * and what every translate path normalizes its flags to, so a config written as
+ * `DE` does not read back as a code the registry cannot look up.
+ */
+function normalizeLanguageValue(path: string, value: unknown): unknown {
+  if (path === 'defaults.sourceLang' && typeof value === 'string') {
+    return value.toLowerCase();
+  }
+  if (path === 'defaults.targetLangs' && Array.isArray(value)) {
+    return value.map(lang => (typeof lang === 'string' ? lang.toLowerCase() : lang));
+  }
+  return value;
+}
+
 export class ConfigService {
   private config: DeepLConfig;
   private configPath: string;
@@ -71,6 +86,7 @@ export class ConfigService {
 
     const keys = key.split('.');
     this.validatePath(keys, value);
+    value = normalizeLanguageValue(keys.join('.'), value);
 
     let current: Record<string, unknown> = this.config as unknown as Record<string, unknown>;
     for (let i = 0; i < keys.length - 1; i++) {
@@ -384,10 +400,23 @@ export class ConfigService {
    * is the authority on which languages exist and the snapshot can lag it.
    */
   private validateLanguage(lang: string, key?: string): void {
-    if (!isValidLanguage(lang) && !looksLikeLanguageTag(lang)) {
+    // Lowercased first: every translate path lowercases the flag before using it,
+    // so `--from DE` works while `config set defaults.sourceLang DE` was rejected
+    // by a lowercase-only pattern -- the one casing that is certainly valid.
+    const normalized = typeof lang === 'string' ? lang.toLowerCase() : lang;
+    if (!isValidLanguage(normalized) && !looksLikeLanguageTag(normalized)) {
       const context = key ? ` for "${key}"` : '';
       throw new ConfigError(`Invalid language code "${lang}"${context}. Run: deepl languages to see valid codes`);
     }
+    if (!isValidLanguage(normalized)) {
+      // Stored anyway, because the snapshot can lag the API -- but a typo written
+      // to config fails on every later command with nothing pointing back here.
+      const context = key ? ` for "${key}"` : '';
+      Logger.warn(
+        `Note: "${lang}"${context} is not in the bundled language list; it will be sent to the API as-is.\n` +
+          '      Run: deepl languages  to see the languages this build knows about.'
+      );
+    }
   }
 
   /**
diff --git a/src/types/api.ts b/src/types/api.ts
index 5aae2431..0dde7419 100644
--- a/src/types/api.ts
+++ b/src/types/api.ts
@@ -2,7 +2,7 @@
  * API-related type definitions
  */
 
-import { Language, Formality } from './common';
+import { Language, Formality } from './common.js';
 import { WRITE_TARGET_LANGUAGES } from '../data/language-entries.js';
 
 export type ModelType =

From 2e925c3a5defa0c7ec0e0ebd2f99655e75ab2a2f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 18:00:38 -0400
Subject: [PATCH 041/256] fix(api): compare glossary pair languages after
 normalization

The v3 cross-product skipped the identity pair on raw casing, so a language
spelled differently across the two role lists would emit a self-pair the API
does not offer.
---
 src/api/glossary-client.ts | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/src/api/glossary-client.ts b/src/api/glossary-client.ts
index fc7efbfd..e65eb2b6 100644
--- a/src/api/glossary-client.ts
+++ b/src/api/glossary-client.ts
@@ -33,13 +33,14 @@ export class GlossaryClient extends HttpClient {
     const pairs: GlossaryLanguagePair[] = [];
     for (const source of sources) {
       for (const target of targets) {
-        if (source.lang === target.lang) {
+        // Compared after normalization: raw casing differing between the two role
+        // lists would otherwise emit a self-pair the API does not offer.
+        const sourceLang = this.normalizeLanguage(source.lang);
+        const targetLang = this.normalizeLanguage(target.lang);
+        if (sourceLang === targetLang) {
           continue;
         }
-        pairs.push({
-          sourceLang: this.normalizeLanguage(source.lang),
-          targetLang: this.normalizeLanguage(target.lang),
-        });
+        pairs.push({ sourceLang, targetLang });
       }
     }
     return pairs;

From f3e9af90b18bbd1bb4ffad7af7e4b226f6c5c6d2 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 18:04:11 -0400
Subject: [PATCH 042/256] docs(changelog): record the review fixes and correct
 claims they invalidated

Adds Fixed entries for the cache-key omissions, the per-batch retry of a
rejected language, the voice usage figure, the glossary minors, the config-only
source language, the --features overclaiming, config code normalization, the
tag-handling version dropped outside text mode, and the generator guards; plus a
Changed entry for the derived Language union.

Five existing Unreleased claims were no longer true and are corrected in place
rather than contradicted further down:

- write no longer rejects every unknown code locally
- the multipart glossary_ids encoding was described as live-verified; the live
  document endpoint answers any unresolvable glossary the same way regardless of
  encoding, so only parameter recognition was confirmed there
- the glossary preflight compares base languages, so regional targets work
- the shared-feature note is scoped when some languages have no data
- formality comes from the v3 features matrix, not the registry
---
 CHANGELOG.md | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 79543c8a..7a3025bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,9 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API). It was previously accepted and then silently discarded with a "document mode does not support --glossary" warning, even though `POST /v2/document` supports glossaries. Repeating the flag works here too, with the same last-one-wins precedence. `--from` is required, because the API rejects a document glossary without a source language; `--translation-memory` remains unsupported for documents. Note that glossary matching is context-dependent for documents exactly as it is for text — a term applied in one sentence may be left alone in another.
 
-- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API, including the two encodings the endpoints require: repeated form fields for `POST /v2/translate`, and one comma-joined value for the multipart `POST /v2/document`, which keeps only the first of several repeated fields and would otherwise silently apply just one glossary.
+- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API: `POST /v2/translate` accepts `glossary_ids` as repeated form fields and resolves them in order, rejects a sixth with `A maximum of 5 glossaries can be specified per request.`, and rejects `glossary_id` and `glossary_ids` together with `Specify either glossary_id or glossary_ids, not both.` -- which is why the CLI collapses a single glossary to `glossary_id` rather than sending both. The multipart `POST /v2/document` takes one comma-joined value, since multipart does not parse repeated fields as a list; that endpoint answers any unresolvable glossary with `glossary_ids is not valid` regardless of encoding, so it was confirmed only to the extent that it recognises the parameter, and the list semantics there rest on the API documentation rather than on a live round trip.
 
-- **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`, which the CLI previously discarded. Support no longer has to be discovered by making a request and reading the error. Which features get a column is derived from the response rather than a fixed list: a feature appears when its support differs across the languages listed, and one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row. That makes the columns differ between listings — `auto detection` appears under `--target`, where target-only variants lack it, but is uniform under `--source` — and means a newly reported feature shows up without a code change. Support is signalled by the API reporting a feature at all; `status` describes maturity, so anything short of generally available renders verbatim (`glossary (beta)`) rather than collapsing to `yes`. Works with `--format table` (one column per feature) and `--format json` (the raw matrix including each status, present only when `--features` is passed, so existing JSON consumers are unaffected). `--features` supersedes the `[F]` shorthand and replaces it when given. It needs an API key; without one the command warns and falls back to the registry, which carries no feature data. Note that the matrix is finer-grained than the core/regional/extended tiers: some extended languages support style rules and translation memory even though they support neither formality nor glossary.
+- **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`, which the CLI previously discarded. Support no longer has to be discovered by making a request and reading the error. Which features get a column is derived from the response rather than a fixed list: a feature appears when its support differs across the languages listed, and one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row (`All languages with reported features also support: ...` when the listing also carries languages the response did not describe, since the note must not speak for those). A language the response omitted reads as `no feature data` rather than as supporting nothing, and does not count towards whether a feature varies. That makes the columns differ between listings — `auto detection` appears under `--target`, where target-only variants lack it, but is uniform under `--source` — and means a newly reported feature shows up without a code change. Support is signalled by the API reporting a feature at all; `status` describes maturity, so anything short of generally available renders verbatim (`glossary (beta)`) rather than collapsing to `yes`. Works with `--format table` (one column per feature) and `--format json` (the raw matrix including each status, present only when `--features` is passed, so existing JSON consumers are unaffected). `--features` supersedes the `[F]` shorthand and replaces it when given. It needs an API key; without one the command warns and falls back to the registry, which carries no feature data. Note that the matrix is finer-grained than the core/regional/extended tiers: some extended languages support style rules and translation memory even though they support neither formality nor glossary.
 
 - **cli**: `deepl correct` command (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`), but not `--style`/`--tone`, which the correct endpoint does not accept. Results are cached under a separate `correct:` namespace so corrections and rephrasings of the same text never collide.
 
@@ -21,16 +21,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **translate**: **`--tag-handling` requests now pin `tag_handling_version=v2`** instead of letting the API pick. The CLI previously sent the parameter only when `--tag-handling-version` was passed, so everyone else inherited the server default — which DeepL documents as moving from v1 (deprecation-bound) to v2 at an unannounced date. That flip would have changed tag-handling output with no CLI change to point at, and worse, would have gone unnoticed by the cache: a request that omits the version hashes identically before and after, so cached v1 output would have kept being served after the API started returning v2. Adopting v2 now makes that one output shift deliberate and dated, and DeepL's own docs recommend v2 for structure handling. **`--tag-handling xml`/`html` output may differ from previous releases**; pass `--tag-handling-version v1` to keep the old behaviour, which is still honoured and always wins over the default. Requests without `--tag-handling` send no version and keep their existing cache keys; tag-handling entries cached by earlier versions now miss rather than being served stale, so the first such translation after upgrading is refetched.
 
-- **translate**: **A glossary referenced by name is checked against the requested language pair before any translation request.** Previously only translation memories did this; a glossary whose dictionaries did not cover the pair reached the API and came back as `No dictionary found for language pair EN-DE in glossary <uuid>`, naming a UUID the user never typed. It now fails locally, exit 7, naming what the glossary actually covers: `Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.` This costs no extra request, because the glossary list is already fetched to resolve the name. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr is not treated as covering en→fr, and when translating to several targets at once every one of them must be covered. Two deliberate exemptions: a glossary passed as a **UUID** is trusted and left to the API, matching how translation-memory resolution already behaves and giving an escape hatch if the check is ever wrong; and a glossary the API reports with no dictionaries is left alone, since that says nothing about coverage.
+- **translate**: **A glossary referenced by name is checked against the requested language pair before any translation request.** Previously only translation memories did this; a glossary whose dictionaries did not cover the pair reached the API and came back as `No dictionary found for language pair EN-DE in glossary <uuid>`, naming a UUID the user never typed. It now fails locally, exit 7, naming what the glossary actually covers: `Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.` This costs no extra request, because the glossary list is already fetched to resolve the name. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr is not treated as covering en→fr, and when translating to several targets at once every one of them must be covered. Both sides are compared on their **base** language, because glossary dictionaries only ever name base languages while `--to` accepts regional variants: a de→en glossary covers `--to en-us`, which the API accepts, and demanding an exact match would have made glossaries unusable for every regional target — `en-us`, `en-gb`, `pt-br`, `pt-pt`, `zh-hans`, `es-419`, `fr-ca` — including the ones DeepL steers users towards over bare `en`/`pt`. The check is therefore deliberately permissive at the edges: a pair it lets through is still the API's to reject, which is much the cheaper mistake. Two deliberate exemptions: a glossary passed as a **UUID** is trusted and left to the API, matching how translation-memory resolution already behaves and giving an escape hatch if the check is ever wrong; and a glossary the API reports with no dictionaries is left alone, since that says nothing about coverage.
 
-- **write**: **The Write API's 14 target languages are generated rather than hand-maintained**, closing the last hand-kept language list. The list and the `WriteLanguage` type were two separate hand-edited copies of the same set, either of which could fall behind `GET /v3/languages?resource=write` — the same way the translation list silently went four codes stale. `npm run generate:languages` now emits both language lists and `npm run check:languages` reports which one drifted; the type is derived from the generated list, so a language added upstream widens it on regenerate instead of needing a second edit. No behaviour change: the generated list is byte-identical to what was there, and `write`/`correct` still **reject** a code outside it locally while naming every valid option, deliberately unlike `translate --to`, which passes well-formed unknown codes to the API. At 14 of 125 languages an enumerated error beats a round trip. Note the documented style/tone support table is unchanged and still maintained by hand, because it records what the API accepts rather than what its metadata claims: `resource=write` omits `writing_style` for `en`, but `--style` with `--lang en` works.
+- **write**: **The Write API's 14 target languages are generated rather than hand-maintained**, closing the last hand-kept language list. The list and the `WriteLanguage` type were two separate hand-edited copies of the same set, either of which could fall behind `GET /v3/languages?resource=write` — the same way the translation list silently went four codes stale. `npm run generate:languages` now emits both language lists and `npm run check:languages` reports which one drifted; the type is derived from the generated list, so a language added upstream widens it on regenerate instead of needing a second edit. The generated list is byte-identical to what was there. `write`/`correct` still check the code locally and name every valid option, because at 14 of 125 languages an enumerated error beats a round trip -- but a code that is *shaped* like a language tag and simply is not in the snapshot is now sent to the API with that list as a warning, rather than refused. Nothing in CI regenerates the snapshot, so refusing outright made a language DeepL had added unreachable until someone ran the generator, with no flag to get past it. Malformed input is still rejected locally. Note the documented style/tone support table is unchanged and still maintained by hand, because it records what the API accepts rather than what its metadata claims: `resource=write` omits `writing_style` for `en`, but `--style` with `--lang en` works.
 
 - **languages**: **The DeepL API is now the authority on which languages exist, not the CLI's bundled list.** That list was hand-maintained, so it could silently fall behind the API and make languages the API accepts unusable — which is exactly what happened to `de-CH`, `de-DE`, `fr-CA` and `fr-FR` (see Fixed). Three changes remove the failure mode rather than just correcting the data. **Validation defers to the API:** a well-formed language code the bundled list does not contain is sent to the API, which accepts or rejects it authoritatively, instead of being rejected locally. Input that is not shaped like a language tag is still rejected immediately with a pointer to `deepl languages`, so typos like `--to grman` still fail fast without a request. This covers `translate`, `sync` and language values in the config file. **The listing is API-driven:** `deepl languages` renders the union of the API response and the bundled list, so a language DeepL offers can no longer be missing from the output. **The list is generated:** `npm run generate:languages` rewrites it from `GET /v3/languages` and `npm run check:languages` fails on drift, so it is a build artifact of the API rather than something maintained by hand. The core/regional/extended tiers are derived in the same pass — glossary support separates extended from the rest, source usability separates core from regional — which reproduces the previously hand-assigned tiers exactly, so the tiers can no longer disagree with the API either. No command line changes; `--to de` and every other existing code behave as before.
 
+- **types**: **The published `Language` union is derived from the generated language snapshot** instead of being written out by hand. It was a fourth copy of the same list and had already fallen four codes behind the snapshot it describes — `de-ch`, `de-de`, `fr-ca`, `fr-fr`, the very codes the /v3 migration added — so `const lang: Language = 'de-de'` was a compile error in the published typings while `deepl config set defaults.targetLangs de-de` succeeded at runtime and wrote a config `DeepLConfig` could not type. Neither `generate:languages` nor `check:languages` touched it. `ENTRIES` is now generated `as const satisfies readonly LanguageEntry[]` and the union derives from its codes, exactly as `WriteLanguage` already derived from `WRITE_TARGET_LANGUAGES`, so regenerating the snapshot widens both. The union only ever gains codes here, so nothing that compiled before stops compiling; runtime validation still defers to the API, which means the union describes what the CLI can name offline rather than what works.
+
 - **languages**: **Ten display names changed to match the API**, a consequence of generating the language list rather than hand-writing it: `ckb` Central Kurdish → Kurdish (Sorani), `es-419` Spanish (Latin America) → Spanish (Latin American), `gom` Goan Konkani → Konkani, `kmr` Northern Kurdish → Kurdish (Kurmanji), `my` Myanmar (Burmese) → Burmese, `nb` Norwegian Bokmål → Norwegian (bokmål), `pam` Pampanga → Kapampangan, `st` Southern Sotho → Sesotho, `zh-hans` Chinese (Simplified) → Chinese (simplified), `zh-hant` Chinese (Traditional) → Chinese (traditional). **Only offline output changes**: with an API key configured, `deepl languages` already took names from the API and was therefore already showing these, so this makes the no-API-key output consistent with the keyed output rather than changing what keyed users saw. Language codes are unaffected, so nothing that selects a language by code has to change; only output that scrapes display names.
 
 - **cli**: **Language codes are displayed in lowercase everywhere.** Output previously mixed three casings: `deepl languages` printed lowercase from the registry, `glossary show` and `tm list` uppercased at display time, `translate`'s table uppercased the target language, and `write`/`correct` used BCP-47 (`en-GB`, `zh-Hans`). Lowercase matches the CLI's own normalized form, the registry, what `deepl languages` teaches users to type, and the wire format `/v3/languages` moved to; uppercase followed a v2-era docs convention that v3 abandons. **Scripts scraping these values will see a casing change** — `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"`. Input remains case-insensitive everywhere, so no command line has to change. `write`/`correct` also send the lowercase code as `target_lang`: the Write API accepts any casing and canonicalizes server-side (verified live on `/v2/write/rephrase` and `/v2/write/correct` — `en-gb`, `zh-hans`, and `zh-HANS` all return 200 and echo back `en-GB` / `zh-Hans`). Wire parameters that are not display are untouched: `translate` and the glossary create endpoint still send uppercase `target_lang`/`source_lang` as those endpoints document.
-- **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers now come from the language registry since the v3 response no longer reports formality support.
+- **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers come from the per-language `features` matrix, which is what v2's `supports_formality` boolean became (see the Fixed entry on `pt`). A language whose features the response does not describe is left unmarked rather than marked unsupported, so the `[F]` legend cannot appear with no `[F]` beneath it.
 
 ### Removed
 
@@ -81,12 +83,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **cache**: **The translation cache keyed on too little and could serve the wrong text.** `translationMemoryId`, `translationMemoryThreshold`, `--ignore-tags`, `--splitting-tags`, `--non-splitting-tags`, `--outline-detection` and `--preserve-formatting` were absent from the key, so `deepl translate "Hello" --to de` and the same command with `--translation-memory my-tm` collided: the second returned the cached non-TM translation, never consulted the memory, and reported `cached: true`. Likewise two runs differing only in `--ignore-tags` returned each other's output. `preserveFormatting` had been excluded on the grounds that it does not affect output, but `preserve_formatting` suppresses the sentence-boundary punctuation and case correction, which shows up in the text. **Entries cached by earlier versions for requests using any of these options now miss rather than being served wrongly**, so the first such translation after upgrading is refetched.
+
+- **translate**: **A rejected language no longer costs one API round trip per batch.** Because validation defers well-formed unknown codes to the API, a two-letter typo reaches it — and a directory translation asked the same rejected question once per batch, so `deepl translate ./docs --to ex` on 200 files made 200 failing requests to be told the same thing 200 times. An unsupported `target_lang` or `source_lang` is a property of the request, not of one batch, so the remaining batches now fail without being sent; errors specific to a batch (a rate limit, say) still let the run continue. Relatedly, local validation used to be what pointed at `deepl languages`, and deferring left users with a bare `Value for 'target_lang' not supported.` from the server: a code the bundled snapshot does not list now says so up front, before anything is sent or billed.
+
+- **usage**: **Voice usage reported the API key's own consumption as the account total.** Duration-billed products fell back to `apiKeyUnitCount` for the account figure because live `GET /v2/usage` responses omit `unit_count` for them, so `deepl usage` printed the same number in both columns — an account with 100 minutes used and 10 on this key showed 10 for both. The account-wide field the response does carry, `account_unit_count`, was neither typed nor parsed; it is now, and where no account-wide figure exists the row reads `(API key)` instead of inventing a total. This is the only place voice usage appears since the Speech-to-Text section was removed, which is why the wrong number mattered.
+
+- **glossary**: Six smaller defects around the multi-glossary work. Naming one glossary twice — or a name plus its own UUID — sent a duplicate in `glossary_ids`, which flipped the wire parameter away from `glossary_id`, minted a third cache key for an identical request, and spent two of the five slots the API allows; IDs are deduplicated after resolution. `sync` resolved its glossary without the language pair, so a glossary that did not cover it failed once per file instead of at startup, unlike the sibling translation-memory resolution. `translate --dry-run` reported a glossary command as runnable that the real run rejects for a missing `--from`, and `watch --dry-run` did the same. The document path never ran the extended-tier constraint check, newly reachable now that documents accept glossaries, so it uploaded the file and let the API refuse it while the text path said so locally. `glossary info` printed raw dictionary languages beneath a normalized summary, so one glossary could show `EN → DE` under `Source language: en`. And a coverage error listed every dictionary of a multilingual glossary on a single line.
+
+- **glossary**: `--glossary` with a source language set only in config no longer fails. `TranslationService` merges `defaults.sourceLang`, so the request carries `source_lang` whether or not `--from` was typed, but the guard tested the flag alone — so `deepl config set defaults.sourceLang en` followed by `deepl watch ./docs --to es --glossary my-terms` broke a session that had been working. The effective source language is now resolved onto the request, which also gives the document path (which merges no defaults of its own) and the glossary preflight the pair they need. An empty `--glossary` selection is no longer treated as a glossary either: `[]` is truthy, so a caller passing one got a spurious "Source language (--from) is required".
+
+- **languages**: `--features` no longer claims knowledge it does not have. The listing keeps snapshot entries the API response omitted, and every one of them was rendered as the positive claim `none` — with a response covering a handful of languages, `--features` reported over a hundred as supporting nothing. Those rows also made every feature look non-uniform, so features shared by all the described languages became columns of repeated values instead of the single footer note the flag was built around. A feature reported without a `status` rendered as the literal string `undefined` (the enum is open, and an absent status still means the feature is there), and `supportsFormality` was asserted `false` for languages whose features the response never mentioned, turning on the `[F]` legend with no `[F]` anywhere to explain it. `deepl languages` also makes one `GET /v3/languages` request instead of two identical ones — both roles are filtered out of the same payload.
+
+- **config**: `deepl config set defaults.sourceLang DE` was rejected while `deepl translate --from DE` works. Every translate path lowercases the flag before validating, but the config validator matched a lowercase-only pattern, so the one casing that is certainly valid was the one class of input still refused. Language values are lowercased before validation and stored normalized. A code the bundled snapshot does not list is still accepted, since the snapshot can lag the API, but now warns at the point of entry — a typo written to config otherwise failed on every later command with nothing pointing back at the config value responsible.
+
+- **translate**: `--tag-handling-version` is honoured for files and directories, not only for text. The shared option mapping carried `--tag-handling` but not the version, so with the CLI now pinning v2 whenever tag handling is on, `deepl translate page.html --tag-handling html --tag-handling-version v1` silently sent v2 — and single-file mode emits no ignored-option warning to say so. The flag is mapped in the shared mapping every handler uses, and its validation moved with it.
+
+- **scripts**: `npm run generate:languages` refuses to write a snapshot that would break the CLI. An empty write list would collapse the `WriteLanguage` union to `never`, rejecting every `--lang` while naming no valid option; a features matrix that stopped reporting `glossary` would retier all 125 languages as extended and make `--formality` and `--glossary` unusable everywhere. Both now fail the run instead. `--check` compares whole blocks rather than quoted codes, so a renamed display name is reported as real drift instead of "formatting only", and the generated file is in `.prettierignore` so `npm run format` cannot make that check fail permanently. Both resources are fetched together and their failures reported together, so a key that cannot read `resource=write` no longer blocks regenerating the translation list it can read.
+
 - **languages**: **Four target languages the API accepts were unusable.** `de-CH` (Swiss German), `de-DE`, `fr-CA` (Canadian French) and `fr-FR` are returned by `GET /v3/languages` and accepted by the translate endpoint, but the CLI's bundled language list did not contain them, so `deepl translate --to de-CH` failed locally with `Invalid target language code` before any request was made — and the `deepl languages` the error suggested did not list them either, because the listing used the bundled list as its row set rather than the API response. Swiss German and Canadian French had no workaround; `de-DE`/`fr-FR` could be spelled `de`/`fr`. The list now contains all 125 languages the API serves (32 core, 11 regional, 82 extended). See the Changed entry below for why this class of divergence can no longer make a language unusable.
 
 - **languages**: `deepl languages --target` marks Portuguese (`pt`) with `[F]`. Formality support is now read from `features.formality` on `GET /v3/languages` instead of a static table in the language registry. The v3 migration had assumed v3 stopped reporting formality, but the capability was only renamed — v2's `supports_formality` boolean became the presence of a `formality` key in the per-language features matrix — so the CLI was answering from an 11-entry snapshot of the final v2 response that had already drifted from the API. The snapshot and the registry's `supportsFormality` field are gone; the registry's `category` tiers are unaffected. Output is otherwise unchanged: the `[F]` set is identical apart from `pt`.
 
 - **watch**: `--glossary` without `--from` now exits 6 before the watcher starts, instead of starting a session that fails on every single file change with a raw server message. The API rejects any translation naming a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"), which `translate` already guarded against up front for text, files, and documents; `watch` passed `--from` straight through. A long-running command is the worst place for this, since the operator saw the failure once per edit rather than once at launch. The check runs before the glossary name is resolved, so it costs no API call. `sync` needs no equivalent: it has no `--from` at all, taking the source language from the required `source_locale` field in `.deepl-sync.yaml`, so its requests always carry one.
-- **voice**: A session that ends with the audio transcribed but no translation for a requested `--to` language now fails with exit code 9 and names the languages, instead of printing an empty translation line and exiting 0. Silent partial output was the worse failure: a script consuming `deepl voice` output saw success with the translation missing. Audio containing no speech transcribes to nothing and translates to nothing, which is legitimate and still exits 0, so the check only applies when a source transcript exists. Whitespace-only and tentative-but-never-concluded translations count as missing, since neither reaches the printed output. Investigated as an intermittent (~1 in 4) empty translated line; the leading hypothesis was disproved with frame-level traces of live sessions — the server sends `end_of_stream` strictly after `end_of_target_transcript`, and the client only tears the socket down on `end_of_stream`, so there is no client-side teardown race. Reconnect was ruled out too: a socket dropped after end-of-source cannot be resumed (the API returns `410 Gone`) and already exited non-zero. The empty line did not reproduce in 64 live runs across pacing, burst, multi-target, and concurrency variations, so the trigger appears to be server-side and transient — which is exactly why the client needs to detect it rather than report success.
+- **voice**: A session that ends with the audio transcribed but no translation for a requested `--to` language now fails with exit code 9 and names the languages, instead of printing an empty translation line and exiting 0. The failure **carries the transcripts that did arrive**, which the command prints to stderr before exiting: the audio is transcribed and billed before the missing translation is noticed, so with `--to de,fr,es,it,ja` one dropped target must not throw away the source transcript and four good translations and make the user re-stream to see them. Target updates are also matched **case-insensitively**, because the requested spellings include `zh-HANS` and `en-GB`: a server echoing another canonicalization had its translation silently dropped by the existing unmatched-update guard, and this check would then have reported that target as missing — turning a cosmetic mismatch into a failed session. Silent partial output was the worse failure: a script consuming `deepl voice` output saw success with the translation missing. Audio containing no speech transcribes to nothing and translates to nothing, which is legitimate and still exits 0, so the check only applies when a source transcript exists. Whitespace-only and tentative-but-never-concluded translations count as missing, since neither reaches the printed output. Investigated as an intermittent (~1 in 4) empty translated line; the leading hypothesis was disproved with frame-level traces of live sessions — the server sends `end_of_stream` strictly after `end_of_target_transcript`, and the client only tears the socket down on `end_of_stream`, so there is no client-side teardown race. Reconnect was ruled out too: a socket dropped after end-of-source cannot be resumed (the API returns `410 Gone`) and already exited non-zero. The empty line did not reproduce in 64 live runs across pacing, burst, multi-target, and concurrency variations, so the trigger appears to be server-side and transient — which is exactly why the client needs to detect it rather than report success.
 - **formats**: TOML reconstruction escapes U+2028/U+2029 (Unicode line/paragraph separators) in double-quoted values, and literal-string values gaining one fall back to double quotes. Written raw, these characters broke the entry-line scan on the *next* sync (JavaScript's `.` excludes line terminators), which re-appended the key as a duplicate and made the third sync fail to parse the file at all — first sync fine, second silently corrupting, third crashing. Found by the property-based round-trip suite.
 - **formats**: `.properties` reconstruction escapes leading spaces in values (`\ `), which the value parser otherwise strips on the next read — a translation beginning with a space silently lost it on every subsequent sync. Leading tabs, trailing spaces, and newlines were already escaped correctly. Found by the property-based round-trip suite.
 - **sync**: `--auto-commit` now recognises its own translation output rather than only the files a given run wrote, which fixes two related problems. A translation left on disk by an earlier refused run was classed as an unrelated modification, so auto-commit refused forever and the user had to commit it by hand; it is now committed once the genuinely unrelated changes are dealt with. And in `--watch` mode, where the same path runs once per trigger, a trigger that translated nothing skipped the checks entirely and reported success while a commit was still owed. Staging is also driven by what is actually dirty, so a rewrite that produced identical bytes no longer attempts an empty commit. Ownership is derived from the lockfile's tracked source files, with each file matched to its own bucket so one bucket's `target_path_pattern` cannot claim another's output.

From 8c26e1e3b14b4f78ee40a336c6e7b17866dd467a Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 18:10:36 -0400
Subject: [PATCH 043/256] fix(languages): list the bundled snapshot in --format
 json without an API key

The JSON path answered {"source":[],"target":[]} while text and table printed all
125 languages from the same snapshot, so the documented offline listing worked in
two formats out of three. JSON falls back to the snapshot as the others do.
---
 CHANGELOG.md                           |  2 ++
 src/cli/commands/register-languages.ts | 37 +++++++++++++++++++++-----
 tests/e2e/cli-languages.e2e.test.ts    | 27 +++++++++++++++++++
 3 files changed, 60 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a3025bf..96cc0824 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,6 +95,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **languages**: `--features` no longer claims knowledge it does not have. The listing keeps snapshot entries the API response omitted, and every one of them was rendered as the positive claim `none` — with a response covering a handful of languages, `--features` reported over a hundred as supporting nothing. Those rows also made every feature look non-uniform, so features shared by all the described languages became columns of repeated values instead of the single footer note the flag was built around. A feature reported without a `status` rendered as the literal string `undefined` (the enum is open, and an absent status still means the feature is there), and `supportsFormality` was asserted `false` for languages whose features the response never mentioned, turning on the `[F]` legend with no `[F]` anywhere to explain it. `deepl languages` also makes one `GET /v3/languages` request instead of two identical ones — both roles are filtered out of the same payload.
 
+- **languages**: `deepl languages --format json` with no API key answered `{"source":[],"target":[]}` while the text and table formats printed all 125 from the bundled snapshot. Both read the same snapshot, so the JSON path now falls back to it too — listing languages works offline in every format.
+
 - **config**: `deepl config set defaults.sourceLang DE` was rejected while `deepl translate --from DE` works. Every translate path lowercases the flag before validating, but the config validator matched a lowercase-only pattern, so the one casing that is certainly valid was the one class of input still refused. Language values are lowercased before validation and stored normalized. A code the bundled snapshot does not list is still accepted, since the snapshot can lag the API, but now warns at the point of entry — a typo written to config otherwise failed on every later command with nothing pointing back at the config value responsible.
 
 - **translate**: `--tag-handling-version` is honoured for files and directories, not only for text. The shared option mapping carried `--tag-handling` but not the version, so with the CLI now pinning v2 whenever tag handling is on, `deepl translate page.html --tag-handling html --tag-handling-version v1` silently sent v2 — and single-file mode emits no ignored-option warning to say so. The flag is mapped in the shared mapping every handler uses, and its validation moved with it.
diff --git a/src/cli/commands/register-languages.ts b/src/cli/commands/register-languages.ts
index 87c171fb..4679b081 100644
--- a/src/cli/commands/register-languages.ts
+++ b/src/cli/commands/register-languages.ts
@@ -18,6 +18,23 @@ function forJson(languages: LanguageInfo[], includeFeatures: boolean): unknown[]
   });
 }
 
+/**
+ * The bundled snapshot in LanguageInfo shape, for output with no API key.
+ *
+ * Without this the JSON path answered `{"source":[],"target":[]}` while the text
+ * path printed all 125 from the same snapshot -- listing languages works offline
+ * either way, so the two formats have no business disagreeing.
+ */
+function registryAsLanguageInfo(
+  command: { getRegistryLanguages: (type: 'source' | 'target') => Array<{ code: string; name: string }> },
+  type: 'source' | 'target',
+): LanguageInfo[] {
+  return command.getRegistryLanguages(type).map(entry => ({
+    language: entry.code as LanguageInfo['language'],
+    name: entry.name,
+  }));
+}
+
 export function registerLanguages(
   program: Command,
   deps: {
@@ -66,16 +83,24 @@ Examples:
         const languagesCommand = await createLanguagesCommand(client);
 
         if (options.format === 'json') {
+          const listFor = async (type: 'source' | 'target'): Promise<LanguageInfo[]> => {
+            const fromApi =
+              type === 'source'
+                ? await languagesCommand.getSourceLanguages()
+                : await languagesCommand.getTargetLanguages();
+            return fromApi.length === 0 && !hasApiKey
+              ? registryAsLanguageInfo(languagesCommand, type)
+              : fromApi;
+          };
+
           if (options.source && !options.target) {
-            const sourceLanguages = await languagesCommand.getSourceLanguages();
-            Logger.output(JSON.stringify(forJson(sourceLanguages, showFeatures), null, 2));
+            Logger.output(JSON.stringify(forJson(await listFor('source'), showFeatures), null, 2));
           } else if (options.target && !options.source) {
-            const targetLanguages = await languagesCommand.getTargetLanguages();
-            Logger.output(JSON.stringify(forJson(targetLanguages, showFeatures), null, 2));
+            Logger.output(JSON.stringify(forJson(await listFor('target'), showFeatures), null, 2));
           } else {
             const [sourceLanguages, targetLanguages] = await Promise.all([
-              languagesCommand.getSourceLanguages(),
-              languagesCommand.getTargetLanguages(),
+              listFor('source'),
+              listFor('target'),
             ]);
             Logger.output(JSON.stringify({
               source: forJson(sourceLanguages, showFeatures),
diff --git a/tests/e2e/cli-languages.e2e.test.ts b/tests/e2e/cli-languages.e2e.test.ts
index 8283a661..4d2ec491 100644
--- a/tests/e2e/cli-languages.e2e.test.ts
+++ b/tests/e2e/cli-languages.e2e.test.ts
@@ -102,6 +102,33 @@ describe('Languages Command E2E', () => {
       const combined = result.stdout + result.stderr;
       expect(combined).toMatch(/no api key|local.*registry/i);
     });
+
+    it('should list the same languages in --format json as in text output', () => {
+      // Both formats read the same bundled snapshot, so answering
+      // {"source":[],"target":[]} while the text output printed 125 was the JSON
+      // path simply not falling back.
+      const result = runCLIWithEnv('languages --format json', { DEEPL_API_KEY: '' });
+
+      expect(result.status).toBe(0);
+      const parsed = JSON.parse(result.stdout) as {
+        source: Array<{ language: string; name: string }>;
+        target: Array<{ language: string; name: string }>;
+      };
+      expect(parsed.source.length).toBeGreaterThan(100);
+      expect(parsed.target.length).toBeGreaterThan(parsed.source.length);
+      expect(parsed.source).toEqual(
+        expect.arrayContaining([{ language: 'de', name: 'German' }]),
+      );
+      expect(parsed.target.map(entry => entry.language)).toContain('en-gb');
+    });
+
+    it('should list target-only languages in --format json --target', () => {
+      const result = runCLIWithEnv('languages --target --format json', { DEEPL_API_KEY: '' });
+
+      expect(result.status).toBe(0);
+      const parsed = JSON.parse(result.stdout) as Array<{ language: string }>;
+      expect(parsed.map(entry => entry.language)).toContain('pt-br');
+    });
   });
 
   describe('languages --features (against the mock API)', () => {

From 66f5e55c8315d0820a81ce70cc73bf0f36bfe246 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 18:21:10 -0400
Subject: [PATCH 044/256] docs(comments): describe current behaviour instead of
 how it got there

Comments across the language, glossary, voice, cache, usage and generator code
narrated the development process -- what the code used to do, which bug a check
exists because of, what an earlier version got wrong. They now state the
behaviour and the constraint behind it.

Two corrections came with the pass: the generated Write-language doc still said
`write`/`correct` reject an unknown code locally, which is no longer what the
code does, and the same text lives in the generator template, so the snapshot
was re-rendered from it and verified byte-identical against the live API.
---
 scripts/generate-language-registry.mjs        | 52 ++++++++-----------
 src/api/glossary-client.ts                    |  4 +-
 src/api/translation-client.ts                 | 20 +++----
 src/cli/commands/glossary.ts                  |  4 +-
 src/cli/commands/languages.ts                 | 18 +++----
 src/cli/commands/register-languages.ts        |  7 +--
 src/cli/commands/register-translate.ts        |  6 +--
 src/cli/commands/register-watch.ts            |  4 +-
 src/cli/commands/register-write.ts            | 13 +++--
 .../translate/document-translation-handler.ts |  5 +-
 src/cli/commands/translate/translate-utils.ts | 14 +++--
 .../translate/translation-options-factory.ts  |  6 +--
 src/cli/commands/voice.ts                     |  6 +--
 src/data/language-entries.ts                  | 13 +++--
 src/data/language-registry.ts                 | 15 +++---
 src/services/batch-translation.ts             |  4 +-
 src/services/glossary.ts                      | 12 ++---
 src/services/translation.ts                   | 12 ++---
 src/services/voice-stream-session.ts          | 10 ++--
 src/storage/config.ts                         | 12 ++---
 src/sync/sync-service.ts                      |  4 +-
 src/types/common.ts                           | 16 +++---
 src/utils/glossary-params.ts                  | 11 ++--
 src/utils/unrecoverable-request-error.ts      |  7 ++-
 tests/e2e/cli-languages.e2e.test.ts           |  7 ++-
 tests/unit/glossary-params.test.ts            |  4 +-
 tests/unit/language-registry.test.ts          |  3 +-
 tests/unit/register-write.test.ts             |  5 +-
 tests/unit/translate-utils.test.ts            |  8 +--
 tests/unit/translation-client.test.ts         |  2 +-
 tests/unit/voice-stream-session.test.ts       |  5 +-
 31 files changed, 139 insertions(+), 170 deletions(-)

diff --git a/scripts/generate-language-registry.mjs b/scripts/generate-language-registry.mjs
index 55314b4d..19233669 100644
--- a/scripts/generate-language-registry.mjs
+++ b/scripts/generate-language-registry.mjs
@@ -1,11 +1,7 @@
 #!/usr/bin/env node
 /**
- * Regenerates src/data/language-entries.ts from GET /v3/languages.
- *
- * The language list used to be hand-maintained, which meant it could silently
- * fall behind the API: four target languages DeepL had added (de-CH, de-DE,
- * fr-CA, fr-FR) were missing, so the CLI rejected them locally even though the
- * API accepted them. Generating the file keeps it an honest snapshot.
+ * Regenerates src/data/language-entries.ts from GET /v3/languages, keeping the
+ * bundled snapshot a build artifact of the API rather than a hand-kept list.
  *
  * Tiers are derived, not judged: the derivation lives in
  * src/data/language-registry.ts and is imported from dist/ so the snapshot and
@@ -25,11 +21,10 @@ const TARGET = path.join(ROOT, 'src', 'data', 'language-entries.ts');
 const DERIVATION = path.join(ROOT, 'dist', 'data', 'language-registry.js');
 
 /**
- * A tier count this far below the live shape means the derivation stopped
- * working rather than that DeepL dropped languages -- most likely the features
- * matrix stopped reporting `glossary`, which would silently retier all 125
- * languages as extended and make --formality and --glossary unusable
- * everywhere. Cheap floor, catches the whole failure class.
+ * A core count below this means the derivation is broken rather than that DeepL
+ * dropped languages -- most likely the features matrix no longer reports
+ * `glossary`, which would tier every language as extended and make --formality
+ * and --glossary unusable. Cheap floor over the whole failure class.
  */
 const MIN_CORE_LANGUAGES = 20;
 
@@ -54,9 +49,8 @@ function renderEntry(entry) {
 }
 
 /**
- * Renders the whole file. Exported so the snapshot can be re-rendered from the
- * data it already holds -- a formatting or type change to the template does not
- * need a live API call to apply.
+ * Renders the whole file. Exported so the snapshot can also be re-rendered from
+ * the data it already holds, without a live API call.
  */
 export function renderRegistry(entries, writeTargets) {
   const body = GROUPS.map(([category, heading]) => {
@@ -78,7 +72,7 @@ export function renderRegistry(entries, writeTargets) {
  *
  * \`as const\` is load-bearing: the Language union in src/types/common.ts is
  * derived from these codes, so a language added upstream widens the type on
- * regenerate instead of needing a second hand-kept copy of the same list.
+ * regenerate.
  */
 import type { LanguageEntry } from './language-registry.js';
 
@@ -89,14 +83,13 @@ ${body}
 /**
  * Target languages the Write API accepts, from resource=write.
  *
- * Unlike translation, \`write\` and \`correct\` reject a code outside this list
- * locally rather than deferring to the API: the supported set is small enough
- * to enumerate in the error, so naming the valid options beats a round trip.
- * That makes keeping this generated the thing that stops it going stale.
+ * \`write\` and \`correct\` check a code against this list locally, because the
+ * set is small enough for the error to name every option. A code shaped like a
+ * language tag but absent from the list still goes to the API, with the list as
+ * a warning, so a language added upstream is usable before a regenerate.
  *
  * \`as const\` is load-bearing -- the WriteLanguage union in src/types/api.ts is
- * derived from it, so adding a language upstream widens the type on regenerate
- * instead of needing a second hand edit.
+ * derived from it, so a language added upstream widens the type on regenerate.
  */
 export const WRITE_TARGET_LANGUAGES = [
 ${writeTargets.map(code => `  '${code}',`).join('\n')}
@@ -136,9 +129,8 @@ async function main() {
     return { resource, languages };
   }
 
-  // Fetched together and reported together: failing fast on the first resource
-  // meant a key that cannot read resource=write blocked regenerating the
-  // translation list too, which it can read perfectly well.
+  // Fetched and reported together, so a key that cannot read one resource still
+  // regenerates from the other and both failures surface at once.
   const [translateResult, writeResult] = await Promise.all([
     fetchResource('translate_text'),
     fetchResource('write'),
@@ -165,8 +157,8 @@ async function main() {
         'snapshot that would retier every language as extended.',
     );
   }
-  // An empty write list would collapse the WriteLanguage union to never, so
-  // every --lang would be rejected while naming no valid option at all.
+  // An empty write list collapses the WriteLanguage union to never, which would
+  // reject every --lang while naming no valid option at all.
   if (writeTargets.length === 0) {
     fail('no write target languages reported (expected usable_as_target on resource=write)');
   }
@@ -181,10 +173,10 @@ async function main() {
       );
       process.exit(0);
     }
-    // Name which list moved: the two are generated from different resources, and
-    // "N languages upstream" is misleading when it is the write list that drifted.
-    // Compared on the whole block rather than the codes alone, so a renamed
-    // display name is not reported as "formatting only".
+    // Name which list moved: the two come from different resources, so "N
+    // languages upstream" is misleading when it is the write list that drifted.
+    // Whole blocks are compared, not just the codes, so a renamed display name
+    // is reported as real drift.
     const blockIn = (source, open, close) => {
       const start = source.indexOf(open);
       if (start === -1) return '';
diff --git a/src/api/glossary-client.ts b/src/api/glossary-client.ts
index e65eb2b6..2203e6ca 100644
--- a/src/api/glossary-client.ts
+++ b/src/api/glossary-client.ts
@@ -33,8 +33,8 @@ export class GlossaryClient extends HttpClient {
     const pairs: GlossaryLanguagePair[] = [];
     for (const source of sources) {
       for (const target of targets) {
-        // Compared after normalization: raw casing differing between the two role
-        // lists would otherwise emit a self-pair the API does not offer.
+        // Compared after normalization, so casing differing between the two role
+        // lists cannot emit a self-pair the API does not offer.
         const sourceLang = this.normalizeLanguage(source.lang);
         const targetLang = this.normalizeLanguage(target.lang);
         if (sourceLang === targetLang) {
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index 1d031cb9..a2e4a4f9 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -76,9 +76,8 @@ export interface ProductUsage {
   apiKeyCharacterCount: number;
   unitCount?: number;
   /**
-   * Account-wide units. What live responses actually carry for duration-billed
-   * products, where `unit_count` is absent -- so leaving it unparsed made the
-   * account total unreportable.
+   * Account-wide units, which is what duration-billed products report instead of
+   * `unit_count`.
    */
   accountUnitCount?: number;
   apiKeyUnitCount?: number;
@@ -297,12 +296,10 @@ export class TranslationClient extends HttpClient {
    * per-language features matrix, which is what v2's supports_formality became.
    */
   /**
-   * The raw translate_text language list, fetched at most once per client.
-   *
-   * Both roles are filtered out of one payload, and the request does not vary by
-   * role, so `deepl languages` -- which asks for both -- was making the same
-   * full-list request twice. A failed fetch is not retained, so the next caller
-   * retries.
+   * The raw translate_text language list, fetched at most once per client. The
+   * request does not vary by role and both roles are filtered out of the one
+   * payload, so a caller asking for both costs a single request. A failed fetch
+   * is not retained, leaving the next caller free to retry.
    */
   private translateLanguages?: Promise<DeepLV3LanguageResponse[]>;
 
@@ -331,9 +328,8 @@ export class TranslationClient extends HttpClient {
           return {
             language: code,
             name: lang.name,
-            // Only claimed when the response actually described this language's
-            // features: asserting false for a language it said nothing about
-            // turned the [F] legend on with no [F] anywhere to explain it.
+            // Only claimed when the response described this language's features;
+            // silence about a language is not evidence that formality is absent.
             ...(type === 'target' &&
               lang.features && {
                 supportsFormality: lang.features['formality'] !== undefined,
diff --git a/src/cli/commands/glossary.ts b/src/cli/commands/glossary.ts
index fcf41191..d0e6a158 100644
--- a/src/cli/commands/glossary.ts
+++ b/src/cli/commands/glossary.ts
@@ -251,8 +251,8 @@ export class GlossaryCommand {
     if (multilingual) {
       lines.push('\nLanguage pairs:');
       glossary.dictionaries.forEach(dict => {
-        // Lowercased like the summary above: normalizeGlossaryInfo only touches
-        // the top-level fields, so raw dictionaries printed EN -> DE under en.
+        // Lowercased like the summary above; normalizeGlossaryInfo only touches
+        // the top-level fields.
         lines.push(`  ${dict.source_lang.toLowerCase()} → ${dict.target_lang.toLowerCase()}: ${dict.entry_count} entries`);
       });
     }
diff --git a/src/cli/commands/languages.ts b/src/cli/commands/languages.ts
index 2a20079a..7cab4644 100644
--- a/src/cli/commands/languages.ts
+++ b/src/cli/commands/languages.ts
@@ -52,7 +52,7 @@ const UNKNOWN_CELL = '?';
 /**
  * Whether the response described this language's features at all. An empty
  * matrix is data -- it says the language supports none of them -- while a
- * missing one means the language never appeared in the response.
+ * missing one means the language did not appear in the response.
  */
 function hasFeatureData(entry: LanguageDisplayEntry): boolean {
   return entry.features !== undefined;
@@ -64,9 +64,9 @@ function hasFeatureData(entry: LanguageDisplayEntry): boolean {
  * than `stable` is shown verbatim rather than collapsed to yes. `status` is an
  * open enum and may be absent, which still means the feature is there.
  *
- * A language the response omitted entirely reads as unknown rather than
- * unsupported: the listing keeps snapshot entries the API did not mention, and
- * claiming they support nothing would be inventing an answer.
+ * A language the response omitted reads as unknown rather than unsupported:
+ * the listing includes snapshot entries the API did not mention, and claiming
+ * they support nothing would be inventing an answer.
  */
 function featureCell(entry: LanguageDisplayEntry, key: string): string {
   if (!hasFeatureData(entry)) return UNKNOWN_CELL;
@@ -96,9 +96,9 @@ export function partitionFeatureKeys(entries: LanguageDisplayEntry[]): {
   columns: string[];
   uniform: Array<{ key: string; cell: string }>;
 } {
-  // Only languages the response described can say whether a feature varies;
-  // including the rest made every feature look non-uniform, so a feature all of
-  // them share became a column of repeated values instead of one footer note.
+  // Only languages the response described can say whether a feature varies.
+  // Counting the rest would make every feature look non-uniform, turning one
+  // shared by all of them into a column of repeated values.
   const described = entries.filter(hasFeatureData);
   if (described.length === 0) return { columns: [], uniform: [] };
 
@@ -133,7 +133,7 @@ function hasAnyFeatures(entries: LanguageDisplayEntry[]): boolean {
 /**
  * Lowercased feature list for prose contexts, e.g. `glossary, style rules`.
  * Empty when there is nothing per-language to say: with no discriminating
- * features the footer note carries the answer, and annotating every row `none`
+ * features the footer note carries the answer, so annotating each row `none`
  * would contradict it.
  */
 function featureList(entry: LanguageDisplayEntry, keys: string[]): string {
@@ -152,7 +152,7 @@ function featureList(entry: LanguageDisplayEntry, keys: string[]): string {
 /**
  * The one-line summary for features every language shares. Scoped to the
  * languages the response described when some rows carry no data, since those
- * rows are listed too and the note must not speak for them.
+ * rows are listed too and the note cannot speak for them.
  */
 function uniformNote(
   uniform: Array<{ key: string; cell: string }>,
diff --git a/src/cli/commands/register-languages.ts b/src/cli/commands/register-languages.ts
index 4679b081..3cc0243f 100644
--- a/src/cli/commands/register-languages.ts
+++ b/src/cli/commands/register-languages.ts
@@ -19,11 +19,8 @@ function forJson(languages: LanguageInfo[], includeFeatures: boolean): unknown[]
 }
 
 /**
- * The bundled snapshot in LanguageInfo shape, for output with no API key.
- *
- * Without this the JSON path answered `{"source":[],"target":[]}` while the text
- * path printed all 125 from the same snapshot -- listing languages works offline
- * either way, so the two formats have no business disagreeing.
+ * The bundled snapshot in LanguageInfo shape, for output with no API key, so that
+ * JSON lists the same languages the text and table formats read from it.
  */
 function registryAsLanguageInfo(
   command: { getRegistryLanguages: (type: 'source' | 'target') => Array<{ code: string; name: string }> },
diff --git a/src/cli/commands/register-translate.ts b/src/cli/commands/register-translate.ts
index 21f3e4b8..ae76845b 100644
--- a/src/cli/commands/register-translate.ts
+++ b/src/cli/commands/register-translate.ts
@@ -170,9 +170,9 @@ Examples:
           );
         }
 
-        // Checked before --dry-run reports the command as runnable. Glossary name
-        // resolution still needs the API and stays out of dry-run, but the
-        // requirement that a glossary carry a source language does not.
+        // Checked before --dry-run reports the command as runnable. Resolving a
+        // glossary name needs the API and stays out of dry-run; the requirement
+        // that a glossary carry a source language does not.
         if (hasGlossarySelection(options)) {
           applyGlossarySourceLang(
             options,
diff --git a/src/cli/commands/register-watch.ts b/src/cli/commands/register-watch.ts
index 406a50f0..a78fa3c3 100644
--- a/src/cli/commands/register-watch.ts
+++ b/src/cli/commands/register-watch.ts
@@ -68,8 +68,8 @@ Examples:
           }
         }
 
-        // Resolved before --dry-run so a well-formed-looking command is not
-        // reported as runnable when it would fail on the first file change.
+        // Resolved before --dry-run, which otherwise reports a command as
+        // runnable when it would fail on the first file change.
         if (hasGlossarySelection(options)) {
           applyGlossarySourceLang(
             options,
diff --git a/src/cli/commands/register-write.ts b/src/cli/commands/register-write.ts
index 62ad3ad2..5d573627 100644
--- a/src/cli/commands/register-write.ts
+++ b/src/cli/commands/register-write.ts
@@ -13,10 +13,10 @@ import { createWriteCommand, type ServiceDeps } from './service-factory.js';
 
 /**
  * Generated from GET /v3/languages?resource=write. Small enough that an error can
- * name every option, which is why it is checked locally at all -- but it is still
- * a snapshot, so an unrecognized code that is shaped like a language tag is
- * deferred to the API with a warning rather than rejected. Rejecting outright
- * made a language DeepL had added unreachable until someone regenerated the file.
+ * name every option, which is why it is checked locally at all. It is still a
+ * snapshot, so a code shaped like a language tag but absent from it goes to the
+ * API with a warning rather than being rejected -- otherwise a language DeepL
+ * adds is unreachable until the file is regenerated.
  */
 export const WRITE_LANGUAGES = WRITE_TARGET_LANGUAGES;
 /**
@@ -89,9 +89,8 @@ export function createWriteAction(
         if (canonical) {
           options.lang = canonical;
         } else if (looksLikeLanguageTag(options.lang.toLowerCase())) {
-          // The bundled list is a snapshot and can lag the API, and nothing in CI
-          // regenerates it, so a language DeepL has added must not be
-          // unreachable: a well-formed code goes to the API to accept or reject.
+          // The snapshot can lag the API, so a well-formed code it does not list
+          // is the API's to accept or reject.
           Logger.warn(
             `Note: "${options.lang}" is not in the bundled Write language list; deferring to the API.\n` +
               `      Bundled options: ${WRITE_LANGUAGES.join(', ')}`
diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index 0a3f0502..ae80286b 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -26,9 +26,8 @@ export class DocumentTranslationHandler {
     warnIgnoredOptions('document', options, supported);
 
     validateLanguageCodes([options.to]);
-    // Documents support glossaries now, which makes the extended-tier constraint
-    // reachable here: without this the upload happens and the API rejects it,
-    // while the text path says so locally.
+    // Documents accept glossaries, so the extended-tier constraint applies here
+    // too: checked before the upload rather than left to the API.
     validateExtendedLanguageConstraints(options.to, options);
 
     // The API rejects a document glossary without source_lang: "source_lang has
diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index a24544ef..4e448d0b 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -61,17 +61,15 @@ export function warnIgnoredOptions(mode: string, options: TranslateOptions, supp
 /**
  * Rejects input that is not shaped like a language tag. Codes the bundled
  * snapshot does not list are passed through: GET /v3/languages is the authority
- * on which languages exist, and the snapshot can lag it, so rejecting here made
- * languages the API accepts unusable. The API answers an unknown code with a
- * 400 of its own.
+ * on which languages exist and the snapshot can lag it, so an unknown code is
+ * the API's to accept or reject with a 400 of its own.
  */
 export function validateLanguageCodes(langCodes: string[]): void {
   for (const lang of langCodes) {
     if (VALID_LANGUAGES.has(lang)) continue;
     if (looksLikeLanguageTag(lang)) {
-      // Said up front, before anything is sent or billed. Deferring to the API
-      // means a two-letter typo now comes back as a bare "target_lang not
-      // supported" from the server, which no longer points anywhere useful.
+      // Said up front, before anything is sent or billed: the API answers an
+      // unknown code with a bare "target_lang not supported" that points nowhere.
       Logger.warn(
         `Note: "${lang}" is not in the bundled language list; deferring to the API.\n` +
           '      Run: deepl languages  to see the languages this build knows about.'
@@ -128,8 +126,8 @@ export function validateXmlTags(tags: string[], paramName: string): void {
 
 /**
  * Validate `--tag-handling-version` and return it. Shared so every handler maps
- * the flag: since the CLI pins v2 whenever tag handling is on, a handler that
- * dropped the flag would silently send v2 to a caller who asked for v1.
+ * the flag: the CLI pins v2 whenever tag handling is on, so a handler that
+ * dropped the flag would send v2 to a caller who asked for v1.
  */
 export function validateTagHandlingVersion(
   options: TranslateOptions,
diff --git a/src/cli/commands/translate/translation-options-factory.ts b/src/cli/commands/translate/translation-options-factory.ts
index 5cd483f9..21958f48 100644
--- a/src/cli/commands/translate/translation-options-factory.ts
+++ b/src/cli/commands/translate/translation-options-factory.ts
@@ -60,9 +60,9 @@ export async function applyGlossarySelection<
   // before the next name-or-ID lookup needs the glossary list.
   //
   // Deduplicated after resolution, because a name and its own UUID resolve to
-  // the same glossary: naming one twice would otherwise flip the wire parameter
-  // from glossary_id to glossary_ids, mint a third cache key for an identical
-  // request, and spend two of the five slots the API allows.
+  // the same glossary: a duplicate would flip the wire parameter from
+  // glossary_id to glossary_ids, key an identical request differently, and
+  // spend two of the five slots the API allows.
   const ids: string[] = [];
   for (const nameOrId of options.glossary) {
     const id = await resolveGlossaryId(glossaryService, nameOrId, expected);
diff --git a/src/cli/commands/voice.ts b/src/cli/commands/voice.ts
index f8cdfeca..75b54f72 100644
--- a/src/cli/commands/voice.ts
+++ b/src/cli/commands/voice.ts
@@ -262,9 +262,9 @@ export class VoiceCommand {
 
   /**
    * Print what a failed session did produce. The audio is transcribed and billed
-   * before the missing translation is noticed, so discarding the transcripts
-   * would make the user re-stream and pay again to see them. Written to stderr so
-   * a partial result is never mistaken for the command's output.
+   * before a missing translation is noticed, so discarding the transcripts would
+   * cost another stream to see them. Written to stderr, so a partial result is
+   * never mistaken for the command's output.
    */
   private reportPartialResult(error: unknown, targetCount: number, isTTY: boolean): void {
     if (!(error instanceof VoicePartialResultError)) {
diff --git a/src/data/language-entries.ts b/src/data/language-entries.ts
index 60db1bea..dd544e29 100644
--- a/src/data/language-entries.ts
+++ b/src/data/language-entries.ts
@@ -12,7 +12,7 @@
  *
  * `as const` is load-bearing: the Language union in src/types/common.ts is
  * derived from these codes, so a language added upstream widens the type on
- * regenerate instead of needing a second hand-kept copy of the same list.
+ * regenerate.
  */
 import type { LanguageEntry } from './language-registry.js';
 
@@ -152,14 +152,13 @@ export const ENTRIES = [
 /**
  * Target languages the Write API accepts, from resource=write.
  *
- * Unlike translation, `write` and `correct` reject a code outside this list
- * locally rather than deferring to the API: the supported set is small enough
- * to enumerate in the error, so naming the valid options beats a round trip.
- * That makes keeping this generated the thing that stops it going stale.
+ * `write` and `correct` check a code against this list locally, because the
+ * set is small enough for the error to name every option. A code shaped like a
+ * language tag but absent from the list still goes to the API, with the list as
+ * a warning, so a language added upstream is usable before a regenerate.
  *
  * `as const` is load-bearing -- the WriteLanguage union in src/types/api.ts is
- * derived from it, so adding a language upstream widens the type on regenerate
- * instead of needing a second hand edit.
+ * derived from it, so a language added upstream widens the type on regenerate.
  */
 export const WRITE_TARGET_LANGUAGES = [
   'de',
diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index 5c09de67..c1f7b081 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -40,8 +40,8 @@ export interface LanguageEntry {
 
 /**
  * The snapshot as plain entries. It is generated `as const` so the `Language`
- * union can be derived from its codes; the lookups below want the interface, not
- * 125 individual literal types.
+ * union can derive from its codes; the lookups below want the interface rather
+ * than one literal type per language.
  */
 const ENTRIES: readonly LanguageEntry[] = GENERATED_ENTRIES;
 
@@ -61,11 +61,10 @@ export interface DerivableLanguage {
 /**
  * Derives a registry entry from one GET /v3/languages entry. The tiers are not
  * a human judgement: glossary support separates extended from the rest, and
- * source usability separates core from regional. Checked against the live
- * response, this reproduces the hand-maintained tiers exactly.
+ * source usability separates core from regional.
  *
  * Shared with scripts/generate-language-registry.mjs so the snapshot and the
- * runtime fallback for codes the snapshot predates cannot disagree.
+ * runtime fallback for codes it does not list cannot disagree.
  */
 export function deriveLanguageEntry(language: DerivableLanguage): LanguageEntry {
   const code = language.lang.toLowerCase();
@@ -100,9 +99,9 @@ export function looksLikeLanguageTag(code: string): boolean {
 
 /**
  * The base language of a code, dropping any regional subtag: `en-us` -> `en`.
- * Used where one side of a comparison carries variants the other cannot, such as
- * glossary dictionaries, which only ever name base languages while `--to`
- * accepts `en-us`, `pt-br` and the rest.
+ * For comparisons where one side carries variants the other cannot -- glossary
+ * dictionaries name base languages only, while `--to` accepts `en-us`, `pt-br`
+ * and the rest.
  */
 export function baseLanguage(code: string): string {
   return code.toLowerCase().split('-')[0] ?? code.toLowerCase();
diff --git a/src/services/batch-translation.ts b/src/services/batch-translation.ts
index b4a087f2..9f1080e7 100644
--- a/src/services/batch-translation.ts
+++ b/src/services/batch-translation.ts
@@ -222,8 +222,8 @@ export class BatchTranslationService {
     let currentBatch: FileEntry[] = [];
     let currentBytes = 0;
     // Set once the API rejects the request itself (an unsupported target_lang,
-    // say). Every remaining batch would be told the same thing, so they are
-    // failed without spending the round trips.
+    // say). Every remaining batch would draw the same rejection, so they fail
+    // without spending the round trips.
     let requestRejected: unknown;
 
     const flushBatch = async (): Promise<void> => {
diff --git a/src/services/glossary.ts b/src/services/glossary.ts
index ff93a3e5..d1831626 100644
--- a/src/services/glossary.ts
+++ b/src/services/glossary.ts
@@ -173,11 +173,11 @@ export class GlossaryService {
    * fetched to resolve the name; the UUID path trusts the caller and skips the
    * check, as translation-memory resolution does.
    *
-   * Both sides are compared on their base language, because dictionaries only
-   * ever name base languages while `--to` accepts regional variants: a de→en
-   * glossary has to count as covering de→en-us, which the API accepts. That
-   * makes the check deliberately permissive at the edges — a pair it lets
-   * through is still the API's to reject, which is the cheaper mistake.
+   * Both sides are compared on their base language, because dictionaries name
+   * base languages only while `--to` accepts regional variants: a de→en glossary
+   * covers de→en-us, which the API accepts. That makes the check deliberately
+   * permissive at the edges — a pair it lets through is still the API's to
+   * reject, which is the cheaper mistake.
    */
   async resolveGlossaryId(
     nameOrId: string,
@@ -223,7 +223,7 @@ export class GlossaryService {
         const allPairs = match.dictionaries.map(
           d => `${d.source_lang.toLowerCase()}→${d.target_lang.toLowerCase()}`,
         );
-        // A multilingual glossary can hold dozens of dictionaries, and the whole
+        // A multilingual glossary can hold dozens of dictionaries; the whole
         // cross-product on one line stops being a suggestion.
         const pairs =
           allPairs.length > MAX_PAIRS_IN_SUGGESTION
diff --git a/src/services/translation.ts b/src/services/translation.ts
index d9f8e0d3..1c6448eb 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -403,12 +403,12 @@ export class TranslationService {
    * would let the key stay stable across a change of the API's own default,
    * serving entries the API would no longer produce.
    *
-   * Every parameter that changes the returned text has to appear here or the
-   * cache serves the wrong translation: a plain request and the same request
-   * with a translation memory, different --ignore-tags, or --preserve-formatting
-   * are different requests. `preserveFormatting` is included because
-   * preserve_formatting suppresses the sentence-boundary punctuation and case
-   * correction, which shows up in the text.
+   * Every parameter that changes the returned text belongs here, or the cache
+   * serves the wrong translation: a plain request and the same request with a
+   * translation memory, different --ignore-tags, or --preserve-formatting are
+   * different requests. `preserveFormatting` counts because preserve_formatting
+   * suppresses the sentence-boundary punctuation and case correction, which
+   * shows up in the text.
    */
   private generateCacheKey(text: string, options: TranslationOptions): string {
     // Keyed on the parameter the request will actually carry, so the two ways of
diff --git a/src/services/voice-stream-session.ts b/src/services/voice-stream-session.ts
index bb09a3e4..28c943c6 100644
--- a/src/services/voice-stream-session.ts
+++ b/src/services/voice-stream-session.ts
@@ -24,8 +24,8 @@ const DEFAULT_MAX_RECONNECT_ATTEMPTS = 3;
 
 /**
  * A session that ended with at least one target untranslated, carrying whatever
- * did arrive. The audio has been transcribed and billed by this point, so the
- * partial transcripts travel with the failure instead of being discarded.
+ * did arrive. The audio is transcribed and billed by this point, so the partial
+ * transcripts travel with the failure rather than being discarded.
  */
 export class VoicePartialResultError extends VoiceError {
   constructor(
@@ -76,9 +76,9 @@ export class VoiceStreamSession {
 
     for (const lang of options.targetLangs) {
       const transcript: VoiceTranscript = { lang, text: '', segments: [] };
-      // Keyed lowercase because the requested spellings (zh-HANS, en-GB) are not
-      // the only canonicalization the server might echo, and an unmatched update
-      // is dropped silently -- which then reads as a missing translation.
+      // Keyed lowercase: the requested spellings (zh-HANS, en-GB) are not the
+      // only canonicalization the server may echo, and an update that matches no
+      // target is dropped, which reads as a missing translation.
       this.targetTranscripts.set(lang.toLowerCase(), transcript);
       this.textParts.set(transcript, []);
     }
diff --git a/src/storage/config.ts b/src/storage/config.ts
index b4d979e1..0f0b0e5b 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -47,7 +47,7 @@ const DEFAULT_DEBOUNCE_MS = 500;
 
 /**
  * Language values are stored lowercase, matching what `deepl languages` prints
- * and what every translate path normalizes its flags to, so a config written as
+ * and what the translate paths normalize their flags to, so a config written as
  * `DE` does not read back as a code the registry cannot look up.
  */
 function normalizeLanguageValue(path: string, value: unknown): unknown {
@@ -400,17 +400,17 @@ export class ConfigService {
    * is the authority on which languages exist and the snapshot can lag it.
    */
   private validateLanguage(lang: string, key?: string): void {
-    // Lowercased first: every translate path lowercases the flag before using it,
-    // so `--from DE` works while `config set defaults.sourceLang DE` was rejected
-    // by a lowercase-only pattern -- the one casing that is certainly valid.
+    // Lowercased first: the translate paths lowercase their flags before use, and
+    // the tag pattern below is lowercase-only, so `DE` is as valid as `de` here.
     const normalized = typeof lang === 'string' ? lang.toLowerCase() : lang;
     if (!isValidLanguage(normalized) && !looksLikeLanguageTag(normalized)) {
       const context = key ? ` for "${key}"` : '';
       throw new ConfigError(`Invalid language code "${lang}"${context}. Run: deepl languages to see valid codes`);
     }
     if (!isValidLanguage(normalized)) {
-      // Stored anyway, because the snapshot can lag the API -- but a typo written
-      // to config fails on every later command with nothing pointing back here.
+      // Stored anyway, since the snapshot can lag the API -- but flagged here,
+      // because a typo in config otherwise surfaces on every later command with
+      // nothing pointing back at the value responsible.
       const context = key ? ` for "${key}"` : '';
       Logger.warn(
         `Note: "${lang}"${context} is not in the bundled language list; it will be sent to the API as-is.\n` +
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index b08ea1a1..088d223a 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -192,8 +192,8 @@ export class SyncService {
     let resolvedGlossaryId: string | undefined;
     if (config.translation?.glossary && config.translation.glossary !== 'auto' && !options?.dryRun) {
       // The pair is known from the config, so a glossary that does not cover it
-      // fails here rather than once per file, as translation-memory resolution
-      // below already does.
+      // fails here rather than once per file, as with the translation memory
+      // below.
       const glossaryLocales = options?.localeFilter?.length
         ? config.target_locales.filter(l => options.localeFilter!.includes(l))
         : config.target_locales;
diff --git a/src/types/common.ts b/src/types/common.ts
index ffe3f10f..069ec28d 100644
--- a/src/types/common.ts
+++ b/src/types/common.ts
@@ -5,17 +5,13 @@
 import { ENTRIES } from '../data/language-entries.js';
 
 /**
- * Every language code the bundled snapshot lists, which is generated from
- * GET /v3/languages.
+ * Every language code in the bundled snapshot, which is generated from
+ * GET /v3/languages. Derived from the snapshot so the two cannot disagree:
+ * regenerating it widens this union.
  *
- * Derived rather than hand-maintained: as a written-out union this was a fourth
- * copy of the same list and had already fallen four codes behind the snapshot
- * (de-ch, de-de, fr-ca, fr-fr), so the published typings could not describe a
- * config the CLI itself accepts. Regenerating the snapshot now widens this too.
- *
- * The API remains the authority on which languages exist -- runtime validation
- * accepts well-formed codes the snapshot predates, so this union is the set the
- * CLI can name offline, not the set that works.
+ * The API is the authority on which languages exist, and runtime validation
+ * accepts well-formed codes the snapshot does not list, so this is the set the
+ * CLI can name offline rather than the set that works.
  */
 export type Language = (typeof ENTRIES)[number]['code'];
 
diff --git a/src/utils/glossary-params.ts b/src/utils/glossary-params.ts
index 1046dec1..c03f0f41 100644
--- a/src/utils/glossary-params.ts
+++ b/src/utils/glossary-params.ts
@@ -24,12 +24,11 @@ export function hasGlossarySelection(selection: GlossarySourceLangSelection): bo
  * Settle the source language a glossary request will carry, filling `from` from
  * the configured default when the flag is absent.
  *
- * The API rejects a glossary without `source_lang`, but `--from` is not the only
- * way one is supplied: `TranslationService` merges `defaults.sourceLang`, so
- * rejecting on a missing flag alone broke sessions that had been working from
- * config. Resolving it onto `from` instead means every path sees the same
- * answer, including the document path, which merges no defaults of its own, and
- * the glossary preflight, which needs the pair to check coverage.
+ * The API rejects a glossary without `source_lang`, and `--from` is not the only
+ * way one is supplied: `TranslationService` merges `defaults.sourceLang`.
+ * Resolving the effective value onto `from` gives every path the same answer,
+ * including the document path, which merges no defaults of its own, and the
+ * glossary preflight, which needs the pair to check coverage.
  */
 export function applyGlossarySourceLang(
   selection: GlossarySourceLangSelection,
diff --git a/src/utils/unrecoverable-request-error.ts b/src/utils/unrecoverable-request-error.ts
index 5f7efb9d..cffe1856 100644
--- a/src/utils/unrecoverable-request-error.ts
+++ b/src/utils/unrecoverable-request-error.ts
@@ -5,10 +5,9 @@ import { errorMessage } from './error-message.js';
  * item failed.
  *
  * A rejected `target_lang` is the same rejection for every file and every target
- * in the run, so retrying it per batch buys nothing: it just spends another round
- * trip -- and bills the items that do succeed -- to be told the same thing again.
- * Language validation defers to the API on codes the bundled snapshot predates,
- * which is what makes this reachable from a plain typo.
+ * in the run, so retrying it per batch buys nothing but another round trip.
+ * Language validation defers to the API on codes the bundled snapshot does not
+ * list, which is what makes this reachable from a plain typo.
  */
 export function isUnrecoverableRequestError(error: unknown): boolean {
   const message = errorMessage(error).toLowerCase();
diff --git a/tests/e2e/cli-languages.e2e.test.ts b/tests/e2e/cli-languages.e2e.test.ts
index 4d2ec491..473b2e8a 100644
--- a/tests/e2e/cli-languages.e2e.test.ts
+++ b/tests/e2e/cli-languages.e2e.test.ts
@@ -104,9 +104,8 @@ describe('Languages Command E2E', () => {
     });
 
     it('should list the same languages in --format json as in text output', () => {
-      // Both formats read the same bundled snapshot, so answering
-      // {"source":[],"target":[]} while the text output printed 125 was the JSON
-      // path simply not falling back.
+      // Both formats read the same bundled snapshot, so both list the same
+      // languages when there is no API key.
       const result = runCLIWithEnv('languages --format json', { DEEPL_API_KEY: '' });
 
       expect(result.status).toBe(0);
@@ -196,7 +195,7 @@ describe('Languages Command E2E', () => {
 
       // formality is what varies across the languages the mock describes, so it
       // is the per-row annotation; glossary is shared by all of them and is
-      // reported once at the end instead of on every row.
+      // reported once at the end rather than on every row.
       expect(german).toContain('formality');
       expect(english).not.toContain('formality');
       expect(output).toContain('glossary');
diff --git a/tests/unit/glossary-params.test.ts b/tests/unit/glossary-params.test.ts
index c2852b40..12a12acc 100644
--- a/tests/unit/glossary-params.test.ts
+++ b/tests/unit/glossary-params.test.ts
@@ -110,8 +110,8 @@ describe('applyGlossarySourceLang', () => {
   });
 
   it('should fall back to the configured source language', () => {
-    // The request carries source_lang either way, so rejecting on a missing
-    // flag alone broke sessions that had been working from config.
+    // The request carries source_lang either way, so a missing flag is not on
+    // its own a reason to reject.
     const options: { glossary: string[]; from?: string } = { glossary: ['terms'] };
     applyGlossarySourceLang(options, 'EN', example);
     expect(options.from).toBe('en');
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index 6cf30469..6e13e1fc 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -357,8 +357,7 @@ describe('Language Registry', () => {
   describe('Language union', () => {
     /**
      * Compile-time, not runtime: these assignments fail to build if the union
-     * goes back to being hand-written and falls behind the snapshot again, which
-     * is exactly how de-ch, de-de, fr-ca and fr-fr came to be missing from it.
+     * stops deriving from the snapshot and falls behind it.
      */
     it('should cover the regional variants a hand-written union had missed', () => {
       const codes: Language[] = ['de-ch', 'de-de', 'fr-ca', 'fr-fr'];
diff --git a/tests/unit/register-write.test.ts b/tests/unit/register-write.test.ts
index f8fbccaf..7b92a7c2 100644
--- a/tests/unit/register-write.test.ts
+++ b/tests/unit/register-write.test.ts
@@ -197,9 +197,8 @@ describe('registerWrite', () => {
     });
 
     it('should defer a well-formed code the bundled list does not have', async () => {
-      // The bundled list is a snapshot and nothing in CI regenerates it, so
-      // rejecting outright made a language DeepL had added unreachable. The
-      // request goes through with a warning that still names the bundled set.
+      // The bundled list is a snapshot, so a well-formed code it does not list
+      // goes through with a warning that still names the bundled set.
       await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'xx']);
 
       expect(handleError).not.toHaveBeenCalled();
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index 7288d64a..bb62fd7f 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -114,8 +114,8 @@ describe('translate-utils', () => {
     });
 
     it('should pass through a well-formed code the snapshot does not know', () => {
-      // The API is the authority on which languages exist, and the bundled
-      // snapshot can lag it. Rejecting locally made valid targets unusable.
+      // The API is the authority on which languages exist and the bundled
+      // snapshot can lag it, so a well-formed code is the API's to judge.
       expect(() => validateLanguageCodes(['xx'])).not.toThrow();
       expect(() => validateLanguageCodes(['de-ch', 'fr-ca'])).not.toThrow();
       expect(() => validateLanguageCodes(['abc-1234'])).not.toThrow();
@@ -125,8 +125,8 @@ describe('translate-utils', () => {
       mockedLoggerWarn.mockClear();
       validateLanguageCodes(['ex']);
 
-      // Said before anything is sent: the API answers a typo with a bare
-      // "target_lang not supported" that points nowhere.
+      // Said before anything is sent, since the API answers an unknown code with
+      // a bare "target_lang not supported" that points nowhere.
       const warning = mockedLoggerWarn.mock.calls.map(call => String(call[0])).join('\n');
       expect(warning).toContain('"ex" is not in the bundled language list');
       expect(warning).toContain('deepl languages');
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index 52f5cedc..9fad3ab8 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -505,7 +505,7 @@ describe('TranslationClient', () => {
 
       // Formality support is left unstated rather than denied: a response that
       // described no features is not evidence that formality is unavailable, and
-      // claiming false turned on the [F] legend with no [F] to explain.
+      // claiming false would turn on the [F] legend with no [F] to explain.
       expect(result[0]).not.toHaveProperty('features');
       expect(result[0]!.supportsFormality).toBeUndefined();
     });
diff --git a/tests/unit/voice-stream-session.test.ts b/tests/unit/voice-stream-session.test.ts
index 1e4b9cd4..a3bb4f61 100644
--- a/tests/unit/voice-stream-session.test.ts
+++ b/tests/unit/voice-stream-session.test.ts
@@ -798,9 +798,8 @@ describe('VoiceStreamSession', () => {
     });
 
     it('should match the echoed language regardless of casing', async () => {
-      // The requested set spells variants zh-HANS and en-GB; a server echoing
-      // another canonicalization used to have its translation dropped on the
-      // floor and then reported as missing.
+      // The requested set spells variants zh-HANS and en-GB, so a server echoing
+      // another canonicalization must still match its requested target.
       const result = await runWithFrames(
         (callbacks) => {
           callbacks.onSourceTranscript?.({

From 469f8beb2a172be69bf3468e70b95ba2e3302dee Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 18:30:44 -0400
Subject: [PATCH 045/256] fix(package)!: give the ESM entry point resolvable
 specifiers

`import '@deepl/cli'` failed with ERR_UNSUPPORTED_DIR_IMPORT: the package is
`type: module`, but src/index.ts re-exported the directory './types' and
src/types/config.ts imported './common' without an extension. Node resolves
neither, so the programmatic API could not be loaded at all, and `nodenext`
consumers saw no exported types -- `import type { Language }` was an error
whatever the union held.

The CLI itself was unaffected, which is why nothing caught it: `bin` points at
dist/cli/index.js, whose module graph uses full specifiers throughout.

The manifest suite now imports the built entry in a real Node ESM process (jest's
CJS transform cannot) and fails on any extensionless relative specifier in the
emitted entry chain. Verified by reverting the fix: 3 of the new assertions fail.
---
 CHANGELOG.md                        |  2 +
 src/index.ts                        |  2 +-
 src/types/config.ts                 |  2 +-
 tests/unit/package-manifest.test.ts | 60 +++++++++++++++++++++++++++++
 4 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 96cc0824..0b6f052e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -83,6 +83,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **package**: **`import '@deepl/cli'` threw instead of loading.** The package is ESM, so Node requires a full specifier for every relative import, but the entry point re-exported `'./types'` — a directory — which fails with `ERR_UNSUPPORTED_DIR_IMPORT`. The whole programmatic surface was therefore unreachable, and the published typings resolved to nothing for a `nodenext` consumer, so `import type { Language } from '@deepl/cli'` was an error regardless of what the union contained. `deepl --help` never exercised this, because the `bin` entry has its own module graph. Both remaining directory specifiers now carry `/index.js`, and the manifest suite imports the built entry in a real Node ESM process and rejects any extensionless relative specifier in the emitted entry chain.
+
 - **cache**: **The translation cache keyed on too little and could serve the wrong text.** `translationMemoryId`, `translationMemoryThreshold`, `--ignore-tags`, `--splitting-tags`, `--non-splitting-tags`, `--outline-detection` and `--preserve-formatting` were absent from the key, so `deepl translate "Hello" --to de` and the same command with `--translation-memory my-tm` collided: the second returned the cached non-TM translation, never consulted the memory, and reported `cached: true`. Likewise two runs differing only in `--ignore-tags` returned each other's output. `preserveFormatting` had been excluded on the grounds that it does not affect output, but `preserve_formatting` suppresses the sentence-boundary punctuation and case correction, which shows up in the text. **Entries cached by earlier versions for requests using any of these options now miss rather than being served wrongly**, so the first such translation after upgrading is refetched.
 
 - **translate**: **A rejected language no longer costs one API round trip per batch.** Because validation defers well-formed unknown codes to the API, a two-letter typo reaches it — and a directory translation asked the same rejected question once per batch, so `deepl translate ./docs --to ex` on 200 files made 200 failing requests to be told the same thing 200 times. An unsupported `target_lang` or `source_lang` is a property of the request, not of one batch, so the remaining batches now fail without being sent; errors specific to a batch (a rate limit, say) still let the run continue. Relatedly, local validation used to be what pointed at `deepl languages`, and deferring left users with a bare `Value for 'target_lang' not supported.` from the server: a code the bundled snapshot does not list now says so up front, before anything is sent or billed.
diff --git a/src/index.ts b/src/index.ts
index 844c81b8..63622f90 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -5,4 +5,4 @@
  * For CLI usage, see src/cli/index.ts
  */
 
-export * from './types';
+export * from './types/index.js';
diff --git a/src/types/config.ts b/src/types/config.ts
index c8c9e0dd..9a009471 100644
--- a/src/types/config.ts
+++ b/src/types/config.ts
@@ -2,7 +2,7 @@
  * Configuration type definitions
  */
 
-import { Language, Formality, OutputFormat } from './common';
+import { Language, Formality, OutputFormat } from './common.js';
 
 export interface DeepLConfig {
   auth: {
diff --git a/tests/unit/package-manifest.test.ts b/tests/unit/package-manifest.test.ts
index 21c43541..f8077b9d 100644
--- a/tests/unit/package-manifest.test.ts
+++ b/tests/unit/package-manifest.test.ts
@@ -6,11 +6,13 @@
  * `npm pack`.
  */
 
+import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 
 interface PackageManifest {
   name: string;
+  main?: string;
   version: string;
   publishConfig?: { access?: string };
   repository: { type: string; url: string };
@@ -115,4 +117,62 @@ describe('package.json manifest', () => {
       expect(pkg.homepage).toBe('https://github.com/DeepL/deepl-cli#readme');
     });
   });
+
+  describe('programmatic entry point', () => {
+    /**
+     * The package is ESM (`type: module`), so Node needs a full specifier for
+     * every relative import it resolves. A directory specifier anywhere on the
+     * path from `main` throws ERR_UNSUPPORTED_DIR_IMPORT on `import '@deepl/cli'`
+     * -- which `deepl --help` never exercises, because the bin has its own entry.
+     */
+    /** Imported in a real Node ESM process; jest's CJS transform cannot load it. */
+    const importEntry = (): { status: number; stdout: string; stderr: string } => {
+      const entry = path.join(__dirname, '..', '..', pkg.main ?? 'dist/index.js');
+      const result = spawnSync(
+        'node',
+        [
+          '--input-type=module',
+          '-e',
+          `const m = await import(${JSON.stringify(entry)});` +
+            'process.stdout.write(Object.keys(m).sort().join(","));',
+        ],
+        { encoding: 'utf-8' },
+      );
+      return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+      };
+    };
+
+    it('should be importable', () => {
+      const result = importEntry();
+
+      expect(result.stderr).not.toMatch(/ERR_UNSUPPORTED_DIR_IMPORT|ERR_MODULE_NOT_FOUND/);
+      expect(result.status).toBe(0);
+    });
+
+    it('should expose the type barrel through the entry point', () => {
+      const exported = importEntry().stdout.split(',');
+
+      expect(exported).toContain('isMultilingual');
+      expect(exported).toContain('normalizeGlossaryInfo');
+    });
+
+    it('should declare no directory specifiers in the emitted entry chain', () => {
+      const distDir = path.join(__dirname, '..', '..', 'dist');
+      const emitted = ['index.js', 'index.d.ts', path.join('types', 'index.js')]
+        .map(file => path.join(distDir, file))
+        .filter(file => fs.existsSync(file));
+
+      expect(emitted.length).toBeGreaterThan(0);
+      for (const file of emitted) {
+        const source = fs.readFileSync(file, 'utf-8');
+        const specifiers = [...source.matchAll(/from\s+'(\.[^']*)'/g)].map(match => match[1]!);
+        for (const specifier of specifiers) {
+          expect(specifier).toMatch(/\.js$/);
+        }
+      }
+    });
+  });
 });

From d5e43f1a5e48374d3e50a907a5116e7be0e59679 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:10:13 -0400
Subject: [PATCH 046/256] fix(scripts)!: validate the API response before
 writing it into TypeScript

The generator interpolated `lang` and `name` from GET /v3/languages straight into
a single-quoted TypeScript literal. `lang` was not escaped at all and `name`
escaped only quotes, so a response field ending in a backslash -- or containing
`' }] as const;` -- could close the literal and append arbitrary code to
src/data/language-entries.ts, which the next build compiles and the test suite
imports. The existing guards check the shape of the response, never the content
of a field.

Codes must now match the language-tag pattern, display names a conservative
letter/mark/digit/punctuation set, and categories one of the three tiers;
everything is quoted with escaping as well. Validation runs before grouping,
because grouping filters by category and would otherwise drop an entry with an
unrecognized one before it was ever checked.

The main guard also compares argv[1] through realpathSync: Node resolves the ESM
entry to its real path, so under a symlinked checkout both npm scripts exited 0
without doing anything -- including the release step that exists to stop the
Write list going stale.
---
 scripts/generate-language-registry.mjs        |  78 ++++++++++--
 tests/unit/generate-language-registry.test.ts | 114 ++++++++++++++++++
 2 files changed, 185 insertions(+), 7 deletions(-)
 create mode 100644 tests/unit/generate-language-registry.test.ts

diff --git a/scripts/generate-language-registry.mjs b/scripts/generate-language-registry.mjs
index 19233669..15596bac 100644
--- a/scripts/generate-language-registry.mjs
+++ b/scripts/generate-language-registry.mjs
@@ -13,7 +13,7 @@
  *
  * Needs DEEPL_API_KEY and a current build (npm run build).
  */
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
 import * as path from 'node:path';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
@@ -41,9 +41,46 @@ function fail(message) {
 
 const byCode = (a, b) => a.code.localeCompare(b.code, 'en');
 
+const LANGUAGE_CODE = /^[a-z]{2,3}(-[a-z0-9]{2,4})?$/;
+/** Letters, marks, digits and the punctuation DeepL's display names actually use. */
+const DISPLAY_NAME = /^[\p{L}\p{M}\p{N} ()'’.,-]{1,60}$/u;
+
+/**
+ * Quote a value as a single-quoted TypeScript string literal, escaping what
+ * would otherwise end the literal or the line.
+ */
+function quote(value) {
+  const escaped = String(value)
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+  return `'${escaped}'`;
+}
+
+/**
+ * Rejects a response field that has no business being in a language list.
+ * The output of this script is TypeScript that the next build compiles and the
+ * test suite imports, so a response field is untrusted input to a code
+ * generator: it is validated, not merely escaped.
+ */
+export function assertRenderable(entry) {
+  if (typeof entry.code !== 'string' || !LANGUAGE_CODE.test(entry.code)) {
+    throw new Error(`refusing to write language code ${JSON.stringify(entry.code)}: not shaped like a language tag`);
+  }
+  if (typeof entry.name !== 'string' || !DISPLAY_NAME.test(entry.name)) {
+    throw new Error(`refusing to write display name ${JSON.stringify(entry.name)} for ${entry.code}`);
+  }
+  if (!['core', 'regional', 'extended'].includes(entry.category)) {
+    throw new Error(`unexpected category ${JSON.stringify(entry.category)} for ${entry.code}`);
+  }
+}
+
 function renderEntry(entry) {
-  const fields = [`code: '${entry.code}'`, `name: '${entry.name.replace(/'/g, "\\'")}'`];
-  fields.push(`category: '${entry.category}'`);
+  const fields = [`code: ${quote(entry.code)}`, `name: ${quote(entry.name)}`];
+  fields.push(`category: ${quote(entry.category)}`);
   if (entry.targetOnly) fields.push('targetOnly: true');
   return `  { ${fields.join(', ')} },`;
 }
@@ -53,6 +90,10 @@ function renderEntry(entry) {
  * the data it already holds, without a live API call.
  */
 export function renderRegistry(entries, writeTargets) {
+  // Validated before grouping: grouping filters by category, so an entry with an
+  // unrecognized one would be dropped from the output without ever being checked.
+  entries.forEach(assertRenderable);
+
   const body = GROUPS.map(([category, heading]) => {
     const group = entries.filter(e => e.category === category).sort(byCode);
     return [`  // ${heading}`, ...group.map(renderEntry)].join('\n');
@@ -92,7 +133,7 @@ ${body}
  * derived from it, so a language added upstream widens the type on regenerate.
  */
 export const WRITE_TARGET_LANGUAGES = [
-${writeTargets.map(code => `  '${code}',`).join('\n')}
+${writeTargets.map(code => `  ${quote(code)},`).join('\n')}
 ] as const;
 `;
 }
@@ -162,8 +203,18 @@ async function main() {
   if (writeTargets.length === 0) {
     fail('no write target languages reported (expected usable_as_target on resource=write)');
   }
+  for (const code of writeTargets) {
+    if (!LANGUAGE_CODE.test(code)) {
+      fail(`refusing to write Write language code ${JSON.stringify(code)}: not shaped like a language tag`);
+    }
+  }
 
-  const contents = renderRegistry(entries, writeTargets);
+  let contents;
+  try {
+    contents = renderRegistry(entries, writeTargets);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
 
   if (checkOnly) {
     const current = existsSync(TARGET) ? readFileSync(TARGET, 'utf8') : '';
@@ -208,7 +259,20 @@ async function main() {
 }
 
 // Importable for re-rendering without touching the network; only the CLI entry
-// point fetches.
-if (process.argv[1] === import.meta.filename) {
+// point fetches. argv[1] is compared through realpathSync because Node resolves
+// the ESM entry to its real path, so a symlinked checkout (or an npm-linked
+// package) would otherwise make both npm scripts silent no-ops.
+const invokedPath = process.argv[1];
+const invokedDirectly =
+  invokedPath !== undefined &&
+  (() => {
+    try {
+      return realpathSync(invokedPath) === import.meta.filename;
+    } catch {
+      return invokedPath === import.meta.filename;
+    }
+  })();
+
+if (invokedDirectly) {
   await main();
 }
diff --git a/tests/unit/generate-language-registry.test.ts b/tests/unit/generate-language-registry.test.ts
new file mode 100644
index 00000000..923f009e
--- /dev/null
+++ b/tests/unit/generate-language-registry.test.ts
@@ -0,0 +1,114 @@
+/**
+ * Tests for the language-snapshot generator's rendering contract.
+ *
+ * The script's output is TypeScript that the next build compiles and the test
+ * suite imports, so `GET /v3/languages` is untrusted input to a code generator.
+ *
+ * Exercised in a spawned Node process: the script is ESM and jest's CJS
+ * transform cannot load it.
+ */
+
+import { spawnSync } from 'child_process';
+import * as path from 'path';
+
+const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'generate-language-registry.mjs');
+
+/** Renders `entries`/`writeTargets` and reports either the output or the rejection. */
+function render(
+  entries: Array<Record<string, unknown>>,
+  writeTargets: string[] = ['de'],
+): { ok: boolean; output: string } {
+  const source = `
+    const gen = await import(${JSON.stringify(SCRIPT)});
+    try {
+      const out = gen.renderRegistry(${JSON.stringify(entries)}, ${JSON.stringify(writeTargets)});
+      process.stdout.write('OK\\n' + out);
+    } catch (error) {
+      process.stdout.write('ERR\\n' + error.message);
+    }
+  `;
+  const result = spawnSync('node', ['--input-type=module', '-e', source], { encoding: 'utf-8' });
+  const stdout = result.stdout ?? '';
+  return { ok: stdout.startsWith('OK'), output: stdout.slice(stdout.indexOf('\n') + 1) };
+}
+
+describe('generate-language-registry', () => {
+  describe('benign responses', () => {
+    it('should render an entry as a single-quoted literal', () => {
+      const { ok, output } = render([{ code: 'de', name: 'German', category: 'core' }]);
+
+      expect(ok).toBe(true);
+      expect(output).toContain("{ code: 'de', name: 'German', category: 'core' },");
+      expect(output).toContain("  'de',");
+    });
+
+    it('should mark a target-only entry', () => {
+      const { ok, output } = render(
+        [{ code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true }],
+        ['en-gb'],
+      );
+
+      expect(ok).toBe(true);
+      expect(output).toContain('targetOnly: true');
+    });
+
+    it('should accept the punctuation real display names use', () => {
+      for (const name of ['Norwegian (bokmål)', 'Kurdish (Sorani)', 'Chinese (simplified)']) {
+        expect(render([{ code: 'nb', name, category: 'core' }]).ok).toBe(true);
+      }
+    });
+  });
+
+  describe('hostile responses', () => {
+    it('should reject a language code that could terminate the literal', () => {
+      const { ok, output } = render([
+        {
+          code: "x' }] as const; eval('boom'); const z = [{ code: 'y",
+          name: 'X',
+          category: 'core',
+        },
+      ]);
+
+      expect(ok).toBe(false);
+      expect(output).toMatch(/not shaped like a language tag/);
+    });
+
+    it('should reject a display name carrying a quote or comment marker', () => {
+      const { ok, output } = render([{ code: 'de', name: "Ger'; eval('x'); //", category: 'core' }]);
+
+      expect(ok).toBe(false);
+      expect(output).toMatch(/refusing to write display name/);
+    });
+
+    it.each([['newline', 'German\nExtra'], ['backslash', 'German\\']])(
+      'should reject a display name containing a %s',
+      (_label, name) => {
+        expect(render([{ code: 'de', name, category: 'core' }]).ok).toBe(false);
+      },
+    );
+
+    it('should reject a category outside the three tiers', () => {
+      const { ok, output } = render([{ code: 'de', name: 'German', category: "core'; eval('x')" }]);
+
+      expect(ok).toBe(false);
+      expect(output).toMatch(/unexpected category/);
+    });
+
+    it('should reject a non-string code or name', () => {
+      expect(render([{ code: 42, name: 'X', category: 'core' }]).ok).toBe(false);
+      expect(render([{ code: 'de', name: 42, category: 'core' }]).ok).toBe(false);
+    });
+
+    it('should reject a Write target that is not a language tag', () => {
+      const { ok } = render([{ code: 'de', name: 'German', category: 'core' }], [
+        "de' ], evil = [",
+      ]);
+
+      // The Write list is validated in main(); rendering it quotes the value so
+      // it cannot escape the literal even when reached directly.
+      expect(ok).toBe(true);
+      expect(render([{ code: 'de', name: 'German', category: 'core' }], ["de' ], evil = ["]).output)
+        .toContain("'de\\' ], evil = ['");
+    });
+  });
+});

From 559a89a127c1b5202414360cc705507daa3f602a Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:10:29 -0400
Subject: [PATCH 047/256] fix(cache): retire the translation entries the new
 key derivation orphans

Adding preserveFormatting to the cache key changes every translation key, not
only the keys of requests using the newly-hashed parameters: the service merges
`defaults.preserveFormatting`, which defaults to true, so the field is always
materialized. The design note and the CHANGELOG both claimed otherwise.

Rather than walk the correctness fix back, the schema version is bumped so those
rows are dropped on first open instead of lingering unreachable until their
30-day TTL, counting towards the size budget and `cache stats` in the meantime.
The purge is scoped to the `translation:` namespace -- write and correct entries
key the same way they always did and are still read in place, as the v2 notes
promise.
---
 src/services/translation.ts      |  8 +++++---
 src/storage/cache.ts             | 17 ++++++++++++----
 tests/unit/cache-service.test.ts | 35 +++++++++++++++++++++++++-------
 3 files changed, 46 insertions(+), 14 deletions(-)

diff --git a/src/services/translation.ts b/src/services/translation.ts
index 1c6448eb..e8edbd87 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -393,9 +393,11 @@ export class TranslationService {
    * intentional — the API receives the un-normalized bytes, so the cache keys
    * on exactly what is sent.
    *
-   * New fields are appended after the existing ones so that keys for requests
-   * not using them stay unchanged. `glossaryIds` is hashed in the caller's
-   * order rather than sorted, because reordering the list changes which
+   * New fields are appended after the existing ones, so a field left `undefined`
+   * does not perturb the key -- `JSON.stringify` omits it. `preserveFormatting`
+   * is the exception: the service merges a config default for it, so it is always
+   * materialized and every key reflects it. `glossaryIds` is hashed in the
+   * caller's order rather than sorted, because reordering the list changes which
    * glossary wins a conflicting term and therefore the translation itself.
    *
    * `tagHandlingVersion` is resolved rather than read straight off the options,
diff --git a/src/storage/cache.ts b/src/storage/cache.ts
index dd6ef871..72894162 100644
--- a/src/storage/cache.ts
+++ b/src/storage/cache.ts
@@ -66,11 +66,13 @@ function isCorruptionError(error: unknown): boolean {
  * Current on-disk schema version for the SQLite cache. Stamped into
  * `PRAGMA user_version` on fresh DBs and checked on every open. Bumping
  * this number means "future callers will read a DB laid out differently."
- * Pre-versioned databases (created before this field existed) report
- * `user_version = 0` and are upgrade-stamped in place without data
- * migration — the schema is backward-compatible.
+ *
+ * Version 2 marks a change in how translation cache keys are computed. Opening
+ * an older DB drops the `translation:` rows -- no reader can reach them again --
+ * and leaves every other namespace in place, since their keys are unchanged. The
+ * table layout is identical in all versions, so nothing is migrated.
  */
-const CACHE_SCHEMA_VERSION = 1;
+const CACHE_SCHEMA_VERSION = 2;
 
 export class CacheService {
   private static instance: CacheService | null = null;
@@ -243,6 +245,13 @@ export class CacheService {
     `);
 
     if (userVersion < CACHE_SCHEMA_VERSION) {
+      // Only the translation namespace: its key derivation changed, so those rows
+      // address entries no reader can reach again, and leaving them would let
+      // them occupy the size budget and `cache stats` until their TTL expires.
+      // Every other namespace (write, correct) keys the same way it always did
+      // and is read in place. A fresh DB has no rows, so this is a no-op on
+      // first open.
+      this.db.exec("DELETE FROM cache WHERE key LIKE 'translation:%'");
       this.db.exec(`PRAGMA user_version = ${CACHE_SCHEMA_VERSION}`);
     }
   }
diff --git a/tests/unit/cache-service.test.ts b/tests/unit/cache-service.test.ts
index cd63d4fd..015b48b7 100644
--- a/tests/unit/cache-service.test.ts
+++ b/tests/unit/cache-service.test.ts
@@ -76,16 +76,16 @@ describe('CacheService', () => {
       expect(result).toEqual({ journal_mode: 'wal' });
     });
 
-    it('should stamp user_version = 1 on a fresh database', () => {
+    it('should stamp the current schema version on a fresh database', () => {
       const db = (cacheService as any).db;
-      const result = db.prepare('PRAGMA user_version').get();
-      expect(result).toEqual({ user_version: 1 });
+      const result = db.prepare('PRAGMA user_version').get() as { user_version: number };
+      expect(result.user_version).toBe(2);
     });
 
     it('should upgrade-stamp a pre-versioned (user_version=0) database in place', () => {
-      // Simulate a DB created before schema versioning: stamp 0, close,
-      // reopen via a new CacheService, verify it got stamped to 1 and
-      // existing data survived.
+      // Simulate a DB created before schema versioning: stamp 0, close, reopen
+      // via a new CacheService, verify it got stamped and non-translation data
+      // survived.
       const db = (cacheService as any).db;
       db.exec('PRAGMA user_version = 0');
       cacheService.set('preexisting', { text: 'survives' });
@@ -94,13 +94,34 @@ describe('CacheService', () => {
       const reopened = new CacheService({ dbPath: testCachePath });
       try {
         const reopenedDb = (reopened as any).db;
-        expect(reopenedDb.prepare('PRAGMA user_version').get()).toEqual({ user_version: 1 });
+        expect(
+          (reopenedDb.prepare('PRAGMA user_version').get() as { user_version: number })
+            .user_version,
+        ).toBe(2);
         expect(reopened.get('preexisting')).toEqual({ text: 'survives' });
       } finally {
         reopened.close();
       }
     });
 
+    it('should drop only translation rows when upgrading an older database', () => {
+      // Translation keys are derived differently from version 2 on, so those rows
+      // are unreachable; every other namespace keys the same way and is kept.
+      const db = (cacheService as any).db;
+      db.exec('PRAGMA user_version = 1');
+      cacheService.set('translation:oldhash', { text: 'unreachable' });
+      cacheService.set('write:samehash', { text: 'still reachable' });
+      cacheService.close();
+
+      const reopened = new CacheService({ dbPath: testCachePath });
+      try {
+        expect(reopened.get('translation:oldhash')).toBeNull();
+        expect(reopened.get('write:samehash')).toEqual({ text: 'still reachable' });
+      } finally {
+        reopened.close();
+      }
+    });
+
     it('should back up a corrupted database rather than unlinking it', () => {
       // Write a non-SQLite file to the cache path. The constructor's
       // openDatabase catch should rename it aside and recreate.

From a464fd9ec9e61fa1705d9acc3cc8e2fa9a7e9777 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:10:29 -0400
Subject: [PATCH 048/256] fix(translate): extend the doomed-request abort past
 plain-text batches

The short-circuit only covered .txt/.md, the files that were already grouped into
batches. Everything else -- .json, .yaml, .html, .srt, .xliff -- goes through the
per-file path, which still spent one round trip per file to collect the same
rejection, so `translate ./locales --to xx` over 200 JSON files made 200 failing
requests. That path now stops the same way, and the files it never sent are
reported as skipped rather than as failures carrying another batch's error text.

The classifier also gates on the error class before matching the message. A 5xx
interpolates the upstream body into a NetworkError, so a gateway error quoting
`target_lang` would have aborted a run that was otherwise succeeding. A refused
key and an exhausted quota now abort too: they are as identical across items as a
bad language code.
---
 src/services/batch-translation.ts             | 31 ++++++++++++++---
 src/utils/unrecoverable-request-error.ts      | 33 +++++++++++++++----
 tests/unit/services/batch-translation.test.ts | 24 ++++++++++++--
 3 files changed, 75 insertions(+), 13 deletions(-)

diff --git a/src/services/batch-translation.ts b/src/services/batch-translation.ts
index 9f1080e7..554f15a3 100644
--- a/src/services/batch-translation.ts
+++ b/src/services/batch-translation.ts
@@ -144,12 +144,18 @@ export class BatchTranslationService {
       );
       result.successful.push(...batchResult.successful);
       result.failed.push(...batchResult.failed);
-      completed += batchResult.successful.length + batchResult.failed.length;
+      result.skipped.push(...batchResult.skipped);
+      completed +=
+        batchResult.successful.length + batchResult.failed.length + batchResult.skipped.length;
     }
 
     // Per-file translation for structured/other files
     if (perFileFiles.length > 0) {
       const limit = pLimit(this.concurrency);
+      // Same reasoning as the batched path: an unsupported target_lang is a
+      // property of the request, so the files still queued would each spend a
+      // round trip to be told the same thing.
+      let requestRejected: unknown;
 
       const tasks = perFileFiles.map(file =>
         limit(async () => {
@@ -160,6 +166,13 @@ export class BatchTranslationService {
             return;
           }
 
+          if (requestRejected !== undefined) {
+            result.skipped.push({ file, reason: errorMessage(requestRejected) });
+            completed++;
+            batchOptions.onProgress?.({ completed, total: totalFiles, current: file });
+            return;
+          }
+
           try {
             const outputPath = this.generateOutputPath(
               file,
@@ -178,6 +191,9 @@ export class BatchTranslationService {
             completed++;
             batchOptions.onProgress?.({ completed, total: totalFiles, current: file });
           } catch (error) {
+            if (isUnrecoverableRequestError(error)) {
+              requestRejected = error;
+            }
             result.failed.push({
               file,
               error: errorMessage(error),
@@ -207,9 +223,14 @@ export class BatchTranslationService {
     totalFiles: number,
     startCompleted: number,
     onProgress?: (progress: ProgressInfo) => void,
-  ): Promise<{ successful: Array<{ file: string; outputPath: string }>; failed: Array<{ file: string; error: string }> }> {
+  ): Promise<{
+    successful: Array<{ file: string; outputPath: string }>;
+    failed: Array<{ file: string; error: string }>;
+    skipped: Array<{ file: string; reason: string }>;
+  }> {
     const successful: Array<{ file: string; outputPath: string }> = [];
     const failed: Array<{ file: string; error: string }> = [];
+    const skipped: Array<{ file: string; reason: string }> = [];
 
     interface FileEntry {
       file: string;
@@ -235,8 +256,10 @@ export class BatchTranslationService {
       }
 
       if (requestRejected !== undefined) {
+        // Never sent, so reported as skipped rather than as individual failures
+        // carrying another batch's error.
         for (const entry of batch) {
-          failed.push({ file: entry.file, error: errorMessage(requestRejected) });
+          skipped.push({ file: entry.file, reason: errorMessage(requestRejected) });
           completed++;
           onProgress?.({ completed, total: totalFiles, current: entry.file });
         }
@@ -346,7 +369,7 @@ export class BatchTranslationService {
     }
     await flushBatch();
 
-    return { successful, failed };
+    return { successful, failed, skipped };
   }
 
   /**
diff --git a/src/utils/unrecoverable-request-error.ts b/src/utils/unrecoverable-request-error.ts
index cffe1856..7d229f3c 100644
--- a/src/utils/unrecoverable-request-error.ts
+++ b/src/utils/unrecoverable-request-error.ts
@@ -1,5 +1,17 @@
+import { AuthError, QuotaError, ValidationError } from './errors.js';
 import { errorMessage } from './error-message.js';
 
+/**
+ * Rejections that describe the request rather than one item, and so will be
+ * identical for everything still queued.
+ */
+const REJECTED_REQUEST_PATTERNS = [
+  "value for 'target_lang' not supported",
+  "value for 'source_lang' not supported",
+  'target_lang not supported',
+  'source_lang not supported',
+];
+
 /**
  * Whether an error means the request itself is wrong, not that this particular
  * item failed.
@@ -7,14 +19,21 @@ import { errorMessage } from './error-message.js';
  * A rejected `target_lang` is the same rejection for every file and every target
  * in the run, so retrying it per batch buys nothing but another round trip.
  * Language validation defers to the API on codes the bundled snapshot does not
- * list, which is what makes this reachable from a plain typo.
+ * list, which is what makes this reachable from a plain typo. A refused key or
+ * an exhausted quota are the same for every item too.
+ *
+ * The error class is checked before the message: 4xx rejections arrive as
+ * ValidationError, while a 5xx interpolates the upstream body into a
+ * NetworkError -- so a transient gateway error quoting the same phrase must not
+ * abort a run that would otherwise mostly succeed.
  */
 export function isUnrecoverableRequestError(error: unknown): boolean {
+  if (error instanceof AuthError || error instanceof QuotaError) {
+    return true;
+  }
+  if (!(error instanceof ValidationError)) {
+    return false;
+  }
   const message = errorMessage(error).toLowerCase();
-  return (
-    message.includes("value for 'target_lang' not supported") ||
-    message.includes("value for 'source_lang' not supported") ||
-    message.includes('target_lang not supported') ||
-    message.includes('source_lang not supported')
-  );
+  return REJECTED_REQUEST_PATTERNS.some(pattern => message.includes(pattern));
 }
diff --git a/tests/unit/services/batch-translation.test.ts b/tests/unit/services/batch-translation.test.ts
index bd3ebea3..2e7cf0df 100644
--- a/tests/unit/services/batch-translation.test.ts
+++ b/tests/unit/services/batch-translation.test.ts
@@ -11,6 +11,8 @@ import { TranslationService, MAX_TEXT_BYTES } from '../../../src/services/transl
 import pLimit from 'p-limit';
 import fg from 'fast-glob';
 import { createMockFileTranslationService, createMockTranslationService } from '../../helpers/mock-factories';
+import { NetworkError, ValidationError } from '../../../src/utils/errors';
+import { isUnrecoverableRequestError } from '../../../src/utils/unrecoverable-request-error';
 
 // Mock ESM modules
 jest.mock('p-limit');
@@ -511,7 +513,7 @@ describe('BatchTranslationService', () => {
       }
 
       mockTranslationService.translateBatch.mockRejectedValue(
-        new Error("API error: Value for 'target_lang' not supported."),
+        new ValidationError("API error: Value for 'target_lang' not supported."),
       );
 
       const result = await batchServiceWithTranslation.translateFiles(
@@ -523,8 +525,26 @@ describe('BatchTranslationService', () => {
       // The same rejection applies to every batch, so it is asked once rather
       // than once per batch.
       expect(mockTranslationService.translateBatch).toHaveBeenCalledTimes(1);
-      expect(result.failed).toHaveLength(52);
       expect(result.successful).toHaveLength(0);
+      // The first batch genuinely failed; the rest were never sent, so they are
+      // reported as skipped rather than as failures carrying another batch's error.
+      expect(result.failed).toHaveLength(50);
+      expect(result.skipped).toHaveLength(2);
+      expect(result.skipped[0]!.reason).toMatch(/target_lang/);
+    });
+
+    it('should keep going when a 5xx quotes the same phrase as a rejected language', () => {
+      // A gateway error interpolates the upstream body, so the message alone
+      // cannot distinguish it from a genuine rejection.
+      const transient = new NetworkError(
+        "Server error (502): upstream unavailable, value for 'target_lang' not supported by shard",
+      );
+      expect(isUnrecoverableRequestError(transient)).toBe(false);
+      expect(
+        isUnrecoverableRequestError(
+          new ValidationError("API error: Value for 'target_lang' not supported."),
+        ),
+      ).toBe(true);
     });
 
     it('should keep going when a batch fails for a reason specific to it', async () => {

From fa5a6c49558de3c559735fcb0a4d1291b8e52144 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:10:56 -0400
Subject: [PATCH 049/256] fix(voice): keep the salvaged transcripts visible,
 and match casing in the display
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three holes in the partial-result path:

- the salvage went through Logger.warn, which --quiet suppresses, while the TTY
  display was erased regardless -- so `voice … -q` on a TTY wiped the rendered
  transcripts and printed nothing in their place, for audio already billed. It
  goes through Logger.error now, which quiet mode does not touch, and the display
  is only cleared once there is something to print instead
- --format json was ignored, so a consumer capturing stderr got prose
- the live display still keyed target state by the requested spelling, the exact
  defect the session-level fix addressed: with `--to zh-HANS`, a `zh-Hans` echo
  left the row blank for the whole session

Also corrects the voice `--glossary` row in docs/API.md, which had picked up
translate's semantics: voice takes a single glossary, is not repeatable, and has
no --from requirement.
---
 docs/API.md               |  2 +-
 src/cli/commands/voice.ts | 43 +++++++++++++++++++++++++++++----------
 2 files changed, 33 insertions(+), 12 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index 78a80023..078dabff 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1005,7 +1005,7 @@ deepl voice [options] <file>
 | `--to <languages>`              | `-t`  | Target language(s), comma-separated, max 5 (required)                                          | -         |
 | `--from <language>`             | `-f`  | Source language (auto-detect if not specified)                                                 | auto      |
 | `--formality <level>`           |       | Formality level: `default`, `formal`, `more`, `informal`, `less`, `prefer_more`, `prefer_less` | `default` |
-| `--glossary <name-or-id>`       |       | Use glossary by name or ID (requires `--from`; repeatable, max 5, last wins on conflicts)       | -         |
+| `--glossary <name-or-id>`       |       | Use glossary by name or ID (single glossary; not repeatable)                                    | -         |
 | `--content-type <type>`         |       | Audio content type (auto-detected from file extension)                                         | auto      |
 | `--chunk-size <bytes>`          |       | Audio chunk size in bytes                                                                      | `6400`    |
 | `--chunk-interval <ms>`         |       | Interval between audio chunks in milliseconds                                                  | `200`     |
diff --git a/src/cli/commands/voice.ts b/src/cli/commands/voice.ts
index 75b54f72..a62566d5 100644
--- a/src/cli/commands/voice.ts
+++ b/src/cli/commands/voice.ts
@@ -86,7 +86,12 @@ export class VoiceCommand {
 
       return this.formatResult(result, options.format);
     } catch (error) {
-      this.reportPartialResult(error, translateOptions.targetLangs.length, isTTY);
+      this.reportPartialResult(
+        error,
+        translateOptions.targetLangs.length,
+        isTTY,
+        options.format,
+      );
       throw error;
     } finally {
       process.removeListener('SIGINT', sigintHandler);
@@ -114,7 +119,12 @@ export class VoiceCommand {
 
       return this.formatResult(result, options.format);
     } catch (error) {
-      this.reportPartialResult(error, translateOptions.targetLangs.length, isTTY);
+      this.reportPartialResult(
+        error,
+        translateOptions.targetLangs.length,
+        isTTY,
+        options.format,
+      );
       throw error;
     } finally {
       process.removeListener('SIGINT', sigintHandler);
@@ -170,10 +180,12 @@ export class VoiceCommand {
   private createTTYCallbacks(targetLangs: VoiceTargetLanguage[], maxReconnectAttempts?: number): VoiceStreamCallbacks {
     const state: Record<string, { concluded: string; tentative: string }> = {};
 
-    // Initialize state for source + each target
+    // Initialize state for source + each target. Keyed lowercase for the same
+    // reason the session is: the server may echo a different canonicalization of
+    // a requested code, and an update matching no key renders nothing.
     state['source'] = { concluded: '', tentative: '' };
     for (const lang of targetLangs) {
-      state[lang] = { concluded: '', tentative: '' };
+      state[lang.toLowerCase()] = { concluded: '', tentative: '' };
     }
 
     const lineCount = 1 + targetLangs.length; // source + targets
@@ -232,7 +244,7 @@ export class VoiceCommand {
         scheduleRender();
       },
       onTargetTranscript: (update) => {
-        const tgt = state[update.language];
+        const tgt = state[update.language.toLowerCase()];
         if (!tgt) return;
         const concludedText = update.concluded.map((s) => s.text).join(' ');
         if (concludedText) {
@@ -266,18 +278,27 @@ export class VoiceCommand {
    * cost another stream to see them. Written to stderr, so a partial result is
    * never mistaken for the command's output.
    */
-  private reportPartialResult(error: unknown, targetCount: number, isTTY: boolean): void {
+  private reportPartialResult(
+    error: unknown,
+    targetCount: number,
+    isTTY: boolean,
+    format?: string,
+  ): void {
     if (!(error instanceof VoicePartialResultError)) {
       return;
     }
+    const salvaged = this.formatResult(error.result, format);
+    if (salvaged.trim() === '') {
+      return;
+    }
     if (isTTY) {
       this.clearTTYDisplay(targetCount);
     }
-    const salvaged = this.formatResult(error.result);
-    if (salvaged.trim() !== '') {
-      Logger.warn(chalk.yellow('Partial result before the session failed:'));
-      Logger.warn(salvaged);
-    }
+    // Logger.error, not warn: warnings are suppressed under --quiet, and erasing
+    // the live display without reprinting would leave the user with nothing for
+    // audio that has already been transcribed and billed.
+    Logger.error(chalk.yellow('Partial result before the session failed:'));
+    Logger.error(salvaged);
   }
 
   private formatResult(result: VoiceSessionResult, format?: string): string {

From 2fe564c5ac1e2578220c46006a54b1082808b51b Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:10:56 -0400
Subject: [PATCH 050/256] fix(languages): stop --features contradicting its own
 footer

A language the response described but which supports none of the discriminating
features rendered as `none`, two lines above a footer crediting it with the
features every described language shares. Only a language credited with nothing
at all now reads `none`; the rest defer to the footer.

Two more display defects with it: `--features` disabled the Formality column
without always replacing it, so the flag could show strictly less than the plain
listing, and the `?` cell for an undescribed language had no legend even though
the text mode and the `[F]` marker both explain themselves. The `[F]` legend also
keyed on `supportsFormality !== undefined`, so a language whose features were
described without formality turned the legend on with nothing under it.
---
 src/cli/commands/languages.ts        | 26 +++++++++++++++++++++-----
 tests/unit/languages-command.test.ts | 17 ++++++++++++++++-
 2 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/src/cli/commands/languages.ts b/src/cli/commands/languages.ts
index 7cab4644..a283540a 100644
--- a/src/cli/commands/languages.ts
+++ b/src/cli/commands/languages.ts
@@ -146,7 +146,11 @@ function featureList(entry: LanguageDisplayEntry, keys: string[]): string {
       const label = featureLabel(key).toLowerCase();
       return cell === 'yes' ? label : `${label} (${cell})`;
     });
-  return supported.length > 0 ? supported.join(', ') : 'none';
+  if (supported.length > 0) return supported.join(', ');
+  // Supports none of the columns, but the footer may still be crediting it with
+  // the features every described language shares; "none" would contradict that.
+  // Only a language supporting nothing at all is reported as supporting nothing.
+  return Object.keys(entry.features ?? {}).length === 0 ? 'none' : '';
 }
 
 /**
@@ -284,9 +288,11 @@ export class LanguagesCommand {
     const lines: string[] = [];
     const header = type === 'source' ? 'Source Languages:' : 'Target Languages:';
     const renderFeatures = showFeatures && hasAnyFeatures(entries);
-    // Formality is one of the feature columns, so the [F] shorthand would say it twice.
+    // Formality is one of the feature columns, so the [F] shorthand would say it
+    // twice. `=== true` because a language the response did not describe carries
+    // no answer, and a legend with no [F] beneath it reads as "none support it".
     const showFormality =
-      !renderFeatures && type === 'target' && entries.some(e => e.supportsFormality !== undefined);
+      !renderFeatures && type === 'target' && entries.some(e => e.supportsFormality === true);
 
     lines.push(chalk.bold(header));
 
@@ -376,8 +382,13 @@ export class LanguagesCommand {
     const { columns, uniform } = renderFeatures
       ? partitionFeatureKeys(entries)
       : { columns: [], uniform: [] };
+    // Formality is one of the feature columns, so the dedicated column would say
+    // it twice -- unless no feature discriminates, in which case dropping it
+    // would make --features show strictly less than the plain listing.
     const showFormality =
-      !renderFeatures && type === 'target' && entries.some(e => e.supportsFormality !== undefined);
+      (!renderFeatures || columns.length === 0) &&
+      type === 'target' &&
+      entries.some(e => e.supportsFormality === true);
 
     const head = ['Code', 'Name', 'Category'];
     const colWidths = [10, renderFeatures ? 24 : showFormality ? 30 : 36, 12];
@@ -409,8 +420,13 @@ export class LanguagesCommand {
       table.push(row);
     }
 
+    const notes: string[] = [];
+    if (renderFeatures && columns.length > 0 && entries.some(e => !hasFeatureData(e))) {
+      notes.push(`${UNKNOWN_CELL} = the API response did not describe this language`);
+    }
     const note = renderFeatures ? uniformNote(uniform, entries) : undefined;
-    return `${header}:\n${table.toString()}${note ? `\n${note}` : ''}`;
+    if (note) notes.push(note);
+    return `${header}:\n${table.toString()}${notes.length > 0 ? `\n${notes.join('\n')}` : ''}`;
   }
 
   /** Format both source and target language tables joined by a blank line. */
diff --git a/tests/unit/languages-command.test.ts b/tests/unit/languages-command.test.ts
index e3115584..de2eb358 100644
--- a/tests/unit/languages-command.test.ts
+++ b/tests/unit/languages-command.test.ts
@@ -584,10 +584,25 @@ describe('LanguagesCommand', () => {
       expect(formatted).toContain('All listed languages also support: tag handling.');
     });
 
-    it('should mark a language with no supported features', () => {
+    it('should not claim a language supports nothing when the footer credits it', () => {
       const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
       const hi = formatted.split('\n').find(l => l.includes('Hindi'));
 
+      // Hindi supports none of the discriminating columns but does support the
+      // uniform one, which the footer reports -- "none" would contradict it.
+      expect(hi).not.toContain('none');
+      expect(formatted).toContain('All listed languages also support: tag handling.');
+    });
+
+    it('should mark a language the response credits with no features at all', () => {
+      const entries: LanguageDisplayEntry[] = [
+        { code: 'de', name: 'German', category: 'core', features: { glossary: { status: 'stable' } } },
+        { code: 'hi', name: 'Hindi', category: 'extended', features: {} },
+      ];
+
+      const formatted = languagesCommand.formatDisplayEntries(entries, 'target', true);
+      const hi = formatted.split('\n').find(l => l.includes('Hindi'));
+
       expect(hi).toContain('none');
     });
 

From fa721dd3b94d48fb8430a41d18f2164413334966 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:11:22 -0400
Subject: [PATCH 051/256] fix: five defects the second review pass turned up

- **glossary**: deduplication kept a repeat's first position, which inverted the
  documented last-wins precedence -- `--glossary base --glossary override
  --glossary base` handed conflicts to `override` although the user put `base`
  last. A repeat now keeps its last position.
- **sync**: the new startup coverage check required the top-level glossary to
  cover every target locale, including ones with their own
  `locale_overrides.<locale>.glossary`. That glossary never translates those
  locales, so a documented configuration failed before any file was touched.
- **config**: normalization was wired into `set()` only, so a file written or
  edited with uppercase codes kept them, and `TranslationService` merges
  `defaults.sourceLang` verbatim -- `DE` in config and `--from de` keyed two
  cache entries for one request. The load path normalizes too. The
  unknown-code note is also scoped to the write path; shared with the loader it
  fired on every invocation, including `deepl --version`.
- **translate**: document mode warned that `--model-type` and `--tag-handling*`
  would be ignored and then rejected the command over them, because the shared
  validation still saw them. They are dropped after the warning, so the mode
  ignores what it says it ignores.
- **usage**: a duration-billed product could still render a character count as
  hours by scaling it, and a `null` count was reported as a real zero. Character
  counts are read only for `milliseconds` billing, where they carry the duration;
  non-finite values are treated as absent.
---
 .../translate/document-translation-handler.ts |  5 +++
 .../translate/translation-options-factory.ts  | 10 ++++-
 src/cli/commands/usage.ts                     | 41 ++++++++++++-------
 src/storage/config.ts                         | 34 ++++++++++-----
 src/sync/sync-service.ts                      | 17 ++++++--
 tests/unit/usage-command.test.ts              | 38 +++++++++++++++++
 6 files changed, 116 insertions(+), 29 deletions(-)

diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index ae80286b..17209a79 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -24,6 +24,11 @@ export class DocumentTranslationHandler {
 
     const supported = new Set(['from', 'formality', 'glossary', 'outputFormat', 'enableMinification']);
     warnIgnoredOptions('document', options, supported);
+    // Actually ignored, not just announced: leaving them set let shared
+    // validation reject a command over a flag this mode has just said it would
+    // disregard.
+    const { modelType: _model, tagHandling: _tags, tagHandlingVersion: _version, ...rest } = options;
+    options = rest;
 
     validateLanguageCodes([options.to]);
     // Documents accept glossaries, so the extended-tier constraint applies here
diff --git a/src/cli/commands/translate/translation-options-factory.ts b/src/cli/commands/translate/translation-options-factory.ts
index 21958f48..09abfc43 100644
--- a/src/cli/commands/translate/translation-options-factory.ts
+++ b/src/cli/commands/translate/translation-options-factory.ts
@@ -63,12 +63,18 @@ export async function applyGlossarySelection<
   // the same glossary: a duplicate would flip the wire parameter from
   // glossary_id to glossary_ids, key an identical request differently, and
   // spend two of the five slots the API allows.
+  //
+  // A repeat keeps its LAST position, because the last glossary to define a term
+  // is the one the API applies -- dropping the later occurrence would hand the
+  // conflict to a glossary the user had deliberately overridden.
   const ids: string[] = [];
   for (const nameOrId of options.glossary) {
     const id = await resolveGlossaryId(glossaryService, nameOrId, expected);
-    if (!ids.includes(id)) {
-      ids.push(id);
+    const existing = ids.indexOf(id);
+    if (existing !== -1) {
+      ids.splice(existing, 1);
     }
+    ids.push(id);
   }
 
   const [only] = ids;
diff --git a/src/cli/commands/usage.ts b/src/cli/commands/usage.ts
index 53127626..870721b2 100644
--- a/src/cli/commands/usage.ts
+++ b/src/cli/commands/usage.ts
@@ -26,19 +26,28 @@ function isDurationBilled(product: ProductUsage): boolean {
  * response carries one, and the API-key-scoped amount.
  *
  * `accountUsed` stays undefined rather than falling back to the API-key figure:
- * live responses omit `unit_count` for these products, so the fallback printed
- * the key's own usage in the account column and the two were always equal.
+ * live responses omit `unit_count` for these products, so a fallback would print
+ * the key's own usage in the account column and the two would always be equal.
+ *
+ * A `milliseconds`-billed product reports its duration in the character-count
+ * fields, which is why those are read at all -- but only there. Under `minutes`
+ * billing they are character counts, and scaling one by 60,000 invents hours of
+ * usage that never happened.
  */
 function productDurationsMs(product: ProductUsage): {
   accountUsed: number | undefined;
-  apiKeyUsed: number;
+  apiKeyUsed: number | undefined;
 } {
-  const scale = product.billingUnit === 'minutes' ? 60_000 : 1;
-  const account = product.unitCount ?? product.accountUnitCount;
-  const apiKeyUsed = product.apiKeyUnitCount ?? product.apiKeyCharacterCount;
+  const perMinute = product.billingUnit === 'minutes';
+  const scale = perMinute ? 60_000 : 1;
+  const duration = (value: number | null | undefined): number | undefined =>
+    typeof value === 'number' && Number.isFinite(value) ? value * scale : undefined;
+  const accountFallback = perMinute ? undefined : duration(product.characterCount);
+  const apiKeyFallback = perMinute ? undefined : duration(product.apiKeyCharacterCount);
   return {
-    accountUsed: account === undefined ? undefined : account * scale,
-    apiKeyUsed: apiKeyUsed * scale,
+    accountUsed:
+      duration(product.unitCount) ?? duration(product.accountUnitCount) ?? accountFallback,
+    apiKeyUsed: duration(product.apiKeyUnitCount) ?? apiKeyFallback,
   };
 }
 
@@ -123,11 +132,15 @@ export class UsageCommand {
         const name = productDisplayName(product.productType);
         if (isDurationBilled(product)) {
           const { accountUsed, apiKeyUsed } = productDurationsMs(product);
-          lines.push(
-            accountUsed === undefined
-              ? `  ${name}: ${this.formatMilliseconds(apiKeyUsed)} (API key)`
-              : `  ${name}: ${this.formatMilliseconds(accountUsed)} (API key: ${this.formatMilliseconds(apiKeyUsed)})`,
-          );
+          const account = accountUsed === undefined ? undefined : this.formatMilliseconds(accountUsed);
+          const apiKey = apiKeyUsed === undefined ? undefined : this.formatMilliseconds(apiKeyUsed);
+          if (account !== undefined && apiKey !== undefined) {
+            lines.push(`  ${name}: ${account} (API key: ${apiKey})`);
+          } else if (apiKey !== undefined) {
+            lines.push(`  ${name}: ${apiKey} (API key)`);
+          } else {
+            lines.push(`  ${name}: ${account ?? 'not reported'}`);
+          }
         } else if (product.unitCount !== undefined) {
           const apiKeyPart = product.apiKeyUnitCount !== undefined
             ? ` (API key: ${formatNumber(product.apiKeyUnitCount)} units)`
@@ -219,7 +232,7 @@ export class UsageCommand {
           productTable.push([
             name,
             accountUsed === undefined ? '—' : this.formatMilliseconds(accountUsed),
-            this.formatMilliseconds(apiKeyUsed),
+            apiKeyUsed === undefined ? '—' : this.formatMilliseconds(apiKeyUsed),
           ]);
         } else if (product.unitCount !== undefined) {
           const apiKeyVal = product.apiKeyUnitCount !== undefined
diff --git a/src/storage/config.ts b/src/storage/config.ts
index 0f0b0e5b..06ef78d6 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -6,7 +6,7 @@
 import { randomBytes } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { DeepLConfig, Formality, OutputFormat } from '../types/index.js';
+import { DeepLConfig, Formality, Language, OutputFormat } from '../types/index.js';
 import { resolvePaths } from '../utils/paths.js';
 import { isValidLanguage, looksLikeLanguageTag } from '../data/language-registry.js';
 import { ConfigError } from '../utils/errors.js';
@@ -247,17 +247,28 @@ export class ConfigService {
     return ConfigService.getDefaults();
   }
 
+  /**
+   * Validates a config read from disk, and normalizes its language codes in
+   * place. A file written before codes were stored lowercase -- or edited by
+   * hand -- otherwise keeps its casing, and `TranslationService` merges
+   * `defaults.sourceLang` verbatim, so `DE` and an explicit `--from de` would key
+   * two cache entries for one request.
+   */
   private validateLoadedConfig(config: DeepLConfig): void {
     if (config.api?.baseUrl) {
       validateApiUrl(config.api.baseUrl);
     }
     if (config.defaults?.sourceLang) {
       this.validateLanguage(config.defaults.sourceLang, 'defaults.sourceLang');
+      config.defaults.sourceLang = config.defaults.sourceLang.toLowerCase() as Language;
     }
     if (config.defaults?.targetLangs) {
       for (const lang of config.defaults.targetLangs) {
         this.validateLanguage(lang, 'defaults.targetLangs');
       }
+      config.defaults.targetLangs = config.defaults.targetLangs.map(
+        lang => lang.toLowerCase() as Language,
+      );
     }
     if (config.defaults?.formality) {
       this.validateFormality(config.defaults.formality, 'defaults.formality');
@@ -352,8 +363,7 @@ export class ConfigService {
 
     // Validate specific paths
     if (path === 'defaults.sourceLang' && value !== undefined) {
-
-      this.validateLanguage(value as string, path);
+      this.validateLanguage(value as string, path, true);
     }
 
     if (path === 'defaults.targetLangs') {
@@ -361,8 +371,7 @@ export class ConfigService {
         throw new ConfigError('Target languages must be an array');
       }
       for (const lang of value) {
-
-        this.validateLanguage(lang, path);
+        this.validateLanguage(lang, path, true);
       }
     }
 
@@ -399,7 +408,12 @@ export class ConfigService {
    * accepted when they are shaped like a language tag, because GET /v3/languages
    * is the authority on which languages exist and the snapshot can lag it.
    */
-  private validateLanguage(lang: string, key?: string): void {
+  /**
+   * @param announceUnknown - warn when the code is well-formed but absent from
+   *   the bundled snapshot. Only the write path announces: every command loads
+   *   the config, and a note on each invocation is noise, not guidance.
+   */
+  private validateLanguage(lang: string, key?: string, announceUnknown = false): void {
     // Lowercased first: the translate paths lowercase their flags before use, and
     // the tag pattern below is lowercase-only, so `DE` is as valid as `de` here.
     const normalized = typeof lang === 'string' ? lang.toLowerCase() : lang;
@@ -407,10 +421,10 @@ export class ConfigService {
       const context = key ? ` for "${key}"` : '';
       throw new ConfigError(`Invalid language code "${lang}"${context}. Run: deepl languages to see valid codes`);
     }
-    if (!isValidLanguage(normalized)) {
-      // Stored anyway, since the snapshot can lag the API -- but flagged here,
-      // because a typo in config otherwise surfaces on every later command with
-      // nothing pointing back at the value responsible.
+    if (announceUnknown && !isValidLanguage(normalized)) {
+      // Stored anyway, since the snapshot can lag the API -- but flagged as it is
+      // written, because a typo in config otherwise surfaces on every later
+      // command with nothing pointing back at the value responsible.
       const context = key ? ` for "${key}"` : '';
       Logger.warn(
         `Note: "${lang}"${context} is not in the bundled language list; it will be sent to the API as-is.\n` +
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index 088d223a..3a15a861 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -194,9 +194,20 @@ export class SyncService {
       // The pair is known from the config, so a glossary that does not cover it
       // fails here rather than once per file, as with the translation memory
       // below.
-      const glossaryLocales = options?.localeFilter?.length
-        ? config.target_locales.filter(l => options.localeFilter!.includes(l))
-        : config.target_locales;
+      //
+      // Locales with their own `locale_overrides.<locale>.glossary` are excluded:
+      // the top-level glossary is never asked to translate them, so requiring it
+      // to cover them would reject a configuration that works.
+      const overriddenLocales = new Set(
+        Object.entries(config.translation?.locale_overrides ?? {})
+          .filter(([, override]) => override?.glossary)
+          .map(([locale]) => locale),
+      );
+      const glossaryLocales = (
+        options?.localeFilter?.length
+          ? config.target_locales.filter(l => options.localeFilter!.includes(l))
+          : config.target_locales
+      ).filter(locale => !overriddenLocales.has(locale));
       resolvedGlossaryId = await this.glossaryService.resolveGlossaryId(
         config.translation.glossary,
         { from: config.source_locale as Language, targets: glossaryLocales as Language[] },
diff --git a/tests/unit/usage-command.test.ts b/tests/unit/usage-command.test.ts
index 59887458..9220a0a0 100644
--- a/tests/unit/usage-command.test.ts
+++ b/tests/unit/usage-command.test.ts
@@ -347,6 +347,44 @@ describe('UsageCommand', () => {
       expect(formatted).not.toContain('speech_to_text: 0 characters');
     });
 
+    it('should not render a character count as minutes of usage', () => {
+      const formatted = usageCommand.formatUsage({
+        characterCount: 0,
+        characterLimit: 20000000,
+        products: [
+          {
+            productType: 'speechToText',
+            characterCount: 1000,
+            apiKeyCharacterCount: 1000,
+            billingUnit: 'minutes',
+          },
+        ],
+      });
+
+      // 1000 characters scaled by 60,000 would claim 16h 40m of voice usage.
+      expect(formatted).not.toContain('16h 40m');
+      expect(formatted).toContain('speech_to_text: not reported');
+    });
+
+    it('should ignore a null count rather than reporting it as zero', () => {
+      const formatted = usageCommand.formatUsage({
+        characterCount: 0,
+        characterLimit: 20000000,
+        products: [
+          {
+            productType: 'speechToText',
+            characterCount: 0,
+            apiKeyCharacterCount: 0,
+            accountUnitCount: null as unknown as number,
+            apiKeyUnitCount: 60,
+            billingUnit: 'minutes',
+          },
+        ],
+      });
+
+      expect(formatted).toContain('speech_to_text: 1h 0m 0s (API key)');
+    });
+
     it('should report the account-wide duration when the response carries one', () => {
       const formatted = usageCommand.formatUsage({
         characterCount: 0,

From 35b273b8a4243336e9b0168b7d5f43eee8361d78 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:42:34 -0400
Subject: [PATCH 052/256] fix: report a failed directory run, and accept voice
 codes in any casing

A directory translation where every file failed printed its failure list and
exited 0, so a script or CI job read it as success. Since language validation
defers unknown codes to the API, a plain --to typo takes that path: on 1.x it
exited 6 locally. A run with no successes now exits 1 and a partial failure
exits 12, matching sync.

`voice` also demanded the exact mixed-case spelling of a regional code, so
`--to en-gb` and `--to zh-hans` exited 6 while `--to en-GB` worked -- the
lowercase form being the one `deepl languages` prints and every other command
accepts. Codes are matched case-insensitively and canonicalized to what the
Voice API expects.
---
 .../directory-translation-handler.ts          |  7 +++
 src/cli/commands/voice.ts                     | 48 ++++++++++++++-----
 tests/unit/voice-command.test.ts              | 34 +++++++++++++
 3 files changed, 78 insertions(+), 11 deletions(-)

diff --git a/src/cli/commands/translate/directory-translation-handler.ts b/src/cli/commands/translate/directory-translation-handler.ts
index 70a9d534..c206e8a8 100644
--- a/src/cli/commands/translate/directory-translation-handler.ts
+++ b/src/cli/commands/translate/directory-translation-handler.ts
@@ -2,6 +2,7 @@ import ora from 'ora';
 import { BatchTranslationService } from '../../../services/batch-translation.js';
 import { ValidationError } from '../../../utils/errors.js';
 import { Logger } from '../../../utils/logger.js';
+import { ExitCode } from '../../../utils/exit-codes.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
 import { warnIgnoredOptions, validateLanguageCodes } from './translate-utils.js';
 import { buildBaseTranslationOptions } from './translation-options-factory.js';
@@ -90,6 +91,12 @@ export class DirectoryTranslationHandler {
         result.failed.forEach(f => {
           output.push(`  - ${f.file}: ${f.error}`);
         });
+        // Reported in the exit code as well as the summary: a run where nothing
+        // translated must not look like success to a script or a CI job, and
+        // language validation defers to the API, so a bad --to surfaces here
+        // rather than as a local rejection.
+        process.exitCode =
+          stats.successful === 0 ? ExitCode.GeneralError : ExitCode.PartialFailure;
       }
 
       if (stats.skipped > 0) {
diff --git a/src/cli/commands/voice.ts b/src/cli/commands/voice.ts
index a62566d5..ebb835ea 100644
--- a/src/cli/commands/voice.ts
+++ b/src/cli/commands/voice.ts
@@ -31,6 +31,23 @@ const VALID_VOICE_SOURCE_LANGS: ReadonlySet<string> = new Set<VoiceSourceLanguag
   'ja','ko','lt','lv','nb','nl','pl','pt','ro','ru','sk','sl','sv','tr','uk','zh',
 ]);
 
+/**
+ * Lowercase lookups onto the spellings the Voice API expects (`en-GB`,
+ * `zh-HANS`), so input is accepted in any casing as it is everywhere else.
+ */
+const VOICE_TARGET_BY_LOWERCASE = new Map<string, VoiceTargetLanguage>(
+  Array.from(VALID_VOICE_TARGET_LANGS, lang => [
+    lang.toLowerCase(),
+    lang as VoiceTargetLanguage,
+  ]),
+);
+const VOICE_SOURCE_BY_LOWERCASE = new Map<string, VoiceSourceLanguage>(
+  Array.from(VALID_VOICE_SOURCE_LANGS, lang => [
+    lang.toLowerCase(),
+    lang as VoiceSourceLanguage,
+  ]),
+);
+
 const VALID_VOICE_CONTENT_TYPES: ReadonlySet<string> = new Set<VoiceSourceMediaContentType>([
   'audio/auto',
   'audio/pcm;encoding=s16le;rate=8000','audio/pcm;encoding=s16le;rate=16000',
@@ -132,20 +149,29 @@ export class VoiceCommand {
   }
 
   private buildOptions(options: VoiceCommandOptions): VoiceTranslateOptions {
-    const targetLangs = options.to.split(',').map((l) => l.trim());
-
-    for (const lang of targetLangs) {
-      if (!VALID_VOICE_TARGET_LANGS.has(lang)) {
+    // Matched case-insensitively and canonicalized to the spelling the Voice API
+    // expects. The rest of the CLI accepts any casing and `deepl languages`
+    // prints these codes lowercase, so requiring `zh-HANS` would reject the
+    // spelling the CLI itself teaches.
+    const targetLangs = options.to.split(',').map((l) => {
+      const raw = l.trim();
+      const canonical = VOICE_TARGET_BY_LOWERCASE.get(raw.toLowerCase());
+      if (!canonical) {
         throw new ValidationError(
-          `Invalid voice target language: "${lang}". Valid codes: ${Array.from(VALID_VOICE_TARGET_LANGS).sort().join(', ')}`,
+          `Invalid voice target language: "${raw}". Valid codes: ${Array.from(VALID_VOICE_TARGET_LANGS).sort().join(', ')}`,
         );
       }
-    }
+      return canonical;
+    });
 
-    if (options.from && !VALID_VOICE_SOURCE_LANGS.has(options.from)) {
-      throw new ValidationError(
-        `Invalid voice source language: "${options.from}". Valid codes: ${Array.from(VALID_VOICE_SOURCE_LANGS).sort().join(', ')}`,
-      );
+    if (options.from) {
+      const canonicalSource = VOICE_SOURCE_BY_LOWERCASE.get(options.from.toLowerCase());
+      if (!canonicalSource) {
+        throw new ValidationError(
+          `Invalid voice source language: "${options.from}". Valid codes: ${Array.from(VALID_VOICE_SOURCE_LANGS).sort().join(', ')}`,
+        );
+      }
+      options.from = canonicalSource;
     }
 
     if (options.contentType && !VALID_VOICE_CONTENT_TYPES.has(options.contentType)) {
@@ -164,7 +190,7 @@ export class VoiceCommand {
     }
 
     return {
-      targetLangs: targetLangs as VoiceTargetLanguage[],
+      targetLangs,
       sourceLang: options.from as VoiceSourceLanguage | undefined,
       sourceLanguageMode: options.sourceLanguageMode as VoiceSourceLanguageMode | undefined,
       formality: options.formality as VoiceTranslateOptions['formality'],
diff --git a/tests/unit/voice-command.test.ts b/tests/unit/voice-command.test.ts
index 9a9bc769..fa7d5ba7 100644
--- a/tests/unit/voice-command.test.ts
+++ b/tests/unit/voice-command.test.ts
@@ -1039,4 +1039,38 @@ describe('VoiceCommand', () => {
       expect(result).toBe('[de] Welt\n[fr] Monde');
     });
   });
+  describe('language code casing', () => {
+    it('should accept a regional target in the casing the CLI prints', async () => {
+      // `deepl languages` prints en-gb / zh-hans, and every other command takes
+      // any casing, so requiring en-GB / zh-HANS here would reject the CLI's own
+      // spelling.
+      mockService.translateFile.mockResolvedValue(mockResult);
+
+      for (const code of ['en-gb', 'zh-hans', 'PT-br']) {
+        await expect(command.translate('test.mp3', { to: code })).resolves.toContain('[source]');
+      }
+    });
+
+    it('should canonicalize the code the Voice API receives', async () => {
+      mockService.translateFile.mockResolvedValue(mockResult);
+
+      await command.translate('test.mp3', { to: 'zh-hans,en-gb', from: 'EN' });
+
+      expect(mockService.translateFile).toHaveBeenLastCalledWith(
+        'test.mp3',
+        expect.objectContaining({ targetLangs: ['zh-HANS', 'en-GB'], sourceLang: 'en' }),
+        undefined,
+      );
+    });
+
+    it('should still reject a code that is not a voice language', async () => {
+      await expect(command.translate('test.mp3', { to: 'xx' })).rejects.toThrow(
+        /Invalid voice target language/,
+      );
+      await expect(command.translate('test.mp3', { to: 'de', from: 'xx' })).rejects.toThrow(
+        /Invalid voice source language/,
+      );
+    });
+  });
+
 });

From 586085e163efc5196b073333a81551a8a6f13a4f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:42:34 -0400
Subject: [PATCH 053/256] test: restore the guards the relational counts
 removed

Comparing the registry against the ENTRIES array it is built from proves the
plumbing and nothing about the data: deleting 71 of 125 languages left the
registry suite green. Floors well under today's counts, plus named codes from
every tier, fail on a snapshot that lost most of its languages while still
surviving any plausible upstream change -- which was the point of de-pinning the
literal counts.

Three more assertions that could not fail:

- the batch-abort classifier had no direct test at all; three of its four
  patterns were unverified, and the error-class gate untested
- the tiering heuristic for a language the snapshot does not list was asserted
  nowhere, so a regional variant could silently land in the wrong tier
- two assertions passed on substrings that occur in unrelated words ('de' inside
  "code", 'glossary' inside the extended-languages header)

The shared /v3/languages nock fixture also carried no `features` matrix, so
through the real code every language in it tiered as extended with formality
unreported -- the opposite of what those four languages support.
---
 tests/helpers/nock-setup.ts                   | 48 ++++++++++--
 tests/unit/language-registry.test.ts          | 40 ++++++++--
 tests/unit/languages-command.test.ts          | 41 +++++++++-
 tests/unit/register-write.test.ts             | 10 +--
 .../unit/unrecoverable-request-error.test.ts  | 74 +++++++++++++++++++
 5 files changed, 190 insertions(+), 23 deletions(-)
 create mode 100644 tests/unit/unrecoverable-request-error.test.ts

diff --git a/tests/helpers/nock-setup.ts b/tests/helpers/nock-setup.ts
index 509f2f1b..f235f02d 100644
--- a/tests/helpers/nock-setup.ts
+++ b/tests/helpers/nock-setup.ts
@@ -39,13 +39,51 @@ export function mockAuthError(scope: nock.Scope): nock.Scope {
   return scope.post('/v2/translate').reply(403, { message: 'Invalid API key' });
 }
 
+/**
+ * The default carries a `features` matrix because the live response does: tiers
+ * and formality support are both derived from it, so a fixture without one makes
+ * every language read as extended with formality unreported -- the opposite of
+ * what these four languages actually support.
+ */
+const STABLE = { status: 'stable' } as const;
+
 export function mockLanguagesResponse(
   scope: nock.Scope,
-  languages: Array<{ lang: string; name: string; usable_as_source?: boolean; usable_as_target?: boolean }> = [
-    { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
-    { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
-    { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
-    { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
+  languages: Array<{
+    lang: string;
+    name: string;
+    usable_as_source?: boolean;
+    usable_as_target?: boolean;
+    features?: Record<string, { status: string }>;
+  }> = [
+    {
+      lang: 'de',
+      name: 'German',
+      usable_as_source: true,
+      usable_as_target: true,
+      features: { formality: STABLE, glossary: STABLE, tag_handling: STABLE },
+    },
+    {
+      lang: 'en',
+      name: 'English',
+      usable_as_source: true,
+      usable_as_target: true,
+      features: { glossary: STABLE, tag_handling: STABLE },
+    },
+    {
+      lang: 'es',
+      name: 'Spanish',
+      usable_as_source: true,
+      usable_as_target: true,
+      features: { formality: STABLE, glossary: STABLE, tag_handling: STABLE },
+    },
+    {
+      lang: 'fr',
+      name: 'French',
+      usable_as_source: true,
+      usable_as_target: true,
+      features: { formality: STABLE, glossary: STABLE, tag_handling: STABLE },
+    },
   ],
   resource: string = 'translate_text',
 ): nock.Scope {
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index 6e13e1fc..eec39ee4 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -18,16 +18,47 @@ import type { Language } from '../../src/types/common';
  * regenerating it -- the documented release step -- does not turn this suite red
  * for a change it is supposed to accept. Drift from the API is checked by
  * "npm run check:languages", which is where that belongs.
+ *
+ * Comparing the registry against the array it is built from proves the plumbing
+ * but not the data, so the floors below stand in for the literal counts: they
+ * hold across any plausible upstream change and still fail on a snapshot that
+ * lost most of its languages.
  */
 const TIERS = ['core', 'regional', 'extended'] as const;
 const entriesIn = (category: string) => ENTRIES.filter(e => e.category === category);
 
+/** Floors chosen well under today's 125/32/11/82 and well over an empty file. */
+const MIN_TOTAL = 100;
+const MIN_PER_TIER: Record<(typeof TIERS)[number], number> = {
+  core: 20,
+  regional: 5,
+  extended: 50,
+};
+
 describe('Language Registry', () => {
   describe('LANGUAGE_REGISTRY', () => {
     it('should contain one entry per snapshot language', () => {
       expect(LANGUAGE_REGISTRY.size).toBe(ENTRIES.length);
     });
 
+    it('should hold a plausible number of languages', () => {
+      // Independent of ENTRIES.length, which the assertion above compares against
+      // itself: a snapshot regenerated from a broken response fails here.
+      expect(LANGUAGE_REGISTRY.size).toBeGreaterThanOrEqual(MIN_TOTAL);
+    });
+
+    it.each(TIERS)('should hold a plausible number of %s languages', category => {
+      expect(entriesIn(category).length).toBeGreaterThanOrEqual(MIN_PER_TIER[category]);
+    });
+
+    it('should still contain a representative language from every tier', () => {
+      // Named codes, so losing a whole tier or a common language is caught even
+      // if the totals stay plausible.
+      for (const code of ['en', 'de', 'ja', 'zh', 'en-gb', 'pt-br', 'zh-hans', 'hi', 'sw', 'th']) {
+        expect(LANGUAGE_REGISTRY.has(code)).toBe(true);
+      }
+    });
+
     it('should have unique language codes', () => {
       const codes = Array.from(LANGUAGE_REGISTRY.keys());
       const unique = new Set(codes);
@@ -48,14 +79,7 @@ describe('Language Registry', () => {
       );
     });
 
-    /**
-     * Mirrors the generator's floor: the tiers come from the features matrix, so
-     * a matrix that stopped reporting `glossary` would retier every language as
-     * extended and make --formality and --glossary unusable everywhere.
-     */
-    it('should keep a plausible number of core languages', () => {
-      expect(entriesIn('core').length).toBeGreaterThanOrEqual(20);
-    });
+
 
     it('should mark regional variants as targetOnly', () => {
       const regional = Array.from(LANGUAGE_REGISTRY.values()).filter(e => e.category === 'regional');
diff --git a/tests/unit/languages-command.test.ts b/tests/unit/languages-command.test.ts
index de2eb358..095b3aba 100644
--- a/tests/unit/languages-command.test.ts
+++ b/tests/unit/languages-command.test.ts
@@ -467,6 +467,39 @@ describe('LanguagesCommand', () => {
     });
   });
 
+  describe('tiering a language the snapshot does not list', () => {
+    it('should treat a hyphenated code as a target-only regional variant', () => {
+      // LanguageInfo carries no usable_as_source, so the subtag is the only
+      // signal available; asserted because nothing else pins this guess.
+      const merged = languagesCommand.mergeWithRegistry(
+        [{ language: 'de-ch', name: 'German (Swiss)', features: { glossary: { status: 'stable' } } }],
+        'target',
+      );
+      const entry = merged.find(e => e.code === 'de-ch');
+
+      expect(entry).toBeDefined();
+      expect(entry!.category).toBe('regional');
+    });
+
+    it('should treat a bare code with glossary support as core', () => {
+      const merged = languagesCommand.mergeWithRegistry(
+        [{ language: 'xx' as never, name: 'Novel', features: { glossary: { status: 'stable' } } }],
+        'target',
+      );
+
+      expect(merged.find(e => e.code === 'xx')!.category).toBe('core');
+    });
+
+    it('should treat a code without glossary support as extended', () => {
+      const merged = languagesCommand.mergeWithRegistry(
+        [{ language: 'yy' as never, name: 'Other', features: { tag_handling: { status: 'stable' } } }],
+        'target',
+      );
+
+      expect(merged.find(e => e.code === 'yy')!.category).toBe('extended');
+    });
+  });
+
   describe('partitionFeatureKeys()', () => {
     const entry = (
       code: string,
@@ -667,10 +700,10 @@ describe('LanguagesCommand', () => {
       ];
       const formatted = languagesCommand.formatLanguages(apiLangs, 'target', true);
 
-      // Reported once for the whole listing rather than per row: the languages
-      // the response omitted carry no feature data, so they cannot make glossary
-      // look like a discriminating column.
-      expect(formatted).toContain('glossary');
+      // Asserted on the footer line specifically: the section header for extended
+      // languages also contains the word "glossary", so a bare toContain would
+      // pass even with the flag ignored entirely.
+      expect(formatted).toMatch(/also support:.*glossary/);
     });
 
     it('should report a language the response omitted as unknown, not as supporting nothing', () => {
diff --git a/tests/unit/register-write.test.ts b/tests/unit/register-write.test.ts
index 7b92a7c2..01229654 100644
--- a/tests/unit/register-write.test.ts
+++ b/tests/unit/register-write.test.ts
@@ -205,17 +205,15 @@ describe('registerWrite', () => {
       expect(mockWriteCommand.improve).toHaveBeenCalled();
       const warning = (Logger.warn as jest.Mock).mock.calls.map(c => String(c[0])).join('\n');
       expect(warning).toContain('not in the bundled Write language list');
-      for (const code of WRITE_TARGET_LANGUAGES) {
-        expect(warning).toContain(code);
-      }
+      expect(warning).toContain(WRITE_TARGET_LANGUAGES.join(', '));
     });
 
     it('should enumerate every supported language when rejecting malformed input', async () => {
       await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'nope_nope']);
       const error = handleError.mock.calls[0]?.[0] as Error;
-      for (const code of WRITE_TARGET_LANGUAGES) {
-        expect(error.message).toContain(code);
-      }
+      // Asserted as the joined list: individual codes like 'de' occur inside
+      // ordinary words in the message, so per-code checks cannot fail.
+      expect(error.message).toContain(WRITE_TARGET_LANGUAGES.join(', '));
     });
 
     it('should accept every language in the generated list', async () => {
diff --git a/tests/unit/unrecoverable-request-error.test.ts b/tests/unit/unrecoverable-request-error.test.ts
new file mode 100644
index 00000000..20e1a6a9
--- /dev/null
+++ b/tests/unit/unrecoverable-request-error.test.ts
@@ -0,0 +1,74 @@
+/**
+ * Tests for the classifier that decides whether a run aborts.
+ *
+ * It matches an API error string that carries no compatibility contract, and it
+ * decides whether the remaining files in a batch are sent at all, so every
+ * pattern is pinned rather than left as a guess.
+ */
+
+import { isUnrecoverableRequestError } from '../../src/utils/unrecoverable-request-error';
+import {
+  AuthError,
+  NetworkError,
+  QuotaError,
+  RateLimitError,
+  ValidationError,
+} from '../../src/utils/errors';
+
+describe('isUnrecoverableRequestError', () => {
+  describe('rejections that apply to every item', () => {
+    it.each([
+      "API error: Value for 'target_lang' not supported.",
+      "API error: Value for 'source_lang' not supported.",
+      'API error: target_lang not supported',
+      'API error: source_lang not supported',
+    ])('should match %s', message => {
+      expect(isUnrecoverableRequestError(new ValidationError(message))).toBe(true);
+    });
+
+    it('should match regardless of case', () => {
+      expect(
+        isUnrecoverableRequestError(new ValidationError("VALUE FOR 'TARGET_LANG' NOT SUPPORTED.")),
+      ).toBe(true);
+    });
+
+    it('should treat a refused key and an exhausted quota as request-wide', () => {
+      expect(isUnrecoverableRequestError(new AuthError('Authentication failed'))).toBe(true);
+      expect(isUnrecoverableRequestError(new QuotaError('Quota exceeded'))).toBe(true);
+    });
+  });
+
+  describe('failures specific to one attempt', () => {
+    it('should not match a transient error quoting the same phrase', () => {
+      // 5xx interpolates the upstream body, so the message alone cannot tell a
+      // gateway hiccup from a rejected language.
+      expect(
+        isUnrecoverableRequestError(
+          new NetworkError(
+            "Server error (502): upstream unavailable, value for 'target_lang' not supported by shard",
+          ),
+        ),
+      ).toBe(false);
+    });
+
+    it('should not match a rate limit', () => {
+      expect(isUnrecoverableRequestError(new RateLimitError('Rate limit exceeded'))).toBe(false);
+    });
+
+    it('should not match an unrelated validation error', () => {
+      expect(isUnrecoverableRequestError(new ValidationError('Text cannot be empty'))).toBe(false);
+    });
+
+    it('should not match a plain Error, whatever it says', () => {
+      expect(
+        isUnrecoverableRequestError(new Error("Value for 'target_lang' not supported.")),
+      ).toBe(false);
+    });
+
+    it('should not match a non-error value', () => {
+      for (const value of [undefined, null, 'target_lang not supported', 42]) {
+        expect(isUnrecoverableRequestError(value)).toBe(false);
+      }
+    });
+  });
+});

From 83f54e72828e89f95099647325ce730da6fd9c97 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 3 Aug 2026 19:42:48 -0400
Subject: [PATCH 054/256] docs(changelog): repair the Unreleased structure and
 the claims that were false

The Unreleased section had two `### Changed` and two `### Removed` headings, and
eight entries under the first `### Removed` described features that exist and
work: NO_PROXY support, `auth set-key --no-verify`, `check-deps`, the `t`/`w`
aliases, the GitHub Release workflow, `--timeout`/`--max-retries`, `cached` in
JSON output, and the Node<24 fast-fail. release.yml publishes this section
verbatim as the release notes, so v2 would have announced eight live features as
deleted. Categories are merged, one per release, in Keep a Changelog order.

Three claims corrected rather than left to ship:

- the cache entry scoped invalidation to "requests using any of these options";
  it is every translation entry, because a preserveFormatting default is always
  merged. The schema bump that retires them is described instead
- the tag-handling entry repeated the same scoping
- "Input remains case-insensitive everywhere" was false for `voice`, which
  rejected the lowercase regional codes the CLI itself prints

Also fixes three stale passages in docs/API.md: the `voice --glossary` row had
picked up translate's repeatable/`--from` semantics, the `write` reference still
said an unknown code is rejected locally, and the `usage` reference still
documented the removed Speech-to-Text section with output showing the duplicated
API-key figure.
---
 CHANGELOG.md | 190 +++++++++++++++++++++++++++++++++++++++++++++------
 docs/API.md  |  11 +--
 2 files changed, 173 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b6f052e..3c34936f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,9 +17,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **cli**: `deepl correct` command (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`), but not `--style`/`--tone`, which the correct endpoint does not accept. Results are cached under a separate `correct:` namespace so corrections and rephrasings of the same text never collide.
 
+- **http**: `NO_PROXY` / `no_proxy` are honoured, with the standard semantics — `*` for everything, a leading dot or `*.` for subdomains, and an optional `host:port` that must agree. A corporate `HTTPS_PROXY` was previously applied to every request, including one aimed at localhost.
+
+- **auth**: `deepl auth set-key --no-verify` stores a key without validating it against the API. Validation ran before persisting, so on a network without proxy configuration both documented setup paths — `auth set-key` and `init` — failed and discarded the key; an unreachable API now also names `DEEPL_API_KEY` as the zero-network alternative.
+
+- **ci**: `npm run check-deps` fails the build when a package imported by `src/` is missing from `dependencies`, including one declared only under `devDependencies`. It runs in CI and in the publish job, and matches package names as quoted strings so indirect loads such as `requireModule('php-parser')` count as references.
+
+- **cli**: `t` and `w` command aliases for `translate` and `write` ([#12](https://github.com/DeepL/deepl-cli/issues/12)). The aliases appear in `--help` output and in bash/zsh/fish shell completions. `w` is deliberately assigned to `write` rather than `watch` — write is a primary API feature, watch a workflow helper.
+
+- **ci**: Pushing a `v*` tag now creates a GitHub Release, with notes extracted from that version's CHANGELOG section and generated notes as a fallback when the section is missing. This is why the repo has 17 tags and zero Releases. The workflow does **not** publish to npm: releases are published from GitLab, which is the source of truth and mirrors to GitHub, matching the other DeepL client libraries. The tag is checked against `package.json` first, so a mislabelled tag cannot mint a Release whose title disagrees with the version it contains.
+
+- **cli**: Global `--timeout <ms>` and `--max-retries <n>` options override the HTTP transport defaults (30000 ms, 3 retries) for a single invocation. Neither was previously configurable from the CLI.
+
+- **translate**: `--format json` output now includes the documented `cached` boolean, so scripts can distinguish cache hits from fresh API calls.
+
+- **cli**: Running under Node.js < 24 now fails fast with a clear one-line error (exit 6) instead of surfacing a raw `node:sqlite` ExperimentalWarning or crashing later.
+
 ### Changed
 
-- **translate**: **`--tag-handling` requests now pin `tag_handling_version=v2`** instead of letting the API pick. The CLI previously sent the parameter only when `--tag-handling-version` was passed, so everyone else inherited the server default — which DeepL documents as moving from v1 (deprecation-bound) to v2 at an unannounced date. That flip would have changed tag-handling output with no CLI change to point at, and worse, would have gone unnoticed by the cache: a request that omits the version hashes identically before and after, so cached v1 output would have kept being served after the API started returning v2. Adopting v2 now makes that one output shift deliberate and dated, and DeepL's own docs recommend v2 for structure handling. **`--tag-handling xml`/`html` output may differ from previous releases**; pass `--tag-handling-version v1` to keep the old behaviour, which is still honoured and always wins over the default. Requests without `--tag-handling` send no version and keep their existing cache keys; tag-handling entries cached by earlier versions now miss rather than being served stale, so the first such translation after upgrading is refetched.
+- **translate**: **`--tag-handling` requests now pin `tag_handling_version=v2`** instead of letting the API pick. The CLI previously sent the parameter only when `--tag-handling-version` was passed, so everyone else inherited the server default — which DeepL documents as moving from v1 (deprecation-bound) to v2 at an unannounced date. That flip would have changed tag-handling output with no CLI change to point at, and worse, would have gone unnoticed by the cache: a request that omits the version hashes identically before and after, so cached v1 output would have kept being served after the API started returning v2. Adopting v2 now makes that one output shift deliberate and dated, and DeepL's own docs recommend v2 for structure handling. **`--tag-handling xml`/`html` output may differ from previous releases**; pass `--tag-handling-version v1` to keep the old behaviour, which is still honoured and always wins over the default. Requests without `--tag-handling` send no version. Cached translations from earlier versions are retired on first open regardless — see the cache entry under Fixed — so no tag-handling entry can be served stale.
 
 - **translate**: **A glossary referenced by name is checked against the requested language pair before any translation request.** Previously only translation memories did this; a glossary whose dictionaries did not cover the pair reached the API and came back as `No dictionary found for language pair EN-DE in glossary <uuid>`, naming a UUID the user never typed. It now fails locally, exit 7, naming what the glossary actually covers: `Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.` This costs no extra request, because the glossary list is already fetched to resolve the name. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr is not treated as covering en→fr, and when translating to several targets at once every one of them must be covered. Both sides are compared on their **base** language, because glossary dictionaries only ever name base languages while `--to` accepts regional variants: a de→en glossary covers `--to en-us`, which the API accepts, and demanding an exact match would have made glossaries unusable for every regional target — `en-us`, `en-gb`, `pt-br`, `pt-pt`, `zh-hans`, `es-419`, `fr-ca` — including the ones DeepL steers users towards over bare `en`/`pt`. The check is therefore deliberately permissive at the edges: a pair it lets through is still the API's to reject, which is much the cheaper mistake. Two deliberate exemptions: a glossary passed as a **UUID** is trusted and left to the API, matching how translation-memory resolution already behaves and giving an escape hatch if the check is ever wrong; and a glossary the API reports with no dictionaries is left alone, since that says nothing about coverage.
 
@@ -31,61 +47,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **languages**: **Ten display names changed to match the API**, a consequence of generating the language list rather than hand-writing it: `ckb` Central Kurdish → Kurdish (Sorani), `es-419` Spanish (Latin America) → Spanish (Latin American), `gom` Goan Konkani → Konkani, `kmr` Northern Kurdish → Kurdish (Kurmanji), `my` Myanmar (Burmese) → Burmese, `nb` Norwegian Bokmål → Norwegian (bokmål), `pam` Pampanga → Kapampangan, `st` Southern Sotho → Sesotho, `zh-hans` Chinese (Simplified) → Chinese (simplified), `zh-hant` Chinese (Traditional) → Chinese (traditional). **Only offline output changes**: with an API key configured, `deepl languages` already took names from the API and was therefore already showing these, so this makes the no-API-key output consistent with the keyed output rather than changing what keyed users saw. Language codes are unaffected, so nothing that selects a language by code has to change; only output that scrapes display names.
 
-- **cli**: **Language codes are displayed in lowercase everywhere.** Output previously mixed three casings: `deepl languages` printed lowercase from the registry, `glossary show` and `tm list` uppercased at display time, `translate`'s table uppercased the target language, and `write`/`correct` used BCP-47 (`en-GB`, `zh-Hans`). Lowercase matches the CLI's own normalized form, the registry, what `deepl languages` teaches users to type, and the wire format `/v3/languages` moved to; uppercase followed a v2-era docs convention that v3 abandons. **Scripts scraping these values will see a casing change** — `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"`. Input remains case-insensitive everywhere, so no command line has to change. `write`/`correct` also send the lowercase code as `target_lang`: the Write API accepts any casing and canonicalizes server-side (verified live on `/v2/write/rephrase` and `/v2/write/correct` — `en-gb`, `zh-hans`, and `zh-HANS` all return 200 and echo back `en-GB` / `zh-Hans`). Wire parameters that are not display are untouched: `translate` and the glossary create endpoint still send uppercase `target_lang`/`source_lang` as those endpoints document.
-- **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers come from the per-language `features` matrix, which is what v2's `supports_formality` boolean became (see the Fixed entry on `pt`). A language whose features the response does not describe is left unmarked rather than marked unsupported, so the `[F]` legend cannot appear with no `[F]` beneath it.
-
-### Removed
-
-- **cli**: **BREAKING**: The `--enable-beta-languages` flag on `translate` is gone. The API deprecated the underlying `enable_beta_languages` parameter with "has no effect" — beta languages are simply part of the regular language set now — so the flag had become a silent no-op. Scripts passing it will exit with an unknown-option error; remove the flag.
-- **usage**: The dedicated "Speech-to-Text Usage" section (text output) and "Speech-to-text" row (table output) are gone, along with the `speechToTextMilliseconds*` fields they read. The API deprecated `speech_to_text_milliseconds_count`/`_limit` on `GET /v2/usage` ("Always returns 0"), so the section could only ever display zero. Voice usage remains visible in the Product Breakdown, which reads the live per-product minutes data. The Admin API's per-key `speech_to_text_milliseconds` usage limit is a different, still-current field and is unaffected.
+- **cli**: **Language codes are displayed in lowercase everywhere.** Output previously mixed three casings: `deepl languages` printed lowercase from the registry, `glossary show` and `tm list` uppercased at display time, `translate`'s table uppercased the target language, and `write`/`correct` used BCP-47 (`en-GB`, `zh-Hans`). Lowercase matches the CLI's own normalized form, the registry, what `deepl languages` teaches users to type, and the wire format `/v3/languages` moved to; uppercase followed a v2-era docs convention that v3 abandons. **Scripts scraping these values will see a casing change** — `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"`. Input is case-insensitive everywhere, so no command line has to change -- `voice` included, which previously demanded the exact mixed-case spelling of a regional code (`--to zh-HANS`) and rejected the lowercase form the rest of the CLI prints. `write`/`correct` also send the lowercase code as `target_lang`: the Write API accepts any casing and canonicalizes server-side (verified live on `/v2/write/rephrase` and `/v2/write/correct` — `en-gb`, `zh-hans`, and `zh-HANS` all return 200 and echo back `en-GB` / `zh-Hans`). Wire parameters that are not display are untouched: `translate` and the glossary create endpoint still send uppercase `target_lang`/`source_lang` as those endpoints document.
 
-- **http**: `NO_PROXY` / `no_proxy` are honoured, with the standard semantics — `*` for everything, a leading dot or `*.` for subdomains, and an optional `host:port` that must agree. A corporate `HTTPS_PROXY` was previously applied to every request, including one aimed at localhost.
-- **auth**: `deepl auth set-key --no-verify` stores a key without validating it against the API. Validation ran before persisting, so on a network without proxy configuration both documented setup paths — `auth set-key` and `init` — failed and discarded the key; an unreachable API now also names `DEEPL_API_KEY` as the zero-network alternative.
-- **ci**: `npm run check-deps` fails the build when a package imported by `src/` is missing from `dependencies`, including one declared only under `devDependencies`. It runs in CI and in the publish job, and matches package names as quoted strings so indirect loads such as `requireModule('php-parser')` count as references.
-- **cli**: `t` and `w` command aliases for `translate` and `write` ([#12](https://github.com/DeepL/deepl-cli/issues/12)). The aliases appear in `--help` output and in bash/zsh/fish shell completions. `w` is deliberately assigned to `write` rather than `watch` — write is a primary API feature, watch a workflow helper.
-
-- **ci**: Pushing a `v*` tag now creates a GitHub Release, with notes extracted from that version's CHANGELOG section and generated notes as a fallback when the section is missing. This is why the repo has 17 tags and zero Releases. The workflow does **not** publish to npm: releases are published from GitLab, which is the source of truth and mirrors to GitHub, matching the other DeepL client libraries. The tag is checked against `package.json` first, so a mislabelled tag cannot mint a Release whose title disagrees with the version it contains.
-- **cli**: Global `--timeout <ms>` and `--max-retries <n>` options override the HTTP transport defaults (30000 ms, 3 retries) for a single invocation. Neither was previously configurable from the CLI.
-- **translate**: `--format json` output now includes the documented `cached` boolean, so scripts can distinguish cache hits from fresh API calls.
-- **cli**: Running under Node.js < 24 now fails fast with a clear one-line error (exit 6) instead of surfacing a raw `node:sqlite` ExperimentalWarning or crashing later.
-
-### Changed
+- **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers come from the per-language `features` matrix, which is what v2's `supports_formality` boolean became (see the Fixed entry on `pt`). A language whose features the response does not describe is left unmarked rather than marked unsupported, so the `[F]` legend cannot appear with no `[F]` beneath it.
 
 - **tests**: A fast-check property suite (`tests/property/`) now enforces round-trip laws across all 11 format parsers — translated values survive reconstruct/extract intact, re-applying the same translations never changes the file, and an identity sync is a fixed point — plus preservation laws for the placeholder and ICU utilities. Runs are seeded-random with 200 cases per law by default (`FC_NUM_RUNS` overrides; `FC_SEED`/`FC_PATH` replay a recorded counterexample). The suite found the U+2028 TOML corruption and the `.properties` leading-space loss fixed in this release; example tests document decisions, properties enforce laws.
+
 - **tests**: Tests that assert only inside a `catch` block now declare their assertion count, so they fail instead of passing with zero assertions when the command under test unexpectedly succeeds — the failure they exist to detect was the one they could not see. Sites that already assert on the success path are unchanged. `npm test` also refuses to run against a **stale** `dist/`, not just a missing one: the suites execute the built CLI, so a stale build reported results that did not describe the current source. A new suite checks every documented `deepl …` invocation in the README and docs against the CLI's real surface, so a command or flag that drifts out of existence fails CI rather than waiting for a reader to find it.
+
 - **docs**: The README leads with the npm install path and marks Homebrew as pending until the tap exists. Install instructions target `@deepl/cli` (10 occurrences across `docs/SYNC.md`, four example scripts, `examples/README.md`, and the git-hook template in `src/services/git-hooks.ts`). The README installation section documents three install paths — npm (`npm install -g @deepl/cli`), from source, and Homebrew (`brew install deepl/tap/deepl`, marked pending until the tap ships) — with an explicit Node.js 24 prerequisite, replacing the `better-sqlite3` native-compilation caveat (Xcode CLT / python3-make-gcc), which no longer applies. The `TROUBLESHOOTING.md` `NODE_MODULE_VERSION` / `npm rebuild better-sqlite3` entry is replaced by accurate guidance for the one remaining cache-degradation cause (running on Node < 24). Six stale `DeepLcom` GitHub URLs now point at the `DeepL` org directly. `CONTRIBUTING.md` states the Node 24 development prerequisite, and `SECURITY.md`'s supported-versions table reflects that only 2.x is a published, supported line.
+
 - **tests**: Removed the global manual mocks for `p-limit` and `fast-glob` (`tests/__mocks__/`). Because a manual mock for a node module is auto-applied to every suite, and `resetMocks: true` strips its implementation, `pLimit(n)` resolved to `undefined` and `fg(...)` resolved to `undefined` in all 236 suites — so no test exercised a real concurrency limit or a real glob walk, and two concurrency defects reached a release candidate undetected. The suites that need these mocked declare them explicitly with their own implementations, so nothing depended on the global versions. Added `tests/unit/concurrency-limiting.test.ts`, which asserts that `p-limit` rejects a non-positive concurrency, that peak overlap never exceeds the limit, and that `fast-glob` returns real paths — it fails if either global mock is reintroduced.
+
 - **tests**: Suites that shell out to the bare `deepl` command now run this tree's built CLI via a PATH shim installed in jest `globalSetup`, instead of whatever `deepl` happens to be globally installed. 23 suites (392 tests) previously required a global install — absent one they all failed with `command not found`, and present one they silently tested the installed version rather than the working tree. The shim lives in the real environment before jest workers spawn (a `setupFilesAfterEnv` hook cannot do this: test code sees a copied `process.env` that child processes never inherit). CI's now-redundant `npm link` step is removed, and a new unit suite pins that `deepl` resolves to the shim and reports the tree's version.
+
 - **tests**: `npm test` now fails fast with an actionable message when `dist/cli/index.js` is missing. `dist/` is gitignored and `npm test` does not build, yet all three test tiers execute the built CLI, so a fresh checkout previously failed hundreds of tests with errors that never mentioned the missing build.
+
 - **tests**: Jest's haste map no longer indexes `.claude/` (via `modulePathIgnorePatterns`). A leftover agent worktree under `.claude/worktrees/` duplicated the manual mocks in `tests/__mocks__/` and made every jest run emit a `jest-haste-map: duplicate manual mock found` warning; test files in worktrees were already excluded, but module indexing was not. Verified warning-free with a worktree present.
+
 - **BREAKING — package**: The package is now published as the scoped **`@deepl/cli`** (previously the unpublished working name `deepl-cli`). Scoped packages default to restricted visibility, so `publishConfig.access: "public"` is set explicitly — without it the publish fails. The `bin` name is unchanged: the command is still `deepl`, and scoping changes only the install string (`npm install -g @deepl/cli`). Repository, bugs, and homepage metadata now point at `github.com/DeepL/deepl-cli` directly instead of relying on the redirect from the legacy `DeepLcom` org name.
+
 - **BREAKING — cache/runtime**: The translation cache now uses Node's built-in `node:sqlite` module instead of the `better-sqlite3` native addon, and the CLI consequently requires **Node.js >= 24** (`engines.node` is now `>=24.0.0`). Node 24 is the first release where `node:sqlite` is non-experimental; Node 18/20 lack the module entirely and Node 22 would both warn on every invocation and downgrade the bundled SQLite (3.50.4 vs 3.53.1). Existing cache databases are read in place with no migration — the on-disk format is unchanged (SQLite 3.53.2-written files verified readable, WAL mode and `user_version` stamp included). **Migration**: upgrade to Node 24 (current LTS), e.g. `nvm install 24`; no other action is needed, and the cache keeps its contents.
+
 - **ci**: `.nvmrc` now pins Node 24, matching the CI matrix. It still read `20`, so `nvm use` handed local developers a runtime that cannot load `node:sqlite` and does not satisfy `commander`'s `engines.node >=22.12.0`.
+
 - **build**: `npm run build` now runs a `clean` step first, removing `dist/` and `tsconfig.tsbuildinfo` before compiling. Without it, `tsc` leaves output for sources that no longer exist, so a file rename could ship stale artifacts — verified reproducible: planting a stale module under `dist/sync/` and rebuilding left both files in `npm pack` output. Removing the build-info file is required too; deleting only `dist/` makes the incremental compiler report the output as up to date and emit nothing.
+
 - **tests**: Raised the timeout for the `watchAndSync` test block to 30s and replaced its fixed-round setup flush with a wait on an observable readiness signal. These tests intermittently exceeded the 10s default on CI runners — always as timeouts, never assertions — failing unrelated dependency PRs. Suite duration was measured to be flat across 250/25/5 flush rounds, so the historical 20 → 50 → 250 escalation could not have addressed it; the cost is runner CPU starvation (1.8s locally vs 10.8s observed on CI). The flush now also fails with the pending state rather than a bare timeout if setup genuinely stalls.
+
 - **deps**: `commander` 14.0.3 → 15.0.0. commander 15 is ESM-only (`"type": "module"`) and requires Node >=22.12.0, so it was unmergeable until the Node 24 baseline landed. Jest's `transformIgnorePatterns` allowlist gains `commander` so ts-jest transforms it under CommonJS test execution; without that, 28 suites fail to load with `SyntaxError: Cannot use import statement outside a module`.
+
 - **ci**: Test matrix, release workflow, and security workflow now target Node 24 (previously Node 20 and 22). Node 20 reached end-of-life in April 2026, and Node 24 is the current LTS. This aligns CI with the runtime the project is moving to; the `engines.node` range is unchanged in this entry and is bumped separately.
+
 - **perf**: CLI startup no longer eagerly loads the HTTP client (axios) or the format-parser stack (yaml, smol-toml): the API URL constants moved to a dependency-free module, and `sync init`'s `--file-format` choices are filled lazily via a commander `preSubcommand` hook. Measured on `--version`: ~144 ms → ~80 ms median, 358 → 137 modules loaded. Help output and invalid-value errors are unchanged.
+
 - **perf**: YAML reconstruction now indexes every string slot in a single document walk instead of calling `setIn`/`deleteIn` per key, scaling roughly linearly with file size — measured ~3.6 s → ~170 ms for a 16,000-key file. Batched deletion also fixes a correctness bug where removing several items from one sequence shifted indices mid-iteration and deleted the wrong entries.
+
 - **batch**: Plain-text batch translation now reads, translates, and writes one API batch at a time instead of loading every file into memory up front, so memory stays proportional to a single batch rather than the whole tree. Batch grouping also measures the form-encoded body size (what the API's 128 KiB limit actually applies to) instead of raw UTF-8 bytes, so CJK-heavy batches whose percent-encoding inflates ~3x are split correctly instead of being rejected server-side.
+
 - **sync**: Backups are written as `<file>.deepl.bak` instead of `<file>.bak`, and the stale-backup sweep considers only the `.deepl.bak` suffix — a user's own `*.bak` files are never touched again. The sweep also no longer re-creates a target file that was deleted; it restores a backup only over a sibling that exists but is empty. **Migration**: `.bak` files from earlier versions are no longer swept or restored — delete leftover `<target>.bak` files manually if desired.
+
 - **cli**: The primary human-readable reports of `sync status`, `sync validate`, `sync audit`, `sync init`, and `auth show` print to stdout, so `deepl sync status > report.txt` and `deepl auth show > key.txt` capture output instead of producing empty files. Diagnostics, warnings, and progress stay on stderr, and `--format json` stdout purity is unchanged.
+
 - **glossary**: `create` and `show` render language codes uppercase and the creation timestamp as a locale-independent ISO string, and the create success line prints to stdout — matching the documented output instead of a locale-dependent date on stderr.
+
 - **hooks**: The installed pre-commit hook now actually validates translations — when a `.deepl-sync.yaml` exists and the CLI is on PATH it runs `deepl sync validate` and blocks the commit on validation errors (with a `--no-verify` hint). It was previously a no-op that grepped staged files and always exited 0.
 
 ### Removed
 
+- **cli**: **BREAKING**: The `--enable-beta-languages` flag on `translate` is gone. The API deprecated the underlying `enable_beta_languages` parameter with "has no effect" — beta languages are simply part of the regular language set now — so the flag had become a silent no-op. Scripts passing it will exit with an unknown-option error; remove the flag.
+
+- **usage**: The dedicated "Speech-to-Text Usage" section (text output) and "Speech-to-text" row (table output) are gone, along with the `speechToTextMilliseconds*` fields they read. The API deprecated `speech_to_text_milliseconds_count`/`_limit` on `GET /v2/usage` ("Always returns 0"), so the section could only ever display zero. Voice usage remains visible in the Product Breakdown, which reads the live per-product minutes data. The Admin API's per-key `speech_to_text_milliseconds` usage limit is a different, still-current field and is unaffected.
+
 - **repo**: The `VERSION` file and `.npmignore`. Nothing read `VERSION` — `deepl --version` reports `package.json`'s value — so it was a second, hand-edited source of truth that could only drift; use `npm version X.Y.Z --no-git-tag-version`, which updates the manifest and lockfile together. `.npmignore` was dead weight because the `files` array governs what is packed.
+
 - **build**: Source maps and declaration maps are no longer emitted. They were already excluded from the published package, so emitting them only left dangling `sourceMappingURL` comments in the shipped files, giving library consumers unresolvable stack frames and broken go-to-definition.
+
 - **deps**: `inquirer`, which no source file imported (see the `@inquirer/prompts` entry under Fixed).
+
 - **deps**: `better-sqlite3` and `@types/better-sqlite3`. The production dependency tree no longer contains any native addon, removing the entire class of ABI-mismatch failures (`ERR_DLOPEN_FAILED` / `NODE_MODULE_VERSION` errors after a Node major upgrade, e.g. via `brew upgrade node`), a 1.9 MB platform-specific binary, and the C++ compilation-toolchain requirement for installs from source. The cacheless-degradation safety net remains: a runtime whose `node:sqlite` is missing (Node < 22.5.0) warns once and runs uncached rather than crashing, and never touches the cache database.
+
 - **BREAKING — sync**: `deepl sync init --source-lang` and `--target-langs`, the deprecated aliases introduced in 1.x, are removed and now fail with `unknown option` (exit 1). Use `--source-locale` and `--target-locales`. This is the documented removal of 1.x aliases at the 2.0 cut. `deepl translate --target-lang` is unaffected — it is the API's wire name, not a deprecated alias.
 
 ### Fixed
 
 - **package**: **`import '@deepl/cli'` threw instead of loading.** The package is ESM, so Node requires a full specifier for every relative import, but the entry point re-exported `'./types'` — a directory — which fails with `ERR_UNSUPPORTED_DIR_IMPORT`. The whole programmatic surface was therefore unreachable, and the published typings resolved to nothing for a `nodenext` consumer, so `import type { Language } from '@deepl/cli'` was an error regardless of what the union contained. `deepl --help` never exercised this, because the `bin` entry has its own module graph. Both remaining directory specifiers now carry `/index.js`, and the manifest suite imports the built entry in a real Node ESM process and rejects any extensionless relative specifier in the emitted entry chain.
 
-- **cache**: **The translation cache keyed on too little and could serve the wrong text.** `translationMemoryId`, `translationMemoryThreshold`, `--ignore-tags`, `--splitting-tags`, `--non-splitting-tags`, `--outline-detection` and `--preserve-formatting` were absent from the key, so `deepl translate "Hello" --to de` and the same command with `--translation-memory my-tm` collided: the second returned the cached non-TM translation, never consulted the memory, and reported `cached: true`. Likewise two runs differing only in `--ignore-tags` returned each other's output. `preserveFormatting` had been excluded on the grounds that it does not affect output, but `preserve_formatting` suppresses the sentence-boundary punctuation and case correction, which shows up in the text. **Entries cached by earlier versions for requests using any of these options now miss rather than being served wrongly**, so the first such translation after upgrading is refetched.
+- **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
+
+- **translate**: **A directory translation where every file failed exited 0.** The summary reported `✓ Successful: 0 / ✗ Failed: N` and the command still looked like success to a script or CI job. Since language validation defers unknown codes to the API, a plain `--to` typo took this path: on 1.x it exited 6 locally, and in this release it printed a failure list and exited 0. A run with no successes now exits 1, and a partial failure exits 12, matching what `sync` already does.
+
+- **translate**: **The rejected-request abort covered only plain-text batches.** `.txt` and `.md` files are grouped into batches and stopped after the first rejection, but `.json`, `.yaml`, `.html`, `.srt` and `.xliff` go through the per-file path, which still spent one round trip per file collecting the same answer. That path stops the same way now, and files that were never sent are reported as skipped rather than as failures carrying another batch's error. The classifier also checks the error class before the message: a 5xx interpolates the upstream body, so a gateway error quoting `target_lang` no longer aborts a run that is otherwise succeeding, while a refused key or an exhausted quota — as request-wide as a bad code — now do.
+
+- **voice**: **`--quiet` discarded the salvaged transcripts of a failed session.** The partial result went through the warning channel, which quiet mode suppresses, while the live display was erased regardless — so audio that had been transcribed and billed left nothing on screen. It goes through the error channel now, the display is only cleared once there is something to print in its place, and `--format json` is honoured on that path. The live display also keyed target rows by the requested spelling, so with `--to zh-HANS` a `zh-Hans` echo left the row blank for the whole session; it is matched case-insensitively, as the session already was.
+
+- **voice**: **Regional target and source codes had to be spelled in exactly the API's casing.** `--to en-gb` or `--to zh-hans` exited 6 while `--to en-GB` worked, even though `deepl languages` prints the lowercase form and every other command accepts any casing. Codes are matched case-insensitively and canonicalized to what the Voice API expects.
+
+- **glossary**: **Deduplicating repeated `--glossary` flags inverted the documented precedence.** A repeat kept its first position, so `--glossary base --glossary override --glossary base` let `override` win the terms both define, although the user put `base` last. A repeat now keeps its last position, which is the one the API applies.
+
+- **sync**: The startup glossary coverage check required the top-level glossary to cover every target locale, including locales configured with their own `locale_overrides.<locale>.glossary`. That glossary never translates those locales, so a documented configuration aborted before any file was touched.
+
+- **config**: Language normalization applied to `config set` but not to the load path, so a file written or hand-edited with uppercase codes kept them — and because `TranslationService` merges `defaults.sourceLang` verbatim, `DE` in config and an explicit `--from de` keyed two cache entries for one request. Codes are normalized on load too. The note about a code the snapshot does not list is also limited to the write path; shared with the loader it printed on every invocation, including `deepl --version`.
+
+- **translate**: Document mode warned that `--model-type` and `--tag-handling*` would be ignored and then rejected the command over them, because the shared validation still saw them. The mode now discards what it says it discards.
+
+- **usage**: A duration-billed product could render a character count as hours by scaling it, and a `null` count was reported as a genuine zero. Character counts are read only for `milliseconds` billing, where they carry the duration; anything non-finite is treated as absent.
+
+- **languages**: `--features` contradicted its own footer: a language supporting none of the discriminating features read as `none` two lines above a note crediting it with the features every described language shares. Only a language credited with nothing at all reads `none` now. `--features` also disabled the Formality column without always replacing it, so the flag could show less than the plain listing, and the `?` cell for an undescribed language had no legend.
+
+- **docs**: Three passages described behaviour that no longer exists — the `voice --glossary` row had picked up `translate`'s repeatable/`--from` semantics (voice takes one glossary and requires neither), the `write` reference still said an unknown code is rejected locally, and the `usage` reference still documented the removed Speech-to-Text section along with output showing the duplicated API-key figure.
+
+- **cache**: **The translation cache keyed on too little and could serve the wrong text.** `translationMemoryId`, `translationMemoryThreshold`, `--ignore-tags`, `--splitting-tags`, `--non-splitting-tags`, `--outline-detection` and `--preserve-formatting` were absent from the key, so `deepl translate "Hello" --to de` and the same command with `--translation-memory my-tm` collided: the second returned the cached non-TM translation, never consulted the memory, and reported `cached: true`. Likewise two runs differing only in `--ignore-tags` returned each other's output. `preserveFormatting` had been excluded on the grounds that it does not affect output, but `preserve_formatting` suppresses the sentence-boundary punctuation and case correction, which shows up in the text. **Every translation entry cached by an earlier version is retired**, not only the ones using these options: the service merges a `preserveFormatting` default, so it is always part of the key. The cache schema version is bumped, so those rows are dropped on first open rather than sitting unreachable until their 30-day TTL — `write` and `correct` entries key the same way they always did and are kept. The first translation of any given text after upgrading is refetched.
 
 - **translate**: **A rejected language no longer costs one API round trip per batch.** Because validation defers well-formed unknown codes to the API, a two-letter typo reaches it — and a directory translation asked the same rejected question once per batch, so `deepl translate ./docs --to ex` on 200 files made 200 failing requests to be told the same thing 200 times. An unsupported `target_lang` or `source_lang` is a property of the request, not of one batch, so the remaining batches now fail without being sent; errors specific to a batch (a rate limit, say) still let the run continue. Relatedly, local validation used to be what pointed at `deepl languages`, and deferring left users with a bare `Value for 'target_lang' not supported.` from the server: a code the bundled snapshot does not list now says so up front, before anything is sent or billed.
 
@@ -110,107 +162,205 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **languages**: `deepl languages --target` marks Portuguese (`pt`) with `[F]`. Formality support is now read from `features.formality` on `GET /v3/languages` instead of a static table in the language registry. The v3 migration had assumed v3 stopped reporting formality, but the capability was only renamed — v2's `supports_formality` boolean became the presence of a `formality` key in the per-language features matrix — so the CLI was answering from an 11-entry snapshot of the final v2 response that had already drifted from the API. The snapshot and the registry's `supportsFormality` field are gone; the registry's `category` tiers are unaffected. Output is otherwise unchanged: the `[F]` set is identical apart from `pt`.
 
 - **watch**: `--glossary` without `--from` now exits 6 before the watcher starts, instead of starting a session that fails on every single file change with a raw server message. The API rejects any translation naming a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"), which `translate` already guarded against up front for text, files, and documents; `watch` passed `--from` straight through. A long-running command is the worst place for this, since the operator saw the failure once per edit rather than once at launch. The check runs before the glossary name is resolved, so it costs no API call. `sync` needs no equivalent: it has no `--from` at all, taking the source language from the required `source_locale` field in `.deepl-sync.yaml`, so its requests always carry one.
+
 - **voice**: A session that ends with the audio transcribed but no translation for a requested `--to` language now fails with exit code 9 and names the languages, instead of printing an empty translation line and exiting 0. The failure **carries the transcripts that did arrive**, which the command prints to stderr before exiting: the audio is transcribed and billed before the missing translation is noticed, so with `--to de,fr,es,it,ja` one dropped target must not throw away the source transcript and four good translations and make the user re-stream to see them. Target updates are also matched **case-insensitively**, because the requested spellings include `zh-HANS` and `en-GB`: a server echoing another canonicalization had its translation silently dropped by the existing unmatched-update guard, and this check would then have reported that target as missing — turning a cosmetic mismatch into a failed session. Silent partial output was the worse failure: a script consuming `deepl voice` output saw success with the translation missing. Audio containing no speech transcribes to nothing and translates to nothing, which is legitimate and still exits 0, so the check only applies when a source transcript exists. Whitespace-only and tentative-but-never-concluded translations count as missing, since neither reaches the printed output. Investigated as an intermittent (~1 in 4) empty translated line; the leading hypothesis was disproved with frame-level traces of live sessions — the server sends `end_of_stream` strictly after `end_of_target_transcript`, and the client only tears the socket down on `end_of_stream`, so there is no client-side teardown race. Reconnect was ruled out too: a socket dropped after end-of-source cannot be resumed (the API returns `410 Gone`) and already exited non-zero. The empty line did not reproduce in 64 live runs across pacing, burst, multi-target, and concurrency variations, so the trigger appears to be server-side and transient — which is exactly why the client needs to detect it rather than report success.
+
 - **formats**: TOML reconstruction escapes U+2028/U+2029 (Unicode line/paragraph separators) in double-quoted values, and literal-string values gaining one fall back to double quotes. Written raw, these characters broke the entry-line scan on the *next* sync (JavaScript's `.` excludes line terminators), which re-appended the key as a duplicate and made the third sync fail to parse the file at all — first sync fine, second silently corrupting, third crashing. Found by the property-based round-trip suite.
+
 - **formats**: `.properties` reconstruction escapes leading spaces in values (`\ `), which the value parser otherwise strips on the next read — a translation beginning with a space silently lost it on every subsequent sync. Leading tabs, trailing spaces, and newlines were already escaped correctly. Found by the property-based round-trip suite.
+
 - **sync**: `--auto-commit` now recognises its own translation output rather than only the files a given run wrote, which fixes two related problems. A translation left on disk by an earlier refused run was classed as an unrelated modification, so auto-commit refused forever and the user had to commit it by hand; it is now committed once the genuinely unrelated changes are dealt with. And in `--watch` mode, where the same path runs once per trigger, a trigger that translated nothing skipped the checks entirely and reported success while a commit was still owed. Staging is also driven by what is actually dirty, so a rewrite that produced identical bytes no longer attempts an empty commit. Ownership is derived from the lockfile's tracked source files, with each file matched to its own bucket so one bucket's `target_path_pattern` cannot claim another's output.
+
 - **sync**: Re-running `deepl sync --auto-commit` after a refusal no longer reports success without committing. A refused run still writes its translations to disk, so the retry found nothing to translate; the preflight was skipped in that case and the command exited 0 with no commit made, the translation still uncommitted and the tree still dirty. The repo-state checks now run whenever `--auto-commit` is requested, so the refusal is reported identically on every attempt. Staging and committing are still skipped when there is nothing to commit. Two tests covered this path but could not see the defect: their assertions ran only inside a `catch` the retry never entered, which also hid an assertion that could never have matched (it looked for "detached HEAD" against a message reading "HEAD is detached").
+
 - **write**: `deepl write` now runs from a published install. `diff` is imported at the top of the write command but was declared only under `devDependencies`, which consumers do not install, so every command that loaded the module failed with `Cannot find package 'diff'` before producing output. `--help` did not surface it because the module loads lazily.
+
 - **init/write/sync**: `@inquirer/prompts` is declared as a dependency. It is imported at runtime by `init`, `write --interactive` and `sync init` while only the unused `inquirer` was declared, so it resolved through npm's hoisting: under a strict layout (pnpm, `--install-strategy=nested`) those commands failed with `ERR_MODULE_NOT_FOUND`, and under npm the prompt that reads the API key bound to whatever major another dependent happened to hoist.
+
 - **init**: `deepl init` with stdin at end-of-file now exits 6 with the documented non-interactive message, instead of starting to prompt and then exiting 1 with a Node `unsettled top-level await` warning. Reached by `docker run` without `-it`, CI, and piped invocations. The command checked only `--no-input`, where the sibling guard in `write --interactive` also checks whether stdin is a terminal; the existing test covered only the `--no-input` variant, which already worked.
+
 - **write**: `--lang` and `--to` accept language codes in any casing and normalize them to the API's form. They previously compared against a mixed-case list with an exact match, rejecting the lowercase codes `deepl languages` prints and `translate --to` accepts — so the CLI's own discovery output was unusable with the command documented as consistent with `translate`.
+
 - **translate**: The error raised for an unexpected API response pointed at a bug tracker under an unrelated third-party account rather than this repository's.
+
 - **cli**: Shell completions and the did-you-mean suggester no longer offer hidden internal commands, and the suggester now knows about aliases and prefers a prefix match — `deepl tr` suggests `translate` rather than `tm`. `--version` is also no longer duplicated in the bash and zsh candidate lists.
+
 - **cli**: The remediation for a missing API key survives `--quiet`. It was emitted as a warning, which quiet mode suppresses entirely, leaving only `Error: API key not set`; `docs/API.md` claimed quiet mode still showed such warnings and now describes the actual behaviour.
+
 - **cache**: The size cap is now actually enforced. Size accounting previously lived in a process-local counter that drifted in both directions — downward when an overwrite's eviction deleted the very key being replaced (after which the cap stopped firing and the DB grew without bound), upward when `get()` deleted expired rows without decrementing (evicting entries that didn't need evicting), and negative when a concurrent process's rows were swept (disabling eviction for the process lifetime). The total is now always read from `SELECT SUM(size)`. Eviction now deletes oldest rows in batches until enough space is actually freed, instead of a one-shot estimate from the average row size that under-evicted whenever sizes were skewed. An entry larger than `maxSize` itself is skipped instead of stored — previously it wiped every other entry first (eviction deleted all rows and inserted the oversized one anyway), leaving a cache that re-wiped on every subsequent write. The expired-entry sweep's throttle timer is seeded so the sweep runs on a process's first operation; it was seeded to construction time, so it never ran in any process shorter than 60 seconds — essentially every CLI invocation. Repeated `getInstance()`/`close()` cycles no longer accumulate process signal listeners until Node prints `MaxListenersExceededWarning` to stderr. Docs now describe eviction as oldest-first rather than LRU, which is what the code has always done (`timestamp` is only written on `set()`).
+
 - **cache**: Only genuine corruption (`SQLITE_CORRUPT` / `SQLITE_NOTADB`) now triggers the rename-aside-and-recreate recovery. The constructor previously treated *every* unexpected error as corruption, so transient lock contention (`SQLITE_BUSY` — e.g. two concurrent invocations against a cache on a filesystem where WAL cannot be enabled) renamed a healthy cache aside, recreated it empty, and broke the other process's open transaction; and a DB written by a newer CLI version was destroyed instead of refused, defeating the schema check's stated purpose. Lock waits now go through `PRAGMA busy_timeout` (5s), and everything that isn't corruption propagates so the CLI degrades to an uncached run with a warning. When recovery does run, the backup's WAL/SHM sidecars are copied before the failed handle is closed (SQLite deletes them on close) and named `<backup>-wal` / `<backup>-shm` so SQLite can actually recover the preserved data — the old naming (`<original>-wal<suffix>`) orphaned the WAL, silently losing any rows not yet checkpointed. Rename-aside backups are pruned to the most recent three so repeated corruption cannot fill the disk.
+
 - **sync**: `deepl sync pull` no longer discards existing translations for keys named after `Object.prototype` members. `sanitizePullKeysResponse` built its result on a plain object, and callers test membership with `pulledKeys[key] !== undefined` / `??` — so for a source key called `toString`, `constructor`, `valueOf`, `hasOwnProperty`, or `__proto__`, the lookup returned an inherited *function*, which is neither `undefined` nor nullish. The entry was therefore treated as a freshly approved TMS translation and won over the real one, then vanished from the file when `JSON.stringify` dropped the function value — while the lockfile recorded it as `translated` / `human_reviewed`, so no later sync repaired it. The accumulator now has a null prototype.
+
 - **sync**: ICU plural/select messages with text around the block are now preserved. The detection pattern was anchored to the start of the string, so `You have {count, plural, one {# item} other {# items}} in your cart.` — arguably the most common real shape — was not recognised as ICU at all and the raw syntax went to the engine as prose. Confirmed against the live API: it returned `{count, Plural, ein {…} weiteres {…}}`, translating the format keyword *and* both selectors, leaving a message with no valid format type and no `other` fallback. Detection now matches an ICU block anywhere in the string, and the prose on either side becomes a translatable segment instead of being silently dropped from the reassembled output (trailing text was previously lost outright). Re-verified end to end after the fix: `plural`, `one`, `other`, and the `count` argument all survive while the surrounding prose is translated. Note this affects `deepl sync`, the only path with ICU preservation; `deepl translate` on a raw ICU string is unchanged.
+
 - **sync**: ICU structural damage is now detected instead of reported as passing. `checkIcuBrackets` compared only brace counts and nesting depth, which are identical when the engine translates the keyword, a selector, or the argument name — so `fail_on_error` never tripped on a message that no longer renders. Validation now compares the parsed argument/format-type headers and the selector keyword sets, while tolerating reordered selectors (order is not meaningful in ICU).
+
 - **sync**: A failed ICU segment no longer yields a part-English message reported as a successful translation — the message is marked failed and retried. `reassemble` also throws on a translation-count mismatch rather than filling the gaps with empty strings, which produced empty plural branches that render nothing for that category.
+
 - **sync**: A locale that failed completely now fails the run. The check used `.every()`, so a run was only unsuccessful when *every* locale failed — with two locales where one succeeded and the other failed outright, the run reported success and exited 0, leaving the failed locale's file absent while CI went green. It now matches the documented contract for exit 12 (`docs/API.md`: "completed with at least one failed locale"): a locale that translated nothing and recorded failures fails the run, while a locale that partly succeeded still reports its per-key failures in the summary without failing the run, and a locale with nothing to do is simply up to date. `--auto-commit` additionally now refuses to commit an unsuccessful sync — it previously checked only drift and dry-run, so it would happily commit a state with a missing locale file.
+
 - **sync**: Staleness is now judged per target locale, so `--frozen` can detect a locale that has fallen behind. `computeDiff` compared only the entry-level `source_hash`, so once one locale was re-synced after a source edit, the entry hash matched again and every *other* locale reported `current` **forever** — no API call was ever issued for them, `sync status` showed 100%, and the CI gate whose entire purpose is catching out-of-date translations could not see it. A key is now stale if any configured target locale's stored hash lags the source or its last attempt failed. Relatedly, the failure check was previously unscoped (`Object.values(translations).some(failed)`), so **one** locale's failure marked the key stale for **all** locales and the next run re-translated locales that were already correct — overwriting human-edited files. Locales absent from `target_locales` are ignored, so a leftover entry for a de-configured locale no longer flags a key indefinitely, and a locale with no entry at all is still treated as a new-locale backfill (counted as new keys) rather than as drift. `sync status` computes the same per-locale determination inline instead of inheriting the shared source-level status.
+
 - **BREAKING — sync**: Untranslated source text is never written into a target locale file and recorded as a translation. When a key's source was unchanged, the lockfile claimed the locale already had a translation, and the target file supplied none — because the file had been deleted to force regeneration, or held an empty value — the source string was written through as the "translation" and the lockfile kept its `translated` status, so **no later run ever corrected it**: the locale file silently retained English and the run reported success. Such a key is now re-translated, and a verbose message explains why. A translation that is present but deliberately empty is preserved rather than treated as missing. **Behaviour change to be aware of**: deleting a target locale file now causes its keys to be translated again (billed) instead of being backfilled with English — which is the point, but it does mean a deleted file costs a real re-translation. Two existing tests asserted the old fallback; neither the CHANGELOG nor `docs/SYNC.md` documented it, and both arrived inside a bulk development commit rather than as a deliberate decision, so they have been updated to the corrected contract.
+
 - **api**: A blank `Retry-After` header no longer collapses 429 backoff into a tight retry loop. `Number('')` is `0`, which passed the finite check and returned a 0 ms delay — and because `0` is a real number the jitter-backoff fallback never engaged, so all retries fired back-to-back at an endpoint that was already rate-limiting the client. A blank or whitespace-only header is now treated as absent; an explicit `Retry-After: 0` is still honoured.
+
 - **watch**: A file changed during its own translation is no longer translated twice concurrently. The debounce entry was deleted in the translation's `finally` rather than when the timer fired, so it removed whatever entry was current by then — usually a *newer* pending timer for the same file, which then could not be cancelled. A subsequent change therefore started a second translation racing to write the same output path, doubling API spend with a nondeterministic winner. The entry is now cleared when the timer fires, and only if it is still the entry that timer registered.
+
 - **sync**: An invalid `--concurrency` no longer makes a sync silently do nothing while reporting success. `--concurrency` was parsed with a bare `parseInt`, so `abc` produced `NaN`, which survives `??` defaulting; `Math.min(NaN, n)` is `NaN` and `Array.from({length: NaN})` is empty, so **zero** workers were started and `mapWithConcurrency` returned an empty result having translated nothing and thrown nothing. Verified end-to-end: with a deliberately invalid API key, `deepl sync` correctly failed with exit 2 while `--concurrency 0`, `--concurrency abc`, and `--concurrency -3` each printed `Sync complete` with exit 0 and no output file. The flag (and `--debounce`) now reject non-positive and non-numeric values at the boundary, `sync.concurrency` is validated in the config like `tms.push_concurrency` already was, and `mapWithConcurrency` clamps to at least one worker as defence in depth.
+
 - **cache/cli**: Interrupting a command no longer reports success or leaks the sync process lock. `CacheService`'s `SIGINT` handler called `process.exit(0)`, and because the cache singleton is constructed during service setup that handler ran *before* the sync engine's own — so `deepl sync` interrupted with Ctrl-C exited **0** (so `deepl sync && git commit` would commit a half-finished sync) and left `.deepl-sync.lock.pidfile` behind. The cache handler now only closes the database, and termination belongs to the CLI entry point, which defers the exit so every other listener's cleanup runs first: verified end-to-end as exit 130 with the lock released. Commands that own their shutdown — `sync --watch`, for which SIGTERM is the normal stop signal — opt out and still exit 0.
+
 - **formats**: TOML multi-line (`"""` / `'''`) values survive a sync. Only the opening line was emitted verbatim, so body lines that happened to look like `key = "…"` were parsed as entries and **deleted from the value**, and the multi-line key — never marked as used — was re-appended at end of file, leaving a document that no longer parses (`trying to redefine an already defined table or value`). The whole block is now emitted verbatim and skipped, including the single-line `k = """text"""` form. Multi-line values remain untranslated, which is the existing documented behaviour.
+
 - **formats**: Translating a key in an Xcode String Catalog no longer destroys that key's plural `variations`. Reconstruct replaced the locale's entire localization object with a single `stringUnit`, discarding per-category translations the parser never surfaces as entries — so they could not be recovered. Existing `variations` are now preserved alongside the updated `stringUnit`, and the `Localization` type declares the field so this cannot silently recur.
+
 - **formats**: ARB (Flutter) files with a UTF-8 BOM are readable. `JSON.parse` rejects a leading BOM, so a BOM-prefixed `.arb` file failed outright; the BOM is now stripped on extract and reconstruct, matching the JSON parser's existing behaviour.
+
 - **formats**: A translated Android string can no longer break out of its CDATA section. `escapeForReconstruct` wrapped the translation in `<![CDATA[…]]>` with no escaping, so a value containing `]]>` closed the section early and the remainder was parsed as XML — allowing extra `<string>` elements into a generated resource file. This was reachable without a malicious API response, because on translation failure the source string is written through verbatim and the source file is used as the template when the target locale file does not exist yet. Occurrences of `]]>` are now split across adjacent CDATA sections, which keeps the text literal, and extract concatenates adjacent sections so such values round-trip unchanged.
+
 - **formats**: New TOML keys are written into the section they belong to. They were appended at end of file using the full dotted path while a `[section]` header was still in scope, so `messages.newkey` parsed back as `messages.messages.newkey` — and because the intended key was therefore still missing, it was re-appended on every subsequent run. Keys are now inserted inside their own section block, with a new `[section]` header added only when that section is absent.
+
 - **formats**: Android XML entities no longer compound on every sync run. `extract` never decoded XML entities, and `escapeAndroid` replaced `&` *last* — so it re-escaped its own output. `Terms &amp; Conditions` became `&amp;amp;` after one run and `&amp;amp;amp;` after three, verified. Entities are now decoded on extract via a single-pass decoder (so a literal `&amp;lt;` decodes to `&lt;`, not to `<`), and `&` is escaped before `<`/`>`; a three-run identity sync is now a fixed point.
+
 - **formats**: Emoji and other astral characters survive `.properties` files. `escapeValue` iterated by code point but escaped with `charCodeAt(0)`, emitting only the high surrogate — `Hello 😀 world` was written as `Hello \ud83d world`, which cannot be decoded back. All UTF-16 code units of a character are now emitted, so an emoji round-trips as a complete surrogate pair.
+
 - **formats**: XLIFF files carrying a `state` attribute are no longer mangled. `state` is a standard attribute that every CAT tool writes, but the `<segment>` and `<target>` patterns required bare tags. For XLIFF 2.0 this meant `extract` returned nothing and `reconstruct` then **deleted every `<unit>`**; for XLIFF 1.2 an existing `<target state="…">` was treated as absent, so a second `<target>` was injected, yielding schema-invalid output that retained the stale translation. Both elements now accept attributes and preserve them through a round-trip.
+
 - **formats**: CRLF-authored resource files are no longer invisible to the tool. Line-based parsers split on `'\n'`, leaving a trailing `'\r'` that defeated their `$`-anchored patterns: a Windows-authored `.po` file extracted **zero** entries, so `deepl sync status` reported `totalKeys: 0` and 0% coverage with exit 0, and `sync export` emitted an empty XLIFF. TOML was affected differently — reconstruct failed to match existing keys and appended duplicates, producing a file that no longer parses (`trying to redefine an already defined table or value`). All line-based parsers (PO, TOML, iOS `.strings`, Java `.properties`) now split on `/\r?\n/`; the latter two already tolerated CRLF, and the change makes that explicit rather than incidental.
+
 - **glossary**: A glossary term named after an `Object.prototype` member is no longer silently dropped or misreported. `tsvToEntries` accumulated into a plain object and tested for duplicates with `entries[source] !== undefined`, so `toString` (and friends) triggered a spurious "Duplicate source" warning, and a `__proto__` term was swallowed by the prototype setter instead of being stored. Genuine duplicate detection is unchanged.
+
 - **sync**: A lockfile entry whose i18n key is named `__proto__` no longer vanishes on every write — the key-sorting JSON replacer accumulated into a plain object, where that assignment invokes the prototype setter. Auto-glossary term extraction, which is keyed by untrusted source strings, was fixed the same way.
+
 - **formats**: The JSON parser no longer pollutes `Object.prototype` via a `__proto__` key in a resource file, and now round-trips prototype-named keys as ordinary data. `hasKey` used `part in record`, which reports inherited members, and `setKeyWithParts` assigned with `current[part] = …`, where `current['__proto__'] = {}` invokes the prototype setter instead of creating a property. Membership is now an own-property check, and assignment goes through `Object.defineProperty`, so a key legitimately called `toString` translates like any other.
+
 - **hooks**: Generated git hooks no longer emit a broken install instruction. The `pre-push` hook template told users to globally install the unpublished `deepl-cli` name — which fails with `ENOVERSIONS` — and now points at `@deepl/cli`. Reported by **@maa-xx** in #70, who correctly diagnosed that the documentation instructed readers to install a package that does not resolve; their docs fix was superseded by actually publishing the package, but this source-level occurrence was the one their PR missed and is now guarded by a regression test asserting generated hook output never references an unpublished package name.
+
 - **cache**: A cache backend that fails to load (e.g. `better-sqlite3` ABI mismatch after a Node major upgrade, `ERR_DLOPEN_FAILED`) is no longer misclassified as database corruption. Previously the constructor's catch-all renamed the user's healthy `cache.db` to `cache.db.corrupt-<timestamp>` and recreated an empty database — verified to quarantine a 2,646-entry cache that passed `integrity_check`. Native-module load failures now leave the database and its `-wal`/`-shm` sidecars untouched; genuine corruption still triggers the rename-aside recovery. `deepl translate` and `deepl write` degrade to running without a cache (single warning per process, exit code 0) instead of crashing, since the cache backend is loaded lazily behind a warn-once latch; `deepl cache …` subcommands, which cannot run cacheless, fail with an actionable error suggesting a reinstall or matching Node version.
+
 - **sync**: `deepl sync --frozen` now reports an accurate key count when drift is caused by a newly-added target locale. Previously the message read `Sync drift detected: 0 new, 0 stale keys.` because the frozen branch in `processBucket` short-circuited before promoting current-status keys missing a target-locale translation into `newKeys` — even though `--dry-run` against the same state correctly reported the backfill count. The drift exit code (10) is unchanged. The drift message now also surfaces `deletedKeys` and only mentions nonzero categories, mirroring the success-path summary format.
+
 - **cache**: `deepl cache enable` / `deepl cache disable` now persist `cache.enabled` to the config file. Both reported success but only flipped an in-memory flag in a process that exited immediately, so the state reverted instantly and subsequent translations kept using the cache after it had been disabled. `deepl cache stats` likewise read a process-local flag that always initialized to enabled, so the status line could never show `disabled` — not even after `deepl config set cache.enabled false`; it now reports the persisted state.
+
 - **sync**: Subcommands now honor `--locale`. Commander bound the flag to the parent `sync` command even when it trailed the subcommand name, so `sync status --locale de` listed every configured locale and `sync export --locale de` emitted XLIFF for all of them. Affects `status`, `validate`, and `export`.
+
 - **sync**: Subcommands now honor `--sync-config`. The flag was silently ignored and the auto-detected `.deepl-sync.yaml` used instead, so `sync validate --sync-config /missing.yaml` exited 0. Affects `status`, `validate`, `export`, `audit`, `resolve`, `push`, and `pull`.
+
 - **sync**: A `--locale` value that is not in `target_locales` now exits with a `ConfigError` (exit 7) naming the offending and configured locales, as documented. Previously `sync --locale <typo>` exited 0 reporting success while translating nothing, which made a typo'd locale in CI report green.
+
 - **sync**: `deepl sync init --sync-config <path>` now writes the config at that path and checks the already-exists guard against it, instead of always using the current directory. `.deepl-sync.yaml` is also written atomically, so an interrupted run cannot leave a truncated config behind.
+
 - **formats**: Android XML and XLIFF parsing is now linear in file size. Both parsers matched elements with a lazy `([\s\S]*?)` pattern, so every opening tag without a matching close rescanned the rest of the file; a 4 MiB resource file took minutes to parse. Android reconstruct also rescanned the whole file once per dotted key to identify `<string-array>` members (2.7 s → 63 ms on a 3.6 MiB, 52,000-entry file).
+
 - **formats**: Android XML self-closing elements (`<string name="x"/>`) are no longer deleted together with the element that follows them.
+
 - **formats**: Android XML values whose CDATA body contains `</string>` are no longer truncated on extract, and plural `<item>` attributes are preserved when a translation is written back.
+
 - **formats**: XLIFF files with a CDATA section in a `<note>` between `<source>` and `<target>` are no longer rejected; only CDATA inside `<source>` / `<target>` is unsupported.
+
 - **hooks**: `deepl hooks install` now resolves the hooks directory git actually reads (`git rev-parse --git-path hooks`), so it honours `core.hooksPath` (husky) and works inside linked worktrees and submodules where `.git` is a pointer file. Previously it reported success while writing a hook git never ran, and crashed with a raw `ENOTDIR` on worktrees and submodules.
+
 - **hooks**: `deepl hooks install` no longer overwrites an existing hook backup. A repeat install writes to the next free `.backup` slot, and the install output now prints the hook path and the backup path. `findGitRoot` also no longer loops forever when given a relative start path.
+
 - **sync**: Auto-glossary sync (`translation.glossary: auto`) skips terms whose source or translation is empty or contains a tab, carriage return, or newline. Such terms were uploaded as corrupted or outright wrong glossary entries, which DeepL then applied to live translations. An unchanged dictionary is no longer re-uploaded on every run (entries were compared against a lossy TSV round trip that could never compare equal), and a glossary failure for one locale no longer ends glossary sync for the remaining locales — the warning now names the locale, glossary, and cause.
+
 - **glossary**: `deepl glossary add-entry` / `update-entry` reject terms containing a tab, carriage return, or newline instead of shifting every following column of the uploaded dictionary, and glossary import picks the TSV or CSV dialect once per file, so a quoted CSV field containing a tab is no longer split into garbage columns.
+
 - **sync**: `deepl sync audit` no longer uses the lock file's source hash as a stand-in for a translation. Divergent translations were reported as consistent and identical ones as an inconsistency displaying a hex hash. Targets that cannot be read are now listed separately as missing — a new additive `missingTargets` field in the `sync audit --format json` output.
+
 - **sync**: TMS request URLs are built with the URL API: a trailing slash on `server:` no longer produces a doubled separator, a base path is preserved, and a URL with a query string or fragment is rejected instead of silently truncating the API path. TMS timeouts now exit with the network-error code (5) instead of 1, TMS error messages redact credentials embedded in the server URL, and `deepl sync pull` enforces a 32 MiB cap on the response body while reading it, instead of after the whole payload had been parsed.
+
 - **api**: Non-idempotent POST requests are no longer re-submitted after a client-side timeout. Every failure short of a 4xx reached the retry loop for all HTTP methods, so a batch or document upload that outlived the 30 s timeout was silently re-sent up to three more times — each already accepted and billed server-side (confirmed with server-side request counts: 4 per timed-out translate and upload), with the worst case being duplicate admin API keys whose secret is returned only once. Automatic retry is now restricted to idempotent methods (GET, HEAD, PUT, DELETE); a POST is replayed only on an error that proves the request never reached the server (`ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`). A 429 is still retried for every method, honoring `Retry-After`.
+
 - **api**: A client-side timeout now exits 5 (network error) instead of 6 (invalid input), matching the documented exit-code contract. Error classification substring-matched the message and missed axios's `timeout of 30000ms exceeded` (`ECONNABORTED` and `ERR_CANCELED` were absent entirely), falling through to `ValidationError` — so CI that retries on 5 and hard-fails on 6 did exactly the wrong thing on a flaky network. Classification now branches on `error.code` and the absence of a response. An HTTP 401 is likewise mapped to `AuthError` (exit 2) instead of falling through to exit 6.
+
 - **api**: Retries run under an overall time budget rather than only a per-attempt timeout — twice the request timeout by default — so a never-responding server no longer holds a single command for two minutes (measured 125 s before). Honest `Retry-After` waits are not charged against the budget.
+
 - **api**: The Trace ID quoted in an error message now belongs to the request that failed rather than the client's last-seen response, so concurrent requests no longer cross-quote each other's Trace IDs.
+
 - **api**: Errors already classified by the API client are no longer re-classified when a client wraps its own error handling, which could turn a validation error into a network error and drop its recovery hint. Error messages also no longer print a doubled `Network error: Network error:` prefix.
+
 - **api**: The document translation result endpoint is never retried — the download is effectively single-use, so a retry after a timeout on a large file could permanently lose an already-billed translation — and document transfers get their own larger timeout.
+
 - **voice**: `deepl voice` now actually reconnects after a transport failure. The socket `error` handler marked the stream ended before the `close` event that always follows arrived, so the reconnect path (up to 3 attempts, `--reconnect` on by default) was unreachable for a real network drop — only a clean remote close ever reconnected. A reconnect that exhausts its attempts now closes the audio input instead of leaving the stream generator awaiting forever.
+
 - **formats**: YAML files using merge keys (`<<: *anchor`) or aliases to anchored maps and sequences no longer fail at sync write-back with `Expected YAML collection`. Extraction previously emitted paths through aliases that reconstruction could not apply; aliased collections are now translated at their anchor site and the references round-trip untouched.
+
 - **sync**: ICU plural messages using `offset:N` and messages with single-quote-escaped braces (`'{'`, `'}'`, `''` for a literal apostrophe, `'#'` in plural context) are now recognized and preserved instead of falling back to raw machine translation, which demonstrably corrupts ICU keywords and selectors. `sync validate` placeholder checking is also ICU-aware: plural/select branch braces are treated as structure, eliminating spurious `Extra placeholders in translation` warnings for translated branch bodies.
+
 - **sync**: Template literals containing regex metacharacters in scanned source code (e.g. `` t(`item(${i}`) ``) no longer abort context resolution with a raw `SyntaxError` or silently mismatch keys — all metacharacters are escaped before the scan pattern is compiled.
+
 - **watch**: `filesWatched` statistics now report the actual number of files under watch — seeded from the watcher's inventory once the initial scan completes and tracked live on add/unlink. It was previously never incremented and always reported 0.
+
 - **cli**: The global `--timeout`/`--max-retries` flags now also apply to the API-key validation requests made by `deepl init` and `deepl auth set-key`, which previously always used the 30 s default.
+
 - **utils**: Atomic file writes preserve the target's existing permissions instead of resetting them to the umask default — e.g. `deepl write --fix` on a `0600` secrets file no longer leaves it world-readable at `0644`.
+
 - **docs**: README translate examples no longer show a `Translation (XX):` label the CLI never emits; corrected `--model-type` (no CLI default), `--config` precedence (replaces the config file only; the cache path is unaffected), unknown-command and `deepl detect` sample output, and the nonexistent 10 MB PDF cap (the document limit is 30 MB uniformly). README now covers `deepl sync`, `deepl tm`, and all nine `style-rules` subcommands, with dead in-page anchors repaired and `docs/SYNC.md` listed under Documentation.
+
 - **docs**: TROUBLESHOOTING's exit-code table gains codes 10–12 (SyncDrift, SyncConflict, PartialFailure) and its environment-variable table gains `TMS_API_KEY`, `TMS_TOKEN`, `FORCE_COLOR`, `TERM`; sync JSON-contract stability promises are rescoped from "1.x" to "within a major version"; the GitHub Actions recipes in docs/SYNC.md pin Node 24; CONTRIBUTING no longer cites Zod (validation is commander `Option.choices()` plus hand-written validators); examples/README no longer references a nonexistent `sample-files/` directory.
+
 - **cli**: Subcommand parse errors (unknown subcommand, unknown option, invalid choice, missing argument) exit 6 (invalid input) as documented, instead of 1 ("CLI crashed"). Top-level parse errors already exited 6; the mapping is now uniform across all subcommands, so CI scripts following the documented exit-code table no longer misread a typo as a crash.
+
 - **usage**: Text and table output no longer report duration-billed products (e.g. speech-to-text minutes) as zero characters — duration billing units are recognized, rendered in h/m/s as documented, and product names print in the documented snake_case. `--format json` was already correct and is unchanged.
+
 - **admin**: An entitlement failure (valid key without admin scope) no longer suggests re-running `deepl init` / `auth set-key` — the suggestion now explains that the admin API requires an administrator API key. Exit code and classification are unchanged.
+
 - **cli**: The non-TTY `--format table` fallback notice carries the documented `WARN` prefix at all six call sites, matching `sync resolve`'s existing convention.
+
 - **glossary**: Scoped commands (`show`, `entries`, `delete`) no longer emit an unrelated org glossary's "empty dictionaries" warning during name resolution — the warning appears only when the glossary actually operated on is affected.
+
 - **sync**: `sync resolve` prints each parse-error fallback warning once (relative path) instead of twice.
+
 - **write**: The unsupported-style error links to the published docs URL instead of a `docs/API.md` path npm users don't have.
+
 - **config**: `config delete` and the config read paths can no longer walk or mutate the prototype chain — `__proto__`/`constructor`/`prototype` segments are rejected, completing the `config set` hardening.
+
 - **perf**: `sync audit` registration no longer loads fast-glob on every CLI invocation (lazy import, matching its sibling subcommands).
 
 ### Security
 
 - **config**: `ConfigService.save()` writes through an unpredictably named temp file created with an exclusive flag, instead of a fixed `config.json.tmp`. A symlink planted at the predictable path redirected the config — which holds the API key in plaintext — to a path of the planter's choosing, and the subsequent rename left `config.json` as that symlink, so every later write followed it too. The mode is also applied with `chmod` after creation, which the umask cannot widen.
+
 - **tests**: The test suite no longer inherits real credentials or the real config directory. Suites that spawn the bare `deepl` command cannot be intercepted by nock, so they reached the live DeepL API with whatever key was exported and read and wrote the developer's cache database; cached responses matching this suite's fixtures were recovered from a real cache, confirming it had happened. `globalSetup` now clears `DEEPL_API_KEY`, `TMS_API_KEY` and `TMS_TOKEN` and points `DEEPL_CONFIG_DIR` at a temporary directory before workers fork.
+
 - **formats**: The prototype-pollution guard in the JSON parser is now pinned by tests. Replacing `Object.defineProperty` with plain assignment previously left the whole suite green: on a fresh object `obj['__proto__'] = value` retargets that object's prototype rather than `Object.prototype`, so the translation was silently dropped while the negative pollution assertion still passed.
+
 - **ci**: The release workflow refuses to create a GitHub Release when the pushed tag does not match `package.json`. A tag can be pushed at any commit, so without the check a mislabelled tag would mint a Release whose title disagrees with the version it contains.
+
 - **translate/sync**: Placeholder restoration no longer hangs the CLI with unbounded memory growth. `restorePlaceholders` looped `while (restored.includes(placeholder))`, replacing one occurrence per pass — so when the preserved original itself contained the placeholder token, every pass re-inserted it and the guard never went false. Measured before the fix: the input `{__VAR_0__}` grew from 9 to 400,009 bytes across 200,000 iterations without converging, and the real function had to be killed. It needed no attacker and no network: `preserveVariables`' pattern matches `{__VAR_0__}` (underscores and digits are in its character class), variable preservation runs unconditionally, and restoration also runs on **cached** results — so a locale value of that shape hung the process with no API call. Each placeholder is now restored in a single pass, using the function form of the replacement so `$&`/`$1` inside a preserved value stay literal.
+
 - **sync**: Bucket `include` globs can no longer escape the project root, and `--dry-run` no longer modifies the working tree. `include` entries were validated only as non-empty strings, while `target_path_pattern` a few lines later already rejected `..`. The unvalidated glob's literal prefix was resolved and handed to the stale-`.bak` sweep, which recursed with **no containment check** — deleting every old `*.bak` it found and *re-creating* any file whose `.bak` existed while the live file was missing or empty. Verified: `include: "../../../../../../**/*.json"` produced a sweep root of `/var`, an out-of-root `.bak` was deleted and its sibling resurrected with the backup's contents. Two things made it worse: the sweep was gated only on watch runs, so it ran under `--dry-run` — the flag a cautious user reaches for to avoid side effects — and its errors were swallowed entirely, so it was silent. `include` entries are now rejected at config load for traversal segments and absolute paths (the check the `sync init` wizard already applied, which simply did not exist on the load path), the sweep independently refuses any root outside the project and logs the attempt, the sweep is skipped under `--dry-run`, and its failures are reported instead of discarded.
+
 - **deps**: Resolved four production-dependency advisories flagged by `npm audit --omit=dev` via lockfile-only transitive bumps (no `package.json` ranges changed): `brace-expansion` 5.0.5 → 5.0.6 (GHSA-jxxr-4gwj-5jf2, ReDoS), `form-data` → 4.0.6 (GHSA-hmw2-7cc7-3qxx, CRLF injection), and `ws` 8.20.0 → 8.21.0 (GHSA-58qx-3vcg-4xpx and GHSA-96hv-2xvq-fx4p, uninitialized-memory disclosure and memory-exhaustion DoS). Production `npm audit` is back to zero vulnerabilities, unblocking the CI audit gate.
+
 - **deps**: Resolved two further `brace-expansion` denial-of-service advisories disclosed after the bump above: `brace-expansion` 5.0.6 → 5.0.8 (GHSA-3jxr-9vmj-r5cp, exponential-time expansion of consecutive non-expanding `{}` groups; GHSA-mh99-v99m-4gvg, unbounded expansion length causing an out-of-memory crash). Reached in production through `minimatch`, which accepts `^5.0.5`, so this is again a lockfile-only bump with no `package.json` range changes. Dev-tree instances of the same advisories are intentionally left in place: npm's proposed remediation downgrades `jest` 30 → 25 and `ts-jest` 29 → 27, `devDependencies` are not installed by consumers, and the CI audit gate is production-only.
+
 - **formats**: The YAML i18n parser no longer expands aliases at all, structurally removing the denial-of-service vector where documents with exponentially-expanding anchors ("alias bombs") or self-referential anchors hung `deepl sync` indefinitely. Aliased content is extracted and translated only at its anchor site and every alias — including merge keys — round-trips as a reference, so alias bombs now parse in milliseconds as plain references instead of being rejected by the interim expansion budget.
+
 - **formats**: Android XML translations containing `]]>` are refused instead of being written into a CDATA section, where they closed the section and had their remainder parsed as XML — injecting elements into generated resource files. This was reachable without a malicious API response, since a failed translation is written through verbatim and the source file is used as the template for a missing target locale.
+
 - **sync**: Target-path containment is enforced *before* any target file is read or backed up. The check previously ran after the read and the `.bak` copy, so a committed symlink directory plus a crafted `target_path_pattern` could read an out-of-root file into memory and clobber an out-of-root `.bak` sibling before the write was blocked — and the swallowed error made it repeat per locale × file. A containment violation now also aborts the sync instead of being absorbed, and the bucket pre-read loop (which had no containment check at all) now asserts it too.
+
 - **sync**: `source_locale` and `target_locales` are validated against a BCP-47 whitelist at config load (previously a three-substring denylist), and `target_path_pattern` may not contain a `.git` or `.github` path segment — closing a write primitive where a "locale" like `config` plus a pattern like `.git/{locale}` wrote inside `.git/`. **Migration**: underscore-style locale codes (`pt_BR`) are now rejected; use hyphenated BCP-47 (`pt-BR`).
+
 - **sync**: `.deepl-sync.yaml` discovery stops at the repository boundary (the first directory containing `.git`) instead of walking to the filesystem root, so a config planted in an ancestor directory outside the repo is no longer silently adopted as project root.
+
 - **init**: `deepl init` masks the API-key prompt instead of echoing the key in cleartext into terminal scrollback.
+
 - **logger**: Credential redaction now recurses through objects, arrays, and `Error` values (with cycle protection) instead of applying only to strings, so a dumped error object can no longer print an `Authorization` header or API key verbatim.
+
 - **glossary**: Server-supplied glossary names are sanitized before terminal display, blocking ANSI escape injection via glossaries shared within a team account. Style-rule names were already sanitized; the two sites now match.
+
 - **config**: `deepl config set` rejects `__proto__`, `constructor`, and `prototype` path segments and resolves keys with `Object.hasOwn`, so crafted paths can no longer pollute `Object.prototype`.
+
 - **batch**: `translate --pattern` values containing `..` can no longer write translated output outside `--output-dir` (the default output branch now enforces the same containment as `--output-pattern`), and directory batch translation no longer follows symlinks out of the input directory.
+
 - **ci**: `ci.yml` and `security.yml` explicitly request `contents: read` instead of inheriting the repository default token permissions.
+
 ## [1.2.0] - 2026-04-25
 
 ### Added
diff --git a/docs/API.md b/docs/API.md
index 078dabff..057434fb 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -760,7 +760,7 @@ This table is maintained by hand and reflects what the API **accepts**, which is
 
 The 14 languages are generated from `GET /v3/languages?resource=write` into `src/data/language-entries.ts` by `npm run generate:languages`, alongside the translation list, and `npm run check:languages` reports drift in either. The `WriteLanguage` type is derived from that same list, so a language added upstream widens it on regenerate rather than needing a second hand edit.
 
-Unlike `translate --to`, which passes a well-formed unknown code to the API, `write` and `correct` **reject** a code outside this list locally (exit 6) and name every valid option. The set is small enough to enumerate, so that beats a round trip — the reasoning that makes permissiveness right for translation does not transfer to 14 of 125 languages.
+`write` and `correct` check `--lang` against this list locally and name every valid option, because the set is small enough to enumerate in an error. The list is a snapshot, though, so a code that is *shaped* like a language tag but absent from it is sent to the API with the list as a warning rather than rejected — otherwise a language DeepL adds is unreachable until the snapshot is regenerated. Input that is not shaped like a language tag still exits 6 locally.
 
 **Output Options:**
 
@@ -2327,14 +2327,10 @@ deepl usage
 # API Key Usage:
 #   Used: 1,880,000 / unlimited
 #
-# Speech-to-Text Usage:
-#   Used: 12m 34s / 1h 0m 0s (20.9%)
-#   Remaining: 47m 26s
-#
 # Product Breakdown:
 #   translate: 900,000 characters (API key: 880,000)
 #   write: 1,250,000 characters (API key: 1,000,000)
-#   speech_to_text: 12m 34s (API key: 12m 34s)
+#   speech_to_text: 12m 34s (API key)
 ```
 
 **Output Fields:**
@@ -2348,8 +2344,7 @@ deepl usage
 
 - **Billing Period**: Start and end dates of the current billing cycle
 - **API Key Usage**: Characters used by this specific API key (vs. the whole account)
-- **Speech-to-Text Usage**: Duration used and remaining for speech-to-text quota (displayed as hours/minutes/seconds)
-- **Product Breakdown**: Per-product character counts (translate, write) and durations (speech_to_text) with API key-level breakdown
+- **Product Breakdown**: Per-product character counts (translate, write) and durations (speech_to_text) with the API-key-level figure alongside. A duration-billed product shows `(API key)` when the response carries no account-wide total, rather than repeating the key's own figure as if it were one.
 
 **Notes:**
 

From af3bf4cf3075653e86a1c3a2bfb92c7b3e41b7b0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 00:53:30 -0400
Subject: [PATCH 055/256] fix(usage): render a null count as unreported instead
 of throwing

`unit_count: null` reached formatNumber on the non-duration path and threw a
TypeError, so one unexpected null in the response took down `deepl usage`
entirely rather than leaving one field blank.

Also records in the changelog that write/correct entries for the five recased
target codes are unreachable. They are left to their TTL rather than dropped: the
key is a hash, so those rows cannot be distinguished from the ones for de/en/es/fr,
which still serve, and purging the namespace would discard far more than it
reclaimed.
---
 CHANGELOG.md                     |  2 ++
 src/cli/commands/usage.ts        |  6 ++++--
 src/storage/cache.ts             | 17 +++++++++--------
 tests/unit/cache-service.test.ts |  6 ++++--
 4 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3c34936f..7828a813 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -137,6 +137,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **docs**: Three passages described behaviour that no longer exists — the `voice --glossary` row had picked up `translate`'s repeatable/`--from` semantics (voice takes one glossary and requires neither), the `write` reference still said an unknown code is rejected locally, and the `usage` reference still documented the removed Speech-to-Text section along with output showing the duplicated API-key figure.
 
+- **cache**: `write` and `correct` entries cached for the five target codes whose casing changed (`en-GB`, `en-US`, `pt-BR`, `pt-PT`, `zh-Hans`) are no longer reachable, since those keys hash the target language. They are left to expire with their 30-day TTL rather than dropped: the key is a hash, so the affected rows cannot be told apart from the ones for `de`/`en`/`es`/`fr`, which are unaffected and still serve.
+
 - **cache**: **The translation cache keyed on too little and could serve the wrong text.** `translationMemoryId`, `translationMemoryThreshold`, `--ignore-tags`, `--splitting-tags`, `--non-splitting-tags`, `--outline-detection` and `--preserve-formatting` were absent from the key, so `deepl translate "Hello" --to de` and the same command with `--translation-memory my-tm` collided: the second returned the cached non-TM translation, never consulted the memory, and reported `cached: true`. Likewise two runs differing only in `--ignore-tags` returned each other's output. `preserveFormatting` had been excluded on the grounds that it does not affect output, but `preserve_formatting` suppresses the sentence-boundary punctuation and case correction, which shows up in the text. **Every translation entry cached by an earlier version is retired**, not only the ones using these options: the service merges a `preserveFormatting` default, so it is always part of the key. The cache schema version is bumped, so those rows are dropped on first open rather than sitting unreachable until their 30-day TTL — `write` and `correct` entries key the same way they always did and are kept. The first translation of any given text after upgrading is refetched.
 
 - **translate**: **A rejected language no longer costs one API round trip per batch.** Because validation defers well-formed unknown codes to the API, a two-letter typo reaches it — and a directory translation asked the same rejected question once per batch, so `deepl translate ./docs --to ex` on 200 files made 200 failing requests to be told the same thing 200 times. An unsupported `target_lang` or `source_lang` is a property of the request, not of one batch, so the remaining batches now fail without being sent; errors specific to a batch (a rate limit, say) still let the run continue. Relatedly, local validation used to be what pointed at `deepl languages`, and deferring left users with a bare `Value for 'target_lang' not supported.` from the server: a code the bundled snapshot does not list now says so up front, before anything is sent or billed.
diff --git a/src/cli/commands/usage.ts b/src/cli/commands/usage.ts
index 870721b2..0b44e7dd 100644
--- a/src/cli/commands/usage.ts
+++ b/src/cli/commands/usage.ts
@@ -78,8 +78,10 @@ export class UsageCommand {
     const remaining = characterLimit - characterCount;
     const isHighUsage = characterLimit > 0 && (characterCount / characterLimit) > 0.8;
 
-    const formatNumber = (num: number): string => {
-      return num.toLocaleString('en-US');
+    // Tolerates a null the response may carry where the type says number: the
+    // alternative is `deepl usage` throwing on a field it only displays.
+    const formatNumber = (num: number | null | undefined): string => {
+      return typeof num === 'number' && Number.isFinite(num) ? num.toLocaleString('en-US') : '—';
     };
 
     const lines: string[] = [];
diff --git a/src/storage/cache.ts b/src/storage/cache.ts
index 72894162..15a7ac6e 100644
--- a/src/storage/cache.ts
+++ b/src/storage/cache.ts
@@ -69,8 +69,8 @@ function isCorruptionError(error: unknown): boolean {
  *
  * Version 2 marks a change in how translation cache keys are computed. Opening
  * an older DB drops the `translation:` rows -- no reader can reach them again --
- * and leaves every other namespace in place, since their keys are unchanged. The
- * table layout is identical in all versions, so nothing is migrated.
+ * and leaves every other namespace in place. The table layout is identical in all
+ * versions, so nothing is migrated.
  */
 const CACHE_SCHEMA_VERSION = 2;
 
@@ -245,12 +245,13 @@ export class CacheService {
     `);
 
     if (userVersion < CACHE_SCHEMA_VERSION) {
-      // Only the translation namespace: its key derivation changed, so those rows
-      // address entries no reader can reach again, and leaving them would let
-      // them occupy the size budget and `cache stats` until their TTL expires.
-      // Every other namespace (write, correct) keys the same way it always did
-      // and is read in place. A fresh DB has no rows, so this is a no-op on
-      // first open.
+      // Only the translation namespace. Its keys all changed, so every row is
+      // unreachable and would otherwise occupy the size budget and `cache stats`
+      // until its TTL expires. `write`/`correct` keys changed only for the five
+      // target codes whose casing moved, and a hash cannot say which rows those
+      // are -- dropping the namespace would discard far more reachable entries
+      // than it reclaimed, so those few expire on their own. A fresh DB has no
+      // rows, so this is a no-op on first open.
       this.db.exec("DELETE FROM cache WHERE key LIKE 'translation:%'");
       this.db.exec(`PRAGMA user_version = ${CACHE_SCHEMA_VERSION}`);
     }
diff --git a/tests/unit/cache-service.test.ts b/tests/unit/cache-service.test.ts
index 015b48b7..ef28155c 100644
--- a/tests/unit/cache-service.test.ts
+++ b/tests/unit/cache-service.test.ts
@@ -105,8 +105,10 @@ describe('CacheService', () => {
     });
 
     it('should drop only translation rows when upgrading an older database', () => {
-      // Translation keys are derived differently from version 2 on, so those rows
-      // are unreachable; every other namespace keys the same way and is kept.
+      // Every translation key changed, so those rows are unreachable. write and
+      // correct keys changed only for the five recased target codes, which a hash
+      // cannot identify, so that namespace is left to its TTL rather than dropped
+      // wholesale.
       const db = (cacheService as any).db;
       db.exec('PRAGMA user_version = 1');
       cacheService.set('translation:oldhash', { text: 'unreachable' });

From ca9e6f575295b56639c4d200e1e4abe16dd2069b Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 09:02:37 -0400
Subject: [PATCH 056/256] fix(translate): validate languages in one place for
 every input mode

Language validation was spread over eight call sites in five files and
only three paired the target-code check with the extended-tier check, so
file, directory and --dry-run runs accepted constrained options that text
runs rejected locally: --to af --formality more exited 6 for text and went
to the network for a file, and a dry run reported --to 'not!!a!!lang' as
runnable.

validateTranslationLanguages() is now the single gate. Each mode passes
only the flags it honours, so nothing is refused over a flag its mode
discards -- a document run still accepts --model-type, which it strips
after warning, and a directory run still accepts --glossary, which it
ignores.

Also folds in the two rough edges around the same code path: --from is
validated, with its own wording, and the deferral note is said once per
code per run rather than once per call site. The extended-tier glossary
arm reads hasGlossarySelection(), so an empty repeatable --glossary list
no longer counts as selecting one.

Closes cli-01on.2, cli-01on.1, cli-01on.7
---
 CHANGELOG.md                                  |   2 +
 src/cli/commands/register-translate.ts        |  29 ++-
 .../directory-translation-handler.ts          |  23 +-
 .../translate/document-translation-handler.ts |  12 +-
 .../translate/file-translation-handler.ts     |  14 +-
 src/cli/commands/translate/index.ts           |   7 +
 .../translate/text-translation-handler.ts     |   9 +-
 src/cli/commands/translate/translate-utils.ts |  96 ++++++--
 tests/e2e/cli-success-paths.e2e.test.ts       |  43 ++++
 .../cli-dry-run.integration.test.ts           | 103 +++++++-
 .../directory-translation-handler.test.ts     |  34 ++-
 tests/unit/translate-command.test.ts          | 225 ++++++++++++++++++
 tests/unit/translate-utils.test.ts            | 111 ++++++++-
 13 files changed, 661 insertions(+), 47 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7828a813..2c19cfd6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -115,6 +115,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
 
+- **translate**: **File, directory and `--dry-run` runs skipped the extended-tier language checks that text runs made.** `translate "Hi" --to af --formality more` exited 6 locally, while the same flags on a file or a directory reached the network and came back as an API rejection; `--dry-run` reported both as runnable, along with `--to 'not!!a!!lang'`, which every real run refuses. Language validation was spread over eight call sites in five files and only three paired the code check with the extended-tier check, which is how the modes drifted apart. There is now one entry point that every input mode calls, so a constrained option fails before anything is sent whichever mode handles the argument. Each mode passes only the flags it actually honours, so nothing is refused over a flag its mode discards: a document run still accepts `--model-type`, which it strips after warning, and a directory run still accepts `--glossary`, which it ignores. **`--from` is validated too** — it never was, so a malformed source language went unremarked until the API answered — and is named as such: `Invalid source language code: "grman"`. The "not in the bundled language list; deferring to the API" note is now said once per code per run instead of once per call site, which had it printing twice for `--to de,ex` and four times for `--to ex,zz` on a directory. An empty repeatable `--glossary` list no longer trips the "do not support glossaries" rejection, and a dry run lowercases `--to`/`--from` the way the real run does.
+
 - **translate**: **A directory translation where every file failed exited 0.** The summary reported `✓ Successful: 0 / ✗ Failed: N` and the command still looked like success to a script or CI job. Since language validation defers unknown codes to the API, a plain `--to` typo took this path: on 1.x it exited 6 locally, and in this release it printed a failure list and exited 0. A run with no successes now exits 1, and a partial failure exits 12, matching what `sync` already does.
 
 - **translate**: **The rejected-request abort covered only plain-text batches.** `.txt` and `.md` files are grouped into batches and stopped after the first rejection, but `.json`, `.yaml`, `.html`, `.srt` and `.xliff` go through the per-file path, which still spent one round trip per file collecting the same answer. That path stops the same way now, and files that were never sent are reported as skipped rather than as failures carrying another batch's error. The classifier also checks the error class before the message: a 5xx interpolates the upstream body, so a gateway error quoting `target_lang` no longer aborts a run that is otherwise succeeding, while a refused key or an exhausted quota — as request-wide as a bad code — now do.
diff --git a/src/cli/commands/register-translate.ts b/src/cli/commands/register-translate.ts
index ae76845b..425e6969 100644
--- a/src/cli/commands/register-translate.ts
+++ b/src/cli/commands/register-translate.ts
@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
 import { createTranslateCommand, type ServiceDeps } from './service-factory.js';
+import { validateTranslationLanguages } from './translate/translate-utils.js';
 import {
   MAX_GLOSSARIES_PER_REQUEST,
   applyGlossarySourceLang,
@@ -182,15 +183,35 @@ Examples:
         }
 
         if (options.dryRun) {
-          const targetLangs = options.to!.split(',').map(l => l.trim());
+          // Normalized here because the real run lowercases inside
+          // TranslateCommand, past the point a dry run returns.
+          options.to = options.to!.toLowerCase();
+          if (options.from) {
+            options.from = options.from.toLowerCase();
+          }
+
+          const targetLangs = options.to.split(',').map(l => l.trim());
+          const isDir = !!text && fs.existsSync(text) && fs.statSync(text).isDirectory();
+          const isFile = !!text && !isDir && fs.existsSync(text) && fs.statSync(text).isFile();
+
+          // A dry run reports a command as runnable, so it rejects whatever the
+          // real run rejects locally. Which extended-tier arms hold depends on the
+          // mode that will handle this argument: directory mode ignores --glossary
+          // but sends --model-type, while a document run discards --model-type
+          // after warning, so asserting either arm for both would refuse a command
+          // that works.
+          validateTranslationLanguages(
+            targetLangs,
+            isDir
+              ? { from: options.from, formality: options.formality, modelType: options.modelType }
+              : { from: options.from, formality: options.formality, glossary: options.glossary },
+          );
+
           const lines: string[] = [
             chalk.yellow('[dry-run] No translations will be performed.'),
           ];
 
           if (text) {
-            const isDir = fs.existsSync(text) && fs.statSync(text).isDirectory();
-            const isFile = !isDir && fs.existsSync(text) && fs.statSync(text).isFile();
-
             if (isDir) {
               lines.push(chalk.yellow(`[dry-run] Would translate directory: ${text}`));
               lines.push(chalk.yellow(`[dry-run] Output directory: ${options.output ?? '<required>'}`));
diff --git a/src/cli/commands/translate/directory-translation-handler.ts b/src/cli/commands/translate/directory-translation-handler.ts
index c206e8a8..26576c4d 100644
--- a/src/cli/commands/translate/directory-translation-handler.ts
+++ b/src/cli/commands/translate/directory-translation-handler.ts
@@ -4,9 +4,26 @@ import { ValidationError } from '../../../utils/errors.js';
 import { Logger } from '../../../utils/logger.js';
 import { ExitCode } from '../../../utils/exit-codes.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
-import { warnIgnoredOptions, validateLanguageCodes } from './translate-utils.js';
+import {
+  warnIgnoredOptions,
+  validateTranslationLanguages,
+  type TranslationLanguageConstraints,
+} from './translate-utils.js';
 import { buildBaseTranslationOptions } from './translation-options-factory.js';
 
+/**
+ * The constrained flags this mode passes on to the request. `--glossary` is not
+ * one of them — directory mode announces it as ignored and resolves no glossary —
+ * so a glossary must not fail a directory run the way it fails a text one.
+ */
+function honouredConstraints(options: TranslateOptions): TranslationLanguageConstraints {
+  return {
+    from: options.from,
+    formality: options.formality,
+    modelType: options.modelType,
+  };
+}
+
 export class DirectoryTranslationHandler {
   constructor(public ctx: HandlerContext) {}
 
@@ -20,7 +37,7 @@ export class DirectoryTranslationHandler {
 
     if (options.to.includes(',')) {
       const targetLangs = options.to.split(',').map(lang => lang.trim());
-      validateLanguageCodes(targetLangs);
+      validateTranslationLanguages(targetLangs, honouredConstraints(options));
 
       const allOutputs: string[] = [];
 
@@ -37,7 +54,7 @@ export class DirectoryTranslationHandler {
   }
 
   private async translateSingleTarget(dirPath: string, options: TranslateOptions): Promise<string> {
-    validateLanguageCodes([options.to]);
+    validateTranslationLanguages([options.to], honouredConstraints(options));
 
     const translationOptions = buildBaseTranslationOptions(options);
 
diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index 17209a79..30ae1ffe 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -4,11 +4,7 @@ import { ValidationError } from '../../../utils/errors.js';
 import type { Language } from '../../../types/index.js';
 import type { DocumentTranslationOptions } from '../../../types/api.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
-import {
-  warnIgnoredOptions,
-  validateLanguageCodes,
-  validateExtendedLanguageConstraints,
-} from './translate-utils.js';
+import { warnIgnoredOptions, validateTranslationLanguages } from './translate-utils.js';
 import { buildBaseTranslationOptions, applyGlossarySelection } from './translation-options-factory.js';
 import { applyGlossarySourceLang } from '../../../utils/glossary-params.js';
 
@@ -30,10 +26,10 @@ export class DocumentTranslationHandler {
     const { modelType: _model, tagHandling: _tags, tagHandlingVersion: _version, ...rest } = options;
     options = rest;
 
-    validateLanguageCodes([options.to]);
     // Documents accept glossaries, so the extended-tier constraint applies here
-    // too: checked before the upload rather than left to the API.
-    validateExtendedLanguageConstraints(options.to, options);
+    // too: checked before the upload rather than left to the API. After the strip
+    // above, so the flags this mode discards cannot fail a command it accepts.
+    validateTranslationLanguages([options.to], options);
 
     // The API rejects a document glossary without source_lang: "source_lang has
     // to be specified in order to use a glossary."
diff --git a/src/cli/commands/translate/file-translation-handler.ts b/src/cli/commands/translate/file-translation-handler.ts
index 64d4a885..fddef98d 100644
--- a/src/cli/commands/translate/file-translation-handler.ts
+++ b/src/cli/commands/translate/file-translation-handler.ts
@@ -7,7 +7,7 @@ import { Logger } from '../../../utils/logger.js';
 import { safeReadFileSync } from '../../../utils/safe-read-file.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
 import {
-  validateLanguageCodes,
+  validateTranslationLanguages,
   isTextBasedFile,
   isStructuredFile,
   getFileSize,
@@ -33,7 +33,7 @@ export class FileTranslationHandler {
 
     if (options.to.includes(',')) {
       const targetLangs = options.to.split(',').map(lang => lang.trim());
-      validateLanguageCodes(targetLangs);
+      validateTranslationLanguages(targetLangs, options);
 
       const validTargetLangs = targetLangs as Language[];
 
@@ -106,7 +106,13 @@ export class FileTranslationHandler {
       return this.documentHandler.translateDocument(filePath, options);
     }
 
-    validateLanguageCodes([options.to]);
+    // This path resolves no glossary, so the glossary arm is left out: rejecting
+    // over a flag the request never carries would refuse a run that works.
+    validateTranslationLanguages([options.to], {
+      from: options.from,
+      formality: options.formality,
+      modelType: options.modelType,
+    });
 
     const translationOptions = buildBaseTranslationOptions(options);
 
@@ -121,7 +127,7 @@ export class FileTranslationHandler {
   }
 
   async translateTextFile(filePath: string, options: TranslateOptions): Promise<string> {
-    validateLanguageCodes([options.to]);
+    validateTranslationLanguages([options.to], options);
 
     applyGlossarySourceLang(
       options,
diff --git a/src/cli/commands/translate/index.ts b/src/cli/commands/translate/index.ts
index c8e3a9c5..b702a700 100644
--- a/src/cli/commands/translate/index.ts
+++ b/src/cli/commands/translate/index.ts
@@ -1,4 +1,8 @@
 export type { TranslateOptions, TranslationParams, HandlerContext } from './types.js';
+export type {
+  ExtendedLanguageConstraints,
+  TranslationLanguageConstraints,
+} from './translate-utils.js';
 export {
   VALID_LANGUAGES,
   EXTENDED_ONLY_LANGUAGES,
@@ -9,6 +13,9 @@ export {
   MAX_CUSTOM_INSTRUCTION_CHARS,
   warnIgnoredOptions,
   validateLanguageCodes,
+  validateSourceLanguage,
+  validateTranslationLanguages,
+  resetDeferredLanguageWarnings,
   validateExtendedLanguageConstraints,
   validateXmlTags,
   buildTranslationOptions,
diff --git a/src/cli/commands/translate/text-translation-handler.ts b/src/cli/commands/translate/text-translation-handler.ts
index d2cf8f61..d127f649 100644
--- a/src/cli/commands/translate/text-translation-handler.ts
+++ b/src/cli/commands/translate/text-translation-handler.ts
@@ -4,8 +4,7 @@ import { Logger } from '../../../utils/logger.js';
 import { ValidationError, AuthError } from '../../../utils/errors.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
 import {
-  validateLanguageCodes,
-  validateExtendedLanguageConstraints,
+  validateTranslationLanguages,
   validateXmlTags,
   warnIgnoredOptions,
   MAX_CUSTOM_INSTRUCTIONS,
@@ -42,8 +41,7 @@ export class TextTranslationHandler {
       return this.translateToMultiple(text, options);
     }
 
-    validateLanguageCodes([options.to]);
-    validateExtendedLanguageConstraints(options.to, options);
+    validateTranslationLanguages([options.to], options);
 
     applyGlossarySourceLang(
       options,
@@ -167,8 +165,7 @@ export class TextTranslationHandler {
     warnIgnoredOptions('multi-target', options, supported);
 
     const targetLangs = options.to.split(',').map(lang => lang.trim());
-    validateLanguageCodes(targetLangs);
-    validateExtendedLanguageConstraints(options.to, options);
+    validateTranslationLanguages(targetLangs, options);
 
     applyGlossarySourceLang(
       options,
diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index 4e448d0b..d6819716 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -3,6 +3,7 @@ import * as path from 'path';
 import { Language, Formality } from '../../../types/index.js';
 import { ValidationError } from '../../../utils/errors.js';
 import { Logger } from '../../../utils/logger.js';
+import { hasGlossarySelection } from '../../../utils/glossary-params.js';
 import {
   getAllLanguageCodes,
   getExtendedLanguageCodes,
@@ -58,32 +59,95 @@ export function warnIgnoredOptions(mode: string, options: TranslateOptions, supp
   }
 }
 
+/**
+ * Codes already deferred to the API in this process. One run validates the same
+ * target list from more than one place — the registrar's dry run, a mode's
+ * multi-target split, then its per-target pass — and the note is worth saying
+ * once, not once per call site.
+ */
+const deferredCodesWarned = new Set<string>();
+
+/**
+ * Clears the deferral-warning state. Tests asserting the warning need this in
+ * `beforeEach`: the set is module state, which clearing Jest mocks leaves alone.
+ */
+export function resetDeferredLanguageWarnings(): void {
+  deferredCodesWarned.clear();
+}
+
 /**
  * Rejects input that is not shaped like a language tag. Codes the bundled
  * snapshot does not list are passed through: GET /v3/languages is the authority
  * on which languages exist and the snapshot can lag it, so an unknown code is
  * the API's to accept or reject with a 400 of its own.
+ *
+ * `role` names the flag in the rejection, since `--from` and `--to` are rejected
+ * for the same reasons and a user needs to know which one to fix.
  */
+function validateLanguageCode(langCode: string, role: 'target' | 'source'): void {
+  if (VALID_LANGUAGES.has(langCode)) return;
+
+  if (looksLikeLanguageTag(langCode)) {
+    if (deferredCodesWarned.has(langCode)) return;
+    deferredCodesWarned.add(langCode);
+    // Said up front, before anything is sent or billed: the API answers an
+    // unknown code with a bare "target_lang not supported" that points nowhere.
+    Logger.warn(
+      `Note: "${langCode}" is not in the bundled language list; deferring to the API.\n` +
+        '      Run: deepl languages  to see the languages this build knows about.'
+    );
+    return;
+  }
+
+  throw new ValidationError(
+    `Invalid ${role} language code: "${langCode}".`,
+    'Run: deepl languages  to see all available languages'
+  );
+}
+
 export function validateLanguageCodes(langCodes: string[]): void {
   for (const lang of langCodes) {
-    if (VALID_LANGUAGES.has(lang)) continue;
-    if (looksLikeLanguageTag(lang)) {
-      // Said up front, before anything is sent or billed: the API answers an
-      // unknown code with a bare "target_lang not supported" that points nowhere.
-      Logger.warn(
-        `Note: "${lang}" is not in the bundled language list; deferring to the API.\n` +
-          '      Run: deepl languages  to see the languages this build knows about.'
-      );
-      continue;
-    }
-    throw new ValidationError(
-      `Invalid target language code: "${lang}".`,
-      'Run: deepl languages  to see all available languages'
-    );
+    validateLanguageCode(lang, 'target');
   }
 }
 
-export function validateExtendedLanguageConstraints(targetLang: string, options: TranslateOptions): void {
+/** Validates `--from`. Absent means auto-detect, which every mode allows. */
+export function validateSourceLanguage(from: string | undefined): void {
+  if (!from) return;
+  validateLanguageCode(from, 'source');
+}
+
+/**
+ * The flags whose extended-tier arms are checked below. Callers name only the
+ * flags the run will honour: the input modes disagree about which they keep, and
+ * refusing a command over a flag its mode discards contradicts that run.
+ */
+export interface ExtendedLanguageConstraints {
+  modelType?: string;
+  formality?: string;
+  glossary?: string | string[];
+}
+
+/** `ExtendedLanguageConstraints` plus the source language, for the entry point below. */
+export interface TranslationLanguageConstraints extends ExtendedLanguageConstraints {
+  from?: string;
+}
+
+/**
+ * The language gate for every translate input mode. One entry point because a
+ * mode that checked codes without the extended-tier arms accepted, and sent,
+ * commands its siblings rejected locally.
+ */
+export function validateTranslationLanguages(
+  targets: string[],
+  options: TranslationLanguageConstraints,
+): void {
+  validateSourceLanguage(options.from);
+  validateLanguageCodes(targets);
+  validateExtendedLanguageConstraints(targets.join(','), options);
+}
+
+export function validateExtendedLanguageConstraints(targetLang: string, options: ExtendedLanguageConstraints): void {
   const langs = targetLang.includes(',')
     ? targetLang.split(',').map(l => l.trim())
     : [targetLang];
@@ -101,7 +165,7 @@ export function validateExtendedLanguageConstraints(targetLang: string, options:
     throw new ValidationError(`Language(s) ${langList} do not support formality settings`);
   }
 
-  if (options.glossary) {
+  if (hasGlossarySelection(options)) {
     throw new ValidationError(`Language(s) ${langList} do not support glossaries`);
   }
 }
diff --git a/tests/e2e/cli-success-paths.e2e.test.ts b/tests/e2e/cli-success-paths.e2e.test.ts
index 7f907fc2..d1d2d818 100644
--- a/tests/e2e/cli-success-paths.e2e.test.ts
+++ b/tests/e2e/cli-success-paths.e2e.test.ts
@@ -162,6 +162,49 @@ describe('CLI Success Paths E2E', () => {
     });
   });
 
+  describe('local language validation across input modes', () => {
+    it('should reject formality for an extended target before sending a file', () => {
+      const inputFile = path.join(testDir, 'extended-file.txt');
+      fs.writeFileSync(inputFile, 'Hello', 'utf-8');
+      const outputFile = path.join(testDir, 'extended-file.af.txt');
+
+      const result = runCLIExpectError(
+        `translate "${inputFile}" --to af --formality more --output "${outputFile}"`,
+      );
+
+      expect(result.status).toBe(6);
+      expect(result.output).toContain('do not support formality');
+      expect(fs.existsSync(outputFile)).toBe(false);
+    });
+
+    it('should reject formality for an extended target before scanning a directory', () => {
+      const dirPath = path.join(testDir, 'extended-dir');
+      fs.mkdirSync(dirPath, { recursive: true });
+      fs.writeFileSync(path.join(dirPath, 'a.txt'), 'Hello', 'utf-8');
+
+      const result = runCLIExpectError(
+        `translate "${dirPath}" --to af --formality more --output "${testDir}/extended-dir-out"`,
+      );
+
+      expect(result.status).toBe(6);
+      expect(result.output).toContain('do not support formality');
+    });
+
+    it('should note an unknown code once per directory run, not once per call site', () => {
+      const dirPath = path.join(testDir, 'deferral-dir');
+      fs.mkdirSync(dirPath, { recursive: true });
+      fs.writeFileSync(path.join(dirPath, 'a.txt'), 'Hello', 'utf-8');
+
+      const output = runCLIAll(
+        `translate "${dirPath}" --to de,ex --output "${testDir}/deferral-dir-out"`,
+      );
+
+      const notices = output.match(/is not in the bundled language list/g) ?? [];
+      expect(notices).toHaveLength(1);
+      expect(output).toContain('"ex" is not in the bundled language list');
+    });
+  });
+
   describe('write command success paths', () => {
     it('should improve text using write command', () => {
       const output = runCLIAll('write "Their going to the store" --lang en-US');
diff --git a/tests/integration/cli-dry-run.integration.test.ts b/tests/integration/cli-dry-run.integration.test.ts
index 7c6da304..5941aa02 100644
--- a/tests/integration/cli-dry-run.integration.test.ts
+++ b/tests/integration/cli-dry-run.integration.test.ts
@@ -6,11 +6,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createTestConfigDir, createTestDir, makeRunCLI } from '../helpers';
+import { ExitCode } from '../../src/utils/exit-codes';
 
 describe('--dry-run CLI Integration', () => {
   const testConfig = createTestConfigDir('dryrun');
   const testFiles = createTestDir('dryrun-files');
-  const { runCLI } = makeRunCLI(testConfig.path);
+  const { runCLI, runCLIAll, runCLIExpectError } = makeRunCLI(testConfig.path);
 
   afterAll(() => {
     testConfig.cleanup();
@@ -90,6 +91,106 @@ describe('--dry-run CLI Integration', () => {
     });
   });
 
+  describe('deepl translate --dry-run validation', () => {
+    // A dry run reports a command as runnable, so it has to reject whatever the
+    // real run rejects locally, with the same message and exit code.
+    it('should reject a malformed target language code', () => {
+      const result = runCLIExpectError(`deepl translate "Hi" --to 'not!!a!!lang' --dry-run`, {
+        excludeApiKey: true,
+        noColor: true,
+      });
+
+      expect(result.status).toBe(ExitCode.InvalidInput);
+      expect(result.output).toContain('Invalid target language code');
+      expect(result.output).not.toContain('Would translate');
+    });
+
+    it('should reject a malformed source language code', () => {
+      const result = runCLIExpectError(
+        `deepl translate "Hi" --to de --from 'not!!a!!lang' --dry-run`,
+        { excludeApiKey: true, noColor: true },
+      );
+
+      expect(result.status).toBe(ExitCode.InvalidInput);
+      expect(result.output).toContain('Invalid source language code');
+    });
+
+    it('should reject formality for an extended-tier target', () => {
+      const result = runCLIExpectError(`deepl translate "Hi" --to af --formality more --dry-run`, {
+        excludeApiKey: true,
+        noColor: true,
+      });
+
+      expect(result.status).toBe(ExitCode.InvalidInput);
+      expect(result.output).toContain('do not support formality');
+    });
+
+    it('should reject a glossary for an extended-tier target', () => {
+      const result = runCLIExpectError(
+        `deepl translate "Hi" --to af --from en --glossary my-glossary --dry-run`,
+        { excludeApiKey: true, noColor: true },
+      );
+
+      expect(result.status).toBe(ExitCode.InvalidInput);
+      expect(result.output).toContain('do not support glossaries');
+    });
+
+    it('should not reject --model-type, which a document run discards', () => {
+      const testFile = path.join(testFiles.path, 'dryrun-model.pdf');
+      fs.writeFileSync(testFile, 'not really a pdf');
+
+      const output = runCLI(
+        `deepl translate "${testFile}" --to af --model-type latency_optimized --output "${testFiles.path}/out.pdf" --dry-run`,
+        { excludeApiKey: true, noColor: true },
+      );
+
+      expect(output).toContain('Would translate file');
+    });
+
+    it('should not reject a glossary for a directory, which ignores one', () => {
+      const dirPath = path.join(testFiles.path, 'dryrun-glossary-dir');
+      fs.mkdirSync(dirPath, { recursive: true });
+      fs.writeFileSync(path.join(dirPath, 'a.txt'), 'hello');
+
+      const output = runCLI(
+        `deepl translate "${dirPath}" --to af --from en --glossary my-glossary --output "${testFiles.path}/out-gdir" --dry-run`,
+        { excludeApiKey: true, noColor: true },
+      );
+
+      expect(output).toContain('Would translate directory');
+    });
+
+    it('should warn once per unknown code rather than once per validation', () => {
+      const output = runCLIAll(`deepl translate "Hi" --to 'de,ex' --dry-run`, {
+        excludeApiKey: true,
+        noColor: true,
+      });
+
+      const notices = output.match(/is not in the bundled language list/g) ?? [];
+      expect(notices).toHaveLength(1);
+      expect(output).toContain('"ex" is not in the bundled language list');
+    });
+
+    it('should warn about an unknown source language too', () => {
+      const output = runCLIAll(`deepl translate "Hi" --to de --from zz --dry-run`, {
+        excludeApiKey: true,
+        noColor: true,
+      });
+
+      expect(output).toContain('"zz" is not in the bundled language list');
+    });
+
+    it('should lowercase language codes the way the real run does', () => {
+      const output = runCLI(`deepl translate "Hi" --to DE --from EN --dry-run`, {
+        excludeApiKey: true,
+        noColor: true,
+      });
+
+      expect(output).toContain('Target language(s): de');
+      expect(output).toContain('Source language: en');
+    });
+  });
+
   describe('deepl glossary delete --dry-run', () => {
     it('should show --dry-run in glossary delete help', () => {
       const output = runCLI('deepl glossary delete --help');
diff --git a/tests/unit/directory-translation-handler.test.ts b/tests/unit/directory-translation-handler.test.ts
index d378626e..f708669b 100644
--- a/tests/unit/directory-translation-handler.test.ts
+++ b/tests/unit/directory-translation-handler.test.ts
@@ -51,7 +51,7 @@ jest.mock('../../src/services/batch-translation', () => ({
 
 jest.mock('../../src/cli/commands/translate/translate-utils', () => ({
   warnIgnoredOptions: jest.fn(),
-  validateLanguageCodes: jest.fn(),
+  validateTranslationLanguages: jest.fn(),
   buildTranslationOptions: jest.fn().mockReturnValue({ targetLang: 'de' }),
 }));
 
@@ -429,11 +429,39 @@ describe('DirectoryTranslationHandler', () => {
 
       await handler.translateDirectory('/some/dir', options);
 
-      const { validateLanguageCodes } = jest.requireMock(
+      const { validateTranslationLanguages } = jest.requireMock(
         '../../src/cli/commands/translate/translate-utils'
       );
 
-      expect(validateLanguageCodes).toHaveBeenCalledWith(['de', 'fr']);
+      expect(validateTranslationLanguages).toHaveBeenCalledWith(
+        ['de', 'fr'],
+        expect.anything(),
+      );
+    });
+
+    it('should validate the flags this mode passes on, and not --glossary', async () => {
+      // Directory mode announces --glossary as ignored and resolves none, so the
+      // extended-tier glossary arm must not fail a run that would have worked.
+      const options: TranslateOptions = {
+        ...baseOptions,
+        to: 'de, fr',
+        from: 'en',
+        formality: 'more',
+        modelType: 'latency_optimized',
+        glossary: ['my-glossary'],
+      };
+
+      await handler.translateDirectory('/some/dir', options);
+
+      const { validateTranslationLanguages } = jest.requireMock(
+        '../../src/cli/commands/translate/translate-utils'
+      );
+
+      expect(validateTranslationLanguages).toHaveBeenCalledWith(['de', 'fr'], {
+        from: 'en',
+        formality: 'more',
+        modelType: 'latency_optimized',
+      });
     });
 
     it('should call buildTranslationOptions with each individual language', async () => {
diff --git a/tests/unit/translate-command.test.ts b/tests/unit/translate-command.test.ts
index 0c9a6c73..b37d37d6 100644
--- a/tests/unit/translate-command.test.ts
+++ b/tests/unit/translate-command.test.ts
@@ -2175,6 +2175,231 @@ describe('TranslateCommand', () => {
     });
   });
 
+  describe('extended-tier constraints per input mode', () => {
+    let mockFs: any;
+
+    beforeEach(() => {
+      mockFs = jest.requireActual('fs');
+      jest.spyOn(Logger, 'shouldShowSpinner').mockReturnValue(false);
+      jest.spyOn(mockFs, 'existsSync').mockReturnValue(true);
+      jest.spyOn(mockFs, 'statSync').mockReturnValue({
+        size: 1024,
+        isDirectory: () => false,
+      } as any);
+      (safeReadFileSync as jest.Mock).mockReturnValue('Hello');
+    });
+
+    afterEach(() => {
+      jest.restoreAllMocks();
+    });
+
+    function fileHandler() {
+      return (translateCommand as any).fileHandler;
+    }
+
+    describe('file mode', () => {
+      it('should reject formality for an extended target', async () => {
+        await expect(
+          fileHandler().translateTextFile('/doc.txt', {
+            to: 'sw',
+            formality: 'more',
+            output: '/out.txt',
+          })
+        ).rejects.toThrow('do not support formality');
+      });
+
+      it('should reject a glossary for an extended target', async () => {
+        await expect(
+          fileHandler().translateTextFile('/doc.txt', {
+            to: 'sw',
+            from: 'en',
+            glossary: ['my-glossary'],
+            output: '/out.txt',
+          })
+        ).rejects.toThrow('do not support glossaries');
+      });
+
+      it('should reject latency_optimized for an extended target', async () => {
+        await expect(
+          fileHandler().translateTextFile('/doc.txt', {
+            to: 'sw',
+            modelType: 'latency_optimized',
+            output: '/out.txt',
+          })
+        ).rejects.toThrow('only support quality_optimized');
+      });
+
+      it('should reject formality for an extended target among several', async () => {
+        (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+
+        await expect(
+          fileHandler().translateFile('/doc.txt', {
+            to: 'es,sw',
+            formality: 'more',
+            output: '/out',
+          })
+        ).rejects.toThrow('do not support formality');
+      });
+
+      it('should reject formality for a format routed through fileTranslationService', async () => {
+        (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+        (translateCommand as any).ctx.fileTranslationService = {
+          translateFile: jest.fn().mockResolvedValue(undefined),
+          isSupportedFile: jest.fn().mockReturnValue(true),
+          translateFileToMultiple: jest.fn(),
+        };
+
+        await expect(
+          fileHandler().translateFile('/input.csv', {
+            to: 'sw',
+            formality: 'more',
+            output: '/output.csv',
+          })
+        ).rejects.toThrow('do not support formality');
+      });
+
+      it('should not reject a glossary on a path that resolves none', async () => {
+        // The csv path carries no glossary to the request, so refusing the run
+        // over one would refuse a command that works.
+        (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+        const mockFileService = {
+          translateFile: jest.fn().mockResolvedValue(undefined),
+          isSupportedFile: jest.fn().mockReturnValue(true),
+          translateFileToMultiple: jest.fn(),
+        };
+        (translateCommand as any).ctx.fileTranslationService = mockFileService;
+
+        await fileHandler().translateFile('/input.csv', {
+          to: 'sw',
+          from: 'en',
+          glossary: ['my-glossary'],
+          output: '/output.csv',
+        });
+
+        expect(mockFileService.translateFile).toHaveBeenCalled();
+      });
+    });
+
+    describe('directory mode', () => {
+      function directory(options: Record<string, unknown>) {
+        return (translateCommand as any).directoryHandler.translateDirectory('/src', options);
+      }
+
+      beforeEach(() => {
+        (translateCommand as any).ctx.batchTranslationService = {
+          translateDirectory: jest.fn().mockResolvedValue({
+            successful: [{ file: 'a.txt', outputPath: '/out/a.txt' }],
+            failed: [],
+            skipped: [],
+          }),
+          getStatistics: jest
+            .fn()
+            .mockReturnValue({ total: 1, successful: 1, failed: 0, skipped: 0 }),
+        };
+      });
+
+      it('should reject formality for an extended target', async () => {
+        await expect(
+          directory({ to: 'sw', formality: 'more', output: '/out' })
+        ).rejects.toThrow('do not support formality');
+      });
+
+      it('should reject latency_optimized for an extended target', async () => {
+        await expect(
+          directory({ to: 'sw', modelType: 'latency_optimized', output: '/out' })
+        ).rejects.toThrow('only support quality_optimized');
+      });
+
+      it('should reject formality for an extended target among several', async () => {
+        await expect(
+          directory({ to: 'es,sw', formality: 'more', output: '/out' })
+        ).rejects.toThrow('do not support formality');
+      });
+
+      it('should not reject a glossary it has announced as ignored', async () => {
+        const result = await directory({
+          to: 'sw',
+          from: 'en',
+          glossary: ['my-glossary'],
+          output: '/out',
+        });
+
+        expect(result).toContain('Translation Statistics');
+      });
+    });
+
+    describe('document mode', () => {
+      function document(options: Record<string, unknown>) {
+        return fileHandler().documentHandler.translateDocument('/doc.pdf', options);
+      }
+
+      it('should reject formality for an extended target', async () => {
+        await expect(document({ to: 'sw', formality: 'more', output: '/out.pdf' })).rejects.toThrow(
+          'do not support formality'
+        );
+      });
+
+      it('should reject a glossary for an extended target', async () => {
+        await expect(
+          document({ to: 'sw', from: 'en', glossary: ['my-glossary'], output: '/out.pdf' })
+        ).rejects.toThrow('do not support glossaries');
+      });
+
+      it('should not reject a model type it strips after warning', async () => {
+        (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+          success: true,
+          outputPath: '/out.pdf',
+        });
+
+        const result = await document({
+          to: 'sw',
+          modelType: 'latency_optimized',
+          output: '/out.pdf',
+        });
+
+        expect(result).toContain('Translated /doc.pdf');
+      });
+    });
+
+    describe('source language', () => {
+      it('should reject a malformed --from in text mode', async () => {
+        await expect(
+          translateCommand.translateText('Hello', { to: 'es', from: 'not!!a!!lang' })
+        ).rejects.toThrow('Invalid source language code');
+      });
+
+      it('should reject a malformed --from in file mode', async () => {
+        await expect(
+          fileHandler().translateTextFile('/doc.txt', {
+            to: 'es',
+            from: 'not!!a!!lang',
+            output: '/out.txt',
+          })
+        ).rejects.toThrow('Invalid source language code');
+      });
+
+      it('should reject a malformed --from in directory mode', async () => {
+        await expect(
+          (translateCommand as any).directoryHandler.translateDirectory('/src', {
+            to: 'es',
+            from: 'not!!a!!lang',
+            output: '/out',
+          })
+        ).rejects.toThrow('Invalid source language code');
+      });
+
+      it('should reject a malformed --from in document mode', async () => {
+        await expect(
+          fileHandler().documentHandler.translateDocument('/doc.pdf', {
+            to: 'es',
+            from: 'not!!a!!lang',
+            output: '/out.pdf',
+          })
+        ).rejects.toThrow('Invalid source language code');
+      });
+    });
+  });
+
   describe('tag handling version', () => {
     it('should pass tagHandlingVersion to translation service', async () => {
       mockTranslationService.translate.mockResolvedValue({
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index bb62fd7f..a317f013 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -8,6 +8,9 @@ import {
   MAX_CUSTOM_INSTRUCTIONS,
   MAX_CUSTOM_INSTRUCTION_CHARS,
   validateLanguageCodes,
+  validateSourceLanguage,
+  validateTranslationLanguages,
+  resetDeferredLanguageWarnings,
   validateExtendedLanguageConstraints,
   validateXmlTags,
   warnIgnoredOptions,
@@ -47,6 +50,8 @@ const mockedLoggerWarn = Logger.warn as jest.MockedFunction<typeof Logger.warn>;
 describe('translate-utils', () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    // Module state, which clearing the Logger spy does not touch.
+    resetDeferredLanguageWarnings();
   });
 
   describe('constants', () => {
@@ -163,6 +168,103 @@ describe('translate-utils', () => {
     it('should throw on first invalid code in array', () => {
       expect(() => validateLanguageCodes(['en', 'invalid', 'de'])).toThrow(/Invalid target language code: "invalid"/);
     });
+
+    it('should warn once per unknown code however many times it is validated', () => {
+      // Several input modes validate the same list on the way to one request.
+      validateLanguageCodes(['ex']);
+      validateLanguageCodes(['ex']);
+      validateLanguageCodes(['de', 'ex']);
+
+      expect(mockedLoggerWarn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should warn once for each distinct unknown code', () => {
+      validateLanguageCodes(['ex', 'zz']);
+      validateLanguageCodes(['ex', 'zz']);
+
+      const warnings = mockedLoggerWarn.mock.calls.map(call => String(call[0]));
+      expect(warnings).toHaveLength(2);
+      expect(warnings[0]).toContain('"ex"');
+      expect(warnings[1]).toContain('"zz"');
+    });
+
+    it('should warn again after the warned-code state is reset', () => {
+      validateLanguageCodes(['ex']);
+      resetDeferredLanguageWarnings();
+      validateLanguageCodes(['ex']);
+
+      expect(mockedLoggerWarn).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('validateSourceLanguage()', () => {
+    it('should accept an absent source language, which means auto-detect', () => {
+      expect(() => validateSourceLanguage(undefined)).not.toThrow();
+      expect(mockedLoggerWarn).not.toHaveBeenCalled();
+    });
+
+    it('should accept a code the snapshot lists', () => {
+      expect(() => validateSourceLanguage('en')).not.toThrow();
+      expect(mockedLoggerWarn).not.toHaveBeenCalled();
+    });
+
+    it('should reject a malformed code as a source, not a target', () => {
+      expect(() => validateSourceLanguage('not!!a!!lang')).toThrow(ValidationError);
+      expect(() => validateSourceLanguage('not!!a!!lang')).toThrow(
+        /Invalid source language code: "not!!a!!lang"/,
+      );
+    });
+
+    it('should defer a well-formed unknown code to the API with a warning', () => {
+      expect(() => validateSourceLanguage('zz')).not.toThrow();
+
+      const warning = mockedLoggerWarn.mock.calls.map(call => String(call[0])).join('\n');
+      expect(warning).toContain('"zz" is not in the bundled language list');
+    });
+
+    it('should share the warned-code state with target validation', () => {
+      validateLanguageCodes(['zz']);
+      validateSourceLanguage('zz');
+
+      expect(mockedLoggerWarn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('validateTranslationLanguages()', () => {
+    it('should reject a malformed target code', () => {
+      expect(() => validateTranslationLanguages(['not!!a!!lang'], {})).toThrow(
+        /Invalid target language code/,
+      );
+    });
+
+    it('should reject a malformed source code', () => {
+      expect(() => validateTranslationLanguages(['de'], { from: 'not!!a!!lang' })).toThrow(
+        /Invalid source language code/,
+      );
+    });
+
+    it('should enforce the extended-tier constraint over the whole target list', () => {
+      expect(() => validateTranslationLanguages(['de', 'hi'], { formality: 'more' })).toThrow(
+        /Language\(s\) hi do not support formality/,
+      );
+    });
+
+    it('should enforce the extended-tier constraint for a single target', () => {
+      expect(() =>
+        validateTranslationLanguages(['hi'], { modelType: 'latency_optimized' }),
+      ).toThrow(/only support quality_optimized/);
+    });
+
+    it('should accept a valid pair with no constrained options', () => {
+      expect(() => validateTranslationLanguages(['de', 'fr'], { from: 'en' })).not.toThrow();
+    });
+
+    it('should not enforce an arm the caller left out', () => {
+      // The input modes disagree about which flags they honour; a mode that
+      // discards a flag passes it here as absent.
+      expect(() => validateTranslationLanguages(['hi'], { formality: 'more' })).toThrow();
+      expect(() => validateTranslationLanguages(['hi'], {})).not.toThrow();
+    });
   });
 
   describe('validateExtendedLanguageConstraints()', () => {
@@ -201,10 +303,15 @@ describe('translate-utils', () => {
       ).toThrow(/do not support glossaries/);
     });
 
+    it('should not throw for an empty glossary list, which selects nothing', () => {
+      expect(() =>
+        validateExtendedLanguageConstraints('hi', { ...baseOptions, glossary: [] })
+      ).not.toThrow();
+    });
+
     it('should not throw for non-extended languages', () => {
       expect(() =>
         validateExtendedLanguageConstraints('de', {
-          to: 'de',
           modelType: 'latency_optimized',
           formality: 'more',
           glossary: ['some-glossary'],
@@ -220,7 +327,7 @@ describe('translate-utils', () => {
 
     it('should not throw when only non-extended langs in comma-separated list', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('en, de', { to: 'en', modelType: 'latency_optimized' })
+        validateExtendedLanguageConstraints('en, de', { modelType: 'latency_optimized' })
       ).not.toThrow();
     });
 

From 0789e109c4093a02628f3006f6afd03986f848e1 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 09:08:10 -0400
Subject: [PATCH 057/256] fix(voice): validate options before resolving
 --glossary, and check coverage

Resolution costs a glossary-list round trip, and it was spent before the
target language, source language and content type were checked -- so
'voice a.ogg --to bogus --glossary g' paid for a request and then failed
locally. The local checks move into an exported validateVoiceOptions()
that the registrar calls first and buildOptions reuses.

Resolution now also passes the requested pair, so a glossary that does not
cover it fails locally the way it already did for translate, watch and
sync. The pair is the canonical spelling voice sends; without --from there
is no pair and the API keeps the judgement.

Closes cli-01on.3
---
 CHANGELOG.md                                 |  2 +
 src/cli/commands/register-voice.ts           | 16 +++-
 src/cli/commands/voice.ts                    | 85 +++++++++++++-------
 tests/e2e/cli-voice.e2e.test.ts              | 49 +++++++++++
 tests/unit/voice-glossary-resolution.test.ts | 81 ++++++++++++++++++-
 5 files changed, 199 insertions(+), 34 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c19cfd6..c1ee1057 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -115,6 +115,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
 
+- **voice**: **`--glossary` was resolved before the rest of the command was checked, and without the language pair.** `voice a.ogg --to bogus --glossary my-terms` spent a glossary-list round trip and only then failed locally on the target language; every local check now runs first. Resolution also passes the requested pair, so a glossary whose dictionaries do not cover it fails locally with `Glossary "my-terms" does not support the requested language pair` instead of at the API — the preflight the other commands already had. The pair is the canonical one voice sends, so `--from EN --to zh-hans` is checked as `en→zh-HANS`. Without `--from` there is no pair to check and the API still judges it.
+
 - **translate**: **File, directory and `--dry-run` runs skipped the extended-tier language checks that text runs made.** `translate "Hi" --to af --formality more` exited 6 locally, while the same flags on a file or a directory reached the network and came back as an API rejection; `--dry-run` reported both as runnable, along with `--to 'not!!a!!lang'`, which every real run refuses. Language validation was spread over eight call sites in five files and only three paired the code check with the extended-tier check, which is how the modes drifted apart. There is now one entry point that every input mode calls, so a constrained option fails before anything is sent whichever mode handles the argument. Each mode passes only the flags it actually honours, so nothing is refused over a flag its mode discards: a document run still accepts `--model-type`, which it strips after warning, and a directory run still accepts `--glossary`, which it ignores. **`--from` is validated too** — it never was, so a malformed source language went unremarked until the API answered — and is named as such: `Invalid source language code: "grman"`. The "not in the bundled language list; deferring to the API" note is now said once per code per run instead of once per call site, which had it printing twice for `--to de,ex` and four times for `--to ex,zz` on a directory. An empty repeatable `--glossary` list no longer trips the "do not support glossaries" rejection, and a dry run lowercases `--to`/`--from` the way the real run does.
 
 - **translate**: **A directory translation where every file failed exited 0.** The summary reported `✓ Successful: 0 / ✗ Failed: N` and the command still looked like success to a script or CI job. Since language validation defers unknown codes to the API, a plain `--to` typo took this path: on 1.x it exited 6 locally, and in this release it printed a failure list and exited 0. A run with no successes now exits 1, and a partial failure exits 12, matching what `sync` already does.
diff --git a/src/cli/commands/register-voice.ts b/src/cli/commands/register-voice.ts
index 117de3db..9ac63c58 100644
--- a/src/cli/commands/register-voice.ts
+++ b/src/cli/commands/register-voice.ts
@@ -1,6 +1,7 @@
 import { Command, InvalidArgumentError, Option } from 'commander';
 import { Logger } from '../../utils/logger.js';
 import { createVoiceCommand, type ServiceDeps } from './service-factory.js';
+import type { Language } from '../../types/index.js';
 
 function parsePositiveInt(value: string, name: string, max: number): number {
   const n = parseInt(value, 10);
@@ -72,11 +73,24 @@ Examples:
       format?: string;
     }) => {
       try {
+        // Ahead of the resolution below, which costs a glossary-list round trip:
+        // a command that fails locally must not spend one first. Imported
+        // dynamically to keep the voice module off every other command's path.
+        const { validateVoiceOptions } = await import('./voice.js');
+        const { targetLangs, sourceLang } = validateVoiceOptions(options);
+
         if (options.glossary) {
           const client = await deps.createDeepLClient();
           const { GlossaryService } = await import('../../services/glossary.js');
           const glossaryService = new GlossaryService(client);
-          options.glossary = await glossaryService.resolveGlossaryId(options.glossary);
+          // The pair lets resolution check dictionary coverage locally. Without
+          // `--from` there is no pair to check, so the API judges it instead.
+          options.glossary = await glossaryService.resolveGlossaryId(
+            options.glossary,
+            sourceLang
+              ? { from: sourceLang as Language, targets: targetLangs as unknown as Language[] }
+              : undefined,
+          );
         }
 
         const voiceCommand = await createVoiceCommand(deps.getApiKeyAndOptions);
diff --git a/src/cli/commands/voice.ts b/src/cli/commands/voice.ts
index ebb835ea..aff12e7f 100644
--- a/src/cli/commands/voice.ts
+++ b/src/cli/commands/voice.ts
@@ -60,6 +60,58 @@ const VALID_VOICE_CONTENT_TYPES: ReadonlySet<string> = new Set<VoiceSourceMediaC
   'audio/flac','audio/mpeg',
 ]);
 
+/** The canonical language pair a validated `voice` invocation will send. */
+export interface VoiceLanguagePair {
+  targetLangs: VoiceTargetLanguage[];
+  sourceLang?: VoiceSourceLanguage;
+}
+
+/**
+ * Canonicalizes and checks everything `voice` can reject without the network,
+ * returning the language pair. Exported because the registrar needs both halves
+ * before it resolves `--glossary`: resolution costs a glossary-list round trip,
+ * which must not be spent on a command that fails locally, and the coverage
+ * preflight needs the pair to check against.
+ */
+export function validateVoiceOptions(options: {
+  to: string;
+  from?: string;
+  contentType?: string;
+}): VoiceLanguagePair {
+  // Matched case-insensitively and canonicalized to the spelling the Voice API
+  // expects. The rest of the CLI accepts any casing and `deepl languages`
+  // prints these codes lowercase, so requiring `zh-HANS` would reject the
+  // spelling the CLI itself teaches.
+  const targetLangs = options.to.split(',').map((l) => {
+    const raw = l.trim();
+    const canonical = VOICE_TARGET_BY_LOWERCASE.get(raw.toLowerCase());
+    if (!canonical) {
+      throw new ValidationError(
+        `Invalid voice target language: "${raw}". Valid codes: ${Array.from(VALID_VOICE_TARGET_LANGS).sort().join(', ')}`,
+      );
+    }
+    return canonical;
+  });
+
+  let sourceLang: VoiceSourceLanguage | undefined;
+  if (options.from) {
+    sourceLang = VOICE_SOURCE_BY_LOWERCASE.get(options.from.toLowerCase());
+    if (!sourceLang) {
+      throw new ValidationError(
+        `Invalid voice source language: "${options.from}". Valid codes: ${Array.from(VALID_VOICE_SOURCE_LANGS).sort().join(', ')}`,
+      );
+    }
+  }
+
+  if (options.contentType && !VALID_VOICE_CONTENT_TYPES.has(options.contentType)) {
+    throw new ValidationError(
+      `Invalid voice content type: "${options.contentType}". Valid types: ${Array.from(VALID_VOICE_CONTENT_TYPES).sort().join(', ')}`,
+    );
+  }
+
+  return { targetLangs, sourceLang };
+}
+
 interface VoiceCommandOptions {
   to: string;
   from?: string;
@@ -149,36 +201,7 @@ export class VoiceCommand {
   }
 
   private buildOptions(options: VoiceCommandOptions): VoiceTranslateOptions {
-    // Matched case-insensitively and canonicalized to the spelling the Voice API
-    // expects. The rest of the CLI accepts any casing and `deepl languages`
-    // prints these codes lowercase, so requiring `zh-HANS` would reject the
-    // spelling the CLI itself teaches.
-    const targetLangs = options.to.split(',').map((l) => {
-      const raw = l.trim();
-      const canonical = VOICE_TARGET_BY_LOWERCASE.get(raw.toLowerCase());
-      if (!canonical) {
-        throw new ValidationError(
-          `Invalid voice target language: "${raw}". Valid codes: ${Array.from(VALID_VOICE_TARGET_LANGS).sort().join(', ')}`,
-        );
-      }
-      return canonical;
-    });
-
-    if (options.from) {
-      const canonicalSource = VOICE_SOURCE_BY_LOWERCASE.get(options.from.toLowerCase());
-      if (!canonicalSource) {
-        throw new ValidationError(
-          `Invalid voice source language: "${options.from}". Valid codes: ${Array.from(VALID_VOICE_SOURCE_LANGS).sort().join(', ')}`,
-        );
-      }
-      options.from = canonicalSource;
-    }
-
-    if (options.contentType && !VALID_VOICE_CONTENT_TYPES.has(options.contentType)) {
-      throw new ValidationError(
-        `Invalid voice content type: "${options.contentType}". Valid types: ${Array.from(VALID_VOICE_CONTENT_TYPES).sort().join(', ')}`,
-      );
-    }
+    const { targetLangs, sourceLang } = validateVoiceOptions(options);
 
     if (options.glossary && targetLangs.length > 1) {
       process.stderr.write(
@@ -191,7 +214,7 @@ export class VoiceCommand {
 
     return {
       targetLangs,
-      sourceLang: options.from as VoiceSourceLanguage | undefined,
+      sourceLang,
       sourceLanguageMode: options.sourceLanguageMode as VoiceSourceLanguageMode | undefined,
       formality: options.formality as VoiceTranslateOptions['formality'],
       glossaryId: options.glossary,
diff --git a/tests/e2e/cli-voice.e2e.test.ts b/tests/e2e/cli-voice.e2e.test.ts
index eb7a775c..3bbc464c 100644
--- a/tests/e2e/cli-voice.e2e.test.ts
+++ b/tests/e2e/cli-voice.e2e.test.ts
@@ -96,6 +96,55 @@ describe('Voice CLI E2E', () => {
     });
   });
 
+  describe('Validation before the glossary round trip', () => {
+    // Resolving --glossary lists the account's glossaries, so a command that
+    // fails locally must fail before that request rather than after it. The
+    // config points at a dead port, so a regression that resolved first would
+    // report a network error instead of the local rejection.
+    const orderConfig = createTestConfigDir('voice-e2e-glossary-order');
+    const orderCLI = makeRunCLI(orderConfig.path, { noColor: true });
+
+    beforeAll(() => {
+      fs.writeFileSync(
+        path.join(orderConfig.path, 'config.json'),
+        JSON.stringify({
+          auth: { apiKey: 'mock-api-key-for-testing:fx' },
+          api: { baseUrl: 'http://127.0.0.1:9/v2', usePro: false },
+        }),
+      );
+    });
+
+    afterAll(() => {
+      orderConfig.cleanup();
+    });
+
+    it('should reject an invalid target language ahead of glossary resolution', () => {
+      const testFile = path.join(testDir, 'glossary-order.mp3');
+      fs.writeFileSync(testFile, Buffer.alloc(100));
+
+      const result = orderCLI.runCLIExpectError(
+        `deepl voice ${testFile} --to bogus --glossary my-glossary`,
+      );
+
+      expect(result.status).toBe(6);
+      expect(result.output).toContain('Invalid voice target language');
+      expect(result.output).not.toMatch(/Network error/);
+    });
+
+    it('should reject an invalid content type ahead of glossary resolution', () => {
+      const testFile = path.join(testDir, 'glossary-order-ct.mp3');
+      fs.writeFileSync(testFile, Buffer.alloc(100));
+
+      const result = orderCLI.runCLIExpectError(
+        `deepl voice ${testFile} --to de --content-type audio/wav --glossary my-glossary`,
+      );
+
+      expect(result.status).toBe(6);
+      expect(result.output).toContain('Invalid voice content type');
+      expect(result.output).not.toMatch(/Network error/);
+    });
+  });
+
   describe('Error messages', () => {
     it('should show clear error when API key is not set', () => {
       const testFile = path.join(testDir, 'error-msg-test.mp3');
diff --git a/tests/unit/voice-glossary-resolution.test.ts b/tests/unit/voice-glossary-resolution.test.ts
index e8739009..fda7cd1f 100644
--- a/tests/unit/voice-glossary-resolution.test.ts
+++ b/tests/unit/voice-glossary-resolution.test.ts
@@ -90,7 +90,7 @@ describe('Voice Glossary Resolution', () => {
     await program.parseAsync(['node', 'test', 'voice', 'test.ogg', '--to', 'de', '--glossary', uuid]);
 
     expect(createDeepLClient).toHaveBeenCalled();
-    expect(mockResolveGlossaryId).toHaveBeenCalledWith(uuid);
+    expect(mockResolveGlossaryId).toHaveBeenCalledWith(uuid, undefined);
     expect(mockTranslate).toHaveBeenCalledWith(
       'test.ogg',
       expect.objectContaining({ glossary: uuid }),
@@ -105,13 +105,90 @@ describe('Voice Glossary Resolution', () => {
     await program.parseAsync(['node', 'test', 'voice', 'test.ogg', '--to', 'de', '--glossary', 'my-glossary']);
 
     expect(createDeepLClient).toHaveBeenCalled();
-    expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+    expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary', undefined);
     expect(mockTranslate).toHaveBeenCalledWith(
       'test.ogg',
       expect.objectContaining({ glossary: resolvedId }),
     );
   });
 
+  it('should resolve with the requested pair so coverage is checked locally', async () => {
+    mockResolveGlossaryId.mockResolvedValue('aaaabbbb-cccc-dddd-eeee-ffffffffffff');
+
+    await loadAndRegister();
+    await program.parseAsync([
+      'node', 'test', 'voice', 'test.ogg',
+      '--from', 'en', '--to', 'de,fr', '--glossary', 'my-glossary',
+    ]);
+
+    expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+      from: 'en',
+      targets: ['de', 'fr'],
+    });
+  });
+
+  it('should pass the canonical spellings of the pair, not what was typed', async () => {
+    mockResolveGlossaryId.mockResolvedValue('aaaabbbb-cccc-dddd-eeee-ffffffffffff');
+
+    await loadAndRegister();
+    await program.parseAsync([
+      'node', 'test', 'voice', 'test.ogg',
+      '--from', 'EN', '--to', 'zh-hans', '--glossary', 'my-glossary',
+    ]);
+
+    expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+      from: 'en',
+      targets: ['zh-HANS'],
+    });
+  });
+
+  it('should resolve without a pair when --from is absent, since coverage needs both', async () => {
+    mockResolveGlossaryId.mockResolvedValue('aaaabbbb-cccc-dddd-eeee-ffffffffffff');
+
+    await loadAndRegister();
+    await program.parseAsync([
+      'node', 'test', 'voice', 'test.ogg', '--to', 'de', '--glossary', 'my-glossary',
+    ]);
+
+    expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary', undefined);
+  });
+
+  it('should reject an invalid target language before spending the resolution call', async () => {
+    await loadAndRegister();
+    await expect(
+      program.parseAsync([
+        'node', 'test', 'voice', 'test.ogg', '--to', 'bogus', '--glossary', 'my-glossary',
+      ]),
+    ).rejects.toThrow('Invalid voice target language');
+
+    expect(createDeepLClient).not.toHaveBeenCalled();
+    expect(mockResolveGlossaryId).not.toHaveBeenCalled();
+  });
+
+  it('should reject an invalid source language before spending the resolution call', async () => {
+    await loadAndRegister();
+    await expect(
+      program.parseAsync([
+        'node', 'test', 'voice', 'test.ogg',
+        '--to', 'de', '--from', 'bogus', '--glossary', 'my-glossary',
+      ]),
+    ).rejects.toThrow('Invalid voice source language');
+
+    expect(mockResolveGlossaryId).not.toHaveBeenCalled();
+  });
+
+  it('should reject an invalid content type before spending the resolution call', async () => {
+    await loadAndRegister();
+    await expect(
+      program.parseAsync([
+        'node', 'test', 'voice', 'test.ogg',
+        '--to', 'de', '--content-type', 'audio/wav', '--glossary', 'my-glossary',
+      ]),
+    ).rejects.toThrow('Invalid voice content type');
+
+    expect(mockResolveGlossaryId).not.toHaveBeenCalled();
+  });
+
   it('should not create DeepLClient or call resolveGlossaryId when no glossary is specified', async () => {
     await loadAndRegister();
     await program.parseAsync(['node', 'test', 'voice', 'test.ogg', '--to', 'de']);

From c4b5b0e9bedf72b32a4292ce884e801554b64496 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 09:18:51 -0400
Subject: [PATCH 058/256] fix(sync): check override glossaries at startup, and
 validate during --dry-run

locale_overrides.<locale>.glossary was resolved with no expected pair, so
it skipped the coverage preflight the top-level glossary and the TM
override already had. It was also resolved inside the bucket loop, once
per file, which means a reference that does not cover its locale failed
only after earlier files had been translated and written.

Both kinds of override now resolve once in the orchestrator, against their
own locale, and the resolved maps are threaded into processBucket -- so
that function no longer needs the glossary service, the translation
service or the TM cache.

sync --dry-run also drops its resolution guards. It already requires an
API key to get that far, and a glossary or TM the config names but the
account cannot use for the pair is what a preview exists to report. Zero
/v2/translate calls is unchanged and still asserted.

Closes cli-01on.4
---
 CHANGELOG.md                                |   2 +
 src/sync/sync-process-bucket.ts             |  38 ++----
 src/sync/sync-service.ts                    |  56 ++++++--
 tests/integration/sync.integration.test.ts  |  48 ++++++-
 tests/unit/sync/sync-process-bucket.test.ts |   7 +-
 tests/unit/sync/sync-service.test.ts        | 137 ++++++++++++++++++--
 6 files changed, 226 insertions(+), 62 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c1ee1057..dec0e21d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -115,6 +115,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
 
+- **sync**: **Per-locale glossary overrides skipped the coverage preflight, and `--dry-run` performed no resolution at all.** `locale_overrides.<locale>.glossary` was resolved without the language pair, so an override that did not cover its own locale reached the API — unlike the top-level glossary and the translation-memory override, which were already checked. Both kinds of override now resolve once at startup against their own locale, rather than being re-resolved for every file, so a bad reference fails before anything is translated instead of after earlier files have been written. `sync --dry-run` resolves and checks the same references a real run does: the command already needs an API key to reach that point, and a glossary or translation memory the config names but the account cannot use for the requested pair is exactly what a preview should report. A dry run still sends nothing to `/v2/translate`.
+
 - **voice**: **`--glossary` was resolved before the rest of the command was checked, and without the language pair.** `voice a.ogg --to bogus --glossary my-terms` spent a glossary-list round trip and only then failed locally on the target language; every local check now runs first. Resolution also passes the requested pair, so a glossary whose dictionaries do not cover it fails locally with `Glossary "my-terms" does not support the requested language pair` instead of at the API — the preflight the other commands already had. The pair is the canonical one voice sends, so `--from EN --to zh-hans` is checked as `en→zh-HANS`. Without `--from` there is no pair to check and the API still judges it.
 
 - **translate**: **File, directory and `--dry-run` runs skipped the extended-tier language checks that text runs made.** `translate "Hi" --to af --formality more` exited 6 locally, while the same flags on a file or a directory reached the network and came back as an API rejection; `--dry-run` reported both as runnable, along with `--to 'not!!a!!lang'`, which every real run refuses. Language validation was spread over eight call sites in five files and only three paired the code check with the extended-tier check, which is how the modes drifted apart. There is now one entry point that every input mode calls, so a constrained option fails before anything is sent whichever mode handles the argument. Each mode passes only the flags it actually honours, so nothing is refused over a flag its mode discards: a document run still accepts `--model-type`, which it strips after warning, and a directory run still accepts `--glossary`, which it ignores. **`--from` is validated too** — it never was, so a malformed source language went unremarked until the API answered — and is named as such: `Invalid source language code: "grman"`. The "not in the bundled language list; deferring to the API" note is now said once per code per run instead of once per call site, which had it printing twice for `--to de,ex` and four times for `--to ex,zz` on a directory. An empty repeatable `--glossary` list no longer trips the "do not support glossaries" rejection, and a dry run lowercases `--to`/`--from` the way the real run does.
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index 47a0be88..848fdb29 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -1,7 +1,5 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import type { TranslationService } from '../services/translation.js';
-import type { GlossaryService } from '../services/glossary.js';
 import { computeDiff } from './sync-differ.js';
 import { mapWithConcurrency, MULTI_TARGET_CONCURRENCY } from '../utils/concurrency.js';
 import { ValidationError } from '../utils/errors.js';
@@ -9,10 +7,7 @@ import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
 import { computeSourceHash } from './sync-lock.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncLockFile, SyncLockTranslation } from './types.js';
-import type { Language } from '../types/common.js';
 import type { KeyContext } from './sync-context.js';
-import { resolveTranslationMemoryId } from '../services/translation-memory.js';
-import type { TmCacheLike } from './tm-cache.js';
 import { Logger } from '../utils/logger.js';
 import { extractTranslatable, type WalkedBucketFile } from './sync-bucket-walker.js';
 import type { LocaleTranslator } from './sync-locale-translator.js';
@@ -31,9 +26,13 @@ export interface ProcessBucketDeps {
   // Read-only refs:
   keyContexts: Map<string, KeyContext>;
   localeTranslator: LocaleTranslator;
-  glossaryService: GlossaryService;
-  translationService: TranslationService;
-  tmCache: TmCacheLike;
+  /**
+   * Glossary and translation-memory IDs for locales carrying a
+   * `locale_overrides.<locale>` entry, resolved once by the orchestrator so a
+   * reference that does not cover its locale fails before any file is touched.
+   */
+  localeGlossaryIds: Map<string, string>;
+  localeTmIds: Map<string, string>;
   // For cost-cap check — orchestrator's cumulative as of this bucket:
   currentTotalCharsBilled: number;
 }
@@ -66,7 +65,7 @@ export async function processBucket(
 ): Promise<BucketContribution> {
   const { config, options, lockFile, sourceEntryMap, targetEntryMap,
     allContextSentKeys, allInstructionSentKeys, allInstructionGroupTotals,
-    keyContexts, localeTranslator, glossaryService, translationService, tmCache,
+    keyContexts, localeTranslator, localeGlossaryIds, localeTmIds,
     currentTotalCharsBilled } = deps;
   const { bucketConfig, parser, relPath, content, entries, isMultiLocale } = walked;
 
@@ -230,27 +229,6 @@ export async function processBucket(
     }
   }
 
-  const localeGlossaryIds = new Map<string, string>();
-  for (const locale of locales) {
-    const override = config.translation?.locale_overrides?.[locale]?.glossary;
-    if (override && override !== 'auto' && !options?.dryRun) {
-      localeGlossaryIds.set(locale, await glossaryService.resolveGlossaryId(override));
-    }
-  }
-
-  const localeTmIds = new Map<string, string>();
-  for (const locale of locales) {
-    const override = config.translation?.locale_overrides?.[locale]?.translation_memory;
-    if (override && !options?.dryRun) {
-      localeTmIds.set(locale, await resolveTranslationMemoryId(
-        translationService,
-        override,
-        tmCache,
-        { from: config.source_locale as Language, targets: [locale as Language] },
-      ));
-    }
-  }
-
   await mapWithConcurrency(locales, async (locale) => {
    if (options?.cancellationSignal?.cancelled) {
     return;
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index 3a15a861..c8c78f68 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -189,8 +189,16 @@ export class SyncService {
     let driftDetected = false;
     let lockDirty = false;
 
+    // Resolution runs for a dry run too. It costs one listing per kind, the
+    // command already needs an API key to reach this point, and a glossary or
+    // translation memory the config names but the account cannot use for the
+    // requested pair is exactly what a preview exists to report.
+    const effectiveLocales = options?.localeFilter?.length
+      ? config.target_locales.filter(l => options.localeFilter!.includes(l))
+      : config.target_locales;
+
     let resolvedGlossaryId: string | undefined;
-    if (config.translation?.glossary && config.translation.glossary !== 'auto' && !options?.dryRun) {
+    if (config.translation?.glossary && config.translation.glossary !== 'auto') {
       // The pair is known from the config, so a glossary that does not cover it
       // fails here rather than once per file, as with the translation memory
       // below.
@@ -203,11 +211,7 @@ export class SyncService {
           .filter(([, override]) => override?.glossary)
           .map(([locale]) => locale),
       );
-      const glossaryLocales = (
-        options?.localeFilter?.length
-          ? config.target_locales.filter(l => options.localeFilter!.includes(l))
-          : config.target_locales
-      ).filter(locale => !overriddenLocales.has(locale));
+      const glossaryLocales = effectiveLocales.filter(locale => !overriddenLocales.has(locale));
       resolvedGlossaryId = await this.glossaryService.resolveGlossaryId(
         config.translation.glossary,
         { from: config.source_locale as Language, targets: glossaryLocales as Language[] },
@@ -215,10 +219,7 @@ export class SyncService {
     }
 
     let resolvedTmId: string | undefined;
-    if (config.translation?.translation_memory && !options?.dryRun) {
-      const effectiveLocales = options?.localeFilter?.length
-        ? config.target_locales.filter(l => options.localeFilter!.includes(l))
-        : config.target_locales;
+    if (config.translation?.translation_memory) {
       resolvedTmId = await resolveTranslationMemoryId(
         this.translationService,
         config.translation.translation_memory,
@@ -227,6 +228,37 @@ export class SyncService {
       );
     }
 
+    // Per-locale overrides are resolved here rather than inside the bucket loop,
+    // which repeated the work for every file: an override that does not cover its
+    // own locale has to fail before anything is translated, not after earlier
+    // files have already been written. `auto` names no glossary to resolve — it
+    // is managed by the auto-glossary pass after translation.
+    const localeGlossaryIds = new Map<string, string>();
+    const localeTmIds = new Map<string, string>();
+    for (const locale of effectiveLocales) {
+      const override = config.translation?.locale_overrides?.[locale];
+      if (override?.glossary && override.glossary !== 'auto') {
+        localeGlossaryIds.set(
+          locale,
+          await this.glossaryService.resolveGlossaryId(override.glossary, {
+            from: config.source_locale as Language,
+            targets: [locale as Language],
+          }),
+        );
+      }
+      if (override?.translation_memory) {
+        localeTmIds.set(
+          locale,
+          await resolveTranslationMemoryId(
+            this.translationService,
+            override.translation_memory,
+            this.tmCache,
+            { from: config.source_locale as Language, targets: [locale as Language] },
+          ),
+        );
+      }
+    }
+
     let keyContexts = new Map<string, KeyContext>();
     let templatePatterns: TemplatePatternMatch[] = [];
     if (config.context?.enabled) {
@@ -307,9 +339,7 @@ export class SyncService {
         sourceEntryMap, targetEntryMap,
         allContextSentKeys, allInstructionSentKeys, allInstructionGroupTotals,
         keyContexts, localeTranslator,
-        glossaryService: this.glossaryService,
-        translationService: this.translationService,
-        tmCache: this.tmCache,
+        localeGlossaryIds, localeTmIds,
         currentTotalCharsBilled: totalCharsBilled,
       });
 
diff --git a/tests/integration/sync.integration.test.ts b/tests/integration/sync.integration.test.ts
index 46593591..5993c027 100644
--- a/tests/integration/sync.integration.test.ts
+++ b/tests/integration/sync.integration.test.ts
@@ -2527,9 +2527,9 @@ translation:
     });
   });
 
-  // ---- 9. Dry-run suppression ----
-  describe('dry-run suppression', () => {
-    it('makes zero list calls and zero translate calls when dryRun is set even with TM configured', async () => {
+  // ---- 9. Dry-run resolution ----
+  describe('dry-run resolution', () => {
+    it('resolves configured TMs during a dry run but sends nothing to translate', async () => {
       writeYamlConfig(
         tmpDir,
         `version: 1
@@ -2549,15 +2549,53 @@ translation:
       );
       writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
-      // No nock interceptors registered — any outbound request would
-      // surface as an unmatched-request error and fail the test.
+      // Only the listing is mocked. A /v2/translate request would be unmatched
+      // and fail the test, which is the invariant a dry run has to keep.
+      // Twice: the top-level name and the override name are separate cache keys.
+      const listScope = mockListTms(
+        [
+          { id: TM_UUID_MY, name: 'my-tm', source: 'en', target: 'de' },
+          { id: TM_UUID_DE_SPECIFIC, name: 'de-specific-tm', source: 'en', target: 'de' },
+        ],
+        2,
+      );
 
       const config = await loadSyncConfig(tmpDir);
       const result = await syncService.sync(config, { dryRun: true });
 
       expect(result.dryRun).toBe(true);
+      expect(listScope.isDone()).toBe(true);
       expect(nock.pendingMocks()).toEqual([]);
     });
+
+    it('fails a dry run when a per-locale override TM does not cover its locale', async () => {
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
+source_locale: en
+target_locales:
+  - de
+  - fr
+buckets:
+  json:
+    include:
+      - "locales/en.json"
+translation:
+  locale_overrides:
+    fr:
+      translation_memory: "de-only"
+`,
+      );
+      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
+
+      mockListTms([{ id: TM_UUID_DE, name: 'de-only', source: 'en', target: 'de' }]);
+
+      const config = await loadSyncConfig(tmpDir);
+      const caught = await syncService.sync(config, { dryRun: true }).catch((e: unknown) => e);
+
+      expect(caught).toBeInstanceOf(ConfigError);
+      expect((caught as Error).message).toMatch(/does not support the requested language pair/);
+    });
   });
 });
 
diff --git a/tests/unit/sync/sync-process-bucket.test.ts b/tests/unit/sync/sync-process-bucket.test.ts
index d14c963f..07e78844 100644
--- a/tests/unit/sync/sync-process-bucket.test.ts
+++ b/tests/unit/sync/sync-process-bucket.test.ts
@@ -7,9 +7,7 @@ import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
 import type { SyncLockFile } from '../../../src/sync/types';
 import type { WalkedBucketFile } from '../../../src/sync/sync-bucket-walker';
 import type { LocaleTranslator, TranslateLocaleResult } from '../../../src/sync/sync-locale-translator';
-import type { GlossaryService } from '../../../src/services/glossary';
 import { ValidationError } from '../../../src/utils/errors';
-import { createMockTranslationService } from '../../helpers/mock-factories';
 
 jest.mock('../../../src/utils/logger', () => ({
   Logger: {
@@ -77,9 +75,8 @@ function makeDeps(
     allInstructionGroupTotals: new Map(),
     keyContexts: new Map(),
     localeTranslator: { translate } as unknown as LocaleTranslator,
-    glossaryService: { resolveGlossaryId: jest.fn() } as unknown as GlossaryService,
-    translationService: createMockTranslationService(),
-    tmCache: { has: () => false, get: () => undefined, set: () => undefined },
+    localeGlossaryIds: new Map(),
+    localeTmIds: new Map(),
     currentTotalCharsBilled: 0,
   };
 }
diff --git a/tests/unit/sync/sync-service.test.ts b/tests/unit/sync/sync-service.test.ts
index 40699b4f..309b17b2 100644
--- a/tests/unit/sync/sync-service.test.ts
+++ b/tests/unit/sync/sync-service.test.ts
@@ -7,7 +7,7 @@ import { FormatRegistry } from '../../../src/formats/index';
 import type { FormatParser, ExtractedEntry, TranslatedEntry } from '../../../src/formats/format';
 import { JsonFormatParser } from '../../../src/formats/json';
 import { YamlFormatParser } from '../../../src/formats/yaml';
-import { ValidationError } from '../../../src/utils/errors';
+import { ValidationError, ConfigError } from '../../../src/utils/errors';
 
 jest.mock('fast-glob', () => {
   const mockFn = Object.assign(
@@ -1783,7 +1783,12 @@ describe('SyncService', () => {
       });
       await service.sync(config);
 
-      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('my-glossary');
+      // With the override's own locale as the pair, so a glossary that does not
+      // cover it fails at startup rather than reaching the API.
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+        from: 'en',
+        targets: ['de'],
+      });
       expect(translateBatch).toHaveBeenCalledWith(
         expect.anything(),
         expect.objectContaining({ glossaryId: 'resolved-glossary-id-123' }),
@@ -2353,20 +2358,20 @@ describe('SyncService', () => {
       expect((deCall![1] as Record<string, unknown>)['translationMemoryThreshold']).toBe(90);
     });
 
-    it('should not resolve TM during dryRun', async () => {
+    it('should resolve the top-level TM during dryRun so the preview validates it', async () => {
       setupLockManager(makeEmptyLockFile());
       const { service, mockTranslation } = createService();
+      mockTranslation.listTranslationMemories.mockResolvedValue([
+        { translation_memory_id: TM_UUID_A, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+      ]);
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
       await service.sync(makeConfig({
-        translation: {
-          translation_memory: 'my-tm',
-          locale_overrides: { de: { translation_memory: 'de-tm' } },
-        },
+        translation: { translation_memory: 'my-tm' },
       }), { dryRun: true });
 
-      expect(mockTranslation.listTranslationMemories).not.toHaveBeenCalled();
+      expect(mockTranslation.listTranslationMemories).toHaveBeenCalled();
     });
 
     it('should throw ConfigError when top-level TM does not support all target locales', async () => {
@@ -2432,16 +2437,130 @@ describe('SyncService', () => {
       });
     });
 
-    it('should not resolve glossary during dryRun', async () => {
+    it('should resolve glossary during dryRun so the preview validates the config', async () => {
+      // A dry run reports what a real run would do, and already needs an API key
+      // to get this far, so a glossary the config names but the account cannot
+      // use is something the preview has to surface.
       const { service, mockGlossary } = createService();
       setupLockManager(makeEmptyLockFile());
       mockFg.mockResolvedValue(['/test/locales/en.json']);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
+      mockGlossary.resolveGlossaryId.mockResolvedValue('glos-123');
 
       await service.sync(makeConfig({
         translation: { glossary: 'my-glossary' },
       }), { dryRun: true });
 
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+        from: 'en',
+        targets: ['de'],
+      });
+    });
+
+    it('should surface a top-level glossary that does not cover the pair during dryRun', async () => {
+      const { service, mockGlossary } = createService();
+      setupLockManager(makeEmptyLockFile());
+      mockFg.mockResolvedValue(['/test/locales/en.json']);
+      mockReadFile.mockResolvedValue(SOURCE_JSON);
+      mockGlossary.resolveGlossaryId.mockRejectedValue(
+        new ConfigError('Glossary "my-glossary" does not support the requested language pair'),
+      );
+
+      await expect(
+        service.sync(makeConfig({ translation: { glossary: 'my-glossary' } }), { dryRun: true }),
+      ).rejects.toThrow(/does not support the requested language pair/);
+    });
+
+    it('should check a per-locale override glossary against its own locale at startup', async () => {
+      const { service, mockGlossary } = createService();
+      setupLockManager(makeEmptyLockFile());
+      mockFg.mockResolvedValue(['/test/locales/en.json']);
+      mockReadFile.mockResolvedValue(SOURCE_JSON);
+      mockGlossary.resolveGlossaryId.mockResolvedValue('glos-fr');
+
+      await service.sync(makeConfig({
+        target_locales: ['de', 'fr'],
+        translation: {
+          locale_overrides: { fr: { glossary: 'fr-terms' } },
+        },
+      }));
+
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('fr-terms', {
+        from: 'en',
+        targets: ['fr'],
+      });
+    });
+
+    it('should fail once at startup when an override glossary does not cover its locale', async () => {
+      // Resolution also runs per file, where the same rejection was reported
+      // once per file rather than once for the run.
+      const { service, mockGlossary } = createService();
+      setupLockManager(makeEmptyLockFile());
+      mockFg.mockResolvedValue(['/test/locales/en.json']);
+      mockReadFile.mockResolvedValue(SOURCE_JSON);
+      mockGlossary.resolveGlossaryId.mockRejectedValue(
+        new ConfigError('Glossary "fr-terms" does not support the requested language pair'),
+      );
+
+      await expect(service.sync(makeConfig({
+        target_locales: ['de', 'fr'],
+        translation: {
+          locale_overrides: { fr: { glossary: 'fr-terms' } },
+        },
+      }))).rejects.toThrow(/does not support the requested language pair/);
+
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledTimes(1);
+    });
+
+    it('should check override glossaries during dryRun too', async () => {
+      const { service, mockGlossary } = createService();
+      setupLockManager(makeEmptyLockFile());
+      mockFg.mockResolvedValue(['/test/locales/en.json']);
+      mockReadFile.mockResolvedValue(SOURCE_JSON);
+      mockGlossary.resolveGlossaryId.mockResolvedValue('glos-fr');
+
+      await service.sync(makeConfig({
+        target_locales: ['de', 'fr'],
+        translation: {
+          locale_overrides: { fr: { glossary: 'fr-terms' } },
+        },
+      }), { dryRun: true });
+
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('fr-terms', {
+        from: 'en',
+        targets: ['fr'],
+      });
+    });
+
+    it('should not resolve an "auto" override glossary, which is managed rather than named', async () => {
+      const { service, mockGlossary } = createService();
+      setupLockManager(makeEmptyLockFile());
+      mockFg.mockResolvedValue(['/test/locales/en.json']);
+      mockReadFile.mockResolvedValue(SOURCE_JSON);
+
+      await service.sync(makeConfig({
+        target_locales: ['de'],
+        translation: {
+          locale_overrides: { de: { glossary: 'auto' } },
+        },
+      }));
+
+      expect(mockGlossary.resolveGlossaryId).not.toHaveBeenCalled();
+    });
+
+    it('should skip an override for a locale the filter excludes', async () => {
+      const { service, mockGlossary } = createService();
+      setupLockManager(makeEmptyLockFile());
+      mockFg.mockResolvedValue(['/test/locales/en.json']);
+      mockReadFile.mockResolvedValue(SOURCE_JSON);
+
+      await service.sync(makeConfig({
+        target_locales: ['de', 'fr'],
+        translation: {
+          locale_overrides: { fr: { glossary: 'fr-terms' } },
+        },
+      }), { localeFilter: ['de'] });
+
       expect(mockGlossary.resolveGlossaryId).not.toHaveBeenCalled();
     });
   });

From 0fb522a0244720e0663af0288ff659650c94102b Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 09:23:18 -0400
Subject: [PATCH 059/256] test(languages): pin the supportsFormality JSON
 contract

The field moved from v2's supports_formality boolean to the v3 features
matrix, and is now omitted for a target whose features the response does
not describe rather than reported as false. /v3/languages carries a matrix
for all 125 languages it lists, so the serialized shape is the same one
1.2.0 produced -- present and boolean for every target, absent for every
source. Nothing was asserting that, so nothing would have caught it
changing.

Also states the omission case in the CHANGELOG next to the "existing JSON
consumers are unaffected" claim, which spoke only for the features matrix.

Closes cli-01on.5
---
 CHANGELOG.md                            |  2 +-
 tests/e2e/cli-success-paths.e2e.test.ts | 34 ++++++++++++++++++
 tests/unit/deepl-client.test.ts         | 47 +++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dec0e21d..ef43e990 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API: `POST /v2/translate` accepts `glossary_ids` as repeated form fields and resolves them in order, rejects a sixth with `A maximum of 5 glossaries can be specified per request.`, and rejects `glossary_id` and `glossary_ids` together with `Specify either glossary_id or glossary_ids, not both.` -- which is why the CLI collapses a single glossary to `glossary_id` rather than sending both. The multipart `POST /v2/document` takes one comma-joined value, since multipart does not parse repeated fields as a list; that endpoint answers any unresolvable glossary with `glossary_ids is not valid` regardless of encoding, so it was confirmed only to the extent that it recognises the parameter, and the list semantics there rest on the API documentation rather than on a live round trip.
 
-- **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`, which the CLI previously discarded. Support no longer has to be discovered by making a request and reading the error. Which features get a column is derived from the response rather than a fixed list: a feature appears when its support differs across the languages listed, and one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row (`All languages with reported features also support: ...` when the listing also carries languages the response did not describe, since the note must not speak for those). A language the response omitted reads as `no feature data` rather than as supporting nothing, and does not count towards whether a feature varies. That makes the columns differ between listings — `auto detection` appears under `--target`, where target-only variants lack it, but is uniform under `--source` — and means a newly reported feature shows up without a code change. Support is signalled by the API reporting a feature at all; `status` describes maturity, so anything short of generally available renders verbatim (`glossary (beta)`) rather than collapsing to `yes`. Works with `--format table` (one column per feature) and `--format json` (the raw matrix including each status, present only when `--features` is passed, so existing JSON consumers are unaffected). `--features` supersedes the `[F]` shorthand and replaces it when given. It needs an API key; without one the command warns and falls back to the registry, which carries no feature data. Note that the matrix is finer-grained than the core/regional/extended tiers: some extended languages support style rules and translation memory even though they support neither formality nor glossary.
+- **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`, which the CLI previously discarded. Support no longer has to be discovered by making a request and reading the error. Which features get a column is derived from the response rather than a fixed list: a feature appears when its support differs across the languages listed, and one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row (`All languages with reported features also support: ...` when the listing also carries languages the response did not describe, since the note must not speak for those). A language the response omitted reads as `no feature data` rather than as supporting nothing, and does not count towards whether a feature varies. That makes the columns differ between listings — `auto detection` appears under `--target`, where target-only variants lack it, but is uniform under `--source` — and means a newly reported feature shows up without a code change. Support is signalled by the API reporting a feature at all; `status` describes maturity, so anything short of generally available renders verbatim (`glossary (beta)`) rather than collapsing to `yes`. Works with `--format table` (one column per feature) and `--format json` (the raw matrix including each status, present only when `--features` is passed, so existing JSON consumers are unaffected). The `supportsFormality` field is unchanged for every language `GET /v3/languages` describes, which is all of them today; it now comes from the matrix rather than v2's `supports_formality` boolean, and is **omitted rather than reported as `false`** for a target the response says nothing about, since silence is not evidence that formality is absent. `--features` supersedes the `[F]` shorthand and replaces it when given. It needs an API key; without one the command warns and falls back to the registry, which carries no feature data. Note that the matrix is finer-grained than the core/regional/extended tiers: some extended languages support style rules and translation memory even though they support neither formality nor glossary.
 
 - **cli**: `deepl correct` command (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`), but not `--style`/`--tone`, which the correct endpoint does not accept. Results are cached under a separate `correct:` namespace so corrections and rephrasings of the same text never collide.
 
diff --git a/tests/e2e/cli-success-paths.e2e.test.ts b/tests/e2e/cli-success-paths.e2e.test.ts
index d1d2d818..5245aafb 100644
--- a/tests/e2e/cli-success-paths.e2e.test.ts
+++ b/tests/e2e/cli-success-paths.e2e.test.ts
@@ -271,5 +271,39 @@ describe('CLI Success Paths E2E', () => {
       const output = runCLIAll('languages');
       expect(output).toContain('Source Languages:');
     });
+
+    it('should report supportsFormality on every target in --format json', () => {
+      // The documented JSON shape for targets. The features matrix rides along on
+      // the same objects and is stripped without --features, so the two must not
+      // be confused: this field stays.
+      const output = runCLI('languages --target --format json');
+      const parsed = JSON.parse(output.trim()) as Array<Record<string, unknown>>;
+
+      expect(parsed.length).toBeGreaterThan(0);
+      for (const entry of parsed) {
+        expect(entry).toHaveProperty('supportsFormality');
+        expect(typeof entry['supportsFormality']).toBe('boolean');
+        expect(entry).not.toHaveProperty('features');
+      }
+      expect(parsed.find(e => e['language'] === 'de')?.['supportsFormality']).toBe(true);
+      expect(parsed.find(e => e['language'] === 'en')?.['supportsFormality']).toBe(false);
+    });
+
+    it('should omit supportsFormality from source languages in --format json', () => {
+      const output = runCLI('languages --source --format json');
+      const parsed = JSON.parse(output.trim()) as Array<Record<string, unknown>>;
+
+      expect(parsed.length).toBeGreaterThan(0);
+      for (const entry of parsed) {
+        expect(entry).not.toHaveProperty('supportsFormality');
+      }
+    });
+
+    it('should include the features matrix only with --features', () => {
+      const output = runCLI('languages --target --features --format json');
+      const parsed = JSON.parse(output.trim()) as Array<Record<string, unknown>>;
+
+      expect(parsed.find(e => e['language'] === 'de')).toHaveProperty('features');
+    });
   });
 });
diff --git a/tests/unit/deepl-client.test.ts b/tests/unit/deepl-client.test.ts
index 4d28befa..293a1d2c 100644
--- a/tests/unit/deepl-client.test.ts
+++ b/tests/unit/deepl-client.test.ts
@@ -857,6 +857,53 @@ describe('DeepLClient', () => {
       expect(languages.find(l => l.language === 'ko')?.supportsFormality).toBe(false);
     });
 
+    it('should report formality for every target the response describes', async () => {
+      // The field is part of the JSON contract for targets: /v3/languages carries
+      // a features matrix for every language it lists, so every target answers.
+      nock(baseUrl)
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
+        .reply(200, [
+          { lang: 'de', name: 'German', usable_as_target: true, features: { formality: { status: 'stable' } } },
+          { lang: 'sw', name: 'Swahili', usable_as_target: true, features: { tag_handling: { status: 'stable' } } },
+        ]);
+
+      const languages = await client.getSupportedLanguages('target');
+
+      expect(languages).toHaveLength(2);
+      for (const language of languages) {
+        expect(language).toHaveProperty('supportsFormality');
+      }
+    });
+
+    it('should omit formality rather than deny it for a target with no features', async () => {
+      // Silence about a language is not evidence that formality is absent, and
+      // `false` would turn on the [F] legend with nothing beneath it.
+      nock(baseUrl)
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
+        .reply(200, [
+          { lang: 'de', name: 'German', usable_as_target: true },
+        ]);
+
+      const languages = await client.getSupportedLanguages('target');
+
+      expect(languages[0]).not.toHaveProperty('supportsFormality');
+    });
+
+    it('should never report formality for source languages', async () => {
+      nock(baseUrl)
+        .get('/v3/languages')
+        .query({ resource: 'translate_text' })
+        .reply(200, [
+          { lang: 'de', name: 'German', usable_as_source: true, features: { formality: { status: 'stable' } } },
+        ]);
+
+      const languages = await client.getSupportedLanguages('source');
+
+      expect(languages[0]).not.toHaveProperty('supportsFormality');
+    });
+
     it('should handle language API errors', async () => {
       nock(baseUrl)
         .get('/v3/languages')

From 8e209fe8185e124f2252eba8e6d513aed41ad4fa Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 09:30:11 -0400
Subject: [PATCH 060/256] docs: correct example output, the language endpoint,
 and the glossary rule

Display output went lowercase in d15bc89 but several examples still showed
`[ES]` and `| ES |` table cells, so copied output did not match reality.
Two file-translation examples were wrong beyond casing: a single-target run
prints `Translated x -> y`, not a `to 1 language(s):` list. Verified each
against a real run.

TROUBLESHOOTING's reachability check called /v2/languages, which this
release migrates off; it now uses /v3/languages?resource=translate_text and
names both hosts, since the free host answers a Pro key with 403 -- a
reachable server, which is what the check is asking about.

--glossary was documented as requiring --from in four places, which stopped
being true when the requirement started accepting defaults.sourceLang, and
the translate flag reference omitted it entirely. All five now state the
implemented rule.

Adds two mechanical guards to the docs suite, which previously checked only
that documented commands and flags exist: no documented line may show an
uppercase language code (matched against the registry, so markdown badges
are left alone), and no doc may reference a retired v2 language endpoint.

Closes cli-01on.9
---
 README.md                                  | 38 ++++++++++----------
 docs/API.md                                | 18 +++++-----
 docs/TROUBLESHOOTING.md                    |  6 +++-
 tests/unit/docs/documented-surface.test.ts | 41 ++++++++++++++++++++++
 4 files changed, 73 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index 1e1b61ea..fdd7f4a1 100644
--- a/README.md
+++ b/README.md
@@ -283,9 +283,9 @@ deepl translate "Bonjour" --from fr --to en
 
 # Multiple target languages (each result is prefixed with its language)
 deepl translate "Good morning" --to es,fr,de
-# [ES] Buenos días
-# [FR] Bonjour
-# [DE] Guten Morgen
+# [es] Buenos días
+# [fr] Bonjour
+# [de] Guten Morgen
 
 # Read from stdin
 echo "Hello world" | deepl translate --to es
@@ -325,15 +325,14 @@ Small text-based files (under 100 KiB) automatically use the cached text transla
 ```bash
 # Single file translation (uses cache for small text files)
 deepl translate README.md --to es --output README.es.md
-# Translated README.md to 1 language(s):
-#   [ES] README.es.md
+# Translated README.md -> README.es.md
 
 # Multiple target languages (creates README.es.md, README.fr.md, etc.)
 deepl translate docs.md --to es,fr,de --output ./translated/
-# Translated docs.md to 3 language(s):
-#   [ES] ./translated/docs.es.md
-#   [FR] ./translated/docs.fr.md
-#   [DE] ./translated/docs.de.md
+# Translated docs.md to 3 languages:
+#   [es] ./translated/docs.es.md
+#   [fr] ./translated/docs.fr.md
+#   [de] ./translated/docs.de.md
 
 # With code preservation (preserves code blocks in markdown)
 deepl translate tutorial.md --to ja --output tutorial.ja.md --preserve-code
@@ -341,8 +340,7 @@ deepl translate tutorial.md --to ja --output tutorial.ja.md --preserve-code
 # Large text file (over 100 KiB) - automatic fallback with warning
 deepl translate large-document.txt --to es --output large-document.es.txt
 # ⚠ File exceeds 100 KiB limit for cached translation (150.5 KiB), using document API instead
-# Translated large-document.txt to 1 language(s):
-#   [ES] large-document.es.txt
+# Translated large-document.txt -> large-document.es.txt
 ```
 
 #### Document Translation
@@ -377,7 +375,7 @@ deepl translate contract.pdf --to de --formality more --output contract.de.pdf
 # Specify source language
 deepl translate document.pdf --from en --to es --output document.es.pdf
 
-# Apply a glossary (--from is required whenever a glossary is used)
+# Apply a glossary (needs a source language: --from, or defaults.sourceLang)
 deepl translate report.docx --from en --to de --glossary tech-terms --output report.de.docx
 
 # Repeat --glossary for up to 5; the last one wins a conflicting term
@@ -400,7 +398,7 @@ deepl translate document.pdf --to es --output-format docx --output document.es.d
 - ✅ **Progress Tracking** - Real-time status updates during translation
 - ✅ **Large Files** - Handles documents up to 30MB
 - ✅ **Cost Tracking** - Shows billed characters after translation
-- ✅ **Glossaries** - `--glossary` applies to documents too, repeatable up to 5 (requires `--from`). Translation memories are not supported for documents.
+- ✅ **Glossaries** - `--glossary` applies to documents too, repeatable up to 5 (needs a source language: `--from`, or `defaults.sourceLang`). Translation memories are not supported for documents.
 - ✅ **Async Processing** - Documents are translated on DeepL servers with polling
 
 **Supported Formats:**
@@ -523,9 +521,9 @@ deepl translate "Hello, world!" --to es,fr,de --format table
 # ┌──────────┬──────────────────────────────────────────────────────────────────────┐
 # │ Language │ Translation                                                          │
 # ├──────────┼──────────────────────────────────────────────────────────────────────┤
-# │ ES       │ ¡Hola, mundo!                                                        │
-# │ FR       │ Bonjour le monde!                                                    │
-# │ DE       │ Hallo, Welt!                                                         │
+# │ es       │ ¡Hola, mundo!                                                        │
+# │ fr       │ Bonjour le monde!                                                    │
+# │ de       │ Hallo, Welt!                                                         │
 # └──────────┴──────────────────────────────────────────────────────────────────────┘
 
 # Table format with cost tracking (adds Characters column)
@@ -533,9 +531,9 @@ deepl translate "Cost analysis" --to es,fr,de --format table --show-billed-chara
 # ┌──────────┬────────────────────────────────────────────────────────────┬────────────┐
 # │ Language │ Translation                                                │ Characters │
 # ├──────────┼────────────────────────────────────────────────────────────┼────────────┤
-# │ ES       │ Análisis de costes                                         │ 14         │
-# │ FR       │ Analyse des coûts                                          │ 14         │
-# │ DE       │ Kostenanalyse                                              │ 14         │
+# │ es       │ Análisis de costes                                         │ 14         │
+# │ fr       │ Analyse des coûts                                          │ 14         │
+# │ de       │ Kostenanalyse                                              │ 14         │
 # └──────────┴────────────────────────────────────────────────────────────┴────────────┘
 
 # Preview what would be translated without making API calls (file/directory mode)
@@ -1307,7 +1305,7 @@ authentication	Authentifizierung
 - **Direct updates** - v3 API uses PATCH endpoints for efficient updates (no delete+recreate)
 - **Smart defaults** - `--target` flag only required for multilingual glossaries
 - **Visual indicators** - 📖 for single-target, 📚 for multilingual glossaries
-- **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms (`--from` is required alongside it; the API rejects a glossary without a source language)
+- **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms (a source language is required, since the API rejects a glossary without one: pass `--from`, or set `defaults.sourceLang`)
 - **Several glossaries at once** - Repeat `--glossary` on `translate` for up to 5 glossaries; entries are merged and the last glossary given wins any conflicting term
 
 ```bash
diff --git a/docs/API.md b/docs/API.md
index 057434fb..689a2e41 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -251,7 +251,7 @@ Translate text directly, from stdin, from files, or entire directories. Supports
 - `--non-splitting-tags TAGS` - Comma-separated XML tags that should not be used to split sentences (requires `--tag-handling xml`)
 - `--ignore-tags TAGS` - Comma-separated XML tags with content to ignore (requires `--tag-handling xml`)
 - `--tag-handling-version VERSION` - Tag handling version: `v1`, `v2`. v2 improves XML/HTML structure handling (requires `--tag-handling`). **Defaults to `v2`**, sent explicitly on every `--tag-handling` request rather than left to the API's own default, which is documented as moving from v1 to v2 at some point — pinning keeps output from shifting on DeepL's timetable. Pass `--tag-handling-version v1` for the older behaviour, which DeepL documents as heading for deprecation
-- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. Repeatable, up to 5 per request; when several glossaries define the same source term, the last one given wins. Passing a 6th exits 6 (ValidationError).
+- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. Repeatable, up to 5 per request; when several glossaries define the same source term, the last one given wins. Passing a 6th exits 6 (ValidationError). A source language is required, because the API rejects a glossary without one: supply `--from`, or set `defaults.sourceLang` and it is used automatically. With neither, the command exits 6 before any request.
 - `--translation-memory NAME-OR-UUID` - Use translation memory by name or UUID (forces `quality_optimized` model). Requires `--from` because TMs are pinned to a specific source→target language pair. Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
 - `--tm-threshold N` - Minimum match score 0–100 (default 75, requires `--translation-memory`). Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
 - `--custom-instruction INSTRUCTION` - Custom instruction for translation (repeatable, max 10, max 300 chars each). Forces `quality_optimized` model. Cannot be used with `latency_optimized`.
@@ -447,7 +447,7 @@ deepl translate report.docx --from en --to de --output report.de.docx \
 - Large documents may take several seconds to translate
 - Maximum file sizes: 30MB (document API, all formats), 100 KiB (cached text API)
 - **Document minification** (`--enable-minification`): Reduces file size for PPTX and DOCX files only. Useful for large presentations and documents.
-- **Glossaries**: `--glossary` applies to documents and is repeatable up to 5, with the same last-one-wins precedence as text translation. `--from` is required — the API rejects a document glossary without a source language ("source_lang has to be specified in order to use a glossary"). Glossary matching is context-dependent exactly as it is for text: a term may be applied in one sentence and left alone in another, and a bare newline-separated word list often gets few terms applied. `--translation-memory` remains unsupported for documents.
+- **Glossaries**: `--glossary` applies to documents and is repeatable up to 5, with the same last-one-wins precedence as text translation. A source language is required — the API rejects a document glossary without one ("source_lang has to be specified in order to use a glossary") — so pass `--from`, or set `defaults.sourceLang` and it is used automatically. Glossary matching is context-dependent exactly as it is for text: a term may be applied in one sentence and left alone in another, and a bare newline-separated word list often gets few terms applied. `--translation-memory` remains unsupported for documents.
 
 **Directory translation:**
 
@@ -665,9 +665,9 @@ deepl translate "Hello, world!" --to es,fr,de --format table
 # ┌──────────┬──────────────────────────────────────────────────────────────────────┐
 # │ Language │ Translation                                                          │
 # ├──────────┼──────────────────────────────────────────────────────────────────────┤
-# │ ES       │ ¡Hola mundo!                                                         │
-# │ FR       │ Bonjour le monde!                                                    │
-# │ DE       │ Hallo Welt!                                                          │
+# │ es       │ ¡Hola mundo!                                                         │
+# │ fr       │ Bonjour le monde!                                                    │
+# │ de       │ Hallo Welt!                                                          │
 # └──────────┴──────────────────────────────────────────────────────────────────────┘
 
 # Add --show-billed-characters to display the Characters column
@@ -675,9 +675,9 @@ deepl translate "Cost tracking" --to es,fr,de --format table --show-billed-chara
 # ┌──────────┬────────────────────────────────────────────────────────────────┬────────────┐
 # │ Language │ Translation                                                    │ Characters │
 # ├──────────┼────────────────────────────────────────────────────────────────┼────────────┤
-# │ ES       │ Seguimiento de costes                                          │ 16         │
-# │ FR       │ Suivi des coûts                                                │ 16         │
-# │ DE       │ Kostenverfolgung                                               │ 16         │
+# │ es       │ Seguimiento de costes                                          │ 16         │
+# │ fr       │ Suivi des coûts                                                │ 16         │
+# │ de       │ Kostenverfolgung                                               │ 16         │
 # └──────────┴────────────────────────────────────────────────────────────────┴────────────┘
 
 # Long translations automatically wrap in the Translation column
@@ -1122,7 +1122,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 - `--formality LEVEL` - Formality level: `default`, `more`, `less`, `prefer_more`, `prefer_less`, `formal`, `informal`
 - `--preserve-code` - Preserve code blocks
 - `--preserve-formatting` - Preserve line breaks and whitespace formatting
-- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. `--from` is required, because the API refuses a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"); omitting it exits 6 before the watcher starts rather than failing on every file change. Unlike `translate`, `watch` takes a single glossary.
+- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. A source language is required, because the API refuses a glossary without one ("Use of a glossary requires the source_lang parameter to be specified"): pass `--from`, or set `defaults.sourceLang` and it is used automatically. With neither, the command exits 6 before the watcher starts rather than failing on every file change. Unlike `translate`, `watch` takes a single glossary.
 
 **Git Integration:**
 
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index d6146efa..a639e965 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -156,7 +156,11 @@ Common issues and solutions when using the DeepL CLI.
 2. Verify DeepL API is reachable:
 
    ```bash
-   curl -s https://api-free.deepl.com/v2/languages -H "Authorization: DeepL-Auth-Key YOUR_KEY"
+   # Free keys (those ending in :fx)
+   curl -s "https://api-free.deepl.com/v3/languages?resource=translate_text" -H "Authorization: DeepL-Auth-Key YOUR_KEY"
+
+   # Pro keys — the free host answers a Pro key with 403, which is a reachable server
+   curl -s "https://api.deepl.com/v3/languages?resource=translate_text" -H "Authorization: DeepL-Auth-Key YOUR_KEY"
    ```
 
 3. If behind a corporate proxy, configure it via environment variables:
diff --git a/tests/unit/docs/documented-surface.test.ts b/tests/unit/docs/documented-surface.test.ts
index 0872d9a1..b1be8c93 100644
--- a/tests/unit/docs/documented-surface.test.ts
+++ b/tests/unit/docs/documented-surface.test.ts
@@ -7,6 +7,7 @@
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
+import { getAllLanguageCodes } from '../../../src/data/language-registry';
 
 interface DescribedCommand {
   name: string;
@@ -22,6 +23,8 @@ const DOCS = ['README.md', 'docs/API.md', 'docs/SYNC.md', 'docs/TROUBLESHOOTING.
 /** Deliberate misspellings used to demonstrate did-you-mean suggestions. */
 const TYPO_EXAMPLES = new Set(['transalte', 'translte', 'glossry', 'conifg', 'descibe']);
 
+const LANGUAGE_CODES = getAllLanguageCodes();
+
 function longFlags(options: { flags: string }[]): string[] {
   return options.flatMap((option) => option.flags.match(/--[a-z0-9-]+/g) ?? []);
 }
@@ -119,5 +122,43 @@ describe('documented CLI surface', () => {
 
       expect(unknown).toEqual([]);
     });
+
+    it('shows language codes in the lowercase the CLI prints', () => {
+      // Every code the CLI displays is lowercase. Documented output that shows
+      // `[ES]` or a `│ ES │` table cell does not match what a reader will see,
+      // and copying it into a script that compares codes gives a wrong answer.
+      // Matched against the registry so markdown badges like `[![CI](...)]` and
+      // labels that are not languages are left alone.
+      const lines = fs.readFileSync(path.join(ROOT, docPath), 'utf-8').split('\n');
+      const offenders: string[] = [];
+
+      for (const line of lines) {
+        const candidates = [
+          ...(line.match(/\[([A-Z]{2,3}(?:-[A-Z0-9]{2,4})?)\]/g) ?? []),
+          ...(line.match(/│\s*([A-Z]{2,3}(?:-[A-Z0-9]{2,4})?)\s*│/g) ?? []),
+        ];
+        for (const candidate of candidates) {
+          const code = candidate.replace(/[[\]│\s]/g, '').toLowerCase();
+          if (LANGUAGE_CODES.has(code)) {
+            offenders.push(`${candidate.trim()}  in  ${line.trim()}`);
+          }
+        }
+      }
+
+      expect(offenders).toEqual([]);
+    });
+  });
+
+  describe('retired endpoints', () => {
+    // Language listings moved to GET /v3/languages; the v2 endpoints are
+    // formally deprecated, so no doc should teach a reader to call them.
+    const RETIRED = ['/v2/languages', '/v2/glossary-language-pairs'];
+
+    it.each(DOCS)('%s references no retired language endpoint', (docPath) => {
+      const contents = fs.readFileSync(path.join(ROOT, docPath), 'utf-8');
+      const found = RETIRED.filter((endpoint) => contents.includes(endpoint));
+
+      expect(found).toEqual([]);
+    });
   });
 });

From fa7b4eb542a081a270985782eeff099a26f267f4 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 16:41:18 -0400
Subject: [PATCH 061/256] fix(watch): settle the glossary source language in
 the handler, not the registrar

register-watch filled options.from from defaults.sourceLang before calling
watch(), while the handler kept a flag-only guard -- so a library consumer
calling WatchCommand.watch() directly with a glossary and a configured
source language got a rejection the CLI does not make.

The handler now calls the shared applyGlossarySourceLang, as every other
command does, and WatchCommand takes the config service to read the default
from. The parameter is optional, so a caller with no configuration still
gets the requirement, just without a default to satisfy it from.

Closes cli-01on.6
---
 src/cli/commands/service-factory.ts         |  2 +-
 src/cli/commands/watch.ts                   | 27 ++++++++---
 tests/unit/register-commands-group1.test.ts |  8 +++-
 tests/unit/watch-command.test.ts            | 50 +++++++++++++++++++++
 4 files changed, 80 insertions(+), 7 deletions(-)

diff --git a/src/cli/commands/service-factory.ts b/src/cli/commands/service-factory.ts
index 31210c1e..67df690c 100644
--- a/src/cli/commands/service-factory.ts
+++ b/src/cli/commands/service-factory.ts
@@ -111,7 +111,7 @@ export async function createWatchCommand(
   const { WatchCommand: WatchCmd } = await import('./watch.js');
   const translationService = new TranslationService(client, deps.getConfigService(), await deps.getCacheService());
   const glossaryService = new GlossaryService(client);
-  return new WatchCmd(translationService, glossaryService);
+  return new WatchCmd(translationService, glossaryService, deps.getConfigService());
 }
 
 export async function createDetectCommand(
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index e3c03cfa..759bdb4d 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -14,6 +14,8 @@ import { Language, Formality } from '../../types/index.js';
 import { FileTranslationResult, WatchTranslationResult } from '../../services/watch.js';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
+import { applyGlossarySourceLang, hasGlossarySelection } from '../../utils/glossary-params.js';
+import type { ConfigService } from '../../storage/config.js';
 
 interface WatchOptions {
   to: string;
@@ -33,11 +35,22 @@ interface WatchOptions {
 export class WatchCommand {
   private fileTranslationService: FileTranslationService;
   private glossaryService: GlossaryService;
+  private config?: ConfigService;
   private watchService?: WatchService;
 
-  constructor(translationService: TranslationService, glossaryService: GlossaryService) {
+  /**
+   * `config` supplies `defaults.sourceLang` for the glossary requirement below.
+   * Optional so a caller that has no configuration still gets the requirement,
+   * just without a default to satisfy it from.
+   */
+  constructor(
+    translationService: TranslationService,
+    glossaryService: GlossaryService,
+    config?: ConfigService,
+  ) {
     this.fileTranslationService = new FileTranslationService(translationService);
     this.glossaryService = glossaryService;
+    this.config = config;
   }
 
   private async resolveGlossaryId(
@@ -89,10 +102,14 @@ export class WatchCommand {
 
     // The API rejects any translation naming a glossary without source_lang, so
     // an unguarded watch session fails once per file change instead of at launch.
-    if (options.glossary && !options.from) {
-      throw new ValidationError(
-        'Source language (--from) is required when using a glossary',
-        'Example: deepl watch ./docs --from en --to es --glossary my-glossary'
+    // Settled from `defaults.sourceLang` when the flag is absent, the same way
+    // every other command does it, so a direct call and the CLI agree on what is
+    // runnable.
+    if (hasGlossarySelection(options)) {
+      applyGlossarySourceLang(
+        options,
+        this.config?.getValue<string>('defaults.sourceLang'),
+        'Example: deepl watch ./docs --from en --to es --glossary my-glossary',
       );
     }
 
diff --git a/tests/unit/register-commands-group1.test.ts b/tests/unit/register-commands-group1.test.ts
index 7c756d83..b090bd6c 100644
--- a/tests/unit/register-commands-group1.test.ts
+++ b/tests/unit/register-commands-group1.test.ts
@@ -372,7 +372,13 @@ describe('service-factory', () => {
     const { GlossaryService } = require('../../src/services/glossary');
     expect(GlossaryService).toHaveBeenCalledWith(mockClient);
     const { WatchCommand } = require('../../src/cli/commands/watch');
-    expect(WatchCommand).toHaveBeenCalledWith(mockTranslationServiceObj, mockGlossaryServiceObj);
+    // The config service too: WatchCommand settles the glossary source language
+    // from defaults.sourceLang, so a CLI watch and a direct call agree.
+    expect(WatchCommand).toHaveBeenCalledWith(
+      mockTranslationServiceObj,
+      mockGlossaryServiceObj,
+      mockConfigService,
+    );
     expect(cmd).toBe(mockWatchCmdObj);
   });
 
diff --git a/tests/unit/watch-command.test.ts b/tests/unit/watch-command.test.ts
index c68068a5..7e354679 100644
--- a/tests/unit/watch-command.test.ts
+++ b/tests/unit/watch-command.test.ts
@@ -14,6 +14,7 @@ import {
   createMockGlossaryService,
   createMockFileTranslationService,
   createMockWatchService,
+  createMockConfigService,
 } from '../helpers/mock-factories';
 
 // Mock chalk
@@ -448,6 +449,55 @@ describe('WatchCommand', () => {
         expect(mockGlossaryService.resolveGlossaryId).not.toHaveBeenCalled();
       });
 
+      it('should accept a configured defaults.sourceLang in place of --from', async () => {
+        // The requirement is for a source language, not for the flag. A direct
+        // WatchCommand call has to read the configured default the same way the
+        // CLI path does, or the two disagree about what is runnable.
+        (fs.existsSync as jest.Mock).mockReturnValue(true);
+        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+        mockGlossaryService.resolveGlossaryId.mockResolvedValue('glossary-123');
+        // Thrown so the watcher does not keep the test open, as elsewhere here.
+        mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+
+        const configured = new WatchCommand(
+          mockTranslationService,
+          mockGlossaryService,
+          createMockConfigService({
+            getValue: jest.fn((key: string) =>
+              key === 'defaults.sourceLang' ? 'en' : undefined,
+            ),
+          }),
+        );
+
+        await expect(
+          configured.watch('/some/file.md', { to: 'es', glossary: 'my-glossary' }),
+        ).rejects.toThrow('Test complete');
+
+        expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
+          from: 'en',
+          targets: ['es'],
+        });
+        expect(mockWatchService.watch).toHaveBeenCalledWith(
+          '/some/file.md',
+          expect.objectContaining({ glossaryId: 'glossary-123', sourceLang: 'en' }),
+        );
+      });
+
+      it('should still reject when the configured default is absent too', async () => {
+        (fs.existsSync as jest.Mock).mockReturnValue(true);
+        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+
+        const configured = new WatchCommand(
+          mockTranslationService,
+          mockGlossaryService,
+          createMockConfigService({ getValue: jest.fn(() => undefined) }),
+        );
+
+        await expect(
+          configured.watch('/some/file.md', { to: 'es', glossary: 'my-glossary' }),
+        ).rejects.toThrow('Source language (--from) is required when using a glossary');
+      });
+
       it('should accept --glossary when --from is provided', async () => {
         expect.assertions(1);
         (fs.existsSync as jest.Mock).mockReturnValue(true);

From e66f18ad65e79280a4573873ad175d09b7ef6b07 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 16:41:58 -0400
Subject: [PATCH 062/256] fix(languages,voice): sanitize API-provided strings
 before printing them

languages printed the name, feature keys and feature statuses from
/v3/languages raw, and voice did the same with transcript text and language
labels, while the glossary and style-rule listings hardened in this release
already wrapped API strings in sanitizeForTerminal. Logger's own sanitizer
only redacts secrets; it does not strip ANSI or bidi.

It matters most for voice, whose live display clears a fixed number of
lines: a newline inside a transcript deranges the whole rendering rather
than one line of it. --format json keeps the text verbatim, since
JSON.stringify escapes control characters and that path feeds machines.

Test strings spell the hostile characters as JS unicode escapes rather than
embedding literal control bytes, which do not survive editing reliably.

Closes cli-01on.8
---
 CHANGELOG.md                         |  4 ++
 src/cli/commands/languages.ts        | 26 +++++++------
 src/cli/commands/voice.ts            | 30 ++++++++++++---
 tests/unit/languages-command.test.ts | 57 ++++++++++++++++++++++++++++
 tests/unit/voice-command.test.ts     | 39 +++++++++++++++++++
 5 files changed, 139 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef43e990..7ffeea5d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -115,6 +115,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
 
+- **languages**, **voice**: **Strings the API supplies are sanitized before they reach the terminal.** `deepl languages` printed the name, feature keys and feature statuses from `GET /v3/languages` verbatim, and `voice` did the same with transcript text and language labels, so a hostile or intercepted endpoint could move the cursor, clear the screen, or hide text behind a bidi override. Both now go through the same `sanitizeForTerminal` the glossary and style-rule listings already used, replacing control and zero-width characters with `?`. It matters most for `voice`, whose live display clears a fixed number of lines: a newline inside a transcript threw off the whole rendering, not just its own line. `voice --format json` keeps the text byte-for-byte, since JSON escaping already makes it inert and that is the path machines read.
+
+- **watch**: **A direct `WatchCommand.watch()` call rejected `--glossary` without `--from` even when `defaults.sourceLang` was set.** The config-aware resolution every other command uses lived only in watch's CLI registration layer, while the handler kept the older flag-only guard — so the CLI accepted a command a library caller was refused. The handler now settles the source language the same way, from `defaults.sourceLang` when the flag is absent, and `WatchCommand` takes the config service to do it. The requirement itself is unchanged: with neither a flag nor a default, the command still exits 6 before the watcher starts.
+
 - **sync**: **Per-locale glossary overrides skipped the coverage preflight, and `--dry-run` performed no resolution at all.** `locale_overrides.<locale>.glossary` was resolved without the language pair, so an override that did not cover its own locale reached the API — unlike the top-level glossary and the translation-memory override, which were already checked. Both kinds of override now resolve once at startup against their own locale, rather than being re-resolved for every file, so a bad reference fails before anything is translated instead of after earlier files have been written. `sync --dry-run` resolves and checks the same references a real run does: the command already needs an API key to reach that point, and a glossary or translation memory the config names but the account cannot use for the requested pair is exactly what a preview should report. A dry run still sends nothing to `/v2/translate`.
 
 - **voice**: **`--glossary` was resolved before the rest of the command was checked, and without the language pair.** `voice a.ogg --to bogus --glossary my-terms` spent a glossary-list round trip and only then failed locally on the target language; every local check now runs first. Resolution also passes the requested pair, so a glossary whose dictionaries do not cover it fails locally with `Glossary "my-terms" does not support the requested language pair` instead of at the API — the preflight the other commands already had. The pair is the canonical one voice sends, so `--from EN --to zh-hans` is checked as `en→zh-HANS`. Without `--from` there is no pair to check and the API still judges it.
diff --git a/src/cli/commands/languages.ts b/src/cli/commands/languages.ts
index a283540a..02bd23f2 100644
--- a/src/cli/commands/languages.ts
+++ b/src/cli/commands/languages.ts
@@ -8,6 +8,7 @@ import {
   deriveLanguageEntry,
 } from '../../data/language-registry.js';
 import { isColorEnabled } from '../../utils/formatters.js';
+import { sanitizeForTerminal } from '../../utils/control-chars.js';
 
 export interface LanguageDisplayEntry {
   code: string;
@@ -37,13 +38,13 @@ const FEATURE_LABELS: Record<string, string> = {
 };
 
 function featureLabel(key: string): string {
-  return (
-    FEATURE_LABELS[key] ??
-    key
-      .split('_')
-      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-      .join(' ')
-  );
+  const known = FEATURE_LABELS[key];
+  if (known) return known;
+  // The key is a response field, so it is sanitized before it is displayed.
+  return sanitizeForTerminal(key)
+    .split('_')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
 }
 
 /** Cell text for a language the response carried no feature data for at all. */
@@ -72,7 +73,10 @@ function featureCell(entry: LanguageDisplayEntry, key: string): string {
   if (!hasFeatureData(entry)) return UNKNOWN_CELL;
   const feature = entry.features?.[key];
   if (!feature) return '—';
-  return !feature.status || feature.status === 'stable' ? 'yes' : feature.status;
+  if (!feature.status || feature.status === 'stable') return 'yes';
+  // `status` is an open enum echoed verbatim, so it is sanitized like any other
+  // response field before it reaches the terminal.
+  return sanitizeForTerminal(feature.status);
 }
 
 function sortFeatureKeys(keys: string[]): string[] {
@@ -318,7 +322,7 @@ export class LanguagesCommand {
     coreAndRegional.forEach(entry => {
       const code = entry.code.padEnd(maxCodeLength + 2);
       const formalityMarker = showFormality && entry.supportsFormality ? chalk.green(' [F]') : '';
-      lines.push(`  ${chalk.cyan(code)} ${entry.name}${formalityMarker}${suffix(entry)}`);
+      lines.push(`  ${chalk.cyan(code)} ${sanitizeForTerminal(entry.name)}${formalityMarker}${suffix(entry)}`);
     });
 
     if (extended.length > 0) {
@@ -326,7 +330,7 @@ export class LanguagesCommand {
       lines.push(chalk.gray('  Extended Languages (quality_optimized only, no formality/glossary):'));
       extended.forEach(entry => {
         const code = entry.code.padEnd(maxCodeLength + 2);
-        lines.push(`  ${chalk.gray(code)} ${chalk.gray(entry.name)}${suffix(entry)}`);
+        lines.push(`  ${chalk.gray(code)} ${chalk.gray(sanitizeForTerminal(entry.name))}${suffix(entry)}`);
       });
     }
 
@@ -410,7 +414,7 @@ export class LanguagesCommand {
     });
 
     for (const entry of entries) {
-      const row: string[] = [entry.code, entry.name, entry.category];
+      const row: string[] = [entry.code, sanitizeForTerminal(entry.name), entry.category];
       if (showFormality) {
         row.push(entry.supportsFormality ? 'yes' : '—');
       }
diff --git a/src/cli/commands/voice.ts b/src/cli/commands/voice.ts
index aff12e7f..f27d32e9 100644
--- a/src/cli/commands/voice.ts
+++ b/src/cli/commands/voice.ts
@@ -18,6 +18,7 @@ import type {
 } from '../../types/index.js';
 import { ValidationError } from '../../utils/errors.js';
 import { Logger } from '../../utils/logger.js';
+import { sanitizeForTerminal } from '../../utils/control-chars.js';
 import { VoicePartialResultError } from '../../services/voice-stream-session.js';
 
 const VALID_VOICE_TARGET_LANGS: ReadonlySet<string> = new Set<VoiceTargetLanguage>([
@@ -60,6 +61,16 @@ const VALID_VOICE_CONTENT_TYPES: ReadonlySet<string> = new Set<VoiceSourceMediaC
   'audio/flac','audio/mpeg',
 ]);
 
+/**
+ * Join transcript segments for the live display, with response text sanitized.
+ * The display moves the cursor and clears a fixed number of lines, so a newline
+ * or escape sequence in a segment would derange the whole rendering rather than
+ * just its own line.
+ */
+function segmentText(segments: ReadonlyArray<{ text: string }>): string {
+  return segments.map((segment) => sanitizeForTerminal(segment.text)).join(' ');
+}
+
 /** The canonical language pair a validated `voice` invocation will send. */
 export interface VoiceLanguagePair {
   targetLangs: VoiceTargetLanguage[];
@@ -282,11 +293,11 @@ export class VoiceCommand {
       },
       onSourceTranscript: (update) => {
         const src = state['source']!;
-        const concludedText = update.concluded.map((s) => s.text).join(' ');
+        const concludedText = segmentText(update.concluded);
         if (concludedText) {
           src.concluded += (src.concluded ? ' ' : '') + concludedText;
         }
-        src.tentative = update.tentative.map((s) => s.text).join(' ');
+        src.tentative = segmentText(update.tentative);
         if (src.tentative) {
           src.tentative = ' ' + src.tentative;
         }
@@ -295,11 +306,11 @@ export class VoiceCommand {
       onTargetTranscript: (update) => {
         const tgt = state[update.language.toLowerCase()];
         if (!tgt) return;
-        const concludedText = update.concluded.map((s) => s.text).join(' ');
+        const concludedText = segmentText(update.concluded);
         if (concludedText) {
           tgt.concluded += (tgt.concluded ? ' ' : '') + concludedText;
         }
-        tgt.tentative = update.tentative.map((s) => s.text).join(' ');
+        tgt.tentative = segmentText(update.tentative);
         if (tgt.tentative) {
           tgt.tentative = ' ' + tgt.tentative;
         }
@@ -350,6 +361,13 @@ export class VoiceCommand {
     Logger.error(salvaged);
   }
 
+  /**
+   * Transcripts and language labels are response fields, so the text format
+   * sanitizes them: the live display below moves the cursor and clears a fixed
+   * line count, which an embedded newline or escape sequence would throw off
+   * beyond the line it sits on. `--format json` keeps them verbatim, since
+   * JSON escaping makes them inert and that is the path machines read.
+   */
   private formatResult(result: VoiceSessionResult, format?: string): string {
     if (format === 'json') {
       return formatVoiceJson(result);
@@ -358,11 +376,11 @@ export class VoiceCommand {
     const lines: string[] = [];
 
     if (result.source.text) {
-      lines.push(`[source] ${result.source.text}`);
+      lines.push(`[source] ${sanitizeForTerminal(result.source.text)}`);
     }
 
     for (const target of result.targets) {
-      lines.push(`[${target.lang}] ${target.text}`);
+      lines.push(`[${sanitizeForTerminal(target.lang)}] ${sanitizeForTerminal(target.text)}`);
     }
 
     return lines.join('\n');
diff --git a/tests/unit/languages-command.test.ts b/tests/unit/languages-command.test.ts
index 095b3aba..b1d35521 100644
--- a/tests/unit/languages-command.test.ts
+++ b/tests/unit/languages-command.test.ts
@@ -259,6 +259,63 @@ describe('LanguagesCommand', () => {
     });
   });
 
+  describe('untrusted API strings', () => {
+    // Names, feature keys and feature statuses all come straight from
+    // /v3/languages. A hostile or intercepted endpoint could otherwise move the
+    // cursor, clear the screen, or hide text with a bidi override.
+    const HOSTILE_NAME = 'Ger\u001b[2Kman\u200b';
+
+    it('should strip control characters from a language name in text output', () => {
+      const formatted = languagesCommand.formatDisplayEntries(
+        [{ code: 'de', name: HOSTILE_NAME, category: 'core' as const }],
+        'target',
+      );
+
+      expect(formatted).not.toContain('\u001b');
+      expect(formatted).not.toContain('\u200b');
+      expect(formatted).toContain('Ger?[2Kman?');
+    });
+
+    it('should strip control characters from an extended-tier language name', () => {
+      const formatted = languagesCommand.formatDisplayEntries(
+        [{ code: 'hi', name: HOSTILE_NAME, category: 'extended' as const }],
+        'target',
+      );
+
+      expect(formatted).not.toContain('\u001b');
+    });
+
+    it('should strip control characters from a language name in table output', () => {
+      const formatted = languagesCommand.formatLanguagesTable(
+        [{ language: 'de' as const, name: HOSTILE_NAME }],
+        'target',
+      );
+
+      // cli-table3 colours its own borders, so the assertion is about the cell:
+      // the hostile name must not survive, and its sanitized form must appear.
+      expect(formatted).not.toContain(HOSTILE_NAME);
+      expect(formatted).toContain('Ger?[2Kman?');
+    });
+
+    it('should strip control characters from a feature key and status', () => {
+      const formatted = languagesCommand.formatDisplayEntries(
+        [
+          {
+            code: 'de',
+            name: 'German',
+            category: 'core' as const,
+            features: { 'glo\u001b[2Kssary': { status: 'be\u001b[2Kta' } },
+          },
+          { code: 'fr', name: 'French', category: 'core' as const, features: {} },
+        ],
+        'target',
+        true,
+      );
+
+      expect(formatted).not.toContain('\u001b');
+    });
+  });
+
   describe('formatAllLanguages()', () => {
     it('should format both source and target languages', () => {
       const formatted = languagesCommand.formatAllLanguages(
diff --git a/tests/unit/voice-command.test.ts b/tests/unit/voice-command.test.ts
index fa7d5ba7..d56b6d72 100644
--- a/tests/unit/voice-command.test.ts
+++ b/tests/unit/voice-command.test.ts
@@ -1038,6 +1038,45 @@ describe('VoiceCommand', () => {
 
       expect(result).toBe('[de] Welt\n[fr] Monde');
     });
+
+    it('should strip control characters from transcript text and language labels', async () => {
+      // The live display moves the cursor and clears a fixed number of lines, so
+      // a newline or escape sequence inside transcript text would corrupt the
+      // rendering, not just the line it sits on. --format json keeps the text
+      // verbatim, since JSON escapes it and machines read that path.
+      // Cast because `lang` is a typed union, while on the wire it is whatever
+      // the endpoint sends.
+      const hostileResult = {
+        sessionId: 'session-hostile',
+        source: { lang: 'en', text: 'He\u001b[2Kllo\nthere', segments: [] },
+        targets: [
+          { lang: 'd\u001b[2Ke', text: 'Hal\u001b[2Klo', segments: [] },
+        ],
+      } as unknown as VoiceSessionResult;
+      mockService.translateFile.mockResolvedValue(hostileResult);
+
+      const result = await command.translate('test.mp3', { to: 'de' });
+
+      expect(result).not.toContain('\u001b');
+      expect(result).toContain('[source] He?[2Kllo?there');
+      expect(result).toContain('[d?[2Ke] Hal?[2Klo');
+    });
+
+    it('should keep transcript text verbatim in --format json', async () => {
+      const hostileResult: VoiceSessionResult = {
+        sessionId: 'session-hostile-json',
+        source: { lang: 'en', text: 'He\u001b[2Kllo', segments: [] },
+        targets: [{ lang: 'de', text: 'Hallo', segments: [] }],
+      };
+      mockService.translateFile.mockResolvedValue(hostileResult);
+
+      const result = await command.translate('test.mp3', { to: 'de', format: 'json' });
+
+      // JSON.stringify escapes the control character, so it cannot act on a
+      // terminal, and a consumer still gets the text the API returned.
+      expect(result).toContain('\\u001b[2K');
+      expect(JSON.parse(result).source.text).toBe('He\u001b[2Kllo');
+    });
   });
   describe('language code casing', () => {
     it('should accept a regional target in the casing the CLI prints', async () => {

From e0f185418c20d55f59c5eeb71ccb19a9d00668bf Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 16:55:53 -0400
Subject: [PATCH 063/256] fix(translate): report a directory run's rejection
 class in the exit code

A directory run where the API refused the request itself exited 1, the
generic "nothing succeeded" code, even though the run aborted for a reason
the caller can act on. The batch services already tracked that rejection to
stop sending doomed batches; it is now surfaced on the result, and the
handler reports its exit code -- 6 for a refused target_lang, 4 for an
exhausted quota, 2 for a refused key. A run whose files failed individually
still exits 1, or 12 with some successes.

Text and file modes already exited 6 here, since the rejection reaches the
top-level handler as a typed ValidationError; only the directory path
substituted its own code.

Also resets process.exitCode after each test in the directory handler
suite. The handler writes to the jest process's own exit code, which left
set made the suite exit non-zero with every test passing.
---
 .../directory-translation-handler.ts          | 15 ++++--
 src/services/batch-translation.ts             | 12 ++++-
 .../directory-translation-handler.test.ts     | 47 +++++++++++++++++++
 3 files changed, 70 insertions(+), 4 deletions(-)

diff --git a/src/cli/commands/translate/directory-translation-handler.ts b/src/cli/commands/translate/directory-translation-handler.ts
index 26576c4d..b75734e3 100644
--- a/src/cli/commands/translate/directory-translation-handler.ts
+++ b/src/cli/commands/translate/directory-translation-handler.ts
@@ -2,7 +2,7 @@ import ora from 'ora';
 import { BatchTranslationService } from '../../../services/batch-translation.js';
 import { ValidationError } from '../../../utils/errors.js';
 import { Logger } from '../../../utils/logger.js';
-import { ExitCode } from '../../../utils/exit-codes.js';
+import { ExitCode, exitCodeForError } from '../../../utils/exit-codes.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
 import {
   warnIgnoredOptions,
@@ -112,8 +112,17 @@ export class DirectoryTranslationHandler {
         // translated must not look like success to a script or a CI job, and
         // language validation defers to the API, so a bad --to surfaces here
         // rather than as a local rejection.
-        process.exitCode =
-          stats.successful === 0 ? ExitCode.GeneralError : ExitCode.PartialFailure;
+        //
+        // When one rejection stopped the whole run, its own code is reported
+        // instead of the generic failure — a refused `target_lang` is invalid
+        // input (6) and an exhausted quota is a quota error (4), which a script
+        // can act on differently from a file that happened to fail.
+        if (result.requestRejected !== undefined) {
+          process.exitCode = exitCodeForError(result.requestRejected);
+        } else {
+          process.exitCode =
+            stats.successful === 0 ? ExitCode.GeneralError : ExitCode.PartialFailure;
+        }
       }
 
       if (stats.skipped > 0) {
diff --git a/src/services/batch-translation.ts b/src/services/batch-translation.ts
index 554f15a3..ae4ac6ab 100644
--- a/src/services/batch-translation.ts
+++ b/src/services/batch-translation.ts
@@ -38,6 +38,13 @@ interface BatchResult {
   successful: Array<{ file: string; outputPath: string }>;
   failed: Array<{ file: string; error: string }>;
   skipped: Array<{ file: string; reason: string }>;
+  /**
+   * The rejection that stopped the run, when one described the request rather
+   * than a single file. Surfaced so the caller can report the rejection's own
+   * exit code instead of a generic failure: a refused `target_lang` is user
+   * input, not an unclassified error.
+   */
+  requestRejected?: unknown;
 }
 
 interface BatchStatistics {
@@ -145,6 +152,7 @@ export class BatchTranslationService {
       result.successful.push(...batchResult.successful);
       result.failed.push(...batchResult.failed);
       result.skipped.push(...batchResult.skipped);
+      result.requestRejected ??= batchResult.requestRejected;
       completed +=
         batchResult.successful.length + batchResult.failed.length + batchResult.skipped.length;
     }
@@ -205,6 +213,7 @@ export class BatchTranslationService {
       );
 
       await Promise.all(tasks);
+      result.requestRejected ??= requestRejected;
     }
 
     return result;
@@ -227,6 +236,7 @@ export class BatchTranslationService {
     successful: Array<{ file: string; outputPath: string }>;
     failed: Array<{ file: string; error: string }>;
     skipped: Array<{ file: string; reason: string }>;
+    requestRejected?: unknown;
   }> {
     const successful: Array<{ file: string; outputPath: string }> = [];
     const failed: Array<{ file: string; error: string }> = [];
@@ -369,7 +379,7 @@ export class BatchTranslationService {
     }
     await flushBatch();
 
-    return { successful, failed, skipped };
+    return { successful, failed, skipped, requestRejected };
   }
 
   /**
diff --git a/tests/unit/directory-translation-handler.test.ts b/tests/unit/directory-translation-handler.test.ts
index f708669b..e91c362d 100644
--- a/tests/unit/directory-translation-handler.test.ts
+++ b/tests/unit/directory-translation-handler.test.ts
@@ -266,6 +266,13 @@ describe('DirectoryTranslationHandler', () => {
     getStatistics: jest.Mock;
   };
 
+  // The handler reports a failed run through process.exitCode, which is this
+  // process's own: left set, it makes jest exit non-zero even when every test
+  // passed, so a real failure elsewhere would be indistinguishable.
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
   beforeEach(() => {
     // Re-apply mock implementations cleared by resetMocks: true in jest.config
     const translateUtilsMock = jest.requireMock(
@@ -439,6 +446,46 @@ describe('DirectoryTranslationHandler', () => {
       );
     });
 
+    it('should classify the exit code from a request-level rejection', async () => {
+      // A rejected target_lang aborts the whole run, so it is user input rather
+      // than an unclassified failure: exit 6, not the generic 1 that a run where
+      // every file failed for its own reason gets.
+      mockBatchService.translateDirectory.mockResolvedValue({
+        successful: [],
+        failed: [{ file: 'a.txt', error: "Value for 'target_lang' not supported." }],
+        skipped: [],
+        requestRejected: new ValidationError("Value for 'target_lang' not supported."),
+      });
+      mockBatchService.getStatistics.mockReturnValue({
+        total: 1,
+        successful: 0,
+        failed: 1,
+        skipped: 0,
+      });
+
+      await handler.translateDirectory('/some/dir', baseOptions);
+
+      expect(process.exitCode).toBe(6);
+    });
+
+    it('should still exit 1 when every file failed for its own reason', async () => {
+      mockBatchService.translateDirectory.mockResolvedValue({
+        successful: [],
+        failed: [{ file: 'a.txt', error: 'Network error' }],
+        skipped: [],
+      });
+      mockBatchService.getStatistics.mockReturnValue({
+        total: 1,
+        successful: 0,
+        failed: 1,
+        skipped: 0,
+      });
+
+      await handler.translateDirectory('/some/dir', baseOptions);
+
+      expect(process.exitCode).toBe(1);
+    });
+
     it('should validate the flags this mode passes on, and not --glossary', async () => {
       // Directory mode announces --glossary as ignored and resolves none, so the
       // extended-tier glossary arm must not fail a run that would have worked.

From dbebba4a86f76437cc2ac4788fd48165833b3e47 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 16:56:03 -0400
Subject: [PATCH 064/256] fix(glossary): relax the coverage check on the
 requested side only

The preflight compared both sides on their base language, so a pt-br
dictionary satisfied a request for pt-pt -- a different language pair. The
relaxation exists because dictionaries name base languages while --to
accepts regional variants, which needs it in one direction: a dictionary
language now matches the requested one exactly, or matches the base it
reduces to.

de->en still covers --to en-us, and a dictionary naming pt-br still matches
--to pt-br. Not reachable through the current API, whose glossary language
set is entirely base codes, but GlossaryClient types targets as Language,
which includes the variants.
---
 src/services/glossary.ts            | 13 ++++++++---
 tests/unit/glossary-service.test.ts | 34 +++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/src/services/glossary.ts b/src/services/glossary.ts
index d1831626..5f98940d 100644
--- a/src/services/glossary.ts
+++ b/src/services/glossary.ts
@@ -212,11 +212,18 @@ export class GlossaryService {
     // judgement to the API rather than rejecting on no evidence.
     if (expected && match.dictionaries.length > 0) {
       const from = expected.from.toLowerCase();
+      // Relaxed on the requested side only: a dictionary language matches the
+      // requested one exactly, or matches the base it reduces to. Dictionaries
+      // name base languages while `--to` accepts regional variants, so `de→en`
+      // has to cover `de→en-us` -- but reducing the dictionary's side too would
+      // let a `pt-br` dictionary satisfy `pt-pt`, a different pair.
+      const matches = (dictionaryLang: string, requested: string): boolean => {
+        const dictionary = dictionaryLang.toLowerCase();
+        return dictionary === requested.toLowerCase() || dictionary === baseLanguage(requested);
+      };
       const covered = (target: string): boolean =>
         match.dictionaries.some(
-          d =>
-            baseLanguage(d.source_lang) === baseLanguage(from) &&
-            baseLanguage(d.target_lang) === baseLanguage(target),
+          d => matches(d.source_lang, from) && matches(d.target_lang, target),
         );
       const missing = expected.targets.filter(target => !covered(target));
       if (missing.length > 0) {
diff --git a/tests/unit/glossary-service.test.ts b/tests/unit/glossary-service.test.ts
index 37783236..b5256b1c 100644
--- a/tests/unit/glossary-service.test.ts
+++ b/tests/unit/glossary-service.test.ts
@@ -452,6 +452,40 @@ describe('GlossaryService', () => {
         ).rejects.toThrow('does not support the requested language pair');
       });
 
+      it('should not let one regional dictionary cover a different region', async () => {
+        // The relaxation exists because dictionaries name base languages while
+        // --to accepts variants, so it is needed in one direction only. Comparing
+        // both sides on their base language would make a pt-br dictionary satisfy
+        // pt-pt, which is a different language pair.
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'en', target_lang: 'pt-br' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['pt-pt'] }),
+        ).rejects.toThrow('does not support the requested language pair');
+      });
+
+      it('should not let a regional dictionary source cover a different region', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'pt-br', target_lang: 'de' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'pt-pt', targets: ['de'] }),
+        ).rejects.toThrow('does not support the requested language pair');
+      });
+
+      it('should still match a regional dictionary asked for exactly', async () => {
+        mockDeepLClient.listGlossaries.mockResolvedValue(
+          listing([{ source_lang: 'en', target_lang: 'pt-br' }]) as never,
+        );
+
+        await expect(
+          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['pt-br'] }),
+        ).resolves.toBe('found-glossary-id');
+      });
+
       it('should compare languages case-insensitively', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
           listing([{ source_lang: 'EN', target_lang: 'ES' }]) as never,

From 149cccfd3527ce56f993781203dbbe085d4c2b7c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 16:56:16 -0400
Subject: [PATCH 065/256] fix(languages): stop inferring a tier, and a role,
 from a silent response

Three related conflations of "unknown" with "no", all in how a
/v3/languages entry is read:

deriveLanguageEntry filed a language with no features matrix as extended,
inferring absent glossary support from silence. The extended tier is what
refuses formality and glossary before a request is sent, so that claims
knowledge the response did not give -- the same fault already fixed for the
--features table. Such a language is now tiered by source usability and the
API keeps the judgement. An empty matrix is still evidence, and still
extended. The bundled snapshot is unchanged, since every language the API
lists today carries a matrix.

The role flags had two conventions: the registry reads
`usable_as_source !== false` while the translation and glossary clients
filtered on truthiness, so an entry with the flag absent was dropped from
`deepl languages` but recorded as core by the generator. Both clients now
read it the registry's way.

LanguageEntry's fields are readonly, because the accessors hand out the
registry's own objects: mutating one changed the registry for the rest of
the process, which the generated `as const` snapshot forbids but the widened
element type allowed.
---
 src/api/glossary-client.ts            |  6 ++++--
 src/api/translation-client.ts         |  7 ++++++-
 src/data/language-registry.ts         | 22 +++++++++++++++++-----
 tests/unit/glossary-client.test.ts    | 20 ++++++++++++++++++++
 tests/unit/language-registry.test.ts  | 24 ++++++++++++++++++++++--
 tests/unit/translation-client.test.ts | 23 +++++++++++++++++++++++
 6 files changed, 92 insertions(+), 10 deletions(-)

diff --git a/src/api/glossary-client.ts b/src/api/glossary-client.ts
index 2203e6ca..53c7d701 100644
--- a/src/api/glossary-client.ts
+++ b/src/api/glossary-client.ts
@@ -27,8 +27,10 @@ export class GlossaryClient extends HttpClient {
       { resource: 'glossary' }
     );
 
-    const sources = response.filter((lang) => lang.usable_as_source);
-    const targets = response.filter((lang) => lang.usable_as_target);
+    // `!== false`, not truthiness: an absent flag is not a denial, and the
+    // language registry reads it the same way.
+    const sources = response.filter((lang) => lang.usable_as_source !== false);
+    const targets = response.filter((lang) => lang.usable_as_target !== false);
 
     const pairs: GlossaryLanguagePair[] = [];
     for (const source of sources) {
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index a2e4a4f9..f229009e 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -322,7 +322,12 @@ export class TranslationClient extends HttpClient {
       const response = await this.fetchTranslateLanguages();
 
       return response
-        .filter((lang) => (type === 'source' ? lang.usable_as_source : lang.usable_as_target))
+        // `!== false`, not truthiness: an absent flag is not a denial, and the
+        // language registry reads it the same way, so a truthy filter here would
+        // drop a language the generator records as usable.
+        .filter((lang) =>
+          type === 'source' ? lang.usable_as_source !== false : lang.usable_as_target !== false,
+        )
         .map((lang) => {
           const code = this.normalizeLanguage(lang.lang);
           return {
diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index c1f7b081..4fa85fd1 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -32,16 +32,21 @@ export type LanguageCategory = 'core' | 'regional' | 'extended';
  *   (not as a source). Applies to regional variants like 'en-gb' and 'pt-br'.
  */
 export interface LanguageEntry {
-  code: string;
-  name: string;
-  category: LanguageCategory;
-  targetOnly?: boolean;
+  readonly code: string;
+  readonly name: string;
+  readonly category: LanguageCategory;
+  readonly targetOnly?: boolean;
 }
 
 /**
  * The snapshot as plain entries. It is generated `as const` so the `Language`
  * union can derive from its codes; the lookups below want the interface rather
  * than one literal type per language.
+ *
+ * `LanguageEntry`'s fields are `readonly` because the accessors below hand out
+ * these very objects: a caller mutating one would change the registry for the
+ * whole process, which the generated `as const` tuple forbids but a widened
+ * element type would have silently permitted.
  */
 const ENTRIES: readonly LanguageEntry[] = GENERATED_ENTRIES;
 
@@ -69,9 +74,16 @@ export interface DerivableLanguage {
 export function deriveLanguageEntry(language: DerivableLanguage): LanguageEntry {
   const code = language.lang.toLowerCase();
   const usableAsSource = language.usable_as_source !== false;
+
+  // An empty matrix is evidence — it says the language supports none of them,
+  // glossary included — while a missing one says nothing. Since the extended
+  // tier is what refuses formality and glossary before a request is sent,
+  // silence must not put a language there; tiering it by source usability
+  // leaves the judgement to the API instead.
+  const described = language.features !== undefined;
   const supportsGlossary = language.features?.['glossary'] !== undefined;
 
-  const category: LanguageCategory = !supportsGlossary
+  const category: LanguageCategory = described && !supportsGlossary
     ? 'extended'
     : usableAsSource
       ? 'core'
diff --git a/tests/unit/glossary-client.test.ts b/tests/unit/glossary-client.test.ts
index a036daac..b891b9a5 100644
--- a/tests/unit/glossary-client.test.ts
+++ b/tests/unit/glossary-client.test.ts
@@ -67,6 +67,26 @@ describe('GlossaryClient', () => {
       );
     });
 
+    it('should treat an absent role flag as usable, matching the registry', async () => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: [
+          { lang: 'en', name: 'English' },
+          { lang: 'de', name: 'German' },
+        ],
+        status: 200,
+        headers: {},
+      });
+
+      const pairs = await client.getGlossaryLanguages();
+
+      expect(pairs).toEqual(
+        expect.arrayContaining([
+          { sourceLang: 'en', targetLang: 'de' },
+          { sourceLang: 'de', targetLang: 'en' },
+        ]),
+      );
+    });
+
     it('should exclude identity pairs', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index eec39ee4..08c14295 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -344,12 +344,32 @@ describe('Language Registry', () => {
       ).toEqual({ code: 'hi', name: 'Hindi', category: 'extended' });
     });
 
-    it('should treat a missing features object as extended', () => {
+    it('should classify an empty features matrix as extended, which is evidence', () => {
+      // An empty matrix says the language supports none of them, glossary
+      // included. A missing one says nothing -- see below.
       expect(
-        deriveLanguageEntry({ lang: 'xx', name: 'Test', usable_as_source: true }).category,
+        deriveLanguageEntry({
+          lang: 'hi',
+          name: 'Hindi',
+          usable_as_source: true,
+          features: {},
+        }).category,
       ).toBe('extended');
     });
 
+    it('should not file a language with no features matrix as extended', () => {
+      // Silence about a language is not evidence that it lacks glossary support,
+      // and the extended tier is what suppresses formality and glossary locally.
+      // Tiering it by source usability instead leaves the judgement to the API,
+      // which is the same choice the --features table makes.
+      expect(
+        deriveLanguageEntry({ lang: 'xx', name: 'Test', usable_as_source: true }).category,
+      ).toBe('core');
+      expect(
+        deriveLanguageEntry({ lang: 'xx', name: 'Test', usable_as_source: false }).category,
+      ).toBe('regional');
+    });
+
     it('should lowercase the code', () => {
       expect(deriveLanguageEntry({ lang: 'ZH-Hans', name: 'Chinese' }).code).toBe('zh-hans');
     });
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index 9fad3ab8..a0cea26f 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -399,6 +399,29 @@ describe('TranslationClient', () => {
   });
 
   describe('getSupportedLanguages()', () => {
+    it('should treat an absent role flag as usable, matching the registry', async () => {
+      // The registry reads `usable_as_source !== false`, so an entry with the
+      // flag absent is recorded as core there. Dropping it here instead would
+      // make `deepl languages` omit a language the generator files as usable.
+      mockAxiosInstance.request.mockResolvedValue({
+        data: [{ lang: 'en', name: 'English' }],
+        status: 200,
+        headers: {},
+      });
+
+      await expect(client.getSupportedLanguages('source')).resolves.toHaveLength(1);
+    });
+
+    it('should still drop a language whose role flag is explicitly false', async () => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: [{ lang: 'en-gb', name: 'English (British)', usable_as_source: false }],
+        status: 200,
+        headers: {},
+      });
+
+      await expect(client.getSupportedLanguages('source')).resolves.toEqual([]);
+    });
+
     it('should return source languages', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [

From 97e567c764695b56114a21864b28c3ae04f071d1 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 16:56:25 -0400
Subject: [PATCH 066/256] fix(scripts): report a thrown fetch from the language
 generator as an error

The generator had no top-level catch, so a rejected fetch or an error body
that does not parse surfaced as an unhandled rejection with a stack trace
rather than the script's own "error:" line and exit 1. Every other failure
in the script already reported itself that way.

Covered by a test that preloads a throwing fetch, which fails without the
catch.
---
 CHANGELOG.md                                  | 12 ++++++++++
 scripts/generate-language-registry.mjs        |  9 +++++++-
 tests/fixtures/throwing-fetch.mjs             |  7 ++++++
 tests/unit/generate-language-registry.test.ts | 23 +++++++++++++++++++
 4 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 tests/fixtures/throwing-fetch.mjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7ffeea5d..13d1d5e2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -115,6 +115,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
 
+- **translate**: **A directory run stopped by one request-level rejection now reports that rejection's exit code** instead of the generic `1` for "nothing succeeded". A refused `target_lang` is invalid input and exits 6, an exhausted quota exits 4, a refused key exits 2 — all cases where every file draws the same answer and the run aborts. A run where files failed for their own reasons still exits 1 with no successes, or 12 with some. Text and file modes already exited 6 for this.
+
+- **glossary**: **The language-pair preflight no longer treats two regional variants of one language as interchangeable.** Both sides were compared on their base language, so a `pt-br` dictionary satisfied a request for `pt-pt`. The relaxation is needed in one direction only — dictionaries name base languages while `--to` accepts variants — so a dictionary language now matches the requested one exactly or matches the base it reduces to. `de→en` still covers `--to en-us`, and a dictionary naming `pt-br` still matches `--to pt-br`. Not reachable through the current API, whose glossary language set is entirely base codes.
+
+- **languages**: **A language `GET /v3/languages` describes with no feature matrix is no longer filed as extended.** The tier was derived from the absence of glossary support, and an absent matrix is silence rather than a denial — the same unknown-versus-none conflation already fixed for the `--features` table. Since the extended tier is what refuses formality and glossary before a request is sent, such a language is now tiered by source usability and the API keeps the judgement. An **empty** matrix is still evidence and still means extended. The bundled snapshot is unchanged, since every language the API currently lists carries a matrix.
+
+- **languages**: An absent `usable_as_source` / `usable_as_target` flag is read as "usable" in the language and glossary-pair listings, matching how the language registry has always read it. The two disagreed, so a language whose flag was absent was dropped from `deepl languages` while the snapshot generator recorded it as core.
+
+- **types**: `LanguageEntry`'s fields are `readonly`. The accessors hand out the registry's own objects, so `getTargetLanguages()[0].code = 'x'` changed the registry for the rest of the process — something the generated `as const` snapshot forbids but the widened element type permitted.
+
+- **scripts**: `npm run generate:languages` reports a thrown fetch or an unparseable error body as its own `error:` line and exit 1, rather than as an unhandled rejection with a stack trace.
+
 - **languages**, **voice**: **Strings the API supplies are sanitized before they reach the terminal.** `deepl languages` printed the name, feature keys and feature statuses from `GET /v3/languages` verbatim, and `voice` did the same with transcript text and language labels, so a hostile or intercepted endpoint could move the cursor, clear the screen, or hide text behind a bidi override. Both now go through the same `sanitizeForTerminal` the glossary and style-rule listings already used, replacing control and zero-width characters with `?`. It matters most for `voice`, whose live display clears a fixed number of lines: a newline inside a transcript threw off the whole rendering, not just its own line. `voice --format json` keeps the text byte-for-byte, since JSON escaping already makes it inert and that is the path machines read.
 
 - **watch**: **A direct `WatchCommand.watch()` call rejected `--glossary` without `--from` even when `defaults.sourceLang` was set.** The config-aware resolution every other command uses lived only in watch's CLI registration layer, while the handler kept the older flag-only guard — so the CLI accepted a command a library caller was refused. The handler now settles the source language the same way, from `defaults.sourceLang` when the flag is absent, and `WatchCommand` takes the config service to do it. The requirement itself is unchanged: with neither a flag nor a default, the command still exits 6 before the watcher starts.
diff --git a/scripts/generate-language-registry.mjs b/scripts/generate-language-registry.mjs
index 15596bac..c1f26b13 100644
--- a/scripts/generate-language-registry.mjs
+++ b/scripts/generate-language-registry.mjs
@@ -274,5 +274,12 @@ const invokedDirectly =
   })();
 
 if (invokedDirectly) {
-  await main();
+  // Caught so a thrown fetch, or an HTML error body that does not parse, reports
+  // itself the way every other failure in this script does rather than as an
+  // unhandled rejection with a stack trace.
+  try {
+    await main();
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
 }
diff --git a/tests/fixtures/throwing-fetch.mjs b/tests/fixtures/throwing-fetch.mjs
new file mode 100644
index 00000000..432e1fad
--- /dev/null
+++ b/tests/fixtures/throwing-fetch.mjs
@@ -0,0 +1,7 @@
+/**
+ * Preload that makes every fetch throw, so a script's transport-failure handling
+ * can be exercised without a network. Used via `node --import`.
+ */
+globalThis.fetch = () => {
+  throw new Error('simulated transport failure');
+};
diff --git a/tests/unit/generate-language-registry.test.ts b/tests/unit/generate-language-registry.test.ts
index 923f009e..b09fcdf1 100644
--- a/tests/unit/generate-language-registry.test.ts
+++ b/tests/unit/generate-language-registry.test.ts
@@ -10,6 +10,7 @@
 
 import { spawnSync } from 'child_process';
 import * as path from 'path';
+import { pathToFileURL } from 'url';
 
 const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'generate-language-registry.mjs');
 
@@ -111,4 +112,26 @@ describe('generate-language-registry', () => {
         .toContain("'de\\' ], evil = ['");
     });
   });
+
+  describe('failure reporting', () => {
+    it('should report a thrown fetch as its own error line, not an unhandled rejection', () => {
+      // A DNS failure or a socket reset throws rather than returning a response,
+      // and the script has to name it the way it names every other failure.
+      const preload = path.join(
+        __dirname,
+        '..',
+        'fixtures',
+        'throwing-fetch.mjs',
+      );
+      const result = spawnSync('node', ['--import', pathToFileURL(preload).href, SCRIPT], {
+        encoding: 'utf-8',
+        env: { ...process.env, DEEPL_API_KEY: 'test-key-for-generator:fx' },
+      });
+
+      expect(result.status).toBe(1);
+      expect(result.stderr).toContain('error: simulated transport failure');
+      expect(result.stderr).not.toContain('UnhandledPromiseRejection');
+      expect(result.stderr).not.toContain('at async main');
+    });
+  });
 });

From 24da5ec1fc6ac0358947a5554e52fdbb5900e61d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 17:34:11 -0400
Subject: [PATCH 067/256] docs(glossary): record the verified multipart
 glossary_ids semantics

The multi-glossary work could not establish how the multipart
POST /v2/document parses glossary_ids, because that endpoint answers any
unresolvable glossary with `glossary_ids is not valid` whatever the
encoding, so probing with fake UUIDs cannot separate a parse failure from
a non-existent glossary. Two real glossaries settle it.

A comma-joined glossary_ids applies the terms from every glossary in the
list. The same two IDs sent as repeated multipart fields apply only the
first, and the API reports no error for the ones it drops, so the
comma-joining encodeGlossaryIdsForMultipart() performs is required rather
than merely sufficient and its absence would fail silently.

Whitespace after the commas turns out to be tolerated, contrary to what
the comment claimed; the encoder emits none either way, so this is a
comment correction only.
---
 CHANGELOG.md                 | 2 +-
 src/utils/glossary-params.ts | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 13d1d5e2..d6cea16e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API). It was previously accepted and then silently discarded with a "document mode does not support --glossary" warning, even though `POST /v2/document` supports glossaries. Repeating the flag works here too, with the same last-one-wins precedence. `--from` is required, because the API rejects a document glossary without a source language; `--translation-memory` remains unsupported for documents. Note that glossary matching is context-dependent for documents exactly as it is for text — a term applied in one sentence may be left alone in another.
 
-- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API: `POST /v2/translate` accepts `glossary_ids` as repeated form fields and resolves them in order, rejects a sixth with `A maximum of 5 glossaries can be specified per request.`, and rejects `glossary_id` and `glossary_ids` together with `Specify either glossary_id or glossary_ids, not both.` -- which is why the CLI collapses a single glossary to `glossary_id` rather than sending both. The multipart `POST /v2/document` takes one comma-joined value, since multipart does not parse repeated fields as a list; that endpoint answers any unresolvable glossary with `glossary_ids is not valid` regardless of encoding, so it was confirmed only to the extent that it recognises the parameter, and the list semantics there rest on the API documentation rather than on a live round trip.
+- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API: `POST /v2/translate` accepts `glossary_ids` as repeated form fields and resolves them in order, rejects a sixth with `A maximum of 5 glossaries can be specified per request.`, and rejects `glossary_id` and `glossary_ids` together with `Specify either glossary_id or glossary_ids, not both.` -- which is why the CLI collapses a single glossary to `glossary_id` rather than sending both. The multipart `POST /v2/document` takes one comma-joined value, since multipart does not parse repeated fields as a list. Both halves of that are now confirmed against the live API with two real single-entry glossaries: a comma-joined `glossary_ids` applies the terms from both, while sending the same two IDs as repeated multipart fields applies only the first and reports no error, so the comma-joining is required rather than merely sufficient.
 
 - **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`, which the CLI previously discarded. Support no longer has to be discovered by making a request and reading the error. Which features get a column is derived from the response rather than a fixed list: a feature appears when its support differs across the languages listed, and one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row (`All languages with reported features also support: ...` when the listing also carries languages the response did not describe, since the note must not speak for those). A language the response omitted reads as `no feature data` rather than as supporting nothing, and does not count towards whether a feature varies. That makes the columns differ between listings — `auto detection` appears under `--target`, where target-only variants lack it, but is uniform under `--source` — and means a newly reported feature shows up without a code change. Support is signalled by the API reporting a feature at all; `status` describes maturity, so anything short of generally available renders verbatim (`glossary (beta)`) rather than collapsing to `yes`. Works with `--format table` (one column per feature) and `--format json` (the raw matrix including each status, present only when `--features` is passed, so existing JSON consumers are unaffected). The `supportsFormality` field is unchanged for every language `GET /v3/languages` describes, which is all of them today; it now comes from the matrix rather than v2's `supports_formality` boolean, and is **omitted rather than reported as `false`** for a target the response says nothing about, since silence is not evidence that formality is absent. `--features` supersedes the `[F]` shorthand and replaces it when given. It needs an API key; without one the command warns and falls back to the registry, which carries no feature data. Note that the matrix is finer-grained than the core/regional/extended tiers: some extended languages support style rules and translation memory even though they support neither formality nor glossary.
 
diff --git a/src/utils/glossary-params.ts b/src/utils/glossary-params.ts
index c03f0f41..9622cedd 100644
--- a/src/utils/glossary-params.ts
+++ b/src/utils/glossary-params.ts
@@ -99,8 +99,8 @@ export function resolveGlossaryWireParams(
  * Encode `glossary_ids` for multipart requests. Unlike form-urlencoded bodies,
  * multipart uploads do not parse repeated `glossary_ids` fields as a list — the
  * API keeps only the first and silently applies that one glossary — so the IDs
- * travel as a single comma-joined value. Whitespace around the commas makes the
- * API ignore the parameter outright.
+ * travel as a single comma-joined value, which the API applies in full. Spaces
+ * after the commas are tolerated, but nothing depends on that, so none are sent.
  */
 export function encodeGlossaryIdsForMultipart(ids: string[]): string {
   return ids.join(',');

From c541e1a212d542ad563945ebe69e086ffbfc3a47 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 17:35:02 -0400
Subject: [PATCH 068/256] fix(glossary): stop documenting flag order as
 resolving a conflicting term
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

--glossary was documented as last-one-wins: with a term defined in
several glossaries, the last flag on the command line was said to decide
the translation. Two real glossaries defining the same source term show
that it does not. The winner did not track list order — the same glossary
won under both orderings in five of six trials, and the first-listed one
won in the sixth. Differing verb choices between those two runs confirm
they were separate translations rather than cache hits, so conflict
resolution belongs to the API and is context-dependent, exactly as
glossary matching itself already is.

Nothing about the request changes. The list is still sent in the caller's
order and never sorted, which stays correct for the reason the cache
always needed it: a reordered list is a different request, so it gets its
own cache entry. Only the rationale was wrong, and four tests carried
that rationale in their names.

The --help text now says the API picks the winner regardless of flag
order, so users have no reason to reorder flags expecting an override.
---
 CHANGELOG.md                             | 4 ++--
 README.md                                | 3 ++-
 docs/API.md                              | 3 ++-
 src/cli/commands/register-translate.ts   | 2 +-
 src/services/translation.ts              | 5 +++--
 src/types/api.ts                         | 9 ++++++---
 src/utils/glossary-params.ts             | 6 ++++--
 tests/e2e/cli-multi-glossary.e2e.test.ts | 9 +++++++--
 tests/unit/document-client.test.ts       | 4 ++--
 tests/unit/glossary-params.test.ts       | 2 +-
 tests/unit/translation-client.test.ts    | 2 +-
 tests/unit/translation-service.test.ts   | 2 +-
 12 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d6cea16e..c92f801b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,9 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API). It was previously accepted and then silently discarded with a "document mode does not support --glossary" warning, even though `POST /v2/document` supports glossaries. Repeating the flag works here too, with the same last-one-wins precedence. `--from` is required, because the API rejects a document glossary without a source language; `--translation-memory` remains unsupported for documents. Note that glossary matching is context-dependent for documents exactly as it is for text — a term applied in one sentence may be left alone in another.
+- **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API). It was previously accepted and then silently discarded with a "document mode does not support --glossary" warning, even though `POST /v2/document` supports glossaries. Repeating the flag works here too, with the same merge behaviour and the same API-decided conflict resolution. `--from` is required, because the API rejects a document glossary without a source language; `--translation-memory` remains unsupported for documents. Note that glossary matching is context-dependent for documents exactly as it is for text — a term applied in one sentence may be left alone in another.
 
-- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply; when several glossaries define the same source term the **last** `--glossary` on the command line wins, so the order is significant and is never sorted — reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API: `POST /v2/translate` accepts `glossary_ids` as repeated form fields and resolves them in order, rejects a sixth with `A maximum of 5 glossaries can be specified per request.`, and rejects `glossary_id` and `glossary_ids` together with `Specify either glossary_id or glossary_ids, not both.` -- which is why the CLI collapses a single glossary to `glossary_id` rather than sending both. The multipart `POST /v2/document` takes one comma-joined value, since multipart does not parse repeated fields as a list. Both halves of that are now confirmed against the live API with two real single-entry glossaries: a comma-joined `glossary_ids` applies the terms from both, while sending the same two IDs as repeated multipart fields applies only the first and reports no error, so the comma-joining is required rather than merely sufficient.
+- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply. When several glossaries define the same source term, **which mapping wins is the API's choice and does not follow flag order** — verified live with two glossaries defining the same term, where the same one won in both orderings in five of six trials and the first-listed one won in the sixth, so position is not a way to override a term. The order is still sent as given and never sorted, because it is part of the cache key: reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API: `POST /v2/translate` accepts `glossary_ids` as repeated form fields and resolves them in order, rejects a sixth with `A maximum of 5 glossaries can be specified per request.`, and rejects `glossary_id` and `glossary_ids` together with `Specify either glossary_id or glossary_ids, not both.` -- which is why the CLI collapses a single glossary to `glossary_id` rather than sending both. The multipart `POST /v2/document` takes one comma-joined value, since multipart does not parse repeated fields as a list. Both halves of that are now confirmed against the live API with two real single-entry glossaries: a comma-joined `glossary_ids` applies the terms from both, while sending the same two IDs as repeated multipart fields applies only the first and reports no error, so the comma-joining is required rather than merely sufficient.
 
 - **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`, which the CLI previously discarded. Support no longer has to be discovered by making a request and reading the error. Which features get a column is derived from the response rather than a fixed list: a feature appears when its support differs across the languages listed, and one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row (`All languages with reported features also support: ...` when the listing also carries languages the response did not describe, since the note must not speak for those). A language the response omitted reads as `no feature data` rather than as supporting nothing, and does not count towards whether a feature varies. That makes the columns differ between listings — `auto detection` appears under `--target`, where target-only variants lack it, but is uniform under `--source` — and means a newly reported feature shows up without a code change. Support is signalled by the API reporting a feature at all; `status` describes maturity, so anything short of generally available renders verbatim (`glossary (beta)`) rather than collapsing to `yes`. Works with `--format table` (one column per feature) and `--format json` (the raw matrix including each status, present only when `--features` is passed, so existing JSON consumers are unaffected). The `supportsFormality` field is unchanged for every language `GET /v3/languages` describes, which is all of them today; it now comes from the matrix rather than v2's `supports_formality` boolean, and is **omitted rather than reported as `false`** for a target the response says nothing about, since silence is not evidence that formality is absent. `--features` supersedes the `[F]` shorthand and replaces it when given. It needs an API key; without one the command warns and falls back to the registry, which carries no feature data. Note that the matrix is finer-grained than the core/regional/extended tiers: some extended languages support style rules and translation memory even though they support neither formality nor glossary.
 
diff --git a/README.md b/README.md
index fdd7f4a1..edadd994 100644
--- a/README.md
+++ b/README.md
@@ -378,7 +378,8 @@ deepl translate document.pdf --from en --to es --output document.es.pdf
 # Apply a glossary (needs a source language: --from, or defaults.sourceLang)
 deepl translate report.docx --from en --to de --glossary tech-terms --output report.de.docx
 
-# Repeat --glossary for up to 5; the last one wins a conflicting term
+# Repeat --glossary for up to 5; entries merge, and a term defined in
+# several is resolved by the API, not by flag order
 deepl translate report.docx --from en --to de --output report.de.docx \
   --glossary base-terms --glossary project-overrides
 
diff --git a/docs/API.md b/docs/API.md
index 689a2e41..566111a9 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -414,7 +414,8 @@ deepl translate report.docx --to fr --output report.fr.docx --enable-minificatio
 # Apply a glossary (--from is required for document glossaries)
 deepl translate report.docx --from en --to de --output report.de.docx --glossary tech-terms
 
-# Repeat --glossary for up to 5; the last one wins a conflicting term
+# Repeat --glossary for up to 5; entries merge, and a term defined in
+# several is resolved by the API, not by flag order
 deepl translate report.docx --from en --to de --output report.de.docx \
   --glossary base-terms --glossary project-overrides
 ```
diff --git a/src/cli/commands/register-translate.ts b/src/cli/commands/register-translate.ts
index 425e6969..3c9eb8e8 100644
--- a/src/cli/commands/register-translate.ts
+++ b/src/cli/commands/register-translate.ts
@@ -31,7 +31,7 @@ export function registerTranslate(
     .option('--context <text>', 'Additional context to improve translation quality')
     .option(
       '--glossary <name-or-id>',
-      `Use glossary by name or ID (requires --from; repeatable, max ${MAX_GLOSSARIES_PER_REQUEST}; when several define the same term, the last one wins). Applies to text, files and documents.`,
+      `Use glossary by name or ID (requires --from; repeatable, max ${MAX_GLOSSARIES_PER_REQUEST}; entries are merged, and for a term defined in several the API picks the winner regardless of flag order). Applies to text, files and documents.`,
       (val: string, prev: string[] | undefined) => (prev ?? []).concat([val]),
     )
     .option(
diff --git a/src/services/translation.ts b/src/services/translation.ts
index e8edbd87..cde7e2a9 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -397,8 +397,9 @@ export class TranslationService {
    * does not perturb the key -- `JSON.stringify` omits it. `preserveFormatting`
    * is the exception: the service merges a config default for it, so it is always
    * materialized and every key reflects it. `glossaryIds` is hashed in the
-   * caller's order rather than sorted, because reordering the list changes which
-   * glossary wins a conflicting term and therefore the translation itself.
+   * caller's order rather than sorted, because that order is what goes on the
+   * wire, and the API is free to return a different translation for a different
+   * ordering of the same glossaries.
    *
    * `tagHandlingVersion` is resolved rather than read straight off the options,
    * so it holds the version the request will actually carry. Leaving it unset
diff --git a/src/types/api.ts b/src/types/api.ts
index 0dde7419..cfc2e429 100644
--- a/src/types/api.ts
+++ b/src/types/api.ts
@@ -15,9 +15,12 @@ export interface TranslationOptions {
   targetLang: Language;
   glossaryId?: string;
   /**
-   * Two to five glossaries applied to one request. Their entries are merged;
-   * when more than one defines the same source term the last one wins, so the
-   * order is significant. Mutually exclusive with `glossaryId`.
+   * Two to five glossaries applied to one request. Their entries are merged, so
+   * a term unique to any one of them applies. When more than one defines the
+   * same source term the API picks the winner, and it does not follow this
+   * order — do not rely on position to resolve a conflict. The order is still
+   * sent as given and never sorted, since it is part of the cache key.
+   * Mutually exclusive with `glossaryId`.
    */
   glossaryIds?: string[];
   translationMemoryId?: string;
diff --git a/src/utils/glossary-params.ts b/src/utils/glossary-params.ts
index 9622cedd..2b2ed5b1 100644
--- a/src/utils/glossary-params.ts
+++ b/src/utils/glossary-params.ts
@@ -57,8 +57,10 @@ export type GlossaryWireParams =
  * cache keys — they had before `glossary_ids` existed. Two or more go out as
  * `glossary_ids`, which the API refuses to accept alongside `glossary_id`.
  *
- * The list order is preserved and never sorted: when several glossaries define
- * the same source term, the API applies the last one that names it.
+ * The list order is preserved and never sorted, because it is part of the cache
+ * key. It does not decide conflicts: when several glossaries define the same
+ * source term, which mapping wins is the API's choice and does not track
+ * position in this list.
  */
 export function resolveGlossaryWireParams(
   selection: GlossarySelection,
diff --git a/tests/e2e/cli-multi-glossary.e2e.test.ts b/tests/e2e/cli-multi-glossary.e2e.test.ts
index 8ae6e131..48fc2c8e 100644
--- a/tests/e2e/cli-multi-glossary.e2e.test.ts
+++ b/tests/e2e/cli-multi-glossary.e2e.test.ts
@@ -25,8 +25,13 @@ describe('translate --glossary repetition E2E', () => {
       expect(runCLI('translate --help')).toMatch(/max 5/i);
     });
 
-    it('should document that the last glossary wins a conflict', () => {
-      expect(runCLI('translate --help')).toMatch(/last one wins/i);
+    it('should document that flag order does not resolve a conflicting term', () => {
+      const output = runCLI('translate --help');
+
+      expect(output).toMatch(/merged/i);
+      // The help text is wrapped, so the phrase can carry a newline and indent.
+      expect(output).toMatch(/regardless\s+of\s+flag\s+order/i);
+      expect(output).not.toMatch(/last one wins/i);
     });
   });
 
diff --git a/tests/unit/document-client.test.ts b/tests/unit/document-client.test.ts
index b9a51ea3..b0ae55d6 100644
--- a/tests/unit/document-client.test.ts
+++ b/tests/unit/document-client.test.ts
@@ -175,12 +175,12 @@ describe('DocumentClient', () => {
         expect(body.match(/name="glossary_ids"/g)).toHaveLength(1);
       });
 
-      it('should not pad the joined IDs with whitespace, which voids the parameter', async () => {
+      it('should join the IDs without padding whitespace', async () => {
         await upload({ glossaryIds: [A, B] });
         expect(getMultipartBody()).not.toContain(`${A}, ${B}`);
       });
 
-      it('should keep the caller order, since the last glossary wins', async () => {
+      it('should keep the caller order rather than sorting it', async () => {
         await upload({ glossaryIds: [B, A] });
         expect(getMultipartBody()).toContain(`${B},${A}`);
       });
diff --git a/tests/unit/glossary-params.test.ts b/tests/unit/glossary-params.test.ts
index 12a12acc..ff76014f 100644
--- a/tests/unit/glossary-params.test.ts
+++ b/tests/unit/glossary-params.test.ts
@@ -36,7 +36,7 @@ describe('resolveGlossaryWireParams', () => {
     expect(resolveGlossaryWireParams({ glossaryIds: [A, B] })).toEqual({ glossary_ids: [A, B] });
   });
 
-  it('should preserve the caller order, since the last glossary wins conflicts', () => {
+  it('should preserve the caller order rather than sorting it', () => {
     expect(resolveGlossaryWireParams({ glossaryIds: [C, A, B] })).toEqual({
       glossary_ids: [C, A, B],
     });
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index a0cea26f..8264a54a 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -285,7 +285,7 @@ describe('TranslationClient', () => {
       expect(body).not.toMatch(/(^|&)glossary_id=/);
     });
 
-    it('should keep the caller order on the wire, since the last glossary wins', async () => {
+    it('should keep the caller order on the wire rather than sorting it', async () => {
       await client.translate('Hello', { targetLang: 'es', glossaryIds: [C, A] });
       expect(getRequestBody()).toContain(`glossary_ids=${C}&glossary_ids=${A}`);
     });
diff --git a/tests/unit/translation-service.test.ts b/tests/unit/translation-service.test.ts
index 615bedde..e203e6c0 100644
--- a/tests/unit/translation-service.test.ts
+++ b/tests/unit/translation-service.test.ts
@@ -1187,7 +1187,7 @@ describe('TranslationService', () => {
         expect(one).not.toBe(two);
       });
 
-      /** Reordering changes which glossary wins a conflicting term, so the keys must differ. */
+      /** A reordered list is a different request to the API, so the keys must differ. */
       it('should separate the two orderings of the same glossaries', async () => {
         const [ab, ba] = await keysFor([{ glossaryIds: [A, B] }, { glossaryIds: [B, A] }]);
         expect(ab).not.toBe(ba);

From 193510ccb3bc764448530464bb5c0e73cad073fc Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 18:07:20 -0400
Subject: [PATCH 069/256] docs(test): correct the nock leak comment's
 attribution and audit rule
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The block added in dd7591c pinned the leak on six `replyWithError` sites
in deepl-client.test.ts plus three integration files. Tracing the handles
says otherwise: they arise in the translate() and error handling blocks,
through ordinary `.reply(...)` interceptions. That file has 122 `.reply()`
calls against 2 `replyWithError`, only one of which even sits in a leaking
block, and the replyWithError inventory has since grown to 14 call sites
across 6 files.

That stale baseline made the audit instruction unusable: it asked for "any
NEW leak source beyond the six known replyWithError sites", which names the
wrong construct and drifts every time a test moves. The rule is now
type-based — every reported handle should be HTTPINCOMINGMESSAGE from
@mswjs/interceptors, and anything else is a real leak.

The mechanism and both mitigations were re-verified and kept: forceExit
does not suppress the warning, and --runInBand avoids it at ~5x wall clock.
Whether a newer @mswjs/interceptors helps is now recorded as untested
rather than assumed, since 0.42 is ESM-only and fails the CJS transform.
---
 jest.config.js | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/jest.config.js b/jest.config.js
index 8a2c83ff..290b6b46 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -93,18 +93,18 @@ export default {
   resetMocks: true,
   restoreMocks: true,
 
-  // KNOWN BENIGN WARNING: jest emits "A worker process has failed to exit
-  // gracefully" at the end of every full-suite run. Stack traces lead to six
-  // `nock(...).replyWithError(...)` test sites in deepl-client.test.ts and
-  // three integration files. The leak is in nock v14 + @mswjs/interceptors:
-  // each replyWithError call constructs a synthetic Node IncomingMessage
-  // that is never drained, leaving an HTTPINCOMINGMESSAGE handle pinned in
-  // the worker. The affected tests all PASS — only the orphaned handles
-  // trigger the warning. `forceExit: true` does not suppress it (the warning
-  // fires from the worker, not the main process, before forceExit applies),
-  // and `--runInBand` eliminates it but is 5× slower. Fixing upstream
-  // (nock/mswjs) is out of scope. Run `npm run test:debug` to audit for
-  // any NEW leak source beyond the six known replyWithError sites.
+  // KNOWN BENIGN WARNING: every full-suite run ends with "A worker process has
+  // failed to exit gracefully". nock's interceptor (@mswjs/interceptors) leaves
+  // undrained IncomingMessage objects behind, each pinned as an
+  // HTTPINCOMINGMESSAGE handle the worker cannot shed. All tests still pass.
+  //
+  // Nothing available here suppresses it: the teardown in tests/setup.ts and
+  // HttpClient.destroy() never own that socket, `forceExit` fires too late, and
+  // `--runInBand` avoids it at ~5x wall clock. Going past interceptors 0.41 is
+  // untested — 0.42 is ESM-only and fails the CJS transform.
+  //
+  // Audit real leaks with `npm run test:debug` by handle type, not count:
+  // anything but HTTPINCOMINGMESSAGE from @mswjs/interceptors is new.
 
   // Verbose output
   verbose: true,

From 80717393dba348579e6cd5e400ffd76c2a7dbf21 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 22:26:20 -0400
Subject: [PATCH 070/256] docs: correct inaccuracies found in the pre-2.0 audit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`docs/API.md` and `README.md` said the last `--glossary` wins a conflicting
term, contradicting the same files, the flag's own help text, and the verified
behaviour: which mapping wins is the API's choice and does not follow flag
order.

`docs/API.md`'s command-group table omitted `correct` while claiming to match
`deepl --help`, and the README's table of contents omitted its Spelling and
Grammar Correction section. A new check in the documented-surface suite fails
when the table and the CLI's top-level commands disagree in either direction.

`docs/API.md`'s environment-variable reference omitted `NO_PROXY`, which the
HTTP client honours and the README already documented.

`docs/TROUBLESHOOTING.md` attributed "Translation cache backend failed to load"
to running Node.js < 24, which the startup version check rejects earlier with
its own message, so the stated cause was unreachable. That entry now describes
the reachable case — a v24+ runtime with no usable `node:sqlite` — and the
version error is documented under exit code 6, where it appeared nowhere.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                               |  2 +
 README.md                                  |  6 +--
 docs/API.md                                | 22 +++++++----
 docs/TROUBLESHOOTING.md                    | 14 +++++--
 tests/unit/docs/documented-surface.test.ts | 43 ++++++++++++++++++++++
 5 files changed, 73 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c92f801b..8214fd2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **docs**: Five documentation inaccuracies found in the pre-2.0 audit. `docs/API.md` and `README.md` still said the **last** `--glossary` wins a conflicting term, contradicting the same files, the flag's own help text, and the verified behaviour — which mapping wins is the API's choice and does not follow flag order. `docs/API.md`'s command-group table omitted `correct` while claiming to match `deepl --help`, and the README's table of contents omitted its Spelling and Grammar Correction section. `docs/API.md`'s environment-variable reference omitted `NO_PROXY`, which the HTTP client honours and the README already documented. `docs/TROUBLESHOOTING.md` attributed "Translation cache backend failed to load" to running Node.js < 24, which the startup version check now rejects earlier with its own message, so the stated cause was unreachable; that entry now describes the reachable case (a v24+ runtime with no usable `node:sqlite`) and the version error is documented under exit code 6, where it previously appeared nowhere.
+
 - **package**: **`import '@deepl/cli'` threw instead of loading.** The package is ESM, so Node requires a full specifier for every relative import, but the entry point re-exported `'./types'` — a directory — which fails with `ERR_UNSUPPORTED_DIR_IMPORT`. The whole programmatic surface was therefore unreachable, and the published typings resolved to nothing for a `nodenext` consumer, so `import type { Language } from '@deepl/cli'` was an error regardless of what the union contained. `deepl --help` never exercised this, because the `bin` entry has its own module graph. Both remaining directory specifiers now carry `/index.js`, and the manifest suite imports the built entry in a real Node ESM process and rejects any extensionless relative specifier in the emitted entry chain.
 
 - **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
diff --git a/README.md b/README.md
index edadd994..60edc71d 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ For security policy and vulnerability reporting, see [SECURITY.md](SECURITY.md).
     - [Proxy Configuration](#proxy-configuration)
     - [Retry and Timeout Configuration](#retry-and-timeout-configuration)
 - [Usage](#-usage)
-  - **Core Commands:** [Translation](#translation) | [Writing Enhancement](#writing-enhancement) | [Voice Translation](#voice-translation)
+  - **Core Commands:** [Translation](#translation) | [Writing Enhancement](#writing-enhancement) | [Spelling and Grammar Correction](#spelling-and-grammar-correction) | [Voice Translation](#voice-translation)
   - **Resources:** [Glossaries](#glossaries) | [Translation Memories](#translation-memories)
   - **Workflow:** [Continuous Localization (sync)](#continuous-localization-deepl-sync) | [Watch Mode](#watch-mode) | [Git Hooks](#git-hooks)
   - **Configuration:** [Setup Wizard](#setup-wizard) | [Authentication](#authentication) | [Configure Defaults](#configure-defaults) | [Cache Management](#cache-management) | [Style Rules](#style-rules)
@@ -1307,10 +1307,10 @@ authentication	Authentifizierung
 - **Smart defaults** - `--target` flag only required for multilingual glossaries
 - **Visual indicators** - 📖 for single-target, 📚 for multilingual glossaries
 - **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms (a source language is required, since the API rejects a glossary without one: pass `--from`, or set `defaults.sourceLang`)
-- **Several glossaries at once** - Repeat `--glossary` on `translate` for up to 5 glossaries; entries are merged and the last glossary given wins any conflicting term
+- **Several glossaries at once** - Repeat `--glossary` on `translate` for up to 5 glossaries; entries are merged, and a term defined in more than one is resolved by the API, not by flag order
 
 ```bash
-# Layer project overrides on top of shared base terminology
+# Combine shared base terminology with project-specific terms
 deepl translate "Hello world" --from en --to de --glossary base-terms --glossary project-overrides
 ```
 
diff --git a/docs/API.md b/docs/API.md
index 566111a9..a6c51983 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -186,7 +186,7 @@ Commands are organized into six groups, matching the `deepl --help` output:
 
 | Group              | Commands                                         | Description                                                               |
 | ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------- |
-| **Core Commands**  | `translate`, `write`, `voice`                    | Translation, writing enhancement, and speech translation                  |
+| **Core Commands**  | `translate`, `write`, `correct`, `voice`         | Translation, writing enhancement, spelling and grammar correction, and speech translation |
 | **Resources**      | `glossary`, `tm`                                 | Manage translation glossaries and translation memory                      |
 | **Workflow**       | `watch`, `sync`, `hooks`                         | File watching, project sync, and git hook automation                      |
 | **Configuration**  | `init`, `auth`, `config`, `cache`, `style-rules` | Setup wizard, authentication, settings, caching, and style rules          |
@@ -251,7 +251,7 @@ Translate text directly, from stdin, from files, or entire directories. Supports
 - `--non-splitting-tags TAGS` - Comma-separated XML tags that should not be used to split sentences (requires `--tag-handling xml`)
 - `--ignore-tags TAGS` - Comma-separated XML tags with content to ignore (requires `--tag-handling xml`)
 - `--tag-handling-version VERSION` - Tag handling version: `v1`, `v2`. v2 improves XML/HTML structure handling (requires `--tag-handling`). **Defaults to `v2`**, sent explicitly on every `--tag-handling` request rather than left to the API's own default, which is documented as moving from v1 to v2 at some point — pinning keeps output from shifting on DeepL's timetable. Pass `--tag-handling-version v1` for the older behaviour, which DeepL documents as heading for deprecation
-- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. Repeatable, up to 5 per request; when several glossaries define the same source term, the last one given wins. Passing a 6th exits 6 (ValidationError). A source language is required, because the API rejects a glossary without one: supply `--from`, or set `defaults.sourceLang` and it is used automatically. With neither, the command exits 6 before any request.
+- `--glossary NAME-OR-ID` - Use glossary by name or ID for consistent terminology. Repeatable, up to 5 per request; entries are merged, so terms unique to each glossary all apply. When several glossaries define the same source term, which mapping wins is the API's choice and does not follow flag order, so position is not a way to override a term. Passing a 6th exits 6 (ValidationError). A source language is required, because the API rejects a glossary without one: supply `--from`, or set `defaults.sourceLang` and it is used automatically. With neither, the command exits 6 before any request.
 - `--translation-memory NAME-OR-UUID` - Use translation memory by name or UUID (forces `quality_optimized` model). Requires `--from` because TMs are pinned to a specific source→target language pair. Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
 - `--tm-threshold N` - Minimum match score 0–100 (default 75, requires `--translation-memory`). Invalid use exits 6 (ValidationError); unresolvable/misconfigured TM exits 7 (ConfigError).
 - `--custom-instruction INSTRUCTION` - Custom instruction for translation (repeatable, max 10, max 300 chars each). Forces `quality_optimized` model. Cannot be used with `latency_optimized`.
@@ -553,15 +553,13 @@ deepl translate README.md --from en --to fr --glossary abc-123-def-456 --output
 
 **Multiple glossaries on one request:**
 
-Repeat `--glossary` to apply up to 5 glossaries to a single request. Their entries are merged, so terms unique to each glossary all apply. When more than one glossary defines the same source term, the **last** `--glossary` on the command line wins — order is significant, and reordering the flags produces a different translation (and a separate cache entry). Names and UUIDs can be mixed; each value is resolved independently. A 6th `--glossary` exits 6 (ValidationError). A name that cannot be resolved — unknown, ambiguous, or covering a different language pair than the one requested — exits 7 (ConfigError) without sending a translation request.
+Repeat `--glossary` to apply up to 5 glossaries to a single request. Their entries are merged, so terms unique to each glossary all apply. When more than one glossary defines the same source term, **which mapping wins is the API's choice and does not follow flag order** — position is not a way to override a term, so avoid relying on one glossary to shadow another. The order is still sent as given and never sorted, because it is part of the cache key: reordering the flags is a different request with its own cache entry. Names and UUIDs can be mixed; each value is resolved independently. A 6th `--glossary` exits 6 (ValidationError). A name that cannot be resolved — unknown, ambiguous, or covering a different language pair than the one requested — exits 7 (ConfigError) without sending a translation request.
 
 ```bash
-# Shared base terminology, overridden by project-specific terms
+# Shared base terminology combined with project-specific terms; terms unique
+# to each apply, and a term defined in both is resolved by the API
 deepl translate "Hello world" --from en --to de --glossary base-terms --glossary project-overrides
 
-# Reversing the order makes base-terms win any conflicting entry
-deepl translate "Hello world" --from en --to de --glossary project-overrides --glossary base-terms
-
 # Names and UUIDs can be mixed
 deepl translate README.md --from en --to fr --output README.fr.md \
   --glossary abc-123-def-456 --glossary house-style
@@ -1114,7 +1112,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 - `--to, -t LANGS` - Target language(s), comma-separated (uses configured `defaults.targetLangs` if omitted)
 - `--output, -o DIR` - Output directory (default: `<path>/translations` for directories, same dir for files)
 - `--pattern GLOB` - File pattern filter (e.g., `*.md`, `**/*.json`)
-- `--debounce MS` - Debounce delay in milliseconds (default: 500)
+- `--debounce MS` - Debounce delay in milliseconds. The flag wins, then the configured `watch.debounceMs`, then the default of 500
 - `--concurrency NUM` - Maximum parallel translations (default: 5)
 
 **Translation Options:**
@@ -3199,6 +3197,14 @@ Route outbound DeepL API requests through an HTTPS proxy. Takes precedence over
 export HTTPS_PROXY="http://proxy.example.com:3128"
 ```
 
+### `NO_PROXY`
+
+Comma-separated list of hosts that bypass `HTTP_PROXY` / `HTTPS_PROXY`. Standard semantics apply: `*` bypasses everything, a leading dot or `*.` matches subdomains, and an entry may carry a `host:port` that must agree with the target port. Also recognized as lowercase `no_proxy`.
+
+```bash
+export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
+```
+
 ### `TMS_API_KEY`
 
 API key used by `deepl sync push` and `deepl sync pull` to authenticate against the external translation management system configured under `tms.server` in `.deepl-sync.yaml`. See [docs/SYNC.md](SYNC.md) for setup details.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index a639e965..3dd74858 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -392,6 +392,14 @@ deepl languages --source
 deepl languages --target
 ```
 
+### Unsupported Node.js version
+
+The CLI exits 6 with a single line naming the required and the running version — `requires Node.js >= 24, you are running v22.11.0. Upgrade Node.js to use the DeepL CLI.`
+
+**Cause:** The CLI requires Node.js 24 or later and checks the version at startup, before loading anything else, so an unsupported runtime gets that one line instead of an experimental-module warning or a later crash.
+
+**Solution:** upgrade Node.js — e.g. `nvm install 24 && nvm use 24`, or install Node 24 from [nodejs.org](https://nodejs.org/). Confirm with `node --version` that the runtime invoking `deepl` is the upgraded one; a globally linked CLI can otherwise still run under an older default.
+
 ---
 
 ## Cache Issues
@@ -423,11 +431,11 @@ deepl cache enable
 
 ### "Translation cache backend failed to load"
 
-**Cause:** The cache uses Node's built-in `node:sqlite` module, which requires Node.js 24 or later (the CLI's minimum supported version). On an older runtime the module doesn't exist, so caching cannot start.
+**Cause:** The cache uses Node's built-in `node:sqlite` module and the runtime could not load it. Running on Node.js older than 24 is reported earlier and separately — see [Unsupported Node.js version](#unsupported-nodejs-version) — so what reaches this message is a runtime that reports version 24 or later but still has no usable `node:sqlite`: a Node built without SQLite support, or a non-Node runtime claiming a compatible version.
 
-Translation and write commands keep working with caching disabled for the run; your cache database is not modified. `deepl cache` subcommands fail until the CLI runs on a supported Node.js version.
+Translation and write commands keep working with caching disabled for the run; your cache database is not modified. `deepl cache` subcommands fail until the module loads.
 
-**Solution:** run the CLI with Node.js 24 or later — e.g. `nvm install 24 && nvm use 24`, or install Node 24 from [nodejs.org](https://nodejs.org/).
+**Solution:** run the CLI on an official Node.js 24+ build — e.g. `nvm install 24 && nvm use 24`, or install Node 24 from [nodejs.org](https://nodejs.org/). To confirm the module is the problem, check that `node -e "require('node:sqlite')"` succeeds on the same runtime.
 
 ---
 
diff --git a/tests/unit/docs/documented-surface.test.ts b/tests/unit/docs/documented-surface.test.ts
index b1be8c93..f41bf5b4 100644
--- a/tests/unit/docs/documented-surface.test.ts
+++ b/tests/unit/docs/documented-surface.test.ts
@@ -149,6 +149,49 @@ describe('documented CLI surface', () => {
     });
   });
 
+  describe('command-group table in docs/API.md', () => {
+    // The table claims to match `deepl --help`, so a command missing from it
+    // reads as one the CLI does not have. `correct` was absent from the Core
+    // Commands row for a whole release while having its own reference section,
+    // which no invocation-level check can see.
+    function groupedCommands(): Set<string> {
+      const contents = fs.readFileSync(path.join(ROOT, 'docs/API.md'), 'utf-8');
+      const table = contents.slice(contents.indexOf('## Commands'));
+      const names = new Set<string>();
+
+      let started = false;
+      for (const line of table.split('\n')) {
+        const isGroupRow = line.startsWith('| **');
+        if (isGroupRow) started = true;
+        else if (started) break;
+        if (!isGroupRow) continue;
+
+        for (const cell of line.match(/`([a-z-]+)`/g) ?? []) {
+          names.add(cell.replace(/`/g, ''));
+        }
+      }
+      return names;
+    }
+
+    it('lists every command the CLI exposes in --help', () => {
+      const documented = groupedCommands();
+      const missing = surface.commands
+        .map((command) => command.name)
+        .filter((name) => !name.startsWith('_') && name !== 'help')
+        .filter((name) => !documented.has(name));
+
+      expect(missing).toEqual([]);
+    });
+
+    it('lists no command the CLI does not provide', () => {
+      const unknown = [...groupedCommands()].filter(
+        (name) => resolveCommand([name]) === undefined,
+      );
+
+      expect(unknown).toEqual([]);
+    });
+  });
+
   describe('retired endpoints', () => {
     // Language listings moved to GET /v3/languages; the v2 endpoints are
     // formally deprecated, so no doc should teach a reader to call them.

From ca19cf1243a57162d3cb3c36e9cdd345182dda8f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 22:26:41 -0400
Subject: [PATCH 071/256] fix(watch): honour the documented 500ms debounce
 default and watch.debounceMs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`deepl watch` debounced at 300 ms while `--help`, the docs and the config
schema all said 500. The command forwarded a debounce only when `--debounce`
was passed, so an omitted flag fell through to `WatchService`'s own 300 ms
fallback — a third copy of a value the schema and the help text both put at
500.

`watch.debounceMs` was also dead: `deepl config set` accepted it and the
documented schema listed it, but nothing read it for `watch`.

Resolution is now the flag, then `watch.debounceMs`, then the documented
default, which is a single exported constant shared with the config schema so
the two cannot drift again. `deepl sync --watch` already resolved to 500 and is
unchanged.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                     |  2 +
 src/cli/commands/watch.ts        | 11 +++--
 src/storage/config.ts            |  5 ++-
 tests/unit/watch-command.test.ts | 76 ++++++++++++++++++++++++++++++++
 4 files changed, 90 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8214fd2e..a27a461e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -113,6 +113,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **docs**: Five documentation inaccuracies found in the pre-2.0 audit. `docs/API.md` and `README.md` still said the **last** `--glossary` wins a conflicting term, contradicting the same files, the flag's own help text, and the verified behaviour — which mapping wins is the API's choice and does not follow flag order. `docs/API.md`'s command-group table omitted `correct` while claiming to match `deepl --help`, and the README's table of contents omitted its Spelling and Grammar Correction section. `docs/API.md`'s environment-variable reference omitted `NO_PROXY`, which the HTTP client honours and the README already documented. `docs/TROUBLESHOOTING.md` attributed "Translation cache backend failed to load" to running Node.js < 24, which the startup version check now rejects earlier with its own message, so the stated cause was unreachable; that entry now describes the reachable case (a v24+ runtime with no usable `node:sqlite`) and the version error is documented under exit code 6, where it previously appeared nowhere.
 
+- **watch**: **`deepl watch` debounced at 300 ms while `--help` and every doc said 500, and `watch.debounceMs` did nothing.** The command forwarded a debounce only when `--debounce` was passed, so an omitted flag fell through to `WatchService`'s own 300 ms fallback — a third copy of a value the config schema and the flag's help text both put at 500. The configured key was accepted by `deepl config set` and listed in the documented schema, but nothing ever read it for `watch`. Resolution is now flag, then `watch.debounceMs`, then the documented 500 ms default, and that default is a single exported constant shared with the config schema so the two cannot drift again. `deepl sync --watch` was already correct at 500 and is unchanged.
+
 - **package**: **`import '@deepl/cli'` threw instead of loading.** The package is ESM, so Node requires a full specifier for every relative import, but the entry point re-exported `'./types'` — a directory — which fails with `ERR_UNSUPPORTED_DIR_IMPORT`. The whole programmatic surface was therefore unreachable, and the published typings resolved to nothing for a `nodenext` consumer, so `import type { Language } from '@deepl/cli'` was an error regardless of what the union contained. `deepl --help` never exercised this, because the `bin` entry has its own module graph. Both remaining directory specifiers now carry `/index.js`, and the manifest suite imports the built entry in a real Node ESM process and rejects any extensionless relative specifier in the emitted entry chain.
 
 - **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index 759bdb4d..f2820833 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -16,6 +16,7 @@ import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
 import { applyGlossarySourceLang, hasGlossarySelection } from '../../utils/glossary-params.js';
 import type { ConfigService } from '../../storage/config.js';
+import { DEFAULT_DEBOUNCE_MS } from '../../storage/config.js';
 
 interface WatchOptions {
   to: string;
@@ -164,9 +165,13 @@ export class WatchCommand {
       stagedFiles?: Set<string>;
     } = { pattern: options.pattern, stagedFiles };
 
-    if (options.debounce) {
-      watchServiceOptions.debounceMs = options.debounce;
-    }
+    // The default is applied here rather than left to WatchService so that the
+    // documented value holds and `watch.debounceMs` takes effect: the flag wins,
+    // then configuration, then the documented default.
+    watchServiceOptions.debounceMs =
+      options.debounce ??
+      this.config?.getValue<number>('watch.debounceMs') ??
+      DEFAULT_DEBOUNCE_MS;
     if (options.concurrency) {
       watchServiceOptions.concurrency = options.concurrency;
     }
diff --git a/src/storage/config.ts b/src/storage/config.ts
index 06ef78d6..4ee76055 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -43,7 +43,10 @@ const FORBIDDEN_KEY_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']
 
 const DEFAULT_CACHE_SIZE = 1024 * 1024 * 1024; // 1GB
 const DEFAULT_CACHE_TTL = 30 * 24 * 60 * 60; // 30 days in seconds
-const DEFAULT_DEBOUNCE_MS = 500;
+/** Debounce delay applied by `watch` when neither the flag nor configuration
+ *  names one. Exported so the CLI default and this schema default stay one
+ *  value. */
+export const DEFAULT_DEBOUNCE_MS = 500;
 
 /**
  * Language values are stored lowercase, matching what `deepl languages` prints
diff --git a/tests/unit/watch-command.test.ts b/tests/unit/watch-command.test.ts
index 7e354679..344331fb 100644
--- a/tests/unit/watch-command.test.ts
+++ b/tests/unit/watch-command.test.ts
@@ -243,6 +243,82 @@ describe('WatchCommand', () => {
       );
     });
 
+    it('should apply the documented 500ms default when --debounce is omitted', async () => {
+      expect.assertions(1);
+      (fs.existsSync as jest.Mock).mockReturnValue(true);
+      (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+
+      try {
+        await watchCommand.watch('/some/file.md', { to: 'es' });
+      } catch {
+        // Expected
+      }
+
+      expect(WatchService).toHaveBeenCalledWith(
+        mockFileTranslationService,
+        expect.objectContaining({
+          debounceMs: 500,
+        })
+      );
+    });
+
+    it('should honour watch.debounceMs from config when --debounce is omitted', async () => {
+      expect.assertions(1);
+      (fs.existsSync as jest.Mock).mockReturnValue(true);
+      (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+
+      const configured = new WatchCommand(
+        mockTranslationService,
+        mockGlossaryService,
+        createMockConfigService({
+          getValue: jest.fn((key: string) => (key === 'watch.debounceMs' ? 1200 : undefined)),
+        }),
+      );
+
+      try {
+        await configured.watch('/some/file.md', { to: 'es' });
+      } catch {
+        // Expected
+      }
+
+      expect(WatchService).toHaveBeenCalledWith(
+        mockFileTranslationService,
+        expect.objectContaining({
+          debounceMs: 1200,
+        })
+      );
+    });
+
+    it('should let --debounce override watch.debounceMs from config', async () => {
+      expect.assertions(1);
+      (fs.existsSync as jest.Mock).mockReturnValue(true);
+      (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+
+      const configured = new WatchCommand(
+        mockTranslationService,
+        mockGlossaryService,
+        createMockConfigService({
+          getValue: jest.fn((key: string) => (key === 'watch.debounceMs' ? 1200 : undefined)),
+        }),
+      );
+
+      try {
+        await configured.watch('/some/file.md', { to: 'es', debounce: 250 });
+      } catch {
+        // Expected
+      }
+
+      expect(WatchService).toHaveBeenCalledWith(
+        mockFileTranslationService,
+        expect.objectContaining({
+          debounceMs: 250,
+        })
+      );
+    });
+
     it('should pass pattern option to WatchService', async () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);

From b627b424145135ce6fb4aa7fd336b9629fc701dc Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 22:29:06 -0400
Subject: [PATCH 072/256] refactor(exit-codes): consolidate on exitCodeForError
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`getExitCodeFromError` was a same-body alias documented as kept "for backwards
compatibility with callers that import the old name", but `exit-codes.ts` is
not exported from the package entry, so no such caller could exist — the only
`src/` use was the CLI's own top-level handler.

Dropping it also removes a redundant guard at that call site: the alias
narrowed its parameter to `Error`, so the handler tested `instanceof Error` and
supplied `GeneralError` itself. `exitCodeForError` takes `unknown` and already
returns `GeneralError` for a non-`Error`, so the ternary is now a single call
with identical behaviour.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/cli/index.ts                      |  7 ++-----
 src/utils/exit-codes.ts               |  8 --------
 tests/unit/exit-codes.test.ts         | 16 ++++++++--------
 tests/unit/voice-types-errors.test.ts |  8 ++++----
 4 files changed, 14 insertions(+), 25 deletions(-)

diff --git a/src/cli/index.ts b/src/cli/index.ts
index 1c1365ce..1a853154 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -16,7 +16,7 @@ import { resolvePaths } from '../utils/paths.js';
 import type { DeepLClient } from '../api/deepl-client.js';
 import { Logger } from '../utils/logger.js';
 import { AuthError, DeepLCLIError } from '../utils/errors.js';
-import { ExitCode, getExitCodeFromError } from '../utils/exit-codes.js';
+import { ExitCode, exitCodeForError } from '../utils/exit-codes.js';
 import { isSymlink } from '../utils/safe-read-file.js';
 import { setNoInput } from '../utils/confirm.js';
 import { registerAuth } from './commands/register-auth.js';
@@ -76,10 +76,7 @@ const getCacheService = createCacheServiceGetter(() =>
  */
 function handleError(error: unknown): never {
   const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-  const exitCode =
-    error instanceof Error
-      ? getExitCodeFromError(error)
-      : ExitCode.GeneralError;
+  const exitCode = exitCodeForError(error);
 
   Logger.error(chalk.red('Error:'), errorMessage);
 
diff --git a/src/utils/exit-codes.ts b/src/utils/exit-codes.ts
index cb1bb5ce..6b156f72 100644
--- a/src/utils/exit-codes.ts
+++ b/src/utils/exit-codes.ts
@@ -66,14 +66,6 @@ export function exitCodeForError(error: unknown): ExitCode {
   return ExitCode.GeneralError;
 }
 
-/**
- * Legacy alias kept for backwards compatibility with callers that import
- * the old name. Prefer `exitCodeForError`.
- */
-export function getExitCodeFromError(error: Error): ExitCode {
-  return exitCodeForError(error);
-}
-
 function classifyByMessage(rawMessage: string): ExitCode {
   Logger.verbose(`Untyped error reached fallback classifier: "${rawMessage.substring(0, 120)}"`);
   const message = rawMessage.toLowerCase();
diff --git a/tests/unit/exit-codes.test.ts b/tests/unit/exit-codes.test.ts
index 7be7f989..e7605783 100644
--- a/tests/unit/exit-codes.test.ts
+++ b/tests/unit/exit-codes.test.ts
@@ -3,7 +3,7 @@
  * Tests for exit code classification and retry logic
  */
 
-import { ExitCode, getExitCodeFromError, isRetryableError } from '../../src/utils/exit-codes';
+import { ExitCode, exitCodeForError, isRetryableError } from '../../src/utils/exit-codes';
 import { AuthError } from '../../src/utils/errors';
 import { Logger } from '../../src/utils/logger';
 
@@ -33,7 +33,7 @@ describe('ExitCode', () => {
     });
   });
 
-  describe('getExitCodeFromError', () => {
+  describe('exitCodeForError', () => {
     it.each<[string, string, ExitCode]>([
       // AuthError classification
       ['authentication failed', 'Authentication failed', ExitCode.AuthError],
@@ -96,19 +96,19 @@ describe('ExitCode', () => {
     ])(
       'should classify %s error message "%s" → exit code %i',
       (_, message, expectedCode) => {
-        expect(getExitCodeFromError(new Error(message))).toBe(expectedCode);
+        expect(exitCodeForError(new Error(message))).toBe(expectedCode);
       },
     );
 
     describe('priority ordering', () => {
       it('should prioritize specific auth patterns over generic invalid pattern', () => {
         const error = new Error('invalid api key');
-        expect(getExitCodeFromError(error)).toBe(ExitCode.AuthError);
+        expect(exitCodeForError(error)).toBe(ExitCode.AuthError);
       });
 
       it('should classify pure config file errors correctly', () => {
         const error = new Error('Config file corrupted');
-        expect(getExitCodeFromError(error)).toBe(ExitCode.ConfigError);
+        expect(exitCodeForError(error)).toBe(ExitCode.ConfigError);
       });
     });
 
@@ -134,20 +134,20 @@ describe('ExitCode', () => {
     ])(
       'should fall back to GeneralError for %s ("%s")',
       (_, message) => {
-        expect(getExitCodeFromError(new Error(message))).toBe(ExitCode.GeneralError);
+        expect(exitCodeForError(new Error(message))).toBe(ExitCode.GeneralError);
       },
     );
 
     it('should log verbose warning when classifyByMessage is invoked', () => {
       const verboseSpy = jest.spyOn(Logger, 'verbose').mockImplementation();
-      getExitCodeFromError(new Error('some unknown error'));
+      exitCodeForError(new Error('some unknown error'));
       expect(verboseSpy).toHaveBeenCalledWith(expect.stringContaining('Untyped error'));
       verboseSpy.mockRestore();
     });
 
     it('should not log verbose warning for typed DeepLCLIError', () => {
       const verboseSpy = jest.spyOn(Logger, 'verbose').mockImplementation();
-      getExitCodeFromError(new AuthError('test'));
+      exitCodeForError(new AuthError('test'));
       expect(verboseSpy).not.toHaveBeenCalled();
       verboseSpy.mockRestore();
     });
diff --git a/tests/unit/voice-types-errors.test.ts b/tests/unit/voice-types-errors.test.ts
index 6022ebcf..bdf354ae 100644
--- a/tests/unit/voice-types-errors.test.ts
+++ b/tests/unit/voice-types-errors.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { VoiceError } from '../../src/utils/errors.js';
-import { ExitCode, getExitCodeFromError } from '../../src/utils/exit-codes.js';
+import { ExitCode, exitCodeForError } from '../../src/utils/exit-codes.js';
 import { formatVoiceJson } from '../../src/utils/formatters.js';
 import type { VoiceSessionResult } from '../../src/types/voice.js';
 
@@ -47,17 +47,17 @@ describe('ExitCode.VoiceError', () => {
 
   it('should return VoiceError exit code for VoiceError instances', () => {
     const error = new VoiceError('test');
-    expect(getExitCodeFromError(error)).toBe(ExitCode.VoiceError);
+    expect(exitCodeForError(error)).toBe(ExitCode.VoiceError);
   });
 
   it('should classify "voice api" messages as VoiceError', () => {
     const error = new Error('Voice API not available');
-    expect(getExitCodeFromError(error)).toBe(ExitCode.VoiceError);
+    expect(exitCodeForError(error)).toBe(ExitCode.VoiceError);
   });
 
   it('should classify "voice session" messages as VoiceError', () => {
     const error = new Error('Voice session creation failed');
-    expect(getExitCodeFromError(error)).toBe(ExitCode.VoiceError);
+    expect(exitCodeForError(error)).toBe(ExitCode.VoiceError);
   });
 });
 

From 01ec9a3890845750bfc052339adb3296e5e18c60 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 22:37:51 -0400
Subject: [PATCH 073/256] style: apply prettier to src and tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`npm run format:check` failed on 409 of the repo's TypeScript files, so the
gate could not be used to catch anything. This applies the existing
`.prettierrc` with no configuration changes. `src/data/language-entries.ts`
stays untouched, as `.prettierignore` requires: `check:languages` compares its
raw text, so reformatting it would report permanent drift.

Reformatting relocated four `eslint-disable-next-line` directives away from the
lines they suppressed, because rewrapping to the 80-column width split those
lines in two. That turned one into a `require-yield` error and left
`prefer-nullish-coalescing` reported 15 times against deliberate `||` uses.
Each directive is restored over the code it covers, using the block
disable/enable form where a statement now spans several lines and a
`-next-line` directive cannot reach it. `paths.ts` and `run-cli.ts` keep `||`
on purpose — an empty string is a value `??` would pass through, but which the
XDG spec and the exit-status handling both need to treat as unset.

Lint, type-check, `format:check` and all 284 suites pass; lint is back to the
zero-warning baseline it had before the reformat.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/api/admin-client.ts                       |   59 +-
 src/api/deepl-client.ts                       |   94 +-
 src/api/document-client.ts                    |   27 +-
 src/api/glossary-client.ts                    |   45 +-
 src/api/http-client.ts                        |   36 +-
 src/api/style-rules-client.ts                 |   74 +-
 src/api/translation-client.ts                 |  100 +-
 src/api/voice-client.ts                       |    3 +-
 src/api/write-client.ts                       |    8 +-
 src/cli/cache-loader.ts                       |   14 +-
 src/cli/commands/admin.ts                     |   61 +-
 src/cli/commands/auth.ts                      |   13 +-
 src/cli/commands/cache.ts                     |   16 +-
 src/cli/commands/completion.ts                |   33 +-
 src/cli/commands/config.ts                    |   45 +-
 src/cli/commands/detect.ts                    |   12 +-
 src/cli/commands/glossary.ts                  |   36 +-
 src/cli/commands/hooks.ts                     |   20 +-
 src/cli/commands/init.ts                      |    5 +-
 src/cli/commands/languages.ts                 |  127 +-
 src/cli/commands/parse-int-option.ts          |    8 +-
 src/cli/commands/register-admin.ts            |  144 +-
 src/cli/commands/register-auth.ts             |  102 +-
 src/cli/commands/register-cache.ts            |   72 +-
 src/cli/commands/register-completion.ts       |   15 +-
 src/cli/commands/register-config.ts           |   38 +-
 src/cli/commands/register-correct.ts          |   48 +-
 src/cli/commands/register-describe.ts         |   14 +-
 src/cli/commands/register-detect.ts           |   24 +-
 src/cli/commands/register-glossary.ts         |  484 ++++---
 src/cli/commands/register-hooks.ts            |   34 +-
 src/cli/commands/register-init.ts             |   29 +-
 src/cli/commands/register-languages.ts        |  239 ++--
 src/cli/commands/register-style-rules.ts      |  581 +++++---
 src/cli/commands/register-tm.ts               |   17 +-
 src/cli/commands/register-translate.ts        |  556 +++++---
 src/cli/commands/register-usage.ts            |   24 +-
 src/cli/commands/register-voice.ts            |  188 ++-
 src/cli/commands/register-watch.ts            |  260 ++--
 src/cli/commands/register-write.ts            |  151 +-
 src/cli/commands/service-factory.ts           |   93 +-
 src/cli/commands/style-rules.ts               |   82 +-
 src/cli/commands/sync-command.ts              |  233 +++-
 src/cli/commands/sync/register-sync-audit.ts  |   45 +-
 src/cli/commands/sync/register-sync-export.ts |   49 +-
 src/cli/commands/sync/register-sync-init.ts   |   59 +-
 src/cli/commands/sync/register-sync-pull.ts   |   34 +-
 src/cli/commands/sync/register-sync-push.ts   |   35 +-
 .../commands/sync/register-sync-resolve.ts    |   38 +-
 src/cli/commands/sync/register-sync-root.ts   |   69 +-
 src/cli/commands/sync/register-sync-status.ts |   29 +-
 .../commands/sync/register-sync-validate.ts   |   26 +-
 src/cli/commands/sync/sync-options.ts         |   20 +-
 src/cli/commands/tm.ts                        |    2 +-
 src/cli/commands/translate.ts                 |   23 +-
 .../directory-translation-handler.ts          |   45 +-
 .../translate/document-translation-handler.ts |   86 +-
 .../translate/file-translation-handler.ts     |   69 +-
 src/cli/commands/translate/index.ts           |   11 +-
 .../translate/text-translation-handler.ts     |  103 +-
 src/cli/commands/translate/translate-utils.ts |  112 +-
 .../translate/translation-options-factory.ts  |   22 +-
 src/cli/commands/usage.ts                     |  108 +-
 src/cli/commands/voice.ts                     |  212 ++-
 src/cli/commands/watch.ts                     |   79 +-
 src/cli/commands/write.ts                     |   94 +-
 src/cli/index.ts                              |   14 +-
 src/cli/node-version-check.ts                 |    4 +-
 src/data/language-registry.ts                 |   25 +-
 src/formats/android-xml.ts                    |  159 ++-
 src/formats/arb.ts                            |    7 +-
 src/formats/format.ts                         |    6 +-
 src/formats/index.ts                          |   11 +-
 src/formats/ios-strings.ts                    |   71 +-
 src/formats/json.ts                           |   56 +-
 src/formats/php-arrays.ts                     |   42 +-
 src/formats/po.ts                             |   53 +-
 src/formats/properties.ts                     |   57 +-
 src/formats/toml.ts                           |   40 +-
 src/formats/xcstrings.ts                      |   19 +-
 src/formats/xliff.ts                          |   68 +-
 src/formats/xml-scan.ts                       |   28 +-
 src/formats/yaml.ts                           |   44 +-
 src/services/admin.ts                         |    8 +-
 src/services/batch-translation.ts             |  131 +-
 src/services/detect.ts                        |    8 +-
 src/services/document-translation.ts          |    2 +-
 src/services/file-translation.ts              |   16 +-
 src/services/git-hooks.ts                     |  113 +-
 src/services/glossary.ts                      |  177 ++-
 src/services/languages.ts                     |    4 +-
 src/services/structured-file-translation.ts   |   27 +-
 src/services/style-rules.ts                   |   28 +-
 src/services/translation-memory.ts            |   26 +-
 src/services/translation.ts                   |  115 +-
 src/services/voice-stream-session.ts          |   81 +-
 src/services/voice.ts                         |   59 +-
 src/services/watch.ts                         |   54 +-
 src/services/write.ts                         |   17 +-
 src/storage/cache.ts                          |   60 +-
 src/storage/config.ts                         |   94 +-
 src/sync/sync-bak-cleanup.ts                  |   37 +-
 src/sync/sync-bucket-walker.ts                |   34 +-
 src/sync/sync-config.ts                       |  260 ++--
 src/sync/sync-context.ts                      |  193 ++-
 src/sync/sync-differ.ts                       |   40 +-
 src/sync/sync-export.ts                       |   25 +-
 src/sync/sync-finalize.ts                     |    4 +-
 src/sync/sync-glossary-report.ts              |  Bin 3095 -> 3150 bytes
 src/sync/sync-glossary.ts                     |   67 +-
 src/sync/sync-init-validate.ts                |   30 +-
 src/sync/sync-init.ts                         |   50 +-
 src/sync/sync-instructions.ts                 |   57 +-
 src/sync/sync-locale-translator.ts            |  383 +++--
 src/sync/sync-lock.ts                         |   73 +-
 src/sync/sync-message-preprocess.ts           |   65 +-
 src/sync/sync-process-bucket.ts               |  374 +++--
 src/sync/sync-process-lock.ts                 |   12 +-
 src/sync/sync-resolve.ts                      |   64 +-
 src/sync/sync-service.ts                      |  200 ++-
 src/sync/sync-status.ts                       |   27 +-
 src/sync/sync-tms.ts                          |   84 +-
 src/sync/sync-utils.ts                        |   38 +-
 src/sync/sync-validate.ts                     |   32 +-
 src/sync/tm-cache.ts                          |    7 +-
 src/sync/tms-client.ts                        |  136 +-
 src/sync/translation-validator.ts             |  Bin 8450 -> 8684 bytes
 src/sync/types.ts                             |    4 +-
 src/types/api.ts                              |   22 +-
 src/types/glossary.ts                         |   13 +-
 src/types/voice.ts                            |   10 +-
 src/utils/atomic-write.ts                     |   36 +-
 src/utils/errors.ts                           |   34 +-
 src/utils/exit-codes.ts                       |   12 +-
 src/utils/formality.ts                        |    5 +-
 src/utils/formatters.ts                       |   25 +-
 src/utils/glob-prefix.ts                      |   26 +-
 src/utils/glossary-params.ts                  |   20 +-
 src/utils/icu-preservation.ts                 |   28 +-
 src/utils/logger.ts                           |   28 +-
 src/utils/output-helper.ts                    |    6 +-
 src/utils/parse-size.ts                       |   20 +-
 src/utils/paths.ts                            |   11 +-
 src/utils/safe-read-file.ts                   |   23 +-
 src/utils/tag-handling-version.ts             |    2 +-
 src/utils/text-preservation.ts                |   25 +-
 src/utils/unrecoverable-request-error.ts      |    2 +-
 src/utils/validate-url.ts                     |    6 +-
 src/version.ts                                |    4 +-
 tests/e2e/cli-aliases.e2e.test.ts             |    2 +-
 tests/e2e/cli-auth.e2e.test.ts                |    5 +-
 tests/e2e/cli-cache-degraded.e2e.test.ts      |   35 +-
 tests/e2e/cli-cache.e2e.test.ts               |   12 +-
 tests/e2e/cli-config.e2e.test.ts              |    4 +-
 tests/e2e/cli-correct.e2e.test.ts             |   30 +-
 tests/e2e/cli-detect.e2e.test.ts              |    8 +-
 .../e2e/cli-document-translation.e2e.test.ts  |    8 +-
 tests/e2e/cli-file-translation.e2e.test.ts    |    7 +-
 tests/e2e/cli-http-options.e2e.test.ts        |   19 +-
 tests/e2e/cli-languages.e2e.test.ts           |   82 +-
 tests/e2e/cli-multi-glossary.e2e.test.ts      |   28 +-
 tests/e2e/cli-no-input.e2e.test.ts            |   13 +-
 tests/e2e/cli-parse-errors.e2e.test.ts        |    2 +-
 tests/e2e/cli-stdin-stdout.e2e.test.ts        |   82 +-
 tests/e2e/cli-stdout-routing.e2e.test.ts      |   33 +-
 tests/e2e/cli-structured-file.e2e.test.ts     |   63 +-
 tests/e2e/cli-success-paths.e2e.test.ts       |   71 +-
 tests/e2e/cli-sync-error-envelope.e2e.test.ts |   91 +-
 tests/e2e/cli-sync-force-guard.e2e.test.ts    |   47 +-
 tests/e2e/cli-sync-init.e2e.test.ts           |   32 +-
 tests/e2e/cli-sync-json-contract.e2e.test.ts  |   69 +-
 tests/e2e/cli-sync-option-routing.e2e.test.ts |  166 ++-
 tests/e2e/cli-sync-push-pull.e2e.test.ts      |  128 +-
 tests/e2e/cli-sync-tms.e2e.test.ts            |   80 +-
 tests/e2e/cli-sync-watch.e2e.test.ts          |   26 +-
 tests/e2e/cli-sync.e2e.test.ts                |  613 +++++---
 tests/e2e/cli-voice.e2e.test.ts               |   37 +-
 tests/e2e/cli-watch.e2e.test.ts               |   54 +-
 tests/e2e/cli-workflow.e2e.test.ts            |    2 +-
 tests/e2e/cli-write.e2e.test.ts               |   46 +-
 tests/global-setup.ts                         |    4 +-
 tests/helpers/assert-error-envelope.ts        |   63 +-
 tests/helpers/mock-factories.ts               |  320 +++--
 tests/helpers/nock-setup.ts                   |   23 +-
 tests/helpers/run-cli.ts                      |   92 +-
 tests/helpers/sync-harness.ts                 |   84 +-
 tests/helpers/tms-nock.ts                     |   27 +-
 tests/hermetic-deepl.ts                       |   15 +-
 .../admin-client.integration.test.ts          |   12 +-
 .../batch-translation.integration.test.ts     |   80 +-
 .../integration/cli-auth.integration.test.ts  |    8 +-
 .../cli-completion.integration.test.ts        |   20 +-
 .../cli-config-file.integration.test.ts       |  111 +-
 .../cli-config.integration.test.ts            |   10 +-
 .../cli-correct.integration.test.ts           |   75 +-
 .../cli-detect.integration.test.ts            |   25 +-
 ...i-document-translation.integration.test.ts |  169 +--
 .../cli-dry-run.integration.test.ts           |   63 +-
 .../cli-help-hint.integration.test.ts         |   19 +-
 .../integration/cli-hooks.integration.test.ts |    7 +-
 .../cli-languages.integration.test.ts         |    4 +-
 .../cli-lazy-cache.integration.test.ts        |   19 +-
 .../cli-no-input.integration.test.ts          |    4 +-
 ...uctured-file-translate.integration.test.ts |  162 ++-
 .../cli-style-rules.integration.test.ts       |  116 +-
 .../cli-translate.integration.test.ts         |   97 +-
 .../integration/cli-watch.integration.test.ts |  103 +-
 .../integration/cli-write.integration.test.ts |  286 ++--
 .../deepl-client.integration.test.ts          |  337 +++--
 .../deepl-glossary-v3.integration.test.ts     |  159 ++-
 .../file-translation.integration.test.ts      |   33 +-
 .../git-hooks-resolution.integration.test.ts  |   68 +-
 .../sync-auto-commit.integration.test.ts      |   96 +-
 .../sync-concurrent.integration.test.ts       |   65 +-
 ...-export-path-traversal.integration.test.ts |   34 +-
 ...nc-init-format-choices.integration.test.ts |   12 +-
 .../integration/sync-init.integration.test.ts |  112 +-
 ...translator-plural-perf.integration.test.ts |   22 +-
 .../sync-php-arrays.integration.test.ts       |   40 +-
 .../sync-properties.integration.test.ts       |   30 +-
 .../sync-scan-bounds.integration.test.ts      |   29 +-
 ...stale-lock-fg-coalesce.integration.test.ts |   84 +-
 .../sync-symlink-safety.integration.test.ts   |   64 +-
 ...te-patterns-dedup-perf.integration.test.ts |   40 +-
 .../sync-template-prep.integration.test.ts    |   27 +-
 .../sync-tms-push.integration.test.ts         |   78 +-
 .../integration/sync-tms.integration.test.ts  |   83 +-
 .../integration/sync-toml.integration.test.ts |   31 +-
 ...sync-watch-reliability.integration.test.ts |   37 +-
 .../sync-watch.integration.test.ts            |   15 +-
 .../sync-xcstrings.integration.test.ts        |   42 +-
 tests/integration/sync.integration.test.ts    | 1227 +++++++++++++----
 .../watch-auto-commit.integration.test.ts     |   39 +-
 tests/require-build.ts                        |   16 +-
 tests/setup.ts                                |    2 +-
 tests/unit/admin-client.test.ts               |   24 +-
 tests/unit/admin-command.test.ts              |   48 +-
 tests/unit/atomic-write.test.ts               |  118 +-
 tests/unit/auth-command.test.ts               |  216 ++-
 tests/unit/cache-backcompat.test.ts           |   19 +-
 tests/unit/cache-command.test.ts              |   35 +-
 tests/unit/cache-corruption-allowlist.test.ts |   20 +-
 tests/unit/cache-loader.test.ts               |   31 +-
 tests/unit/cache-native-failure.test.ts       |   34 +-
 tests/unit/cache-service.test.ts              |   90 +-
 tests/unit/cli-did-you-mean.test.ts           |   19 +-
 tests/unit/cli-no-args-exit.test.ts           |    4 +-
 tests/unit/cli-translate-workflow.test.ts     |  212 +--
 tests/unit/cli.test.ts                        |   67 +-
 tests/unit/cli/node-version-check.test.ts     |    4 +-
 .../unit/cli/register-sync-audit-lazy.test.ts |    5 +-
 .../unit/cli/register-sync-force-help.test.ts |    7 +-
 tests/unit/cli/register-sync-init.test.ts     |   73 +-
 tests/unit/cli/register-sync-root.test.ts     |   10 +-
 .../register-sync-scan-context-help.test.ts   |    5 +-
 tests/unit/cli/register-sync-tms-help.test.ts |    6 +-
 .../register-sync.commander-snapshot.test.ts  |  472 ++++---
 tests/unit/cli/sync-options.test.ts           |   17 +-
 tests/unit/completion-command.test.ts         |   65 +-
 tests/unit/concurrency-limiting.test.ts       |   64 +-
 tests/unit/concurrency.test.ts                |   17 +-
 tests/unit/config-command.test.ts             |   75 +-
 tests/unit/config-service.test.ts             |   48 +-
 tests/unit/confirm.test.ts                    |  126 +-
 tests/unit/deepl-client-document.test.ts      |    4 +-
 tests/unit/deepl-client-lazy.test.ts          |   60 +-
 tests/unit/deepl-client.test.ts               |  466 ++++---
 tests/unit/detect-command.test.ts             |   92 +-
 tests/unit/detect-service.test.ts             |    4 +-
 .../directory-translation-handler.test.ts     |  130 +-
 tests/unit/docs/documented-surface.test.ts    |   57 +-
 tests/unit/docs/sync-terminology.test.ts      |    4 +-
 tests/unit/document-client.test.ts            |   64 +-
 .../unit/document-translation-handler.test.ts |  202 ++-
 .../unit/document-translation-service.test.ts |  127 +-
 tests/unit/dry-run.test.ts                    |  118 +-
 tests/unit/error-suggestions.test.ts          |   81 +-
 tests/unit/errors.test.ts                     |    5 +-
 tests/unit/exit-codes.test.ts                 |  154 ++-
 tests/unit/file-translation-handler.test.ts   |  436 ++++--
 tests/unit/file-translation-service.test.ts   |   15 +-
 tests/unit/formats-android-cdata.test.ts      |   48 +-
 tests/unit/formats-crlf.test.ts               |   24 +-
 tests/unit/formats-roundtrip.test.ts          |   23 +-
 tests/unit/formats-toml-sections.test.ts      |   74 +-
 tests/unit/formats-xcstrings-arb.test.ts      |   58 +-
 tests/unit/formats-xliff-attributes.test.ts   |   11 +-
 tests/unit/formats/android-xml.test.ts        |   30 +-
 tests/unit/formats/arb.test.ts                |  282 ++--
 tests/unit/formats/detect-indent.test.ts      |   21 +-
 tests/unit/formats/format-registry.test.ts    |   59 +-
 tests/unit/formats/ios-strings.test.ts        |   29 +-
 tests/unit/formats/json.test.ts               |  191 ++-
 tests/unit/formats/php-arrays.test.ts         |   97 +-
 tests/unit/formats/po.test.ts                 |  167 +--
 tests/unit/formats/properties.test.ts         |   17 +-
 tests/unit/formats/toml.test.ts               |   64 +-
 tests/unit/formats/xcstrings.test.ts          |  163 ++-
 tests/unit/formats/xliff.test.ts              |   12 +-
 tests/unit/formats/xml-scan.test.ts           |   35 +-
 tests/unit/formats/yaml.test.ts               |   55 +-
 tests/unit/formatters.test.ts                 |   12 +-
 tests/unit/generate-language-registry.test.ts |  101 +-
 tests/unit/glossary-client.test.ts            |   98 +-
 tests/unit/glossary-command.test.ts           |  443 ++++--
 tests/unit/glossary-params.test.ts            |   57 +-
 tests/unit/glossary-service.test.ts           |  611 +++++---
 tests/unit/hermetic-deepl.test.ts             |    8 +-
 tests/unit/hooks-command.test.ts              |   30 +-
 tests/unit/http-client.test.ts                |   99 +-
 tests/unit/http-retry-policy.test.ts          |   94 +-
 tests/unit/icu-surrounding-text.test.ts       |    7 +-
 tests/unit/init-command.test.ts               |    9 +-
 tests/unit/language-registry.test.ts          |  210 ++-
 tests/unit/languages-command.test.ts          |  351 +++--
 tests/unit/languages-service.test.ts          |    8 +-
 tests/unit/logger.test.ts                     |   42 +-
 tests/unit/package-manifest.test.ts           |   42 +-
 tests/unit/paths.test.ts                      |   12 +-
 tests/unit/prototype-key-safety.test.ts       |  184 ++-
 tests/unit/read-stdin.test.ts                 |    9 +-
 tests/unit/register-admin.test.ts             |  196 ++-
 .../unit/register-cache-registration.test.ts  |  186 ++-
 tests/unit/register-commands-group1.test.ts   |  182 ++-
 tests/unit/register-config.test.ts            |   89 +-
 tests/unit/register-correct.test.ts           |  142 +-
 tests/unit/register-glossary.test.ts          |  534 +++++--
 tests/unit/register-hooks.test.ts             |   33 +-
 tests/unit/register-init.test.ts              |   19 +-
 tests/unit/register-languages.test.ts         |  389 ++++--
 tests/unit/register-style-rules.test.ts       |  421 +++++-
 tests/unit/register-translate.test.ts         |  187 ++-
 tests/unit/register-usage.test.ts             |   39 +-
 tests/unit/register-voice.test.ts             |  180 ++-
 tests/unit/register-write.test.ts             |  588 ++++++--
 tests/unit/resolve-endpoint.test.ts           |   30 +-
 tests/unit/retry-after-blank.test.ts          |    9 +-
 tests/unit/safe-read-file.test.ts             |   11 +-
 tests/unit/service-factory-voice.test.ts      |   25 +-
 tests/unit/services/batch-translation.test.ts |  134 +-
 tests/unit/services/git-hooks.test.ts         |  145 +-
 tests/unit/services/watch.test.ts             |   64 +-
 tests/unit/signal-exit.test.ts                |    4 +-
 tests/unit/stdin-translation-handler.test.ts  |   25 +-
 .../unit/structured-file-translation.test.ts  |  285 ++--
 tests/unit/style-rules-client.test.ts         |  313 +++--
 tests/unit/style-rules-command.test.ts        |  108 +-
 tests/unit/style-rules-service.test.ts        |   41 +-
 .../sync/icu-structure-validation.test.ts     |   42 +-
 tests/unit/sync/sync-bak-cleanup.test.ts      |   54 +-
 tests/unit/sync/sync-bucket-walker.test.ts    |   36 +-
 tests/unit/sync/sync-command.test.ts          |  521 +++++--
 .../sync-config-include-containment.test.ts   |   16 +-
 tests/unit/sync/sync-config.test.ts           | 1119 ++++++++++-----
 tests/unit/sync/sync-context.test.ts          |  272 +++-
 .../unit/sync/sync-differ-per-locale.test.ts  |   38 +-
 tests/unit/sync/sync-differ.test.ts           |   94 +-
 tests/unit/sync/sync-export.test.ts           |   16 +-
 tests/unit/sync/sync-finalize-failure.test.ts |    8 +-
 tests/unit/sync/sync-glossary-report.test.ts  |  214 ++-
 tests/unit/sync/sync-glossary.test.ts         |  353 +++--
 .../sync/sync-init-detector-table.test.ts     |  193 ++-
 tests/unit/sync/sync-init-validate.test.ts    |   68 +-
 tests/unit/sync/sync-init.test.ts             |  171 ++-
 tests/unit/sync/sync-instructions.test.ts     |   78 +-
 .../unit/sync/sync-locale-translator.test.ts  |  684 +++++++--
 tests/unit/sync/sync-lock.test.ts             |  100 +-
 .../unit/sync/sync-message-preprocess.test.ts |   43 +-
 tests/unit/sync/sync-process-bucket.test.ts   |   67 +-
 tests/unit/sync/sync-push-pull.test.ts        |  131 +-
 tests/unit/sync/sync-resolve.test.ts          |   77 +-
 tests/unit/sync/sync-service.test.ts          | 1089 ++++++++++-----
 .../sync/sync-source-as-translation.test.ts   |   95 +-
 tests/unit/sync/sync-status.test.ts           |   69 +-
 tests/unit/sync/sync-tms.test.ts              |   77 +-
 tests/unit/sync/sync-utils.test.ts            |  167 ++-
 tests/unit/sync/sync-validate.test.ts         |  101 +-
 tests/unit/sync/tms-client.test.ts            |  298 +++-
 tests/unit/sync/translation-validator.test.ts |  148 +-
 tests/unit/tag-handling-version.test.ts       |   14 +-
 tests/unit/text-preservation-loop.test.ts     |   11 +-
 tests/unit/text-preservation.test.ts          |    9 +-
 tests/unit/text-translation-handler.test.ts   |  442 ++++--
 tests/unit/tm-command.test.ts                 |   28 +-
 tests/unit/translate-command.test.ts          | 1208 +++++++++++-----
 tests/unit/translate-default-target.test.ts   |   44 +-
 tests/unit/translate-utils.test.ts            |  317 +++--
 tests/unit/translation-client.test.ts         |  161 ++-
 tests/unit/translation-memory.test.ts         |   96 +-
 .../unit/translation-options-factory.test.ts  |  224 ++-
 tests/unit/translation-service.test.ts        |  464 +++++--
 tests/unit/type-guards.test.ts                |   34 +-
 tests/unit/types/glossary-types.test.ts       |   12 +-
 .../unit/unrecoverable-request-error.test.ts  |   36 +-
 tests/unit/usage-command.test.ts              |  108 +-
 tests/unit/utils/glob-prefix.test.ts          |   40 +-
 tests/unit/utils/icu-preservation.test.ts     |  101 +-
 tests/unit/uuid.test.ts                       |   30 +-
 tests/unit/validate-url.test.ts               |   40 +-
 .../voice-command-endpoint-resolution.test.ts |    9 +-
 tests/unit/voice-command.test.ts              |  615 ++++++---
 tests/unit/voice-glossary-resolution.test.ts  |  157 ++-
 tests/unit/voice-service.test.ts              |  666 +++++----
 tests/unit/voice-stream-session.test.ts       |  648 +++++----
 tests/unit/voice-types-errors.test.ts         |    8 +-
 tests/unit/watch-command.test.ts              |  253 +++-
 tests/unit/write-client.test.ts               |  107 +-
 tests/unit/write-command.test.ts              |   94 +-
 tests/unit/write-service.test.ts              |  125 +-
 409 files changed, 29299 insertions(+), 12204 deletions(-)

diff --git a/src/api/admin-client.ts b/src/api/admin-client.ts
index bfe8550e..64852c9e 100644
--- a/src/api/admin-client.ts
+++ b/src/api/admin-client.ts
@@ -1,5 +1,10 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
-import { AdminApiKey, AdminUsageOptions, AdminUsageReport, UsageBreakdown } from '../types/index.js';
+import {
+  AdminApiKey,
+  AdminUsageOptions,
+  AdminUsageReport,
+  UsageBreakdown,
+} from '../types/index.js';
 import { AuthError } from '../utils/errors.js';
 
 export class AdminClient extends HttpClient {
@@ -15,26 +20,31 @@ export class AdminClient extends HttpClient {
   protected override handleError(
     error: unknown,
     context?: string,
-    traceId?: string,
+    traceId?: string
   ): Error {
     const result = super.handleError(error, context, traceId);
     if (result instanceof AuthError) {
       return new AuthError(
         result.message,
-        'The admin API requires an administrator API key; a valid regular API key is not sufficient. Use a key created by your DeepL account administrator.',
+        'The admin API requires an administrator API key; a valid regular API key is not sufficient. Use a key created by your DeepL account administrator.'
       );
     }
     return result;
   }
 
   async listApiKeys(): Promise<AdminApiKey[]> {
-    const response = await this.makeJsonRequest<Array<{
-      key_id: string;
-      label: string;
-      creation_time: string;
-      is_deactivated: boolean;
-      usage_limits?: { characters?: number | null; speech_to_text_milliseconds?: number | null };
-    }>>('GET', '/v2/admin/developer-keys');
+    const response = await this.makeJsonRequest<
+      Array<{
+        key_id: string;
+        label: string;
+        creation_time: string;
+        is_deactivated: boolean;
+        usage_limits?: {
+          characters?: number | null;
+          speech_to_text_milliseconds?: number | null;
+        };
+      }>
+    >('GET', '/v2/admin/developer-keys');
 
     return response.map((key) => this.normalizeApiKey(key));
   }
@@ -51,7 +61,10 @@ export class AdminClient extends HttpClient {
       label: string;
       creation_time: string;
       is_deactivated: boolean;
-      usage_limits?: { characters?: number | null; speech_to_text_milliseconds?: number | null };
+      usage_limits?: {
+        characters?: number | null;
+        speech_to_text_milliseconds?: number | null;
+      };
     }>('POST', '/v2/admin/developer-keys', body);
 
     return this.normalizeApiKey(response);
@@ -59,27 +72,31 @@ export class AdminClient extends HttpClient {
 
   async deactivateApiKey(keyId: string): Promise<void> {
     await this.makeJsonRequest<void>(
-      'PUT', '/v2/admin/developer-keys/deactivate', { key_id: keyId }
+      'PUT',
+      '/v2/admin/developer-keys/deactivate',
+      { key_id: keyId }
     );
   }
 
   async renameApiKey(keyId: string, label: string): Promise<void> {
-    await this.makeJsonRequest<void>(
-      'PUT', '/v2/admin/developer-keys/label', { key_id: keyId, label }
-    );
+    await this.makeJsonRequest<void>('PUT', '/v2/admin/developer-keys/label', {
+      key_id: keyId,
+      label,
+    });
   }
 
   async setApiKeyLimit(
     keyId: string,
     characters: number | null,
-    speechToTextMilliseconds?: number | null,
+    speechToTextMilliseconds?: number | null
   ): Promise<void> {
     const body: Record<string, unknown> = { key_id: keyId, characters };
     if (speechToTextMilliseconds !== undefined) {
       body['speech_to_text_milliseconds'] = speechToTextMilliseconds;
     }
     await this.makeJsonRequest<void>(
-      'PUT', '/v2/admin/developer-keys/limits',
+      'PUT',
+      '/v2/admin/developer-keys/limits',
       body
     );
   }
@@ -152,7 +169,10 @@ export class AdminClient extends HttpClient {
     label: string;
     creation_time: string;
     is_deactivated: boolean;
-    usage_limits?: { characters?: number | null; speech_to_text_milliseconds?: number | null };
+    usage_limits?: {
+      characters?: number | null;
+      speech_to_text_milliseconds?: number | null;
+    };
   }): AdminApiKey {
     const result: AdminApiKey = {
       keyId: key.key_id,
@@ -164,7 +184,8 @@ export class AdminClient extends HttpClient {
       result.usageLimits = {
         characters: key.usage_limits.characters,
         ...(key.usage_limits.speech_to_text_milliseconds !== undefined && {
-          speechToTextMilliseconds: key.usage_limits.speech_to_text_milliseconds,
+          speechToTextMilliseconds:
+            key.usage_limits.speech_to_text_milliseconds,
         }),
       };
     }
diff --git a/src/api/deepl-client.ts b/src/api/deepl-client.ts
index 31e77166..3496317e 100644
--- a/src/api/deepl-client.ts
+++ b/src/api/deepl-client.ts
@@ -1,5 +1,14 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
-import { TranslationClient, TranslationResult, isTranslationResult, ProductUsage, UsageInfo, LanguageInfo, LanguageFeature, LanguageFeatures } from './translation-client.js';
+import {
+  TranslationClient,
+  TranslationResult,
+  isTranslationResult,
+  ProductUsage,
+  UsageInfo,
+  LanguageInfo,
+  LanguageFeature,
+  LanguageFeatures,
+} from './translation-client.js';
 import { GlossaryClient } from './glossary-client.js';
 import { DocumentClient } from './document-client.js';
 import { WriteClient } from './write-client.js';
@@ -31,7 +40,15 @@ import {
   AdminUsageReport,
 } from '../types/index.js';
 
-export { TranslationResult, isTranslationResult, ProductUsage, UsageInfo, LanguageInfo, LanguageFeature, LanguageFeatures };
+export {
+  TranslationResult,
+  isTranslationResult,
+  ProductUsage,
+  UsageInfo,
+  LanguageInfo,
+  LanguageFeature,
+  LanguageFeatures,
+};
 
 export class DeepLClient {
   private readonly apiKey: string;
@@ -51,7 +68,10 @@ export class DeepLClient {
   }
 
   private get translationClient(): TranslationClient {
-    this._translationClient ??= new TranslationClient(this.apiKey, this.options);
+    this._translationClient ??= new TranslationClient(
+      this.apiKey,
+      this.options
+    );
     return this._translationClient;
   }
 
@@ -131,7 +151,12 @@ export class DeepLClient {
     targetLangs: Language[],
     entries: string
   ): Promise<GlossaryInfo> {
-    return this.glossaryClient.createGlossary(name, sourceLang, targetLangs, entries);
+    return this.glossaryClient.createGlossary(
+      name,
+      sourceLang,
+      targetLangs,
+      entries
+    );
   }
 
   async listGlossaries(): Promise<GlossaryInfo[]> {
@@ -151,7 +176,11 @@ export class DeepLClient {
     sourceLang: Language,
     targetLang: Language
   ): Promise<string> {
-    return this.glossaryClient.getGlossaryEntries(glossaryId, sourceLang, targetLang);
+    return this.glossaryClient.getGlossaryEntries(
+      glossaryId,
+      sourceLang,
+      targetLang
+    );
   }
 
   async updateGlossaryEntries(
@@ -160,7 +189,12 @@ export class DeepLClient {
     targetLang: Language,
     entries: string
   ): Promise<void> {
-    return this.glossaryClient.updateGlossaryEntries(glossaryId, sourceLang, targetLang, entries);
+    return this.glossaryClient.updateGlossaryEntries(
+      glossaryId,
+      sourceLang,
+      targetLang,
+      entries
+    );
   }
 
   async replaceGlossaryDictionary(
@@ -169,7 +203,12 @@ export class DeepLClient {
     targetLang: Language,
     entries: string
   ): Promise<void> {
-    return this.glossaryClient.replaceGlossaryDictionary(glossaryId, sourceLang, targetLang, entries);
+    return this.glossaryClient.replaceGlossaryDictionary(
+      glossaryId,
+      sourceLang,
+      targetLang,
+      entries
+    );
   }
 
   async updateGlossary(
@@ -196,7 +235,11 @@ export class DeepLClient {
     sourceLang: Language,
     targetLang: Language
   ): Promise<void> {
-    return this.glossaryClient.deleteGlossaryDictionary(glossaryId, sourceLang, targetLang);
+    return this.glossaryClient.deleteGlossaryDictionary(
+      glossaryId,
+      sourceLang,
+      targetLang
+    );
   }
 
   async uploadDocument(
@@ -238,11 +281,17 @@ export class DeepLClient {
     return this.styleRulesClient.createStyleRule(options);
   }
 
-  async getStyleRule(styleId: string, detailed = false): Promise<StyleRule | StyleRuleDetailed> {
+  async getStyleRule(
+    styleId: string,
+    detailed = false
+  ): Promise<StyleRule | StyleRuleDetailed> {
     return this.styleRulesClient.getStyleRule(styleId, detailed);
   }
 
-  async updateStyleRule(styleId: string, options: UpdateStyleRuleOptions): Promise<StyleRule> {
+  async updateStyleRule(
+    styleId: string,
+    options: UpdateStyleRuleOptions
+  ): Promise<StyleRule> {
     return this.styleRulesClient.updateStyleRule(styleId, options);
   }
 
@@ -250,27 +299,37 @@ export class DeepLClient {
     return this.styleRulesClient.deleteStyleRule(styleId);
   }
 
-  async replaceConfiguredRules(styleId: string, rules: ConfiguredRules): Promise<StyleRuleDetailed> {
+  async replaceConfiguredRules(
+    styleId: string,
+    rules: ConfiguredRules
+  ): Promise<StyleRuleDetailed> {
     return this.styleRulesClient.replaceConfiguredRules(styleId, rules);
   }
 
   async createCustomInstruction(
     styleId: string,
-    options: CreateCustomInstructionOptions,
+    options: CreateCustomInstructionOptions
   ): Promise<CustomInstruction> {
     return this.styleRulesClient.createCustomInstruction(styleId, options);
   }
 
-  async getCustomInstruction(styleId: string, label: string): Promise<CustomInstruction> {
+  async getCustomInstruction(
+    styleId: string,
+    label: string
+  ): Promise<CustomInstruction> {
     return this.styleRulesClient.getCustomInstruction(styleId, label);
   }
 
   async updateCustomInstruction(
     styleId: string,
     label: string,
-    options: UpdateCustomInstructionOptions,
+    options: UpdateCustomInstructionOptions
   ): Promise<CustomInstruction> {
-    return this.styleRulesClient.updateCustomInstruction(styleId, label, options);
+    return this.styleRulesClient.updateCustomInstruction(
+      styleId,
+      label,
+      options
+    );
   }
 
   async deleteCustomInstruction(styleId: string, label: string): Promise<void> {
@@ -293,7 +352,10 @@ export class DeepLClient {
     return this.adminClient.renameApiKey(keyId, label);
   }
 
-  async setApiKeyLimit(keyId: string, characters: number | null): Promise<void> {
+  async setApiKeyLimit(
+    keyId: string,
+    characters: number | null
+  ): Promise<void> {
     return this.adminClient.setApiKeyLimit(keyId, characters);
   }
 
diff --git a/src/api/document-client.ts b/src/api/document-client.ts
index 020084df..6e4bf905 100644
--- a/src/api/document-client.ts
+++ b/src/api/document-client.ts
@@ -1,5 +1,9 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
-import { DocumentTranslationOptions, DocumentHandle, DocumentStatus } from '../types/index.js';
+import {
+  DocumentTranslationOptions,
+  DocumentHandle,
+  DocumentStatus,
+} from '../types/index.js';
 import { ValidationError } from '../utils/errors.js';
 import { normalizeFormality } from '../utils/formality.js';
 import {
@@ -42,7 +46,9 @@ export class DocumentClient extends HttpClient {
     }
 
     if (!options.filename) {
-      throw new ValidationError('filename is required when uploading document as Buffer');
+      throw new ValidationError(
+        'filename is required when uploading document as Buffer'
+      );
     }
 
     const { default: FormData } = await import('form-data');
@@ -54,13 +60,22 @@ export class DocumentClient extends HttpClient {
         () => {
           const formData = new FormData();
           formData.append('file', file, options.filename);
-          formData.append('target_lang', this.normalizeLanguage(options.targetLang).toUpperCase());
+          formData.append(
+            'target_lang',
+            this.normalizeLanguage(options.targetLang).toUpperCase()
+          );
 
           if (options.sourceLang) {
-            formData.append('source_lang', this.normalizeLanguage(options.sourceLang).toUpperCase());
+            formData.append(
+              'source_lang',
+              this.normalizeLanguage(options.sourceLang).toUpperCase()
+            );
           }
           if (options.formality) {
-            formData.append('formality', normalizeFormality(options.formality, 'text'));
+            formData.append(
+              'formality',
+              normalizeFormality(options.formality, 'text')
+            );
           }
           const glossaryParams = resolveGlossaryWireParams(options);
           if (glossaryParams) {
@@ -69,7 +84,7 @@ export class DocumentClient extends HttpClient {
             } else {
               formData.append(
                 'glossary_ids',
-                encodeGlossaryIdsForMultipart(glossaryParams.glossary_ids),
+                encodeGlossaryIdsForMultipart(glossaryParams.glossary_ids)
               );
             }
           }
diff --git a/src/api/glossary-client.ts b/src/api/glossary-client.ts
index 53c7d701..2aed47b8 100644
--- a/src/api/glossary-client.ts
+++ b/src/api/glossary-client.ts
@@ -1,5 +1,11 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
-import { Language, GlossaryInfo, GlossaryLanguagePair, normalizeGlossaryInfo, GlossaryApiResponse } from '../types/index.js';
+import {
+  Language,
+  GlossaryInfo,
+  GlossaryLanguagePair,
+  normalizeGlossaryInfo,
+  GlossaryApiResponse,
+} from '../types/index.js';
 import { ValidationError } from '../utils/errors.js';
 
 interface DeepLV3GlossaryLanguageResponse {
@@ -58,7 +64,7 @@ export class GlossaryClient extends HttpClient {
       throw new ValidationError('At least one target language is required');
     }
 
-    const dictionaries = targetLangs.map(targetLang => ({
+    const dictionaries = targetLangs.map((targetLang) => ({
       source_lang: sourceLang.toUpperCase(),
       target_lang: targetLang.toUpperCase(),
       entries,
@@ -66,7 +72,8 @@ export class GlossaryClient extends HttpClient {
     }));
 
     const response = await this.makeJsonRequest<GlossaryApiResponse>(
-      'POST', '/v3/glossaries',
+      'POST',
+      '/v3/glossaries',
       { name, dictionaries }
     );
 
@@ -75,13 +82,12 @@ export class GlossaryClient extends HttpClient {
 
   async listGlossaries(): Promise<GlossaryInfo[]> {
     try {
-      const response = await this.makeRequest<{ glossaries: GlossaryApiResponse[] }>(
-        'GET',
-        '/v3/glossaries'
-      );
+      const response = await this.makeRequest<{
+        glossaries: GlossaryApiResponse[];
+      }>('GET', '/v3/glossaries');
 
       return (response.glossaries || []).map((g) =>
-        normalizeGlossaryInfo(g, { warnOnEmpty: false }),
+        normalizeGlossaryInfo(g, { warnOnEmpty: false })
       );
     } catch (error) {
       throw this.handleError(error, 'listGlossaries');
@@ -100,10 +106,7 @@ export class GlossaryClient extends HttpClient {
 
   async deleteGlossary(glossaryId: string): Promise<void> {
     this.validateGlossaryId(glossaryId);
-    await this.makeRequest<void>(
-      'DELETE',
-      `/v3/glossaries/${glossaryId}`
-    );
+    await this.makeRequest<void>('DELETE', `/v3/glossaries/${glossaryId}`);
   }
 
   async getGlossaryEntries(
@@ -143,18 +146,16 @@ export class GlossaryClient extends HttpClient {
     entries: string
   ): Promise<void> {
     this.validateGlossaryId(glossaryId);
-    await this.makeJsonRequest<void>(
-      'PATCH',
-      `/v3/glossaries/${glossaryId}`,
-      {
-        dictionaries: [{
+    await this.makeJsonRequest<void>('PATCH', `/v3/glossaries/${glossaryId}`, {
+      dictionaries: [
+        {
           source_lang: sourceLang.toUpperCase(),
           target_lang: targetLang.toUpperCase(),
           entries,
           entries_format: 'tsv',
-        }],
-      }
-    );
+        },
+      ],
+    });
   }
 
   async replaceGlossaryDictionary(
@@ -190,7 +191,9 @@ export class GlossaryClient extends HttpClient {
   ): Promise<void> {
     this.validateGlossaryId(glossaryId);
     if (!updates.name && !updates.dictionaries) {
-      throw new ValidationError('At least one of name or dictionaries must be provided');
+      throw new ValidationError(
+        'At least one of name or dictionaries must be provided'
+      );
     }
     await this.makeJsonRequest<void>(
       'PATCH',
diff --git a/src/api/http-client.ts b/src/api/http-client.ts
index 52055ff3..c4712128 100644
--- a/src/api/http-client.ts
+++ b/src/api/http-client.ts
@@ -102,7 +102,10 @@ export interface RequestPolicy {
  * and passes it straight to `sleep()`.
  */
 export function computeBackoffWithJitter(attempt: number): number {
-  const cap = Math.min(RETRY_INITIAL_DELAY_MS * 2 ** attempt, RETRY_MAX_DELAY_MS);
+  const cap = Math.min(
+    RETRY_INITIAL_DELAY_MS * 2 ** attempt,
+    RETRY_MAX_DELAY_MS
+  );
   return Math.floor(Math.random() * cap);
 }
 
@@ -158,7 +161,9 @@ export class HttpClient {
       });
   }
 
-  private static parseProxyFromEnv(targetUrl?: string): ProxyConfig | undefined {
+  private static parseProxyFromEnv(
+    targetUrl?: string
+  ): ProxyConfig | undefined {
     if (targetUrl !== undefined && HttpClient.isProxyBypassed(targetUrl)) {
       return undefined;
     }
@@ -257,8 +262,8 @@ export class HttpClient {
       if (proxyConfig.protocol === 'http' && baseURL.startsWith('https:')) {
         Logger.warn(
           `Warning: routing HTTPS traffic to ${baseURL} via HTTP proxy ${proxyConfig.host}:${proxyConfig.port}. ` +
-          `TLS is tunneled end-to-end via CONNECT, but a malicious proxy that terminates TLS would see the Authorization header. ` +
-          `Set HTTPS_PROXY to an https:// URL if possible, or unset it if the proxy isn't required.`,
+            `TLS is tunneled end-to-end via CONNECT, but a malicious proxy that terminates TLS would see the Authorization header. ` +
+            `Set HTTPS_PROXY to an https:// URL if possible, or unset it if the proxy isn't required.`
         );
       }
       axiosConfig['proxy'] = {
@@ -275,8 +280,7 @@ export class HttpClient {
   destroy(): void {
     const httpAgent = this.client.defaults?.httpAgent as http.Agent | undefined;
     const httpsAgent = this.client.defaults?.httpsAgent as
-      | https.Agent
-      | undefined;
+      https.Agent | undefined;
     httpAgent?.destroy();
     httpsAgent?.destroy();
   }
@@ -391,8 +395,7 @@ export class HttpClient {
         );
 
         const responseTraceId = response.headers?.['x-trace-id'] as
-          | string
-          | undefined;
+          string | undefined;
         if (responseTraceId) {
           this._lastTraceId = responseTraceId;
         }
@@ -404,8 +407,7 @@ export class HttpClient {
 
         if (this.isAxiosError(error)) {
           const responseTraceId = error.response?.headers?.['x-trace-id'] as
-            | string
-            | undefined;
+            string | undefined;
           if (responseTraceId) {
             traceId = responseTraceId;
             this._lastTraceId = responseTraceId;
@@ -420,8 +422,7 @@ export class HttpClient {
             // backoff with full jitter. Jitter prevents concurrent sync
             // buckets that all 429 at the same moment from forming a
             // thundering herd on the next attempt.
-            const delay =
-              retryAfterDelay ?? computeBackoffWithJitter(attempt);
+            const delay = retryAfterDelay ?? computeBackoffWithJitter(attempt);
             Logger.verbose(
               `[verbose] HTTP ${method} ${path} retry ${attempt + 1}/${maxRetries} in ${delay}ms (status 429${retryAfterDelay !== null && retryAfterDelay !== undefined ? ', Retry-After' : ', jitter backoff'})`
             );
@@ -439,7 +440,9 @@ export class HttpClient {
           this.isReplayable(method, error)
         ) {
           const delay = computeBackoffWithJitter(attempt);
-          const status = this.isAxiosError(error) ? error.response?.status : undefined;
+          const status = this.isAxiosError(error)
+            ? error.response?.status
+            : undefined;
           Logger.verbose(
             `[verbose] HTTP ${method} ${path} retry ${attempt + 1}/${maxRetries} in ${delay}ms (${status ? `status ${status}` : 'network error'}, jitter backoff)`
           );
@@ -500,15 +503,16 @@ export class HttpClient {
     if (this.isAxiosError(error)) {
       const status = error.response?.status;
       const responseData = error.response?.data as
-        | { message?: string }
-        | undefined;
+        { message?: string } | undefined;
       // Sanitize the server-returned message before any interpolation into
       // user-facing error strings. Defense-in-depth against a malicious or
       // buggy server scribbling ANSI escape codes / control chars on the
       // user's terminal, matching the sanitization in tms-client.ts.
       // Coalesce to '' before sanitizing — some axios error shapes have no
       // `.message` field, and sanitizeForTerminal expects a string.
-      const message = sanitizeForTerminal(responseData?.message ?? error.message ?? '');
+      const message = sanitizeForTerminal(
+        responseData?.message ?? error.message ?? ''
+      );
 
       switch (status) {
         case 401:
diff --git a/src/api/style-rules-client.ts b/src/api/style-rules-client.ts
index 11e9f8f3..571e5569 100644
--- a/src/api/style-rules-client.ts
+++ b/src/api/style-rules-client.ts
@@ -19,12 +19,16 @@ interface CustomInstructionWireShape {
   source_language?: string;
 }
 
-function mapCustomInstruction(wire: CustomInstructionWireShape): CustomInstruction {
+function mapCustomInstruction(
+  wire: CustomInstructionWireShape
+): CustomInstruction {
   return {
     ...(wire.id !== undefined && { id: wire.id }),
     label: wire.label,
     prompt: wire.prompt,
-    ...(wire.source_language !== undefined && { sourceLanguage: wire.source_language }),
+    ...(wire.source_language !== undefined && {
+      sourceLanguage: wire.source_language,
+    }),
   };
 }
 
@@ -54,7 +58,9 @@ function mapStyleRuleDetailed(wire: StyleRuleWireShape): StyleRuleDetailed {
   return {
     ...mapStyleRule(wire),
     configuredRules: wire.configured_rules ?? {},
-    customInstructions: (wire.custom_instructions ?? []).map(mapCustomInstruction),
+    customInstructions: (wire.custom_instructions ?? []).map(
+      mapCustomInstruction
+    ),
   };
 }
 
@@ -85,7 +91,7 @@ export class StyleRulesClient extends HttpClient {
     }>('GET', '/v3/style_rules', params);
 
     return response.style_rules.map((rule) =>
-      options.detailed ? mapStyleRuleDetailed(rule) : mapStyleRule(rule),
+      options.detailed ? mapStyleRuleDetailed(rule) : mapStyleRule(rule)
     );
   }
 
@@ -98,7 +104,7 @@ export class StyleRulesClient extends HttpClient {
       body['configured_rules'] = options.configuredRules;
     }
     if (options.customInstructions !== undefined) {
-      body['custom_instructions'] = options.customInstructions.map(ci => ({
+      body['custom_instructions'] = options.customInstructions.map((ci) => ({
         label: ci.label,
         prompt: ci.prompt,
         ...(ci.sourceLanguage && { source_language: ci.sourceLanguage }),
@@ -107,12 +113,15 @@ export class StyleRulesClient extends HttpClient {
     const wire = await this.makeJsonRequest<StyleRuleWireShape>(
       'POST',
       '/v3/style_rules',
-      body,
+      body
     );
     return mapStyleRule(wire);
   }
 
-  async getStyleRule(styleId: string, detailed = false): Promise<StyleRule | StyleRuleDetailed> {
+  async getStyleRule(
+    styleId: string,
+    detailed = false
+  ): Promise<StyleRule | StyleRuleDetailed> {
     const params: Record<string, string | number | boolean> = {};
     if (detailed) {
       params['detailed'] = true;
@@ -121,12 +130,15 @@ export class StyleRulesClient extends HttpClient {
       'GET',
       `/v3/style_rules/${encodeURIComponent(styleId)}`,
       undefined,
-      params,
+      params
     );
     return detailed ? mapStyleRuleDetailed(wire) : mapStyleRule(wire);
   }
 
-  async updateStyleRule(styleId: string, options: UpdateStyleRuleOptions): Promise<StyleRule> {
+  async updateStyleRule(
+    styleId: string,
+    options: UpdateStyleRuleOptions
+  ): Promise<StyleRule> {
     const body: Record<string, unknown> = {};
     if (options.name !== undefined) {
       body['name'] = options.name;
@@ -135,7 +147,7 @@ export class StyleRulesClient extends HttpClient {
       body['configured_rules'] = options.configuredRules;
     }
     if (options.customInstructions !== undefined) {
-      body['custom_instructions'] = options.customInstructions.map(ci => ({
+      body['custom_instructions'] = options.customInstructions.map((ci) => ({
         label: ci.label,
         prompt: ci.prompt,
         ...(ci.sourceLanguage && { source_language: ci.sourceLanguage }),
@@ -144,7 +156,7 @@ export class StyleRulesClient extends HttpClient {
     const wire = await this.makeJsonRequest<StyleRuleWireShape>(
       'PATCH',
       `/v3/style_rules/${encodeURIComponent(styleId)}`,
-      body,
+      body
     );
     return mapStyleRule(wire);
   }
@@ -152,25 +164,28 @@ export class StyleRulesClient extends HttpClient {
   async deleteStyleRule(styleId: string): Promise<void> {
     await this.makeJsonRequest<void>(
       'DELETE',
-      `/v3/style_rules/${encodeURIComponent(styleId)}`,
+      `/v3/style_rules/${encodeURIComponent(styleId)}`
     );
   }
 
-  async replaceConfiguredRules(styleId: string, rules: ConfiguredRules): Promise<StyleRuleDetailed> {
+  async replaceConfiguredRules(
+    styleId: string,
+    rules: ConfiguredRules
+  ): Promise<StyleRuleDetailed> {
     // The PUT endpoint at /configured_rules takes the rules dict as the entire body
     // (no `configured_rules` outer wrapper). The wrapper is only used on POST /v3/style_rules
     // and PATCH /v3/style_rules/{id} where the body has multiple top-level fields.
     const wire = await this.makeJsonRequest<StyleRuleWireShape>(
       'PUT',
       `/v3/style_rules/${encodeURIComponent(styleId)}/configured_rules`,
-      rules,
+      rules
     );
     return mapStyleRuleDetailed(wire);
   }
 
   async createCustomInstruction(
     styleId: string,
-    options: CreateCustomInstructionOptions,
+    options: CreateCustomInstructionOptions
   ): Promise<CustomInstruction> {
     const body: Record<string, unknown> = {
       label: options.label,
@@ -182,7 +197,7 @@ export class StyleRulesClient extends HttpClient {
     const wire = await this.makeJsonRequest<CustomInstructionWireShape>(
       'POST',
       `/v3/style_rules/${encodeURIComponent(styleId)}/custom_instructions`,
-      body,
+      body
     );
     return mapCustomInstruction(wire);
   }
@@ -194,22 +209,31 @@ export class StyleRulesClient extends HttpClient {
    * instructions by label. This helper does the lookup via a detailed
    * `getStyleRule`. Throws ValidationError if no instruction with that label exists.
    */
-  private async resolveInstructionId(styleId: string, label: string): Promise<string> {
-    const detailed = await this.getStyleRule(styleId, true) as StyleRuleDetailed;
-    const found = detailed.customInstructions.find(ci => ci.label === label);
+  private async resolveInstructionId(
+    styleId: string,
+    label: string
+  ): Promise<string> {
+    const detailed = (await this.getStyleRule(
+      styleId,
+      true
+    )) as StyleRuleDetailed;
+    const found = detailed.customInstructions.find((ci) => ci.label === label);
     if (!found?.id) {
       throw new ValidationError(
-        `No custom instruction with label "${label}" found on style rule ${styleId}.`,
+        `No custom instruction with label "${label}" found on style rule ${styleId}.`
       );
     }
     return found.id;
   }
 
-  async getCustomInstruction(styleId: string, label: string): Promise<CustomInstruction> {
+  async getCustomInstruction(
+    styleId: string,
+    label: string
+  ): Promise<CustomInstruction> {
     const instructionId = await this.resolveInstructionId(styleId, label);
     const wire = await this.makeJsonRequest<CustomInstructionWireShape>(
       'GET',
-      `/v3/style_rules/${encodeURIComponent(styleId)}/custom_instructions/${encodeURIComponent(instructionId)}`,
+      `/v3/style_rules/${encodeURIComponent(styleId)}/custom_instructions/${encodeURIComponent(instructionId)}`
     );
     return mapCustomInstruction(wire);
   }
@@ -217,7 +241,7 @@ export class StyleRulesClient extends HttpClient {
   async updateCustomInstruction(
     styleId: string,
     label: string,
-    options: UpdateCustomInstructionOptions,
+    options: UpdateCustomInstructionOptions
   ): Promise<CustomInstruction> {
     const instructionId = await this.resolveInstructionId(styleId, label);
     // The PUT body requires `label` even though `instruction_id` appears in the URL path.
@@ -231,7 +255,7 @@ export class StyleRulesClient extends HttpClient {
     const wire = await this.makeJsonRequest<CustomInstructionWireShape>(
       'PUT',
       `/v3/style_rules/${encodeURIComponent(styleId)}/custom_instructions/${encodeURIComponent(instructionId)}`,
-      body,
+      body
     );
     return mapCustomInstruction(wire);
   }
@@ -240,7 +264,7 @@ export class StyleRulesClient extends HttpClient {
     const instructionId = await this.resolveInstructionId(styleId, label);
     await this.makeJsonRequest<void>(
       'DELETE',
-      `/v3/style_rules/${encodeURIComponent(styleId)}/custom_instructions/${encodeURIComponent(instructionId)}`,
+      `/v3/style_rules/${encodeURIComponent(styleId)}/custom_instructions/${encodeURIComponent(instructionId)}`
     );
   }
 }
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index f229009e..c4150d93 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -1,5 +1,9 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
-import { TranslationOptions, Language, TranslationMemory } from '../types/index.js';
+import {
+  TranslationOptions,
+  Language,
+  TranslationMemory,
+} from '../types/index.js';
 import { NetworkError } from '../utils/errors.js';
 import { normalizeFormality } from '../utils/formality.js';
 import { resolveGlossaryWireParams } from '../utils/glossary-params.js';
@@ -137,12 +141,16 @@ export class TranslationClient extends HttpClient {
       );
 
       if (!response.translations || response.translations.length === 0) {
-        throw new NetworkError(`No translation returned from DeepL API. Request: translate text (${text.length} chars) to ${options.targetLang}`);
+        throw new NetworkError(
+          `No translation returned from DeepL API. Request: translate text (${text.length} chars) to ${options.targetLang}`
+        );
       }
 
       const translation = response.translations[0];
       if (!translation) {
-        throw new NetworkError(`Empty translation in API response. Request: translate text (${text.length} chars) to ${options.targetLang}`);
+        throw new NetworkError(
+          `Empty translation in API response. Request: translate text (${text.length} chars) to ${options.targetLang}`
+        );
       }
 
       return {
@@ -150,7 +158,8 @@ export class TranslationClient extends HttpClient {
         detectedSourceLang: translation.detected_source_language
           ? this.normalizeLanguage(translation.detected_source_language)
           : undefined,
-        billedCharacters: translation.billed_characters ?? response.billed_characters,
+        billedCharacters:
+          translation.billed_characters ?? response.billed_characters,
         modelTypeUsed: translation.model_type_used,
       };
     } catch (error) {
@@ -176,11 +185,15 @@ export class TranslationClient extends HttpClient {
       );
 
       if (!response.translations) {
-        throw new NetworkError('Unexpected API response. Please retry your translation. If the issue persists, report it at https://github.com/DeepL/deepl-cli/issues');
+        throw new NetworkError(
+          'Unexpected API response. Please retry your translation. If the issue persists, report it at https://github.com/DeepL/deepl-cli/issues'
+        );
       }
 
       if (response.translations.length !== texts.length) {
-        throw new NetworkError('Unexpected API response. Please retry your translation. If the issue persists, report it at https://github.com/DeepL/deepl-cli/issues');
+        throw new NetworkError(
+          'Unexpected API response. Please retry your translation. If the issue persists, report it at https://github.com/DeepL/deepl-cli/issues'
+        );
       }
 
       return response.translations.map((translation) => ({
@@ -188,7 +201,8 @@ export class TranslationClient extends HttpClient {
         detectedSourceLang: translation.detected_source_language
           ? this.normalizeLanguage(translation.detected_source_language)
           : undefined,
-        billedCharacters: translation.billed_characters ?? response.billed_characters,
+        billedCharacters:
+          translation.billed_characters ?? response.billed_characters,
         modelTypeUsed: translation.model_type_used,
       }));
     } catch (error) {
@@ -233,13 +247,17 @@ export class TranslationClient extends HttpClient {
         usage.accountUnitLimit = response.account_unit_limit;
       }
       if (response.products) {
-        usage.products = response.products.map(p => ({
+        usage.products = response.products.map((p) => ({
           productType: p.product_type,
           characterCount: p.character_count,
           apiKeyCharacterCount: p.api_key_character_count,
           ...(p.unit_count !== undefined && { unitCount: p.unit_count }),
-          ...(p.account_unit_count !== undefined && { accountUnitCount: p.account_unit_count }),
-          ...(p.api_key_unit_count !== undefined && { apiKeyUnitCount: p.api_key_unit_count }),
+          ...(p.account_unit_count !== undefined && {
+            accountUnitCount: p.account_unit_count,
+          }),
+          ...(p.api_key_unit_count !== undefined && {
+            apiKeyUnitCount: p.api_key_unit_count,
+          }),
           ...(p.billing_unit && { billingUnit: p.billing_unit }),
         }));
       }
@@ -257,7 +275,9 @@ export class TranslationClient extends HttpClient {
         total_count?: number;
       }>('GET', '/v3/translation_memories');
 
-      const aggregated: TranslationMemory[] = [...(first.translation_memories ?? [])];
+      const aggregated: TranslationMemory[] = [
+        ...(first.translation_memories ?? []),
+      ];
       const total = first.total_count;
       if (typeof total !== 'number' || aggregated.length >= total) {
         return aggregated;
@@ -321,27 +341,31 @@ export class TranslationClient extends HttpClient {
     try {
       const response = await this.fetchTranslateLanguages();
 
-      return response
-        // `!== false`, not truthiness: an absent flag is not a denial, and the
-        // language registry reads it the same way, so a truthy filter here would
-        // drop a language the generator records as usable.
-        .filter((lang) =>
-          type === 'source' ? lang.usable_as_source !== false : lang.usable_as_target !== false,
-        )
-        .map((lang) => {
-          const code = this.normalizeLanguage(lang.lang);
-          return {
-            language: code,
-            name: lang.name,
-            // Only claimed when the response described this language's features;
-            // silence about a language is not evidence that formality is absent.
-            ...(type === 'target' &&
-              lang.features && {
-                supportsFormality: lang.features['formality'] !== undefined,
-              }),
-            ...(lang.features && { features: lang.features }),
-          };
-        });
+      return (
+        response
+          // `!== false`, not truthiness: an absent flag is not a denial, and the
+          // language registry reads it the same way, so a truthy filter here would
+          // drop a language the generator records as usable.
+          .filter((lang) =>
+            type === 'source'
+              ? lang.usable_as_source !== false
+              : lang.usable_as_target !== false
+          )
+          .map((lang) => {
+            const code = this.normalizeLanguage(lang.lang);
+            return {
+              language: code,
+              name: lang.name,
+              // Only claimed when the response described this language's features;
+              // silence about a language is not evidence that formality is absent.
+              ...(type === 'target' &&
+                lang.features && {
+                  supportsFormality: lang.features['formality'] !== undefined,
+                }),
+              ...(lang.features && { features: lang.features }),
+            };
+          })
+      );
     } catch (error) {
       throw this.handleError(error);
     }
@@ -357,7 +381,9 @@ export class TranslationClient extends HttpClient {
     };
 
     if (options.sourceLang) {
-      params['source_lang'] = this.normalizeLanguage(options.sourceLang).toUpperCase();
+      params['source_lang'] = this.normalizeLanguage(
+        options.sourceLang
+      ).toUpperCase();
     }
 
     if (options.formality) {
@@ -371,7 +397,9 @@ export class TranslationClient extends HttpClient {
 
     if (options.translationMemoryId) {
       params['translation_memory_id'] = options.translationMemoryId;
-      params['translation_memory_threshold'] = String(options.translationMemoryThreshold ?? 75);
+      params['translation_memory_threshold'] = String(
+        options.translationMemoryThreshold ?? 75
+      );
     }
 
     if (options.preserveFormatting) {
@@ -384,7 +412,8 @@ export class TranslationClient extends HttpClient {
 
     if (options.splitSentences) {
       const splitMap: Record<string, string> = { on: '1', off: '0' };
-      params['split_sentences'] = splitMap[options.splitSentences] ?? options.splitSentences;
+      params['split_sentences'] =
+        splitMap[options.splitSentences] ?? options.splitSentences;
     }
 
     if (options.tagHandling) {
@@ -428,7 +457,6 @@ export class TranslationClient extends HttpClient {
       params['tag_handling_version'] = tagHandlingVersion;
     }
 
-
     return params;
   }
 }
diff --git a/src/api/voice-client.ts b/src/api/voice-client.ts
index d19600e1..dd3b789a 100644
--- a/src/api/voice-client.ts
+++ b/src/api/voice-client.ts
@@ -165,8 +165,7 @@ export class VoiceClient extends HttpClient {
     if (this.isAxiosError(error)) {
       const status = error.response?.status;
       const responseData = error.response?.data as
-        | { message?: string }
-        | undefined;
+        { message?: string } | undefined;
 
       if (status === 403) {
         return new VoiceError(
diff --git a/src/api/write-client.ts b/src/api/write-client.ts
index 43892fad..393ac511 100644
--- a/src/api/write-client.ts
+++ b/src/api/write-client.ts
@@ -1,5 +1,9 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
-import { WriteOptions, CorrectOptions, WriteImprovement } from '../types/index.js';
+import {
+  WriteOptions,
+  CorrectOptions,
+  WriteImprovement,
+} from '../types/index.js';
 import { NetworkError, ValidationError } from '../utils/errors.js';
 
 interface DeepLWriteResponse {
@@ -87,7 +91,7 @@ export class WriteClient extends HttpClient {
       throw new NetworkError('No improvements returned');
     }
 
-    return response.improvements.map(improvement => ({
+    return response.improvements.map((improvement) => ({
       text: improvement.text,
       targetLanguage: improvement.target_language,
       detectedSourceLanguage: improvement.detected_source_language,
diff --git a/src/cli/cache-loader.ts b/src/cli/cache-loader.ts
index 3dbbf7c9..3e8a2dd4 100644
--- a/src/cli/cache-loader.ts
+++ b/src/cli/cache-loader.ts
@@ -19,7 +19,10 @@ type CacheModule = Pick<typeof import('../storage/cache.js'), 'CacheService'>;
  * here is what keeps the service's in-memory flag from diverging from config:
  * `cache stats` and the translation path then agree on the same value.
  */
-export function resolveCacheOptions(config: ConfigService, dbPath: string): CacheServiceOptions {
+export function resolveCacheOptions(
+  config: ConfigService,
+  dbPath: string
+): CacheServiceOptions {
   const ttlSeconds = config.getValue<number>('cache.ttl');
   return {
     dbPath,
@@ -32,7 +35,8 @@ export function resolveCacheOptions(config: ConfigService, dbPath: string): Cach
 
 export function createCacheServiceGetter(
   getOptions: () => CacheServiceOptions,
-  importCacheModule: () => Promise<CacheModule> = () => import('../storage/cache.js'),
+  importCacheModule: () => Promise<CacheModule> = () =>
+    import('../storage/cache.js')
 ): () => Promise<CacheService | undefined> {
   let instance: CacheService | undefined;
   let unavailable = false;
@@ -50,12 +54,12 @@ export function createCacheServiceGetter(
       if (isNativeModuleLoadError(error)) {
         Logger.warn(
           `Translation cache backend failed to load (${detail}). ` +
-          'Your cache database has not been modified. Caching is disabled for this run. ' +
-          'Reinstall the CLI, or run it with the Node.js version it was installed with, to restore caching.',
+            'Your cache database has not been modified. Caching is disabled for this run. ' +
+            'Reinstall the CLI, or run it with the Node.js version it was installed with, to restore caching.'
         );
       } else {
         Logger.warn(
-          `Translation cache is unavailable (${detail}). Caching is disabled for this run.`,
+          `Translation cache is unavailable (${detail}). Caching is disabled for this run.`
         );
       }
     }
diff --git a/src/cli/commands/admin.ts b/src/cli/commands/admin.ts
index 0a3bb3e3..e9fc14f7 100644
--- a/src/cli/commands/admin.ts
+++ b/src/cli/commands/admin.ts
@@ -4,7 +4,12 @@
  */
 
 import type { AdminService } from '../../services/admin.js';
-import { AdminApiKey, AdminUsageOptions, AdminUsageReport, UsageBreakdown } from '../../types/index.js';
+import {
+  AdminApiKey,
+  AdminUsageOptions,
+  AdminUsageReport,
+  UsageBreakdown,
+} from '../../types/index.js';
 
 /**
  * Manages DeepL admin API operations for team accounts.
@@ -42,7 +47,11 @@ export class AdminCommand {
    * @param characters - Maximum characters allowed, or null for unlimited.
    * @param sttLimit - Optional speech-to-text milliseconds limit.
    */
-  async setKeyLimit(keyId: string, characters: number | null, sttLimit?: number | null): Promise<void> {
+  async setKeyLimit(
+    keyId: string,
+    characters: number | null,
+    sttLimit?: number | null
+  ): Promise<void> {
     return this.service.setApiKeyLimit(keyId, characters, sttLimit);
   }
 
@@ -69,15 +78,17 @@ export class AdminCommand {
       lines.push(`    ID:      ${key.keyId}`);
       lines.push(`    Created: ${key.creationTime}`);
       if (key.usageLimits?.characters !== undefined) {
-        const limit = key.usageLimits.characters === null
-          ? 'unlimited'
-          : key.usageLimits.characters.toLocaleString();
+        const limit =
+          key.usageLimits.characters === null
+            ? 'unlimited'
+            : key.usageLimits.characters.toLocaleString();
         lines.push(`    Limit:   ${limit} characters`);
       }
       if (key.usageLimits?.speechToTextMilliseconds !== undefined) {
-        const sttLimit = key.usageLimits.speechToTextMilliseconds === null
-          ? 'unlimited'
-          : this.formatMilliseconds(key.usageLimits.speechToTextMilliseconds);
+        const sttLimit =
+          key.usageLimits.speechToTextMilliseconds === null
+            ? 'unlimited'
+            : this.formatMilliseconds(key.usageLimits.speechToTextMilliseconds);
         lines.push(`    STT Limit: ${sttLimit}`);
       }
       lines.push('');
@@ -98,15 +109,17 @@ export class AdminCommand {
     lines.push(`  Status:  ${status}`);
     lines.push(`  Created: ${key.creationTime}`);
     if (key.usageLimits?.characters !== undefined) {
-      const limit = key.usageLimits.characters === null
-        ? 'unlimited'
-        : key.usageLimits.characters.toLocaleString();
+      const limit =
+        key.usageLimits.characters === null
+          ? 'unlimited'
+          : key.usageLimits.characters.toLocaleString();
       lines.push(`  Limit:   ${limit} characters`);
     }
     if (key.usageLimits?.speechToTextMilliseconds !== undefined) {
-      const sttLimit = key.usageLimits.speechToTextMilliseconds === null
-        ? 'unlimited'
-        : this.formatMilliseconds(key.usageLimits.speechToTextMilliseconds);
+      const sttLimit =
+        key.usageLimits.speechToTextMilliseconds === null
+          ? 'unlimited'
+          : this.formatMilliseconds(key.usageLimits.speechToTextMilliseconds);
       lines.push(`  STT Limit: ${sttLimit}`);
     }
     return lines.join('\n');
@@ -115,11 +128,21 @@ export class AdminCommand {
   /** Format a per-product usage breakdown (translation, documents, write, voice). */
   private formatBreakdown(usage: UsageBreakdown, indent = '  '): string[] {
     const lines: string[] = [];
-    lines.push(`${indent}Total:       ${usage.totalCharacters.toLocaleString()}`);
-    lines.push(`${indent}Translation: ${usage.textTranslationCharacters.toLocaleString()}`);
-    lines.push(`${indent}Documents:   ${usage.documentTranslationCharacters.toLocaleString()}`);
-    lines.push(`${indent}Write:       ${usage.textImprovementCharacters.toLocaleString()}`);
-    lines.push(`${indent}Voice:       ${this.formatMilliseconds(usage.speechToTextMilliseconds)}`);
+    lines.push(
+      `${indent}Total:       ${usage.totalCharacters.toLocaleString()}`
+    );
+    lines.push(
+      `${indent}Translation: ${usage.textTranslationCharacters.toLocaleString()}`
+    );
+    lines.push(
+      `${indent}Documents:   ${usage.documentTranslationCharacters.toLocaleString()}`
+    );
+    lines.push(
+      `${indent}Write:       ${usage.textImprovementCharacters.toLocaleString()}`
+    );
+    lines.push(
+      `${indent}Voice:       ${this.formatMilliseconds(usage.speechToTextMilliseconds)}`
+    );
     return lines;
   }
 
diff --git a/src/cli/commands/auth.ts b/src/cli/commands/auth.ts
index 3ab3e65e..90337113 100644
--- a/src/cli/commands/auth.ts
+++ b/src/cli/commands/auth.ts
@@ -6,7 +6,11 @@
 import { ConfigService } from '../../storage/config.js';
 import { DeepLClient } from '../../api/deepl-client.js';
 import type { DeepLClientOptions } from '../../api/http-client.js';
-import { ValidationError, AuthError, NetworkError } from '../../utils/errors.js';
+import {
+  ValidationError,
+  AuthError,
+  NetworkError,
+} from '../../utils/errors.js';
 import { resolveEndpoint } from '../../utils/resolve-endpoint.js';
 
 export class AuthCommand {
@@ -21,7 +25,10 @@ export class AuthCommand {
   /**
    * Set API key and validate it
    */
-  async setKey(apiKey: string, options: { verify?: boolean } = {}): Promise<void> {
+  async setKey(
+    apiKey: string,
+    options: { verify?: boolean } = {}
+  ): Promise<void> {
     // Validate input
     if (!apiKey || apiKey.trim() === '') {
       throw new ValidationError('API key cannot be empty');
@@ -55,7 +62,7 @@ export class AuthCommand {
         if (error instanceof NetworkError) {
           throw new NetworkError(
             `Could not reach the DeepL API to validate the key: ${error.message}`,
-            'Store the key without validating with --no-verify, or set DEEPL_API_KEY in your environment instead.',
+            'Store the key without validating with --no-verify, or set DEEPL_API_KEY in your environment instead.'
           );
         }
         throw error;
diff --git a/src/cli/commands/cache.ts b/src/cli/commands/cache.ts
index d8567e8a..28ddfb77 100644
--- a/src/cli/commands/cache.ts
+++ b/src/cli/commands/cache.ts
@@ -67,9 +67,10 @@ export class CacheCommand {
     const totalSizeMB = (stats.totalSize / (1024 * 1024)).toFixed(2);
     const maxSizeMB = (stats.maxSize / (1024 * 1024)).toFixed(2);
     const status = stats.enabled ? 'enabled' : 'disabled';
-    const percentUsed = stats.maxSize > 0
-      ? ((stats.totalSize / stats.maxSize) * 100).toFixed(1)
-      : '0.0';
+    const percentUsed =
+      stats.maxSize > 0
+        ? ((stats.totalSize / stats.maxSize) * 100).toFixed(1)
+        : '0.0';
 
     return [
       `Cache Status: ${status}`,
@@ -82,9 +83,10 @@ export class CacheCommand {
   formatStatsTable(stats: CacheStats): string {
     const totalSizeMB = (stats.totalSize / (1024 * 1024)).toFixed(2);
     const maxSizeMB = (stats.maxSize / (1024 * 1024)).toFixed(2);
-    const percentUsed = stats.maxSize > 0
-      ? ((stats.totalSize / stats.maxSize) * 100).toFixed(1)
-      : '0.0';
+    const percentUsed =
+      stats.maxSize > 0
+        ? ((stats.totalSize / stats.maxSize) * 100).toFixed(1)
+        : '0.0';
     const colorDisabled = !isColorEnabled();
 
     const table = new Table({
@@ -99,7 +101,7 @@ export class CacheCommand {
       ['Entries', String(stats.entries)],
       ['Used', `${totalSizeMB} MB`],
       ['Limit', `${maxSizeMB} MB`],
-      ['Usage', `${percentUsed}%`],
+      ['Usage', `${percentUsed}%`]
     );
 
     return table.toString();
diff --git a/src/cli/commands/completion.ts b/src/cli/commands/completion.ts
index 521e6bc7..3a43538e 100644
--- a/src/cli/commands/completion.ts
+++ b/src/cli/commands/completion.ts
@@ -42,7 +42,9 @@ export class CompletionCommand {
   }
 
   private findCommand(name: string): Command | undefined {
-    return this.program.commands.find((c) => c.name() === name || c.aliases().includes(name));
+    return this.program.commands.find(
+      (c) => c.name() === name || c.aliases().includes(name)
+    );
   }
 
   private getCommandOptions(cmdName: string): string[] {
@@ -59,7 +61,7 @@ export class CompletionCommand {
         this.program.options
           .map((opt) => opt.long)
           .filter((o): o is string => !!o)
-          .concat('--help', '--version'),
+          .concat('--help', '--version')
       ),
     ];
   }
@@ -76,7 +78,9 @@ export class CompletionCommand {
       }
       const cmdOpts = this.getCommandOptions(parent);
       const words = [...subs, ...cmdOpts].join(' ');
-      subcommandCases.push(`        ${parent})\n            COMPREPLY=($(compgen -W "${words}" -- "\${cur}"))\n            return 0\n            ;;`);
+      subcommandCases.push(
+        `        ${parent})\n            COMPREPLY=($(compgen -W "${words}" -- "\${cur}"))\n            return 0\n            ;;`
+      );
     }
 
     const topLevelWords = [...topLevel, ...globalOpts].join(' ');
@@ -153,7 +157,9 @@ complete -F _deepl_completions deepl
     _describe -t ${safeName}-commands '${parent} subcommand' subcmds
 }`);
 
-      subcommandDispatch.push(`        ${parent})\n            _deepl_${safeName}\n            ;;`);
+      subcommandDispatch.push(
+        `        ${parent})\n            _deepl_${safeName}\n            ;;`
+      );
     }
 
     const topLevelDescriptions: string[] = [];
@@ -232,7 +238,9 @@ _deepl "$@"
     for (const cmdName of topLevel) {
       const cmd = this.findCommand(cmdName);
       const desc = cmd ? cmd.description() : '';
-      lines.push(`complete -c deepl -n '${noSubcmdCondition}' -a '${cmdName}' -d '${desc.replace(/'/g, "\\'")}'`);
+      lines.push(
+        `complete -c deepl -n '${noSubcmdCondition}' -a '${cmdName}' -d '${desc.replace(/'/g, "\\'")}'`
+      );
     }
 
     for (const opt of globalOpts) {
@@ -257,15 +265,18 @@ _deepl "$@"
       }
       const parentCmd = this.findCommand(parent);
       const seenCondition = `__fish_seen_subcommand_from ${parent}`;
-      const notSeenSub = subs.length > 0
-        ? `; and not __fish_seen_subcommand_from ${subs.join(' ')}`
-        : '';
+      const notSeenSub =
+        subs.length > 0
+          ? `; and not __fish_seen_subcommand_from ${subs.join(' ')}`
+          : '';
 
       lines.push(`# ${parent} subcommands`);
       if (parentCmd) {
         for (const sub of this.visibleCommands(parentCmd)) {
           const desc = sub.description().replace(/'/g, "\\'");
-          lines.push(`complete -c deepl -n '${seenCondition}${notSeenSub}' -a '${sub.name()}' -d '${desc}'`);
+          lines.push(
+            `complete -c deepl -n '${seenCondition}${notSeenSub}' -a '${sub.name()}' -d '${desc}'`
+          );
         }
       }
 
@@ -274,7 +285,9 @@ _deepl "$@"
         const optObj = parentCmd?.options.find((o) => o.long === opt);
         const desc = optObj ? optObj.description.replace(/'/g, "\\'") : '';
         const longFlag = opt.replace(/^--/, '');
-        lines.push(`complete -c deepl -n '${seenCondition}' -l '${longFlag}' -d '${desc}'`);
+        lines.push(
+          `complete -c deepl -n '${seenCondition}' -l '${longFlag}' -d '${desc}'`
+        );
       }
       lines.push('');
     }
diff --git a/src/cli/commands/config.ts b/src/cli/commands/config.ts
index 570fc39d..345ae9cf 100644
--- a/src/cli/commands/config.ts
+++ b/src/cli/commands/config.ts
@@ -14,11 +14,7 @@ const BOOLEAN_KEYS = [
   'defaults.preserveFormatting',
 ];
 
-const NUMERIC_KEYS = [
-  'cache.maxSize',
-  'cache.ttl',
-  'watch.debounceMs',
-];
+const NUMERIC_KEYS = ['cache.maxSize', 'cache.ttl', 'watch.debounceMs'];
 
 export class ConfigCommand {
   private config: ConfigService;
@@ -33,8 +29,14 @@ export class ConfigCommand {
   async get(key?: string): Promise<unknown> {
     if (key) {
       const value = this.config.getValue(key);
-      if (key === 'auth.apiKey' && typeof value === 'string' && value.length > 8) {
-        return value.substring(0, 4) + '...' + value.substring(value.length - 4);
+      if (
+        key === 'auth.apiKey' &&
+        typeof value === 'string' &&
+        value.length > 8
+      ) {
+        return (
+          value.substring(0, 4) + '...' + value.substring(value.length - 4)
+        );
       }
       return value;
     }
@@ -87,13 +89,22 @@ export class ConfigCommand {
     return lines.join('\n');
   }
 
-  private flattenConfig(obj: Record<string, unknown>, prefix: string, lines: string[]): void {
+  private flattenConfig(
+    obj: Record<string, unknown>,
+    prefix: string,
+    lines: string[]
+  ): void {
     for (const [key, value] of Object.entries(obj)) {
       const fullKey = prefix ? `${prefix}.${key}` : key;
-      if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      if (
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value)
+      ) {
         this.flattenConfig(value as Record<string, unknown>, fullKey, lines);
       } else {
-        const display = value === undefined ? '(not set)' : JSON.stringify(value);
+        const display =
+          value === undefined ? '(not set)' : JSON.stringify(value);
         lines.push(`${fullKey} = ${display}`);
       }
     }
@@ -105,7 +116,7 @@ export class ConfigCommand {
   private parseValue(key: string, value: string): unknown {
     // Handle array values (comma-separated)
     if (key.includes('targetLangs') || value.includes(',')) {
-      return value.split(',').map(v => v.trim());
+      return value.split(',').map((v) => v.trim());
     }
 
     // Auto-coerce string values to booleans for known boolean config keys
@@ -126,15 +137,21 @@ export class ConfigCommand {
   /**
    * Mask sensitive values like API keys
    */
-  private maskSensitiveValues(config: Record<string, unknown>): Record<string, unknown> {
-    const masked = JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
+  private maskSensitiveValues(
+    config: Record<string, unknown>
+  ): Record<string, unknown> {
+    const masked = JSON.parse(JSON.stringify(config)) as Record<
+      string,
+      unknown
+    >;
 
     // Mask API key
     if (masked['auth'] && typeof masked['auth'] === 'object') {
       const auth = masked['auth'] as Record<string, unknown>;
       if (auth['apiKey'] && typeof auth['apiKey'] === 'string') {
         const apiKey = auth['apiKey'];
-        auth['apiKey'] = apiKey.substring(0, 4) + '...' + apiKey.substring(apiKey.length - 4);
+        auth['apiKey'] =
+          apiKey.substring(0, 4) + '...' + apiKey.substring(apiKey.length - 4);
       }
     }
 
diff --git a/src/cli/commands/detect.ts b/src/cli/commands/detect.ts
index 9ce5a045..50dd09a9 100644
--- a/src/cli/commands/detect.ts
+++ b/src/cli/commands/detect.ts
@@ -18,9 +18,13 @@ export class DetectCommand {
   }
 
   formatJson(result: DetectResult): string {
-    return JSON.stringify({
-      detected_language: result.detectedLanguage,
-      language_name: result.languageName,
-    }, null, 2);
+    return JSON.stringify(
+      {
+        detected_language: result.detectedLanguage,
+        language_name: result.languageName,
+      },
+      null,
+      2
+    );
   }
 }
diff --git a/src/cli/commands/glossary.ts b/src/cli/commands/glossary.ts
index d0e6a158..d487acf5 100644
--- a/src/cli/commands/glossary.ts
+++ b/src/cli/commands/glossary.ts
@@ -5,7 +5,14 @@
 
 import * as fs from 'fs';
 import { GlossaryService } from '../../services/glossary.js';
-import { GlossaryInfo, GlossaryLanguagePair, Language, getTargetLang, getTotalEntryCount, isMultilingual } from '../../types/index.js';
+import {
+  GlossaryInfo,
+  GlossaryLanguagePair,
+  Language,
+  getTargetLang,
+  getTotalEntryCount,
+  isMultilingual,
+} from '../../types/index.js';
 import { safeReadFileSync } from '../../utils/safe-read-file.js';
 import { sanitizeForTerminal } from '../../utils/control-chars.js';
 import { ValidationError, ConfigError } from '../../utils/errors.js';
@@ -75,7 +82,10 @@ export class GlossaryCommand {
   /**
    * Get glossary entries (v3 API - requires target lang for multilingual glossaries)
    */
-  async entries(nameOrId: string, targetLang?: Language): Promise<Record<string, string>> {
+  async entries(
+    nameOrId: string,
+    targetLang?: Language
+  ): Promise<Record<string, string>> {
     const glossary = await this.show(nameOrId);
     // Get target language (will throw if glossary is multilingual and targetLang not provided)
     const target = getTargetLang(glossary, targetLang);
@@ -170,7 +180,7 @@ export class GlossaryCommand {
     const glossary = await this.show(nameOrId);
     await this.glossaryService.updateGlossary(glossary.glossary_id, {
       name: options.name,
-      dictionaries: options.dictionaries?.map(dict => ({
+      dictionaries: options.dictionaries?.map((dict) => ({
         sourceLang: glossary.source_lang,
         targetLang: dict.targetLang,
         entries: dict.entries,
@@ -181,10 +191,7 @@ export class GlossaryCommand {
   /**
    * Rename a glossary (v3 API - uses PATCH)
    */
-  async rename(
-    nameOrId: string,
-    newName: string
-  ): Promise<void> {
+  async rename(nameOrId: string, newName: string): Promise<void> {
     const glossary = await this.show(nameOrId);
     await this.glossaryService.renameGlossary(glossary.glossary_id, newName);
   }
@@ -250,10 +257,12 @@ export class GlossaryCommand {
 
     if (multilingual) {
       lines.push('\nLanguage pairs:');
-      glossary.dictionaries.forEach(dict => {
+      glossary.dictionaries.forEach((dict) => {
         // Lowercased like the summary above; normalizeGlossaryInfo only touches
         // the top-level fields.
-        lines.push(`  ${dict.source_lang.toLowerCase()} → ${dict.target_lang.toLowerCase()}: ${dict.entry_count} entries`);
+        lines.push(
+          `  ${dict.source_lang.toLowerCase()} → ${dict.target_lang.toLowerCase()}: ${dict.entry_count} entries`
+        );
       });
     }
 
@@ -268,11 +277,12 @@ export class GlossaryCommand {
       return 'No glossaries found';
     }
 
-    const lines = glossaries.map(g => {
+    const lines = glossaries.map((g) => {
       const totalEntries = getTotalEntryCount(g);
-      const targetStr = g.target_langs.length === 1
-        ? g.target_langs[0]
-        : `${g.target_langs.length} targets`;
+      const targetStr =
+        g.target_langs.length === 1
+          ? g.target_langs[0]
+          : `${g.target_langs.length} targets`;
       const icon = isMultilingual(g) ? '📚' : '📖';
       return `${icon} ${sanitizeForTerminal(g.name)} (${g.source_lang}→${targetStr}) - ${totalEntries} entries`;
     });
diff --git a/src/cli/commands/hooks.ts b/src/cli/commands/hooks.ts
index bdf91348..b4e43a0c 100644
--- a/src/cli/commands/hooks.ts
+++ b/src/cli/commands/hooks.ts
@@ -26,7 +26,9 @@ export class HooksCommand {
    */
   install(hookType: HookType): string {
     if (!this.gitHooksService) {
-      throw new ValidationError('Not in a git repository. Run this command from within a git repository.');
+      throw new ValidationError(
+        'Not in a git repository. Run this command from within a git repository.'
+      );
     }
 
     const result = this.gitHooksService.install(hookType);
@@ -36,7 +38,9 @@ export class HooksCommand {
       lines.push(chalk.gray(`  Path: ${result.hookPath}`));
     }
     if (result?.backupPath) {
-      lines.push(chalk.gray(`  Previous hook backed up to: ${result.backupPath}`));
+      lines.push(
+        chalk.gray(`  Previous hook backed up to: ${result.backupPath}`)
+      );
     }
 
     return lines.join('\n');
@@ -47,7 +51,9 @@ export class HooksCommand {
    */
   uninstall(hookType: HookType): string {
     if (!this.gitHooksService) {
-      throw new ValidationError('Not in a git repository. Run this command from within a git repository.');
+      throw new ValidationError(
+        'Not in a git repository. Run this command from within a git repository.'
+      );
     }
 
     this.gitHooksService.uninstall(hookType);
@@ -78,7 +84,9 @@ export class HooksCommand {
 
     for (const [hook, installed] of Object.entries(status)) {
       const icon = installed ? chalk.green('✓') : chalk.gray('✗');
-      const text = installed ? chalk.green('installed') : chalk.gray('not installed');
+      const text = installed
+        ? chalk.green('installed')
+        : chalk.gray('not installed');
       lines.push(`  ${icon} ${hook.padEnd(15)} ${text}`);
     }
 
@@ -90,7 +98,9 @@ export class HooksCommand {
    */
   showPath(hookType: HookType): string {
     if (!this.gitHooksService) {
-      throw new ValidationError('Not in a git repository. Run this command from within a git repository.');
+      throw new ValidationError(
+        'Not in a git repository. Run this command from within a git repository.'
+      );
     }
 
     const hookPath = this.gitHooksService.getHookPath(hookType);
diff --git a/src/cli/commands/init.ts b/src/cli/commands/init.ts
index e7b0d6bf..0d3924d4 100644
--- a/src/cli/commands/init.ts
+++ b/src/cli/commands/init.ts
@@ -52,7 +52,10 @@ export class InitCommand {
       configBaseUrl,
       usePro,
     });
-    const client = new DeepLClient(apiKey.trim(), { ...this.httpOptions, baseUrl });
+    const client = new DeepLClient(apiKey.trim(), {
+      ...this.httpOptions,
+      baseUrl,
+    });
     await client.getUsage();
 
     this.config.set('auth.apiKey', apiKey.trim());
diff --git a/src/cli/commands/languages.ts b/src/cli/commands/languages.ts
index 02bd23f2..fab78eaf 100644
--- a/src/cli/commands/languages.ts
+++ b/src/cli/commands/languages.ts
@@ -43,7 +43,7 @@ function featureLabel(key: string): string {
   // The key is a response field, so it is sanitized before it is displayed.
   return sanitizeForTerminal(key)
     .split('_')
-    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join(' ');
 }
 
@@ -115,7 +115,7 @@ export function partitionFeatureKeys(entries: LanguageDisplayEntry[]): {
   const uniform: Array<{ key: string; cell: string }> = [];
   for (const key of allKeys) {
     const first = featureCell(described[0]!, key);
-    if (described.some(entry => featureCell(entry, key) !== first)) {
+    if (described.some((entry) => featureCell(entry, key) !== first)) {
       columns.push(key);
     } else {
       uniform.push({ key, cell: first });
@@ -124,8 +124,8 @@ export function partitionFeatureKeys(entries: LanguageDisplayEntry[]): {
 
   return {
     columns: sortFeatureKeys(columns),
-    uniform: sortFeatureKeys(uniform.map(u => u.key)).map(
-      key => uniform.find(u => u.key === key)!,
+    uniform: sortFeatureKeys(uniform.map((u) => u.key)).map((key) =>
+      uniform.find((u) => u.key === key)!
     ),
   };
 }
@@ -144,8 +144,8 @@ function featureList(entry: LanguageDisplayEntry, keys: string[]): string {
   if (!hasFeatureData(entry)) return 'no feature data';
   if (keys.length === 0) return '';
   const supported = keys
-    .filter(key => featureCell(entry, key) !== '—')
-    .map(key => {
+    .filter((key) => featureCell(entry, key) !== '—')
+    .map((key) => {
       const cell = featureCell(entry, key);
       const label = featureLabel(key).toLowerCase();
       return cell === 'yes' ? label : `${label} (${cell})`;
@@ -164,12 +164,14 @@ function featureList(entry: LanguageDisplayEntry, keys: string[]): string {
  */
 function uniformNote(
   uniform: Array<{ key: string; cell: string }>,
-  entries: LanguageDisplayEntry[],
+  entries: LanguageDisplayEntry[]
 ): string | undefined {
-  const supported = uniform.filter(u => u.cell !== '—' && u.cell !== UNKNOWN_CELL);
+  const supported = uniform.filter(
+    (u) => u.cell !== '—' && u.cell !== UNKNOWN_CELL
+  );
   if (supported.length === 0) return undefined;
   const list = supported
-    .map(u => {
+    .map((u) => {
       const label = featureLabel(u.key).toLowerCase();
       return u.cell === 'yes' ? label : `${label} (${u.cell})`;
     })
@@ -213,22 +215,25 @@ export class LanguagesCommand {
       apiMap.set(lang.language.toLowerCase(), lang);
     }
 
-    const registryEntries = type === 'source'
-      ? getRegistrySourceLanguages()
-      : getRegistryTargetLanguages();
+    const registryEntries =
+      type === 'source'
+        ? getRegistrySourceLanguages()
+        : getRegistryTargetLanguages();
 
-    const merged = registryEntries.map(entry => {
+    const merged = registryEntries.map((entry) => {
       const apiLang = apiMap.get(entry.code);
       return {
         code: entry.code,
         name: apiLang?.name ?? entry.name,
         category: entry.category,
-        ...(apiLang?.supportsFormality !== undefined && { supportsFormality: apiLang.supportsFormality }),
+        ...(apiLang?.supportsFormality !== undefined && {
+          supportsFormality: apiLang.supportsFormality,
+        }),
         ...(apiLang?.features && { features: apiLang.features }),
       };
     });
 
-    const known = new Set(registryEntries.map(entry => entry.code));
+    const known = new Set(registryEntries.map((entry) => entry.code));
     for (const lang of apiLanguages) {
       const code = lang.language.toLowerCase();
       if (known.has(code)) continue;
@@ -237,7 +242,11 @@ export class LanguagesCommand {
       // always carries a subtag, which is the stable signal available here; core
       // and regional render in the same section anyway, and regenerating the
       // snapshot replaces the guess with the API's own answer.
-      const { code: derivedCode, name, category } = deriveLanguageEntry({
+      const {
+        code: derivedCode,
+        name,
+        category,
+      } = deriveLanguageEntry({
         lang: code,
         name: lang.name,
         usable_as_source: !code.includes('-'),
@@ -247,7 +256,9 @@ export class LanguagesCommand {
         code: derivedCode,
         name,
         category,
-        ...(lang.supportsFormality !== undefined && { supportsFormality: lang.supportsFormality }),
+        ...(lang.supportsFormality !== undefined && {
+          supportsFormality: lang.supportsFormality,
+        }),
         ...(lang.features && { features: lang.features }),
       });
     }
@@ -259,11 +270,12 @@ export class LanguagesCommand {
    * Get display entries from registry only (no API call).
    */
   getRegistryLanguages(type: 'source' | 'target'): LanguageDisplayEntry[] {
-    const entries = type === 'source'
-      ? getRegistrySourceLanguages()
-      : getRegistryTargetLanguages();
+    const entries =
+      type === 'source'
+        ? getRegistrySourceLanguages()
+        : getRegistryTargetLanguages();
 
-    return entries.map(entry => ({
+    return entries.map((entry) => ({
       code: entry.code,
       name: entry.name,
       category: entry.category,
@@ -290,13 +302,16 @@ export class LanguagesCommand {
     showFeatures = false
   ): string {
     const lines: string[] = [];
-    const header = type === 'source' ? 'Source Languages:' : 'Target Languages:';
+    const header =
+      type === 'source' ? 'Source Languages:' : 'Target Languages:';
     const renderFeatures = showFeatures && hasAnyFeatures(entries);
     // Formality is one of the feature columns, so the [F] shorthand would say it
     // twice. `=== true` because a language the response did not describe carries
     // no answer, and a legend with no [F] beneath it reads as "none support it".
     const showFormality =
-      !renderFeatures && type === 'target' && entries.some(e => e.supportsFormality === true);
+      !renderFeatures &&
+      type === 'target' &&
+      entries.some((e) => e.supportsFormality === true);
 
     lines.push(chalk.bold(header));
 
@@ -305,11 +320,13 @@ export class LanguagesCommand {
       return lines.join('\n');
     }
 
-    const coreAndRegional = entries.filter(e => e.category === 'core' || e.category === 'regional');
-    const extended = entries.filter(e => e.category === 'extended');
+    const coreAndRegional = entries.filter(
+      (e) => e.category === 'core' || e.category === 'regional'
+    );
+    const extended = entries.filter((e) => e.category === 'extended');
 
     const allEntries = [...coreAndRegional, ...extended];
-    const maxCodeLength = Math.max(...allEntries.map(e => e.code.length));
+    const maxCodeLength = Math.max(...allEntries.map((e) => e.code.length));
     const { columns, uniform } = renderFeatures
       ? partitionFeatureKeys(entries)
       : { columns: [], uniform: [] };
@@ -319,18 +336,27 @@ export class LanguagesCommand {
       return list ? chalk.gray(` — ${list}`) : '';
     };
 
-    coreAndRegional.forEach(entry => {
+    coreAndRegional.forEach((entry) => {
       const code = entry.code.padEnd(maxCodeLength + 2);
-      const formalityMarker = showFormality && entry.supportsFormality ? chalk.green(' [F]') : '';
-      lines.push(`  ${chalk.cyan(code)} ${sanitizeForTerminal(entry.name)}${formalityMarker}${suffix(entry)}`);
+      const formalityMarker =
+        showFormality && entry.supportsFormality ? chalk.green(' [F]') : '';
+      lines.push(
+        `  ${chalk.cyan(code)} ${sanitizeForTerminal(entry.name)}${formalityMarker}${suffix(entry)}`
+      );
     });
 
     if (extended.length > 0) {
       lines.push('');
-      lines.push(chalk.gray('  Extended Languages (quality_optimized only, no formality/glossary):'));
-      extended.forEach(entry => {
+      lines.push(
+        chalk.gray(
+          '  Extended Languages (quality_optimized only, no formality/glossary):'
+        )
+      );
+      extended.forEach((entry) => {
         const code = entry.code.padEnd(maxCodeLength + 2);
-        lines.push(`  ${chalk.gray(code)} ${chalk.gray(sanitizeForTerminal(entry.name))}${suffix(entry)}`);
+        lines.push(
+          `  ${chalk.gray(code)} ${chalk.gray(sanitizeForTerminal(entry.name))}${suffix(entry)}`
+        );
       });
     }
 
@@ -353,8 +379,16 @@ export class LanguagesCommand {
     targetLanguages: LanguageInfo[],
     showFeatures = false
   ): string {
-    const sourcePart = this.formatLanguages(sourceLanguages, 'source', showFeatures);
-    const targetPart = this.formatLanguages(targetLanguages, 'target', showFeatures);
+    const sourcePart = this.formatLanguages(
+      sourceLanguages,
+      'source',
+      showFeatures
+    );
+    const targetPart = this.formatLanguages(
+      targetLanguages,
+      'target',
+      showFeatures
+    );
 
     return `${sourcePart}\n\n${targetPart}`;
   }
@@ -365,9 +399,10 @@ export class LanguagesCommand {
     type: 'source' | 'target',
     showFeatures = false
   ): string {
-    const entries = languages.length === 0 && !this.service.hasClient()
-      ? this.getRegistryLanguages(type)
-      : this.mergeWithRegistry(languages, type);
+    const entries =
+      languages.length === 0 && !this.service.hasClient()
+        ? this.getRegistryLanguages(type)
+        : this.mergeWithRegistry(languages, type);
 
     return this.formatDisplayEntriesTable(entries, type, showFeatures);
   }
@@ -392,7 +427,7 @@ export class LanguagesCommand {
     const showFormality =
       (!renderFeatures || columns.length === 0) &&
       type === 'target' &&
-      entries.some(e => e.supportsFormality === true);
+      entries.some((e) => e.supportsFormality === true);
 
     const head = ['Code', 'Name', 'Category'];
     const colWidths = [10, renderFeatures ? 24 : showFormality ? 30 : 36, 12];
@@ -414,7 +449,11 @@ export class LanguagesCommand {
     });
 
     for (const entry of entries) {
-      const row: string[] = [entry.code, sanitizeForTerminal(entry.name), entry.category];
+      const row: string[] = [
+        entry.code,
+        sanitizeForTerminal(entry.name),
+        entry.category,
+      ];
       if (showFormality) {
         row.push(entry.supportsFormality ? 'yes' : '—');
       }
@@ -425,8 +464,14 @@ export class LanguagesCommand {
     }
 
     const notes: string[] = [];
-    if (renderFeatures && columns.length > 0 && entries.some(e => !hasFeatureData(e))) {
-      notes.push(`${UNKNOWN_CELL} = the API response did not describe this language`);
+    if (
+      renderFeatures &&
+      columns.length > 0 &&
+      entries.some((e) => !hasFeatureData(e))
+    ) {
+      notes.push(
+        `${UNKNOWN_CELL} = the API response did not describe this language`
+      );
     }
     const note = renderFeatures ? uniformNote(uniform, entries) : undefined;
     if (note) notes.push(note);
diff --git a/src/cli/commands/parse-int-option.ts b/src/cli/commands/parse-int-option.ts
index b897f543..493de9a1 100644
--- a/src/cli/commands/parse-int-option.ts
+++ b/src/cli/commands/parse-int-option.ts
@@ -8,11 +8,15 @@ import { InvalidArgumentError } from 'commander';
  * the worker-pool sizing and silently produced zero workers. Rejecting at the
  * boundary means the user is told instead.
  */
-export function parsePositiveIntOption(value: string, name: string, max: number): number {
+export function parsePositiveIntOption(
+  value: string,
+  name: string,
+  max: number
+): number {
   const parsed = Number.parseInt(value, 10);
   if (!Number.isInteger(parsed) || parsed <= 0 || parsed > max) {
     throw new InvalidArgumentError(
-      `--${name} must be an integer between 1 and ${max}, got '${value}'`,
+      `--${name} must be an integer between 1 and ${max}, got '${value}'`
     );
   }
   return parsed;
diff --git a/src/cli/commands/register-admin.ts b/src/cli/commands/register-admin.ts
index 77f4a875..ea20bcf8 100644
--- a/src/cli/commands/register-admin.ts
+++ b/src/cli/commands/register-admin.ts
@@ -2,7 +2,11 @@ import { Command, Option } from 'commander';
 import chalk from 'chalk';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
-import { createAdminCommand, type CreateDeepLClient, type GetApiKeyAndOptions } from './service-factory.js';
+import {
+  createAdminCommand,
+  type CreateDeepLClient,
+  type GetApiKeyAndOptions,
+} from './service-factory.js';
 
 export function registerAdmin(
   program: Command,
@@ -10,14 +14,18 @@ export function registerAdmin(
     createDeepLClient: CreateDeepLClient;
     getApiKeyAndOptions?: GetApiKeyAndOptions;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { createDeepLClient, handleError } = deps;
 
   const adminCmd = program
     .command('admin')
-    .description('Admin API: manage API keys and view organization usage (requires admin key)')
-    .addHelpText('after', `
+    .description(
+      'Admin API: manage API keys and view organization usage (requires admin key)'
+    )
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl admin keys list
   $ deepl admin keys create --label "CI/CD key"
@@ -27,17 +35,20 @@ Examples:
   $ deepl admin usage --start 2024-01-01 --end 2024-01-31
   $ deepl admin usage --start 2024-01-01 --end 2024-01-31 --group-by key
   $ deepl admin keys list --format json
-`);
+`
+    );
 
-  const adminKeysCmd = adminCmd
-    .command('keys')
-    .description('Manage API keys');
+  const adminKeysCmd = adminCmd.command('keys').description('Manage API keys');
 
   adminKeysCmd
     .addCommand(
       new Command('list')
         .description('List all API keys')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
         .action(async (options: { format?: string }) => {
           try {
             const admin = await createAdminCommand(createDeepLClient);
@@ -56,7 +67,11 @@ Examples:
       new Command('create')
         .description('Create a new API key')
         .option('--label <label>', 'Label for the new key')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
         .action(async (options: { label?: string; format?: string }) => {
           try {
             const admin = await createAdminCommand(createDeepLClient);
@@ -81,7 +96,9 @@ Examples:
           try {
             if (!options.yes) {
               const { confirm } = await import('../../utils/confirm.js');
-              const confirmed = await confirm({ message: `Deactivate API key "${keyId}"? This action is permanent.` });
+              const confirmed = await confirm({
+                message: `Deactivate API key "${keyId}"? This action is permanent.`,
+              });
               if (!confirmed) {
                 Logger.info('Aborted.');
                 return;
@@ -105,7 +122,9 @@ Examples:
           try {
             const admin = await createAdminCommand(createDeepLClient);
             await admin.renameKey(keyId, label);
-            Logger.success(chalk.green(`\u2713 API key ${keyId} renamed to "${label}"`));
+            Logger.success(
+              chalk.green(`\u2713 API key ${keyId} renamed to "${label}"`)
+            );
           } catch (error) {
             handleError(error);
           }
@@ -116,47 +135,77 @@ Examples:
         .description('Set usage limits for an API key')
         .argument('<key-id>', 'Key ID')
         .argument('<characters>', 'Character limit (number or "unlimited")')
-        .option('--stt-limit <milliseconds>', 'Speech-to-text milliseconds limit (number or "unlimited")')
-        .action(async (keyId: string, characters: string, options: { sttLimit?: string }) => {
-          try {
-            const limit = characters === 'unlimited' ? null : parseInt(characters, 10);
-            if (limit !== null && isNaN(limit)) {
-              throw new ValidationError('Characters must be a number or "unlimited"');
-            }
+        .option(
+          '--stt-limit <milliseconds>',
+          'Speech-to-text milliseconds limit (number or "unlimited")'
+        )
+        .action(
+          async (
+            keyId: string,
+            characters: string,
+            options: { sttLimit?: string }
+          ) => {
+            try {
+              const limit =
+                characters === 'unlimited' ? null : parseInt(characters, 10);
+              if (limit !== null && isNaN(limit)) {
+                throw new ValidationError(
+                  'Characters must be a number or "unlimited"'
+                );
+              }
 
-            let sttLimit: number | null | undefined;
-            if (options.sttLimit !== undefined) {
-              sttLimit = options.sttLimit === 'unlimited' ? null : parseInt(options.sttLimit, 10);
-              if (sttLimit !== null && isNaN(sttLimit)) {
-                throw new ValidationError('STT limit must be a number or "unlimited"');
+              let sttLimit: number | null | undefined;
+              if (options.sttLimit !== undefined) {
+                sttLimit =
+                  options.sttLimit === 'unlimited'
+                    ? null
+                    : parseInt(options.sttLimit, 10);
+                if (sttLimit !== null && isNaN(sttLimit)) {
+                  throw new ValidationError(
+                    'STT limit must be a number or "unlimited"'
+                  );
+                }
               }
-            }
 
-            const admin = await createAdminCommand(createDeepLClient, deps.getApiKeyAndOptions);
-            await admin.setKeyLimit(keyId, limit, sttLimit);
+              const admin = await createAdminCommand(
+                createDeepLClient,
+                deps.getApiKeyAndOptions
+              );
+              await admin.setKeyLimit(keyId, limit, sttLimit);
 
-            const limitStr = limit === null ? 'unlimited' : limit.toLocaleString();
-            const parts = [`${limitStr} characters`];
-            if (sttLimit !== undefined) {
-              const sttStr = sttLimit === null ? 'unlimited' : sttLimit.toLocaleString();
-              parts.push(`${sttStr} STT ms`);
+              const limitStr =
+                limit === null ? 'unlimited' : limit.toLocaleString();
+              const parts = [`${limitStr} characters`];
+              if (sttLimit !== undefined) {
+                const sttStr =
+                  sttLimit === null ? 'unlimited' : sttLimit.toLocaleString();
+                parts.push(`${sttStr} STT ms`);
+              }
+              Logger.success(
+                chalk.green(
+                  `\u2713 Usage limit for ${keyId} set to ${parts.join(', ')}`
+                )
+              );
+            } catch (error) {
+              handleError(error);
             }
-            Logger.success(chalk.green(`\u2713 Usage limit for ${keyId} set to ${parts.join(', ')}`));
-          } catch (error) {
-            handleError(error);
           }
-        })
+        )
     );
 
-  adminCmd
-    .addCommand(
-      new Command('usage')
-        .description('View organization usage analytics')
-        .requiredOption('--start <date>', 'Start date (YYYY-MM-DD)')
-        .requiredOption('--end <date>', 'End date (YYYY-MM-DD)')
-        .option('--group-by <grouping>', 'Group results: key, key_and_day')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-        .action(async (options: {
+  adminCmd.addCommand(
+    new Command('usage')
+      .description('View organization usage analytics')
+      .requiredOption('--start <date>', 'Start date (YYYY-MM-DD)')
+      .requiredOption('--end <date>', 'End date (YYYY-MM-DD)')
+      .option('--group-by <grouping>', 'Group results: key, key_and_day')
+      .addOption(
+        new Option('--format <format>', 'Output format')
+          .choices(['text', 'json'])
+          .default('text')
+      )
+      .action(
+        async (options: {
           start: string;
           end: string;
           groupBy?: string;
@@ -177,6 +226,7 @@ Examples:
           } catch (error) {
             handleError(error);
           }
-        })
-    );
+        }
+      )
+  );
 }
diff --git a/src/cli/commands/register-auth.ts b/src/cli/commands/register-auth.ts
index 38529d8a..9e91f569 100644
--- a/src/cli/commands/register-auth.ts
+++ b/src/cli/commands/register-auth.ts
@@ -11,14 +11,16 @@ export function registerAuth(
     getConfigService: () => ConfigService;
     getHttpOptions?: () => DeepLClientOptions;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { getConfigService, getHttpOptions, handleError } = deps;
 
   program
     .command('auth')
     .description('Manage DeepL API authentication')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ echo "YOUR_API_KEY" | deepl auth set-key --from-stdin
   $ deepl auth set-key --from-stdin < ~/.deepl-api-key
@@ -28,52 +30,71 @@ Examples:
 
 Note: Prefer --from-stdin over passing the key as an argument.
 Command arguments are visible to other users via process listings.
-`)
+`
+    )
     .addCommand(
       new Command('set-key')
         .description('Set your DeepL API key')
         .argument('[api-key]', 'Your DeepL API key (or pipe via stdin)')
         .option('--from-stdin', 'Read API key from stdin')
-        .option('--no-verify', 'Store the key without validating it against the API (for offline or proxied networks)')
-        .action(async (apiKey: string | undefined, opts: { fromStdin?: boolean; verify?: boolean }) => {
-          try {
-            let key = apiKey;
-            if (apiKey && !opts.fromStdin) {
-              Logger.warn('Passing API key as argument is deprecated (visible in ps). Use --from-stdin instead.');
-            }
-            if (opts.fromStdin === true || !key) {
-              if (process.stdin.isTTY && !key) {
-                handleError(new ValidationError('API key required: provide as argument or use --from-stdin'));
-                return;
+        .option(
+          '--no-verify',
+          'Store the key without validating it against the API (for offline or proxied networks)'
+        )
+        .action(
+          async (
+            apiKey: string | undefined,
+            opts: { fromStdin?: boolean; verify?: boolean }
+          ) => {
+            try {
+              let key = apiKey;
+              if (apiKey && !opts.fromStdin) {
+                Logger.warn(
+                  'Passing API key as argument is deprecated (visible in ps). Use --from-stdin instead.'
+                );
               }
-              const MAX_STDIN_BYTES = 131072; // 128KB
-              const chunks: Buffer[] = [];
-              let totalBytes = 0;
-              for await (const chunk of process.stdin) {
-                const buf = chunk as Buffer;
-                totalBytes += buf.length;
-                if (totalBytes > MAX_STDIN_BYTES) {
-                  throw new ValidationError('Input exceeds maximum size of 128KB');
+              if (opts.fromStdin === true || !key) {
+                if (process.stdin.isTTY && !key) {
+                  handleError(
+                    new ValidationError(
+                      'API key required: provide as argument or use --from-stdin'
+                    )
+                  );
+                  return;
                 }
-                chunks.push(buf);
+                const MAX_STDIN_BYTES = 131072; // 128KB
+                const chunks: Buffer[] = [];
+                let totalBytes = 0;
+                for await (const chunk of process.stdin) {
+                  const buf = chunk as Buffer;
+                  totalBytes += buf.length;
+                  if (totalBytes > MAX_STDIN_BYTES) {
+                    throw new ValidationError(
+                      'Input exceeds maximum size of 128KB'
+                    );
+                  }
+                  chunks.push(buf);
+                }
+                key = Buffer.concat(chunks).toString('utf-8').trim();
               }
-              key = Buffer.concat(chunks).toString('utf-8').trim();
+              const { AuthCommand } = await import('./auth.js');
+              const authCommand = new AuthCommand(
+                getConfigService(),
+                getHttpOptions?.()
+              );
+              await authCommand.setKey(key, { verify: opts.verify });
+              Logger.success(
+                chalk.green(
+                  opts.verify === false
+                    ? '\u2713 API key saved without validation'
+                    : '\u2713 API key saved and validated successfully'
+                )
+              );
+            } catch (error) {
+              handleError(error);
             }
-            const { AuthCommand } = await import('./auth.js');
-            const authCommand = new AuthCommand(getConfigService(), getHttpOptions?.());
-            await authCommand.setKey(key, { verify: opts.verify });
-            Logger.success(
-              chalk.green(
-                opts.verify === false
-                  ? '\u2713 API key saved without validation'
-                  : '\u2713 API key saved and validated successfully',
-              ),
-            );
-          } catch (error) {
-            handleError(error);
-
           }
-        })
+        )
     )
     .addCommand(
       new Command('show')
@@ -84,14 +105,14 @@ Command arguments are visible to other users via process listings.
             const authCommand = new AuthCommand(getConfigService());
             const key = await authCommand.getKey();
             if (key) {
-              const masked = key.substring(0, 4) + '...' + key.substring(key.length - 4);
+              const masked =
+                key.substring(0, 4) + '...' + key.substring(key.length - 4);
               Logger.output(chalk.blue('API Key:'), masked);
             } else {
               Logger.output(chalk.yellow('No API key set'));
             }
           } catch (error) {
             handleError(error);
-
           }
         })
     )
@@ -106,7 +127,6 @@ Command arguments are visible to other users via process listings.
             Logger.success(chalk.green('\u2713 API key removed'));
           } catch (error) {
             handleError(error);
-
           }
         })
     );
diff --git a/src/cli/commands/register-cache.ts b/src/cli/commands/register-cache.ts
index 78c0e9b2..dad094d2 100644
--- a/src/cli/commands/register-cache.ts
+++ b/src/cli/commands/register-cache.ts
@@ -11,7 +11,7 @@ export function registerCache(
     getConfigService: () => ConfigService;
     getCacheService: () => Promise<CacheService | undefined>;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { getConfigService, getCacheService, handleError } = deps;
 
@@ -20,7 +20,7 @@ export function registerCache(
     if (!cacheService) {
       throw new ConfigError(
         'Cache backend is unavailable, so cache commands cannot run.',
-        'Reinstall the CLI, or run it with the Node.js version it was installed with.',
+        'Reinstall the CLI, or run it with the Node.js version it was installed with.'
       );
     }
     return cacheService;
@@ -29,28 +29,40 @@ export function registerCache(
   program
     .command('cache')
     .description('Manage translation cache')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl cache stats
   $ deepl cache clear --yes
   $ deepl cache clear --dry-run
   $ deepl cache enable --max-size 500M
   $ deepl cache disable
-`)
+`
+    )
     .addCommand(
       new Command('stats')
         .description('Show cache statistics')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json', 'table']).default('text'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json', 'table'])
+            .default('text')
+        )
         .action(async (options: { format?: string }) => {
           try {
             const { CacheCommand } = await import('./cache.js');
-            const cacheCommand = new CacheCommand(await requireCacheService(), getConfigService());
+            const cacheCommand = new CacheCommand(
+              await requireCacheService(),
+              getConfigService()
+            );
             const stats = await cacheCommand.stats();
             if (options.format === 'json') {
               Logger.output(JSON.stringify(stats, null, 2));
             } else if (options.format === 'table') {
               if (!process.stdout.isTTY) {
-                Logger.warn('WARN  --format table is not supported in non-TTY output; falling back to plain text');
+                Logger.warn(
+                  'WARN  --format table is not supported in non-TTY output; falling back to plain text'
+                );
                 Logger.output(cacheCommand.formatStats(stats));
               } else {
                 Logger.output(cacheCommand.formatStatsTable(stats));
@@ -60,7 +72,6 @@ Examples:
             }
           } catch (error) {
             handleError(error);
-
           }
         })
     )
@@ -68,18 +79,28 @@ Examples:
       new Command('clear')
         .description('Clear all cached translations')
         .option('-y, --yes', 'Skip confirmation prompt')
-        .option('--dry-run', 'Show cache stats that would be cleared without performing the operation')
+        .option(
+          '--dry-run',
+          'Show cache stats that would be cleared without performing the operation'
+        )
         .action(async (options: { yes?: boolean; dryRun?: boolean }) => {
           try {
             if (options.dryRun) {
               const { CacheCommand } = await import('./cache.js');
-              const cacheCommand = new CacheCommand(await requireCacheService(), getConfigService());
+              const cacheCommand = new CacheCommand(
+                await requireCacheService(),
+                getConfigService()
+              );
               const stats = await cacheCommand.stats();
               const totalSizeMB = (stats.totalSize / (1024 * 1024)).toFixed(2);
               const lines = [
                 chalk.yellow('[dry-run] No cache entries will be cleared.'),
-                chalk.yellow(`[dry-run] Would clear ${stats.entries} cached entries (${totalSizeMB} MB)`),
-                chalk.yellow(`[dry-run] Cache status: ${stats.enabled ? 'enabled' : 'disabled'}`),
+                chalk.yellow(
+                  `[dry-run] Would clear ${stats.entries} cached entries (${totalSizeMB} MB)`
+                ),
+                chalk.yellow(
+                  `[dry-run] Cache status: ${stats.enabled ? 'enabled' : 'disabled'}`
+                ),
               ];
               Logger.output(lines.join('\n'));
               return;
@@ -87,7 +108,9 @@ Examples:
 
             if (!options.yes) {
               const { confirm } = await import('../../utils/confirm.js');
-              const confirmed = await confirm({ message: 'Clear all cached translations?' });
+              const confirmed = await confirm({
+                message: 'Clear all cached translations?',
+              });
               if (!confirmed) {
                 Logger.info('Aborted.');
                 return;
@@ -95,19 +118,24 @@ Examples:
             }
 
             const { CacheCommand } = await import('./cache.js');
-            const cacheCommand = new CacheCommand(await requireCacheService(), getConfigService());
+            const cacheCommand = new CacheCommand(
+              await requireCacheService(),
+              getConfigService()
+            );
             await cacheCommand.clear();
             Logger.success(chalk.green('\u2713 Cache cleared successfully'));
           } catch (error) {
             handleError(error);
-
           }
         })
     )
     .addCommand(
       new Command('enable')
         .description('Enable translation cache')
-        .option('--max-size <size>', 'Maximum cache size (e.g., 100M, 1G, 500MB)')
+        .option(
+          '--max-size <size>',
+          'Maximum cache size (e.g., 100M, 1G, 500MB)'
+        )
         .action(async (options: { maxSize?: string }) => {
           try {
             let maxSizeBytes: number | undefined;
@@ -118,7 +146,10 @@ Examples:
             }
 
             const { CacheCommand } = await import('./cache.js');
-            const cacheCommand = new CacheCommand(await requireCacheService(), getConfigService());
+            const cacheCommand = new CacheCommand(
+              await requireCacheService(),
+              getConfigService()
+            );
             await cacheCommand.enable(maxSizeBytes);
             Logger.success(chalk.green('\u2713 Cache enabled'));
 
@@ -128,7 +159,6 @@ Examples:
             }
           } catch (error) {
             handleError(error);
-
           }
         })
     )
@@ -138,12 +168,14 @@ Examples:
         .action(async () => {
           try {
             const { CacheCommand } = await import('./cache.js');
-            const cacheCommand = new CacheCommand(await requireCacheService(), getConfigService());
+            const cacheCommand = new CacheCommand(
+              await requireCacheService(),
+              getConfigService()
+            );
             await cacheCommand.disable();
             Logger.success(chalk.green('\u2713 Cache disabled'));
           } catch (error) {
             handleError(error);
-
           }
         })
     );
diff --git a/src/cli/commands/register-completion.ts b/src/cli/commands/register-completion.ts
index cbc0cd40..a862db5a 100644
--- a/src/cli/commands/register-completion.ts
+++ b/src/cli/commands/register-completion.ts
@@ -9,7 +9,7 @@ export function registerCompletion(
   program: Command,
   _deps: {
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { handleError } = _deps;
 
@@ -17,7 +17,9 @@ export function registerCompletion(
     .command('completion')
     .description('Generate shell completion scripts')
     .argument('<shell>', `Shell type (${SUPPORTED_SHELLS.join(', ')})`)
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl completion bash > /etc/bash_completion.d/deepl
   $ deepl completion zsh > "\${fpath[1]}/_deepl"
@@ -27,19 +29,22 @@ Examples:
   $ source <(deepl completion bash)
   $ eval "$(deepl completion zsh)"
   $ deepl completion fish | source
-`)
+`
+    )
     .action(async (shell: string) => {
       try {
         const normalized = shell.toLowerCase().trim();
 
         if (!SUPPORTED_SHELLS.includes(normalized as ShellType)) {
           throw new ValidationError(
-            `Unsupported shell: "${shell}". Supported shells: ${SUPPORTED_SHELLS.join(', ')}`,
+            `Unsupported shell: "${shell}". Supported shells: ${SUPPORTED_SHELLS.join(', ')}`
           );
         }
 
         const { CompletionCommand } = await import('./completion.js');
-        const completionCommand = new CompletionCommand(program.parent ?? program);
+        const completionCommand = new CompletionCommand(
+          program.parent ?? program
+        );
         const script = completionCommand.generate(normalized as ShellType);
         Logger.output(script);
       } catch (error) {
diff --git a/src/cli/commands/register-config.ts b/src/cli/commands/register-config.ts
index 447da4ed..8dc5769c 100644
--- a/src/cli/commands/register-config.ts
+++ b/src/cli/commands/register-config.ts
@@ -8,25 +8,32 @@ export function registerConfig(
   deps: {
     getConfigService: () => ConfigService;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { getConfigService, handleError } = deps;
 
   program
     .command('config')
     .description('Manage configuration')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl config set api.usePro true
   $ deepl config get auth.apiKey
   $ deepl config list
   $ deepl config reset
-`)
+`
+    )
     .addCommand(
       new Command('get')
         .description('Get configuration value')
         .argument('[key]', 'Config key (dot notation) or empty for all')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('json'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('json')
+        )
         .action(async (key?: string, options?: { format?: string }) => {
           try {
             const { ConfigCommand: ConfigCmd } = await import('./config.js');
@@ -39,7 +46,6 @@ Examples:
             }
           } catch (error) {
             handleError(error);
-
           }
         })
     )
@@ -55,19 +61,25 @@ Examples:
             await configCommand.set(key, value);
             let displayValue: string = value;
             if (key === 'auth.apiKey' && value.length > 8) {
-              displayValue = value.substring(0, 4) + '...' + value.substring(value.length - 4);
+              displayValue =
+                value.substring(0, 4) +
+                '...' +
+                value.substring(value.length - 4);
             }
             Logger.success(chalk.green(`\u2713 Set ${key} = ${displayValue}`));
           } catch (error) {
             handleError(error);
-
           }
         })
     )
     .addCommand(
       new Command('list')
         .description('List all configuration values')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('json'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('json')
+        )
         .action(async (options: { format?: string }) => {
           try {
             const { ConfigCommand: ConfigCmd } = await import('./config.js');
@@ -80,7 +92,6 @@ Examples:
             }
           } catch (error) {
             handleError(error);
-
           }
         })
     )
@@ -92,7 +103,9 @@ Examples:
           try {
             if (!options.yes) {
               const { confirm } = await import('../../utils/confirm.js');
-              const confirmed = await confirm({ message: 'Reset all configuration to defaults?' });
+              const confirmed = await confirm({
+                message: 'Reset all configuration to defaults?',
+              });
               if (!confirmed) {
                 Logger.info('Aborted.');
                 return;
@@ -102,10 +115,11 @@ Examples:
             const { ConfigCommand: ConfigCmd } = await import('./config.js');
             const configCommand = new ConfigCmd(getConfigService());
             await configCommand.reset();
-            Logger.success(chalk.green('\u2713 Configuration reset to defaults'));
+            Logger.success(
+              chalk.green('\u2713 Configuration reset to defaults')
+            );
           } catch (error) {
             handleError(error);
-
           }
         })
     );
diff --git a/src/cli/commands/register-correct.ts b/src/cli/commands/register-correct.ts
index d92b01db..81846bde 100644
--- a/src/cli/commands/register-correct.ts
+++ b/src/cli/commands/register-correct.ts
@@ -1,33 +1,54 @@
 import { type Command, Option } from 'commander';
-import { createWriteAction, WRITE_LANGUAGES, type WriteDeps } from './register-write.js';
+import {
+  createWriteAction,
+  WRITE_LANGUAGES,
+  type WriteDeps,
+} from './register-write.js';
 
-export function registerCorrect(
-  program: Command,
-  deps: WriteDeps,
-): void {
+export function registerCorrect(program: Command, deps: WriteDeps): void {
   program
     .command('correct')
     .alias('c')
-    .description('Correct spelling and grammar using DeepL Write API (no rewording)')
+    .description(
+      'Correct spelling and grammar using DeepL Write API (no rewording)'
+    )
     .argument('[text]', 'Text to correct, file path, or read from stdin')
     .optionsGroup('Core Options:')
-    .option('-l, --lang <language>', `Target language: ${WRITE_LANGUAGES.join(', ')} (auto-detect if omitted)`)
-    .option('--to <language>', 'Alias of --lang — accepts the same language values. Provided for muscle-memory consistency with `deepl translate --to`.')
+    .option(
+      '-l, --lang <language>',
+      `Target language: ${WRITE_LANGUAGES.join(', ')} (auto-detect if omitted)`
+    )
+    .option(
+      '--to <language>',
+      'Alias of --lang — accepts the same language values. Provided for muscle-memory consistency with `deepl translate --to`.'
+    )
     .optionsGroup('Output Modes:')
     .option('-a, --alternatives', 'Show all alternative corrections')
     .option('-o, --output <file>', 'Write corrected text to file')
     .option('--in-place', 'Edit file in place (use with file input)')
-    .option('-i, --interactive', 'Interactive mode - review the correction before accepting')
+    .option(
+      '-i, --interactive',
+      'Interactive mode - review the correction before accepting'
+    )
     .option('-d, --diff', 'Show diff between original and corrected text')
     .optionsGroup('Fix Operations:')
-    .option('--check', 'Check if text needs correction (exit 0 if clean, exit 8 if corrections needed)')
+    .option(
+      '--check',
+      'Check if text needs correction (exit 0 if clean, exit 8 if corrections needed)'
+    )
     .option('--fix', 'Automatically fix file in place')
     .option('-b, --backup', 'Create backup file before fixing (use with --fix)')
     .optionsGroup('Advanced:')
     .option('--no-cache', 'Bypass cache for this request')
     .optionsGroup('Output:')
-    .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-    .addHelpText('after', `
+    .addOption(
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
+    )
+    .addHelpText(
+      'after',
+      `
 Unlike \`deepl write\`, which may reword text for style, \`correct\` fixes
 spelling and grammar only and leaves the wording alone.
 
@@ -40,6 +61,7 @@ Examples:
   $ deepl correct report.txt --output corrected.txt
   $ cat notes.txt | deepl correct
   $ deepl c "quick proofread"                               (c is an alias of correct)
-`)
+`
+    )
     .action(createWriteAction(deps, 'correct'));
 }
diff --git a/src/cli/commands/register-describe.ts b/src/cli/commands/register-describe.ts
index 26781f1d..7f3528ed 100644
--- a/src/cli/commands/register-describe.ts
+++ b/src/cli/commands/register-describe.ts
@@ -10,20 +10,26 @@ export function registerDescribe(
   program: Command,
   deps: {
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { handleError } = deps;
 
   program
     .command('_describe', { hidden: true })
-    .description('Emit CLI subcommand tree and flag vocabulary (operator tooling)')
-    .option('--format <format>', `Output format (${SUPPORTED_FORMATS.join(', ')})`, 'json')
+    .description(
+      'Emit CLI subcommand tree and flag vocabulary (operator tooling)'
+    )
+    .option(
+      '--format <format>',
+      `Output format (${SUPPORTED_FORMATS.join(', ')})`,
+      'json'
+    )
     .action((opts: { format?: string }) => {
       try {
         const format = (opts.format ?? 'json').toLowerCase().trim();
         if (!SUPPORTED_FORMATS.includes(format as DescribeFormat)) {
           throw new ValidationError(
-            `Unsupported --format: "${opts.format ?? ''}". Supported: ${SUPPORTED_FORMATS.join(', ')}`,
+            `Unsupported --format: "${opts.format ?? ''}". Supported: ${SUPPORTED_FORMATS.join(', ')}`
           );
         }
         const tree = describeProgram(program);
diff --git a/src/cli/commands/register-detect.ts b/src/cli/commands/register-detect.ts
index cb1f4636..23a66812 100644
--- a/src/cli/commands/register-detect.ts
+++ b/src/cli/commands/register-detect.ts
@@ -2,14 +2,17 @@ import { Option, type Command } from 'commander';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
 import { readStdin } from '../../utils/read-stdin.js';
-import { createDetectCommand, type CreateDeepLClient } from './service-factory.js';
+import {
+  createDetectCommand,
+  type CreateDeepLClient,
+} from './service-factory.js';
 
 export function registerDetect(
   program: Command,
   deps: {
     createDeepLClient: CreateDeepLClient;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { createDeepLClient, handleError } = deps;
 
@@ -17,13 +20,20 @@ export function registerDetect(
     .command('detect')
     .description('Detect the language of text using DeepL API')
     .argument('[text]', 'Text to detect language of (or read from stdin)')
-    .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-    .addHelpText('after', `
+    .addOption(
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
+    )
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl detect "Bonjour le monde"
   $ deepl detect "Hallo Welt" --format json
   $ echo "Ciao mondo" | deepl detect
-`)
+`
+    )
     .action(async (text: string | undefined, options: { format?: string }) => {
       try {
         const detectCommand = await createDetectCommand(createDeepLClient);
@@ -35,7 +45,9 @@ Examples:
         } else {
           inputText = await readStdin();
           if (!inputText || inputText.trim() === '') {
-            throw new ValidationError('No input provided. Provide text as an argument or pipe via stdin.');
+            throw new ValidationError(
+              'No input provided. Provide text as an argument or pipe via stdin.'
+            );
           }
         }
 
diff --git a/src/cli/commands/register-glossary.ts b/src/cli/commands/register-glossary.ts
index fc5e7a22..474c1e6e 100644
--- a/src/cli/commands/register-glossary.ts
+++ b/src/cli/commands/register-glossary.ts
@@ -7,14 +7,16 @@ import { createGlossaryCommand, type ServiceDeps } from './service-factory.js';
 
 export function registerGlossary(
   program: Command,
-  deps: Pick<ServiceDeps, 'createDeepLClient' | 'handleError'>,
+  deps: Pick<ServiceDeps, 'createDeepLClient' | 'handleError'>
 ): void {
   const { createDeepLClient, handleError } = deps;
 
   program
     .command('glossary')
     .description('Manage translation glossaries')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl glossary create my-terms en de terms.tsv
   $ deepl glossary create my-terms en de,fr,es terms.tsv
@@ -30,36 +32,61 @@ Examples:
   $ deepl glossary update my-terms --name new-name --target-lang de --file updated.tsv
   $ deepl glossary replace-dictionary my-terms de updated.tsv
   $ deepl glossary delete-dictionary my-terms de --yes
-`)
+`
+    )
     .addCommand(
       new Command('create')
         .description('Create a glossary from TSV/CSV file')
         .argument('<name>', 'Glossary name')
         .argument('<source-lang>', 'Source language code')
-        .argument('<target-lang>', 'Target language code (comma-separated for multiple, e.g. de,fr,es)')
+        .argument(
+          '<target-lang>',
+          'Target language code (comma-separated for multiple, e.g. de,fr,es)'
+        )
         .argument('<file>', 'TSV/CSV file path')
-        .action(async (name: string, sourceLang: string, targetLang: string, file: string) => {
-          try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
-
-            const targetLangs = targetLang.split(',').map(l => l.trim()) as Language[];
-
-            const glossary = await glossaryCommand.create(name, sourceLang as Language, targetLangs, file);
-            Logger.output(chalk.green('\u2713 Glossary created successfully'));
-            Logger.output(glossaryCommand.formatGlossaryInfo(glossary));
-          } catch (error) {
-            handleError(error);
-
+        .action(
+          async (
+            name: string,
+            sourceLang: string,
+            targetLang: string,
+            file: string
+          ) => {
+            try {
+              const glossaryCommand =
+                await createGlossaryCommand(createDeepLClient);
+
+              const targetLangs = targetLang
+                .split(',')
+                .map((l) => l.trim()) as Language[];
+
+              const glossary = await glossaryCommand.create(
+                name,
+                sourceLang as Language,
+                targetLangs,
+                file
+              );
+              Logger.output(
+                chalk.green('\u2713 Glossary created successfully')
+              );
+              Logger.output(glossaryCommand.formatGlossaryInfo(glossary));
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     )
     .addCommand(
       new Command('list')
         .description('List all glossaries')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
         .action(async (options: { format?: string }) => {
           try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
+            const glossaryCommand =
+              await createGlossaryCommand(createDeepLClient);
 
             const glossaries = await glossaryCommand.list();
             if (options.format === 'json') {
@@ -69,7 +96,6 @@ Examples:
             }
           } catch (error) {
             handleError(error);
-
           }
         })
     )
@@ -77,10 +103,15 @@ Examples:
       new Command('show')
         .description('Show glossary details')
         .argument('<name-or-id>', 'Glossary name or ID')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
         .action(async (nameOrId: string, options: { format?: string }) => {
           try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
+            const glossaryCommand =
+              await createGlossaryCommand(createDeepLClient);
 
             const glossary = await glossaryCommand.show(nameOrId);
             if (options.format === 'json') {
@@ -90,7 +121,6 @@ Examples:
             }
           } catch (error) {
             handleError(error);
-
           }
         })
     )
@@ -98,73 +128,102 @@ Examples:
       new Command('entries')
         .description('Show glossary entries')
         .argument('<name-or-id>', 'Glossary name or ID')
-        .option('--target-lang <lang>', 'Target language (required for multilingual glossaries)')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-        .action(async (nameOrId: string, options: { targetLang?: string; format?: string }) => {
-          try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
-
-            const targetLang = options.targetLang as Language | undefined;
-            const entries = await glossaryCommand.entries(nameOrId, targetLang);
-            if (options.format === 'json') {
-              Logger.output(JSON.stringify(entries, null, 2));
-            } else {
-              Logger.output(glossaryCommand.formatEntries(entries));
+        .option(
+          '--target-lang <lang>',
+          'Target language (required for multilingual glossaries)'
+        )
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
+        .action(
+          async (
+            nameOrId: string,
+            options: { targetLang?: string; format?: string }
+          ) => {
+            try {
+              const glossaryCommand =
+                await createGlossaryCommand(createDeepLClient);
+
+              const targetLang = options.targetLang as Language | undefined;
+              const entries = await glossaryCommand.entries(
+                nameOrId,
+                targetLang
+              );
+              if (options.format === 'json') {
+                Logger.output(JSON.stringify(entries, null, 2));
+              } else {
+                Logger.output(glossaryCommand.formatEntries(entries));
+              }
+            } catch (error) {
+              handleError(error);
             }
-          } catch (error) {
-            handleError(error);
-
           }
-        })
+        )
     )
     .addCommand(
       new Command('delete')
         .description('Delete a glossary')
         .argument('<name-or-id>', 'Glossary name or ID')
         .option('-y, --yes', 'Skip confirmation prompt')
-        .option('--dry-run', 'Show what would be deleted without performing the operation')
-        .action(async (nameOrId: string, options: { yes?: boolean; dryRun?: boolean }) => {
-          try {
-            if (options.dryRun) {
-              const lines = [
-                chalk.yellow(`[dry-run] No deletions will be performed.`),
-                chalk.yellow(`[dry-run] Would delete glossary: "${nameOrId}"`),
-              ];
-              Logger.output(lines.join('\n'));
-              return;
-            }
-
-            if (!options.yes) {
-              const { confirm } = await import('../../utils/confirm.js');
-              const confirmed = await confirm({ message: `Delete glossary "${nameOrId}"?` });
-              if (!confirmed) {
-                Logger.info('Aborted.');
+        .option(
+          '--dry-run',
+          'Show what would be deleted without performing the operation'
+        )
+        .action(
+          async (
+            nameOrId: string,
+            options: { yes?: boolean; dryRun?: boolean }
+          ) => {
+            try {
+              if (options.dryRun) {
+                const lines = [
+                  chalk.yellow(`[dry-run] No deletions will be performed.`),
+                  chalk.yellow(
+                    `[dry-run] Would delete glossary: "${nameOrId}"`
+                  ),
+                ];
+                Logger.output(lines.join('\n'));
                 return;
               }
-            }
 
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
+              if (!options.yes) {
+                const { confirm } = await import('../../utils/confirm.js');
+                const confirmed = await confirm({
+                  message: `Delete glossary "${nameOrId}"?`,
+                });
+                if (!confirmed) {
+                  Logger.info('Aborted.');
+                  return;
+                }
+              }
 
-            await glossaryCommand.delete(nameOrId);
-            Logger.success(chalk.green('\u2713 Glossary deleted successfully'));
-          } catch (error) {
-            handleError(error);
+              const glossaryCommand =
+                await createGlossaryCommand(createDeepLClient);
 
+              await glossaryCommand.delete(nameOrId);
+              Logger.success(
+                chalk.green('\u2713 Glossary deleted successfully')
+              );
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     )
     .addCommand(
       new Command('languages')
         .description('List supported glossary language pairs')
         .action(async () => {
           try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
+            const glossaryCommand =
+              await createGlossaryCommand(createDeepLClient);
 
             const pairs = await glossaryCommand.listLanguages();
             Logger.output(glossaryCommand.formatLanguagePairs(pairs));
           } catch (error) {
             handleError(error);
-
           }
         })
     )
@@ -174,19 +233,34 @@ Examples:
         .argument('<name-or-id>', 'Glossary name or ID')
         .argument('<source>', 'Source text')
         .argument('<target>', 'Target text')
-        .option('--target-lang <lang>', 'Target language (required for multilingual glossaries)')
-        .action(async (nameOrId: string, source: string, target: string, options: { targetLang?: string }) => {
-          try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
-
-            const targetLang = options.targetLang as Language | undefined;
-            await glossaryCommand.addEntry(nameOrId, source, target, targetLang);
-            Logger.success(chalk.green('\u2713 Entry added successfully'));
-          } catch (error) {
-            handleError(error);
-
+        .option(
+          '--target-lang <lang>',
+          'Target language (required for multilingual glossaries)'
+        )
+        .action(
+          async (
+            nameOrId: string,
+            source: string,
+            target: string,
+            options: { targetLang?: string }
+          ) => {
+            try {
+              const glossaryCommand =
+                await createGlossaryCommand(createDeepLClient);
+
+              const targetLang = options.targetLang as Language | undefined;
+              await glossaryCommand.addEntry(
+                nameOrId,
+                source,
+                target,
+                targetLang
+              );
+              Logger.success(chalk.green('\u2713 Entry added successfully'));
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     )
     .addCommand(
       new Command('update-entry')
@@ -194,38 +268,62 @@ Examples:
         .argument('<name-or-id>', 'Glossary name or ID')
         .argument('<source>', 'Source text to update')
         .argument('<new-target>', 'New target text')
-        .option('--target-lang <lang>', 'Target language (required for multilingual glossaries)')
-        .action(async (nameOrId: string, source: string, newTarget: string, options: { targetLang?: string }) => {
-          try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
-
-            const targetLang = options.targetLang as Language | undefined;
-            await glossaryCommand.updateEntry(nameOrId, source, newTarget, targetLang);
-            Logger.success(chalk.green('\u2713 Entry updated successfully'));
-          } catch (error) {
-            handleError(error);
-
+        .option(
+          '--target-lang <lang>',
+          'Target language (required for multilingual glossaries)'
+        )
+        .action(
+          async (
+            nameOrId: string,
+            source: string,
+            newTarget: string,
+            options: { targetLang?: string }
+          ) => {
+            try {
+              const glossaryCommand =
+                await createGlossaryCommand(createDeepLClient);
+
+              const targetLang = options.targetLang as Language | undefined;
+              await glossaryCommand.updateEntry(
+                nameOrId,
+                source,
+                newTarget,
+                targetLang
+              );
+              Logger.success(chalk.green('\u2713 Entry updated successfully'));
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     )
     .addCommand(
       new Command('remove-entry')
         .description('Remove an entry from a glossary')
         .argument('<name-or-id>', 'Glossary name or ID')
         .argument('<source>', 'Source text to remove')
-        .option('--target-lang <lang>', 'Target language (required for multilingual glossaries)')
-        .action(async (nameOrId: string, source: string, options: { targetLang?: string }) => {
-          try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
-
-            const targetLang = options.targetLang as Language | undefined;
-            await glossaryCommand.removeEntry(nameOrId, source, targetLang);
-            Logger.success(chalk.green('\u2713 Entry removed successfully'));
-          } catch (error) {
-            handleError(error);
-
+        .option(
+          '--target-lang <lang>',
+          'Target language (required for multilingual glossaries)'
+        )
+        .action(
+          async (
+            nameOrId: string,
+            source: string,
+            options: { targetLang?: string }
+          ) => {
+            try {
+              const glossaryCommand =
+                await createGlossaryCommand(createDeepLClient);
+
+              const targetLang = options.targetLang as Language | undefined;
+              await glossaryCommand.removeEntry(nameOrId, source, targetLang);
+              Logger.success(chalk.green('\u2713 Entry removed successfully'));
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     )
     .addCommand(
       new Command('rename')
@@ -234,84 +332,121 @@ Examples:
         .argument('<new-name>', 'New glossary name')
         .action(async (nameOrId: string, newName: string) => {
           try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
+            const glossaryCommand =
+              await createGlossaryCommand(createDeepLClient);
 
             await glossaryCommand.rename(nameOrId, newName);
             Logger.success(chalk.green('\u2713 Glossary renamed successfully'));
           } catch (error) {
             handleError(error);
-
           }
         })
     )
     .addCommand(
       new Command('update')
-        .description('Update glossary name and/or dictionary entries in a single request')
+        .description(
+          'Update glossary name and/or dictionary entries in a single request'
+        )
         .argument('<name-or-id>', 'Glossary name or ID')
         .option('--name <name>', 'New glossary name')
         .option('--target-lang <lang>', 'Target language for dictionary update')
-        .option('--file <path>', 'TSV/CSV file with entries for dictionary update')
-        .action(async (nameOrId: string, options: { name?: string; targetLang?: string; file?: string }) => {
-          try {
-            if (!options.name && !options.file) {
-              throw new ValidationError('At least one of --name or --file (with --target-lang) must be provided');
-            }
-
-            if (options.file && !options.targetLang) {
-              throw new ValidationError('--target-lang is required when using --file');
-            }
+        .option(
+          '--file <path>',
+          'TSV/CSV file with entries for dictionary update'
+        )
+        .action(
+          async (
+            nameOrId: string,
+            options: { name?: string; targetLang?: string; file?: string }
+          ) => {
+            try {
+              if (!options.name && !options.file) {
+                throw new ValidationError(
+                  'At least one of --name or --file (with --target-lang) must be provided'
+                );
+              }
 
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
+              if (options.file && !options.targetLang) {
+                throw new ValidationError(
+                  '--target-lang is required when using --file'
+                );
+              }
 
-            const updateOptions: {
-              name?: string;
-              dictionaries?: Array<{ targetLang: Language; entries: Record<string, string> }>;
-            } = {};
+              const glossaryCommand =
+                await createGlossaryCommand(createDeepLClient);
 
-            if (options.name) {
-              updateOptions.name = options.name;
-            }
+              const updateOptions: {
+                name?: string;
+                dictionaries?: Array<{
+                  targetLang: Language;
+                  entries: Record<string, string>;
+                }>;
+              } = {};
 
-            if (options.file && options.targetLang) {
-              const fs = await import('fs');
-              if (!fs.existsSync(options.file)) {
-                throw new ValidationError(`File not found: ${options.file}`);
+              if (options.name) {
+                updateOptions.name = options.name;
               }
-              const { safeReadFileSync } = await import('../../utils/safe-read-file.js');
-              const content = safeReadFileSync(options.file, 'utf-8');
-              const { GlossaryService } = await import('../../services/glossary.js');
-              const entries = GlossaryService.tsvToEntries(content);
-              if (Object.keys(entries).length === 0) {
-                throw new ValidationError('No valid entries found in file');
+
+              if (options.file && options.targetLang) {
+                const fs = await import('fs');
+                if (!fs.existsSync(options.file)) {
+                  throw new ValidationError(`File not found: ${options.file}`);
+                }
+                const { safeReadFileSync } =
+                  await import('../../utils/safe-read-file.js');
+                const content = safeReadFileSync(options.file, 'utf-8');
+                const { GlossaryService } =
+                  await import('../../services/glossary.js');
+                const entries = GlossaryService.tsvToEntries(content);
+                if (Object.keys(entries).length === 0) {
+                  throw new ValidationError('No valid entries found in file');
+                }
+                updateOptions.dictionaries = [
+                  {
+                    targetLang: options.targetLang as Language,
+                    entries,
+                  },
+                ];
               }
-              updateOptions.dictionaries = [{
-                targetLang: options.targetLang as Language,
-                entries,
-              }];
-            }
 
-            await glossaryCommand.update(nameOrId, updateOptions);
-            const parts: string[] = [];
-            if (options.name) parts.push('renamed');
-            if (options.file) parts.push('dictionary updated');
-            Logger.success(chalk.green(`\u2713 Glossary ${parts.join(' and ')} successfully`));
-          } catch (error) {
-            handleError(error);
+              await glossaryCommand.update(nameOrId, updateOptions);
+              const parts: string[] = [];
+              if (options.name) parts.push('renamed');
+              if (options.file) parts.push('dictionary updated');
+              Logger.success(
+                chalk.green(
+                  `\u2713 Glossary ${parts.join(' and ')} successfully`
+                )
+              );
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     )
     .addCommand(
       new Command('replace-dictionary')
-        .description('Replace all entries in a glossary dictionary from a TSV/CSV file')
+        .description(
+          'Replace all entries in a glossary dictionary from a TSV/CSV file'
+        )
         .argument('<name-or-id>', 'Glossary name or ID')
         .argument('<target-lang>', 'Target language of dictionary to replace')
         .argument('<file>', 'TSV/CSV file with replacement entries')
         .action(async (nameOrId: string, targetLang: string, file: string) => {
           try {
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
-
-            await glossaryCommand.replaceDictionary(nameOrId, targetLang as Language, file);
-            Logger.success(chalk.green(`\u2713 Dictionary replaced successfully (${targetLang})`));
+            const glossaryCommand =
+              await createGlossaryCommand(createDeepLClient);
+
+            await glossaryCommand.replaceDictionary(
+              nameOrId,
+              targetLang as Language,
+              file
+            );
+            Logger.success(
+              chalk.green(
+                `\u2713 Dictionary replaced successfully (${targetLang})`
+              )
+            );
           } catch (error) {
             handleError(error);
           }
@@ -323,25 +458,40 @@ Examples:
         .argument('<name-or-id>', 'Glossary name or ID')
         .argument('<target-lang>', 'Target language of dictionary to delete')
         .option('-y, --yes', 'Skip confirmation prompt')
-        .action(async (nameOrId: string, targetLang: string, options: { yes?: boolean }) => {
-          try {
-            if (!options.yes) {
-              const { confirm } = await import('../../utils/confirm.js');
-              const confirmed = await confirm({ message: `Delete dictionary "${targetLang}" from glossary "${nameOrId}"?` });
-              if (!confirmed) {
-                Logger.info('Aborted.');
-                return;
+        .action(
+          async (
+            nameOrId: string,
+            targetLang: string,
+            options: { yes?: boolean }
+          ) => {
+            try {
+              if (!options.yes) {
+                const { confirm } = await import('../../utils/confirm.js');
+                const confirmed = await confirm({
+                  message: `Delete dictionary "${targetLang}" from glossary "${nameOrId}"?`,
+                });
+                if (!confirmed) {
+                  Logger.info('Aborted.');
+                  return;
+                }
               }
-            }
-
-            const glossaryCommand = await createGlossaryCommand(createDeepLClient);
-
-            await glossaryCommand.deleteDictionary(nameOrId, targetLang as Language);
-            Logger.success(chalk.green(`\u2713 Dictionary deleted successfully (${targetLang})`));
-          } catch (error) {
-            handleError(error);
 
+              const glossaryCommand =
+                await createGlossaryCommand(createDeepLClient);
+
+              await glossaryCommand.deleteDictionary(
+                nameOrId,
+                targetLang as Language
+              );
+              Logger.success(
+                chalk.green(
+                  `\u2713 Dictionary deleted successfully (${targetLang})`
+                )
+              );
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     );
 }
diff --git a/src/cli/commands/register-hooks.ts b/src/cli/commands/register-hooks.ts
index a7dd423f..1f982c93 100644
--- a/src/cli/commands/register-hooks.ts
+++ b/src/cli/commands/register-hooks.ts
@@ -6,25 +6,31 @@ export function registerHooks(
   program: Command,
   deps: {
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { handleError } = deps;
 
   program
     .command('hooks')
     .description('Manage git hooks for translation workflow')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl hooks install pre-commit
   $ deepl hooks install post-commit
   $ deepl hooks uninstall pre-commit
   $ deepl hooks list
   $ deepl hooks path pre-commit
-`)
+`
+    )
     .addCommand(
       new Command('install')
         .description('Install a git hook')
-        .argument('<hook-type>', 'Hook type: pre-commit, pre-push, commit-msg, or post-commit')
+        .argument(
+          '<hook-type>',
+          'Hook type: pre-commit, pre-push, commit-msg, or post-commit'
+        )
         .action(async (hookType: string) => {
           try {
             const { HooksCommand } = await import('./hooks.js');
@@ -33,14 +39,16 @@ Examples:
             Logger.output(result);
           } catch (error) {
             handleError(error);
-
           }
         })
     )
     .addCommand(
       new Command('uninstall')
         .description('Uninstall a git hook')
-        .argument('<hook-type>', 'Hook type: pre-commit, pre-push, commit-msg, or post-commit')
+        .argument(
+          '<hook-type>',
+          'Hook type: pre-commit, pre-push, commit-msg, or post-commit'
+        )
         .action(async (hookType: string) => {
           try {
             const { HooksCommand } = await import('./hooks.js');
@@ -49,14 +57,17 @@ Examples:
             Logger.output(result);
           } catch (error) {
             handleError(error);
-
           }
         })
     )
     .addCommand(
       new Command('list')
         .description('List all hooks and their status')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
         .action(async (options: { format?: string }) => {
           try {
             const { HooksCommand } = await import('./hooks.js');
@@ -70,14 +81,16 @@ Examples:
             }
           } catch (error) {
             handleError(error);
-
           }
         })
     )
     .addCommand(
       new Command('path')
         .description('Show path to a hook file')
-        .argument('<hook-type>', 'Hook type: pre-commit, pre-push, commit-msg, or post-commit')
+        .argument(
+          '<hook-type>',
+          'Hook type: pre-commit, pre-push, commit-msg, or post-commit'
+        )
         .action(async (hookType: string) => {
           try {
             const { HooksCommand } = await import('./hooks.js');
@@ -86,7 +99,6 @@ Examples:
             Logger.output(result);
           } catch (error) {
             handleError(error);
-
           }
         })
     );
diff --git a/src/cli/commands/register-init.ts b/src/cli/commands/register-init.ts
index 3651648e..c69ea4fc 100644
--- a/src/cli/commands/register-init.ts
+++ b/src/cli/commands/register-init.ts
@@ -10,28 +10,43 @@ export function registerInit(
     getConfigService: () => ConfigService;
     getHttpOptions?: () => DeepLClientOptions;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { getConfigService, getHttpOptions, handleError } = deps;
 
   program
     .command('init')
     .description('Interactive setup wizard for first-time configuration')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl init
-`)
+`
+    )
     .action(async () => {
       try {
         if (isNoInput() || !process.stdin.isTTY) {
-          throw new ValidationError('init is not supported in non-interactive mode. Use deepl auth set-key <your-api-key> to configure authentication.');
+          throw new ValidationError(
+            'init is not supported in non-interactive mode. Use deepl auth set-key <your-api-key> to configure authentication.'
+          );
         }
         const { InitCommand } = await import('./init.js');
-        const initCommand = new InitCommand(getConfigService(), getHttpOptions?.());
+        const initCommand = new InitCommand(
+          getConfigService(),
+          getHttpOptions?.()
+        );
         await initCommand.run();
       } catch (error) {
-        if (error instanceof Error && error.message.includes('Authentication failed')) {
-          handleError(new AuthError('Invalid API key: Authentication failed with DeepL API'));
+        if (
+          error instanceof Error &&
+          error.message.includes('Authentication failed')
+        ) {
+          handleError(
+            new AuthError(
+              'Invalid API key: Authentication failed with DeepL API'
+            )
+          );
         }
         handleError(error);
       }
diff --git a/src/cli/commands/register-languages.ts b/src/cli/commands/register-languages.ts
index 3cc0243f..4048c2d9 100644
--- a/src/cli/commands/register-languages.ts
+++ b/src/cli/commands/register-languages.ts
@@ -3,15 +3,21 @@ import chalk from 'chalk';
 import type { ConfigService } from '../../storage/config.js';
 import type { LanguageInfo } from '../../api/deepl-client.js';
 import { Logger } from '../../utils/logger.js';
-import { createLanguagesCommand, type CreateDeepLClient } from './service-factory.js';
+import {
+  createLanguagesCommand,
+  type CreateDeepLClient,
+} from './service-factory.js';
 
 /**
  * The features matrix rides along on every LanguageInfo, so it is stripped from
  * JSON unless asked for; existing consumers keep the shape they were written to.
  */
-function forJson(languages: LanguageInfo[], includeFeatures: boolean): unknown[] {
+function forJson(
+  languages: LanguageInfo[],
+  includeFeatures: boolean
+): unknown[] {
   if (includeFeatures) return languages;
-  return languages.map(language => {
+  return languages.map((language) => {
     const copy = { ...language };
     delete copy.features;
     return copy;
@@ -23,10 +29,14 @@ function forJson(languages: LanguageInfo[], includeFeatures: boolean): unknown[]
  * JSON lists the same languages the text and table formats read from it.
  */
 function registryAsLanguageInfo(
-  command: { getRegistryLanguages: (type: 'source' | 'target') => Array<{ code: string; name: string }> },
-  type: 'source' | 'target',
+  command: {
+    getRegistryLanguages: (
+      type: 'source' | 'target'
+    ) => Array<{ code: string; name: string }>;
+  },
+  type: 'source' | 'target'
 ): LanguageInfo[] {
-  return command.getRegistryLanguages(type).map(entry => ({
+  return command.getRegistryLanguages(type).map((entry) => ({
     language: entry.code as LanguageInfo['language'],
     name: entry.name,
   }));
@@ -38,7 +48,7 @@ export function registerLanguages(
     getConfigService: () => ConfigService;
     createDeepLClient: CreateDeepLClient;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { getConfigService, createDeepLClient, handleError } = deps;
 
@@ -47,9 +57,18 @@ export function registerLanguages(
     .description('List supported source and target languages')
     .option('-s, --source', 'Show only source languages')
     .option('--target', 'Show only target languages')
-    .option('--features', 'Show per-language feature support (requires an API key)')
-    .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json', 'table']).default('text'))
-    .addHelpText('after', `
+    .option(
+      '--features',
+      'Show per-language feature support (requires an API key)'
+    )
+    .addOption(
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json', 'table'])
+        .default('text')
+    )
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl languages
   $ deepl languages --source
@@ -58,85 +77,151 @@ Examples:
   $ deepl languages --target --features --format table
   $ deepl languages --format json
   $ deepl languages --format table
-`)
-    .action(async (options: { source?: boolean; target?: boolean; features?: boolean; format?: string }) => {
-      try {
-        const apiKey = getConfigService().getValue<string>('auth.apiKey');
-        const envKey = process.env['DEEPL_API_KEY'];
-        const hasApiKey = !!(apiKey ?? envKey);
-        const showFeatures = !!options.features;
+`
+    )
+    .action(
+      async (options: {
+        source?: boolean;
+        target?: boolean;
+        features?: boolean;
+        format?: string;
+      }) => {
+        try {
+          const apiKey = getConfigService().getValue<string>('auth.apiKey');
+          const envKey = process.env['DEEPL_API_KEY'];
+          const hasApiKey = !!(apiKey ?? envKey);
+          const showFeatures = !!options.features;
 
-        let client = null;
-        if (hasApiKey) {
-          client = await createDeepLClient();
-        } else {
-          Logger.warn(chalk.yellow('Note: No API key configured. Showing local language registry only.'));
-          Logger.warn(chalk.yellow('Run: deepl auth set-key <your-api-key> for API-verified names.\n'));
-          if (showFeatures) {
-            Logger.warn(chalk.yellow('Note: --features needs an API key; the local registry carries no feature data.\n'));
+          let client = null;
+          if (hasApiKey) {
+            client = await createDeepLClient();
+          } else {
+            Logger.warn(
+              chalk.yellow(
+                'Note: No API key configured. Showing local language registry only.'
+              )
+            );
+            Logger.warn(
+              chalk.yellow(
+                'Run: deepl auth set-key <your-api-key> for API-verified names.\n'
+              )
+            );
+            if (showFeatures) {
+              Logger.warn(
+                chalk.yellow(
+                  'Note: --features needs an API key; the local registry carries no feature data.\n'
+                )
+              );
+            }
           }
-        }
 
-        const languagesCommand = await createLanguagesCommand(client);
+          const languagesCommand = await createLanguagesCommand(client);
+
+          if (options.format === 'json') {
+            const listFor = async (
+              type: 'source' | 'target'
+            ): Promise<LanguageInfo[]> => {
+              const fromApi =
+                type === 'source'
+                  ? await languagesCommand.getSourceLanguages()
+                  : await languagesCommand.getTargetLanguages();
+              return fromApi.length === 0 && !hasApiKey
+                ? registryAsLanguageInfo(languagesCommand, type)
+                : fromApi;
+            };
+
+            if (options.source && !options.target) {
+              Logger.output(
+                JSON.stringify(
+                  forJson(await listFor('source'), showFeatures),
+                  null,
+                  2
+                )
+              );
+            } else if (options.target && !options.source) {
+              Logger.output(
+                JSON.stringify(
+                  forJson(await listFor('target'), showFeatures),
+                  null,
+                  2
+                )
+              );
+            } else {
+              const [sourceLanguages, targetLanguages] = await Promise.all([
+                listFor('source'),
+                listFor('target'),
+              ]);
+              Logger.output(
+                JSON.stringify(
+                  {
+                    source: forJson(sourceLanguages, showFeatures),
+                    target: forJson(targetLanguages, showFeatures),
+                  },
+                  null,
+                  2
+                )
+              );
+            }
+            return;
+          }
 
-        if (options.format === 'json') {
-          const listFor = async (type: 'source' | 'target'): Promise<LanguageInfo[]> => {
-            const fromApi =
-              type === 'source'
-                ? await languagesCommand.getSourceLanguages()
-                : await languagesCommand.getTargetLanguages();
-            return fromApi.length === 0 && !hasApiKey
-              ? registryAsLanguageInfo(languagesCommand, type)
-              : fromApi;
-          };
+          const useTable = options.format === 'table';
+          if (useTable && !process.stdout.isTTY) {
+            Logger.warn(
+              'WARN  --format table is not supported in non-TTY output; falling back to plain text'
+            );
+          }
+          const wantTable = useTable && process.stdout.isTTY;
 
+          let output: string;
           if (options.source && !options.target) {
-            Logger.output(JSON.stringify(forJson(await listFor('source'), showFeatures), null, 2));
+            const sourceLanguages = await languagesCommand.getSourceLanguages();
+            output = wantTable
+              ? languagesCommand.formatLanguagesTable(
+                  sourceLanguages,
+                  'source',
+                  showFeatures
+                )
+              : languagesCommand.formatLanguages(
+                  sourceLanguages,
+                  'source',
+                  showFeatures
+                );
           } else if (options.target && !options.source) {
-            Logger.output(JSON.stringify(forJson(await listFor('target'), showFeatures), null, 2));
+            const targetLanguages = await languagesCommand.getTargetLanguages();
+            output = wantTable
+              ? languagesCommand.formatLanguagesTable(
+                  targetLanguages,
+                  'target',
+                  showFeatures
+                )
+              : languagesCommand.formatLanguages(
+                  targetLanguages,
+                  'target',
+                  showFeatures
+                );
           } else {
             const [sourceLanguages, targetLanguages] = await Promise.all([
-              listFor('source'),
-              listFor('target'),
+              languagesCommand.getSourceLanguages(),
+              languagesCommand.getTargetLanguages(),
             ]);
-            Logger.output(JSON.stringify({
-              source: forJson(sourceLanguages, showFeatures),
-              target: forJson(targetLanguages, showFeatures),
-            }, null, 2));
+            output = wantTable
+              ? languagesCommand.formatAllLanguagesTable(
+                  sourceLanguages,
+                  targetLanguages,
+                  showFeatures
+                )
+              : languagesCommand.formatAllLanguages(
+                  sourceLanguages,
+                  targetLanguages,
+                  showFeatures
+                );
           }
-          return;
-        }
 
-        const useTable = options.format === 'table';
-        if (useTable && !process.stdout.isTTY) {
-          Logger.warn('WARN  --format table is not supported in non-TTY output; falling back to plain text');
+          Logger.output(output);
+        } catch (error) {
+          handleError(error);
         }
-        const wantTable = useTable && process.stdout.isTTY;
-
-        let output: string;
-        if (options.source && !options.target) {
-          const sourceLanguages = await languagesCommand.getSourceLanguages();
-          output = wantTable
-            ? languagesCommand.formatLanguagesTable(sourceLanguages, 'source', showFeatures)
-            : languagesCommand.formatLanguages(sourceLanguages, 'source', showFeatures);
-        } else if (options.target && !options.source) {
-          const targetLanguages = await languagesCommand.getTargetLanguages();
-          output = wantTable
-            ? languagesCommand.formatLanguagesTable(targetLanguages, 'target', showFeatures)
-            : languagesCommand.formatLanguages(targetLanguages, 'target', showFeatures);
-        } else {
-          const [sourceLanguages, targetLanguages] = await Promise.all([
-            languagesCommand.getSourceLanguages(),
-            languagesCommand.getTargetLanguages(),
-          ]);
-          output = wantTable
-            ? languagesCommand.formatAllLanguagesTable(sourceLanguages, targetLanguages, showFeatures)
-            : languagesCommand.formatAllLanguages(sourceLanguages, targetLanguages, showFeatures);
-        }
-
-        Logger.output(output);
-      } catch (error) {
-        handleError(error);
       }
-    });
+    );
 }
diff --git a/src/cli/commands/register-style-rules.ts b/src/cli/commands/register-style-rules.ts
index 00b27dde..b0c17f5c 100644
--- a/src/cli/commands/register-style-rules.ts
+++ b/src/cli/commands/register-style-rules.ts
@@ -2,8 +2,15 @@ import { Command, Option } from 'commander';
 import chalk from 'chalk';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
-import type { ConfiguredRules, CreateCustomInstructionOptions, UpdateCustomInstructionOptions } from '../../types/index.js';
-import { createStyleRulesCommand, type CreateDeepLClient } from './service-factory.js';
+import type {
+  ConfiguredRules,
+  CreateCustomInstructionOptions,
+  UpdateCustomInstructionOptions,
+} from '../../types/index.js';
+import {
+  createStyleRulesCommand,
+  type CreateDeepLClient,
+} from './service-factory.js';
 
 /**
  * Parse `--rules` into the configured-rules dictionary the API expects:
@@ -16,27 +23,37 @@ function parseRulesArg(input: string): ConfiguredRules {
   try {
     parsed = JSON.parse(trimmed);
   } catch (error) {
-    throw new ValidationError(`--rules JSON is malformed: ${(error as Error).message}`);
+    throw new ValidationError(
+      `--rules JSON is malformed: ${(error as Error).message}`
+    );
   }
 
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     throw new ValidationError(
-      '--rules must be a JSON object of category → settings, e.g. \'{"punctuation":{"quotation_mark":"use_guillemets"}}\'',
+      '--rules must be a JSON object of category → settings, e.g. \'{"punctuation":{"quotation_mark":"use_guillemets"}}\''
     );
   }
 
   const result: ConfiguredRules = {};
-  for (const [category, settings] of Object.entries(parsed as Record<string, unknown>)) {
-    if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+  for (const [category, settings] of Object.entries(
+    parsed as Record<string, unknown>
+  )) {
+    if (
+      typeof settings !== 'object' ||
+      settings === null ||
+      Array.isArray(settings)
+    ) {
       throw new ValidationError(
-        `--rules category "${category}" must map to an object of setting → value`,
+        `--rules category "${category}" must map to an object of setting → value`
       );
     }
     const inner: Record<string, string> = {};
-    for (const [key, value] of Object.entries(settings as Record<string, unknown>)) {
+    for (const [key, value] of Object.entries(
+      settings as Record<string, unknown>
+    )) {
       if (typeof value !== 'string') {
         throw new ValidationError(
-          `--rules setting "${category}.${key}" must be a string`,
+          `--rules setting "${category}.${key}" must be a string`
         );
       }
       inner[key] = value;
@@ -51,14 +68,16 @@ export function registerStyleRules(
   deps: {
     createDeepLClient: CreateDeepLClient;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { createDeepLClient, handleError } = deps;
 
   program
     .command('style-rules')
     .description('Manage DeepL style rules (Pro API only)')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl style-rules list
   $ deepl style-rules list --detailed
@@ -74,191 +93,291 @@ Examples:
   $ deepl style-rules add-instruction sr-abc123 tone "Be formal"
   $ deepl style-rules update-instruction sr-abc123 tone "Be friendlier"
   $ deepl style-rules remove-instruction sr-abc123 tone --yes
-`)
+`
+    )
     .addCommand(
       new Command('list')
         .description('List all style rules')
-        .option('--detailed', 'Show detailed information including configured rules and custom instructions')
+        .option(
+          '--detailed',
+          'Show detailed information including configured rules and custom instructions'
+        )
         .option('--page <number>', 'Page number for pagination', parseInt)
-        .option('--page-size <number>', 'Number of results per page (1-25)', parseInt)
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json', 'table']).default('text'))
-        .action(async (options: {
-          detailed?: boolean;
-          page?: number;
-          pageSize?: number;
-          format?: string;
-        }) => {
-          try {
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
+        .option(
+          '--page-size <number>',
+          'Number of results per page (1-25)',
+          parseInt
+        )
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json', 'table'])
+            .default('text')
+        )
+        .action(
+          async (options: {
+            detailed?: boolean;
+            page?: number;
+            pageSize?: number;
+            format?: string;
+          }) => {
+            try {
+              const styleRulesCommand =
+                await createStyleRulesCommand(createDeepLClient);
 
-            const rules = await styleRulesCommand.list({
-              detailed: options.detailed,
-              page: options.page,
-              pageSize: options.pageSize,
-            });
+              const rules = await styleRulesCommand.list({
+                detailed: options.detailed,
+                page: options.page,
+                pageSize: options.pageSize,
+              });
 
-            if (options.format === 'json') {
-              Logger.output(styleRulesCommand.formatStyleRulesJson(rules));
-            } else if (options.format === 'table') {
-              if (!process.stdout.isTTY) {
-                Logger.warn('WARN  --format table is not supported in non-TTY output; falling back to plain text');
-                Logger.output(styleRulesCommand.formatStyleRulesList(rules));
+              if (options.format === 'json') {
+                Logger.output(styleRulesCommand.formatStyleRulesJson(rules));
+              } else if (options.format === 'table') {
+                if (!process.stdout.isTTY) {
+                  Logger.warn(
+                    'WARN  --format table is not supported in non-TTY output; falling back to plain text'
+                  );
+                  Logger.output(styleRulesCommand.formatStyleRulesList(rules));
+                } else {
+                  Logger.output(styleRulesCommand.formatStyleRulesTable(rules));
+                }
               } else {
-                Logger.output(styleRulesCommand.formatStyleRulesTable(rules));
+                Logger.output(styleRulesCommand.formatStyleRulesList(rules));
               }
-            } else {
-              Logger.output(styleRulesCommand.formatStyleRulesList(rules));
+            } catch (error) {
+              handleError(error);
             }
-          } catch (error) {
-            handleError(error);
           }
-        })
+        )
     )
     .addCommand(
       new Command('create')
         .description('Create a new style rule list')
         .requiredOption('--name <name>', 'Style rule list name')
-        .requiredOption('--language <lang>', 'Target language (e.g. en, de, es)')
-        .option('--rules <json>', 'Configured rules as a JSON object of category → settings (e.g. \'{"punctuation":{"quotation_mark":"use_guillemets"}}\')')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-        .action(async (options: {
-          name: string;
-          language: string;
-          rules?: string;
-          format?: string;
-        }) => {
-          try {
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
+        .requiredOption(
+          '--language <lang>',
+          'Target language (e.g. en, de, es)'
+        )
+        .option(
+          '--rules <json>',
+          'Configured rules as a JSON object of category → settings (e.g. \'{"punctuation":{"quotation_mark":"use_guillemets"}}\')'
+        )
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
+        .action(
+          async (options: {
+            name: string;
+            language: string;
+            rules?: string;
+            format?: string;
+          }) => {
+            try {
+              const styleRulesCommand =
+                await createStyleRulesCommand(createDeepLClient);
 
-            const createOpts: { name: string; language: string; configuredRules?: ConfiguredRules } = {
-              name: options.name,
-              language: options.language,
-            };
-            if (options.rules !== undefined) {
-              createOpts.configuredRules = parseRulesArg(options.rules);
-            }
+              const createOpts: {
+                name: string;
+                language: string;
+                configuredRules?: ConfiguredRules;
+              } = {
+                name: options.name,
+                language: options.language,
+              };
+              if (options.rules !== undefined) {
+                createOpts.configuredRules = parseRulesArg(options.rules);
+              }
 
-            const rule = await styleRulesCommand.create(createOpts);
-            if (options.format === 'json') {
-              Logger.output(styleRulesCommand.formatStyleRuleJson(rule));
-            } else {
-              Logger.success(chalk.green(`\u2713 Style rule created: ${rule.styleId}`));
-              Logger.output(styleRulesCommand.formatStyleRule(rule));
+              const rule = await styleRulesCommand.create(createOpts);
+              if (options.format === 'json') {
+                Logger.output(styleRulesCommand.formatStyleRuleJson(rule));
+              } else {
+                Logger.success(
+                  chalk.green(`\u2713 Style rule created: ${rule.styleId}`)
+                );
+                Logger.output(styleRulesCommand.formatStyleRule(rule));
+              }
+            } catch (error) {
+              handleError(error);
             }
-          } catch (error) {
-            handleError(error);
           }
-        })
+        )
     )
     .addCommand(
       new Command('show')
         .description('Show a single style rule list')
         .argument('<id>', 'Style rule ID')
-        .option('--detailed', 'Include configured rules and custom instructions')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-        .action(async (id: string, options: { detailed?: boolean; format?: string }) => {
-          try {
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
+        .option(
+          '--detailed',
+          'Include configured rules and custom instructions'
+        )
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
+        .action(
+          async (
+            id: string,
+            options: { detailed?: boolean; format?: string }
+          ) => {
+            try {
+              const styleRulesCommand =
+                await createStyleRulesCommand(createDeepLClient);
 
-            const rule = await styleRulesCommand.show(id, options.detailed ?? false);
-            if (options.format === 'json') {
-              Logger.output(styleRulesCommand.formatStyleRuleJson(rule));
-            } else {
-              Logger.output(styleRulesCommand.formatStyleRule(rule));
+              const rule = await styleRulesCommand.show(
+                id,
+                options.detailed ?? false
+              );
+              if (options.format === 'json') {
+                Logger.output(styleRulesCommand.formatStyleRuleJson(rule));
+              } else {
+                Logger.output(styleRulesCommand.formatStyleRule(rule));
+              }
+            } catch (error) {
+              handleError(error);
             }
-          } catch (error) {
-            handleError(error);
           }
-        })
+        )
     )
     .addCommand(
       new Command('update')
-        .description('Update a style rule list (rename and/or replace configured rules)')
+        .description(
+          'Update a style rule list (rename and/or replace configured rules)'
+        )
         .argument('<id>', 'Style rule ID')
         .option('--name <name>', 'New name')
-        .option('--rules <json>', 'Replace configured rules with a JSON object of category → settings')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-        .action(async (id: string, options: { name?: string; rules?: string; format?: string }) => {
-          try {
-            if (options.name === undefined && options.rules === undefined) {
-              throw new ValidationError('Specify at least one of --name or --rules');
-            }
+        .option(
+          '--rules <json>',
+          'Replace configured rules with a JSON object of category → settings'
+        )
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
+        .action(
+          async (
+            id: string,
+            options: { name?: string; rules?: string; format?: string }
+          ) => {
+            try {
+              if (options.name === undefined && options.rules === undefined) {
+                throw new ValidationError(
+                  'Specify at least one of --name or --rules'
+                );
+              }
 
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
+              const styleRulesCommand =
+                await createStyleRulesCommand(createDeepLClient);
 
-            if (options.name !== undefined) {
-              await styleRulesCommand.update(id, { name: options.name });
-            }
+              if (options.name !== undefined) {
+                await styleRulesCommand.update(id, { name: options.name });
+              }
 
-            let finalRule;
-            if (options.rules !== undefined) {
-              finalRule = await styleRulesCommand.replaceRules(id, parseRulesArg(options.rules));
-            } else {
-              finalRule = await styleRulesCommand.show(id);
-            }
+              let finalRule;
+              if (options.rules !== undefined) {
+                finalRule = await styleRulesCommand.replaceRules(
+                  id,
+                  parseRulesArg(options.rules)
+                );
+              } else {
+                finalRule = await styleRulesCommand.show(id);
+              }
 
-            if (options.format === 'json') {
-              Logger.output(styleRulesCommand.formatStyleRuleJson(finalRule));
-            } else {
-              Logger.success(chalk.green(`\u2713 Style rule updated: ${id}`));
-              Logger.output(styleRulesCommand.formatStyleRule(finalRule));
+              if (options.format === 'json') {
+                Logger.output(styleRulesCommand.formatStyleRuleJson(finalRule));
+              } else {
+                Logger.success(chalk.green(`\u2713 Style rule updated: ${id}`));
+                Logger.output(styleRulesCommand.formatStyleRule(finalRule));
+              }
+            } catch (error) {
+              handleError(error);
             }
-          } catch (error) {
-            handleError(error);
           }
-        })
+        )
     )
     .addCommand(
       new Command('delete')
         .description('Delete a style rule list')
         .argument('<id>', 'Style rule ID')
         .option('-y, --yes', 'Skip confirmation prompt')
-        .option('--dry-run', 'Show what would be deleted without performing the operation')
-        .action(async (id: string, options: { yes?: boolean; dryRun?: boolean }) => {
-          try {
-            if (options.dryRun) {
-              Logger.output(chalk.yellow(`[dry-run] No deletions will be performed.`));
-              Logger.output(chalk.yellow(`[dry-run] Would delete style rule: "${id}"`));
-              return;
-            }
-
-            if (!options.yes) {
-              const { confirm } = await import('../../utils/confirm.js');
-              const confirmed = await confirm({ message: `Delete style rule "${id}"?` });
-              if (!confirmed) {
-                Logger.info('Aborted.');
+        .option(
+          '--dry-run',
+          'Show what would be deleted without performing the operation'
+        )
+        .action(
+          async (id: string, options: { yes?: boolean; dryRun?: boolean }) => {
+            try {
+              if (options.dryRun) {
+                Logger.output(
+                  chalk.yellow(`[dry-run] No deletions will be performed.`)
+                );
+                Logger.output(
+                  chalk.yellow(`[dry-run] Would delete style rule: "${id}"`)
+                );
                 return;
               }
-            }
 
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
-            await styleRulesCommand.delete(id);
-            Logger.success(chalk.green(`\u2713 Style rule deleted: ${id}`));
-          } catch (error) {
-            handleError(error);
+              if (!options.yes) {
+                const { confirm } = await import('../../utils/confirm.js');
+                const confirmed = await confirm({
+                  message: `Delete style rule "${id}"?`,
+                });
+                if (!confirmed) {
+                  Logger.info('Aborted.');
+                  return;
+                }
+              }
+
+              const styleRulesCommand =
+                await createStyleRulesCommand(createDeepLClient);
+              await styleRulesCommand.delete(id);
+              Logger.success(chalk.green(`\u2713 Style rule deleted: ${id}`));
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     )
     .addCommand(
       new Command('instructions')
         .description('List custom instructions for a style rule')
         .argument('<style-id>', 'Style rule ID')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json', 'table']).default('text'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json', 'table'])
+            .default('text')
+        )
         .action(async (styleId: string, options: { format?: string }) => {
           try {
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
-            const instructions = await styleRulesCommand.listInstructions(styleId);
+            const styleRulesCommand =
+              await createStyleRulesCommand(createDeepLClient);
+            const instructions =
+              await styleRulesCommand.listInstructions(styleId);
             if (options.format === 'json') {
-              Logger.output(styleRulesCommand.formatCustomInstructionJson(instructions));
+              Logger.output(
+                styleRulesCommand.formatCustomInstructionJson(instructions)
+              );
             } else if (options.format === 'table') {
               if (!process.stdout.isTTY) {
-                Logger.warn('WARN  --format table is not supported in non-TTY output; falling back to plain text');
-                Logger.output(styleRulesCommand.formatCustomInstructionsList(instructions));
+                Logger.warn(
+                  'WARN  --format table is not supported in non-TTY output; falling back to plain text'
+                );
+                Logger.output(
+                  styleRulesCommand.formatCustomInstructionsList(instructions)
+                );
               } else {
-                Logger.output(styleRulesCommand.formatCustomInstructionsTable(instructions));
+                Logger.output(
+                  styleRulesCommand.formatCustomInstructionsTable(instructions)
+                );
               }
             } else {
-              Logger.output(styleRulesCommand.formatCustomInstructionsList(instructions));
+              Logger.output(
+                styleRulesCommand.formatCustomInstructionsList(instructions)
+              );
             }
           } catch (error) {
             handleError(error);
@@ -272,30 +391,49 @@ Examples:
         .argument('<label>', 'Instruction label (unique within the style rule)')
         .argument('<prompt>', 'Instruction prompt text')
         .option('--source-language <lang>', 'Source language code (optional)')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-        .action(async (
-          styleId: string,
-          label: string,
-          prompt: string,
-          options: { sourceLanguage?: string; format?: string },
-        ) => {
-          try {
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
-            const createOpts: CreateCustomInstructionOptions = { label, prompt };
-            if (options.sourceLanguage !== undefined) {
-              createOpts.sourceLanguage = options.sourceLanguage;
-            }
-            const instruction = await styleRulesCommand.addInstruction(styleId, createOpts);
-            if (options.format === 'json') {
-              Logger.output(styleRulesCommand.formatCustomInstructionJson(instruction));
-            } else {
-              Logger.success(chalk.green(`\u2713 Instruction added: ${instruction.label}`));
-              Logger.output(styleRulesCommand.formatCustomInstruction(instruction));
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
+        .action(
+          async (
+            styleId: string,
+            label: string,
+            prompt: string,
+            options: { sourceLanguage?: string; format?: string }
+          ) => {
+            try {
+              const styleRulesCommand =
+                await createStyleRulesCommand(createDeepLClient);
+              const createOpts: CreateCustomInstructionOptions = {
+                label,
+                prompt,
+              };
+              if (options.sourceLanguage !== undefined) {
+                createOpts.sourceLanguage = options.sourceLanguage;
+              }
+              const instruction = await styleRulesCommand.addInstruction(
+                styleId,
+                createOpts
+              );
+              if (options.format === 'json') {
+                Logger.output(
+                  styleRulesCommand.formatCustomInstructionJson(instruction)
+                );
+              } else {
+                Logger.success(
+                  chalk.green(`\u2713 Instruction added: ${instruction.label}`)
+                );
+                Logger.output(
+                  styleRulesCommand.formatCustomInstruction(instruction)
+                );
+              }
+            } catch (error) {
+              handleError(error);
             }
-          } catch (error) {
-            handleError(error);
           }
-        })
+        )
     )
     .addCommand(
       new Command('update-instruction')
@@ -304,30 +442,49 @@ Examples:
         .argument('<label>', 'Instruction label')
         .argument('<prompt>', 'New instruction prompt text')
         .option('--source-language <lang>', 'Source language code (optional)')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-        .action(async (
-          styleId: string,
-          label: string,
-          prompt: string,
-          options: { sourceLanguage?: string; format?: string },
-        ) => {
-          try {
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
-            const updateOpts: UpdateCustomInstructionOptions = { prompt };
-            if (options.sourceLanguage !== undefined) {
-              updateOpts.sourceLanguage = options.sourceLanguage;
-            }
-            const instruction = await styleRulesCommand.updateInstruction(styleId, label, updateOpts);
-            if (options.format === 'json') {
-              Logger.output(styleRulesCommand.formatCustomInstructionJson(instruction));
-            } else {
-              Logger.success(chalk.green(`\u2713 Instruction updated: ${instruction.label}`));
-              Logger.output(styleRulesCommand.formatCustomInstruction(instruction));
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
+        .action(
+          async (
+            styleId: string,
+            label: string,
+            prompt: string,
+            options: { sourceLanguage?: string; format?: string }
+          ) => {
+            try {
+              const styleRulesCommand =
+                await createStyleRulesCommand(createDeepLClient);
+              const updateOpts: UpdateCustomInstructionOptions = { prompt };
+              if (options.sourceLanguage !== undefined) {
+                updateOpts.sourceLanguage = options.sourceLanguage;
+              }
+              const instruction = await styleRulesCommand.updateInstruction(
+                styleId,
+                label,
+                updateOpts
+              );
+              if (options.format === 'json') {
+                Logger.output(
+                  styleRulesCommand.formatCustomInstructionJson(instruction)
+                );
+              } else {
+                Logger.success(
+                  chalk.green(
+                    `\u2713 Instruction updated: ${instruction.label}`
+                  )
+                );
+                Logger.output(
+                  styleRulesCommand.formatCustomInstruction(instruction)
+                );
+              }
+            } catch (error) {
+              handleError(error);
             }
-          } catch (error) {
-            handleError(error);
           }
-        })
+        )
     )
     .addCommand(
       new Command('remove-instruction')
@@ -335,34 +492,50 @@ Examples:
         .argument('<style-id>', 'Style rule ID')
         .argument('<label>', 'Instruction label')
         .option('-y, --yes', 'Skip confirmation prompt')
-        .option('--dry-run', 'Show what would be removed without performing the operation')
-        .action(async (
-          styleId: string,
-          label: string,
-          options: { yes?: boolean; dryRun?: boolean },
-        ) => {
-          try {
-            if (options.dryRun) {
-              Logger.output(chalk.yellow(`[dry-run] No removals will be performed.`));
-              Logger.output(chalk.yellow(`[dry-run] Would remove instruction "${label}" from style rule "${styleId}"`));
-              return;
-            }
-
-            if (!options.yes) {
-              const { confirm } = await import('../../utils/confirm.js');
-              const confirmed = await confirm({ message: `Remove instruction "${label}" from style rule "${styleId}"?` });
-              if (!confirmed) {
-                Logger.info('Aborted.');
+        .option(
+          '--dry-run',
+          'Show what would be removed without performing the operation'
+        )
+        .action(
+          async (
+            styleId: string,
+            label: string,
+            options: { yes?: boolean; dryRun?: boolean }
+          ) => {
+            try {
+              if (options.dryRun) {
+                Logger.output(
+                  chalk.yellow(`[dry-run] No removals will be performed.`)
+                );
+                Logger.output(
+                  chalk.yellow(
+                    `[dry-run] Would remove instruction "${label}" from style rule "${styleId}"`
+                  )
+                );
                 return;
               }
-            }
 
-            const styleRulesCommand = await createStyleRulesCommand(createDeepLClient);
-            await styleRulesCommand.removeInstruction(styleId, label);
-            Logger.success(chalk.green(`\u2713 Instruction removed: ${label}`));
-          } catch (error) {
-            handleError(error);
+              if (!options.yes) {
+                const { confirm } = await import('../../utils/confirm.js');
+                const confirmed = await confirm({
+                  message: `Remove instruction "${label}" from style rule "${styleId}"?`,
+                });
+                if (!confirmed) {
+                  Logger.info('Aborted.');
+                  return;
+                }
+              }
+
+              const styleRulesCommand =
+                await createStyleRulesCommand(createDeepLClient);
+              await styleRulesCommand.removeInstruction(styleId, label);
+              Logger.success(
+                chalk.green(`\u2713 Instruction removed: ${label}`)
+              );
+            } catch (error) {
+              handleError(error);
+            }
           }
-        })
+        )
     );
 }
diff --git a/src/cli/commands/register-tm.ts b/src/cli/commands/register-tm.ts
index 692c0878..e1f61a01 100644
--- a/src/cli/commands/register-tm.ts
+++ b/src/cli/commands/register-tm.ts
@@ -4,25 +4,32 @@ import { createTmCommand, type ServiceDeps } from './service-factory.js';
 
 export function registerTm(
   program: Command,
-  deps: Pick<ServiceDeps, 'createDeepLClient' | 'handleError'>,
+  deps: Pick<ServiceDeps, 'createDeepLClient' | 'handleError'>
 ): void {
   const { createDeepLClient, handleError } = deps;
 
   program
     .command('tm')
     .description('Manage translation memories')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl tm list
   $ deepl tm list --format json
 
 Pass a listed UUID or name to 'deepl translate --translation-memory' and
 'deepl sync' (via .deepl-sync.yaml translation.translation_memory).
-`)
+`
+    )
     .addCommand(
       new Command('list')
         .description('List all translation memories on the account')
-        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .addOption(
+          new Option('--format <format>', 'Output format')
+            .choices(['text', 'json'])
+            .default('text')
+        )
         .action(async (options: { format?: string }) => {
           try {
             const tmCommand = await createTmCommand(createDeepLClient);
@@ -35,6 +42,6 @@ Pass a listed UUID or name to 'deepl translate --translation-memory' and
           } catch (error) {
             handleError(error);
           }
-        }),
+        })
     );
 }
diff --git a/src/cli/commands/register-translate.ts b/src/cli/commands/register-translate.ts
index 3c9eb8e8..405bccd2 100644
--- a/src/cli/commands/register-translate.ts
+++ b/src/cli/commands/register-translate.ts
@@ -11,32 +11,57 @@ import {
   hasGlossarySelection,
 } from '../../utils/glossary-params.js';
 
-export function registerTranslate(
-  program: Command,
-  deps: ServiceDeps,
-): void {
+export function registerTranslate(program: Command, deps: ServiceDeps): void {
   const { handleError } = deps;
 
   program
     .command('translate')
     .alias('t')
     .description('Translate text, files, or directories using DeepL API')
-    .argument('[text]', 'Text, file path, or directory to translate (or read from stdin)')
+    .argument(
+      '[text]',
+      'Text, file path, or directory to translate (or read from stdin)'
+    )
     .optionsGroup('Core Options:')
-    .option('-t, --to <language>', 'Target language(s), comma-separated for multiple (uses config default if omitted)')
-    .option('-f, --from <language>', 'Source language (auto-detect if not specified)')
-    .option('-o, --output <path>', 'Output file path or directory (required for file/directory translation)')
+    .option(
+      '-t, --to <language>',
+      'Target language(s), comma-separated for multiple (uses config default if omitted)'
+    )
+    .option(
+      '-f, --from <language>',
+      'Source language (auto-detect if not specified)'
+    )
+    .option(
+      '-o, --output <path>',
+      'Output file path or directory (required for file/directory translation)'
+    )
     .optionsGroup('Translation Quality:')
-    .addOption(new Option('--formality <level>', 'Formality level (formal/informal are aliases for more/less)').choices(['default', 'more', 'less', 'prefer_more', 'prefer_less', 'formal', 'informal']))
-    .option('--context <text>', 'Additional context to improve translation quality')
+    .addOption(
+      new Option(
+        '--formality <level>',
+        'Formality level (formal/informal are aliases for more/less)'
+      ).choices([
+        'default',
+        'more',
+        'less',
+        'prefer_more',
+        'prefer_less',
+        'formal',
+        'informal',
+      ])
+    )
+    .option(
+      '--context <text>',
+      'Additional context to improve translation quality'
+    )
     .option(
       '--glossary <name-or-id>',
       `Use glossary by name or ID (requires --from; repeatable, max ${MAX_GLOSSARIES_PER_REQUEST}; entries are merged, and for a term defined in several the API picks the winner regardless of flag order). Applies to text, files and documents.`,
-      (val: string, prev: string[] | undefined) => (prev ?? []).concat([val]),
+      (val: string, prev: string[] | undefined) => (prev ?? []).concat([val])
     )
     .option(
       '--translation-memory <name-or-uuid>',
-      'Use translation memory by name or UUID (forces quality_optimized model). Run "deepl tm list" to see available TMs.',
+      'Use translation memory by name or UUID (forces quality_optimized model). Run "deepl tm list" to see available TMs.'
     )
     .option(
       '--tm-threshold <n>',
@@ -45,41 +70,121 @@ export function registerTranslate(
         if (!/^-?\d+$/.test(raw)) {
           throw new ValidationError(
             `--tm-threshold must be an integer, got: ${raw}`,
-            'Example: --tm-threshold 80',
+            'Example: --tm-threshold 80'
           );
         }
         return parseInt(raw, 10);
-      },
+      }
+    )
+    .option(
+      '--custom-instruction <instruction>',
+      'Custom instruction for translation (repeatable, max 10, max 300 chars each)',
+      (val: string, prev: string[]) => prev.concat([val]),
+      [] as string[]
+    )
+    .option(
+      '--style-id <uuid>',
+      'Style rule ID for translation (Pro API only, forces quality_optimized model)'
+    )
+    .addOption(
+      new Option('--model-type <type>', 'Model type').choices([
+        'quality_optimized',
+        'prefer_quality_optimized',
+        'latency_optimized',
+      ])
     )
-    .option('--custom-instruction <instruction>', 'Custom instruction for translation (repeatable, max 10, max 300 chars each)', (val: string, prev: string[]) => prev.concat([val]), [] as string[])
-    .option('--style-id <uuid>', 'Style rule ID for translation (Pro API only, forces quality_optimized model)')
-    .addOption(new Option('--model-type <type>', 'Model type').choices(['quality_optimized', 'prefer_quality_optimized', 'latency_optimized']))
     .optionsGroup('Preservation:')
-    .option('--preserve-code', 'Preserve code blocks and variables during translation')
-    .option('--preserve-formatting', 'Preserve line breaks and whitespace formatting')
-    .addOption(new Option('--split-sentences <mode>', 'Sentence splitting (default: on)').choices(['on', 'off', 'nonewlines']))
+    .option(
+      '--preserve-code',
+      'Preserve code blocks and variables during translation'
+    )
+    .option(
+      '--preserve-formatting',
+      'Preserve line breaks and whitespace formatting'
+    )
+    .addOption(
+      new Option(
+        '--split-sentences <mode>',
+        'Sentence splitting (default: on)'
+      ).choices(['on', 'off', 'nonewlines'])
+    )
     .optionsGroup('Document Options:')
-    .addOption(new Option('--output-format <format>', 'Convert PDF to DOCX during translation (only supported conversion)').choices(['docx']))
-    .option('--enable-minification', 'Enable document minification (PPTX/DOCX only, reduces file size)')
+    .addOption(
+      new Option(
+        '--output-format <format>',
+        'Convert PDF to DOCX during translation (only supported conversion)'
+      ).choices(['docx'])
+    )
+    .option(
+      '--enable-minification',
+      'Enable document minification (PPTX/DOCX only, reduces file size)'
+    )
     .optionsGroup('XML/HTML Options:')
-    .addOption(new Option('--tag-handling <mode>', 'Tag handling for XML/HTML').choices(['xml', 'html']))
-    .addOption(new Option('--tag-handling-version <version>', 'Tag handling version (v2 improves structure handling, requires --tag-handling)').choices(['v1', 'v2']))
-    .option('--outline-detection <bool>', 'Control automatic XML structure detection (true/false, default: true, requires --tag-handling xml)')
-    .option('--splitting-tags <tags>', 'Comma-separated XML tags that split sentences (requires --tag-handling xml)')
-    .option('--non-splitting-tags <tags>', 'Comma-separated XML tags that should not be used to split sentences (requires --tag-handling xml)')
-    .option('--ignore-tags <tags>', 'Comma-separated XML tags with content to ignore (requires --tag-handling xml)')
+    .addOption(
+      new Option('--tag-handling <mode>', 'Tag handling for XML/HTML').choices([
+        'xml',
+        'html',
+      ])
+    )
+    .addOption(
+      new Option(
+        '--tag-handling-version <version>',
+        'Tag handling version (v2 improves structure handling, requires --tag-handling)'
+      ).choices(['v1', 'v2'])
+    )
+    .option(
+      '--outline-detection <bool>',
+      'Control automatic XML structure detection (true/false, default: true, requires --tag-handling xml)'
+    )
+    .option(
+      '--splitting-tags <tags>',
+      'Comma-separated XML tags that split sentences (requires --tag-handling xml)'
+    )
+    .option(
+      '--non-splitting-tags <tags>',
+      'Comma-separated XML tags that should not be used to split sentences (requires --tag-handling xml)'
+    )
+    .option(
+      '--ignore-tags <tags>',
+      'Comma-separated XML tags with content to ignore (requires --tag-handling xml)'
+    )
     .optionsGroup('File/Directory Options:')
     .option('--no-recursive', 'Do not recurse into subdirectories')
-    .option('--pattern <pattern>', 'Glob pattern for file filtering (e.g., "*.md")')
-    .option('--concurrency <number>', 'Number of parallel translations (default: 5)', parseInt)
-    .option('--dry-run', 'Show what would be translated without performing the operation')
+    .option(
+      '--pattern <pattern>',
+      'Glob pattern for file filtering (e.g., "*.md")'
+    )
+    .option(
+      '--concurrency <number>',
+      'Number of parallel translations (default: 5)',
+      parseInt
+    )
+    .option(
+      '--dry-run',
+      'Show what would be translated without performing the operation'
+    )
     .optionsGroup('Output & Display:')
-    .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json', 'table']).default('text'))
-    .option('--show-billed-characters', 'Request and display actual billed character count for cost transparency')
+    .addOption(
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json', 'table'])
+        .default('text')
+    )
+    .option(
+      '--show-billed-characters',
+      'Request and display actual billed character count for cost transparency'
+    )
     .optionsGroup('Advanced:')
-    .option('--no-cache', 'Bypass cache for this translation (useful for testing)')
-    .option('--api-url <url>', 'Custom API endpoint (e.g., https://api-free.deepl.com/v2 or internal test URLs)')
-    .addHelpText('after', `
+    .option(
+      '--no-cache',
+      'Bypass cache for this translation (useful for testing)'
+    )
+    .option(
+      '--api-url <url>',
+      'Custom API endpoint (e.g., https://api-free.deepl.com/v2 or internal test URLs)'
+    )
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl translate "Hello world" --to es
   $ deepl translate README.md --to fr --output README.fr.md
@@ -92,177 +197,258 @@ Examples:
   $ deepl translate page.html --to fr --tag-handling html
   $ deepl translate "Hello" --to es --custom-instruction "Use informal language"
   $ deepl translate ./docs --to es --dry-run
-`)
-    .action(async (text: string | undefined, options: {
-      to?: string;
-      from?: string;
-      output?: string;
-      formality?: string;
-      outputFormat?: string;
-      preserveCode?: boolean;
-      preserveFormatting?: boolean;
-      context?: string;
-      splitSentences?: string;
-      tagHandling?: string;
-      modelType?: string;
-      showBilledCharacters?: boolean;
-      enableMinification?: boolean;
-      outlineDetection?: string;
-      splittingTags?: string;
-      nonSplittingTags?: string;
-      ignoreTags?: string;
-      tagHandlingVersion?: string;
-      recursive?: boolean;
-      pattern?: string;
-      concurrency?: number;
-      glossary?: string[];
-      translationMemory?: string;
-      tmThreshold?: number;
-      customInstruction?: string[];
-      styleId?: string;
-      format?: string;
-      apiUrl?: string;
-      dryRun?: boolean;
-    }) => {
-      try {
-        if (!options.to) {
-          const configService = deps.getConfigService();
-          const targetLangs = configService.getValue<string[]>('defaults.targetLangs');
-          if (targetLangs && targetLangs.length > 0) {
-            options.to = targetLangs[0];
-          } else {
-            throw new ValidationError(
-              'No target language specified.',
-              'Use --to <lang>:   deepl translate "Hello" --to de\n  Set a default:     deepl init',
+`
+    )
+    .action(
+      async (
+        text: string | undefined,
+        options: {
+          to?: string;
+          from?: string;
+          output?: string;
+          formality?: string;
+          outputFormat?: string;
+          preserveCode?: boolean;
+          preserveFormatting?: boolean;
+          context?: string;
+          splitSentences?: string;
+          tagHandling?: string;
+          modelType?: string;
+          showBilledCharacters?: boolean;
+          enableMinification?: boolean;
+          outlineDetection?: string;
+          splittingTags?: string;
+          nonSplittingTags?: string;
+          ignoreTags?: string;
+          tagHandlingVersion?: string;
+          recursive?: boolean;
+          pattern?: string;
+          concurrency?: number;
+          glossary?: string[];
+          translationMemory?: string;
+          tmThreshold?: number;
+          customInstruction?: string[];
+          styleId?: string;
+          format?: string;
+          apiUrl?: string;
+          dryRun?: boolean;
+        }
+      ) => {
+        try {
+          if (!options.to) {
+            const configService = deps.getConfigService();
+            const targetLangs = configService.getValue<string[]>(
+              'defaults.targetLangs'
             );
+            if (targetLangs && targetLangs.length > 0) {
+              options.to = targetLangs[0];
+            } else {
+              throw new ValidationError(
+                'No target language specified.',
+                'Use --to <lang>:   deepl translate "Hello" --to de\n  Set a default:     deepl init'
+              );
+            }
           }
-        }
 
-        if (options.glossary && options.glossary.length > MAX_GLOSSARIES_PER_REQUEST) {
-          throw new ValidationError(
-            `--glossary can be given at most ${MAX_GLOSSARIES_PER_REQUEST} times, got ${options.glossary.length}`,
-            'Merge entries into fewer glossaries, or drop some --glossary flags.',
-          );
-        }
-
-        if (options.tmThreshold !== undefined && !options.translationMemory) {
-          throw new ValidationError(
-            '--tm-threshold requires --translation-memory',
-            'Example: --translation-memory my-tm --tm-threshold 80',
-          );
-        }
-        if (options.tmThreshold !== undefined) {
-          const n = options.tmThreshold;
-          if (n < 0 || n > 100) {
+          if (
+            options.glossary &&
+            options.glossary.length > MAX_GLOSSARIES_PER_REQUEST
+          ) {
             throw new ValidationError(
-              `--tm-threshold must be an integer between 0 and 100, got: ${n}`,
-              'Use a value between 0 and 100, or omit --tm-threshold to use the default (75).',
+              `--glossary can be given at most ${MAX_GLOSSARIES_PER_REQUEST} times, got ${options.glossary.length}`,
+              'Merge entries into fewer glossaries, or drop some --glossary flags.'
             );
           }
-        }
-        if (
-          options.translationMemory &&
-          options.modelType &&
-          options.modelType !== 'quality_optimized'
-        ) {
-          throw new ValidationError(
-            '--translation-memory requires quality_optimized model type',
-            'Remove --model-type or set --model-type quality_optimized',
-          );
-        }
 
-        // Checked before --dry-run reports the command as runnable. Resolving a
-        // glossary name needs the API and stays out of dry-run; the requirement
-        // that a glossary carry a source language does not.
-        if (hasGlossarySelection(options)) {
-          applyGlossarySourceLang(
-            options,
-            deps.getConfigService().getValue<string>('defaults.sourceLang'),
-            'Example: deepl translate --from en --to es --glossary my-glossary "Hello"',
-          );
-        }
+          if (options.tmThreshold !== undefined && !options.translationMemory) {
+            throw new ValidationError(
+              '--tm-threshold requires --translation-memory',
+              'Example: --translation-memory my-tm --tm-threshold 80'
+            );
+          }
+          if (options.tmThreshold !== undefined) {
+            const n = options.tmThreshold;
+            if (n < 0 || n > 100) {
+              throw new ValidationError(
+                `--tm-threshold must be an integer between 0 and 100, got: ${n}`,
+                'Use a value between 0 and 100, or omit --tm-threshold to use the default (75).'
+              );
+            }
+          }
+          if (
+            options.translationMemory &&
+            options.modelType &&
+            options.modelType !== 'quality_optimized'
+          ) {
+            throw new ValidationError(
+              '--translation-memory requires quality_optimized model type',
+              'Remove --model-type or set --model-type quality_optimized'
+            );
+          }
 
-        if (options.dryRun) {
-          // Normalized here because the real run lowercases inside
-          // TranslateCommand, past the point a dry run returns.
-          options.to = options.to!.toLowerCase();
-          if (options.from) {
-            options.from = options.from.toLowerCase();
+          // Checked before --dry-run reports the command as runnable. Resolving a
+          // glossary name needs the API and stays out of dry-run; the requirement
+          // that a glossary carry a source language does not.
+          if (hasGlossarySelection(options)) {
+            applyGlossarySourceLang(
+              options,
+              deps.getConfigService().getValue<string>('defaults.sourceLang'),
+              'Example: deepl translate --from en --to es --glossary my-glossary "Hello"'
+            );
           }
 
-          const targetLangs = options.to.split(',').map(l => l.trim());
-          const isDir = !!text && fs.existsSync(text) && fs.statSync(text).isDirectory();
-          const isFile = !!text && !isDir && fs.existsSync(text) && fs.statSync(text).isFile();
+          if (options.dryRun) {
+            // Normalized here because the real run lowercases inside
+            // TranslateCommand, past the point a dry run returns.
+            options.to = options.to!.toLowerCase();
+            if (options.from) {
+              options.from = options.from.toLowerCase();
+            }
+
+            const targetLangs = options.to.split(',').map((l) => l.trim());
+            const isDir =
+              !!text && fs.existsSync(text) && fs.statSync(text).isDirectory();
+            const isFile =
+              !!text &&
+              !isDir &&
+              fs.existsSync(text) &&
+              fs.statSync(text).isFile();
 
-          // A dry run reports a command as runnable, so it rejects whatever the
-          // real run rejects locally. Which extended-tier arms hold depends on the
-          // mode that will handle this argument: directory mode ignores --glossary
-          // but sends --model-type, while a document run discards --model-type
-          // after warning, so asserting either arm for both would refuse a command
-          // that works.
-          validateTranslationLanguages(
-            targetLangs,
-            isDir
-              ? { from: options.from, formality: options.formality, modelType: options.modelType }
-              : { from: options.from, formality: options.formality, glossary: options.glossary },
-          );
+            // A dry run reports a command as runnable, so it rejects whatever the
+            // real run rejects locally. Which extended-tier arms hold depends on the
+            // mode that will handle this argument: directory mode ignores --glossary
+            // but sends --model-type, while a document run discards --model-type
+            // after warning, so asserting either arm for both would refuse a command
+            // that works.
+            validateTranslationLanguages(
+              targetLangs,
+              isDir
+                ? {
+                    from: options.from,
+                    formality: options.formality,
+                    modelType: options.modelType,
+                  }
+                : {
+                    from: options.from,
+                    formality: options.formality,
+                    glossary: options.glossary,
+                  }
+            );
 
-          const lines: string[] = [
-            chalk.yellow('[dry-run] No translations will be performed.'),
-          ];
+            const lines: string[] = [
+              chalk.yellow('[dry-run] No translations will be performed.'),
+            ];
 
-          if (text) {
-            if (isDir) {
-              lines.push(chalk.yellow(`[dry-run] Would translate directory: ${text}`));
-              lines.push(chalk.yellow(`[dry-run] Output directory: ${options.output ?? '<required>'}`));
-              if (options.pattern) {
-                lines.push(chalk.yellow(`[dry-run] File pattern: ${options.pattern}`));
+            if (text) {
+              if (isDir) {
+                lines.push(
+                  chalk.yellow(`[dry-run] Would translate directory: ${text}`)
+                );
+                lines.push(
+                  chalk.yellow(
+                    `[dry-run] Output directory: ${options.output ?? '<required>'}`
+                  )
+                );
+                if (options.pattern) {
+                  lines.push(
+                    chalk.yellow(`[dry-run] File pattern: ${options.pattern}`)
+                  );
+                }
+                lines.push(
+                  chalk.yellow(
+                    `[dry-run] Recursive: ${options.recursive !== false}`
+                  )
+                );
+              } else if (isFile) {
+                lines.push(
+                  chalk.yellow(`[dry-run] Would translate file: ${text}`)
+                );
+                lines.push(
+                  chalk.yellow(
+                    `[dry-run] Output: ${options.output ?? '<stdout>'}`
+                  )
+                );
+              } else {
+                lines.push(
+                  chalk.yellow(
+                    `[dry-run] Would translate text: "${text.length > 80 ? text.substring(0, 80) + '...' : text}"`
+                  )
+                );
               }
-              lines.push(chalk.yellow(`[dry-run] Recursive: ${options.recursive !== false}`));
-            } else if (isFile) {
-              lines.push(chalk.yellow(`[dry-run] Would translate file: ${text}`));
-              lines.push(chalk.yellow(`[dry-run] Output: ${options.output ?? '<stdout>'}`));
             } else {
-              lines.push(chalk.yellow(`[dry-run] Would translate text: "${text.length > 80 ? text.substring(0, 80) + '...' : text}"`));
+              lines.push(
+                chalk.yellow(`[dry-run] Would translate text from stdin`)
+              );
             }
-          } else {
-            lines.push(chalk.yellow(`[dry-run] Would translate text from stdin`));
-          }
 
-          lines.push(chalk.yellow(`[dry-run] Target language(s): ${targetLangs.join(', ')}`));
-          if (options.from) {
-            lines.push(chalk.yellow(`[dry-run] Source language: ${options.from}`));
-          }
-          if (options.glossary && options.glossary.length > 0) {
-            const label = options.glossary.length > 1 ? 'Glossaries' : 'Glossary';
-            lines.push(chalk.yellow(`[dry-run] ${label}: ${options.glossary.join(', ')}`));
-          }
-          if (options.translationMemory) {
-            lines.push(chalk.yellow(`[dry-run] Translation memory: ${options.translationMemory}`));
-            lines.push(chalk.yellow(`[dry-run] Match threshold: ${options.tmThreshold ?? 75}`));
-            lines.push(chalk.yellow(`[dry-run] Model: quality_optimized (forced by --translation-memory)`));
-          }
-          if (options.formality) {
-            lines.push(chalk.yellow(`[dry-run] Formality: ${options.formality}`));
+            lines.push(
+              chalk.yellow(
+                `[dry-run] Target language(s): ${targetLangs.join(', ')}`
+              )
+            );
+            if (options.from) {
+              lines.push(
+                chalk.yellow(`[dry-run] Source language: ${options.from}`)
+              );
+            }
+            if (options.glossary && options.glossary.length > 0) {
+              const label =
+                options.glossary.length > 1 ? 'Glossaries' : 'Glossary';
+              lines.push(
+                chalk.yellow(
+                  `[dry-run] ${label}: ${options.glossary.join(', ')}`
+                )
+              );
+            }
+            if (options.translationMemory) {
+              lines.push(
+                chalk.yellow(
+                  `[dry-run] Translation memory: ${options.translationMemory}`
+                )
+              );
+              lines.push(
+                chalk.yellow(
+                  `[dry-run] Match threshold: ${options.tmThreshold ?? 75}`
+                )
+              );
+              lines.push(
+                chalk.yellow(
+                  `[dry-run] Model: quality_optimized (forced by --translation-memory)`
+                )
+              );
+            }
+            if (options.formality) {
+              lines.push(
+                chalk.yellow(`[dry-run] Formality: ${options.formality}`)
+              );
+            }
+
+            Logger.output(lines.join('\n'));
+            return;
           }
 
-          Logger.output(lines.join('\n'));
-          return;
-        }
+          const translateCommand = await createTranslateCommand(
+            deps,
+            options.apiUrl
+          );
 
-        const translateCommand = await createTranslateCommand(deps, options.apiUrl);
+          let result: string;
 
-        let result: string;
+          if (text !== undefined) {
+            result = await translateCommand.translate(
+              text,
+              options as { to: string } & typeof options
+            );
+          } else {
+            result = await translateCommand.translateFromStdin(
+              options as { to: string } & typeof options
+            );
+          }
 
-        if (text !== undefined) {
-          result = await translateCommand.translate(text, options as { to: string } & typeof options);
-        } else {
-          result = await translateCommand.translateFromStdin(options as { to: string } & typeof options);
+          Logger.output(result);
+        } catch (error) {
+          handleError(error);
         }
-
-        Logger.output(result);
-      } catch (error) {
-        handleError(error);
       }
-    });
+    );
 }
diff --git a/src/cli/commands/register-usage.ts b/src/cli/commands/register-usage.ts
index 205e7532..a2e3cdc9 100644
--- a/src/cli/commands/register-usage.ts
+++ b/src/cli/commands/register-usage.ts
@@ -1,26 +1,36 @@
 import { Option, type Command } from 'commander';
 import { Logger } from '../../utils/logger.js';
-import { createUsageCommand, type CreateDeepLClient } from './service-factory.js';
+import {
+  createUsageCommand,
+  type CreateDeepLClient,
+} from './service-factory.js';
 
 export function registerUsage(
   program: Command,
   deps: {
     createDeepLClient: CreateDeepLClient;
     handleError: (error: unknown) => never;
-  },
+  }
 ): void {
   const { createDeepLClient, handleError } = deps;
 
   program
     .command('usage')
     .description('Show API usage statistics')
-    .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json', 'table']).default('text'))
-    .addHelpText('after', `
+    .addOption(
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json', 'table'])
+        .default('text')
+    )
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl usage
   $ deepl usage --format json
   $ deepl usage --format table
-`)
+`
+    )
     .action(async (options: { format?: string }) => {
       try {
         const usageCommand = await createUsageCommand(createDeepLClient);
@@ -30,7 +40,9 @@ Examples:
           Logger.output(JSON.stringify(usage, null, 2));
         } else if (options.format === 'table') {
           if (!process.stdout.isTTY) {
-            Logger.warn('WARN  --format table is not supported in non-TTY output; falling back to plain text');
+            Logger.warn(
+              'WARN  --format table is not supported in non-TTY output; falling back to plain text'
+            );
             Logger.output(usageCommand.formatUsage(usage));
           } else {
             Logger.output(usageCommand.formatUsageTable(usage));
diff --git a/src/cli/commands/register-voice.ts b/src/cli/commands/register-voice.ts
index 9ac63c58..d5b02bde 100644
--- a/src/cli/commands/register-voice.ts
+++ b/src/cli/commands/register-voice.ts
@@ -7,7 +7,7 @@ function parsePositiveInt(value: string, name: string, max: number): number {
   const n = parseInt(value, 10);
   if (isNaN(n) || n <= 0 || n > max) {
     throw new InvalidArgumentError(
-      `--${name} must be an integer between 1 and ${max}, got '${value}'`,
+      `--${name} must be an integer between 1 and ${max}, got '${value}'`
     );
   }
   return n;
@@ -17,7 +17,7 @@ function parseNonNegativeInt(value: string, name: string, max: number): number {
   const n = parseInt(value, 10);
   if (isNaN(n) || n < 0 || n > max) {
     throw new InvalidArgumentError(
-      `--${name} must be an integer between 0 and ${max}, got '${value}'`,
+      `--${name} must be an integer between 0 and ${max}, got '${value}'`
     );
   }
   return n;
@@ -25,31 +25,87 @@ function parseNonNegativeInt(value: string, name: string, max: number): number {
 
 export function registerVoice(
   program: Command,
-  deps: Pick<ServiceDeps, 'getApiKeyAndOptions' | 'createDeepLClient' | 'handleError'>,
+  deps: Pick<
+    ServiceDeps,
+    'getApiKeyAndOptions' | 'createDeepLClient' | 'handleError'
+  >
 ): void {
   const { handleError } = deps;
 
   program
     .command('voice')
-    .description('Translate audio using DeepL Voice API (real-time speech translation)')
+    .description(
+      'Translate audio using DeepL Voice API (real-time speech translation)'
+    )
     .argument('<file>', 'Audio file to translate (use "-" for stdin)')
     .optionsGroup('Core Options:')
-    .requiredOption('-t, --to <languages>', 'Target language(s), comma-separated, max 5')
-    .option('-f, --from <language>', 'Source language (auto-detect if not specified)')
+    .requiredOption(
+      '-t, --to <languages>',
+      'Target language(s), comma-separated, max 5'
+    )
+    .option(
+      '-f, --from <language>',
+      'Source language (auto-detect if not specified)'
+    )
     .optionsGroup('Translation Quality:')
-    .addOption(new Option('--formality <level>', 'Formality level (formal/informal are aliases for more/less)').choices(['default', 'more', 'less', 'prefer_more', 'prefer_less', 'formal', 'informal']))
-    .addOption(new Option('--source-language-mode <mode>', 'Source language detection mode').choices(['auto', 'fixed']))
+    .addOption(
+      new Option(
+        '--formality <level>',
+        'Formality level (formal/informal are aliases for more/less)'
+      ).choices([
+        'default',
+        'more',
+        'less',
+        'prefer_more',
+        'prefer_less',
+        'formal',
+        'informal',
+      ])
+    )
+    .addOption(
+      new Option(
+        '--source-language-mode <mode>',
+        'Source language detection mode'
+      ).choices(['auto', 'fixed'])
+    )
     .option('--glossary <name-or-id>', 'Use glossary by name or ID')
     .optionsGroup('Streaming & Audio:')
-    .option('--content-type <type>', 'Audio content type (auto-detected from extension: ogg, opus, webm, mka, flac, mp3, pcm)')
-    .option('--chunk-size <bytes>', 'Audio chunk size in bytes (default: 6400)', (v) => parsePositiveInt(v, 'chunk-size', 10_485_760))
-    .option('--chunk-interval <ms>', 'Interval between chunks in ms (default: 200)', (v) => parsePositiveInt(v, 'chunk-interval', 60_000))
-    .option('--no-stream', 'Disable live streaming output (collect and print at end)')
-    .option('--no-reconnect', 'Disable automatic reconnection on WebSocket drop')
-    .option('--max-reconnect-attempts <n>', 'Maximum reconnect attempts (default: 3)', (v) => parseNonNegativeInt(v, 'max-reconnect-attempts', 100))
+    .option(
+      '--content-type <type>',
+      'Audio content type (auto-detected from extension: ogg, opus, webm, mka, flac, mp3, pcm)'
+    )
+    .option(
+      '--chunk-size <bytes>',
+      'Audio chunk size in bytes (default: 6400)',
+      (v) => parsePositiveInt(v, 'chunk-size', 10_485_760)
+    )
+    .option(
+      '--chunk-interval <ms>',
+      'Interval between chunks in ms (default: 200)',
+      (v) => parsePositiveInt(v, 'chunk-interval', 60_000)
+    )
+    .option(
+      '--no-stream',
+      'Disable live streaming output (collect and print at end)'
+    )
+    .option(
+      '--no-reconnect',
+      'Disable automatic reconnection on WebSocket drop'
+    )
+    .option(
+      '--max-reconnect-attempts <n>',
+      'Maximum reconnect attempts (default: 3)',
+      (v) => parseNonNegativeInt(v, 'max-reconnect-attempts', 100)
+    )
     .optionsGroup('Output:')
-    .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-    .addHelpText('after', `
+    .addOption(
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
+    )
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl voice recording.ogg --to de
   $ deepl voice meeting.mp3 --to es,fr,de
@@ -57,55 +113,67 @@ Examples:
   $ cat audio.pcm | deepl voice - --to es --content-type 'audio/pcm;encoding=s16le;rate=16000'
   $ deepl voice speech.ogg --to de --no-stream
   $ deepl voice speech.ogg --to de --format json
-`)
-    .action(async (file: string, options: {
-      to: string;
-      from?: string;
-      formality?: string;
-      sourceLanguageMode?: string;
-      glossary?: string;
-      contentType?: string;
-      chunkSize?: number;
-      chunkInterval?: number;
-      stream?: boolean;
-      reconnect?: boolean;
-      maxReconnectAttempts?: number;
-      format?: string;
-    }) => {
-      try {
-        // Ahead of the resolution below, which costs a glossary-list round trip:
-        // a command that fails locally must not spend one first. Imported
-        // dynamically to keep the voice module off every other command's path.
-        const { validateVoiceOptions } = await import('./voice.js');
-        const { targetLangs, sourceLang } = validateVoiceOptions(options);
+`
+    )
+    .action(
+      async (
+        file: string,
+        options: {
+          to: string;
+          from?: string;
+          formality?: string;
+          sourceLanguageMode?: string;
+          glossary?: string;
+          contentType?: string;
+          chunkSize?: number;
+          chunkInterval?: number;
+          stream?: boolean;
+          reconnect?: boolean;
+          maxReconnectAttempts?: number;
+          format?: string;
+        }
+      ) => {
+        try {
+          // Ahead of the resolution below, which costs a glossary-list round trip:
+          // a command that fails locally must not spend one first. Imported
+          // dynamically to keep the voice module off every other command's path.
+          const { validateVoiceOptions } = await import('./voice.js');
+          const { targetLangs, sourceLang } = validateVoiceOptions(options);
+
+          if (options.glossary) {
+            const client = await deps.createDeepLClient();
+            const { GlossaryService } =
+              await import('../../services/glossary.js');
+            const glossaryService = new GlossaryService(client);
+            // The pair lets resolution check dictionary coverage locally. Without
+            // `--from` there is no pair to check, so the API judges it instead.
+            options.glossary = await glossaryService.resolveGlossaryId(
+              options.glossary,
+              sourceLang
+                ? {
+                    from: sourceLang as Language,
+                    targets: targetLangs as unknown as Language[],
+                  }
+                : undefined
+            );
+          }
 
-        if (options.glossary) {
-          const client = await deps.createDeepLClient();
-          const { GlossaryService } = await import('../../services/glossary.js');
-          const glossaryService = new GlossaryService(client);
-          // The pair lets resolution check dictionary coverage locally. Without
-          // `--from` there is no pair to check, so the API judges it instead.
-          options.glossary = await glossaryService.resolveGlossaryId(
-            options.glossary,
-            sourceLang
-              ? { from: sourceLang as Language, targets: targetLangs as unknown as Language[] }
-              : undefined,
+          const voiceCommand = await createVoiceCommand(
+            deps.getApiKeyAndOptions
           );
-        }
 
-        const voiceCommand = await createVoiceCommand(deps.getApiKeyAndOptions);
+          let result: string;
 
-        let result: string;
+          if (file === '-') {
+            result = await voiceCommand.translateFromStdin(options);
+          } else {
+            result = await voiceCommand.translate(file, options);
+          }
 
-        if (file === '-') {
-          result = await voiceCommand.translateFromStdin(options);
-        } else {
-          result = await voiceCommand.translate(file, options);
+          Logger.output(result);
+        } catch (error) {
+          handleError(error);
         }
-
-        Logger.output(result);
-      } catch (error) {
-        handleError(error);
       }
-    });
+    );
 }
diff --git a/src/cli/commands/register-watch.ts b/src/cli/commands/register-watch.ts
index a78fa3c3..bcb841ff 100644
--- a/src/cli/commands/register-watch.ts
+++ b/src/cli/commands/register-watch.ts
@@ -4,12 +4,12 @@ import chalk from 'chalk';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
 import { createWatchCommand, type ServiceDeps } from './service-factory.js';
-import { applyGlossarySourceLang, hasGlossarySelection } from '../../utils/glossary-params.js';
+import {
+  applyGlossarySourceLang,
+  hasGlossarySelection,
+} from '../../utils/glossary-params.js';
 
-export function registerWatch(
-  program: Command,
-  deps: ServiceDeps,
-): void {
+export function registerWatch(program: Command, deps: ServiceDeps): void {
   const { handleError } = deps;
 
   program
@@ -17,112 +17,182 @@ export function registerWatch(
     .description('Watch files/directories for changes and auto-translate')
     .argument('<path>', 'File or directory path to watch')
     .optionsGroup('Core Options:')
-    .option('-t, --to <languages>', 'Target language(s), comma-separated (uses config default if omitted)')
-    .option('-f, --from <language>', 'Source language (auto-detect if not specified)')
-    .option('-o, --output <path>', 'Output directory (default: <path>/translations or same dir for files)')
+    .option(
+      '-t, --to <languages>',
+      'Target language(s), comma-separated (uses config default if omitted)'
+    )
+    .option(
+      '-f, --from <language>',
+      'Source language (auto-detect if not specified)'
+    )
+    .option(
+      '-o, --output <path>',
+      'Output directory (default: <path>/translations or same dir for files)'
+    )
     .optionsGroup('Translation Quality:')
-    .addOption(new Option('--formality <level>', 'Formality level').choices(['default', 'more', 'less', 'prefer_more', 'prefer_less', 'formal', 'informal']))
-    .option('--glossary <name-or-id>', 'Use glossary by name or ID (requires --from; the API rejects a glossary without a source language)')
-    .option('--preserve-code', 'Preserve code blocks and variables during translation')
-    .option('--preserve-formatting', 'Preserve line breaks and whitespace formatting')
+    .addOption(
+      new Option('--formality <level>', 'Formality level').choices([
+        'default',
+        'more',
+        'less',
+        'prefer_more',
+        'prefer_less',
+        'formal',
+        'informal',
+      ])
+    )
+    .option(
+      '--glossary <name-or-id>',
+      'Use glossary by name or ID (requires --from; the API rejects a glossary without a source language)'
+    )
+    .option(
+      '--preserve-code',
+      'Preserve code blocks and variables during translation'
+    )
+    .option(
+      '--preserve-formatting',
+      'Preserve line breaks and whitespace formatting'
+    )
     .optionsGroup('Watch Behavior:')
-    .option('--pattern <pattern>', 'Glob pattern for file filtering (e.g., "*.md")')
-    .option('--debounce <ms>', 'Debounce delay in milliseconds (default: 500)', parseInt)
-    .option('--concurrency <number>', 'Max parallel translations (default: 5)', parseInt)
-    .option('--dry-run', 'Show what would be watched without starting the watcher')
+    .option(
+      '--pattern <pattern>',
+      'Glob pattern for file filtering (e.g., "*.md")'
+    )
+    .option(
+      '--debounce <ms>',
+      'Debounce delay in milliseconds (default: 500)',
+      parseInt
+    )
+    .option(
+      '--concurrency <number>',
+      'Max parallel translations (default: 5)',
+      parseInt
+    )
+    .option(
+      '--dry-run',
+      'Show what would be watched without starting the watcher'
+    )
     .option('--git-staged', 'Only watch git-staged files (snapshot at startup)')
     .optionsGroup('Git Integration:')
     .option('--auto-commit', 'Automatically commit translations to git')
-    .addHelpText('after', `
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl watch ./docs --to es,fr
   $ deepl watch ./src/i18n --to de --pattern "*.json" --auto-commit
   $ deepl watch README.md --to ja --debounce 500
-`)
-    .action(async (watchPath: string, options: {
-      to?: string;
-      from?: string;
-      output?: string;
-      formality?: string;
-      preserveCode?: boolean;
-      preserveFormatting?: boolean;
-      pattern?: string;
-      debounce?: number;
-      concurrency?: number;
-      glossary?: string;
-      autoCommit?: boolean;
-      gitStaged?: boolean;
-      dryRun?: boolean;
-    }) => {
-      try {
-        if (!options.to) {
-          const configService = deps.getConfigService();
-          const targetLangs = configService.getValue<string[]>('defaults.targetLangs');
-          if (targetLangs && targetLangs.length > 0) {
-            options.to = targetLangs.join(',');
-          } else {
-            throw new ValidationError(
-              'No target language specified.',
-              'Use --to <lang>:   deepl watch ./docs --to de\n  Set a default:     deepl init',
+`
+    )
+    .action(
+      async (
+        watchPath: string,
+        options: {
+          to?: string;
+          from?: string;
+          output?: string;
+          formality?: string;
+          preserveCode?: boolean;
+          preserveFormatting?: boolean;
+          pattern?: string;
+          debounce?: number;
+          concurrency?: number;
+          glossary?: string;
+          autoCommit?: boolean;
+          gitStaged?: boolean;
+          dryRun?: boolean;
+        }
+      ) => {
+        try {
+          if (!options.to) {
+            const configService = deps.getConfigService();
+            const targetLangs = configService.getValue<string[]>(
+              'defaults.targetLangs'
             );
+            if (targetLangs && targetLangs.length > 0) {
+              options.to = targetLangs.join(',');
+            } else {
+              throw new ValidationError(
+                'No target language specified.',
+                'Use --to <lang>:   deepl watch ./docs --to de\n  Set a default:     deepl init'
+              );
+            }
           }
-        }
-
-        // Resolved before --dry-run, which otherwise reports a command as
-        // runnable when it would fail on the first file change.
-        if (hasGlossarySelection(options)) {
-          applyGlossarySourceLang(
-            options,
-            deps.getConfigService().getValue<string>('defaults.sourceLang'),
-            'Example: deepl watch ./docs --from en --to es --glossary my-glossary',
-          );
-        }
 
-        if (options.dryRun) {
-          const targetLangs = options.to.split(',').map(l => l.trim()).filter(l => l.length > 0);
-          const isDirectory = fs.existsSync(watchPath) && fs.statSync(watchPath).isDirectory();
-          let outputDir: string;
-          if (options.output) {
-            outputDir = options.output;
-          } else if (isDirectory) {
-            outputDir = `${watchPath}/translations`;
-          } else {
-            const parts = watchPath.split('/');
-            parts.pop();
-            outputDir = parts.join('/') || '.';
+          // Resolved before --dry-run, which otherwise reports a command as
+          // runnable when it would fail on the first file change.
+          if (hasGlossarySelection(options)) {
+            applyGlossarySourceLang(
+              options,
+              deps.getConfigService().getValue<string>('defaults.sourceLang'),
+              'Example: deepl watch ./docs --from en --to es --glossary my-glossary'
+            );
           }
 
-          const lines = [
-            chalk.yellow('[dry-run] Watch mode will not be started.'),
-            chalk.yellow(`[dry-run] Would watch: ${watchPath}`),
-            chalk.yellow(`[dry-run] Target language(s): ${targetLangs.join(', ')}`),
-            chalk.yellow(`[dry-run] Output directory: ${outputDir}`),
-          ];
-          if (options.pattern) {
-            lines.push(chalk.yellow(`[dry-run] File pattern: ${options.pattern}`));
-          }
-          if (options.from) {
-            lines.push(chalk.yellow(`[dry-run] Source language: ${options.from}`));
-          }
-          if (options.gitStaged) {
-            lines.push(chalk.yellow(`[dry-run] Git-staged: only watching staged files`));
-          }
-          if (options.autoCommit) {
-            lines.push(chalk.yellow(`[dry-run] Auto-commit: enabled`));
-          }
-          if (options.debounce) {
-            lines.push(chalk.yellow(`[dry-run] Debounce: ${options.debounce}ms`));
+          if (options.dryRun) {
+            const targetLangs = options.to
+              .split(',')
+              .map((l) => l.trim())
+              .filter((l) => l.length > 0);
+            const isDirectory =
+              fs.existsSync(watchPath) && fs.statSync(watchPath).isDirectory();
+            let outputDir: string;
+            if (options.output) {
+              outputDir = options.output;
+            } else if (isDirectory) {
+              outputDir = `${watchPath}/translations`;
+            } else {
+              const parts = watchPath.split('/');
+              parts.pop();
+              outputDir = parts.join('/') || '.';
+            }
+
+            const lines = [
+              chalk.yellow('[dry-run] Watch mode will not be started.'),
+              chalk.yellow(`[dry-run] Would watch: ${watchPath}`),
+              chalk.yellow(
+                `[dry-run] Target language(s): ${targetLangs.join(', ')}`
+              ),
+              chalk.yellow(`[dry-run] Output directory: ${outputDir}`),
+            ];
+            if (options.pattern) {
+              lines.push(
+                chalk.yellow(`[dry-run] File pattern: ${options.pattern}`)
+              );
+            }
+            if (options.from) {
+              lines.push(
+                chalk.yellow(`[dry-run] Source language: ${options.from}`)
+              );
+            }
+            if (options.gitStaged) {
+              lines.push(
+                chalk.yellow(`[dry-run] Git-staged: only watching staged files`)
+              );
+            }
+            if (options.autoCommit) {
+              lines.push(chalk.yellow(`[dry-run] Auto-commit: enabled`));
+            }
+            if (options.debounce) {
+              lines.push(
+                chalk.yellow(`[dry-run] Debounce: ${options.debounce}ms`)
+              );
+            }
+            lines.push(
+              chalk.yellow(
+                '[dry-run] On file change, translations would be triggered for the above target languages.'
+              )
+            );
+            Logger.output(lines.join('\n'));
+            return;
           }
-          lines.push(chalk.yellow('[dry-run] On file change, translations would be triggered for the above target languages.'));
-          Logger.output(lines.join('\n'));
-          return;
-        }
 
-        const watchCommand = await createWatchCommand(deps);
+          const watchCommand = await createWatchCommand(deps);
 
-        await watchCommand.watch(watchPath, { ...options, to: options.to });
-      } catch (error) {
-        handleError(error);
+          await watchCommand.watch(watchPath, { ...options, to: options.to });
+        } catch (error) {
+          handleError(error);
+        }
       }
-    });
+    );
 }
diff --git a/src/cli/commands/register-write.ts b/src/cli/commands/register-write.ts
index 5d573627..9dfaad04 100644
--- a/src/cli/commands/register-write.ts
+++ b/src/cli/commands/register-write.ts
@@ -2,7 +2,11 @@ import { type Command, Option } from 'commander';
 import { existsSync } from 'fs';
 import { atomicWriteFile } from '../../utils/atomic-write.js';
 import chalk from 'chalk';
-import type { WriteLanguage, WritingStyle, WriteTone } from '../../types/index.js';
+import type {
+  WriteLanguage,
+  WritingStyle,
+  WriteTone,
+} from '../../types/index.js';
 import { WRITE_TARGET_LANGUAGES } from '../../data/language-entries.js';
 import { looksLikeLanguageTag } from '../../data/language-registry.js';
 import { Logger } from '../../utils/logger.js';
@@ -25,13 +29,36 @@ export const WRITE_LANGUAGES = WRITE_TARGET_LANGUAGES;
  * accepts any casing and echoes its own (`en-GB`, `zh-Hans`) regardless.
  */
 const WRITE_LANGUAGE_BY_LOWERCASE = new Map<string, WriteLanguage>(
-  WRITE_LANGUAGES.map((language) => [language.toLowerCase(), language]),
+  WRITE_LANGUAGES.map((language) => [language.toLowerCase(), language])
 );
 
-const WRITE_STYLES = ['default', 'simple', 'business', 'academic', 'casual', 'prefer_simple', 'prefer_business', 'prefer_academic', 'prefer_casual'] as const;
-const WRITE_TONES = ['default', 'enthusiastic', 'friendly', 'confident', 'diplomatic', 'prefer_enthusiastic', 'prefer_friendly', 'prefer_confident', 'prefer_diplomatic'] as const;
-
-export type WriteDeps = Pick<ServiceDeps, 'createDeepLClient' | 'getConfigService' | 'getCacheService' | 'handleError'>;
+const WRITE_STYLES = [
+  'default',
+  'simple',
+  'business',
+  'academic',
+  'casual',
+  'prefer_simple',
+  'prefer_business',
+  'prefer_academic',
+  'prefer_casual',
+] as const;
+const WRITE_TONES = [
+  'default',
+  'enthusiastic',
+  'friendly',
+  'confident',
+  'diplomatic',
+  'prefer_enthusiastic',
+  'prefer_friendly',
+  'prefer_confident',
+  'prefer_diplomatic',
+] as const;
+
+export type WriteDeps = Pick<
+  ServiceDeps,
+  'createDeepLClient' | 'getConfigService' | 'getCacheService' | 'handleError'
+>;
 
 interface WriteActionOptions {
   lang?: string;
@@ -58,7 +85,7 @@ interface WriteActionOptions {
  */
 export function createWriteAction(
   deps: WriteDeps,
-  mode: 'write' | 'correct',
+  mode: 'write' | 'correct'
 ): (text: string | undefined, options: WriteActionOptions) => Promise<void> {
   const { handleError } = deps;
   const correct = mode === 'correct';
@@ -66,9 +93,13 @@ export function createWriteAction(
 
   return async (text: string | undefined, options: WriteActionOptions) => {
     try {
-      if (options.to !== undefined && options.lang !== undefined && options.to !== options.lang) {
+      if (
+        options.to !== undefined &&
+        options.lang !== undefined &&
+        options.to !== options.lang
+      ) {
         throw new ValidationError(
-          'Cannot specify both --to and --lang with different values. --to is an alias of --lang; pick one.',
+          'Cannot specify both --to and --lang with different values. --to is an alias of --lang; pick one.'
         );
       }
       if (options.to !== undefined && options.lang === undefined) {
@@ -79,13 +110,17 @@ export function createWriteAction(
         const { readStdin } = await import('../../utils/read-stdin.js');
         const stdinText = await readStdin();
         if (!stdinText || stdinText.trim() === '') {
-          throw new ValidationError('No input provided. Provide text as an argument, a file path, or pipe via stdin.');
+          throw new ValidationError(
+            'No input provided. Provide text as an argument, a file path, or pipe via stdin.'
+          );
         }
         text = stdinText;
       }
 
       if (options.lang) {
-        const canonical = WRITE_LANGUAGE_BY_LOWERCASE.get(options.lang.toLowerCase());
+        const canonical = WRITE_LANGUAGE_BY_LOWERCASE.get(
+          options.lang.toLowerCase()
+        );
         if (canonical) {
           options.lang = canonical;
         } else if (looksLikeLanguageTag(options.lang.toLowerCase())) {
@@ -97,24 +132,40 @@ export function createWriteAction(
           );
           options.lang = options.lang.toLowerCase();
         } else {
-          throw new ValidationError(`Invalid language code: ${options.lang}. Valid options: ${WRITE_LANGUAGES.join(', ')}`);
+          throw new ValidationError(
+            `Invalid language code: ${options.lang}. Valid options: ${WRITE_LANGUAGES.join(', ')}`
+          );
         }
       }
 
-      if (options.style && !(WRITE_STYLES as readonly string[]).includes(options.style)) {
-        throw new ValidationError(`Invalid writing style: ${options.style}. Valid options: ${WRITE_STYLES.join(', ')}`);
+      if (
+        options.style &&
+        !(WRITE_STYLES as readonly string[]).includes(options.style)
+      ) {
+        throw new ValidationError(
+          `Invalid writing style: ${options.style}. Valid options: ${WRITE_STYLES.join(', ')}`
+        );
       }
 
-      if (options.tone && !(WRITE_TONES as readonly string[]).includes(options.tone)) {
-        throw new ValidationError(`Invalid tone: ${options.tone}. Valid options: ${WRITE_TONES.join(', ')}`);
+      if (
+        options.tone &&
+        !(WRITE_TONES as readonly string[]).includes(options.tone)
+      ) {
+        throw new ValidationError(
+          `Invalid tone: ${options.tone}. Valid options: ${WRITE_TONES.join(', ')}`
+        );
       }
 
       if (options.style && options.tone) {
-        throw new ValidationError('Cannot specify both --style and --tone. Use one or the other.');
+        throw new ValidationError(
+          'Cannot specify both --style and --tone. Use one or the other.'
+        );
       }
 
       if (options.interactive && (isNoInput() || !process.stdin.isTTY)) {
-        throw new ValidationError('--interactive requires an interactive terminal. Run without --interactive in CI or non-TTY environments, or pipe input via stdin.');
+        throw new ValidationError(
+          '--interactive requires an interactive terminal. Run without --interactive in CI or non-TTY environments, or pipe input via stdin.'
+        );
       }
 
       if (options.backup && !options.fix) {
@@ -152,7 +203,11 @@ export function createWriteAction(
         }
 
         if (needsImprovement) {
-          Logger.warn(chalk.yellow(`⚠ Text ${needsChangesLabel} (${changes} potential changes)`));
+          Logger.warn(
+            chalk.yellow(
+              `⚠ Text ${needsChangesLabel} (${changes} potential changes)`
+            )
+          );
           process.exitCode = ExitCode.CheckFailed;
         } else {
           Logger.success(chalk.green('✓ Text looks good'));
@@ -168,13 +223,19 @@ export function createWriteAction(
         const result = await writeCommand.autoFixFile(text, writeOptions);
 
         if (result.fixed) {
-          Logger.success(chalk.green(correct ? '✓ File corrected' : '✓ File improved'));
+          Logger.success(
+            chalk.green(correct ? '✓ File corrected' : '✓ File improved')
+          );
           if (result.backupPath) {
             Logger.info(chalk.gray(`Backup: ${result.backupPath}`));
           }
           Logger.info(chalk.gray(`Changes: ${result.changes}`));
         } else {
-          Logger.success(chalk.green(correct ? '✓ No corrections needed' : '✓ No improvements needed'));
+          Logger.success(
+            chalk.green(
+              correct ? '✓ No corrections needed' : '✓ No improvements needed'
+            )
+          );
         }
         return;
       }
@@ -203,10 +264,12 @@ export function createWriteAction(
         let result: string;
 
         if (existsSync(text)) {
-          const interactiveResult = await writeCommand.improveFileInteractive(text, writeOptions);
+          const interactiveResult = await writeCommand.improveFileInteractive(
+            text,
+            writeOptions
+          );
           result = interactiveResult.selected;
 
-
           if (options.output || options.inPlace) {
             const outputPath = options.inPlace ? text : options.output!;
             await atomicWriteFile(outputPath, result, 'utf-8');
@@ -217,7 +280,9 @@ export function createWriteAction(
         }
 
         Logger.output();
-        Logger.output(chalk.bold(correct ? 'Selected correction:' : 'Selected improvement:'));
+        Logger.output(
+          chalk.bold(correct ? 'Selected correction:' : 'Selected improvement:')
+        );
         Logger.output(result);
         return;
       }
@@ -240,35 +305,50 @@ export function createWriteAction(
   };
 }
 
-export function registerWrite(
-  program: Command,
-  deps: WriteDeps,
-): void {
+export function registerWrite(program: Command, deps: WriteDeps): void {
   program
     .command('write')
     .alias('w')
     .description('Improve text using DeepL Write API (grammar, style, tone)')
     .argument('[text]', 'Text to improve, file path, or read from stdin')
     .optionsGroup('Core Options:')
-    .option('-l, --lang <language>', `Target language: ${WRITE_LANGUAGES.join(', ')} (auto-detect if omitted)`)
-    .option('--to <language>', 'Alias of --lang — accepts the same language values. Provided for muscle-memory consistency with `deepl translate --to`.')
+    .option(
+      '-l, --lang <language>',
+      `Target language: ${WRITE_LANGUAGES.join(', ')} (auto-detect if omitted)`
+    )
+    .option(
+      '--to <language>',
+      'Alias of --lang — accepts the same language values. Provided for muscle-memory consistency with `deepl translate --to`.'
+    )
     .option('--style <style>', `Writing style: ${WRITE_STYLES.join(', ')}`)
     .option('--tone <tone>', `Tone: ${WRITE_TONES.join(', ')}`)
     .optionsGroup('Output Modes:')
     .option('-a, --alternatives', 'Show all alternative improvements')
     .option('-o, --output <file>', 'Write improved text to file')
     .option('--in-place', 'Edit file in place (use with file input)')
-    .option('-i, --interactive', 'Interactive mode - choose from multiple suggestions')
+    .option(
+      '-i, --interactive',
+      'Interactive mode - choose from multiple suggestions'
+    )
     .option('-d, --diff', 'Show diff between original and improved text')
     .optionsGroup('Fix Operations:')
-    .option('--check', 'Check if text needs improvement (exit 0 if clean, exit 8 if changes needed)')
+    .option(
+      '--check',
+      'Check if text needs improvement (exit 0 if clean, exit 8 if changes needed)'
+    )
     .option('--fix', 'Automatically fix file in place')
     .option('-b, --backup', 'Create backup file before fixing (use with --fix)')
     .optionsGroup('Advanced:')
     .option('--no-cache', 'Bypass cache for this request')
     .optionsGroup('Output:')
-    .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
-    .addHelpText('after', `
+    .addOption(
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
+    )
+    .addHelpText(
+      'after',
+      `
 Examples:
   $ deepl write "Their going to the store" --lang en-US
   $ deepl write "Their going to the store" --to en-US      (--to is an alias of --lang)
@@ -281,6 +361,7 @@ Examples:
   $ deepl write "Hello world" --alternatives
   $ deepl write report.txt --output improved.txt
   $ deepl write "Text here" --format json
-`)
+`
+    )
     .action(createWriteAction(deps, 'write'));
 }
diff --git a/src/cli/commands/service-factory.ts b/src/cli/commands/service-factory.ts
index 67df690c..8b0d4cf6 100644
--- a/src/cli/commands/service-factory.ts
+++ b/src/cli/commands/service-factory.ts
@@ -15,8 +15,13 @@ import type { DetectCommand } from './detect.js';
 import type { LanguagesCommand } from './languages.js';
 import type { SyncCommand } from './sync-command.js';
 
-export type CreateDeepLClient = (overrideBaseUrl?: string) => Promise<DeepLClient>;
-export type GetApiKeyAndOptions = () => { apiKey: string; options: DeepLClientOptions };
+export type CreateDeepLClient = (
+  overrideBaseUrl?: string
+) => Promise<DeepLClient>;
+export type GetApiKeyAndOptions = () => {
+  apiKey: string;
+  options: DeepLClientOptions;
+};
 
 export interface ServiceDeps {
   createDeepLClient: CreateDeepLClient;
@@ -27,7 +32,7 @@ export interface ServiceDeps {
 }
 
 export async function createGlossaryCommand(
-  createDeepLClient: CreateDeepLClient,
+  createDeepLClient: CreateDeepLClient
 ): Promise<GlossaryCommand> {
   const client = await createDeepLClient();
   const { GlossaryService } = await import('../../services/glossary.js');
@@ -37,7 +42,7 @@ export async function createGlossaryCommand(
 }
 
 export async function createTmCommand(
-  createDeepLClient: CreateDeepLClient,
+  createDeepLClient: CreateDeepLClient
 ): Promise<TmCommand> {
   const client = await createDeepLClient();
   const { TmCommand: TmCmd } = await import('./tm.js');
@@ -46,7 +51,7 @@ export async function createTmCommand(
 
 export async function createAdminCommand(
   createDeepLClient: CreateDeepLClient,
-  getApiKeyAndOptions?: GetApiKeyAndOptions,
+  getApiKeyAndOptions?: GetApiKeyAndOptions
 ): Promise<AdminCommand> {
   const client = await createDeepLClient();
   const { AdminService } = await import('../../services/admin.js');
@@ -56,18 +61,25 @@ export async function createAdminCommand(
 }
 
 export async function createWriteCommand(
-  deps: Pick<ServiceDeps, 'createDeepLClient' | 'getConfigService' | 'getCacheService'>,
+  deps: Pick<
+    ServiceDeps,
+    'createDeepLClient' | 'getConfigService' | 'getCacheService'
+  >
 ): Promise<WriteCommand> {
   const client = await deps.createDeepLClient();
   const { WriteService } = await import('../../services/write.js');
   const { WriteCommand: WriteCmd } = await import('./write.js');
   const configService = deps.getConfigService();
-  const writeService = new WriteService(client, configService, await deps.getCacheService());
+  const writeService = new WriteService(
+    client,
+    configService,
+    await deps.getCacheService()
+  );
   return new WriteCmd(writeService);
 }
 
 export async function createStyleRulesCommand(
-  createDeepLClient: CreateDeepLClient,
+  createDeepLClient: CreateDeepLClient
 ): Promise<StyleRulesCommand> {
   const client = await createDeepLClient();
   const { StyleRulesService } = await import('../../services/style-rules.js');
@@ -77,7 +89,7 @@ export async function createStyleRulesCommand(
 }
 
 export async function createUsageCommand(
-  createDeepLClient: CreateDeepLClient,
+  createDeepLClient: CreateDeepLClient
 ): Promise<UsageCommand> {
   const client = await createDeepLClient();
   const { UsageService } = await import('../../services/usage.js');
@@ -87,35 +99,59 @@ export async function createUsageCommand(
 }
 
 export async function createTranslateCommand(
-  deps: Pick<ServiceDeps, 'createDeepLClient' | 'getConfigService' | 'getCacheService'>,
-  overrideBaseUrl?: string,
+  deps: Pick<
+    ServiceDeps,
+    'createDeepLClient' | 'getConfigService' | 'getCacheService'
+  >,
+  overrideBaseUrl?: string
 ): Promise<TranslateCommand> {
   const client = await deps.createDeepLClient(overrideBaseUrl);
   const { TranslationService } = await import('../../services/translation.js');
-  const { DocumentTranslationService } = await import('../../services/document-translation.js');
+  const { DocumentTranslationService } =
+    await import('../../services/document-translation.js');
   const { GlossaryService } = await import('../../services/glossary.js');
   const { TranslateCommand: TranslateCmd } = await import('./translate.js');
   const configService = deps.getConfigService();
-  const translationService = new TranslationService(client, configService, await deps.getCacheService());
+  const translationService = new TranslationService(
+    client,
+    configService,
+    await deps.getCacheService()
+  );
   const documentTranslationService = new DocumentTranslationService(client);
   const glossaryService = new GlossaryService(client);
-  return new TranslateCmd(translationService, documentTranslationService, glossaryService, configService);
+  return new TranslateCmd(
+    translationService,
+    documentTranslationService,
+    glossaryService,
+    configService
+  );
 }
 
 export async function createWatchCommand(
-  deps: Pick<ServiceDeps, 'createDeepLClient' | 'getConfigService' | 'getCacheService'>,
+  deps: Pick<
+    ServiceDeps,
+    'createDeepLClient' | 'getConfigService' | 'getCacheService'
+  >
 ): Promise<WatchCommand> {
   const client = await deps.createDeepLClient();
   const { TranslationService } = await import('../../services/translation.js');
   const { GlossaryService } = await import('../../services/glossary.js');
   const { WatchCommand: WatchCmd } = await import('./watch.js');
-  const translationService = new TranslationService(client, deps.getConfigService(), await deps.getCacheService());
+  const translationService = new TranslationService(
+    client,
+    deps.getConfigService(),
+    await deps.getCacheService()
+  );
   const glossaryService = new GlossaryService(client);
-  return new WatchCmd(translationService, glossaryService, deps.getConfigService());
+  return new WatchCmd(
+    translationService,
+    glossaryService,
+    deps.getConfigService()
+  );
 }
 
 export async function createDetectCommand(
-  createDeepLClient: CreateDeepLClient,
+  createDeepLClient: CreateDeepLClient
 ): Promise<DetectCommand> {
   const client = await createDeepLClient();
   const { DetectService } = await import('../../services/detect.js');
@@ -125,7 +161,7 @@ export async function createDetectCommand(
 }
 
 export async function createLanguagesCommand(
-  client: DeepLClient | null,
+  client: DeepLClient | null
 ): Promise<LanguagesCommand> {
   const { LanguagesService } = await import('../../services/languages.js');
   const { LanguagesCommand: LanguagesCmd } = await import('./languages.js');
@@ -134,7 +170,7 @@ export async function createLanguagesCommand(
 }
 
 export async function createVoiceCommand(
-  getApiKeyAndOptions: GetApiKeyAndOptions,
+  getApiKeyAndOptions: GetApiKeyAndOptions
 ): Promise<VoiceCommand> {
   const { apiKey, options } = getApiKeyAndOptions();
   if (options.baseUrl) {
@@ -150,7 +186,10 @@ export async function createVoiceCommand(
 }
 
 export async function createSyncCommand(
-  deps: Pick<ServiceDeps, 'createDeepLClient' | 'getConfigService' | 'getCacheService'>,
+  deps: Pick<
+    ServiceDeps,
+    'createDeepLClient' | 'getConfigService' | 'getCacheService'
+  >
 ): Promise<SyncCommand> {
   const client = await deps.createDeepLClient();
   const { TranslationService } = await import('../../services/translation.js');
@@ -160,9 +199,17 @@ export async function createSyncCommand(
   const { createDefaultRegistry } = await import('../../formats/index.js');
 
   const configService = deps.getConfigService();
-  const translationService = new TranslationService(client, configService, await deps.getCacheService());
+  const translationService = new TranslationService(
+    client,
+    configService,
+    await deps.getCacheService()
+  );
   const glossaryService = new GlossaryService(client);
   const formatRegistry = await createDefaultRegistry();
-  const syncService = new SyncService(translationService, glossaryService, formatRegistry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    formatRegistry
+  );
   return new SyncCmd(syncService);
 }
diff --git a/src/cli/commands/style-rules.ts b/src/cli/commands/style-rules.ts
index b6f5831c..b2a0c5a5 100644
--- a/src/cli/commands/style-rules.ts
+++ b/src/cli/commands/style-rules.ts
@@ -21,11 +21,17 @@ import { isColorEnabled } from '../../utils/formatters.js';
 
 /** Total leaf settings across all categories. Used as the "Rules" count column. */
 function countConfiguredRules(rules: ConfiguredRules): number {
-  return Object.values(rules).reduce((sum, group) => sum + Object.keys(group).length, 0);
+  return Object.values(rules).reduce(
+    (sum, group) => sum + Object.keys(group).length,
+    0
+  );
 }
 
 /** Render the configured-rules dictionary as indented text lines, sanitized. */
-function renderConfiguredRulesText(rules: ConfiguredRules, lines: string[]): void {
+function renderConfiguredRulesText(
+  rules: ConfiguredRules,
+  lines: string[]
+): void {
   if (countConfiguredRules(rules) === 0) {
     return;
   }
@@ -33,7 +39,9 @@ function renderConfiguredRulesText(rules: ConfiguredRules, lines: string[]): voi
   for (const [category, settings] of Object.entries(rules)) {
     lines.push(`      ${sanitizeForTerminal(category)}:`);
     for (const [key, value] of Object.entries(settings)) {
-      lines.push(`        ${sanitizeForTerminal(key)}: ${sanitizeForTerminal(value)}`);
+      lines.push(
+        `        ${sanitizeForTerminal(key)}: ${sanitizeForTerminal(value)}`
+      );
     }
   }
 }
@@ -53,7 +61,9 @@ export class StyleRulesCommand {
    * List available style rules, optionally filtered by language.
    * Returns detailed rules (with configuredRules/customInstructions) when requested.
    */
-  async list(options: StyleRulesListOptions = {}): Promise<(StyleRule | StyleRuleDetailed)[]> {
+  async list(
+    options: StyleRulesListOptions = {}
+  ): Promise<(StyleRule | StyleRuleDetailed)[]> {
     return this.service.getStyleRules(options);
   }
 
@@ -80,8 +90,12 @@ export class StyleRulesCommand {
         if (detailed.customInstructions.length > 0) {
           lines.push(`    Custom Instructions:`);
           for (const instruction of detailed.customInstructions) {
-            const langSuffix = instruction.sourceLanguage ? ` [${instruction.sourceLanguage}]` : '';
-            lines.push(`      - ${sanitizeForTerminal(instruction.label)}: ${sanitizeForTerminal(instruction.prompt)}${langSuffix}`);
+            const langSuffix = instruction.sourceLanguage
+              ? ` [${instruction.sourceLanguage}]`
+              : '';
+            lines.push(
+              `      - ${sanitizeForTerminal(instruction.label)}: ${sanitizeForTerminal(instruction.prompt)}${langSuffix}`
+            );
           }
         }
       }
@@ -103,11 +117,21 @@ export class StyleRulesCommand {
       return 'No style rules found.';
     }
 
-    const detailed = rules.some(r => 'configuredRules' in r);
+    const detailed = rules.some((r) => 'configuredRules' in r);
     const head = detailed
-      ? ['Name', 'ID', 'Language', 'Version', 'Updated', 'Rules', 'Instructions']
+      ? [
+          'Name',
+          'ID',
+          'Language',
+          'Version',
+          'Updated',
+          'Rules',
+          'Instructions',
+        ]
       : ['Name', 'ID', 'Language', 'Version', 'Updated'];
-    const colWidths = detailed ? [24, 18, 10, 9, 22, 7, 14] : [30, 20, 10, 9, 22];
+    const colWidths = detailed
+      ? [24, 18, 10, 9, 22, 7, 14]
+      : [30, 20, 10, 9, 22];
     const colorDisabled = !isColorEnabled();
 
     const table = new Table({
@@ -169,11 +193,17 @@ export class StyleRulesCommand {
     return this.service.createStyleRule(options);
   }
 
-  async show(styleId: string, detailed = false): Promise<StyleRule | StyleRuleDetailed> {
+  async show(
+    styleId: string,
+    detailed = false
+  ): Promise<StyleRule | StyleRuleDetailed> {
     return this.service.getStyleRule(styleId, detailed);
   }
 
-  async update(styleId: string, options: UpdateStyleRuleOptions): Promise<StyleRule> {
+  async update(
+    styleId: string,
+    options: UpdateStyleRuleOptions
+  ): Promise<StyleRule> {
     return this.service.updateStyleRule(styleId, options);
   }
 
@@ -181,7 +211,10 @@ export class StyleRulesCommand {
     return this.service.deleteStyleRule(styleId);
   }
 
-  async replaceRules(styleId: string, rules: ConfiguredRules): Promise<StyleRuleDetailed> {
+  async replaceRules(
+    styleId: string,
+    rules: ConfiguredRules
+  ): Promise<StyleRuleDetailed> {
     return this.service.replaceConfiguredRules(styleId, rules);
   }
 
@@ -200,8 +233,12 @@ export class StyleRulesCommand {
       if (rule.customInstructions.length > 0) {
         lines.push(`    Custom Instructions:`);
         for (const instruction of rule.customInstructions) {
-          const langSuffix = instruction.sourceLanguage ? ` [${instruction.sourceLanguage}]` : '';
-          lines.push(`      - ${sanitizeForTerminal(instruction.label)}: ${sanitizeForTerminal(instruction.prompt)}${langSuffix}`);
+          const langSuffix = instruction.sourceLanguage
+            ? ` [${instruction.sourceLanguage}]`
+            : '';
+          lines.push(
+            `      - ${sanitizeForTerminal(instruction.label)}: ${sanitizeForTerminal(instruction.prompt)}${langSuffix}`
+          );
         }
       }
     }
@@ -221,7 +258,7 @@ export class StyleRulesCommand {
 
   async addInstruction(
     styleId: string,
-    options: CreateCustomInstructionOptions,
+    options: CreateCustomInstructionOptions
   ): Promise<CustomInstruction> {
     return this.service.createCustomInstruction(styleId, options);
   }
@@ -229,7 +266,7 @@ export class StyleRulesCommand {
   async updateInstruction(
     styleId: string,
     label: string,
-    options: UpdateCustomInstructionOptions,
+    options: UpdateCustomInstructionOptions
   ): Promise<CustomInstruction> {
     return this.service.updateCustomInstruction(styleId, label, options);
   }
@@ -240,7 +277,9 @@ export class StyleRulesCommand {
 
   /** Format a single custom instruction for human-readable terminal output. */
   formatCustomInstruction(instruction: CustomInstruction): string {
-    const langSuffix = instruction.sourceLanguage ? ` [${instruction.sourceLanguage}]` : '';
+    const langSuffix = instruction.sourceLanguage
+      ? ` [${instruction.sourceLanguage}]`
+      : '';
     return `  ${sanitizeForTerminal(instruction.label)}${langSuffix}\n    ${sanitizeForTerminal(instruction.prompt)}`;
   }
 
@@ -249,7 +288,10 @@ export class StyleRulesCommand {
     if (instructions.length === 0) {
       return 'No custom instructions found.';
     }
-    const lines: string[] = [`Found ${instructions.length} custom instruction(s):`, ''];
+    const lines: string[] = [
+      `Found ${instructions.length} custom instruction(s):`,
+      '',
+    ];
     for (const instruction of instructions) {
       lines.push(this.formatCustomInstruction(instruction));
       lines.push('');
@@ -258,7 +300,9 @@ export class StyleRulesCommand {
   }
 
   /** Serialize a custom instruction or list as pretty-printed JSON. */
-  formatCustomInstructionJson(data: CustomInstruction | CustomInstruction[]): string {
+  formatCustomInstructionJson(
+    data: CustomInstruction | CustomInstruction[]
+  ): string {
     return JSON.stringify(data, null, 2);
   }
 }
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index e25da13c..e6b39559 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -1,11 +1,24 @@
 import * as fsSync from 'fs';
-import { SyncService, type SyncResult, type SyncOptions, type SyncProgressEvent, type CancellationSignal } from '../../sync/sync-service.js';
-import { loadSyncConfig, type SyncConfigOverrides, type ResolvedSyncConfig } from '../../sync/sync-config.js';
+import {
+  SyncService,
+  type SyncResult,
+  type SyncOptions,
+  type SyncProgressEvent,
+  type CancellationSignal,
+} from '../../sync/sync-service.js';
+import {
+  loadSyncConfig,
+  type SyncConfigOverrides,
+  type ResolvedSyncConfig,
+} from '../../sync/sync-config.js';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
 import { ExitCode } from '../../utils/exit-codes.js';
 import { LOCK_FILE_NAME } from '../../sync/types.js';
-import { sweepStaleBackups as sweepStaleBackupsImpl, DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS } from '../../sync/sync-bak-cleanup.js';
+import {
+  sweepStaleBackups as sweepStaleBackupsImpl,
+  DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS,
+} from '../../sync/sync-bak-cleanup.js';
 import { claimGracefulShutdown } from '../../utils/signal-exit.js';
 
 export const STALE_BACKUP_AGE_MS = DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS * 1000;
@@ -95,7 +108,10 @@ export interface WatchController {
 
 export interface WatchControllerDeps {
   watcher: { close(): Promise<void> | void };
-  runSync: (signal: CancellationSignal, backupTracker: Set<string>) => Promise<void>;
+  runSync: (
+    signal: CancellationSignal,
+    backupTracker: Set<string>
+  ) => Promise<void>;
   projectRoot: string;
   staleBackupAgeMs: number;
   /** Bucket include-glob map for scoped .bak sweep. When absent the sweep falls back to full-tree walk. */
@@ -108,7 +124,9 @@ export interface WatchControllerDeps {
   clearPendingDebounce?: () => void;
 }
 
-export function createWatchController(deps: WatchControllerDeps): WatchController {
+export function createWatchController(
+  deps: WatchControllerDeps
+): WatchController {
   let syncing = false;
   let pendingRun = false;
   const cancellationSignal: CancellationSignal = { cancelled: false };
@@ -122,7 +140,9 @@ export function createWatchController(deps: WatchControllerDeps): WatchControlle
       } catch (err) {
         const code = (err as NodeJS.ErrnoException).code;
         if (code !== 'ENOENT') {
-          Logger.warn(`Failed to remove backup ${bakPath}: ${err instanceof Error ? err.message : String(err)}`);
+          Logger.warn(
+            `Failed to remove backup ${bakPath}: ${err instanceof Error ? err.message : String(err)}`
+          );
         }
       }
     }
@@ -163,7 +183,11 @@ export function createWatchController(deps: WatchControllerDeps): WatchControlle
   }
 
   async function sweepStaleBackups(): Promise<void> {
-    await sweepStaleBackupsImpl(deps.projectRoot, deps.staleBackupAgeMs, deps.buckets);
+    await sweepStaleBackupsImpl(
+      deps.projectRoot,
+      deps.staleBackupAgeMs,
+      deps.buckets
+    );
   }
 
   return { runOnce, shutdown, sweepStaleBackups };
@@ -193,25 +217,45 @@ export interface SyncJsonOutput {
   estimatedCost?: string;
   rateAssumption: 'pro';
   dryRun: boolean;
-  perLocale: Array<{ locale: string; translated: number; skipped: number; failed: number }>;
+  perLocale: Array<{
+    locale: string;
+    translated: number;
+    skipped: number;
+    failed: number;
+  }>;
 }
 
-function projectToPublicShape(result: SyncResult, estimatedCost: string | undefined): SyncJsonOutput {
-  const perLocale = result.fileResults.reduce<Map<string, { translated: number; skipped: number; failed: number }>>(
-    (acc, fr) => {
-      const existing = acc.get(fr.locale) ?? { translated: 0, skipped: 0, failed: 0 };
-      existing.translated += fr.translated;
-      existing.skipped += fr.skipped;
-      existing.failed += fr.failed;
-      acc.set(fr.locale, existing);
-      return acc;
-    },
-    new Map(),
+function projectToPublicShape(
+  result: SyncResult,
+  estimatedCost: string | undefined
+): SyncJsonOutput {
+  const perLocale = result.fileResults.reduce<
+    Map<string, { translated: number; skipped: number; failed: number }>
+  >((acc, fr) => {
+    const existing = acc.get(fr.locale) ?? {
+      translated: 0,
+      skipped: 0,
+      failed: 0,
+    };
+    existing.translated += fr.translated;
+    existing.skipped += fr.skipped;
+    existing.failed += fr.failed;
+    acc.set(fr.locale, existing);
+    return acc;
+  }, new Map());
+
+  const totalTranslated = result.fileResults.reduce(
+    (sum, fr) => sum + fr.translated,
+    0
+  );
+  const totalSkipped = result.fileResults.reduce(
+    (sum, fr) => sum + fr.skipped,
+    0
+  );
+  const totalFailed = result.fileResults.reduce(
+    (sum, fr) => sum + fr.failed,
+    0
   );
-
-  const totalTranslated = result.fileResults.reduce((sum, fr) => sum + fr.translated, 0);
-  const totalSkipped = result.fileResults.reduce((sum, fr) => sum + fr.skipped, 0);
-  const totalFailed = result.fileResults.reduce((sum, fr) => sum + fr.failed, 0);
 
   return {
     ok: result.success,
@@ -224,7 +268,10 @@ function projectToPublicShape(result: SyncResult, estimatedCost: string | undefi
     ...(estimatedCost !== undefined ? { estimatedCost } : {}),
     rateAssumption: 'pro',
     dryRun: result.dryRun,
-    perLocale: Array.from(perLocale.entries()).map(([locale, counts]) => ({ locale, ...counts })),
+    perLocale: Array.from(perLocale.entries()).map(([locale, counts]) => ({
+      locale,
+      ...counts,
+    })),
   };
 }
 
@@ -238,7 +285,9 @@ export class SyncCommand {
       frozen,
       dryRun: options.dryRun,
       force: options.force,
-      localeFilter: options.locale ? options.locale.split(',').map(l => l.trim()) : undefined,
+      localeFilter: options.locale
+        ? options.locale.split(',').map((l) => l.trim())
+        : undefined,
       formality: options.formality,
       glossary: options.glossary,
       modelType: options.modelType,
@@ -270,7 +319,12 @@ export class SyncCommand {
       process.exitCode = ExitCode.PartialFailure;
     }
 
-    if (options.autoCommit && result.success && !result.dryRun && !result.driftDetected) {
+    if (
+      options.autoCommit &&
+      result.success &&
+      !result.dryRun &&
+      !result.driftDetected
+    ) {
       await this.autoCommitTranslations(result, config);
     }
 
@@ -284,7 +338,7 @@ export class SyncCommand {
   private async watchAndSync(
     config: ResolvedSyncConfig,
     syncOptions: SyncOptions,
-    options: CliSyncOptions,
+    options: CliSyncOptions
   ): Promise<void> {
     const chokidar = await import('chokidar');
     const { default: path } = await import('path');
@@ -309,7 +363,9 @@ export class SyncCommand {
       watchPaths.push(configPathResolved);
     }
 
-    Logger.info(`Watching ${watchPaths.length} pattern(s) for changes (debounce: ${debounceMs}ms)...`);
+    Logger.info(
+      `Watching ${watchPaths.length} pattern(s) for changes (debounce: ${debounceMs}ms)...`
+    );
 
     const watcher = chokidar.watch(watchPaths, {
       cwd: config.projectRoot,
@@ -333,11 +389,17 @@ export class SyncCommand {
     let cachedConfig: ResolvedSyncConfig = config;
     const configFileName = path.basename(configPathResolved);
 
-    const ensureFreshConfig = async (changedPaths: string[]): Promise<ResolvedSyncConfig> => {
+    const ensureFreshConfig = async (
+      changedPaths: string[]
+    ): Promise<ResolvedSyncConfig> => {
       const configChanged = changedPaths.some((p) => {
         if (!p) return false;
-        const resolved = path.isAbsolute(p) ? p : path.resolve(config.projectRoot, p);
-        return resolved === configPathResolved || path.basename(p) === configFileName;
+        const resolved = path.isAbsolute(p)
+          ? p
+          : path.resolve(config.projectRoot, p);
+        return (
+          resolved === configPathResolved || path.basename(p) === configFileName
+        );
       });
       if (configChanged) {
         cachedConfig = await loadSyncConfig(process.cwd(), {
@@ -384,7 +446,12 @@ export class SyncCommand {
           backupTracker,
         });
         this.displayResult(result, 'text');
-        if (options.autoCommit && result.success && !result.dryRun && !result.driftDetected) {
+        if (
+          options.autoCommit &&
+          result.success &&
+          !result.dryRun &&
+          !result.driftDetected
+        ) {
           await this.autoCommitTranslations(result, activeConfig);
         }
       },
@@ -432,7 +499,7 @@ export class SyncCommand {
    * one bucket's target_path_pattern cannot claim another bucket's output.
    */
   private async resolveOwnedTargetPaths(
-    config: ResolvedSyncConfig,
+    config: ResolvedSyncConfig
   ): Promise<Map<string, string>> {
     const pathMod = await import('path');
     const { minimatch } = await import('minimatch');
@@ -440,20 +507,27 @@ export class SyncCommand {
     const { resolveTargetPath } = await import('../../sync/sync-utils.js');
 
     const owned = new Map<string, string>();
-    const lockManager = new SyncLockManager(pathMod.join(config.projectRoot, LOCK_FILE_NAME));
+    const lockManager = new SyncLockManager(
+      pathMod.join(config.projectRoot, LOCK_FILE_NAME)
+    );
     const lockFile = await lockManager.read();
     const sourcePaths = Object.keys(lockFile.entries);
 
     for (const bucketConfig of Object.values(config.buckets)) {
       for (const sourcePath of sourcePaths) {
-        if (!bucketConfig.include.some(pattern => minimatch(sourcePath, pattern))) continue;
+        if (
+          !bucketConfig.include.some((pattern) =>
+            minimatch(sourcePath, pattern)
+          )
+        )
+          continue;
         for (const locale of config.target_locales) {
           try {
             const targetPath = resolveTargetPath(
               sourcePath,
               config.source_locale,
               locale,
-              bucketConfig.target_path_pattern,
+              bucketConfig.target_path_pattern
             );
             owned.set(targetPath, locale);
           } catch {
@@ -466,7 +540,10 @@ export class SyncCommand {
     return owned;
   }
 
-  private async autoCommitTranslations(result: SyncResult, config: ResolvedSyncConfig): Promise<void> {
+  private async autoCommitTranslations(
+    result: SyncResult,
+    config: ResolvedSyncConfig
+  ): Promise<void> {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const fsMod = await import('fs');
@@ -482,8 +559,8 @@ export class SyncCommand {
     }
 
     const writtenFiles = result.fileResults
-      .filter(r => r.written)
-      .map(r => r.file);
+      .filter((r) => r.written)
+      .map((r) => r.file);
 
     // Preflight: refuse to auto-commit in unsafe repo states, so unrelated work
     // is never bundled into the chore(i18n) commit and nothing lands on the
@@ -494,11 +571,19 @@ export class SyncCommand {
     // wrote: a translation from an earlier refusal belongs to the next commit
     // rather than being an unrelated modification.
     const ownedPaths = await this.resolveOwnedTargetPaths(config);
-    const expectedStaged = new Set<string>([...writtenFiles, ...ownedPaths.keys(), LOCK_FILE_NAME]);
+    const expectedStaged = new Set<string>([
+      ...writtenFiles,
+      ...ownedPaths.keys(),
+      LOCK_FILE_NAME,
+    ]);
 
     // 1. In-progress rebase/merge/cherry-pick
-    const gitDir = (await execFileAsync('git', ['rev-parse', '--git-dir'], { cwd })).stdout.trim();
-    const gitDirAbs = pathMod.isAbsolute(gitDir) ? gitDir : pathMod.join(cwd, gitDir);
+    const gitDir = (
+      await execFileAsync('git', ['rev-parse', '--git-dir'], { cwd })
+    ).stdout.trim();
+    const gitDirAbs = pathMod.isAbsolute(gitDir)
+      ? gitDir
+      : pathMod.join(cwd, gitDir);
     const inProgressMarkers: Array<{ path: string; label: string }> = [
       { path: 'rebase-apply', label: 'rebase (apply)' },
       { path: 'rebase-merge', label: 'rebase (merge)' },
@@ -509,7 +594,7 @@ export class SyncCommand {
       if (fsMod.existsSync(pathMod.join(gitDirAbs, marker.path))) {
         throw new ValidationError(
           `Refusing to auto-commit: a ${marker.label} is in progress.`,
-          'Complete or abort the in-progress operation (e.g. `git rebase --abort`), then re-run `deepl sync --auto-commit`.',
+          'Complete or abort the in-progress operation (e.g. `git rebase --abort`), then re-run `deepl sync --auto-commit`.'
         );
       }
     }
@@ -520,13 +605,17 @@ export class SyncCommand {
     } catch {
       throw new ValidationError(
         'Refusing to auto-commit: HEAD is detached (no branch to commit to).',
-        'Check out a branch with `git checkout <branch>` before running `deepl sync --auto-commit`.',
+        'Check out a branch with `git checkout <branch>` before running `deepl sync --auto-commit`.'
       );
     }
 
     // 3. Dirty tree with unrelated modifications (or pre-existing staged files
     // that aren't part of this sync run).
-    const { stdout: porcelain } = await execFileAsync('git', ['status', '--porcelain', '-z'], { cwd });
+    const { stdout: porcelain } = await execFileAsync(
+      'git',
+      ['status', '--porcelain', '-z'],
+      { cwd }
+    );
     const unrelated: string[] = [];
     const dirtyOwned: string[] = [];
     if (porcelain.length > 0) {
@@ -552,7 +641,7 @@ export class SyncCommand {
       const list = unrelated.join(', ');
       throw new ValidationError(
         `Refusing to auto-commit: working tree has unrelated modifications in: ${list}.`,
-        'Commit or stash them first, then run `deepl sync --auto-commit` again.',
+        'Commit or stash them first, then run `deepl sync --auto-commit` again.'
       );
     }
 
@@ -566,8 +655,13 @@ export class SyncCommand {
     }
 
     const localeOf = new Map<string, string>(ownedPaths);
-    for (const fileResult of result.fileResults) localeOf.set(fileResult.file, fileResult.locale);
-    const locales = [...new Set(filesToStage.map(file => localeOf.get(file)).filter(Boolean))].join(', ');
+    for (const fileResult of result.fileResults)
+      localeOf.set(fileResult.file, fileResult.locale);
+    const locales = [
+      ...new Set(
+        filesToStage.map((file) => localeOf.get(file)).filter(Boolean)
+      ),
+    ].join(', ');
 
     const msg = locales
       ? `chore(i18n): sync translations for ${locales}`
@@ -576,7 +670,10 @@ export class SyncCommand {
     Logger.info(`Auto-committed ${filesToStage.length} file(s): ${msg}`);
   }
 
-  private renderProgress(event: SyncProgressEvent, format: 'text' | 'json'): void {
+  private renderProgress(
+    event: SyncProgressEvent,
+    format: 'text' | 'json'
+  ): void {
     if (Logger.isQuiet()) return;
     if (format === 'json') {
       Logger.info(JSON.stringify(event));
@@ -584,18 +681,25 @@ export class SyncCommand {
       const total = event.translated + event.failed;
       if (total === 0) return;
       const icon = event.failed > 0 ? '\u2717' : '\u2713';
-      Logger.info(`  ${icon} ${event.locale}: ${event.translated}/${total} keys (${event.file})`);
+      Logger.info(
+        `  ${icon} ${event.locale}: ${event.translated}/${total} keys (${event.file})`
+      );
     }
     // key-translated events are silent in text mode
   }
 
   private displayResult(result: SyncResult, format: 'text' | 'json'): void {
     if (format === 'json') {
-      const charSource = result.totalCharactersBilled || result.estimatedCharacters;
-      const estimatedCost = charSource > 0 ? formatCostEstimate(charSource) : undefined;
+      const charSource =
+        result.totalCharactersBilled || result.estimatedCharacters;
+      const estimatedCost =
+        charSource > 0 ? formatCostEstimate(charSource) : undefined;
       // Success JSON payload routed to stdout so `deepl sync --format json > out.json`
       // captures the final result. Progress events remain on stderr via Logger.info.
-      process.stdout.write(JSON.stringify(projectToPublicShape(result, estimatedCost), null, 2) + '\n');
+      process.stdout.write(
+        JSON.stringify(projectToPublicShape(result, estimatedCost), null, 2) +
+          '\n'
+      );
       return;
     }
 
@@ -607,8 +711,12 @@ export class SyncCommand {
       const driftParts: string[] = [];
       if (result.newKeys > 0) driftParts.push(`${result.newKeys} new`);
       if (result.staleKeys > 0) driftParts.push(`${result.staleKeys} stale`);
-      if (result.deletedKeys > 0) driftParts.push(`${result.deletedKeys} deleted`);
-      const driftSummary = driftParts.length > 0 ? driftParts.join(', ') : 'no key-level diffs surfaced';
+      if (result.deletedKeys > 0)
+        driftParts.push(`${result.deletedKeys} deleted`);
+      const driftSummary =
+        driftParts.length > 0
+          ? driftParts.join(', ')
+          : 'no key-level diffs surfaced';
       Logger.info(`Sync drift detected: ${driftSummary} keys.`);
       return;
     }
@@ -620,9 +728,10 @@ export class SyncCommand {
     if (result.deletedKeys > 0) parts.push(`${result.deletedKeys} deleted`);
 
     const summary = parts.length > 0 ? parts.join(', ') : 'no changes';
-    const localeInfo = result.dryRun && result.targetLocaleCount > 0
-      ? ` across ${result.targetLocaleCount} language${result.targetLocaleCount === 1 ? '' : 's'}`
-      : '';
+    const localeInfo =
+      result.dryRun && result.targetLocaleCount > 0
+        ? ` across ${result.targetLocaleCount} language${result.targetLocaleCount === 1 ? '' : 's'}`
+        : '';
     let chars = '';
     if (result.totalCharactersBilled > 0) {
       chars = ` (${result.totalCharactersBilled.toLocaleString()} chars, ${formatCostEstimate(result.totalCharactersBilled)} (Pro tier estimate))`;
@@ -638,7 +747,9 @@ export class SyncCommand {
       const instrEntries = Object.entries(result.strategy.instruction);
       if (instrEntries.length > 0) {
         const instrTotal = instrEntries.reduce((sum, [, n]) => sum + n, 0);
-        const instrDetail = instrEntries.map(([elem, n]) => `${elem}: ${n}`).join(', ');
+        const instrDetail = instrEntries
+          .map(([elem, n]) => `${elem}: ${n}`)
+          .join(', ');
         stratParts.push(`instructions: ${instrTotal} keys (${instrDetail})`);
       }
       if (stratParts.length > 0) {
@@ -647,7 +758,9 @@ export class SyncCommand {
     }
 
     if (result.dryRun && result.estimatedCharacters > 0) {
-      Logger.info(`This sync: ~${result.estimatedCharacters.toLocaleString()} chars, ${formatCostEstimate(result.estimatedCharacters)} (Pro tier estimate)`);
+      Logger.info(
+        `This sync: ~${result.estimatedCharacters.toLocaleString()} chars, ${formatCostEstimate(result.estimatedCharacters)} (Pro tier estimate)`
+      );
     }
 
     if (result.validationWarnings > 0) {
diff --git a/src/cli/commands/sync/register-sync-audit.ts b/src/cli/commands/sync/register-sync-audit.ts
index b01ba41b..762c6aef 100644
--- a/src/cli/commands/sync/register-sync-audit.ts
+++ b/src/cli/commands/sync/register-sync-audit.ts
@@ -3,7 +3,11 @@ import { Logger } from '../../../utils/logger.js';
 import { ValidationError } from '../../../utils/errors.js';
 import type { ServiceDeps } from '../service-factory.js';
 import type { TargetTranslationIndex } from '../../../sync/sync-glossary-report.js';
-import { emitJsonErrorAndExit, resolveFormat, resolveSyncConfig } from './sync-options.js';
+import {
+  emitJsonErrorAndExit,
+  resolveFormat,
+  resolveSyncConfig,
+} from './sync-options.js';
 
 interface AuditOptions {
   format?: string;
@@ -12,34 +16,38 @@ interface AuditOptions {
 
 export function registerSyncAudit(
   parent: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Command {
   parent
     .command('glossary-report', { hidden: true })
     .allowUnknownOption(true)
     .action((_options: unknown, command: Command) =>
-      handleLegacyGlossaryReport(command, deps),
+      handleLegacyGlossaryReport(command, deps)
     );
 
   return parent
     .command('audit')
-    .description('Analyze translation consistency and detect terminology inconsistencies')
+    .description(
+      'Analyze translation consistency and detect terminology inconsistencies'
+    )
     .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
     )
     .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
     .action((options: AuditOptions, command: Command) =>
-      handleSyncAudit(options, command, deps),
+      handleSyncAudit(options, command, deps)
     );
 }
 
 function handleLegacyGlossaryReport(
   command: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): void {
   const error = new ValidationError(
     "'deepl sync glossary-report' has been renamed to 'deepl sync audit'.",
-    "Use `deepl sync audit` — the subcommand detects terminology inconsistencies across locales (translation-consistency audit), not security auditing in the npm-audit sense.",
+    'Use `deepl sync audit` — the subcommand detects terminology inconsistencies across locales (translation-consistency audit), not security auditing in the npm-audit sense.'
   );
   const parentFormat = command.parent?.opts()['format'] as string | undefined;
   if (parentFormat === 'json') {
@@ -51,15 +59,17 @@ function handleLegacyGlossaryReport(
 async function handleSyncAudit(
   options: AuditOptions,
   command: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Promise<void> {
   options.format = resolveFormat(options, command);
   try {
     const { loadSyncConfig } = await import('../../../sync/sync-config.js');
     const { SyncLockManager } = await import('../../../sync/sync-lock.js');
     const { LOCK_FILE_NAME } = await import('../../../sync/types.js');
-    const { generateGlossaryReport } = await import('../../../sync/sync-glossary-report.js');
-    const { extractTranslatable } = await import('../../../sync/sync-bucket-walker.js');
+    const { generateGlossaryReport } =
+      await import('../../../sync/sync-glossary-report.js');
+    const { extractTranslatable } =
+      await import('../../../sync/sync-bucket-walker.js');
     const { createDefaultRegistry } = await import('../../../formats/index.js');
     const { resolveTargetPath } = await import('../../../sync/sync-utils.js');
     const pathMod = await import('path');
@@ -85,7 +95,7 @@ async function handleSyncAudit(
               relPath,
               config.source_locale,
               locale,
-              bucketConfig.target_path_pattern,
+              bucketConfig.target_path_pattern
             );
             const targetAbs = pathMod.join(config.projectRoot, targetRel);
             if (!fsMod.existsSync(targetAbs)) continue;
@@ -98,7 +108,8 @@ async function handleSyncAudit(
             // Unreadable / unparseable target file — reported as a missing target.
           }
         }
-        if (fileLocaleMap.size > 0) targetTranslations.set(relPath, fileLocaleMap);
+        if (fileLocaleMap.size > 0)
+          targetTranslations.set(relPath, fileLocaleMap);
       }
     }
 
@@ -111,10 +122,12 @@ async function handleSyncAudit(
       if (report.inconsistencies.length === 0) {
         Logger.output('No terminology inconsistencies found.');
       } else {
-        Logger.output(`${report.inconsistencies.length} inconsistency(ies) found:\n`);
+        Logger.output(
+          `${report.inconsistencies.length} inconsistency(ies) found:\n`
+        );
         for (const inc of report.inconsistencies) {
           Logger.output(
-            `  "${inc.sourceText}" [${inc.locale}]: ${inc.translations.length} different translations`,
+            `  "${inc.sourceText}" [${inc.locale}]: ${inc.translations.length} different translations`
           );
           Logger.output(`    Files: ${inc.files.join(', ')}`);
         }
@@ -122,7 +135,7 @@ async function handleSyncAudit(
 
       if (report.missingTargets.length > 0) {
         Logger.output(
-          `\n${report.missingTargets.length} target(s) could not be read and were excluded from the comparison:`,
+          `\n${report.missingTargets.length} target(s) could not be read and were excluded from the comparison:`
         );
         for (const target of report.missingTargets) {
           Logger.output(`  ${target.filePath} [${target.locale}]`);
diff --git a/src/cli/commands/sync/register-sync-export.ts b/src/cli/commands/sync/register-sync-export.ts
index 7579760d..6420b2f9 100644
--- a/src/cli/commands/sync/register-sync-export.ts
+++ b/src/cli/commands/sync/register-sync-export.ts
@@ -20,36 +20,41 @@ interface ExportOptions {
 
 export function registerSyncExport(
   parent: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Command {
-  return parent
-    .command('export')
-    .description('Export source strings to XLIFF for CAT tool handoff')
-    .option('--locale <locales>', 'Filter by locale (comma-separated)')
-    .option('--output <path>', 'Write to file instead of stdout')
-    // Named --overwrite (not --force) because `deepl sync --force` already
-    // exists as a cost-cap bypass on the parent command.
-    .option('--overwrite', 'Overwrite existing --output file')
-    .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
-    )
-    .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
-    .action((options: ExportOptions, command: Command) =>
-      handleSyncExport(options, command, deps),
-    );
+  return (
+    parent
+      .command('export')
+      .description('Export source strings to XLIFF for CAT tool handoff')
+      .option('--locale <locales>', 'Filter by locale (comma-separated)')
+      .option('--output <path>', 'Write to file instead of stdout')
+      // Named --overwrite (not --force) because `deepl sync --force` already
+      // exists as a cost-cap bypass on the parent command.
+      .option('--overwrite', 'Overwrite existing --output file')
+      .addOption(
+        new Option('--format <format>', 'Output format')
+          .choices(['text', 'json'])
+          .default('text')
+      )
+      .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
+      .action((options: ExportOptions, command: Command) =>
+        handleSyncExport(options, command, deps)
+      )
+  );
 }
 
 async function handleSyncExport(
   options: ExportOptions,
   command: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Promise<void> {
   options.format = resolveFormat(options, command);
   try {
     const { loadSyncConfig } = await import('../../../sync/sync-config.js');
     const { createDefaultRegistry } = await import('../../../formats/index.js');
     const { exportTranslations } = await import('../../../sync/sync-export.js');
-    const { assertPathWithinRoot } = await import('../../../sync/sync-utils.js');
+    const { assertPathWithinRoot } =
+      await import('../../../sync/sync-utils.js');
     const pathMod = await import('path');
     const fsMod = await import('fs');
 
@@ -66,13 +71,15 @@ async function handleSyncExport(
       assertPathWithinRoot(absOutput, config.projectRoot);
       if (fsMod.existsSync(absOutput) && !options.overwrite) {
         throw new ValidationError(
-          `Refusing to overwrite existing file ${options.output}. Use --overwrite to overwrite.`,
+          `Refusing to overwrite existing file ${options.output}. Use --overwrite to overwrite.`
         );
       }
-      await fsMod.promises.mkdir(pathMod.dirname(absOutput), { recursive: true });
+      await fsMod.promises.mkdir(pathMod.dirname(absOutput), {
+        recursive: true,
+      });
       await fsMod.promises.writeFile(absOutput, result.content, 'utf-8');
       Logger.info(
-        `Exported ${result.keys} keys from ${result.files} file(s) to ${options.output}`,
+        `Exported ${result.keys} keys from ${result.files} file(s) to ${options.output}`
       );
     } else {
       process.stdout.write(result.content);
diff --git a/src/cli/commands/sync/register-sync-init.ts b/src/cli/commands/sync/register-sync-init.ts
index c49afa9e..e8b079c5 100644
--- a/src/cli/commands/sync/register-sync-init.ts
+++ b/src/cli/commands/sync/register-sync-init.ts
@@ -20,10 +20,9 @@ interface InitOptions {
   format?: string;
 }
 
-
 export function registerSyncInit(
   parent: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Command {
   // Choices are filled in lazily so registration does not load every format
   // parser (yaml, smol-toml, ...) on unrelated CLI invocations. The
@@ -38,14 +37,19 @@ export function registerSyncInit(
     .addOption(fileFormatOption)
     .option('--path <pattern>', 'Source file pattern')
     .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
     )
     .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
-    .action((options: InitOptions, command: Command) => handleSyncInit(options, command, deps));
+    .action((options: InitOptions, command: Command) =>
+      handleSyncInit(options, command, deps)
+    );
 
   parent.hook('preSubcommand', async (_thisCommand, actionCommand) => {
     if (actionCommand === cmd && fileFormatOption.argChoices === undefined) {
-      const { SUPPORTED_FORMAT_KEYS } = await import('../../../formats/index.js');
+      const { SUPPORTED_FORMAT_KEYS } =
+        await import('../../../formats/index.js');
       fileFormatOption.choices([...SUPPORTED_FORMAT_KEYS]);
     }
   });
@@ -62,7 +66,7 @@ interface InitSuccessPayload {
 
 function emitInitSuccess(
   format: string | undefined,
-  payload: InitSuccessPayload,
+  payload: InitSuccessPayload
 ): void {
   if (format === 'json') {
     emitJsonInitSuccessAndExit(payload);
@@ -73,21 +77,27 @@ function emitInitSuccess(
 async function handleSyncInit(
   options: InitOptions,
   command: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Promise<void> {
   const { handleError } = deps;
   options.format = resolveFormat(options, command);
   try {
-    const { configExists, detectI18nFiles, generateSyncConfig, resolveInitConfigPath, writeSyncConfig } =
-      await import('../../../sync/sync-init.js');
+    const {
+      configExists,
+      detectI18nFiles,
+      generateSyncConfig,
+      resolveInitConfigPath,
+      writeSyncConfig,
+    } = await import('../../../sync/sync-init.js');
     const pathMod = await import('path');
 
     const targetConfigPath = resolveInitConfigPath(
       process.cwd(),
-      resolveSyncConfig(options, command),
+      resolveSyncConfig(options, command)
     );
     const cwd = pathMod.dirname(targetConfigPath);
-    const displayPath = pathMod.relative(process.cwd(), targetConfigPath) || targetConfigPath;
+    const displayPath =
+      pathMod.relative(process.cwd(), targetConfigPath) || targetConfigPath;
 
     if (configExists(targetConfigPath)) {
       if (options.format === 'json') {
@@ -110,10 +120,14 @@ async function handleSyncInit(
       return;
     }
 
-    if (options.sourceLocale && options.targetLocales && options.fileFormat && options.path) {
-      const { validateSyncInitFlags } = await import(
-        '../../../sync/sync-init-validate.js'
-      );
+    if (
+      options.sourceLocale &&
+      options.targetLocales &&
+      options.fileFormat &&
+      options.path
+    ) {
+      const { validateSyncInitFlags } =
+        await import('../../../sync/sync-init-validate.js');
       const validated = validateSyncInitFlags({
         sourceLocale: options.sourceLocale,
         targetLocales: options.targetLocales,
@@ -146,7 +160,7 @@ async function handleSyncInit(
     ].filter(Boolean) as string[];
     if (partialFlags.length > 0) {
       Logger.warn(
-        `Partial flags provided (${partialFlags.join(', ')}); all of --source-locale, --target-locales, --file-format, and --path are required for non-interactive mode. Falling back to detection.`,
+        `Partial flags provided (${partialFlags.join(', ')}); all of --source-locale, --target-locales, --file-format, and --path are required for non-interactive mode. Falling back to detection.`
       );
     }
 
@@ -154,7 +168,7 @@ async function handleSyncInit(
     if (detected.length === 0) {
       const noFilesError = new ConfigError(
         'No i18n files detected. No config created. Re-run with all four flags: --source-locale <locale> --target-locales <list> --file-format <format> --path <glob>',
-        'Re-run with --source-locale <locale> --target-locales <list> --file-format <format> --path <glob>',
+        'Re-run with --source-locale <locale> --target-locales <list> --file-format <format> --path <glob>'
       );
       if (options.format === 'json') {
         emitJsonErrorAndExit(noFilesError);
@@ -166,17 +180,18 @@ async function handleSyncInit(
     if (!process.stdin.isTTY) {
       throw new ValidationError(
         'All four flags (--source-locale, --target-locales, --file-format, --path) are required when stdin is not a TTY.',
-        'Provide all four flags for non-interactive use (CI, piped shells), or run in an interactive terminal.',
+        'Provide all four flags for non-interactive use (CI, piped shells), or run in an interactive terminal.'
       );
     }
 
     const project = detected[0]!;
-    Logger.info(`Detected ${project.format} project (${project.keyCount} keys)`);
+    Logger.info(
+      `Detected ${project.format} project (${project.keyCount} keys)`
+    );
 
     const { input, checkbox } = await import('@inquirer/prompts');
-    const { buildTargetLocaleChoices } = await import(
-      '../../../sync/sync-init-validate.js'
-    );
+    const { buildTargetLocaleChoices } =
+      await import('../../../sync/sync-init-validate.js');
     const sourceLocale =
       options.sourceLocale ??
       (await input({
diff --git a/src/cli/commands/sync/register-sync-pull.ts b/src/cli/commands/sync/register-sync-pull.ts
index 49a3844a..3a39e8a8 100644
--- a/src/cli/commands/sync/register-sync-pull.ts
+++ b/src/cli/commands/sync/register-sync-pull.ts
@@ -18,14 +18,16 @@ interface PullOptions {
 
 export function registerSyncPull(
   parent: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Command {
   return parent
     .command('pull')
     .description('Pull approved translations from a TMS')
     .option('--locale <locales>', 'Filter by locale (comma-separated)')
     .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
     )
     .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
     .addHelpText(
@@ -41,7 +43,7 @@ Requires TMS integration. Add a tms: block to .deepl-sync.yaml:
 Credentials: prefer the TMS_API_KEY (or TMS_TOKEN) env var over inlining
 'api_key'/'token' in the YAML. See docs/SYNC.md#tms-rest-contract for the
 full field list and REST contract.
-`,
+`
     )
     .action((options: PullOptions, command: Command) => {
       options.format = resolveFormat(options, command);
@@ -53,14 +55,16 @@ full field list and REST contract.
 
 export async function handleSyncPull(
   options: PullOptions,
-  handleError: (err: Error) => void,
+  handleError: (err: Error) => void
 ): Promise<void> {
   try {
     const { loadSyncConfig } = await import('../../../sync/sync-config.js');
     const { createTmsClient } = await import('../../../sync/tms-client.js');
     const { createDefaultRegistry } = await import('../../../formats/index.js');
-    const { pullTranslations, formatSkippedSummary } = await import('../../../sync/sync-tms.js');
-    const { acquireSyncProcessLock } = await import('../../../sync/sync-process-lock.js');
+    const { pullTranslations, formatSkippedSummary } =
+      await import('../../../sync/sync-tms.js');
+    const { acquireSyncProcessLock } =
+      await import('../../../sync/sync-process-lock.js');
 
     const localeFilter = parseLocaleFilter(options.locale);
     const config = await loadSyncConfig(process.cwd(), {
@@ -70,7 +74,7 @@ export async function handleSyncPull(
     if (!config.tms?.enabled) {
       throw new ConfigError(
         'TMS integration not configured',
-        'Add a "tms:" block with "enabled: true" to .deepl-sync.yaml',
+        'Add a "tms:" block with "enabled: true" to .deepl-sync.yaml'
       );
     }
 
@@ -78,11 +82,21 @@ export async function handleSyncPull(
     try {
       const client = createTmsClient(config.tms);
       const registry = await createDefaultRegistry();
-      const result = await pullTranslations(config, client, registry, { localeFilter });
+      const result = await pullTranslations(config, client, registry, {
+        localeFilter,
+      });
       if (options.format === 'json') {
-        process.stdout.write(JSON.stringify({ ok: true, pulled: result.pulled, skipped: result.skipped }) + '\n');
+        process.stdout.write(
+          JSON.stringify({
+            ok: true,
+            pulled: result.pulled,
+            skipped: result.skipped,
+          }) + '\n'
+        );
       } else {
-        Logger.info(`Pulled ${result.pulled} translations from TMS${formatSkippedSummary(result.skipped)}`);
+        Logger.info(
+          `Pulled ${result.pulled} translations from TMS${formatSkippedSummary(result.skipped)}`
+        );
       }
     } finally {
       processLock.release();
diff --git a/src/cli/commands/sync/register-sync-push.ts b/src/cli/commands/sync/register-sync-push.ts
index a4dfe27f..2e277a6b 100644
--- a/src/cli/commands/sync/register-sync-push.ts
+++ b/src/cli/commands/sync/register-sync-push.ts
@@ -18,14 +18,16 @@ interface PushOptions {
 
 export function registerSyncPush(
   parent: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Command {
   return parent
     .command('push')
     .description('Push translations to a TMS for human review')
     .option('--locale <locales>', 'Filter by locale (comma-separated)')
     .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
     )
     .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
     .addHelpText(
@@ -41,22 +43,25 @@ Requires TMS integration. Add a tms: block to .deepl-sync.yaml:
 Credentials: prefer the TMS_API_KEY (or TMS_TOKEN) env var over inlining
 'api_key'/'token' in the YAML. See docs/SYNC.md#tms-rest-contract for the
 full field list and REST contract.
-`,
+`
     )
-    .action((options: PushOptions, command: Command) => handleSyncPush(options, command, deps));
+    .action((options: PushOptions, command: Command) =>
+      handleSyncPush(options, command, deps)
+    );
 }
 
 async function handleSyncPush(
   options: PushOptions,
   command: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Promise<void> {
   options.format = resolveFormat(options, command);
   try {
     const { loadSyncConfig } = await import('../../../sync/sync-config.js');
     const { createTmsClient } = await import('../../../sync/tms-client.js');
     const { createDefaultRegistry } = await import('../../../formats/index.js');
-    const { pushTranslations, formatSkippedSummary } = await import('../../../sync/sync-tms.js');
+    const { pushTranslations, formatSkippedSummary } =
+      await import('../../../sync/sync-tms.js');
 
     const localeFilter = parseLocaleFilter(resolveLocale(options, command));
     const config = await loadSyncConfig(process.cwd(), {
@@ -66,18 +71,28 @@ async function handleSyncPush(
     if (!config.tms?.enabled) {
       throw new ConfigError(
         'TMS integration not configured',
-        'Add a "tms:" block with "enabled: true" to .deepl-sync.yaml',
+        'Add a "tms:" block with "enabled: true" to .deepl-sync.yaml'
       );
     }
 
     const client = createTmsClient(config.tms);
 
     const registry = await createDefaultRegistry();
-    const result = await pushTranslations(config, client, registry, { localeFilter });
+    const result = await pushTranslations(config, client, registry, {
+      localeFilter,
+    });
     if (options.format === 'json') {
-      process.stdout.write(JSON.stringify({ ok: true, pushed: result.pushed, skipped: result.skipped }) + '\n');
+      process.stdout.write(
+        JSON.stringify({
+          ok: true,
+          pushed: result.pushed,
+          skipped: result.skipped,
+        }) + '\n'
+      );
     } else {
-      Logger.info(`Pushed ${result.pushed} translations to TMS${formatSkippedSummary(result.skipped)}`);
+      Logger.info(
+        `Pushed ${result.pushed} translations to TMS${formatSkippedSummary(result.skipped)}`
+      );
     }
   } catch (error) {
     if (options.format === 'json') {
diff --git a/src/cli/commands/sync/register-sync-resolve.ts b/src/cli/commands/sync/register-sync-resolve.ts
index e2a36572..0952560e 100644
--- a/src/cli/commands/sync/register-sync-resolve.ts
+++ b/src/cli/commands/sync/register-sync-resolve.ts
@@ -2,7 +2,11 @@ import { Command, Option } from 'commander';
 import { Logger } from '../../../utils/logger.js';
 import { SyncConflictError } from '../../../utils/errors.js';
 import type { ServiceDeps } from '../service-factory.js';
-import { emitJsonErrorAndExit, resolveFormat, resolveSyncConfig } from './sync-options.js';
+import {
+  emitJsonErrorAndExit,
+  resolveFormat,
+  resolveSyncConfig,
+} from './sync-options.js';
 
 interface ResolveOptions {
   syncConfig?: string;
@@ -12,25 +16,30 @@ interface ResolveOptions {
 
 export function registerSyncResolve(
   parent: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Command {
   return parent
     .command('resolve')
     .description('Resolve git merge conflicts in .deepl-sync.lock')
     .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
     )
     .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
-    .option('--dry-run', 'Preview the decision report without writing the lockfile')
+    .option(
+      '--dry-run',
+      'Preview the decision report without writing the lockfile'
+    )
     .action((options: ResolveOptions, command: Command) =>
-      handleSyncResolve(options, command, deps),
+      handleSyncResolve(options, command, deps)
     );
 }
 
 async function handleSyncResolve(
   options: ResolveOptions,
   command: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Promise<void> {
   options.format = resolveFormat(options, command);
   // Commander routes --dry-run on the invocation line to the parent `sync`
@@ -51,7 +60,9 @@ async function handleSyncResolve(
 
     if (!result.hadConflicts) {
       if (options.format === 'json') {
-        process.stdout.write(JSON.stringify({ ok: true, resolved: 0, decisions: [] }) + '\n');
+        process.stdout.write(
+          JSON.stringify({ ok: true, resolved: 0, decisions: [] }) + '\n'
+        );
       } else {
         Logger.info('No merge conflicts found in lock file.');
       }
@@ -79,7 +90,11 @@ async function handleSyncResolve(
     if (result.resolved) {
       if (options.format === 'json') {
         process.stdout.write(
-          JSON.stringify({ ok: true, resolved: result.entriesMerged, decisions: decisions }) + '\n',
+          JSON.stringify({
+            ok: true,
+            resolved: result.entriesMerged,
+            decisions: decisions,
+          }) + '\n'
         );
       } else {
         const summaryParts = [
@@ -87,18 +102,19 @@ async function handleSyncResolve(
           `${counts.ours} ours`,
           `${counts.lengthHeuristic} length-heuristic`,
         ];
-        if (counts.unresolved > 0) summaryParts.push(`${counts.unresolved} unresolved`);
+        if (counts.unresolved > 0)
+          summaryParts.push(`${counts.unresolved} unresolved`);
         const dryRunSuffix = dryRun ? ' (dry-run: no files written)' : '';
         Logger.info(
           `Resolved ${result.entriesMerged} conflict${
             result.entriesMerged === 1 ? '' : 's'
-          } (${summaryParts.join(', ')}).${dryRunSuffix} Run "deepl sync" to fill any gaps.`,
+          } (${summaryParts.join(', ')}).${dryRunSuffix} Run "deepl sync" to fill any gaps.`
         );
       }
     } else {
       throw new SyncConflictError(
         'Could not automatically resolve lock file conflicts. Manual resolution required.',
-        'Edit .deepl-sync.lock to resolve conflict markers manually, then run `deepl sync` to fill gaps.',
+        'Edit .deepl-sync.lock to resolve conflict markers manually, then run `deepl sync` to fill gaps.'
       );
     }
   } catch (error) {
diff --git a/src/cli/commands/sync/register-sync-root.ts b/src/cli/commands/sync/register-sync-root.ts
index ad3390ee..a5c4e8ad 100644
--- a/src/cli/commands/sync/register-sync-root.ts
+++ b/src/cli/commands/sync/register-sync-root.ts
@@ -12,13 +12,19 @@ export function registerSyncRoot(program: Command, deps: ServiceDeps): Command {
     .optionsGroup('Sync Mode:')
     .option('--frozen', 'Fail if any strings need translation (for CI)')
     .option('--ci', 'Alias for --frozen')
-    .option('--dry-run', 'Show what would change without writing files or calling API')
+    .option(
+      '--dry-run',
+      'Show what would change without writing files or calling API'
+    )
     .option(
       '--force',
-      'Retranslate all strings, ignoring the lock file. WARNING: also bypasses the sync.max_characters cost-cap preflight — this can rebill every translated key and incur unexpected API costs. Prefer --dry-run first to see the character estimate.',
+      'Retranslate all strings, ignoring the lock file. WARNING: also bypasses the sync.max_characters cost-cap preflight — this can rebill every translated key and incur unexpected API costs. Prefer --dry-run first to see the character estimate.'
     )
     .optionsGroup('Filtering:')
-    .option('--locale <locales>', 'Limit to specific target locales (comma-separated)')
+    .option(
+      '--locale <locales>',
+      'Limit to specific target locales (comma-separated)'
+    )
     .optionsGroup('Translation Quality:')
     .addOption(
       new Option('--formality <level>', 'Override formality level').choices([
@@ -29,7 +35,7 @@ export function registerSyncRoot(program: Command, deps: ServiceDeps): Command {
         'prefer_less',
         'formal',
         'informal',
-      ]),
+      ])
     )
     .option('--glossary <name-or-id>', 'Override glossary for all buckets')
     .addOption(
@@ -37,42 +43,59 @@ export function registerSyncRoot(program: Command, deps: ServiceDeps): Command {
         'quality_optimized',
         'prefer_quality_optimized',
         'latency_optimized',
-      ]),
+      ])
+    )
+    .option(
+      '--scan-context',
+      'Scan source code for context (key paths, HTML element types)'
     )
-    .option('--scan-context', 'Scan source code for context (key paths, HTML element types)')
     .option(
       '--no-scan-context',
-      'Disable source-code context scanning for this run. Overrides context.enabled only; other context.* settings in .deepl-sync.yaml are preserved.',
+      'Disable source-code context scanning for this run. Overrides context.enabled only; other context.* settings in .deepl-sync.yaml are preserved.'
     )
     .addOption(new Option('--context').hideHelp())
     .addOption(new Option('--no-context').hideHelp())
     .optionsGroup('Performance:')
-    .option('--concurrency <number>', 'Max parallel locale translations (default: 5)', (v) =>
-      parsePositiveIntOption(v, 'concurrency', 100))
+    .option(
+      '--concurrency <number>',
+      'Max parallel locale translations (default: 5)',
+      (v) => parsePositiveIntOption(v, 'concurrency', 100)
+    )
     .option('--batch', 'Force batch mode (fastest, no context or instructions)')
     .option(
       '--no-batch',
-      'Force per-key mode (slowest, individual context per key). Default: section-batched context',
+      'Force per-key mode (slowest, individual context per key). Default: section-batched context'
     )
     .optionsGroup('Git:')
     .option('--auto-commit', 'Auto-commit translated files after sync')
     .optionsGroup('Review:')
     .option(
       '--flag-for-review',
-      'Mark translations as machine_translated in lock file for human review',
+      'Mark translations as machine_translated in lock file for human review'
     )
     .optionsGroup('Watch:')
     .option('--watch', 'Watch source files and auto-sync on changes')
-    .option('--debounce <ms>', 'Debounce delay for watch mode (default: 500ms)', (v) =>
-      parsePositiveIntOption(v, 'debounce', 600_000))
+    .option(
+      '--debounce <ms>',
+      'Debounce delay for watch mode (default: 500ms)',
+      (v) => parsePositiveIntOption(v, 'debounce', 600_000)
+    )
     .optionsGroup('Safety:')
-    .option('-y, --yes', 'Skip --force confirmation prompt (required when CI=true)')
+    .option(
+      '-y, --yes',
+      'Skip --force confirmation prompt (required when CI=true)'
+    )
     .optionsGroup('Output:')
     .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
     )
     .optionsGroup('Config:')
-    .option('--sync-config <path>', 'Path to .deepl-sync.yaml (default: auto-detect)')
+    .option(
+      '--sync-config <path>',
+      'Path to .deepl-sync.yaml (default: auto-detect)'
+    )
     .addHelpText(
       'after',
       `
@@ -95,21 +118,23 @@ Everyday use:
 Translation memories:
   Configure TM via .deepl-sync.yaml (translation.translation_memory).
   Run \`deepl tm list\` to see available TMs.
-`,
+`
     )
-    .action((options: Record<string, unknown>) => handleSyncRoot(options, deps));
+    .action((options: Record<string, unknown>) =>
+      handleSyncRoot(options, deps)
+    );
 }
 
 async function handleSyncRoot(
   options: Record<string, unknown>,
-  deps: ServiceDeps,
+  deps: ServiceDeps
 ): Promise<void> {
   const { handleError } = deps;
   try {
     if (options['context'] !== undefined) {
       throw new ValidationError(
         '--context is not a `deepl sync` flag. `deepl translate --context "<text>"` takes a string (translation guidance); `deepl sync` uses a boolean to toggle source-code context scanning, which has been renamed to avoid confusion.',
-        'Use --scan-context / --no-scan-context to control source-code context scanning.',
+        'Use --scan-context / --no-scan-context to control source-code context scanning.'
       );
     }
     const frozen =
@@ -124,13 +149,13 @@ async function handleSyncRoot(
     if (options['watch'] && options['force']) {
       throw new ValidationError(
         'Cannot use --watch and --force together: --force with --watch creates an unbounded billing loop that retranslates every key on every file change.',
-        'Run `deepl sync --force` once to retranslate, then use `deepl sync --watch` for ongoing change detection.',
+        'Run `deepl sync --force` once to retranslate, then use `deepl sync --watch` for ongoing change detection.'
       );
     }
     if (options['force'] && !options['yes']) {
       if (process.env['CI'] === 'true') {
         throw new ValidationError(
-          'Cannot use --force in CI without --yes: add --yes to confirm intentional use and acknowledge the billing risk.',
+          'Cannot use --force in CI without --yes: add --yes to confirm intentional use and acknowledge the billing risk.'
         );
       }
       if (process.stdin.isTTY) {
diff --git a/src/cli/commands/sync/register-sync-status.ts b/src/cli/commands/sync/register-sync-status.ts
index 77b3f3fd..608b1228 100644
--- a/src/cli/commands/sync/register-sync-status.ts
+++ b/src/cli/commands/sync/register-sync-status.ts
@@ -17,25 +17,27 @@ interface StatusOptions {
 
 export function registerSyncStatus(
   parent: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Command {
   return parent
     .command('status')
     .description('Show translation coverage status')
     .option('--locale <locales>', 'Filter by locale (comma-separated)')
     .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
     )
     .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
     .action((options: StatusOptions, command: Command) =>
-      handleSyncStatus(options, command, deps),
+      handleSyncStatus(options, command, deps)
     );
 }
 
 async function handleSyncStatus(
   options: StatusOptions,
   command: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Promise<void> {
   options.format = resolveFormat(options, command);
   try {
@@ -56,18 +58,23 @@ async function handleSyncStatus(
       : status.locales;
 
     if (options.format === 'json') {
-      process.stdout.write(JSON.stringify({ ...status, locales }, null, 2) + '\n');
+      process.stdout.write(
+        JSON.stringify({ ...status, locales }, null, 2) + '\n'
+      );
     } else {
-      const skippedSuffix = status.skippedKeys > 0
-        ? `, ${status.skippedKeys} skipped (pipe pluralization)`
-        : '';
-      Logger.output(`Source: ${status.sourceLocale} (${status.totalKeys} keys${skippedSuffix})\n`);
+      const skippedSuffix =
+        status.skippedKeys > 0
+          ? `, ${status.skippedKeys} skipped (pipe pluralization)`
+          : '';
+      Logger.output(
+        `Source: ${status.sourceLocale} (${status.totalKeys} keys${skippedSuffix})\n`
+      );
       for (const locale of locales) {
         const bar = `${'#'.repeat(Math.floor(locale.coverage / 5))}${'.'.repeat(
-          20 - Math.floor(locale.coverage / 5),
+          20 - Math.floor(locale.coverage / 5)
         )}`;
         Logger.output(
-          `  ${locale.locale}  [${bar}] ${locale.coverage}%  (${locale.missing} missing, ${locale.outdated} outdated)`,
+          `  ${locale.locale}  [${bar}] ${locale.coverage}%  (${locale.missing} missing, ${locale.outdated} outdated)`
         );
       }
     }
diff --git a/src/cli/commands/sync/register-sync-validate.ts b/src/cli/commands/sync/register-sync-validate.ts
index a8ec359b..7b605518 100644
--- a/src/cli/commands/sync/register-sync-validate.ts
+++ b/src/cli/commands/sync/register-sync-validate.ts
@@ -19,31 +19,34 @@ interface ValidateOptions {
 
 export function registerSyncValidate(
   parent: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Command {
   return parent
     .command('validate')
     .description('Validate translations for quality issues')
     .option('--locale <locales>', 'Filter by locale (comma-separated)')
     .addOption(
-      new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'),
+      new Option('--format <format>', 'Output format')
+        .choices(['text', 'json'])
+        .default('text')
     )
     .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
     .action((options: ValidateOptions, command: Command) =>
-      handleSyncValidate(options, command, deps),
+      handleSyncValidate(options, command, deps)
     );
 }
 
 async function handleSyncValidate(
   options: ValidateOptions,
   command: Command,
-  deps: Pick<ServiceDeps, 'handleError'>,
+  deps: Pick<ServiceDeps, 'handleError'>
 ): Promise<void> {
   options.format = resolveFormat(options, command);
   try {
     const { loadSyncConfig } = await import('../../../sync/sync-config.js');
     const { createDefaultRegistry } = await import('../../../formats/index.js');
-    const { validateTranslations } = await import('../../../sync/sync-validate.js');
+    const { validateTranslations } =
+      await import('../../../sync/sync-validate.js');
 
     const localeFilter = parseLocaleFilter(resolveLocale(options, command));
     const config = await loadSyncConfig(process.cwd(), {
@@ -53,7 +56,7 @@ async function handleSyncValidate(
 
     if (localeFilter) {
       config.target_locales = config.target_locales.filter((l: string) =>
-        localeFilter.includes(l),
+        localeFilter.includes(l)
       );
     }
 
@@ -68,12 +71,17 @@ async function handleSyncValidate(
         Logger.output(chalk.green('All translations passed validation.'));
       } else {
         for (const issue of result.issues) {
-          const icon = issue.severity === 'error' ? chalk.red('ERROR') : chalk.yellow('WARN');
+          const icon =
+            issue.severity === 'error'
+              ? chalk.red('ERROR')
+              : chalk.yellow('WARN');
           Logger.output(
-            `  ${icon}  ${issue.locale}/${issue.key}: ${issue.issues.map((i) => i.message).join(', ')}`,
+            `  ${icon}  ${issue.locale}/${issue.key}: ${issue.issues.map((i) => i.message).join(', ')}`
           );
         }
-        Logger.output(`\n${result.errors} error(s), ${result.warnings} warning(s)`);
+        Logger.output(
+          `\n${result.errors} error(s), ${result.warnings} warning(s)`
+        );
       }
     }
 
diff --git a/src/cli/commands/sync/sync-options.ts b/src/cli/commands/sync/sync-options.ts
index 91965d6e..1264ffaa 100644
--- a/src/cli/commands/sync/sync-options.ts
+++ b/src/cli/commands/sync/sync-options.ts
@@ -11,7 +11,7 @@ import { ExitCode, exitCodeForError } from '../../../utils/exit-codes.js';
  */
 export function resolveFormat(
   opts: { format?: string },
-  command: Command,
+  command: Command
 ): string | undefined {
   const parentFormat = command.parent?.opts()['format'] as string | undefined;
   if (parentFormat && parentFormat !== 'text' && opts.format === 'text') {
@@ -31,7 +31,7 @@ export function resolveFormat(
  */
 export function resolveLocale(
   opts: { locale?: string },
-  command: Command,
+  command: Command
 ): string | undefined {
   if (opts.locale !== undefined) return opts.locale;
   return command.parent?.opts()['locale'] as string | undefined;
@@ -44,7 +44,7 @@ export function resolveLocale(
  */
 export function resolveSyncConfig(
   opts: { syncConfig?: string },
-  command: Command,
+  command: Command
 ): string | undefined {
   if (opts.syncConfig !== undefined) return opts.syncConfig;
   return command.parent?.opts()['syncConfig'] as string | undefined;
@@ -54,7 +54,9 @@ export function resolveSyncConfig(
  * Split a resolved --locale value into the comma-separated filter list that
  * `loadSyncConfig` validates against `target_locales`.
  */
-export function parseLocaleFilter(locale: string | undefined): string[] | undefined {
+export function parseLocaleFilter(
+  locale: string | undefined
+): string[] | undefined {
   if (!locale) return undefined;
   return locale.split(',').map((l) => l.trim());
 }
@@ -105,13 +107,13 @@ function sanitizeMessage(message: string): string {
  */
 export function emitJsonErrorAndExit(
   error: unknown,
-  overrideExitCode?: number,
+  overrideExitCode?: number
 ): never {
   const err = error instanceof Error ? error : new Error(String(error));
   const code = err instanceof DeepLCLIError ? err.name : 'UnknownError';
-  const exitCode = overrideExitCode ?? (
-    err instanceof DeepLCLIError ? err.exitCode : exitCodeForError(err)
-  );
+  const exitCode =
+    overrideExitCode ??
+    (err instanceof DeepLCLIError ? err.exitCode : exitCodeForError(err));
   const envelope: SyncJsonErrorEnvelope = {
     ok: false,
     error: {
@@ -133,7 +135,7 @@ export function emitJsonErrorAndExit(
  * have richer payloads and write them directly.
  */
 export function emitJsonInitSuccessAndExit(
-  payload: SyncInitJsonSuccessEnvelope['created'],
+  payload: SyncInitJsonSuccessEnvelope['created']
 ): never {
   const envelope: SyncInitJsonSuccessEnvelope = {
     ok: true,
diff --git a/src/cli/commands/tm.ts b/src/cli/commands/tm.ts
index d9d31a73..18f51b1b 100644
--- a/src/cli/commands/tm.ts
+++ b/src/cli/commands/tm.ts
@@ -22,7 +22,7 @@ export class TmCommand {
       return 'No translation memories found';
     }
     return tms
-      .map(tm => {
+      .map((tm) => {
         const src = tm.source_language;
         const targets = tm.target_languages.join(', ');
         return `${sanitizeName(tm.name)} (${src} \u2192 ${targets})`;
diff --git a/src/cli/commands/translate.ts b/src/cli/commands/translate.ts
index f7d67c28..35077cad 100644
--- a/src/cli/commands/translate.ts
+++ b/src/cli/commands/translate.ts
@@ -29,7 +29,9 @@ export class TranslateCommand {
     glossaryService: GlossaryService,
     config: ConfigService
   ) {
-    const fileTranslationService = new FileTranslationService(translationService);
+    const fileTranslationService = new FileTranslationService(
+      translationService
+    );
     const batchTranslationService = new BatchTranslationService(
       fileTranslationService,
       { concurrency: 5, translationService }
@@ -51,7 +53,10 @@ export class TranslateCommand {
     this.stdinHandler = new StdinTranslationHandler(this.textHandler);
   }
 
-  async translate(textOrPath: string, options: TranslateOptions): Promise<string> {
+  async translate(
+    textOrPath: string,
+    options: TranslateOptions
+  ): Promise<string> {
     if (options.to) {
       options.to = options.to.toLowerCase();
     }
@@ -63,7 +68,9 @@ export class TranslateCommand {
     try {
       const lstat = fs.lstatSync(textOrPath);
       if (lstat.isSymbolicLink()) {
-        throw new ValidationError(`Symlinks are not supported for security reasons: ${textOrPath}`);
+        throw new ValidationError(
+          `Symlinks are not supported for security reasons: ${textOrPath}`
+        );
       }
 
       stats = fs.statSync(textOrPath);
@@ -71,7 +78,10 @@ export class TranslateCommand {
         return this.directoryHandler.translateDirectory(textOrPath, options);
       }
     } catch (error) {
-      if (error instanceof Error && error.message.includes('Symlinks are not supported')) {
+      if (
+        error instanceof Error &&
+        error.message.includes('Symlinks are not supported')
+      ) {
         throw error;
       }
     }
@@ -83,7 +93,10 @@ export class TranslateCommand {
     return this.textHandler.translateText(textOrPath, options);
   }
 
-  async translateText(text: string, options: TranslateOptions): Promise<string> {
+  async translateText(
+    text: string,
+    options: TranslateOptions
+  ): Promise<string> {
     return this.textHandler.translateText(text, options);
   }
 
diff --git a/src/cli/commands/translate/directory-translation-handler.ts b/src/cli/commands/translate/directory-translation-handler.ts
index b75734e3..fc651253 100644
--- a/src/cli/commands/translate/directory-translation-handler.ts
+++ b/src/cli/commands/translate/directory-translation-handler.ts
@@ -16,7 +16,9 @@ import { buildBaseTranslationOptions } from './translation-options-factory.js';
  * one of them — directory mode announces it as ignored and resolves no glossary —
  * so a glossary must not fail a directory run the way it fails a text one.
  */
-function honouredConstraints(options: TranslateOptions): TranslationLanguageConstraints {
+function honouredConstraints(
+  options: TranslateOptions
+): TranslationLanguageConstraints {
   return {
     from: options.from,
     formality: options.formality,
@@ -27,16 +29,21 @@ function honouredConstraints(options: TranslateOptions): TranslationLanguageCons
 export class DirectoryTranslationHandler {
   constructor(public ctx: HandlerContext) {}
 
-  async translateDirectory(dirPath: string, options: TranslateOptions): Promise<string> {
+  async translateDirectory(
+    dirPath: string,
+    options: TranslateOptions
+  ): Promise<string> {
     if (!options.output) {
-      throw new ValidationError('Output directory is required for batch translation. Use --output <dir>');
+      throw new ValidationError(
+        'Output directory is required for batch translation. Use --output <dir>'
+      );
     }
 
     const supported = new Set(['from', 'formality']);
     warnIgnoredOptions('directory', options, supported);
 
     if (options.to.includes(',')) {
-      const targetLangs = options.to.split(',').map(lang => lang.trim());
+      const targetLangs = options.to.split(',').map((lang) => lang.trim());
       validateTranslationLanguages(targetLangs, honouredConstraints(options));
 
       const allOutputs: string[] = [];
@@ -53,15 +60,22 @@ export class DirectoryTranslationHandler {
     return this.translateSingleTarget(dirPath, options);
   }
 
-  private async translateSingleTarget(dirPath: string, options: TranslateOptions): Promise<string> {
+  private async translateSingleTarget(
+    dirPath: string,
+    options: TranslateOptions
+  ): Promise<string> {
     validateTranslationLanguages([options.to], honouredConstraints(options));
 
     const translationOptions = buildBaseTranslationOptions(options);
 
-    const spinner = Logger.shouldShowSpinner() ? ora('Scanning files...').start() : null;
+    const spinner = Logger.shouldShowSpinner()
+      ? ora('Scanning files...').start()
+      : null;
 
     const controller = new AbortController();
-    const onAbort = () => { controller.abort(); };
+    const onAbort = () => {
+      controller.abort();
+    };
     process.on('SIGINT', onAbort);
 
     const batchOptions = {
@@ -69,7 +83,11 @@ export class DirectoryTranslationHandler {
       recursive: options.recursive !== false,
       pattern: options.pattern,
       abortSignal: controller.signal,
-      onProgress: (progress: { completed: number; total: number; current?: string }) => {
+      onProgress: (progress: {
+        completed: number;
+        total: number;
+        current?: string;
+      }) => {
         if (spinner) {
           spinner.text = `Translating files: ${progress.completed}/${progress.total}`;
         }
@@ -80,7 +98,10 @@ export class DirectoryTranslationHandler {
       if (options.concurrency) {
         this.ctx.batchTranslationService = new BatchTranslationService(
           this.ctx.fileTranslationService,
-          { concurrency: options.concurrency, translationService: this.ctx.translationService }
+          {
+            concurrency: options.concurrency,
+            translationService: this.ctx.translationService,
+          }
         );
       }
 
@@ -105,7 +126,7 @@ export class DirectoryTranslationHandler {
       if (stats.failed > 0) {
         output.push(`  ✗ Failed: ${stats.failed}`);
         output.push(`\nFailed files:`);
-        result.failed.forEach(f => {
+        result.failed.forEach((f) => {
           output.push(`  - ${f.file}: ${f.error}`);
         });
         // Reported in the exit code as well as the summary: a run where nothing
@@ -121,7 +142,9 @@ export class DirectoryTranslationHandler {
           process.exitCode = exitCodeForError(result.requestRejected);
         } else {
           process.exitCode =
-            stats.successful === 0 ? ExitCode.GeneralError : ExitCode.PartialFailure;
+            stats.successful === 0
+              ? ExitCode.GeneralError
+              : ExitCode.PartialFailure;
         }
       }
 
diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index 30ae1ffe..9952db9f 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -4,26 +4,46 @@ import { ValidationError } from '../../../utils/errors.js';
 import type { Language } from '../../../types/index.js';
 import type { DocumentTranslationOptions } from '../../../types/api.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
-import { warnIgnoredOptions, validateTranslationLanguages } from './translate-utils.js';
-import { buildBaseTranslationOptions, applyGlossarySelection } from './translation-options-factory.js';
+import {
+  warnIgnoredOptions,
+  validateTranslationLanguages,
+} from './translate-utils.js';
+import {
+  buildBaseTranslationOptions,
+  applyGlossarySelection,
+} from './translation-options-factory.js';
 import { applyGlossarySourceLang } from '../../../utils/glossary-params.js';
 
 export class DocumentTranslationHandler {
   constructor(public ctx: HandlerContext) {}
 
-  async translateDocument(filePath: string, options: TranslateOptions): Promise<string> {
+  async translateDocument(
+    filePath: string,
+    options: TranslateOptions
+  ): Promise<string> {
     if (options.output === '-') {
       throw new ValidationError(
         'Cannot stream binary document translation to stdout. Use --output <file> instead.'
       );
     }
 
-    const supported = new Set(['from', 'formality', 'glossary', 'outputFormat', 'enableMinification']);
+    const supported = new Set([
+      'from',
+      'formality',
+      'glossary',
+      'outputFormat',
+      'enableMinification',
+    ]);
     warnIgnoredOptions('document', options, supported);
     // Actually ignored, not just announced: leaving them set let shared
     // validation reject a command over a flag this mode has just said it would
     // disregard.
-    const { modelType: _model, tagHandling: _tags, tagHandlingVersion: _version, ...rest } = options;
+    const {
+      modelType: _model,
+      tagHandling: _tags,
+      tagHandlingVersion: _version,
+      ...rest
+    } = options;
     options = rest;
 
     // Documents accept glossaries, so the extended-tier constraint applies here
@@ -43,9 +63,12 @@ export class DocumentTranslationHandler {
 
     const translationOptions = buildBaseTranslationOptions(options);
 
-    await applyGlossarySelection(translationOptions, options, this.ctx.glossaryService, [
-      options.to as Language,
-    ]);
+    await applyGlossarySelection(
+      translationOptions,
+      options,
+      this.ctx.glossaryService,
+      [options.to as Language]
+    );
 
     if (options.outputFormat) {
       translationOptions.outputFormat = options.outputFormat;
@@ -55,39 +78,42 @@ export class DocumentTranslationHandler {
       translationOptions.enableDocumentMinification = true;
     }
 
-    const spinner = Logger.shouldShowSpinner() ? ora('Uploading document...').start() : null;
+    const spinner = Logger.shouldShowSpinner()
+      ? ora('Uploading document...').start()
+      : null;
 
     try {
-      const result = await this.ctx.documentTranslationService.translateDocument(
-        filePath,
-        outputPath,
-        translationOptions as DocumentTranslationOptions,
-        (progress) => {
-          if (spinner) {
-            if (progress.status === 'queued') {
-              spinner.text = 'Document queued for translation...';
-            } else if (progress.status === 'translating') {
-              const timeText = progress.secondsRemaining
-                ? ` (est. ${progress.secondsRemaining}s remaining)`
-                : '';
-              spinner.text = `Translating document${timeText}...`;
-            } else if (progress.status === 'done') {
-              spinner.text = 'Downloading translated document...';
+      const result =
+        await this.ctx.documentTranslationService.translateDocument(
+          filePath,
+          outputPath,
+          translationOptions as DocumentTranslationOptions,
+          (progress) => {
+            if (spinner) {
+              if (progress.status === 'queued') {
+                spinner.text = 'Document queued for translation...';
+              } else if (progress.status === 'translating') {
+                const timeText = progress.secondsRemaining
+                  ? ` (est. ${progress.secondsRemaining}s remaining)`
+                  : '';
+                spinner.text = `Translating document${timeText}...`;
+              } else if (progress.status === 'done') {
+                spinner.text = 'Downloading translated document...';
+              }
             }
           }
-        }
-      );
+        );
 
       if (spinner) {
         spinner.succeed(`Document translated successfully!`);
       }
 
-      const output: string[] = [
-        `Translated ${filePath} -> ${outputPath}`,
-      ];
+      const output: string[] = [`Translated ${filePath} -> ${outputPath}`];
 
       if (result.billedCharacters) {
-        output.push(`Billed characters: ${result.billedCharacters.toLocaleString()}`);
+        output.push(
+          `Billed characters: ${result.billedCharacters.toLocaleString()}`
+        );
       }
 
       return output.join('\n');
diff --git a/src/cli/commands/translate/file-translation-handler.ts b/src/cli/commands/translate/file-translation-handler.ts
index fddef98d..8b6a240a 100644
--- a/src/cli/commands/translate/file-translation-handler.ts
+++ b/src/cli/commands/translate/file-translation-handler.ts
@@ -13,26 +13,40 @@ import {
   getFileSize,
   SAFE_TEXT_SIZE_LIMIT,
 } from './translate-utils.js';
-import { buildBaseTranslationOptions, applySharedTmAndGlossary } from './translation-options-factory.js';
+import {
+  buildBaseTranslationOptions,
+  applySharedTmAndGlossary,
+} from './translation-options-factory.js';
 import { applyGlossarySourceLang } from '../../../utils/glossary-params.js';
 import type { DocumentTranslationHandler } from './document-translation-handler.js';
 
 export class FileTranslationHandler {
-  constructor(public ctx: HandlerContext, public documentHandler: DocumentTranslationHandler) {}
-
-  async translateFile(filePath: string, options: TranslateOptions, cachedStats?: fs.Stats | null): Promise<string> {
+  constructor(
+    public ctx: HandlerContext,
+    public documentHandler: DocumentTranslationHandler
+  ) {}
+
+  async translateFile(
+    filePath: string,
+    options: TranslateOptions,
+    cachedStats?: fs.Stats | null
+  ): Promise<string> {
     if (!options.output) {
-      throw new ValidationError('Output file path is required for file translation. Use --output <path>');
+      throw new ValidationError(
+        'Output file path is required for file translation. Use --output <path>'
+      );
     }
 
     const stdoutMode = options.output === '-';
 
     if (options.to.includes(',') && stdoutMode) {
-      throw new ValidationError('Cannot use --output - with multiple target languages. Use a directory path instead.');
+      throw new ValidationError(
+        'Cannot use --output - with multiple target languages. Use a directory path instead.'
+      );
     }
 
     if (options.to.includes(',')) {
-      const targetLangs = options.to.split(',').map(lang => lang.trim());
+      const targetLangs = options.to.split(',').map((lang) => lang.trim());
       validateTranslationLanguages(targetLangs, options);
 
       const validTargetLangs = targetLangs as Language[];
@@ -69,14 +83,17 @@ export class FileTranslationHandler {
         targets: validTargetLangs,
       });
 
-      const results = await this.ctx.fileTranslationService.translateFileToMultiple(
-        filePath,
-        validTargetLangs,
-        translationOptions
-      );
+      const results =
+        await this.ctx.fileTranslationService.translateFileToMultiple(
+          filePath,
+          validTargetLangs,
+          translationOptions
+        );
 
-      return `Translated ${filePath} to ${validTargetLangs.length} languages:\n` +
-        results.map(r => `  [${r.targetLang}] ${r.outputPath}`).join('\n');
+      return (
+        `Translated ${filePath} to ${validTargetLangs.length} languages:\n` +
+        results.map((r) => `  [${r.targetLang}] ${r.outputPath}`).join('\n')
+      );
     }
 
     if (isTextBasedFile(filePath)) {
@@ -88,16 +105,23 @@ export class FileTranslationHandler {
       }
 
       if (fileSize === null) {
-        throw new ValidationError(`File not found or cannot be accessed: ${filePath}`);
+        throw new ValidationError(
+          `File not found or cannot be accessed: ${filePath}`
+        );
       }
 
       if (fileSize <= SAFE_TEXT_SIZE_LIMIT) {
         return this.translateTextFile(filePath, options);
-      } else if (this.ctx.documentTranslationService.isDocumentSupported(filePath)) {
+      } else if (
+        this.ctx.documentTranslationService.isDocumentSupported(filePath)
+      ) {
         const fileSizeKiB = (fileSize / 1024).toFixed(1);
         const warning = `⚠ File exceeds 100 KiB limit for cached translation (${fileSizeKiB} KiB), using document API instead`;
         Logger.warn(warning);
-        const result = await this.documentHandler.translateDocument(filePath, options);
+        const result = await this.documentHandler.translateDocument(
+          filePath,
+          options
+        );
         return `${warning}\n${result}`;
       }
     }
@@ -126,7 +150,10 @@ export class FileTranslationHandler {
     return `Translated ${filePath} -> ${options.output}`;
   }
 
-  async translateTextFile(filePath: string, options: TranslateOptions): Promise<string> {
+  async translateTextFile(
+    filePath: string,
+    options: TranslateOptions
+  ): Promise<string> {
     validateTranslationLanguages([options.to], options);
 
     applyGlossarySourceLang(
@@ -154,7 +181,9 @@ export class FileTranslationHandler {
 
     if (isStructuredFile(filePath)) {
       if (options.output === '-') {
-        throw new ValidationError('Cannot stream structured file (JSON/YAML) translation to stdout. Use --output <file> instead.');
+        throw new ValidationError(
+          'Cannot stream structured file (JSON/YAML) translation to stdout. Use --output <file> instead.'
+        );
       }
 
       const translationOptions = buildBaseTranslationOptions(options);
@@ -190,7 +219,7 @@ export class FileTranslationHandler {
       translationOptions,
       {
         preserveCode: options.preserveCode,
-        skipCache: !options.cache
+        skipCache: !options.cache,
       }
     );
 
diff --git a/src/cli/commands/translate/index.ts b/src/cli/commands/translate/index.ts
index b702a700..d63c175e 100644
--- a/src/cli/commands/translate/index.ts
+++ b/src/cli/commands/translate/index.ts
@@ -1,4 +1,8 @@
-export type { TranslateOptions, TranslationParams, HandlerContext } from './types.js';
+export type {
+  TranslateOptions,
+  TranslationParams,
+  HandlerContext,
+} from './types.js';
 export type {
   ExtendedLanguageConstraints,
   TranslationLanguageConstraints,
@@ -30,4 +34,7 @@ export { StdinTranslationHandler } from './stdin-translation-handler.js';
 export { FileTranslationHandler } from './file-translation-handler.js';
 export { DocumentTranslationHandler } from './document-translation-handler.js';
 export { DirectoryTranslationHandler } from './directory-translation-handler.js';
-export { buildBaseTranslationOptions, applySharedTmAndGlossary } from './translation-options-factory.js';
+export {
+  buildBaseTranslationOptions,
+  applySharedTmAndGlossary,
+} from './translation-options-factory.js';
diff --git a/src/cli/commands/translate/text-translation-handler.ts b/src/cli/commands/translate/text-translation-handler.ts
index d127f649..9b007dc0 100644
--- a/src/cli/commands/translate/text-translation-handler.ts
+++ b/src/cli/commands/translate/text-translation-handler.ts
@@ -1,5 +1,9 @@
 import { Language } from '../../../types/index.js';
-import { formatTranslationJson, formatMultiTranslationJson, formatMultiTranslationTable } from '../../../utils/formatters.js';
+import {
+  formatTranslationJson,
+  formatMultiTranslationJson,
+  formatMultiTranslationTable,
+} from '../../../utils/formatters.js';
 import { Logger } from '../../../utils/logger.js';
 import { ValidationError, AuthError } from '../../../utils/errors.js';
 import type { HandlerContext, TranslateOptions } from './types.js';
@@ -10,13 +14,19 @@ import {
   MAX_CUSTOM_INSTRUCTIONS,
   MAX_CUSTOM_INSTRUCTION_CHARS,
 } from './translate-utils.js';
-import { buildBaseTranslationOptions, applySharedTmAndGlossary } from './translation-options-factory.js';
+import {
+  buildBaseTranslationOptions,
+  applySharedTmAndGlossary,
+} from './translation-options-factory.js';
 import { applyGlossarySourceLang } from '../../../utils/glossary-params.js';
 
 export class TextTranslationHandler {
   constructor(public ctx: HandlerContext) {}
 
-  async translateText(text: string, options: TranslateOptions): Promise<string> {
+  async translateText(
+    text: string,
+    options: TranslateOptions
+  ): Promise<string> {
     if (options.to) {
       options.to = options.to.toLowerCase();
     }
@@ -34,7 +44,9 @@ export class TextTranslationHandler {
     const apiKey = this.ctx.config.getValue<string>('auth.apiKey');
     const envKey = process.env['DEEPL_API_KEY'];
     if (!apiKey && !envKey) {
-      throw new AuthError('API key not set. Run: deepl auth set-key <your-api-key>');
+      throw new AuthError(
+        'API key not set. Run: deepl auth set-key <your-api-key>'
+      );
     }
 
     if (options.to.includes(',')) {
@@ -73,54 +85,71 @@ export class TextTranslationHandler {
 
     if (options.customInstruction && options.customInstruction.length > 0) {
       if (options.customInstruction.length > MAX_CUSTOM_INSTRUCTIONS) {
-        throw new ValidationError(`Maximum ${MAX_CUSTOM_INSTRUCTIONS} custom instructions allowed`);
+        throw new ValidationError(
+          `Maximum ${MAX_CUSTOM_INSTRUCTIONS} custom instructions allowed`
+        );
       }
       for (const instruction of options.customInstruction) {
         if (instruction.length > MAX_CUSTOM_INSTRUCTION_CHARS) {
-          throw new ValidationError(`Custom instruction exceeds ${MAX_CUSTOM_INSTRUCTION_CHARS} character limit (${instruction.length} chars): "${instruction.substring(0, 50)}..."`);
+          throw new ValidationError(
+            `Custom instruction exceeds ${MAX_CUSTOM_INSTRUCTION_CHARS} character limit (${instruction.length} chars): "${instruction.substring(0, 50)}..."`
+          );
         }
       }
       if (options.modelType === 'latency_optimized') {
-        throw new ValidationError('Custom instructions cannot be used with latency_optimized model type');
+        throw new ValidationError(
+          'Custom instructions cannot be used with latency_optimized model type'
+        );
       }
       translationOptions.customInstructions = options.customInstruction;
     }
 
     if (options.styleId) {
       if (options.modelType === 'latency_optimized') {
-        throw new ValidationError('Style ID cannot be used with latency_optimized model type');
+        throw new ValidationError(
+          'Style ID cannot be used with latency_optimized model type'
+        );
       }
       translationOptions.styleId = options.styleId;
     }
 
-    if (options.outlineDetection !== undefined || options.splittingTags || options.nonSplittingTags || options.ignoreTags) {
+    if (
+      options.outlineDetection !== undefined ||
+      options.splittingTags ||
+      options.nonSplittingTags ||
+      options.ignoreTags
+    ) {
       if (options.tagHandling !== 'xml') {
-        throw new ValidationError('XML tag handling parameters (--outline-detection, --splitting-tags, --non-splitting-tags, --ignore-tags) require --tag-handling xml');
+        throw new ValidationError(
+          'XML tag handling parameters (--outline-detection, --splitting-tags, --non-splitting-tags, --ignore-tags) require --tag-handling xml'
+        );
       }
     }
 
     if (options.outlineDetection !== undefined) {
       const boolValue = options.outlineDetection.toLowerCase();
       if (boolValue !== 'true' && boolValue !== 'false') {
-        throw new ValidationError('--outline-detection must be "true" or "false"');
+        throw new ValidationError(
+          '--outline-detection must be "true" or "false"'
+        );
       }
       translationOptions.outlineDetection = boolValue === 'true';
     }
 
     if (options.splittingTags) {
-      const tags = options.splittingTags.split(',').map(tag => tag.trim());
+      const tags = options.splittingTags.split(',').map((tag) => tag.trim());
       validateXmlTags(tags, '--splitting-tags');
       translationOptions.splittingTags = tags;
     }
 
     if (options.nonSplittingTags) {
-      const tags = options.nonSplittingTags.split(',').map(tag => tag.trim());
+      const tags = options.nonSplittingTags.split(',').map((tag) => tag.trim());
       validateXmlTags(tags, '--non-splitting-tags');
       translationOptions.nonSplittingTags = tags;
     }
 
     if (options.ignoreTags) {
-      const tags = options.ignoreTags.split(',').map(tag => tag.trim());
+      const tags = options.ignoreTags.split(',').map((tag) => tag.trim());
       validateXmlTags(tags, '--ignore-tags');
       translationOptions.ignoreTags = tags;
     }
@@ -130,12 +159,14 @@ export class TextTranslationHandler {
       translationOptions,
       {
         preserveCode: options.preserveCode,
-        skipCache: !options.cache
+        skipCache: !options.cache,
       }
     );
 
     if (result.detectedSourceLang) {
-      Logger.verbose(`[verbose] Detected source language: ${result.detectedSourceLang}`);
+      Logger.verbose(
+        `[verbose] Detected source language: ${result.detectedSourceLang}`
+      );
     }
     if (result.modelTypeUsed) {
       Logger.verbose(`[verbose] Model type used: ${result.modelTypeUsed}`);
@@ -143,12 +174,18 @@ export class TextTranslationHandler {
     Logger.verbose(`[verbose] Character count: ${text.length}`);
 
     if (options.format === 'json') {
-      return formatTranslationJson(result, options.to as Language, result.cached ?? false);
+      return formatTranslationJson(
+        result,
+        options.to as Language,
+        result.cached ?? false
+      );
     }
 
     const metadata: string[] = [];
     if (result.billedCharacters !== undefined) {
-      metadata.push(`Billed characters: ${result.billedCharacters.toLocaleString()}`);
+      metadata.push(
+        `Billed characters: ${result.billedCharacters.toLocaleString()}`
+      );
     }
     if (result.modelTypeUsed) {
       metadata.push(`Model: ${result.modelTypeUsed}`);
@@ -160,11 +197,24 @@ export class TextTranslationHandler {
     return result.text;
   }
 
-  private async translateToMultiple(text: string, options: TranslateOptions): Promise<string> {
-    const supported = new Set(['from', 'formality', 'context', 'glossary', 'translationMemory', 'tmThreshold', 'showBilledCharacters', 'customInstruction', 'styleId']);
+  private async translateToMultiple(
+    text: string,
+    options: TranslateOptions
+  ): Promise<string> {
+    const supported = new Set([
+      'from',
+      'formality',
+      'context',
+      'glossary',
+      'translationMemory',
+      'tmThreshold',
+      'showBilledCharacters',
+      'customInstruction',
+      'styleId',
+    ]);
     warnIgnoredOptions('multi-target', options, supported);
 
-    const targetLangs = options.to.split(',').map(lang => lang.trim());
+    const targetLangs = options.to.split(',').map((lang) => lang.trim());
     validateTranslationLanguages(targetLangs, options);
 
     applyGlossarySourceLang(
@@ -190,7 +240,8 @@ export class TextTranslationHandler {
 
     const validTargetLangs = targetLangs as Language[];
 
-    const { targetLang: _, ...translationOptions } = buildBaseTranslationOptions(options);
+    const { targetLang: _, ...translationOptions } =
+      buildBaseTranslationOptions(options);
 
     await applySharedTmAndGlossary(translationOptions, options, {
       glossaryService: this.ctx.glossaryService,
@@ -218,16 +269,18 @@ export class TextTranslationHandler {
 
     if (options.format === 'table') {
       if (!process.stdout.isTTY) {
-        Logger.warn('WARN  --format table is not supported in non-TTY output; falling back to plain text');
+        Logger.warn(
+          'WARN  --format table is not supported in non-TTY output; falling back to plain text'
+        );
         return results
-          .map(result => `[${result.targetLang}] ${result.text}`)
+          .map((result) => `[${result.targetLang}] ${result.text}`)
           .join('\n');
       }
       return formatMultiTranslationTable(results);
     }
 
     return results
-      .map(result => `[${result.targetLang}] ${result.text}`)
+      .map((result) => `[${result.targetLang}] ${result.text}`)
       .join('\n');
   }
 }
diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index d6819716..a6fa90a7 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -14,16 +14,32 @@ import type { GlossaryService } from '../../../services/glossary.js';
 import type { TranslateOptions, TranslationParams } from './types.js';
 
 export const VALID_LANGUAGES: ReadonlySet<string> = getAllLanguageCodes();
-export const EXTENDED_ONLY_LANGUAGES: ReadonlySet<string> = getExtendedLanguageCodes();
-
-export const TEXT_BASED_EXTENSIONS = ['.txt', '.md', '.html', '.htm', '.srt', '.xlf', '.xliff', '.json', '.yaml', '.yml'];
+export const EXTENDED_ONLY_LANGUAGES: ReadonlySet<string> =
+  getExtendedLanguageCodes();
+
+export const TEXT_BASED_EXTENSIONS = [
+  '.txt',
+  '.md',
+  '.html',
+  '.htm',
+  '.srt',
+  '.xlf',
+  '.xliff',
+  '.json',
+  '.yaml',
+  '.yml',
+];
 export const STRUCTURED_EXTENSIONS = ['.json', '.yaml', '.yml'];
 export const SAFE_TEXT_SIZE_LIMIT = 100 * 1024; // 100 KiB (safe threshold, API limit is 128 KiB)
 
 export const MAX_CUSTOM_INSTRUCTIONS = 10;
 export const MAX_CUSTOM_INSTRUCTION_CHARS = 300;
 
-export function warnIgnoredOptions(mode: string, options: TranslateOptions, supportedKeys: Set<string>): void {
+export function warnIgnoredOptions(
+  mode: string,
+  options: TranslateOptions,
+  supportedKeys: Set<string>
+): void {
   const optionLabels: Record<string, string> = {
     splitSentences: '--split-sentences',
     tagHandling: '--tag-handling',
@@ -49,13 +65,19 @@ export function warnIgnoredOptions(mode: string, options: TranslateOptions, supp
   for (const [key, flag] of Object.entries(optionLabels)) {
     if (supportedKeys.has(key)) continue;
     const val = options[key as keyof TranslateOptions];
-    if (val !== undefined && val !== false && !(Array.isArray(val) && val.length === 0)) {
+    if (
+      val !== undefined &&
+      val !== false &&
+      !(Array.isArray(val) && val.length === 0)
+    ) {
       ignored.push(flag);
     }
   }
 
   if (ignored.length > 0) {
-    Logger.warn(`Warning: ${mode} mode does not support ${ignored.join(', ')}; these options will be ignored.`);
+    Logger.warn(
+      `Warning: ${mode} mode does not support ${ignored.join(', ')}; these options will be ignored.`
+    );
   }
 }
 
@@ -84,7 +106,10 @@ export function resetDeferredLanguageWarnings(): void {
  * `role` names the flag in the rejection, since `--from` and `--to` are rejected
  * for the same reasons and a user needs to know which one to fix.
  */
-function validateLanguageCode(langCode: string, role: 'target' | 'source'): void {
+function validateLanguageCode(
+  langCode: string,
+  role: 'target' | 'source'
+): void {
   if (VALID_LANGUAGES.has(langCode)) return;
 
   if (looksLikeLanguageTag(langCode)) {
@@ -140,33 +165,42 @@ export interface TranslationLanguageConstraints extends ExtendedLanguageConstrai
  */
 export function validateTranslationLanguages(
   targets: string[],
-  options: TranslationLanguageConstraints,
+  options: TranslationLanguageConstraints
 ): void {
   validateSourceLanguage(options.from);
   validateLanguageCodes(targets);
   validateExtendedLanguageConstraints(targets.join(','), options);
 }
 
-export function validateExtendedLanguageConstraints(targetLang: string, options: ExtendedLanguageConstraints): void {
+export function validateExtendedLanguageConstraints(
+  targetLang: string,
+  options: ExtendedLanguageConstraints
+): void {
   const langs = targetLang.includes(',')
-    ? targetLang.split(',').map(l => l.trim())
+    ? targetLang.split(',').map((l) => l.trim())
     : [targetLang];
 
-  const extendedLangs = langs.filter(l => EXTENDED_ONLY_LANGUAGES.has(l));
+  const extendedLangs = langs.filter((l) => EXTENDED_ONLY_LANGUAGES.has(l));
   if (extendedLangs.length === 0) return;
 
   const langList = extendedLangs.join(', ');
 
   if (options.modelType === 'latency_optimized') {
-    throw new ValidationError(`Language(s) ${langList} only support quality_optimized model type, not latency_optimized`);
+    throw new ValidationError(
+      `Language(s) ${langList} only support quality_optimized model type, not latency_optimized`
+    );
   }
 
   if (options.formality && options.formality !== 'default') {
-    throw new ValidationError(`Language(s) ${langList} do not support formality settings`);
+    throw new ValidationError(
+      `Language(s) ${langList} do not support formality settings`
+    );
   }
 
   if (hasGlossarySelection(options)) {
-    throw new ValidationError(`Language(s) ${langList} do not support glossaries`);
+    throw new ValidationError(
+      `Language(s) ${langList} do not support glossaries`
+    );
   }
 }
 
@@ -179,11 +213,15 @@ export function validateXmlTags(tags: string[], paramName: string): void {
     }
 
     if (tag.toLowerCase().startsWith('xml')) {
-      throw new ValidationError(`${paramName}: Tag name "${tag}" cannot start with "xml" (reserved)`);
+      throw new ValidationError(
+        `${paramName}: Tag name "${tag}" cannot start with "xml" (reserved)`
+      );
     }
 
     if (!xmlNamePattern.test(tag)) {
-      throw new ValidationError(`${paramName}: Invalid XML tag name "${tag}". Tags must start with a letter or underscore and contain only letters, digits, hyphens, underscores, or periods.`);
+      throw new ValidationError(
+        `${paramName}: Invalid XML tag name "${tag}". Tags must start with a letter or underscore and contain only letters, digits, hyphens, underscores, or periods.`
+      );
     }
   }
 }
@@ -194,19 +232,26 @@ export function validateXmlTags(tags: string[], paramName: string): void {
  * dropped the flag would send v2 to a caller who asked for v1.
  */
 export function validateTagHandlingVersion(
-  options: TranslateOptions,
+  options: TranslateOptions
 ): TranslationParams['tagHandlingVersion'] {
   if (!options.tagHandlingVersion) return undefined;
   if (!options.tagHandling) {
-    throw new ValidationError('--tag-handling-version requires --tag-handling to be set (xml or html)');
+    throw new ValidationError(
+      '--tag-handling-version requires --tag-handling to be set (xml or html)'
+    );
   }
-  if (options.tagHandlingVersion !== 'v1' && options.tagHandlingVersion !== 'v2') {
+  if (
+    options.tagHandlingVersion !== 'v1' &&
+    options.tagHandlingVersion !== 'v2'
+  ) {
     throw new ValidationError('--tag-handling-version must be "v1" or "v2"');
   }
   return options.tagHandlingVersion;
 }
 
-export function buildTranslationOptions(options: TranslateOptions): TranslationParams {
+export function buildTranslationOptions(
+  options: TranslateOptions
+): TranslationParams {
   const result: TranslationParams = {
     targetLang: options.to as Language,
   };
@@ -214,12 +259,18 @@ export function buildTranslationOptions(options: TranslateOptions): TranslationP
   if (options.from) result.sourceLang = options.from as Language;
   if (options.formality) result.formality = options.formality as Formality;
   if (options.context) result.context = options.context;
-  if (options.splitSentences) result.splitSentences = options.splitSentences as TranslationParams['splitSentences'];
-  if (options.tagHandling) result.tagHandling = options.tagHandling as TranslationParams['tagHandling'];
+  if (options.splitSentences)
+    result.splitSentences =
+      options.splitSentences as TranslationParams['splitSentences'];
+  if (options.tagHandling)
+    result.tagHandling =
+      options.tagHandling as TranslationParams['tagHandling'];
   const tagHandlingVersion = validateTagHandlingVersion(options);
   if (tagHandlingVersion) result.tagHandlingVersion = tagHandlingVersion;
-  if (options.modelType) result.modelType = options.modelType as TranslationParams['modelType'];
-  if (options.preserveFormatting !== undefined) result.preserveFormatting = options.preserveFormatting;
+  if (options.modelType)
+    result.modelType = options.modelType as TranslationParams['modelType'];
+  if (options.preserveFormatting !== undefined)
+    result.preserveFormatting = options.preserveFormatting;
   if (options.showBilledCharacters) result.showBilledCharacters = true;
 
   return result;
@@ -228,12 +279,16 @@ export function buildTranslationOptions(options: TranslateOptions): TranslationP
 export async function resolveGlossaryId(
   glossaryService: GlossaryService,
   nameOrId: string,
-  expected?: { from: Language; targets: Language[] },
+  expected?: { from: Language; targets: Language[] }
 ): Promise<string> {
   return glossaryService.resolveGlossaryId(nameOrId, expected);
 }
 
-export function isFilePath(input: string, cachedStats: fs.Stats | null | undefined, fileTranslationService: FileTranslationService): boolean {
+export function isFilePath(
+  input: string,
+  cachedStats: fs.Stats | null | undefined,
+  fileTranslationService: FileTranslationService
+): boolean {
   if (cachedStats?.isFile()) {
     return true;
   }
@@ -246,9 +301,8 @@ export function isFilePath(input: string, cachedStats: fs.Stats | null | undefin
     return false;
   }
 
-  const hasPathSep = input.includes(path.sep) ||
-                     input.includes('/') ||
-                     input.includes('\\');
+  const hasPathSep =
+    input.includes(path.sep) || input.includes('/') || input.includes('\\');
 
   return hasPathSep && fileTranslationService.isSupportedFile(input);
 }
diff --git a/src/cli/commands/translate/translation-options-factory.ts b/src/cli/commands/translate/translation-options-factory.ts
index 09abfc43..4e266ae6 100644
--- a/src/cli/commands/translate/translation-options-factory.ts
+++ b/src/cli/commands/translate/translation-options-factory.ts
@@ -3,7 +3,10 @@ import type { GlossaryService } from '../../../services/glossary.js';
 import type { TranslationService } from '../../../services/translation.js';
 import { resolveTranslationMemoryId } from '../../../services/translation-memory.js';
 import type { TranslateOptions, TranslationParams } from './types.js';
-import { buildTranslationOptions as buildBaseLegacy, resolveGlossaryId } from './translate-utils.js';
+import {
+  buildTranslationOptions as buildBaseLegacy,
+  resolveGlossaryId,
+} from './translate-utils.js';
 
 /**
  * Single source of truth for the *base* TranslateOptions mapping from CLI
@@ -24,7 +27,9 @@ import { buildTranslationOptions as buildBaseLegacy, resolveGlossaryId } from '.
  *  - XML tag-handling parameters (`outlineDetection`, `splittingTags`, etc.)
  *    are text-handler-specific.
  */
-export function buildBaseTranslationOptions(options: TranslateOptions): TranslationParams {
+export function buildBaseTranslationOptions(
+  options: TranslateOptions
+): TranslationParams {
   return buildBaseLegacy(options);
 }
 
@@ -44,7 +49,7 @@ export async function applyGlossarySelection<
   base: T,
   options: TranslateOptions,
   glossaryService: GlossaryService,
-  targets?: Language[],
+  targets?: Language[]
 ): Promise<void> {
   if (!options.glossary || options.glossary.length === 0) {
     return;
@@ -123,9 +128,14 @@ export async function applySharedTmAndGlossary<
 >(
   base: T,
   options: TranslateOptions,
-  deps: SharedTmAndGlossaryDeps,
+  deps: SharedTmAndGlossaryDeps
 ): Promise<void> {
-  await applyGlossarySelection(base, options, deps.glossaryService, deps.targets);
+  await applyGlossarySelection(
+    base,
+    options,
+    deps.glossaryService,
+    deps.targets
+  );
 
   if (options.translationMemory) {
     const cache = deps.tmCache ?? new Map<string, string>();
@@ -133,7 +143,7 @@ export async function applySharedTmAndGlossary<
       deps.translationService,
       options.translationMemory,
       cache,
-      { from: options.from as Language, targets: deps.targets },
+      { from: options.from as Language, targets: deps.targets }
     );
     if (options.tmThreshold !== undefined) {
       base.translationMemoryThreshold = options.tmThreshold;
diff --git a/src/cli/commands/usage.ts b/src/cli/commands/usage.ts
index 0b44e7dd..a8134157 100644
--- a/src/cli/commands/usage.ts
+++ b/src/cli/commands/usage.ts
@@ -18,7 +18,10 @@ function productDisplayName(productType: string): string {
 }
 
 function isDurationBilled(product: ProductUsage): boolean {
-  return product.billingUnit !== undefined && DURATION_BILLING_UNITS.has(product.billingUnit);
+  return (
+    product.billingUnit !== undefined &&
+    DURATION_BILLING_UNITS.has(product.billingUnit)
+  );
 }
 
 /**
@@ -41,12 +44,20 @@ function productDurationsMs(product: ProductUsage): {
   const perMinute = product.billingUnit === 'minutes';
   const scale = perMinute ? 60_000 : 1;
   const duration = (value: number | null | undefined): number | undefined =>
-    typeof value === 'number' && Number.isFinite(value) ? value * scale : undefined;
-  const accountFallback = perMinute ? undefined : duration(product.characterCount);
-  const apiKeyFallback = perMinute ? undefined : duration(product.apiKeyCharacterCount);
+    typeof value === 'number' && Number.isFinite(value)
+      ? value * scale
+      : undefined;
+  const accountFallback = perMinute
+    ? undefined
+    : duration(product.characterCount);
+  const apiKeyFallback = perMinute
+    ? undefined
+    : duration(product.apiKeyCharacterCount);
   return {
     accountUsed:
-      duration(product.unitCount) ?? duration(product.accountUnitCount) ?? accountFallback,
+      duration(product.unitCount) ??
+      duration(product.accountUnitCount) ??
+      accountFallback,
     apiKeyUsed: duration(product.apiKeyUnitCount) ?? apiKeyFallback,
   };
 }
@@ -71,29 +82,37 @@ export class UsageCommand {
   formatUsage(usage: UsageInfo): string {
     const { characterCount, characterLimit } = usage;
 
-    const percentage = characterLimit > 0
-      ? ((characterCount / characterLimit) * 100).toFixed(1)
-      : '0.0';
+    const percentage =
+      characterLimit > 0
+        ? ((characterCount / characterLimit) * 100).toFixed(1)
+        : '0.0';
 
     const remaining = characterLimit - characterCount;
-    const isHighUsage = characterLimit > 0 && (characterCount / characterLimit) > 0.8;
+    const isHighUsage =
+      characterLimit > 0 && characterCount / characterLimit > 0.8;
 
     // Tolerates a null the response may carry where the type says number: the
     // alternative is `deepl usage` throwing on a field it only displays.
     const formatNumber = (num: number | null | undefined): string => {
-      return typeof num === 'number' && Number.isFinite(num) ? num.toLocaleString('en-US') : '—';
+      return typeof num === 'number' && Number.isFinite(num)
+        ? num.toLocaleString('en-US')
+        : '—';
     };
 
     const lines: string[] = [];
     lines.push(chalk.bold('Character Usage:'));
 
     const usageColor = isHighUsage ? chalk.yellow : chalk.green;
-    lines.push(`  Used: ${usageColor(formatNumber(characterCount))} / ${formatNumber(characterLimit)} (${usageColor(percentage + '%')})`);
+    lines.push(
+      `  Used: ${usageColor(formatNumber(characterCount))} / ${formatNumber(characterLimit)} (${usageColor(percentage + '%')})`
+    );
     lines.push(`  Remaining: ${formatNumber(remaining)}`);
 
     if (isHighUsage) {
       lines.push('');
-      lines.push(chalk.yellow('⚠ Warning: You are approaching your character limit'));
+      lines.push(
+        chalk.yellow('⚠ Warning: You are approaching your character limit')
+      );
     }
 
     if (usage.startTime || usage.endTime) {
@@ -108,23 +127,32 @@ export class UsageCommand {
       lines.push('');
       lines.push(chalk.bold('Account Unit Usage:'));
       const unitLimit = usage.accountUnitLimit ?? 0;
-      const unitLimitStr = unitLimit === 0 ? 'unlimited' : formatNumber(unitLimit);
-      lines.push(`  Used: ${formatNumber(usage.accountUnitCount)} / ${unitLimitStr} units`);
+      const unitLimitStr =
+        unitLimit === 0 ? 'unlimited' : formatNumber(unitLimit);
+      lines.push(
+        `  Used: ${formatNumber(usage.accountUnitCount)} / ${unitLimitStr} units`
+      );
     }
 
     if (usage.apiKeyUnitCount !== undefined) {
       lines.push('');
       lines.push(chalk.bold('API Key Unit Usage:'));
       const unitLimit = usage.apiKeyUnitLimit ?? 0;
-      const unitLimitStr = unitLimit === 0 ? 'unlimited' : formatNumber(unitLimit);
-      lines.push(`  Used: ${formatNumber(usage.apiKeyUnitCount)} / ${unitLimitStr} units`);
+      const unitLimitStr =
+        unitLimit === 0 ? 'unlimited' : formatNumber(unitLimit);
+      lines.push(
+        `  Used: ${formatNumber(usage.apiKeyUnitCount)} / ${unitLimitStr} units`
+      );
     } else if (usage.apiKeyCharacterCount !== undefined) {
       lines.push('');
       lines.push(chalk.bold('API Key Usage:'));
-      const limitStr = usage.apiKeyCharacterLimit === 0
-        ? 'unlimited'
-        : formatNumber(usage.apiKeyCharacterLimit ?? 0);
-      lines.push(`  Used: ${formatNumber(usage.apiKeyCharacterCount)} / ${limitStr}`);
+      const limitStr =
+        usage.apiKeyCharacterLimit === 0
+          ? 'unlimited'
+          : formatNumber(usage.apiKeyCharacterLimit ?? 0);
+      lines.push(
+        `  Used: ${formatNumber(usage.apiKeyCharacterCount)} / ${limitStr}`
+      );
     }
 
     if (usage.products && usage.products.length > 0) {
@@ -134,8 +162,14 @@ export class UsageCommand {
         const name = productDisplayName(product.productType);
         if (isDurationBilled(product)) {
           const { accountUsed, apiKeyUsed } = productDurationsMs(product);
-          const account = accountUsed === undefined ? undefined : this.formatMilliseconds(accountUsed);
-          const apiKey = apiKeyUsed === undefined ? undefined : this.formatMilliseconds(apiKeyUsed);
+          const account =
+            accountUsed === undefined
+              ? undefined
+              : this.formatMilliseconds(accountUsed);
+          const apiKey =
+            apiKeyUsed === undefined
+              ? undefined
+              : this.formatMilliseconds(apiKeyUsed);
           if (account !== undefined && apiKey !== undefined) {
             lines.push(`  ${name}: ${account} (API key: ${apiKey})`);
           } else if (apiKey !== undefined) {
@@ -144,12 +178,17 @@ export class UsageCommand {
             lines.push(`  ${name}: ${account ?? 'not reported'}`);
           }
         } else if (product.unitCount !== undefined) {
-          const apiKeyPart = product.apiKeyUnitCount !== undefined
-            ? ` (API key: ${formatNumber(product.apiKeyUnitCount)} units)`
-            : ` (API key: ${formatNumber(product.apiKeyCharacterCount)} characters)`;
-          lines.push(`  ${name}: ${formatNumber(product.unitCount)} units${apiKeyPart}`);
+          const apiKeyPart =
+            product.apiKeyUnitCount !== undefined
+              ? ` (API key: ${formatNumber(product.apiKeyUnitCount)} units)`
+              : ` (API key: ${formatNumber(product.apiKeyCharacterCount)} characters)`;
+          lines.push(
+            `  ${name}: ${formatNumber(product.unitCount)} units${apiKeyPart}`
+          );
         } else {
-          lines.push(`  ${name}: ${formatNumber(product.characterCount)} characters (API key: ${formatNumber(product.apiKeyCharacterCount)})`);
+          lines.push(
+            `  ${name}: ${formatNumber(product.characterCount)} characters (API key: ${formatNumber(product.apiKeyCharacterCount)})`
+          );
         }
       }
     }
@@ -233,13 +272,18 @@ export class UsageCommand {
           const { accountUsed, apiKeyUsed } = productDurationsMs(product);
           productTable.push([
             name,
-            accountUsed === undefined ? '—' : this.formatMilliseconds(accountUsed),
-            apiKeyUsed === undefined ? '—' : this.formatMilliseconds(apiKeyUsed),
+            accountUsed === undefined
+              ? '—'
+              : this.formatMilliseconds(accountUsed),
+            apiKeyUsed === undefined
+              ? '—'
+              : this.formatMilliseconds(apiKeyUsed),
           ]);
         } else if (product.unitCount !== undefined) {
-          const apiKeyVal = product.apiKeyUnitCount !== undefined
-            ? `${formatNumber(product.apiKeyUnitCount)} units`
-            : `${formatNumber(product.apiKeyCharacterCount)} chars`;
+          const apiKeyVal =
+            product.apiKeyUnitCount !== undefined
+              ? `${formatNumber(product.apiKeyUnitCount)} units`
+              : `${formatNumber(product.apiKeyCharacterCount)} chars`;
           productTable.push([
             name,
             `${formatNumber(product.unitCount)} units`,
diff --git a/src/cli/commands/voice.ts b/src/cli/commands/voice.ts
index f27d32e9..1bd00dd2 100644
--- a/src/cli/commands/voice.ts
+++ b/src/cli/commands/voice.ts
@@ -21,45 +21,123 @@ import { Logger } from '../../utils/logger.js';
 import { sanitizeForTerminal } from '../../utils/control-chars.js';
 import { VoicePartialResultError } from '../../services/voice-stream-session.js';
 
-const VALID_VOICE_TARGET_LANGS: ReadonlySet<string> = new Set<VoiceTargetLanguage>([
-  'ar','bg','cs','da','de','el','en','en-GB','en-US','es','et','fi','fr',
-  'he','hu','id','it','ja','ko','lt','lv','nb','nl','pl','pt','pt-BR','pt-PT',
-  'ro','ru','sk','sl','sv','th','tr','uk','vi','zh','zh-HANS','zh-HANT',
-]);
-
-const VALID_VOICE_SOURCE_LANGS: ReadonlySet<string> = new Set<VoiceSourceLanguage>([
-  'ar','bg','cs','da','de','el','en','es','et','fi','fr','hu','id','it',
-  'ja','ko','lt','lv','nb','nl','pl','pt','ro','ru','sk','sl','sv','tr','uk','zh',
-]);
+const VALID_VOICE_TARGET_LANGS: ReadonlySet<string> =
+  new Set<VoiceTargetLanguage>([
+    'ar',
+    'bg',
+    'cs',
+    'da',
+    'de',
+    'el',
+    'en',
+    'en-GB',
+    'en-US',
+    'es',
+    'et',
+    'fi',
+    'fr',
+    'he',
+    'hu',
+    'id',
+    'it',
+    'ja',
+    'ko',
+    'lt',
+    'lv',
+    'nb',
+    'nl',
+    'pl',
+    'pt',
+    'pt-BR',
+    'pt-PT',
+    'ro',
+    'ru',
+    'sk',
+    'sl',
+    'sv',
+    'th',
+    'tr',
+    'uk',
+    'vi',
+    'zh',
+    'zh-HANS',
+    'zh-HANT',
+  ]);
+
+const VALID_VOICE_SOURCE_LANGS: ReadonlySet<string> =
+  new Set<VoiceSourceLanguage>([
+    'ar',
+    'bg',
+    'cs',
+    'da',
+    'de',
+    'el',
+    'en',
+    'es',
+    'et',
+    'fi',
+    'fr',
+    'hu',
+    'id',
+    'it',
+    'ja',
+    'ko',
+    'lt',
+    'lv',
+    'nb',
+    'nl',
+    'pl',
+    'pt',
+    'ro',
+    'ru',
+    'sk',
+    'sl',
+    'sv',
+    'tr',
+    'uk',
+    'zh',
+  ]);
 
 /**
  * Lowercase lookups onto the spellings the Voice API expects (`en-GB`,
  * `zh-HANS`), so input is accepted in any casing as it is everywhere else.
  */
 const VOICE_TARGET_BY_LOWERCASE = new Map<string, VoiceTargetLanguage>(
-  Array.from(VALID_VOICE_TARGET_LANGS, lang => [
+  Array.from(VALID_VOICE_TARGET_LANGS, (lang) => [
     lang.toLowerCase(),
     lang as VoiceTargetLanguage,
-  ]),
+  ])
 );
 const VOICE_SOURCE_BY_LOWERCASE = new Map<string, VoiceSourceLanguage>(
-  Array.from(VALID_VOICE_SOURCE_LANGS, lang => [
+  Array.from(VALID_VOICE_SOURCE_LANGS, (lang) => [
     lang.toLowerCase(),
     lang as VoiceSourceLanguage,
-  ]),
+  ])
 );
 
-const VALID_VOICE_CONTENT_TYPES: ReadonlySet<string> = new Set<VoiceSourceMediaContentType>([
-  'audio/auto',
-  'audio/pcm;encoding=s16le;rate=8000','audio/pcm;encoding=s16le;rate=16000',
-  'audio/pcm;encoding=s16le;rate=44100','audio/pcm;encoding=s16le;rate=48000',
-  'audio/opus;container=ogg','audio/opus;container=webm','audio/opus;container=matroska',
-  'audio/ogg','audio/ogg;codecs=flac','audio/ogg;codecs=opus',
-  'audio/webm','audio/webm;codecs=opus',
-  'audio/x-matroska','audio/x-matroska;codecs=aac','audio/x-matroska;codecs=flac',
-  'audio/x-matroska;codecs=mp3','audio/x-matroska;codecs=opus',
-  'audio/flac','audio/mpeg',
-]);
+const VALID_VOICE_CONTENT_TYPES: ReadonlySet<string> =
+  new Set<VoiceSourceMediaContentType>([
+    'audio/auto',
+    'audio/pcm;encoding=s16le;rate=8000',
+    'audio/pcm;encoding=s16le;rate=16000',
+    'audio/pcm;encoding=s16le;rate=44100',
+    'audio/pcm;encoding=s16le;rate=48000',
+    'audio/opus;container=ogg',
+    'audio/opus;container=webm',
+    'audio/opus;container=matroska',
+    'audio/ogg',
+    'audio/ogg;codecs=flac',
+    'audio/ogg;codecs=opus',
+    'audio/webm',
+    'audio/webm;codecs=opus',
+    'audio/x-matroska',
+    'audio/x-matroska;codecs=aac',
+    'audio/x-matroska;codecs=flac',
+    'audio/x-matroska;codecs=mp3',
+    'audio/x-matroska;codecs=opus',
+    'audio/flac',
+    'audio/mpeg',
+  ]);
 
 /**
  * Join transcript segments for the live display, with response text sanitized.
@@ -98,7 +176,7 @@ export function validateVoiceOptions(options: {
     const canonical = VOICE_TARGET_BY_LOWERCASE.get(raw.toLowerCase());
     if (!canonical) {
       throw new ValidationError(
-        `Invalid voice target language: "${raw}". Valid codes: ${Array.from(VALID_VOICE_TARGET_LANGS).sort().join(', ')}`,
+        `Invalid voice target language: "${raw}". Valid codes: ${Array.from(VALID_VOICE_TARGET_LANGS).sort().join(', ')}`
       );
     }
     return canonical;
@@ -109,14 +187,17 @@ export function validateVoiceOptions(options: {
     sourceLang = VOICE_SOURCE_BY_LOWERCASE.get(options.from.toLowerCase());
     if (!sourceLang) {
       throw new ValidationError(
-        `Invalid voice source language: "${options.from}". Valid codes: ${Array.from(VALID_VOICE_SOURCE_LANGS).sort().join(', ')}`,
+        `Invalid voice source language: "${options.from}". Valid codes: ${Array.from(VALID_VOICE_SOURCE_LANGS).sort().join(', ')}`
       );
     }
   }
 
-  if (options.contentType && !VALID_VOICE_CONTENT_TYPES.has(options.contentType)) {
+  if (
+    options.contentType &&
+    !VALID_VOICE_CONTENT_TYPES.has(options.contentType)
+  ) {
     throw new ValidationError(
-      `Invalid voice content type: "${options.contentType}". Valid types: ${Array.from(VALID_VOICE_CONTENT_TYPES).sort().join(', ')}`,
+      `Invalid voice content type: "${options.contentType}". Valid types: ${Array.from(VALID_VOICE_CONTENT_TYPES).sort().join(', ')}`
     );
   }
 
@@ -145,20 +226,32 @@ export class VoiceCommand {
     this.voiceService = voiceService;
   }
 
-  async translate(filePath: string, options: VoiceCommandOptions): Promise<string> {
+  async translate(
+    filePath: string,
+    options: VoiceCommandOptions
+  ): Promise<string> {
     const translateOptions = this.buildOptions(options);
     const isTTY = process.stdout.isTTY && options.stream !== false;
 
     let callbacks: VoiceStreamCallbacks | undefined;
     if (isTTY) {
-      callbacks = this.createTTYCallbacks(translateOptions.targetLangs, translateOptions.maxReconnectAttempts);
+      callbacks = this.createTTYCallbacks(
+        translateOptions.targetLangs,
+        translateOptions.maxReconnectAttempts
+      );
     }
 
-    const sigintHandler = () => { this.voiceService.cancel(); };
+    const sigintHandler = () => {
+      this.voiceService.cancel();
+    };
     process.on('SIGINT', sigintHandler);
 
     try {
-      const result = await this.voiceService.translateFile(filePath, translateOptions, callbacks);
+      const result = await this.voiceService.translateFile(
+        filePath,
+        translateOptions,
+        callbacks
+      );
 
       if (isTTY) {
         this.clearTTYDisplay(translateOptions.targetLangs.length);
@@ -170,7 +263,7 @@ export class VoiceCommand {
         error,
         translateOptions.targetLangs.length,
         isTTY,
-        options.format,
+        options.format
       );
       throw error;
     } finally {
@@ -184,14 +277,22 @@ export class VoiceCommand {
 
     let callbacks: VoiceStreamCallbacks | undefined;
     if (isTTY) {
-      callbacks = this.createTTYCallbacks(translateOptions.targetLangs, translateOptions.maxReconnectAttempts);
+      callbacks = this.createTTYCallbacks(
+        translateOptions.targetLangs,
+        translateOptions.maxReconnectAttempts
+      );
     }
 
-    const sigintHandler = () => { this.voiceService.cancel(); };
+    const sigintHandler = () => {
+      this.voiceService.cancel();
+    };
     process.on('SIGINT', sigintHandler);
 
     try {
-      const result = await this.voiceService.translateStdin(translateOptions, callbacks);
+      const result = await this.voiceService.translateStdin(
+        translateOptions,
+        callbacks
+      );
 
       if (isTTY) {
         this.clearTTYDisplay(translateOptions.targetLangs.length);
@@ -203,7 +304,7 @@ export class VoiceCommand {
         error,
         translateOptions.targetLangs.length,
         isTTY,
-        options.format,
+        options.format
       );
       throw error;
     } finally {
@@ -217,19 +318,21 @@ export class VoiceCommand {
     if (options.glossary && targetLangs.length > 1) {
       process.stderr.write(
         `Warning: --glossary applies a single glossary ID to all target languages. ` +
-        `DeepL glossaries are language-pair-specific, so the glossary may not be compatible ` +
-        `with all targets (${targetLangs.join(', ')}). ` +
-        `Consider translating each target language separately with its own glossary.\n`,
+          `DeepL glossaries are language-pair-specific, so the glossary may not be compatible ` +
+          `with all targets (${targetLangs.join(', ')}). ` +
+          `Consider translating each target language separately with its own glossary.\n`
       );
     }
 
     return {
       targetLangs,
       sourceLang,
-      sourceLanguageMode: options.sourceLanguageMode as VoiceSourceLanguageMode | undefined,
+      sourceLanguageMode: options.sourceLanguageMode as
+        VoiceSourceLanguageMode | undefined,
       formality: options.formality as VoiceTranslateOptions['formality'],
       glossaryId: options.glossary,
-      contentType: options.contentType as VoiceSourceMediaContentType | undefined,
+      contentType: options.contentType as
+        VoiceSourceMediaContentType | undefined,
       chunkSize: options.chunkSize,
       chunkInterval: options.chunkInterval,
       reconnect: options.reconnect,
@@ -237,7 +340,10 @@ export class VoiceCommand {
     };
   }
 
-  private createTTYCallbacks(targetLangs: VoiceTargetLanguage[], maxReconnectAttempts?: number): VoiceStreamCallbacks {
+  private createTTYCallbacks(
+    targetLangs: VoiceTargetLanguage[],
+    maxReconnectAttempts?: number
+  ): VoiceStreamCallbacks {
     const state: Record<string, { concluded: string; tentative: string }> = {};
 
     // Initialize state for source + each target. Keyed lowercase for the same
@@ -258,14 +364,18 @@ export class VoiceCommand {
       const src = state['source']!;
       readline.clearLine(process.stdout, 0);
       readline.cursorTo(process.stdout, 0);
-      process.stdout.write(`${chalk.bold('[source]')} ${src.concluded}${chalk.gray(src.tentative)}\n`);
+      process.stdout.write(
+        `${chalk.bold('[source]')} ${src.concluded}${chalk.gray(src.tentative)}\n`
+      );
 
       // Render each target language
       for (const lang of targetLangs) {
         const tgt = state[lang]!;
         readline.clearLine(process.stdout, 0);
         readline.cursorTo(process.stdout, 0);
-        process.stdout.write(`${chalk.bold(`[${lang}]`)} ${tgt.concluded}${chalk.gray(tgt.tentative)}\n`);
+        process.stdout.write(
+          `${chalk.bold(`[${lang}]`)} ${tgt.concluded}${chalk.gray(tgt.tentative)}\n`
+        );
       }
     };
 
@@ -289,7 +399,9 @@ export class VoiceCommand {
 
     return {
       onReconnecting: (attempt: number) => {
-        process.stdout.write(chalk.yellow(`[reconnecting ${attempt}/${maxAttempts}...]\n`));
+        process.stdout.write(
+          chalk.yellow(`[reconnecting ${attempt}/${maxAttempts}...]\n`)
+        );
       },
       onSourceTranscript: (update) => {
         const src = state['source']!;
@@ -342,7 +454,7 @@ export class VoiceCommand {
     error: unknown,
     targetCount: number,
     isTTY: boolean,
-    format?: string,
+    format?: string
   ): void {
     if (!(error instanceof VoicePartialResultError)) {
       return;
@@ -380,7 +492,9 @@ export class VoiceCommand {
     }
 
     for (const target of result.targets) {
-      lines.push(`[${sanitizeForTerminal(target.lang)}] ${sanitizeForTerminal(target.text)}`);
+      lines.push(
+        `[${sanitizeForTerminal(target.lang)}] ${sanitizeForTerminal(target.text)}`
+      );
     }
 
     return lines.join('\n');
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index f2820833..8893ee97 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -11,10 +11,16 @@ import { FileTranslationService } from '../../services/file-translation.js';
 import { TranslationService } from '../../services/translation.js';
 import { GlossaryService } from '../../services/glossary.js';
 import { Language, Formality } from '../../types/index.js';
-import { FileTranslationResult, WatchTranslationResult } from '../../services/watch.js';
+import {
+  FileTranslationResult,
+  WatchTranslationResult,
+} from '../../services/watch.js';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
-import { applyGlossarySourceLang, hasGlossarySelection } from '../../utils/glossary-params.js';
+import {
+  applyGlossarySourceLang,
+  hasGlossarySelection,
+} from '../../utils/glossary-params.js';
 import type { ConfigService } from '../../storage/config.js';
 import { DEFAULT_DEBOUNCE_MS } from '../../storage/config.js';
 
@@ -47,16 +53,18 @@ export class WatchCommand {
   constructor(
     translationService: TranslationService,
     glossaryService: GlossaryService,
-    config?: ConfigService,
+    config?: ConfigService
   ) {
-    this.fileTranslationService = new FileTranslationService(translationService);
+    this.fileTranslationService = new FileTranslationService(
+      translationService
+    );
     this.glossaryService = glossaryService;
     this.config = config;
   }
 
   private async resolveGlossaryId(
     nameOrId: string,
-    expected?: { from: Language; targets: Language[] },
+    expected?: { from: Language; targets: Language[] }
   ): Promise<string> {
     return this.glossaryService.resolveGlossaryId(nameOrId, expected);
   }
@@ -77,9 +85,17 @@ export class WatchCommand {
       throw new ValidationError('--git-staged requires a git repository');
     }
 
-    const { stdout } = await execFileAsync('git', ['diff', '--cached', '--name-only', '--diff-filter=ACM']);
-    const files = stdout.trim().split('\n').filter(f => f.length > 0);
-    return new Set(files.map(f => path.resolve(f)));
+    const { stdout } = await execFileAsync('git', [
+      'diff',
+      '--cached',
+      '--name-only',
+      '--diff-filter=ACM',
+    ]);
+    const files = stdout
+      .trim()
+      .split('\n')
+      .filter((f) => f.length > 0);
+    return new Set(files.map((f) => path.resolve(f)));
   }
 
   /**
@@ -92,12 +108,15 @@ export class WatchCommand {
     }
 
     // Parse target languages
-    const targetLangs = options.to.split(',').map(lang => lang.trim()).filter(lang => lang.length > 0) as Language[];
+    const targetLangs = options.to
+      .split(',')
+      .map((lang) => lang.trim())
+      .filter((lang) => lang.length > 0) as Language[];
 
     if (targetLangs.length === 0) {
       throw new ValidationError(
         'No target language specified.',
-        'Use --to <lang>:   deepl watch ./docs --to es,fr,de\n  Set a default:     deepl init',
+        'Use --to <lang>:   deepl watch ./docs --to es,fr,de\n  Set a default:     deepl init'
       );
     }
 
@@ -110,7 +129,7 @@ export class WatchCommand {
       applyGlossarySourceLang(
         options,
         this.config?.getValue<string>('defaults.sourceLang'),
-        'Example: deepl watch ./docs --from en --to es --glossary my-glossary',
+        'Example: deepl watch ./docs --from en --to es --glossary my-glossary'
       );
     }
 
@@ -119,7 +138,9 @@ export class WatchCommand {
     if (options.gitStaged) {
       stagedFiles = await this.getStagedFiles();
       if (stagedFiles.size === 0) {
-        Logger.warn(chalk.yellow('No git-staged files found. Nothing to watch.'));
+        Logger.warn(
+          chalk.yellow('No git-staged files found. Nothing to watch.')
+        );
         return;
       }
       Logger.info(chalk.gray(`Git-staged files: ${stagedFiles.size}`));
@@ -131,7 +152,9 @@ export class WatchCommand {
     if (options.glossary) {
       glossaryId = await this.resolveGlossaryId(
         options.glossary,
-        options.from ? { from: options.from as Language, targets: targetLangs } : undefined,
+        options.from
+          ? { from: options.from as Language, targets: targetLangs }
+          : undefined
       );
     }
 
@@ -176,7 +199,10 @@ export class WatchCommand {
       watchServiceOptions.concurrency = options.concurrency;
     }
 
-    this.watchService = new WatchService(this.fileTranslationService, watchServiceOptions);
+    this.watchService = new WatchService(
+      this.fileTranslationService,
+      watchServiceOptions
+    );
 
     // Create abort controller for cancellation
     const controller = new AbortController();
@@ -197,7 +223,11 @@ export class WatchCommand {
       onTranslate: async (filePath: string, result: WatchTranslationResult) => {
         if (Array.isArray(result)) {
           // Multiple languages
-          Logger.success(chalk.green(`✓ Translated ${filePath} to ${result.length} languages`));
+          Logger.success(
+            chalk.green(
+              `✓ Translated ${filePath} to ${result.length} languages`
+            )
+          );
           result.forEach((r: FileTranslationResult) => {
             Logger.info(chalk.gray(`  → [${r.targetLang}] ${r.outputPath}`));
           });
@@ -213,7 +243,10 @@ export class WatchCommand {
         }
       },
       onError: (filePath: string, error: Error) => {
-        Logger.error(chalk.red(`✗ Translation failed for ${filePath}:`), error.message);
+        Logger.error(
+          chalk.red(`✗ Translation failed for ${filePath}:`),
+          error.message
+        );
       },
     };
 
@@ -263,7 +296,10 @@ export class WatchCommand {
    * Auto-commit translated files to git
    * SECURITY: Uses execFile instead of exec to prevent command injection
    */
-  private async autoCommit(sourceFile: string, result: WatchTranslationResult): Promise<void> {
+  private async autoCommit(
+    sourceFile: string,
+    result: WatchTranslationResult
+  ): Promise<void> {
     try {
       const { execFile } = await import('child_process');
       const { promisify } = await import('util');
@@ -273,7 +309,9 @@ export class WatchCommand {
       try {
         await execFileAsync('git', ['rev-parse', '--git-dir']);
       } catch {
-        Logger.warn(chalk.yellow('⚠️  Not a git repository, skipping auto-commit'));
+        Logger.warn(
+          chalk.yellow('⚠️  Not a git repository, skipping auto-commit')
+        );
         return;
       }
 
@@ -310,7 +348,10 @@ export class WatchCommand {
 
       Logger.success(chalk.green('✓ Auto-committed translations'));
     } catch (error) {
-      Logger.error(chalk.red('✗ Auto-commit failed:'), error instanceof Error ? error.message : 'Unknown error');
+      Logger.error(
+        chalk.red('✗ Auto-commit failed:'),
+        error instanceof Error ? error.message : 'Unknown error'
+      );
     }
   }
 
diff --git a/src/cli/commands/write.ts b/src/cli/commands/write.ts
index 04c01524..be0a2a20 100644
--- a/src/cli/commands/write.ts
+++ b/src/cli/commands/write.ts
@@ -45,15 +45,27 @@ export class WriteCommand {
     const serviceOptions = { skipCache: options.noCache };
 
     if (options.showAlternatives) {
-      const improvements = await this.fetchImprovements(text, options, serviceOptions);
-      return this.formatAlternatives(improvements.map(i => i.text));
+      const improvements = await this.fetchImprovements(
+        text,
+        options,
+        serviceOptions
+      );
+      return this.formatAlternatives(improvements.map((i) => i.text));
     }
 
-    const improvement = await this.fetchBestImprovement(text, options, serviceOptions);
+    const improvement = await this.fetchBestImprovement(
+      text,
+      options,
+      serviceOptions
+    );
 
     // Format output based on format option
     if (options.format === 'json') {
-      return formatWriteJson(text, improvement.text, options.lang ?? 'auto-detected');
+      return formatWriteJson(
+        text,
+        improvement.text,
+        options.lang ?? 'auto-detected'
+      );
     }
 
     return improvement.text;
@@ -68,9 +80,17 @@ export class WriteCommand {
     serviceOptions: { skipCache?: boolean }
   ) {
     if (options.correct) {
-      return this.writeService.correct(text, this.toCorrectOptions(options), serviceOptions);
+      return this.writeService.correct(
+        text,
+        this.toCorrectOptions(options),
+        serviceOptions
+      );
     }
-    return this.writeService.improve(text, this.toWriteOptions(options), serviceOptions);
+    return this.writeService.improve(
+      text,
+      this.toWriteOptions(options),
+      serviceOptions
+    );
   }
 
   private fetchBestImprovement(
@@ -79,9 +99,17 @@ export class WriteCommand {
     serviceOptions: { skipCache?: boolean }
   ) {
     if (options.correct) {
-      return this.writeService.getBestCorrection(text, this.toCorrectOptions(options), serviceOptions);
+      return this.writeService.getBestCorrection(
+        text,
+        this.toCorrectOptions(options),
+        serviceOptions
+      );
     }
-    return this.writeService.getBestImprovement(text, this.toWriteOptions(options), serviceOptions);
+    return this.writeService.getBestImprovement(
+      text,
+      this.toWriteOptions(options),
+      serviceOptions
+    );
   }
 
   private toWriteOptions(options: WriteOptions): {
@@ -96,7 +124,9 @@ export class WriteCommand {
     };
   }
 
-  private toCorrectOptions(options: WriteOptions): { targetLang?: WriteLanguage } {
+  private toCorrectOptions(options: WriteOptions): {
+    targetLang?: WriteLanguage;
+  } {
     return options.lang ? { targetLang: options.lang } : {};
   }
 
@@ -204,7 +234,7 @@ export class WriteCommand {
 
     // Count the number of changes using diff
     const patches = Diff.diffWords(text, improvedText);
-    const changes = patches.filter(p => p.added || p.removed).length;
+    const changes = patches.filter((p) => p.added || p.removed).length;
 
     return {
       needsImprovement: changes > 0,
@@ -294,14 +324,21 @@ export class WriteCommand {
    * Improve text interactively - show alternatives and let user choose
    * Generates multiple alternatives by calling the API with different styles/tones
    */
-  async improveInteractive(text: string, options: WriteOptions): Promise<string> {
+  async improveInteractive(
+    text: string,
+    options: WriteOptions
+  ): Promise<string> {
     const { select } = await import('@inquirer/prompts');
     const serviceOptions = { skipCache: options.noCache };
 
     // A single result is offered when the user pinned the request down to one
     // variant: an explicit style or tone, or correct mode (which has no styles).
     if (options.style || options.tone || options.correct) {
-      const improvements = await this.fetchImprovements(text, options, serviceOptions);
+      const improvements = await this.fetchImprovements(
+        text,
+        options,
+        serviceOptions
+      );
 
       const maxLen = this.getPreviewWidth();
       const choices = [
@@ -318,7 +355,9 @@ export class WriteCommand {
       ];
 
       const selection = await select({
-        message: options.correct ? 'Choose a correction:' : 'Choose an improvement:',
+        message: options.correct
+          ? 'Choose a correction:'
+          : 'Choose an improvement:',
         choices,
       });
 
@@ -332,10 +371,14 @@ export class WriteCommand {
     // Call API for each style
     for (const style of styles) {
       try {
-        const improvements = await this.writeService.improve(text, {
-          ...(options.lang ? { targetLang: options.lang } : {}),
-          writingStyle: style,
-        }, serviceOptions);
+        const improvements = await this.writeService.improve(
+          text,
+          {
+            ...(options.lang ? { targetLang: options.lang } : {}),
+            writingStyle: style,
+          },
+          serviceOptions
+        );
 
         if (improvements.length > 0 && improvements[0]) {
           allImprovements.push({
@@ -355,7 +398,7 @@ export class WriteCommand {
     // Remove duplicates (same text with different styles)
     const uniqueImprovements = allImprovements.filter(
       (improvement, index, self) =>
-        index === self.findIndex(t => t.text === improvement.text)
+        index === self.findIndex((t) => t.text === improvement.text)
     );
 
     // Create choices with style labels
@@ -404,8 +447,10 @@ export class WriteCommand {
 
     const content = await this.readFileContent(filePath);
 
-    const improvements = await this.fetchImprovements(content, options, { skipCache: options.noCache });
-    const alternatives = improvements.map(i => i.text);
+    const improvements = await this.fetchImprovements(content, options, {
+      skipCache: options.noCache,
+    });
+    const alternatives = improvements.map((i) => i.text);
 
     // Interactive selection
     const selected = await this.improveInteractive(content, options);
@@ -423,7 +468,10 @@ export class WriteCommand {
     try {
       return await safeReadFile(absolutePath, 'utf-8');
     } catch (error) {
-      if (error instanceof Error && error.message.includes('Symlinks are not supported')) {
+      if (
+        error instanceof Error &&
+        error.message.includes('Symlinks are not supported')
+      ) {
         throw error;
       }
       if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
@@ -461,6 +509,8 @@ export class WriteCommand {
    * Format alternatives with numbering
    */
   private formatAlternatives(alternatives: string[]): string {
-    return alternatives.map((alt, index) => `${index + 1}. ${alt}`).join('\n\n');
+    return alternatives
+      .map((alt, index) => `${index + 1}. ${alt}`)
+      .join('\n\n');
   }
 }
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 1a853154..7485e397 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -11,7 +11,10 @@ import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve, isAbsolute, extname } from 'path';
 import { ConfigService } from '../storage/config.js';
-import { createCacheServiceGetter, resolveCacheOptions } from './cache-loader.js';
+import {
+  createCacheServiceGetter,
+  resolveCacheOptions,
+} from './cache-loader.js';
 import { resolvePaths } from '../utils/paths.js';
 import type { DeepLClient } from '../api/deepl-client.js';
 import { Logger } from '../utils/logger.js';
@@ -68,7 +71,7 @@ let configService = new ConfigService(paths.configFile);
 let httpOptions: { timeout?: number; maxRetries?: number } = {};
 
 const getCacheService = createCacheServiceGetter(() =>
-  resolveCacheOptions(configService, paths.cacheFile),
+  resolveCacheOptions(configService, paths.cacheFile)
 );
 
 /**
@@ -377,7 +380,12 @@ program.on('command:*', (operands: string[]) => {
   const candidates = program
     .createHelp()
     .visibleCommands(program)
-    .flatMap((cmd) => [cmd.name(), ...cmd.aliases()].map((name) => ({ name, target: cmd.name() })));
+    .flatMap((cmd) =>
+      [cmd.name(), ...cmd.aliases()].map((name) => ({
+        name,
+        target: cmd.name(),
+      }))
+    );
 
   let bestMatch = '';
   let bestDistance = Infinity;
diff --git a/src/cli/node-version-check.ts b/src/cli/node-version-check.ts
index 2661dfbd..52c8cdbc 100644
--- a/src/cli/node-version-check.ts
+++ b/src/cli/node-version-check.ts
@@ -13,7 +13,7 @@ export const MIN_NODE_MAJOR = 24;
  * version is supported. Unparseable versions fail open.
  */
 export function unsupportedNodeVersionMessage(
-  version: string = process.versions.node,
+  version: string = process.versions.node
 ): string | null {
   const major = Number(version.split('.')[0]);
   if (!Number.isInteger(major) || major >= MIN_NODE_MAJOR) {
@@ -23,7 +23,7 @@ export function unsupportedNodeVersionMessage(
 }
 
 export function assertSupportedNodeVersion(
-  version: string = process.versions.node,
+  version: string = process.versions.node
 ): void {
   const message = unsupportedNodeVersionMessage(version);
   if (message) {
diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index 4fa85fd1..1594a14c 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -52,7 +52,7 @@ const ENTRIES: readonly LanguageEntry[] = GENERATED_ENTRIES;
 
 /** Read-only map of language code to its registry entry. Primary lookup structure. */
 export const LANGUAGE_REGISTRY: ReadonlyMap<string, LanguageEntry> = new Map(
-  ENTRIES.map(entry => [entry.code, entry])
+  ENTRIES.map((entry) => [entry.code, entry])
 );
 
 /** The fields of a GET /v3/languages entry the derivation below depends on. */
@@ -71,7 +71,9 @@ export interface DerivableLanguage {
  * Shared with scripts/generate-language-registry.mjs so the snapshot and the
  * runtime fallback for codes it does not list cannot disagree.
  */
-export function deriveLanguageEntry(language: DerivableLanguage): LanguageEntry {
+export function deriveLanguageEntry(
+  language: DerivableLanguage
+): LanguageEntry {
   const code = language.lang.toLowerCase();
   const usableAsSource = language.usable_as_source !== false;
 
@@ -83,11 +85,12 @@ export function deriveLanguageEntry(language: DerivableLanguage): LanguageEntry
   const described = language.features !== undefined;
   const supportsGlossary = language.features?.['glossary'] !== undefined;
 
-  const category: LanguageCategory = described && !supportsGlossary
-    ? 'extended'
-    : usableAsSource
-      ? 'core'
-      : 'regional';
+  const category: LanguageCategory =
+    described && !supportsGlossary
+      ? 'extended'
+      : usableAsSource
+        ? 'core'
+        : 'regional';
 
   return {
     code,
@@ -137,7 +140,7 @@ export function getLanguageName(code: string): string | undefined {
 
 /** Return all languages that can be used as a source language (excludes regional target-only variants). */
 export function getSourceLanguages(): LanguageEntry[] {
-  return ENTRIES.filter(e => !e.targetOnly);
+  return ENTRIES.filter((e) => !e.targetOnly);
 }
 
 /** Return all languages that can be used as a target language (includes regional variants). */
@@ -147,10 +150,12 @@ export function getTargetLanguages(): LanguageEntry[] {
 
 /** Return the set of all known language codes (core + regional + extended). */
 export function getAllLanguageCodes(): ReadonlySet<string> {
-  return new Set(ENTRIES.map(e => e.code));
+  return new Set(ENTRIES.map((e) => e.code));
 }
 
 /** Return only the extended-tier language codes (no formality/glossary support). */
 export function getExtendedLanguageCodes(): ReadonlySet<string> {
-  return new Set(ENTRIES.filter(e => e.category === 'extended').map(e => e.code));
+  return new Set(
+    ENTRIES.filter((e) => e.category === 'extended').map((e) => e.code)
+  );
 }
diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index d59b4318..796d5586 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -1,4 +1,8 @@
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 import { ValidationError } from '../utils/errors.js';
 import {
   replaceElements,
@@ -48,52 +52,82 @@ const XML_ENTITY_RE = /&(?:#x([0-9a-fA-F]+)|#(\d+)|(amp|lt|gt|quot|apos));/g;
  * `&lt;` rather than collapsing all the way to `<`.
  */
 function decodeXmlEntities(value: string): string {
-  return value.replace(XML_ENTITY_RE, (match, hex: string | undefined, dec: string | undefined, named: string | undefined) => {
-    if (hex !== undefined) {
-      const code = Number.parseInt(hex, 16);
-      return code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
-    }
-    if (dec !== undefined) {
-      const code = Number.parseInt(dec, 10);
-      return code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
-    }
-    switch (named) {
-      case 'amp': return '&';
-      case 'lt': return '<';
-      case 'gt': return '>';
-      case 'quot': return '"';
-      case 'apos': return "'";
-      default: return match;
+  return value.replace(
+    XML_ENTITY_RE,
+    (
+      match,
+      hex: string | undefined,
+      dec: string | undefined,
+      named: string | undefined
+    ) => {
+      if (hex !== undefined) {
+        const code = Number.parseInt(hex, 16);
+        return code >= 0 && code <= 0x10ffff
+          ? String.fromCodePoint(code)
+          : match;
+      }
+      if (dec !== undefined) {
+        const code = Number.parseInt(dec, 10);
+        return code >= 0 && code <= 0x10ffff
+          ? String.fromCodePoint(code)
+          : match;
+      }
+      switch (named) {
+        case 'amp':
+          return '&';
+        case 'lt':
+          return '<';
+        case 'gt':
+          return '>';
+        case 'quot':
+          return '"';
+        case 'apos':
+          return "'";
+        default:
+          return match;
+      }
     }
-  });
+  );
 }
 
 function unescapeAndroid(value: string): string {
-  const withoutBackslashEscapes = value.replace(/\\(\\|'|"|n|t|r)/g, (_match, ch: string) => {
-    switch (ch) {
-      case '\\': return '\\';
-      case "'": return "'";
-      case '"': return '"';
-      case 'n': return '\n';
-      case 't': return '\t';
-      case 'r': return '\r';
-      default: return ch;
+  const withoutBackslashEscapes = value.replace(
+    /\\(\\|'|"|n|t|r)/g,
+    (_match, ch: string) => {
+      switch (ch) {
+        case '\\':
+          return '\\';
+        case "'":
+          return "'";
+        case '"':
+          return '"';
+        case 'n':
+          return '\n';
+        case 't':
+          return '\t';
+        case 'r':
+          return '\r';
+        default:
+          return ch;
+      }
     }
-  });
+  );
   return decodeXmlEntities(withoutBackslashEscapes);
 }
 
 function escapeAndroid(value: string): string {
-  return value
-    .replace(/\\/g, '\\\\')
-    .replace(/\n/g, '\\n')
-    .replace(/'/g, "\\'")
-    .replace(/"/g, '\\"')
-    // & must precede < and >, or the entities produced below get re-escaped
-    // into &amp;lt; — which compounds on every subsequent sync run.
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+  return (
+    value
+      .replace(/\\/g, '\\\\')
+      .replace(/\n/g, '\\n')
+      .replace(/'/g, "\\'")
+      .replace(/"/g, '\\"')
+      // & must precede < and >, or the entities produced below get re-escaped
+      // into &amp;lt; — which compounds on every subsequent sync run.
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+  );
 }
 
 /**
@@ -107,7 +141,7 @@ function assertNoCdataBreakout(value: string): void {
   if (value.includes(']]>')) {
     throw new ValidationError(
       'Android CDATA values containing "]]>" are not supported.',
-      'Remove the "]]>" sequence from the text, or drop the <![CDATA[...]]> wrapper in the source file so the value is entity-escaped instead.',
+      'Remove the "]]>" sequence from the text, or drop the <![CDATA[...]]> wrapper in the source file so the value is entity-escaped instead.'
     );
   }
 }
@@ -146,7 +180,9 @@ export class AndroidXmlFormatParser implements FormatParser {
         const arrayName = entry.key.substring(0, lastDot);
         const index = parseInt(entry.key.substring(lastDot + 1), 10);
         arrayNames ??= new Set(
-          scanElements(originalContent, STRING_ARRAY_EL).map((el) => el.groups[0]!),
+          scanElements(originalContent, STRING_ARRAY_EL).map(
+            (el) => el.groups[0]!
+          )
         );
 
         if (!isNaN(index) && arrayNames.has(arrayName)) {
@@ -171,7 +207,10 @@ export class AndroidXmlFormatParser implements FormatParser {
       if (translation === undefined) {
         return null;
       }
-      return this.rewriteInner(el, this.escapeForReconstruct(el.inner, translation));
+      return this.rewriteInner(
+        el,
+        this.escapeForReconstruct(el.inner, translation)
+      );
     });
 
     result = replaceElements(result, PLURALS_EL, (el) => {
@@ -184,7 +223,10 @@ export class AndroidXmlFormatParser implements FormatParser {
         if (translation === undefined) {
           return item.text;
         }
-        return this.rewriteInner(item, this.escapeForReconstruct(item.inner, translation));
+        return this.rewriteInner(
+          item,
+          this.escapeForReconstruct(item.inner, translation)
+        );
       });
       return this.rewriteInner(el, inner);
     });
@@ -201,7 +243,10 @@ export class AndroidXmlFormatParser implements FormatParser {
         if (translation === undefined) {
           return item.text;
         }
-        return this.rewriteInner(item, this.escapeForReconstruct(item.inner, translation));
+        return this.rewriteInner(
+          item,
+          this.escapeForReconstruct(item.inner, translation)
+        );
       });
       return this.rewriteInner(el, inner);
     });
@@ -224,12 +269,15 @@ export class AndroidXmlFormatParser implements FormatParser {
 
   private extractPlurals(content: string, entries: ExtractedEntry[]): void {
     for (const el of scanElements(content, PLURALS_EL)) {
-      const plurals: PluralItem[] = scanElements(el.inner, PLURAL_ITEM_EL).map((item) => ({
-        quantity: item.groups[0]!,
-        value: this.decodeValue(item.inner),
-      }));
+      const plurals: PluralItem[] = scanElements(el.inner, PLURAL_ITEM_EL).map(
+        (item) => ({
+          quantity: item.groups[0]!,
+          value: this.decodeValue(item.inner),
+        })
+      );
 
-      const defaultItem = plurals.find(p => p.quantity === 'other') ?? plurals[0];
+      const defaultItem =
+        plurals.find((p) => p.quantity === 'other') ?? plurals[0];
       entries.push({
         key: el.groups[0]!,
         value: defaultItem?.value ?? '',
@@ -238,12 +286,18 @@ export class AndroidXmlFormatParser implements FormatParser {
     }
   }
 
-  private extractStringArrays(content: string, entries: ExtractedEntry[]): void {
+  private extractStringArrays(
+    content: string,
+    entries: ExtractedEntry[]
+  ): void {
     for (const el of scanElements(content, STRING_ARRAY_EL)) {
       const name = el.groups[0]!;
       let index = 0;
       for (const item of scanElements(el.inner, ARRAY_ITEM_EL)) {
-        entries.push({ key: `${name}.${index}`, value: this.decodeValue(item.inner) });
+        entries.push({
+          key: `${name}.${index}`,
+          value: this.decodeValue(item.inner),
+        });
         index++;
       }
     }
@@ -266,7 +320,10 @@ export class AndroidXmlFormatParser implements FormatParser {
     return unescapeAndroid(raw);
   }
 
-  private escapeForReconstruct(originalInner: string, translation: string): string {
+  private escapeForReconstruct(
+    originalInner: string,
+    translation: string
+  ): string {
     if (originalInner.startsWith('<![CDATA[')) {
       assertNoCdataBreakout(translation);
       return `<![CDATA[${translation}]]>`;
diff --git a/src/formats/arb.ts b/src/formats/arb.ts
index 548ec82c..778c055b 100644
--- a/src/formats/arb.ts
+++ b/src/formats/arb.ts
@@ -1,4 +1,8 @@
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 import { detectIndent } from './util/detect-indent.js';
 
 /** JSON.parse rejects a leading BOM, which editors on Windows add routinely. */
@@ -100,5 +104,4 @@ export class ArbFormatParser implements FormatParser {
     }
     return undefined;
   }
-
 }
diff --git a/src/formats/format.ts b/src/formats/format.ts
index 03b0a98c..57504317 100644
--- a/src/formats/format.ts
+++ b/src/formats/format.ts
@@ -26,7 +26,11 @@ export interface FormatParser {
   /** Extract translatable entries from file content. For multi-locale formats, locale scopes extraction. */
   extract(content: string, locale?: string): ExtractedEntry[];
   /** Reconstruct file content with translated entries applied. For multi-locale formats, locale scopes the update. */
-  reconstruct(content: string, entries: TranslatedEntry[], locale?: string): string;
+  reconstruct(
+    content: string,
+    entries: TranslatedEntry[],
+    locale?: string
+  ): string;
   /** Optional: extract context for a specific key from file content */
   extractContext?(content: string, key: string): string | undefined;
 }
diff --git a/src/formats/index.ts b/src/formats/index.ts
index 281ffbb6..04063ad0 100644
--- a/src/formats/index.ts
+++ b/src/formats/index.ts
@@ -68,7 +68,12 @@ export async function createDefaultRegistry(): Promise<FormatRegistry> {
  * the default registry. Adding a parser + registering it automatically
  * surfaces the new format in CLI choices — no parallel arrays to maintain.
  */
-export const SUPPORTED_FORMAT_KEYS: readonly string[] =
-  Object.freeze(buildDefaultRegistry().getFormatKeys());
+export const SUPPORTED_FORMAT_KEYS: readonly string[] = Object.freeze(
+  buildDefaultRegistry().getFormatKeys()
+);
 
-export type { FormatParser, ExtractedEntry, TranslatedEntry } from './format.js';
+export type {
+  FormatParser,
+  ExtractedEntry,
+  TranslatedEntry,
+} from './format.js';
diff --git a/src/formats/ios-strings.ts b/src/formats/ios-strings.ts
index fdb66d7c..bf3fc5bc 100644
--- a/src/formats/ios-strings.ts
+++ b/src/formats/ios-strings.ts
@@ -1,4 +1,8 @@
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 
 const ENTRY_RE = /^\s*"((?:[^"\\]|\\.)*)"\s*=\s*"((?:[^"\\]|\\.)*)"\s*;\s*$/;
 
@@ -44,7 +48,10 @@ export class IosStringsFormatParser implements FormatParser {
             break;
           }
         }
-        const inner = commentBody.replace(/^\/\*/, '').replace(/\*\/$/, '').trim();
+        const inner = commentBody
+          .replace(/^\/\*/, '')
+          .replace(/\*\/$/, '')
+          .trim();
         pendingComment = inner;
         continue;
       }
@@ -97,7 +104,7 @@ export class IosStringsFormatParser implements FormatParser {
           const escapedValue = this.escape(translation);
           const newLine = line.replace(
             /=\s*"(?:[^"\\]|\\.)*"\s*;/,
-            () => `= "${escapedValue}";`,
+            () => `= "${escapedValue}";`
           );
           result.push(newLine);
         } else {
@@ -131,12 +138,30 @@ export class IosStringsFormatParser implements FormatParser {
       if (s[i] === '\\' && i + 1 < s.length) {
         const next = s[i + 1]!;
         switch (next) {
-          case '"': result += '"'; i += 2; break;
-          case '\\': result += '\\'; i += 2; break;
-          case 'n': result += '\n'; i += 2; break;
-          case 't': result += '\t'; i += 2; break;
-          case 'r': result += '\r'; i += 2; break;
-          case '0': result += '\0'; i += 2; break;
+          case '"':
+            result += '"';
+            i += 2;
+            break;
+          case '\\':
+            result += '\\';
+            i += 2;
+            break;
+          case 'n':
+            result += '\n';
+            i += 2;
+            break;
+          case 't':
+            result += '\t';
+            i += 2;
+            break;
+          case 'r':
+            result += '\r';
+            i += 2;
+            break;
+          case '0':
+            result += '\0';
+            i += 2;
+            break;
           case 'U':
           case 'u': {
             const hex = s.slice(i + 2, i + 6);
@@ -167,13 +192,27 @@ export class IosStringsFormatParser implements FormatParser {
     for (let i = 0; i < s.length; i++) {
       const ch = s[i]!;
       switch (ch) {
-        case '"': result += '\\"'; break;
-        case '\\': result += '\\\\'; break;
-        case '\n': result += '\\n'; break;
-        case '\t': result += '\\t'; break;
-        case '\r': result += '\\r'; break;
-        case '\0': result += '\\0'; break;
-        default: result += ch; break;
+        case '"':
+          result += '\\"';
+          break;
+        case '\\':
+          result += '\\\\';
+          break;
+        case '\n':
+          result += '\\n';
+          break;
+        case '\t':
+          result += '\\t';
+          break;
+        case '\r':
+          result += '\\r';
+          break;
+        case '\0':
+          result += '\\0';
+          break;
+        default:
+          result += ch;
+          break;
       }
     }
     return result;
diff --git a/src/formats/json.ts b/src/formats/json.ts
index 54cb9f86..12ee25af 100644
--- a/src/formats/json.ts
+++ b/src/formats/json.ts
@@ -1,4 +1,8 @@
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 import { detectIndent } from './util/detect-indent.js';
 import { Logger } from '../utils/logger.js';
 
@@ -20,7 +24,7 @@ export class JsonFormatParser implements FormatParser {
     if (duplicates.length > 0) {
       Logger.warn(
         `JSON file contains duplicate keys: ${duplicates.join(', ')}. ` +
-        `Only the last value for each key will be used.`,
+          `Only the last value for each key will be used.`
       );
     }
 
@@ -68,7 +72,7 @@ export class JsonFormatParser implements FormatParser {
     obj: Record<string, unknown>,
     prefix: string,
     keys: Set<string>,
-    scopes: Map<string, number>,
+    scopes: Map<string, number>
   ): void {
     for (const prop of Object.keys(obj)) {
       const dotPath = prefix ? `${prefix}.${prop}` : prop;
@@ -79,7 +83,12 @@ export class JsonFormatParser implements FormatParser {
       }
       const val = obj[prop];
       if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
-        this.collectFlatKeys(val as Record<string, unknown>, dotPath, keys, scopes);
+        this.collectFlatKeys(
+          val as Record<string, unknown>,
+          dotPath,
+          keys,
+          scopes
+        );
       }
     }
   }
@@ -93,7 +102,10 @@ export class JsonFormatParser implements FormatParser {
         return [flatKey, ...dotPath.slice(flatKey.length + 1).split('.')];
       }
       if (dotPath.endsWith('.' + flatKey)) {
-        return [...dotPath.slice(0, dotPath.length - flatKey.length - 1).split('.'), flatKey];
+        return [
+          ...dotPath.slice(0, dotPath.length - flatKey.length - 1).split('.'),
+          flatKey,
+        ];
       }
     }
 
@@ -155,7 +167,7 @@ export class JsonFormatParser implements FormatParser {
     obj: unknown,
     prefix: string,
     translations: Map<string, string>,
-    flatKeyInfo: FlatKeyInfo,
+    flatKeyInfo: FlatKeyInfo
   ): void {
     if (Array.isArray(obj)) {
       for (let i = 0; i < obj.length; i++) {
@@ -190,7 +202,11 @@ export class JsonFormatParser implements FormatParser {
     }
   }
 
-  private insertNewKeys(obj: unknown, translations: Map<string, string>, flatKeyInfo: FlatKeyInfo): void {
+  private insertNewKeys(
+    obj: unknown,
+    translations: Map<string, string>,
+    flatKeyInfo: FlatKeyInfo
+  ): void {
     if (typeof obj !== 'object' || obj === null) return;
     for (const [key, value] of translations) {
       if (!this.hasKey(obj, key, flatKeyInfo)) {
@@ -200,7 +216,11 @@ export class JsonFormatParser implements FormatParser {
     }
   }
 
-  private hasKey(obj: unknown, dotPath: string, flatKeyInfo: FlatKeyInfo): boolean {
+  private hasKey(
+    obj: unknown,
+    dotPath: string,
+    flatKeyInfo: FlatKeyInfo
+  ): boolean {
     const parts = this.splitKeyParts(dotPath, flatKeyInfo);
     let current: unknown = obj;
     for (const part of parts) {
@@ -219,7 +239,11 @@ export class JsonFormatParser implements FormatParser {
    * `obj['__proto__'] = v` invokes the prototype setter instead of creating a
    * property, which both loses the translation and mutates Object.prototype.
    */
-  private setOwn(obj: Record<string, unknown>, key: string, value: unknown): void {
+  private setOwn(
+    obj: Record<string, unknown>,
+    key: string,
+    value: unknown
+  ): void {
     Object.defineProperty(obj, key, {
       value,
       writable: true,
@@ -228,7 +252,11 @@ export class JsonFormatParser implements FormatParser {
     });
   }
 
-  private setKeyWithParts(obj: Record<string, unknown>, parts: string[], value: string): void {
+  private setKeyWithParts(
+    obj: Record<string, unknown>,
+    parts: string[],
+    value: string
+  ): void {
     let current: Record<string, unknown> = obj;
     for (let i = 0; i < parts.length - 1; i++) {
       const part = parts[i]!;
@@ -248,7 +276,7 @@ export class JsonFormatParser implements FormatParser {
     obj: unknown,
     prefix: string,
     translations: Map<string, string>,
-    flatKeyInfo: FlatKeyInfo,
+    flatKeyInfo: FlatKeyInfo
   ): void {
     if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) return;
     const record = obj as Record<string, unknown>;
@@ -259,7 +287,11 @@ export class JsonFormatParser implements FormatParser {
         if (!translations.has(key)) {
           delete record[prop];
         }
-      } else if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+      } else if (
+        typeof val === 'object' &&
+        val !== null &&
+        !Array.isArray(val)
+      ) {
         this.removeDeletedKeys(val, key, translations, flatKeyInfo);
         if (Object.keys(val).length === 0) {
           delete record[prop];
diff --git a/src/formats/php-arrays.ts b/src/formats/php-arrays.ts
index f582f5de..113e69a0 100644
--- a/src/formats/php-arrays.ts
+++ b/src/formats/php-arrays.ts
@@ -1,4 +1,8 @@
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 import { ValidationError } from '../utils/errors.js';
 import { Logger } from '../utils/logger.js';
 import { requireModule } from './php-parser-bridge.js';
@@ -122,14 +126,14 @@ export class PhpArraysFormatParser implements FormatParser {
 
     const ast = getEngine().parseCode(clean);
     const returnNode = (ast.children ?? []).find(
-      (c): c is PhpReturn => c.kind === 'return',
+      (c): c is PhpReturn => c.kind === 'return'
     );
     if (!returnNode?.expr) return [];
 
     if (returnNode.expr.kind !== 'array') {
       throw new ValidationError(
         `Laravel PHP file must return an array literal (got '${returnNode.expr.kind}').`,
-        ALLOWLIST_HINT,
+        ALLOWLIST_HINT
       );
     }
 
@@ -138,7 +142,11 @@ export class PhpArraysFormatParser implements FormatParser {
     return entries;
   }
 
-  reconstruct(content: string, entries: TranslatedEntry[], _locale?: string): string {
+  reconstruct(
+    content: string,
+    entries: TranslatedEntry[],
+    _locale?: string
+  ): string {
     if (entries.length === 0) return content;
 
     const hadBom = content.startsWith('\uFEFF');
@@ -146,12 +154,12 @@ export class PhpArraysFormatParser implements FormatParser {
 
     const ast = getEngine().parseCode(body);
     const returnNode = (ast.children ?? []).find(
-      (c): c is PhpReturn => c.kind === 'return',
+      (c): c is PhpReturn => c.kind === 'return'
     );
     if (returnNode?.expr?.kind !== 'array') {
       throw new ValidationError(
         'Cannot reconstruct: file must return an array literal.',
-        ALLOWLIST_HINT,
+        ALLOWLIST_HINT
       );
     }
 
@@ -189,7 +197,11 @@ interface StringLoc {
   readonly isDoubleQuote: boolean;
 }
 
-function collectStringLocs(arr: PhpArray, prefix: string, out: Map<string, StringLoc>): void {
+function collectStringLocs(
+  arr: PhpArray,
+  prefix: string,
+  out: Map<string, StringLoc>
+): void {
   for (const item of arr.items) {
     if (item.kind !== 'entry' || item.key?.kind !== 'string') continue;
     const keyStr = (item.key as PhpString).value;
@@ -239,24 +251,24 @@ function walkArray(
   prefix: string,
   out: ExtractedEntry[],
   depth: number,
-  maxDepth: number,
+  maxDepth: number
 ): void {
   if (depth > maxDepth) {
     throw new PhpArraysCapExceededError(
-      `Laravel PHP: max nesting depth ${maxDepth} exceeded at '${prefix || '<root>'}'.`,
+      `Laravel PHP: max nesting depth ${maxDepth} exceeded at '${prefix || '<root>'}'.`
     );
   }
   for (const item of arr.items) {
     if (item.kind !== 'entry') {
       throw new ValidationError(
         `Unsupported array item kind '${item.kind}' at '${prefix || '<root>'}'.`,
-        ALLOWLIST_HINT,
+        ALLOWLIST_HINT
       );
     }
     if (item.key?.kind !== 'string') {
       throw new ValidationError(
         `Unsupported array key kind '${item.key?.kind ?? 'none'}' at '${prefix || '<root>'}' (string keys required).`,
-        ALLOWLIST_HINT,
+        ALLOWLIST_HINT
       );
     }
     const keyStr = (item.key as PhpString).value;
@@ -268,9 +280,11 @@ function walkArray(
         const stringValue = (val as PhpString).value;
         const entry: ExtractedEntry = { key: dotPath, value: stringValue };
         if (PIPE_PLURALIZATION_REGEX.test(stringValue)) {
-          entry.metadata = { skipped: { reason: SKIP_REASON_PIPE_PLURALIZATION } };
+          entry.metadata = {
+            skipped: { reason: SKIP_REASON_PIPE_PLURALIZATION },
+          };
           Logger.warn(
-            `Laravel PHP: skipping pipe-pluralization value at '${dotPath}' — preserved verbatim, not sent for translation.`,
+            `Laravel PHP: skipping pipe-pluralization value at '${dotPath}' — preserved verbatim, not sent for translation.`
           );
         }
         out.push(entry);
@@ -286,7 +300,7 @@ function walkArray(
       default:
         throw new ValidationError(
           `Unsupported value kind '${val.kind}' at key '${dotPath}'.`,
-          ALLOWLIST_HINT,
+          ALLOWLIST_HINT
         );
     }
   }
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 10d0fd38..fa87dc82 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -1,4 +1,8 @@
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 
 interface PoEntry {
   translatorComments: string[];
@@ -14,11 +18,7 @@ interface PoEntry {
 }
 
 type ParseTarget =
-  | 'msgctxt'
-  | 'msgid'
-  | 'msgid_plural'
-  | 'msgstr'
-  | `msgstr[${number}]`;
+  'msgctxt' | 'msgid' | 'msgid_plural' | 'msgstr' | `msgstr[${number}]`;
 
 function unquote(line: string): string {
   const trimmed = line.trim();
@@ -27,11 +27,16 @@ function unquote(line: string): string {
       .slice(1, -1)
       .replace(/\\(\\|"|n|t)/g, (_match, ch: string) => {
         switch (ch) {
-          case '\\': return '\\';
-          case '"': return '"';
-          case 'n': return '\n';
-          case 't': return '\t';
-          default: return ch;
+          case '\\':
+            return '\\';
+          case '"':
+            return '"';
+          case 'n':
+            return '\n';
+          case 't':
+            return '\t';
+          default:
+            return ch;
         }
       });
   }
@@ -72,7 +77,9 @@ function quoteLong(value: string): string {
 }
 
 function isHeaderEntry(entry: PoEntry): boolean {
-  return entry.msgid === '' && entry.msgstr.length > 0 && entry.msgstr[0] !== '';
+  return (
+    entry.msgid === '' && entry.msgstr.length > 0 && entry.msgstr[0] !== ''
+  );
 }
 
 const CONTEXT_SEPARATOR = '\x04';
@@ -123,7 +130,9 @@ function parseEntries(content: string): PoEntry[] {
       continue;
     }
     if (line.startsWith('# ') || line === '#') {
-      current.translatorComments.push(line.startsWith('# ') ? line.slice(2) : '');
+      current.translatorComments.push(
+        line.startsWith('# ') ? line.slice(2) : ''
+      );
       continue;
     }
     if (line.startsWith('#~ ')) {
@@ -240,7 +249,11 @@ export class PoFormatParser implements FormatParser {
         continue;
       }
 
-      if (pe.msgid === '' && pe.msgstr.length === 0 && pe.msgstrPlural.size === 0) {
+      if (
+        pe.msgid === '' &&
+        pe.msgstr.length === 0 &&
+        pe.msgstrPlural.size === 0
+      ) {
         continue;
       }
 
@@ -429,7 +442,11 @@ export class PoFormatParser implements FormatParser {
       result.splice(commentStart, commentLines.length);
       for (const cl of commentLines) {
         if (/^#,/.test(cl)) {
-          const flags = cl.slice(2).trim().split(/,\s*/).filter(f => f !== 'fuzzy');
+          const flags = cl
+            .slice(2)
+            .trim()
+            .split(/,\s*/)
+            .filter((f) => f !== 'fuzzy');
           if (flags.length > 0) {
             result.push(`#, ${flags.join(', ')}`);
           }
@@ -439,10 +456,8 @@ export class PoFormatParser implements FormatParser {
       }
 
       const translation = translatedEntry.translation;
-      const pluralTranslations =
-        translatedEntry.metadata?.['plural_forms'] as
-          | Record<string, string>
-          | undefined;
+      const pluralTranslations = translatedEntry.metadata?.['plural_forms'] as
+        Record<string, string> | undefined;
 
       let inMsgstr = false;
       let inMsgstrPlural = false;
diff --git a/src/formats/properties.ts b/src/formats/properties.ts
index 6cb4e343..fc77adf2 100644
--- a/src/formats/properties.ts
+++ b/src/formats/properties.ts
@@ -1,4 +1,8 @@
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 import { PendingCommentBuffer } from './pending-comment-buffer.js';
 
 const ENTRY_RE = /^([^=:#!\s][^=:]*?)\s*[=:]\s*(.*)/;
@@ -119,13 +123,34 @@ export class PropertiesFormatParser implements FormatParser {
       if (s[i] === '\\' && i + 1 < s.length) {
         const next = s[i + 1]!;
         switch (next) {
-          case 'n': result += '\n'; i += 2; break;
-          case 't': result += '\t'; i += 2; break;
-          case 'r': result += '\r'; i += 2; break;
-          case '\\': result += '\\'; i += 2; break;
-          case '=': result += '='; i += 2; break;
-          case ':': result += ':'; i += 2; break;
-          case ' ': result += ' '; i += 2; break;
+          case 'n':
+            result += '\n';
+            i += 2;
+            break;
+          case 't':
+            result += '\t';
+            i += 2;
+            break;
+          case 'r':
+            result += '\r';
+            i += 2;
+            break;
+          case '\\':
+            result += '\\';
+            i += 2;
+            break;
+          case '=':
+            result += '=';
+            i += 2;
+            break;
+          case ':':
+            result += ':';
+            i += 2;
+            break;
+          case ' ':
+            result += ' ';
+            i += 2;
+            break;
           case 'u': {
             const hex = s.slice(i + 2, i + 6);
             if (hex.length === 4 && /^[0-9a-fA-F]{4}$/.test(hex)) {
@@ -162,10 +187,18 @@ export class PropertiesFormatParser implements FormatParser {
     let result = leading ? '\\ '.repeat(leading[0].length) : '';
     for (const ch of s.slice(leading ? leading[0].length : 0)) {
       switch (ch) {
-        case '\n': result += '\\n'; break;
-        case '\t': result += '\\t'; break;
-        case '\r': result += '\\r'; break;
-        case '\\': result += '\\\\'; break;
+        case '\n':
+          result += '\\n';
+          break;
+        case '\t':
+          result += '\\t';
+          break;
+        case '\r':
+          result += '\\r';
+          break;
+        case '\\':
+          result += '\\\\';
+          break;
         default: {
           if (ch.codePointAt(0)! > 0x7e) {
             // Emit every UTF-16 code unit: an astral character such as an
diff --git a/src/formats/toml.ts b/src/formats/toml.ts
index 08474a30..677c9d57 100644
--- a/src/formats/toml.ts
+++ b/src/formats/toml.ts
@@ -1,5 +1,9 @@
 import * as TOML from 'smol-toml';
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 import { PendingCommentBuffer } from './pending-comment-buffer.js';
 
 // `[section]` or `[a.b.c]` — captures the path. Matches only at the start of a
@@ -111,12 +115,16 @@ export class TomlFormatParser implements FormatParser {
               if (bodyLine.includes(delimiter)) break;
             }
           }
-          const multilineKey = currentSection ? `${currentSection}.${keyPart}` : keyPart;
+          const multilineKey = currentSection
+            ? `${currentSection}.${keyPart}`
+            : keyPart;
           usedKeys.add(multilineKey);
           continue;
         }
 
-        const fullKey = currentSection ? `${currentSection}.${keyPart}` : keyPart;
+        const fullKey = currentSection
+          ? `${currentSection}.${keyPart}`
+          : keyPart;
         const stringMatch = valuePart.match(STRING_VALUE_RE);
 
         if (stringMatch) {
@@ -127,7 +135,10 @@ export class TomlFormatParser implements FormatParser {
 
           if (translation !== undefined) {
             pending.flushToOutput(out);
-            const newValue = encodeTomlString(translation.translation, useDoubleQuote);
+            const newValue = encodeTomlString(
+              translation.translation,
+              useDoubleQuote
+            );
             out.push(`${indent}${keyPart}${equals}${newValue}${trailing}`);
             usedKeys.add(fullKey);
             continue;
@@ -189,7 +200,10 @@ export class TomlFormatParser implements FormatParser {
     }
 
     // Group by section so each section is touched once.
-    const bySection = new Map<string, { leaf: string; entry: TranslatedEntry }[]>();
+    const bySection = new Map<
+      string,
+      { leaf: string; entry: TranslatedEntry }[]
+    >();
     for (const entry of newEntries) {
       const lastDot = entry.key.lastIndexOf('.');
       const section = lastDot === -1 ? '' : entry.key.slice(0, lastDot);
@@ -206,8 +220,14 @@ export class TomlFormatParser implements FormatParser {
 
     for (const [section, group] of existing) {
       const at = sectionEnd.get(section)!;
-      out.splice(at, 0, ...group.map(({ leaf, entry }) =>
-        `${leaf} = ${encodeTomlString(entry.translation, true)}`));
+      out.splice(
+        at,
+        0,
+        ...group.map(
+          ({ leaf, entry }) =>
+            `${leaf} = ${encodeTomlString(entry.translation, true)}`
+        )
+      );
     }
 
     // Sections not present in the file get appended with a header.
@@ -221,7 +241,11 @@ export class TomlFormatParser implements FormatParser {
     }
   }
 
-  private walk(obj: Record<string, unknown>, prefix: string, entries: ExtractedEntry[]): void {
+  private walk(
+    obj: Record<string, unknown>,
+    prefix: string,
+    entries: ExtractedEntry[]
+  ): void {
     for (const [prop, val] of Object.entries(obj)) {
       const key = prefix ? `${prefix}.${prop}` : prop;
       if (typeof val === 'string') {
diff --git a/src/formats/xcstrings.ts b/src/formats/xcstrings.ts
index 81e019e7..9cca9d3f 100644
--- a/src/formats/xcstrings.ts
+++ b/src/formats/xcstrings.ts
@@ -1,4 +1,8 @@
-import type { FormatParser, ExtractedEntry, TranslatedEntry } from './format.js';
+import type {
+  FormatParser,
+  ExtractedEntry,
+  TranslatedEntry,
+} from './format.js';
 import { detectIndent } from './util/detect-indent.js';
 
 interface StringUnit {
@@ -46,20 +50,26 @@ export class XcstringsFormatParser implements FormatParser {
       entries.push({
         key,
         value: localization.stringUnit.value,
-        ...(def.comment ? { context: def.comment, metadata: { comment: def.comment } } : {}),
+        ...(def.comment
+          ? { context: def.comment, metadata: { comment: def.comment } }
+          : {}),
       });
     }
 
     return entries;
   }
 
-  reconstruct(content: string, entries: TranslatedEntry[], locale?: string): string {
+  reconstruct(
+    content: string,
+    entries: TranslatedEntry[],
+    locale?: string
+  ): string {
     if (!locale) return content;
     const data = JSON.parse(content) as XcstringsFile;
     const hadTrailingNewline = content.endsWith('\n');
 
     for (const entry of entries) {
-      const def = data.strings[entry.key] ??= {} as StringDefinition;
+      const def = (data.strings[entry.key] ??= {} as StringDefinition);
       def.localizations ??= {};
       const existing = def.localizations[locale];
       // Replacing the whole localization discarded plural `variations`, which
@@ -84,5 +94,4 @@ export class XcstringsFormatParser implements FormatParser {
     }
     return result;
   }
-
 }
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index 1201780f..91b6d403 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -1,4 +1,8 @@
-import type { ExtractedEntry, FormatParser, TranslatedEntry } from './format.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  TranslatedEntry,
+} from './format.js';
 import { ValidationError } from '../utils/errors.js';
 import {
   findElement,
@@ -67,18 +71,22 @@ const XML_ENTITY_RE = /&(?:(amp|lt|gt|quot|apos)|#(x[0-9a-fA-F]+|[0-9]+));/g;
  * payloads that carry literal entities.
  */
 function unescapeXml(value: string): string {
-  return value.replace(XML_ENTITY_RE, (match, named: string | undefined, numeric: string | undefined) => {
-    if (named) return NAMED_ENTITIES[named] ?? match;
-    if (numeric) {
-      const code = numeric.startsWith('x') || numeric.startsWith('X')
-        ? parseInt(numeric.slice(1), 16)
-        : parseInt(numeric, 10);
-      return Number.isFinite(code) && code >= 0 && code <= 0x10FFFF
-        ? String.fromCodePoint(code)
-        : match;
+  return value.replace(
+    XML_ENTITY_RE,
+    (match, named: string | undefined, numeric: string | undefined) => {
+      if (named) return NAMED_ENTITIES[named] ?? match;
+      if (numeric) {
+        const code =
+          numeric.startsWith('x') || numeric.startsWith('X')
+            ? parseInt(numeric.slice(1), 16)
+            : parseInt(numeric, 10);
+        return Number.isFinite(code) && code >= 0 && code <= 0x10ffff
+          ? String.fromCodePoint(code)
+          : match;
+      }
+      return match;
     }
-    return match;
-  });
+  );
 }
 
 /**
@@ -96,7 +104,7 @@ function assertNoCdataInTranslatable(content: string): void {
     if (element.inner.includes('<![CDATA[')) {
       throw new ValidationError(
         'XLIFF <source> / <target> elements containing CDATA sections are not supported.',
-        'Inline the literal text without the <![CDATA[...]]> wrapper, or preprocess the file to entity-escape CDATA content before syncing.',
+        'Inline the literal text without the <![CDATA[...]]> wrapper, or preprocess the file to entity-escape CDATA content before syncing.'
       );
     }
   }
@@ -192,7 +200,9 @@ export class XliffFormatParser implements FormatParser {
     for (const element of scanElements(content, TRANS_UNIT_EL)) {
       const source = findElement(element.inner, SOURCE_EL);
       if (!source) continue;
-      entries.push(this.toEntry(element.groups[0]!, source.inner, element.inner));
+      entries.push(
+        this.toEntry(element.groups[0]!, source.inner, element.inner)
+      );
     }
   }
 
@@ -203,11 +213,17 @@ export class XliffFormatParser implements FormatParser {
 
       const source = findElement(segment.inner, SOURCE_EL);
       if (!source) continue;
-      entries.push(this.toEntry(element.groups[0]!, source.inner, element.inner));
+      entries.push(
+        this.toEntry(element.groups[0]!, source.inner, element.inner)
+      );
     }
   }
 
-  private toEntry(id: string, rawSource: string, block: string): ExtractedEntry {
+  private toEntry(
+    id: string,
+    rawSource: string,
+    block: string
+  ): ExtractedEntry {
     const entry: ExtractedEntry = { key: id, value: unescapeXml(rawSource) };
     const note = findElement(block, NOTE_EL);
     if (note) {
@@ -216,16 +232,25 @@ export class XliffFormatParser implements FormatParser {
     return entry;
   }
 
-  private reconstructV12(content: string, translations: Map<string, string>): string {
+  private reconstructV12(
+    content: string,
+    translations: Map<string, string>
+  ): string {
     const result = replaceElements(content, TRANS_UNIT_EL, (element) => {
       const translation = translations.get(element.groups[0]!);
       if (translation === undefined) return '';
-      return rewriteInner(element, applyTarget(element.inner, escapeXml(translation)));
+      return rewriteInner(
+        element,
+        applyTarget(element.inner, escapeXml(translation))
+      );
     });
     return result.replace(/\n{3,}/g, '\n\n');
   }
 
-  private reconstructV2(content: string, translations: Map<string, string>): string {
+  private reconstructV2(
+    content: string,
+    translations: Map<string, string>
+  ): string {
     const result = replaceElements(content, UNIT_EL, (element) => {
       const translation = translations.get(element.groups[0]!);
       if (translation === undefined) return '';
@@ -235,7 +260,10 @@ export class XliffFormatParser implements FormatParser {
 
       const inner =
         element.inner.slice(0, segment.start) +
-        rewriteInner(segment, applyTarget(segment.inner, escapeXml(translation))) +
+        rewriteInner(
+          segment,
+          applyTarget(segment.inner, escapeXml(translation))
+        ) +
         element.inner.slice(segment.end);
       return rewriteInner(element, inner);
     });
diff --git a/src/formats/xml-scan.ts b/src/formats/xml-scan.ts
index b5cc881c..6b553f2c 100644
--- a/src/formats/xml-scan.ts
+++ b/src/formats/xml-scan.ts
@@ -39,7 +39,11 @@ export interface ScannedElement {
   groups: (string | undefined)[];
 }
 
-function matchAt(content: string, index: number, sticky: RegExp): RegExpExecArray | null {
+function matchAt(
+  content: string,
+  index: number,
+  sticky: RegExp
+): RegExpExecArray | null {
   sticky.lastIndex = index;
   return sticky.exec(content);
 }
@@ -57,7 +61,7 @@ function isCloseTagStart(content: string, lt: number): boolean {
 function findClose(
   content: string,
   from: number,
-  close: RegExp,
+  close: RegExp
 ): { index: number; length: number } | undefined {
   let pos = from;
   while (pos < content.length) {
@@ -81,7 +85,7 @@ function findClose(
 function nextElement(
   content: string,
   cursor: number,
-  pattern: ElementPattern,
+  pattern: ElementPattern
 ): ScannedElement | undefined {
   let pos = cursor;
 
@@ -120,7 +124,10 @@ function nextElement(
 }
 
 /** Every non-overlapping element matching `pattern`, in document order. */
-export function scanElements(content: string, pattern: ElementPattern): ScannedElement[] {
+export function scanElements(
+  content: string,
+  pattern: ElementPattern
+): ScannedElement[] {
   const elements: ScannedElement[] = [];
   let cursor = 0;
 
@@ -133,7 +140,10 @@ export function scanElements(content: string, pattern: ElementPattern): ScannedE
 }
 
 /** The first element matching `pattern`, or undefined. */
-export function findElement(content: string, pattern: ElementPattern): ScannedElement | undefined {
+export function findElement(
+  content: string,
+  pattern: ElementPattern
+): ScannedElement | undefined {
   return nextElement(content, 0, pattern);
 }
 
@@ -144,7 +154,7 @@ export function findElement(content: string, pattern: ElementPattern): ScannedEl
 export function replaceElements(
   content: string,
   pattern: ElementPattern,
-  replace: (element: ScannedElement) => string | null,
+  replace: (element: ScannedElement) => string | null
 ): string {
   const elements = scanElements(content, pattern);
   if (elements.length === 0) return content;
@@ -156,7 +166,11 @@ export function replaceElements(
     const replacement = replace(element);
     if (replacement === null) {
       let from = element.start;
-      while (from > copied && (content[from - 1] === ' ' || content[from - 1] === '\t')) from--;
+      while (
+        from > copied &&
+        (content[from - 1] === ' ' || content[from - 1] === '\t')
+      )
+        from--;
       let to = element.end;
       while (to < content.length && WHITESPACE_RE.test(content[to]!)) to++;
       parts.push(content.slice(copied, from));
diff --git a/src/formats/yaml.ts b/src/formats/yaml.ts
index 41f567ea..64810b0a 100644
--- a/src/formats/yaml.ts
+++ b/src/formats/yaml.ts
@@ -1,5 +1,9 @@
 import * as YAML from 'yaml';
-import type { FormatParser, ExtractedEntry, TranslatedEntry } from './format.js';
+import type {
+  FormatParser,
+  ExtractedEntry,
+  TranslatedEntry,
+} from './format.js';
 
 type StringSlot =
   | { path: string[]; value: string; parent: YAML.YAMLMap; pair: YAML.Pair }
@@ -18,7 +22,7 @@ export class YamlFormatParser implements FormatParser {
     const doc = YAML.parseDocument(content);
 
     if (doc.errors.length > 0) {
-      const messages = doc.errors.map(e => e.message).join('; ');
+      const messages = doc.errors.map((e) => e.message).join('; ');
       throw new Error(`YAML parse error: ${messages}`);
     }
 
@@ -30,7 +34,7 @@ export class YamlFormatParser implements FormatParser {
       return [{ key: '', value: doc.contents.value }];
     }
 
-    return this.collectStringSlots(doc).map(slot => ({
+    return this.collectStringSlots(doc).map((slot) => ({
       key: slot.path.join('\0'),
       value: slot.value,
     }));
@@ -86,7 +90,7 @@ export class YamlFormatParser implements FormatParser {
     }
 
     for (const [map, pairs] of mapRemovals) {
-      map.items = map.items.filter(pair => !pairs.has(pair));
+      map.items = map.items.filter((pair) => !pairs.has(pair));
     }
     for (const [seq, indices] of seqRemovals) {
       seq.items = seq.items.filter((_, i) => !indices.has(i));
@@ -141,18 +145,30 @@ export class YamlFormatParser implements FormatParser {
     const visit = (node: unknown, path: string[]): void => {
       if (YAML.isMap(node)) {
         for (const pair of node.items) {
-          const key = String(YAML.isScalar(pair.key) ? pair.key.value : pair.key);
+          const key = String(
+            YAML.isScalar(pair.key) ? pair.key.value : pair.key
+          );
           const childPath = [...path, key];
           const value = pair.value;
           recordAnchor(value);
           if (YAML.isScalar(value) && typeof value.value === 'string') {
-            slots.push({ path: childPath, value: value.value, parent: node, pair });
+            slots.push({
+              path: childPath,
+              value: value.value,
+              parent: node,
+              pair,
+            });
           } else if (YAML.isMap(value) || YAML.isSeq(value)) {
             visit(value, childPath);
           } else if (YAML.isAlias(value)) {
             const resolved = resolveAliasString(value);
             if (resolved !== undefined) {
-              slots.push({ path: childPath, value: resolved, parent: node, pair });
+              slots.push({
+                path: childPath,
+                value: resolved,
+                parent: node,
+                pair,
+              });
             }
           }
         }
@@ -162,13 +178,23 @@ export class YamlFormatParser implements FormatParser {
           const childPath = [...path, String(i)];
           recordAnchor(item);
           if (YAML.isScalar(item) && typeof item.value === 'string') {
-            slots.push({ path: childPath, value: item.value, parent: node, index: i });
+            slots.push({
+              path: childPath,
+              value: item.value,
+              parent: node,
+              index: i,
+            });
           } else if (YAML.isMap(item) || YAML.isSeq(item)) {
             visit(item, childPath);
           } else if (YAML.isAlias(item)) {
             const resolved = resolveAliasString(item);
             if (resolved !== undefined) {
-              slots.push({ path: childPath, value: resolved, parent: node, index: i });
+              slots.push({
+                path: childPath,
+                value: resolved,
+                parent: node,
+                index: i,
+              });
             }
           }
         }
diff --git a/src/services/admin.ts b/src/services/admin.ts
index d459c9c8..dc2403fa 100644
--- a/src/services/admin.ts
+++ b/src/services/admin.ts
@@ -1,5 +1,9 @@
 import { DeepLClient } from '../api/deepl-client.js';
-import { AdminApiKey, AdminUsageOptions, AdminUsageReport } from '../types/index.js';
+import {
+  AdminApiKey,
+  AdminUsageOptions,
+  AdminUsageReport,
+} from '../types/index.js';
 import type { GetApiKeyAndOptions } from '../cli/commands/service-factory.js';
 
 export class AdminService {
@@ -30,7 +34,7 @@ export class AdminService {
   async setApiKeyLimit(
     keyId: string,
     characters: number | null,
-    sttLimit?: number | null,
+    sttLimit?: number | null
   ): Promise<void> {
     if (sttLimit !== undefined && this.getApiKeyAndOptions) {
       const { apiKey, options } = this.getApiKeyAndOptions();
diff --git a/src/services/batch-translation.ts b/src/services/batch-translation.ts
index ae4ac6ab..2dd93a90 100644
--- a/src/services/batch-translation.ts
+++ b/src/services/batch-translation.ts
@@ -9,8 +9,16 @@ import pLimit from 'p-limit';
 import fg from 'fast-glob';
 import { FileTranslationService } from './file-translation.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
-import { TranslationService, MAX_TEXT_BYTES, TRANSLATE_BATCH_SIZE } from './translation.js';
-import { preserveCodeBlocks, preserveVariables, restorePlaceholders } from '../utils/text-preservation.js';
+import {
+  TranslationService,
+  MAX_TEXT_BYTES,
+  TRANSLATE_BATCH_SIZE,
+} from './translation.js';
+import {
+  preserveCodeBlocks,
+  preserveVariables,
+  restorePlaceholders,
+} from '../utils/text-preservation.js';
 import { TranslationOptions } from '../types/index.js';
 import { safeReadFile } from '../utils/safe-read-file.js';
 import { Logger } from '../utils/logger.js';
@@ -75,7 +83,10 @@ export class BatchTranslationService {
 
   constructor(
     fileTranslationService: FileTranslationService,
-    options: { concurrency?: number; translationService?: TranslationService } = {}
+    options: {
+      concurrency?: number;
+      translationService?: TranslationService;
+    } = {}
   ) {
     this.fileTranslationService = fileTranslationService;
     this.translationService = options.translationService ?? null;
@@ -136,7 +147,11 @@ export class BatchTranslationService {
 
     // Report progress for skipped files
     for (const entry of result.skipped) {
-      batchOptions.onProgress?.({ completed, total: totalFiles, current: entry.file });
+      batchOptions.onProgress?.({
+        completed,
+        total: totalFiles,
+        current: entry.file,
+      });
     }
 
     // Batch-translate plain text files
@@ -147,14 +162,16 @@ export class BatchTranslationService {
         batchOptions,
         totalFiles,
         completed,
-        batchOptions.onProgress,
+        batchOptions.onProgress
       );
       result.successful.push(...batchResult.successful);
       result.failed.push(...batchResult.failed);
       result.skipped.push(...batchResult.skipped);
       result.requestRejected ??= batchResult.requestRejected;
       completed +=
-        batchResult.successful.length + batchResult.failed.length + batchResult.skipped.length;
+        batchResult.successful.length +
+        batchResult.failed.length +
+        batchResult.skipped.length;
     }
 
     // Per-file translation for structured/other files
@@ -165,19 +182,30 @@ export class BatchTranslationService {
       // round trip to be told the same thing.
       let requestRejected: unknown;
 
-      const tasks = perFileFiles.map(file =>
+      const tasks = perFileFiles.map((file) =>
         limit(async () => {
           if (batchOptions.abortSignal?.aborted) {
             result.skipped.push({ file, reason: 'Aborted' });
             completed++;
-            batchOptions.onProgress?.({ completed, total: totalFiles, current: file });
+            batchOptions.onProgress?.({
+              completed,
+              total: totalFiles,
+              current: file,
+            });
             return;
           }
 
           if (requestRejected !== undefined) {
-            result.skipped.push({ file, reason: errorMessage(requestRejected) });
+            result.skipped.push({
+              file,
+              reason: errorMessage(requestRejected),
+            });
             completed++;
-            batchOptions.onProgress?.({ completed, total: totalFiles, current: file });
+            batchOptions.onProgress?.({
+              completed,
+              total: totalFiles,
+              current: file,
+            });
             return;
           }
 
@@ -197,7 +225,11 @@ export class BatchTranslationService {
 
             result.successful.push({ file, outputPath });
             completed++;
-            batchOptions.onProgress?.({ completed, total: totalFiles, current: file });
+            batchOptions.onProgress?.({
+              completed,
+              total: totalFiles,
+              current: file,
+            });
           } catch (error) {
             if (isUnrecoverableRequestError(error)) {
               requestRejected = error;
@@ -207,7 +239,11 @@ export class BatchTranslationService {
               error: errorMessage(error),
             });
             completed++;
-            batchOptions.onProgress?.({ completed, total: totalFiles, current: file });
+            batchOptions.onProgress?.({
+              completed,
+              total: totalFiles,
+              current: file,
+            });
           }
         })
       );
@@ -231,7 +267,7 @@ export class BatchTranslationService {
     batchOptions: Partial<BatchOptions>,
     totalFiles: number,
     startCompleted: number,
-    onProgress?: (progress: ProgressInfo) => void,
+    onProgress?: (progress: ProgressInfo) => void
   ): Promise<{
     successful: Array<{ file: string; outputPath: string }>;
     failed: Array<{ file: string; error: string }>;
@@ -269,7 +305,10 @@ export class BatchTranslationService {
         // Never sent, so reported as skipped rather than as individual failures
         // carrying another batch's error.
         for (const entry of batch) {
-          skipped.push({ file: entry.file, reason: errorMessage(requestRejected) });
+          skipped.push({
+            file: entry.file,
+            reason: errorMessage(requestRejected),
+          });
           completed++;
           onProgress?.({ completed, total: totalFiles, current: entry.file });
         }
@@ -284,15 +323,21 @@ export class BatchTranslationService {
         return;
       }
 
-      const texts = batch.map(e => e.processedText);
+      const texts = batch.map((e) => e.processedText);
 
       try {
-        const results = await this.translationService!.translateBatch(texts, translationOptions);
+        const results = await this.translationService!.translateBatch(
+          texts,
+          translationOptions
+        );
 
         if (results.length !== batch.length) {
           // Result count mismatch — mark entire batch as failed
           for (const entry of batch) {
-            failed.push({ file: entry.file, error: 'Batch result count mismatch' });
+            failed.push({
+              file: entry.file,
+              error: 'Batch result count mismatch',
+            });
             completed++;
             onProgress?.({ completed, total: totalFiles, current: entry.file });
           }
@@ -303,7 +348,7 @@ export class BatchTranslationService {
           const entry = batch[i]!;
           const translatedText = restorePlaceholders(
             results[i]!.text,
-            entry.preservationMap,
+            entry.preservationMap
           );
 
           try {
@@ -348,7 +393,10 @@ export class BatchTranslationService {
 
         const byteSize = Buffer.byteLength(content, 'utf8');
         if (byteSize > MAX_TEXT_BYTES) {
-          failed.push({ file, error: `File too large: ${byteSize} bytes exceeds ${MAX_TEXT_BYTES} byte limit` });
+          failed.push({
+            file,
+            error: `File too large: ${byteSize} bytes exceeds ${MAX_TEXT_BYTES} byte limit`,
+          });
           continue;
         }
 
@@ -359,7 +407,7 @@ export class BatchTranslationService {
         const outputPath = this.generateOutputPath(
           file,
           translationOptions.targetLang,
-          batchOptions,
+          batchOptions
         );
 
         entry = { file, outputPath, processedText, preservationMap };
@@ -369,8 +417,11 @@ export class BatchTranslationService {
       }
 
       const entryBytes = formEncodedByteLength(entry.processedText);
-      if (currentBatch.length > 0 &&
-          (currentBatch.length >= TRANSLATE_BATCH_SIZE || currentBytes + entryBytes > MAX_TEXT_BYTES)) {
+      if (
+        currentBatch.length > 0 &&
+        (currentBatch.length >= TRANSLATE_BATCH_SIZE ||
+          currentBytes + entryBytes > MAX_TEXT_BYTES)
+      ) {
         await flushBatch();
       }
 
@@ -403,9 +454,10 @@ export class BatchTranslationService {
     // Build glob pattern
     const pattern = batchOptions.pattern ?? '*';
     const depth = batchOptions.recursive === false ? 1 : undefined;
-    const globPattern = batchOptions.recursive === false
-      ? path.join(inputDir, pattern)
-      : path.join(inputDir, '**', pattern);
+    const globPattern =
+      batchOptions.recursive === false
+        ? path.join(inputDir, pattern)
+        : path.join(inputDir, '**', pattern);
 
     // Find all files
     const files = await fg(globPattern, {
@@ -417,20 +469,16 @@ export class BatchTranslationService {
     });
 
     // Filter to only supported files
-    const supportedFiles = files.filter(file =>
+    const supportedFiles = files.filter((file) =>
       this.fileTranslationService.isSupportedFile(file)
     );
 
     // Translate files with preserved directory structure
-    return this.translateFiles(
-      supportedFiles,
-      translationOptions,
-      {
-        ...batchOptions,
-        outputDir: batchOptions.outputDir ?? inputDir,
-        baseDir: inputDir,
-      }
-    );
+    return this.translateFiles(supportedFiles, translationOptions, {
+      ...batchOptions,
+      outputDir: batchOptions.outputDir ?? inputDir,
+      baseDir: inputDir,
+    });
   }
 
   /**
@@ -438,7 +486,8 @@ export class BatchTranslationService {
    */
   getStatistics(result: BatchResult): BatchStatistics {
     return {
-      total: result.successful.length + result.failed.length + result.skipped.length,
+      total:
+        result.successful.length + result.failed.length + result.skipped.length,
       successful: result.successful.length,
       failed: result.failed.length,
       skipped: result.skipped.length,
@@ -466,7 +515,10 @@ export class BatchTranslationService {
 
       const outputPath = path.resolve(outputDir, outputFilename);
       const resolvedOutputDir = path.resolve(outputDir);
-      if (!outputPath.startsWith(resolvedOutputDir + path.sep) && outputPath !== resolvedOutputDir) {
+      if (
+        !outputPath.startsWith(resolvedOutputDir + path.sep) &&
+        outputPath !== resolvedOutputDir
+      ) {
         throw new ValidationError(
           `Output path "${outputFilename}" escapes output directory "${outputDir}"`
         );
@@ -483,7 +535,10 @@ export class BatchTranslationService {
       const relativeDir = path.dirname(relativePath);
       const outputPath = path.resolve(outputDir, relativeDir, outputFilename);
       const resolvedOutputDir = path.resolve(outputDir);
-      if (!outputPath.startsWith(resolvedOutputDir + path.sep) && outputPath !== resolvedOutputDir) {
+      if (
+        !outputPath.startsWith(resolvedOutputDir + path.sep) &&
+        outputPath !== resolvedOutputDir
+      ) {
         throw new ValidationError(
           `Output path "${path.join(relativeDir, outputFilename)}" escapes output directory "${outputDir}"`
         );
diff --git a/src/services/detect.ts b/src/services/detect.ts
index 00ea31ed..632478fd 100644
--- a/src/services/detect.ts
+++ b/src/services/detect.ts
@@ -17,7 +17,9 @@ export class DetectService {
 
   async detect(text: string): Promise<DetectResult> {
     if (!text || text.trim() === '') {
-      throw new ValidationError('Text cannot be empty. Provide text to detect language.');
+      throw new ValidationError(
+        'Text cannot be empty. Provide text to detect language.'
+      );
     }
 
     const result = await this.client.translate(text, {
@@ -25,7 +27,9 @@ export class DetectService {
     });
 
     if (!result.detectedSourceLang) {
-      throw new ValidationError('Could not detect source language. The text may be too short or ambiguous.');
+      throw new ValidationError(
+        'Could not detect source language. The text may be too short or ambiguous.'
+      );
     }
 
     const langCode = result.detectedSourceLang;
diff --git a/src/services/document-translation.ts b/src/services/document-translation.ts
index 7b694ffc..899a678b 100644
--- a/src/services/document-translation.ts
+++ b/src/services/document-translation.ts
@@ -108,7 +108,7 @@ export class DocumentTranslationService {
       const limitMB = (MAX_DOCUMENT_FILE_SIZE / (1024 * 1024)).toFixed(0);
       throw new ValidationError(
         `File size (${sizeMB} MB) exceeds the maximum allowed size of ${limitMB} MB. ` +
-        `Please check DeepL's document size limits: https://developers.deepl.com/docs/api-reference/document`
+          `Please check DeepL's document size limits: https://developers.deepl.com/docs/api-reference/document`
       );
     }
 
diff --git a/src/services/file-translation.ts b/src/services/file-translation.ts
index 0eb5256f..9810648e 100644
--- a/src/services/file-translation.ts
+++ b/src/services/file-translation.ts
@@ -41,7 +41,8 @@ export class FileTranslationService {
 
   private async getStructuredService(): Promise<StructuredFileTranslationService> {
     if (!this.structuredService) {
-      const { StructuredFileTranslationService: Cls } = await import('./structured-file-translation.js');
+      const { StructuredFileTranslationService: Cls } =
+        await import('./structured-file-translation.js');
       this.structuredService = new Cls(this.translationService);
     }
     return this.structuredService;
@@ -151,14 +152,15 @@ export class FileTranslationService {
     }
 
     // Translate to multiple languages
-    const translationResults = await this.translationService.translateToMultiple(
-      content,
-      targetLangs,
-      options
-    );
+    const translationResults =
+      await this.translationService.translateToMultiple(
+        content,
+        targetLangs,
+        options
+      );
 
     // Convert to FileMultiTargetResult
-    const results: FileMultiTargetResult[] = translationResults.map(r => ({
+    const results: FileMultiTargetResult[] = translationResults.map((r) => ({
       targetLang: r.targetLang,
       text: r.text,
     }));
diff --git a/src/services/git-hooks.ts b/src/services/git-hooks.ts
index 5124cc58..7db9b8a1 100644
--- a/src/services/git-hooks.ts
+++ b/src/services/git-hooks.ts
@@ -57,11 +57,15 @@ export class GitHooksService {
     const workDir = path.dirname(gitDir);
 
     try {
-      const resolved = execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
-        cwd: workDir,
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-      }).trim();
+      const resolved = execFileSync(
+        'git',
+        ['rev-parse', '--git-path', 'hooks'],
+        {
+          cwd: workDir,
+          encoding: 'utf-8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        }
+      ).trim();
       if (resolved) {
         return path.resolve(workDir, resolved);
       }
@@ -72,7 +76,7 @@ export class GitHooksService {
     if (!fs.statSync(gitDir).isDirectory()) {
       throw new ValidationError(
         `Cannot resolve the hooks directory for "${gitDir}": it is a gitdir pointer file and git is not available to resolve it.`,
-        'Install git, or run this command from the repository that owns the worktree.',
+        'Install git, or run this command from the repository that owns the worktree.'
       );
     }
 
@@ -129,7 +133,7 @@ export class GitHooksService {
     }
     throw new ValidationError(
       `Refusing to install: ${MAX_BACKUP_SLOTS} backups of "${path.basename(hookPath)}" already exist.`,
-      `Remove the unneeded ${path.basename(primary)}* files and retry.`,
+      `Remove the unneeded ${path.basename(primary)}* files and retry.`
     );
   }
 
@@ -148,7 +152,9 @@ export class GitHooksService {
     // Verify it's a DeepL hook before removing
     const content = fs.readFileSync(hookPath, 'utf-8');
     if (!this.isDeepLHook(content)) {
-      throw new ValidationError('Hook is not a DeepL CLI hook. Remove it manually if needed.');
+      throw new ValidationError(
+        'Hook is not a DeepL CLI hook. Remove it manually if needed.'
+      );
     }
 
     fs.unlinkSync(hookPath);
@@ -181,7 +187,12 @@ export class GitHooksService {
    * List all hooks and their installation status
    */
   list(): HookStatus {
-    const hooks: HookType[] = ['pre-commit', 'pre-push', 'commit-msg', 'post-commit'];
+    const hooks: HookType[] = [
+      'pre-commit',
+      'pre-push',
+      'commit-msg',
+      'post-commit',
+    ];
     const status: HookStatus = {};
 
     for (const hook of hooks) {
@@ -228,22 +239,46 @@ export class GitHooksService {
     const hookPath = this.getHookPath(hookType);
 
     if (!fs.existsSync(hookPath)) {
-      return { installed: false, markerVersion: null, hashMatch: null, expectedHash: null, actualHash: null };
+      return {
+        installed: false,
+        markerVersion: null,
+        hashMatch: null,
+        expectedHash: null,
+        actualHash: null,
+      };
     }
 
     const content = fs.readFileSync(hookPath, 'utf-8');
 
     if (!this.isDeepLHook(content)) {
-      return { installed: false, markerVersion: null, hashMatch: null, expectedHash: null, actualHash: null };
+      return {
+        installed: false,
+        markerVersion: null,
+        hashMatch: null,
+        expectedHash: null,
+        actualHash: null,
+      };
     }
 
     const markerMatch = content.match(MARKER_PATTERN);
 
     if (!markerMatch) {
       if (content.includes(LEGACY_MARKER)) {
-        return { installed: true, markerVersion: 'legacy', hashMatch: null, expectedHash: null, actualHash: null };
+        return {
+          installed: true,
+          markerVersion: 'legacy',
+          hashMatch: null,
+          expectedHash: null,
+          actualHash: null,
+        };
       }
-      return { installed: false, markerVersion: null, hashMatch: null, expectedHash: null, actualHash: null };
+      return {
+        installed: false,
+        markerVersion: null,
+        hashMatch: null,
+        expectedHash: null,
+        actualHash: null,
+      };
     }
 
     const expectedHash = markerMatch[2]!;
@@ -272,7 +307,7 @@ export class GitHooksService {
   static extractHookBody(content: string): string {
     const lines = content.split('\n');
     const markerIndex = lines.findIndex(
-      line => MARKER_PATTERN.test(line) || line === LEGACY_MARKER
+      (line) => MARKER_PATTERN.test(line) || line === LEGACY_MARKER
     );
     if (markerIndex === -1) {
       return content;
@@ -299,7 +334,9 @@ export class GitHooksService {
 `;
 
     if (hookType === 'pre-commit') {
-      return commonPreamble + `# Pre-commit hook for DeepL CLI
+      return (
+        commonPreamble +
+        `# Pre-commit hook for DeepL CLI
 # Validates translations before committing
 
 # Check if deepl CLI is available
@@ -323,9 +360,12 @@ fi
 
 echo "✓ Translation validation passed"
 exit 0
-`;
+`
+      );
     } else if (hookType === 'pre-push') {
-      return commonPreamble + `# Pre-push hook for DeepL CLI
+      return (
+        commonPreamble +
+        `# Pre-push hook for DeepL CLI
 # Validates all translations before pushing
 
 echo "🔍 Validating all translations before push..."
@@ -345,9 +385,12 @@ fi
 
 echo "✓ Translation validation passed"
 exit 0
-`;
+`
+      );
     } else if (hookType === 'commit-msg') {
-      return commonPreamble + `# Commit message hook for DeepL CLI
+      return (
+        commonPreamble +
+        `# Commit message hook for DeepL CLI
 # Validates commit messages follow Conventional Commits format
 
 COMMIT_MSG_FILE=$1
@@ -369,9 +412,12 @@ npx --no -- commitlint --edit "$COMMIT_MSG_FILE"
 
 # Exit with commitlint's exit code
 exit $?
-`;
+`
+      );
     } else if (hookType === 'post-commit') {
-      return commonPreamble + `# Post-commit hook for DeepL CLI
+      return (
+        commonPreamble +
+        `# Post-commit hook for DeepL CLI
 # Provides feedback and automation after successful commits
 
 # Get the commit message and hash
@@ -414,11 +460,19 @@ if [ "$COMMIT_TYPE" = "feat" ] || [ "$COMMIT_TYPE" = "fix" ]; then
 fi
 
 exit 0
-`;
+`
+      );
     }
 
-    const validTypes: HookType[] = ['pre-commit', 'pre-push', 'commit-msg', 'post-commit'];
-    throw new ValidationError(`Invalid hook type: ${hookType}. Must be one of: ${validTypes.join(', ')}`);
+    const validTypes: HookType[] = [
+      'pre-commit',
+      'pre-push',
+      'commit-msg',
+      'post-commit',
+    ];
+    throw new ValidationError(
+      `Invalid hook type: ${hookType}. Must be one of: ${validTypes.join(', ')}`
+    );
   }
 
   /**
@@ -432,9 +486,16 @@ exit 0
    * Validate hook type
    */
   private validateHookType(hookType: string): asserts hookType is HookType {
-    const validTypes: HookType[] = ['pre-commit', 'pre-push', 'commit-msg', 'post-commit'];
+    const validTypes: HookType[] = [
+      'pre-commit',
+      'pre-push',
+      'commit-msg',
+      'post-commit',
+    ];
     if (!validTypes.includes(hookType as HookType)) {
-      throw new ValidationError(`Invalid hook type: ${hookType}. Must be one of: ${validTypes.join(', ')}`);
+      throw new ValidationError(
+        `Invalid hook type: ${hookType}. Must be one of: ${validTypes.join(', ')}`
+      );
     }
   }
 }
diff --git a/src/services/glossary.ts b/src/services/glossary.ts
index 5f98940d..528af06d 100644
--- a/src/services/glossary.ts
+++ b/src/services/glossary.ts
@@ -4,7 +4,12 @@
  */
 
 import { DeepLClient } from '../api/deepl-client.js';
-import { GlossaryInfo, GlossaryLanguagePair, Language, isMultilingual } from '../types/index.js';
+import {
+  GlossaryInfo,
+  GlossaryLanguagePair,
+  Language,
+  isMultilingual,
+} from '../types/index.js';
 import { Logger } from '../utils/logger.js';
 import { baseLanguage } from '../data/language-registry.js';
 import { ValidationError, ConfigError } from '../utils/errors.js';
@@ -47,7 +52,7 @@ function assertNoSeparatorChars(label: string, text: string): void {
   if (found) {
     throw new ValidationError(
       `${label} cannot contain a ${found} character`,
-      'Glossary entries are stored as tab-separated rows; split the term into separate entries instead.',
+      'Glossary entries are stored as tab-separated rows; split the term into separate entries instead.'
     );
   }
 }
@@ -102,7 +107,12 @@ export class GlossaryService {
     const tsv = GlossaryService.entriesToTSV(entries);
 
     // Create glossary via API
-    const result = await this.client.createGlossary(name, sourceLang, targetLangs, tsv);
+    const result = await this.client.createGlossary(
+      name,
+      sourceLang,
+      targetLangs,
+      tsv
+    );
     this.invalidateResolutionCache();
     return result;
   }
@@ -128,7 +138,12 @@ export class GlossaryService {
       throw new ValidationError('Glossary entries cannot be empty');
     }
 
-    const result = await this.client.createGlossary(name, sourceLang, targetLangs, tsv);
+    const result = await this.client.createGlossary(
+      name,
+      sourceLang,
+      targetLangs,
+      tsv
+    );
     this.invalidateResolutionCache();
     return result;
   }
@@ -152,11 +167,13 @@ export class GlossaryService {
    */
   async getGlossaryByName(name: string): Promise<GlossaryInfo | null> {
     const glossaries = await this.getCachedGlossaryList();
-    const match = glossaries.find(g => g.name === name) ?? null;
+    const match = glossaries.find((g) => g.name === name) ?? null;
     // List normalization suppresses this warning for unrelated glossaries;
     // surface it here only for the glossary actually being operated on.
     if (match?.dictionaries.length === 0) {
-      Logger.warn('Glossary has empty dictionaries; defaulting source language to "en"');
+      Logger.warn(
+        'Glossary has empty dictionaries; defaulting source language to "en"'
+      );
     }
     return match;
   }
@@ -181,31 +198,39 @@ export class GlossaryService {
    */
   async resolveGlossaryId(
     nameOrId: string,
-    expected?: { from: Language; targets: Language[] },
+    expected?: { from: Language; targets: Language[] }
   ): Promise<string> {
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(nameOrId)) {
+    if (
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+        nameOrId
+      )
+    ) {
       return nameOrId;
     }
     const cacheKey = expected
-      ? `${nameOrId}|${expected.from.toLowerCase()}|${expected.targets.map(t => t.toLowerCase()).join(',')}`
+      ? `${nameOrId}|${expected.from.toLowerCase()}|${expected.targets.map((t) => t.toLowerCase()).join(',')}`
       : nameOrId;
     const cached = this.resolutionCache.get(cacheKey);
     if (cached !== undefined) {
-      Logger.verbose(`[verbose] Glossary cache hit: "${nameOrId}" -> ${cached}`);
+      Logger.verbose(
+        `[verbose] Glossary cache hit: "${nameOrId}" -> ${cached}`
+      );
       return cached;
     }
     const glossaries = await this.getCachedGlossaryList();
-    const candidates = glossaries.filter(g => !hasSuspiciousChars(g.name));
-    const matches = candidates.filter(g => g.name === nameOrId);
+    const candidates = glossaries.filter((g) => !hasSuspiciousChars(g.name));
+    const matches = candidates.filter((g) => g.name === nameOrId);
     if (matches.length > 1) {
       throw new ConfigError(
         `Multiple glossaries share the name "${sanitizeForError(nameOrId)}"`,
-        'Pass the UUID directly to disambiguate.',
+        'Pass the UUID directly to disambiguate.'
       );
     }
     const match = matches[0];
     if (!match) {
-      throw new ConfigError(`Glossary "${sanitizeForError(nameOrId)}" not found`);
+      throw new ConfigError(
+        `Glossary "${sanitizeForError(nameOrId)}" not found`
+      );
     }
 
     // An empty dictionary list says nothing about coverage, so leave the
@@ -219,16 +244,19 @@ export class GlossaryService {
       // let a `pt-br` dictionary satisfy `pt-pt`, a different pair.
       const matches = (dictionaryLang: string, requested: string): boolean => {
         const dictionary = dictionaryLang.toLowerCase();
-        return dictionary === requested.toLowerCase() || dictionary === baseLanguage(requested);
+        return (
+          dictionary === requested.toLowerCase() ||
+          dictionary === baseLanguage(requested)
+        );
       };
       const covered = (target: string): boolean =>
         match.dictionaries.some(
-          d => matches(d.source_lang, from) && matches(d.target_lang, target),
+          (d) => matches(d.source_lang, from) && matches(d.target_lang, target)
         );
-      const missing = expected.targets.filter(target => !covered(target));
+      const missing = expected.targets.filter((target) => !covered(target));
       if (missing.length > 0) {
         const allPairs = match.dictionaries.map(
-          d => `${d.source_lang.toLowerCase()}→${d.target_lang.toLowerCase()}`,
+          (d) => `${d.source_lang.toLowerCase()}→${d.target_lang.toLowerCase()}`
         );
         // A multilingual glossary can hold dozens of dictionaries; the whole
         // cross-product on one line stops being a suggestion.
@@ -238,13 +266,15 @@ export class GlossaryService {
             : allPairs.join(', ');
         throw new ConfigError(
           `Glossary "${sanitizeForError(nameOrId)}" does not support the requested language pair`,
-          `Glossary covers ${pairs}; requested ${from}→${missing.map(t => t.toLowerCase()).join(',')}.`,
+          `Glossary covers ${pairs}; requested ${from}→${missing.map((t) => t.toLowerCase()).join(',')}.`
         );
       }
     }
 
     this.resolutionCache.set(cacheKey, match.glossary_id);
-    Logger.verbose(`[verbose] Resolved glossary "${nameOrId}" -> ${match.glossary_id}`);
+    Logger.verbose(
+      `[verbose] Resolved glossary "${nameOrId}" -> ${match.glossary_id}`
+    );
     return match.glossary_id;
   }
 
@@ -264,7 +294,11 @@ export class GlossaryService {
     sourceLang: Language,
     targetLang: Language
   ): Promise<Record<string, string>> {
-    const tsv = await this.client.getGlossaryEntries(glossaryId, sourceLang, targetLang);
+    const tsv = await this.client.getGlossaryEntries(
+      glossaryId,
+      sourceLang,
+      targetLang
+    );
     return GlossaryService.tsvToEntries(tsv);
   }
 
@@ -295,7 +329,9 @@ export class GlossaryService {
     assertNoSeparatorChars('Target text', targetText);
     await this.mutateEntries(glossaryId, sourceLang, targetLang, (entries) => {
       if (entries[sourceText] !== undefined) {
-        throw new ValidationError(`Entry "${sourceText}" already exists in glossary`);
+        throw new ValidationError(
+          `Entry "${sourceText}" already exists in glossary`
+        );
       }
       entries[sourceText] = targetText;
     });
@@ -344,7 +380,9 @@ export class GlossaryService {
         throw new ConfigError(`Entry "${sourceText}" not found in glossary`);
       }
       if (Object.keys(entries).length === 1) {
-        throw new ValidationError('Cannot remove last entry from glossary. Delete the glossary instead.');
+        throw new ValidationError(
+          'Cannot remove last entry from glossary. Delete the glossary instead.'
+        );
       }
       delete entries[sourceText];
     });
@@ -356,10 +394,19 @@ export class GlossaryService {
     targetLang: Language,
     mutate: (entries: Record<string, string>) => void
   ): Promise<void> {
-    const entries = await this.getGlossaryEntries(glossaryId, sourceLang, targetLang);
+    const entries = await this.getGlossaryEntries(
+      glossaryId,
+      sourceLang,
+      targetLang
+    );
     mutate(entries);
     const tsv = GlossaryService.entriesToTSV(entries);
-    await this.client.updateGlossaryEntries(glossaryId, sourceLang, targetLang, tsv);
+    await this.client.updateGlossaryEntries(
+      glossaryId,
+      sourceLang,
+      targetLang,
+      tsv
+    );
   }
 
   /**
@@ -377,18 +424,25 @@ export class GlossaryService {
       }>;
     }
   ): Promise<void> {
-    if (options.name !== undefined && (!options.name || options.name.trim() === '')) {
+    if (
+      options.name !== undefined &&
+      (!options.name || options.name.trim() === '')
+    ) {
       throw new ValidationError('New glossary name cannot be empty');
     }
 
     if (!options.name && !options.dictionaries) {
-      throw new ValidationError('At least one of name or dictionaries must be provided');
+      throw new ValidationError(
+        'At least one of name or dictionaries must be provided'
+      );
     }
 
     if (options.name) {
       const glossary = await this.client.getGlossary(glossaryId);
       if (glossary.name === options.name) {
-        throw new ValidationError('New name must be different from current name');
+        throw new ValidationError(
+          'New name must be different from current name'
+        );
       }
     }
 
@@ -407,7 +461,7 @@ export class GlossaryService {
     }
 
     if (options.dictionaries) {
-      updates.dictionaries = options.dictionaries.map(dict => ({
+      updates.dictionaries = options.dictionaries.map((dict) => ({
         source_lang: dict.sourceLang.toUpperCase(),
         target_lang: dict.targetLang.toUpperCase(),
         entries: GlossaryService.entriesToTSV(dict.entries),
@@ -424,10 +478,7 @@ export class GlossaryService {
   /**
    * Rename a glossary (v3 API - uses PATCH endpoint)
    */
-  async renameGlossary(
-    glossaryId: string,
-    newName: string
-  ): Promise<void> {
+  async renameGlossary(glossaryId: string, newName: string): Promise<void> {
     return this.updateGlossary(glossaryId, { name: newName });
   }
 
@@ -447,7 +498,12 @@ export class GlossaryService {
     }
 
     const tsv = GlossaryService.entriesToTSV(entries);
-    await this.client.replaceGlossaryDictionary(glossaryId, sourceLang, targetLang, tsv);
+    await this.client.replaceGlossaryDictionary(
+      glossaryId,
+      sourceLang,
+      targetLang,
+      tsv
+    );
   }
 
   /**
@@ -464,26 +520,37 @@ export class GlossaryService {
 
     // Check if glossary has multiple dictionaries
     if (!isMultilingual(glossary)) {
-      throw new ValidationError('Cannot delete dictionary from single-language glossary. Delete the entire glossary instead.');
+      throw new ValidationError(
+        'Cannot delete dictionary from single-language glossary. Delete the entire glossary instead.'
+      );
     }
 
     // Check if this would be the last dictionary
     if (glossary.dictionaries.length === 1) {
-      throw new ValidationError('Cannot delete last dictionary from glossary. Delete the entire glossary instead.');
+      throw new ValidationError(
+        'Cannot delete last dictionary from glossary. Delete the entire glossary instead.'
+      );
     }
 
     // Validate the dictionary exists
     const dictionaryExists = glossary.dictionaries.some(
-      dict => dict.source_lang.toUpperCase() === sourceLang.toUpperCase() &&
-              dict.target_lang.toUpperCase() === targetLang.toUpperCase()
+      (dict) =>
+        dict.source_lang.toUpperCase() === sourceLang.toUpperCase() &&
+        dict.target_lang.toUpperCase() === targetLang.toUpperCase()
     );
 
     if (!dictionaryExists) {
-      throw new ValidationError(`Dictionary ${sourceLang}-${targetLang} not found in glossary`);
+      throw new ValidationError(
+        `Dictionary ${sourceLang}-${targetLang} not found in glossary`
+      );
     }
 
     // Delete the dictionary using v3 DELETE endpoint
-    await this.client.deleteGlossaryDictionary(glossaryId, sourceLang, targetLang);
+    await this.client.deleteGlossaryDictionary(
+      glossaryId,
+      sourceLang,
+      targetLang
+    );
   }
 
   /**
@@ -504,18 +571,22 @@ export class GlossaryService {
     // "__proto__", which on a plain object would read as an existing entry
     // (false duplicate warning) or, for __proto__, be swallowed by the
     // prototype setter instead of stored.
-    const entries: Record<string, string> = Object.create(null) as Record<string, string>;
+    const entries: Record<string, string> = Object.create(null) as Record<
+      string,
+      string
+    >;
 
     // Remove UTF-8 BOM if present (0xFEFF)
     let content = tsv;
-    if (content.charCodeAt(0) === 0xFEFF) {
+    if (content.charCodeAt(0) === 0xfeff) {
       content = content.slice(1);
     }
 
     const lines = content.split('\n');
     // Pick the dialect once for the whole file. Sniffing per line tab-splits a
     // quoted CSV field that happens to contain a tab into garbage columns.
-    const firstDataLine = lines.map(line => line.trim()).find(line => line !== '') ?? '';
+    const firstDataLine =
+      lines.map((line) => line.trim()).find((line) => line !== '') ?? '';
     const isTabSeparated = firstDataLine.includes('\t');
     let lineNumber = 0;
 
@@ -537,19 +608,25 @@ export class GlossaryService {
         parts = GlossaryService.parseCsvLine(trimmed);
       } else {
         // Line has no separator - skip it
-        Logger.warn(`Line ${lineNumber}: No tab or comma separator found, skipping`);
+        Logger.warn(
+          `Line ${lineNumber}: No tab or comma separator found, skipping`
+        );
         continue;
       }
 
       // Validate we have at least 2 columns
       if (parts.length < 2) {
-        Logger.warn(`Line ${lineNumber}: Expected 2 columns, found ${parts.length}, skipping`);
+        Logger.warn(
+          `Line ${lineNumber}: Expected 2 columns, found ${parts.length}, skipping`
+        );
         continue;
       }
 
       // Warn if more than 2 columns (extra data will be ignored)
       if (parts.length > 2) {
-        Logger.warn(`Line ${lineNumber}: Found ${parts.length} columns, expected 2. Using first 2 columns.`);
+        Logger.warn(
+          `Line ${lineNumber}: Found ${parts.length} columns, expected 2. Using first 2 columns.`
+        );
       }
 
       const source = parts[0]?.trim();
@@ -565,13 +642,17 @@ export class GlossaryService {
       // cannot represent; keeping it would corrupt every following entry.
       const separator = findSeparatorChar(source) ?? findSeparatorChar(target);
       if (separator) {
-        Logger.warn(`Line ${lineNumber}: Source or target contains a ${separator} character, skipping`);
+        Logger.warn(
+          `Line ${lineNumber}: Source or target contains a ${separator} character, skipping`
+        );
         continue;
       }
 
       // Add to entries (duplicates will overwrite earlier entries)
       if (Object.hasOwn(entries, source)) {
-        Logger.warn(`Line ${lineNumber}: Duplicate source "${source}", overwriting previous entry`);
+        Logger.warn(
+          `Line ${lineNumber}: Duplicate source "${source}", overwriting previous entry`
+        );
       }
 
       entries[source] = target;
diff --git a/src/services/languages.ts b/src/services/languages.ts
index 8efe8866..3dbc3172 100644
--- a/src/services/languages.ts
+++ b/src/services/languages.ts
@@ -7,7 +7,9 @@ export class LanguagesService {
     this.client = client;
   }
 
-  async getSupportedLanguages(type: 'source' | 'target'): Promise<LanguageInfo[]> {
+  async getSupportedLanguages(
+    type: 'source' | 'target'
+  ): Promise<LanguageInfo[]> {
     if (!this.client) {
       return [];
     }
diff --git a/src/services/structured-file-translation.ts b/src/services/structured-file-translation.ts
index 2424c292..632f4df5 100644
--- a/src/services/structured-file-translation.ts
+++ b/src/services/structured-file-translation.ts
@@ -11,7 +11,10 @@ import { TranslationService, MAX_TEXT_BYTES } from './translation.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { TranslationOptions, Language } from '../types/index.js';
 import { safeReadFile } from '../utils/safe-read-file.js';
-import { mapWithConcurrency, MULTI_TARGET_CONCURRENCY } from '../utils/concurrency.js';
+import {
+  mapWithConcurrency,
+  MULTI_TARGET_CONCURRENCY,
+} from '../utils/concurrency.js';
 import { ValidationError, NetworkError } from '../utils/errors.js';
 
 interface FileTranslationOptions {
@@ -70,7 +73,7 @@ export class StructuredFileTranslationService {
 
     if (strings.length > 0) {
       const translations = await this.translateStringsInBatches(
-        strings.map(s => s.value),
+        strings.map((s) => s.value),
         options
       );
 
@@ -91,7 +94,9 @@ export class StructuredFileTranslationService {
   async translateFileToMultiple(
     inputPath: string,
     targetLangs: Language[],
-    options: Omit<TranslationOptions, 'targetLang'> & { outputDir?: string } = {}
+    options: Omit<TranslationOptions, 'targetLang'> & {
+      outputDir?: string;
+    } = {}
   ): Promise<FileMultiTargetResult[]> {
     const content = await this.readFile(inputPath);
 
@@ -104,7 +109,7 @@ export class StructuredFileTranslationService {
     // Parse once to extract strings (read-only, shared across all languages)
     const referenceParsed = this.parseFile(content, ext);
     const strings = this.extractStrings(referenceParsed.data);
-    const stringValues = strings.map(s => s.value);
+    const stringValues = strings.map((s) => s.value);
 
     // Create output directory once before fan-out to avoid races
     if (options.outputDir) {
@@ -318,11 +323,14 @@ export class StructuredFileTranslationService {
       const strBytes = Buffer.byteLength(str, 'utf-8');
 
       if (batch.length > 0 && batchBytes + strBytes > MAX_TEXT_BYTES) {
-        const batchResults = await this.translationService.translateBatch(batch, options);
+        const batchResults = await this.translationService.translateBatch(
+          batch,
+          options
+        );
         if (batchResults.length !== batch.length) {
           throw new NetworkError(
             `Translation batch failed: expected ${batch.length} results but got ${batchResults.length}. ` +
-            'Aborting to prevent misaligned output.'
+              'Aborting to prevent misaligned output.'
           );
         }
         for (const r of batchResults) {
@@ -337,11 +345,14 @@ export class StructuredFileTranslationService {
     }
 
     if (batch.length > 0) {
-      const batchResults = await this.translationService.translateBatch(batch, options);
+      const batchResults = await this.translationService.translateBatch(
+        batch,
+        options
+      );
       if (batchResults.length !== batch.length) {
         throw new NetworkError(
           `Translation batch failed: expected ${batch.length} results but got ${batchResults.length}. ` +
-          'Aborting to prevent misaligned output.'
+            'Aborting to prevent misaligned output.'
         );
       }
       for (const r of batchResults) {
diff --git a/src/services/style-rules.ts b/src/services/style-rules.ts
index c6f4b254..53bb486b 100644
--- a/src/services/style-rules.ts
+++ b/src/services/style-rules.ts
@@ -18,7 +18,9 @@ export class StyleRulesService {
     this.client = client;
   }
 
-  async getStyleRules(options: StyleRulesListOptions = {}): Promise<(StyleRule | StyleRuleDetailed)[]> {
+  async getStyleRules(
+    options: StyleRulesListOptions = {}
+  ): Promise<(StyleRule | StyleRuleDetailed)[]> {
     return this.client.getStyleRules(options);
   }
 
@@ -26,11 +28,17 @@ export class StyleRulesService {
     return this.client.createStyleRule(options);
   }
 
-  async getStyleRule(styleId: string, detailed = false): Promise<StyleRule | StyleRuleDetailed> {
+  async getStyleRule(
+    styleId: string,
+    detailed = false
+  ): Promise<StyleRule | StyleRuleDetailed> {
     return this.client.getStyleRule(styleId, detailed);
   }
 
-  async updateStyleRule(styleId: string, options: UpdateStyleRuleOptions): Promise<StyleRule> {
+  async updateStyleRule(
+    styleId: string,
+    options: UpdateStyleRuleOptions
+  ): Promise<StyleRule> {
     return this.client.updateStyleRule(styleId, options);
   }
 
@@ -38,25 +46,31 @@ export class StyleRulesService {
     return this.client.deleteStyleRule(styleId);
   }
 
-  async replaceConfiguredRules(styleId: string, rules: ConfiguredRules): Promise<StyleRuleDetailed> {
+  async replaceConfiguredRules(
+    styleId: string,
+    rules: ConfiguredRules
+  ): Promise<StyleRuleDetailed> {
     return this.client.replaceConfiguredRules(styleId, rules);
   }
 
   async createCustomInstruction(
     styleId: string,
-    options: CreateCustomInstructionOptions,
+    options: CreateCustomInstructionOptions
   ): Promise<CustomInstruction> {
     return this.client.createCustomInstruction(styleId, options);
   }
 
-  async getCustomInstruction(styleId: string, label: string): Promise<CustomInstruction> {
+  async getCustomInstruction(
+    styleId: string,
+    label: string
+  ): Promise<CustomInstruction> {
     return this.client.getCustomInstruction(styleId, label);
   }
 
   async updateCustomInstruction(
     styleId: string,
     label: string,
-    options: UpdateCustomInstructionOptions,
+    options: UpdateCustomInstructionOptions
   ): Promise<CustomInstruction> {
     return this.client.updateCustomInstruction(styleId, label, options);
   }
diff --git a/src/services/translation-memory.ts b/src/services/translation-memory.ts
index 98e57a5b..409de988 100644
--- a/src/services/translation-memory.ts
+++ b/src/services/translation-memory.ts
@@ -32,52 +32,56 @@ export async function resolveTranslationMemoryId(
   client: TranslationMemoryLister,
   nameOrId: string,
   cache: TmCacheLike,
-  expected?: { from: Language; targets: Language[] },
+  expected?: { from: Language; targets: Language[] }
 ): Promise<string> {
   if (UUID_RE.test(nameOrId)) return nameOrId;
 
   const cacheKey = expected
-    ? `${nameOrId}|${expected.from.toLowerCase()}|${expected.targets.map(t => t.toLowerCase()).join(',')}`
+    ? `${nameOrId}|${expected.from.toLowerCase()}|${expected.targets.map((t) => t.toLowerCase()).join(',')}`
     : nameOrId;
   if (cache.has(cacheKey)) {
     const cached = cache.get(cacheKey)!;
-    Logger.verbose(`[verbose] Translation memory cache hit: "${nameOrId}" -> ${cached}`);
+    Logger.verbose(
+      `[verbose] Translation memory cache hit: "${nameOrId}" -> ${cached}`
+    );
     return cached;
   }
 
   const list = await client.listTranslationMemories();
-  const candidates = list.filter(tm => !hasSuspiciousChars(tm.name));
-  const matches = candidates.filter(tm => tm.name === nameOrId);
+  const candidates = list.filter((tm) => !hasSuspiciousChars(tm.name));
+  const matches = candidates.filter((tm) => tm.name === nameOrId);
   if (matches.length > 1) {
     throw new ConfigError(
       `Multiple translation memories share the name "${sanitizeForError(nameOrId)}"`,
-      'Pass the UUID directly to disambiguate.',
+      'Pass the UUID directly to disambiguate.'
     );
   }
   const match = matches[0];
   if (!match) {
     throw new ConfigError(
       `Translation memory "${sanitizeForError(nameOrId)}" not found`,
-      'Pass the UUID directly, or check your translation memories on the DeepL dashboard.',
+      'Pass the UUID directly, or check your translation memories on the DeepL dashboard.'
     );
   }
 
   if (expected) {
     const tmFrom = match.source_language.toLowerCase();
-    const tmTargets = match.target_languages.map(t => t.toLowerCase());
+    const tmTargets = match.target_languages.map((t) => t.toLowerCase());
     const expectedFrom = expected.from.toLowerCase();
     const mismatch =
       tmFrom !== expectedFrom ||
-      expected.targets.some(t => !tmTargets.includes(t.toLowerCase()));
+      expected.targets.some((t) => !tmTargets.includes(t.toLowerCase()));
     if (mismatch) {
       throw new ConfigError(
         `Translation memory "${sanitizeForError(nameOrId)}" does not support the requested language pair`,
-        `TM is ${match.source_language}\u2192${match.target_languages.join(',')}; requested ${expected.from}\u2192${expected.targets.join(',')}.`,
+        `TM is ${match.source_language}\u2192${match.target_languages.join(',')}; requested ${expected.from}\u2192${expected.targets.join(',')}.`
       );
     }
   }
 
   cache.set(cacheKey, match.translation_memory_id);
-  Logger.verbose(`[verbose] Resolved translation memory "${nameOrId}" -> ${match.translation_memory_id}`);
+  Logger.verbose(
+    `[verbose] Resolved translation memory "${nameOrId}" -> ${match.translation_memory_id}`
+  );
   return match.translation_memory_id;
 }
diff --git a/src/services/translation.ts b/src/services/translation.ts
index cde7e2a9..5fc06141 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -4,17 +4,34 @@
  */
 
 import * as crypto from 'crypto';
-import { DeepLClient, TranslationResult, isTranslationResult, UsageInfo, LanguageInfo } from '../api/deepl-client.js';
+import {
+  DeepLClient,
+  TranslationResult,
+  isTranslationResult,
+  UsageInfo,
+  LanguageInfo,
+} from '../api/deepl-client.js';
 import { ConfigService } from '../storage/config.js';
 import type { CacheService } from '../storage/cache.js';
-import { TranslationOptions, Language, TranslationMemory } from '../types/index.js';
+import {
+  TranslationOptions,
+  Language,
+  TranslationMemory,
+} from '../types/index.js';
 import { Logger } from '../utils/logger.js';
-import { mapWithConcurrency, MULTI_TARGET_CONCURRENCY } from '../utils/concurrency.js';
+import {
+  mapWithConcurrency,
+  MULTI_TARGET_CONCURRENCY,
+} from '../utils/concurrency.js';
 import { ValidationError } from '../utils/errors.js';
 import { errorMessage } from '../utils/error-message.js';
 import { resolveGlossaryWireParams } from '../utils/glossary-params.js';
 import { resolveTagHandlingVersion } from '../utils/tag-handling-version.js';
-import { preserveCodeBlocks, preserveVariables, restorePlaceholders } from '../utils/text-preservation.js';
+import {
+  preserveCodeBlocks,
+  preserveVariables,
+  restorePlaceholders,
+} from '../utils/text-preservation.js';
 
 export { MULTI_TARGET_CONCURRENCY };
 
@@ -45,10 +62,17 @@ export class TranslationService {
   // No cache means "run cacheless" — the CLI passes undefined when the
   // cache backend is unavailable (see cli/cache-loader.ts).
   private cache?: CacheService;
-  private languageCache: Map<'source' | 'target', { data: LanguageInfo[]; timestamp: number }> = new Map();
+  private languageCache: Map<
+    'source' | 'target',
+    { data: LanguageInfo[]; timestamp: number }
+  > = new Map();
   private readonly LANGUAGE_CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours
 
-  constructor(client: DeepLClient, config: ConfigService, cache?: CacheService) {
+  constructor(
+    client: DeepLClient,
+    config: ConfigService,
+    cache?: CacheService
+  ) {
     this.client = client;
     this.config = config;
     this.cache = cache;
@@ -75,7 +99,7 @@ export class TranslationService {
     if (textBytes > MAX_TEXT_BYTES) {
       throw new ValidationError(
         `Text too large: ${textBytes} bytes exceeds the ${MAX_TEXT_BYTES} byte limit (128KB). ` +
-        'Split the text into smaller chunks or use file translation for large documents.'
+          'Split the text into smaller chunks or use file translation for large documents.'
       );
     }
 
@@ -88,7 +112,8 @@ export class TranslationService {
       ...options,
       sourceLang: options.sourceLang ?? defaults.sourceLang,
       formality: options.formality ?? defaults.formality,
-      preserveFormatting: options.preserveFormatting ?? defaults.preserveFormatting,
+      preserveFormatting:
+        options.preserveFormatting ?? defaults.preserveFormatting,
     };
 
     // Preserve code blocks if requested
@@ -130,7 +155,10 @@ export class TranslationService {
 
     // Translate via API
     const startTime = Date.now();
-    const result = await this.client.translate(processedText, translationOptions);
+    const result = await this.client.translate(
+      processedText,
+      translationOptions
+    );
     const elapsed = Date.now() - startTime;
     Logger.verbose(`[verbose] API response time: ${elapsed}ms`);
 
@@ -171,7 +199,7 @@ export class TranslationService {
       if (itemBytes > MAX_TEXT_BYTES) {
         throw new ValidationError(
           `Text at index ${i} too large: ${itemBytes} bytes exceeds the ${MAX_TEXT_BYTES} byte limit (128KB). ` +
-          'Split the text into smaller chunks or use file translation for large documents.'
+            'Split the text into smaller chunks or use file translation for large documents.'
         );
       }
     }
@@ -186,14 +214,16 @@ export class TranslationService {
       ...options,
       sourceLang: options.sourceLang ?? defaults.sourceLang,
       formality: options.formality ?? defaults.formality,
-      preserveFormatting: options.preserveFormatting ?? defaults.preserveFormatting,
+      preserveFormatting:
+        options.preserveFormatting ?? defaults.preserveFormatting,
     };
 
     // Check cache and separate cached vs non-cached texts
     // Use Set for deduplication and Map to track all indices for each text
     const textsToTranslateSet = new Set<string>();
     const textIndexMap = new Map<string, number[]>(); // Maps text to ALL original indices
-    const results: (TranslationResult | null)[] = new Array<TranslationResult | null>(texts.length).fill(null);
+    const results: (TranslationResult | null)[] =
+      new Array<TranslationResult | null>(texts.length).fill(null);
 
     for (let i = 0; i < texts.length; i++) {
       const text = texts[i];
@@ -245,7 +275,10 @@ export class TranslationService {
 
     for (const batch of batches) {
       try {
-        const batchResults = await this.client.translateBatch(batch, translationOptions);
+        const batchResults = await this.client.translateBatch(
+          batch,
+          translationOptions
+        );
 
         // Map each result to its corresponding text
         for (let i = 0; i < batch.length; i++) {
@@ -293,9 +326,11 @@ export class TranslationService {
     }
 
     // Calculate actual failures
-    const actualFailures = results.filter(r => r === null).length;
+    const actualFailures = results.filter((r) => r === null).length;
     if (actualFailures > 0) {
-      Logger.warn(`⚠️  Warning: ${actualFailures} of ${texts.length} translations failed`);
+      Logger.warn(
+        `⚠️  Warning: ${actualFailures} of ${texts.length} translations failed`
+      );
     }
 
     // Return sparse array preserving positional correspondence with input texts.
@@ -309,7 +344,9 @@ export class TranslationService {
   async translateToMultiple(
     text: string,
     targetLangs: Language[],
-    options: Omit<TranslationOptions, 'targetLang'> & { skipCache?: boolean } = {}
+    options: Omit<TranslationOptions, 'targetLang'> & {
+      skipCache?: boolean;
+    } = {}
   ): Promise<MultiTargetResult[]> {
     if (targetLangs.length === 0) {
       throw new ValidationError('At least one target language is required');
@@ -318,10 +355,14 @@ export class TranslationService {
     return mapWithConcurrency(
       targetLangs,
       async (targetLang) => {
-        const result = await this.translate(text, {
-          ...options,
-          targetLang,
-        }, { skipCache: options.skipCache });
+        const result = await this.translate(
+          text,
+          {
+            ...options,
+            targetLang,
+          },
+          { skipCache: options.skipCache }
+        );
 
         return {
           targetLang,
@@ -358,13 +399,15 @@ export class TranslationService {
   /**
    * Get supported languages with caching (24-hour TTL)
    */
-  async getSupportedLanguages(type: 'source' | 'target'): Promise<LanguageInfo[]> {
+  async getSupportedLanguages(
+    type: 'source' | 'target'
+  ): Promise<LanguageInfo[]> {
     // Check cache first
     const cached = this.languageCache.get(type);
     const now = Date.now();
 
     // Return cached data if it exists and hasn't expired
-    if (cached && (now - cached.timestamp) < this.LANGUAGE_CACHE_TTL) {
+    if (cached && now - cached.timestamp < this.LANGUAGE_CACHE_TTL) {
       return cached.data;
     }
 
@@ -421,22 +464,28 @@ export class TranslationService {
     // Create a stable representation with deterministic property order
     // Property order matters because JSON.stringify() preserves insertion order
     const cacheData = {
-      text,                      // 1. Text to translate
-      targetLang: options.targetLang,    // 2. Target language
-      sourceLang: options.sourceLang,    // 3. Source language (if specified)
-      formality: options.formality,      // 4. Formality level
-      glossaryId: glossary && 'glossary_id' in glossary ? glossary.glossary_id : undefined, // 5. Glossary ID
-      context: options.context,          // 6. Context hint
-      modelType: options.modelType,      // 7. Model type affects output quality
+      text, // 1. Text to translate
+      targetLang: options.targetLang, // 2. Target language
+      sourceLang: options.sourceLang, // 3. Source language (if specified)
+      formality: options.formality, // 4. Formality level
+      glossaryId:
+        glossary && 'glossary_id' in glossary
+          ? glossary.glossary_id
+          : undefined, // 5. Glossary ID
+      context: options.context, // 6. Context hint
+      modelType: options.modelType, // 7. Model type affects output quality
       splitSentences: options.splitSentences, // 8. Sentence splitting behavior
-      tagHandling: options.tagHandling,  // 9. HTML/XML processing
+      tagHandling: options.tagHandling, // 9. HTML/XML processing
       tagHandlingVersion: resolveTagHandlingVersion(options), // 10. Tag handling version
       customInstructions: options.customInstructions, // 11. Custom instructions
-      styleId: options.styleId,          // 12. Style rules
-      glossaryIds: glossary && 'glossary_ids' in glossary ? glossary.glossary_ids : undefined, // 13. Multi-glossary selection (order-significant)
+      styleId: options.styleId, // 12. Style rules
+      glossaryIds:
+        glossary && 'glossary_ids' in glossary
+          ? glossary.glossary_ids
+          : undefined, // 13. Multi-glossary selection (order-significant)
       translationMemoryId: options.translationMemoryId, // 14. Memory consulted for matches
       translationMemoryThreshold: options.translationMemoryThreshold, // 15. Which matches it reuses
-      ignoreTags: options.ignoreTags,     // 16. Tags left untranslated
+      ignoreTags: options.ignoreTags, // 16. Tags left untranslated
       splittingTags: options.splittingTags, // 17. Tags that split sentences
       nonSplittingTags: options.nonSplittingTags, // 18. Tags that do not
       outlineDetection: options.outlineDetection, // 19. XML structure inference
diff --git a/src/services/voice-stream-session.ts b/src/services/voice-stream-session.ts
index 28c943c6..ceb206bc 100644
--- a/src/services/voice-stream-session.ts
+++ b/src/services/voice-stream-session.ts
@@ -31,7 +31,7 @@ export class VoicePartialResultError extends VoiceError {
   constructor(
     message: string,
     suggestion: string,
-    readonly result: VoiceSessionResult,
+    readonly result: VoiceSessionResult
   ) {
     super(message, suggestion);
   }
@@ -61,17 +61,22 @@ export class VoiceStreamSession {
     client: VoiceClient,
     session: VoiceSessionResponse,
     options: VoiceTranslateOptions,
-    callbacks?: VoiceStreamCallbacks,
+    callbacks?: VoiceStreamCallbacks
   ) {
     this.client = client;
     this.session = session;
     this.callbacks = callbacks;
 
     this.reconnectEnabled = options.reconnect !== false;
-    this.maxReconnectAttempts = options.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    this.maxReconnectAttempts =
+      options.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
     this.currentToken = session.token;
 
-    this.sourceTranscript = { lang: options.sourceLang ?? 'auto', text: '', segments: [] };
+    this.sourceTranscript = {
+      lang: options.sourceLang ?? 'auto',
+      text: '',
+      segments: [],
+    };
     this.textParts.set(this.sourceTranscript, []);
 
     for (const lang of options.targetLangs) {
@@ -98,7 +103,7 @@ export class VoiceStreamSession {
       this.ws = this.client.createWebSocket(
         this.session.streaming_url,
         this.session.token,
-        internalCallbacks,
+        internalCallbacks
       );
 
       this.ws.on('open', () => {
@@ -116,27 +121,34 @@ export class VoiceStreamSession {
    */
   private attachSocketHandlers(
     internalCallbacks: VoiceStreamCallbacks,
-    reject: (reason: unknown) => void,
+    reject: (reason: unknown) => void
   ): void {
-    this.ws.on('close', () => { this.handleClose(internalCallbacks, reject); });
-    this.ws.on('error', (error: Error) => { this.transportError = error; });
+    this.ws.on('close', () => {
+      this.handleClose(internalCallbacks, reject);
+    });
+    this.ws.on('error', (error: Error) => {
+      this.transportError = error;
+    });
   }
 
   private createInternalCallbacks(
     resolve: (value: VoiceSessionResult) => void,
-    reject: (reason: unknown) => void,
+    reject: (reason: unknown) => void
   ): VoiceStreamCallbacks {
     return {
       onSourceTranscript: (update: VoiceSourceTranscriptUpdate) => {
         this.accumulateTranscript(this.sourceTranscript, update.concluded);
-        const detectedLang = update.concluded[0]?.language ?? update.tentative[0]?.language;
+        const detectedLang =
+          update.concluded[0]?.language ?? update.tentative[0]?.language;
         if (detectedLang) {
           this.sourceTranscript.lang = detectedLang as VoiceSourceLanguage;
         }
         this.callbacks?.onSourceTranscript?.(update);
       },
       onTargetTranscript: (update: VoiceTargetTranscriptUpdate) => {
-        const target = this.targetTranscripts.get(update.language.toLowerCase());
+        const target = this.targetTranscripts.get(
+          update.language.toLowerCase()
+        );
         if (target) {
           this.accumulateTranscript(target, update.concluded);
         }
@@ -168,8 +180,8 @@ export class VoiceStreamSession {
             new VoicePartialResultError(
               `Voice session ended without a translation for: ${untranslated.join(', ')}.`,
               'The audio was transcribed but the server sent no translated text. Retry the request.',
-              result,
-            ),
+              result
+            )
           );
           return;
         }
@@ -180,7 +192,9 @@ export class VoiceStreamSession {
         this.callbacks?.onError?.(error);
         this.fail(
           reject,
-          new VoiceError(`Voice streaming error: ${error.error_message} (${error.error_code})`),
+          new VoiceError(
+            `Voice streaming error: ${error.error_message} (${error.error_code})`
+          )
         );
       },
     };
@@ -188,13 +202,16 @@ export class VoiceStreamSession {
 
   private handleClose(
     internalCallbacks: VoiceStreamCallbacks,
-    reject: (reason: unknown) => void,
+    reject: (reason: unknown) => void
   ): void {
     if (this.streamEnded) {
       return;
     }
 
-    if (this.reconnectEnabled && this.reconnectAttempts < this.maxReconnectAttempts) {
+    if (
+      this.reconnectEnabled &&
+      this.reconnectAttempts < this.maxReconnectAttempts
+    ) {
       this.reconnectAttempts++;
       this.callbacks?.onReconnecting?.(this.reconnectAttempts);
 
@@ -205,24 +222,28 @@ export class VoiceStreamSession {
     this.fail(
       reject,
       this.transportError
-        ? new VoiceError(`WebSocket connection failed: ${this.transportError.message}`)
-        : new VoiceError('WebSocket closed unexpectedly'),
+        ? new VoiceError(
+            `WebSocket connection failed: ${this.transportError.message}`
+          )
+        : new VoiceError('WebSocket closed unexpectedly')
     );
   }
 
   private async reconnect(
     internalCallbacks: VoiceStreamCallbacks,
-    reject: (reason: unknown) => void,
+    reject: (reason: unknown) => void
   ): Promise<void> {
     try {
-      const reconnectResponse = await this.client.reconnectSession(this.currentToken);
+      const reconnectResponse = await this.client.reconnectSession(
+        this.currentToken
+      );
       this.currentToken = reconnectResponse.token;
       this.transportError = undefined;
 
       this.ws = this.client.createWebSocket(
         reconnectResponse.streaming_url,
         reconnectResponse.token,
-        internalCallbacks,
+        internalCallbacks
       );
 
       this.attachSocketHandlers(internalCallbacks, reject);
@@ -234,7 +255,10 @@ export class VoiceStreamSession {
         }
       });
     } catch (error) {
-      this.fail(reject, error instanceof Error ? error : new VoiceError(String(error)));
+      this.fail(
+        reject,
+        error instanceof Error ? error : new VoiceError(String(error))
+      );
     }
   }
 
@@ -262,7 +286,7 @@ export class VoiceStreamSession {
 
   private streamChunks(
     chunks: AsyncGenerator<Buffer>,
-    reject: (reason: unknown) => void,
+    reject: (reason: unknown) => void
   ): void {
     void (async () => {
       try {
@@ -271,20 +295,25 @@ export class VoiceStreamSession {
             if (this.streamEnded) {
               return;
             }
-            await new Promise<void>((r) => { this.chunkStreamingResolve = r; });
+            await new Promise<void>((r) => {
+              this.chunkStreamingResolve = r;
+            });
           }
           this.client.sendAudioChunk(this.ws, chunk.toString('base64'));
         }
         this.client.sendEndOfSource(this.ws);
       } catch (error) {
-        this.fail(reject, error instanceof Error ? error : new VoiceError(String(error)));
+        this.fail(
+          reject,
+          error instanceof Error ? error : new VoiceError(String(error))
+        );
       }
     })();
   }
 
   private accumulateTranscript(
     transcript: VoiceTranscript,
-    concluded: VoiceTranscriptSegment[],
+    concluded: VoiceTranscriptSegment[]
   ): void {
     const parts = this.textParts.get(transcript)!;
     for (const segment of concluded) {
diff --git a/src/services/voice.ts b/src/services/voice.ts
index c63c4c04..5afe3405 100644
--- a/src/services/voice.ts
+++ b/src/services/voice.ts
@@ -20,16 +20,17 @@ const MAX_TARGET_LANGS = 5;
 const DEFAULT_CHUNK_SIZE = 6400;
 const DEFAULT_CHUNK_INTERVAL = 200;
 
-const EXTENSION_CONTENT_TYPE_MAP: Record<string, VoiceSourceMediaContentType> = {
-  '.ogg': 'audio/opus;container=ogg',
-  '.opus': 'audio/opus;container=ogg',
-  '.webm': 'audio/opus;container=webm',
-  '.mka': 'audio/opus;container=matroska',
-  '.flac': 'audio/flac',
-  '.mp3': 'audio/mpeg',
-  '.pcm': 'audio/pcm;encoding=s16le;rate=16000',
-  '.raw': 'audio/pcm;encoding=s16le;rate=16000',
-};
+const EXTENSION_CONTENT_TYPE_MAP: Record<string, VoiceSourceMediaContentType> =
+  {
+    '.ogg': 'audio/opus;container=ogg',
+    '.opus': 'audio/opus;container=ogg',
+    '.webm': 'audio/opus;container=webm',
+    '.mka': 'audio/opus;container=matroska',
+    '.flac': 'audio/flac',
+    '.mp3': 'audio/mpeg',
+    '.pcm': 'audio/pcm;encoding=s16le;rate=16000',
+    '.raw': 'audio/pcm;encoding=s16le;rate=16000',
+  };
 
 export class VoiceService {
   private client: VoiceClient;
@@ -49,22 +50,23 @@ export class VoiceService {
   async translateFile(
     filePath: string,
     options: VoiceTranslateOptions,
-    callbacks?: VoiceStreamCallbacks,
+    callbacks?: VoiceStreamCallbacks
   ): Promise<VoiceSessionResult> {
     this.validateOptions(options);
 
     const resolvedPath = resolve(filePath);
-    const contentType = options.contentType ?? this.detectContentType(resolvedPath);
+    const contentType =
+      options.contentType ?? this.detectContentType(resolvedPath);
     if (!contentType) {
       throw new ValidationError(
-        `Cannot detect audio format for "${resolvedPath}". Use --content-type to specify explicitly.`,
+        `Cannot detect audio format for "${resolvedPath}". Use --content-type to specify explicitly.`
       );
     }
 
     const fileStat = await lstat(resolvedPath);
     if (fileStat.isSymbolicLink()) {
       throw new ValidationError(
-        `Symlinks are not supported for security reasons: ${resolvedPath}`,
+        `Symlinks are not supported for security reasons: ${resolvedPath}`
       );
     }
 
@@ -76,19 +78,19 @@ export class VoiceService {
       contentType,
       options,
       chunkInterval,
-      callbacks,
+      callbacks
     );
   }
 
   async translateStdin(
     options: VoiceTranslateOptions,
-    callbacks?: VoiceStreamCallbacks,
+    callbacks?: VoiceStreamCallbacks
   ): Promise<VoiceSessionResult> {
     this.validateOptions(options);
 
     if (!options.contentType) {
       throw new ValidationError(
-        'Content type is required when reading from stdin. Use --content-type to specify the audio format.',
+        'Content type is required when reading from stdin. Use --content-type to specify the audio format.'
       );
     }
 
@@ -100,7 +102,7 @@ export class VoiceService {
       options.contentType,
       options,
       chunkInterval,
-      callbacks,
+      callbacks
     );
   }
 
@@ -116,7 +118,7 @@ export class VoiceService {
 
     if (options.targetLangs.length > MAX_TARGET_LANGS) {
       throw new ValidationError(
-        `Maximum ${MAX_TARGET_LANGS} target languages allowed, got ${options.targetLangs.length}.`,
+        `Maximum ${MAX_TARGET_LANGS} target languages allowed, got ${options.targetLangs.length}.`
       );
     }
   }
@@ -126,7 +128,7 @@ export class VoiceService {
     contentType: VoiceSourceMediaContentType,
     options: VoiceTranslateOptions,
     chunkInterval: number,
-    callbacks?: VoiceStreamCallbacks,
+    callbacks?: VoiceStreamCallbacks
   ): Promise<VoiceSessionResult> {
     const session = await this.client.createSession({
       source_language: options.sourceLang,
@@ -137,7 +139,12 @@ export class VoiceService {
       glossary_id: options.glossaryId,
     });
 
-    const streamSession = new VoiceStreamSession(this.client, session, options, callbacks);
+    const streamSession = new VoiceStreamSession(
+      this.client,
+      session,
+      options,
+      callbacks
+    );
     this.activeSession = streamSession;
     try {
       return await streamSession.run(this.paceChunks(chunks, chunkInterval));
@@ -146,7 +153,10 @@ export class VoiceService {
     }
   }
 
-  private async *readFileInChunks(filePath: string, chunkSize: number): AsyncGenerator<Buffer> {
+  private async *readFileInChunks(
+    filePath: string,
+    chunkSize: number
+  ): AsyncGenerator<Buffer> {
     const stream = createReadStream(filePath, { highWaterMark: chunkSize });
     for await (const chunk of stream) {
       yield Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string);
@@ -187,7 +197,10 @@ export class VoiceService {
     }
   }
 
-  private async *paceChunks(chunks: AsyncGenerator<Buffer>, intervalMs: number): AsyncGenerator<Buffer> {
+  private async *paceChunks(
+    chunks: AsyncGenerator<Buffer>,
+    intervalMs: number
+  ): AsyncGenerator<Buffer> {
     for await (const chunk of chunks) {
       yield chunk;
       if (intervalMs > 0) {
diff --git a/src/services/watch.ts b/src/services/watch.ts
index 13805126..0b235cc0 100644
--- a/src/services/watch.ts
+++ b/src/services/watch.ts
@@ -20,13 +20,21 @@ export interface FileTranslationResult {
   outputPath?: string;
 }
 
-export type WatchTranslationResult = FileTranslationResult | FileTranslationResult[];
+export type WatchTranslationResult =
+  FileTranslationResult | FileTranslationResult[];
 
 export interface WatchOptions {
   targetLangs: readonly Language[];
   outputDir: string;
   sourceLang?: Language;
-  formality?: 'default' | 'more' | 'less' | 'prefer_more' | 'prefer_less' | 'formal' | 'informal';
+  formality?:
+    | 'default'
+    | 'more'
+    | 'less'
+    | 'prefer_more'
+    | 'prefer_less'
+    | 'formal'
+    | 'informal';
   glossaryId?: string;
   preserveCode?: boolean;
   pattern?: string;
@@ -129,7 +137,10 @@ export class WatchService {
       try {
         this.handleFileChange(filePath);
       } catch (error) {
-        Logger.error(`Error handling file change for ${filePath}:`, errorMessage(error));
+        Logger.error(
+          `Error handling file change for ${filePath}:`,
+          errorMessage(error)
+        );
       }
     });
 
@@ -138,7 +149,10 @@ export class WatchService {
       try {
         this.handleFileChange(filePath);
       } catch (error) {
-        Logger.error(`Error handling file add for ${filePath}:`, errorMessage(error));
+        Logger.error(
+          `Error handling file add for ${filePath}:`,
+          errorMessage(error)
+        );
       }
     });
 
@@ -201,7 +215,10 @@ export class WatchService {
     }
 
     // Check if file is in the git-staged set
-    if (this.options.stagedFiles && !this.options.stagedFiles.has(path.resolve(filePath))) {
+    if (
+      this.options.stagedFiles &&
+      !this.options.stagedFiles.has(path.resolve(filePath))
+    ) {
       return;
     }
 
@@ -242,7 +259,10 @@ export class WatchService {
           if (this.watchOptions?.onError) {
             this.watchOptions.onError(filePath, error as Error);
           }
-          Logger.error(`Translation failed for ${filePath}:`, errorMessage(error));
+          Logger.error(
+            `Translation failed for ${filePath}:`,
+            errorMessage(error)
+          );
         }
       })();
     }, this.options.debounceMs);
@@ -270,7 +290,7 @@ export class WatchService {
     // Check any segment between the first and last could be a target language code
     for (let i = 1; i < parts.length - 1; i++) {
       const segment = parts[i]!.toLowerCase();
-      if (targetLangs.some(lang => lang.toLowerCase() === segment)) {
+      if (targetLangs.some((lang) => lang.toLowerCase() === segment)) {
         return true;
       }
     }
@@ -286,7 +306,14 @@ export class WatchService {
       throw new ValidationError('Watch not started');
     }
 
-    const { targetLangs, outputDir, sourceLang, formality, glossaryId, preserveCode } = this.watchOptions;
+    const {
+      targetLangs,
+      outputDir,
+      sourceLang,
+      formality,
+      glossaryId,
+      preserveCode,
+    } = this.watchOptions;
 
     // Build translation options base (targetLang will be set per operation)
     const baseOptions: Partial<TranslationOptions> = {};
@@ -310,7 +337,10 @@ export class WatchService {
     if (targetLangs.length === 1) {
       // Single target language (length === 1 guarantees targetLangs[0] exists)
       const targetLang = targetLangs[0]!;
-      const outputPath = path.join(outputDir, `${fileName}.${targetLang}${ext}`);
+      const outputPath = path.join(
+        outputDir,
+        `${fileName}.${targetLang}${ext}`
+      );
 
       await this.fileTranslationService.translateFile(
         filePath,
@@ -322,7 +352,11 @@ export class WatchService {
       this.stats.translationsCount++;
 
       if (this.watchOptions.onTranslate) {
-        this.watchOptions.onTranslate(filePath, { text: '', outputPath, targetLang });
+        this.watchOptions.onTranslate(filePath, {
+          text: '',
+          outputPath,
+          targetLang,
+        });
       }
     } else {
       // Multiple target languages
diff --git a/src/services/write.ts b/src/services/write.ts
index 658399b9..f3eda215 100644
--- a/src/services/write.ts
+++ b/src/services/write.ts
@@ -7,7 +7,12 @@ import * as crypto from 'crypto';
 import { DeepLClient } from '../api/deepl-client.js';
 import { ConfigService } from '../storage/config.js';
 import type { CacheService } from '../storage/cache.js';
-import { WriteOptions, CorrectOptions, WriteImprovement, isWriteImprovementArray } from '../types/index.js';
+import {
+  WriteOptions,
+  CorrectOptions,
+  WriteImprovement,
+  isWriteImprovementArray,
+} from '../types/index.js';
 import { Logger } from '../utils/logger.js';
 import { ValidationError, ConfigError } from '../utils/errors.js';
 
@@ -22,7 +27,11 @@ export class WriteService {
   // cache backend is unavailable (see cli/cache-loader.ts).
   private cache?: CacheService;
 
-  constructor(client: DeepLClient, config: ConfigService, cache?: CacheService) {
+  constructor(
+    client: DeepLClient,
+    config: ConfigService,
+    cache?: CacheService
+  ) {
     if (!client) {
       throw new ConfigError('DeepL client is required');
     }
@@ -49,7 +58,9 @@ export class WriteService {
     }
 
     if (options.writingStyle && options.tone) {
-      throw new ValidationError('Cannot specify both --style and --tone in a single request');
+      throw new ValidationError(
+        'Cannot specify both --style and --tone in a single request'
+      );
     }
 
     return this.requestWithCache(
diff --git a/src/storage/cache.ts b/src/storage/cache.ts
index 15a7ac6e..80f3e7ab 100644
--- a/src/storage/cache.ts
+++ b/src/storage/cache.ts
@@ -51,7 +51,10 @@ const SQLITE_NOTADB = 26;
 // in a jest test context).
 function isCorruptionError(error: unknown): boolean {
   if (typeof error !== 'object' || error === null) return false;
-  const { errcode, message } = error as { errcode?: unknown; message?: unknown };
+  const { errcode, message } = error as {
+    errcode?: unknown;
+    message?: unknown;
+  };
   if (typeof errcode === 'number') {
     const primary = errcode & 0xff;
     return primary === SQLITE_CORRUPT || primary === SQLITE_NOTADB;
@@ -120,7 +123,7 @@ export class CacheService {
       const suffix = `.corrupt-${Date.now()}`;
       Logger.warn(
         `Cache database corrupted, backing up and recreating: ${(error as Error).message}. ` +
-        `Previous contents preserved at ${path.basename(dbPath)}${suffix} (and ${path.basename(dbPath)}${suffix}-wal / -shm if present).`,
+          `Previous contents preserved at ${path.basename(dbPath)}${suffix} (and ${path.basename(dbPath)}${suffix}-wal / -shm if present).`
       );
       try {
         // Sidecars must be preserved BEFORE closing the failed handle —
@@ -158,12 +161,15 @@ export class CacheService {
     try {
       const dir = path.dirname(dbPath);
       const prefix = `${path.basename(dbPath)}.corrupt-`;
-      const stamps = [...new Set(
-        fs.readdirSync(dir)
-          .filter((f) => f.startsWith(prefix))
-          .map((f) => /\.corrupt-(\d+)/.exec(f)?.[1])
-          .filter((s): s is string => s !== undefined),
-      )].sort((a, b) => Number(b) - Number(a));
+      const stamps = [
+        ...new Set(
+          fs
+            .readdirSync(dir)
+            .filter((f) => f.startsWith(prefix))
+            .map((f) => /\.corrupt-(\d+)/.exec(f)?.[1])
+            .filter((s): s is string => s !== undefined)
+        ),
+      ].sort((a, b) => Number(b) - Number(a));
       for (const stamp of stamps.slice(CORRUPT_BACKUPS_TO_KEEP)) {
         for (const suffix of ['', '-wal', '-shm']) {
           fs.rmSync(`${dbPath}.corrupt-${stamp}${suffix}`, { force: true });
@@ -186,8 +192,10 @@ export class CacheService {
   }
 
   static getInstance(options?: CacheServiceOptions): CacheService {
-    const needsNewInstance = !CacheService.instance || CacheService.instance.isClosed;
-    const needsHandlerRegistration = needsNewInstance && !CacheService.handlersRegistered;
+    const needsNewInstance =
+      !CacheService.instance || CacheService.instance.isClosed;
+    const needsHandlerRegistration =
+      needsNewInstance && !CacheService.handlersRegistered;
 
     if (needsHandlerRegistration) {
       CacheService.handlersRegistered = true;
@@ -230,7 +238,7 @@ export class CacheService {
       .get() as { user_version: number };
     if (userVersion > CACHE_SCHEMA_VERSION) {
       throw new ConfigError(
-        `Cache DB schema version ${userVersion} is newer than this CLI supports (${CACHE_SCHEMA_VERSION}). Upgrade the CLI, or delete the cache DB to start fresh.`,
+        `Cache DB schema version ${userVersion} is newer than this CLI supports (${CACHE_SCHEMA_VERSION}). Upgrade the CLI, or delete the cache DB to start fresh.`
       );
     }
 
@@ -283,7 +291,9 @@ export class CacheService {
     // Clean up expired entries first
     this.cleanupExpired();
 
-    const stmt = this.db.prepare('SELECT value, timestamp FROM cache WHERE key = ?');
+    const stmt = this.db.prepare(
+      'SELECT value, timestamp FROM cache WHERE key = ?'
+    );
     const row = stmt.get(key) as CacheRow | undefined;
 
     if (!row) {
@@ -302,7 +312,9 @@ export class CacheService {
 
       if (guard && !guard(parsed)) {
         const truncatedKey = key.length > 8 ? key.substring(0, 8) + '...' : key;
-        Logger.warn(`Cache type mismatch for key "${truncatedKey}". Removing entry.`);
+        Logger.warn(
+          `Cache type mismatch for key "${truncatedKey}". Removing entry.`
+        );
         this.db.prepare('DELETE FROM cache WHERE key = ?').run(key);
         return null;
       }
@@ -310,7 +322,9 @@ export class CacheService {
       return parsed as T;
     } catch (error) {
       const truncatedKey = key.length > 8 ? key.substring(0, 8) + '...' : key;
-      Logger.warn(`Cache corruption detected for key "${truncatedKey}": ${errorMessage(error)}. Removing entry.`);
+      Logger.warn(
+        `Cache corruption detected for key "${truncatedKey}": ${errorMessage(error)}. Removing entry.`
+      );
       this.db.prepare('DELETE FROM cache WHERE key = ?').run(key);
       return null;
     }
@@ -333,7 +347,7 @@ export class CacheService {
     // evicting everything else first — skip it rather than wipe the cache.
     if (size > this.maxSize) {
       Logger.verbose(
-        `Skipping cache write: entry of ${size} bytes exceeds the ${this.maxSize}-byte cache size limit.`,
+        `Skipping cache write: entry of ${size} bytes exceeds the ${this.maxSize}-byte cache size limit.`
       );
       return;
     }
@@ -342,7 +356,9 @@ export class CacheService {
     this.cleanupExpired();
 
     // Check if key already exists and get its size
-    const existingStmt = this.db.prepare('SELECT size FROM cache WHERE key = ?');
+    const existingStmt = this.db.prepare(
+      'SELECT size FROM cache WHERE key = ?'
+    );
     const existing = existingStmt.get(key) as { size: number } | undefined;
     const existingSize = existing?.size ?? 0;
 
@@ -434,7 +450,9 @@ export class CacheService {
     }
     this.lastCleanupTime = now;
 
-    this.db.prepare('DELETE FROM cache WHERE timestamp < ?').run(now - this.ttl);
+    this.db
+      .prepare('DELETE FROM cache WHERE timestamp < ?')
+      .run(now - this.ttl);
   }
 
   private evictIfNeeded(newEntrySize: number): void {
@@ -444,7 +462,9 @@ export class CacheService {
     // estimate from the average row size under-evicts whenever sizes are
     // skewed, leaving the cache over its cap.
     while (excess > 0) {
-      const deleted = this.db.prepare(`
+      const deleted = this.db
+        .prepare(
+          `
         DELETE FROM cache
         WHERE key IN (
           SELECT key FROM cache
@@ -452,7 +472,9 @@ export class CacheService {
           LIMIT ${EVICTION_BATCH}
         )
         RETURNING size
-      `).all() as { size: number }[];
+      `
+        )
+        .all() as { size: number }[];
 
       if (deleted.length === 0) {
         return;
diff --git a/src/storage/config.ts b/src/storage/config.ts
index 4ee76055..85d75572 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -6,9 +6,17 @@
 import { randomBytes } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { DeepLConfig, Formality, Language, OutputFormat } from '../types/index.js';
+import {
+  DeepLConfig,
+  Formality,
+  Language,
+  OutputFormat,
+} from '../types/index.js';
 import { resolvePaths } from '../utils/paths.js';
-import { isValidLanguage, looksLikeLanguageTag } from '../data/language-registry.js';
+import {
+  isValidLanguage,
+  looksLikeLanguageTag,
+} from '../data/language-registry.js';
 import { ConfigError } from '../utils/errors.js';
 import { validateApiUrl } from '../utils/validate-url.js';
 import { Logger } from '../utils/logger.js';
@@ -39,7 +47,11 @@ const BOOLEAN_CONFIG_PATHS = [
 
 // Path segments that would walk or rewrite the prototype chain instead of
 // plain config data (prototype pollution).
-const FORBIDDEN_KEY_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+const FORBIDDEN_KEY_SEGMENTS = new Set([
+  '__proto__',
+  'constructor',
+  'prototype',
+]);
 
 const DEFAULT_CACHE_SIZE = 1024 * 1024 * 1024; // 1GB
 const DEFAULT_CACHE_TTL = 30 * 24 * 60 * 60; // 30 days in seconds
@@ -58,7 +70,9 @@ function normalizeLanguageValue(path: string, value: unknown): unknown {
     return value.toLowerCase();
   }
   if (path === 'defaults.targetLangs' && Array.isArray(value)) {
-    return value.map(lang => (typeof lang === 'string' ? lang.toLowerCase() : lang));
+    return value.map((lang) =>
+      typeof lang === 'string' ? lang.toLowerCase() : lang
+    );
   }
   return value;
 }
@@ -68,8 +82,7 @@ export class ConfigService {
   private configPath: string;
 
   constructor(configPath?: string) {
-    this.configPath =
-      configPath ?? resolvePaths().configFile;
+    this.configPath = configPath ?? resolvePaths().configFile;
     this.config = this.load();
   }
 
@@ -91,7 +104,10 @@ export class ConfigService {
     this.validatePath(keys, value);
     value = normalizeLanguageValue(keys.join('.'), value);
 
-    let current: Record<string, unknown> = this.config as unknown as Record<string, unknown>;
+    let current: Record<string, unknown> = this.config as unknown as Record<
+      string,
+      unknown
+    >;
     for (let i = 0; i < keys.length - 1; i++) {
       const k = keys[i];
       if (!k || !Object.hasOwn(current, k)) {
@@ -163,7 +179,10 @@ export class ConfigService {
   delete(key: string): void {
     const keys = key.split('.');
     this.validateSegments(keys);
-    let current: Record<string, unknown> = this.config as unknown as Record<string, unknown>;
+    let current: Record<string, unknown> = this.config as unknown as Record<
+      string,
+      unknown
+    >;
 
     for (let i = 0; i < keys.length - 1; i++) {
       const k = keys[i];
@@ -244,7 +263,10 @@ export class ConfigService {
         return merged;
       }
     } catch (error) {
-      Logger.warn('Failed to load config, using defaults:', errorMessage(error));
+      Logger.warn(
+        'Failed to load config, using defaults:',
+        errorMessage(error)
+      );
     }
 
     return ConfigService.getDefaults();
@@ -263,14 +285,15 @@ export class ConfigService {
     }
     if (config.defaults?.sourceLang) {
       this.validateLanguage(config.defaults.sourceLang, 'defaults.sourceLang');
-      config.defaults.sourceLang = config.defaults.sourceLang.toLowerCase() as Language;
+      config.defaults.sourceLang =
+        config.defaults.sourceLang.toLowerCase() as Language;
     }
     if (config.defaults?.targetLangs) {
       for (const lang of config.defaults.targetLangs) {
         this.validateLanguage(lang, 'defaults.targetLangs');
       }
       config.defaults.targetLangs = config.defaults.targetLangs.map(
-        lang => lang.toLowerCase() as Language,
+        (lang) => lang.toLowerCase() as Language
       );
     }
     if (config.defaults?.formality) {
@@ -292,16 +315,20 @@ export class ConfigService {
       if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
       }
-      fs.writeFileSync(
-        tmpPath,
-        JSON.stringify(this.config, null, 2),
-        { encoding: 'utf-8', mode: 0o600, flag: 'wx' }
-      );
+      fs.writeFileSync(tmpPath, JSON.stringify(this.config, null, 2), {
+        encoding: 'utf-8',
+        mode: 0o600,
+        flag: 'wx',
+      });
       // The mode above is masked by the umask at creation; chmod is not.
       fs.chmodSync(tmpPath, 0o600);
       fs.renameSync(tmpPath, this.configPath);
     } catch (error) {
-      try { fs.unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        /* ignore cleanup errors */
+      }
       throw new ConfigError(`Failed to save config: ${errorMessage(error)}`);
     }
   }
@@ -396,13 +423,22 @@ export class ConfigService {
       try {
         validateApiUrl(value as string);
       } catch {
-        throw new ConfigError('Invalid API base URL: must be HTTPS (or http://localhost for testing)');
+        throw new ConfigError(
+          'Invalid API base URL: must be HTTPS (or http://localhost for testing)'
+        );
       }
     }
 
     // Validate boolean fields
-    if (BOOLEAN_CONFIG_PATHS.includes(path as typeof BOOLEAN_CONFIG_PATHS[number]) && typeof value !== 'boolean') {
-      throw new ConfigError(`Expected boolean for "${path}". Use true or false.`);
+    if (
+      BOOLEAN_CONFIG_PATHS.includes(
+        path as (typeof BOOLEAN_CONFIG_PATHS)[number]
+      ) &&
+      typeof value !== 'boolean'
+    ) {
+      throw new ConfigError(
+        `Expected boolean for "${path}". Use true or false.`
+      );
     }
   }
 
@@ -416,13 +452,19 @@ export class ConfigService {
    *   the bundled snapshot. Only the write path announces: every command loads
    *   the config, and a note on each invocation is noise, not guidance.
    */
-  private validateLanguage(lang: string, key?: string, announceUnknown = false): void {
+  private validateLanguage(
+    lang: string,
+    key?: string,
+    announceUnknown = false
+  ): void {
     // Lowercased first: the translate paths lowercase their flags before use, and
     // the tag pattern below is lowercase-only, so `DE` is as valid as `de` here.
     const normalized = typeof lang === 'string' ? lang.toLowerCase() : lang;
     if (!isValidLanguage(normalized) && !looksLikeLanguageTag(normalized)) {
       const context = key ? ` for "${key}"` : '';
-      throw new ConfigError(`Invalid language code "${lang}"${context}. Run: deepl languages to see valid codes`);
+      throw new ConfigError(
+        `Invalid language code "${lang}"${context}. Run: deepl languages to see valid codes`
+      );
     }
     if (announceUnknown && !isValidLanguage(normalized)) {
       // Stored anyway, since the snapshot can lag the API -- but flagged as it is
@@ -442,7 +484,9 @@ export class ConfigService {
   private validateFormality(formality: string, key?: string): void {
     if (!VALID_FORMALITY.includes(formality as Formality)) {
       const context = key ? ` for "${key}"` : '';
-      throw new ConfigError(`Invalid formality "${formality}"${context}. Valid values: ${VALID_FORMALITY.join(', ')}`);
+      throw new ConfigError(
+        `Invalid formality "${formality}"${context}. Valid values: ${VALID_FORMALITY.join(', ')}`
+      );
     }
   }
 
@@ -452,7 +496,9 @@ export class ConfigService {
   private validateOutputFormat(format: string, key?: string): void {
     if (!VALID_OUTPUT_FORMATS.includes(format as OutputFormat)) {
       const context = key ? ` for "${key}"` : '';
-      throw new ConfigError(`Invalid output format "${format}"${context}. Valid values: ${VALID_OUTPUT_FORMATS.join(', ')}`);
+      throw new ConfigError(
+        `Invalid output format "${format}"${context}. Valid values: ${VALID_OUTPUT_FORMATS.join(', ')}`
+      );
     }
   }
 
diff --git a/src/sync/sync-bak-cleanup.ts b/src/sync/sync-bak-cleanup.ts
index 3a624a9b..d48b98fa 100644
--- a/src/sync/sync-bak-cleanup.ts
+++ b/src/sync/sync-bak-cleanup.ts
@@ -27,7 +27,7 @@ let _warnedNoScope = false;
  */
 export function bucketSweepRoots(
   projectRoot: string,
-  buckets: Record<string, { include: string[] }>,
+  buckets: Record<string, { include: string[] }>
 ): string[] {
   const roots = new Set<string>();
   const rootPrefix = path.resolve(projectRoot) + path.sep;
@@ -35,13 +35,20 @@ export function bucketSweepRoots(
     for (const glob of bucket.include) {
       const specialIdx = glob.search(/[*?{[]/);
       const literal = specialIdx === -1 ? glob : glob.slice(0, specialIdx);
-      const dir = literal.endsWith('/') ? literal.slice(0, -1) : path.dirname(literal);
+      const dir = literal.endsWith('/')
+        ? literal.slice(0, -1)
+        : path.dirname(literal);
       const abs = path.resolve(projectRoot, dir);
       // Defence in depth. validateSyncConfig rejects traversing includes, but
       // this sweep deletes and re-creates files, so it must never accept a
       // root outside the project even if it is reached another way.
-      if (abs !== path.resolve(projectRoot) && !(abs + path.sep).startsWith(rootPrefix)) {
-        Logger.warn(`Ignoring stale-backup sweep root outside the project: ${abs}`);
+      if (
+        abs !== path.resolve(projectRoot) &&
+        !(abs + path.sep).startsWith(rootPrefix)
+      ) {
+        Logger.warn(
+          `Ignoring stale-backup sweep root outside the project: ${abs}`
+        );
         continue;
       }
       roots.add(abs);
@@ -67,7 +74,7 @@ export function bucketSweepRoots(
 export async function sweepStaleBackups(
   projectRoot: string,
   maxAgeMs: number,
-  buckets?: Record<string, { include: string[] }>,
+  buckets?: Record<string, { include: string[] }>
 ): Promise<void> {
   const threshold = Date.now() - maxAgeMs;
   const visited = new Set<string>();
@@ -76,7 +83,9 @@ export async function sweepStaleBackups(
     roots = bucketSweepRoots(projectRoot, buckets);
   } else {
     if (!_warnedNoScope) {
-      Logger.warn('sweepStaleBackups: no bucket config provided, falling back to full project tree sweep.');
+      Logger.warn(
+        'sweepStaleBackups: no bucket config provided, falling back to full project tree sweep.'
+      );
       _warnedNoScope = true;
     }
     roots = [projectRoot];
@@ -86,9 +95,17 @@ export async function sweepStaleBackups(
   }
 }
 
-async function sweepDir(dir: string, visited: Set<string>, threshold: number): Promise<void> {
+async function sweepDir(
+  dir: string,
+  visited: Set<string>,
+  threshold: number
+): Promise<void> {
   const real = (() => {
-    try { return fs.realpathSync(dir); } catch { return dir; }
+    try {
+      return fs.realpathSync(dir);
+    } catch {
+      return dir;
+    }
   })();
   if (visited.has(real)) return;
   visited.add(real);
@@ -142,7 +159,9 @@ async function sweepDir(dir: string, visited: Set<string>, threshold: number): P
  * route through this so the guard against non-positive values stays in one
  * place.
  */
-export function resolveBakSweepAgeMs(configuredSeconds: number | undefined): number {
+export function resolveBakSweepAgeMs(
+  configuredSeconds: number | undefined
+): number {
   if (configuredSeconds === undefined || configuredSeconds <= 0) {
     return DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS * 1000;
   }
diff --git a/src/sync/sync-bucket-walker.ts b/src/sync/sync-bucket-walker.ts
index 1afef29e..2b4d0372 100644
--- a/src/sync/sync-bucket-walker.ts
+++ b/src/sync/sync-bucket-walker.ts
@@ -1,7 +1,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import fg from 'fast-glob';
-import type { ExtractedEntry, FormatParser, FormatRegistry } from '../formats/index.js';
+import type {
+  ExtractedEntry,
+  FormatParser,
+  FormatRegistry,
+} from '../formats/index.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncBucketConfig } from './types.js';
 import { resolveSyncLimits, DEFAULT_SYNC_LIMITS } from './types.js';
@@ -72,11 +76,12 @@ export function partitionEntries(all: ExtractedEntry[]): {
 export function extractTranslatable(
   parser: FormatParser,
   content: string,
-  locale?: string,
+  locale?: string
 ): ExtractedEntry[] {
-  const raw = parser.multiLocale && locale
-    ? parser.extract(content, locale)
-    : parser.extract(content);
+  const raw =
+    parser.multiLocale && locale
+      ? parser.extract(content, locale)
+      : parser.extract(content);
   return partitionEntries(raw).entries;
 }
 
@@ -93,7 +98,7 @@ export interface WalkBucketsOptions {
 export async function* walkBuckets(
   config: ResolvedSyncConfig,
   registry: FormatRegistry,
-  opts: WalkBucketsOptions = {},
+  opts: WalkBucketsOptions = {}
 ): AsyncIterable<WalkedBucketFile> {
   const limits = resolveSyncLimits(config);
 
@@ -115,7 +120,10 @@ export async function* walkBuckets(
         ? new PhpArraysFormatParser({ maxDepth: limits.max_depth })
         : registeredParser;
 
-    const ignorePatterns = [...(bucketConfig.exclude ?? []), ...(config.ignore ?? [])];
+    const ignorePatterns = [
+      ...(bucketConfig.exclude ?? []),
+      ...(config.ignore ?? []),
+    ];
     const sourceFiles = await fg(bucketConfig.include, {
       cwd: config.projectRoot,
       ignore: ignorePatterns,
@@ -124,13 +132,15 @@ export async function* walkBuckets(
     });
 
     if (sourceFiles.length === 0) {
-      Logger.warn(`Bucket "${bucket}": glob pattern matched no files (include: ${bucketConfig.include.join(', ')})`);
+      Logger.warn(
+        `Bucket "${bucket}": glob pattern matched no files (include: ${bucketConfig.include.join(', ')})`
+      );
     }
 
     if (sourceFiles.length > limits.max_source_files) {
       Logger.warn(
         `Skipping bucket "${bucket}": glob matched ${sourceFiles.length} files, exceeding sync.limits.max_source_files (${limits.max_source_files}). ` +
-        `Narrow the include pattern or raise the cap in .deepl-sync.yaml.`,
+          `Narrow the include pattern or raise the cap in .deepl-sync.yaml.`
       );
       continue;
     }
@@ -149,7 +159,7 @@ export async function* walkBuckets(
           if (stat.size > limits.max_file_bytes) {
             Logger.warn(
               `Skipping ${path.relative(config.projectRoot, sourceFile)}: ` +
-              `file size ${stat.size} bytes exceeds sync.limits.max_file_bytes (${limits.max_file_bytes}).`,
+                `file size ${stat.size} bytes exceeds sync.limits.max_file_bytes (${limits.max_file_bytes}).`
             );
             continue;
           }
@@ -172,7 +182,7 @@ export async function* walkBuckets(
       } catch (err) {
         if (err instanceof PhpArraysCapExceededError) {
           Logger.warn(
-            `Skipping ${path.relative(config.projectRoot, sourceFile)}: ${err.message}`,
+            `Skipping ${path.relative(config.projectRoot, sourceFile)}: ${err.message}`
           );
           continue;
         }
@@ -185,7 +195,7 @@ export async function* walkBuckets(
       if (rawEntries.length > limits.max_entries_per_file) {
         Logger.warn(
           `Skipping ${path.relative(config.projectRoot, sourceFile)}: ` +
-          `${rawEntries.length} entries exceeds sync.limits.max_entries_per_file (${limits.max_entries_per_file}).`,
+            `${rawEntries.length} entries exceeds sync.limits.max_entries_per_file (${limits.max_entries_per_file}).`
         );
         continue;
       }
diff --git a/src/sync/sync-config.ts b/src/sync/sync-config.ts
index c2ddf813..21208a24 100644
--- a/src/sync/sync-config.ts
+++ b/src/sync/sync-config.ts
@@ -4,7 +4,14 @@ import * as YAML from 'yaml';
 import { ConfigError } from '../utils/errors.js';
 import { safeReadFileSync } from '../utils/safe-read-file.js';
 import { sanitizeForTerminal } from '../utils/control-chars.js';
-import type { SyncConfig, SyncBucketConfig, SyncTranslationSettings, SyncValidationSettings, SyncBehavior, SyncTmsConfig } from './types.js';
+import type {
+  SyncConfig,
+  SyncBucketConfig,
+  SyncTranslationSettings,
+  SyncValidationSettings,
+  SyncBehavior,
+  SyncTmsConfig,
+} from './types.js';
 import { HARD_MAX_SYNC_LIMITS } from './types.js';
 import type { Formality } from '../types/common.js';
 
@@ -20,7 +27,10 @@ export const LOCALE_CODE_RE = /^[a-zA-Z]{2,8}(-[a-zA-Z0-9]{2,8})*$/;
 
 // Directories a target_path_pattern must never resolve into: writing there
 // lets a translated-locale name become VCS metadata or CI workflow code.
-const FORBIDDEN_TARGET_SEGMENTS: ReadonlySet<string> = new Set(['.git', '.github']);
+const FORBIDDEN_TARGET_SEGMENTS: ReadonlySet<string> = new Set([
+  '.git',
+  '.github',
+]);
 
 export interface SyncConfigOverrides {
   frozen?: boolean;
@@ -175,7 +185,7 @@ function levenshtein(a: string, b: string): number {
       curr[j] = Math.min(
         (curr[j - 1] ?? 0) + 1,
         (prev[j] ?? 0) + 1,
-        (prev[j - 1] ?? 0) + cost,
+        (prev[j - 1] ?? 0) + cost
       );
     }
     for (let j = 0; j <= b.length; j += 1) prev[j] = curr[j] ?? 0;
@@ -203,7 +213,7 @@ function findClosestKey(key: string, known: readonly string[]): string | null {
 function assertOnlyKnownKeys(
   obj: Record<string, unknown>,
   knownKeys: readonly string[],
-  context: string,
+  context: string
 ): void {
   for (const key of Object.keys(obj)) {
     if (knownKeys.includes(key)) continue;
@@ -212,19 +222,20 @@ function assertOnlyKnownKeys(
     const hint = suggestion
       ? `Did you mean "${suggestion}"? Remove or rename "${safeKey}" in ${context}.`
       : `Remove "${safeKey}" from ${context}, or check .deepl-sync.yaml schema documentation.`;
-    throw new ConfigError(
-      `Unknown field "${safeKey}" in ${context}`,
-      hint,
-    );
+    throw new ConfigError(`Unknown field "${safeKey}" in ${context}`, hint);
   }
 }
 
 function validateTmThreshold(value: unknown, keyPath: string): void {
   if (value === undefined) return;
-  if (!Number.isInteger(value) || (value as number) < 0 || (value as number) > 100) {
+  if (
+    !Number.isInteger(value) ||
+    (value as number) < 0 ||
+    (value as number) > 100
+  ) {
     throw new ConfigError(
       `${keyPath} must be an integer between 0 and 100, got: ${String(value)}`,
-      `Set ${keyPath} to an integer between 0 and 100 in .deepl-sync.yaml.`,
+      `Set ${keyPath} to an integer between 0 and 100 in .deepl-sync.yaml.`
     );
   }
 }
@@ -232,7 +243,7 @@ function validateTmThreshold(value: unknown, keyPath: string): void {
 function validateTmModelType(
   translation: Record<string, unknown>,
   keyPath: string,
-  tmInherited: boolean,
+  tmInherited: boolean
 ): void {
   const hasTm = tmInherited || translation['translation_memory'] !== undefined;
   if (!hasTm) return;
@@ -240,16 +251,21 @@ function validateTmModelType(
   if (mt !== undefined && mt !== 'quality_optimized') {
     throw new ConfigError(
       `${keyPath}.model_type must be 'quality_optimized' when translation_memory is set, got: ${String(mt)}`,
-      `Set ${keyPath}.model_type: quality_optimized or remove translation_memory.`,
+      `Set ${keyPath}.model_type: quality_optimized or remove translation_memory.`
     );
   }
 }
 
 export function validateSyncConfig(raw: unknown): SyncConfig {
-  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) {
+  if (
+    raw === null ||
+    raw === undefined ||
+    typeof raw !== 'object' ||
+    Array.isArray(raw)
+  ) {
     throw new ConfigError(
       'Sync config must be a YAML object',
-      'Ensure .deepl-sync.yaml contains a top-level mapping (key: value pairs).',
+      'Ensure .deepl-sync.yaml contains a top-level mapping (key: value pairs).'
     );
   }
 
@@ -260,46 +276,53 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
   if (obj['version'] === undefined) {
     throw new ConfigError(
       'Sync config missing required field: version',
-      'Add version: 1 at the top of .deepl-sync.yaml.',
+      'Add version: 1 at the top of .deepl-sync.yaml.'
     );
   }
   if (obj['version'] !== 1) {
     throw new ConfigError(
       `Unsupported sync config version: ${String(obj['version'])} (expected 1)`,
-      'Set version: 1 in .deepl-sync.yaml.',
+      'Set version: 1 in .deepl-sync.yaml.'
     );
   }
 
-  if (obj['source_locale'] === undefined || typeof obj['source_locale'] !== 'string' || obj['source_locale'].trim() === '') {
+  if (
+    obj['source_locale'] === undefined ||
+    typeof obj['source_locale'] !== 'string' ||
+    obj['source_locale'].trim() === ''
+  ) {
     throw new ConfigError(
       'Sync config missing required field: source_locale',
-      'Add source_locale: <code> to .deepl-sync.yaml (e.g., source_locale: en).',
+      'Add source_locale: <code> to .deepl-sync.yaml (e.g., source_locale: en).'
     );
   }
   if (!LOCALE_CODE_RE.test(obj['source_locale'])) {
     throw new ConfigError(
       `Invalid source locale "${sanitizeForTerminal(obj['source_locale'])}": must be a BCP-47 style code (letters, digits, hyphens; no path separators or "..")`,
-      'Set source_locale in .deepl-sync.yaml to a plain code like "en" or "en-US".',
+      'Set source_locale in .deepl-sync.yaml to a plain code like "en" or "en-US".'
     );
   }
 
-  if (!Array.isArray(obj['target_locales']) || obj['target_locales'].length === 0) {
+  if (
+    !Array.isArray(obj['target_locales']) ||
+    obj['target_locales'].length === 0
+  ) {
     throw new ConfigError(
       'Sync config target_locales must be a non-empty array of strings',
-      'Add target_locales: [<code>, ...] to .deepl-sync.yaml (e.g., [de, fr]).',
+      'Add target_locales: [<code>, ...] to .deepl-sync.yaml (e.g., [de, fr]).'
     );
   }
   for (const locale of obj['target_locales']) {
     if (typeof locale !== 'string') {
       throw new ConfigError(
         'Sync config target_locales must be a non-empty array of strings',
-        'Ensure every entry in target_locales is a quoted string locale code.',
+        'Ensure every entry in target_locales is a quoted string locale code.'
       );
     }
     if (!LOCALE_CODE_RE.test(locale)) {
       throw new ConfigError(
         `Invalid target locale "${sanitizeForTerminal(locale)}": must be a BCP-47 style code (letters, digits, hyphens; no path separators or "..")`,
-        'Set entries in target_locales to plain codes like "de" or "fr-CA".',
+        'Set entries in target_locales to plain codes like "de" or "fr-CA".'
       );
     }
   }
@@ -307,14 +330,19 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
   if ((obj['target_locales'] as string[]).includes(obj['source_locale'])) {
     throw new ConfigError(
       'target_locales must not contain source_locale',
-      'Remove the source_locale value from target_locales in .deepl-sync.yaml.',
+      'Remove the source_locale value from target_locales in .deepl-sync.yaml.'
     );
   }
 
-  if (obj['buckets'] === undefined || typeof obj['buckets'] !== 'object' || obj['buckets'] === null || Array.isArray(obj['buckets'])) {
+  if (
+    obj['buckets'] === undefined ||
+    typeof obj['buckets'] !== 'object' ||
+    obj['buckets'] === null ||
+    Array.isArray(obj['buckets'])
+  ) {
     throw new ConfigError(
       'Sync config buckets must be a non-empty object',
-      'Add a buckets: mapping to .deepl-sync.yaml with at least one named bucket.',
+      'Add a buckets: mapping to .deepl-sync.yaml with at least one named bucket.'
     );
   }
 
@@ -322,16 +350,21 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
   if (Object.keys(buckets).length === 0) {
     throw new ConfigError(
       'Sync config buckets must be a non-empty object',
-      'Define at least one bucket under buckets: in .deepl-sync.yaml.',
+      'Define at least one bucket under buckets: in .deepl-sync.yaml.'
     );
   }
 
   for (const [name, bucket] of Object.entries(buckets)) {
     const safeName = sanitizeForTerminal(name);
-    if (bucket === null || bucket === undefined || typeof bucket !== 'object' || Array.isArray(bucket)) {
+    if (
+      bucket === null ||
+      bucket === undefined ||
+      typeof bucket !== 'object' ||
+      Array.isArray(bucket)
+    ) {
       throw new ConfigError(
         `Sync config bucket "${safeName}" must be an object`,
-        `Define buckets.${safeName} as a mapping with at least an include: list.`,
+        `Define buckets.${safeName} as a mapping with at least an include: list.`
       );
     }
     const b = bucket as Record<string, unknown>;
@@ -339,14 +372,14 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
     if (!Array.isArray(b['include']) || b['include'].length === 0) {
       throw new ConfigError(
         `Sync config bucket "${safeName}" must have a non-empty include array`,
-        `Add a non-empty include: glob list under buckets.${safeName} in .deepl-sync.yaml.`,
+        `Add a non-empty include: glob list under buckets.${safeName} in .deepl-sync.yaml.`
       );
     }
     for (const inc of b['include']) {
       if (typeof inc !== 'string') {
         throw new ConfigError(
           `Sync config bucket "${safeName}" include must contain only strings`,
-          `Ensure every entry in buckets.${safeName}.include is a quoted glob string.`,
+          `Ensure every entry in buckets.${safeName}.include is a quoted glob string.`
         );
       }
       // Containment must be enforced here, not only in the `sync init` wizard
@@ -356,13 +389,13 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
       if (inc.split(/[/\\]/).some((segment) => segment === '..')) {
         throw new ConfigError(
           `Sync config bucket "${safeName}" include entry "${inc}" contains a ".." traversal segment`,
-          `Use globs relative to the project root without traversal segments in buckets.${safeName}.include.`,
+          `Use globs relative to the project root without traversal segments in buckets.${safeName}.include.`
         );
       }
       if (path.isAbsolute(inc)) {
         throw new ConfigError(
           `Sync config bucket "${safeName}" include entry "${inc}" must be relative to the project root`,
-          `Replace the absolute path in buckets.${safeName}.include with a path relative to the project root.`,
+          `Replace the absolute path in buckets.${safeName}.include with a path relative to the project root.`
         );
       }
     }
@@ -370,73 +403,106 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
       if (typeof b['target_path_pattern'] !== 'string') {
         throw new ConfigError(
           `Sync config bucket "${safeName}" target_path_pattern must be a string`,
-          `Quote buckets.${safeName}.target_path_pattern as a string with {locale}.`,
+          `Quote buckets.${safeName}.target_path_pattern as a string with {locale}.`
         );
       }
       if (!b['target_path_pattern'].includes('{locale}')) {
         throw new ConfigError(
           `Sync config bucket "${safeName}" target_path_pattern must contain {locale} placeholder`,
-          `Include the {locale} placeholder in buckets.${safeName}.target_path_pattern.`,
+          `Include the {locale} placeholder in buckets.${safeName}.target_path_pattern.`
         );
       }
       if (b['target_path_pattern'].includes('..')) {
         throw new ConfigError(
           `Sync config bucket "${safeName}" target_path_pattern must not contain ".."`,
-          `Remove ".." from buckets.${safeName}.target_path_pattern in .deepl-sync.yaml.`,
+          `Remove ".." from buckets.${safeName}.target_path_pattern in .deepl-sync.yaml.`
         );
       }
       const forbidden = b['target_path_pattern']
         .split(/[/\\]/)
-        .find(seg => FORBIDDEN_TARGET_SEGMENTS.has(seg.toLowerCase()));
+        .find((seg) => FORBIDDEN_TARGET_SEGMENTS.has(seg.toLowerCase()));
       if (forbidden) {
         throw new ConfigError(
           `Sync config bucket "${safeName}" target_path_pattern must not write into "${forbidden}/"`,
-          `Point buckets.${safeName}.target_path_pattern at a locale directory outside ${forbidden}/.`,
+          `Point buckets.${safeName}.target_path_pattern at a locale directory outside ${forbidden}/.`
         );
       }
     }
   }
 
   for (const block of ['translation', 'validation', 'sync', 'tms'] as const) {
-    if (obj[block] !== undefined && (typeof obj[block] !== 'object' || Array.isArray(obj[block]) || obj[block] === null)) {
+    if (
+      obj[block] !== undefined &&
+      (typeof obj[block] !== 'object' ||
+        Array.isArray(obj[block]) ||
+        obj[block] === null)
+    ) {
       throw new ConfigError(
         `Sync config ${block} must be an object`,
-        `Define ${block}: as a mapping in .deepl-sync.yaml, or remove it.`,
+        `Define ${block}: as a mapping in .deepl-sync.yaml, or remove it.`
       );
     }
   }
 
   if (obj['translation'] !== undefined) {
-    assertOnlyKnownKeys(obj['translation'] as Record<string, unknown>, KNOWN_TRANSLATION_KEYS, 'translation');
+    assertOnlyKnownKeys(
+      obj['translation'] as Record<string, unknown>,
+      KNOWN_TRANSLATION_KEYS,
+      'translation'
+    );
     const tr = obj['translation'] as Record<string, unknown>;
-    if (tr['length_limits'] !== undefined && typeof tr['length_limits'] === 'object' && tr['length_limits'] !== null && !Array.isArray(tr['length_limits'])) {
-      assertOnlyKnownKeys(tr['length_limits'] as Record<string, unknown>, KNOWN_LENGTH_LIMITS_KEYS, 'translation.length_limits');
+    if (
+      tr['length_limits'] !== undefined &&
+      typeof tr['length_limits'] === 'object' &&
+      tr['length_limits'] !== null &&
+      !Array.isArray(tr['length_limits'])
+    ) {
+      assertOnlyKnownKeys(
+        tr['length_limits'] as Record<string, unknown>,
+        KNOWN_LENGTH_LIMITS_KEYS,
+        'translation.length_limits'
+      );
     }
     const overrides = tr['locale_overrides'];
-    if (overrides !== undefined && typeof overrides === 'object' && overrides !== null && !Array.isArray(overrides)) {
-      for (const [locale, ov] of Object.entries(overrides as Record<string, unknown>)) {
+    if (
+      overrides !== undefined &&
+      typeof overrides === 'object' &&
+      overrides !== null &&
+      !Array.isArray(overrides)
+    ) {
+      for (const [locale, ov] of Object.entries(
+        overrides as Record<string, unknown>
+      )) {
         if (ov !== null && typeof ov === 'object' && !Array.isArray(ov)) {
           assertOnlyKnownKeys(
             ov as Record<string, unknown>,
             KNOWN_LOCALE_OVERRIDE_KEYS,
-            `translation.locale_overrides.${locale}`,
+            `translation.locale_overrides.${locale}`
           );
         }
       }
     }
   }
   if (obj['validation'] !== undefined) {
-    assertOnlyKnownKeys(obj['validation'] as Record<string, unknown>, KNOWN_VALIDATION_KEYS, 'validation');
+    assertOnlyKnownKeys(
+      obj['validation'] as Record<string, unknown>,
+      KNOWN_VALIDATION_KEYS,
+      'validation'
+    );
   }
   if (obj['sync'] !== undefined) {
-    assertOnlyKnownKeys(obj['sync'] as Record<string, unknown>, KNOWN_SYNC_BEHAVIOR_KEYS, 'sync');
+    assertOnlyKnownKeys(
+      obj['sync'] as Record<string, unknown>,
+      KNOWN_SYNC_BEHAVIOR_KEYS,
+      'sync'
+    );
     const syncBlock = obj['sync'] as Record<string, unknown>;
     if (syncBlock['concurrency'] !== undefined) {
       const c = syncBlock['concurrency'];
       if (!Number.isInteger(c) || (c as number) <= 0) {
         throw new ConfigError(
           `sync.concurrency must be a positive integer, got: ${String(c)}`,
-          'Set sync.concurrency to a positive integer in .deepl-sync.yaml (default 5).',
+          'Set sync.concurrency to a positive integer in .deepl-sync.yaml (default 5).'
         );
       }
     }
@@ -445,7 +511,7 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
       if (!Number.isInteger(m) || (m as number) <= 0) {
         throw new ConfigError(
           `sync.max_scan_files must be a positive integer, got: ${String(m)}`,
-          'Set sync.max_scan_files to a positive integer in .deepl-sync.yaml (default 50000).',
+          'Set sync.max_scan_files to a positive integer in .deepl-sync.yaml (default 50000).'
         );
       }
     }
@@ -454,7 +520,7 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
       if (!Number.isInteger(s) || (s as number) <= 0) {
         throw new ConfigError(
           `sync.bak_sweep_max_age_seconds must be a positive integer (seconds), got: ${String(s)}`,
-          'Set sync.bak_sweep_max_age_seconds to a positive integer in .deepl-sync.yaml (default 300).',
+          'Set sync.bak_sweep_max_age_seconds to a positive integer in .deepl-sync.yaml (default 300).'
         );
       }
     }
@@ -466,7 +532,7 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
       ) {
         throw new ConfigError(
           'sync.limits must be an object mapping cap names to positive integers.',
-          'See docs/SYNC.md for valid keys: max_entries_per_file, max_file_bytes, max_depth, max_source_files.',
+          'See docs/SYNC.md for valid keys: max_entries_per_file, max_file_bytes, max_depth, max_source_files.'
         );
       }
       const limits = syncBlock['limits'] as Record<string, unknown>;
@@ -477,24 +543,38 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
         if (!Number.isInteger(raw) || (raw as number) <= 0) {
           throw new ConfigError(
             `sync.limits.${key} must be a positive integer, got: ${String(raw)}`,
-            `Set sync.limits.${key} to a positive integer in .deepl-sync.yaml.`,
+            `Set sync.limits.${key} to a positive integer in .deepl-sync.yaml.`
           );
         }
-        const hardMax = HARD_MAX_SYNC_LIMITS[key as keyof typeof HARD_MAX_SYNC_LIMITS];
+        const hardMax =
+          HARD_MAX_SYNC_LIMITS[key as keyof typeof HARD_MAX_SYNC_LIMITS];
         if ((raw as number) > hardMax) {
           throw new ConfigError(
             `sync.limits.${key} exceeds the hard ceiling of ${hardMax} (got: ${String(raw)}).`,
-            'Lower the value in .deepl-sync.yaml. The hard ceiling protects the parser from stack-overflow and memory-exhaustion edge cases.',
+            'Lower the value in .deepl-sync.yaml. The hard ceiling protects the parser from stack-overflow and memory-exhaustion edge cases.'
           );
         }
       }
     }
   }
   if (obj['tms'] !== undefined) {
-    assertOnlyKnownKeys(obj['tms'] as Record<string, unknown>, KNOWN_TMS_KEYS, 'tms');
+    assertOnlyKnownKeys(
+      obj['tms'] as Record<string, unknown>,
+      KNOWN_TMS_KEYS,
+      'tms'
+    );
   }
-  if (obj['context'] !== undefined && typeof obj['context'] === 'object' && obj['context'] !== null && !Array.isArray(obj['context'])) {
-    assertOnlyKnownKeys(obj['context'] as Record<string, unknown>, KNOWN_CONTEXT_KEYS, 'context');
+  if (
+    obj['context'] !== undefined &&
+    typeof obj['context'] === 'object' &&
+    obj['context'] !== null &&
+    !Array.isArray(obj['context'])
+  ) {
+    assertOnlyKnownKeys(
+      obj['context'] as Record<string, unknown>,
+      KNOWN_CONTEXT_KEYS,
+      'context'
+    );
   }
 
   const tmsBlock = obj['tms'] as Record<string, unknown> | undefined;
@@ -503,7 +583,7 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
     if (!Number.isInteger(t) || (t as number) <= 0) {
       throw new ConfigError(
         `tms.timeout_ms must be a positive integer (milliseconds), got: ${String(t)}`,
-        'Set tms.timeout_ms to a positive integer in .deepl-sync.yaml (default 30000).',
+        'Set tms.timeout_ms to a positive integer in .deepl-sync.yaml (default 30000).'
       );
     }
   }
@@ -512,24 +592,32 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
     if (!Number.isInteger(c) || (c as number) <= 0) {
       throw new ConfigError(
         `tms.push_concurrency must be a positive integer, got: ${String(c)}`,
-        'Set tms.push_concurrency to a positive integer in .deepl-sync.yaml (default 10).',
+        'Set tms.push_concurrency to a positive integer in .deepl-sync.yaml (default 10).'
       );
     }
   }
 
   const t = obj['translation'] as Record<string, unknown> | undefined;
   if (t) {
-    validateTmThreshold(t['translation_memory_threshold'], 'translation.translation_memory_threshold');
+    validateTmThreshold(
+      t['translation_memory_threshold'],
+      'translation.translation_memory_threshold'
+    );
     validateTmModelType(t, 'translation', false);
     const topLevelTm = t['translation_memory'] !== undefined;
-    const overrides = t['locale_overrides'] as Record<string, Record<string, unknown>> | undefined;
+    const overrides = t['locale_overrides'] as
+      Record<string, Record<string, unknown>> | undefined;
     if (overrides) {
       for (const [locale, ov] of Object.entries(overrides)) {
         validateTmThreshold(
           ov['translation_memory_threshold'],
-          `translation.locale_overrides.${locale}.translation_memory_threshold`,
+          `translation.locale_overrides.${locale}.translation_memory_threshold`
+        );
+        validateTmModelType(
+          ov,
+          `translation.locale_overrides.${locale}`,
+          topLevelTm
         );
-        validateTmModelType(ov, `translation.locale_overrides.${locale}`, topLevelTm);
       }
     }
   }
@@ -539,12 +627,21 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
     source_locale: obj['source_locale'],
     target_locales: obj['target_locales'] as string[],
     buckets: obj['buckets'] as Record<string, SyncBucketConfig>,
-    ...(obj['translation'] !== undefined && { translation: obj['translation'] as SyncTranslationSettings }),
-    ...(obj['validation'] !== undefined && { validation: obj['validation'] as SyncValidationSettings }),
+    ...(obj['translation'] !== undefined && {
+      translation: obj['translation'] as SyncTranslationSettings,
+    }),
+    ...(obj['validation'] !== undefined && {
+      validation: obj['validation'] as SyncValidationSettings,
+    }),
     ...(obj['sync'] !== undefined && { sync: obj['sync'] as SyncBehavior }),
     ...(Array.isArray(obj['ignore']) && { ignore: obj['ignore'] as string[] }),
     ...(obj['tms'] !== undefined && { tms: obj['tms'] as SyncTmsConfig }),
-    ...(obj["context"] !== undefined && { context: typeof obj["context"] === "boolean" ? { enabled: obj["context"] } : obj["context"] as { enabled: boolean } }),
+    ...(obj['context'] !== undefined && {
+      context:
+        typeof obj['context'] === 'boolean'
+          ? { enabled: obj['context'] }
+          : (obj['context'] as { enabled: boolean }),
+    }),
   };
 }
 
@@ -556,16 +653,16 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
 // outside target_locales is a ConfigError rather than a silent no-op.
 export function applyCliOverrides(
   config: SyncConfig,
-  overrides: SyncConfigOverrides,
+  overrides: SyncConfigOverrides
 ): SyncConfig {
   if (overrides.localeFilter !== undefined) {
     const unconfigured = overrides.localeFilter.filter(
-      (locale) => !config.target_locales.includes(locale),
+      (locale) => !config.target_locales.includes(locale)
     );
     if (unconfigured.length > 0) {
       throw new ConfigError(
         `--locale ${unconfigured.join(', ')} not in target_locales (configured: ${config.target_locales.join(', ')})`,
-        'Pass only locales listed in target_locales, or add the locale to target_locales in .deepl-sync.yaml.',
+        'Pass only locales listed in target_locales, or add the locale to target_locales in .deepl-sync.yaml.'
       );
     }
   }
@@ -579,12 +676,15 @@ export function applyCliOverrides(
   }
   if (overrides.modelType !== undefined) {
     config.translation = config.translation ?? {};
-    config.translation.model_type = overrides.modelType as SyncTranslationSettings['model_type'];
-    if (config.translation.translation_memory !== undefined
-      && config.translation.model_type !== 'quality_optimized') {
+    config.translation.model_type =
+      overrides.modelType as SyncTranslationSettings['model_type'];
+    if (
+      config.translation.translation_memory !== undefined &&
+      config.translation.model_type !== 'quality_optimized'
+    ) {
       throw new ConfigError(
         `--model-type ${overrides.modelType} is incompatible with translation_memory (requires quality_optimized)`,
-        'Pass --model-type quality_optimized, or remove translation_memory from .deepl-sync.yaml.',
+        'Pass --model-type quality_optimized, or remove translation_memory from .deepl-sync.yaml.'
       );
     }
   }
@@ -607,7 +707,7 @@ export function applyCliOverrides(
 
 export async function loadSyncConfig(
   startDir?: string,
-  overrides: SyncConfigOverrides = {},
+  overrides: SyncConfigOverrides = {}
 ): Promise<ResolvedSyncConfig> {
   let configPath: string;
 
@@ -616,7 +716,7 @@ export async function loadSyncConfig(
     if (!fs.existsSync(configPath)) {
       throw new ConfigError(
         `Sync config file not found: ${configPath}`,
-        'Check the --config path, or create .deepl-sync.yaml at that location.',
+        'Check the --config path, or create .deepl-sync.yaml at that location.'
       );
     }
   } else {
@@ -624,7 +724,7 @@ export async function loadSyncConfig(
     if (!found) {
       throw new ConfigError(
         `No ${SYNC_CONFIG_FILENAME} found in ${startDir ?? process.cwd()} or any parent directory`,
-        "Run 'deepl sync init' to create one, or create .deepl-sync.yaml manually.",
+        "Run 'deepl sync init' to create one, or create .deepl-sync.yaml manually."
       );
     }
     configPath = found;
@@ -641,7 +741,7 @@ export async function loadSyncConfig(
     const message = err instanceof Error ? err.message : String(err);
     throw new ConfigError(
       `Failed to parse YAML in ${configPath}: ${message}`,
-      'Fix the YAML syntax in .deepl-sync.yaml (check indentation, quoting, and braces).',
+      'Fix the YAML syntax in .deepl-sync.yaml (check indentation, quoting, and braces).'
     );
   }
 
@@ -665,12 +765,12 @@ function warnOnInlineTmsCredentials(tms: SyncTmsConfig | undefined): void {
   if (!tms) return;
   if (tms.api_key && !process.env['TMS_API_KEY']) {
     process.stderr.write(
-      'Warning: TMS api_key is set in .deepl-sync.yaml. Use the TMS_API_KEY env var instead to avoid committing secrets.\n',
+      'Warning: TMS api_key is set in .deepl-sync.yaml. Use the TMS_API_KEY env var instead to avoid committing secrets.\n'
     );
   }
   if (tms.token && !process.env['TMS_TOKEN']) {
     process.stderr.write(
-      'Warning: TMS token is set in .deepl-sync.yaml. Use the TMS_TOKEN env var instead to avoid committing secrets.\n',
+      'Warning: TMS token is set in .deepl-sync.yaml. Use the TMS_TOKEN env var instead to avoid committing secrets.\n'
     );
   }
 }
diff --git a/src/sync/sync-context.ts b/src/sync/sync-context.ts
index 88916068..1bf4a9a8 100644
--- a/src/sync/sync-context.ts
+++ b/src/sync/sync-context.ts
@@ -5,7 +5,12 @@ import { Logger } from '../utils/logger.js';
 import { ConfigError, ValidationError } from '../utils/errors.js';
 import { extractGlobLiteralPrefix } from '../utils/glob-prefix.js';
 
-export const DEFAULT_FUNCTION_NAMES = ['t', 'i18n.t', '$t', 'intl.formatMessage'];
+export const DEFAULT_FUNCTION_NAMES = [
+  't',
+  'i18n.t',
+  '$t',
+  'intl.formatMessage',
+];
 
 // Hard ceiling on scan_paths fan-out. User-controlled `scan_paths` globs can
 // expand to every file under a large source tree; on shared CI with slow
@@ -87,7 +92,8 @@ const ROLE_MAP: Record<string, string> = {
 
 const ROLE_MODIFIERS = ['primary', 'secondary', 'main', 'default'];
 
-const ELEMENT_TAG_RE = /<(button|a|h[1-6]|p|span|label|th|td|li|option|input|textarea|select|summary|figcaption|legend|caption|dt|dd|title)[\s>/]/g;
+const ELEMENT_TAG_RE =
+  /<(button|a|h[1-6]|p|span|label|th|td|li|option|input|textarea|select|summary|figcaption|legend|caption|dt|dd|title)[\s>/]/g;
 
 // Format parsers flatten nested keys using either `.` (e.g., JSON) or `\0`
 // (e.g., YAML, to tolerate literal `.` characters in YAML keys). The
@@ -102,13 +108,19 @@ export function sectionContextKey(key: string): string {
   const sep = keyPathSeparator(key);
   const segments = key.split(sep);
   if (segments.length < 2) return '';
-  return segments.slice(0, -1).filter((s) => !/^\d+$/.test(s)).join(sep);
+  return segments
+    .slice(0, -1)
+    .filter((s) => !/^\d+$/.test(s))
+    .join(sep);
 }
 
 export function sectionToContext(sectionKey: string): string {
   if (!sectionKey) return '';
   const sep = keyPathSeparator(sectionKey);
-  const display = sep === '\0' ? sectionKey.split(sep).join(' > ') : sectionKey.replace(/\./g, ' > ');
+  const display =
+    sep === '\0'
+      ? sectionKey.split(sep).join(' > ')
+      : sectionKey.replace(/\./g, ' > ');
   return `Used in the ${display} section.`;
 }
 
@@ -150,7 +162,11 @@ function resolveRole(segment: string): string {
   for (let i = 1; i <= parts.length; i++) {
     const prefix = parts.slice(0, i).join('_');
     const suffix = parts.slice(i);
-    if (ROLE_MAP[prefix] && suffix.length > 0 && suffix.every((s) => ROLE_MODIFIERS.includes(s))) {
+    if (
+      ROLE_MAP[prefix] &&
+      suffix.length > 0 &&
+      suffix.every((s) => ROLE_MODIFIERS.includes(s))
+    ) {
       return `${capitalize(suffix.join(' '))} ${ROLE_MAP[prefix].toLowerCase()}`;
     }
   }
@@ -179,29 +195,23 @@ export function buildKeyPatterns(functionNames: string[]): RegExp[] {
     if (name === 'intl.formatMessage') {
       return new RegExp(
         `\\bintl\\.formatMessage\\(\\s*\\{[^}]*id\\s*:\\s*['"]([^'"]+)['"]`,
-        'g',
+        'g'
       );
     }
 
     const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
     if (name.includes('.')) {
-      return new RegExp(
-        `\\b${escaped}\\(\\s*['"]([^'"]+)['"]\\s*[,)]`,
-        'g',
-      );
+      return new RegExp(`\\b${escaped}\\(\\s*['"]([^'"]+)['"]\\s*[,)]`, 'g');
     }
 
     if (name.startsWith('$')) {
-      return new RegExp(
-        `${escaped}\\(\\s*['"]([^'"]+)['"]\\s*[,)]`,
-        'g',
-      );
+      return new RegExp(`${escaped}\\(\\s*['"]([^'"]+)['"]\\s*[,)]`, 'g');
     }
 
     return new RegExp(
       `(?:^|[^.\\w])${escaped}\\(\\s*['"]([^'"]+)['"]\\s*[,)]`,
-      'g',
+      'g'
     );
   });
 }
@@ -209,7 +219,7 @@ export function buildKeyPatterns(functionNames: string[]): RegExp[] {
 function extractSurroundingCode(
   lines: string[],
   lineIndex: number,
-  contextLines: number,
+  contextLines: number
 ): string {
   const start = Math.max(0, lineIndex - contextLines);
   const end = Math.min(lines.length - 1, lineIndex + contextLines);
@@ -220,7 +230,7 @@ export function extractContextFromSource(
   content: string,
   filePath: string,
   functionNames: string[],
-  contextLines: number,
+  contextLines: number
 ): ContextMatch[] {
   const patterns = buildKeyPatterns(functionNames);
   const lines = content.split('\n');
@@ -243,7 +253,11 @@ export function extractContextFromSource(
             key,
             filePath,
             line: lineIndex + 1,
-            surroundingCode: extractSurroundingCode(lines, lineIndex, contextLines),
+            surroundingCode: extractSurroundingCode(
+              lines,
+              lineIndex,
+              contextLines
+            ),
             matchedFunction: fnName,
           });
         }
@@ -254,7 +268,10 @@ export function extractContextFromSource(
   return matches;
 }
 
-export function synthesizeContext(matches: ContextMatch[], options?: { key?: string }): string {
+export function synthesizeContext(
+  matches: ContextMatch[],
+  options?: { key?: string }
+): string {
   const keyContext = options?.key ? keyPathToContext(options.key) : '';
 
   if (matches.length === 0 && !keyContext) {
@@ -270,7 +287,9 @@ export function synthesizeContext(matches: ContextMatch[], options?: { key?: str
   const displayed = matches.slice(0, MAX_LOCATIONS);
 
   for (const m of displayed) {
-    parts.push(`Used as ${m.matchedFunction}() in ${m.filePath}:${m.line}:\n${m.surroundingCode}`);
+    parts.push(
+      `Used as ${m.matchedFunction}() in ${m.filePath}:${m.line}:\n${m.surroundingCode}`
+    );
   }
 
   if (matches.length > MAX_LOCATIONS) {
@@ -286,34 +305,32 @@ export function synthesizeContext(matches: ContextMatch[], options?: { key?: str
   return result;
 }
 
-export function buildTemplateLiteralPatterns(functionNames: string[]): RegExp[] {
-  return functionNames.map((name) => {
-    // intl.formatMessage uses object syntax, not template literals for keys
-    if (name === 'intl.formatMessage') {
-      return null;
-    }
+export function buildTemplateLiteralPatterns(
+  functionNames: string[]
+): RegExp[] {
+  return functionNames
+    .map((name) => {
+      // intl.formatMessage uses object syntax, not template literals for keys
+      if (name === 'intl.formatMessage') {
+        return null;
+      }
 
-    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
-    if (name.includes('.')) {
-      return new RegExp(
-        `\\b${escaped}\\(\\s*\`([^\`]+)\`\\s*[,)]`,
-        'g',
-      );
-    }
+      if (name.includes('.')) {
+        return new RegExp(`\\b${escaped}\\(\\s*\`([^\`]+)\`\\s*[,)]`, 'g');
+      }
+
+      if (name.startsWith('$')) {
+        return new RegExp(`${escaped}\\(\\s*\`([^\`]+)\`\\s*[,)]`, 'g');
+      }
 
-    if (name.startsWith('$')) {
       return new RegExp(
-        `${escaped}\\(\\s*\`([^\`]+)\`\\s*[,)]`,
-        'g',
+        `(?:^|[^.\\w])${escaped}\\(\\s*\`([^\`]+)\`\\s*[,)]`,
+        'g'
       );
-    }
-
-    return new RegExp(
-      `(?:^|[^.\\w])${escaped}\\(\\s*\`([^\`]+)\`\\s*[,)]`,
-      'g',
-    );
-  }).filter((p): p is RegExp => p !== null);
+    })
+    .filter((p): p is RegExp => p !== null);
 }
 
 export function templateToGlobPattern(template: string): string {
@@ -324,7 +341,7 @@ export function extractTemplateLiteralMatches(
   content: string,
   filePath: string,
   functionNames: string[],
-  contextLines: number,
+  contextLines: number
 ): TemplatePatternMatch[] {
   const patterns = buildTemplateLiteralPatterns(functionNames);
   const lines = content.split('\n');
@@ -332,7 +349,9 @@ export function extractTemplateLiteralMatches(
 
   // Build a filtered function name list matching the patterns array
   // (intl.formatMessage is excluded from template patterns)
-  const filteredNames = functionNames.filter((name) => name !== 'intl.formatMessage');
+  const filteredNames = functionNames.filter(
+    (name) => name !== 'intl.formatMessage'
+  );
 
   for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
     const line = lines[lineIndex]!;
@@ -351,7 +370,11 @@ export function extractTemplateLiteralMatches(
             pattern: templateContent,
             filePath,
             line: lineIndex + 1,
-            surroundingCode: extractSurroundingCode(lines, lineIndex, contextLines),
+            surroundingCode: extractSurroundingCode(
+              lines,
+              lineIndex,
+              contextLines
+            ),
             matchedFunction: fnName,
           });
         }
@@ -364,11 +387,13 @@ export function extractTemplateLiteralMatches(
 
 export function resolveTemplatePatterns(
   patterns: TemplatePatternMatch[],
-  knownKeys: string[],
+  knownKeys: string[]
 ): Map<string, ContextMatch[]> {
   const result = new Map<string, ContextMatch[]>();
   const seen = new Set<string>();
-  const deduped = patterns.filter((t) => !seen.has(t.pattern) && seen.add(t.pattern));
+  const deduped = patterns.filter(
+    (t) => !seen.has(t.pattern) && seen.add(t.pattern)
+  );
   const regexByPattern = new Map<string, RegExp>();
 
   for (const tmpl of deduped) {
@@ -378,7 +403,10 @@ export function resolveTemplatePatterns(
       // Escape all regex metacharacters, then turn the glob * into a
       // single-segment match. Construction stays guarded so a scanned
       // pattern can never abort the whole sync.
-      const regexStr = '^' + glob.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\\\*/g, '[^.]+') + '$';
+      const regexStr =
+        '^' +
+        glob.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\\\*/g, '[^.]+') +
+        '$';
       try {
         regex = new RegExp(regexStr);
       } catch {
@@ -410,7 +438,7 @@ export function resolveTemplatePatterns(
 }
 
 export async function extractAllKeyContexts(
-  options: ContextExtractionOptions,
+  options: ContextExtractionOptions
 ): Promise<ContextExtractionResult> {
   const functionNames = options.functionNames ?? DEFAULT_FUNCTION_NAMES;
   const contextLines = options.contextLines ?? 3;
@@ -419,26 +447,35 @@ export async function extractAllKeyContexts(
   const allTemplatePatterns: TemplatePatternMatch[] = [];
 
   const normalizedRoot = path.resolve(options.rootDir);
-  const scanPatterns = options.scanPaths.map((scanPath) => {
-    let literalPrefix: string;
-    try {
-      literalPrefix = extractGlobLiteralPrefix(scanPath);
-    } catch (err) {
-      if (err instanceof ConfigError) {
-        Logger.warn(`Skipping scan_path "${scanPath}": ${err.message}`);
+  const scanPatterns = options.scanPaths
+    .map((scanPath) => {
+      let literalPrefix: string;
+      try {
+        literalPrefix = extractGlobLiteralPrefix(scanPath);
+      } catch (err) {
+        if (err instanceof ConfigError) {
+          Logger.warn(`Skipping scan_path "${scanPath}": ${err.message}`);
+          return null;
+        }
+        throw err;
+      }
+      const prefixResolved = path.isAbsolute(literalPrefix)
+        ? path.resolve(literalPrefix)
+        : path.resolve(options.rootDir, literalPrefix);
+      if (
+        prefixResolved !== normalizedRoot &&
+        !prefixResolved.startsWith(normalizedRoot + path.sep)
+      ) {
+        Logger.warn(
+          `Skipping scan_path "${scanPath}": resolves outside project root`
+        );
         return null;
       }
-      throw err;
-    }
-    const prefixResolved = path.isAbsolute(literalPrefix)
-      ? path.resolve(literalPrefix)
-      : path.resolve(options.rootDir, literalPrefix);
-    if (prefixResolved !== normalizedRoot && !prefixResolved.startsWith(normalizedRoot + path.sep)) {
-      Logger.warn(`Skipping scan_path "${scanPath}": resolves outside project root`);
-      return null;
-    }
-    return path.isAbsolute(scanPath) ? scanPath : path.join(options.rootDir, scanPath);
-  }).filter((p): p is string => p !== null);
+      return path.isAbsolute(scanPath)
+        ? scanPath
+        : path.join(options.rootDir, scanPath);
+    })
+    .filter((p): p is string => p !== null);
 
   const files = await fg(scanPatterns, {
     cwd: options.rootDir,
@@ -450,7 +487,7 @@ export async function extractAllKeyContexts(
   const maxFiles = options.maxScanFiles ?? SCAN_PATHS_MAX_FILES;
   if (files.length > maxFiles) {
     throw new ValidationError(
-      `scan_paths matched ${files.length} files (> max ${maxFiles}); narrow the pattern or set sync.max_scan_files.`,
+      `scan_paths matched ${files.length} files (> max ${maxFiles}); narrow the pattern or set sync.max_scan_files.`
     );
   }
 
@@ -464,7 +501,12 @@ export async function extractAllKeyContexts(
 
     const relPath = path.relative(options.rootDir, file);
 
-    const matches = extractContextFromSource(content, relPath, functionNames, contextLines);
+    const matches = extractContextFromSource(
+      content,
+      relPath,
+      functionNames,
+      contextLines
+    );
     for (const match of matches) {
       const existing = allMatches.get(match.key);
       if (existing) {
@@ -474,7 +516,12 @@ export async function extractAllKeyContexts(
       }
     }
 
-    const templateMatches = extractTemplateLiteralMatches(content, relPath, functionNames, contextLines);
+    const templateMatches = extractTemplateLiteralMatches(
+      content,
+      relPath,
+      functionNames,
+      contextLines
+    );
     allTemplatePatterns.push(...templateMatches);
   }
 
@@ -482,7 +529,9 @@ export async function extractAllKeyContexts(
 
   for (const [key, matches] of allMatches) {
     const firstMatch = matches[0];
-    const elementType = firstMatch ? extractElementType(firstMatch.surroundingCode) : null;
+    const elementType = firstMatch
+      ? extractElementType(firstMatch.surroundingCode)
+      : null;
     keyContexts.set(key, {
       key,
       context: synthesizeContext(matches, { key }),
diff --git a/src/sync/sync-differ.ts b/src/sync/sync-differ.ts
index 199976bb..b47e9fd6 100644
--- a/src/sync/sync-differ.ts
+++ b/src/sync/sync-differ.ts
@@ -14,7 +14,7 @@ import { computeSourceHash } from './sync-lock.js';
 function hasOutdatedLocale(
   lockEntry: SyncLockEntry,
   sourceHash: string,
-  targetLocales: readonly string[],
+  targetLocales: readonly string[]
 ): boolean {
   return targetLocales.some((locale) => {
     const translation = lockEntry.translations[locale];
@@ -31,7 +31,7 @@ function hasOutdatedLocale(
 export function computeDiff(
   lockEntries: Record<string, SyncLockEntry>,
   currentEntries: ExtractedEntry[],
-  targetLocales?: readonly string[],
+  targetLocales?: readonly string[]
 ): SyncDiff[] {
   const currentKeys = new Set(currentEntries.map((e) => e.key));
   const currentMap = new Map(currentEntries.map((e) => [e.key, e]));
@@ -40,19 +40,39 @@ export function computeDiff(
   for (const [key, entry] of currentMap) {
     const lockEntry = lockEntries[key];
     if (!lockEntry) {
-      diffs.push({ key, status: 'new', value: entry.value, metadata: entry.metadata });
-    } else if (computeSourceHash(entry.value, entry.metadata) === lockEntry.source_hash) {
+      diffs.push({
+        key,
+        status: 'new',
+        value: entry.value,
+        metadata: entry.metadata,
+      });
+    } else if (
+      computeSourceHash(entry.value, entry.metadata) === lockEntry.source_hash
+    ) {
       // Scope the check to the configured target locales when they are known: a
       // whole-entry `some(failed)` check would mark the key stale for EVERY
       // locale as soon as one had failed, re-translating locales that are already
       // fine and overwriting human-edited files.
       const needsWork = targetLocales
         ? hasOutdatedLocale(lockEntry, lockEntry.source_hash, targetLocales)
-        : Object.values(lockEntry.translations).some(t => t.status === 'failed');
+        : Object.values(lockEntry.translations).some(
+            (t) => t.status === 'failed'
+          );
       if (needsWork) {
-        diffs.push({ key, status: 'stale', value: entry.value, previous_hash: lockEntry.source_hash, metadata: entry.metadata });
+        diffs.push({
+          key,
+          status: 'stale',
+          value: entry.value,
+          previous_hash: lockEntry.source_hash,
+          metadata: entry.metadata,
+        });
       } else {
-        diffs.push({ key, status: 'current', value: entry.value, metadata: entry.metadata });
+        diffs.push({
+          key,
+          status: 'current',
+          value: entry.value,
+          metadata: entry.metadata,
+        });
       }
     } else {
       diffs.push({
@@ -69,7 +89,11 @@ export function computeDiff(
     if (!currentKeys.has(key)) {
       const lockEntry = lockEntries[key];
       if (lockEntry) {
-        diffs.push({ key, status: 'deleted', previous_hash: lockEntry.source_hash });
+        diffs.push({
+          key,
+          status: 'deleted',
+          previous_hash: lockEntry.source_hash,
+        });
       }
     }
   }
diff --git a/src/sync/sync-export.ts b/src/sync/sync-export.ts
index 4284f1d4..27f1ff4c 100644
--- a/src/sync/sync-export.ts
+++ b/src/sync/sync-export.ts
@@ -17,20 +17,20 @@ export interface ExportResult {
 export async function exportTranslations(
   config: ResolvedSyncConfig,
   registry: FormatRegistry,
-  options?: ExportOptions,
+  options?: ExportOptions
 ): Promise<ExportResult> {
   try {
     await sweepStaleBackups(
       config.projectRoot,
       resolveBakSweepAgeMs(config.sync?.bak_sweep_max_age_seconds),
-      config.buckets,
+      config.buckets
     );
   } catch {
     /* best-effort */
   }
 
   const locales = options?.localeFilter?.length
-    ? config.target_locales.filter(l => options.localeFilter!.includes(l))
+    ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
     : config.target_locales;
 
   const units: string[] = [];
@@ -42,10 +42,12 @@ export async function exportTranslations(
       const escaped = escapeXml(entry.value);
       units.push(
         `    <trans-unit id="${escapeXml(entry.key)}" resname="${escapeXml(entry.key)}">` +
-        `\n      <source>${escaped}</source>` +
-        (entry.context ? `\n      <note>${escapeXml(entry.context)}</note>` : '') +
-        `\n      <note from="location">${escapeXml(walked.relPath)}</note>` +
-        `\n    </trans-unit>`,
+          `\n      <source>${escaped}</source>` +
+          (entry.context
+            ? `\n      <note>${escapeXml(entry.context)}</note>`
+            : '') +
+          `\n      <note from="location">${escapeXml(walked.relPath)}</note>` +
+          `\n    </trans-unit>`
       );
     }
   }
@@ -53,10 +55,11 @@ export async function exportTranslations(
   const xliff = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     '<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">',
-    ...locales.map(locale =>
-      `  <file source-language="${escapeXml(config.source_locale)}" target-language="${escapeXml(locale)}" datatype="plaintext">` +
-      `\n    <body>\n${units.join('\n')}\n    </body>` +
-      `\n  </file>`,
+    ...locales.map(
+      (locale) =>
+        `  <file source-language="${escapeXml(config.source_locale)}" target-language="${escapeXml(locale)}" datatype="plaintext">` +
+        `\n    <body>\n${units.join('\n')}\n    </body>` +
+        `\n  </file>`
     ),
     '</xliff>',
     '',
diff --git a/src/sync/sync-finalize.ts b/src/sync/sync-finalize.ts
index 2f7f453d..8c02a38a 100644
--- a/src/sync/sync-finalize.ts
+++ b/src/sync/sync-finalize.ts
@@ -35,7 +35,9 @@ export function finalizeSyncResult(i: FinalizeInputs): SyncResult {
   // locale", so this is `some`, not `every`: one locale failing completely
   // must fail the run even when the others succeeded.
   // A locale that translated nothing and has no failures is simply up to date.
-  const anyLocaleFailed = i.fileResults.some(fr => fr.translated === 0 && fr.failed > 0);
+  const anyLocaleFailed = i.fileResults.some(
+    (fr) => fr.translated === 0 && fr.failed > 0
+  );
 
   return {
     success: !i.driftDetected && !anyLocaleFailed,
diff --git a/src/sync/sync-glossary-report.ts b/src/sync/sync-glossary-report.ts
index c23742ac32eee9e6139d7fc8682be12893a9e35c..ca79f1e88666e925ef465a05f06ceaeb27b5d553 100644
GIT binary patch
delta 154
zcmbO(aZX~xYi1rU1%=|0qRhN>9WI5*4_PERAv`-fuF1kI#gp4v;st<8kQ6B>On%E^
z&kPjYti$TZWDAxBsZda`*Go?=(MZe8NexIW$<V}*$;nSn%t=KS-#m@|Ix`zY;pALy
J&&k`l69DSRC~5!z

delta 86
zcmX>nF<oNAYi9Q1lA_GKbe+lHnH48XvJ^AwOzvTcpB%%=Ir%S(?Pgn6KPDM_z4X))
mjkL_1)PTg23{40(CqFqcCslLv3HIyElb3RP0yVzlP5=NX{T@dE

diff --git a/src/sync/sync-glossary.ts b/src/sync/sync-glossary.ts
index cadb2a64..1f2c17aa 100644
--- a/src/sync/sync-glossary.ts
+++ b/src/sync/sync-glossary.ts
@@ -27,7 +27,9 @@ function isUnusableTerm(text: string): boolean {
  * parsed back out of TSV, which trims each field. Comparing raw local terms
  * against that could never be equal, so every sync re-uploaded the dictionary.
  */
-function normalizeForComparison(entries: Record<string, string>): Map<string, string> {
+function normalizeForComparison(
+  entries: Record<string, string>
+): Map<string, string> {
   const normalized = new Map<string, string>();
   for (const [source, target] of Object.entries(entries)) {
     normalized.set(source.trim(), target.trim());
@@ -35,7 +37,10 @@ function normalizeForComparison(entries: Record<string, string>): Map<string, st
   return normalized;
 }
 
-function entriesEqual(a: Record<string, string>, b: Record<string, string>): boolean {
+function entriesEqual(
+  a: Record<string, string>,
+  b: Record<string, string>
+): boolean {
   const normalizedA = normalizeForComparison(a);
   const normalizedB = normalizeForComparison(b);
   if (normalizedA.size !== normalizedB.size) return false;
@@ -55,7 +60,7 @@ export class SyncGlossaryManager {
    */
   extractTerms(
     sourceEntries: Map<string, string>,
-    targetEntries: Map<string, Map<string, string>>,
+    targetEntries: Map<string, Map<string, string>>
   ): Map<string, Record<string, string>> {
     const result = new Map<string, Record<string, string>>();
 
@@ -75,7 +80,10 @@ export class SyncGlossaryManager {
     for (const [locale, localeEntries] of targetEntries) {
       // Null-prototype: keyed by untrusted source strings, which may be
       // named after Object.prototype members.
-      const terms: Record<string, string> = Object.create(null) as Record<string, string>;
+      const terms: Record<string, string> = Object.create(null) as Record<
+        string,
+        string
+      >;
 
       for (const [sourceText, keys] of sourceTextToKeys) {
         if (keys.size < MIN_KEY_COUNT) continue;
@@ -100,10 +108,13 @@ export class SyncGlossaryManager {
 
         if (!isConsistent || consistentTranslation === undefined) continue;
 
-        if (isUnusableTerm(sourceText) || isUnusableTerm(consistentTranslation)) {
+        if (
+          isUnusableTerm(sourceText) ||
+          isUnusableTerm(consistentTranslation)
+        ) {
           const sampleKey = keys.values().next().value;
           Logger.warn(
-            `Skipping glossary term from key "${sampleKey}" (${locale}): source or translation is empty or contains a tab, carriage return or newline.`,
+            `Skipping glossary term from key "${sampleKey}" (${locale}): source or translation is empty or contains a tab, carriage return or newline.`
           );
           continue;
         }
@@ -125,10 +136,13 @@ export class SyncGlossaryManager {
    */
   async syncGlossaries(
     sourceEntries: Map<string, string>,
-    targetEntries: Map<string, Map<string, string>>,
+    targetEntries: Map<string, Map<string, string>>
   ): Promise<Record<string, string>> {
     const terms = this.extractTerms(sourceEntries, targetEntries);
-    const glossaryIds: Record<string, string> = Object.create(null) as Record<string, string>;
+    const glossaryIds: Record<string, string> = Object.create(null) as Record<
+      string,
+      string
+    >;
 
     for (const targetLocale of this.options.targetLocales) {
       const localeTerms = terms.get(targetLocale);
@@ -143,25 +157,32 @@ export class SyncGlossaryManager {
 
       // One rejected dictionary must not abandon the remaining locales.
       try {
-        const existing = await this.options.glossaryService.getGlossaryByName(name);
+        const existing =
+          await this.options.glossaryService.getGlossaryByName(name);
 
         if (existing) {
-          const currentEntries = await this.options.glossaryService.getGlossaryEntries(
-            existing.glossary_id,
-            sourceLang,
-            targetLang,
-          );
+          const currentEntries =
+            await this.options.glossaryService.getGlossaryEntries(
+              existing.glossary_id,
+              sourceLang,
+              targetLang
+            );
 
           glossaryIds[localePair] = existing.glossary_id;
 
           if (!entriesEqual(currentEntries, localeTerms)) {
-            await this.options.glossaryService.updateGlossary(existing.glossary_id, {
-              dictionaries: [{
-                sourceLang,
-                targetLang,
-                entries: localeTerms,
-              }],
-            });
+            await this.options.glossaryService.updateGlossary(
+              existing.glossary_id,
+              {
+                dictionaries: [
+                  {
+                    sourceLang,
+                    targetLang,
+                    entries: localeTerms,
+                  },
+                ],
+              }
+            );
             Logger.info(`Updated glossary "${name}" (${existing.glossary_id})`);
           }
         } else {
@@ -169,7 +190,7 @@ export class SyncGlossaryManager {
             name,
             sourceLang,
             [targetLang],
-            localeTerms,
+            localeTerms
           );
           glossaryIds[localePair] = created.glossary_id;
           Logger.info(`Created glossary "${name}" (${created.glossary_id})`);
@@ -177,7 +198,7 @@ export class SyncGlossaryManager {
       } catch (error) {
         delete glossaryIds[localePair];
         Logger.warn(
-          `Glossary sync failed for ${localePair} (glossary "${name}", ${Object.keys(localeTerms).length} terms): ${errorMessage(error)}`,
+          `Glossary sync failed for ${localePair} (glossary "${name}", ${Object.keys(localeTerms).length} terms): ${errorMessage(error)}`
         );
       }
     }
diff --git a/src/sync/sync-init-validate.ts b/src/sync/sync-init-validate.ts
index 2e9a0b04..a364d88a 100644
--- a/src/sync/sync-init-validate.ts
+++ b/src/sync/sync-init-validate.ts
@@ -36,17 +36,29 @@ export interface TargetLocaleChoice {
 // everything else in the registry remains available but unchecked so the
 // wizard does not silently bill for 30+ locales on a bare [Enter].
 const DEFAULT_CHECKED: ReadonlySet<string> = new Set([
-  'de', 'es', 'fr', 'it', 'ja', 'ko', 'pt-br', 'zh',
+  'de',
+  'es',
+  'fr',
+  'it',
+  'ja',
+  'ko',
+  'pt-br',
+  'zh',
 ]);
 
-export function validateSyncInitFlags(flags: SyncInitFlagValidation): SyncInitValidationResult {
+export function validateSyncInitFlags(
+  flags: SyncInitFlagValidation
+): SyncInitValidationResult {
   const warnings: string[] = [];
 
-  const rawTargets = flags.targetLocales.split(',').map((l) => l.trim()).filter((l) => l.length > 0);
+  const rawTargets = flags.targetLocales
+    .split(',')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
   if (rawTargets.length === 0) {
     throw new ValidationError(
       '--target-locales is empty after parsing.',
-      'Provide at least one target locale, e.g. --target-locales de,fr,ja',
+      'Provide at least one target locale, e.g. --target-locales de,fr,ja'
     );
   }
 
@@ -57,7 +69,7 @@ export function validateSyncInitFlags(flags: SyncInitFlagValidation): SyncInitVa
     if (code.toLowerCase() === sourceLc) {
       throw new ValidationError(
         `--source-locale "${source}" also appears in --target-locales ("${code}").`,
-        `Remove "${code}" from --target-locales; it's the source locale.`,
+        `Remove "${code}" from --target-locales; it's the source locale.`
       );
     }
     const lc = code.toLowerCase();
@@ -65,13 +77,13 @@ export function validateSyncInitFlags(flags: SyncInitFlagValidation): SyncInitVa
       const first = seen.get(lc)!;
       throw new ValidationError(
         `Duplicate target locale in --target-locales: "${first}" and "${code}".`,
-        'Each target locale must appear at most once.',
+        'Each target locale must appear at most once.'
       );
     }
     if (!LOCALE_CODE_RE.test(code)) {
       throw new ValidationError(
         `Malformed locale code in --target-locales: "${code}".`,
-        'Use a BCP-47 style code, e.g. "de", "ja", "pt-BR", "zh-Hans".',
+        'Use a BCP-47 style code, e.g. "de", "ja", "pt-BR", "zh-Hans".'
       );
     }
     seen.set(lc, code);
@@ -81,7 +93,7 @@ export function validateSyncInitFlags(flags: SyncInitFlagValidation): SyncInitVa
   if (filePath.split(/[/\\]/).some((seg) => seg === '..')) {
     throw new ValidationError(
       `--path "${filePath}" contains a ".." traversal segment.`,
-      'Use a path relative to the project root without traversal segments.',
+      'Use a path relative to the project root without traversal segments.'
     );
   }
 
@@ -92,7 +104,7 @@ export function validateSyncInitFlags(flags: SyncInitFlagValidation): SyncInitVa
     if (!fs.existsSync(abs)) {
       warnings.push(
         `--path "${filePath}" does not exist yet; the config will still be written. ` +
-        `Make sure the source file is present before running "deepl sync".`,
+          `Make sure the source file is present before running "deepl sync".`
       );
     }
   }
diff --git a/src/sync/sync-init.ts b/src/sync/sync-init.ts
index 2d69d6b6..a846a3ca 100644
--- a/src/sync/sync-init.ts
+++ b/src/sync/sync-init.ts
@@ -5,7 +5,10 @@ import fg from 'fast-glob';
 import { SYNC_CONFIG_FILENAME } from './sync-config.js';
 import { safeReadFileSync } from '../utils/safe-read-file.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
-import { createDefaultRegistry, type FormatRegistry } from '../formats/index.js';
+import {
+  createDefaultRegistry,
+  type FormatRegistry,
+} from '../formats/index.js';
 
 export interface DetectedProject {
   format: string;
@@ -151,7 +154,11 @@ export const DETECTION_PATTERNS: DetectionPattern[] = [
   // root-level XLIFF is CAT-tool dump territory (Trados/memoQ/Xcode `.xcloc`
   // extracts) and a false-positive magnet. Canonical Angular layouts stay.
   {
-    globs: ['src/locale/messages.xlf', 'src/locale/*.xlf', 'src/locale/*.xliff'],
+    globs: [
+      'src/locale/messages.xlf',
+      'src/locale/*.xlf',
+      'src/locale/*.xliff',
+    ],
     format: 'xliff',
     sourceLocale: 'en',
     patternTemplate: 'src/locale/messages.{locale}.xlf',
@@ -186,7 +193,11 @@ export const DETECTION_PATTERNS: DetectionPattern[] = [
   // Xcode String Catalog — multi-locale (all locales in one file). The same
   // file is the target for every locale; no target_path_pattern needed.
   {
-    globs: ['Localizable.xcstrings', 'Resources/Localizable.xcstrings', '*.xcstrings'],
+    globs: [
+      'Localizable.xcstrings',
+      'Resources/Localizable.xcstrings',
+      '*.xcstrings',
+    ],
     format: 'xcstrings',
     sourceLocale: 'en',
     patternTemplate: '',
@@ -224,7 +235,7 @@ export const DETECTION_PATTERNS: DetectionPattern[] = [
 ];
 
 const PACKAGE_JSON_HINTS: Record<string, string> = {
-  'i18next': 'json',
+  i18next: 'json',
   'react-intl': 'json',
   'react-i18next': 'json',
   'next-intl': 'json',
@@ -232,7 +243,7 @@ const PACKAGE_JSON_HINTS: Record<string, string> = {
   'ngx-translate': 'json',
   '@angular/localize': 'xliff',
   'gettext-parser': 'po',
-  'flutter_localizations': 'arb',
+  flutter_localizations: 'arb',
 };
 
 export function detectFromPackageJson(rootDir: string): string | undefined {
@@ -242,23 +253,30 @@ export function detectFromPackageJson(rootDir: string): string | undefined {
     // file would be JSON-parsed and the CLI would act on whatever dependency
     // hints it found there.
     const content = safeReadFileSync(pkgPath, 'utf-8');
-    const pkg = JSON.parse(content) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+    const pkg = JSON.parse(content) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
     const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
     for (const [dep, format] of Object.entries(PACKAGE_JSON_HINTS)) {
       if (dep in allDeps) return format;
     }
-  } catch { /* no package.json or parse error */ }
+  } catch {
+    /* no package.json or parse error */
+  }
   return undefined;
 }
 
-export async function detectI18nFiles(rootDir: string): Promise<DetectedProject[]> {
+export async function detectI18nFiles(
+  rootDir: string
+): Promise<DetectedProject[]> {
   const detected: DetectedProject[] = [];
   let registry: FormatRegistry | undefined;
 
   for (const pattern of DETECTION_PATTERNS) {
     if (pattern.requires) {
       const allMarkersPresent = pattern.requires.every((marker) =>
-        fs.existsSync(path.join(rootDir, marker)),
+        fs.existsSync(path.join(rootDir, marker))
       );
       if (!allMarkersPresent) continue;
     }
@@ -350,11 +368,19 @@ export function generateSyncConfig(opts: {
  * so its directory becomes the project root that detection and the generated
  * globs are relative to.
  */
-export function resolveInitConfigPath(cwd: string, configPath?: string): string {
-  return configPath ? path.resolve(cwd, configPath) : path.join(cwd, SYNC_CONFIG_FILENAME);
+export function resolveInitConfigPath(
+  cwd: string,
+  configPath?: string
+): string {
+  return configPath
+    ? path.resolve(cwd, configPath)
+    : path.join(cwd, SYNC_CONFIG_FILENAME);
 }
 
-export async function writeSyncConfig(configPath: string, content: string): Promise<string> {
+export async function writeSyncConfig(
+  configPath: string,
+  content: string
+): Promise<string> {
   await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
   await atomicWriteFile(configPath, content, 'utf-8');
   return configPath;
diff --git a/src/sync/sync-instructions.ts b/src/sync/sync-instructions.ts
index f3e457a0..89c1f7f9 100644
--- a/src/sync/sync-instructions.ts
+++ b/src/sync/sync-instructions.ts
@@ -10,7 +10,16 @@ import { Logger } from '../utils/logger.js';
 export const MAX_INSTRUCTIONS = 5;
 export const MAX_INSTRUCTION_LENGTH = 2000;
 
-const SUPPORTED_BASE_LOCALES = new Set(['de', 'en', 'es', 'fr', 'it', 'ja', 'ko', 'zh']);
+const SUPPORTED_BASE_LOCALES = new Set([
+  'de',
+  'en',
+  'es',
+  'fr',
+  'it',
+  'ja',
+  'ko',
+  'zh',
+]);
 
 export const CUSTOM_INSTRUCTION_LOCALES: Set<string> = SUPPORTED_BASE_LOCALES;
 
@@ -44,7 +53,7 @@ export const DEFAULT_INSTRUCTION_TEMPLATES: Record<string, string> = {
 
 export function generateElementInstruction(
   elementType: string | null | undefined,
-  userTemplates?: Record<string, string>,
+  userTemplates?: Record<string, string>
 ): string | undefined {
   if (elementType === null || elementType === undefined) return undefined;
 
@@ -57,7 +66,7 @@ export function generateElementInstruction(
 
 export function mergeInstructions(
   userInstructions: string[] | undefined,
-  autoInstruction: string | undefined,
+  autoInstruction: string | undefined
 ): string[] | undefined {
   const parts: string[] = [];
 
@@ -72,7 +81,7 @@ export function mergeInstructions(
   if (parts.length === 0) return undefined;
 
   let truncatedLength = false;
-  const capped = parts.map(instruction => {
+  const capped = parts.map((instruction) => {
     if (instruction.length > MAX_INSTRUCTION_LENGTH) {
       truncatedLength = true;
       return instruction.slice(0, MAX_INSTRUCTION_LENGTH);
@@ -81,11 +90,15 @@ export function mergeInstructions(
   });
 
   if (truncatedLength) {
-    Logger.warn(`One or more instructions exceeded ${MAX_INSTRUCTION_LENGTH} characters and were truncated.`);
+    Logger.warn(
+      `One or more instructions exceeded ${MAX_INSTRUCTION_LENGTH} characters and were truncated.`
+    );
   }
 
   if (capped.length > MAX_INSTRUCTIONS) {
-    Logger.warn(`Instructions count (${capped.length}) exceeds maximum of ${MAX_INSTRUCTIONS}; extra instructions dropped.`);
+    Logger.warn(
+      `Instructions count (${capped.length}) exceeds maximum of ${MAX_INSTRUCTIONS}; extra instructions dropped.`
+    );
     return capped.slice(0, MAX_INSTRUCTIONS);
   }
 
@@ -99,15 +112,30 @@ export function mergeInstructions(
 // Industry-standard approximations (IBM, W3C localization guidelines).
 // Not calculated from our data. Users can override via length_limits.expansion_factors.
 export const DEFAULT_EXPANSION_FACTORS: Record<string, number> = {
-  de: 1.3, es: 1.25, fr: 1.3, it: 1.25,
-  'pt-br': 1.25, 'pt-pt': 1.25,
-  ja: 0.5, ko: 0.7, zh: 0.5,
-  ar: 1.2, he: 1.0, nl: 1.1,
-  pl: 1.1, ru: 1.1, tr: 1.1,
+  de: 1.3,
+  es: 1.25,
+  fr: 1.3,
+  it: 1.25,
+  'pt-br': 1.25,
+  'pt-pt': 1.25,
+  ja: 0.5,
+  ko: 0.7,
+  zh: 0.5,
+  ar: 1.2,
+  he: 1.0,
+  nl: 1.1,
+  pl: 1.1,
+  ru: 1.1,
+  tr: 1.1,
 };
 
 export const LENGTH_CONSTRAINED_ELEMENTS: Set<string> = new Set([
-  'button', 'th', 'label', 'option', 'input', 'title',
+  'button',
+  'th',
+  'label',
+  'option',
+  'input',
+  'title',
 ]);
 
 const MIN_LENGTH_CHARS = 5;
@@ -116,7 +144,7 @@ export function generateLengthInstruction(
   sourceText: string,
   elementType: string | null | undefined,
   locale: string,
-  config?: { expansion_factors?: Record<string, number> },
+  config?: { expansion_factors?: Record<string, number> }
 ): string | undefined {
   if (elementType === null || elementType === undefined) return undefined;
   if (!LENGTH_CONSTRAINED_ELEMENTS.has(elementType)) return undefined;
@@ -126,7 +154,8 @@ export function generateLengthInstruction(
     : DEFAULT_EXPANSION_FACTORS;
 
   const normalizedLocale = locale.toLowerCase();
-  const factor = factors[normalizedLocale] ?? factors[extractBaseLocale(normalizedLocale)];
+  const factor =
+    factors[normalizedLocale] ?? factors[extractBaseLocale(normalizedLocale)];
   if (factor === undefined) return undefined;
 
   const max = Math.ceil(sourceText.length * factor * 1.1);
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 96471133..418e6843 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -9,15 +9,28 @@ import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncBucketConfig, SyncDiff, SyncLockEntry } from './types.js';
 import type { KeyContext } from './sync-context.js';
 import { sectionContextKey, sectionToContext } from './sync-context.js';
-import { supportsCustomInstructions, generateElementInstruction, mergeInstructions, generateLengthInstruction } from './sync-instructions.js';
+import {
+  supportsCustomInstructions,
+  generateElementInstruction,
+  mergeInstructions,
+  generateLengthInstruction,
+} from './sync-instructions.js';
 import { validateBatch } from './translation-validator.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
 import { BACKUP_SUFFIX } from './sync-bak-cleanup.js';
 import { Logger } from '../utils/logger.js';
-import { preserveVariables, restorePlaceholders } from '../utils/text-preservation.js';
-import { expandPlurals, detectIcu, reassembleIcu, writebackPlurals } from './sync-message-preprocess.js';
+import {
+  preserveVariables,
+  restorePlaceholders,
+} from '../utils/text-preservation.js';
+import {
+  expandPlurals,
+  detectIcu,
+  reassembleIcu,
+  writebackPlurals,
+} from './sync-message-preprocess.js';
 import type { SyncProgressEvent, SyncFileResult } from './sync-service.js';
 
 export interface LocaleTranslatorContext {
@@ -61,14 +74,27 @@ export class LocaleTranslator {
     private readonly resolvedGlossaryId: string | undefined,
     private readonly resolvedTmId: string | undefined,
     private readonly forceBatch: boolean | undefined,
-    private readonly onProgress: ((e: SyncProgressEvent) => void) | undefined,
+    private readonly onProgress: ((e: SyncProgressEvent) => void) | undefined
   ) {}
 
-  async translate(ctx: LocaleTranslatorContext): Promise<TranslateLocaleResult> {
-    const { locale, relPath, content, parser, diffs, toTranslate,
-      fileLockEntries, existingTargetEntries, keyContexts,
-      localeGlossaryIds, localeTmIds,
-      bucketConfig, isMultiLocale } = ctx;
+  async translate(
+    ctx: LocaleTranslatorContext
+  ): Promise<TranslateLocaleResult> {
+    const {
+      locale,
+      relPath,
+      content,
+      parser,
+      diffs,
+      toTranslate,
+      fileLockEntries,
+      existingTargetEntries,
+      keyContexts,
+      localeGlossaryIds,
+      localeTmIds,
+      bucketConfig,
+      isMultiLocale,
+    } = ctx;
     const config = this.config;
     const resolvedGlossaryId = this.resolvedGlossaryId;
     const resolvedTmId = this.resolvedTmId;
@@ -82,28 +108,36 @@ export class LocaleTranslator {
       glossaryId: localeGlossaryIds.get(locale) ?? resolvedGlossaryId,
       translationMemoryId: localeTmIds.get(locale) ?? resolvedTmId,
       translationMemoryThreshold:
-        localeOverrides?.translation_memory_threshold ?? config.translation?.translation_memory_threshold,
+        localeOverrides?.translation_memory_threshold ??
+        config.translation?.translation_memory_threshold,
       modelType: config.translation?.model_type,
-      customInstructions: localeOverrides?.custom_instructions ?? config.translation?.custom_instructions,
+      customInstructions:
+        localeOverrides?.custom_instructions ??
+        config.translation?.custom_instructions,
       styleId: localeOverrides?.style_id ?? config.translation?.style_id,
       showBilledCharacters: true,
     };
 
     // Deep-clone metadata per locale to prevent concurrent mutation
-    const localeDiffs = toTranslate.map(d => ({
+    const localeDiffs = toTranslate.map((d) => ({
       ...d,
-      metadata: d.metadata ? JSON.parse(JSON.stringify(d.metadata)) as Record<string, unknown> : undefined,
+      metadata: d.metadata
+        ? (JSON.parse(JSON.stringify(d.metadata)) as Record<string, unknown>)
+        : undefined,
     }));
 
     const textsToTranslate = localeDiffs
-      .map(d => d.value)
+      .map((d) => d.value)
       .filter((v): v is string => v !== undefined);
 
-    const { extendedTexts: pluralExpanded, pluralSlots } = expandPlurals(textsToTranslate, localeDiffs);
+    const { extendedTexts: pluralExpanded, pluralSlots } = expandPlurals(
+      textsToTranslate,
+      localeDiffs
+    );
     const { extendedTexts, icuMappings } = detectIcu(pluralExpanded);
 
     const preservationMaps: Map<string, string>[] = [];
-    const protectedTexts = extendedTexts.map(text => {
+    const protectedTexts = extendedTexts.map((text) => {
       const preservationMap = new Map<string, string>();
       const protected_ = preserveVariables(text, preservationMap);
       preservationMaps.push(preservationMap);
@@ -118,18 +152,30 @@ export class LocaleTranslator {
 
     if (forceBatch === true || localeDiffs.length <= 1) {
       // --batch mode or single key: use existing batch behavior
-      const contextForSingle = localeDiffs.length === 1
-        ? (config.context?.overrides?.[localeDiffs[0]?.key ?? ''] ?? keyContexts.get(localeDiffs[0]?.key ?? '')?.context)
-        : undefined;
+      const contextForSingle =
+        localeDiffs.length === 1
+          ? (config.context?.overrides?.[localeDiffs[0]?.key ?? ''] ??
+            keyContexts.get(localeDiffs[0]?.key ?? '')?.context)
+          : undefined;
       if (contextForSingle && !forceBatch) {
         contextSentKeys.add(localeDiffs[0]!.key);
       }
-      const translationOpts: TranslationOptions = { ...baseTranslationOpts, context: contextForSingle };
-      results = await this.translationService.translateBatch(protectedTexts, translationOpts);
+      const translationOpts: TranslationOptions = {
+        ...baseTranslationOpts,
+        context: contextForSingle,
+      };
+      results = await this.translationService.translateBatch(
+        protectedTexts,
+        translationOpts
+      );
       for (let i = 0; i < localeDiffs.length; i++) {
         this.onProgress?.({
-          type: 'key-translated', locale, file: relPath,
-          key: localeDiffs[i]!.key, translated: i + 1, totalKeys: localeDiffs.length,
+          type: 'key-translated',
+          locale,
+          file: relPath,
+          key: localeDiffs[i]!.key,
+          translated: i + 1,
+          totalKeys: localeDiffs.length,
         });
       }
     } else {
@@ -141,13 +187,18 @@ export class LocaleTranslator {
 
       for (let i = 0; i < localeDiffs.length; i++) {
         const diff = localeDiffs[i]!;
-        const keyContext = config.context?.overrides?.[diff.key] ?? keyContexts.get(diff.key)?.context;
+        const keyContext =
+          config.context?.overrides?.[diff.key] ??
+          keyContexts.get(diff.key)?.context;
         if (keyContext) {
           // Path B: per-key context takes priority
           contextIndices.push(i);
         } else if (localeSupportsInstructions) {
           const elementType = keyContexts.get(diff.key)?.elementType;
-          const instruction = generateElementInstruction(elementType, config.translation?.instruction_templates);
+          const instruction = generateElementInstruction(
+            elementType,
+            config.translation?.instruction_templates
+          );
           if (instruction) {
             // Path C: batch by element type with shared instructions
             const group = instructionGroups.get(elementType!) ?? [];
@@ -161,7 +212,9 @@ export class LocaleTranslator {
         }
       }
 
-      results = new Array<TranslationResult | null>(protectedTexts.length).fill(null);
+      results = new Array<TranslationResult | null>(protectedTexts.length).fill(
+        null
+      );
 
       // Path A: batch translation for keys without context or instructions
       if (batchIndices.length > 0) {
@@ -178,15 +231,25 @@ export class LocaleTranslator {
             batchPMapIndices.push(slot.textIndex);
           }
         }
-        const batchOpts: TranslationOptions = { ...baseTranslationOpts, context: undefined };
-        const batchResults = await this.translationService.translateBatch(batchTexts, batchOpts);
+        const batchOpts: TranslationOptions = {
+          ...baseTranslationOpts,
+          context: undefined,
+        };
+        const batchResults = await this.translationService.translateBatch(
+          batchTexts,
+          batchOpts
+        );
         for (let bi = 0; bi < batchPMapIndices.length; bi++) {
           results[batchPMapIndices[bi]!] = batchResults[bi] ?? null;
         }
         for (let bi = 0; bi < batchIndices.length; bi++) {
           this.onProgress?.({
-            type: 'key-translated', locale, file: relPath,
-            key: localeDiffs[batchIndices[bi]!]!.key, translated: bi + 1, totalKeys: localeDiffs.length,
+            type: 'key-translated',
+            locale,
+            file: relPath,
+            key: localeDiffs[batchIndices[bi]!]!.key,
+            translated: bi + 1,
+            totalKeys: localeDiffs.length,
           });
         }
       }
@@ -194,12 +257,21 @@ export class LocaleTranslator {
       // Path C: batch by element type with shared custom_instructions
       let pathCCompleted = batchIndices.length;
       for (const [elementType, indices] of instructionGroups) {
-        instructionGroupCounts.set(elementType, (instructionGroupCounts.get(elementType) ?? 0) + indices.length);
+        instructionGroupCounts.set(
+          elementType,
+          (instructionGroupCounts.get(elementType) ?? 0) + indices.length
+        );
         for (const idx of indices) {
           instructionSentKeys.add(localeDiffs[idx]!.key);
         }
-        const instruction = generateElementInstruction(elementType, config.translation?.instruction_templates)!;
-        const groupInstructions = mergeInstructions(baseTranslationOpts.customInstructions, instruction);
+        const instruction = generateElementInstruction(
+          elementType,
+          config.translation?.instruction_templates
+        )!;
+        const groupInstructions = mergeInstructions(
+          baseTranslationOpts.customInstructions,
+          instruction
+        );
 
         const groupTexts: string[] = [];
         const groupPMapIndices: number[] = [];
@@ -215,16 +287,27 @@ export class LocaleTranslator {
           }
         }
 
-        const groupOpts: TranslationOptions = { ...baseTranslationOpts, context: undefined, customInstructions: groupInstructions };
-        const groupResults = await this.translationService.translateBatch(groupTexts, groupOpts);
+        const groupOpts: TranslationOptions = {
+          ...baseTranslationOpts,
+          context: undefined,
+          customInstructions: groupInstructions,
+        };
+        const groupResults = await this.translationService.translateBatch(
+          groupTexts,
+          groupOpts
+        );
         for (let gi = 0; gi < groupPMapIndices.length; gi++) {
           results[groupPMapIndices[gi]!] = groupResults[gi] ?? null;
         }
         for (const idx of indices) {
           pathCCompleted++;
           this.onProgress?.({
-            type: 'key-translated', locale, file: relPath,
-            key: localeDiffs[idx]!.key, translated: pathCCompleted, totalKeys: localeDiffs.length,
+            type: 'key-translated',
+            locale,
+            file: relPath,
+            key: localeDiffs[idx]!.key,
+            translated: pathCCompleted,
+            totalKeys: localeDiffs.length,
           });
         }
       }
@@ -243,7 +326,11 @@ export class LocaleTranslator {
         for (const idx of contextIndices) {
           const diff = localeDiffs[idx]!;
           const section = sectionContextKey(diff.key);
-          if (forcePerKey || config.context?.overrides?.[diff.key] || !section) {
+          if (
+            forcePerKey ||
+            config.context?.overrides?.[diff.key] ||
+            !section
+          ) {
             perKeyIndices.push(idx);
           } else {
             const group = sectionGroups.get(section) ?? [];
@@ -258,13 +345,21 @@ export class LocaleTranslator {
 
           // Track element instructions for keys in this section batch
           for (const idx of indices) {
-            const elementType = keyContexts.get(localeDiffs[idx]!.key)?.elementType;
+            const elementType = keyContexts.get(
+              localeDiffs[idx]!.key
+            )?.elementType;
             const autoInstruction = localeSupportsInstructions
-              ? generateElementInstruction(elementType, config.translation?.instruction_templates)
+              ? generateElementInstruction(
+                  elementType,
+                  config.translation?.instruction_templates
+                )
               : undefined;
             if (autoInstruction && elementType) {
               instructionSentKeys.add(localeDiffs[idx]!.key);
-              instructionGroupCounts.set(elementType, (instructionGroupCounts.get(elementType) ?? 0) + 1);
+              instructionGroupCounts.set(
+                elementType,
+                (instructionGroupCounts.get(elementType) ?? 0) + 1
+              );
             }
           }
 
@@ -282,16 +377,26 @@ export class LocaleTranslator {
             }
           }
 
-          const groupOpts: TranslationOptions = { ...baseTranslationOpts, context: sectionCtx };
-          const groupResults = await this.translationService.translateBatch(groupTexts, groupOpts);
+          const groupOpts: TranslationOptions = {
+            ...baseTranslationOpts,
+            context: sectionCtx,
+          };
+          const groupResults = await this.translationService.translateBatch(
+            groupTexts,
+            groupOpts
+          );
           for (let gi = 0; gi < groupPMapIndices.length; gi++) {
             results[groupPMapIndices[gi]!] = groupResults[gi] ?? null;
           }
           for (const idx of indices) {
             perKeyCompleted++;
             this.onProgress?.({
-              type: 'key-translated', locale, file: relPath,
-              key: localeDiffs[idx]!.key, translated: perKeyCompleted, totalKeys: localeDiffs.length,
+              type: 'key-translated',
+              locale,
+              file: relPath,
+              key: localeDiffs[idx]!.key,
+              translated: perKeyCompleted,
+              totalKeys: localeDiffs.length,
             });
           }
         }
@@ -299,45 +404,82 @@ export class LocaleTranslator {
         // Path B2: per-key for override keys and single-segment keys
         if (perKeyIndices.length > 0) {
           const concurrency = config.sync?.concurrency ?? 5;
-          await mapWithConcurrency(perKeyIndices, async (idx) => {
-            const diff = localeDiffs[idx]!;
-            const keyContext = config.context?.overrides?.[diff.key] ?? keyContexts.get(diff.key)?.context ?? '';
-
-            const elementType = keyContexts.get(diff.key)?.elementType;
-            const autoInstruction = localeSupportsInstructions
-              ? generateElementInstruction(elementType, config.translation?.instruction_templates)
-              : undefined;
-            if (autoInstruction && elementType) {
-              instructionSentKeys.add(diff.key);
-              instructionGroupCounts.set(elementType, (instructionGroupCounts.get(elementType) ?? 0) + 1);
-            }
-            const lengthInstruction = (localeSupportsInstructions && config.translation?.length_limits?.enabled)
-              ? generateLengthInstruction(diff.value ?? '', elementType, locale, config.translation.length_limits)
-              : undefined;
-            let perKeyInstructions = mergeInstructions(baseTranslationOpts.customInstructions, autoInstruction);
-            perKeyInstructions = mergeInstructions(perKeyInstructions, lengthInstruction);
-
-            const keyOpts: TranslationOptions = { ...baseTranslationOpts, context: keyContext, customInstructions: perKeyInstructions };
-
-            const keyTexts = [protectedTexts[idx]!];
-            const keyTextIndices = [idx];
-            for (const slot of pluralSlots) {
-              if (slot.diffIndex === idx) {
-                keyTexts.push(protectedTexts[slot.textIndex]!);
-                keyTextIndices.push(slot.textIndex);
+          await mapWithConcurrency(
+            perKeyIndices,
+            async (idx) => {
+              const diff = localeDiffs[idx]!;
+              const keyContext =
+                config.context?.overrides?.[diff.key] ??
+                keyContexts.get(diff.key)?.context ??
+                '';
+
+              const elementType = keyContexts.get(diff.key)?.elementType;
+              const autoInstruction = localeSupportsInstructions
+                ? generateElementInstruction(
+                    elementType,
+                    config.translation?.instruction_templates
+                  )
+                : undefined;
+              if (autoInstruction && elementType) {
+                instructionSentKeys.add(diff.key);
+                instructionGroupCounts.set(
+                  elementType,
+                  (instructionGroupCounts.get(elementType) ?? 0) + 1
+                );
+              }
+              const lengthInstruction =
+                localeSupportsInstructions &&
+                config.translation?.length_limits?.enabled
+                  ? generateLengthInstruction(
+                      diff.value ?? '',
+                      elementType,
+                      locale,
+                      config.translation.length_limits
+                    )
+                  : undefined;
+              let perKeyInstructions = mergeInstructions(
+                baseTranslationOpts.customInstructions,
+                autoInstruction
+              );
+              perKeyInstructions = mergeInstructions(
+                perKeyInstructions,
+                lengthInstruction
+              );
+
+              const keyOpts: TranslationOptions = {
+                ...baseTranslationOpts,
+                context: keyContext,
+                customInstructions: perKeyInstructions,
+              };
+
+              const keyTexts = [protectedTexts[idx]!];
+              const keyTextIndices = [idx];
+              for (const slot of pluralSlots) {
+                if (slot.diffIndex === idx) {
+                  keyTexts.push(protectedTexts[slot.textIndex]!);
+                  keyTextIndices.push(slot.textIndex);
+                }
               }
-            }
 
-            const keyResults = await this.translationService.translateBatch(keyTexts, keyOpts);
-            for (let ki = 0; ki < keyTextIndices.length; ki++) {
-              results[keyTextIndices[ki]!] = keyResults[ki] ?? null;
-            }
-            perKeyCompleted++;
-            this.onProgress?.({
-              type: 'key-translated', locale, file: relPath,
-              key: diff.key, translated: perKeyCompleted, totalKeys: localeDiffs.length,
-            });
-          }, concurrency);
+              const keyResults = await this.translationService.translateBatch(
+                keyTexts,
+                keyOpts
+              );
+              for (let ki = 0; ki < keyTextIndices.length; ki++) {
+                results[keyTextIndices[ki]!] = keyResults[ki] ?? null;
+              }
+              perKeyCompleted++;
+              this.onProgress?.({
+                type: 'key-translated',
+                locale,
+                file: relPath,
+                key: diff.key,
+                translated: perKeyCompleted,
+                totalKeys: localeDiffs.length,
+              });
+            },
+            concurrency
+          );
         }
       }
     }
@@ -350,7 +492,12 @@ export class LocaleTranslator {
       }
     }
 
-    await reassembleIcu(this.translationService, results, icuMappings, baseTranslationOpts);
+    await reassembleIcu(
+      this.translationService,
+      results,
+      icuMappings,
+      baseTranslationOpts
+    );
     writebackPlurals(results, pluralSlots, localeDiffs);
 
     for (let i = 0; i < localeDiffs.length; i++) {
@@ -359,14 +506,16 @@ export class LocaleTranslator {
       if (!result || !diff.metadata) continue;
 
       if (diff.metadata['msgid_plural'] !== undefined) {
-        const forms = (diff.metadata['plural_forms'] as Record<string, string>) ?? {};
+        const forms =
+          (diff.metadata['plural_forms'] as Record<string, string>) ?? {};
         forms['msgstr[0]'] = result.text;
         diff.metadata['plural_forms'] = forms;
       }
 
-      const androidPlurals = diff.metadata['plurals'] as Array<{quantity: string; value: string}> | undefined;
+      const androidPlurals = diff.metadata['plurals'] as
+        Array<{ quantity: string; value: string }> | undefined;
       if (androidPlurals) {
-        const primary = androidPlurals.find(p => p.value === diff.value);
+        const primary = androidPlurals.find((p) => p.value === diff.value);
         if (primary) primary.value = result.text;
       }
     }
@@ -403,12 +552,15 @@ export class LocaleTranslator {
       }
     }
 
-    const successfulKeys: string[] = translatedEntries.map(te => te.key);
+    const successfulKeys: string[] = translatedEntries.map((te) => te.key);
 
     let localeValidationWarnings = 0;
     let localeValidationErrors = 0;
-    if (config.validation?.validate_after_sync !== false && config.validation?.check_placeholders !== false) {
-      const validationInputs = translatedEntries.map(e => ({
+    if (
+      config.validation?.validate_after_sync !== false &&
+      config.validation?.check_placeholders !== false
+    ) {
+      const validationInputs = translatedEntries.map((e) => ({
         key: e.key,
         source: e.value,
         translation: e.translation,
@@ -423,16 +575,18 @@ export class LocaleTranslator {
     }
 
     // Use target file translations for current keys
-    const existingTranslations = existingTargetEntries.get(locale) ?? new Map<string, string>();
+    const existingTranslations =
+      existingTargetEntries.get(locale) ?? new Map<string, string>();
     const allTranslatedEntries: TranslatedEntry[] = [...translatedEntries];
-    const currentDiffs = diffs.filter(d => d.status === 'current');
+    const currentDiffs = diffs.filter((d) => d.status === 'current');
     const currentDiffByKey = new Map(currentDiffs.map((d) => [d.key, d]));
     const untranslatedCurrentKeys: string[] = [];
     for (const cd of currentDiffs) {
       if (cd.value === undefined) continue;
       const existingTranslation = existingTranslations.get(cd.key);
       const lockEntry = fileLockEntries[cd.key];
-      const hasLocaleTranslation = lockEntry?.translations[locale] !== undefined;
+      const hasLocaleTranslation =
+        lockEntry?.translations[locale] !== undefined;
       if (existingTranslation !== undefined) {
         // Present in the target file — including a deliberately empty string,
         // which must be preserved rather than treated as missing.
@@ -451,7 +605,7 @@ export class LocaleTranslator {
         untranslatedCurrentKeys.push(cd.key);
         if (hasLocaleTranslation) {
           Logger.verbose(
-            `[verbose] ${locale}: lockfile records a translation for "${cd.key}" but the target file has none — re-translating`,
+            `[verbose] ${locale}: lockfile records a translation for "${cd.key}" but the target file has none — re-translating`
           );
         }
       }
@@ -460,25 +614,34 @@ export class LocaleTranslator {
     // Translate current keys that have no translation for this locale (new locale scenario)
     if (untranslatedCurrentKeys.length > 0) {
       const textsForNewLocale = untranslatedCurrentKeys
-        .map(key => currentDiffByKey.get(key)!)
-        .map(d => d.value!)
+        .map((key) => currentDiffByKey.get(key)!)
+        .map((d) => d.value!)
         .filter((v): v is string => v !== null && v !== undefined);
       if (textsForNewLocale.length > 0) {
         const nlPreservationMaps: Map<string, string>[] = [];
-        const nlProtectedTexts = textsForNewLocale.map(text => {
+        const nlProtectedTexts = textsForNewLocale.map((text) => {
           const pMap = new Map<string, string>();
           const protected_ = preserveVariables(text, pMap);
           nlPreservationMaps.push(pMap);
           return protected_;
         });
 
-        const newLocaleOpts: TranslationOptions = { ...baseTranslationOpts, context: undefined };
-        const newLocaleResults = await this.translationService.translateBatch(nlProtectedTexts, newLocaleOpts);
+        const newLocaleOpts: TranslationOptions = {
+          ...baseTranslationOpts,
+          context: undefined,
+        };
+        const newLocaleResults = await this.translationService.translateBatch(
+          nlProtectedTexts,
+          newLocaleOpts
+        );
 
         for (let ri = 0; ri < newLocaleResults.length; ri++) {
           const pMap = nlPreservationMaps[ri];
           if (newLocaleResults[ri] && pMap && pMap.size > 0) {
-            newLocaleResults[ri]!.text = restorePlaceholders(newLocaleResults[ri]!.text, pMap);
+            newLocaleResults[ri]!.text = restorePlaceholders(
+              newLocaleResults[ri]!.text,
+              pMap
+            );
           }
         }
 
@@ -513,14 +676,22 @@ export class LocaleTranslator {
 
     const targetRelPath = isMultiLocale
       ? relPath
-      : resolveTargetPath(relPath, config.source_locale, locale, bucketConfig.target_path_pattern);
+      : resolveTargetPath(
+          relPath,
+          config.source_locale,
+          locale,
+          bucketConfig.target_path_pattern
+        );
     const targetAbsPath = path.join(config.projectRoot, targetRelPath);
     assertPathWithinRoot(targetAbsPath, config.projectRoot);
 
     let templateContent = content;
     let targetExists = false;
     try {
-      const existingTargetContent = await fs.promises.readFile(targetAbsPath, 'utf-8');
+      const existingTargetContent = await fs.promises.readFile(
+        targetAbsPath,
+        'utf-8'
+      );
       if (existingTargetContent.trim()) {
         templateContent = existingTargetContent;
       }
@@ -529,13 +700,19 @@ export class LocaleTranslator {
       templateContent = content;
     }
 
-    if (targetExists && config.sync?.backup !== false && !this.backupPaths.has(targetAbsPath + BACKUP_SUFFIX)) {
+    if (
+      targetExists &&
+      config.sync?.backup !== false &&
+      !this.backupPaths.has(targetAbsPath + BACKUP_SUFFIX)
+    ) {
       const bakPath = targetAbsPath + BACKUP_SUFFIX;
       try {
         await fs.promises.copyFile(targetAbsPath, bakPath);
         this.backupPaths.add(bakPath);
       } catch (err) {
-        Logger.warn(`Failed to backup ${targetRelPath}: ${err instanceof Error ? err.message : String(err)}`);
+        Logger.warn(
+          `Failed to backup ${targetRelPath}: ${err instanceof Error ? err.message : String(err)}`
+        );
       }
     }
 
diff --git a/src/sync/sync-lock.ts b/src/sync/sync-lock.ts
index 44760045..b53c21d5 100644
--- a/src/sync/sync-lock.ts
+++ b/src/sync/sync-lock.ts
@@ -9,27 +9,43 @@ function filesystemSafeTimestamp(): string {
   return new Date().toISOString().replace(/:/g, '-').replace(/\.\d+/, '');
 }
 
-function backupLockFile(lockFilePath: string, raw: string, tag: string): string | null {
+function backupLockFile(
+  lockFilePath: string,
+  raw: string,
+  tag: string
+): string | null {
   const backupPath = `${lockFilePath}.bak-${tag}-${filesystemSafeTimestamp()}`;
   try {
     fs.writeFileSync(backupPath, raw, 'utf-8');
     return backupPath;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    Logger.warn(`Failed to write lock file backup to ${backupPath}: ${message}`);
+    Logger.warn(
+      `Failed to write lock file backup to ${backupPath}: ${message}`
+    );
     return null;
   }
 }
 
-export function computeSourceHash(text: string, metadata?: Record<string, unknown>): string {
+export function computeSourceHash(
+  text: string,
+  metadata?: Record<string, unknown>
+): string {
   let input = text;
   if (metadata) {
-    const plurals = metadata['plurals'] ?? metadata['msgid_plural'] ?? metadata['plural_forms'];
+    const plurals =
+      metadata['plurals'] ??
+      metadata['msgid_plural'] ??
+      metadata['plural_forms'];
     if (plurals) {
       input += '\0' + JSON.stringify(plurals);
     }
   }
-  return crypto.createHash('sha256').update(input, 'utf-8').digest('hex').substring(0, 12);
+  return crypto
+    .createHash('sha256')
+    .update(input, 'utf-8')
+    .digest('hex')
+    .substring(0, 12);
 }
 
 export function createEmptyLockFile(sourceLocale: string): SyncLockFile {
@@ -72,7 +88,10 @@ export function sortedKeysReplacer(_key: string, value: unknown): unknown {
   // Null-prototype: `out['__proto__'] = v` on a plain object invokes the
   // prototype setter, so an i18n key of that name would vanish from the
   // serialized lockfile on every write.
-  const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  const out: Record<string, unknown> = Object.create(null) as Record<
+    string,
+    unknown
+  >;
   for (const k of sortedKeys) {
     out[k] = src[k];
   }
@@ -85,7 +104,10 @@ export function sortedKeysReplacer(_key: string, value: unknown): unknown {
 const lockFileMutationVersion = new WeakMap<SyncLockFile, number>();
 
 function bumpMutationVersion(lockFile: SyncLockFile): void {
-  lockFileMutationVersion.set(lockFile, (lockFileMutationVersion.get(lockFile) ?? 0) + 1);
+  lockFileMutationVersion.set(
+    lockFile,
+    (lockFileMutationVersion.get(lockFile) ?? 0) + 1
+  );
 }
 
 function recomputeStats(lockFile: SyncLockFile): void {
@@ -121,7 +143,9 @@ export class SyncLockManager {
       parsed = JSON.parse(raw);
     } catch {
       const backup = backupLockFile(this.lockFilePath, raw, 'corrupt');
-      const suffix = backup ? ` Previous lock file backed up to ${backup}.` : '';
+      const suffix = backup
+        ? ` Previous lock file backed up to ${backup}.`
+        : '';
       Logger.warn(`Lock file corrupted, performing full sync.${suffix}`);
       return createEmptyLockFile('');
     }
@@ -129,22 +153,35 @@ export class SyncLockManager {
     const obj = parsed as Record<string, unknown>;
     if (obj['version'] === undefined) {
       const backup = backupLockFile(this.lockFilePath, raw, 'v-unknown');
-      const suffix = backup ? ` Previous lock file backed up to ${backup}.` : '';
-      Logger.warn(`Lock file corrupted (missing version), performing full sync.${suffix}`);
+      const suffix = backup
+        ? ` Previous lock file backed up to ${backup}.`
+        : '';
+      Logger.warn(
+        `Lock file corrupted (missing version), performing full sync.${suffix}`
+      );
       return createEmptyLockFile('');
     }
     if (obj['version'] !== LOCK_FILE_VERSION) {
-      const versionTag = typeof obj['version'] === 'number' ? `v${obj['version']}` : 'v-unknown';
+      const versionTag =
+        typeof obj['version'] === 'number' ? `v${obj['version']}` : 'v-unknown';
       const backup = backupLockFile(this.lockFilePath, raw, versionTag);
-      const suffix = backup ? ` Previous lock file backed up to ${backup}.` : '';
+      const suffix = backup
+        ? ` Previous lock file backed up to ${backup}.`
+        : '';
       Logger.warn(
-        `Unsupported lock file version ${obj['version']} (expected ${LOCK_FILE_VERSION}), performing full sync.${suffix}`,
+        `Unsupported lock file version ${obj['version']} (expected ${LOCK_FILE_VERSION}), performing full sync.${suffix}`
       );
       return createEmptyLockFile('');
     }
     if (!obj['entries'] || typeof obj['entries'] !== 'object') {
-      const backup = backupLockFile(this.lockFilePath, raw, `v${LOCK_FILE_VERSION}-no-entries`);
-      const suffix = backup ? ` Previous lock file backed up to ${backup}.` : '';
+      const backup = backupLockFile(
+        this.lockFilePath,
+        raw,
+        `v${LOCK_FILE_VERSION}-no-entries`
+      );
+      const suffix = backup
+        ? ` Previous lock file backed up to ${backup}.`
+        : '';
       Logger.warn(`Lock file missing entries, performing full sync.${suffix}`);
       return createEmptyLockFile('');
     }
@@ -167,7 +204,11 @@ export class SyncLockManager {
     await atomicWriteFile(this.lockFilePath, serialized, 'utf-8');
   }
 
-  async updateEntry(filePath: string, key: string, entry: SyncLockEntry): Promise<void> {
+  async updateEntry(
+    filePath: string,
+    key: string,
+    entry: SyncLockEntry
+  ): Promise<void> {
     const lockFile = await this.read();
     lockFile.entries[filePath] ??= {};
     lockFile.entries[filePath][key] = entry;
diff --git a/src/sync/sync-message-preprocess.ts b/src/sync/sync-message-preprocess.ts
index ac49b30a..09ef8a6a 100644
--- a/src/sync/sync-message-preprocess.ts
+++ b/src/sync/sync-message-preprocess.ts
@@ -13,7 +13,10 @@
  */
 
 import { parseIcu } from '../utils/icu-preservation.js';
-import { preserveVariables, restorePlaceholders } from '../utils/text-preservation.js';
+import {
+  preserveVariables,
+  restorePlaceholders,
+} from '../utils/text-preservation.js';
 import type { TranslationService } from '../services/translation.js';
 import type { TranslationOptions } from '../types/api.js';
 import type { TranslationResult } from '../api/translation-client.js';
@@ -33,7 +36,7 @@ export interface IcuMapping {
 
 export function expandPlurals(
   textsToTranslate: string[],
-  localeDiffs: SyncDiff[],
+  localeDiffs: SyncDiff[]
 ): { extendedTexts: string[]; pluralSlots: PluralSlot[] } {
   const pluralSlots: PluralSlot[] = [];
   const extendedTexts = [...textsToTranslate];
@@ -42,18 +45,29 @@ export function expandPlurals(
     const diff = localeDiffs[di]!;
     if (!diff.metadata) continue;
 
-    const androidPlurals = diff.metadata['plurals'] as Array<{quantity: string; value: string}> | undefined;
+    const androidPlurals = diff.metadata['plurals'] as
+      Array<{ quantity: string; value: string }> | undefined;
     if (androidPlurals) {
       for (const p of androidPlurals) {
         if (p.value === diff.value) continue;
-        pluralSlots.push({ diffIndex: di, format: 'android', slotKey: p.quantity, textIndex: extendedTexts.length });
+        pluralSlots.push({
+          diffIndex: di,
+          format: 'android',
+          slotKey: p.quantity,
+          textIndex: extendedTexts.length,
+        });
         extendedTexts.push(p.value);
       }
     }
 
     const msgidPlural = diff.metadata['msgid_plural'] as string | undefined;
     if (msgidPlural && msgidPlural !== diff.value) {
-      pluralSlots.push({ diffIndex: di, format: 'po', slotKey: 'msgid_plural', textIndex: extendedTexts.length });
+      pluralSlots.push({
+        diffIndex: di,
+        format: 'po',
+        slotKey: 'msgid_plural',
+        textIndex: extendedTexts.length,
+      });
       extendedTexts.push(msgidPlural);
     }
   }
@@ -61,9 +75,10 @@ export function expandPlurals(
   return { extendedTexts, pluralSlots };
 }
 
-export function detectIcu(
-  extendedTexts: string[],
-): { extendedTexts: string[]; icuMappings: IcuMapping[] } {
+export function detectIcu(extendedTexts: string[]): {
+  extendedTexts: string[];
+  icuMappings: IcuMapping[];
+} {
   const icuMappings: IcuMapping[] = [];
   const out = [...extendedTexts];
 
@@ -83,10 +98,10 @@ export async function reassembleIcu(
   translationService: TranslationService,
   results: (TranslationResult | null)[],
   icuMappings: IcuMapping[],
-  baseOpts: TranslationOptions,
+  baseOpts: TranslationOptions
 ): Promise<void> {
   for (const icu of icuMappings) {
-    const segTexts = icu.icuResult.segments.map(seg => {
+    const segTexts = icu.icuResult.segments.map((seg) => {
       let text = seg.text;
       const pMap = new Map<string, string>();
       if (seg.isPluralBranch) {
@@ -101,15 +116,16 @@ export async function reassembleIcu(
     });
 
     const segResults = await translationService.translateBatch(
-      segTexts.map(s => s.text),
-      { ...baseOpts },
+      segTexts.map((s) => s.text),
+      { ...baseOpts }
     );
 
     // Every segment must come back. Substituting the source segment for a failed
     // one would emit a part-source message reported as successfully translated,
     // so leave the result unset — the message is marked failed and retried.
     const anySegmentFailed =
-      segResults.length !== segTexts.length || segResults.some((sr) => !sr?.text);
+      segResults.length !== segTexts.length ||
+      segResults.some((sr) => !sr?.text);
     if (anySegmentFailed) {
       results[icu.textIndex] = null;
       continue;
@@ -125,7 +141,10 @@ export async function reassembleIcu(
     const reassembled = icu.icuResult.reassemble(translatedSegments);
     results[icu.textIndex] = {
       text: reassembled,
-      billedCharacters: segResults.reduce((s, r) => s + (r?.billedCharacters ?? 0), 0),
+      billedCharacters: segResults.reduce(
+        (s, r) => s + (r?.billedCharacters ?? 0),
+        0
+      ),
     };
   }
 }
@@ -133,7 +152,7 @@ export async function reassembleIcu(
 export function writebackPlurals(
   results: (TranslationResult | null)[],
   pluralSlots: PluralSlot[],
-  localeDiffs: SyncDiff[],
+  localeDiffs: SyncDiff[]
 ): void {
   for (const slot of pluralSlots) {
     const result = results[slot.textIndex];
@@ -142,16 +161,24 @@ export function writebackPlurals(
     if (!diff.metadata) continue;
 
     if (slot.format === 'android') {
-      const plurals = diff.metadata['plurals'] as Array<{quantity: string; value: string}>;
-      const item = plurals.find(p => p.quantity === slot.slotKey);
+      const plurals = diff.metadata['plurals'] as Array<{
+        quantity: string;
+        value: string;
+      }>;
+      const item = plurals.find((p) => p.quantity === slot.slotKey);
       if (item) item.value = result.text;
     }
 
     if (slot.format === 'po' && slot.slotKey === 'msgid_plural') {
-      const forms = (diff.metadata['plural_forms'] as Record<string, string>) ?? {};
+      const forms =
+        (diff.metadata['plural_forms'] as Record<string, string>) ?? {};
       forms['msgstr[1]'] = result.text;
       for (const key of Object.keys(forms)) {
-        if (/^msgstr\[\d+]$/.test(key) && key !== 'msgstr[0]' && key !== 'msgstr[1]') {
+        if (
+          /^msgstr\[\d+]$/.test(key) &&
+          key !== 'msgstr[0]' &&
+          key !== 'msgstr[1]'
+        ) {
           forms[key] = result.text;
         }
       }
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index 848fdb29..5b51715a 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -1,7 +1,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { computeDiff } from './sync-differ.js';
-import { mapWithConcurrency, MULTI_TARGET_CONCURRENCY } from '../utils/concurrency.js';
+import {
+  mapWithConcurrency,
+  MULTI_TARGET_CONCURRENCY,
+} from '../utils/concurrency.js';
 import { ValidationError } from '../utils/errors.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
 import { computeSourceHash } from './sync-lock.js';
@@ -9,7 +12,10 @@ import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncLockFile, SyncLockTranslation } from './types.js';
 import type { KeyContext } from './sync-context.js';
 import { Logger } from '../utils/logger.js';
-import { extractTranslatable, type WalkedBucketFile } from './sync-bucket-walker.js';
+import {
+  extractTranslatable,
+  type WalkedBucketFile,
+} from './sync-bucket-walker.js';
 import type { LocaleTranslator } from './sync-locale-translator.js';
 import type { SyncFileResult, SyncOptions } from './sync-service.js';
 
@@ -53,21 +59,41 @@ export interface BucketContribution {
 }
 
 const EMPTY: BucketContribution = {
-  totalKeysDelta: 0, newKeysDelta: 0, staleKeysDelta: 0, deletedKeysDelta: 0,
-  currentKeysDelta: 0, totalCharsBilledDelta: 0, estimatedCharactersDelta: 0,
-  validationWarningsDelta: 0, validationErrorsDelta: 0,
-  fileResults: [], driftDetected: false, lockDirty: false,
+  totalKeysDelta: 0,
+  newKeysDelta: 0,
+  staleKeysDelta: 0,
+  deletedKeysDelta: 0,
+  currentKeysDelta: 0,
+  totalCharsBilledDelta: 0,
+  estimatedCharactersDelta: 0,
+  validationWarningsDelta: 0,
+  validationErrorsDelta: 0,
+  fileResults: [],
+  driftDetected: false,
+  lockDirty: false,
 };
 
 export async function processBucket(
   walked: WalkedBucketFile,
-  deps: ProcessBucketDeps,
+  deps: ProcessBucketDeps
 ): Promise<BucketContribution> {
-  const { config, options, lockFile, sourceEntryMap, targetEntryMap,
-    allContextSentKeys, allInstructionSentKeys, allInstructionGroupTotals,
-    keyContexts, localeTranslator, localeGlossaryIds, localeTmIds,
-    currentTotalCharsBilled } = deps;
-  const { bucketConfig, parser, relPath, content, entries, isMultiLocale } = walked;
+  const {
+    config,
+    options,
+    lockFile,
+    sourceEntryMap,
+    targetEntryMap,
+    allContextSentKeys,
+    allInstructionSentKeys,
+    allInstructionGroupTotals,
+    keyContexts,
+    localeTranslator,
+    localeGlossaryIds,
+    localeTmIds,
+    currentTotalCharsBilled,
+  } = deps;
+  const { bucketConfig, parser, relPath, content, entries, isMultiLocale } =
+    walked;
 
   const out: BucketContribution = { ...EMPTY, fileResults: [] };
 
@@ -78,7 +104,7 @@ export async function processBucket(
   let diffs = computeDiff(fileLockEntries, entries, config.target_locales);
 
   if (options?.force) {
-    diffs = diffs.map(d => ({ ...d, status: 'new' as const }));
+    diffs = diffs.map((d) => ({ ...d, status: 'new' as const }));
   }
 
   for (const d of diffs) {
@@ -87,33 +113,47 @@ export async function processBucket(
         if (d.value !== undefined) out.newKeysDelta++;
         else out.deletedKeysDelta++;
         break;
-      case 'stale': out.staleKeysDelta++; break;
-      case 'deleted': out.deletedKeysDelta++; break;
-      case 'current': out.currentKeysDelta++; break;
+      case 'stale':
+        out.staleKeysDelta++;
+        break;
+      case 'deleted':
+        out.deletedKeysDelta++;
+        break;
+      case 'current':
+        out.currentKeysDelta++;
+        break;
     }
   }
   out.totalKeysDelta += entries.length;
 
-  const toTranslate = diffs.filter(d => (d.status === 'new' || d.status === 'stale') && d.value !== undefined);
-  const deletedDiffs = diffs.filter(d => d.status === 'deleted');
+  const toTranslate = diffs.filter(
+    (d) => (d.status === 'new' || d.status === 'stale') && d.value !== undefined
+  );
+  const deletedDiffs = diffs.filter((d) => d.status === 'deleted');
 
   // Check if any target locale is missing translations for current keys
-  const hasNewLocale = config.target_locales.some(locale => {
+  const hasNewLocale = config.target_locales.some((locale) => {
     const localeFilter = options?.localeFilter;
     if (localeFilter?.length && !localeFilter.includes(locale)) return false;
-    return diffs.some(d => d.status === 'current' && !fileLockEntries[d.key]?.translations[locale]);
+    return diffs.some(
+      (d) =>
+        d.status === 'current' && !fileLockEntries[d.key]?.translations[locale]
+    );
   });
 
   if (options?.frozen) {
     const failMissing = config.validation?.fail_on_missing !== false;
     const failStale = config.validation?.fail_on_stale !== false;
-    const hasNew = toTranslate.some(d => d.status === 'new') || hasNewLocale;
-    const hasStale = toTranslate.some(d => d.status === 'stale');
-    if ((failMissing && (hasNew || deletedDiffs.length > 0)) || (failStale && hasStale)) {
+    const hasNew = toTranslate.some((d) => d.status === 'new') || hasNewLocale;
+    const hasStale = toTranslate.some((d) => d.status === 'stale');
+    if (
+      (failMissing && (hasNew || deletedDiffs.length > 0)) ||
+      (failStale && hasStale)
+    ) {
       // Promote current keys missing a target-locale translation into newKeysDelta
       // so the displayed count matches dry-run for the same input state.
       if (hasNewLocale) {
-        const currentDiffs = diffs.filter(d => d.status === 'current');
+        const currentDiffs = diffs.filter((d) => d.status === 'current');
         out.newKeysDelta += currentDiffs.length;
       }
       out.driftDetected = true;
@@ -123,21 +163,30 @@ export async function processBucket(
 
   if (options?.dryRun) {
     const effectiveLocales = options?.localeFilter?.length
-      ? config.target_locales.filter(l => options.localeFilter!.includes(l))
+      ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
       : config.target_locales;
 
     // Estimate characters for new/stale keys across all effective locales
-    out.estimatedCharactersDelta += toTranslate.reduce((sum, d) => sum + (d.value?.length ?? 0), 0) * effectiveLocales.length;
+    out.estimatedCharactersDelta +=
+      toTranslate.reduce((sum, d) => sum + (d.value?.length ?? 0), 0) *
+      effectiveLocales.length;
 
     if (hasNewLocale) {
       // Count current keys needing translation for new locales
-      const currentDiffs = diffs.filter(d => d.status === 'current');
+      const currentDiffs = diffs.filter((d) => d.status === 'current');
       out.newKeysDelta += currentDiffs.length;
 
       // Estimate characters for current keys needing translation for new locales only
-      const currentChars = currentDiffs.reduce((sum, d) => sum + (d.value?.length ?? 0), 0);
-      const newLocaleCount = effectiveLocales.filter(locale =>
-        diffs.some(d => d.status === 'current' && !fileLockEntries[d.key]?.translations[locale]),
+      const currentChars = currentDiffs.reduce(
+        (sum, d) => sum + (d.value?.length ?? 0),
+        0
+      );
+      const newLocaleCount = effectiveLocales.filter((locale) =>
+        diffs.some(
+          (d) =>
+            d.status === 'current' &&
+            !fileLockEntries[d.key]?.translations[locale]
+        )
       ).length;
       out.estimatedCharactersDelta += currentChars * newLocaleCount;
     }
@@ -145,7 +194,7 @@ export async function processBucket(
   }
 
   if (deletedDiffs.length > 0) {
-    const fileEntryMap = lockFile.entries[relPath] ??= {};
+    const fileEntryMap = (lockFile.entries[relPath] ??= {});
     for (const diff of deletedDiffs) {
       delete fileEntryMap[diff.key];
     }
@@ -155,38 +204,54 @@ export async function processBucket(
     out.lockDirty = true;
   }
 
-  const hasDeleted = diffs.some(d => d.status === 'deleted');
+  const hasDeleted = diffs.some((d) => d.status === 'deleted');
 
   if (toTranslate.length === 0 && !hasDeleted && !hasNewLocale) {
     return out;
   }
 
   const locales = options?.localeFilter?.length
-    ? config.target_locales.filter(l => options.localeFilter!.includes(l))
+    ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
     : config.target_locales;
 
   if (options?.localeFilter?.length && locales.length === 0) {
-    Logger.warn(`No matching locales for filter [${options.localeFilter.join(', ')}]. Available: ${config.target_locales.join(', ')}`);
+    Logger.warn(
+      `No matching locales for filter [${options.localeFilter.join(', ')}]. Available: ${config.target_locales.join(', ')}`
+    );
   }
 
   const concurrency = isMultiLocale
     ? 1
-    : (options?.concurrency ?? config.sync?.concurrency ?? MULTI_TARGET_CONCURRENCY);
+    : (options?.concurrency ??
+      config.sync?.concurrency ??
+      MULTI_TARGET_CONCURRENCY);
 
   if (config.sync?.max_characters !== undefined && !options?.force) {
-    let estimatedChars = toTranslate.reduce((sum, d) => sum + (d.value?.length ?? 0), 0) * locales.length;
+    let estimatedChars =
+      toTranslate.reduce((sum, d) => sum + (d.value?.length ?? 0), 0) *
+      locales.length;
     if (hasNewLocale) {
-      const currentDiffs = diffs.filter(d => d.status === 'current');
-      const currentChars = currentDiffs.reduce((sum, d) => sum + (d.value?.length ?? 0), 0);
-      const newLocaleCount = locales.filter(locale =>
-        diffs.some(d => d.status === 'current' && !fileLockEntries[d.key]?.translations[locale]),
+      const currentDiffs = diffs.filter((d) => d.status === 'current');
+      const currentChars = currentDiffs.reduce(
+        (sum, d) => sum + (d.value?.length ?? 0),
+        0
+      );
+      const newLocaleCount = locales.filter((locale) =>
+        diffs.some(
+          (d) =>
+            d.status === 'current' &&
+            !fileLockEntries[d.key]?.translations[locale]
+        )
       ).length;
       estimatedChars += currentChars * newLocaleCount;
     }
-    if (currentTotalCharsBilled + out.totalCharsBilledDelta + estimatedChars > config.sync.max_characters) {
+    if (
+      currentTotalCharsBilled + out.totalCharsBilledDelta + estimatedChars >
+      config.sync.max_characters
+    ) {
       throw new ValidationError(
         `Cost cap exceeded: this sync would use ~${(currentTotalCharsBilled + out.totalCharsBilledDelta + estimatedChars).toLocaleString()} characters ` +
-        `(cap: ${config.sync.max_characters.toLocaleString()}). Use --force to override.`,
+          `(cap: ${config.sync.max_characters.toLocaleString()}). Use --force to override.`
       );
     }
   }
@@ -196,15 +261,29 @@ export async function processBucket(
   for (const locale of locales) {
     if (isMultiLocale) {
       const targetParsed = extractTranslatable(parser, content, locale);
-      existingTargetEntries.set(locale, new Map(targetParsed.map(e => [e.key, e.value])));
+      existingTargetEntries.set(
+        locale,
+        new Map(targetParsed.map((e) => [e.key, e.value]))
+      );
     } else {
-      const targetRelPath = resolveTargetPath(relPath, config.source_locale, locale, bucketConfig.target_path_pattern);
+      const targetRelPath = resolveTargetPath(
+        relPath,
+        config.source_locale,
+        locale,
+        bucketConfig.target_path_pattern
+      );
       const targetAbsPath = path.join(config.projectRoot, targetRelPath);
       assertPathWithinRoot(targetAbsPath, config.projectRoot);
       try {
-        const targetContent = await fs.promises.readFile(targetAbsPath, 'utf-8');
+        const targetContent = await fs.promises.readFile(
+          targetAbsPath,
+          'utf-8'
+        );
         const targetParsed = extractTranslatable(parser, targetContent);
-        existingTargetEntries.set(locale, new Map(targetParsed.map(e => [e.key, e.value])));
+        existingTargetEntries.set(
+          locale,
+          new Map(targetParsed.map((e) => [e.key, e.value]))
+        );
       } catch {
         existingTargetEntries.set(locale, new Map());
       }
@@ -229,102 +308,135 @@ export async function processBucket(
     }
   }
 
-  await mapWithConcurrency(locales, async (locale) => {
-   if (options?.cancellationSignal?.cancelled) {
-    return;
-   }
-   try {
-    const result = await localeTranslator.translate({
-      locale, relPath, content, parser,
-      diffs, toTranslate, fileLockEntries,
-      existingTargetEntries, keyContexts,
-      localeGlossaryIds, localeTmIds,
-      bucketConfig, isMultiLocale,
-    });
-
-    out.totalCharsBilledDelta += result.charactersBilled;
-    out.validationWarningsDelta += result.validationWarnings;
-    out.validationErrorsDelta += result.validationErrors;
-    out.fileResults.push(result.fileResult);
-
-    for (const key of result.successfulKeys) {
-      localeSuccessMap.get(key)?.add(locale);
-    }
-    for (const [key, chars] of result.billedPerKey) {
-      const billedMap = localeBilledMap.get(key) ?? new Map<string, number>();
-      billedMap.set(locale, chars);
-      localeBilledMap.set(key, billedMap);
-    }
-    for (const key of result.contextSentKeys) {
-      contextSentSet.add(key);
-      allContextSentKeys.add(key);
-    }
-    for (const key of result.instructionSentKeys) {
-      allInstructionSentKeys.add(key);
-    }
-    for (const [elemType, count] of result.instructionGroupCounts) {
-      allInstructionGroupTotals.set(elemType, (allInstructionGroupTotals.get(elemType) ?? 0) + count);
-    }
+  await mapWithConcurrency(
+    locales,
+    async (locale) => {
+      if (options?.cancellationSignal?.cancelled) {
+        return;
+      }
+      try {
+        const result = await localeTranslator.translate({
+          locale,
+          relPath,
+          content,
+          parser,
+          diffs,
+          toTranslate,
+          fileLockEntries,
+          existingTargetEntries,
+          keyContexts,
+          localeGlossaryIds,
+          localeTmIds,
+          bucketConfig,
+          isMultiLocale,
+        });
+
+        out.totalCharsBilledDelta += result.charactersBilled;
+        out.validationWarningsDelta += result.validationWarnings;
+        out.validationErrorsDelta += result.validationErrors;
+        out.fileResults.push(result.fileResult);
+
+        for (const key of result.successfulKeys) {
+          localeSuccessMap.get(key)?.add(locale);
+        }
+        for (const [key, chars] of result.billedPerKey) {
+          const billedMap =
+            localeBilledMap.get(key) ?? new Map<string, number>();
+          billedMap.set(locale, chars);
+          localeBilledMap.set(key, billedMap);
+        }
+        for (const key of result.contextSentKeys) {
+          contextSentSet.add(key);
+          allContextSentKeys.add(key);
+        }
+        for (const key of result.instructionSentKeys) {
+          allInstructionSentKeys.add(key);
+        }
+        for (const [elemType, count] of result.instructionGroupCounts) {
+          allInstructionGroupTotals.set(
+            elemType,
+            (allInstructionGroupTotals.get(elemType) ?? 0) + count
+          );
+        }
+
+        const localeTargetEntries =
+          targetEntryMap.get(locale) ?? new Map<string, string>();
+        for (const [key, value] of result.targetEntries) {
+          localeTargetEntries.set(key, value);
+        }
+        targetEntryMap.set(locale, localeTargetEntries);
+
+        options?.onProgress?.({
+          type: 'locale-complete',
+          locale,
+          file: relPath,
+          translated: result.fileResult.translated,
+          failed: result.fileResult.failed,
+          totalKeys: result.fileResult.translated + result.fileResult.failed,
+          charactersBilled: result.charactersBilled,
+        });
+      } catch (localeError) {
+        const msg =
+          localeError instanceof Error
+            ? localeError.message
+            : String(localeError);
+        // Containment violations abort the whole sync instead of being retried per locale.
+        if (
+          msg.includes('Authentication') ||
+          msg.includes('Forbidden') ||
+          msg.includes('quota') ||
+          (localeError instanceof ValidationError &&
+            msg.includes('escapes project root'))
+        ) {
+          throw localeError;
+        }
+        Logger.error(
+          `Sync failed for locale "${locale}" on "${relPath}": ${msg}`
+        );
+        out.fileResults.push({
+          file: relPath,
+          locale,
+          translated: 0,
+          skipped: 0,
+          failed: diffs.length,
+          written: false,
+        });
+        options?.onProgress?.({
+          type: 'locale-complete',
+          locale,
+          file: relPath,
+          translated: 0,
+          failed: diffs.length,
+          totalKeys: toTranslate.length,
+          charactersBilled: 0,
+        });
+      }
+    },
+    concurrency
+  );
 
-    const localeTargetEntries = targetEntryMap.get(locale) ?? new Map<string, string>();
-    for (const [key, value] of result.targetEntries) {
-      localeTargetEntries.set(key, value);
-    }
-    targetEntryMap.set(locale, localeTargetEntries);
-
-    options?.onProgress?.({
-      type: 'locale-complete',
-      locale,
-      file: relPath,
-      translated: result.fileResult.translated,
-      failed: result.fileResult.failed,
-      totalKeys: result.fileResult.translated + result.fileResult.failed,
-      charactersBilled: result.charactersBilled,
-    });
-   } catch (localeError) {
-    const msg = localeError instanceof Error ? localeError.message : String(localeError);
-    // Containment violations abort the whole sync instead of being retried per locale.
-    if (msg.includes('Authentication') || msg.includes('Forbidden') || msg.includes('quota')
-      || (localeError instanceof ValidationError && msg.includes('escapes project root'))) {
-      throw localeError;
-    }
-    Logger.error(`Sync failed for locale "${locale}" on "${relPath}": ${msg}`);
-    out.fileResults.push({
-      file: relPath,
-      locale,
-      translated: 0,
-      skipped: 0,
-      failed: diffs.length,
-      written: false,
-    });
-    options?.onProgress?.({
-      type: 'locale-complete',
-      locale,
-      file: relPath,
-      translated: 0,
-      failed: diffs.length,
-      totalKeys: toTranslate.length,
-      charactersBilled: 0,
-    });
-   }
-  }, concurrency);
-
-  const fileEntryMap = lockFile.entries[relPath] ??= {};
+  const fileEntryMap = (lockFile.entries[relPath] ??= {});
   for (const diff of toTranslate) {
     if (diff.value === undefined) continue;
     const existingEntry = fileEntryMap[diff.key];
     const existingTranslations = existingEntry?.translations ?? {};
 
-    const newTranslations: Record<string, SyncLockTranslation> = { ...existingTranslations };
+    const newTranslations: Record<string, SyncLockTranslation> = {
+      ...existingTranslations,
+    };
     for (const locale of locales) {
       const charCount = localeBilledMap.get(diff.key)?.get(locale);
       newTranslations[locale] = {
         hash: computeSourceHash(diff.value, diff.metadata),
         translated_at: new Date().toISOString(),
-        status: localeSuccessMap.get(diff.key)?.has(locale) ? 'translated' : 'failed',
+        status: localeSuccessMap.get(diff.key)?.has(locale)
+          ? 'translated'
+          : 'failed',
         ...(charCount !== undefined && { character_count: charCount }),
         ...(contextSentSet.has(diff.key) && { context_sent: true }),
-        ...(options?.flagForReview && { review_status: 'machine_translated' as const }),
+        ...(options?.flagForReview && {
+          review_status: 'machine_translated' as const,
+        }),
       };
     }
 
@@ -352,7 +464,9 @@ export async function processBucket(
           translated_at: new Date().toISOString(),
           status: 'translated' as const,
           ...(contextSentSet.has(diff.key) && { context_sent: true }),
-          ...(options?.flagForReview && { review_status: 'machine_translated' as const }),
+          ...(options?.flagForReview && {
+            review_status: 'machine_translated' as const,
+          }),
         };
         updated = true;
       }
diff --git a/src/sync/sync-process-lock.ts b/src/sync/sync-process-lock.ts
index 9d9c284a..4571ddaa 100644
--- a/src/sync/sync-process-lock.ts
+++ b/src/sync/sync-process-lock.ts
@@ -59,7 +59,11 @@ function writePidFile(pidFilePath: string): void {
     pid: process.pid,
     startedAt: new Date().toISOString(),
   };
-  const fd = fs.openSync(pidFilePath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o644);
+  const fd = fs.openSync(
+    pidFilePath,
+    fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY,
+    0o644
+  );
   try {
     fs.writeSync(fd, JSON.stringify(payload));
   } finally {
@@ -85,13 +89,13 @@ export function acquireSyncProcessLock(projectRoot: string): ProcessLockHandle {
     if (existing && isProcessAlive(existing.pid)) {
       throw new ConfigError(
         `Another \`deepl sync\` process is running in this directory (PID=${existing.pid}, started ${existing.startedAt}). Wait for it to finish or kill it before retrying.`,
-        `If the process is definitely not running, remove ${PROCESS_LOCK_FILE_NAME} manually and retry.`,
+        `If the process is definitely not running, remove ${PROCESS_LOCK_FILE_NAME} manually and retry.`
       );
     }
 
     const stalePidLabel = existing ? `PID=${existing.pid}` : 'unknown PID';
     Logger.warn(
-      `Removing stale ${PROCESS_LOCK_FILE_NAME} (${stalePidLabel} is not alive); reclaiming lock.`,
+      `Removing stale ${PROCESS_LOCK_FILE_NAME} (${stalePidLabel} is not alive); reclaiming lock.`
     );
     try {
       fs.unlinkSync(pidFilePath);
@@ -117,7 +121,7 @@ export function acquireSyncProcessLock(projectRoot: string): ProcessLockHandle {
       const code = (err as NodeJS.ErrnoException).code;
       if (code !== 'ENOENT') {
         Logger.warn(
-          `Failed to remove ${PROCESS_LOCK_FILE_NAME}: ${err instanceof Error ? err.message : String(err)}`,
+          `Failed to remove ${PROCESS_LOCK_FILE_NAME}: ${err instanceof Error ? err.message : String(err)}`
         );
       }
     }
diff --git a/src/sync/sync-resolve.ts b/src/sync/sync-resolve.ts
index 6e7f8905..759cce7b 100644
--- a/src/sync/sync-resolve.ts
+++ b/src/sync/sync-resolve.ts
@@ -7,7 +7,8 @@ const CONFLICT_END = /^>{7}/m;
 const MAX_REASON_LEN = 80;
 const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 
-export type DecisionSource = 'ours' | 'theirs' | 'length-heuristic' | 'unresolved';
+export type DecisionSource =
+  'ours' | 'theirs' | 'length-heuristic' | 'unresolved';
 
 export interface ResolveDecision {
   file?: string;
@@ -37,7 +38,7 @@ export function hasConflictMarkers(content: string): boolean {
 
 export function resolveConflicts(
   content: string,
-  options: ResolveConflictsOptions = {},
+  options: ResolveConflictsOptions = {}
 ): { resolved: string; mergeCount: number; decisions: ResolveDecision[] } {
   const lines = content.split('\n');
   const result: string[] = [];
@@ -64,7 +65,7 @@ export function resolveConflicts(
       const { merged, decisions: sectionDecisions } = mergeConflictSections(
         oursLines.join('\n'),
         theirsLines.join('\n'),
-        options.file,
+        options.file
       );
       result.push(merged);
       decisions.push(...sectionDecisions);
@@ -86,7 +87,7 @@ export function resolveConflicts(
 function mergeConflictSections(
   ours: string,
   theirs: string,
-  file?: string,
+  file?: string
 ): { merged: string; decisions: ResolveDecision[] } {
   let oursObj: Record<string, unknown> | undefined;
   let theirsObj: Record<string, unknown> | undefined;
@@ -107,7 +108,12 @@ function mergeConflictSections(
   }
 
   if (oursObj && theirsObj) {
-    const { merged, decisions } = deepMergeWithDecisions(oursObj, theirsObj, file, '');
+    const { merged, decisions } = deepMergeWithDecisions(
+      oursObj,
+      theirsObj,
+      file,
+      ''
+    );
     const json = JSON.stringify(merged, null, 2);
     return { merged: json.slice(2, -2), decisions };
   }
@@ -119,14 +125,18 @@ function mergeConflictSections(
 
   // The decision below carries the warning; the command layer prints it once
   // with a project-relative path.
-  const winningSide: 'ours' | 'theirs' = ours.length >= theirs.length ? 'ours' : 'theirs';
+  const winningSide: 'ours' | 'theirs' =
+    ours.length >= theirs.length ? 'ours' : 'theirs';
   const decision: ResolveDecision = {
     file,
     key: '<conflict-region>',
     source: 'length-heuristic',
     reason: reasonMsg,
   };
-  return { merged: winningSide === 'ours' ? ours : theirs, decisions: [decision] };
+  return {
+    merged: winningSide === 'ours' ? ours : theirs,
+    decisions: [decision],
+  };
 }
 
 function truncate(s: string, max: number): string {
@@ -137,9 +147,12 @@ function deepMergeWithDecisions(
   ours: Record<string, unknown>,
   theirs: Record<string, unknown>,
   file: string | undefined,
-  keyPath: string,
+  keyPath: string
 ): { merged: Record<string, unknown>; decisions: ResolveDecision[] } {
-  const merged: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  const merged: Record<string, unknown> = Object.create(null) as Record<
+    string,
+    unknown
+  >;
   for (const [key, value] of Object.entries(ours)) {
     if (FORBIDDEN_KEYS.has(key)) continue;
     merged[key] = value;
@@ -163,8 +176,11 @@ function deepMergeWithDecisions(
     }
 
     if (isTranslationEntry(ourValue) && isTranslationEntry(theirValue)) {
-      const ourDate = (ourValue as Record<string, unknown>)['translated_at'] as string | undefined;
-      const theirDate = (theirValue as Record<string, unknown>)['translated_at'] as string | undefined;
+      const ourDate = (ourValue as Record<string, unknown>)['translated_at'] as
+        string | undefined;
+      const theirDate = (theirValue as Record<string, unknown>)[
+        'translated_at'
+      ] as string | undefined;
       if (ourDate && theirDate) {
         if (ourDate >= theirDate) {
           merged[key] = ourValue;
@@ -210,12 +226,13 @@ function deepMergeWithDecisions(
       !Array.isArray(ourValue) &&
       !Array.isArray(theirValue)
     ) {
-      const { merged: childMerged, decisions: childDecisions } = deepMergeWithDecisions(
-        ourValue as Record<string, unknown>,
-        theirValue as Record<string, unknown>,
-        file,
-        childPath,
-      );
+      const { merged: childMerged, decisions: childDecisions } =
+        deepMergeWithDecisions(
+          ourValue as Record<string, unknown>,
+          theirValue as Record<string, unknown>,
+          file,
+          childPath
+        );
       merged[key] = childMerged;
       decisions.push(...childDecisions);
       continue;
@@ -240,7 +257,7 @@ function isTranslationEntry(obj: unknown): boolean {
 
 export async function resolveLockFile(
   lockPath: string,
-  options: ResolveLockFileOptions = {},
+  options: ResolveLockFileOptions = {}
 ): Promise<ResolveResult> {
   let content: string;
   try {
@@ -253,7 +270,9 @@ export async function resolveLockFile(
     return { hadConflicts: false, resolved: false, entriesMerged: 0 };
   }
 
-  const { resolved, mergeCount, decisions } = resolveConflicts(content, { file: lockPath });
+  const { resolved, mergeCount, decisions } = resolveConflicts(content, {
+    file: lockPath,
+  });
 
   try {
     JSON.parse(resolved) as SyncLockFile;
@@ -264,5 +283,10 @@ export async function resolveLockFile(
   if (!options.dryRun) {
     await fs.promises.writeFile(lockPath, resolved, 'utf-8');
   }
-  return { hadConflicts: true, resolved: true, entriesMerged: mergeCount, decisions };
+  return {
+    hadConflicts: true,
+    resolved: true,
+    entriesMerged: mergeCount,
+    decisions,
+  };
 }
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index c8c78f68..7ed713f5 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -17,7 +17,11 @@ export { resolveTargetPath } from './sync-utils.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import { LOCK_FILE_NAME } from './types.js';
 import type { Language } from '../types/common.js';
-import { extractAllKeyContexts, resolveTemplatePatterns, synthesizeContext } from './sync-context.js';
+import {
+  extractAllKeyContexts,
+  resolveTemplatePatterns,
+  synthesizeContext,
+} from './sync-context.js';
 import type { TemplatePatternMatch } from './sync-context.js';
 import type { KeyContext } from './sync-context.js';
 import { SyncGlossaryManager } from './sync-glossary.js';
@@ -27,8 +31,23 @@ import { Logger } from '../utils/logger.js';
 import { errorMessage } from '../utils/error-message.js';
 
 export type SyncProgressEvent =
-  | { type: 'locale-complete'; locale: string; file: string; translated: number; failed: number; totalKeys: number; charactersBilled: number }
-  | { type: 'key-translated'; locale: string; file: string; key: string; translated: number; totalKeys: number };
+  | {
+      type: 'locale-complete';
+      locale: string;
+      file: string;
+      translated: number;
+      failed: number;
+      totalKeys: number;
+      charactersBilled: number;
+    }
+  | {
+      type: 'key-translated';
+      locale: string;
+      file: string;
+      key: string;
+      translated: number;
+      totalKeys: number;
+    };
 
 export interface CancellationSignal {
   cancelled: boolean;
@@ -102,10 +121,13 @@ export class SyncService {
   constructor(
     private readonly translationService: TranslationService,
     private readonly glossaryService: GlossaryService,
-    private readonly formatRegistry: FormatRegistry,
+    private readonly formatRegistry: FormatRegistry
   ) {}
 
-  async sync(config: ResolvedSyncConfig, options?: SyncOptions): Promise<SyncResult> {
+  async sync(
+    config: ResolvedSyncConfig,
+    options?: SyncOptions
+  ): Promise<SyncResult> {
     const processLock = acquireSyncProcessLock(config.projectRoot);
     // Watch mode owns its own sweep + backup cleanup via `backupTracker`;
     // only the non-watch runs (single `deepl sync`, `sync push/pull/export`,
@@ -139,19 +161,22 @@ export class SyncService {
         await sweepStaleBackups(
           config.projectRoot,
           resolveBakSweepAgeMs(config.sync?.bak_sweep_max_age_seconds),
-          config.buckets,
+          config.buckets
         );
       } catch (error) {
         // Best-effort — never block the sync — but warn rather than swallowing
         // the error silently.
         Logger.warn(
-          `Stale-backup sweep skipped: ${error instanceof Error ? error.message : String(error)}`,
+          `Stale-backup sweep skipped: ${error instanceof Error ? error.message : String(error)}`
         );
       }
     }
 
     try {
-      return await this.runSync(config, { ...options, backupTracker: runBackupPaths });
+      return await this.runSync(config, {
+        ...options,
+        backupTracker: runBackupPaths,
+      });
     } finally {
       process.off('SIGINT', onSignal);
       process.off('SIGTERM', onSignal);
@@ -159,7 +184,10 @@ export class SyncService {
     }
   }
 
-  private async runSync(config: ResolvedSyncConfig, options?: SyncOptions): Promise<SyncResult> {
+  private async runSync(
+    config: ResolvedSyncConfig,
+    options?: SyncOptions
+  ): Promise<SyncResult> {
     const lockPath = path.join(config.projectRoot, LOCK_FILE_NAME);
     const lockManager = new SyncLockManager(lockPath);
     const lockFile = await lockManager.read();
@@ -169,7 +197,9 @@ export class SyncService {
     }
 
     if (options?.dryRun && options?.force) {
-      Logger.warn('--dry-run with --force shows all keys as new; this does not reflect actual translation needs');
+      Logger.warn(
+        '--dry-run with --force shows all keys as new; this does not reflect actual translation needs'
+      );
     }
 
     if (lockFile.source_locale === '') {
@@ -194,11 +224,14 @@ export class SyncService {
     // translation memory the config names but the account cannot use for the
     // requested pair is exactly what a preview exists to report.
     const effectiveLocales = options?.localeFilter?.length
-      ? config.target_locales.filter(l => options.localeFilter!.includes(l))
+      ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
       : config.target_locales;
 
     let resolvedGlossaryId: string | undefined;
-    if (config.translation?.glossary && config.translation.glossary !== 'auto') {
+    if (
+      config.translation?.glossary &&
+      config.translation.glossary !== 'auto'
+    ) {
       // The pair is known from the config, so a glossary that does not cover it
       // fails here rather than once per file, as with the translation memory
       // below.
@@ -209,12 +242,17 @@ export class SyncService {
       const overriddenLocales = new Set(
         Object.entries(config.translation?.locale_overrides ?? {})
           .filter(([, override]) => override?.glossary)
-          .map(([locale]) => locale),
+          .map(([locale]) => locale)
+      );
+      const glossaryLocales = effectiveLocales.filter(
+        (locale) => !overriddenLocales.has(locale)
       );
-      const glossaryLocales = effectiveLocales.filter(locale => !overriddenLocales.has(locale));
       resolvedGlossaryId = await this.glossaryService.resolveGlossaryId(
         config.translation.glossary,
-        { from: config.source_locale as Language, targets: glossaryLocales as Language[] },
+        {
+          from: config.source_locale as Language,
+          targets: glossaryLocales as Language[],
+        }
       );
     }
 
@@ -224,7 +262,10 @@ export class SyncService {
         this.translationService,
         config.translation.translation_memory,
         this.tmCache,
-        { from: config.source_locale as Language, targets: effectiveLocales as Language[] },
+        {
+          from: config.source_locale as Language,
+          targets: effectiveLocales as Language[],
+        }
       );
     }
 
@@ -243,7 +284,7 @@ export class SyncService {
           await this.glossaryService.resolveGlossaryId(override.glossary, {
             from: config.source_locale as Language,
             targets: [locale as Language],
-          }),
+          })
         );
       }
       if (override?.translation_memory) {
@@ -253,8 +294,11 @@ export class SyncService {
             this.translationService,
             override.translation_memory,
             this.tmCache,
-            { from: config.source_locale as Language, targets: [locale as Language] },
-          ),
+            {
+              from: config.source_locale as Language,
+              targets: [locale as Language],
+            }
+          )
         );
       }
     }
@@ -273,9 +317,13 @@ export class SyncService {
       templatePatterns = contextResult.templatePatterns;
 
       if (config.translation?.instruction_templates) {
-        const hasElementTypes = [...keyContexts.values()].some(kc => kc.elementType);
+        const hasElementTypes = [...keyContexts.values()].some(
+          (kc) => kc.elementType
+        );
         if (!hasElementTypes) {
-          Logger.warn('instruction_templates configured but no element types detected in source. Templates only apply to keys inside recognized HTML elements (button, label, th, etc.).');
+          Logger.warn(
+            'instruction_templates configured but no element types detected in source. Templates only apply to keys inside recognized HTML elements (button, label, th, etc.).'
+          );
         }
       }
     }
@@ -289,30 +337,48 @@ export class SyncService {
       for (const [fk, bc] of Object.entries(config.buckets)) {
         const p = this.formatRegistry.getParserByFormatKey(fk);
         if (!p) continue;
-        const ignorePatterns = [...(bc.exclude ?? []), ...(config.ignore ?? [])];
+        const ignorePatterns = [
+          ...(bc.exclude ?? []),
+          ...(config.ignore ?? []),
+        ];
         const files = await fg(bc.include, {
-          cwd: config.projectRoot, ignore: ignorePatterns,
-          absolute: true, followSymbolicLinks: false,
+          cwd: config.projectRoot,
+          ignore: ignorePatterns,
+          absolute: true,
+          followSymbolicLinks: false,
         });
         for (const f of files) {
           try {
             const c = await fs.promises.readFile(f, 'utf-8');
-            const entries = p.multiLocale ? p.extract(c, config.source_locale) : p.extract(c);
+            const entries = p.multiLocale
+              ? p.extract(c, config.source_locale)
+              : p.extract(c);
             bucketFileCache.set(f, { content: c, entries });
             for (const entry of entries) allKnownKeys.add(entry.key);
-          } catch { /* skip unreadable files */ }
+          } catch {
+            /* skip unreadable files */
+          }
         }
       }
-      const resolved = resolveTemplatePatterns(templatePatterns, Array.from(allKnownKeys));
+      const resolved = resolveTemplatePatterns(
+        templatePatterns,
+        Array.from(allKnownKeys)
+      );
       for (const [key, matches] of resolved) {
         if (!keyContexts.has(key)) {
-          keyContexts.set(key, { key, context: synthesizeContext(matches, { key }), occurrences: matches.length });
+          keyContexts.set(key, {
+            key,
+            context: synthesizeContext(matches, { key }),
+            occurrences: matches.length,
+          });
         }
       }
     }
 
     if (config.translation?.instruction_templates && !config.context?.enabled) {
-      Logger.warn('instruction_templates configured but context scanning is disabled — templates have no effect. Set context.enabled: true.');
+      Logger.warn(
+        'instruction_templates configured but context scanning is disabled — templates have no effect. Set context.enabled: true.'
+      );
     }
 
     const sourceEntryMap = new Map<string, string>();
@@ -326,20 +392,30 @@ export class SyncService {
       resolvedGlossaryId,
       resolvedTmId,
       options?.batch ?? config.sync?.batch,
-      options?.onProgress,
+      options?.onProgress
     );
     const allContextSentKeys = new Set<string>();
     const allInstructionSentKeys = new Set<string>();
     const allInstructionGroupTotals = new Map<string, number>();
 
-    for await (const walked of walkBuckets(config, this.formatRegistry, { strictParser: true, fileCache: bucketFileCache })) {
+    for await (const walked of walkBuckets(config, this.formatRegistry, {
+      strictParser: true,
+      fileCache: bucketFileCache,
+    })) {
       processedFiles.add(walked.relPath);
       const contribution = await processBucket(walked, {
-        config, options, lockFile,
-        sourceEntryMap, targetEntryMap,
-        allContextSentKeys, allInstructionSentKeys, allInstructionGroupTotals,
-        keyContexts, localeTranslator,
-        localeGlossaryIds, localeTmIds,
+        config,
+        options,
+        lockFile,
+        sourceEntryMap,
+        targetEntryMap,
+        allContextSentKeys,
+        allInstructionSentKeys,
+        allInstructionGroupTotals,
+        keyContexts,
+        localeTranslator,
+        localeGlossaryIds,
+        localeTmIds,
         currentTotalCharsBilled: totalCharsBilled,
       });
 
@@ -358,9 +434,13 @@ export class SyncService {
     }
 
     // Fix SPEC-02: Wire auto-glossary sync
-    if (config.translation?.glossary === 'auto' && !options?.dryRun && !driftDetected) {
+    if (
+      config.translation?.glossary === 'auto' &&
+      !options?.dryRun &&
+      !driftDetected
+    ) {
       const effectiveLocales = options?.localeFilter?.length
-        ? config.target_locales.filter(l => options.localeFilter!.includes(l))
+        ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
         : config.target_locales;
       const glossaryManager = new SyncGlossaryManager({
         sourceLocale: config.source_locale,
@@ -368,12 +448,15 @@ export class SyncService {
         glossaryService: this.glossaryService,
       });
       try {
-        const glossaryIds = await glossaryManager.syncGlossaries(sourceEntryMap, targetEntryMap);
+        const glossaryIds = await glossaryManager.syncGlossaries(
+          sourceEntryMap,
+          targetEntryMap
+        );
         lockFile.glossary_ids = { ...lockFile.glossary_ids, ...glossaryIds };
         lockDirty = true;
       } catch (error) {
         Logger.warn(
-          `Auto-glossary sync failed for locales ${effectiveLocales.join(', ')}: ${errorMessage(error)}. Translations were written; the project glossaries were not updated.`,
+          `Auto-glossary sync failed for locales ${effectiveLocales.join(', ')}: ${errorMessage(error)}. Translations were written; the project glossaries were not updated.`
         );
       }
     }
@@ -399,7 +482,7 @@ export class SyncService {
 
       if (staleByBaseName.size > 0) {
         const patterns = Array.from(staleByBaseName.keys()).map(
-          (b) => `**/${fg.escapePath(b)}`,
+          (b) => `**/${fg.escapePath(b)}`
         );
         const scanHits = await fg(patterns, {
           cwd: config.projectRoot,
@@ -408,9 +491,13 @@ export class SyncService {
           ignore: config.ignore,
         });
         for (const [baseName, lockPaths] of staleByBaseName) {
-          const hitsForBase = scanHits.filter((hit) => path.basename(hit) === baseName);
+          const hitsForBase = scanHits.filter(
+            (hit) => path.basename(hit) === baseName
+          );
           for (const lockPath of lockPaths) {
-            const foundElsewhere = hitsForBase.filter((hit) => hit !== lockPath);
+            const foundElsewhere = hitsForBase.filter(
+              (hit) => hit !== lockPath
+            );
             if (foundElsewhere.length > 0) {
               const preview = foundElsewhere.slice(0, 3).join(', ');
               const suffix = foundElsewhere.length > 3 ? ', …' : '';
@@ -418,7 +505,7 @@ export class SyncService {
                 `Lock entry "${lockPath}" no longer matches any bucket glob, but a ` +
                   `file named "${baseName}" exists at: ${preview}${suffix}. ` +
                   `Preserving entry — glob change suspected. Update your bucket ` +
-                  `patterns or remove the entry manually to resolve.`,
+                  `patterns or remove the entry manually to resolve.`
               );
               continue;
             }
@@ -458,18 +545,29 @@ export class SyncService {
     }
 
     const effectiveLocaleCount = options?.localeFilter?.length
-      ? config.target_locales.filter(l => options.localeFilter!.includes(l)).length
+      ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
+          .length
       : config.target_locales.length;
 
     return finalizeSyncResult({
-      totalKeys, newKeys, staleKeys, deletedKeys, currentKeys,
-      totalCharsBilled, fileResults, validationWarnings, validationErrors,
-      estimatedCharacters, effectiveLocaleCount,
+      totalKeys,
+      newKeys,
+      staleKeys,
+      deletedKeys,
+      currentKeys,
+      totalCharsBilled,
+      fileResults,
+      validationWarnings,
+      validationErrors,
+      estimatedCharacters,
+      effectiveLocaleCount,
       dryRun: options?.dryRun ?? false,
       frozen: options?.frozen ?? false,
-      driftDetected, lockUpdated,
-      allContextSentKeys, allInstructionSentKeys, allInstructionGroupTotals,
+      driftDetected,
+      lockUpdated,
+      allContextSentKeys,
+      allInstructionSentKeys,
+      allInstructionGroupTotals,
     });
   }
-
 }
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index 8976fd7e..c045370f 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -28,13 +28,18 @@ export interface SyncStatusResult {
 
 export async function computeSyncStatus(
   config: ResolvedSyncConfig,
-  formatRegistry: FormatRegistry,
+  formatRegistry: FormatRegistry
 ): Promise<SyncStatusResult> {
-  const lockManager = new SyncLockManager(path.join(config.projectRoot, LOCK_FILE_NAME));
+  const lockManager = new SyncLockManager(
+    path.join(config.projectRoot, LOCK_FILE_NAME)
+  );
   const lockFile = await lockManager.read();
   let totalKeys = 0;
   let skippedKeys = 0;
-  const localeStats = new Map<string, { complete: number; missing: number; outdated: number }>();
+  const localeStats = new Map<
+    string,
+    { complete: number; missing: number; outdated: number }
+  >();
 
   for (const locale of config.target_locales) {
     localeStats.set(locale, { complete: 0, missing: 0, outdated: 0 });
@@ -63,7 +68,8 @@ export async function computeSyncStatus(
         const localeOutdated =
           lockEntry !== undefined &&
           translation !== undefined &&
-          (translation.status === 'failed' || translation.hash !== lockEntry.source_hash);
+          (translation.status === 'failed' ||
+            translation.hash !== lockEntry.source_hash);
 
         if (diff.status === 'new' || !hasTranslation) {
           stats.missing++;
@@ -77,11 +83,20 @@ export async function computeSyncStatus(
   }
 
   const locales: LocaleStatus[] = config.target_locales.map((locale) => {
-    const stats = localeStats.get(locale) ?? { complete: 0, missing: 0, outdated: 0 };
+    const stats = localeStats.get(locale) ?? {
+      complete: 0,
+      missing: 0,
+      outdated: 0,
+    };
     const total = stats.complete + stats.missing + stats.outdated;
     const coverage = total > 0 ? Math.round((stats.complete / total) * 100) : 0;
     return { locale, ...stats, coverage };
   });
 
-  return { sourceLocale: config.source_locale, totalKeys, skippedKeys, locales };
+  return {
+    sourceLocale: config.source_locale,
+    totalKeys,
+    skippedKeys,
+    locales,
+  };
 }
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index 58770e27..8e8cdbbd 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -4,7 +4,11 @@ import type { ExtractedEntry, FormatRegistry } from '../formats/index.js';
 import type { TmsClient } from './tms-client.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import { SyncLockManager, computeSourceHash } from './sync-lock.js';
-import { resolveTargetPath, assertPathWithinRoot, mergePulledTranslations } from './sync-utils.js';
+import {
+  resolveTargetPath,
+  assertPathWithinRoot,
+  mergePulledTranslations,
+} from './sync-utils.js';
 import { LOCK_FILE_NAME } from './types.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency, PUSH_CONCURRENCY } from '../utils/concurrency.js';
@@ -48,9 +52,10 @@ const SKIP_REASON_LABELS: Record<SkipReason, string> = {
 export function formatSkippedSummary(skipped: SkippedRecord[]): string {
   if (skipped.length === 0) return '';
   const counts = new Map<SkipReason, number>();
-  for (const s of skipped) counts.set(s.reason, (counts.get(s.reason) ?? 0) + 1);
+  for (const s of skipped)
+    counts.set(s.reason, (counts.get(s.reason) ?? 0) + 1);
   const parts = Array.from(counts.entries()).map(
-    ([reason, count]) => `${count} ${SKIP_REASON_LABELS[reason]}`,
+    ([reason, count]) => `${count} ${SKIP_REASON_LABELS[reason]}`
   );
   return ` (${skipped.length} skipped: ${parts.join(', ')})`;
 }
@@ -59,7 +64,7 @@ export async function pushTranslations(
   config: ResolvedSyncConfig,
   client: TmsClient,
   registry: FormatRegistry,
-  options?: SyncPushPullOptions,
+  options?: SyncPushPullOptions
 ): Promise<PushResult> {
   let pushed = 0;
   const skipped: SkippedRecord[] = [];
@@ -69,27 +74,43 @@ export async function pushTranslations(
     await sweepStaleBackups(
       config.projectRoot,
       resolveBakSweepAgeMs(config.sync?.bak_sweep_max_age_seconds),
-      config.buckets,
+      config.buckets
     );
   } catch {
     /* best-effort */
   }
 
   for await (const walked of walkBuckets(config, registry)) {
-    const { bucketConfig, parser, relPath, content: sourceContent, isMultiLocale } = walked;
+    const {
+      bucketConfig,
+      parser,
+      relPath,
+      content: sourceContent,
+      isMultiLocale,
+    } = walked;
     for (const locale of config.target_locales) {
-      if (options?.localeFilter && !options.localeFilter.includes(locale)) continue;
+      if (options?.localeFilter && !options.localeFilter.includes(locale))
+        continue;
       try {
         let entries: ExtractedEntry[];
         let skippedEntries: ExtractedEntry[];
         if (isMultiLocale) {
-          ({ entries, skippedEntries } = partitionEntries(parser.extract(sourceContent, locale)));
+          ({ entries, skippedEntries } = partitionEntries(
+            parser.extract(sourceContent, locale)
+          ));
         } else {
-          const targetPath = resolveTargetPath(relPath, config.source_locale, locale, bucketConfig.target_path_pattern);
+          const targetPath = resolveTargetPath(
+            relPath,
+            config.source_locale,
+            locale,
+            bucketConfig.target_path_pattern
+          );
           const targetAbsPath = path.join(config.projectRoot, targetPath);
           assertPathWithinRoot(targetAbsPath, config.projectRoot);
           const content = fs.readFileSync(targetAbsPath, 'utf-8');
-          ({ entries, skippedEntries } = partitionEntries(parser.extract(content)));
+          ({ entries, skippedEntries } = partitionEntries(
+            parser.extract(content)
+          ));
         }
         for (const skippedEntry of skippedEntries) {
           skipped.push({
@@ -105,7 +126,7 @@ export async function pushTranslations(
             await client.pushEntry(entry, locale);
             pushed++;
           },
-          pushConcurrency,
+          pushConcurrency
         );
       } catch (err) {
         // Record and continue on "target file does not exist yet" (common on
@@ -124,7 +145,7 @@ export async function pullTranslations(
   config: ResolvedSyncConfig,
   client: TmsClient,
   registry: FormatRegistry,
-  options?: SyncPushPullOptions,
+  options?: SyncPushPullOptions
 ): Promise<PullResult> {
   const lockPath = path.join(config.projectRoot, LOCK_FILE_NAME);
   const lockManager = new SyncLockManager(lockPath);
@@ -137,7 +158,7 @@ export async function pullTranslations(
     await sweepStaleBackups(
       config.projectRoot,
       resolveBakSweepAgeMs(config.sync?.bak_sweep_max_age_seconds),
-      config.buckets,
+      config.buckets
     );
   } catch {
     /* best-effort */
@@ -150,22 +171,39 @@ export async function pullTranslations(
   let localeKeys = new Map<string, Record<string, string>>();
 
   for await (const walked of walkBuckets(config, registry)) {
-    const { bucket, bucketConfig, parser, relPath, content: sourceContent, entries: sourceEntries, isMultiLocale } = walked;
+    const {
+      bucket,
+      bucketConfig,
+      parser,
+      relPath,
+      content: sourceContent,
+      entries: sourceEntries,
+      isMultiLocale,
+    } = walked;
 
     if (bucket !== currentBucket) {
       currentBucket = bucket;
       localeKeys = new Map();
       for (const locale of config.target_locales) {
-        if (options?.localeFilter && !options.localeFilter.includes(locale)) continue;
+        if (options?.localeFilter && !options.localeFilter.includes(locale))
+          continue;
         localeKeys.set(locale, await client.pullKeys(locale));
       }
     }
 
     for (const locale of config.target_locales) {
-      if (options?.localeFilter && !options.localeFilter.includes(locale)) continue;
+      if (options?.localeFilter && !options.localeFilter.includes(locale))
+        continue;
 
       const keys = localeKeys.get(locale)!;
-      const targetRelPath = isMultiLocale ? relPath : resolveTargetPath(relPath, config.source_locale, locale, bucketConfig.target_path_pattern);
+      const targetRelPath = isMultiLocale
+        ? relPath
+        : resolveTargetPath(
+            relPath,
+            config.source_locale,
+            locale,
+            bucketConfig.target_path_pattern
+          );
       const targetAbsPath = path.join(config.projectRoot, targetRelPath);
       assertPathWithinRoot(targetAbsPath, config.projectRoot);
 
@@ -176,14 +214,16 @@ export async function pullTranslations(
         const { entries: existingEntries } = isMultiLocale
           ? partitionEntries(parser.extract(templateContent, locale))
           : partitionEntries(parser.extract(templateContent));
-        existingTargetEntries = new Map(existingEntries.map((entry) => [entry.key, entry.value]));
+        existingTargetEntries = new Map(
+          existingEntries.map((entry) => [entry.key, entry.value])
+        );
       } catch {
         templateContent = sourceContent;
       }
 
       const pulledEntries = sourceEntries
-        .filter(entry => keys[entry.key] !== undefined)
-        .map(entry => ({
+        .filter((entry) => keys[entry.key] !== undefined)
+        .map((entry) => ({
           key: entry.key,
           value: entry.value,
           translation: keys[entry.key]!,
@@ -198,7 +238,7 @@ export async function pullTranslations(
       const translatedEntries = mergePulledTranslations(
         sourceEntries,
         keys,
-        existingTargetEntries,
+        existingTargetEntries
       );
 
       const reconstructed = isMultiLocale
@@ -208,7 +248,7 @@ export async function pullTranslations(
       await atomicWriteFile(targetAbsPath, reconstructed, 'utf-8');
       pulled += pulledEntries.length;
 
-      const fileEntryMap = lockFile.entries[relPath] ??= {};
+      const fileEntryMap = (lockFile.entries[relPath] ??= {});
       for (const entry of pulledEntries) {
         const existing = fileEntryMap[entry.key];
         const existingTranslations = existing?.translations ?? {};
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index 2cdfe3b5..d3ca13de 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -1,12 +1,17 @@
 import * as path from 'path';
 import * as fs from 'fs';
-import type { ExtractedEntry, FormatRegistry, FormatParser, TranslatedEntry } from '../formats/index.js';
+import type {
+  ExtractedEntry,
+  FormatRegistry,
+  FormatParser,
+  TranslatedEntry,
+} from '../formats/index.js';
 import { ValidationError } from '../utils/errors.js';
 import { sanitizeForTerminal } from '../utils/control-chars.js';
 
 export function getParserForBucket(
   formatRegistry: FormatRegistry,
-  formatKey: string,
+  formatKey: string
 ): FormatParser | undefined {
   return formatRegistry.getParserByFormatKey(formatKey);
 }
@@ -14,14 +19,17 @@ export function getParserForBucket(
 export function mergePulledTranslations(
   sourceEntries: ExtractedEntry[],
   pulledKeys: Record<string, string>,
-  existingTargetEntries: Map<string, string> = new Map(),
+  existingTargetEntries: Map<string, string> = new Map()
 ): TranslatedEntry[] {
   return sourceEntries.map((entry) => ({
     key: entry.key,
     value: entry.value,
     context: entry.context,
     metadata: entry.metadata,
-    translation: pulledKeys[entry.key] ?? existingTargetEntries.get(entry.key) ?? entry.value,
+    translation:
+      pulledKeys[entry.key] ??
+      existingTargetEntries.get(entry.key) ??
+      entry.value,
   }));
 }
 
@@ -38,7 +46,7 @@ export function resolveTargetPath(
   sourcePath: string,
   sourceLocale: string,
   targetLocale: string,
-  targetPathPattern?: string,
+  targetPathPattern?: string
 ): string {
   if (targetPathPattern) {
     return targetPathPattern
@@ -49,13 +57,13 @@ export function resolveTargetPath(
   const escaped = sourceLocale.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const result = sourcePath.replace(
     new RegExp(`(^|[/_.])${escaped}([/_.])`, 'g'),
-    (_match: string, p1: string, p2: string) => p1 + targetLocale + p2,
+    (_match: string, p1: string, p2: string) => p1 + targetLocale + p2
   );
 
   if (result === sourcePath) {
     const result2 = sourcePath.replace(
       new RegExp(`${escaped}(\\.[^./]+)$`),
-      (_match: string, p1: string) => targetLocale + p1,
+      (_match: string, p1: string) => targetLocale + p1
     );
     if (result2 !== sourcePath) return result2;
   }
@@ -63,7 +71,7 @@ export function resolveTargetPath(
   if (result === sourcePath) {
     throw new ValidationError(
       `Cannot resolve target path: locale "${sanitizeForTerminal(sourceLocale)}" not found in path "${sanitizeForTerminal(sourcePath)}". ` +
-      `Ensure the source file path contains the source locale code.`,
+        `Ensure the source file path contains the source locale code.`
     );
   }
 
@@ -113,10 +121,18 @@ function realpathOrAncestor(absPath: string): string {
  * unresolved form. Symlink-based escapes (a symlink inside the project
  * pointing outside) are now also caught.
  */
-export function assertPathWithinRoot(absPath: string, projectRoot: string): void {
+export function assertPathWithinRoot(
+  absPath: string,
+  projectRoot: string
+): void {
   const resolvedRoot = realpathOrAncestor(projectRoot);
   const resolvedPath = realpathOrAncestor(absPath);
-  if (!resolvedPath.startsWith(resolvedRoot + path.sep) && resolvedPath !== resolvedRoot) {
-    throw new ValidationError(`Target path escapes project root: ${sanitizeForTerminal(absPath)}`);
+  if (
+    !resolvedPath.startsWith(resolvedRoot + path.sep) &&
+    resolvedPath !== resolvedRoot
+  ) {
+    throw new ValidationError(
+      `Target path escapes project root: ${sanitizeForTerminal(absPath)}`
+    );
   }
 }
diff --git a/src/sync/sync-validate.ts b/src/sync/sync-validate.ts
index 811a4420..be131d77 100644
--- a/src/sync/sync-validate.ts
+++ b/src/sync/sync-validate.ts
@@ -1,7 +1,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import type { FormatRegistry } from '../formats/index.js';
-import { validateBatch, type ValidationResult } from './translation-validator.js';
+import {
+  validateBatch,
+  type ValidationResult,
+} from './translation-validator.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import { extractTranslatable, walkBuckets } from './sync-bucket-walker.js';
@@ -21,13 +24,20 @@ export interface ValidateResult {
 
 export async function validateTranslations(
   config: ResolvedSyncConfig,
-  formatRegistry: FormatRegistry,
+  formatRegistry: FormatRegistry
 ): Promise<ValidateResult> {
   const allIssues: ValidateIssue[] = [];
   let totalChecked = 0;
 
   for await (const walked of walkBuckets(config, formatRegistry)) {
-    const { bucketConfig, parser, relPath, content: sourceContent, entries: sourceEntries, isMultiLocale } = walked;
+    const {
+      bucketConfig,
+      parser,
+      relPath,
+      content: sourceContent,
+      entries: sourceEntries,
+      isMultiLocale,
+    } = walked;
 
     for (const locale of config.target_locales) {
       let targetEntries;
@@ -37,7 +47,12 @@ export async function validateTranslations(
         targetRelPath = relPath;
         targetEntries = extractTranslatable(parser, sourceContent, locale);
       } else {
-        targetRelPath = resolveTargetPath(relPath, config.source_locale, locale, bucketConfig.target_path_pattern);
+        targetRelPath = resolveTargetPath(
+          relPath,
+          config.source_locale,
+          locale,
+          bucketConfig.target_path_pattern
+        );
         const targetAbsPath = path.join(config.projectRoot, targetRelPath);
         assertPathWithinRoot(targetAbsPath, config.projectRoot);
 
@@ -47,7 +62,10 @@ export async function validateTranslations(
           continue;
         }
 
-        const targetContent = await fs.promises.readFile(targetAbsPath, 'utf-8');
+        const targetContent = await fs.promises.readFile(
+          targetAbsPath,
+          'utf-8'
+        );
         targetEntries = extractTranslatable(parser, targetContent);
       }
 
@@ -64,7 +82,9 @@ export async function validateTranslations(
       totalChecked += pairs.length;
       const results = validateBatch(pairs);
       const issuesOnly = results.filter((r) => r.severity !== 'pass');
-      allIssues.push(...issuesOnly.map((r) => ({ ...r, locale, file: targetRelPath })));
+      allIssues.push(
+        ...issuesOnly.map((r) => ({ ...r, locale, file: targetRelPath }))
+      );
     }
   }
 
diff --git a/src/sync/tm-cache.ts b/src/sync/tm-cache.ts
index 6e74ac72..61ec941c 100644
--- a/src/sync/tm-cache.ts
+++ b/src/sync/tm-cache.ts
@@ -19,11 +19,14 @@ export interface TmCacheLike {
  * process.
  */
 export class TmCache implements TmCacheLike {
-  private readonly entries = new Map<string, { value: string; expiresAt: number }>();
+  private readonly entries = new Map<
+    string,
+    { value: string; expiresAt: number }
+  >();
 
   constructor(
     private readonly ttlMs: number = TmCache.DEFAULT_TTL_MS,
-    private readonly now: () => number = Date.now,
+    private readonly now: () => number = Date.now
   ) {}
 
   static readonly DEFAULT_TTL_MS = 5 * 60_000;
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index ccb2745a..c657181c 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -17,38 +17,41 @@ export function sanitizePullKeysResponse(raw: unknown): Record<string, string> {
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
     throw new ValidationError(
       'TMS pull response must be a JSON object mapping keys to string values',
-      'Check that your TMS server returns the documented shape: {"<key>": "<translation>", ...}.',
+      'Check that your TMS server returns the documented shape: {"<key>": "<translation>", ...}.'
     );
   }
   const keys = Object.keys(raw);
   if (keys.length > MAX_PULL_KEY_COUNT) {
     throw new ValidationError(
       `TMS pull response exceeds MAX_PULL_KEY_COUNT (${MAX_PULL_KEY_COUNT})`,
-      `Partition the TMS export by locale, or paginate the pull.`,
+      `Partition the TMS export by locale, or paginate the pull.`
     );
   }
   // Null-prototype: callers test membership with `result[key] !== undefined`
   // and `??`, so an inherited Object.prototype member for a key named
   // "toString" or "constructor" would read as an approved translation and
   // silently replace the real one.
-  const result: Record<string, string> = Object.create(null) as Record<string, string>;
+  const result: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
   for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
     if (KEY_FORBIDDEN_CHARS.test(key)) {
       throw new ValidationError(
         `TMS pull response contains invalid key "${key.replace(VALUE_CONTROL_CHARS, '?')}" (path separators and control chars are not permitted)`,
-        'Check your TMS for keys containing "/", "\\", or control characters; these cannot be written to the filesystem safely.',
+        'Check your TMS for keys containing "/", "\\", or control characters; these cannot be written to the filesystem safely.'
       );
     }
     if (typeof value !== 'string') {
       throw new ValidationError(
         `TMS pull response contains non-string value for key "${key.replace(VALUE_CONTROL_CHARS, '?')}" (got ${value === null ? 'null' : typeof value})`,
-        'Check that your TMS server returns string translations; nested objects, arrays, numbers, and null are not supported.',
+        'Check that your TMS server returns string translations; nested objects, arrays, numbers, and null are not supported.'
       );
     }
     if (Buffer.byteLength(value, 'utf8') > MAX_PULL_VALUE_BYTES) {
       throw new ValidationError(
         `TMS pull response value for key "${key.replace(VALUE_CONTROL_CHARS, '?')}" exceeds the ${MAX_PULL_VALUE_BYTES / 1024}KiB per-value limit`,
-        'Split oversized translations into smaller keys, or raise the issue with your TMS administrator.',
+        'Split oversized translations into smaller keys, or raise the issue with your TMS administrator.'
       );
     }
     result[key] = value.replace(VALUE_CONTROL_CHARS, '');
@@ -59,7 +62,10 @@ export function sanitizePullKeysResponse(raw: unknown): Record<string, string> {
 /** A TMS request that hit the client-side timeout; classified as a network error (exit 5). */
 export class TmsTimeoutError extends NetworkError {
   constructor(message: string) {
-    super(message, 'Raise timeout_ms in the tms: block of .deepl-sync.yaml, or check that the TMS server is reachable.');
+    super(
+      message,
+      'Raise timeout_ms in the tms: block of .deepl-sync.yaml, or check that the TMS server is reachable.'
+    );
     this.name = 'TmsTimeoutError';
   }
 }
@@ -88,16 +94,23 @@ const DEFAULT_RETRY_MAX_DELAY_MS = 10000;
 const ERROR_BODY_MAX_BYTES = 1024;
 
 const RETRIABLE_STATUS = new Set([429, 503]);
-const RETRIABLE_NETWORK_CODES = new Set(['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED', 'EAI_AGAIN']);
+const RETRIABLE_NETWORK_CODES = new Set([
+  'ECONNRESET',
+  'ETIMEDOUT',
+  'ECONNREFUSED',
+  'EAI_AGAIN',
+]);
 
 function isRetriableNetworkError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
   const code = (err as NodeJS.ErrnoException).code;
-  if (typeof code === 'string' && RETRIABLE_NETWORK_CODES.has(code)) return true;
+  if (typeof code === 'string' && RETRIABLE_NETWORK_CODES.has(code))
+    return true;
   const cause = (err as { cause?: unknown }).cause;
   if (cause && typeof cause === 'object') {
     const causeCode = (cause as { code?: unknown }).code;
-    if (typeof causeCode === 'string' && RETRIABLE_NETWORK_CODES.has(causeCode)) return true;
+    if (typeof causeCode === 'string' && RETRIABLE_NETWORK_CODES.has(causeCode))
+      return true;
   }
   return false;
 }
@@ -110,7 +123,7 @@ function computeBackoffDelay(
   attempt: number,
   baseDelayMs: number,
   maxDelayMs: number,
-  jitter: boolean,
+  jitter: boolean
 ): number {
   const exp = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
   if (!jitter) return exp;
@@ -127,7 +140,10 @@ async function readErrorBody(response: Response): Promise<string> {
   try {
     const text = await response.text();
     if (!text) return '';
-    const truncated = text.length > ERROR_BODY_MAX_BYTES ? text.slice(0, ERROR_BODY_MAX_BYTES) + '...' : text;
+    const truncated =
+      text.length > ERROR_BODY_MAX_BYTES
+        ? text.slice(0, ERROR_BODY_MAX_BYTES) + '...'
+        : text;
     return sanitizeForTerminal(truncated);
   } catch {
     return '';
@@ -137,7 +153,7 @@ async function readErrorBody(response: Response): Promise<string> {
 function oversizedBodyError(): ValidationError {
   return new ValidationError(
     `TMS pull response exceeds the ${MAX_PULL_BODY_BYTES / (1024 * 1024)}MiB response size limit`,
-    'Partition the TMS export by locale, or paginate the pull.',
+    'Partition the TMS export by locale, or paginate the pull.'
   );
 }
 
@@ -190,26 +206,35 @@ export class TmsClient {
   }
 
   private getAuthHeader(): Record<string, string> {
-    if (this.options.apiKey) return { Authorization: `ApiKey ${this.options.apiKey}` };
-    if (this.options.token) return { Authorization: `Bearer ${this.options.token}` };
+    if (this.options.apiKey)
+      return { Authorization: `ApiKey ${this.options.apiKey}` };
+    if (this.options.token)
+      return { Authorization: `Bearer ${this.options.token}` };
     return {};
   }
 
-  private async fetchOnce(url: string, method: string, body?: unknown): Promise<Response> {
+  private async fetchOnce(
+    url: string,
+    method: string,
+    body?: unknown
+  ): Promise<Response> {
     const fetchImpl = this.options.fetch ?? globalThis.fetch;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
       return await fetchImpl(url, {
         method,
-        headers: { 'Content-Type': 'application/json', ...this.getAuthHeader() },
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.getAuthHeader(),
+        },
         body: body ? JSON.stringify(body) : undefined,
         signal: controller.signal,
       });
     } catch (err) {
       if (isAbortError(err)) {
         throw new TmsTimeoutError(
-          `TMS request timed out after ${this.timeoutMs}ms: ${method} ${sanitizeUrl(url)}`,
+          `TMS request timed out after ${this.timeoutMs}ms: ${method} ${sanitizeUrl(url)}`
         );
       }
       throw err;
@@ -227,17 +252,20 @@ export class TmsClient {
     try {
       parsedUrl = new URL(this.options.serverUrl);
     } catch {
-      throw new ConfigError(`Invalid TMS server URL: ${sanitizeUrl(this.options.serverUrl)}`);
+      throw new ConfigError(
+        `Invalid TMS server URL: ${sanitizeUrl(this.options.serverUrl)}`
+      );
     }
 
-    const isLocalhost = parsedUrl.hostname === 'localhost' || parsedUrl.hostname === '127.0.0.1';
+    const isLocalhost =
+      parsedUrl.hostname === 'localhost' || parsedUrl.hostname === '127.0.0.1';
     if (parsedUrl.protocol !== 'https:' && !isLocalhost) {
       throw new ConfigError('TMS server URL must use HTTPS');
     }
     if (parsedUrl.search || parsedUrl.hash) {
       throw new ConfigError(
         `TMS server URL must not contain a query string or fragment: ${sanitizeUrl(this.options.serverUrl)}`,
-        'Set server: to the bare origin (plus a base path if your TMS is mounted under one).',
+        'Set server: to the bare origin (plus a base path if your TMS is mounted under one).'
       );
     }
 
@@ -246,7 +274,11 @@ export class TmsClient {
     return new URL(`${projectPath}${path}`, parsedUrl).toString();
   }
 
-  private async request(method: string, path: string, body?: unknown): Promise<Response> {
+  private async request(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<Response> {
     const url = this.buildUrl(path);
 
     let lastError: unknown;
@@ -256,9 +288,15 @@ export class TmsClient {
         response = await this.fetchOnce(url, method, body);
       } catch (err) {
         lastError = err;
-        const retriable = err instanceof TmsTimeoutError || isRetriableNetworkError(err);
+        const retriable =
+          err instanceof TmsTimeoutError || isRetriableNetworkError(err);
         if (!retriable || attempt === this.retry.maxAttempts - 1) throw err;
-        const delay = computeBackoffDelay(attempt, this.retry.baseDelayMs, this.retry.maxDelayMs, this.retry.jitter);
+        const delay = computeBackoffDelay(
+          attempt,
+          this.retry.baseDelayMs,
+          this.retry.maxDelayMs,
+          this.retry.jitter
+        );
         await sleep(delay);
         continue;
       }
@@ -268,12 +306,20 @@ export class TmsClient {
       if (response.status === 401 || response.status === 403) {
         throw new ConfigError(
           `TMS authentication failed (${response.status} ${response.statusText})`,
-          'Check that TMS_API_KEY or TMS_TOKEN is set correctly, and that the server and project_id in your .deepl-sync.yaml match the TMS you intended to reach.',
+          'Check that TMS_API_KEY or TMS_TOKEN is set correctly, and that the server and project_id in your .deepl-sync.yaml match the TMS you intended to reach.'
         );
       }
 
-      if (RETRIABLE_STATUS.has(response.status) && attempt < this.retry.maxAttempts - 1) {
-        const delay = computeBackoffDelay(attempt, this.retry.baseDelayMs, this.retry.maxDelayMs, this.retry.jitter);
+      if (
+        RETRIABLE_STATUS.has(response.status) &&
+        attempt < this.retry.maxAttempts - 1
+      ) {
+        const delay = computeBackoffDelay(
+          attempt,
+          this.retry.baseDelayMs,
+          this.retry.maxDelayMs,
+          this.retry.jitter
+        );
         await sleep(delay);
         lastError = response;
         continue;
@@ -281,7 +327,9 @@ export class TmsClient {
 
       const bodyText = await readErrorBody(response);
       const suffix = bodyText ? `: ${bodyText}` : '';
-      throw new Error(`TMS API error: ${response.status} ${sanitizeForTerminal(response.statusText)}${suffix}`);
+      throw new Error(
+        `TMS API error: ${response.status} ${sanitizeForTerminal(response.statusText)}${suffix}`
+      );
     }
 
     throw lastError instanceof Error
@@ -290,22 +338,28 @@ export class TmsClient {
   }
 
   async pushKey(keyPath: string, locale: string, value: string): Promise<void> {
-    await this.request('PUT', `/keys/${encodeURIComponent(keyPath)}`, { locale, value });
+    await this.request('PUT', `/keys/${encodeURIComponent(keyPath)}`, {
+      locale,
+      value,
+    });
   }
 
   async pushEntry(entry: ExtractedEntry, locale: string): Promise<void> {
     if (entry.metadata && 'skipped' in entry.metadata) {
       throw new Error(
         `TmsClient.pushEntry refused to push key "${entry.key}" (locale=${locale}): ` +
-        `entry is tagged metadata.skipped and must be filtered by the walker ` +
-        `skip-partition (partitionEntries in src/sync/sync-bucket-walker.ts) before reaching push.`,
+          `entry is tagged metadata.skipped and must be filtered by the walker ` +
+          `skip-partition (partitionEntries in src/sync/sync-bucket-walker.ts) before reaching push.`
       );
     }
     await this.pushKey(entry.key, locale, entry.value);
   }
 
   async pullKeys(locale: string): Promise<Record<string, string>> {
-    const resp = await this.request('GET', `/keys/export?format=json&locale=${encodeURIComponent(locale)}`);
+    const resp = await this.request(
+      'GET',
+      `/keys/export?format=json&locale=${encodeURIComponent(locale)}`
+    );
     return sanitizePullKeysResponse(await readJsonBounded(resp));
   }
 
@@ -315,22 +369,32 @@ export class TmsClient {
   }
 }
 
-export function resolveTmsCredentials(config: { api_key?: string; token?: string }): { apiKey?: string; token?: string } {
+export function resolveTmsCredentials(config: {
+  api_key?: string;
+  token?: string;
+}): { apiKey?: string; token?: string } {
   const apiKey = process.env['TMS_API_KEY'] ?? config.api_key;
   const token = process.env['TMS_TOKEN'] ?? config.token;
 
   if (!process.env['TMS_API_KEY'] && config.api_key) {
-    Logger.warn('Warning: TMS API key found in config file. Use TMS_API_KEY env var instead to avoid committing secrets.');
+    Logger.warn(
+      'Warning: TMS API key found in config file. Use TMS_API_KEY env var instead to avoid committing secrets.'
+    );
   }
   if (!process.env['TMS_TOKEN'] && config.token) {
-    Logger.warn('Warning: TMS token found in config file. Use TMS_TOKEN env var instead to avoid committing secrets.');
+    Logger.warn(
+      'Warning: TMS token found in config file. Use TMS_TOKEN env var instead to avoid committing secrets.'
+    );
   }
 
   return { apiKey, token };
 }
 
 export function createTmsClient(config: SyncTmsConfig): TmsClient {
-  const { apiKey, token } = resolveTmsCredentials({ api_key: config.api_key, token: config.token });
+  const { apiKey, token } = resolveTmsCredentials({
+    api_key: config.api_key,
+    token: config.token,
+  });
   return new TmsClient({
     serverUrl: config.server,
     projectId: config.project_id,
diff --git a/src/sync/translation-validator.ts b/src/sync/translation-validator.ts
index 590b6c33f6b9f9034a0df9dd990ec0cc1c4cd0f2..4635ce9fc613afba2041481cdafba8fe2b3e1f1f 100644
GIT binary patch
delta 544
zcmZp2dgHv|G$Rw2!sgSA+nFYp$Z0TgO<o`&KY5Rw?B<6oR?Hk+3J@?^nnMo3vE)!-
z*MUe)j^sFvkieyCa}wucW>&C{$*#N#5Z2~YUU7t_lACw%w=r@<EvyF8lN|(=CvO&(
zo?Io^%Bi4G3$byNP(P}wiNY#iRiR?SlkW;gO*R#=pIjsoh|n?lKfl=ITOwUh`%^@f
znL(zvi<&@1c8kh^MQ)1Pqu7sZa+;X`<jrD+lOKttAWYuuE^fdyxkgf%S<{+p@@-Mc
z$@?V*P>i@JsW7=jT59qkc9F@_QWlc~rJNAjC%cO)PR^HLoxDqm7asVMlTBnqCW}j3
zp_mgatqeA&N7@QWzmKc}SpOSo9u)l*D0<h)K=eMBL3X;2YyjitxpLnbCr?!{VF3mE
T<N!I*$@diGLD32HPc0V!zA%Jo

delta 355
zcmaFk+~l<3G~?#8jN6$e%Sk$IKEo2uJefsWaIy^t@8m!Zg~=5hr;+)aXK+4dp4`Bz
zuz4x3I7o}l=70Qcj7-&BllujgCvOpyoP36zYw}IOO2*pF(L()TnU!KHP#KQNb|RdU
zJw+lWFBY+#{7A%~v39bR=z_`jMU^MBikVEd6O)@9FJ=!i4qek<G2h8P;`)<o#gl+W
zzYsTIV&zf*g2@t6%4|A7rl$4e1a_s#@lqTT)nFL~h2)IX<ZLSi^^B6-9Nm({^vUNq
zbSCeRa+v%}$^mHe3vtECDbhld;}zH@t4Nwn-XZM=vRP0@dGZYo#mSK}`ane!Weh>y
z1WJlbmXJ*WDQK4kDNvexK{f*D6hpZHMn;{@jq=}t)Z|8ak;y%Z3X?Y|ny_kGbJcPI
E0G@(xssI20

diff --git a/src/sync/types.ts b/src/sync/types.ts
index 27a27bc3..f78e2ca3 100644
--- a/src/sync/types.ts
+++ b/src/sync/types.ts
@@ -197,7 +197,9 @@ export const HARD_MAX_SYNC_LIMITS: Required<SyncLimits> = {
   max_source_files: 1_000_000,
 };
 
-export function resolveSyncLimits(config: { sync?: SyncBehavior }): Required<SyncLimits> {
+export function resolveSyncLimits(config: {
+  sync?: SyncBehavior;
+}): Required<SyncLimits> {
   const user = config.sync?.limits;
   return {
     max_entries_per_file:
diff --git a/src/types/api.ts b/src/types/api.ts
index cfc2e429..67d73406 100644
--- a/src/types/api.ts
+++ b/src/types/api.ts
@@ -6,9 +6,7 @@ import { Language, Formality } from './common.js';
 import { WRITE_TARGET_LANGUAGES } from '../data/language-entries.js';
 
 export type ModelType =
-  | 'quality_optimized'
-  | 'prefer_quality_optimized'
-  | 'latency_optimized';
+  'quality_optimized' | 'prefer_quality_optimized' | 'latency_optimized';
 
 export interface TranslationOptions {
   sourceLang?: Language;
@@ -95,11 +93,13 @@ export interface WriteImprovement {
   detectedSourceLanguage?: string;
 }
 
-export function isWriteImprovementArray(data: unknown): data is WriteImprovement[] {
+export function isWriteImprovementArray(
+  data: unknown
+): data is WriteImprovement[] {
   if (!Array.isArray(data)) {
     return false;
   }
-  return data.every(item => {
+  return data.every((item) => {
     if (item === null || typeof item !== 'object') {
       return false;
     }
@@ -125,7 +125,17 @@ export interface DocumentStatus {
   errorMessage?: string;
 }
 
-export type DocumentOutputFormat = 'pdf' | 'docx' | 'pptx' | 'xlsx' | 'html' | 'htm' | 'txt' | 'srt' | 'xlf' | 'xliff';
+export type DocumentOutputFormat =
+  | 'pdf'
+  | 'docx'
+  | 'pptx'
+  | 'xlsx'
+  | 'html'
+  | 'htm'
+  | 'txt'
+  | 'srt'
+  | 'xlf'
+  | 'xliff';
 
 export interface DocumentTranslationOptions {
   sourceLang?: Language;
diff --git a/src/types/glossary.ts b/src/types/glossary.ts
index 444ec9bc..aab1e817 100644
--- a/src/types/glossary.ts
+++ b/src/types/glossary.ts
@@ -45,14 +45,14 @@ export interface LanguagePairInfo {
  */
 export function normalizeGlossaryInfo(
   response: GlossaryApiResponse,
-  options: { warnOnEmpty?: boolean } = {},
+  options: { warnOnEmpty?: boolean } = {}
 ): GlossaryInfo {
   const { warnOnEmpty = true } = options;
   // Extract unique source and target languages from dictionaries
   const sourceLangs = new Set<Language>();
   const targetLangs = new Set<Language>();
 
-  response.dictionaries.forEach(dict => {
+  response.dictionaries.forEach((dict) => {
     sourceLangs.add(dict.source_lang.toLowerCase() as Language);
     targetLangs.add(dict.target_lang.toLowerCase() as Language);
   });
@@ -64,7 +64,9 @@ export function normalizeGlossaryInfo(
     source_lang = Array.from(sourceLangs)[0]!;
   } else {
     if (warnOnEmpty) {
-      Logger.warn('Glossary has empty dictionaries; defaulting source language to "en"');
+      Logger.warn(
+        'Glossary has empty dictionaries; defaulting source language to "en"'
+      );
     }
     source_lang = 'en';
   }
@@ -94,7 +96,10 @@ export function getTotalEntryCount(glossary: GlossaryInfo): number {
  * Helper: Get target language (specified or default to first)
  * Throws error if target is required but not provided
  */
-export function getTargetLang(glossary: GlossaryInfo, targetLang?: Language): Language {
+export function getTargetLang(
+  glossary: GlossaryInfo,
+  targetLang?: Language
+): Language {
   // If specified, validate it exists
   if (targetLang) {
     if (!glossary.target_langs.includes(targetLang)) {
diff --git a/src/types/voice.ts b/src/types/voice.ts
index 77537d2f..639c474d 100644
--- a/src/types/voice.ts
+++ b/src/types/voice.ts
@@ -3,7 +3,6 @@
  * Types for DeepL Voice API real-time speech transcription and translation.
  */
 
-
 // Source languages supported by the Voice API (30 languages)
 export type VoiceSourceLanguage =
   | 'ar'
@@ -105,7 +104,14 @@ export type VoiceSourceMediaContentType =
 export type VoiceSourceLanguageMode = 'auto' | 'fixed';
 
 // Voice-specific formality values (differs from text translation API)
-export type VoiceFormality = 'default' | 'formal' | 'more' | 'informal' | 'less' | 'prefer_more' | 'prefer_less';
+export type VoiceFormality =
+  | 'default'
+  | 'formal'
+  | 'more'
+  | 'informal'
+  | 'less'
+  | 'prefer_more'
+  | 'prefer_less';
 
 // REST endpoint: POST /v3/voice/realtime
 
diff --git a/src/utils/atomic-write.ts b/src/utils/atomic-write.ts
index 38942a0d..b77447e5 100644
--- a/src/utils/atomic-write.ts
+++ b/src/utils/atomic-write.ts
@@ -82,9 +82,14 @@ export function __getInFlightTmpCount(): number {
 export async function atomicWriteFile(
   filePath: string,
   content: string | Buffer,
-  encoding?: BufferEncoding,
+  encoding?: BufferEncoding
 ): Promise<void> {
-  const tmpPath = filePath + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 8);
+  const tmpPath =
+    filePath +
+    '.tmp.' +
+    process.pid +
+    '.' +
+    Math.random().toString(36).slice(2, 8);
   let existingMode: number | undefined;
   try {
     existingMode = (await fs.promises.stat(filePath)).mode & 0o7777;
@@ -93,13 +98,21 @@ export async function atomicWriteFile(
   }
   registerTmp(tmpPath);
   try {
-    await fs.promises.writeFile(tmpPath, content, encoding ? { encoding } : undefined);
+    await fs.promises.writeFile(
+      tmpPath,
+      content,
+      encoding ? { encoding } : undefined
+    );
     if (existingMode !== undefined) {
       await fs.promises.chmod(tmpPath, existingMode);
     }
     await fs.promises.rename(tmpPath, filePath);
   } catch (error) {
-    try { await fs.promises.unlink(tmpPath); } catch { /* ignore cleanup errors */ }
+    try {
+      await fs.promises.unlink(tmpPath);
+    } catch {
+      /* ignore cleanup errors */
+    }
     throw error;
   } finally {
     unregisterTmp(tmpPath);
@@ -112,9 +125,14 @@ export async function atomicWriteFile(
 export function atomicWriteFileSync(
   filePath: string,
   content: string | Buffer,
-  encoding?: BufferEncoding,
+  encoding?: BufferEncoding
 ): void {
-  const tmpPath = filePath + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 8);
+  const tmpPath =
+    filePath +
+    '.tmp.' +
+    process.pid +
+    '.' +
+    Math.random().toString(36).slice(2, 8);
   let existingMode: number | undefined;
   try {
     existingMode = fs.statSync(filePath).mode & 0o7777;
@@ -129,7 +147,11 @@ export function atomicWriteFileSync(
     }
     fs.renameSync(tmpPath, filePath);
   } catch (error) {
-    try { fs.unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      /* ignore cleanup errors */
+    }
     throw error;
   } finally {
     unregisterTmp(tmpPath);
diff --git a/src/utils/errors.ts b/src/utils/errors.ts
index 05c99cd5..af09e98c 100644
--- a/src/utils/errors.ts
+++ b/src/utils/errors.ts
@@ -21,28 +21,44 @@ export abstract class DeepLCLIError extends Error {
 export class AuthError extends DeepLCLIError {
   readonly exitCode = 2;
   constructor(message: string, suggestion?: string) {
-    super(message, suggestion ?? 'Run: deepl init (setup wizard) or deepl auth set-key <your-api-key>');
+    super(
+      message,
+      suggestion ??
+        'Run: deepl init (setup wizard) or deepl auth set-key <your-api-key>'
+    );
   }
 }
 
 export class RateLimitError extends DeepLCLIError {
   readonly exitCode = 3;
   constructor(message: string, suggestion?: string) {
-    super(message, suggestion ?? 'Wait a moment and retry, or reduce concurrency with --concurrency flag');
+    super(
+      message,
+      suggestion ??
+        'Wait a moment and retry, or reduce concurrency with --concurrency flag'
+    );
   }
 }
 
 export class QuotaError extends DeepLCLIError {
   readonly exitCode = 4;
   constructor(message: string, suggestion?: string) {
-    super(message, suggestion ?? 'Run: deepl usage to check your limits, or upgrade your plan at https://www.deepl.com/pro');
+    super(
+      message,
+      suggestion ??
+        'Run: deepl usage to check your limits, or upgrade your plan at https://www.deepl.com/pro'
+    );
   }
 }
 
 export class NetworkError extends DeepLCLIError {
   readonly exitCode = 5;
   constructor(message: string, suggestion?: string) {
-    super(message, suggestion ?? 'Check your internet connection and proxy settings (HTTPS_PROXY or HTTP_PROXY environment variable)');
+    super(
+      message,
+      suggestion ??
+        'Check your internet connection and proxy settings (HTTPS_PROXY or HTTP_PROXY environment variable)'
+    );
   }
 }
 
@@ -57,7 +73,11 @@ export class ConfigError extends DeepLCLIError {
 export class VoiceError extends DeepLCLIError {
   readonly exitCode = 9;
   constructor(message: string, suggestion?: string) {
-    super(message, suggestion ?? 'The Voice API requires a DeepL Pro or Enterprise plan. Visit https://www.deepl.com/pro to upgrade.');
+    super(
+      message,
+      suggestion ??
+        'The Voice API requires a DeepL Pro or Enterprise plan. Visit https://www.deepl.com/pro to upgrade.'
+    );
   }
 }
 
@@ -74,7 +94,7 @@ export class SyncConflictError extends DeepLCLIError {
     super(
       message,
       suggestion ??
-        'Edit .deepl-sync.lock to resolve conflict markers manually, then run `deepl sync` to fill gaps.',
+        'Edit .deepl-sync.lock to resolve conflict markers manually, then run `deepl sync` to fill gaps.'
     );
     // Preserve the existing JSON error-envelope code "SyncConflict" (the
     // class-name-based default would emit "SyncConflictError" and break the
@@ -89,7 +109,7 @@ export class SyncPartialFailureError extends DeepLCLIError {
     super(
       message,
       suggestion ??
-        'Inspect the per-locale error report in the sync output, then re-run `deepl sync --locale <failed>` to retry just the failed locales.',
+        'Inspect the per-locale error report in the sync output, then re-run `deepl sync --locale <failed>` to retry just the failed locales.'
     );
     // Match the SyncConflictError envelope-naming pattern so the JSON
     // error envelope emits `code: "SyncPartialFailure"` rather than
diff --git a/src/utils/exit-codes.ts b/src/utils/exit-codes.ts
index 6b156f72..f726424e 100644
--- a/src/utils/exit-codes.ts
+++ b/src/utils/exit-codes.ts
@@ -67,7 +67,9 @@ export function exitCodeForError(error: unknown): ExitCode {
 }
 
 function classifyByMessage(rawMessage: string): ExitCode {
-  Logger.verbose(`Untyped error reached fallback classifier: "${rawMessage.substring(0, 120)}"`);
+  Logger.verbose(
+    `Untyped error reached fallback classifier: "${rawMessage.substring(0, 120)}"`
+  );
   const message = rawMessage.toLowerCase();
 
   if (
@@ -112,10 +114,7 @@ function classifyByMessage(rawMessage: string): ExitCode {
     return ExitCode.NetworkError;
   }
 
-  if (
-    message.includes('voice api') ||
-    message.includes('voice session')
-  ) {
+  if (message.includes('voice api') || message.includes('voice session')) {
     return ExitCode.VoiceError;
   }
 
@@ -161,7 +160,6 @@ function classifyByMessage(rawMessage: string): ExitCode {
 
 export function isRetryableError(exitCode: ExitCode): boolean {
   return (
-    exitCode === ExitCode.RateLimitError ||
-    exitCode === ExitCode.NetworkError
+    exitCode === ExitCode.RateLimitError || exitCode === ExitCode.NetworkError
   );
 }
diff --git a/src/utils/formality.ts b/src/utils/formality.ts
index 27a60d66..c88c98cb 100644
--- a/src/utils/formality.ts
+++ b/src/utils/formality.ts
@@ -8,7 +8,10 @@ const VOICE_FORMALITY_MAP: Record<string, string> = {
   prefer_less: 'informal',
 };
 
-export function normalizeFormality(value: string, api: 'text' | 'voice'): string {
+export function normalizeFormality(
+  value: string,
+  api: 'text' | 'voice'
+): string {
   const map = api === 'text' ? TEXT_FORMALITY_MAP : VOICE_FORMALITY_MAP;
   return map[value] ?? value;
 }
diff --git a/src/utils/formatters.ts b/src/utils/formatters.ts
index b64506a0..206d9eac 100644
--- a/src/utils/formatters.ts
+++ b/src/utils/formatters.ts
@@ -87,14 +87,22 @@ export function formatTranslationJson(
  * Format multiple translation results as JSON
  */
 export function formatMultiTranslationJson(
-  results: Array<{ targetLang: Language; text: string; detectedSourceLang?: Language; billedCharacters?: number; modelTypeUsed?: string }>
+  results: Array<{
+    targetLang: Language;
+    text: string;
+    detectedSourceLang?: Language;
+    billedCharacters?: number;
+    modelTypeUsed?: string;
+  }>
 ): string {
   const output: MultiTranslateJsonOutput = {
-    translations: results.map(r => ({
+    translations: results.map((r) => ({
       targetLang: r.targetLang,
       text: r.text,
       detectedSourceLang: r.detectedSourceLang,
-      ...(r.billedCharacters !== undefined && { billedCharacters: r.billedCharacters }),
+      ...(r.billedCharacters !== undefined && {
+        billedCharacters: r.billedCharacters,
+      }),
       ...(r.modelTypeUsed && { modelTypeUsed: r.modelTypeUsed }),
     })),
   };
@@ -134,21 +142,20 @@ export function formatMultiTranslationTable(
   }>
 ): string {
   // Check if any result has billedCharacters - if so, show the Characters column
-  const showCharacters = results.some(r => r.billedCharacters !== undefined);
+  const showCharacters = results.some((r) => r.billedCharacters !== undefined);
   const colorDisabled = !isColorEnabled();
 
   const table = new Table({
-    head: showCharacters ? ['Language', 'Translation', 'Characters'] : ['Language', 'Translation'],
+    head: showCharacters
+      ? ['Language', 'Translation', 'Characters']
+      : ['Language', 'Translation'],
     colWidths: showCharacters ? [10, 60, 12] : [10, 70],
     wordWrap: true,
     ...(colorDisabled && { style: { head: [], border: [] } }),
   });
 
   results.forEach((result) => {
-    const row = [
-      result.targetLang,
-      result.text,
-    ];
+    const row = [result.targetLang, result.text];
 
     if (showCharacters) {
       row.push(result.billedCharacters?.toLocaleString() ?? 'N/A');
diff --git a/src/utils/glob-prefix.ts b/src/utils/glob-prefix.ts
index b5c1a047..106472dc 100644
--- a/src/utils/glob-prefix.ts
+++ b/src/utils/glob-prefix.ts
@@ -1,7 +1,19 @@
 import { ConfigError } from './errors.js';
 import { sanitizeForTerminal } from './control-chars.js';
 
-const META_CHARS = new Set(['*', '?', '[', ']', '{', '}', '(', ')', '!', '+', '@']);
+const META_CHARS = new Set([
+  '*',
+  '?',
+  '[',
+  ']',
+  '{',
+  '}',
+  '(',
+  ')',
+  '!',
+  '+',
+  '@',
+]);
 
 interface SegmentScan {
   isDynamic: boolean;
@@ -61,7 +73,13 @@ function scanSegment(segment: string): SegmentScan {
 
     if (ch === '(' && i > 0) {
       const prev = segment[i - 1];
-      if (prev === '@' || prev === '+' || prev === '?' || prev === '*' || prev === '!') {
+      if (
+        prev === '@' ||
+        prev === '+' ||
+        prev === '?' ||
+        prev === '*' ||
+        prev === '!'
+      ) {
         depth += 1;
         altStart = i + 1;
         continue;
@@ -119,7 +137,7 @@ export function extractGlobLiteralPrefix(pattern: string): string {
     if (isDotDotSegment(segment)) {
       throw new ConfigError(
         `scan_paths pattern contains parent-directory traversal: "${sanitizeForTerminal(pattern)}"`,
-        'Remove ".." segments from scan_paths in .deepl-sync.yaml; scan paths must stay within the project root.',
+        'Remove ".." segments from scan_paths in .deepl-sync.yaml; scan paths must stay within the project root.'
       );
     }
 
@@ -128,7 +146,7 @@ export function extractGlobLiteralPrefix(pattern: string): string {
     if (scan.containsTraversal) {
       throw new ConfigError(
         `scan_paths pattern contains parent-directory traversal in brace/extglob: "${sanitizeForTerminal(pattern)}"`,
-        'Remove ".." alternatives from brace or extglob groups in scan_paths; scan paths must stay within the project root.',
+        'Remove ".." alternatives from brace or extglob groups in scan_paths; scan paths must stay within the project root.'
       );
     }
 
diff --git a/src/utils/glossary-params.ts b/src/utils/glossary-params.ts
index 2b2ed5b1..6bd8fb17 100644
--- a/src/utils/glossary-params.ts
+++ b/src/utils/glossary-params.ts
@@ -15,7 +15,9 @@ export interface GlossarySourceLangSelection {
 }
 
 /** Whether `--glossary` names anything; `[]` is truthy but selects nothing. */
-export function hasGlossarySelection(selection: GlossarySourceLangSelection): boolean {
+export function hasGlossarySelection(
+  selection: GlossarySourceLangSelection
+): boolean {
   const { glossary } = selection;
   return Array.isArray(glossary) ? glossary.length > 0 : !!glossary;
 }
@@ -33,7 +35,7 @@ export function hasGlossarySelection(selection: GlossarySourceLangSelection): bo
 export function applyGlossarySourceLang(
   selection: GlossarySourceLangSelection,
   configuredSourceLang: string | undefined,
-  example: string,
+  example: string
 ): void {
   if (!hasGlossarySelection(selection) || selection.from) {
     return;
@@ -42,12 +44,14 @@ export function applyGlossarySourceLang(
     selection.from = configuredSourceLang.toLowerCase();
     return;
   }
-  throw new ValidationError('Source language (--from) is required when using a glossary', example);
+  throw new ValidationError(
+    'Source language (--from) is required when using a glossary',
+    example
+  );
 }
 
 export type GlossaryWireParams =
-  | { glossary_id: string }
-  | { glossary_ids: string[] };
+  { glossary_id: string } | { glossary_ids: string[] };
 
 /**
  * Pick the glossary parameter to send for a resolved glossary selection.
@@ -63,14 +67,14 @@ export type GlossaryWireParams =
  * position in this list.
  */
 export function resolveGlossaryWireParams(
-  selection: GlossarySelection,
+  selection: GlossarySelection
 ): GlossaryWireParams | undefined {
   const ids = selection.glossaryIds;
 
   if (selection.glossaryId && ids && ids.length > 0) {
     throw new ValidationError(
       'Cannot combine glossaryId with glossaryIds',
-      'Pass every glossary through glossaryIds; a single entry is sent as glossary_id automatically.',
+      'Pass every glossary through glossaryIds; a single entry is sent as glossary_id automatically.'
     );
   }
 
@@ -85,7 +89,7 @@ export function resolveGlossaryWireParams(
   if (ids.length > MAX_GLOSSARIES_PER_REQUEST) {
     throw new ValidationError(
       `A maximum of ${MAX_GLOSSARIES_PER_REQUEST} glossaries can be used per request, got ${ids.length}`,
-      'Merge entries into fewer glossaries, or pass fewer --glossary flags.',
+      'Merge entries into fewer glossaries, or pass fewer --glossary flags.'
     );
   }
 
diff --git a/src/utils/icu-preservation.ts b/src/utils/icu-preservation.ts
index 3afd5ce2..86be530f 100644
--- a/src/utils/icu-preservation.ts
+++ b/src/utils/icu-preservation.ts
@@ -75,11 +75,14 @@ export function parseIcu(text: string): IcuParseResult {
           // Filling missing values with '' produced empty plural branches,
           // which render nothing for that category.
           throw new Error(
-            `ICU reassemble expected ${segments.length} translations, received ${translations.length}`,
+            `ICU reassemble expected ${segments.length} translations, received ${translations.length}`
           );
         }
         let idx = 0;
-        return template.replace(/__ICU_LEAF_(?:\d+|P|S)__/g, () => translations[idx++] ?? '');
+        return template.replace(
+          /__ICU_LEAF_(?:\d+|P|S)__/g,
+          () => translations[idx++] ?? ''
+        );
       },
     };
   } catch {
@@ -95,7 +98,11 @@ interface ParseBlockResult {
 
 const OFFSET_RE = /^offset\s*:\s*\d+/;
 
-function parseIcuBlock(text: string, start: number, inPluralContext = false): ParseBlockResult | null {
+function parseIcuBlock(
+  text: string,
+  start: number,
+  inPluralContext = false
+): ParseBlockResult | null {
   let i = start;
 
   // Skip leading whitespace
@@ -174,7 +181,11 @@ function parseIcuBlock(text: string, start: number, inPluralContext = false): Pa
     i = branchContent.endIndex + 1;
 
     // Check if branch content itself contains nested ICU
-    const nestedResult = tryParseNestedContent(content, pluralContext, segments);
+    const nestedResult = tryParseNestedContent(
+      content,
+      pluralContext,
+      segments
+    );
     const leafIndex = segments.length;
 
     if (nestedResult) {
@@ -192,7 +203,7 @@ function parseIcuBlock(text: string, start: number, inPluralContext = false): Pa
 function tryParseNestedContent(
   content: string,
   inPluralContext: boolean,
-  segments: IcuSegment[],
+  segments: IcuSegment[]
 ): { template: string } | null {
   // Check if content contains a nested ICU block
   // e.g., "{gender, select, male {He has # items} female {She has # items}}"
@@ -214,7 +225,10 @@ function tryParseNestedContent(
   // Reindex the nested template's leaf references
   let reindexed = nested.template;
   for (let j = nested.segments.length - 1; j >= 0; j--) {
-    reindexed = reindexed.replace(`__ICU_LEAF_${j}__`, `__ICU_LEAF_${baseIndex + j}__`);
+    reindexed = reindexed.replace(
+      `__ICU_LEAF_${j}__`,
+      `__ICU_LEAF_${baseIndex + j}__`
+    );
   }
 
   return { template: reindexed };
@@ -229,7 +243,7 @@ function tryParseNestedContent(
 function extractBraceContent(
   text: string,
   start: number,
-  inPluralContext: boolean,
+  inPluralContext: boolean
 ): { content: string; endIndex: number } | null {
   if (text[start] !== '{') return null;
 
diff --git a/src/utils/logger.ts b/src/utils/logger.ts
index 0dafb013..628c00d4 100644
--- a/src/utils/logger.ts
+++ b/src/utils/logger.ts
@@ -55,15 +55,18 @@ class LoggerClass {
     }
 
     if (value instanceof Error) {
-      const copy = Object.create(Object.getPrototypeOf(value) as object) as object;
+      const copy = Object.create(
+        Object.getPrototypeOf(value) as object
+      ) as object;
       for (const key of Object.getOwnPropertyNames(value)) {
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
         if (!descriptor) continue;
         // Accessor properties (V8 materializes `stack` lazily via a getter)
         // are flattened to their current value so the copy stays self-contained.
-        const raw = 'value' in descriptor
-          ? descriptor.value
-          : (value as unknown as Record<string, unknown>)[key];
+        const raw =
+          'value' in descriptor
+            ? descriptor.value
+            : (value as unknown as Record<string, unknown>)[key];
         Object.defineProperty(copy, key, {
           value: this.sanitizeValue(raw, seen),
           writable: true,
@@ -89,17 +92,26 @@ class LoggerClass {
   private sanitizeString(value: string): string {
     let result = value;
     result = result.replace(/([?&])token=[^&\s]*/gi, '$1token=[REDACTED]');
-    result = result.replace(/([?&])api[_-]?key=[^&\s]*/gi, '$1api_key=[REDACTED]');
-    result = result.replace(/DeepL-Auth-Key\s+\S+/gi, 'DeepL-Auth-Key [REDACTED]');
+    result = result.replace(
+      /([?&])api[_-]?key=[^&\s]*/gi,
+      '$1api_key=[REDACTED]'
+    );
+    result = result.replace(
+      /DeepL-Auth-Key\s+\S+/gi,
+      'DeepL-Auth-Key [REDACTED]'
+    );
     result = result.replace(
       /Authorization:\s+(ApiKey|Bearer)\s+\S+/gi,
-      'Authorization: $1 [REDACTED]',
+      'Authorization: $1 [REDACTED]'
     );
     // X-Api-Key / X-Auth-Token — common in REST APIs and present on
     // TMS-style backends. axios error dumps frequently include the full
     // `config.headers` object, so these need explicit coverage.
     result = result.replace(/X-Api-Key:\s+\S+/gi, 'X-Api-Key: [REDACTED]');
-    result = result.replace(/X-Auth-Token:\s+\S+/gi, 'X-Auth-Token: [REDACTED]');
+    result = result.replace(
+      /X-Auth-Token:\s+\S+/gi,
+      'X-Auth-Token: [REDACTED]'
+    );
     const apiKey = process.env['DEEPL_API_KEY'];
     if (apiKey) {
       result = result.replaceAll(apiKey, '[REDACTED]');
diff --git a/src/utils/output-helper.ts b/src/utils/output-helper.ts
index 85092d49..38a6b052 100644
--- a/src/utils/output-helper.ts
+++ b/src/utils/output-helper.ts
@@ -20,7 +20,11 @@ export function formatJson(data: unknown): string {
  * @param text  - The human-readable string to return when format is 'text' (default).
  * @param format - 'json' | 'text' (defaults to 'text').
  */
-export function formatOutput(data: unknown, text: string, format?: OutputFormat): string {
+export function formatOutput(
+  data: unknown,
+  text: string,
+  format?: OutputFormat
+): string {
   if (format === 'json') {
     return formatJson(data);
   }
diff --git a/src/utils/parse-size.ts b/src/utils/parse-size.ts
index bf49a357..8f20c814 100644
--- a/src/utils/parse-size.ts
+++ b/src/utils/parse-size.ts
@@ -38,7 +38,9 @@ export function parseSize(size: string): number {
   const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*([KMGT]B?)$/);
 
   if (!match) {
-    throw new ValidationError(`Invalid size format: ${size}. Use formats like: 100, 100K, 100MB, 1G`);
+    throw new ValidationError(
+      `Invalid size format: ${size}. Use formats like: 100, 100K, 100MB, 1G`
+    );
   }
 
   const value = parseFloat(match[1]!);
@@ -50,14 +52,14 @@ export function parseSize(size: string): number {
 
   // Convert to bytes based on unit
   const multipliers: Record<string, number> = {
-    'K': 1024,
-    'KB': 1024,
-    'M': 1024 * 1024,
-    'MB': 1024 * 1024,
-    'G': 1024 * 1024 * 1024,
-    'GB': 1024 * 1024 * 1024,
-    'T': 1024 * 1024 * 1024 * 1024,
-    'TB': 1024 * 1024 * 1024 * 1024,
+    K: 1024,
+    KB: 1024,
+    M: 1024 * 1024,
+    MB: 1024 * 1024,
+    G: 1024 * 1024 * 1024,
+    GB: 1024 * 1024 * 1024,
+    T: 1024 * 1024 * 1024 * 1024,
+    TB: 1024 * 1024 * 1024 * 1024,
   };
 
   const multiplier = multipliers[unit];
diff --git a/src/utils/paths.ts b/src/utils/paths.ts
index 1bee0fe8..2ec95b54 100644
--- a/src/utils/paths.ts
+++ b/src/utils/paths.ts
@@ -35,10 +35,13 @@ export function resolvePaths(): ResolvedPaths {
   }
 
   // 3. XDG env vars / defaults (empty string = unset per XDG spec)
-  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-  const xdgConfigHome = process.env['XDG_CONFIG_HOME'] || path.join(home, '.config');
-  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-  const xdgCacheHome = process.env['XDG_CACHE_HOME'] || path.join(home, '.cache');
+  /* eslint-disable @typescript-eslint/prefer-nullish-coalescing -- an empty
+     value counts as unset per the XDG spec, which `??` would pass through */
+  const xdgConfigHome =
+    process.env['XDG_CONFIG_HOME'] || path.join(home, '.config');
+  const xdgCacheHome =
+    process.env['XDG_CACHE_HOME'] || path.join(home, '.cache');
+  /* eslint-enable @typescript-eslint/prefer-nullish-coalescing */
 
   const configDir = path.join(xdgConfigHome, 'deepl-cli');
   const cacheDir = path.join(xdgCacheHome, 'deepl-cli');
diff --git a/src/utils/safe-read-file.ts b/src/utils/safe-read-file.ts
index a2929028..af0b5769 100644
--- a/src/utils/safe-read-file.ts
+++ b/src/utils/safe-read-file.ts
@@ -8,10 +8,15 @@ import { ValidationError } from './errors.js';
  */
 export function safeReadFileSync(filePath: string, encoding: 'utf-8'): string;
 export function safeReadFileSync(filePath: string): Buffer;
-export function safeReadFileSync(filePath: string, encoding?: 'utf-8'): string | Buffer {
+export function safeReadFileSync(
+  filePath: string,
+  encoding?: 'utf-8'
+): string | Buffer {
   const stat = fs.lstatSync(filePath);
   if (stat.isSymbolicLink()) {
-    throw new ValidationError(`Symlinks are not supported for security reasons: ${filePath}`);
+    throw new ValidationError(
+      `Symlinks are not supported for security reasons: ${filePath}`
+    );
   }
   if (encoding) {
     return fs.readFileSync(filePath, encoding);
@@ -22,12 +27,20 @@ export function safeReadFileSync(filePath: string, encoding?: 'utf-8'): string |
 /**
  * Async version: read a file after verifying it is not a symlink.
  */
-export async function safeReadFile(filePath: string, encoding: 'utf-8'): Promise<string>;
+export async function safeReadFile(
+  filePath: string,
+  encoding: 'utf-8'
+): Promise<string>;
 export async function safeReadFile(filePath: string): Promise<Buffer>;
-export async function safeReadFile(filePath: string, encoding?: 'utf-8'): Promise<string | Buffer> {
+export async function safeReadFile(
+  filePath: string,
+  encoding?: 'utf-8'
+): Promise<string | Buffer> {
   const stat = await fs.promises.lstat(filePath);
   if (stat.isSymbolicLink()) {
-    throw new ValidationError(`Symlinks are not supported for security reasons: ${filePath}`);
+    throw new ValidationError(
+      `Symlinks are not supported for security reasons: ${filePath}`
+    );
   }
   if (encoding) {
     return fs.promises.readFile(filePath, encoding);
diff --git a/src/utils/tag-handling-version.ts b/src/utils/tag-handling-version.ts
index 4b60d089..ede92db9 100644
--- a/src/utils/tag-handling-version.ts
+++ b/src/utils/tag-handling-version.ts
@@ -24,7 +24,7 @@ export interface TagHandlingSelection {
  * version and keep the cache keys they had.
  */
 export function resolveTagHandlingVersion(
-  selection: TagHandlingSelection,
+  selection: TagHandlingSelection
 ): 'v1' | 'v2' | undefined {
   if (selection.tagHandlingVersion) {
     return selection.tagHandlingVersion;
diff --git a/src/utils/text-preservation.ts b/src/utils/text-preservation.ts
index 0e259519..6fc6cf85 100644
--- a/src/utils/text-preservation.ts
+++ b/src/utils/text-preservation.ts
@@ -3,7 +3,10 @@
  * Preserves code blocks and variables during translation by replacing them with placeholders
  */
 
-export function preserveCodeBlocks(text: string, preservationMap: Map<string, string>): string {
+export function preserveCodeBlocks(
+  text: string,
+  preservationMap: Map<string, string>
+): string {
   let processed = text;
   let counter = 0;
 
@@ -24,17 +27,20 @@ export function preserveCodeBlocks(text: string, preservationMap: Map<string, st
   return processed;
 }
 
-export function preserveVariables(text: string, preservationMap: Map<string, string>): string {
+export function preserveVariables(
+  text: string,
+  preservationMap: Map<string, string>
+): string {
   let processed = text;
   let counter = 0;
 
   // Preserve various variable formats (order matters - longest match first)
   const patterns = [
-    /\$\{[\p{L}\p{N}_]+\}/gu,       // ${name}, ${имя}
-    /\{\{[\p{L}\p{N}_]+\}\}/gu,     // {{name}}, {{имя}} — must precede {name}
-    /\{[\p{L}\p{N}_]+\}/gu,         // {name}, {名前}, {0}
-    /%\d+\$[sdfu@]/g,               // %1$s, %2$d
-    /%[sdfu@]/g,                     // %s, %d, %f, %u, %@
+    /\$\{[\p{L}\p{N}_]+\}/gu, // ${name}, ${имя}
+    /\{\{[\p{L}\p{N}_]+\}\}/gu, // {{name}}, {{имя}} — must precede {name}
+    /\{[\p{L}\p{N}_]+\}/gu, // {name}, {名前}, {0}
+    /%\d+\$[sdfu@]/g, // %1$s, %2$d
+    /%[sdfu@]/g, // %s, %d, %f, %u, %@
   ];
 
   for (const pattern of patterns) {
@@ -48,7 +54,10 @@ export function preserveVariables(text: string, preservationMap: Map<string, str
   return processed;
 }
 
-export function restorePlaceholders(text: string, preservationMap: Map<string, string>): string {
+export function restorePlaceholders(
+  text: string,
+  preservationMap: Map<string, string>
+): string {
   let restored = text;
   for (const [placeholder, original] of preservationMap.entries()) {
     // Single pass per placeholder: `original` may itself contain the
diff --git a/src/utils/unrecoverable-request-error.ts b/src/utils/unrecoverable-request-error.ts
index 7d229f3c..9bc5661e 100644
--- a/src/utils/unrecoverable-request-error.ts
+++ b/src/utils/unrecoverable-request-error.ts
@@ -35,5 +35,5 @@ export function isUnrecoverableRequestError(error: unknown): boolean {
     return false;
   }
   const message = errorMessage(error).toLowerCase();
-  return REJECTED_REQUEST_PATTERNS.some(pattern => message.includes(pattern));
+  return REJECTED_REQUEST_PATTERNS.some((pattern) => message.includes(pattern));
 }
diff --git a/src/utils/validate-url.ts b/src/utils/validate-url.ts
index a1472708..7ed586b3 100644
--- a/src/utils/validate-url.ts
+++ b/src/utils/validate-url.ts
@@ -25,13 +25,13 @@ export function validateApiUrl(url: string): void {
     }
     throw new ValidationError(
       `Insecure HTTP URL rejected: ${url}\n` +
-      'API keys must only be sent over HTTPS to prevent credential exposure.\n' +
-      'Use https:// or http://localhost / http://127.0.0.1 for local testing.'
+        'API keys must only be sent over HTTPS to prevent credential exposure.\n' +
+        'Use https:// or http://localhost / http://127.0.0.1 for local testing.'
     );
   }
 
   throw new ValidationError(
     `Unsupported protocol in URL: ${url}\n` +
-    'Only https:// URLs are allowed (http://localhost and http://127.0.0.1 permitted for testing).'
+      'Only https:// URLs are allowed (http://localhost and http://127.0.0.1 permitted for testing).'
   );
 }
diff --git a/src/version.ts b/src/version.ts
index 763d3d9c..fac462d6 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -4,6 +4,8 @@ import { dirname, join } from 'path';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8')) as { version: string };
+const packageJson = JSON.parse(
+  readFileSync(join(__dirname, '../package.json'), 'utf-8')
+) as { version: string };
 
 export const VERSION = packageJson.version;
diff --git a/tests/e2e/cli-aliases.e2e.test.ts b/tests/e2e/cli-aliases.e2e.test.ts
index acd9fc0a..559e8309 100644
--- a/tests/e2e/cli-aliases.e2e.test.ts
+++ b/tests/e2e/cli-aliases.e2e.test.ts
@@ -45,7 +45,7 @@ describe('Command Aliases E2E', () => {
     it('should dispatch to write option validation', () => {
       const result = runCLIExpectError('w "Hello" --format bogus');
       expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toContain("Allowed choices are text, json");
+      expect(result.output).toContain('Allowed choices are text, json');
     });
 
     it('should fail identically to write on an unknown option', () => {
diff --git a/tests/e2e/cli-auth.e2e.test.ts b/tests/e2e/cli-auth.e2e.test.ts
index b79b6a7e..892f59e2 100644
--- a/tests/e2e/cli-auth.e2e.test.ts
+++ b/tests/e2e/cli-auth.e2e.test.ts
@@ -7,7 +7,10 @@ import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
 describe('Auth Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-auth');
-  const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(testConfig.path, { excludeApiKey: true });
+  const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(
+    testConfig.path,
+    { excludeApiKey: true }
+  );
 
   afterAll(() => {
     testConfig.cleanup();
diff --git a/tests/e2e/cli-cache-degraded.e2e.test.ts b/tests/e2e/cli-cache-degraded.e2e.test.ts
index 8df2e165..e0aaf583 100644
--- a/tests/e2e/cli-cache-degraded.e2e.test.ts
+++ b/tests/e2e/cli-cache-degraded.e2e.test.ts
@@ -34,10 +34,13 @@ describe('CLI with unavailable cache backend E2E', () => {
   let preloadPath: string;
   let cacheDbPath: string;
 
-  let runCLIAll: (command: string, options?: { env?: Record<string, string | undefined> }) => string;
+  let runCLIAll: (
+    command: string,
+    options?: { env?: Record<string, string | undefined> }
+  ) => string;
   let runCLIExpectError: (
     command: string,
-    options?: { env?: Record<string, string | undefined> },
+    options?: { env?: Record<string, string | undefined> }
   ) => { status: number; output: string };
 
   function brokenEnv(): { env: Record<string, string> } {
@@ -70,12 +73,18 @@ describe('CLI with unavailable cache backend E2E', () => {
         }
       });
 
-      setTimeout(() => reject(new Error('Mock server did not start within 15s')), 15000).unref();
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      ).unref();
     });
   }
 
   beforeAll(async () => {
-    const helpers = makeNodeRunCLI(testConfig.path, { noColor: true, timeout: 15000 });
+    const helpers = makeNodeRunCLI(testConfig.path, {
+      noColor: true,
+      timeout: 15000,
+    });
     runCLIAll = helpers.runCLIAll;
     runCLIExpectError = helpers.runCLIExpectError;
 
@@ -88,11 +97,18 @@ describe('CLI with unavailable cache backend E2E', () => {
     const config = {
       auth: { apiKey: 'mock-api-key-for-testing:fx' },
       api: { baseUrl, usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: true,
+      },
       cache: { enabled: true, maxSize: 1048576, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: false },
     };
-    fs.writeFileSync(path.join(testConfig.path, 'config.json'), JSON.stringify(config, null, 2));
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
 
     // Populate a healthy cache database with a working backend first.
     cacheDbPath = path.join(testConfig.path, 'cache.db');
@@ -111,7 +127,9 @@ describe('CLI with unavailable cache backend E2E', () => {
   });
 
   function listCorruptFiles(): string[] {
-    return fs.readdirSync(testConfig.path).filter((f) => f.includes('.corrupt-'));
+    return fs
+      .readdirSync(testConfig.path)
+      .filter((f) => f.includes('.corrupt-'));
   }
 
   it('translate succeeds with exit code 0 and exactly one warning', () => {
@@ -120,7 +138,8 @@ describe('CLI with unavailable cache backend E2E', () => {
     const output = runCLIAll('translate "Hello world" --to es', brokenEnv());
 
     expect(output).toContain('Hola mundo');
-    const warnings = output.split('Caching is disabled for this run').length - 1;
+    const warnings =
+      output.split('Caching is disabled for this run').length - 1;
     expect(warnings).toBe(1);
 
     // The healthy database was not quarantined or modified.
diff --git a/tests/e2e/cli-cache.e2e.test.ts b/tests/e2e/cli-cache.e2e.test.ts
index a4289c2a..6c9e20a9 100644
--- a/tests/e2e/cli-cache.e2e.test.ts
+++ b/tests/e2e/cli-cache.e2e.test.ts
@@ -7,7 +7,9 @@ import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
 describe('Cache Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-cache');
-  const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(testConfig.path);
+  const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(
+    testConfig.path
+  );
 
   afterAll(() => {
     testConfig.cleanup();
@@ -48,7 +50,9 @@ describe('Cache Command E2E', () => {
       toggle.runCLIAll('cache enable --max-size 100M');
 
       expect(toggle.runCLI('config get cache.enabled').trim()).toBe('true');
-      expect(toggle.runCLI('config get cache.maxSize').trim()).toBe(String(100 * 1024 * 1024));
+      expect(toggle.runCLI('config get cache.maxSize').trim()).toBe(
+        String(100 * 1024 * 1024)
+      );
     });
   });
 
@@ -56,7 +60,9 @@ describe('Cache Command E2E', () => {
     it('should prefix the non-TTY table fallback warning with WARN', () => {
       const output = runCLIAll('cache stats --format table');
 
-      expect(output).toContain('WARN  --format table is not supported in non-TTY output; falling back to plain text');
+      expect(output).toContain(
+        'WARN  --format table is not supported in non-TTY output; falling back to plain text'
+      );
     });
   });
 
diff --git a/tests/e2e/cli-config.e2e.test.ts b/tests/e2e/cli-config.e2e.test.ts
index 6f4fd164..d340b61d 100644
--- a/tests/e2e/cli-config.e2e.test.ts
+++ b/tests/e2e/cli-config.e2e.test.ts
@@ -7,7 +7,9 @@ import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
 describe('Config Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-config');
-  const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(testConfig.path);
+  const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(
+    testConfig.path
+  );
 
   afterAll(() => {
     testConfig.cleanup();
diff --git a/tests/e2e/cli-correct.e2e.test.ts b/tests/e2e/cli-correct.e2e.test.ts
index 306b8fdc..92b46d1f 100644
--- a/tests/e2e/cli-correct.e2e.test.ts
+++ b/tests/e2e/cli-correct.e2e.test.ts
@@ -52,7 +52,10 @@ describe('Correct Command E2E', () => {
     it('should accept correct without --lang flag (auto-detect)', () => {
       expect.assertions(1);
       try {
-        execSync('deepl correct "test text"', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl correct "test text"', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         // May fail on API key, but should NOT fail on missing --lang (exit code 1)
         expect(error.status).not.toBe(1);
@@ -62,7 +65,10 @@ describe('Correct Command E2E', () => {
     it('should reject invalid language code', () => {
       expect.assertions(1);
       try {
-        execSync('deepl correct "test" --lang invalid', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl correct "test" --lang invalid', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         // Exit code 6 = InvalidInput (validation error)
         expect(error.status).toBe(6);
@@ -72,7 +78,10 @@ describe('Correct Command E2E', () => {
     it('should reject --style as an unknown option', () => {
       expect.assertions(2);
       try {
-        execSync('deepl correct "test" --style business', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl correct "test" --style business', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         expect(error.status).not.toBe(0);
         expect(error.stderr?.toString() ?? '').toMatch(/unknown option/i);
@@ -82,7 +91,10 @@ describe('Correct Command E2E', () => {
     it('should reject --tone as an unknown option', () => {
       expect.assertions(2);
       try {
-        execSync('deepl correct "test" --tone friendly', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl correct "test" --tone friendly', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         expect(error.status).not.toBe(0);
         expect(error.stderr?.toString() ?? '').toMatch(/unknown option/i);
@@ -92,7 +104,10 @@ describe('Correct Command E2E', () => {
     it('should reject conflicting --to and --lang values', () => {
       expect.assertions(1);
       try {
-        execSync('deepl correct "test" --to de --lang fr', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl correct "test" --to de --lang fr', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         expect(error.status).toBe(6);
       }
@@ -107,7 +122,10 @@ describe('Correct Command E2E', () => {
       // This will fail without API key, but should recognize it as a file operation
       expect.assertions(1);
       try {
-        execSync(`deepl correct "${testFile}" --lang en-US`, { encoding: 'utf-8', stdio: 'pipe' });
+        execSync(`deepl correct "${testFile}" --lang en-US`, {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         // Expected to fail without API key, but should not error on file path recognition
         const stderr = error.stderr?.toString() ?? '';
diff --git a/tests/e2e/cli-detect.e2e.test.ts b/tests/e2e/cli-detect.e2e.test.ts
index f425ea2d..d89c858d 100644
--- a/tests/e2e/cli-detect.e2e.test.ts
+++ b/tests/e2e/cli-detect.e2e.test.ts
@@ -43,7 +43,9 @@ describe('Detect Command E2E', () => {
 
   describe('detect without API key', () => {
     it('should require API key', () => {
-      const result = runCLIExpectError('detect "Bonjour le monde"', { apiKey: '' });
+      const result = runCLIExpectError('detect "Bonjour le monde"', {
+        apiKey: '',
+      });
 
       expect(result.status).toBeGreaterThan(0);
       expect(result.output).toMatch(/api key/i);
@@ -52,7 +54,9 @@ describe('Detect Command E2E', () => {
 
   describe('detect with invalid API key', () => {
     it('should fail with authentication error', () => {
-      const result = runCLIExpectError('detect "Hallo Welt"', { apiKey: 'invalid-key-123:fx' });
+      const result = runCLIExpectError('detect "Hallo Welt"', {
+        apiKey: 'invalid-key-123:fx',
+      });
 
       expect(result.status).toBeGreaterThan(0);
       expect(result.output).toMatch(/error|authentication|invalid|api/i);
diff --git a/tests/e2e/cli-document-translation.e2e.test.ts b/tests/e2e/cli-document-translation.e2e.test.ts
index 9ae90892..4192725e 100644
--- a/tests/e2e/cli-document-translation.e2e.test.ts
+++ b/tests/e2e/cli-document-translation.e2e.test.ts
@@ -49,7 +49,7 @@ describe('Document Translation E2E', () => {
       const out = path.join(testDir, 'glossary-doc.de.pdf');
 
       const result = run(
-        `translate "${file}" --to de --output "${out}" --glossary my-glossary --api-url ${DEAD_URL}`,
+        `translate "${file}" --to de --output "${out}" --glossary my-glossary --api-url ${DEAD_URL}`
       );
 
       expect(result.status).toBeGreaterThan(0);
@@ -62,7 +62,7 @@ describe('Document Translation E2E', () => {
       const out = path.join(testDir, 'glossary-doc.de2.pdf');
 
       const result = run(
-        `translate "${file}" --from en --to de --output "${out}" --glossary my-glossary --api-url ${DEAD_URL}`,
+        `translate "${file}" --from en --to de --output "${out}" --glossary my-glossary --api-url ${DEAD_URL}`
       );
 
       expect(result.output).not.toMatch(/does not support/i);
@@ -74,7 +74,7 @@ describe('Document Translation E2E', () => {
 
       const result = run(
         `translate "${file}" --from en --to de --output "${out}" ` +
-          `--glossary base-terms --glossary project-overrides --api-url ${DEAD_URL}`,
+          `--glossary base-terms --glossary project-overrides --api-url ${DEAD_URL}`
       );
 
       expect(result.output).not.toMatch(/unknown option/i);
@@ -87,7 +87,7 @@ describe('Document Translation E2E', () => {
 
       const result = run(
         `translate "${file}" --from en --to de --output "${out}" ` +
-          `--glossary a --glossary b --glossary c --glossary d --glossary e --glossary f`,
+          `--glossary a --glossary b --glossary c --glossary d --glossary e --glossary f`
       );
 
       expect(result.status).toBeGreaterThan(0);
diff --git a/tests/e2e/cli-file-translation.e2e.test.ts b/tests/e2e/cli-file-translation.e2e.test.ts
index df93338f..923b551f 100644
--- a/tests/e2e/cli-file-translation.e2e.test.ts
+++ b/tests/e2e/cli-file-translation.e2e.test.ts
@@ -75,10 +75,9 @@ describe('File Translation E2E', () => {
       const filePath = path.join(testDir, 'test.txt');
       fs.writeFileSync(filePath, 'Hello');
 
-      const result = runCLIExpectError(
-        `translate ${filePath} --to de`,
-        { apiKey: 'invalid-api-key-format:fx' }
-      );
+      const result = runCLIExpectError(`translate ${filePath} --to de`, {
+        apiKey: 'invalid-api-key-format:fx',
+      });
 
       expect(result.status).toBeGreaterThan(0);
       expect(result.output).toMatch(/error|authentication|invalid/i);
diff --git a/tests/e2e/cli-http-options.e2e.test.ts b/tests/e2e/cli-http-options.e2e.test.ts
index 4cad014d..be8440f6 100644
--- a/tests/e2e/cli-http-options.e2e.test.ts
+++ b/tests/e2e/cli-http-options.e2e.test.ts
@@ -37,7 +37,10 @@ describe('CLI HTTP options E2E', () => {
       });
 
       child.on('error', reject);
-      setTimeout(() => reject(new Error('Stall server did not start within 15s')), 15000);
+      setTimeout(
+        () => reject(new Error('Stall server did not start within 15s')),
+        15000
+      );
     });
   }
 
@@ -61,7 +64,7 @@ describe('CLI HTTP options E2E', () => {
   it('exits 5 (network error) on a client-side timeout instead of 6', () => {
     const result = runner.runCLIExpectError(
       `--timeout 500 translate "Hello" --to es --api-url ${baseUrl}`,
-      { timeout: 30000 },
+      { timeout: 30000 }
     );
 
     expect(result.status).toBe(5);
@@ -73,7 +76,7 @@ describe('CLI HTTP options E2E', () => {
 
     runner.runCLIExpectError(
       `--timeout 500 translate "Bonjour" --to es --api-url ${baseUrl}`,
-      { timeout: 30000 },
+      { timeout: 30000 }
     );
 
     expect(requestCount() - before).toBe(1);
@@ -83,7 +86,7 @@ describe('CLI HTTP options E2E', () => {
     const start = Date.now();
     const result = runner.runCLIExpectError(
       `--timeout 500 --max-retries 0 translate "Guten Tag" --to es --api-url ${baseUrl}`,
-      { timeout: 30000 },
+      { timeout: 30000 }
     );
     const elapsed = Date.now() - start;
 
@@ -92,14 +95,18 @@ describe('CLI HTTP options E2E', () => {
   });
 
   it('rejects a non-numeric --timeout with exit 6', () => {
-    const result = runner.runCLIExpectError('--timeout abc translate "Hello" --to es');
+    const result = runner.runCLIExpectError(
+      '--timeout abc translate "Hello" --to es'
+    );
 
     expect(result.status).toBe(6);
     expect(result.output).toMatch(/--timeout/);
   });
 
   it('rejects a negative --max-retries with exit 6', () => {
-    const result = runner.runCLIExpectError('--max-retries -1 translate "Hello" --to es');
+    const result = runner.runCLIExpectError(
+      '--max-retries -1 translate "Hello" --to es'
+    );
 
     expect(result.status).toBe(6);
     expect(result.output).toMatch(/--max-retries/);
diff --git a/tests/e2e/cli-languages.e2e.test.ts b/tests/e2e/cli-languages.e2e.test.ts
index 473b2e8a..deb310aa 100644
--- a/tests/e2e/cli-languages.e2e.test.ts
+++ b/tests/e2e/cli-languages.e2e.test.ts
@@ -20,7 +20,10 @@ describe('Languages Command E2E', () => {
     testConfig.cleanup();
   });
 
-  const runCLIWithEnv = (command: string, env: Record<string, string> = {}): { status: number; stdout: string; stderr: string } => {
+  const runCLIWithEnv = (
+    command: string,
+    env: Record<string, string> = {}
+  ): { status: number; stdout: string; stderr: string } => {
     const result = spawnSync('node', [CLI_PATH, ...command.split(' ')], {
       encoding: 'utf-8',
       env: {
@@ -106,7 +109,9 @@ describe('Languages Command E2E', () => {
     it('should list the same languages in --format json as in text output', () => {
       // Both formats read the same bundled snapshot, so both list the same
       // languages when there is no API key.
-      const result = runCLIWithEnv('languages --format json', { DEEPL_API_KEY: '' });
+      const result = runCLIWithEnv('languages --format json', {
+        DEEPL_API_KEY: '',
+      });
 
       expect(result.status).toBe(0);
       const parsed = JSON.parse(result.stdout) as {
@@ -116,17 +121,19 @@ describe('Languages Command E2E', () => {
       expect(parsed.source.length).toBeGreaterThan(100);
       expect(parsed.target.length).toBeGreaterThan(parsed.source.length);
       expect(parsed.source).toEqual(
-        expect.arrayContaining([{ language: 'de', name: 'German' }]),
+        expect.arrayContaining([{ language: 'de', name: 'German' }])
       );
-      expect(parsed.target.map(entry => entry.language)).toContain('en-gb');
+      expect(parsed.target.map((entry) => entry.language)).toContain('en-gb');
     });
 
     it('should list target-only languages in --format json --target', () => {
-      const result = runCLIWithEnv('languages --target --format json', { DEEPL_API_KEY: '' });
+      const result = runCLIWithEnv('languages --target --format json', {
+        DEEPL_API_KEY: '',
+      });
 
       expect(result.status).toBe(0);
       const parsed = JSON.parse(result.stdout) as Array<{ language: string }>;
-      expect(parsed.map(entry => entry.language)).toContain('pt-br');
+      expect(parsed.map((entry) => entry.language)).toContain('pt-br');
     });
   });
 
@@ -155,13 +162,16 @@ describe('Languages Command E2E', () => {
         });
 
         child.on('error', reject);
-        child.on('exit', code => {
+        child.on('exit', (code) => {
           if (code !== null && code !== 0) {
             reject(new Error(`Mock server exited with code ${code}`));
           }
         });
 
-        setTimeout(() => reject(new Error('Mock server did not start within 15s')), 15000);
+        setTimeout(
+          () => reject(new Error('Mock server did not start within 15s')),
+          15000
+        );
       });
     }
 
@@ -175,9 +185,12 @@ describe('Languages Command E2E', () => {
       };
       fs.writeFileSync(
         path.join(featuresConfig.path, 'config.json'),
-        JSON.stringify(config, null, 2),
+        JSON.stringify(config, null, 2)
       );
-      featuresRunCLI = makeNodeRunCLI(featuresConfig.path, { noColor: true, timeout: 15000 }).runCLI;
+      featuresRunCLI = makeNodeRunCLI(featuresConfig.path, {
+        noColor: true,
+        timeout: 15000,
+      }).runCLI;
     }, 30000);
 
     afterAll(() => {
@@ -190,8 +203,10 @@ describe('Languages Command E2E', () => {
     it('should list the features each language supports', () => {
       const output = featuresRunCLI('languages --target --features');
 
-      const german = output.split('\n').find(line => line.includes('German'));
-      const english = output.split('\n').find(line => line.includes('English (British)'));
+      const german = output.split('\n').find((line) => line.includes('German'));
+      const english = output
+        .split('\n')
+        .find((line) => line.includes('English (British)'));
 
       // formality is what varies across the languages the mock describes, so it
       // is the per-row annotation; glossary is shared by all of them and is
@@ -206,8 +221,10 @@ describe('Languages Command E2E', () => {
 
       // The listing also carries snapshot languages the mock never returned, so
       // the note must not speak for them.
-      expect(output).toContain('All languages with reported features also support');
-      const zulu = output.split('\n').find(line => line.includes('Zulu'));
+      expect(output).toContain(
+        'All languages with reported features also support'
+      );
+      const zulu = output.split('\n').find((line) => line.includes('Zulu'));
       expect(zulu).toContain('no feature data');
     });
 
@@ -228,15 +245,24 @@ describe('Languages Command E2E', () => {
     });
 
     it('should include the matrix in JSON only when requested', () => {
-      const withFeatures = JSON.parse(featuresRunCLI('languages --target --features --format json'));
-      const without = JSON.parse(featuresRunCLI('languages --target --format json'));
+      const withFeatures = JSON.parse(
+        featuresRunCLI('languages --target --features --format json')
+      );
+      const without = JSON.parse(
+        featuresRunCLI('languages --target --format json')
+      );
 
-      expect(withFeatures.find((l: { language: string }) => l.language === 'de').features).toEqual({
+      expect(
+        withFeatures.find((l: { language: string }) => l.language === 'de')
+          .features
+      ).toEqual({
         formality: { status: 'stable' },
         glossary: { status: 'stable' },
         tag_handling: { status: 'stable' },
       });
-      expect(without.find((l: { language: string }) => l.language === 'de')).not.toHaveProperty('features');
+      expect(
+        without.find((l: { language: string }) => l.language === 'de')
+      ).not.toHaveProperty('features');
     });
   });
 
@@ -252,17 +278,23 @@ describe('Languages Command E2E', () => {
       const result = runCLIWithEnv('languages --quiet', { DEEPL_API_KEY: '' });
 
       // Should not fail due to invalid flag
-      expect(result.stdout + result.stderr).not.toMatch(/unknown option.*quiet/i);
+      expect(result.stdout + result.stderr).not.toMatch(
+        /unknown option.*quiet/i
+      );
     });
 
     it('should support combining --source and --quiet', () => {
-      const result = runCLIWithEnv('languages --source --quiet', { DEEPL_API_KEY: '' });
+      const result = runCLIWithEnv('languages --source --quiet', {
+        DEEPL_API_KEY: '',
+      });
 
       expect(result.stdout + result.stderr).not.toMatch(/unknown option/i);
     });
 
     it('should support combining --target and --quiet', () => {
-      const result = runCLIWithEnv('languages --target --quiet', { DEEPL_API_KEY: '' });
+      const result = runCLIWithEnv('languages --target --quiet', {
+        DEEPL_API_KEY: '',
+      });
 
       expect(result.stdout + result.stderr).not.toMatch(/unknown option/i);
     });
@@ -270,10 +302,14 @@ describe('Languages Command E2E', () => {
 
   describe('languages flag combinations', () => {
     it('should handle both --source and --target flags together', () => {
-      const result = runCLIWithEnv('languages --source --target', { DEEPL_API_KEY: '' });
+      const result = runCLIWithEnv('languages --source --target', {
+        DEEPL_API_KEY: '',
+      });
 
       // Should show both (or handle appropriately), not fail due to flag conflict
-      expect(result.stdout + result.stderr).not.toMatch(/cannot use both|conflicting options/i);
+      expect(result.stdout + result.stderr).not.toMatch(
+        /cannot use both|conflicting options/i
+      );
     });
 
     it('should accept short flags', () => {
diff --git a/tests/e2e/cli-multi-glossary.e2e.test.ts b/tests/e2e/cli-multi-glossary.e2e.test.ts
index 48fc2c8e..eaa85b4a 100644
--- a/tests/e2e/cli-multi-glossary.e2e.test.ts
+++ b/tests/e2e/cli-multi-glossary.e2e.test.ts
@@ -39,7 +39,7 @@ describe('translate --glossary repetition E2E', () => {
     it('should reject a sixth --glossary with a clear message', () => {
       const result = runCLIExpectError(
         'translate "Hello" --to de --glossary a --glossary b --glossary c ' +
-          '--glossary d --glossary e --glossary f',
+          '--glossary d --glossary e --glossary f'
       );
 
       expect(result.status).toBeGreaterThan(0);
@@ -50,7 +50,7 @@ describe('translate --glossary repetition E2E', () => {
     it('should not reject exactly five glossaries during flag validation', () => {
       const result = runCLIExpectError(
         'translate "Hello" --from en --to de --dry-run --glossary a --glossary b --glossary c ' +
-          '--glossary d --glossary e',
+          '--glossary d --glossary e'
       );
 
       expect(result.status).toBe(0);
@@ -62,23 +62,28 @@ describe('translate --glossary repetition E2E', () => {
     it('should list every requested glossary in order', () => {
       const output = runCLI(
         'translate "Hello" --from en --to de --dry-run --glossary base-terms --glossary project-overrides',
-        { noColor: true },
+        { noColor: true }
       );
 
       expect(output).toContain('Glossaries: base-terms, project-overrides');
     });
 
     it('should keep the singular label for one glossary', () => {
-      const output = runCLI('translate "Hello" --from en --to de --dry-run --glossary base-terms', {
-        noColor: true,
-      });
+      const output = runCLI(
+        'translate "Hello" --from en --to de --dry-run --glossary base-terms',
+        {
+          noColor: true,
+        }
+      );
 
       expect(output).toContain('Glossary: base-terms');
       expect(output).not.toContain('Glossaries:');
     });
 
     it('should report no glossary line when none is given', () => {
-      const output = runCLI('translate "Hello" --to de --dry-run', { noColor: true });
+      const output = runCLI('translate "Hello" --to de --dry-run', {
+        noColor: true,
+      });
 
       expect(output).not.toMatch(/Glossar/i);
     });
@@ -86,9 +91,12 @@ describe('translate --glossary repetition E2E', () => {
     it('should not report a glossary command as runnable when --from is missing', () => {
       // Dry run is where people check a command is well-formed, so it has to
       // apply the same requirement the real run does.
-      const result = runCLIExpectError('translate "Hello" --to de --dry-run --glossary base-terms', {
-        excludeApiKey: true,
-      });
+      const result = runCLIExpectError(
+        'translate "Hello" --to de --dry-run --glossary base-terms',
+        {
+          excludeApiKey: true,
+        }
+      );
 
       expect(result.status).toBeGreaterThan(0);
       expect(result.output).toMatch(/Source language \(--from\) is required/i);
diff --git a/tests/e2e/cli-no-input.e2e.test.ts b/tests/e2e/cli-no-input.e2e.test.ts
index 657ea161..6181d3bf 100644
--- a/tests/e2e/cli-no-input.e2e.test.ts
+++ b/tests/e2e/cli-no-input.e2e.test.ts
@@ -32,7 +32,9 @@ describe('--no-input E2E', () => {
         execSync('deepl --no-input init', { encoding: 'utf-8', stdio: 'pipe' });
       } catch (error: any) {
         expect(error.status).toBe(6);
-        expect(error.stderr.toString()).toContain('not supported in non-interactive mode');
+        expect(error.stderr.toString()).toContain(
+          'not supported in non-interactive mode'
+        );
       }
     });
 
@@ -59,10 +61,15 @@ describe('--no-input E2E', () => {
     it('should exit with code 6 when --no-input is used', () => {
       expect.assertions(2);
       try {
-        execSync('deepl --no-input write "test" --interactive', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl --no-input write "test" --interactive', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         expect(error.status).toBe(6);
-        expect(error.stderr.toString()).toContain('requires an interactive terminal');
+        expect(error.stderr.toString()).toContain(
+          'requires an interactive terminal'
+        );
       }
     });
   });
diff --git a/tests/e2e/cli-parse-errors.e2e.test.ts b/tests/e2e/cli-parse-errors.e2e.test.ts
index ebddcd9a..17f8df54 100644
--- a/tests/e2e/cli-parse-errors.e2e.test.ts
+++ b/tests/e2e/cli-parse-errors.e2e.test.ts
@@ -32,7 +32,7 @@ describe('CLI Parse Errors E2E', () => {
     it('invalid option choice exits 6', () => {
       const result = runCLIExpectError(
         "translate 'Hi' --to es --formality bogus",
-        { excludeApiKey: true },
+        { excludeApiKey: true }
       );
 
       expect(result.status).toBe(6);
diff --git a/tests/e2e/cli-stdin-stdout.e2e.test.ts b/tests/e2e/cli-stdin-stdout.e2e.test.ts
index 6cafd023..cda4c5cc 100644
--- a/tests/e2e/cli-stdin-stdout.e2e.test.ts
+++ b/tests/e2e/cli-stdin-stdout.e2e.test.ts
@@ -16,7 +16,9 @@ describe('CLI Stdin/Stdout E2E', () => {
   const testFiles = createTestDir('stdio-test');
   const testDir = testFiles.path;
   const testConfigDir = testConfig.path;
-  const { runCLIExpectError, runCLIWithStdin } = makeNodeRunCLI(testConfig.path);
+  const { runCLIExpectError, runCLIWithStdin } = makeNodeRunCLI(
+    testConfig.path
+  );
 
   afterAll(() => {
     testConfig.cleanup();
@@ -26,7 +28,9 @@ describe('CLI Stdin/Stdout E2E', () => {
   describe('stdin input handling', () => {
     it('should accept text from stdin for translation', () => {
       // Test that stdin is accepted (will fail at API call but should parse stdin)
-      const result = runCLIWithStdin('translate --to es', 'Hello world', { apiKey: 'test-key:fx' });
+      const result = runCLIWithStdin('translate --to es', 'Hello world', {
+        apiKey: 'test-key:fx',
+      });
 
       expect(result.status).toBeGreaterThan(0);
       // Should fail at API call, not stdin reading
@@ -34,7 +38,9 @@ describe('CLI Stdin/Stdout E2E', () => {
     });
 
     it('should handle empty stdin gracefully', () => {
-      const result = runCLIWithStdin('translate --to es', '', { apiKey: 'test-key:fx' });
+      const result = runCLIWithStdin('translate --to es', '', {
+        apiKey: 'test-key:fx',
+      });
 
       expect(result.status).toBeGreaterThan(0);
       // Should handle empty input (may fail at validation or API)
@@ -43,7 +49,9 @@ describe('CLI Stdin/Stdout E2E', () => {
 
     it('should handle multiline stdin', () => {
       const multiline = 'Line 1\\nLine 2\\nLine 3';
-      const result = runCLIWithStdin('translate --to es', multiline, { apiKey: 'test-key:fx' });
+      const result = runCLIWithStdin('translate --to es', multiline, {
+        apiKey: 'test-key:fx',
+      });
 
       expect(result.status).toBeGreaterThan(0);
       // Should accept multiline input
@@ -77,18 +85,25 @@ describe('CLI Stdin/Stdout E2E', () => {
 
   describe('stderr error handling', () => {
     it('should write errors to stderr', () => {
-      const result = runCLIExpectError('translate nonexistent-file.txt --to es', { apiKey: 'test-key:fx' });
+      const result = runCLIExpectError(
+        'translate nonexistent-file.txt --to es',
+        { apiKey: 'test-key:fx' }
+      );
 
       expect(result.status).toBeGreaterThan(0);
       // Errors should be in output (stderr or stdout)
-      expect(result.output).toMatch(/error|not found|enoent|authentication|api/i);
+      expect(result.output).toMatch(
+        /error|not found|enoent|authentication|api/i
+      );
     });
 
     it('should write missing API key error to stderr', () => {
       const testFile = path.join(testDir, 'error-test.txt');
       fs.writeFileSync(testFile, 'Test');
 
-      const result = runCLIExpectError(`translate "${testFile}" --to es`, { apiKey: '' });
+      const result = runCLIExpectError(`translate "${testFile}" --to es`, {
+        apiKey: '',
+      });
 
       expect(result.status).toBeGreaterThan(0);
       expect(result.output).toMatch(/api key/i);
@@ -99,10 +114,14 @@ describe('CLI Stdin/Stdout E2E', () => {
       fs.writeFileSync(testFile, 'Test');
 
       // Missing required --to flag
-      const result = runCLIExpectError(`translate "${testFile}"`, { apiKey: 'test-key:fx' });
+      const result = runCLIExpectError(`translate "${testFile}"`, {
+        apiKey: 'test-key:fx',
+      });
 
       expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toMatch(/required option.*--to|missing.*--to|target language.*--to|No target language specified/i);
+      expect(result.output).toMatch(
+        /required option.*--to|missing.*--to|target language.*--to|No target language specified/i
+      );
     });
   });
 
@@ -131,14 +150,17 @@ describe('CLI Stdin/Stdout E2E', () => {
     it('should support chaining with pipes', () => {
       // Test that help output can be piped to grep
       try {
-        const result = execSync(`node ${CLI_PATH} translate --help | grep "Usage:"`, {
-          encoding: 'utf-8',
-          shell: '/bin/bash',
-          env: {
-            ...process.env,
-            DEEPL_CONFIG_DIR: testConfigDir,
-          },
-        });
+        const result = execSync(
+          `node ${CLI_PATH} translate --help | grep "Usage:"`,
+          {
+            encoding: 'utf-8',
+            shell: '/bin/bash',
+            env: {
+              ...process.env,
+              DEEPL_CONFIG_DIR: testConfigDir,
+            },
+          }
+        );
 
         expect(result).toContain('Usage:');
       } catch (error) {
@@ -150,7 +172,9 @@ describe('CLI Stdin/Stdout E2E', () => {
       const inputFile = path.join(testDir, 'input.txt');
       fs.writeFileSync(inputFile, 'Test content');
 
-      const result = runCLIWithStdin('translate --to es', 'Test from stdin', { apiKey: 'test-key:fx' });
+      const result = runCLIWithStdin('translate --to es', 'Test from stdin', {
+        apiKey: 'test-key:fx',
+      });
 
       // Should accept piped input
       expect(result.status).toBeGreaterThan(0); // Will fail at API call
@@ -178,7 +202,9 @@ describe('CLI Stdin/Stdout E2E', () => {
     });
 
     it('should exit with non-zero for errors', () => {
-      const result = runCLIExpectError('translate nonexistent.txt --to es', { apiKey: 'test-key' });
+      const result = runCLIExpectError('translate nonexistent.txt --to es', {
+        apiKey: 'test-key',
+      });
 
       expect(result.status).toBeGreaterThan(0);
     });
@@ -187,11 +213,12 @@ describe('CLI Stdin/Stdout E2E', () => {
       const testFile = path.join(testDir, 'exit-code-test.txt');
       fs.writeFileSync(testFile, 'Test');
 
-      const result = runCLIExpectError(`translate "${testFile}"`, { apiKey: 'test-key' });
+      const result = runCLIExpectError(`translate "${testFile}"`, {
+        apiKey: 'test-key',
+      });
 
       expect(result.status).toBeGreaterThan(0);
     });
-
   });
 
   describe('quiet mode', () => {
@@ -199,7 +226,10 @@ describe('CLI Stdin/Stdout E2E', () => {
       const testFile = path.join(testDir, 'quiet-test.txt');
       fs.writeFileSync(testFile, 'Test');
 
-      const result = runCLIExpectError(`translate "${testFile}" --to es --quiet`, { apiKey: 'test-key:fx' });
+      const result = runCLIExpectError(
+        `translate "${testFile}" --to es --quiet`,
+        { apiKey: 'test-key:fx' }
+      );
 
       // Will fail at API call, but --quiet flag should be accepted
       expect(result.output).not.toMatch(/unknown option.*quiet/i);
@@ -210,10 +240,14 @@ describe('CLI Stdin/Stdout E2E', () => {
       fs.writeFileSync(testFile, 'Test');
 
       // Missing --to flag should still show error
-      const result = runCLIExpectError(`translate "${testFile}" --quiet`, { apiKey: 'test-key:fx' });
+      const result = runCLIExpectError(`translate "${testFile}" --quiet`, {
+        apiKey: 'test-key:fx',
+      });
 
       expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toMatch(/required option.*--to|target language.*--to|No target language specified/i);
+      expect(result.output).toMatch(
+        /required option.*--to|target language.*--to|No target language specified/i
+      );
     });
   });
 });
diff --git a/tests/e2e/cli-stdout-routing.e2e.test.ts b/tests/e2e/cli-stdout-routing.e2e.test.ts
index 3881b3d2..a0552510 100644
--- a/tests/e2e/cli-stdout-routing.e2e.test.ts
+++ b/tests/e2e/cli-stdout-routing.e2e.test.ts
@@ -32,26 +32,27 @@ describe('CLI stdout routing E2E', () => {
   }
 
   function writeSyncProject(): void {
-    const yaml = [
-      'version: 1',
-      'source_locale: en',
-      'target_locales:',
-      '  - de',
-      'buckets:',
-      '  json:',
-      '    include:',
-      '      - "locales/en.json"',
-    ].join('\n') + '\n';
+    const yaml =
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - de',
+        'buckets:',
+        '  json:',
+        '    include:',
+        '      - "locales/en.json"',
+      ].join('\n') + '\n';
     fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.yaml'), yaml);
     const dir = path.join(testFiles.path, 'locales');
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(
       path.join(dir, 'en.json'),
-      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n',
+      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
     );
     fs.writeFileSync(
       path.join(dir, 'de.json'),
-      JSON.stringify({ greeting: 'Hallo' }, null, 2) + '\n',
+      JSON.stringify({ greeting: 'Hallo' }, null, 2) + '\n'
     );
   }
 
@@ -90,12 +91,12 @@ describe('CLI stdout routing E2E', () => {
       fs.mkdirSync(localesDir, { recursive: true });
       fs.writeFileSync(
         path.join(localesDir, 'en.json'),
-        JSON.stringify({ greeting: 'Hello' }) + '\n',
+        JSON.stringify({ greeting: 'Hello' }) + '\n'
       );
 
       const stdout = runStdout(
         'sync init --source-locale en --target-locales de --file-format json --path "locales/en.json"',
-        initDir.path,
+        initDir.path
       );
 
       expect(stdout).toContain('Created');
@@ -110,7 +111,9 @@ describe('CLI stdout routing E2E', () => {
     try {
       fs.writeFileSync(
         path.join(authConfig.path, 'config.json'),
-        JSON.stringify({ auth: { apiKey: 'abcd1234-5678-90ef-ghij-klmnopqrwxyz' } }),
+        JSON.stringify({
+          auth: { apiKey: 'abcd1234-5678-90ef-ghij-klmnopqrwxyz' },
+        })
       );
       const stdout = execSync(`node ${CLI_PATH} auth show`, {
         encoding: 'utf-8',
diff --git a/tests/e2e/cli-structured-file.e2e.test.ts b/tests/e2e/cli-structured-file.e2e.test.ts
index ce7ca384..52ae63b0 100644
--- a/tests/e2e/cli-structured-file.e2e.test.ts
+++ b/tests/e2e/cli-structured-file.e2e.test.ts
@@ -11,7 +11,9 @@ describe('Structured File Translation E2E', () => {
   const testConfig = createTestConfigDir('structured-e2e-config');
   const testFiles = createTestDir('structured-e2e');
   const testDir = testFiles.path;
-  const { runCLI } = makeRunCLI(testConfig.path, { apiKey: 'fake-key-for-e2e' });
+  const { runCLI } = makeRunCLI(testConfig.path, {
+    apiKey: 'fake-key-for-e2e',
+  });
 
   afterAll(() => {
     testFiles.cleanup();
@@ -27,7 +29,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, JSON.stringify({ key: 'Hello' }, null, 2));
 
       try {
-        runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+        runCLI(
+          `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+        );
       } catch (error: any) {
         const output = error.stderr ?? error.stdout ?? '';
         // Should NOT fail with "Unsupported file type"
@@ -41,7 +45,9 @@ describe('Structured File Translation E2E', () => {
 
       fs.writeFileSync(inputPath, '{}');
 
-      const output = runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+      const output = runCLI(
+        `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+      );
       expect(output).toContain('Translated');
 
       const result = JSON.parse(fs.readFileSync(outputPath, 'utf-8'));
@@ -55,7 +61,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, '{ not: valid }');
 
       try {
-        runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+        runCLI(
+          `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+        );
         fail('Should have thrown');
       } catch (error: any) {
         expect(error.status).toBeGreaterThan(0);
@@ -69,7 +77,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, '');
 
       try {
-        runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+        runCLI(
+          `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+        );
         fail('Should have thrown');
       } catch (error: any) {
         expect(error.status).toBeGreaterThan(0);
@@ -81,9 +91,14 @@ describe('Structured File Translation E2E', () => {
       const outputPath = path.join(testDir, 'indent-e2e-es.json');
 
       // Write an empty nested object — will be translated without API since no strings
-      fs.writeFileSync(inputPath, JSON.stringify({ nested: { count: 42 } }, null, 4));
-
-      const output = runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify({ nested: { count: 42 } }, null, 4)
+      );
+
+      const output = runCLI(
+        `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+      );
       expect(output).toContain('Translated');
 
       const raw = fs.readFileSync(outputPath, 'utf-8');
@@ -114,7 +129,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, 'key: Hello\n');
 
       try {
-        runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+        runCLI(
+          `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+        );
       } catch (error: any) {
         const output = error.stderr ?? error.stdout ?? '';
         expect(output).not.toContain('Unsupported file type');
@@ -129,7 +146,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, 'key: Hello\n');
 
       try {
-        runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+        runCLI(
+          `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+        );
       } catch (error: any) {
         const output = error.stderr ?? error.stdout ?? '';
         expect(output).not.toContain('Unsupported file type');
@@ -143,7 +162,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, '');
 
       try {
-        runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+        runCLI(
+          `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+        );
         fail('Should have thrown');
       } catch (error: any) {
         expect(error.status).toBeGreaterThan(0);
@@ -159,7 +180,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, '{}');
 
       // Should not throw (exit code 0)
-      const output = runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+      const output = runCLI(
+        `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+      );
       expect(output).toContain('Translated');
     });
 
@@ -170,7 +193,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, 'NOT JSON');
 
       try {
-        runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+        runCLI(
+          `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+        );
         fail('Should have thrown');
       } catch (error: any) {
         expect(error.status).toBeGreaterThan(0);
@@ -184,7 +209,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, JSON.stringify({ key: 'test' }, null, 2));
 
       try {
-        runCLI(`deepl translate "${inputPath}" --to INVALID --output "${outputPath}"`);
+        runCLI(
+          `deepl translate "${inputPath}" --to INVALID --output "${outputPath}"`
+        );
         fail('Should have thrown');
       } catch (error: any) {
         expect(error.status).toBeGreaterThan(0);
@@ -200,7 +227,9 @@ describe('Structured File Translation E2E', () => {
       fs.writeFileSync(inputPath, '{}');
 
       // This should succeed (no API needed for empty object)
-      const output = runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+      const output = runCLI(
+        `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+      );
       expect(output).toContain('Translated');
     });
 
@@ -213,7 +242,9 @@ describe('Structured File Translation E2E', () => {
 
       fs.writeFileSync(inputPath, '{}');
 
-      const output = runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+      const output = runCLI(
+        `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+      );
       expect(output).toContain('Translated');
     });
 
diff --git a/tests/e2e/cli-success-paths.e2e.test.ts b/tests/e2e/cli-success-paths.e2e.test.ts
index 5245aafb..8abc8914 100644
--- a/tests/e2e/cli-success-paths.e2e.test.ts
+++ b/tests/e2e/cli-success-paths.e2e.test.ts
@@ -40,7 +40,10 @@ describe('CLI Success Paths E2E', () => {
 
       child.stderr.on('data', (data: Buffer) => {
         const msg = data.toString();
-        if (!msg.includes('ExperimentalWarning') && !msg.includes('--experimental')) {
+        if (
+          !msg.includes('ExperimentalWarning') &&
+          !msg.includes('--experimental')
+        ) {
           process.stderr.write(`[mock-server stderr] ${msg}`);
         }
       });
@@ -52,7 +55,10 @@ describe('CLI Success Paths E2E', () => {
         }
       });
 
-      setTimeout(() => reject(new Error('Mock server did not start within 15s')), 15000);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
     });
   }
 
@@ -68,24 +74,33 @@ describe('CLI Success Paths E2E', () => {
       cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
-
     };
-    fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(config, null, 2));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
   }
 
   let runCLI: (command: string) => string;
   let runCLIAll: (command: string) => string;
   let runCLIPipe: (stdin: string, command: string) => string;
-  let runCLIExpectError: (command: string) => { status: number; output: string };
+  let runCLIExpectError: (command: string) => {
+    status: number;
+    output: string;
+  };
 
   beforeAll(async () => {
     testConfigDir = testConfig.path;
     testDir = testFiles.path;
 
-    const helpers = makeNodeRunCLI(testConfigDir, { noColor: true, timeout: 15000 });
+    const helpers = makeNodeRunCLI(testConfigDir, {
+      noColor: true,
+      timeout: 15000,
+    });
     runCLI = (command: string) => helpers.runCLI(command);
     runCLIAll = (command: string) => helpers.runCLIAll(command);
-    runCLIPipe = (stdin: string, command: string) => helpers.runCLIPipe(stdin, command);
+    runCLIPipe = (stdin: string, command: string) =>
+      helpers.runCLIPipe(stdin, command);
     runCLIExpectError = (command: string) => helpers.runCLIExpectError(command);
 
     mockPort = await startMockServer();
@@ -119,7 +134,10 @@ describe('CLI Success Paths E2E', () => {
     });
 
     it('should translate text from stdin pipe', () => {
-      const output = runCLIPipe('Translate me', `translate --to es --api-url ${baseUrl}`);
+      const output = runCLIPipe(
+        'Translate me',
+        `translate --to es --api-url ${baseUrl}`
+      );
       expect(output.trim().split('\n')[0]).toBe('Traduceme');
     });
 
@@ -134,7 +152,9 @@ describe('CLI Success Paths E2E', () => {
     it('should still reject a target that is not shaped like a language tag', () => {
       const result = runCLIExpectError('translate "Hello" --to notalanguage');
       expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toMatch(/Invalid target language code: "notalanguage"/);
+      expect(result.output).toMatch(
+        /Invalid target language code: "notalanguage"/
+      );
     });
 
     it('should translate a file and write to output', () => {
@@ -169,7 +189,7 @@ describe('CLI Success Paths E2E', () => {
       const outputFile = path.join(testDir, 'extended-file.af.txt');
 
       const result = runCLIExpectError(
-        `translate "${inputFile}" --to af --formality more --output "${outputFile}"`,
+        `translate "${inputFile}" --to af --formality more --output "${outputFile}"`
       );
 
       expect(result.status).toBe(6);
@@ -183,7 +203,7 @@ describe('CLI Success Paths E2E', () => {
       fs.writeFileSync(path.join(dirPath, 'a.txt'), 'Hello', 'utf-8');
 
       const result = runCLIExpectError(
-        `translate "${dirPath}" --to af --formality more --output "${testDir}/extended-dir-out"`,
+        `translate "${dirPath}" --to af --formality more --output "${testDir}/extended-dir-out"`
       );
 
       expect(result.status).toBe(6);
@@ -196,10 +216,11 @@ describe('CLI Success Paths E2E', () => {
       fs.writeFileSync(path.join(dirPath, 'a.txt'), 'Hello', 'utf-8');
 
       const output = runCLIAll(
-        `translate "${dirPath}" --to de,ex --output "${testDir}/deferral-dir-out"`,
+        `translate "${dirPath}" --to de,ex --output "${testDir}/deferral-dir-out"`
       );
 
-      const notices = output.match(/is not in the bundled language list/g) ?? [];
+      const notices =
+        output.match(/is not in the bundled language list/g) ?? [];
       expect(notices).toHaveLength(1);
       expect(output).toContain('"ex" is not in the bundled language list');
     });
@@ -277,7 +298,9 @@ describe('CLI Success Paths E2E', () => {
       // the same objects and is stripped without --features, so the two must not
       // be confused: this field stays.
       const output = runCLI('languages --target --format json');
-      const parsed = JSON.parse(output.trim()) as Array<Record<string, unknown>>;
+      const parsed = JSON.parse(output.trim()) as Array<
+        Record<string, unknown>
+      >;
 
       expect(parsed.length).toBeGreaterThan(0);
       for (const entry of parsed) {
@@ -285,13 +308,19 @@ describe('CLI Success Paths E2E', () => {
         expect(typeof entry['supportsFormality']).toBe('boolean');
         expect(entry).not.toHaveProperty('features');
       }
-      expect(parsed.find(e => e['language'] === 'de')?.['supportsFormality']).toBe(true);
-      expect(parsed.find(e => e['language'] === 'en')?.['supportsFormality']).toBe(false);
+      expect(
+        parsed.find((e) => e['language'] === 'de')?.['supportsFormality']
+      ).toBe(true);
+      expect(
+        parsed.find((e) => e['language'] === 'en')?.['supportsFormality']
+      ).toBe(false);
     });
 
     it('should omit supportsFormality from source languages in --format json', () => {
       const output = runCLI('languages --source --format json');
-      const parsed = JSON.parse(output.trim()) as Array<Record<string, unknown>>;
+      const parsed = JSON.parse(output.trim()) as Array<
+        Record<string, unknown>
+      >;
 
       expect(parsed.length).toBeGreaterThan(0);
       for (const entry of parsed) {
@@ -301,9 +330,13 @@ describe('CLI Success Paths E2E', () => {
 
     it('should include the features matrix only with --features', () => {
       const output = runCLI('languages --target --features --format json');
-      const parsed = JSON.parse(output.trim()) as Array<Record<string, unknown>>;
+      const parsed = JSON.parse(output.trim()) as Array<
+        Record<string, unknown>
+      >;
 
-      expect(parsed.find(e => e['language'] === 'de')).toHaveProperty('features');
+      expect(parsed.find((e) => e['language'] === 'de')).toHaveProperty(
+        'features'
+      );
     });
   });
 });
diff --git a/tests/e2e/cli-sync-error-envelope.e2e.test.ts b/tests/e2e/cli-sync-error-envelope.e2e.test.ts
index 8d0f7541..e681c1c0 100644
--- a/tests/e2e/cli-sync-error-envelope.e2e.test.ts
+++ b/tests/e2e/cli-sync-error-envelope.e2e.test.ts
@@ -38,10 +38,16 @@ describe('CLI sync --format json error envelope', () => {
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
     };
-    fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(config, null, 2));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
   }
 
-  function writeSyncConfig(projectDir: string, opts?: { enableTms?: boolean }): void {
+  function writeSyncConfig(
+    projectDir: string,
+    opts?: { enableTms?: boolean }
+  ): void {
     const yaml: string[] = [
       'version: 1',
       'source_locale: en',
@@ -60,7 +66,10 @@ describe('CLI sync --format json error envelope', () => {
       yaml.push('  auth: "api_key_env"');
       yaml.push('  api_key_env: "TMS_API_KEY"');
     }
-    fs.writeFileSync(path.join(projectDir, '.deepl-sync.yaml'), yaml.join('\n') + '\n');
+    fs.writeFileSync(
+      path.join(projectDir, '.deepl-sync.yaml'),
+      yaml.join('\n') + '\n'
+    );
   }
 
   function writeSourceFile(projectDir: string): void {
@@ -68,11 +77,13 @@ describe('CLI sync --format json error envelope', () => {
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(
       path.join(dir, 'en.json'),
-      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n',
+      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n'
     );
   }
 
-  function buildEnv(extra: Record<string, string | undefined> = {}): NodeJS.ProcessEnv {
+  function buildEnv(
+    extra: Record<string, string | undefined> = {}
+  ): NodeJS.ProcessEnv {
     return {
       ...process.env,
       DEEPL_CONFIG_DIR: testConfig.path,
@@ -87,14 +98,21 @@ describe('CLI sync --format json error envelope', () => {
     stderr: string;
   }
 
-  function runCli(args: string[], env: Record<string, string | undefined> = {}): Run {
-    const result: SpawnSyncReturns<string> = spawnSync('node', [CLI_PATH, ...args], {
-      encoding: 'utf-8',
-      cwd: testFiles.path,
-      env: buildEnv(env),
-      stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: 15000,
-    });
+  function runCli(
+    args: string[],
+    env: Record<string, string | undefined> = {}
+  ): Run {
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        cwd: testFiles.path,
+        env: buildEnv(env),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 15000,
+      }
+    );
     return {
       status: result.status ?? 1,
       stdout: result.stdout ?? '',
@@ -108,7 +126,8 @@ describe('CLI sync --format json error envelope', () => {
 
   beforeEach(() => {
     const localesDir = path.join(testFiles.path, 'locales');
-    if (fs.existsSync(localesDir)) fs.rmSync(localesDir, { recursive: true, force: true });
+    if (fs.existsSync(localesDir))
+      fs.rmSync(localesDir, { recursive: true, force: true });
     const lock = path.join(testFiles.path, '.deepl-sync.lock');
     if (fs.existsSync(lock)) fs.unlinkSync(lock);
     const syncCfg = path.join(testFiles.path, '.deepl-sync.yaml');
@@ -157,7 +176,14 @@ describe('CLI sync --format json error envelope', () => {
   describe('init envelope on non-TTY without all four flags (ValidationError, exit 6)', () => {
     it('deepl sync init --format json → envelope ValidationError/6', () => {
       writeSourceFile(testFiles.path);
-      const run = runCli(['sync', 'init', '--format', 'json', '--source-locale', 'en']);
+      const run = runCli([
+        'sync',
+        'init',
+        '--format',
+        'json',
+        '--source-locale',
+        'en',
+      ]);
       expect(run.status).toBe(6);
       const envelope = assertErrorEnvelope(run.stderr, 'ValidationError', 6);
       expect(envelope.error.message).toMatch(/All four flags/);
@@ -171,11 +197,16 @@ describe('CLI sync --format json error envelope', () => {
       const run = runCli([
         'sync',
         'init',
-        '--format', 'json',
-        '--source-locale', 'en',
-        '--target-locales', 'de,fr',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        '--format',
+        'json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de,fr',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(run.status).toBe(0);
@@ -195,11 +226,16 @@ describe('CLI sync --format json error envelope', () => {
       const run = runCli([
         'sync',
         'init',
-        '--format', 'json',
-        '--source-locale', 'en',
-        '--target-locales', 'de',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        '--format',
+        'json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(run.status).toBe(7);
@@ -232,7 +268,10 @@ describe('CLI sync --format json error envelope', () => {
         '  "stats": { "total_keys": 1, "total_translations": 1, "last_sync": "2026-04-20T12:00:00Z" }',
         '}',
       ].join('\n');
-      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.lock'), conflictedLock);
+      fs.writeFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        conflictedLock
+      );
 
       const run = runCli(['sync', 'resolve', '--format', 'json']);
       expect(run.status).toBe(11);
diff --git a/tests/e2e/cli-sync-force-guard.e2e.test.ts b/tests/e2e/cli-sync-force-guard.e2e.test.ts
index 5b378047..9a384ad3 100644
--- a/tests/e2e/cli-sync-force-guard.e2e.test.ts
+++ b/tests/e2e/cli-sync-force-guard.e2e.test.ts
@@ -28,14 +28,18 @@ function makeTmpProject(): string {
       cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
-    }),
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: true,
+      },
+    })
   );
   const localesDir = path.join(dir, 'locales');
   fs.mkdirSync(localesDir, { recursive: true });
   fs.writeFileSync(
     path.join(localesDir, 'en.json'),
-    JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n',
+    JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
   );
   fs.writeFileSync(
     path.join(dir, '.deepl-sync.yaml'),
@@ -49,7 +53,7 @@ function makeTmpProject(): string {
       '    include:',
       '      - "locales/en.json"',
       '',
-    ].join('\n'),
+    ].join('\n')
   );
   return dir;
 }
@@ -63,7 +67,7 @@ interface RunResult {
 
 function run(
   args: string[],
-  opts: { cwd: string; env?: NodeJS.ProcessEnv; input?: string },
+  opts: { cwd: string; env?: NodeJS.ProcessEnv; input?: string }
 ): RunResult {
   const result: SpawnSyncReturns<string> = spawnSync(
     'node',
@@ -74,7 +78,7 @@ function run(
       env: opts.env ?? { ...process.env, NO_COLOR: '1' },
       input: opts.input,
       timeout: 15000,
-    },
+    }
   );
   const stdout = result.stdout ?? '';
   const stderr = result.stderr ?? '';
@@ -94,25 +98,36 @@ describe('deepl sync --force billing defense', () => {
   });
 
   afterEach(() => {
-    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+    if (fs.existsSync(tmpDir))
+      fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
   describe('--watch --force rejection', () => {
     it('exits non-zero with a ValidationError when --watch and --force are combined', () => {
       const result = run(['--watch', '--force'], {
         cwd: tmpDir,
-        env: { ...process.env, DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'), NO_COLOR: '1' },
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'),
+          NO_COLOR: '1',
+        },
       });
 
       expect(result.status).toBe(6);
-      expect(result.combined.toLowerCase()).toMatch(/watch.*force|force.*watch/);
+      expect(result.combined.toLowerCase()).toMatch(
+        /watch.*force|force.*watch/
+      );
       expect(result.combined).toMatch(/billing loop|retranslate/i);
     });
 
     it('error message hints at --force once + --watch separately', () => {
       const result = run(['--watch', '--force'], {
         cwd: tmpDir,
-        env: { ...process.env, DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'), NO_COLOR: '1' },
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'),
+          NO_COLOR: '1',
+        },
       });
 
       expect(result.status).toBe(6);
@@ -142,7 +157,11 @@ describe('deepl sync --force billing defense', () => {
     it('proceeds past the guard without a prompt (exits 0 or 1 on API fail, not 6)', () => {
       const result = run(['--force', '--yes', '--dry-run'], {
         cwd: tmpDir,
-        env: { ...process.env, DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'), NO_COLOR: '1' },
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'),
+          NO_COLOR: '1',
+        },
       });
 
       // The guard is bypassed; the process exits for API/config reasons (not ValidationError 6)
@@ -174,7 +193,11 @@ describe('deepl sync --force billing defense', () => {
       const { CI: _ci, ...baseEnv } = process.env;
       const result = run(['--force', '--dry-run'], {
         cwd: tmpDir,
-        env: { ...baseEnv, DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'), NO_COLOR: '1' },
+        env: {
+          ...baseEnv,
+          DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'),
+          NO_COLOR: '1',
+        },
         input: 'y\n',
       });
 
diff --git a/tests/e2e/cli-sync-init.e2e.test.ts b/tests/e2e/cli-sync-init.e2e.test.ts
index ed2ef964..6369b796 100644
--- a/tests/e2e/cli-sync-init.e2e.test.ts
+++ b/tests/e2e/cli-sync-init.e2e.test.ts
@@ -13,7 +13,11 @@
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { assertErrorEnvelope, createTestConfigDir, createTestDir } from '../helpers';
+import {
+  assertErrorEnvelope,
+  createTestConfigDir,
+  createTestDir,
+} from '../helpers';
 
 const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
 
@@ -34,10 +38,15 @@ describe('deepl sync init — no i18n files detected', () => {
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
     };
-    fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(config, null, 2));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
   }
 
-  function buildEnv(extra: Record<string, string | undefined> = {}): NodeJS.ProcessEnv {
+  function buildEnv(
+    extra: Record<string, string | undefined> = {}
+  ): NodeJS.ProcessEnv {
     return {
       ...process.env,
       DEEPL_CONFIG_DIR: testConfig.path,
@@ -113,15 +122,20 @@ describe('deepl sync init — no i18n files detected', () => {
     fs.mkdirSync(localesDir, { recursive: true });
     fs.writeFileSync(
       path.join(localesDir, 'en.json'),
-      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n',
+      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
     );
 
     const run = runCli([
-      'sync', 'init',
-      '--source-locale', 'en',
-      '--target-locales', 'de',
-      '--file-format', 'json',
-      '--path', 'locales/en.json',
+      'sync',
+      'init',
+      '--source-locale',
+      'en',
+      '--target-locales',
+      'de',
+      '--file-format',
+      'json',
+      '--path',
+      'locales/en.json',
     ]);
 
     expect(run.status).toBe(0);
diff --git a/tests/e2e/cli-sync-json-contract.e2e.test.ts b/tests/e2e/cli-sync-json-contract.e2e.test.ts
index af077cf0..6dc7fb41 100644
--- a/tests/e2e/cli-sync-json-contract.e2e.test.ts
+++ b/tests/e2e/cli-sync-json-contract.e2e.test.ts
@@ -5,7 +5,12 @@
  * produces a parseable file. Progress events and diagnostic logs remain on stderr.
  */
 
-import { spawn, ChildProcess, spawnSync, SpawnSyncReturns } from 'child_process';
+import {
+  spawn,
+  ChildProcess,
+  spawnSync,
+  SpawnSyncReturns,
+} from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import nock from 'nock';
@@ -40,7 +45,10 @@ describe('CLI Sync --format json stdout contract', () => {
 
       child.stderr.on('data', (data: Buffer) => {
         const msg = data.toString();
-        if (!msg.includes('ExperimentalWarning') && !msg.includes('--experimental')) {
+        if (
+          !msg.includes('ExperimentalWarning') &&
+          !msg.includes('--experimental')
+        ) {
           process.stderr.write(`[mock-server stderr] ${msg}`);
         }
       });
@@ -52,7 +60,10 @@ describe('CLI Sync --format json stdout contract', () => {
         }
       });
 
-      setTimeout(() => reject(new Error('Mock server did not start within 15s')), 15000);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
     });
   }
 
@@ -69,30 +80,44 @@ describe('CLI Sync --format json stdout contract', () => {
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
     };
-    fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(config, null, 2));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
   }
 
-  function writeSyncConfig(projectDir: string, locales: string[] = ['de']): void {
-    const yaml = [
-      'version: 1',
-      'source_locale: en',
-      'target_locales:',
-      ...locales.map((l) => `  - ${l}`),
-      'buckets:',
-      '  json:',
-      '    include:',
-      '      - "locales/en.json"',
-    ].join('\n') + '\n';
+  function writeSyncConfig(
+    projectDir: string,
+    locales: string[] = ['de']
+  ): void {
+    const yaml =
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        ...locales.map((l) => `  - ${l}`),
+        'buckets:',
+        '  json:',
+        '    include:',
+        '      - "locales/en.json"',
+      ].join('\n') + '\n';
     fs.writeFileSync(path.join(projectDir, '.deepl-sync.yaml'), yaml);
   }
 
   function writeSourceFile(projectDir: string): void {
     const dir = path.join(projectDir, 'locales');
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, 'en.json'), JSON.stringify({
-      greeting: 'Hello',
-      farewell: 'Goodbye',
-    }, null, 2) + '\n');
+    fs.writeFileSync(
+      path.join(dir, 'en.json'),
+      JSON.stringify(
+        {
+          greeting: 'Hello',
+          farewell: 'Goodbye',
+        },
+        null,
+        2
+      ) + '\n'
+    );
   }
 
   function buildEnv(): NodeJS.ProcessEnv {
@@ -118,7 +143,7 @@ describe('CLI Sync --format json stdout contract', () => {
         cwd: testFiles.path,
         env: buildEnv(),
         timeout: 15000,
-      },
+      }
     );
     return {
       status: result.status ?? 1,
@@ -157,7 +182,9 @@ describe('CLI Sync --format json stdout contract', () => {
   function parseFinalJson(stdout: string): Record<string, unknown> {
     const trimmed = stdout.trim();
     if (trimmed.length === 0) {
-      throw new Error('stdout is empty; success JSON payload not routed to stdout');
+      throw new Error(
+        'stdout is empty; success JSON payload not routed to stdout'
+      );
     }
     const match = trimmed.match(/\{[\s\S]*\}\s*$/);
     if (!match) {
diff --git a/tests/e2e/cli-sync-option-routing.e2e.test.ts b/tests/e2e/cli-sync-option-routing.e2e.test.ts
index 69877598..185b0a20 100644
--- a/tests/e2e/cli-sync-option-routing.e2e.test.ts
+++ b/tests/e2e/cli-sync-option-routing.e2e.test.ts
@@ -28,25 +28,36 @@ describe('CLI sync option routing E2E', () => {
     const config = {
       auth: { apiKey: 'mock-api-key-for-testing:fx' },
       api: { baseUrl: 'http://127.0.0.1:1/', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: true,
+      },
       cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
     };
-    fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(config, null, 2));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
   }
 
-  function writeSyncConfig(projectDir: string, locales: string[] = ['de', 'fr']): string {
-    const yaml = [
-      'version: 1',
-      'source_locale: en',
-      'target_locales:',
-      ...locales.map((l) => `  - ${l}`),
-      'buckets:',
-      '  json:',
-      '    include:',
-      '      - "locales/en.json"',
-    ].join('\n') + '\n';
+  function writeSyncConfig(
+    projectDir: string,
+    locales: string[] = ['de', 'fr']
+  ): string {
+    const yaml =
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        ...locales.map((l) => `  - ${l}`),
+        'buckets:',
+        '  json:',
+        '    include:',
+        '      - "locales/en.json"',
+      ].join('\n') + '\n';
     const configPath = path.join(projectDir, '.deepl-sync.yaml');
     fs.writeFileSync(configPath, yaml);
     return configPath;
@@ -57,7 +68,7 @@ describe('CLI sync option routing E2E', () => {
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(
       path.join(dir, 'en.json'),
-      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n',
+      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n'
     );
   }
 
@@ -69,26 +80,35 @@ describe('CLI sync option routing E2E', () => {
   }
 
   function runCli(args: string[], cwd: string = testFiles.path): Run {
-    const result: SpawnSyncReturns<string> = spawnSync('node', [CLI_PATH, ...args], {
-      encoding: 'utf-8',
-      cwd,
-      env: {
-        ...process.env,
-        DEEPL_CONFIG_DIR: testConfig.path,
-        DEEPL_API_KEY: 'mock-api-key-for-testing:fx',
-        NO_COLOR: '1',
-        CI: undefined,
-        // Ambient NODE_OPTIONS can make node print warnings to stderr, which
-        // the JSON-envelope assertions parse.
-        NODE_OPTIONS: undefined,
-        NODE_NO_WARNINGS: '1',
-      },
-      stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: 15000,
-    });
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        cwd,
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: testConfig.path,
+          DEEPL_API_KEY: 'mock-api-key-for-testing:fx',
+          NO_COLOR: '1',
+          CI: undefined,
+          // Ambient NODE_OPTIONS can make node print warnings to stderr, which
+          // the JSON-envelope assertions parse.
+          NODE_OPTIONS: undefined,
+          NODE_NO_WARNINGS: '1',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 15000,
+      }
+    );
     const stdout = result.stdout ?? '';
     const stderr = result.stderr ?? '';
-    return { status: result.status ?? 1, stdout, stderr, output: stdout + stderr };
+    return {
+      status: result.status ?? 1,
+      stdout,
+      stderr,
+      output: stdout + stderr,
+    };
   }
 
   beforeAll(() => {
@@ -97,7 +117,10 @@ describe('CLI sync option routing E2E', () => {
 
   beforeEach(() => {
     for (const entry of fs.readdirSync(testFiles.path)) {
-      fs.rmSync(path.join(testFiles.path, entry), { recursive: true, force: true });
+      fs.rmSync(path.join(testFiles.path, entry), {
+        recursive: true,
+        force: true,
+      });
     }
   });
 
@@ -131,7 +154,15 @@ describe('CLI sync option routing E2E', () => {
   });
 
   describe('--sync-config reaches the subcommand handler', () => {
-    for (const sub of ['status', 'validate', 'export', 'audit', 'resolve', 'push', 'pull']) {
+    for (const sub of [
+      'status',
+      'validate',
+      'export',
+      'audit',
+      'resolve',
+      'push',
+      'pull',
+    ]) {
       it(`\`sync ${sub} --sync-config <missing>\` fails with ConfigError (exit 7)`, () => {
         writeSyncConfig(testFiles.path, ['de', 'fr']);
         writeSourceFile(testFiles.path);
@@ -210,7 +241,14 @@ describe('CLI sync option routing E2E', () => {
       writeSyncConfig(testFiles.path, ['de', 'fr']);
       writeSourceFile(testFiles.path);
 
-      const run = runCli(['sync', 'status', '--locale', 'es', '--format', 'json']);
+      const run = runCli([
+        'sync',
+        'status',
+        '--locale',
+        'es',
+        '--format',
+        'json',
+      ]);
 
       expect(run.status).toBe(7);
       const envelope = JSON.parse(run.stderr.trim()) as {
@@ -253,17 +291,25 @@ describe('CLI sync option routing E2E', () => {
 
       const target = path.join(altRoot, 'custom-sync.yaml');
       const run = runCli([
-        'sync', 'init',
-        '--sync-config', target,
-        '--source-locale', 'en',
-        '--target-locales', 'de',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        'sync',
+        'init',
+        '--sync-config',
+        target,
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(run.status).toBe(0);
       expect(fs.existsSync(target)).toBe(true);
-      expect(fs.existsSync(path.join(testFiles.path, '.deepl-sync.yaml'))).toBe(false);
+      expect(fs.existsSync(path.join(testFiles.path, '.deepl-sync.yaml'))).toBe(
+        false
+      );
       expect(fs.readFileSync(target, 'utf-8')).toContain('source_locale: en');
     });
 
@@ -277,12 +323,18 @@ describe('CLI sync option routing E2E', () => {
 
       const target = path.join(altRoot, '.deepl-sync.yaml');
       const run = runCli([
-        'sync', 'init',
-        '--sync-config', target,
-        '--source-locale', 'en',
-        '--target-locales', 'it',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        'sync',
+        'init',
+        '--sync-config',
+        target,
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'it',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(run.status).toBe(0);
@@ -298,12 +350,18 @@ describe('CLI sync option routing E2E', () => {
       const target = writeSyncConfig(altRoot, ['de']);
 
       const run = runCli([
-        'sync', 'init',
-        '--sync-config', target,
-        '--source-locale', 'en',
-        '--target-locales', 'it',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        'sync',
+        'init',
+        '--sync-config',
+        target,
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'it',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(run.output).toContain('already exists');
diff --git a/tests/e2e/cli-sync-push-pull.e2e.test.ts b/tests/e2e/cli-sync-push-pull.e2e.test.ts
index d273dd82..5405fbb5 100644
--- a/tests/e2e/cli-sync-push-pull.e2e.test.ts
+++ b/tests/e2e/cli-sync-push-pull.e2e.test.ts
@@ -11,12 +11,21 @@
  * the driving test clear state and set canned pull responses between runs.
  */
 
-import { spawn, ChildProcess, spawnSync, SpawnSyncReturns } from 'child_process';
+import {
+  spawn,
+  ChildProcess,
+  spawnSync,
+  SpawnSyncReturns,
+} from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import nock from 'nock';
 
-import { createTestConfigDir, createTestDir, assertErrorEnvelope } from '../helpers';
+import {
+  createTestConfigDir,
+  createTestDir,
+  assertErrorEnvelope,
+} from '../helpers';
 import { buildSyncConfigYaml } from '../helpers/sync-harness';
 
 const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
@@ -62,7 +71,10 @@ describe('CLI sync push/pull dispatch E2E', () => {
 
       child.stderr.on('data', (data: Buffer) => {
         const msg = data.toString();
-        if (!msg.includes('ExperimentalWarning') && !msg.includes('--experimental')) {
+        if (
+          !msg.includes('ExperimentalWarning') &&
+          !msg.includes('--experimental')
+        ) {
           process.stderr.write(`[mock-tms stderr] ${msg}`);
         }
       });
@@ -74,7 +86,10 @@ describe('CLI sync push/pull dispatch E2E', () => {
         }
       });
 
-      setTimeout(() => reject(new Error('Mock TMS server did not start within 15s')), 15000);
+      setTimeout(
+        () => reject(new Error('Mock TMS server did not start within 15s')),
+        15000
+      );
     });
   }
 
@@ -101,21 +116,27 @@ describe('CLI sync push/pull dispatch E2E', () => {
     const config = {
       auth: { apiKey: 'mock-api-key-for-testing:fx' },
       api: { baseUrl: 'http://127.0.0.1:1/', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: true,
+      },
       cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
     };
     fs.writeFileSync(
       path.join(testConfig.path, 'config.json'),
-      JSON.stringify(config, null, 2),
+      JSON.stringify(config, null, 2)
     );
   }
 
-  function writeSyncYaml(opts: {
-    targetLocales?: string[];
-    includeTmsBlock?: boolean;
-  } = {}): void {
+  function writeSyncYaml(
+    opts: {
+      targetLocales?: string[];
+      includeTmsBlock?: boolean;
+    } = {}
+  ): void {
     const tms = opts.includeTmsBlock
       ? { enabled: true, server: baseUrl, project_id: PROJECT_ID }
       : undefined;
@@ -127,16 +148,24 @@ describe('CLI sync push/pull dispatch E2E', () => {
     fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.yaml'), yaml);
   }
 
-  function writeSource(keys: Record<string, string> = { greeting: 'Hello', farewell: 'Goodbye' }): void {
+  function writeSource(
+    keys: Record<string, string> = { greeting: 'Hello', farewell: 'Goodbye' }
+  ): void {
     const dir = path.join(testFiles.path, 'locales');
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, 'en.json'), JSON.stringify(keys, null, 2) + '\n');
+    fs.writeFileSync(
+      path.join(dir, 'en.json'),
+      JSON.stringify(keys, null, 2) + '\n'
+    );
   }
 
   function writeTarget(locale: string, keys: Record<string, string>): void {
     const dir = path.join(testFiles.path, 'locales');
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, `${locale}.json`), JSON.stringify(keys, null, 2) + '\n');
+    fs.writeFileSync(
+      path.join(dir, `${locale}.json`),
+      JSON.stringify(keys, null, 2) + '\n'
+    );
   }
 
   function buildEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
@@ -155,13 +184,17 @@ describe('CLI sync push/pull dispatch E2E', () => {
   }
 
   function runCli(args: string[], extraEnv: Record<string, string> = {}): Run {
-    const result: SpawnSyncReturns<string> = spawnSync('node', [CLI_PATH, ...args], {
-      encoding: 'utf-8',
-      cwd: testFiles.path,
-      env: buildEnv(extraEnv),
-      stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: 15000,
-    });
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        cwd: testFiles.path,
+        env: buildEnv(extraEnv),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 15000,
+      }
+    );
     return {
       status: result.status ?? (result.signal ? 128 : 1),
       stdout: result.stdout ?? '',
@@ -183,7 +216,8 @@ describe('CLI sync push/pull dispatch E2E', () => {
     nock.enableNetConnect('127.0.0.1');
     await resetMockServer();
     const localesDir = path.join(testFiles.path, 'locales');
-    if (fs.existsSync(localesDir)) fs.rmSync(localesDir, { recursive: true, force: true });
+    if (fs.existsSync(localesDir))
+      fs.rmSync(localesDir, { recursive: true, force: true });
     for (const name of ['.deepl-sync.yaml', '.deepl-sync.lock']) {
       const p = path.join(testFiles.path, name);
       if (fs.existsSync(p)) fs.unlinkSync(p);
@@ -213,9 +247,14 @@ describe('CLI sync push/pull dispatch E2E', () => {
       for (const req of state.requests) {
         expect(req.method).toBe('PUT');
         expect(req.authHeader).toBe('ApiKey push-pull-key');
-        expect(req.url).toMatch(new RegExp(`^/api/projects/${PROJECT_ID}/keys/`));
+        expect(req.url).toMatch(
+          new RegExp(`^/api/projects/${PROJECT_ID}/keys/`)
+        );
       }
-      expect(Object.keys(state.pushed['de'] ?? {}).sort()).toEqual(['farewell', 'greeting']);
+      expect(Object.keys(state.pushed['de'] ?? {}).sort()).toEqual([
+        'farewell',
+        'greeting',
+      ]);
       expect(state.pushed['de']!['greeting']).toBe('Hallo');
       expect(state.pushed['de']!['farewell']).toBe('Auf Wiedersehen');
     });
@@ -238,13 +277,19 @@ describe('CLI sync push/pull dispatch E2E', () => {
 
       const targetFile = path.join(testFiles.path, 'locales', 'de.json');
       expect(fs.existsSync(targetFile)).toBe(true);
-      const parsed = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<string, string>;
+      const parsed = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<
+        string,
+        string
+      >;
       expect(parsed['greeting']).toBe('Hallo (approved)');
       expect(parsed['farewell']).toBe('Tschuess (approved)');
 
       const state = await inspectMockServer();
       const pullReqs = state.requests.filter(
-        (r) => r.method === 'GET' && r.url.includes('/keys/export') && r.url.includes('locale=de'),
+        (r) =>
+          r.method === 'GET' &&
+          r.url.includes('/keys/export') &&
+          r.url.includes('locale=de')
       );
       expect(pullReqs.length).toBeGreaterThan(0);
       expect(pullReqs[0]!.authHeader).toBe('ApiKey push-pull-key');
@@ -291,13 +336,18 @@ describe('CLI sync push/pull dispatch E2E', () => {
       writeSyncYaml({ includeTmsBlock: true, targetLocales: ['de', 'fr'] });
       writeSource({ greeting: 'Hello', farewell: 'Goodbye' });
 
-      const run = runCli(['sync', 'pull', '--locale', 'fr'], { TMS_API_KEY: 'push-pull-key' });
+      const run = runCli(['sync', 'pull', '--locale', 'fr'], {
+        TMS_API_KEY: 'push-pull-key',
+      });
 
       expect(run.status).toBe(0);
 
       const frFile = path.join(testFiles.path, 'locales', 'fr.json');
       expect(fs.existsSync(frFile)).toBe(true);
-      const frParsed = JSON.parse(fs.readFileSync(frFile, 'utf-8')) as Record<string, string>;
+      const frParsed = JSON.parse(fs.readFileSync(frFile, 'utf-8')) as Record<
+        string,
+        string
+      >;
       expect(frParsed['greeting']).toBe('Bonjour');
 
       const deFile = path.join(testFiles.path, 'locales', 'de.json');
@@ -305,7 +355,7 @@ describe('CLI sync push/pull dispatch E2E', () => {
 
       const state = await inspectMockServer();
       const pullReqs = state.requests.filter(
-        (r) => r.method === 'GET' && r.url.includes('/keys/export'),
+        (r) => r.method === 'GET' && r.url.includes('/keys/export')
       );
       expect(pullReqs.length).toBeGreaterThan(0);
       expect(pullReqs.some((r) => r.url.includes('locale=fr'))).toBe(true);
@@ -318,12 +368,16 @@ describe('CLI sync push/pull dispatch E2E', () => {
       writeTarget('de', { greeting: 'Hallo' });
       writeTarget('fr', { greeting: 'Bonjour' });
 
-      const run = runCli(['sync', 'push', '--locale', 'de'], { TMS_API_KEY: 'push-pull-key' });
+      const run = runCli(['sync', 'push', '--locale', 'de'], {
+        TMS_API_KEY: 'push-pull-key',
+      });
 
       expect(run.status).toBe(0);
 
       const state = await inspectMockServer();
-      expect(Object.keys(state.pushed['de'] ?? {}).sort()).toEqual(['greeting']);
+      expect(Object.keys(state.pushed['de'] ?? {}).sort()).toEqual([
+        'greeting',
+      ]);
       expect(state.pushed['fr']).toBeUndefined();
     });
 
@@ -346,7 +400,7 @@ describe('CLI sync push/pull dispatch E2E', () => {
 
       const state = await inspectMockServer();
       const pullReqs = state.requests.filter(
-        (r) => r.method === 'GET' && r.url.includes('/keys/export'),
+        (r) => r.method === 'GET' && r.url.includes('/keys/export')
       );
       expect(pullReqs.some((r) => r.url.includes('locale=fr'))).toBe(true);
       expect(pullReqs.some((r) => r.url.includes('locale=de'))).toBe(false);
@@ -368,7 +422,11 @@ describe('CLI sync push/pull dispatch E2E', () => {
       });
 
       expect(run.status).toBe(0);
-      const envelope = JSON.parse(run.stdout) as { ok: boolean; pushed: number; skipped: unknown[] };
+      const envelope = JSON.parse(run.stdout) as {
+        ok: boolean;
+        pushed: number;
+        skipped: unknown[];
+      };
       expect(envelope.ok).toBe(true);
       expect(typeof envelope.pushed).toBe('number');
       expect(Array.isArray(envelope.skipped)).toBe(true);
@@ -387,7 +445,11 @@ describe('CLI sync push/pull dispatch E2E', () => {
       });
 
       expect(run.status).toBe(0);
-      const envelope = JSON.parse(run.stdout) as { ok: boolean; pulled: number; skipped: unknown[] };
+      const envelope = JSON.parse(run.stdout) as {
+        ok: boolean;
+        pulled: number;
+        skipped: unknown[];
+      };
       expect(envelope.ok).toBe(true);
       expect(typeof envelope.pulled).toBe('number');
       expect(Array.isArray(envelope.skipped)).toBe(true);
diff --git a/tests/e2e/cli-sync-tms.e2e.test.ts b/tests/e2e/cli-sync-tms.e2e.test.ts
index 47a4161e..12e4e1d8 100644
--- a/tests/e2e/cli-sync-tms.e2e.test.ts
+++ b/tests/e2e/cli-sync-tms.e2e.test.ts
@@ -59,7 +59,10 @@ describe('CLI Sync TMS E2E', () => {
 
       child.stderr.on('data', (data: Buffer) => {
         const msg = data.toString();
-        if (!msg.includes('ExperimentalWarning') && !msg.includes('--experimental')) {
+        if (
+          !msg.includes('ExperimentalWarning') &&
+          !msg.includes('--experimental')
+        ) {
           process.stderr.write(`[mock-server stderr] ${msg}`);
         }
       });
@@ -71,7 +74,10 @@ describe('CLI Sync TMS E2E', () => {
         }
       });
 
-      setTimeout(() => reject(new Error('Mock server did not start within 15s')), 15000);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
     });
   }
 
@@ -79,12 +85,19 @@ describe('CLI Sync TMS E2E', () => {
     const config = {
       auth: { apiKey: 'mock-api-key-for-testing:fx' },
       api: { baseUrl: apiUrl, usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: true,
+      },
       cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
     };
-    fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(config, null, 2));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
   }
 
   function writeSyncYaml(
@@ -92,7 +105,7 @@ describe('CLI Sync TMS E2E', () => {
       targetLocales?: string[];
       includeTmsBlock?: boolean;
       tmsApiKey?: string;
-    } = {},
+    } = {}
   ): void {
     const tms = opts.includeTmsBlock
       ? {
@@ -110,19 +123,32 @@ describe('CLI Sync TMS E2E', () => {
     fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.yaml'), yaml);
   }
 
-  function writeSource(keys: Record<string, string> = { greeting: 'Hello', farewell: 'Goodbye' }): void {
+  function writeSource(
+    keys: Record<string, string> = { greeting: 'Hello', farewell: 'Goodbye' }
+  ): void {
     const dir = path.join(testFiles.path, 'locales');
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, 'en.json'), JSON.stringify(keys, null, 2) + '\n');
+    fs.writeFileSync(
+      path.join(dir, 'en.json'),
+      JSON.stringify(keys, null, 2) + '\n'
+    );
   }
 
-  function writeTargetLocale(locale: string, keys: Record<string, string>): void {
+  function writeTargetLocale(
+    locale: string,
+    keys: Record<string, string>
+  ): void {
     const dir = path.join(testFiles.path, 'locales');
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, `${locale}.json`), JSON.stringify(keys, null, 2) + '\n');
+    fs.writeFileSync(
+      path.join(dir, `${locale}.json`),
+      JSON.stringify(keys, null, 2) + '\n'
+    );
   }
 
-  function buildEnv(extra: Record<string, string> = {}): Record<string, string | undefined> {
+  function buildEnv(
+    extra: Record<string, string> = {}
+  ): Record<string, string | undefined> {
     return {
       ...process.env,
       DEEPL_CONFIG_DIR: testConfig.path,
@@ -133,7 +159,10 @@ describe('CLI Sync TMS E2E', () => {
 
   // Note: execSync is used here intentionally for E2E CLI testing -- the input
   // is fully controlled test data with no user-supplied values.
-  function runSyncAll(args: string, extraEnv: Record<string, string> = {}): string {
+  function runSyncAll(
+    args: string,
+    extraEnv: Record<string, string> = {}
+  ): string {
     return execSync(`node ${CLI_PATH} sync ${args} 2>&1`, {
       encoding: 'utf-8',
       shell: '/bin/sh',
@@ -145,7 +174,7 @@ describe('CLI Sync TMS E2E', () => {
 
   function runSyncExpectError(
     args: string,
-    extraEnv: Record<string, string> = {},
+    extraEnv: Record<string, string> = {}
   ): { status: number; output: string } {
     try {
       const output = execSync(`node ${CLI_PATH} sync ${args} 2>&1`, {
@@ -157,7 +186,11 @@ describe('CLI Sync TMS E2E', () => {
       });
       return { status: 0, output };
     } catch (error: unknown) {
-      const err = error as { status?: number; stderr?: string; stdout?: string };
+      const err = error as {
+        status?: number;
+        stderr?: string;
+        stdout?: string;
+      };
       return {
         status: err.status ?? 1,
         // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty stderr should fall through to stdout
@@ -235,7 +268,10 @@ describe('CLI Sync TMS E2E', () => {
       expect(req.authHeader).toBe('ApiKey e2e-key');
     }
     expect(state.pushed['de']).toBeDefined();
-    expect(Object.keys(state.pushed['de']!).sort()).toEqual(['farewell', 'greeting']);
+    expect(Object.keys(state.pushed['de']!).sort()).toEqual([
+      'farewell',
+      'greeting',
+    ]);
     expect(state.pushed['de']!['greeting']).toBe('Hallo');
     expect(state.pushed['de']!['farewell']).toBe('Auf Wiedersehen');
   });
@@ -257,12 +293,19 @@ describe('CLI Sync TMS E2E', () => {
 
     const targetFile = path.join(testFiles.path, 'locales', 'de.json');
     expect(fs.existsSync(targetFile)).toBe(true);
-    const parsed = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<string, string>;
+    const parsed = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<
+      string,
+      string
+    >;
     expect(parsed['greeting']).toBe('Hallo (approved)');
     expect(parsed['farewell']).toBe('Tschuess (approved)');
 
     const state = await inspectMockServer();
-    expect(state.requests.some((r) => r.method === 'GET' && r.url.includes('locale=de'))).toBe(true);
+    expect(
+      state.requests.some(
+        (r) => r.method === 'GET' && r.url.includes('locale=de')
+      )
+    ).toBe(true);
   });
 
   // ---- Case 11: missing tms: block ----
@@ -278,7 +321,10 @@ describe('CLI Sync TMS E2E', () => {
 
   // ---- Case 12: wrong credentials surface an actionable auth error ----
   it('push with wrong credentials: exits non-zero, stderr names TMS_API_KEY and references 401', async () => {
-    await configureMockServer({ forceStatus: 401, forceBody: { error: 'Unauthorized' } });
+    await configureMockServer({
+      forceStatus: 401,
+      forceBody: { error: 'Unauthorized' },
+    });
 
     writeSyncYaml({ includeTmsBlock: true });
     writeSource({ k: 'Hello' });
diff --git a/tests/e2e/cli-sync-watch.e2e.test.ts b/tests/e2e/cli-sync-watch.e2e.test.ts
index bddf7be4..32808942 100644
--- a/tests/e2e/cli-sync-watch.e2e.test.ts
+++ b/tests/e2e/cli-sync-watch.e2e.test.ts
@@ -33,7 +33,7 @@ describe('deepl sync --watch (subprocess)', () => {
     fs.mkdirSync(localesDir, { recursive: true });
     fs.writeFileSync(
       path.join(localesDir, 'en.json'),
-      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n',
+      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
     );
     fs.writeFileSync(
       path.join(tmpDir, '.deepl-sync.yaml'),
@@ -47,7 +47,7 @@ describe('deepl sync --watch (subprocess)', () => {
         '    include:',
         '      - "locales/en.json"',
         '',
-      ].join('\n'),
+      ].join('\n')
     );
     combined = '';
   });
@@ -64,8 +64,10 @@ describe('deepl sync --watch (subprocess)', () => {
       });
     }
     child = null;
-    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
-    if (fs.existsSync(configDir)) fs.rmSync(configDir, { recursive: true, force: true });
+    if (fs.existsSync(tmpDir))
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    if (fs.existsSync(configDir))
+      fs.rmSync(configDir, { recursive: true, force: true });
   });
 
   function waitForMarker(marker: RegExp, timeoutMs: number): Promise<boolean> {
@@ -93,10 +95,14 @@ describe('deepl sync --watch (subprocess)', () => {
           NO_COLOR: '1',
         },
         stdio: ['ignore', 'pipe', 'pipe'],
-      },
+      }
     );
-    child.stdout?.on('data', (chunk: Buffer) => { combined += chunk.toString(); });
-    child.stderr?.on('data', (chunk: Buffer) => { combined += chunk.toString(); });
+    child.stdout?.on('data', (chunk: Buffer) => {
+      combined += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk: Buffer) => {
+      combined += chunk.toString();
+    });
 
     // Wait for chokidar to warm up and print the "Watching..." banner.
     const watching = await waitForMarker(/Watching .* pattern/i, 5000);
@@ -105,7 +111,7 @@ describe('deepl sync --watch (subprocess)', () => {
     // Modify the source file to trigger a change event.
     fs.writeFileSync(
       path.join(tmpDir, 'locales', 'en.json'),
-      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n',
+      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n'
     );
 
     // Wait up to 3s for the subprocess to register the change and start a sync cycle.
@@ -119,7 +125,9 @@ describe('deepl sync --watch (subprocess)', () => {
     child.kill('SIGTERM');
     const code = await Promise.race([
       exitPromise,
-      new Promise<number | null>((resolve) => setTimeout(() => resolve(-1), 3000)),
+      new Promise<number | null>((resolve) =>
+        setTimeout(() => resolve(-1), 3000)
+      ),
     ]);
 
     // SIGTERM should lead to a clean exit (code 0, or signal-based null on some platforms).
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 6366b93f..ad51b61b 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -8,7 +8,11 @@ import { spawn, spawnSync, ChildProcess, execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import nock from 'nock';
-import { assertErrorEnvelope, createTestConfigDir, createTestDir } from '../helpers';
+import {
+  assertErrorEnvelope,
+  createTestConfigDir,
+  createTestDir,
+} from '../helpers';
 
 const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
 
@@ -39,7 +43,10 @@ describe('CLI Sync E2E', () => {
 
       child.stderr.on('data', (data: Buffer) => {
         const msg = data.toString();
-        if (!msg.includes('ExperimentalWarning') && !msg.includes('--experimental')) {
+        if (
+          !msg.includes('ExperimentalWarning') &&
+          !msg.includes('--experimental')
+        ) {
           process.stderr.write(`[mock-server stderr] ${msg}`);
         }
       });
@@ -51,7 +58,10 @@ describe('CLI Sync E2E', () => {
         }
       });
 
-      setTimeout(() => reject(new Error('Mock server did not start within 15s')), 15000);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
     });
   }
 
@@ -68,30 +78,44 @@ describe('CLI Sync E2E', () => {
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
     };
-    fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(config, null, 2));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
   }
 
-  function writeSyncConfig(projectDir: string, locales: string[] = ['de']): void {
-    const yaml = [
-      'version: 1',
-      'source_locale: en',
-      'target_locales:',
-      ...locales.map(l => `  - ${l}`),
-      'buckets:',
-      '  json:',
-      '    include:',
-      '      - "locales/en.json"',
-    ].join('\n') + '\n';
+  function writeSyncConfig(
+    projectDir: string,
+    locales: string[] = ['de']
+  ): void {
+    const yaml =
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        ...locales.map((l) => `  - ${l}`),
+        'buckets:',
+        '  json:',
+        '    include:',
+        '      - "locales/en.json"',
+      ].join('\n') + '\n';
     fs.writeFileSync(path.join(projectDir, '.deepl-sync.yaml'), yaml);
   }
 
   function writeSourceFile(projectDir: string): void {
     const dir = path.join(projectDir, 'locales');
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, 'en.json'), JSON.stringify({
-      greeting: 'Hello',
-      farewell: 'Goodbye',
-    }, null, 2) + '\n');
+    fs.writeFileSync(
+      path.join(dir, 'en.json'),
+      JSON.stringify(
+        {
+          greeting: 'Hello',
+          farewell: 'Goodbye',
+        },
+        null,
+        2
+      ) + '\n'
+    );
   }
 
   function buildEnv(): Record<string, string | undefined> {
@@ -128,7 +152,10 @@ describe('CLI Sync E2E', () => {
     });
   }
 
-  function runSyncExpectError(args: string = ''): { status: number; output: string } {
+  function runSyncExpectError(args: string = ''): {
+    status: number;
+    output: string;
+  } {
     try {
       const output = execSync(`node ${CLI_PATH} sync ${args} 2>&1`, {
         encoding: 'utf-8',
@@ -139,10 +166,15 @@ describe('CLI Sync E2E', () => {
       });
       return { status: 0, output };
     } catch (error: unknown) {
-      const err = error as { status?: number; stderr?: string; stdout?: string };
+      const err = error as {
+        status?: number;
+        stderr?: string;
+        stdout?: string;
+      };
       return {
+        status: err.status ?? 1,
         // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional: empty stderr should fall through to stdout
-        status: err.status ?? 1, output: err.stderr?.toString() || err.stdout?.toString() || '',
+        output: err.stderr?.toString() || err.stdout?.toString() || '',
       };
     }
   }
@@ -244,7 +276,9 @@ describe('CLI Sync E2E', () => {
 
       const output = runSyncAll('--format json');
       // Extract the final pretty-printed JSON result (identified by the stable "ok" field)
-      const resultMatch = output.match(/\{[^{}]*"ok"[\s\S]*\}(?![\s\S]*\{[^{}]*"ok")/);
+      const resultMatch = output.match(
+        /\{[^{}]*"ok"[\s\S]*\}(?![\s\S]*\{[^{}]*"ok")/
+      );
       expect(resultMatch).not.toBeNull();
       const parsed = JSON.parse(resultMatch![0]) as Record<string, unknown>;
       expect(parsed).toHaveProperty('ok');
@@ -258,7 +292,9 @@ describe('CLI Sync E2E', () => {
     it('should fail without config file', () => {
       const result = runSyncExpectError();
       expect(result.status).toBeGreaterThan(0);
-      expect(result.output.toLowerCase()).toMatch(/config|\.deepl-sync\.yaml|init/);
+      expect(result.output.toLowerCase()).toMatch(
+        /config|\.deepl-sync\.yaml|init/
+      );
     });
 
     it('emits a parseable JSON error envelope to stderr when --format json and config is missing', () => {
@@ -330,7 +366,9 @@ describe('CLI Sync E2E', () => {
       runSyncAll();
 
       const output = runSyncAll('validate');
-      expect(output.toLowerCase()).toMatch(/checked|translation|validation|passed/);
+      expect(output.toLowerCase()).toMatch(
+        /checked|translation|validation|passed/
+      );
     });
   });
 
@@ -338,7 +376,9 @@ describe('CLI Sync E2E', () => {
     it('should generate working config for JSON format', () => {
       writeSourceFile(testFiles.path);
 
-      runSyncAll('init --source-locale en --target-locales de --file-format json --path "locales/en.json"');
+      runSyncAll(
+        'init --source-locale en --target-locales de --file-format json --path "locales/en.json"'
+      );
 
       const configPath = path.join(testFiles.path, '.deepl-sync.yaml');
       expect(fs.existsSync(configPath)).toBe(true);
@@ -362,7 +402,7 @@ describe('CLI Sync E2E', () => {
           stdio: ['ignore', 'pipe', 'pipe'],
           encoding: 'utf-8',
           timeout: 10000,
-        },
+        }
       );
 
       expect(result.status).toBe(6);
@@ -386,10 +426,14 @@ describe('CLI Sync E2E', () => {
           CLI_PATH,
           'sync',
           'init',
-          '--source-locale', 'en',
-          '--target-locales', 'de',
-          '--file-format', 'json',
-          '--path', 'locales/en.json',
+          '--source-locale',
+          'en',
+          '--target-locales',
+          'de',
+          '--file-format',
+          'json',
+          '--path',
+          'locales/en.json',
         ],
         {
           cwd: testFiles.path,
@@ -397,7 +441,7 @@ describe('CLI Sync E2E', () => {
           stdio: ['ignore', 'pipe', 'pipe'],
           encoding: 'utf-8',
           timeout: 10000,
-        },
+        }
       );
 
       expect(result.status).toBe(0);
@@ -405,18 +449,17 @@ describe('CLI Sync E2E', () => {
       expect(fs.existsSync(configPath)).toBe(true);
     });
 
-    function runInitFlags(args: string[]): { status: number | null; output: string } {
-      const result = spawnSync(
-        'node',
-        [CLI_PATH, 'sync', 'init', ...args],
-        {
-          cwd: testFiles.path,
-          env: buildEnv(),
-          stdio: ['ignore', 'pipe', 'pipe'],
-          encoding: 'utf-8',
-          timeout: 10000,
-        },
-      );
+    function runInitFlags(args: string[]): {
+      status: number | null;
+      output: string;
+    } {
+      const result = spawnSync('node', [CLI_PATH, 'sync', 'init', ...args], {
+        cwd: testFiles.path,
+        env: buildEnv(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+        timeout: 10000,
+      });
       return {
         status: result.status,
         output: `${result.stdout ?? ''}${result.stderr ?? ''}`,
@@ -427,10 +470,14 @@ describe('CLI Sync E2E', () => {
       writeSourceFile(testFiles.path);
 
       const result = runInitFlags([
-        '--source-locale', 'en',
-        '--target-locales', 'de,en,fr',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de,en,fr',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(result.status).toBe(6);
@@ -444,10 +491,14 @@ describe('CLI Sync E2E', () => {
       writeSourceFile(testFiles.path);
 
       const result = runInitFlags([
-        '--source-locale', 'en',
-        '--target-locales', 'de,fr,DE',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de,fr,DE',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(result.status).toBe(6);
@@ -460,14 +511,20 @@ describe('CLI Sync E2E', () => {
       writeSourceFile(testFiles.path);
 
       const result = runInitFlags([
-        '--source-locale', 'en',
-        '--target-locales', 'de,xx_YY',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de,xx_YY',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(result.status).toBe(6);
-      expect(result.output.toLowerCase()).toMatch(/locale|code|malformed|invalid/);
+      expect(result.output.toLowerCase()).toMatch(
+        /locale|code|malformed|invalid/
+      );
       const configPath = path.join(testFiles.path, '.deepl-sync.yaml');
       expect(fs.existsSync(configPath)).toBe(false);
     });
@@ -476,10 +533,14 @@ describe('CLI Sync E2E', () => {
       writeSourceFile(testFiles.path);
 
       const result = runInitFlags([
-        '--source-locale', 'en',
-        '--target-locales', 'de',
-        '--file-format', 'json',
-        '--path', '../etc/en.json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de',
+        '--file-format',
+        'json',
+        '--path',
+        '../etc/en.json',
       ]);
 
       expect(result.status).toBe(6);
@@ -490,10 +551,14 @@ describe('CLI Sync E2E', () => {
 
     it('warns (but succeeds) when --path does not yet exist', () => {
       const result = runInitFlags([
-        '--source-locale', 'en',
-        '--target-locales', 'de',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ]);
 
       expect(result.status).toBe(0);
@@ -507,25 +572,33 @@ describe('CLI Sync E2E', () => {
     it('should translate Android XML files using target_path_pattern', () => {
       const resDir = path.join(testFiles.path, 'res', 'values');
       fs.mkdirSync(resDir, { recursive: true });
-      fs.writeFileSync(path.join(resDir, 'strings.xml'),
-        '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n  <string name="greeting">Hello</string>\n</resources>\n');
+      fs.writeFileSync(
+        path.join(resDir, 'strings.xml'),
+        '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n  <string name="greeting">Hello</string>\n</resources>\n'
+      );
 
-      const yaml = [
-        'version: 1',
-        'source_locale: en',
-        'target_locales:',
-        '  - de',
-        'buckets:',
-        '  android_xml:',
-        '    include:',
-        '      - "res/values/strings.xml"',
-        '    target_path_pattern: "res/values-{locale}/strings.xml"',
-      ].join('\n') + '\n';
+      const yaml =
+        [
+          'version: 1',
+          'source_locale: en',
+          'target_locales:',
+          '  - de',
+          'buckets:',
+          '  android_xml:',
+          '    include:',
+          '      - "res/values/strings.xml"',
+          '    target_path_pattern: "res/values-{locale}/strings.xml"',
+        ].join('\n') + '\n';
       fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.yaml'), yaml);
 
       runSyncAll();
 
-      const targetFile = path.join(testFiles.path, 'res', 'values-de', 'strings.xml');
+      const targetFile = path.join(
+        testFiles.path,
+        'res',
+        'values-de',
+        'strings.xml'
+      );
       expect(fs.existsSync(targetFile)).toBe(true);
       const content = fs.readFileSync(targetFile, 'utf-8');
       expect(content).toContain('greeting');
@@ -534,35 +607,44 @@ describe('CLI Sync E2E', () => {
     it('should translate XLIFF files using target_path_pattern', () => {
       const localeDir = path.join(testFiles.path, 'src', 'locale');
       fs.mkdirSync(localeDir, { recursive: true });
-      fs.writeFileSync(path.join(localeDir, 'messages.xlf'), [
-        '<?xml version="1.0" encoding="UTF-8"?>',
-        '<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">',
-        '  <file source-language="en" target-language="" datatype="plaintext">',
-        '    <body>',
-        '      <trans-unit id="greeting">',
-        '        <source>Hello</source>',
-        '      </trans-unit>',
-        '    </body>',
-        '  </file>',
-        '</xliff>',
-      ].join('\n') + '\n');
-
-      const yaml = [
-        'version: 1',
-        'source_locale: en',
-        'target_locales:',
-        '  - de',
-        'buckets:',
-        '  xliff:',
-        '    include:',
-        '      - "src/locale/messages.xlf"',
-        '    target_path_pattern: "src/locale/messages.{locale}.xlf"',
-      ].join('\n') + '\n';
+      fs.writeFileSync(
+        path.join(localeDir, 'messages.xlf'),
+        [
+          '<?xml version="1.0" encoding="UTF-8"?>',
+          '<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">',
+          '  <file source-language="en" target-language="" datatype="plaintext">',
+          '    <body>',
+          '      <trans-unit id="greeting">',
+          '        <source>Hello</source>',
+          '      </trans-unit>',
+          '    </body>',
+          '  </file>',
+          '</xliff>',
+        ].join('\n') + '\n'
+      );
+
+      const yaml =
+        [
+          'version: 1',
+          'source_locale: en',
+          'target_locales:',
+          '  - de',
+          'buckets:',
+          '  xliff:',
+          '    include:',
+          '      - "src/locale/messages.xlf"',
+          '    target_path_pattern: "src/locale/messages.{locale}.xlf"',
+        ].join('\n') + '\n';
       fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.yaml'), yaml);
 
       runSyncAll();
 
-      const targetFile = path.join(testFiles.path, 'src', 'locale', 'messages.de.xlf');
+      const targetFile = path.join(
+        testFiles.path,
+        'src',
+        'locale',
+        'messages.de.xlf'
+      );
       expect(fs.existsSync(targetFile)).toBe(true);
       const content = fs.readFileSync(targetFile, 'utf-8');
       expect(content).toContain('greeting');
@@ -578,7 +660,10 @@ describe('CLI Sync E2E', () => {
 
       const targetFile = path.join(testFiles.path, 'locales', 'de.json');
       expect(fs.existsSync(targetFile)).toBe(true);
-      const parsed = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<string, string>;
+      const parsed = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<
+        string,
+        string
+      >;
       expect(parsed['greeting']).toBeDefined();
       expect(parsed['farewell']).toBeDefined();
 
@@ -589,7 +674,9 @@ describe('CLI Sync E2E', () => {
       runSyncAll('--no-batch');
 
       expect(fs.existsSync(targetFile)).toBe(true);
-      const parsed2 = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<string, string>;
+      const parsed2 = JSON.parse(
+        fs.readFileSync(targetFile, 'utf-8')
+      ) as Record<string, string>;
       expect(parsed2['greeting']).toBeDefined();
       expect(parsed2['farewell']).toBeDefined();
     });
@@ -600,16 +687,26 @@ describe('CLI Sync E2E', () => {
       writeSyncConfig(testFiles.path, ['de']);
       const dir = path.join(testFiles.path, 'locales');
       fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(path.join(dir, 'en.json'), JSON.stringify({
-        itemCount: '{count, plural, one {# item} other {# items}}',
-        greeting: 'Hello',
-      }, null, 2) + '\n');
+      fs.writeFileSync(
+        path.join(dir, 'en.json'),
+        JSON.stringify(
+          {
+            itemCount: '{count, plural, one {# item} other {# items}}',
+            greeting: 'Hello',
+          },
+          null,
+          2
+        ) + '\n'
+      );
 
       runSyncAll();
 
       const targetFile = path.join(testFiles.path, 'locales', 'de.json');
       expect(fs.existsSync(targetFile)).toBe(true);
-      const parsed = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<string, string>;
+      const parsed = JSON.parse(fs.readFileSync(targetFile, 'utf-8')) as Record<
+        string,
+        string
+      >;
 
       // ICU structure preserved: variable name, keyword, and branch selectors intact
       expect(parsed['itemCount']).toContain('{count, plural,');
@@ -641,16 +738,25 @@ describe('CLI Sync E2E', () => {
 
       const frFile = path.join(testFiles.path, 'locales', 'fr.json');
       expect(fs.existsSync(frFile)).toBe(true);
-      const frParsed = JSON.parse(fs.readFileSync(frFile, 'utf-8')) as Record<string, string>;
+      const frParsed = JSON.parse(fs.readFileSync(frFile, 'utf-8')) as Record<
+        string,
+        string
+      >;
       expect(frParsed['greeting']).toBeDefined();
       expect(frParsed['farewell']).toBeDefined();
 
       // Verify lock file has translations for both locales
-      const lockContent = JSON.parse(fs.readFileSync(
-        path.join(testFiles.path, '.deepl-sync.lock'), 'utf-8',
-      )) as Record<string, unknown>;
-      const entries = lockContent['entries'] as Record<string, Record<string, unknown>>;
-      const bucket = entries['locales/en.json'] as Record<string, Record<string, unknown>>;
+      const lockContent = JSON.parse(
+        fs.readFileSync(path.join(testFiles.path, '.deepl-sync.lock'), 'utf-8')
+      ) as Record<string, unknown>;
+      const entries = lockContent['entries'] as Record<
+        string,
+        Record<string, unknown>
+      >;
+      const bucket = entries['locales/en.json'] as Record<
+        string,
+        Record<string, unknown>
+      >;
       // Lock entries are keyed by i18n key, each with a translations object per locale
       const firstKey = Object.keys(bucket)[0]!;
       const keyEntry = bucket[firstKey] as Record<string, unknown>;
@@ -668,11 +774,11 @@ describe('CLI Sync E2E', () => {
       // Source has a placeholder; hand-written target drops it
       fs.writeFileSync(
         path.join(dir, 'en.json'),
-        JSON.stringify({ welcome: 'Hello {name}' }, null, 2) + '\n',
+        JSON.stringify({ welcome: 'Hello {name}' }, null, 2) + '\n'
       );
       fs.writeFileSync(
         path.join(dir, 'de.json'),
-        JSON.stringify({ welcome: 'Hallo' }, null, 2) + '\n',
+        JSON.stringify({ welcome: 'Hallo' }, null, 2) + '\n'
       );
 
       const result = runSyncExpectError('validate');
@@ -752,12 +858,18 @@ describe('CLI Sync E2E', () => {
         '  "stats": { "total_keys": 1, "total_translations": 1, "last_sync": "2026-04-18T12:00:00Z" }',
         '}',
       ].join('\n');
-      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.lock'), conflictedLock);
+      fs.writeFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        conflictedLock
+      );
 
       const output = runSyncAll('resolve');
       expect(output.toLowerCase()).toMatch(/resolv/);
 
-      const after = fs.readFileSync(path.join(testFiles.path, '.deepl-sync.lock'), 'utf-8');
+      const after = fs.readFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        'utf-8'
+      );
       expect(() => JSON.parse(after)).not.toThrow();
       expect(after).not.toContain('<<<<<<<');
       expect(after).not.toContain('=======');
@@ -768,8 +880,16 @@ describe('CLI Sync E2E', () => {
       writeSyncConfig(testFiles.path, ['de']);
       writeSourceFile(testFiles.path);
 
-      const ourEntry = { hash: 'a', translated_at: '2026-04-20T09:33:15Z', status: 'translated' };
-      const theirEntry = { hash: 'b', translated_at: '2026-04-20T08:12:03Z', status: 'translated' };
+      const ourEntry = {
+        hash: 'a',
+        translated_at: '2026-04-20T09:33:15Z',
+        status: 'translated',
+      };
+      const theirEntry = {
+        hash: 'b',
+        translated_at: '2026-04-20T08:12:03Z',
+        status: 'translated',
+      };
       const conflictedLock = [
         '{',
         '  "version": 1,',
@@ -787,7 +907,10 @@ describe('CLI Sync E2E', () => {
         '  "stats": { "total_keys": 1, "total_translations": 1, "last_sync": "2026-04-20T12:00:00Z" }',
         '}',
       ].join('\n');
-      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.lock'), conflictedLock);
+      fs.writeFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        conflictedLock
+      );
 
       const output = runSyncAll('resolve');
       expect(output).toMatch(/Resolved\s+.+:greeting/);
@@ -802,8 +925,16 @@ describe('CLI Sync E2E', () => {
       // Both halves end with a trailing comma, so the per-region JSON.parse
       // fails and the length heuristic kicks in; the following non-conflicted
       // entry keeps the merged document valid.
-      const ourEntry = { hash: 'a', translated_at: '2026-04-20T09:33:15Z', status: 'translated' };
-      const theirEntry = { hash: 'b', translated_at: '2026-04-20T08:12:03Z', status: 'translated' };
+      const ourEntry = {
+        hash: 'a',
+        translated_at: '2026-04-20T09:33:15Z',
+        status: 'translated',
+      };
+      const theirEntry = {
+        hash: 'b',
+        translated_at: '2026-04-20T08:12:03Z',
+        status: 'translated',
+      };
       const conflictedLock = [
         '{',
         '  "version": 1,',
@@ -822,7 +953,10 @@ describe('CLI Sync E2E', () => {
         '  "stats": { "total_keys": 2, "total_translations": 1, "last_sync": "2026-04-20T12:00:00Z" }',
         '}',
       ].join('\n');
-      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.lock'), conflictedLock);
+      fs.writeFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        conflictedLock
+      );
 
       const output = runSyncAll('resolve');
 
@@ -855,7 +989,10 @@ describe('CLI Sync E2E', () => {
         '  "stats": { "total_keys": 1, "total_translations": 1, "last_sync": "2026-04-20T12:00:00Z" }',
         '}',
       ].join('\n');
-      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.lock'), conflictedLock);
+      fs.writeFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        conflictedLock
+      );
 
       const result = runSyncExpectError('resolve');
       expect(result.status).toBe(11);
@@ -867,8 +1004,16 @@ describe('CLI Sync E2E', () => {
       writeSyncConfig(testFiles.path, ['de']);
       writeSourceFile(testFiles.path);
 
-      const ourEntry = { hash: 'a', translated_at: '2026-04-20T09:33:15Z', status: 'translated' };
-      const theirEntry = { hash: 'b', translated_at: '2026-04-20T08:12:03Z', status: 'translated' };
+      const ourEntry = {
+        hash: 'a',
+        translated_at: '2026-04-20T09:33:15Z',
+        status: 'translated',
+      };
+      const theirEntry = {
+        hash: 'b',
+        translated_at: '2026-04-20T08:12:03Z',
+        status: 'translated',
+      };
       const conflictedLock = [
         '{',
         '  "version": 1,',
@@ -925,23 +1070,39 @@ describe('CLI Sync E2E', () => {
       writeSyncConfig(testFiles.path, ['de']);
       writeSourceFile(testFiles.path);
 
-      const ourEntry = { hash: 'a', translated_at: '2026-04-20T09:33:15Z', status: 'translated' };
-      const theirEntry = { hash: 'b', translated_at: '2026-04-20T08:12:03Z', status: 'translated' };
+      const ourEntry = {
+        hash: 'a',
+        translated_at: '2026-04-20T09:33:15Z',
+        status: 'translated',
+      };
+      const theirEntry = {
+        hash: 'b',
+        translated_at: '2026-04-20T08:12:03Z',
+        status: 'translated',
+      };
       fs.writeFileSync(
         path.join(testFiles.path, '.deepl-sync.lock'),
-        makeConflictedLock(ourEntry, theirEntry),
+        makeConflictedLock(ourEntry, theirEntry)
       );
 
-      const result = spawnSync('node', [CLI_PATH, 'sync', 'resolve', '--format', 'json'], {
-        encoding: 'utf-8',
-        cwd: testFiles.path,
-        env: buildEnv(),
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: 15000,
-      });
+      const result = spawnSync(
+        'node',
+        [CLI_PATH, 'sync', 'resolve', '--format', 'json'],
+        {
+          encoding: 'utf-8',
+          cwd: testFiles.path,
+          env: buildEnv(),
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: 15000,
+        }
+      );
 
       expect(result.status).toBe(0);
-      const envelope = JSON.parse(result.stdout) as { ok: boolean; resolved: number; decisions: unknown[] };
+      const envelope = JSON.parse(result.stdout) as {
+        ok: boolean;
+        resolved: number;
+        decisions: unknown[];
+      };
       expect(envelope.ok).toBe(true);
       expect(typeof envelope.resolved).toBe('number');
       expect(envelope.resolved).toBeGreaterThan(0);
@@ -953,25 +1114,44 @@ describe('CLI Sync E2E', () => {
       writeSyncConfig(testFiles.path, ['de']);
       writeSourceFile(testFiles.path);
 
-      const cleanLock = JSON.stringify({
-        version: 1,
-        generated_at: '2026-04-20T12:00:00Z',
-        source_locale: 'en',
-        entries: {},
-        stats: { total_keys: 0, total_translations: 0, last_sync: '2026-04-20T12:00:00Z' },
-      }, null, 2);
-      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.lock'), cleanLock);
+      const cleanLock = JSON.stringify(
+        {
+          version: 1,
+          generated_at: '2026-04-20T12:00:00Z',
+          source_locale: 'en',
+          entries: {},
+          stats: {
+            total_keys: 0,
+            total_translations: 0,
+            last_sync: '2026-04-20T12:00:00Z',
+          },
+        },
+        null,
+        2
+      );
+      fs.writeFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        cleanLock
+      );
 
-      const result = spawnSync('node', [CLI_PATH, 'sync', 'resolve', '--format', 'json'], {
-        encoding: 'utf-8',
-        cwd: testFiles.path,
-        env: buildEnv(),
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: 15000,
-      });
+      const result = spawnSync(
+        'node',
+        [CLI_PATH, 'sync', 'resolve', '--format', 'json'],
+        {
+          encoding: 'utf-8',
+          cwd: testFiles.path,
+          env: buildEnv(),
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: 15000,
+        }
+      );
 
       expect(result.status).toBe(0);
-      const envelope = JSON.parse(result.stdout) as { ok: boolean; resolved: number; decisions: unknown[] };
+      const envelope = JSON.parse(result.stdout) as {
+        ok: boolean;
+        resolved: number;
+        decisions: unknown[];
+      };
       expect(envelope.ok).toBe(true);
       expect(envelope.resolved).toBe(0);
       expect(envelope.decisions).toEqual([]);
@@ -1029,13 +1209,25 @@ describe('CLI Sync E2E', () => {
       // it two different German translations — a real inconsistency.
       const sourceDir = path.join(testFiles.path, 'locales', 'en');
       fs.mkdirSync(sourceDir, { recursive: true });
-      fs.writeFileSync(path.join(sourceDir, 'common.json'), JSON.stringify({ greeting: 'Dashboard' }, null, 2));
-      fs.writeFileSync(path.join(sourceDir, 'admin.json'), JSON.stringify({ header: 'Dashboard' }, null, 2));
+      fs.writeFileSync(
+        path.join(sourceDir, 'common.json'),
+        JSON.stringify({ greeting: 'Dashboard' }, null, 2)
+      );
+      fs.writeFileSync(
+        path.join(sourceDir, 'admin.json'),
+        JSON.stringify({ header: 'Dashboard' }, null, 2)
+      );
 
       const targetDir = path.join(testFiles.path, 'locales', 'de');
       fs.mkdirSync(targetDir, { recursive: true });
-      fs.writeFileSync(path.join(targetDir, 'common.json'), JSON.stringify({ greeting: 'Armaturenbrett' }, null, 2));
-      fs.writeFileSync(path.join(targetDir, 'admin.json'), JSON.stringify({ header: 'Dashboard' }, null, 2));
+      fs.writeFileSync(
+        path.join(targetDir, 'common.json'),
+        JSON.stringify({ greeting: 'Armaturenbrett' }, null, 2)
+      );
+      fs.writeFileSync(
+        path.join(targetDir, 'admin.json'),
+        JSON.stringify({ header: 'Dashboard' }, null, 2)
+      );
 
       fs.writeFileSync(
         path.join(testFiles.path, '.deepl-sync.yaml'),
@@ -1049,7 +1241,7 @@ describe('CLI Sync E2E', () => {
           '    include:',
           '      - "locales/en/*.json"',
           '',
-        ].join('\n'),
+        ].join('\n')
       );
 
       // Pre-seed lockfile with divergent translation hashes (different content hashes
@@ -1065,7 +1257,11 @@ describe('CLI Sync E2E', () => {
               source_hash: 'sh',
               source_text: 'Dashboard',
               translations: {
-                de: { hash: 'de-hash-a', translated_at: '2026-04-19T00:00:00Z', status: 'translated' },
+                de: {
+                  hash: 'de-hash-a',
+                  translated_at: '2026-04-19T00:00:00Z',
+                  status: 'translated',
+                },
               },
             },
           },
@@ -1074,21 +1270,37 @@ describe('CLI Sync E2E', () => {
               source_hash: 'sh',
               source_text: 'Dashboard',
               translations: {
-                de: { hash: 'de-hash-b', translated_at: '2026-04-19T00:00:00Z', status: 'translated' },
+                de: {
+                  hash: 'de-hash-b',
+                  translated_at: '2026-04-19T00:00:00Z',
+                  status: 'translated',
+                },
               },
             },
           },
         },
-        stats: { total_keys: 2, total_translations: 2, last_sync: '2026-04-19T00:00:00Z' },
+        stats: {
+          total_keys: 2,
+          total_translations: 2,
+          last_sync: '2026-04-19T00:00:00Z',
+        },
       };
-      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.lock'), JSON.stringify(lockContent, null, 2));
+      fs.writeFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        JSON.stringify(lockContent, null, 2)
+      );
 
       const output = runSyncAll('audit --format json');
       const jsonMatch = output.match(/\{[\s\S]*\}/);
       expect(jsonMatch).not.toBeNull();
       const parsed = JSON.parse(jsonMatch![0]) as {
         totalTerms: number;
-        inconsistencies: Array<{ sourceText: string; locale: string; translations: string[]; files: string[] }>;
+        inconsistencies: Array<{
+          sourceText: string;
+          locale: string;
+          translations: string[];
+          files: string[];
+        }>;
       };
 
       expect(parsed.totalTerms).toBe(1);
@@ -1097,7 +1309,9 @@ describe('CLI Sync E2E', () => {
       expect(inc.sourceText).toBe('Dashboard');
       expect(inc.locale).toBe('de');
       // Critical: must be real translated strings, not SHA hashes.
-      expect(inc.translations).toEqual(expect.arrayContaining(['Armaturenbrett', 'Dashboard']));
+      expect(inc.translations).toEqual(
+        expect.arrayContaining(['Armaturenbrett', 'Dashboard'])
+      );
       expect(inc.translations).not.toContain('de-hash-a');
       expect(inc.translations).not.toContain('de-hash-b');
 
@@ -1108,13 +1322,22 @@ describe('CLI Sync E2E', () => {
     it('reports a not-yet-created locale file as missing instead of an inconsistency', () => {
       const sourceDir = path.join(testFiles.path, 'locales', 'en');
       fs.mkdirSync(sourceDir, { recursive: true });
-      fs.writeFileSync(path.join(sourceDir, 'common.json'), JSON.stringify({ greeting: 'Dashboard' }, null, 2));
-      fs.writeFileSync(path.join(sourceDir, 'admin.json'), JSON.stringify({ header: 'Dashboard' }, null, 2));
+      fs.writeFileSync(
+        path.join(sourceDir, 'common.json'),
+        JSON.stringify({ greeting: 'Dashboard' }, null, 2)
+      );
+      fs.writeFileSync(
+        path.join(sourceDir, 'admin.json'),
+        JSON.stringify({ header: 'Dashboard' }, null, 2)
+      );
 
       // Only one of the two German files exists yet.
       const targetDir = path.join(testFiles.path, 'locales', 'de');
       fs.mkdirSync(targetDir, { recursive: true });
-      fs.writeFileSync(path.join(targetDir, 'common.json'), JSON.stringify({ greeting: 'Armaturenbrett' }, null, 2));
+      fs.writeFileSync(
+        path.join(targetDir, 'common.json'),
+        JSON.stringify({ greeting: 'Armaturenbrett' }, null, 2)
+      );
 
       fs.writeFileSync(
         path.join(testFiles.path, '.deepl-sync.yaml'),
@@ -1128,7 +1351,7 @@ describe('CLI Sync E2E', () => {
           '    include:',
           '      - "locales/en/*.json"',
           '',
-        ].join('\n'),
+        ].join('\n')
       );
 
       const lockContent = {
@@ -1142,7 +1365,11 @@ describe('CLI Sync E2E', () => {
               source_hash: 'sh',
               source_text: 'Dashboard',
               translations: {
-                de: { hash: 'de-hash-a', translated_at: '2026-04-19T00:00:00Z', status: 'translated' },
+                de: {
+                  hash: 'de-hash-a',
+                  translated_at: '2026-04-19T00:00:00Z',
+                  status: 'translated',
+                },
               },
             },
           },
@@ -1151,14 +1378,25 @@ describe('CLI Sync E2E', () => {
               source_hash: 'sh',
               source_text: 'Dashboard',
               translations: {
-                de: { hash: 'de-hash-a', translated_at: '2026-04-19T00:00:00Z', status: 'translated' },
+                de: {
+                  hash: 'de-hash-a',
+                  translated_at: '2026-04-19T00:00:00Z',
+                  status: 'translated',
+                },
               },
             },
           },
         },
-        stats: { total_keys: 2, total_translations: 2, last_sync: '2026-04-19T00:00:00Z' },
+        stats: {
+          total_keys: 2,
+          total_translations: 2,
+          last_sync: '2026-04-19T00:00:00Z',
+        },
       };
-      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.lock'), JSON.stringify(lockContent, null, 2));
+      fs.writeFileSync(
+        path.join(testFiles.path, '.deepl-sync.lock'),
+        JSON.stringify(lockContent, null, 2)
+      );
 
       const output = runSyncAll('audit --format json');
       const jsonMatch = output.match(/\{[\s\S]*\}/);
@@ -1192,17 +1430,27 @@ describe('CLI Sync E2E', () => {
     it('rejects --output paths that escape the project root', () => {
       const result = runSyncExpectError('export --output ../../etc/evil.xlf');
       expect(result.status).not.toBe(0);
-      expect(result.output.toLowerCase()).toMatch(/escapes project root|outside/i);
-      expect(fs.existsSync(path.join(testFiles.path, '..', '..', 'etc', 'evil.xlf'))).toBe(false);
+      expect(result.output.toLowerCase()).toMatch(
+        /escapes project root|outside/i
+      );
+      expect(
+        fs.existsSync(path.join(testFiles.path, '..', '..', 'etc', 'evil.xlf'))
+      ).toBe(false);
     });
 
     it('refuses to overwrite an existing output file without --overwrite', () => {
       const outputPath = path.join(testFiles.path, 'preexisting.xlf');
-      fs.writeFileSync(outputPath, 'existing content — do not clobber', 'utf-8');
+      fs.writeFileSync(
+        outputPath,
+        'existing content — do not clobber',
+        'utf-8'
+      );
 
       const result = runSyncExpectError('export --output preexisting.xlf');
       expect(result.status).not.toBe(0);
-      expect(result.output.toLowerCase()).toMatch(/refusing to overwrite|--overwrite/);
+      expect(result.output.toLowerCase()).toMatch(
+        /refusing to overwrite|--overwrite/
+      );
 
       const preserved = fs.readFileSync(outputPath, 'utf-8');
       expect(preserved).toBe('existing content — do not clobber');
@@ -1234,7 +1482,10 @@ describe('CLI Sync E2E', () => {
       const content = fs.readFileSync(absNested, 'utf-8');
       expect(content.startsWith('<?xml')).toBe(true);
 
-      fs.rmSync(path.join(testFiles.path, 'reports'), { recursive: true, force: true });
+      fs.rmSync(path.join(testFiles.path, 'reports'), {
+        recursive: true,
+        force: true,
+      });
     });
   });
 });
diff --git a/tests/e2e/cli-voice.e2e.test.ts b/tests/e2e/cli-voice.e2e.test.ts
index 3bbc464c..5ddee6f2 100644
--- a/tests/e2e/cli-voice.e2e.test.ts
+++ b/tests/e2e/cli-voice.e2e.test.ts
@@ -77,18 +77,28 @@ describe('Voice CLI E2E', () => {
       const testFile = path.join(testDir, 'exit-code-nokey.mp3');
       fs.writeFileSync(testFile, Buffer.alloc(100));
 
-      const cleanEnv: Record<string, string | undefined> = { ...process.env, DEEPL_CONFIG_DIR: testConfig.path };
+      const cleanEnv: Record<string, string | undefined> = {
+        ...process.env,
+        DEEPL_CONFIG_DIR: testConfig.path,
+      };
       delete cleanEnv['DEEPL_API_KEY'];
 
       try {
-        execSync('deepl auth clear', { encoding: 'utf-8', env: cleanEnv, stdio: 'pipe' });
+        execSync('deepl auth clear', {
+          encoding: 'utf-8',
+          env: cleanEnv,
+          stdio: 'pipe',
+        });
       } catch {
         // Ignore
       }
 
       expect.assertions(1);
       try {
-        execSync(`deepl voice ${testFile} --to de`, { encoding: 'utf-8', env: cleanEnv });
+        execSync(`deepl voice ${testFile} --to de`, {
+          encoding: 'utf-8',
+          env: cleanEnv,
+        });
         throw new Error('Should have thrown');
       } catch (error: any) {
         expect(error.status).toBeGreaterThan(0);
@@ -110,7 +120,7 @@ describe('Voice CLI E2E', () => {
         JSON.stringify({
           auth: { apiKey: 'mock-api-key-for-testing:fx' },
           api: { baseUrl: 'http://127.0.0.1:9/v2', usePro: false },
-        }),
+        })
       );
     });
 
@@ -123,7 +133,7 @@ describe('Voice CLI E2E', () => {
       fs.writeFileSync(testFile, Buffer.alloc(100));
 
       const result = orderCLI.runCLIExpectError(
-        `deepl voice ${testFile} --to bogus --glossary my-glossary`,
+        `deepl voice ${testFile} --to bogus --glossary my-glossary`
       );
 
       expect(result.status).toBe(6);
@@ -136,7 +146,7 @@ describe('Voice CLI E2E', () => {
       fs.writeFileSync(testFile, Buffer.alloc(100));
 
       const result = orderCLI.runCLIExpectError(
-        `deepl voice ${testFile} --to de --content-type audio/wav --glossary my-glossary`,
+        `deepl voice ${testFile} --to de --content-type audio/wav --glossary my-glossary`
       );
 
       expect(result.status).toBe(6);
@@ -150,7 +160,10 @@ describe('Voice CLI E2E', () => {
       const testFile = path.join(testDir, 'error-msg-test.mp3');
       fs.writeFileSync(testFile, Buffer.alloc(100));
 
-      const cleanEnv: Record<string, string | undefined> = { ...process.env, DEEPL_CONFIG_DIR: testConfig.path };
+      const cleanEnv: Record<string, string | undefined> = {
+        ...process.env,
+        DEEPL_CONFIG_DIR: testConfig.path,
+      };
       delete cleanEnv['DEEPL_API_KEY'];
 
       try {
@@ -197,7 +210,10 @@ describe('Voice CLI E2E', () => {
       const testFile = path.join(testDir, 'format-text.mp3');
       fs.writeFileSync(testFile, Buffer.alloc(100));
 
-      const cleanEnv: Record<string, string | undefined> = { ...process.env, DEEPL_CONFIG_DIR: testConfig.path };
+      const cleanEnv: Record<string, string | undefined> = {
+        ...process.env,
+        DEEPL_CONFIG_DIR: testConfig.path,
+      };
       delete cleanEnv['DEEPL_API_KEY'];
 
       expect.assertions(1);
@@ -219,7 +235,10 @@ describe('Voice CLI E2E', () => {
       const testFile = path.join(testDir, 'format-json.mp3');
       fs.writeFileSync(testFile, Buffer.alloc(100));
 
-      const cleanEnv: Record<string, string | undefined> = { ...process.env, DEEPL_CONFIG_DIR: testConfig.path };
+      const cleanEnv: Record<string, string | undefined> = {
+        ...process.env,
+        DEEPL_CONFIG_DIR: testConfig.path,
+      };
       delete cleanEnv['DEEPL_API_KEY'];
 
       expect.assertions(1);
diff --git a/tests/e2e/cli-watch.e2e.test.ts b/tests/e2e/cli-watch.e2e.test.ts
index 989b709b..1216de96 100644
--- a/tests/e2e/cli-watch.e2e.test.ts
+++ b/tests/e2e/cli-watch.e2e.test.ts
@@ -89,15 +89,24 @@ describe('Watch Command E2E', () => {
      * as far as resolving the glossary name would fail on the network instead.
      */
     function deadUrlConfigDir(): string {
-      const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-config-'));
-      fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify({
-        auth: { apiKey: 'e2e-watch-glossary-key:fx' },
-        api: { baseUrl: 'http://127.0.0.1:9', usePro: false },
-        defaults: { formality: 'default', preserveFormatting: true },
-        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
-        output: { format: 'text', verbose: false, color: false },
-        watch: { debounceMs: 500, autoCommit: false },
-      }, null, 2));
+      const configDir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-watch-config-')
+      );
+      fs.writeFileSync(
+        path.join(configDir, 'config.json'),
+        JSON.stringify(
+          {
+            auth: { apiKey: 'e2e-watch-glossary-key:fx' },
+            api: { baseUrl: 'http://127.0.0.1:9', usePro: false },
+            defaults: { formality: 'default', preserveFormatting: true },
+            cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+            output: { format: 'text', verbose: false, color: false },
+            watch: { debounceMs: 500, autoCommit: false },
+          },
+          null,
+          2
+        )
+      );
       return configDir;
     }
 
@@ -110,11 +119,13 @@ describe('Watch Command E2E', () => {
       try {
         const { status, output } = runCLIExpectError(
           `watch ${tmpDir} --to es --glossary my-glossary`,
-          { timeout: 20000 },
+          { timeout: 20000 }
         );
 
         expect(status).toBe(6);
-        expect(output).toContain('Source language (--from) is required when using a glossary');
+        expect(output).toContain(
+          'Source language (--from) is required when using a glossary'
+        );
         expect(output).not.toContain('Watching for changes');
       } finally {
         fs.rmSync(tmpDir, { recursive: true, force: true });
@@ -131,7 +142,7 @@ describe('Watch Command E2E', () => {
       try {
         const { status, output } = runCLIExpectError(
           `watch ${tmpDir} --from en --to es --glossary my-glossary`,
-          { timeout: 20000 },
+          { timeout: 20000 }
         );
 
         expect(output).not.toContain('Source language (--from) is required');
@@ -158,7 +169,9 @@ describe('Watch Command E2E', () => {
       const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-e2e-'));
       const { runCLIExpectError } = makeNodeRunCLI(testConfig.path);
       try {
-        const { status, output } = runCLIExpectError(`watch ${tmpDir} --dry-run`);
+        const { status, output } = runCLIExpectError(
+          `watch ${tmpDir} --dry-run`
+        );
         expect(status).toBeGreaterThan(0);
         expect(output).toContain('No target language specified.');
         expect(output).toContain('deepl init');
@@ -172,14 +185,23 @@ describe('Watch Command E2E', () => {
       const configWithDefaults = {
         auth: { apiKey: 'test-key:fx' },
         api: { baseUrl: 'https://api-free.deepl.com', usePro: false },
-        defaults: { targetLangs: ['es', 'fr'], formality: 'default', preserveFormatting: true },
+        defaults: {
+          targetLangs: ['es', 'fr'],
+          formality: 'default',
+          preserveFormatting: true,
+        },
         cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
         output: { format: 'text', verbose: false, color: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
       };
 
-      const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-config-'));
-      fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(configWithDefaults, null, 2));
+      const configDir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-watch-config-')
+      );
+      fs.writeFileSync(
+        path.join(configDir, 'config.json'),
+        JSON.stringify(configWithDefaults, null, 2)
+      );
       fs.writeFileSync(path.join(tmpDir, 'test.md'), 'Hello');
 
       const { runCLI: runWithConfig } = makeNodeRunCLI(configDir);
diff --git a/tests/e2e/cli-workflow.e2e.test.ts b/tests/e2e/cli-workflow.e2e.test.ts
index bbf07966..cc83a7d9 100644
--- a/tests/e2e/cli-workflow.e2e.test.ts
+++ b/tests/e2e/cli-workflow.e2e.test.ts
@@ -274,7 +274,7 @@ describe('CLI Workflow E2E', () => {
       expect.assertions(3);
       const result = runCLIExpectError(
         'deepl translate "Hi" --to de --tm-threshold 80abc',
-        { stdio: 'pipe' },
+        { stdio: 'pipe' }
       );
       expect(result.status).toBe(6);
       expect(result.output).toContain('--tm-threshold must be an integer');
diff --git a/tests/e2e/cli-write.e2e.test.ts b/tests/e2e/cli-write.e2e.test.ts
index fada6d97..aca5a705 100644
--- a/tests/e2e/cli-write.e2e.test.ts
+++ b/tests/e2e/cli-write.e2e.test.ts
@@ -39,7 +39,10 @@ describe('Write Command E2E', () => {
     it('should accept write without --lang flag (auto-detect)', () => {
       expect.assertions(1);
       try {
-        execSync('deepl write "test text"', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl write "test text"', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         // May fail on API key, but should NOT fail on missing --lang (exit code 1)
         expect(error.status).not.toBe(1);
@@ -49,7 +52,10 @@ describe('Write Command E2E', () => {
     it('should reject invalid language code', () => {
       expect.assertions(1);
       try {
-        execSync('deepl write "test" --lang invalid', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl write "test" --lang invalid', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         // Exit code 6 = InvalidInput (validation error)
         expect(error.status).toBe(6);
@@ -59,7 +65,10 @@ describe('Write Command E2E', () => {
     it('should accept --lang ja without validation error', () => {
       expect.assertions(1);
       try {
-        execSync('deepl write "test" --lang ja', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl write "test" --lang ja', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         expect(error.status).not.toBe(6);
       }
@@ -68,7 +77,10 @@ describe('Write Command E2E', () => {
     it('should accept --lang ko without validation error', () => {
       expect.assertions(1);
       try {
-        execSync('deepl write "test" --lang ko', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl write "test" --lang ko', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         expect(error.status).not.toBe(6);
       }
@@ -77,7 +89,10 @@ describe('Write Command E2E', () => {
     it('should accept --lang zh without validation error', () => {
       expect.assertions(1);
       try {
-        execSync('deepl write "test" --lang zh', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl write "test" --lang zh', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         expect(error.status).not.toBe(6);
       }
@@ -86,7 +101,10 @@ describe('Write Command E2E', () => {
     it('should accept --lang zh-Hans without validation error', () => {
       expect.assertions(1);
       try {
-        execSync('deepl write "test" --lang zh-Hans', { encoding: 'utf-8', stdio: 'pipe' });
+        execSync('deepl write "test" --lang zh-Hans', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         expect(error.status).not.toBe(6);
       }
@@ -95,10 +113,13 @@ describe('Write Command E2E', () => {
     it('should reject combining --style and --tone', () => {
       expect.assertions(1);
       try {
-        execSync('deepl write "test" --lang en-US --style business --tone confident', {
-          encoding: 'utf-8',
-          stdio: 'pipe'
-        });
+        execSync(
+          'deepl write "test" --lang en-US --style business --tone confident',
+          {
+            encoding: 'utf-8',
+            stdio: 'pipe',
+          }
+        );
       } catch (error: any) {
         // Exit code 6 = InvalidInput (validation error - "Cannot specify both")
         expect(error.status).toBe(6);
@@ -121,7 +142,10 @@ describe('Write Command E2E', () => {
       // This will fail without API key, but should recognize it as a file operation
       expect.assertions(1);
       try {
-        execSync(`deepl write "${testFile}" --lang en-US`, { encoding: 'utf-8', stdio: 'pipe' });
+        execSync(`deepl write "${testFile}" --lang en-US`, {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         // Expected to fail without API key, but should not error on file path recognition
         const stderr = error.stderr?.toString() ?? '';
diff --git a/tests/global-setup.ts b/tests/global-setup.ts
index d7c985e2..2b118f02 100644
--- a/tests/global-setup.ts
+++ b/tests/global-setup.ts
@@ -1,4 +1,6 @@
-import installHermeticDeepl, { isolateCredentialEnvironment } from './hermetic-deepl';
+import installHermeticDeepl, {
+  isolateCredentialEnvironment,
+} from './hermetic-deepl';
 
 /**
  * Runs in the main jest process before workers spawn, so the shim's PATH entry
diff --git a/tests/helpers/assert-error-envelope.ts b/tests/helpers/assert-error-envelope.ts
index abf60393..84692bff 100644
--- a/tests/helpers/assert-error-envelope.ts
+++ b/tests/helpers/assert-error-envelope.ts
@@ -50,29 +50,30 @@ export interface SyncInitJsonSuccessEnvelope {
   };
 }
 
-export const INIT_SUCCESS_ENVELOPE_SCHEMA: JSONSchemaType<SyncInitJsonSuccessEnvelope> = {
-  type: 'object',
-  additionalProperties: false,
-  required: ['ok', 'created'],
-  properties: {
-    ok: { type: 'boolean', const: true },
-    created: {
-      type: 'object',
-      additionalProperties: false,
-      required: ['configPath', 'sourceLocale', 'targetLocales'],
-      properties: {
-        configPath: { type: 'string', minLength: 1 },
-        sourceLocale: { type: 'string', minLength: 1 },
-        targetLocales: {
-          type: 'array',
-          items: { type: 'string', minLength: 1 },
-          minItems: 1,
+export const INIT_SUCCESS_ENVELOPE_SCHEMA: JSONSchemaType<SyncInitJsonSuccessEnvelope> =
+  {
+    type: 'object',
+    additionalProperties: false,
+    required: ['ok', 'created'],
+    properties: {
+      ok: { type: 'boolean', const: true },
+      created: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['configPath', 'sourceLocale', 'targetLocales'],
+        properties: {
+          configPath: { type: 'string', minLength: 1 },
+          sourceLocale: { type: 'string', minLength: 1 },
+          targetLocales: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 },
+            minItems: 1,
+          },
+          keys: { type: 'integer', minimum: 0, nullable: true },
         },
-        keys: { type: 'integer', minimum: 0, nullable: true },
       },
     },
-  },
-};
+  };
 
 // AJV v8 default export is a class under the CJS type shim; treat both shapes
 // so jest-via-ts-jest and runtime both resolve. In practice ts-jest sees the
@@ -93,12 +94,12 @@ const validateInitSuccess = ajv.compile(INIT_SUCCESS_ENVELOPE_SCHEMA);
 export function assertErrorEnvelope(
   stderr: string,
   expectedCode: string,
-  expectedExitCode: number,
+  expectedExitCode: number
 ): SyncJsonErrorEnvelope {
   const match = stderr.trim().match(/\{[\s\S]*\}\s*$/);
   if (!match) {
     throw new Error(
-      `No trailing JSON object found in stderr. stderr was:\n${stderr}`,
+      `No trailing JSON object found in stderr. stderr was:\n${stderr}`
     );
   }
 
@@ -108,24 +109,24 @@ export function assertErrorEnvelope(
   } catch (err) {
     throw new Error(
       `stderr trailing JSON is not parseable: ${(err as Error).message}\nPayload: ${match[0]}`,
-      { cause: err },
+      { cause: err }
     );
   }
 
   if (!validateError(parsed)) {
     throw new Error(
-      `Envelope failed AJV validation:\n${ajv.errorsText(validateError.errors)}\nPayload: ${JSON.stringify(parsed)}`,
+      `Envelope failed AJV validation:\n${ajv.errorsText(validateError.errors)}\nPayload: ${JSON.stringify(parsed)}`
     );
   }
 
   if (parsed.error.code !== expectedCode) {
     throw new Error(
-      `Envelope error.code = "${parsed.error.code}", expected "${expectedCode}". Payload: ${JSON.stringify(parsed)}`,
+      `Envelope error.code = "${parsed.error.code}", expected "${expectedCode}". Payload: ${JSON.stringify(parsed)}`
     );
   }
   if (parsed.exitCode !== expectedExitCode) {
     throw new Error(
-      `Envelope exitCode = ${parsed.exitCode}, expected ${expectedExitCode}. Payload: ${JSON.stringify(parsed)}`,
+      `Envelope exitCode = ${parsed.exitCode}, expected ${expectedExitCode}. Payload: ${JSON.stringify(parsed)}`
     );
   }
   return parsed;
@@ -136,11 +137,13 @@ export function assertErrorEnvelope(
  * the error envelope because `init` is the only subcommand with a dedicated
  * machine-readable success payload today.
  */
-export function assertInitSuccessEnvelope(stdout: string): SyncInitJsonSuccessEnvelope {
+export function assertInitSuccessEnvelope(
+  stdout: string
+): SyncInitJsonSuccessEnvelope {
   const match = stdout.trim().match(/\{[\s\S]*\}\s*$/);
   if (!match) {
     throw new Error(
-      `No trailing JSON object found in stdout. stdout was:\n${stdout}`,
+      `No trailing JSON object found in stdout. stdout was:\n${stdout}`
     );
   }
 
@@ -150,13 +153,13 @@ export function assertInitSuccessEnvelope(stdout: string): SyncInitJsonSuccessEn
   } catch (err) {
     throw new Error(
       `stdout trailing JSON is not parseable: ${(err as Error).message}\nPayload: ${match[0]}`,
-      { cause: err },
+      { cause: err }
     );
   }
 
   if (!validateInitSuccess(parsed)) {
     throw new Error(
-      `Init success envelope failed AJV validation:\n${ajv.errorsText(validateInitSuccess.errors)}\nPayload: ${JSON.stringify(parsed)}`,
+      `Init success envelope failed AJV validation:\n${ajv.errorsText(validateInitSuccess.errors)}\nPayload: ${JSON.stringify(parsed)}`
     );
   }
   return parsed;
diff --git a/tests/helpers/mock-factories.ts b/tests/helpers/mock-factories.ts
index 8e8a265c..7a36ac04 100644
--- a/tests/helpers/mock-factories.ts
+++ b/tests/helpers/mock-factories.ts
@@ -31,7 +31,9 @@ import type { CacheService } from '../../src/storage/cache';
 // Helper type: picks only function-typed keys from T
 // ---------------------------------------------------------------------------
 type MockShape<T> = {
-  [K in keyof T as T[K] extends (...args: never[]) => unknown ? K : never]: jest.Mock;
+  [
+    K in keyof T as T[K] extends (...args: never[]) => unknown ? K : never
+  ]: jest.Mock;
 };
 
 // ---------------------------------------------------------------------------
@@ -45,8 +47,8 @@ function unconfiguredAsync(methodName: string): jest.Mock {
     return Promise.reject(
       new Error(
         `mock: ${methodName} was called without an explicit override. ` +
-          `Supply a mockResolvedValue or factory override so the assertion is non-vacuous.`,
-      ),
+          `Supply a mockResolvedValue or factory override so the assertion is non-vacuous.`
+      )
     );
   });
 }
@@ -58,7 +60,9 @@ function deepLClientDefaults(): MockShape<DeepLClient> {
   return {
     translate: unconfiguredAsync('DeepLClient.translate'),
     translateBatch: unconfiguredAsync('DeepLClient.translateBatch'),
-    getUsage: jest.fn().mockResolvedValue({ character: { count: 0, limit: 0 } }),
+    getUsage: jest
+      .fn()
+      .mockResolvedValue({ character: { count: 0, limit: 0 } }),
     getSupportedLanguages: jest.fn().mockResolvedValue([]),
     listTranslationMemories: jest.fn().mockResolvedValue([]),
     getGlossaryLanguages: jest.fn().mockResolvedValue([]),
@@ -72,54 +76,94 @@ function deepLClientDefaults(): MockShape<DeepLClient> {
     updateGlossary: jest.fn().mockResolvedValue(undefined),
     renameGlossary: jest.fn().mockResolvedValue(undefined),
     deleteGlossaryDictionary: jest.fn().mockResolvedValue(undefined),
-    uploadDocument: jest.fn().mockResolvedValue({ documentId: '', documentKey: '' }),
+    uploadDocument: jest
+      .fn()
+      .mockResolvedValue({ documentId: '', documentKey: '' }),
     getDocumentStatus: jest.fn().mockResolvedValue({ status: 'done' }),
     downloadDocument: jest.fn().mockResolvedValue(Buffer.alloc(0)),
     improveText: jest.fn().mockResolvedValue([]),
     correctText: jest.fn().mockResolvedValue([]),
     getStyleRules: jest.fn().mockResolvedValue([]),
     createStyleRule: jest.fn().mockResolvedValue({
-      styleId: 'mock-id', name: 'mock', language: 'en', version: 1,
-      creationTime: 'c', updatedTime: 'u',
+      styleId: 'mock-id',
+      name: 'mock',
+      language: 'en',
+      version: 1,
+      creationTime: 'c',
+      updatedTime: 'u',
     }),
     getStyleRule: jest.fn().mockResolvedValue({
-      styleId: 'mock-id', name: 'mock', language: 'en', version: 1,
-      creationTime: 'c', updatedTime: 'u',
+      styleId: 'mock-id',
+      name: 'mock',
+      language: 'en',
+      version: 1,
+      creationTime: 'c',
+      updatedTime: 'u',
     }),
     updateStyleRule: jest.fn().mockResolvedValue({
-      styleId: 'mock-id', name: 'mock', language: 'en', version: 2,
-      creationTime: 'c', updatedTime: 'u',
+      styleId: 'mock-id',
+      name: 'mock',
+      language: 'en',
+      version: 2,
+      creationTime: 'c',
+      updatedTime: 'u',
     }),
     deleteStyleRule: jest.fn().mockResolvedValue(undefined),
     replaceConfiguredRules: jest.fn().mockResolvedValue({
-      styleId: 'mock-id', name: 'mock', language: 'en', version: 2,
-      creationTime: 'c', updatedTime: 'u',
-      configuredRules: {}, customInstructions: [],
+      styleId: 'mock-id',
+      name: 'mock',
+      language: 'en',
+      version: 2,
+      creationTime: 'c',
+      updatedTime: 'u',
+      configuredRules: {},
+      customInstructions: [],
     }),
-    createCustomInstruction: jest.fn().mockResolvedValue({ label: 'mock', prompt: 'mock' }),
-    getCustomInstruction: jest.fn().mockResolvedValue({ label: 'mock', prompt: 'mock' }),
-    updateCustomInstruction: jest.fn().mockResolvedValue({ label: 'mock', prompt: 'mock' }),
+    createCustomInstruction: jest
+      .fn()
+      .mockResolvedValue({ label: 'mock', prompt: 'mock' }),
+    getCustomInstruction: jest
+      .fn()
+      .mockResolvedValue({ label: 'mock', prompt: 'mock' }),
+    updateCustomInstruction: jest
+      .fn()
+      .mockResolvedValue({ label: 'mock', prompt: 'mock' }),
     deleteCustomInstruction: jest.fn().mockResolvedValue(undefined),
     listApiKeys: jest.fn().mockResolvedValue([]),
-    createApiKey: jest.fn().mockResolvedValue({ keyId: '', label: '', creationTime: '', isDeactivated: false }),
+    createApiKey: jest.fn().mockResolvedValue({
+      keyId: '',
+      label: '',
+      creationTime: '',
+      isDeactivated: false,
+    }),
     deactivateApiKey: jest.fn().mockResolvedValue(undefined),
     renameApiKey: jest.fn().mockResolvedValue(undefined),
     setApiKeyLimit: jest.fn().mockResolvedValue(undefined),
-    getAdminUsage: jest.fn().mockResolvedValue({ totalUsage: {}, startDate: '', endDate: '', entries: [] }),
+    getAdminUsage: jest.fn().mockResolvedValue({
+      totalUsage: {},
+      startDate: '',
+      endDate: '',
+      entries: [],
+    }),
     destroy: jest.fn(),
   };
 }
 
 export function createMockDeepLClient(
-  overrides: Partial<MockShape<DeepLClient>> = {},
+  overrides: Partial<MockShape<DeepLClient>> = {}
 ): jest.Mocked<DeepLClient> {
-  return { ...deepLClientDefaults(), ...overrides } as unknown as jest.Mocked<DeepLClient>;
+  return {
+    ...deepLClientDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<DeepLClient>;
 }
 
 // ---------------------------------------------------------------------------
 // ConfigService
 // ---------------------------------------------------------------------------
-function configServiceDefaults(): MockShape<ConfigService> & { getDefaults: jest.Mock } {
+function configServiceDefaults(): MockShape<ConfigService> & {
+  getDefaults: jest.Mock;
+} {
   return {
     get: jest.fn().mockReturnValue({}),
     getValue: jest.fn().mockReturnValue(undefined),
@@ -132,9 +176,12 @@ function configServiceDefaults(): MockShape<ConfigService> & { getDefaults: jest
 }
 
 export function createMockConfigService(
-  overrides: Partial<ReturnType<typeof configServiceDefaults>> = {},
+  overrides: Partial<ReturnType<typeof configServiceDefaults>> = {}
 ): jest.Mocked<ConfigService> {
-  return { ...configServiceDefaults(), ...overrides } as unknown as jest.Mocked<ConfigService>;
+  return {
+    ...configServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<ConfigService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -145,7 +192,12 @@ function cacheServiceDefaults(): MockShape<CacheService> {
     get: jest.fn().mockReturnValue(null),
     set: jest.fn(),
     clear: jest.fn(),
-    stats: jest.fn().mockReturnValue({ entries: 0, totalSize: 0, maxSize: 1024 * 1024 * 1024, enabled: true }),
+    stats: jest.fn().mockReturnValue({
+      entries: 0,
+      totalSize: 0,
+      maxSize: 1024 * 1024 * 1024,
+      enabled: true,
+    }),
     enable: jest.fn(),
     disable: jest.fn(),
     setMaxSize: jest.fn(),
@@ -155,9 +207,12 @@ function cacheServiceDefaults(): MockShape<CacheService> {
 }
 
 export function createMockCacheService(
-  overrides: Partial<MockShape<CacheService>> = {},
+  overrides: Partial<MockShape<CacheService>> = {}
 ): jest.Mocked<CacheService> {
-  return { ...cacheServiceDefaults(), ...overrides } as unknown as jest.Mocked<CacheService>;
+  return {
+    ...cacheServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<CacheService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -167,17 +222,24 @@ function translationServiceDefaults(): MockShape<TranslationService> {
   return {
     translate: unconfiguredAsync('TranslationService.translate'),
     translateBatch: unconfiguredAsync('TranslationService.translateBatch'),
-    translateToMultiple: unconfiguredAsync('TranslationService.translateToMultiple'),
+    translateToMultiple: unconfiguredAsync(
+      'TranslationService.translateToMultiple'
+    ),
     listTranslationMemories: jest.fn().mockResolvedValue([]),
-    getUsage: jest.fn().mockResolvedValue({ character: { count: 0, limit: 0 } }),
+    getUsage: jest
+      .fn()
+      .mockResolvedValue({ character: { count: 0, limit: 0 } }),
     getSupportedLanguages: jest.fn().mockResolvedValue([]),
   };
 }
 
 export function createMockTranslationService(
-  overrides: Partial<MockShape<TranslationService>> = {},
+  overrides: Partial<MockShape<TranslationService>> = {}
 ): jest.Mocked<TranslationService> {
-  return { ...translationServiceDefaults(), ...overrides } as unknown as jest.Mocked<TranslationService>;
+  return {
+    ...translationServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<TranslationService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -190,7 +252,9 @@ function glossaryServiceDefaults(): MockShape<GlossaryService> {
     listGlossaries: jest.fn().mockResolvedValue([]),
     getGlossary: jest.fn().mockResolvedValue(null),
     getGlossaryByName: jest.fn().mockResolvedValue(null),
-    resolveGlossaryId: jest.fn().mockRejectedValue(new Error('Glossary not found')),
+    resolveGlossaryId: jest
+      .fn()
+      .mockRejectedValue(new Error('Glossary not found')),
     deleteGlossary: jest.fn().mockResolvedValue(undefined),
     getGlossaryEntries: jest.fn().mockResolvedValue({}),
     getGlossaryLanguages: jest.fn().mockResolvedValue([]),
@@ -205,9 +269,12 @@ function glossaryServiceDefaults(): MockShape<GlossaryService> {
 }
 
 export function createMockGlossaryService(
-  overrides: Partial<MockShape<GlossaryService>> = {},
+  overrides: Partial<MockShape<GlossaryService>> = {}
 ): jest.Mocked<GlossaryService> {
-  return { ...glossaryServiceDefaults(), ...overrides } as unknown as jest.Mocked<GlossaryService>;
+  return {
+    ...glossaryServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<GlossaryService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -215,16 +282,23 @@ export function createMockGlossaryService(
 // ---------------------------------------------------------------------------
 function documentTranslationServiceDefaults(): MockShape<DocumentTranslationService> {
   return {
-    translateDocument: jest.fn().mockResolvedValue({ success: true, outputPath: '/output.pdf' }),
+    translateDocument: jest
+      .fn()
+      .mockResolvedValue({ success: true, outputPath: '/output.pdf' }),
     isDocumentSupported: jest.fn().mockReturnValue(false),
-    getSupportedFileTypes: jest.fn().mockReturnValue(['.pdf', '.docx', '.pptx']),
+    getSupportedFileTypes: jest
+      .fn()
+      .mockReturnValue(['.pdf', '.docx', '.pptx']),
   };
 }
 
 export function createMockDocumentTranslationService(
-  overrides: Partial<MockShape<DocumentTranslationService>> = {},
+  overrides: Partial<MockShape<DocumentTranslationService>> = {}
 ): jest.Mocked<DocumentTranslationService> {
-  return { ...documentTranslationServiceDefaults(), ...overrides } as unknown as jest.Mocked<DocumentTranslationService>;
+  return {
+    ...documentTranslationServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<DocumentTranslationService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -233,16 +307,23 @@ export function createMockDocumentTranslationService(
 function fileTranslationServiceDefaults(): MockShape<FileTranslationService> {
   return {
     translateFile: jest.fn().mockResolvedValue(undefined),
-    translateFileToMultiple: unconfiguredAsync('FileTranslationService.translateFileToMultiple'),
-    getSupportedFileTypes: jest.fn().mockReturnValue(['.txt', '.md', '.json', '.yaml', '.yml']),
+    translateFileToMultiple: unconfiguredAsync(
+      'FileTranslationService.translateFileToMultiple'
+    ),
+    getSupportedFileTypes: jest
+      .fn()
+      .mockReturnValue(['.txt', '.md', '.json', '.yaml', '.yml']),
     isSupportedFile: jest.fn().mockReturnValue(true),
   };
 }
 
 export function createMockFileTranslationService(
-  overrides: Partial<MockShape<FileTranslationService>> = {},
+  overrides: Partial<MockShape<FileTranslationService>> = {}
 ): jest.Mocked<FileTranslationService> {
-  return { ...fileTranslationServiceDefaults(), ...overrides } as unknown as jest.Mocked<FileTranslationService>;
+  return {
+    ...fileTranslationServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<FileTranslationService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -252,16 +333,24 @@ function watchServiceDefaults(): Record<string, jest.Mock> {
   return {
     watch: jest.fn().mockReturnValue(undefined),
     stop: jest.fn().mockResolvedValue(undefined),
-    getStats: jest.fn().mockReturnValue({ isWatching: false, filesWatched: 0, translationsCount: 0, errorsCount: 0 }),
+    getStats: jest.fn().mockReturnValue({
+      isWatching: false,
+      filesWatched: 0,
+      translationsCount: 0,
+      errorsCount: 0,
+    }),
     isWatching: jest.fn().mockReturnValue(false),
     handleFileChange: jest.fn(),
   };
 }
 
 export function createMockWatchService(
-  overrides: Partial<Record<string, jest.Mock>> = {},
+  overrides: Partial<Record<string, jest.Mock>> = {}
 ): jest.Mocked<WatchService> {
-  return { ...watchServiceDefaults(), ...overrides } as unknown as jest.Mocked<WatchService>;
+  return {
+    ...watchServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<WatchService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -277,9 +366,12 @@ function writeServiceDefaults(): MockShape<WriteService> {
 }
 
 export function createMockWriteService(
-  overrides: Partial<MockShape<WriteService>> = {},
+  overrides: Partial<MockShape<WriteService>> = {}
 ): jest.Mocked<WriteService> {
-  return { ...writeServiceDefaults(), ...overrides } as unknown as jest.Mocked<WriteService>;
+  return {
+    ...writeServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<WriteService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -296,9 +388,12 @@ function voiceClientDefaults(): Record<string, jest.Mock> {
 }
 
 export function createMockVoiceClient(
-  overrides: Partial<Record<string, jest.Mock>> = {},
+  overrides: Partial<Record<string, jest.Mock>> = {}
 ): jest.Mocked<VoiceClient> {
-  return { ...voiceClientDefaults(), ...overrides } as unknown as jest.Mocked<VoiceClient>;
+  return {
+    ...voiceClientDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<VoiceClient>;
 }
 
 // ---------------------------------------------------------------------------
@@ -306,8 +401,16 @@ export function createMockVoiceClient(
 // ---------------------------------------------------------------------------
 function voiceServiceDefaults(): MockShape<VoiceService> {
   return {
-    translateFile: jest.fn().mockResolvedValue({ sessionId: '', source: { lang: '', text: '', segments: [] }, targets: [] }),
-    translateStdin: jest.fn().mockResolvedValue({ sessionId: '', source: { lang: '', text: '', segments: [] }, targets: [] }),
+    translateFile: jest.fn().mockResolvedValue({
+      sessionId: '',
+      source: { lang: '', text: '', segments: [] },
+      targets: [],
+    }),
+    translateStdin: jest.fn().mockResolvedValue({
+      sessionId: '',
+      source: { lang: '', text: '', segments: [] },
+      targets: [],
+    }),
     detectContentType: jest.fn().mockReturnValue(undefined),
     validateOptions: jest.fn(),
     cancel: jest.fn(),
@@ -315,9 +418,12 @@ function voiceServiceDefaults(): MockShape<VoiceService> {
 }
 
 export function createMockVoiceService(
-  overrides: Partial<MockShape<VoiceService>> = {},
+  overrides: Partial<MockShape<VoiceService>> = {}
 ): jest.Mocked<VoiceService> {
-  return { ...voiceServiceDefaults(), ...overrides } as unknown as jest.Mocked<VoiceService>;
+  return {
+    ...voiceServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<VoiceService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -326,18 +432,31 @@ export function createMockVoiceService(
 function adminServiceDefaults(): MockShape<AdminService> {
   return {
     listApiKeys: jest.fn().mockResolvedValue([]),
-    createApiKey: jest.fn().mockResolvedValue({ keyId: '', label: '', creationTime: '', isDeactivated: false }),
+    createApiKey: jest.fn().mockResolvedValue({
+      keyId: '',
+      label: '',
+      creationTime: '',
+      isDeactivated: false,
+    }),
     deactivateApiKey: jest.fn().mockResolvedValue(undefined),
     renameApiKey: jest.fn().mockResolvedValue(undefined),
     setApiKeyLimit: jest.fn().mockResolvedValue(undefined),
-    getAdminUsage: jest.fn().mockResolvedValue({ totalUsage: {}, startDate: '', endDate: '', entries: [] }),
+    getAdminUsage: jest.fn().mockResolvedValue({
+      totalUsage: {},
+      startDate: '',
+      endDate: '',
+      entries: [],
+    }),
   };
 }
 
 export function createMockAdminService(
-  overrides: Partial<MockShape<AdminService>> = {},
+  overrides: Partial<MockShape<AdminService>> = {}
 ): jest.Mocked<AdminService> {
-  return { ...adminServiceDefaults(), ...overrides } as unknown as jest.Mocked<AdminService>;
+  return {
+    ...adminServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<AdminService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -345,14 +464,19 @@ export function createMockAdminService(
 // ---------------------------------------------------------------------------
 function usageServiceDefaults(): MockShape<UsageService> {
   return {
-    getUsage: jest.fn().mockResolvedValue({ characterCount: 0, characterLimit: 0 }),
+    getUsage: jest
+      .fn()
+      .mockResolvedValue({ characterCount: 0, characterLimit: 0 }),
   };
 }
 
 export function createMockUsageService(
-  overrides: Partial<MockShape<UsageService>> = {},
+  overrides: Partial<MockShape<UsageService>> = {}
 ): jest.Mocked<UsageService> {
-  return { ...usageServiceDefaults(), ...overrides } as unknown as jest.Mocked<UsageService>;
+  return {
+    ...usageServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<UsageService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -362,34 +486,60 @@ function styleRulesServiceDefaults(): MockShape<StyleRulesService> {
   return {
     getStyleRules: jest.fn().mockResolvedValue([]),
     createStyleRule: jest.fn().mockResolvedValue({
-      styleId: 'mock-id', name: 'mock', language: 'en', version: 1,
-      creationTime: 'c', updatedTime: 'u',
+      styleId: 'mock-id',
+      name: 'mock',
+      language: 'en',
+      version: 1,
+      creationTime: 'c',
+      updatedTime: 'u',
     }),
     getStyleRule: jest.fn().mockResolvedValue({
-      styleId: 'mock-id', name: 'mock', language: 'en', version: 1,
-      creationTime: 'c', updatedTime: 'u',
+      styleId: 'mock-id',
+      name: 'mock',
+      language: 'en',
+      version: 1,
+      creationTime: 'c',
+      updatedTime: 'u',
     }),
     updateStyleRule: jest.fn().mockResolvedValue({
-      styleId: 'mock-id', name: 'mock', language: 'en', version: 2,
-      creationTime: 'c', updatedTime: 'u',
+      styleId: 'mock-id',
+      name: 'mock',
+      language: 'en',
+      version: 2,
+      creationTime: 'c',
+      updatedTime: 'u',
     }),
     deleteStyleRule: jest.fn().mockResolvedValue(undefined),
     replaceConfiguredRules: jest.fn().mockResolvedValue({
-      styleId: 'mock-id', name: 'mock', language: 'en', version: 2,
-      creationTime: 'c', updatedTime: 'u',
-      configuredRules: {}, customInstructions: [],
+      styleId: 'mock-id',
+      name: 'mock',
+      language: 'en',
+      version: 2,
+      creationTime: 'c',
+      updatedTime: 'u',
+      configuredRules: {},
+      customInstructions: [],
     }),
-    createCustomInstruction: jest.fn().mockResolvedValue({ label: 'mock', prompt: 'mock' }),
-    getCustomInstruction: jest.fn().mockResolvedValue({ label: 'mock', prompt: 'mock' }),
-    updateCustomInstruction: jest.fn().mockResolvedValue({ label: 'mock', prompt: 'mock' }),
+    createCustomInstruction: jest
+      .fn()
+      .mockResolvedValue({ label: 'mock', prompt: 'mock' }),
+    getCustomInstruction: jest
+      .fn()
+      .mockResolvedValue({ label: 'mock', prompt: 'mock' }),
+    updateCustomInstruction: jest
+      .fn()
+      .mockResolvedValue({ label: 'mock', prompt: 'mock' }),
     deleteCustomInstruction: jest.fn().mockResolvedValue(undefined),
   };
 }
 
 export function createMockStyleRulesService(
-  overrides: Partial<MockShape<StyleRulesService>> = {},
+  overrides: Partial<MockShape<StyleRulesService>> = {}
 ): jest.Mocked<StyleRulesService> {
-  return { ...styleRulesServiceDefaults(), ...overrides } as unknown as jest.Mocked<StyleRulesService>;
+  return {
+    ...styleRulesServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<StyleRulesService>;
 }
 
 // ---------------------------------------------------------------------------
@@ -397,20 +547,27 @@ export function createMockStyleRulesService(
 // ---------------------------------------------------------------------------
 function detectServiceDefaults(): MockShape<DetectService> {
   return {
-    detect: jest.fn().mockResolvedValue({ detectedLanguage: 'en', languageName: 'English' }),
+    detect: jest
+      .fn()
+      .mockResolvedValue({ detectedLanguage: 'en', languageName: 'English' }),
   };
 }
 
 export function createMockDetectService(
-  overrides: Partial<MockShape<DetectService>> = {},
+  overrides: Partial<MockShape<DetectService>> = {}
 ): jest.Mocked<DetectService> {
-  return { ...detectServiceDefaults(), ...overrides } as unknown as jest.Mocked<DetectService>;
+  return {
+    ...detectServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<DetectService>;
 }
 
 // ---------------------------------------------------------------------------
 // LanguagesService
 // ---------------------------------------------------------------------------
-function languagesServiceDefaults(): MockShape<LanguagesService> & { hasClient: jest.Mock } {
+function languagesServiceDefaults(): MockShape<LanguagesService> & {
+  hasClient: jest.Mock;
+} {
   return {
     getSupportedLanguages: jest.fn().mockResolvedValue([]),
     hasClient: jest.fn().mockReturnValue(true),
@@ -418,7 +575,10 @@ function languagesServiceDefaults(): MockShape<LanguagesService> & { hasClient:
 }
 
 export function createMockLanguagesService(
-  overrides: Partial<ReturnType<typeof languagesServiceDefaults>> = {},
+  overrides: Partial<ReturnType<typeof languagesServiceDefaults>> = {}
 ): jest.Mocked<LanguagesService> {
-  return { ...languagesServiceDefaults(), ...overrides } as unknown as jest.Mocked<LanguagesService>;
+  return {
+    ...languagesServiceDefaults(),
+    ...overrides,
+  } as unknown as jest.Mocked<LanguagesService>;
 }
diff --git a/tests/helpers/nock-setup.ts b/tests/helpers/nock-setup.ts
index f235f02d..1629da34 100644
--- a/tests/helpers/nock-setup.ts
+++ b/tests/helpers/nock-setup.ts
@@ -4,22 +4,26 @@ export const DEEPL_FREE_API_URL = 'https://api-free.deepl.com';
 export const DEEPL_PRO_API_URL = 'https://api.deepl.com';
 export const TEST_API_KEY = 'test-api-key-123:fx';
 
-export function setupDeepLNock(baseUrl: string = DEEPL_FREE_API_URL): nock.Scope {
+export function setupDeepLNock(
+  baseUrl: string = DEEPL_FREE_API_URL
+): nock.Scope {
   return nock(baseUrl);
 }
 
 export function mockTranslateResponse(
   scope: nock.Scope,
   response: { text: string; detected_source_language?: string }[],
-  statusCode: number = 200,
+  statusCode: number = 200
 ): nock.Scope {
-  return scope.post('/v2/translate').reply(statusCode, { translations: response });
+  return scope
+    .post('/v2/translate')
+    .reply(statusCode, { translations: response });
 }
 
 export function mockTranslateError(
   scope: nock.Scope,
   statusCode: number,
-  body: string | Record<string, unknown> = { message: 'Error' },
+  body: string | Record<string, unknown> = { message: 'Error' }
 ): nock.Scope {
   return scope.post('/v2/translate').reply(statusCode, body);
 }
@@ -30,7 +34,7 @@ export function mockUsageResponse(
     character_count: 50000,
     character_limit: 500000,
   },
-  statusCode: number = 200,
+  statusCode: number = 200
 ): nock.Scope {
   return scope.get('/v2/usage').reply(statusCode, response);
 }
@@ -85,18 +89,15 @@ export function mockLanguagesResponse(
       features: { formality: STABLE, glossary: STABLE, tag_handling: STABLE },
     },
   ],
-  resource: string = 'translate_text',
+  resource: string = 'translate_text'
 ): nock.Scope {
-  return scope
-    .get('/v3/languages')
-    .query({ resource })
-    .reply(200, languages);
+  return scope.get('/v3/languages').query({ resource }).reply(200, languages);
 }
 
 export function mockWriteResponse(
   scope: nock.Scope,
   improvements: Array<{ text: string; [key: string]: unknown }>,
-  statusCode: number = 200,
+  statusCode: number = 200
 ): nock.Scope {
   return scope.post('/v2/write/rephrase').reply(statusCode, { improvements });
 }
diff --git a/tests/helpers/run-cli.ts b/tests/helpers/run-cli.ts
index e3bf8e8b..633c4eaf 100644
--- a/tests/helpers/run-cli.ts
+++ b/tests/helpers/run-cli.ts
@@ -25,7 +25,10 @@ export interface TestConfigDir {
 const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
 
 export function createTestConfigDir(label: string): TestConfigDir {
-  const dirPath = path.join(os.tmpdir(), `.deepl-cli-test-${label}-${Date.now()}`);
+  const dirPath = path.join(
+    os.tmpdir(),
+    `.deepl-cli-test-${label}-${Date.now()}`
+  );
   fs.mkdirSync(dirPath, { recursive: true });
   return {
     path: dirPath,
@@ -50,7 +53,10 @@ export function createTestDir(label: string): TestConfigDir {
   };
 }
 
-function buildEnv(configDir: string, options: CLIRunOptions = {}): Record<string, string | undefined> {
+function buildEnv(
+  configDir: string,
+  options: CLIRunOptions = {}
+): Record<string, string | undefined> {
   let baseEnv: Record<string, string | undefined> = { ...process.env };
 
   if (options.excludeApiKey) {
@@ -67,9 +73,16 @@ function buildEnv(configDir: string, options: CLIRunOptions = {}): Record<string
   };
 }
 
-export function makeRunCLI(configDir: string, defaultOptions: CLIRunOptions = {}) {
+export function makeRunCLI(
+  configDir: string,
+  defaultOptions: CLIRunOptions = {}
+) {
   function mergeOptions(options: CLIRunOptions): CLIRunOptions {
-    return { ...defaultOptions, ...options, env: { ...defaultOptions.env, ...options.env } };
+    return {
+      ...defaultOptions,
+      ...options,
+      env: { ...defaultOptions.env, ...options.env },
+    };
   }
 
   /**
@@ -102,7 +115,10 @@ export function makeRunCLI(configDir: string, defaultOptions: CLIRunOptions = {}
    * Run a CLI command expecting it to fail.
    * Returns the exit status and combined output instead of throwing.
    */
-  function runCLIExpectError(command: string, options: CLIRunOptions = {}): CLIErrorResult {
+  function runCLIExpectError(
+    command: string,
+    options: CLIRunOptions = {}
+  ): CLIErrorResult {
     const merged = mergeOptions(options);
     try {
       const output = execSync(command, {
@@ -113,8 +129,12 @@ export function makeRunCLI(configDir: string, defaultOptions: CLIRunOptions = {}
       return { status: 0, output };
     } catch (error: any) {
       return {
-        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional: status 0 in catch should become 1; empty stderr should fall through to stdout
-        status: error.status || 1, output: error.stderr?.toString() || error.stdout?.toString() || '',
+        /* eslint-disable @typescript-eslint/prefer-nullish-coalescing --
+           intentional: a status of 0 in the catch path should become 1, and an
+           empty stderr should fall through to stdout */
+        status: error.status || 1,
+        output: error.stderr?.toString() || error.stdout?.toString() || '',
+        /* eslint-enable @typescript-eslint/prefer-nullish-coalescing */
       };
     }
   }
@@ -122,7 +142,11 @@ export function makeRunCLI(configDir: string, defaultOptions: CLIRunOptions = {}
   /**
    * Run a CLI command with piped stdin using bash.
    */
-  function runCLIWithStdin(command: string, stdin: string, options: CLIRunOptions = {}): CLIErrorResult {
+  function runCLIWithStdin(
+    command: string,
+    stdin: string,
+    options: CLIRunOptions = {}
+  ): CLIErrorResult {
     const merged = mergeOptions(options);
     try {
       const output = execSync(command, {
@@ -134,8 +158,12 @@ export function makeRunCLI(configDir: string, defaultOptions: CLIRunOptions = {}
       return { status: 0, output };
     } catch (error: any) {
       return {
-        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional: status 0 in catch should become 1; empty stderr should fall through to stdout
-        status: error.status || 1, output: error.stderr?.toString() || error.stdout?.toString() || '',
+        /* eslint-disable @typescript-eslint/prefer-nullish-coalescing --
+           intentional: a status of 0 in the catch path should become 1, and an
+           empty stderr should fall through to stdout */
+        status: error.status || 1,
+        output: error.stderr?.toString() || error.stdout?.toString() || '',
+        /* eslint-enable @typescript-eslint/prefer-nullish-coalescing */
       };
     }
   }
@@ -143,11 +171,18 @@ export function makeRunCLI(configDir: string, defaultOptions: CLIRunOptions = {}
   return { runCLI, runCLIAll, runCLIExpectError, runCLIWithStdin };
 }
 
-export function makeNodeRunCLI(configDir: string, defaultOptions: CLIRunOptions = {}) {
+export function makeNodeRunCLI(
+  configDir: string,
+  defaultOptions: CLIRunOptions = {}
+) {
   const cliPath = CLI_PATH;
 
   function mergeOptions(options: CLIRunOptions): CLIRunOptions {
-    return { ...defaultOptions, ...options, env: { ...defaultOptions.env, ...options.env } };
+    return {
+      ...defaultOptions,
+      ...options,
+      env: { ...defaultOptions.env, ...options.env },
+    };
   }
 
   function runCLI(args: string, options: CLIRunOptions = {}): string {
@@ -169,7 +204,10 @@ export function makeNodeRunCLI(configDir: string, defaultOptions: CLIRunOptions
     });
   }
 
-  function runCLIExpectError(args: string, options: CLIRunOptions = {}): CLIErrorResult {
+  function runCLIExpectError(
+    args: string,
+    options: CLIRunOptions = {}
+  ): CLIErrorResult {
     const merged = mergeOptions(options);
     try {
       const output = execSync(`node ${cliPath} ${args}`, {
@@ -180,13 +218,21 @@ export function makeNodeRunCLI(configDir: string, defaultOptions: CLIRunOptions
       return { status: 0, output };
     } catch (error: any) {
       return {
-        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional: status 0 in catch should become 1; empty stderr should fall through to stdout
-        status: error.status || 1, output: error.stderr?.toString() || error.stdout?.toString() || '',
+        /* eslint-disable @typescript-eslint/prefer-nullish-coalescing --
+           intentional: a status of 0 in the catch path should become 1, and an
+           empty stderr should fall through to stdout */
+        status: error.status || 1,
+        output: error.stderr?.toString() || error.stdout?.toString() || '',
+        /* eslint-enable @typescript-eslint/prefer-nullish-coalescing */
       };
     }
   }
 
-  function runCLIPipe(stdin: string, args: string, options: CLIRunOptions = {}): string {
+  function runCLIPipe(
+    stdin: string,
+    args: string,
+    options: CLIRunOptions = {}
+  ): string {
     const merged = mergeOptions(options);
     return execSync(`node ${cliPath} ${args}`, {
       encoding: 'utf-8',
@@ -196,7 +242,11 @@ export function makeNodeRunCLI(configDir: string, defaultOptions: CLIRunOptions
     });
   }
 
-  function runCLIWithStdin(args: string, stdin: string, options: CLIRunOptions = {}): CLIErrorResult {
+  function runCLIWithStdin(
+    args: string,
+    stdin: string,
+    options: CLIRunOptions = {}
+  ): CLIErrorResult {
     const merged = mergeOptions(options);
     try {
       const output = execSync(`node ${cliPath} ${args}`, {
@@ -208,8 +258,12 @@ export function makeNodeRunCLI(configDir: string, defaultOptions: CLIRunOptions
       return { status: 0, output };
     } catch (error: any) {
       return {
-        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional: status 0 in catch should become 1; empty stderr should fall through to stdout
-        status: error.status || 1, output: error.stderr?.toString() || error.stdout?.toString() || '',
+        /* eslint-disable @typescript-eslint/prefer-nullish-coalescing --
+           intentional: a status of 0 in the catch path should become 1, and an
+           empty stderr should fall through to stdout */
+        status: error.status || 1,
+        output: error.stderr?.toString() || error.stdout?.toString() || '',
+        /* eslint-enable @typescript-eslint/prefer-nullish-coalescing */
       };
     }
   }
diff --git a/tests/helpers/sync-harness.ts b/tests/helpers/sync-harness.ts
index cd172bb9..bf3f519c 100644
--- a/tests/helpers/sync-harness.ts
+++ b/tests/helpers/sync-harness.ts
@@ -31,9 +31,16 @@ import { IosStringsFormatParser } from '../../src/formats/ios-strings';
 import { PropertiesFormatParser } from '../../src/formats/properties';
 import type { FormatParser } from '../../src/formats/index';
 import type { SyncLockFile, SyncLockEntry } from '../../src/sync/types';
-import { LOCK_FILE_NAME, LOCK_FILE_VERSION, LOCK_FILE_COMMENT } from '../../src/sync/types';
+import {
+  LOCK_FILE_NAME,
+  LOCK_FILE_VERSION,
+  LOCK_FILE_COMMENT,
+} from '../../src/sync/types';
 import { TEST_API_KEY } from './nock-setup';
-import { createMockConfigService, createMockCacheService } from './mock-factories';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from './mock-factories';
 
 export type SupportedParser =
   | 'json'
@@ -54,13 +61,21 @@ export interface SyncHarness {
   cleanup: () => void;
 }
 
-export function createSyncHarness(opts: { parsers?: SupportedParser[]; maxRetries?: number } = {}): SyncHarness {
-  const client = new DeepLClient(TEST_API_KEY, { maxRetries: opts.maxRetries ?? 0 });
+export function createSyncHarness(
+  opts: { parsers?: SupportedParser[]; maxRetries?: number } = {}
+): SyncHarness {
+  const client = new DeepLClient(TEST_API_KEY, {
+    maxRetries: opts.maxRetries ?? 0,
+  });
   const mockConfig = createMockConfigService({
     get: jest.fn(() => ({
       auth: {},
       api: { baseUrl: '', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
       cache: { enabled: false },
       output: { format: 'text', color: true },
       proxy: {},
@@ -68,28 +83,46 @@ export function createSyncHarness(opts: { parsers?: SupportedParser[]; maxRetrie
     getValue: jest.fn(() => false),
   });
   const mockCache = createMockCacheService();
-  const translationService = new TranslationService(client, mockConfig, mockCache);
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    mockCache
+  );
   const glossaryService = new GlossaryService(client);
   const registry = new FormatRegistry();
   for (const name of opts.parsers ?? ['json']) {
     registry.register(parserFor(name));
   }
-  const syncService = new SyncService(translationService, glossaryService, registry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    registry
+  );
   return { client, syncService, registry, cleanup: () => client.destroy() };
 }
 
 function parserFor(name: SupportedParser): FormatParser {
   switch (name) {
-    case 'json': return new JsonFormatParser();
-    case 'yaml': return new YamlFormatParser();
-    case 'android_xml': return new AndroidXmlFormatParser();
-    case 'xliff': return new XliffFormatParser();
-    case 'xcstrings': return new XcstringsFormatParser();
-    case 'po': return new PoFormatParser();
-    case 'toml': return new TomlFormatParser();
-    case 'arb': return new ArbFormatParser();
-    case 'ios_strings': return new IosStringsFormatParser();
-    case 'properties': return new PropertiesFormatParser();
+    case 'json':
+      return new JsonFormatParser();
+    case 'yaml':
+      return new YamlFormatParser();
+    case 'android_xml':
+      return new AndroidXmlFormatParser();
+    case 'xliff':
+      return new XliffFormatParser();
+    case 'xcstrings':
+      return new XcstringsFormatParser();
+    case 'po':
+      return new PoFormatParser();
+    case 'toml':
+      return new TomlFormatParser();
+    case 'arb':
+      return new ArbFormatParser();
+    case 'ios_strings':
+      return new IosStringsFormatParser();
+    case 'properties':
+      return new PropertiesFormatParser();
   }
 }
 
@@ -121,7 +154,10 @@ export function buildSyncConfigYaml(opts: SyncConfigYamlOpts = {}): string {
   return YAML.stringify(config);
 }
 
-export function writeSyncConfig(dir: string, opts: SyncConfigYamlOpts = {}): string {
+export function writeSyncConfig(
+  dir: string,
+  opts: SyncConfigYamlOpts = {}
+): string {
   const yaml = buildSyncConfigYaml(opts);
   const filePath = path.join(dir, '.deepl-sync.yaml');
   fs.writeFileSync(filePath, yaml, 'utf-8');
@@ -150,7 +186,15 @@ export function seedLockFile(dir: string, opts: SeedLockOpts): void {
     generated_at: now,
     source_locale: sourceLocale,
     entries: opts.entries,
-    stats: { total_keys: totalKeys, total_translations: totalTranslations, last_sync: now },
+    stats: {
+      total_keys: totalKeys,
+      total_translations: totalTranslations,
+      last_sync: now,
+    },
   };
-  fs.writeFileSync(path.join(dir, LOCK_FILE_NAME), JSON.stringify(lockFile, null, 2) + '\n', 'utf-8');
+  fs.writeFileSync(
+    path.join(dir, LOCK_FILE_NAME),
+    JSON.stringify(lockFile, null, 2) + '\n',
+    'utf-8'
+  );
 }
diff --git a/tests/helpers/tms-nock.ts b/tests/helpers/tms-nock.ts
index 1a4bdee0..d656609f 100644
--- a/tests/helpers/tms-nock.ts
+++ b/tests/helpers/tms-nock.ts
@@ -18,9 +18,7 @@ export const TMS_API_KEY = 'tms-test-api-key';
 export const TMS_TOKEN = 'tms-test-token';
 
 export type AuthExpectation =
-  | { apiKey: string }
-  | { token: string }
-  | { none: true };
+  { apiKey: string } | { token: string } | { none: true };
 
 function authHeader(auth: AuthExpectation | undefined): string | undefined {
   if (!auth) return undefined;
@@ -33,12 +31,15 @@ export function expectTmsPush(
   key: string,
   locale: string,
   value: string,
-  opts: { auth?: AuthExpectation; status?: number } = {},
+  opts: { auth?: AuthExpectation; status?: number } = {}
 ): nock.Scope {
   const scope = nock(TMS_BASE);
   const expectedBody = { locale, value };
   const encoded = encodeURIComponent(key);
-  let interceptor = scope.put(`/api/projects/${TMS_PROJECT}/keys/${encoded}`, expectedBody);
+  let interceptor = scope.put(
+    `/api/projects/${TMS_PROJECT}/keys/${encoded}`,
+    expectedBody
+  );
   const header = authHeader(opts.auth);
   if (header !== undefined) {
     interceptor = interceptor.matchHeader('authorization', header);
@@ -49,7 +50,7 @@ export function expectTmsPush(
 export function expectTmsPull(
   locale: string,
   response: Record<string, string>,
-  opts: { auth?: AuthExpectation; status?: number } = {},
+  opts: { auth?: AuthExpectation; status?: number } = {}
 ): nock.Scope {
   const scope = nock(TMS_BASE);
   let interceptor = scope
@@ -66,20 +67,26 @@ export function expectTmsError(
   method: 'put' | 'get',
   pathSuffix: string,
   status: number,
-  body: Record<string, unknown> = {},
+  body: Record<string, unknown> = {}
 ): nock.Scope {
   const scope = nock(TMS_BASE);
   if (method === 'put') {
-    return scope.put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`)).reply(status, body);
+    return scope
+      .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
+      .reply(status, body);
   }
-  return scope.get(new RegExp(`/api/projects/${TMS_PROJECT}${pathSuffix}.*`)).reply(status, body);
+  return scope
+    .get(new RegExp(`/api/projects/${TMS_PROJECT}${pathSuffix}.*`))
+    .reply(status, body);
 }
 
 /**
  * Standard `tms:` config block pointing at the nock-mocked TMS_BASE/TMS_PROJECT.
  * Spread extra overrides (e.g. token) into the second arg.
  */
-export function tmsConfig(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+export function tmsConfig(
+  overrides: Record<string, unknown> = {}
+): Record<string, unknown> {
   return {
     enabled: true,
     server: TMS_BASE,
diff --git a/tests/hermetic-deepl.ts b/tests/hermetic-deepl.ts
index 88614756..78619e73 100644
--- a/tests/hermetic-deepl.ts
+++ b/tests/hermetic-deepl.ts
@@ -19,11 +19,16 @@ export default function installHermeticDeepl(): void {
   if (existing && fs.existsSync(path.join(existing, 'deepl'))) return;
 
   const shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-cli-shim-'));
-  fs.writeFileSync(path.join(shimDir, 'deepl'), `#!/bin/sh\nexec node "${CLI_ENTRY}" "$@"\n`, {
-    mode: 0o755,
-  });
+  fs.writeFileSync(
+    path.join(shimDir, 'deepl'),
+    `#!/bin/sh\nexec node "${CLI_ENTRY}" "$@"\n`,
+    {
+      mode: 0o755,
+    }
+  );
   process.env['DEEPL_CLI_TEST_SHIM'] = shimDir;
-  process.env['PATH'] = `${shimDir}${path.delimiter}${process.env['PATH'] ?? ''}`;
+  process.env['PATH'] =
+    `${shimDir}${path.delimiter}${process.env['PATH'] ?? ''}`;
 }
 
 /**
@@ -40,6 +45,6 @@ export function isolateCredentialEnvironment(): void {
   delete process.env['TMS_TOKEN'];
 
   process.env['DEEPL_CONFIG_DIR'] ??= fs.mkdtempSync(
-    path.join(os.tmpdir(), 'deepl-cli-test-config-'),
+    path.join(os.tmpdir(), 'deepl-cli-test-config-')
   );
 }
diff --git a/tests/integration/admin-client.integration.test.ts b/tests/integration/admin-client.integration.test.ts
index 1ba6f39f..06da4d10 100644
--- a/tests/integration/admin-client.integration.test.ts
+++ b/tests/integration/admin-client.integration.test.ts
@@ -13,7 +13,7 @@ describe('AdminClient Integration', () => {
   const clients: AdminClient[] = [];
 
   afterEach(() => {
-    clients.forEach(c => c.destroy());
+    clients.forEach((c) => c.destroy());
     clients.length = 0;
     nock.cleanAll();
   });
@@ -63,7 +63,9 @@ describe('AdminClient Integration', () => {
         .get('/v2/admin/developer-keys')
         .reply(403, { message: 'Forbidden' });
 
-      await expect(client.listApiKeys()).rejects.toThrow('Authentication failed');
+      await expect(client.listApiKeys()).rejects.toThrow(
+        'Authentication failed'
+      );
     });
   });
 
@@ -226,7 +228,11 @@ describe('AdminClient Integration', () => {
 
       const scope = nock(API_URL)
         .get('/v2/admin/analytics')
-        .query({ start_date: '2024-01-01', end_date: '2024-01-31', group_by: 'key' })
+        .query({
+          start_date: '2024-01-01',
+          end_date: '2024-01-31',
+          group_by: 'key',
+        })
         .reply(200, {
           usage_report: {
             total_usage: {
diff --git a/tests/integration/batch-translation.integration.test.ts b/tests/integration/batch-translation.integration.test.ts
index 487cda7a..ba384011 100644
--- a/tests/integration/batch-translation.integration.test.ts
+++ b/tests/integration/batch-translation.integration.test.ts
@@ -26,7 +26,12 @@ import { FileTranslationService } from '../../src/services/file-translation.js';
 import { TranslationService } from '../../src/services/translation.js';
 import { DeepLClient } from '../../src/api/deepl-client.js';
 import { ConfigService } from '../../src/storage/config.js';
-import { TEST_API_KEY, createMockConfigService, createMockCacheService, DEEPL_FREE_API_URL } from '../helpers';
+import {
+  TEST_API_KEY,
+  createMockConfigService,
+  createMockCacheService,
+  DEEPL_FREE_API_URL,
+} from '../helpers';
 
 describe('Batch Translation Service Integration', () => {
   const API_KEY = TEST_API_KEY;
@@ -47,7 +52,11 @@ describe('Batch Translation Service Integration', () => {
       get: jest.fn(() => ({
         auth: {},
         api: { baseUrl: '', usePro: false },
-        defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: false,
+        },
         cache: { enabled: true },
         output: { format: 'text', color: true },
         proxy: {},
@@ -75,7 +84,9 @@ describe('Batch Translation Service Integration', () => {
     });
 
     it('should create service with custom concurrency', () => {
-      const service = new BatchTranslationService(fileTranslationService, { concurrency: 10 });
+      const service = new BatchTranslationService(fileTranslationService, {
+        concurrency: 10,
+      });
       expect(service).toBeInstanceOf(BatchTranslationService);
     });
 
@@ -87,24 +98,32 @@ describe('Batch Translation Service Integration', () => {
 
     it('should throw error for concurrency greater than 100', () => {
       expect(() => {
-        new BatchTranslationService(fileTranslationService, { concurrency: 101 });
+        new BatchTranslationService(fileTranslationService, {
+          concurrency: 101,
+        });
       }).toThrow('Concurrency cannot exceed 100');
     });
 
     it('should accept concurrency of 1', () => {
-      const service = new BatchTranslationService(fileTranslationService, { concurrency: 1 });
+      const service = new BatchTranslationService(fileTranslationService, {
+        concurrency: 1,
+      });
       expect(service).toBeInstanceOf(BatchTranslationService);
     });
 
     it('should accept concurrency of 100', () => {
-      const service = new BatchTranslationService(fileTranslationService, { concurrency: 100 });
+      const service = new BatchTranslationService(fileTranslationService, {
+        concurrency: 100,
+      });
       expect(service).toBeInstanceOf(BatchTranslationService);
     });
   });
 
   describe('translateFiles', () => {
     it('should return empty result for empty file list', async () => {
-      const result = await batchService.translateFiles([], { targetLang: 'es' });
+      const result = await batchService.translateFiles([], {
+        targetLang: 'es',
+      });
 
       expect(result.successful).toHaveLength(0);
       expect(result.failed).toHaveLength(0);
@@ -163,7 +182,8 @@ describe('Batch Translation Service Integration', () => {
       fs.writeFileSync(file2, 'World');
 
       // First translation succeeds, second fails
-      jest.spyOn(translationService, 'translate')
+      jest
+        .spyOn(translationService, 'translate')
         .mockResolvedValueOnce({ text: 'Hola' })
         .mockRejectedValueOnce(new Error('API error'));
 
@@ -188,7 +208,11 @@ describe('Batch Translation Service Integration', () => {
         text: 'Hola',
       });
 
-      const progressCalls: Array<{ completed: number; total: number; current?: string }> = [];
+      const progressCalls: Array<{
+        completed: number;
+        total: number;
+        current?: string;
+      }> = [];
       const onProgress = jest.fn((progress) => {
         progressCalls.push(progress);
       });
@@ -221,7 +245,9 @@ describe('Batch Translation Service Integration', () => {
       );
 
       expect(result.successful).toHaveLength(1);
-      expect(result.successful[0]?.outputPath).toBe(path.join(tmpDir, 'test.es.txt'));
+      expect(result.successful[0]?.outputPath).toBe(
+        path.join(tmpDir, 'test.es.txt')
+      );
     });
 
     it('should use custom output pattern', async () => {
@@ -239,7 +265,9 @@ describe('Batch Translation Service Integration', () => {
       );
 
       expect(result.successful).toHaveLength(1);
-      expect(result.successful[0]?.outputPath).toBe(path.join(tmpDir, 'test-es.txt'));
+      expect(result.successful[0]?.outputPath).toBe(
+        path.join(tmpDir, 'test-es.txt')
+      );
     });
 
     it('should preserve directory structure when baseDir is provided', async () => {
@@ -418,9 +446,15 @@ describe('Batch Translation Service Integration', () => {
   describe('getStatistics', () => {
     it('should calculate statistics correctly', () => {
       const result = {
-        successful: [{ file: 'a', outputPath: 'a.es' }, { file: 'b', outputPath: 'b.es' }],
+        successful: [
+          { file: 'a', outputPath: 'a.es' },
+          { file: 'b', outputPath: 'b.es' },
+        ],
         failed: [{ file: 'c', error: 'Error' }],
-        skipped: [{ file: 'd', reason: 'Unsupported' }, { file: 'e', reason: 'Unsupported' }],
+        skipped: [
+          { file: 'd', reason: 'Unsupported' },
+          { file: 'e', reason: 'Unsupported' },
+        ],
       };
 
       const stats = batchService.getStatistics(result);
@@ -452,7 +486,11 @@ describe('Batch Translation Service Integration', () => {
 
     beforeEach(() => {
       const mockCache = createMockCacheService();
-      const isolatedTranslationService = new TranslationService(client, mockConfig, mockCache);
+      const isolatedTranslationService = new TranslationService(
+        client,
+        mockConfig,
+        mockCache
+      );
       batchServiceWithTranslation = new BatchTranslationService(
         new FileTranslationService(isolatedTranslationService),
         { concurrency: 5, translationService: isolatedTranslationService }
@@ -477,10 +515,12 @@ describe('Batch Translation Service Integration', () => {
           return Array.isArray(texts) && texts.length === 5;
         })
         .reply(200, {
-          translations: Array(5).fill(null).map((_, i) => ({
-            text: `Texto número ${i}`,
-            detected_source_language: 'EN',
-          })),
+          translations: Array(5)
+            .fill(null)
+            .map((_, i) => ({
+              text: `Texto número ${i}`,
+              detected_source_language: 'EN',
+            })),
         });
 
       const result = await batchServiceWithTranslation.translateDirectory(
@@ -519,9 +559,7 @@ describe('Batch Translation Service Integration', () => {
       const jsonScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
-          translations: [
-            { text: 'Hola', detected_source_language: 'EN' },
-          ],
+          translations: [{ text: 'Hola', detected_source_language: 'EN' }],
         });
 
       const result = await batchServiceWithTranslation.translateDirectory(
diff --git a/tests/integration/cli-auth.integration.test.ts b/tests/integration/cli-auth.integration.test.ts
index 2e0177ec..69ccb22b 100644
--- a/tests/integration/cli-auth.integration.test.ts
+++ b/tests/integration/cli-auth.integration.test.ts
@@ -10,7 +10,9 @@ import { createTestConfigDir, makeRunCLI } from '../helpers';
 describe('Auth CLI Integration', () => {
   const testConfig = createTestConfigDir('auth');
   const configPath = path.join(testConfig.path, 'config.json');
-  const { runCLI, runCLIAll } = makeRunCLI(testConfig.path, { excludeApiKey: true });
+  const { runCLI, runCLIAll } = makeRunCLI(testConfig.path, {
+    excludeApiKey: true,
+  });
 
   afterAll(() => {
     testConfig.cleanup();
@@ -29,7 +31,9 @@ describe('Auth CLI Integration', () => {
       try {
         runCLI('deepl auth set-key ""');
       } catch (error: any) {
-        expect(error.stderr ?? error.stdout).toContain('API key cannot be empty');
+        expect(error.stderr ?? error.stdout).toContain(
+          'API key cannot be empty'
+        );
       }
     });
 
diff --git a/tests/integration/cli-completion.integration.test.ts b/tests/integration/cli-completion.integration.test.ts
index 2033aa72..2ccfabcc 100644
--- a/tests/integration/cli-completion.integration.test.ts
+++ b/tests/integration/cli-completion.integration.test.ts
@@ -2,7 +2,9 @@ import { createTestConfigDir, makeRunCLI } from '../helpers';
 
 describe('Completion CLI Integration', () => {
   const testConfig = createTestConfigDir('completion');
-  const { runCLI, runCLIAll } = makeRunCLI(testConfig.path, { excludeApiKey: true });
+  const { runCLI, runCLIAll } = makeRunCLI(testConfig.path, {
+    excludeApiKey: true,
+  });
 
   afterAll(() => {
     testConfig.cleanup();
@@ -20,9 +22,19 @@ describe('Completion CLI Integration', () => {
     it('should include all registered top-level commands', () => {
       const output = runCLI('deepl completion bash');
       const expectedCommands = [
-        'translate', 'auth', 'usage', 'languages', 'watch',
-        'write', 'config', 'cache', 'glossary', 'hooks',
-        'style-rules', 'admin', 'completion',
+        'translate',
+        'auth',
+        'usage',
+        'languages',
+        'watch',
+        'write',
+        'config',
+        'cache',
+        'glossary',
+        'hooks',
+        'style-rules',
+        'admin',
+        'completion',
       ];
       for (const cmd of expectedCommands) {
         expect(output).toContain(cmd);
diff --git a/tests/integration/cli-config-file.integration.test.ts b/tests/integration/cli-config-file.integration.test.ts
index 4f6cf7b4..d38d3396 100644
--- a/tests/integration/cli-config-file.integration.test.ts
+++ b/tests/integration/cli-config-file.integration.test.ts
@@ -9,7 +9,10 @@ import * as os from 'os';
 import { makeRunCLI } from '../helpers';
 
 describe('CLI --config flag integration', () => {
-  const testDir = path.join(os.tmpdir(), `.deepl-cli-config-test-${Date.now()}`);
+  const testDir = path.join(
+    os.tmpdir(),
+    `.deepl-cli-config-test-${Date.now()}`
+  );
   const customConfigPath = path.join(testDir, 'custom-config.json');
   const defaultConfigDir = path.join(testDir, '.deepl-cli-default');
   const defaultConfigPath = path.join(defaultConfigDir, 'config.json');
@@ -39,11 +42,15 @@ describe('CLI --config flag integration', () => {
     const defaultConfig = {
       auth: { apiKey: 'default-test-key' },
       api: { baseUrl: 'https://api.deepl.com', usePro: true },
-      defaults: { sourceLang: undefined, targetLangs: [], formality: 'default', preserveFormatting: true },
+      defaults: {
+        sourceLang: undefined,
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: true,
+      },
       cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: true },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
-
     };
     fs.writeFileSync(defaultConfigPath, JSON.stringify(defaultConfig, null, 2));
 
@@ -51,11 +58,15 @@ describe('CLI --config flag integration', () => {
     const customConfig = {
       auth: { apiKey: 'custom-test-key' },
       api: { baseUrl: 'https://api-free.deepl.com', usePro: false },
-      defaults: { sourceLang: 'en', targetLangs: ['es', 'fr'], formality: 'more', preserveFormatting: false },
+      defaults: {
+        sourceLang: 'en',
+        targetLangs: ['es', 'fr'],
+        formality: 'more',
+        preserveFormatting: false,
+      },
       cache: { enabled: false, maxSize: 104857600, ttl: 86400 },
       output: { format: 'json', verbose: true, color: false },
       watch: { debounceMs: 1000, autoCommit: true, pattern: '*.txt' },
-
     };
     fs.writeFileSync(customConfigPath, JSON.stringify(customConfig, null, 2));
   });
@@ -74,17 +85,23 @@ describe('CLI --config flag integration', () => {
     });
 
     it('should use custom config when --config is specified', () => {
-      const output = runCLI(`deepl --config "${customConfigPath}" config get auth.apiKey`);
+      const output = runCLI(
+        `deepl --config "${customConfigPath}" config get auth.apiKey`
+      );
       expect(output.trim()).toBe('"cust...-key"');
     });
 
     it('should read nested config values from custom config', () => {
-      const output = runCLI(`deepl --config "${customConfigPath}" config get api.usePro`);
+      const output = runCLI(
+        `deepl --config "${customConfigPath}" config get api.usePro`
+      );
       expect(output.trim()).toBe('false');
     });
 
     it('should read array values from custom config', () => {
-      const output = runCLI(`deepl --config "${customConfigPath}" config get defaults.targetLangs`);
+      const output = runCLI(
+        `deepl --config "${customConfigPath}" config get defaults.targetLangs`
+      );
       const parsed = JSON.parse(output.trim());
       expect(parsed).toEqual(['es', 'fr']);
     });
@@ -99,13 +116,17 @@ describe('CLI --config flag integration', () => {
     });
 
     it('should write to custom config when --config is specified', () => {
-      runCLI(`deepl --config "${customConfigPath}" config set api.baseUrl https://custom.api.com`);
+      runCLI(
+        `deepl --config "${customConfigPath}" config set api.baseUrl https://custom.api.com`
+      );
 
       const config = JSON.parse(fs.readFileSync(customConfigPath, 'utf-8'));
       expect(config.api.baseUrl).toBe('https://custom.api.com');
 
       // Verify default config is unchanged
-      const defaultConfig = JSON.parse(fs.readFileSync(defaultConfigPath, 'utf-8'));
+      const defaultConfig = JSON.parse(
+        fs.readFileSync(defaultConfigPath, 'utf-8')
+      );
       expect(defaultConfig.api.baseUrl).toBe('https://api.deepl.com');
     });
   });
@@ -132,7 +153,9 @@ describe('CLI --config flag integration', () => {
   describe('auth command', () => {
     it('should set API key in custom config file', () => {
       // Use config set instead of auth set-key to bypass validation
-      runCLI(`deepl --config "${customConfigPath}" config set auth.apiKey new-custom-key`);
+      runCLI(
+        `deepl --config "${customConfigPath}" config set auth.apiKey new-custom-key`
+      );
 
       const config = JSON.parse(fs.readFileSync(customConfigPath, 'utf-8'));
       expect(config.auth.apiKey).toBe('new-custom-key');
@@ -144,7 +167,9 @@ describe('CLI --config flag integration', () => {
       const nonExistentPath = path.join(testDir, 'nonexistent.json');
 
       // Config file doesn't exist, so it should load defaults (apiKey is undefined)
-      const output = runCLI(`deepl --config "${nonExistentPath}" config get auth.apiKey`);
+      const output = runCLI(
+        `deepl --config "${nonExistentPath}" config get auth.apiKey`
+      );
       expect(output.trim()).toBe('null'); // undefined becomes null in JSON output
     });
 
@@ -160,7 +185,9 @@ describe('CLI --config flag integration', () => {
 
   describe('integration with other commands', () => {
     it('should use custom config API key for auth show', () => {
-      const output = runCLIAll(`deepl --config "${customConfigPath}" auth show`);
+      const output = runCLIAll(
+        `deepl --config "${customConfigPath}" auth show`
+      );
       expect(output).toContain('cust');
       expect(output).toContain('-key'); // Masked key
     });
@@ -170,7 +197,9 @@ describe('CLI --config flag integration', () => {
       expect(fs.existsSync(newConfigPath)).toBe(false);
 
       // Use config set instead of auth set-key to bypass validation
-      runCLI(`deepl --config "${newConfigPath}" config set auth.apiKey brand-new-key`);
+      runCLI(
+        `deepl --config "${newConfigPath}" config set auth.apiKey brand-new-key`
+      );
 
       expect(fs.existsSync(newConfigPath)).toBe(true);
       const config = JSON.parse(fs.readFileSync(newConfigPath, 'utf-8'));
@@ -221,17 +250,29 @@ describe('CLI --config flag integration', () => {
 
     it('should accept --config path with .json extension (case-insensitive)', () => {
       const upperCasePath = path.join(testDir, 'config.JSON');
-      fs.writeFileSync(upperCasePath, JSON.stringify({
-        auth: { apiKey: 'upper-case-key' },
-        api: { baseUrl: 'https://api.deepl.com', usePro: true },
-        defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
-        cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
-        output: { format: 'text', verbose: false, color: true },
-        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
-
-      }, null, 2));
-
-      const output = runCLI(`deepl --config "${upperCasePath}" config get auth.apiKey`);
+      fs.writeFileSync(
+        upperCasePath,
+        JSON.stringify(
+          {
+            auth: { apiKey: 'upper-case-key' },
+            api: { baseUrl: 'https://api.deepl.com', usePro: true },
+            defaults: {
+              targetLangs: [],
+              formality: 'default',
+              preserveFormatting: true,
+            },
+            cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
+            output: { format: 'text', verbose: false, color: true },
+            watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+          },
+          null,
+          2
+        )
+      );
+
+      const output = runCLI(
+        `deepl --config "${upperCasePath}" config get auth.apiKey`
+      );
       expect(output.trim()).toContain('uppe');
     });
 
@@ -239,26 +280,36 @@ describe('CLI --config flag integration', () => {
       const newPath = path.join(testDir, 'brand-new.json');
       expect(fs.existsSync(newPath)).toBe(false);
 
-      const output = runCLI(`deepl --config "${newPath}" config get auth.apiKey`);
+      const output = runCLI(
+        `deepl --config "${newPath}" config get auth.apiKey`
+      );
       expect(output.trim()).toBe('null');
     });
   });
 
   describe('precedence and isolation', () => {
     it('should not affect default config when using custom config', () => {
-      const originalDefault = JSON.parse(fs.readFileSync(defaultConfigPath, 'utf-8'));
+      const originalDefault = JSON.parse(
+        fs.readFileSync(defaultConfigPath, 'utf-8')
+      );
 
       // Modify custom config
-      runCLI(`deepl --config "${customConfigPath}" config set api.baseUrl https://changed.com`);
+      runCLI(
+        `deepl --config "${customConfigPath}" config set api.baseUrl https://changed.com`
+      );
 
       // Check default config is unchanged
-      const currentDefault = JSON.parse(fs.readFileSync(defaultConfigPath, 'utf-8'));
+      const currentDefault = JSON.parse(
+        fs.readFileSync(defaultConfigPath, 'utf-8')
+      );
       expect(currentDefault).toEqual(originalDefault);
     });
 
     it('should handle relative paths for --config', () => {
       const relativeConfigPath = path.relative(process.cwd(), customConfigPath);
-      const output = runCLI(`deepl --config "${relativeConfigPath}" config get auth.apiKey`);
+      const output = runCLI(
+        `deepl --config "${relativeConfigPath}" config get auth.apiKey`
+      );
       expect(output.trim()).toBe('"cust...-key"');
     });
   });
diff --git a/tests/integration/cli-config.integration.test.ts b/tests/integration/cli-config.integration.test.ts
index e4fc7f0e..4d612829 100644
--- a/tests/integration/cli-config.integration.test.ts
+++ b/tests/integration/cli-config.integration.test.ts
@@ -47,7 +47,6 @@ describe('Config CLI Integration', () => {
         autoCommit: false,
         pattern: '**/*',
       },
-
     };
 
     fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
@@ -200,7 +199,10 @@ describe('Config CLI Integration', () => {
     const ANSI_REGEX = /\x1b\[/;
 
     // Success messages go to stderr via Logger.success, so redirect stderr to stdout
-    const runCLIWithStderr = (command: string, extraEnv?: Record<string, string>): string => {
+    const runCLIWithStderr = (
+      command: string,
+      extraEnv?: Record<string, string>
+    ): string => {
       return execSync(`${command} 2>&1`, {
         encoding: 'utf-8',
         env: { ...process.env, DEEPL_CONFIG_DIR: testConfigDir, ...extraEnv },
@@ -224,7 +226,9 @@ describe('Config CLI Integration', () => {
       // Run a command that produces colored output
       // Force color output by setting FORCE_COLOR=1 (chalk respects this)
       // Capture stderr where Logger.success writes
-      const output = runCLIWithStderr('deepl config set cache.enabled true', { FORCE_COLOR: '1' });
+      const output = runCLIWithStderr('deepl config set cache.enabled true', {
+        FORCE_COLOR: '1',
+      });
 
       expect(output).toMatch(ANSI_REGEX);
     });
diff --git a/tests/integration/cli-correct.integration.test.ts b/tests/integration/cli-correct.integration.test.ts
index ab0046fe..aa0912b2 100644
--- a/tests/integration/cli-correct.integration.test.ts
+++ b/tests/integration/cli-correct.integration.test.ts
@@ -20,7 +20,10 @@ describe('Correct Command Integration', () => {
   let writeService: WriteService;
   let configService: ConfigService;
   let cacheService: CacheService;
-  const testDir = path.join(os.tmpdir(), `.deepl-cli-correct-int-${Date.now()}`);
+  const testDir = path.join(
+    os.tmpdir(),
+    `.deepl-cli-correct-int-${Date.now()}`
+  );
 
   beforeEach(() => {
     fs.mkdirSync(testDir, { recursive: true });
@@ -36,7 +39,11 @@ describe('Correct Command Integration', () => {
     client.destroy();
     nock.abortPendingRequests();
     nock.cleanAll();
-    try { cacheService.close(); } catch { /* ignore */ }
+    try {
+      cacheService.close();
+    } catch {
+      /* ignore */
+    }
     fs.rmSync(testDir, { recursive: true, force: true });
   });
 
@@ -54,7 +61,9 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'This is a test.', target_language: 'en-US' }],
         });
 
-      const result = await writeService.correct('This is an test.', { targetLang: 'en-us' });
+      const result = await writeService.correct('This is an test.', {
+        targetLang: 'en-us',
+      });
 
       expect(result).toHaveLength(1);
       expect(result[0]?.text).toBe('This is a test.');
@@ -69,7 +78,13 @@ describe('Correct Command Integration', () => {
           return true;
         })
         .reply(200, {
-          improvements: [{ text: 'Das ist ein Test.', target_language: 'de', detected_source_language: 'de' }],
+          improvements: [
+            {
+              text: 'Das ist ein Test.',
+              target_language: 'de',
+              detected_source_language: 'de',
+            },
+          ],
         });
 
       const result = await writeService.correct('Das ist ein Testt.');
@@ -90,7 +105,9 @@ describe('Correct Command Integration', () => {
           ],
         });
 
-      const result = await writeService.correct('This is an test.', { targetLang: 'en-us' });
+      const result = await writeService.correct('This is an test.', {
+        targetLang: 'en-us',
+      });
 
       expect(result).toHaveLength(2);
       expect(result[0]?.text).toBe('This is a test.');
@@ -98,11 +115,9 @@ describe('Correct Command Integration', () => {
     });
 
     it('should throw error for empty improvements array from API', async () => {
-      nock(FREE_API_URL)
-        .post('/v2/write/correct')
-        .reply(200, {
-          improvements: [],
-        });
+      nock(FREE_API_URL).post('/v2/write/correct').reply(200, {
+        improvements: [],
+      });
 
       await expect(
         writeService.correct('Perfect text.', { targetLang: 'en-us' })
@@ -112,7 +127,9 @@ describe('Correct Command Integration', () => {
     it('should not touch the rephrase endpoint', async () => {
       const rephraseScope = nock(FREE_API_URL)
         .post('/v2/write/rephrase')
-        .reply(200, { improvements: [{ text: 'x', target_language: 'en-US' }] });
+        .reply(200, {
+          improvements: [{ text: 'x', target_language: 'en-US' }],
+        });
       nock(FREE_API_URL)
         .post('/v2/write/correct')
         .reply(200, {
@@ -163,7 +180,9 @@ describe('Correct Command Integration', () => {
         .post('/v2/write/correct')
         .reply(200, { improvements: [] });
 
-      await expect(writeService.correct('', {})).rejects.toThrow('Text cannot be empty');
+      await expect(writeService.correct('', {})).rejects.toThrow(
+        'Text cannot be empty'
+      );
       expect(scope.isDone()).toBe(false);
     });
   });
@@ -177,8 +196,12 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'This is a test.', target_language: 'en-US' }],
         });
 
-      const first = await writeService.correct('This is an test.', { targetLang: 'en-us' });
-      const second = await writeService.correct('This is an test.', { targetLang: 'en-us' });
+      const first = await writeService.correct('This is an test.', {
+        targetLang: 'en-us',
+      });
+      const second = await writeService.correct('This is an test.', {
+        targetLang: 'en-us',
+      });
 
       expect(first).toEqual(second);
       expect(scope.isDone()).toBe(true);
@@ -199,8 +222,12 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'Rephrased.', target_language: 'en-US' }],
         });
 
-      const corrected = await writeService.correct('Same text.', { targetLang: 'en-us' });
-      const improved = await writeService.improve('Same text.', { targetLang: 'en-us' });
+      const corrected = await writeService.correct('Same text.', {
+        targetLang: 'en-us',
+      });
+      const improved = await writeService.improve('Same text.', {
+        targetLang: 'en-us',
+      });
 
       expect(corrected[0]?.text).toBe('Corrected.');
       expect(improved[0]?.text).toBe('Rephrased.');
@@ -216,8 +243,16 @@ describe('Correct Command Integration', () => {
           improvements: [{ text: 'This is a test.', target_language: 'en-US' }],
         });
 
-      await writeService.correct('This is an test.', { targetLang: 'en-us' }, { skipCache: true });
-      await writeService.correct('This is an test.', { targetLang: 'en-us' }, { skipCache: true });
+      await writeService.correct(
+        'This is an test.',
+        { targetLang: 'en-us' },
+        { skipCache: true }
+      );
+      await writeService.correct(
+        'This is an test.',
+        { targetLang: 'en-us' },
+        { skipCache: true }
+      );
 
       expect(scope.isDone()).toBe(true);
     });
@@ -234,7 +269,9 @@ describe('Correct Command Integration', () => {
           ],
         });
 
-      const result = await writeService.getBestCorrection('Test', { targetLang: 'en-us' });
+      const result = await writeService.getBestCorrection('Test', {
+        targetLang: 'en-us',
+      });
 
       expect(result.text).toBe('Best correction.');
     });
diff --git a/tests/integration/cli-detect.integration.test.ts b/tests/integration/cli-detect.integration.test.ts
index cbe55569..f71fb2e8 100644
--- a/tests/integration/cli-detect.integration.test.ts
+++ b/tests/integration/cli-detect.integration.test.ts
@@ -10,11 +10,18 @@ describe('Detect CLI Integration', () => {
   const testConfig = createTestConfigDir('detect');
   const { runCLI } = makeRunCLI(testConfig.path);
 
-  const runCLIExpectFail = (command: string, options: { env?: Record<string, string | undefined> } = {}): string => {
+  const runCLIExpectFail = (
+    command: string,
+    options: { env?: Record<string, string | undefined> } = {}
+  ): string => {
     try {
       execSync(command, {
         encoding: 'utf-8',
-        env: { ...process.env, DEEPL_CONFIG_DIR: testConfig.path, ...options.env },
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: testConfig.path,
+          ...options.env,
+        },
         stdio: ['pipe', 'pipe', 'pipe'],
       });
       throw new Error('Expected command to fail');
@@ -74,10 +81,9 @@ describe('Detect CLI Integration', () => {
 
   describe('deepl detect without API key', () => {
     it('should fail with API key error when no key configured', () => {
-      const output = runCLIExpectFail(
-        'deepl detect "Bonjour le monde"',
-        { env: { DEEPL_API_KEY: '' } },
-      );
+      const output = runCLIExpectFail('deepl detect "Bonjour le monde"', {
+        env: { DEEPL_API_KEY: '' },
+      });
 
       expect(output).toMatch(/API key|not set/i);
     });
@@ -85,10 +91,9 @@ describe('Detect CLI Integration', () => {
 
   describe('deepl detect argument validation', () => {
     it('should show error when no text provided and stdin is empty', () => {
-      const output = runCLIExpectFail(
-        'echo "" | deepl detect',
-        { env: { DEEPL_API_KEY: 'fake-key-for-validation' } },
-      );
+      const output = runCLIExpectFail('echo "" | deepl detect', {
+        env: { DEEPL_API_KEY: 'fake-key-for-validation' },
+      });
 
       expect(output.length).toBeGreaterThan(0);
     });
diff --git a/tests/integration/cli-document-translation.integration.test.ts b/tests/integration/cli-document-translation.integration.test.ts
index 72689c9b..41417bcc 100644
--- a/tests/integration/cli-document-translation.integration.test.ts
+++ b/tests/integration/cli-document-translation.integration.test.ts
@@ -51,7 +51,7 @@ describe('Document Translation Integration', () => {
      */
     const uploadWith = async (
       glossary: { glossaryId?: string; glossaryIds?: string[] },
-      label: string,
+      label: string
     ): Promise<string> => {
       const client = new DeepLClient(API_KEY, { maxRetries: 0 });
       clients.push(client);
@@ -67,11 +67,18 @@ describe('Document Translation Integration', () => {
           capturedBody = body;
           return true;
         })
-        .reply(200, { document_id: `doc-${label}`, document_key: `key-${label}` });
+        .reply(200, {
+          document_id: `doc-${label}`,
+          document_key: `key-${label}`,
+        });
 
       nock(FREE_API_URL)
         .post(`/v2/document/doc-${label}`)
-        .reply(200, { document_id: `doc-${label}`, status: 'done', billed_characters: 10 });
+        .reply(200, {
+          document_id: `doc-${label}`,
+          status: 'done',
+          billed_characters: 10,
+        });
 
       nock(FREE_API_URL)
         .post(`/v2/document/doc-${label}/result`)
@@ -262,13 +269,11 @@ describe('Document Translation Integration', () => {
         })
         .reply(200, { document_id: 'd1', document_key: 'k1' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/d1')
-        .reply(200, {
-          document_id: 'd1',
-          status: 'done',
-          billed_characters: 5,
-        });
+      nock(FREE_API_URL).post('/v2/document/d1').reply(200, {
+        document_id: 'd1',
+        status: 'done',
+        billed_characters: 5,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/d1/result')
@@ -297,13 +302,11 @@ describe('Document Translation Integration', () => {
         })
         .reply(200, { document_id: 'd2', document_key: 'k2' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/d2')
-        .reply(200, {
-          document_id: 'd2',
-          status: 'done',
-          billed_characters: 4,
-        });
+      nock(FREE_API_URL).post('/v2/document/d2').reply(200, {
+        document_id: 'd2',
+        status: 'done',
+        billed_characters: 4,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/d2/result')
@@ -333,13 +336,11 @@ describe('Document Translation Integration', () => {
         })
         .reply(200, { document_id: 'd3', document_key: 'k3' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/d3')
-        .reply(200, {
-          document_id: 'd3',
-          status: 'done',
-          billed_characters: 4,
-        });
+      nock(FREE_API_URL).post('/v2/document/d3').reply(200, {
+        document_id: 'd3',
+        status: 'done',
+        billed_characters: 4,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/d3/result')
@@ -369,13 +370,11 @@ describe('Document Translation Integration', () => {
         })
         .reply(200, { document_id: 'd4', document_key: 'k4' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/d4')
-        .reply(200, {
-          document_id: 'd4',
-          status: 'done',
-          billed_characters: 4,
-        });
+      nock(FREE_API_URL).post('/v2/document/d4').reply(200, {
+        document_id: 'd4',
+        status: 'done',
+        billed_characters: 4,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/d4/result')
@@ -405,13 +404,11 @@ describe('Document Translation Integration', () => {
         })
         .reply(200, { document_id: 'd5', document_key: 'k5' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/d5')
-        .reply(200, {
-          document_id: 'd5',
-          status: 'done',
-          billed_characters: 12,
-        });
+      nock(FREE_API_URL).post('/v2/document/d5').reply(200, {
+        document_id: 'd5',
+        status: 'done',
+        billed_characters: 12,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/d5/result')
@@ -440,13 +437,11 @@ describe('Document Translation Integration', () => {
         })
         .reply(200, { document_id: 'd6', document_key: 'k6' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/d6')
-        .reply(200, {
-          document_id: 'd6',
-          status: 'done',
-          billed_characters: 12,
-        });
+      nock(FREE_API_URL).post('/v2/document/d6').reply(200, {
+        document_id: 'd6',
+        status: 'done',
+        billed_characters: 12,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/d6/result')
@@ -476,13 +471,11 @@ describe('Document Translation Integration', () => {
         .post('/v2/document')
         .reply(200, { document_id: 'da', document_key: 'ka' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/da')
-        .reply(200, {
-          document_id: 'da',
-          status: 'done',
-          billed_characters: 4,
-        });
+      nock(FREE_API_URL).post('/v2/document/da').reply(200, {
+        document_id: 'da',
+        status: 'done',
+        billed_characters: 4,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/da/result')
@@ -549,13 +542,11 @@ describe('Document Translation Integration', () => {
         .post('/v2/document')
         .reply(200, { document_id: 'dd1', document_key: 'kd1' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/dd1')
-        .reply(200, {
-          document_id: 'dd1',
-          status: 'done',
-          billed_characters: 4,
-        });
+      nock(FREE_API_URL).post('/v2/document/dd1').reply(200, {
+        document_id: 'dd1',
+        status: 'done',
+        billed_characters: 4,
+      });
 
       const downloadScope = nock(FREE_API_URL, {
         reqheaders: {
@@ -587,13 +578,11 @@ describe('Document Translation Integration', () => {
         .post('/v2/document')
         .reply(200, { document_id: 'db1', document_key: 'kb1' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/db1')
-        .reply(200, {
-          document_id: 'db1',
-          status: 'done',
-          billed_characters: 100,
-        });
+      nock(FREE_API_URL).post('/v2/document/db1').reply(200, {
+        document_id: 'db1',
+        status: 'done',
+        billed_characters: 100,
+      });
 
       const pdfBytes = Buffer.from([
         0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34,
@@ -785,13 +774,11 @@ describe('Document Translation Integration', () => {
         .post('/v2/document')
         .reply(200, { document_id: 'ddl1', document_key: 'kdl1' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/ddl1')
-        .reply(200, {
-          document_id: 'ddl1',
-          status: 'done',
-          billed_characters: 4,
-        });
+      nock(FREE_API_URL).post('/v2/document/ddl1').reply(200, {
+        document_id: 'ddl1',
+        status: 'done',
+        billed_characters: 4,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/ddl1/result')
@@ -815,13 +802,11 @@ describe('Document Translation Integration', () => {
         .post('/v2/document')
         .reply(200, { document_id: 'ddl2', document_key: 'kdl2' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/ddl2')
-        .reply(200, {
-          document_id: 'ddl2',
-          status: 'done',
-          billed_characters: 4,
-        });
+      nock(FREE_API_URL).post('/v2/document/ddl2').reply(200, {
+        document_id: 'ddl2',
+        status: 'done',
+        billed_characters: 4,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/ddl2/result')
@@ -852,13 +837,11 @@ describe('Document Translation Integration', () => {
         .post('/v2/document')
         .reply(200, { document_id: 'dm1', document_key: 'km1' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/dm1')
-        .reply(200, {
-          document_id: 'dm1',
-          status: 'done',
-          billed_characters: 4,
-        });
+      nock(FREE_API_URL).post('/v2/document/dm1').reply(200, {
+        document_id: 'dm1',
+        status: 'done',
+        billed_characters: 4,
+      });
 
       nock(FREE_API_URL)
         .post('/v2/document/dm1/result')
@@ -910,13 +893,11 @@ describe('Document Translation Integration', () => {
         .post('/v2/document')
         .reply(200, { document_id: 'da1', document_key: 'ka1' });
 
-      nock(FREE_API_URL)
-        .post('/v2/document/da1')
-        .reply(200, {
-          document_id: 'da1',
-          status: 'translating',
-          seconds_remaining: 60,
-        });
+      nock(FREE_API_URL).post('/v2/document/da1').reply(200, {
+        document_id: 'da1',
+        status: 'translating',
+        seconds_remaining: 60,
+      });
 
       const controller = new AbortController();
 
diff --git a/tests/integration/cli-dry-run.integration.test.ts b/tests/integration/cli-dry-run.integration.test.ts
index 5941aa02..4694ae45 100644
--- a/tests/integration/cli-dry-run.integration.test.ts
+++ b/tests/integration/cli-dry-run.integration.test.ts
@@ -95,10 +95,13 @@ describe('--dry-run CLI Integration', () => {
     // A dry run reports a command as runnable, so it has to reject whatever the
     // real run rejects locally, with the same message and exit code.
     it('should reject a malformed target language code', () => {
-      const result = runCLIExpectError(`deepl translate "Hi" --to 'not!!a!!lang' --dry-run`, {
-        excludeApiKey: true,
-        noColor: true,
-      });
+      const result = runCLIExpectError(
+        `deepl translate "Hi" --to 'not!!a!!lang' --dry-run`,
+        {
+          excludeApiKey: true,
+          noColor: true,
+        }
+      );
 
       expect(result.status).toBe(ExitCode.InvalidInput);
       expect(result.output).toContain('Invalid target language code');
@@ -108,7 +111,7 @@ describe('--dry-run CLI Integration', () => {
     it('should reject a malformed source language code', () => {
       const result = runCLIExpectError(
         `deepl translate "Hi" --to de --from 'not!!a!!lang' --dry-run`,
-        { excludeApiKey: true, noColor: true },
+        { excludeApiKey: true, noColor: true }
       );
 
       expect(result.status).toBe(ExitCode.InvalidInput);
@@ -116,10 +119,13 @@ describe('--dry-run CLI Integration', () => {
     });
 
     it('should reject formality for an extended-tier target', () => {
-      const result = runCLIExpectError(`deepl translate "Hi" --to af --formality more --dry-run`, {
-        excludeApiKey: true,
-        noColor: true,
-      });
+      const result = runCLIExpectError(
+        `deepl translate "Hi" --to af --formality more --dry-run`,
+        {
+          excludeApiKey: true,
+          noColor: true,
+        }
+      );
 
       expect(result.status).toBe(ExitCode.InvalidInput);
       expect(result.output).toContain('do not support formality');
@@ -128,7 +134,7 @@ describe('--dry-run CLI Integration', () => {
     it('should reject a glossary for an extended-tier target', () => {
       const result = runCLIExpectError(
         `deepl translate "Hi" --to af --from en --glossary my-glossary --dry-run`,
-        { excludeApiKey: true, noColor: true },
+        { excludeApiKey: true, noColor: true }
       );
 
       expect(result.status).toBe(ExitCode.InvalidInput);
@@ -141,7 +147,7 @@ describe('--dry-run CLI Integration', () => {
 
       const output = runCLI(
         `deepl translate "${testFile}" --to af --model-type latency_optimized --output "${testFiles.path}/out.pdf" --dry-run`,
-        { excludeApiKey: true, noColor: true },
+        { excludeApiKey: true, noColor: true }
       );
 
       expect(output).toContain('Would translate file');
@@ -154,7 +160,7 @@ describe('--dry-run CLI Integration', () => {
 
       const output = runCLI(
         `deepl translate "${dirPath}" --to af --from en --glossary my-glossary --output "${testFiles.path}/out-gdir" --dry-run`,
-        { excludeApiKey: true, noColor: true },
+        { excludeApiKey: true, noColor: true }
       );
 
       expect(output).toContain('Would translate directory');
@@ -166,25 +172,32 @@ describe('--dry-run CLI Integration', () => {
         noColor: true,
       });
 
-      const notices = output.match(/is not in the bundled language list/g) ?? [];
+      const notices =
+        output.match(/is not in the bundled language list/g) ?? [];
       expect(notices).toHaveLength(1);
       expect(output).toContain('"ex" is not in the bundled language list');
     });
 
     it('should warn about an unknown source language too', () => {
-      const output = runCLIAll(`deepl translate "Hi" --to de --from zz --dry-run`, {
-        excludeApiKey: true,
-        noColor: true,
-      });
+      const output = runCLIAll(
+        `deepl translate "Hi" --to de --from zz --dry-run`,
+        {
+          excludeApiKey: true,
+          noColor: true,
+        }
+      );
 
       expect(output).toContain('"zz" is not in the bundled language list');
     });
 
     it('should lowercase language codes the way the real run does', () => {
-      const output = runCLI(`deepl translate "Hi" --to DE --from EN --dry-run`, {
-        excludeApiKey: true,
-        noColor: true,
-      });
+      const output = runCLI(
+        `deepl translate "Hi" --to DE --from EN --dry-run`,
+        {
+          excludeApiKey: true,
+          noColor: true,
+        }
+      );
 
       expect(output).toContain('Target language(s): de');
       expect(output).toContain('Source language: en');
@@ -261,9 +274,7 @@ describe('--dry-run CLI Integration', () => {
         fs.mkdirSync(watchDir, { recursive: true });
       }
 
-      const output = runCLI(
-        `deepl watch "${watchDir}" --to es,fr --dry-run`
-      );
+      const output = runCLI(`deepl watch "${watchDir}" --to es,fr --dry-run`);
 
       expect(output).toContain('[dry-run]');
       expect(output).toContain('Watch mode will not be started');
@@ -306,9 +317,7 @@ describe('--dry-run CLI Integration', () => {
         fs.mkdirSync(watchDir, { recursive: true });
       }
 
-      const output = runCLI(
-        `deepl watch "${watchDir}" --to ja --dry-run`
-      );
+      const output = runCLI(`deepl watch "${watchDir}" --to ja --dry-run`);
 
       expect(output).toContain('[dry-run]');
       expect(output).not.toContain('API key');
diff --git a/tests/integration/cli-help-hint.integration.test.ts b/tests/integration/cli-help-hint.integration.test.ts
index 3815b758..f84b34c2 100644
--- a/tests/integration/cli-help-hint.integration.test.ts
+++ b/tests/integration/cli-help-hint.integration.test.ts
@@ -1,4 +1,8 @@
-import { makeNodeRunCLI, createTestConfigDir, type TestConfigDir } from '../helpers/run-cli';
+import {
+  makeNodeRunCLI,
+  createTestConfigDir,
+  type TestConfigDir,
+} from '../helpers/run-cli';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -17,11 +21,15 @@ describe('Getting Started help hint', () => {
     const { runCLI } = makeNodeRunCLI(testDir.path, { excludeApiKey: true });
     const output = runCLI('--help');
 
-    expect(output).toContain('Getting Started: Run deepl init to set up your API key.');
+    expect(output).toContain(
+      'Getting Started: Run deepl init to set up your API key.'
+    );
   });
 
   it('should NOT show Getting Started hint when API key is set via env', () => {
-    const { runCLI } = makeNodeRunCLI(testDir.path, { apiKey: 'test-api-key-1234' });
+    const { runCLI } = makeNodeRunCLI(testDir.path, {
+      apiKey: 'test-api-key-1234',
+    });
     const output = runCLI('--help');
 
     expect(output).not.toContain('Getting Started');
@@ -29,7 +37,10 @@ describe('Getting Started help hint', () => {
 
   it('should NOT show Getting Started hint when API key is in config', () => {
     const configFile = path.join(testDir.path, 'config.json');
-    fs.writeFileSync(configFile, JSON.stringify({ auth: { apiKey: 'test-key-5678' } }));
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({ auth: { apiKey: 'test-key-5678' } })
+    );
 
     const { runCLI } = makeNodeRunCLI(testDir.path, { excludeApiKey: true });
     const output = runCLI('--help');
diff --git a/tests/integration/cli-hooks.integration.test.ts b/tests/integration/cli-hooks.integration.test.ts
index 3e46c95f..6fd2e648 100644
--- a/tests/integration/cli-hooks.integration.test.ts
+++ b/tests/integration/cli-hooks.integration.test.ts
@@ -239,7 +239,12 @@ describe('Git Hooks Service Integration', () => {
     });
 
     it('should return correct path for all hook types', () => {
-      const hookTypes: HookType[] = ['pre-commit', 'pre-push', 'commit-msg', 'post-commit'];
+      const hookTypes: HookType[] = [
+        'pre-commit',
+        'pre-push',
+        'commit-msg',
+        'post-commit',
+      ];
 
       for (const hookType of hookTypes) {
         const hookPath = hooksService.getHookPath(hookType);
diff --git a/tests/integration/cli-languages.integration.test.ts b/tests/integration/cli-languages.integration.test.ts
index a23188c1..1edfacf8 100644
--- a/tests/integration/cli-languages.integration.test.ts
+++ b/tests/integration/cli-languages.integration.test.ts
@@ -69,7 +69,9 @@ describe('Languages CLI Integration', () => {
 
       // Languages command should be listed in main help
       expect(helpOutput).toContain('languages');
-      expect(helpOutput).toContain('List supported source and target languages');
+      expect(helpOutput).toContain(
+        'List supported source and target languages'
+      );
     });
 
     it('should support --source flag', () => {
diff --git a/tests/integration/cli-lazy-cache.integration.test.ts b/tests/integration/cli-lazy-cache.integration.test.ts
index 64d7c0e4..d92b39ef 100644
--- a/tests/integration/cli-lazy-cache.integration.test.ts
+++ b/tests/integration/cli-lazy-cache.integration.test.ts
@@ -13,17 +13,28 @@ describe('Lazy CacheService Instantiation', () => {
   let testHomeDir: string;
   let testConfigDir: string;
   let expectedCachePath: string;
-  let runCLI: (command: string, extraEnv?: Record<string, string | undefined>) => string;
+  let runCLI: (
+    command: string,
+    extraEnv?: Record<string, string | undefined>
+  ) => string;
 
   beforeEach(() => {
-    testHomeDir = path.join(os.tmpdir(), `.deepl-cli-lazy-cache-home-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    testHomeDir = path.join(
+      os.tmpdir(),
+      `.deepl-cli-lazy-cache-home-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
     testConfigDir = path.join(testHomeDir, '.deepl-cli');
     expectedCachePath = path.join(testConfigDir, 'cache.db');
     fs.mkdirSync(testHomeDir, { recursive: true });
 
     const helpers = makeRunCLI(testConfigDir);
-    runCLI = (command: string, extraEnv: Record<string, string | undefined> = {}) => {
-      return helpers.runCLI(command, { env: { HOME: testHomeDir, ...extraEnv } });
+    runCLI = (
+      command: string,
+      extraEnv: Record<string, string | undefined> = {}
+    ) => {
+      return helpers.runCLI(command, {
+        env: { HOME: testHomeDir, ...extraEnv },
+      });
     };
   });
 
diff --git a/tests/integration/cli-no-input.integration.test.ts b/tests/integration/cli-no-input.integration.test.ts
index 74d80b88..9a000412 100644
--- a/tests/integration/cli-no-input.integration.test.ts
+++ b/tests/integration/cli-no-input.integration.test.ts
@@ -29,7 +29,9 @@ describe('--no-input flag', () => {
 
   describe('write --interactive --no-input', () => {
     it('should error with exit code 6', () => {
-      const result = runCLIExpectError('deepl --no-input write "test text" --interactive');
+      const result = runCLIExpectError(
+        'deepl --no-input write "test text" --interactive'
+      );
 
       expect(result.status).toBe(6);
       expect(result.output).toContain('requires an interactive terminal');
diff --git a/tests/integration/cli-structured-file-translate.integration.test.ts b/tests/integration/cli-structured-file-translate.integration.test.ts
index e1887d11..3f5e9b4c 100644
--- a/tests/integration/cli-structured-file-translate.integration.test.ts
+++ b/tests/integration/cli-structured-file-translate.integration.test.ts
@@ -11,13 +11,20 @@ import { FileTranslationService } from '../../src/services/file-translation';
 import { DeepLClient } from '../../src/api/deepl-client';
 import { ConfigService } from '../../src/storage/config';
 import { CacheService } from '../../src/storage/cache';
-import { createTestConfigDir, createTestDir, makeRunCLI, DEEPL_FREE_API_URL } from '../helpers';
+import {
+  createTestConfigDir,
+  createTestDir,
+  makeRunCLI,
+  DEEPL_FREE_API_URL,
+} from '../helpers';
 
 describe('Structured File Translation CLI Integration', () => {
   const testConfig = createTestConfigDir('test-structured');
   const testFiles = createTestDir('structured-files');
   const testDir = testFiles.path;
-  const { runCLI } = makeRunCLI(testConfig.path, { apiKey: 'test-api-key-123' });
+  const { runCLI } = makeRunCLI(testConfig.path, {
+    apiKey: 'test-api-key-123',
+  });
 
   beforeAll(() => {
     fs.writeFileSync(
@@ -25,7 +32,12 @@ describe('Structured File Translation CLI Integration', () => {
       JSON.stringify({
         auth: { apiKey: 'test-api-key-123' },
         api: { baseUrl: 'https://api-free.deepl.com/v2', usePro: false },
-        defaults: { sourceLang: undefined, targetLangs: [], formality: 'default', preserveFormatting: true },
+        defaults: {
+          sourceLang: undefined,
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
         cache: { enabled: false, maxSize: 1073741824, ttl: 2592000 },
       })
     );
@@ -89,7 +101,9 @@ describe('Structured File Translation CLI Integration', () => {
       fs.writeFileSync(testFile, JSON.stringify({ key: 'test' }, null, 2));
 
       expect(() => {
-        runCLI(`deepl translate "${testFile}" --to INVALID --output /tmp/out.json`);
+        runCLI(
+          `deepl translate "${testFile}" --to INVALID --output /tmp/out.json`
+        );
       }).toThrow();
     });
 
@@ -108,7 +122,9 @@ describe('Structured File Translation CLI Integration', () => {
 
       fs.writeFileSync(inputPath, '{}');
 
-      const output = runCLI(`deepl translate "${inputPath}" --to es --output "${outputPath}"`);
+      const output = runCLI(
+        `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+      );
       expect(output).toContain('Translated');
 
       const result = JSON.parse(fs.readFileSync(outputPath, 'utf-8'));
@@ -147,25 +163,43 @@ describe('Structured File Translation CLI Integration', () => {
       const configPath = path.join(svcDir, 'config.json');
       const cachePath = path.join(svcDir, 'cache.db');
       const config = new ConfigService(configPath);
-      cacheService = new CacheService({ dbPath: cachePath, maxSize: 1024 * 100 });
+      cacheService = new CacheService({
+        dbPath: cachePath,
+        maxSize: 1024 * 100,
+      });
       client = new DeepLClient(API_KEY);
-      const translationService = new TranslationService(client, config, cacheService);
+      const translationService = new TranslationService(
+        client,
+        config,
+        cacheService
+      );
       fileTranslationService = new FileTranslationService(translationService);
     });
 
     afterEach(() => {
       client.destroy();
-      try { cacheService.close(); } catch { /* ignore */ }
+      try {
+        cacheService.close();
+      } catch {
+        /* ignore */
+      }
     });
 
     it('should translate flat JSON file via FileTranslationService', async () => {
       const inputPath = path.join(testDir, 'svc-en.json');
       const outputPath = path.join(testDir, 'svc-es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        greeting: 'Hello',
-        farewell: 'Goodbye',
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            farewell: 'Goodbye',
+          },
+          null,
+          2
+        )
+      );
 
       nock(FREE_API_URL)
         .post('/v2/translate')
@@ -176,7 +210,9 @@ describe('Structured File Translation CLI Integration', () => {
           ],
         });
 
-      await fileTranslationService.translateFile(inputPath, outputPath, { targetLang: 'es' });
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       const result = JSON.parse(fs.readFileSync(outputPath, 'utf-8'));
       expect(result.greeting).toBe('Hola');
@@ -187,11 +223,18 @@ describe('Structured File Translation CLI Integration', () => {
       const inputPath = path.join(testDir, 'svc-nested.json');
       const outputPath = path.join(testDir, 'svc-nested-es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        nav: { home: 'Home', about: 'About' },
-        footer: { copyright: 'All rights reserved' },
-        version: 2,
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            nav: { home: 'Home', about: 'About' },
+            footer: { copyright: 'All rights reserved' },
+            version: 2,
+          },
+          null,
+          2
+        )
+      );
 
       nock(FREE_API_URL)
         .post('/v2/translate')
@@ -199,11 +242,16 @@ describe('Structured File Translation CLI Integration', () => {
           translations: [
             { text: 'Inicio', detected_source_language: 'EN' },
             { text: 'Acerca de', detected_source_language: 'EN' },
-            { text: 'Todos los derechos reservados', detected_source_language: 'EN' },
+            {
+              text: 'Todos los derechos reservados',
+              detected_source_language: 'EN',
+            },
           ],
         });
 
-      await fileTranslationService.translateFile(inputPath, outputPath, { targetLang: 'es' });
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       const result = JSON.parse(fs.readFileSync(outputPath, 'utf-8'));
       expect(result.nav.home).toBe('Inicio');
@@ -216,17 +264,20 @@ describe('Structured File Translation CLI Integration', () => {
       const inputPath = path.join(testDir, 'svc-indent.json');
       const outputPath = path.join(testDir, 'svc-indent-es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({ key: 'Hello' }, null, 4) + '\n');
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify({ key: 'Hello' }, null, 4) + '\n'
+      );
 
       nock(FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
-          translations: [
-            { text: 'Hola', detected_source_language: 'EN' },
-          ],
+          translations: [{ text: 'Hola', detected_source_language: 'EN' }],
         });
 
-      await fileTranslationService.translateFile(inputPath, outputPath, { targetLang: 'es' });
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       const raw = fs.readFileSync(outputPath, 'utf-8');
       expect(raw).toContain('    "key"');
@@ -248,7 +299,9 @@ describe('Structured File Translation CLI Integration', () => {
           ],
         });
 
-      await fileTranslationService.translateFile(inputPath, outputPath, { targetLang: 'es' });
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       const raw = fs.readFileSync(outputPath, 'utf-8');
       expect(raw).toContain('greeting: Hola');
@@ -259,21 +312,20 @@ describe('Structured File Translation CLI Integration', () => {
       const inputPath = path.join(testDir, 'svc-comments.yaml');
       const outputPath = path.join(testDir, 'svc-comments-es.yaml');
 
-      fs.writeFileSync(inputPath, [
-        '# Main heading',
-        'greeting: Hello # inline',
-        '',
-      ].join('\n'));
+      fs.writeFileSync(
+        inputPath,
+        ['# Main heading', 'greeting: Hello # inline', ''].join('\n')
+      );
 
       nock(FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
-          translations: [
-            { text: 'Hola', detected_source_language: 'EN' },
-          ],
+          translations: [{ text: 'Hola', detected_source_language: 'EN' }],
         });
 
-      await fileTranslationService.translateFile(inputPath, outputPath, { targetLang: 'es' });
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       const raw = fs.readFileSync(outputPath, 'utf-8');
       expect(raw).toContain('# Main heading');
@@ -284,10 +336,17 @@ describe('Structured File Translation CLI Integration', () => {
       const inputPath = path.join(testDir, 'svc-api-check.json');
       const outputPath = path.join(testDir, 'svc-api-check-es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        title: 'Hello World',
-        count: 42,
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            title: 'Hello World',
+            count: 42,
+          },
+          null,
+          2
+        )
+      );
 
       const scope = nock(FREE_API_URL)
         .post('/v2/translate', (body: any) => {
@@ -303,7 +362,9 @@ describe('Structured File Translation CLI Integration', () => {
           ],
         });
 
-      await fileTranslationService.translateFile(inputPath, outputPath, { targetLang: 'es' });
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -319,9 +380,7 @@ describe('Structured File Translation CLI Integration', () => {
           return true;
         })
         .reply(200, {
-          translations: [
-            { text: 'Hallo', detected_source_language: 'EN' },
-          ],
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
         });
 
       await fileTranslationService.translateFile(inputPath, outputPath, {
@@ -342,7 +401,9 @@ describe('Structured File Translation CLI Integration', () => {
         .reply(403, { message: 'Forbidden' });
 
       await expect(
-        fileTranslationService.translateFile(inputPath, outputPath, { targetLang: 'es' })
+        fileTranslationService.translateFile(inputPath, outputPath, {
+          targetLang: 'es',
+        })
       ).rejects.toThrow();
     });
 
@@ -360,7 +421,9 @@ describe('Structured File Translation CLI Integration', () => {
           ],
         });
 
-      await fileTranslationService.translateFile(inputPath, outputPath, { targetLang: 'es' });
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       const raw = fs.readFileSync(outputPath, 'utf-8');
       expect(raw).toContain('title: Bienvenido');
@@ -369,7 +432,10 @@ describe('Structured File Translation CLI Integration', () => {
     it('should translate file to multiple languages', async () => {
       const inputPath = path.join(testDir, 'svc-multi.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({ greeting: 'Hello' }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify({ greeting: 'Hello' }, null, 2)
+      );
 
       nock(FREE_API_URL)
         .post('/v2/translate', (body: any) => body.target_lang === 'ES')
@@ -391,7 +457,9 @@ describe('Structured File Translation CLI Integration', () => {
       expect(results[0]?.targetLang).toBe('es');
       expect(results[1]?.targetLang).toBe('fr');
 
-      const esResult = JSON.parse(fs.readFileSync(results[0]!.outputPath!, 'utf-8'));
+      const esResult = JSON.parse(
+        fs.readFileSync(results[0]!.outputPath!, 'utf-8')
+      );
       expect(esResult.greeting).toBe('Hola');
     });
   });
diff --git a/tests/integration/cli-style-rules.integration.test.ts b/tests/integration/cli-style-rules.integration.test.ts
index 13ddb716..28114588 100644
--- a/tests/integration/cli-style-rules.integration.test.ts
+++ b/tests/integration/cli-style-rules.integration.test.ts
@@ -54,7 +54,10 @@ describe('Style Rules CLI Integration', () => {
     it('should require API key for style-rules list', () => {
       expect.assertions(1);
       try {
-        runCLI('deepl style-rules list', { stdio: 'pipe', excludeApiKey: true });
+        runCLI('deepl style-rules list', {
+          stdio: 'pipe',
+          excludeApiKey: true,
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).toMatch(/API key|auth|not set/i);
@@ -64,7 +67,10 @@ describe('Style Rules CLI Integration', () => {
     it('should require API key for style-rules list --detailed', () => {
       expect.assertions(1);
       try {
-        runCLI('deepl style-rules list --detailed', { stdio: 'pipe', excludeApiKey: true });
+        runCLI('deepl style-rules list --detailed', {
+          stdio: 'pipe',
+          excludeApiKey: true,
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).toMatch(/API key|auth|not set/i);
@@ -75,7 +81,8 @@ describe('Style Rules CLI Integration', () => {
       expect.assertions(1);
       try {
         runCLI('deepl style-rules list --page 1 --page-size 10', {
-          stdio: 'pipe', excludeApiKey: true,
+          stdio: 'pipe',
+          excludeApiKey: true,
         });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
@@ -146,7 +153,10 @@ describe('Style Rules CLI Integration', () => {
     it('should accept create subcommand with required flags', () => {
       expect.assertions(2);
       try {
-        runCLI('deepl style-rules create --name Foo --language en', { stdio: 'pipe', excludeApiKey: true });
+        runCLI('deepl style-rules create --name Foo --language en', {
+          stdio: 'pipe',
+          excludeApiKey: true,
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).not.toMatch(/unknown.*option/i);
@@ -167,7 +177,10 @@ describe('Style Rules CLI Integration', () => {
     it('should accept show subcommand with positional id', () => {
       expect.assertions(2);
       try {
-        runCLI('deepl style-rules show sr-1', { stdio: 'pipe', excludeApiKey: true });
+        runCLI('deepl style-rules show sr-1', {
+          stdio: 'pipe',
+          excludeApiKey: true,
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).not.toMatch(/unknown.*option/i);
@@ -188,7 +201,10 @@ describe('Style Rules CLI Integration', () => {
     it('should accept update subcommand with --name', () => {
       expect.assertions(2);
       try {
-        runCLI('deepl style-rules update sr-1 --name "New"', { stdio: 'pipe', excludeApiKey: true });
+        runCLI('deepl style-rules update sr-1 --name "New"', {
+          stdio: 'pipe',
+          excludeApiKey: true,
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).not.toMatch(/unknown.*option/i);
@@ -214,7 +230,10 @@ describe('Style Rules CLI Integration', () => {
     it('should accept instructions subcommand with positional style-id', () => {
       expect.assertions(2);
       try {
-        runCLI('deepl style-rules instructions sr-1', { stdio: 'pipe', excludeApiKey: true });
+        runCLI('deepl style-rules instructions sr-1', {
+          stdio: 'pipe',
+          excludeApiKey: true,
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).not.toMatch(/unknown.*option/i);
@@ -235,7 +254,10 @@ describe('Style Rules CLI Integration', () => {
     it('should accept add-instruction with three positional args', () => {
       expect.assertions(2);
       try {
-        runCLI('deepl style-rules add-instruction sr-1 tone "Be formal"', { stdio: 'pipe', excludeApiKey: true });
+        runCLI('deepl style-rules add-instruction sr-1 tone "Be formal"', {
+          stdio: 'pipe',
+          excludeApiKey: true,
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).not.toMatch(/unknown.*option/i);
@@ -246,7 +268,9 @@ describe('Style Rules CLI Integration', () => {
     it('should require all three args on add-instruction', () => {
       expect.assertions(1);
       try {
-        runCLI('deepl style-rules add-instruction sr-1 tone', { stdio: 'pipe' });
+        runCLI('deepl style-rules add-instruction sr-1 tone', {
+          stdio: 'pipe',
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).toMatch(/missing.*argument|prompt.*required/i);
@@ -256,7 +280,10 @@ describe('Style Rules CLI Integration', () => {
     it('should accept update-instruction with three positional args', () => {
       expect.assertions(2);
       try {
-        runCLI('deepl style-rules update-instruction sr-1 tone "Be friendlier"', { stdio: 'pipe', excludeApiKey: true });
+        runCLI(
+          'deepl style-rules update-instruction sr-1 tone "Be friendlier"',
+          { stdio: 'pipe', excludeApiKey: true }
+        );
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).not.toMatch(/unknown.*option/i);
@@ -265,7 +292,9 @@ describe('Style Rules CLI Integration', () => {
     });
 
     it('should accept remove-instruction --dry-run without running', () => {
-      const output = runCLI('deepl style-rules remove-instruction sr-1 tone --dry-run');
+      const output = runCLI(
+        'deepl style-rules remove-instruction sr-1 tone --dry-run'
+      );
       expect(output).toContain('[dry-run]');
       expect(output).toContain('tone');
       expect(output).toContain('sr-1');
@@ -274,7 +303,10 @@ describe('Style Rules CLI Integration', () => {
     it('should accept --source-language on add-instruction', () => {
       expect.assertions(1);
       try {
-        runCLI('deepl style-rules add-instruction sr-1 tone "Be formal" --source-language en', { stdio: 'pipe', excludeApiKey: true });
+        runCLI(
+          'deepl style-rules add-instruction sr-1 tone "Be formal" --source-language en',
+          { stdio: 'pipe', excludeApiKey: true }
+        );
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).not.toMatch(/unknown.*option.*source-language/i);
@@ -835,7 +867,10 @@ describe('Style Rules API Integration', () => {
         })
         .reply(200, styleRuleWire);
 
-      const created = await styleRulesCommand.create({ name: 'Corporate', language: 'en' });
+      const created = await styleRulesCommand.create({
+        name: 'Corporate',
+        language: 'en',
+      });
       expect(created.styleId).toBe('sr-new');
       expect(createScope.isDone()).toBe(true);
 
@@ -857,7 +892,9 @@ describe('Style Rules API Integration', () => {
         })
         .reply(200, { ...styleRuleWire, name: 'Renamed', version: 2 });
 
-      const updated = await styleRulesCommand.update('sr-new', { name: 'Renamed' });
+      const updated = await styleRulesCommand.update('sr-new', {
+        name: 'Renamed',
+      });
       expect(updated.name).toBe('Renamed');
       expect(updated.version).toBe(2);
       expect(updateScope.isDone()).toBe(true);
@@ -897,7 +934,8 @@ describe('Style Rules API Integration', () => {
         .reply(200, { label: 'tone', prompt: 'Be formal' });
 
       const created = await styleRulesCommand.addInstruction('sr-new', {
-        label: 'tone', prompt: 'Be formal',
+        label: 'tone',
+        prompt: 'Be formal',
       });
       expect(created).toEqual({ label: 'tone', prompt: 'Be formal' });
       expect(createScope.isDone()).toBe(true);
@@ -912,7 +950,11 @@ describe('Style Rules API Integration', () => {
           configured_rules: {},
           custom_instructions: [
             { label: 'tone', prompt: 'Be formal' },
-            { label: 'register', prompt: 'First person', source_language: 'en' },
+            {
+              label: 'register',
+              prompt: 'First person',
+              source_language: 'en',
+            },
           ],
         });
 
@@ -932,19 +974,32 @@ describe('Style Rules API Integration', () => {
         .reply(200, {
           ...styleRuleWire,
           configured_rules: {},
-          custom_instructions: [{ id: instructionId, label: 'tone', prompt: 'old' }],
+          custom_instructions: [
+            { id: instructionId, label: 'tone', prompt: 'old' },
+          ],
         });
       const updateScope = nock(FREE_API_URL)
-        .put(`/v3/style_rules/sr-new/custom_instructions/${instructionId}`, (body) => {
-          expect(body.label).toBe('tone');
-          expect(body.prompt).toBe('Be friendlier');
-          return true;
-        })
-        .reply(200, { id: instructionId, label: 'tone', prompt: 'Be friendlier' });
+        .put(
+          `/v3/style_rules/sr-new/custom_instructions/${instructionId}`,
+          (body) => {
+            expect(body.label).toBe('tone');
+            expect(body.prompt).toBe('Be friendlier');
+            return true;
+          }
+        )
+        .reply(200, {
+          id: instructionId,
+          label: 'tone',
+          prompt: 'Be friendlier',
+        });
 
-      const updated = await styleRulesCommand.updateInstruction('sr-new', 'tone', {
-        prompt: 'Be friendlier',
-      });
+      const updated = await styleRulesCommand.updateInstruction(
+        'sr-new',
+        'tone',
+        {
+          prompt: 'Be friendlier',
+        }
+      );
       expect(updated.prompt).toBe('Be friendlier');
       expect(lookupForUpdate.isDone()).toBe(true);
       expect(updateScope.isDone()).toBe(true);
@@ -956,14 +1011,17 @@ describe('Style Rules API Integration', () => {
         .reply(200, {
           ...styleRuleWire,
           configured_rules: {},
-          custom_instructions: [{ id: instructionId, label: 'tone', prompt: 'Be friendlier' }],
+          custom_instructions: [
+            { id: instructionId, label: 'tone', prompt: 'Be friendlier' },
+          ],
         });
       const deleteScope = nock(FREE_API_URL)
         .delete(`/v3/style_rules/sr-new/custom_instructions/${instructionId}`)
         .reply(204);
 
-      await expect(styleRulesCommand.removeInstruction('sr-new', 'tone'))
-        .resolves.toBeUndefined();
+      await expect(
+        styleRulesCommand.removeInstruction('sr-new', 'tone')
+      ).resolves.toBeUndefined();
       expect(lookupForDelete.isDone()).toBe(true);
       expect(deleteScope.isDone()).toBe(true);
     });
diff --git a/tests/integration/cli-translate.integration.test.ts b/tests/integration/cli-translate.integration.test.ts
index 9e81d5a3..68ec9db7 100644
--- a/tests/integration/cli-translate.integration.test.ts
+++ b/tests/integration/cli-translate.integration.test.ts
@@ -23,7 +23,10 @@ import { DeepLClient } from '../../src/api/deepl-client';
 import { TranslationService } from '../../src/services/translation';
 import { GlossaryService } from '../../src/services/glossary';
 import { TextTranslationHandler } from '../../src/cli/commands/translate/text-translation-handler';
-import type { HandlerContext, TranslateOptions } from '../../src/cli/commands/translate/types';
+import type {
+  HandlerContext,
+  TranslateOptions,
+} from '../../src/cli/commands/translate/types';
 import type { BatchTranslationService } from '../../src/services/batch-translation';
 
 describe('Translate CLI Integration', () => {
@@ -759,7 +762,10 @@ describe('Translate CLI Integration', () => {
     it('should require API key for style-rules list', () => {
       expect.assertions(1);
       try {
-        runCLI('deepl style-rules list', { stdio: 'pipe', excludeApiKey: true });
+        runCLI('deepl style-rules list', {
+          stdio: 'pipe',
+          excludeApiKey: true,
+        });
       } catch (error: any) {
         const output = error.stderr ?? error.stdout;
         expect(output).toMatch(/API key|auth/i);
@@ -1070,7 +1076,11 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
       get: jest.fn(() => ({
         auth: {},
         api: { baseUrl: DEEPL_FREE_API_URL, usePro: false },
-        defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: false,
+        },
         cache: { enabled: false },
         output: { format: 'text', color: false },
         proxy: {},
@@ -1084,7 +1094,11 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
     const mockCache = createMockCacheService();
 
     client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
-    const translationService = new TranslationService(client, mockConfig, mockCache);
+    const translationService = new TranslationService(
+      client,
+      mockConfig,
+      mockCache
+    );
     const glossaryService = new GlossaryService(client);
 
     const ctx: HandlerContext = {
@@ -1122,7 +1136,12 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
         .get('/v3/translation_memories')
         .reply(200, {
           translation_memories: [
-            { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+            {
+              translation_memory_id: TM_UUID,
+              name: 'my-tm',
+              source_language: 'en',
+              target_languages: ['de'],
+            },
           ],
         });
 
@@ -1132,7 +1151,9 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
           expect(body['translation_memory_threshold']).toBe('75');
           return true;
         })
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        });
 
       const options: TranslateOptions = {
         to: 'de',
@@ -1157,7 +1178,9 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
           expect(body['translation_memory_threshold']).toBe('80');
           return true;
         })
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        });
 
       const options: TranslateOptions = {
         to: 'de',
@@ -1170,7 +1193,7 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
       await handler.translateText('Hi', options);
 
       expect(nock.pendingMocks()).not.toContain(
-        `GET ${DEEPL_FREE_API_URL}:443/v3/translation_memories`,
+        `GET ${DEEPL_FREE_API_URL}:443/v3/translation_memories`
       );
       expect(translateScope.isDone()).toBe(true);
       expect(nock.isDone()).toBe(true);
@@ -1185,7 +1208,9 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
           expect(body['translation_memory_threshold']).toBeUndefined();
           return true;
         })
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        });
 
       const options: TranslateOptions = {
         to: 'de',
@@ -1222,7 +1247,12 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
         .get('/v3/translation_memories')
         .reply(200, {
           translation_memories: [
-            { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+            {
+              translation_memory_id: TM_UUID,
+              name: 'my-tm',
+              source_language: 'en',
+              target_languages: ['de'],
+            },
           ],
         });
 
@@ -1233,7 +1263,9 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
           expect(body['translation_memory_threshold']).toBe('75');
           return true;
         })
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        });
 
       const options: TranslateOptions = {
         to: 'de',
@@ -1265,14 +1297,18 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
               name: 'base-terms',
               ready: true,
               creation_time: '2026-04-19T00:00:00Z',
-              dictionaries: [{ source_lang: 'EN', target_lang: 'DE', entry_count: 1 }],
+              dictionaries: [
+                { source_lang: 'EN', target_lang: 'DE', entry_count: 1 },
+              ],
             },
             {
               glossary_id: SECOND_GLOSSARY_UUID,
               name: 'project-overrides',
               ready: true,
               creation_time: '2026-04-19T00:00:00Z',
-              dictionaries: [{ source_lang: 'EN', target_lang: 'DE', entry_count: 1 }],
+              dictionaries: [
+                { source_lang: 'EN', target_lang: 'DE', entry_count: 1 },
+              ],
             },
           ],
         });
@@ -1282,11 +1318,16 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
 
       const translateScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
-          expect(body['glossary_ids']).toEqual([GLOSSARY_UUID, SECOND_GLOSSARY_UUID]);
+          expect(body['glossary_ids']).toEqual([
+            GLOSSARY_UUID,
+            SECOND_GLOSSARY_UUID,
+          ]);
           expect(body['glossary_id']).toBeUndefined();
           return true;
         })
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        });
 
       const options: TranslateOptions = {
         to: 'de',
@@ -1307,10 +1348,15 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
 
       const translateScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
-          expect(body['glossary_ids']).toEqual([SECOND_GLOSSARY_UUID, GLOSSARY_UUID]);
+          expect(body['glossary_ids']).toEqual([
+            SECOND_GLOSSARY_UUID,
+            GLOSSARY_UUID,
+          ]);
           return true;
         })
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        });
 
       const options: TranslateOptions = {
         to: 'de',
@@ -1335,7 +1381,9 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
           expect(body['glossary_ids']).toBeUndefined();
           return true;
         })
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        });
 
       const options: TranslateOptions = {
         to: 'de',
@@ -1356,10 +1404,15 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
 
       const translateScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
-          expect(body['glossary_ids']).toEqual([SECOND_GLOSSARY_UUID, GLOSSARY_UUID]);
+          expect(body['glossary_ids']).toEqual([
+            SECOND_GLOSSARY_UUID,
+            GLOSSARY_UUID,
+          ]);
           return true;
         })
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        });
 
       const options: TranslateOptions = {
         to: 'de',
@@ -1385,7 +1438,9 @@ describe('Translate CLI --translation-memory integration (nock)', () => {
         cache: false,
       };
 
-      await expect(handler.translateText('Hi', options)).rejects.toThrow(/no-such-glossary/);
+      await expect(handler.translateText('Hi', options)).rejects.toThrow(
+        /no-such-glossary/
+      );
       expect(glossaryListScope.isDone()).toBe(true);
     });
   });
diff --git a/tests/integration/cli-watch.integration.test.ts b/tests/integration/cli-watch.integration.test.ts
index d48661ed..edfc6035 100644
--- a/tests/integration/cli-watch.integration.test.ts
+++ b/tests/integration/cli-watch.integration.test.ts
@@ -92,7 +92,9 @@ describe('Watch Service Integration', () => {
     });
 
     it('should accept custom debounce time', () => {
-      const service = new WatchService(fileTranslationService, { debounceMs: 500 });
+      const service = new WatchService(fileTranslationService, {
+        debounceMs: 500,
+      });
       expect(service).toBeDefined();
     });
   });
@@ -203,7 +205,9 @@ describe('Watch Service Integration', () => {
       fs.writeFileSync(testFile, 'Hello');
 
       // Mock translation service to throw error
-      jest.spyOn(fileTranslationService, 'translateFile').mockRejectedValue(new Error('API error'));
+      jest
+        .spyOn(fileTranslationService, 'translateFile')
+        .mockRejectedValue(new Error('API error'));
 
       const callbackPromise = new Promise<void>((resolve) => {
         const onErrorMock = jest.fn((filePath: string, error: Error) => {
@@ -238,14 +242,14 @@ describe('Watch Service Integration', () => {
     const waitForFilesWatched = async (
       expected: number,
       nudge?: () => void,
-      timeoutMs = 5000,
+      timeoutMs = 5000
     ): Promise<void> => {
       const start = Date.now();
       let lastNudge = start;
       while (watchService.getStats().filesWatched !== expected) {
         if (Date.now() - start > timeoutMs) {
           throw new Error(
-            `Timed out waiting for filesWatched === ${expected}, last saw ${watchService.getStats().filesWatched}`,
+            `Timed out waiting for filesWatched === ${expected}, last saw ${watchService.getStats().filesWatched}`
           );
         }
         await new Promise((resolve) => setTimeout(resolve, 25));
@@ -296,7 +300,9 @@ describe('Watch Service Integration', () => {
     });
 
     it('should track files added and removed while watching', async () => {
-      jest.spyOn(fileTranslationService, 'translateFile').mockResolvedValue(undefined);
+      jest
+        .spyOn(fileTranslationService, 'translateFile')
+        .mockResolvedValue(undefined);
       fs.writeFileSync(path.join(tmpDir, 'a.txt'), 'Hello');
 
       await new Promise<void>((resolve) => {
@@ -310,7 +316,9 @@ describe('Watch Service Integration', () => {
 
       const newFile = path.join(tmpDir, 'b.txt');
       fs.writeFileSync(newFile, 'World');
-      await waitForFilesWatched(2, () => fs.writeFileSync(newFile, 'World again'));
+      await waitForFilesWatched(2, () =>
+        fs.writeFileSync(newFile, 'World again')
+      );
 
       fs.unlinkSync(newFile);
       await waitForFilesWatched(1);
@@ -320,7 +328,9 @@ describe('Watch Service Integration', () => {
       const testFile = path.join(tmpDir, 'test.txt');
       fs.writeFileSync(testFile, 'Hello');
 
-      jest.spyOn(fileTranslationService, 'translateFile').mockRejectedValue(new Error('Fail'));
+      jest
+        .spyOn(fileTranslationService, 'translateFile')
+        .mockRejectedValue(new Error('Fail'));
 
       const callbackPromise = new Promise<void>((resolve) => {
         watchService.watch(testFile, {
@@ -468,8 +478,15 @@ describe('Watch Service Integration', () => {
   });
 
   describe('--git-staged', () => {
-    const CLI_PATH = path.join(__dirname, '..', '..', 'dist', 'cli', 'index.js');
-     
+    const CLI_PATH = path.join(
+      __dirname,
+      '..',
+      '..',
+      'dist',
+      'cli',
+      'index.js'
+    );
+
     const { execSync: execSyncChild } = require('child_process');
 
     it('should accept --git-staged flag in help text', () => {
@@ -482,15 +499,20 @@ describe('Watch Service Integration', () => {
     });
 
     it('should show git-staged error when used outside a git repo', () => {
-      const nonGitDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-non-git-'));
+      const nonGitDir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-non-git-')
+      );
       fs.writeFileSync(path.join(nonGitDir, 'test.txt'), 'Hello');
 
       try {
-        execSyncChild(`node ${CLI_PATH} watch ${nonGitDir} --to es --git-staged`, {
-          encoding: 'utf-8',
-          cwd: nonGitDir,
-          env: { ...process.env, DEEPL_API_KEY: 'test-key:fx' },
-        });
+        execSyncChild(
+          `node ${CLI_PATH} watch ${nonGitDir} --to es --git-staged`,
+          {
+            encoding: 'utf-8',
+            cwd: nonGitDir,
+            env: { ...process.env, DEEPL_API_KEY: 'test-key:fx' },
+          }
+        );
         fail('Should have thrown');
       } catch (error: any) {
         expect(error.status).toBeGreaterThan(0);
@@ -503,16 +525,30 @@ describe('Watch Service Integration', () => {
   });
 
   describe('getStagedFiles()', () => {
-    const WATCH_MODULE_PATH = path.join(__dirname, '..', '..', 'dist', 'cli', 'commands', 'watch.js');
-     
+    const WATCH_MODULE_PATH = path.join(
+      __dirname,
+      '..',
+      '..',
+      'dist',
+      'cli',
+      'commands',
+      'watch.js'
+    );
+
     const { execSync: execSyncChild } = require('child_process');
     let gitDir: string;
 
     beforeEach(() => {
       gitDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-git-staged-test-'));
       execSyncChild('git init', { cwd: gitDir, stdio: 'ignore' });
-      execSyncChild('git config user.email "test@test.com"', { cwd: gitDir, stdio: 'ignore' });
-      execSyncChild('git config user.name "Test"', { cwd: gitDir, stdio: 'ignore' });
+      execSyncChild('git config user.email "test@test.com"', {
+        cwd: gitDir,
+        stdio: 'ignore',
+      });
+      execSyncChild('git config user.name "Test"', {
+        cwd: gitDir,
+        stdio: 'ignore',
+      });
     });
 
     afterEach(() => {
@@ -544,35 +580,48 @@ ${body}
       fs.writeFileSync(path.join(gitDir, 'file2.txt'), 'World');
       execSyncChild('git add file1.txt', { cwd: gitDir, stdio: 'ignore' });
 
-      const output = runScript(gitDir, `
+      const output = runScript(
+        gitDir,
+        `
 const result = await cmd.getStagedFiles();
 console.log(JSON.stringify({ size: result.size, files: [...result] }));
-`);
+`
+      );
 
       const parsed = JSON.parse(output.trim());
       expect(parsed.size).toBe(1);
-      expect(parsed.files[0]).toBe(path.resolve(fs.realpathSync(gitDir), 'file1.txt'));
+      expect(parsed.files[0]).toBe(
+        path.resolve(fs.realpathSync(gitDir), 'file1.txt')
+      );
     });
 
     it('should return empty set when no files are staged', () => {
       fs.writeFileSync(path.join(gitDir, 'file1.txt'), 'Hello');
 
-      const output = runScript(gitDir, `
+      const output = runScript(
+        gitDir,
+        `
 const result = await cmd.getStagedFiles();
 console.log(JSON.stringify({ size: result.size }));
-`);
+`
+      );
 
       const parsed = JSON.parse(output.trim());
       expect(parsed.size).toBe(0);
     });
 
     it('should throw error when not in a git repository', () => {
-      const nonGitDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-non-git-'));
+      const nonGitDir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-non-git-')
+      );
 
       try {
-        runScript(nonGitDir, `
+        runScript(
+          nonGitDir,
+          `
 await cmd.getStagedFiles();
-`);
+`
+        );
         fail('Should have thrown');
       } catch (error: any) {
         expect(error.status).toBeGreaterThan(0);
diff --git a/tests/integration/cli-write.integration.test.ts b/tests/integration/cli-write.integration.test.ts
index c873363d..053060fb 100644
--- a/tests/integration/cli-write.integration.test.ts
+++ b/tests/integration/cli-write.integration.test.ts
@@ -12,7 +12,11 @@ import { WriteService } from '../../src/services/write.js';
 import { ConfigService } from '../../src/storage/config.js';
 import { CacheService } from '../../src/storage/cache.js';
 import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers';
-import type { WritingStyle, WriteTone, WriteLanguage } from '../../src/types/api.js';
+import type {
+  WritingStyle,
+  WriteTone,
+  WriteLanguage,
+} from '../../src/types/api.js';
 
 describe('Write Command Integration', () => {
   const API_KEY = TEST_API_KEY;
@@ -37,7 +41,11 @@ describe('Write Command Integration', () => {
     client.destroy();
     nock.abortPendingRequests();
     nock.cleanAll();
-    try { cacheService.close(); } catch { /* ignore */ }
+    try {
+      cacheService.close();
+    } catch {
+      /* ignore */
+    }
     fs.rmSync(testDir, { recursive: true, force: true });
   });
 
@@ -53,7 +61,9 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Hello, world!', target_language: 'en-US' }],
         });
 
-      const result = await writeService.improve('Hello world', { targetLang: 'en-us' });
+      const result = await writeService.improve('Hello world', {
+        targetLang: 'en-us',
+      });
 
       expect(result).toHaveLength(1);
       expect(result[0]?.text).toBe('Hello, world!');
@@ -71,7 +81,9 @@ describe('Write Command Integration', () => {
           ],
         });
 
-      const result = await writeService.improve('Hello world', { targetLang: 'en-us' });
+      const result = await writeService.improve('Hello world', {
+        targetLang: 'en-us',
+      });
 
       expect(result).toHaveLength(3);
       expect(result[0]?.text).toBe('Hello, world!');
@@ -80,11 +92,9 @@ describe('Write Command Integration', () => {
     });
 
     it('should throw error for empty improvements array from API', async () => {
-      nock(FREE_API_URL)
-        .post('/v2/write/rephrase')
-        .reply(200, {
-          improvements: [],
-        });
+      nock(FREE_API_URL).post('/v2/write/rephrase').reply(200, {
+        improvements: [],
+      });
 
       await expect(
         writeService.improve('Perfect text', { targetLang: 'en-us' })
@@ -101,7 +111,13 @@ describe('Write Command Integration', () => {
           return true;
         })
         .reply(200, {
-          improvements: [{ text: 'Hallo, Welt!', target_language: 'de', detected_source_language: 'de' }],
+          improvements: [
+            {
+              text: 'Hallo, Welt!',
+              target_language: 'de',
+              detected_source_language: 'de',
+            },
+          ],
         });
 
       const result = await writeService.improve('Hallo Welt', {});
@@ -122,7 +138,9 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Hello, world!', target_language: 'en-GB' }],
         });
 
-      const result = await writeService.improve('Hello world', { targetLang: 'en-gb' });
+      const result = await writeService.improve('Hello world', {
+        targetLang: 'en-gb',
+      });
 
       expect(result[0]?.text).toBe('Hello, world!');
       expect(scope.isDone()).toBe(true);
@@ -155,27 +173,30 @@ describe('Write Command Integration', () => {
         output: 'Use this feature',
         expectedSubstring: undefined,
       },
-    ])('should apply $style writing style', async ({ style, input, output, expectedSubstring }) => {
-      const writingStyle = style as WritingStyle;
-      const scope = nock(FREE_API_URL)
-        .post('/v2/write/rephrase', (body) => {
-          expect(body.writing_style).toBe(writingStyle);
-          return true;
-        })
-        .reply(200, {
-          improvements: [{ text: output, target_language: 'en-US' }],
+    ])(
+      'should apply $style writing style',
+      async ({ style, input, output, expectedSubstring }) => {
+        const writingStyle = style as WritingStyle;
+        const scope = nock(FREE_API_URL)
+          .post('/v2/write/rephrase', (body) => {
+            expect(body.writing_style).toBe(writingStyle);
+            return true;
+          })
+          .reply(200, {
+            improvements: [{ text: output, target_language: 'en-US' }],
+          });
+
+        const result = await writeService.improve(input, {
+          targetLang: 'en-us',
+          writingStyle,
         });
 
-      const result = await writeService.improve(input, {
-        targetLang: 'en-us',
-        writingStyle,
-      });
-
-      if (expectedSubstring !== undefined) {
-        expect(result[0]?.text).toContain(expectedSubstring);
+        if (expectedSubstring !== undefined) {
+          expect(result[0]?.text).toContain(expectedSubstring);
+        }
+        expect(scope.isDone()).toBe(true);
       }
-      expect(scope.isDone()).toBe(true);
-    });
+    );
   });
 
   describe('improve() - Tones', () => {
@@ -208,30 +229,39 @@ describe('Write Command Integration', () => {
         expectedSubstring: undefined,
         checkNoWritingStyle: false,
       },
-    ])('should apply $tone tone', async ({ tone, input, output, expectedSubstring, checkNoWritingStyle }) => {
-      const toneValue = tone as WriteTone;
-      const scope = nock(FREE_API_URL)
-        .post('/v2/write/rephrase', (body) => {
-          expect(body.tone).toBe(toneValue);
-          if (checkNoWritingStyle) {
-            expect(body.writing_style).toBeUndefined();
-          }
-          return true;
-        })
-        .reply(200, {
-          improvements: [{ text: output, target_language: 'en-US' }],
+    ])(
+      'should apply $tone tone',
+      async ({
+        tone,
+        input,
+        output,
+        expectedSubstring,
+        checkNoWritingStyle,
+      }) => {
+        const toneValue = tone as WriteTone;
+        const scope = nock(FREE_API_URL)
+          .post('/v2/write/rephrase', (body) => {
+            expect(body.tone).toBe(toneValue);
+            if (checkNoWritingStyle) {
+              expect(body.writing_style).toBeUndefined();
+            }
+            return true;
+          })
+          .reply(200, {
+            improvements: [{ text: output, target_language: 'en-US' }],
+          });
+
+        const result = await writeService.improve(input, {
+          targetLang: 'en-us',
+          tone: toneValue,
         });
 
-      const result = await writeService.improve(input, {
-        targetLang: 'en-us',
-        tone: toneValue,
-      });
-
-      if (expectedSubstring !== undefined) {
-        expect(result[0]?.text).toContain(expectedSubstring);
+        if (expectedSubstring !== undefined) {
+          expect(result[0]?.text).toContain(expectedSubstring);
+        }
+        expect(scope.isDone()).toBe(true);
       }
-      expect(scope.isDone()).toBe(true);
-    });
+    );
   });
 
   describe('improve() - Different Languages', () => {
@@ -292,24 +322,27 @@ describe('Write Command Integration', () => {
         output: '我想购买这个',
         expectedExact: undefined,
       },
-    ])('should improve $label text', async ({ lang, input, output, expectedExact }) => {
-      const targetLang = lang as WriteLanguage;
-      const scope = nock(FREE_API_URL)
-        .post('/v2/write/rephrase', (body) => {
-          expect(body.target_lang).toBe(targetLang);
-          return true;
-        })
-        .reply(200, {
-          improvements: [{ text: output, target_language: targetLang }],
-        });
-
-      const result = await writeService.improve(input, { targetLang });
-
-      if (expectedExact !== undefined) {
-        expect(result[0]?.text).toBe(expectedExact);
+    ])(
+      'should improve $label text',
+      async ({ lang, input, output, expectedExact }) => {
+        const targetLang = lang as WriteLanguage;
+        const scope = nock(FREE_API_URL)
+          .post('/v2/write/rephrase', (body) => {
+            expect(body.target_lang).toBe(targetLang);
+            return true;
+          })
+          .reply(200, {
+            improvements: [{ text: output, target_language: targetLang }],
+          });
+
+        const result = await writeService.improve(input, { targetLang });
+
+        if (expectedExact !== undefined) {
+          expect(result[0]?.text).toBe(expectedExact);
+        }
+        expect(scope.isDone()).toBe(true);
       }
-      expect(scope.isDone()).toBe(true);
-    });
+    );
   });
 
   describe('improve() - Styles and Tones on Romance language variants', () => {
@@ -326,36 +359,46 @@ describe('Write Command Integration', () => {
       { lang: 'pt', field: 'tone' as const, value: 'enthusiastic' },
       { lang: 'pt-br', field: 'tone' as const, value: 'friendly' },
       { lang: 'pt-pt', field: 'tone' as const, value: 'confident' },
-    ])('should send $field=$value with target_lang=$lang', async ({ lang, field, value }) => {
-      const targetLang = lang as WriteLanguage;
-      const scope = nock(FREE_API_URL)
-        .post('/v2/write/rephrase', (body) => {
-          expect(body.target_lang).toBe(targetLang);
-          expect(body[field]).toBe(value);
-          return true;
-        })
-        .reply(200, {
-          improvements: [{ text: 'improved', target_language: targetLang }],
-        });
-
-      const improveOptions: { targetLang: WriteLanguage; writingStyle?: WritingStyle; tone?: WriteTone } = { targetLang };
-      if (field === 'writing_style') {
-        improveOptions.writingStyle = value as WritingStyle;
-      } else {
-        improveOptions.tone = value as WriteTone;
+    ])(
+      'should send $field=$value with target_lang=$lang',
+      async ({ lang, field, value }) => {
+        const targetLang = lang as WriteLanguage;
+        const scope = nock(FREE_API_URL)
+          .post('/v2/write/rephrase', (body) => {
+            expect(body.target_lang).toBe(targetLang);
+            expect(body[field]).toBe(value);
+            return true;
+          })
+          .reply(200, {
+            improvements: [{ text: 'improved', target_language: targetLang }],
+          });
+
+        const improveOptions: {
+          targetLang: WriteLanguage;
+          writingStyle?: WritingStyle;
+          tone?: WriteTone;
+        } = { targetLang };
+        if (field === 'writing_style') {
+          improveOptions.writingStyle = value as WritingStyle;
+        } else {
+          improveOptions.tone = value as WriteTone;
+        }
+        const result = await writeService.improve(
+          'source text',
+          improveOptions
+        );
+
+        expect(result[0]?.text).toBe('improved');
+        expect(scope.isDone()).toBe(true);
       }
-      const result = await writeService.improve('source text', improveOptions);
-
-      expect(result[0]?.text).toBe('improved');
-      expect(scope.isDone()).toBe(true);
-    });
+    );
   });
 
   describe('improve() - Error Handling', () => {
     it('should throw error for empty text', async () => {
-      await expect(writeService.improve('', { targetLang: 'en-us' })).rejects.toThrow(
-        'Text cannot be empty'
-      );
+      await expect(
+        writeService.improve('', { targetLang: 'en-us' })
+      ).rejects.toThrow('Text cannot be empty');
     });
 
     it('should throw error when both style and tone are specified', async () => {
@@ -369,7 +412,9 @@ describe('Write Command Integration', () => {
     });
 
     it('should handle 403 authentication errors', async () => {
-      nock(FREE_API_URL).post('/v2/write/rephrase').reply(403, { message: 'Invalid API key' });
+      nock(FREE_API_URL)
+        .post('/v2/write/rephrase')
+        .reply(403, { message: 'Invalid API key' });
 
       await expect(
         writeService.improve('Test', { targetLang: 'en-us' })
@@ -377,7 +422,9 @@ describe('Write Command Integration', () => {
     });
 
     it('should handle 456 quota exceeded errors', async () => {
-      nock(FREE_API_URL).post('/v2/write/rephrase').reply(456, { message: 'Quota exceeded' });
+      nock(FREE_API_URL)
+        .post('/v2/write/rephrase')
+        .reply(456, { message: 'Quota exceeded' });
 
       await expect(
         writeService.improve('Test', { targetLang: 'en-us' })
@@ -394,7 +441,6 @@ describe('Write Command Integration', () => {
         writeService.improve('Test', { targetLang: 'en-us' })
       ).rejects.toThrow('Rate limit exceeded');
     });
-
   });
 
   describe('improve() - Edge Cases', () => {
@@ -439,10 +485,14 @@ describe('Write Command Integration', () => {
           return true;
         })
         .reply(200, {
-          improvements: [{ text: 'Hello, 世界 🌍 café!', target_language: 'en-US' }],
+          improvements: [
+            { text: 'Hello, 世界 🌍 café!', target_language: 'en-US' },
+          ],
         });
 
-      const result = await writeService.improve(unicodeText, { targetLang: 'en-us' });
+      const result = await writeService.improve(unicodeText, {
+        targetLang: 'en-us',
+      });
       expect(result[0]?.text).toContain('世界');
       expect(result[0]?.text).toContain('🌍');
       expect(scope.isDone()).toBe(true);
@@ -462,7 +512,9 @@ describe('Write Command Integration', () => {
           ],
         });
 
-      const result = await writeService.improve(multilineText, { targetLang: 'en-us' });
+      const result = await writeService.improve(multilineText, {
+        targetLang: 'en-us',
+      });
       expect(result[0]?.text).toContain('\n');
       expect(result[0]?.text.split('\n')).toHaveLength(3);
     });
@@ -487,11 +539,9 @@ describe('Write Command Integration', () => {
     });
 
     it('should throw error when no improvements returned from API', async () => {
-      nock(FREE_API_URL)
-        .post('/v2/write/rephrase')
-        .reply(200, {
-          improvements: [],
-        });
+      nock(FREE_API_URL).post('/v2/write/rephrase').reply(200, {
+        improvements: [],
+      });
 
       await expect(
         writeService.getBestImprovement('Test', { targetLang: 'en-us' })
@@ -556,8 +606,12 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Improved!', target_language: 'en-US' }],
         });
 
-      const result1 = await writeService.improve('Test', { targetLang: 'en-us' });
-      const result2 = await writeService.improve('Test', { targetLang: 'en-us' });
+      const result1 = await writeService.improve('Test', {
+        targetLang: 'en-us',
+      });
+      const result2 = await writeService.improve('Test', {
+        targetLang: 'en-us',
+      });
 
       expect(result1).toEqual(result2);
       expect(scope.isDone()).toBe(true);
@@ -572,7 +626,11 @@ describe('Write Command Integration', () => {
         });
 
       await writeService.improve('Test', { targetLang: 'en-us' });
-      await writeService.improve('Test', { targetLang: 'en-us' }, { skipCache: true });
+      await writeService.improve(
+        'Test',
+        { targetLang: 'en-us' },
+        { skipCache: true }
+      );
 
       expect(nock.isDone()).toBe(true);
     });
@@ -590,8 +648,14 @@ describe('Write Command Integration', () => {
           improvements: [{ text: 'Casual text', target_language: 'en-US' }],
         });
 
-      const business = await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'business' });
-      const casual = await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'casual' });
+      const business = await writeService.improve('Test', {
+        targetLang: 'en-us',
+        writingStyle: 'business',
+      });
+      const casual = await writeService.improve('Test', {
+        targetLang: 'en-us',
+        writingStyle: 'casual',
+      });
 
       expect(business[0]?.text).toBe('Business text');
       expect(casual[0]?.text).toBe('Casual text');
@@ -604,7 +668,11 @@ describe('Write Command Integration', () => {
   describe('error handling - network', () => {
     it('should handle network errors', async () => {
       const noRetryClient = new DeepLClient(API_KEY, { maxRetries: 0 });
-      const noRetryWriteService = new WriteService(noRetryClient, configService, cacheService);
+      const noRetryWriteService = new WriteService(
+        noRetryClient,
+        configService,
+        cacheService
+      );
 
       nock(FREE_API_URL)
         .post('/v2/write/rephrase')
diff --git a/tests/integration/deepl-client.integration.test.ts b/tests/integration/deepl-client.integration.test.ts
index e4ee5495..11ca623a 100644
--- a/tests/integration/deepl-client.integration.test.ts
+++ b/tests/integration/deepl-client.integration.test.ts
@@ -6,7 +6,11 @@
 
 import nock from 'nock';
 import { DeepLClient } from '../../src/api/deepl-client.js';
-import { DEEPL_FREE_API_URL, DEEPL_PRO_API_URL, TEST_API_KEY } from '../helpers';
+import {
+  DEEPL_FREE_API_URL,
+  DEEPL_PRO_API_URL,
+  TEST_API_KEY,
+} from '../helpers';
 
 describe('DeepLClient Integration', () => {
   const API_KEY = TEST_API_KEY;
@@ -16,12 +20,11 @@ describe('DeepLClient Integration', () => {
 
   afterEach(() => {
     nock.abortPendingRequests();
-    clients.forEach(c => c.destroy());
+    clients.forEach((c) => c.destroy());
     clients.length = 0;
     nock.cleanAll();
   });
 
-
   describe('constructor', () => {
     it('should create client with API key', () => {
       const client = new DeepLClient(API_KEY);
@@ -142,7 +145,10 @@ describe('DeepLClient Integration', () => {
           translations: [{ text: 'Hola' }],
         });
 
-      await client.translate('Hello', { targetLang: 'es', context: 'This is a greeting' });
+      await client.translate('Hello', {
+        targetLang: 'es',
+        context: 'This is a greeting',
+      });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -159,7 +165,10 @@ describe('DeepLClient Integration', () => {
           translations: [{ text: 'Hola' }],
         });
 
-      await client.translate('Hello', { targetLang: 'es', splitSentences: 'nonewlines' });
+      await client.translate('Hello', {
+        targetLang: 'es',
+        splitSentences: 'nonewlines',
+      });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -176,7 +185,10 @@ describe('DeepLClient Integration', () => {
           translations: [{ text: '<p>Hola</p>' }],
         });
 
-      await client.translate('<p>Hello</p>', { targetLang: 'es', tagHandling: 'xml' });
+      await client.translate('<p>Hello</p>', {
+        targetLang: 'es',
+        tagHandling: 'xml',
+      });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -193,7 +205,10 @@ describe('DeepLClient Integration', () => {
           translations: [{ text: 'Hola' }],
         });
 
-      await client.translate('Hello', { targetLang: 'es', modelType: 'quality_optimized' });
+      await client.translate('Hello', {
+        targetLang: 'es',
+        modelType: 'quality_optimized',
+      });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -204,11 +219,13 @@ describe('DeepLClient Integration', () => {
       nock(FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
-          translations: [{
-            text: 'Hola',
-            detected_source_language: 'EN',
-            model_type_used: 'quality_optimized',
-          }],
+          translations: [
+            {
+              text: 'Hola',
+              detected_source_language: 'EN',
+              model_type_used: 'quality_optimized',
+            },
+          ],
         });
 
       const result = await client.translate('Hello', { targetLang: 'es' });
@@ -235,7 +252,7 @@ describe('DeepLClient Integration', () => {
 
       const scope = nock(FREE_API_URL, {
         reqheaders: {
-          'authorization': `DeepL-Auth-Key ${API_KEY}`,
+          authorization: `DeepL-Auth-Key ${API_KEY}`,
         },
       })
         .post('/v2/translate')
@@ -273,9 +290,9 @@ describe('DeepLClient Integration', () => {
         .post('/v2/translate')
         .reply(403, { message: 'Authorization failed' });
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
-        'Authentication failed: Invalid API key'
-      );
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow('Authentication failed: Invalid API key');
     });
 
     it('should handle 456 quota exceeded errors', async () => {
@@ -286,9 +303,9 @@ describe('DeepLClient Integration', () => {
         .post('/v2/translate')
         .reply(456, { message: 'Quota exceeded' });
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
-        'Quota exceeded: Character limit reached'
-      );
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow('Quota exceeded: Character limit reached');
     });
 
     it('should handle 429 rate limit errors', async () => {
@@ -300,9 +317,9 @@ describe('DeepLClient Integration', () => {
         .times(4)
         .reply(429, { message: 'Too many requests' });
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
-        'Rate limit exceeded: Too many requests'
-      );
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow('Rate limit exceeded: Too many requests');
     });
 
     it('should handle 503 service unavailable errors', async () => {
@@ -310,9 +327,13 @@ describe('DeepLClient Integration', () => {
       clients.push(client);
 
       // A translate POST is not replayed, so one attempt is all the server sees.
-      nock(FREE_API_URL).post('/v2/translate').reply(503, { message: 'Service temporarily unavailable' });
+      nock(FREE_API_URL)
+        .post('/v2/translate')
+        .reply(503, { message: 'Service temporarily unavailable' });
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(
         'Service temporarily unavailable: Please try again later'
       );
     });
@@ -321,22 +342,27 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY, { timeout: 100, maxRetries: 0 });
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .post('/v2/translate')
-        .replyWithError({ code: 'ECONNABORTED', message: 'timeout of 100ms exceeded' });
+      nock(FREE_API_URL).post('/v2/translate').replyWithError({
+        code: 'ECONNABORTED',
+        message: 'timeout of 100ms exceeded',
+      });
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow();
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow();
     });
 
     it('should handle malformed API responses', async () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL).post('/v2/translate').reply(200, { invalid: 'response' });
+      nock(FREE_API_URL)
+        .post('/v2/translate')
+        .reply(200, { invalid: 'response' });
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
-        'No translation returned'
-      );
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow('No translation returned');
     });
 
     it('should retry an idempotent request on 500 errors', async () => {
@@ -375,11 +401,13 @@ describe('DeepLClient Integration', () => {
       clients.push(client);
 
       // Only one request should be made for 4xx errors
-      const scope = nock(FREE_API_URL).post('/v2/translate').reply(403, 'Forbidden');
+      const scope = nock(FREE_API_URL)
+        .post('/v2/translate')
+        .reply(403, 'Forbidden');
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
-        'Authentication failed'
-      );
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow('Authentication failed');
 
       expect(scope.isDone()).toBe(true);
       // No additional retries should have been attempted
@@ -392,12 +420,10 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      const scope = nock(FREE_API_URL)
-        .get('/v2/usage')
-        .reply(200, {
-          character_count: 200000,
-          character_limit: 500000,
-        });
+      const scope = nock(FREE_API_URL).get('/v2/usage').reply(200, {
+        character_count: 200000,
+        character_limit: 500000,
+      });
 
       const result = await client.getUsage();
 
@@ -410,12 +436,10 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .get('/v2/usage')
-        .reply(200, {
-          character_count: 12345,
-          character_limit: 50000,
-        });
+      nock(FREE_API_URL).get('/v2/usage').reply(200, {
+        character_count: 12345,
+        character_limit: 50000,
+      });
 
       const result = await client.getUsage();
 
@@ -427,7 +451,9 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL).get('/v2/usage').reply(403, { message: 'Invalid API key' });
+      nock(FREE_API_URL)
+        .get('/v2/usage')
+        .reply(403, { message: 'Invalid API key' });
 
       await expect(client.getUsage()).rejects.toThrow('Authentication failed');
     });
@@ -446,8 +472,16 @@ describe('DeepLClient Integration', () => {
           start_time: '2025-04-24T14:58:02Z',
           end_time: '2025-05-24T14:58:02Z',
           products: [
-            { product_type: 'translate', character_count: 900000, api_key_character_count: 880000 },
-            { product_type: 'write', character_count: 1250000, api_key_character_count: 1000000 },
+            {
+              product_type: 'translate',
+              character_count: 900000,
+              api_key_character_count: 880000,
+            },
+            {
+              product_type: 'write',
+              character_count: 1250000,
+              api_key_character_count: 1000000,
+            },
           ],
         });
 
@@ -460,8 +494,16 @@ describe('DeepLClient Integration', () => {
       expect(result.startTime).toBe('2025-04-24T14:58:02Z');
       expect(result.endTime).toBe('2025-05-24T14:58:02Z');
       expect(result.products).toEqual([
-        { productType: 'translate', characterCount: 900000, apiKeyCharacterCount: 880000 },
-        { productType: 'write', characterCount: 1250000, apiKeyCharacterCount: 1000000 },
+        {
+          productType: 'translate',
+          characterCount: 900000,
+          apiKeyCharacterCount: 880000,
+        },
+        {
+          productType: 'write',
+          characterCount: 1250000,
+          apiKeyCharacterCount: 1000000,
+        },
       ]);
     });
 
@@ -469,12 +511,10 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .get('/v2/usage')
-        .reply(200, {
-          character_count: 12345,
-          character_limit: 50000,
-        });
+      nock(FREE_API_URL).get('/v2/usage').reply(200, {
+        character_count: 12345,
+        character_limit: 50000,
+      });
 
       const result = await client.getUsage();
 
@@ -495,9 +535,24 @@ describe('DeepLClient Integration', () => {
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
-          { lang: 'en-gb', name: 'English (British)', usable_as_source: false, usable_as_target: true },
+          {
+            lang: 'en',
+            name: 'English',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'en-gb',
+            name: 'English (British)',
+            usable_as_source: false,
+            usable_as_target: true,
+          },
         ]);
 
       const result = await client.getSupportedLanguages('source');
@@ -559,7 +614,9 @@ describe('DeepLClient Integration', () => {
       nock(FREE_API_URL)
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
-        .reply(200, [{ lang: 'EN-US', name: 'English (American)', usable_as_source: true }]);
+        .reply(200, [
+          { lang: 'EN-US', name: 'English (American)', usable_as_source: true },
+        ]);
 
       const result = await client.getSupportedLanguages('source');
 
@@ -579,7 +636,10 @@ describe('DeepLClient Integration', () => {
             name: 'German',
             usable_as_source: true,
             usable_as_target: true,
-            features: { formality: { status: 'stable' }, glossary: { status: 'stable' } },
+            features: {
+              formality: { status: 'stable' },
+              glossary: { status: 'stable' },
+            },
           },
           {
             lang: 'en-us',
@@ -626,7 +686,9 @@ describe('DeepLClient Integration', () => {
           improvements: [{ text: 'Hello, world!', target_language: 'en-US' }],
         });
 
-      const result = await client.improveText('Hello world', { targetLang: 'en-us' });
+      const result = await client.improveText('Hello world', {
+        targetLang: 'en-us',
+      });
 
       expect(result[0]?.text).toBe('Hello, world!');
       expect(result[0]?.targetLanguage).toBe('en-US');
@@ -646,7 +708,10 @@ describe('DeepLClient Integration', () => {
           improvements: [{ text: 'Improved text', target_language: 'en-US' }],
         });
 
-      await client.improveText('Test', { targetLang: 'en-us', writingStyle: 'business' });
+      await client.improveText('Test', {
+        targetLang: 'en-us',
+        writingStyle: 'business',
+      });
       expect(scope.isDone()).toBe(true);
     });
 
@@ -663,10 +728,12 @@ describe('DeepLClient Integration', () => {
           improvements: [{ text: 'Improved text', target_language: 'en-US' }],
         });
 
-      await client.improveText('Test', { targetLang: 'en-us', tone: 'friendly' });
+      await client.improveText('Test', {
+        targetLang: 'en-us',
+        tone: 'friendly',
+      });
       expect(scope.isDone()).toBe(true);
     });
-
   });
 
   describe('custom API URLs', () => {
@@ -675,12 +742,10 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY, { baseUrl: customUrl });
       clients.push(client);
 
-      const scope = nock(customUrl)
-        .get('/v2/usage')
-        .reply(200, {
-          character_count: 100,
-          character_limit: 500,
-        });
+      const scope = nock(customUrl).get('/v2/usage').reply(200, {
+        character_count: 100,
+        character_limit: 500,
+      });
 
       await client.getUsage();
       expect(scope.isDone()).toBe(true);
@@ -690,12 +755,10 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY, { usePro: true });
       clients.push(client);
 
-      const scope = nock(PRO_API_URL)
-        .get('/v2/usage')
-        .reply(200, {
-          character_count: 100,
-          character_limit: 500,
-        });
+      const scope = nock(PRO_API_URL).get('/v2/usage').reply(200, {
+        character_count: 100,
+        character_limit: 500,
+      });
 
       await client.getUsage();
       expect(scope.isDone()).toBe(true);
@@ -711,7 +774,9 @@ describe('DeepLClient Integration', () => {
       const scope = nock(FREE_API_URL)
         .post('/v2/document', (body) => {
           // Verify multipart/form-data contains file and target_lang
-          return body.includes('test pdf content') && body.includes('target_lang');
+          return (
+            body.includes('test pdf content') && body.includes('target_lang')
+          );
         })
         .reply(200, {
           document_id: 'doc-123',
@@ -849,7 +914,7 @@ describe('DeepLClient Integration', () => {
 
       const scope = nock(FREE_API_URL, {
         reqheaders: {
-          'authorization': `DeepL-Auth-Key ${API_KEY}`,
+          authorization: `DeepL-Auth-Key ${API_KEY}`,
         },
       })
         .post('/v2/document')
@@ -896,7 +961,9 @@ describe('DeepLClient Integration', () => {
       clients.push(client);
       const fileBuffer = Buffer.from('test content');
 
-      nock(FREE_API_URL).post('/v2/document').reply(403, { message: 'Invalid API key' });
+      nock(FREE_API_URL)
+        .post('/v2/document')
+        .reply(403, { message: 'Invalid API key' });
 
       await expect(
         client.uploadDocument(fileBuffer, {
@@ -911,7 +978,9 @@ describe('DeepLClient Integration', () => {
       clients.push(client);
       const fileBuffer = Buffer.from('test content');
 
-      nock(FREE_API_URL).post('/v2/document').reply(413, { message: 'File too large' });
+      nock(FREE_API_URL)
+        .post('/v2/document')
+        .reply(413, { message: 'File too large' });
 
       await expect(
         client.uploadDocument(fileBuffer, {
@@ -954,12 +1023,10 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .post('/v2/document/doc-123')
-        .reply(200, {
-          document_id: 'doc-123',
-          status: 'queued',
-        });
+      nock(FREE_API_URL).post('/v2/document/doc-123').reply(200, {
+        document_id: 'doc-123',
+        status: 'queued',
+      });
 
       const result = await client.getDocumentStatus({
         documentId: 'doc-123',
@@ -975,13 +1042,11 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .post('/v2/document/doc-123')
-        .reply(200, {
-          document_id: 'doc-123',
-          status: 'translating',
-          seconds_remaining: 10,
-        });
+      nock(FREE_API_URL).post('/v2/document/doc-123').reply(200, {
+        document_id: 'doc-123',
+        status: 'translating',
+        seconds_remaining: 10,
+      });
 
       const result = await client.getDocumentStatus({
         documentId: 'doc-123',
@@ -996,13 +1061,11 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .post('/v2/document/doc-123')
-        .reply(200, {
-          document_id: 'doc-123',
-          status: 'done',
-          billed_characters: 1234,
-        });
+      nock(FREE_API_URL).post('/v2/document/doc-123').reply(200, {
+        document_id: 'doc-123',
+        status: 'done',
+        billed_characters: 1234,
+      });
 
       const result = await client.getDocumentStatus({
         documentId: 'doc-123',
@@ -1017,13 +1080,11 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .post('/v2/document/doc-123')
-        .reply(200, {
-          document_id: 'doc-123',
-          status: 'error',
-          error_message: 'Unsupported file format',
-        });
+      nock(FREE_API_URL).post('/v2/document/doc-123').reply(200, {
+        document_id: 'doc-123',
+        status: 'error',
+        error_message: 'Unsupported file format',
+      });
 
       const result = await client.getDocumentStatus({
         documentId: 'doc-123',
@@ -1179,9 +1240,13 @@ describe('DeepLClient Integration', () => {
 
       nock(FREE_API_URL)
         .post('/v2/translate')
-        .reply(200, { translations: [{ text: 'Hola' }] }, {
-          'x-trace-id': 'abc-123-trace',
-        });
+        .reply(
+          200,
+          { translations: [{ text: 'Hola' }] },
+          {
+            'x-trace-id': 'abc-123-trace',
+          }
+        );
 
       await client.translate('Hello', { targetLang: 'es' });
       expect(client.lastTraceId).toBe('abc-123-trace');
@@ -1192,11 +1257,13 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .get('/v2/usage')
-        .reply(403, { message: 'Invalid API key' }, {
+      nock(FREE_API_URL).get('/v2/usage').reply(
+        403,
+        { message: 'Invalid API key' },
+        {
           'x-trace-id': 'err-456-trace',
-        });
+        }
+      );
 
       try {
         await client.getUsage();
@@ -1210,13 +1277,17 @@ describe('DeepLClient Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .get('/v2/usage')
-        .reply(403, { message: 'Invalid API key' }, {
+      nock(FREE_API_URL).get('/v2/usage').reply(
+        403,
+        { message: 'Invalid API key' },
+        {
           'x-trace-id': 'trace-for-support',
-        });
+        }
+      );
 
-      await expect(client.getUsage()).rejects.toThrow('Trace ID: trace-for-support');
+      await expect(client.getUsage()).rejects.toThrow(
+        'Trace ID: trace-for-support'
+      );
     });
 
     it('should return undefined when no trace ID present', () => {
@@ -1231,18 +1302,26 @@ describe('DeepLClient Integration', () => {
 
       nock(FREE_API_URL)
         .post('/v2/translate')
-        .reply(200, { translations: [{ text: 'Hola' }] }, {
-          'x-trace-id': 'first-trace',
-        });
+        .reply(
+          200,
+          { translations: [{ text: 'Hola' }] },
+          {
+            'x-trace-id': 'first-trace',
+          }
+        );
 
       await client.translate('Hello', { targetLang: 'es' });
       expect(client.lastTraceId).toBe('first-trace');
 
       nock(FREE_API_URL)
         .post('/v2/translate')
-        .reply(200, { translations: [{ text: 'Bonjour' }] }, {
-          'x-trace-id': 'second-trace',
-        });
+        .reply(
+          200,
+          { translations: [{ text: 'Bonjour' }] },
+          {
+            'x-trace-id': 'second-trace',
+          }
+        );
 
       await client.translate('Hello', { targetLang: 'fr' });
       expect(client.lastTraceId).toBe('second-trace');
diff --git a/tests/integration/deepl-glossary-v3.integration.test.ts b/tests/integration/deepl-glossary-v3.integration.test.ts
index 8f0b38b8..2b7bca1d 100644
--- a/tests/integration/deepl-glossary-v3.integration.test.ts
+++ b/tests/integration/deepl-glossary-v3.integration.test.ts
@@ -14,7 +14,7 @@ describe('DeepLClient v3 Glossary Integration', () => {
   const clients: DeepLClient[] = [];
 
   afterEach(() => {
-    clients.forEach(c => c.destroy());
+    clients.forEach((c) => c.destroy());
     clients.length = 0;
     nock.cleanAll();
   });
@@ -48,7 +48,12 @@ describe('DeepLClient v3 Glossary Integration', () => {
           creation_time: '2025-10-13T10:00:00Z',
         });
 
-      const result = await client.createGlossary('Test Glossary', 'en', ['es'], 'Hello\tHola');
+      const result = await client.createGlossary(
+        'Test Glossary',
+        'en',
+        ['es'],
+        'Hello\tHola'
+      );
 
       expect(result.glossary_id).toBe('glossary-123');
       expect(result.name).toBe('Test Glossary');
@@ -127,7 +132,7 @@ describe('DeepLClient v3 Glossary Integration', () => {
 
       const scope = nock(FREE_API_URL, {
         reqheaders: {
-          'authorization': `DeepL-Auth-Key ${API_KEY}`,
+          authorization: `DeepL-Auth-Key ${API_KEY}`,
         },
       })
         .post('/v3/glossaries')
@@ -136,7 +141,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
           name: 'Test',
           source_lang: 'en',
           target_langs: ['es'],
-          dictionaries: [{ source_lang: 'en', target_lang: 'es', entry_count: 1 }],
+          dictionaries: [
+            { source_lang: 'en', target_lang: 'es', entry_count: 1 },
+          ],
           creation_time: '2025-10-13T10:00:00Z',
         });
 
@@ -157,7 +164,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
         .reply(200, {
           glossary_id: 'glossary-123',
           name: 'Test',
-          dictionaries: [{ source_lang: 'en', target_lang: 'es', entry_count: 1 }],
+          dictionaries: [
+            { source_lang: 'en', target_lang: 'es', entry_count: 1 },
+          ],
           creation_time: '2025-10-13T10:00:00Z',
         });
 
@@ -206,7 +215,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
               name: 'Glossary 1',
               source_lang: 'en',
               target_langs: ['es'],
-              dictionaries: [{ source_lang: 'en', target_lang: 'es', entry_count: 10 }],
+              dictionaries: [
+                { source_lang: 'en', target_lang: 'es', entry_count: 10 },
+              ],
               creation_time: '2025-10-13T10:00:00Z',
             },
             {
@@ -237,9 +248,7 @@ describe('DeepLClient v3 Glossary Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      nock(FREE_API_URL)
-        .get('/v3/glossaries')
-        .reply(200, { glossaries: [] });
+      nock(FREE_API_URL).get('/v3/glossaries').reply(200, { glossaries: [] });
 
       const result = await client.listGlossaries();
 
@@ -254,7 +263,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
         .get('/v3/glossaries')
         .reply(403, { message: 'Invalid API key' });
 
-      await expect(client.listGlossaries()).rejects.toThrow('Authentication failed');
+      await expect(client.listGlossaries()).rejects.toThrow(
+        'Authentication failed'
+      );
     });
   });
 
@@ -270,7 +281,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
           name: 'Test Glossary',
           source_lang: 'en',
           target_langs: ['es'],
-          dictionaries: [{ source_lang: 'en', target_lang: 'es', entry_count: 15 }],
+          dictionaries: [
+            { source_lang: 'en', target_lang: 'es', entry_count: 15 },
+          ],
           creation_time: '2025-10-13T10:00:00Z',
         });
 
@@ -291,7 +304,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
         .get('/v3/glossaries/nonexistent')
         .reply(404, { message: 'Glossary not found' });
 
-      await expect(client.getGlossary('nonexistent')).rejects.toThrow('API error');
+      await expect(client.getGlossary('nonexistent')).rejects.toThrow(
+        'API error'
+      );
     });
   });
 
@@ -317,7 +332,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
         .delete('/v3/glossaries/nonexistent')
         .reply(404, { message: 'Glossary not found' });
 
-      await expect(client.deleteGlossary('nonexistent')).rejects.toThrow('API error');
+      await expect(client.deleteGlossary('nonexistent')).rejects.toThrow(
+        'API error'
+      );
     });
   });
 
@@ -343,7 +360,11 @@ describe('DeepLClient v3 Glossary Integration', () => {
           ],
         });
 
-      const result = await client.getGlossaryEntries('glossary-123', 'en', 'es');
+      const result = await client.getGlossaryEntries(
+        'glossary-123',
+        'en',
+        'es'
+      );
 
       expect(result).toBe('Hello\tHola\nWorld\tMundo');
       expect(scope.isDone()).toBe(true);
@@ -367,7 +388,11 @@ describe('DeepLClient v3 Glossary Integration', () => {
           ],
         });
 
-      const result = await client.getGlossaryEntries('glossary-123', 'en', 'es');
+      const result = await client.getGlossaryEntries(
+        'glossary-123',
+        'en',
+        'es'
+      );
       expect(result).toBe('Test\tPrueba');
       expect(scope.isDone()).toBe(true);
     });
@@ -438,13 +463,20 @@ describe('DeepLClient v3 Glossary Integration', () => {
           expect(body.dictionaries).toHaveLength(1);
           expect(body.dictionaries[0].source_lang).toBe('EN');
           expect(body.dictionaries[0].target_lang).toBe('ES');
-          expect(body.dictionaries[0].entries).toBe('Hello\tHola\nWorld\tMundo');
+          expect(body.dictionaries[0].entries).toBe(
+            'Hello\tHola\nWorld\tMundo'
+          );
           expect(body.dictionaries[0].entries_format).toBe('tsv');
           return true;
         })
         .reply(204);
 
-      await client.updateGlossaryEntries('glossary-123', 'en', 'es', 'Hello\tHola\nWorld\tMundo');
+      await client.updateGlossaryEntries(
+        'glossary-123',
+        'en',
+        'es',
+        'Hello\tHola\nWorld\tMundo'
+      );
 
       expect(scope.isDone()).toBe(true);
     });
@@ -461,7 +493,12 @@ describe('DeepLClient v3 Glossary Integration', () => {
         .patch('/v3/glossaries/glossary-123')
         .reply(204);
 
-      await client.updateGlossaryEntries('glossary-123', 'en', 'es', 'Test\tPrueba');
+      await client.updateGlossaryEntries(
+        'glossary-123',
+        'en',
+        'es',
+        'Test\tPrueba'
+      );
       expect(scope.isDone()).toBe(true);
     });
 
@@ -505,7 +542,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
         })
         .reply(204);
 
-      await client.updateGlossary('glossary-123', { name: 'New Glossary Name' });
+      await client.updateGlossary('glossary-123', {
+        name: 'New Glossary Name',
+      });
 
       expect(scope.isDone()).toBe(true);
     });
@@ -527,12 +566,14 @@ describe('DeepLClient v3 Glossary Integration', () => {
         .reply(204);
 
       await client.updateGlossary('glossary-123', {
-        dictionaries: [{
-          source_lang: 'EN',
-          target_lang: 'ES',
-          entries: 'Hello\tHola',
-          entries_format: 'tsv',
-        }],
+        dictionaries: [
+          {
+            source_lang: 'EN',
+            target_lang: 'ES',
+            entries: 'Hello\tHola',
+            entries_format: 'tsv',
+          },
+        ],
       });
 
       expect(scope.isDone()).toBe(true);
@@ -556,12 +597,14 @@ describe('DeepLClient v3 Glossary Integration', () => {
 
       await client.updateGlossary('glossary-123', {
         name: 'Updated Name',
-        dictionaries: [{
-          source_lang: 'EN',
-          target_lang: 'DE',
-          entries: 'Hello\tHallo',
-          entries_format: 'tsv',
-        }],
+        dictionaries: [
+          {
+            source_lang: 'EN',
+            target_lang: 'DE',
+            entries: 'Hello\tHallo',
+            entries_format: 'tsv',
+          },
+        ],
       });
 
       expect(scope.isDone()).toBe(true);
@@ -587,9 +630,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
       const client = new DeepLClient(API_KEY);
       clients.push(client);
 
-      await expect(
-        client.updateGlossary('glossary-123', {})
-      ).rejects.toThrow('At least one of name or dictionaries must be provided');
+      await expect(client.updateGlossary('glossary-123', {})).rejects.toThrow(
+        'At least one of name or dictionaries must be provided'
+      );
     });
 
     it('should handle 404 glossary not found errors', async () => {
@@ -659,7 +702,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
       clients.push(client);
 
       const scope = nock(FREE_API_URL)
-        .delete('/v3/glossaries/glossary-123/dictionaries?source_lang=EN&target_lang=ES')
+        .delete(
+          '/v3/glossaries/glossary-123/dictionaries?source_lang=EN&target_lang=ES'
+        )
         .reply(204);
 
       await client.deleteGlossaryDictionary('glossary-123', 'en', 'es');
@@ -672,7 +717,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
       clients.push(client);
 
       const scope = nock(FREE_API_URL)
-        .delete('/v3/glossaries/glossary-456/dictionaries?source_lang=EN&target_lang=FR')
+        .delete(
+          '/v3/glossaries/glossary-456/dictionaries?source_lang=EN&target_lang=FR'
+        )
         .reply(204);
 
       await client.deleteGlossaryDictionary('glossary-456', 'en', 'fr');
@@ -685,7 +732,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
       clients.push(client);
 
       nock(FREE_API_URL)
-        .delete('/v3/glossaries/nonexistent/dictionaries?source_lang=EN&target_lang=ES')
+        .delete(
+          '/v3/glossaries/nonexistent/dictionaries?source_lang=EN&target_lang=ES'
+        )
         .reply(404, { message: 'Glossary not found' });
 
       await expect(
@@ -698,7 +747,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
       clients.push(client);
 
       nock(FREE_API_URL)
-        .delete('/v3/glossaries/glossary-123/dictionaries?source_lang=EN&target_lang=FR')
+        .delete(
+          '/v3/glossaries/glossary-123/dictionaries?source_lang=EN&target_lang=FR'
+        )
         .reply(404, { message: 'Dictionary not found in glossary' });
 
       await expect(
@@ -711,7 +762,9 @@ describe('DeepLClient v3 Glossary Integration', () => {
       clients.push(client);
 
       nock(FREE_API_URL)
-        .delete('/v3/glossaries/glossary-123/dictionaries?source_lang=EN&target_lang=ES')
+        .delete(
+          '/v3/glossaries/glossary-123/dictionaries?source_lang=EN&target_lang=ES'
+        )
         .reply(400, { message: 'Cannot delete last dictionary' });
 
       await expect(
@@ -735,7 +788,12 @@ describe('DeepLClient v3 Glossary Integration', () => {
         })
         .reply(204);
 
-      await client.replaceGlossaryDictionary('glossary-123', 'en', 'es', 'hello\thola');
+      await client.replaceGlossaryDictionary(
+        'glossary-123',
+        'en',
+        'es',
+        'hello\thola'
+      );
       expect(scope.isDone()).toBe(true);
     });
 
@@ -751,7 +809,12 @@ describe('DeepLClient v3 Glossary Integration', () => {
         })
         .reply(204);
 
-      await client.replaceGlossaryDictionary('glossary-456', 'en', 'fr', 'hello\tbonjour');
+      await client.replaceGlossaryDictionary(
+        'glossary-456',
+        'en',
+        'fr',
+        'hello\tbonjour'
+      );
       expect(scope.isDone()).toBe(true);
     });
 
@@ -764,7 +827,12 @@ describe('DeepLClient v3 Glossary Integration', () => {
         .reply(404, { message: 'Glossary not found' });
 
       await expect(
-        client.replaceGlossaryDictionary('nonexistent', 'en', 'es', 'hello\thola')
+        client.replaceGlossaryDictionary(
+          'nonexistent',
+          'en',
+          'es',
+          'hello\thola'
+        )
       ).rejects.toThrow();
     });
 
@@ -777,7 +845,12 @@ describe('DeepLClient v3 Glossary Integration', () => {
         .reply(404, { message: 'Dictionary not found' });
 
       await expect(
-        client.replaceGlossaryDictionary('glossary-123', 'en', 'zh', 'hello\t你好')
+        client.replaceGlossaryDictionary(
+          'glossary-123',
+          'en',
+          'zh',
+          'hello\t你好'
+        )
       ).rejects.toThrow();
     });
   });
diff --git a/tests/integration/file-translation.integration.test.ts b/tests/integration/file-translation.integration.test.ts
index c1eadbce..4dd88cc4 100644
--- a/tests/integration/file-translation.integration.test.ts
+++ b/tests/integration/file-translation.integration.test.ts
@@ -27,9 +27,17 @@ describe('FileTranslation Integration', () => {
     fs.mkdirSync(configDir, { recursive: true });
 
     client = new DeepLClient(TEST_API_KEY);
-    const configService = new ConfigService(path.join(configDir, 'config.json'));
-    const cacheService = new CacheService({ dbPath: path.join(configDir, 'cache.db') });
-    const translationService = new TranslationService(client, configService, cacheService);
+    const configService = new ConfigService(
+      path.join(configDir, 'config.json')
+    );
+    const cacheService = new CacheService({
+      dbPath: path.join(configDir, 'cache.db'),
+    });
+    const translationService = new TranslationService(
+      client,
+      configService,
+      cacheService
+    );
     service = new FileTranslationService(translationService);
   });
 
@@ -57,7 +65,9 @@ describe('FileTranslation Integration', () => {
           return true;
         })
         .reply(200, {
-          translations: [{ text: 'Hola mundo', detected_source_language: 'EN' }],
+          translations: [
+            { text: 'Hola mundo', detected_source_language: 'EN' },
+          ],
         });
 
       await service.translateFile(inputPath, outputPath, { targetLang: 'es' });
@@ -74,7 +84,12 @@ describe('FileTranslation Integration', () => {
       nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
-          translations: [{ text: '# Hallo\n\nDas ist ein Test.', detected_source_language: 'EN' }],
+          translations: [
+            {
+              text: '# Hallo\n\nDas ist ein Test.',
+              detected_source_language: 'EN',
+            },
+          ],
         });
 
       await service.translateFile(inputPath, outputPath, { targetLang: 'de' });
@@ -164,9 +179,13 @@ describe('FileTranslation Integration', () => {
 
       nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body) => body.target_lang === 'DE')
-        .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] })
+        .reply(200, {
+          translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+        })
         .post('/v2/translate', (body) => body.target_lang === 'FR')
-        .reply(200, { translations: [{ text: 'Bonjour', detected_source_language: 'EN' }] });
+        .reply(200, {
+          translations: [{ text: 'Bonjour', detected_source_language: 'EN' }],
+        });
 
       const results = await service.translateFileToMultiple(
         inputPath,
diff --git a/tests/integration/git-hooks-resolution.integration.test.ts b/tests/integration/git-hooks-resolution.integration.test.ts
index 7e770d22..43dfd695 100644
--- a/tests/integration/git-hooks-resolution.integration.test.ts
+++ b/tests/integration/git-hooks-resolution.integration.test.ts
@@ -35,7 +35,9 @@ describe('GitHooksService hooks directory resolution', () => {
   let tmpRoot: string;
 
   beforeEach(() => {
-    tmpRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-hooks-res-')));
+    tmpRoot = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-hooks-res-'))
+    );
   });
 
   afterEach(() => {
@@ -52,8 +54,12 @@ describe('GitHooksService hooks directory resolution', () => {
       const service = new GitHooksService(path.join(repo, '.git'));
       service.install('pre-commit');
 
-      expect(fs.existsSync(path.join(repo, '.husky', '_', 'pre-commit'))).toBe(true);
-      expect(fs.existsSync(path.join(repo, '.git', 'hooks', 'pre-commit'))).toBe(false);
+      expect(fs.existsSync(path.join(repo, '.husky', '_', 'pre-commit'))).toBe(
+        true
+      );
+      expect(
+        fs.existsSync(path.join(repo, '.git', 'hooks', 'pre-commit'))
+      ).toBe(false);
     });
 
     it('should report the effective hooks path from getHookPath', () => {
@@ -63,7 +69,9 @@ describe('GitHooksService hooks directory resolution', () => {
 
       const service = new GitHooksService(path.join(repo, '.git'));
 
-      expect(service.getHookPath('pre-push')).toBe(path.join(repo, '.husky', '_', 'pre-push'));
+      expect(service.getHookPath('pre-push')).toBe(
+        path.join(repo, '.husky', '_', 'pre-push')
+      );
     });
 
     it('should have list() reflect hooks installed at the effective path', () => {
@@ -74,7 +82,9 @@ describe('GitHooksService hooks directory resolution', () => {
       const service = new GitHooksService(path.join(repo, '.git'));
       service.install('commit-msg');
 
-      expect(fs.existsSync(path.join(repo, 'hooks-dir', 'commit-msg'))).toBe(true);
+      expect(fs.existsSync(path.join(repo, 'hooks-dir', 'commit-msg'))).toBe(
+        true
+      );
       expect(service.list()['commit-msg']).toBe(true);
       expect(service.isInstalled('commit-msg')).toBe(true);
     });
@@ -88,7 +98,9 @@ describe('GitHooksService hooks directory resolution', () => {
       service.install('pre-commit');
       service.uninstall('pre-commit');
 
-      expect(fs.existsSync(path.join(repo, '.husky', '_', 'pre-commit'))).toBe(false);
+      expect(fs.existsSync(path.join(repo, '.husky', '_', 'pre-commit'))).toBe(
+        false
+      );
     });
   });
 
@@ -106,7 +118,9 @@ describe('GitHooksService hooks directory resolution', () => {
       const service = new GitHooksService(gitFile);
       expect(() => service.install('pre-commit')).not.toThrow();
 
-      expect(fs.existsSync(path.join(repo, '.git', 'hooks', 'pre-commit'))).toBe(true);
+      expect(
+        fs.existsSync(path.join(repo, '.git', 'hooks', 'pre-commit'))
+      ).toBe(true);
       expect(service.isInstalled('pre-commit')).toBe(true);
     });
 
@@ -120,7 +134,16 @@ describe('GitHooksService hooks directory resolution', () => {
       const parent = path.join(tmpRoot, 'parent');
       initRepo(parent);
       git(parent, 'commit', '-q', '--allow-empty', '-m', 'init');
-      git(parent, '-c', 'protocol.file.allow=always', 'submodule', 'add', '-q', upstream, 'sub');
+      git(
+        parent,
+        '-c',
+        'protocol.file.allow=always',
+        'submodule',
+        'add',
+        '-q',
+        upstream,
+        'sub'
+      );
 
       const subGitFile = path.join(parent, 'sub', '.git');
       expect(fs.statSync(subGitFile).isFile()).toBe(true);
@@ -128,7 +151,14 @@ describe('GitHooksService hooks directory resolution', () => {
       const service = new GitHooksService(subGitFile);
       expect(() => service.install('pre-commit')).not.toThrow();
 
-      const expected = path.join(parent, '.git', 'modules', 'sub', 'hooks', 'pre-commit');
+      const expected = path.join(
+        parent,
+        '.git',
+        'modules',
+        'sub',
+        'hooks',
+        'pre-commit'
+      );
       expect(fs.existsSync(expected)).toBe(true);
       expect(service.isInstalled('pre-commit')).toBe(true);
     });
@@ -144,16 +174,22 @@ describe('GitHooksService hooks directory resolution', () => {
       const service = new GitHooksService(path.join(repo, '.git'));
       const first = service.install('pre-commit');
       expect(first.backupPath).toBe(hookPath + '.backup');
-      expect(fs.readFileSync(hookPath + '.backup', 'utf-8')).toContain('original user hook');
+      expect(fs.readFileSync(hookPath + '.backup', 'utf-8')).toContain(
+        'original user hook'
+      );
 
       // A third-party tool rewrites the hook, then deepl installs again.
       fs.writeFileSync(hookPath, '#!/bin/sh\n# husky wrapper\nexit 0\n');
       const second = service.install('pre-commit');
 
-      expect(fs.readFileSync(hookPath + '.backup', 'utf-8')).toContain('original user hook');
+      expect(fs.readFileSync(hookPath + '.backup', 'utf-8')).toContain(
+        'original user hook'
+      );
       expect(second.backupPath).not.toBe(hookPath + '.backup');
       expect(second.backupPath).toBeTruthy();
-      expect(fs.readFileSync(second.backupPath!, 'utf-8')).toContain('husky wrapper');
+      expect(fs.readFileSync(second.backupPath!, 'utf-8')).toContain(
+        'husky wrapper'
+      );
     });
 
     it('should report no backup path when no pre-existing hook is present', () => {
@@ -164,7 +200,9 @@ describe('GitHooksService hooks directory resolution', () => {
       const result = service.install('pre-push');
 
       expect(result.backupPath).toBeNull();
-      expect(result.hookPath).toBe(path.join(repo, '.git', 'hooks', 'pre-push'));
+      expect(result.hookPath).toBe(
+        path.join(repo, '.git', 'hooks', 'pre-push')
+      );
     });
 
     it('should not create a backup when replacing an existing DeepL hook', () => {
@@ -187,7 +225,9 @@ describe('GitHooksService hooks directory resolution', () => {
       const originalCwd = process.cwd();
       process.chdir(repo);
       try {
-        expect(GitHooksService.findGitRoot('.')).toBe(path.join(fs.realpathSync(repo), '.git'));
+        expect(GitHooksService.findGitRoot('.')).toBe(
+          path.join(fs.realpathSync(repo), '.git')
+        );
       } finally {
         process.chdir(originalCwd);
       }
diff --git a/tests/integration/sync-auto-commit.integration.test.ts b/tests/integration/sync-auto-commit.integration.test.ts
index 6961fd98..1823b01c 100644
--- a/tests/integration/sync-auto-commit.integration.test.ts
+++ b/tests/integration/sync-auto-commit.integration.test.ts
@@ -25,7 +25,10 @@ import { FormatRegistry } from '../../src/formats/index';
 import { JsonFormatParser } from '../../src/formats/json';
 import { ValidationError } from '../../src/utils/errors';
 import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
-import { createMockConfigService, createMockCacheService } from '../helpers/mock-factories';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
 
 function gitAvailable(): boolean {
   try {
@@ -37,7 +40,11 @@ function gitAvailable(): boolean {
 }
 
 function git(cwd: string, args: string[]): string {
-  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+  return execFileSync('git', args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
 }
 
 function initRepo(cwd: string): void {
@@ -53,7 +60,11 @@ function createServices() {
     get: jest.fn(() => ({
       auth: {},
       api: { baseUrl: '', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
       cache: { enabled: false },
       output: { format: 'text', color: true },
       proxy: {},
@@ -61,11 +72,19 @@ function createServices() {
     getValue: jest.fn(() => false),
   });
   const mockCache = createMockCacheService();
-  const translationService = new TranslationService(client, mockConfig, mockCache);
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    mockCache
+  );
   const glossaryService = new GlossaryService(client);
   const registry = new FormatRegistry();
   registry.register(new JsonFormatParser());
-  const syncService = new SyncService(translationService, glossaryService, registry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    registry
+  );
   return { client, syncService };
 }
 
@@ -95,7 +114,11 @@ function seedRepo(tmpDir: string): void {
   initRepo(tmpDir);
   fs.writeFileSync(path.join(tmpDir, '.deepl-sync.yaml'), SYNC_YAML, 'utf-8');
   fs.mkdirSync(path.join(tmpDir, 'locales'), { recursive: true });
-  fs.writeFileSync(path.join(tmpDir, 'locales', 'en.json'), SOURCE_JSON, 'utf-8');
+  fs.writeFileSync(
+    path.join(tmpDir, 'locales', 'en.json'),
+    SOURCE_JSON,
+    'utf-8'
+  );
   fs.writeFileSync(path.join(tmpDir, 'README.md'), '# test\n', 'utf-8');
   git(tmpDir, ['add', '.']);
   git(tmpDir, ['commit', '-q', '-m', 'initial']);
@@ -137,15 +160,24 @@ describeIfGit('SyncCommand auto-commit preflight', () => {
     expect(scope.isDone()).toBe(true);
 
     const head = git(tmpDir, ['rev-parse', 'HEAD']);
-    const firstCommit = git(tmpDir, ['rev-list', '--max-parents=0', 'HEAD']).trim();
+    const firstCommit = git(tmpDir, [
+      'rev-list',
+      '--max-parents=0',
+      'HEAD',
+    ]).trim();
     expect(head.trim()).not.toBe(firstCommit);
 
     const branch = git(tmpDir, ['symbolic-ref', '--short', 'HEAD']).trim();
     expect(branch).toBe('main');
 
-    const changedFiles = git(tmpDir, ['show', '--name-only', '--pretty=format:', 'HEAD'])
+    const changedFiles = git(tmpDir, [
+      'show',
+      '--name-only',
+      '--pretty=format:',
+      'HEAD',
+    ])
       .split('\n')
-      .map(s => s.trim())
+      .map((s) => s.trim())
       .filter(Boolean)
       .sort();
     expect(changedFiles).toEqual(['.deepl-sync.lock', 'locales/de.json']);
@@ -164,7 +196,9 @@ describeIfGit('SyncCommand auto-commit preflight', () => {
 
     const command = new SyncCommand(syncService);
 
-    await expect(command.run({ autoCommit: true })).rejects.toThrow(ValidationError);
+    await expect(command.run({ autoCommit: true })).rejects.toThrow(
+      ValidationError
+    );
     try {
       await command.run({ autoCommit: true });
     } catch (err) {
@@ -187,16 +221,24 @@ describeIfGit('SyncCommand auto-commit preflight', () => {
     // Simulate a mid-rebase repo by writing the rebase-merge directory.
     const rebaseDir = path.join(tmpDir, '.git', 'rebase-merge');
     fs.mkdirSync(rebaseDir, { recursive: true });
-    fs.writeFileSync(path.join(rebaseDir, 'head-name'), 'refs/heads/main\n', 'utf-8');
+    fs.writeFileSync(
+      path.join(rebaseDir, 'head-name'),
+      'refs/heads/main\n',
+      'utf-8'
+    );
     seedTranslateMock();
 
     const command = new SyncCommand(syncService);
-    await expect(command.run({ autoCommit: true })).rejects.toThrow(ValidationError);
+    await expect(command.run({ autoCommit: true })).rejects.toThrow(
+      ValidationError
+    );
     try {
       await command.run({ autoCommit: true });
     } catch (err) {
       expect((err as Error).message).toMatch(/Refusing to auto-commit/i);
-      expect((err as Error).message).toMatch(/rebase|merge|cherry-pick|in progress/i);
+      expect((err as Error).message).toMatch(
+        /rebase|merge|cherry-pick|in progress/i
+      );
     }
   });
 
@@ -212,7 +254,9 @@ describeIfGit('SyncCommand auto-commit preflight', () => {
     seedTranslateMock();
 
     const command = new SyncCommand(syncService);
-    await expect(command.run({ autoCommit: true })).rejects.toThrow(ValidationError);
+    await expect(command.run({ autoCommit: true })).rejects.toThrow(
+      ValidationError
+    );
     try {
       await command.run({ autoCommit: true });
     } catch (err) {
@@ -231,12 +275,16 @@ describeIfGit('SyncCommand auto-commit preflight', () => {
     scope.persist();
 
     const command = new SyncCommand(syncService);
-    await expect(command.run({ autoCommit: true })).rejects.toThrow(ValidationError);
+    await expect(command.run({ autoCommit: true })).rejects.toThrow(
+      ValidationError
+    );
 
     // Written before the refusal, so the retry finds nothing to translate.
     expect(fs.existsSync(path.join(tmpDir, 'locales', 'de.json'))).toBe(true);
 
-    await expect(command.run({ autoCommit: true })).rejects.toThrow(/Refusing to auto-commit/i);
+    await expect(command.run({ autoCommit: true })).rejects.toThrow(
+      /Refusing to auto-commit/i
+    );
 
     nock.cleanAll();
     expect(git(tmpDir, ['log', '-1', '--pretty=%s']).trim()).toBe('initial');
@@ -252,7 +300,9 @@ describeIfGit('SyncCommand auto-commit preflight', () => {
     scope.persist();
 
     const command = new SyncCommand(syncService);
-    await expect(command.run({ autoCommit: true })).rejects.toThrow(ValidationError);
+    await expect(command.run({ autoCommit: true })).rejects.toThrow(
+      ValidationError
+    );
     expect(fs.existsSync(path.join(tmpDir, 'locales', 'de.json'))).toBe(true);
 
     // Deal with the unrelated change; the leftover translation remains.
@@ -261,7 +311,9 @@ describeIfGit('SyncCommand auto-commit preflight', () => {
     await command.run({ autoCommit: true });
 
     nock.cleanAll();
-    expect(git(tmpDir, ['log', '-1', '--pretty=%s']).trim()).toContain('chore(i18n)');
+    expect(git(tmpDir, ['log', '-1', '--pretty=%s']).trim()).toContain(
+      'chore(i18n)'
+    );
     expect(git(tmpDir, ['status', '--porcelain']).trim()).toBe('');
   });
 
@@ -275,8 +327,12 @@ describeIfGit('SyncCommand auto-commit preflight', () => {
     scope.persist();
 
     const command = new SyncCommand(syncService);
-    await expect(command.run({ autoCommit: true })).rejects.toThrow(/Refusing to auto-commit/i);
-    await expect(command.run({ autoCommit: true })).rejects.toThrow(/Refusing to auto-commit/i);
+    await expect(command.run({ autoCommit: true })).rejects.toThrow(
+      /Refusing to auto-commit/i
+    );
+    await expect(command.run({ autoCommit: true })).rejects.toThrow(
+      /Refusing to auto-commit/i
+    );
 
     // Nothing left to commit: neither throws nor commits.
     fs.unlinkSync(path.join(tmpDir, 'src.ts'));
diff --git a/tests/integration/sync-concurrent.integration.test.ts b/tests/integration/sync-concurrent.integration.test.ts
index 51efdb4e..29f59f29 100644
--- a/tests/integration/sync-concurrent.integration.test.ts
+++ b/tests/integration/sync-concurrent.integration.test.ts
@@ -15,7 +15,10 @@ import { loadSyncConfig } from '../../src/sync/sync-config';
 import { ConfigError } from '../../src/utils/errors';
 import { PROCESS_LOCK_FILE_NAME } from '../../src/sync/sync-process-lock';
 import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
-import { createMockConfigService, createMockCacheService } from '../helpers/mock-factories';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
 import { handleSyncPull } from '../../src/cli/commands/sync/register-sync-pull';
 
 function createServices(): { client: DeepLClient; syncService: SyncService } {
@@ -24,7 +27,11 @@ function createServices(): { client: DeepLClient; syncService: SyncService } {
     get: jest.fn(() => ({
       auth: {},
       api: { baseUrl: '', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
       cache: { enabled: false },
       output: { format: 'text', color: true },
       proxy: {},
@@ -32,11 +39,19 @@ function createServices(): { client: DeepLClient; syncService: SyncService } {
     getValue: jest.fn(() => false),
   });
   const mockCache = createMockCacheService();
-  const translationService = new TranslationService(client, mockConfig, mockCache);
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    mockCache
+  );
   const glossaryService = new GlossaryService(client);
   const registry = new FormatRegistry();
   registry.register(new JsonFormatParser());
-  const syncService = new SyncService(translationService, glossaryService, registry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    registry
+  );
   return { client, syncService };
 }
 
@@ -90,7 +105,11 @@ describe('Sync Concurrent Runs Integration', () => {
       .post('/v2/translate')
       .reply(200, {
         translations: [
-          { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
+          {
+            text: 'Hallo',
+            detected_source_language: 'EN',
+            billed_characters: 5,
+          },
         ],
       });
 
@@ -118,8 +137,11 @@ describe('Sync Concurrent Runs Integration', () => {
     const stalePid = findDeadPid();
     fs.writeFileSync(
       pidFile,
-      JSON.stringify({ pid: stalePid, startedAt: new Date(Date.now() - 60_000).toISOString() }),
-      'utf-8',
+      JSON.stringify({
+        pid: stalePid,
+        startedAt: new Date(Date.now() - 60_000).toISOString(),
+      }),
+      'utf-8'
     );
 
     const warnSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
@@ -128,7 +150,11 @@ describe('Sync Concurrent Runs Integration', () => {
       .post('/v2/translate')
       .reply(200, {
         translations: [
-          { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
+          {
+            text: 'Hallo',
+            detected_source_language: 'EN',
+            billed_characters: 5,
+          },
         ],
       });
 
@@ -138,7 +164,9 @@ describe('Sync Concurrent Runs Integration', () => {
       expect(result.success).toBe(true);
       expect(fs.existsSync(pidFile)).toBe(false);
 
-      const warnCalls = warnSpy.mock.calls.map(args => args.join(' ')).join('\n');
+      const warnCalls = warnSpy.mock.calls
+        .map((args) => args.join(' '))
+        .join('\n');
       expect(warnCalls.toLowerCase()).toContain('stale');
     } finally {
       warnSpy.mockRestore();
@@ -153,7 +181,7 @@ describe('Sync Concurrent Runs Integration', () => {
     fs.writeFileSync(
       pidFile,
       JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }),
-      'utf-8',
+      'utf-8'
     );
 
     const config = await loadSyncConfig(tmpDir);
@@ -212,7 +240,11 @@ tms:
     fs.writeFileSync(path.join(tmpDir, '.deepl-sync.yaml'), TMS_YAML, 'utf-8');
     const localesDir = path.join(tmpDir, 'locales');
     fs.mkdirSync(localesDir, { recursive: true });
-    fs.writeFileSync(path.join(localesDir, 'en.json'), JSON.stringify({ hello: 'Hello' }, null, 2) + '\n', 'utf-8');
+    fs.writeFileSync(
+      path.join(localesDir, 'en.json'),
+      JSON.stringify({ hello: 'Hello' }, null, 2) + '\n',
+      'utf-8'
+    );
     process.env['TMS_API_KEY'] = 'test-key';
   });
 
@@ -229,13 +261,18 @@ tms:
     fs.writeFileSync(
       pidFile,
       JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }),
-      'utf-8',
+      'utf-8'
     );
 
-    const handleError = jest.fn((err: Error) => { throw err; });
+    const handleError = jest.fn((err: Error) => {
+      throw err;
+    });
 
     await expect(
-      handleSyncPull({ syncConfig: path.join(tmpDir, '.deepl-sync.yaml'), format: 'text' }, handleError),
+      handleSyncPull(
+        { syncConfig: path.join(tmpDir, '.deepl-sync.yaml'), format: 'text' },
+        handleError
+      )
     ).rejects.toMatchObject({
       name: 'ConfigError',
       exitCode: 7,
diff --git a/tests/integration/sync-export-path-traversal.integration.test.ts b/tests/integration/sync-export-path-traversal.integration.test.ts
index cd49719e..afd5b27c 100644
--- a/tests/integration/sync-export-path-traversal.integration.test.ts
+++ b/tests/integration/sync-export-path-traversal.integration.test.ts
@@ -39,21 +39,27 @@ describe('sync export source-side path-traversal safety', () => {
   let harness: ReturnType<typeof createSyncHarness>;
 
   beforeEach(() => {
-    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-export-traversal-proj-'));
-    outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-export-traversal-secret-'));
+    projectDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'deepl-sync-export-traversal-proj-')
+    );
+    outsideDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'deepl-sync-export-traversal-secret-')
+    );
     outsideSecret = path.join(outsideDir, 'secret.json');
     fs.writeFileSync(
       outsideSecret,
       JSON.stringify({ exfiltrated: 'TOP_SECRET_VALUE' }, null, 2),
-      'utf-8',
+      'utf-8'
     );
     harness = createSyncHarness({ parsers: ['json'] });
   });
 
   afterEach(() => {
     harness.cleanup();
-    if (fs.existsSync(projectDir)) fs.rmSync(projectDir, { recursive: true, force: true });
-    if (fs.existsSync(outsideDir)) fs.rmSync(outsideDir, { recursive: true, force: true });
+    if (fs.existsSync(projectDir))
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    if (fs.existsSync(outsideDir))
+      fs.rmSync(outsideDir, { recursive: true, force: true });
   });
 
   it('rejects an absolute include pattern at config load', async () => {
@@ -66,7 +72,9 @@ describe('sync export source-side path-traversal safety', () => {
 
     // Containment is now enforced at the boundary, so such a config never
     // loads — the export-time guard below is the second line of defence.
-    await expect(loadSyncConfig(projectDir)).rejects.toThrow(/relative to the project root/);
+    await expect(loadSyncConfig(projectDir)).rejects.toThrow(
+      /relative to the project root/
+    );
   });
 
   it('still rejects an out-of-root source file at export time', async () => {
@@ -84,10 +92,12 @@ describe('sync export source-side path-traversal safety', () => {
       buckets: { json: { include: [path.join(outsideDir, '*.json')] } },
     };
 
-    await expect(exportTranslations(escaping, harness.registry)).rejects.toThrow(ValidationError);
-    await expect(exportTranslations(escaping, harness.registry)).rejects.toThrow(
-      /escapes project root/,
-    );
+    await expect(
+      exportTranslations(escaping, harness.registry)
+    ).rejects.toThrow(ValidationError);
+    await expect(
+      exportTranslations(escaping, harness.registry)
+    ).rejects.toThrow(/escapes project root/);
   });
 
   it('does not embed outside-the-root file contents in the XLIFF output', async () => {
@@ -118,7 +128,9 @@ describe('sync export source-side path-traversal safety', () => {
     // And make sure the secret never leaked into an XLIFF buffer.
     // (result is undefined, so this is belt-and-braces.)
     if (result !== undefined) {
-      expect((result as { content: string }).content).not.toContain('TOP_SECRET_VALUE');
+      expect((result as { content: string }).content).not.toContain(
+        'TOP_SECRET_VALUE'
+      );
     }
   });
 
diff --git a/tests/integration/sync-init-format-choices.integration.test.ts b/tests/integration/sync-init-format-choices.integration.test.ts
index 1dd63680..2cab0a29 100644
--- a/tests/integration/sync-init-format-choices.integration.test.ts
+++ b/tests/integration/sync-init-format-choices.integration.test.ts
@@ -25,10 +25,14 @@ function makeDeps(): ServiceDeps {
   };
 }
 
-function findFileFormatChoices(program: Command): readonly string[] | undefined {
+function findFileFormatChoices(
+  program: Command
+): readonly string[] | undefined {
   const syncCmd = program.commands.find((c) => c.name() === 'sync');
   const initCmd = syncCmd?.commands.find((c) => c.name() === 'init');
-  const fileFormatOpt = initCmd?.options.find((o) => o.long === '--file-format');
+  const fileFormatOpt = initCmd?.options.find(
+    (o) => o.long === '--file-format'
+  );
   return fileFormatOpt?.argChoices;
 }
 
@@ -75,7 +79,9 @@ describe('deepl sync init --file-format choices mirror the format registry', ()
   it('rejects a --file-format value outside the registry keys', async () => {
     const program = buildProgram();
     await expect(
-      program.parseAsync(['sync', 'init', '--file-format', 'bogus'], { from: 'user' })
+      program.parseAsync(['sync', 'init', '--file-format', 'bogus'], {
+        from: 'user',
+      })
     ).rejects.toMatchObject({ code: 'commander.invalidArgument' });
   });
 });
diff --git a/tests/integration/sync-init.integration.test.ts b/tests/integration/sync-init.integration.test.ts
index 8a044ad6..2033ea72 100644
--- a/tests/integration/sync-init.integration.test.ts
+++ b/tests/integration/sync-init.integration.test.ts
@@ -13,13 +13,12 @@ import * as path from 'path';
 import * as os from 'os';
 import * as YAML from 'yaml';
 import fg from 'fast-glob';
-import {
-  detectI18nFiles,
-  generateSyncConfig,
-} from '../../src/sync/sync-init';
+import { detectI18nFiles, generateSyncConfig } from '../../src/sync/sync-init';
 
 function makeTmpDir(label: string): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `deepl-sync-init-integ-${label}-`));
+  const dir = fs.mkdtempSync(
+    path.join(os.tmpdir(), `deepl-sync-init-integ-${label}-`)
+  );
   return dir;
 }
 
@@ -48,10 +47,14 @@ describe('sync init auto-detection with real fast-glob', () => {
   describe('JSON (i18next)', () => {
     it('should detect, generate config, and match source files with fast-glob', async () => {
       tmpDir = makeTmpDir('json');
-      writeFile(tmpDir, 'locales/en.json', '{"greeting":"Hello","farewell":"Goodbye"}');
+      writeFile(
+        tmpDir,
+        'locales/en.json',
+        '{"greeting":"Hello","farewell":"Goodbye"}'
+      );
 
       const detected = await detectI18nFiles(tmpDir);
-      const project = detected.find(p => p.format === 'json');
+      const project = detected.find((p) => p.format === 'json');
       expect(project).toBeDefined();
       expect(project!.pattern).toBe('locales/en.json');
       expect(project!.targetPathPattern).toBeUndefined();
@@ -67,7 +70,9 @@ describe('sync init auto-detection with real fast-glob', () => {
       const parsed = YAML.parse(yaml) as ParsedConfig;
       expect(parsed.buckets['json']!.target_path_pattern).toBeUndefined();
 
-      const matched = await fg(parsed.buckets['json']!.include, { cwd: tmpDir });
+      const matched = await fg(parsed.buckets['json']!.include, {
+        cwd: tmpDir,
+      });
       expect(matched).toContain('locales/en.json');
     });
   });
@@ -75,10 +80,14 @@ describe('sync init auto-detection with real fast-glob', () => {
   describe('YAML (Rails)', () => {
     it('should detect, generate config, and match source files with fast-glob', async () => {
       tmpDir = makeTmpDir('yaml');
-      writeFile(tmpDir, 'locales/en.yaml', 'greeting: Hello\nfarewell: Goodbye\n');
+      writeFile(
+        tmpDir,
+        'locales/en.yaml',
+        'greeting: Hello\nfarewell: Goodbye\n'
+      );
 
       const detected = await detectI18nFiles(tmpDir);
-      const project = detected.find(p => p.format === 'yaml');
+      const project = detected.find((p) => p.format === 'yaml');
       expect(project).toBeDefined();
       expect(project!.pattern).toBe('locales/en.yaml');
       expect(project!.targetPathPattern).toBeUndefined();
@@ -91,7 +100,9 @@ describe('sync init auto-detection with real fast-glob', () => {
       });
       const parsed = YAML.parse(yaml) as ParsedConfig;
 
-      const matched = await fg(parsed.buckets['yaml']!.include, { cwd: tmpDir });
+      const matched = await fg(parsed.buckets['yaml']!.include, {
+        cwd: tmpDir,
+      });
       expect(matched).toContain('locales/en.yaml');
     });
   });
@@ -99,14 +110,19 @@ describe('sync init auto-detection with real fast-glob', () => {
   describe('Android XML', () => {
     it('should detect with target_path_pattern and match source files', async () => {
       tmpDir = makeTmpDir('android');
-      writeFile(tmpDir, 'res/values/strings.xml',
-        '<?xml version="1.0" encoding="utf-8"?>\n<resources><string name="app_name">App</string></resources>');
+      writeFile(
+        tmpDir,
+        'res/values/strings.xml',
+        '<?xml version="1.0" encoding="utf-8"?>\n<resources><string name="app_name">App</string></resources>'
+      );
 
       const detected = await detectI18nFiles(tmpDir);
-      const project = detected.find(p => p.format === 'android_xml');
+      const project = detected.find((p) => p.format === 'android_xml');
       expect(project).toBeDefined();
       expect(project!.pattern).toBe('res/values/strings.xml');
-      expect(project!.targetPathPattern).toBe('res/values-{locale}/strings.xml');
+      expect(project!.targetPathPattern).toBe(
+        'res/values-{locale}/strings.xml'
+      );
 
       const yaml = generateSyncConfig({
         sourceLocale: 'en',
@@ -116,17 +132,23 @@ describe('sync init auto-detection with real fast-glob', () => {
         targetPathPattern: project!.targetPathPattern,
       });
       const parsed = YAML.parse(yaml) as ParsedConfig;
-      expect(parsed.buckets['android_xml']!.target_path_pattern).toBe('res/values-{locale}/strings.xml');
+      expect(parsed.buckets['android_xml']!.target_path_pattern).toBe(
+        'res/values-{locale}/strings.xml'
+      );
 
-      const matched = await fg(parsed.buckets['android_xml']!.include, { cwd: tmpDir });
+      const matched = await fg(parsed.buckets['android_xml']!.include, {
+        cwd: tmpDir,
+      });
       expect(matched).toContain('res/values/strings.xml');
     });
 
     it('should resolve target paths from target_path_pattern', async () => {
       const { resolveTargetPath } = await import('../../src/sync/sync-utils');
       const result = resolveTargetPath(
-        'res/values/strings.xml', 'en', 'de',
-        'res/values-{locale}/strings.xml',
+        'res/values/strings.xml',
+        'en',
+        'de',
+        'res/values-{locale}/strings.xml'
       );
       expect(result).toBe('res/values-de/strings.xml');
     });
@@ -135,10 +157,14 @@ describe('sync init auto-detection with real fast-glob', () => {
   describe('iOS Strings', () => {
     it('should detect and match source files (locale in path)', async () => {
       tmpDir = makeTmpDir('ios');
-      writeFile(tmpDir, 'en.lproj/Localizable.strings', '"greeting" = "Hello";\n"farewell" = "Goodbye";');
+      writeFile(
+        tmpDir,
+        'en.lproj/Localizable.strings',
+        '"greeting" = "Hello";\n"farewell" = "Goodbye";'
+      );
 
       const detected = await detectI18nFiles(tmpDir);
-      const project = detected.find(p => p.format === 'ios_strings');
+      const project = detected.find((p) => p.format === 'ios_strings');
       expect(project).toBeDefined();
       expect(project!.pattern).toBe('en.lproj/Localizable.strings');
       expect(project!.targetPathPattern).toBeUndefined();
@@ -151,7 +177,9 @@ describe('sync init auto-detection with real fast-glob', () => {
       });
       const parsed = YAML.parse(yaml) as ParsedConfig;
 
-      const matched = await fg(parsed.buckets['ios_strings']!.include, { cwd: tmpDir });
+      const matched = await fg(parsed.buckets['ios_strings']!.include, {
+        cwd: tmpDir,
+      });
       expect(matched).toContain('en.lproj/Localizable.strings');
     });
   });
@@ -159,11 +187,14 @@ describe('sync init auto-detection with real fast-glob', () => {
   describe('PO (Django)', () => {
     it('should detect and match source files (locale in path)', async () => {
       tmpDir = makeTmpDir('po');
-      writeFile(tmpDir, 'locale/en/LC_MESSAGES/django.po',
-        'msgid "greeting"\nmsgstr "Hello"\n');
+      writeFile(
+        tmpDir,
+        'locale/en/LC_MESSAGES/django.po',
+        'msgid "greeting"\nmsgstr "Hello"\n'
+      );
 
       const detected = await detectI18nFiles(tmpDir);
-      const project = detected.find(p => p.format === 'po');
+      const project = detected.find((p) => p.format === 'po');
       expect(project).toBeDefined();
       expect(project!.pattern).toBe('locale/en/LC_MESSAGES/*.po');
       expect(project!.targetPathPattern).toBeUndefined();
@@ -184,14 +215,19 @@ describe('sync init auto-detection with real fast-glob', () => {
   describe('XLIFF (Angular)', () => {
     it('should detect with target_path_pattern and match source files', async () => {
       tmpDir = makeTmpDir('xliff');
-      writeFile(tmpDir, 'src/locale/messages.xlf',
-        '<?xml version="1.0" encoding="UTF-8"?>\n<xliff version="1.2"></xliff>');
+      writeFile(
+        tmpDir,
+        'src/locale/messages.xlf',
+        '<?xml version="1.0" encoding="UTF-8"?>\n<xliff version="1.2"></xliff>'
+      );
 
       const detected = await detectI18nFiles(tmpDir);
-      const project = detected.find(p => p.format === 'xliff');
+      const project = detected.find((p) => p.format === 'xliff');
       expect(project).toBeDefined();
       expect(project!.pattern).toBe('src/locale/messages.xlf');
-      expect(project!.targetPathPattern).toBe('src/locale/messages.{locale}.xlf');
+      expect(project!.targetPathPattern).toBe(
+        'src/locale/messages.{locale}.xlf'
+      );
 
       const yaml = generateSyncConfig({
         sourceLocale: 'en',
@@ -201,17 +237,23 @@ describe('sync init auto-detection with real fast-glob', () => {
         targetPathPattern: project!.targetPathPattern,
       });
       const parsed = YAML.parse(yaml) as ParsedConfig;
-      expect(parsed.buckets['xliff']!.target_path_pattern).toBe('src/locale/messages.{locale}.xlf');
+      expect(parsed.buckets['xliff']!.target_path_pattern).toBe(
+        'src/locale/messages.{locale}.xlf'
+      );
 
-      const matched = await fg(parsed.buckets['xliff']!.include, { cwd: tmpDir });
+      const matched = await fg(parsed.buckets['xliff']!.include, {
+        cwd: tmpDir,
+      });
       expect(matched).toContain('src/locale/messages.xlf');
     });
 
     it('should resolve target paths from target_path_pattern', async () => {
       const { resolveTargetPath } = await import('../../src/sync/sync-utils');
       const result = resolveTargetPath(
-        'src/locale/messages.xlf', 'en', 'de',
-        'src/locale/messages.{locale}.xlf',
+        'src/locale/messages.xlf',
+        'en',
+        'de',
+        'src/locale/messages.{locale}.xlf'
       );
       expect(result).toBe('src/locale/messages.de.xlf');
     });
@@ -225,7 +267,7 @@ describe('sync init auto-detection with real fast-glob', () => {
       writeFile(tmpDir, 'l10n/app_en.arb', '{"greeting":"Hello"}');
 
       const detected = await detectI18nFiles(tmpDir);
-      const project = detected.find(p => p.format === 'arb');
+      const project = detected.find((p) => p.format === 'arb');
       expect(project).toBeDefined();
       expect(project!.pattern).toBe('l10n/app_en.arb');
       expect(project!.targetPathPattern).toBeUndefined();
@@ -247,7 +289,7 @@ describe('sync init auto-detection with real fast-glob', () => {
       writeFile(tmpDir, 'l10n/app_en.arb', '{"greeting":"Hello"}');
 
       const detected = await detectI18nFiles(tmpDir);
-      expect(detected.find(p => p.format === 'arb')).toBeUndefined();
+      expect(detected.find((p) => p.format === 'arb')).toBeUndefined();
     });
   });
 });
diff --git a/tests/integration/sync-locale-translator-plural-perf.integration.test.ts b/tests/integration/sync-locale-translator-plural-perf.integration.test.ts
index 4120f4a9..ca0efd09 100644
--- a/tests/integration/sync-locale-translator-plural-perf.integration.test.ts
+++ b/tests/integration/sync-locale-translator-plural-perf.integration.test.ts
@@ -18,12 +18,20 @@ const PLURAL_COUNT = 5_000;
 const LOCALE_COUNT = 50;
 const THRESHOLD_MS = 1_000;
 
-function buildFixture(n: number): { batchIndices: number[]; pluralSlots: PluralSlot[] } {
+function buildFixture(n: number): {
+  batchIndices: number[];
+  pluralSlots: PluralSlot[];
+} {
   const batchIndices: number[] = [];
   const pluralSlots: PluralSlot[] = [];
   for (let i = 0; i < n; i++) {
     batchIndices.push(i);
-    pluralSlots.push({ diffIndex: i, format: 'po', slotKey: 'msgid_plural', textIndex: n + i });
+    pluralSlots.push({
+      diffIndex: i,
+      format: 'po',
+      slotKey: 'msgid_plural',
+      textIndex: n + i,
+    });
   }
   return { batchIndices, pluralSlots };
 }
@@ -32,7 +40,7 @@ describe('pluralSlots batchIndices membership lookup', () => {
   it('Set.has produces identical membership results to Array.includes for known inputs', () => {
     const batchIndices = [0, 2, 4, 6, 8];
     const batchSet = new Set(batchIndices);
-    const slots: PluralSlot[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].map(i => ({
+    const slots: PluralSlot[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].map((i) => ({
       diffIndex: i,
       format: 'po',
       slotKey: 'msgid_plural',
@@ -40,7 +48,9 @@ describe('pluralSlots batchIndices membership lookup', () => {
     }));
 
     for (const slot of slots) {
-      expect(batchSet.has(slot.diffIndex)).toBe(batchIndices.includes(slot.diffIndex));
+      expect(batchSet.has(slot.diffIndex)).toBe(
+        batchIndices.includes(slot.diffIndex)
+      );
     }
   });
 
@@ -58,7 +68,9 @@ describe('pluralSlots batchIndices membership lookup', () => {
       }
       const elapsed = Date.now() - start;
       expect(hits).toBe(PLURAL_COUNT * LOCALE_COUNT);
-      console.log(`[bench] Array.includes baseline: ${elapsed}ms (hits=${hits})`);
+      console.log(
+        `[bench] Array.includes baseline: ${elapsed}ms (hits=${hits})`
+      );
     });
 
     it('Set.has O(N) lookup completes in under 1s for 50 locales × 5K pluralSlots', () => {
diff --git a/tests/integration/sync-php-arrays.integration.test.ts b/tests/integration/sync-php-arrays.integration.test.ts
index 803336cb..d08b6db2 100644
--- a/tests/integration/sync-php-arrays.integration.test.ts
+++ b/tests/integration/sync-php-arrays.integration.test.ts
@@ -22,7 +22,10 @@ import { FormatRegistry } from '../../src/formats/index';
 import { PhpArraysFormatParser } from '../../src/formats/php-arrays';
 import type { ResolvedSyncConfig } from '../../src/sync/sync-config';
 
-const CORPUS_DIR = path.resolve(__dirname, '../fixtures/sync/formats/laravel-php');
+const CORPUS_DIR = path.resolve(
+  __dirname,
+  '../fixtures/sync/formats/laravel-php'
+);
 
 function makeRegistry(): FormatRegistry {
   const registry = new FormatRegistry();
@@ -30,7 +33,10 @@ function makeRegistry(): FormatRegistry {
   return registry;
 }
 
-function makeConfig(projectRoot: string, overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+function makeConfig(
+  projectRoot: string,
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -72,7 +78,10 @@ describe('sync-php-arrays corpus integration', () => {
   beforeEach(() => {
     projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-laravel-'));
     for (const name of ACCEPT_FIXTURES) {
-      fs.copyFileSync(path.join(CORPUS_DIR, name), path.join(projectRoot, name));
+      fs.copyFileSync(
+        path.join(CORPUS_DIR, name),
+        path.join(projectRoot, name)
+      );
     }
   });
 
@@ -83,7 +92,9 @@ describe('sync-php-arrays corpus integration', () => {
   });
 
   it('walks the full accept corpus through walkBuckets with no extract errors', async () => {
-    const result = await collect(walkBuckets(makeConfig(projectRoot), makeRegistry()));
+    const result = await collect(
+      walkBuckets(makeConfig(projectRoot), makeRegistry())
+    );
     expect(result).toHaveLength(ACCEPT_FIXTURES.length);
     for (const walked of result) {
       expect(walked.bucket).toBe('laravel_php');
@@ -92,15 +103,24 @@ describe('sync-php-arrays corpus integration', () => {
   });
 
   it('byte-equal reconstruct on every walked file when translations equal source', async () => {
-    const result = await collect(walkBuckets(makeConfig(projectRoot), makeRegistry()));
+    const result = await collect(
+      walkBuckets(makeConfig(projectRoot), makeRegistry())
+    );
     for (const walked of result) {
-      const translations = walked.entries.map((e) => ({ ...e, translation: e.value }));
-      expect(walked.parser.reconstruct(walked.content, translations)).toBe(walked.content);
+      const translations = walked.entries.map((e) => ({
+        ...e,
+        translation: e.value,
+      }));
+      expect(walked.parser.reconstruct(walked.content, translations)).toBe(
+        walked.content
+      );
     }
   });
 
   it('tags no entries as skipped for any corpus fixture (no pipe-pluralization in 01-15)', async () => {
-    const result = await collect(walkBuckets(makeConfig(projectRoot), makeRegistry()));
+    const result = await collect(
+      walkBuckets(makeConfig(projectRoot), makeRegistry())
+    );
     for (const walked of result) {
       expect(walked.skippedEntries).toEqual([]);
     }
@@ -112,7 +132,7 @@ describe('sync-php-arrays corpus integration', () => {
     fs.writeFileSync(
       bigPath,
       `<?php\n// ${padding}\nreturn ['a' => 'Hello'];\n`,
-      'utf-8',
+      'utf-8'
     );
 
     const config = makeConfig(projectRoot, {
@@ -148,7 +168,7 @@ describe('sync-php-arrays corpus integration', () => {
         '12-escaped-dollar.php',
         '13-utf8-bom.php',
         '14-literal-pipe-in-prose.php',
-      ].sort(),
+      ].sort()
     );
   });
 });
diff --git a/tests/integration/sync-properties.integration.test.ts b/tests/integration/sync-properties.integration.test.ts
index c614bfac..f7618d93 100644
--- a/tests/integration/sync-properties.integration.test.ts
+++ b/tests/integration/sync-properties.integration.test.ts
@@ -24,7 +24,10 @@ import { PropertiesFormatParser } from '../../src/formats/properties';
 import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
 import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
 
-const FIXTURE_DIR = path.resolve(__dirname, '../fixtures/sync/formats/properties');
+const FIXTURE_DIR = path.resolve(
+  __dirname,
+  '../fixtures/sync/formats/properties'
+);
 
 describe('sync Java properties fixture round-trip', () => {
   let tmpDir: string;
@@ -44,10 +47,13 @@ describe('sync Java properties fixture round-trip', () => {
   });
 
   it('translates source.properties and writes de.properties matching the expected fixture', async () => {
-    const source = fs.readFileSync(path.join(FIXTURE_DIR, 'source.properties'), 'utf-8');
+    const source = fs.readFileSync(
+      path.join(FIXTURE_DIR, 'source.properties'),
+      'utf-8'
+    );
     const expected = fs.readFileSync(
       path.join(FIXTURE_DIR, 'expected-after-sync', 'de.properties'),
-      'utf-8',
+      'utf-8'
     );
 
     writeSyncConfig(tmpDir, {
@@ -64,9 +70,21 @@ describe('sync Java properties fixture round-trip', () => {
         // Order matches alphabetical sort from PropertiesFormatParser.extract():
         // farewell, greeting, welcome
         translations: [
-          { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-          { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-          { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+          {
+            text: 'Auf Wiedersehen',
+            detected_source_language: 'EN',
+            billed_characters: 15,
+          },
+          {
+            text: 'Hallo',
+            detected_source_language: 'EN',
+            billed_characters: 5,
+          },
+          {
+            text: 'Willkommen',
+            detected_source_language: 'EN',
+            billed_characters: 10,
+          },
         ],
       });
 
diff --git a/tests/integration/sync-scan-bounds.integration.test.ts b/tests/integration/sync-scan-bounds.integration.test.ts
index ceadfa2a..124b9059 100644
--- a/tests/integration/sync-scan-bounds.integration.test.ts
+++ b/tests/integration/sync-scan-bounds.integration.test.ts
@@ -14,7 +14,10 @@ import { JsonFormatParser } from '../../src/formats/json';
 import { loadSyncConfig } from '../../src/sync/sync-config';
 import { ValidationError } from '../../src/utils/errors';
 import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
-import { createMockConfigService, createMockCacheService } from '../helpers/mock-factories';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
 
 function createServices(): { client: DeepLClient; syncService: SyncService } {
   const client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
@@ -22,7 +25,11 @@ function createServices(): { client: DeepLClient; syncService: SyncService } {
     get: jest.fn(() => ({
       auth: {},
       api: { baseUrl: '', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
       cache: { enabled: false },
       output: { format: 'text', color: true },
       proxy: {},
@@ -30,11 +37,19 @@ function createServices(): { client: DeepLClient; syncService: SyncService } {
     getValue: jest.fn(() => false),
   });
   const mockCache = createMockCacheService();
-  const translationService = new TranslationService(client, mockConfig, mockCache);
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    mockCache
+  );
   const glossaryService = new GlossaryService(client);
   const registry = new FormatRegistry();
   registry.register(new JsonFormatParser());
-  const syncService = new SyncService(translationService, glossaryService, registry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    registry
+  );
   return { client, syncService };
 }
 
@@ -92,7 +107,7 @@ describe('sync-service scan_paths: bounded walk prevents DoS on huge source tree
       fs.writeFileSync(
         path.join(srcDir, `File${i}.tsx`),
         `export const k${i} = 'v${i}';\n`,
-        'utf-8',
+        'utf-8'
       );
     }
     const localePath = path.join(tmpDir, 'locales', 'en.json');
@@ -102,7 +117,9 @@ describe('sync-service scan_paths: bounded walk prevents DoS on huge source tree
     nock(DEEPL_FREE_API_URL)
       .persist()
       .post('/v2/translate')
-      .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+      .reply(200, {
+        translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+      });
 
     const config = await loadSyncConfig(configPath, {});
 
diff --git a/tests/integration/sync-stale-lock-fg-coalesce.integration.test.ts b/tests/integration/sync-stale-lock-fg-coalesce.integration.test.ts
index 68f03527..501cebf6 100644
--- a/tests/integration/sync-stale-lock-fg-coalesce.integration.test.ts
+++ b/tests/integration/sync-stale-lock-fg-coalesce.integration.test.ts
@@ -13,7 +13,10 @@ const fgCalls: Array<string | string[]> = [];
 jest.mock('fast-glob', () => {
   const real = jest.requireActual<any>('fast-glob');
   const realFn = real.default ?? real;
-  const wrapped: any = async (patterns: string | string[], opts?: object): Promise<string[]> => {
+  const wrapped: any = async (
+    patterns: string | string[],
+    opts?: object
+  ): Promise<string[]> => {
     fgCalls.push(patterns);
     return realFn(patterns, opts);
   };
@@ -31,7 +34,10 @@ import { FormatRegistry } from '../../src/formats/index';
 import { JsonFormatParser } from '../../src/formats/json';
 import { loadSyncConfig } from '../../src/sync/sync-config';
 import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
-import { createMockConfigService, createMockCacheService } from '../helpers/mock-factories';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
 
 const STALE_COUNT = 50;
 
@@ -53,7 +59,11 @@ function createServices(): { client: DeepLClient; syncService: SyncService } {
     get: jest.fn(() => ({
       auth: {},
       api: { baseUrl: '', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
       cache: { enabled: false },
       output: { format: 'text', color: true },
       proxy: {},
@@ -61,11 +71,19 @@ function createServices(): { client: DeepLClient; syncService: SyncService } {
     getValue: jest.fn(() => false),
   });
   const mockCache = createMockCacheService();
-  const translationService = new TranslationService(client, mockConfig, mockCache);
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    mockCache
+  );
   const glossaryService = new GlossaryService(client);
   const registry = new FormatRegistry();
   registry.register(new JsonFormatParser());
-  const syncService = new SyncService(translationService, glossaryService, registry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    registry
+  );
   return { client, syncService };
 }
 
@@ -96,26 +114,28 @@ describe('sync-service stale-lock fg coalesce', () => {
 
     const localeDir = path.join(tmpDir, 'locales');
     fs.mkdirSync(localeDir, { recursive: true });
-    fs.writeFileSync(
-      path.join(localeDir, 'en.json'),
-      SOURCE_JSON,
-      'utf-8',
-    );
+    fs.writeFileSync(path.join(localeDir, 'en.json'), SOURCE_JSON, 'utf-8');
     fs.writeFileSync(
       path.join(localeDir, 'de.json'),
       JSON.stringify({ greeting: 'Hallo' }, null, 2) + '\n',
-      'utf-8',
+      'utf-8'
     );
 
     // Seed lock file with STALE_COUNT entries for files that no longer exist.
     // Each entry must have the correct SyncLockFile shape:
     //   entries[filePath][keyName] = { source_hash, source_text, translations }
     const lockPath = path.join(tmpDir, '.deepl-sync.lock');
-    const entries: Record<string, Record<string, {
-      source_hash: string;
-      source_text: string;
-      translations: Record<string, { hash: string; status: string }>;
-    }>> = {};
+    const entries: Record<
+      string,
+      Record<
+        string,
+        {
+          source_hash: string;
+          source_text: string;
+          translations: Record<string, { hash: string; status: string }>;
+        }
+      >
+    > = {};
     for (let i = 0; i < STALE_COUNT; i++) {
       const filePath = 'old/path/stale_' + String(i) + '.json';
       entries[filePath] = {
@@ -139,22 +159,32 @@ describe('sync-service stale-lock fg coalesce', () => {
     const now = new Date().toISOString();
     fs.writeFileSync(
       lockPath,
-      JSON.stringify({
-        _comment: 'test',
-        version: 1,
-        generated_at: now,
-        source_locale: 'en',
-        entries,
-        stats: { total_keys: STALE_COUNT + 1, total_translations: STALE_COUNT, last_sync: now },
-        glossary_ids: {},
-      }, null, 2),
-      'utf-8',
+      JSON.stringify(
+        {
+          _comment: 'test',
+          version: 1,
+          generated_at: now,
+          source_locale: 'en',
+          entries,
+          stats: {
+            total_keys: STALE_COUNT + 1,
+            total_translations: STALE_COUNT,
+            last_sync: now,
+          },
+          glossary_ids: {},
+        },
+        null,
+        2
+      ),
+      'utf-8'
     );
 
     nock(DEEPL_FREE_API_URL)
       .persist()
       .post('/v2/translate')
-      .reply(200, { translations: [{ text: 'Hallo', detected_source_language: 'EN' }] });
+      .reply(200, {
+        translations: [{ text: 'Hallo', detected_source_language: 'EN' }],
+      });
 
     const config = await loadSyncConfig(configPath, {});
     await syncService.sync(config, {});
diff --git a/tests/integration/sync-symlink-safety.integration.test.ts b/tests/integration/sync-symlink-safety.integration.test.ts
index b674da55..5239074a 100644
--- a/tests/integration/sync-symlink-safety.integration.test.ts
+++ b/tests/integration/sync-symlink-safety.integration.test.ts
@@ -61,13 +61,17 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
   const originalEnv = { ...process.env };
 
   beforeEach(() => {
-    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-symlink-proj-'));
-    outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-symlink-secret-'));
+    projectDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'deepl-sync-symlink-proj-')
+    );
+    outsideDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'deepl-sync-symlink-secret-')
+    );
     outsideSecret = path.join(outsideDir, 'secret.json');
     fs.writeFileSync(
       outsideSecret,
       JSON.stringify({ exfiltrated: 'TOP_SECRET_VALUE' }, null, 2),
-      'utf-8',
+      'utf-8'
     );
     harness = createSyncHarness({ parsers: ['json'] });
     delete process.env['TMS_API_KEY'];
@@ -76,8 +80,10 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
 
   afterEach(() => {
     harness.cleanup();
-    if (fs.existsSync(projectDir)) fs.rmSync(projectDir, { recursive: true, force: true });
-    if (fs.existsSync(outsideDir)) fs.rmSync(outsideDir, { recursive: true, force: true });
+    if (fs.existsSync(projectDir))
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    if (fs.existsSync(outsideDir))
+      fs.rmSync(outsideDir, { recursive: true, force: true });
     nock.cleanAll();
     process.env = { ...originalEnv };
   });
@@ -95,10 +101,18 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
     //
     // With followSymbolicLinks:false, the symlinked locales/secrets/en.json is
     // silently skipped and only greeting is pushed.
-    if (!trySymlink(path.join(projectDir, 'locales', 'secrets', 'en.json'), outsideSecret)) return;
+    if (
+      !trySymlink(
+        path.join(projectDir, 'locales', 'secrets', 'en.json'),
+        outsideSecret
+      )
+    )
+      return;
     writeJson(projectDir, 'locales/en.json', { greeting: 'Hello' });
     writeJson(projectDir, 'locales/de.json', { greeting: 'Hallo' });
-    writeJson(projectDir, 'locales/secrets/de.json', { exfiltrated: 'SHOULD_NOT_PUSH' });
+    writeJson(projectDir, 'locales/secrets/de.json', {
+      exfiltrated: 'SHOULD_NOT_PUSH',
+    });
     writeSyncConfig(projectDir, {
       targetLocales: ['de'],
       buckets: { json: { include: ['locales/**/en.json'] } },
@@ -111,7 +125,9 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
 
     // Only the real file's key is expected on the wire; the symlinked secret
     // must not be read or transmitted.
-    const scope = expectTmsPush('greeting', 'de', 'Hallo', { auth: { apiKey: 'env-key' } });
+    const scope = expectTmsPush('greeting', 'de', 'Hallo', {
+      auth: { apiKey: 'env-key' },
+    });
 
     const result = await pushTranslations(config, client, harness.registry);
     expect(result.pushed).toBe(1);
@@ -121,7 +137,13 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
   });
 
   it('pull: does not treat a symlink as a source file when scanning for locale targets', async () => {
-    if (!trySymlink(path.join(projectDir, 'locales', 'secrets', 'en.json'), outsideSecret)) return;
+    if (
+      !trySymlink(
+        path.join(projectDir, 'locales', 'secrets', 'en.json'),
+        outsideSecret
+      )
+    )
+      return;
     writeJson(projectDir, 'locales/en.json', { greeting: 'Hello' });
     writeSyncConfig(projectDir, {
       targetLocales: ['de'],
@@ -140,7 +162,7 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
     const pullScope = expectTmsPull(
       'de',
       { greeting: 'Hallo', exfiltrated: 'SHOULD_NEVER_APPEAR' },
-      { auth: { apiKey: 'env-key' } },
+      { auth: { apiKey: 'env-key' } }
     );
 
     const result = await pullTranslations(config, client, harness.registry);
@@ -149,11 +171,19 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
 
     // The target file derived from the symlink (locales/secrets/de.json) must
     // never have been written.
-    expect(fs.existsSync(path.join(projectDir, 'locales', 'secrets', 'de.json'))).toBe(false);
+    expect(
+      fs.existsSync(path.join(projectDir, 'locales', 'secrets', 'de.json'))
+    ).toBe(false);
   });
 
   it('export: does not embed symlinked-file contents in XLIFF output', async () => {
-    if (!trySymlink(path.join(projectDir, 'locales', 'secrets', 'en.json'), outsideSecret)) return;
+    if (
+      !trySymlink(
+        path.join(projectDir, 'locales', 'secrets', 'en.json'),
+        outsideSecret
+      )
+    )
+      return;
     writeJson(projectDir, 'locales/en.json', { greeting: 'Hello' });
     writeSyncConfig(projectDir, {
       targetLocales: ['de'],
@@ -177,9 +207,15 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
     fs.writeFileSync(
       maliciousSource,
       JSON.stringify({ greeting: 'LEAKED %s %d %x' }, null, 2),
-      'utf-8',
+      'utf-8'
     );
-    if (!trySymlink(path.join(projectDir, 'locales', 'secrets', 'en.json'), maliciousSource)) return;
+    if (
+      !trySymlink(
+        path.join(projectDir, 'locales', 'secrets', 'en.json'),
+        maliciousSource
+      )
+    )
+      return;
     writeJson(projectDir, 'locales/en.json', { greeting: 'Hello %s' });
     writeJson(projectDir, 'locales/de.json', { greeting: 'Hallo %s' });
     // Target for the symlinked "source" -- no placeholder mismatches here so
diff --git a/tests/integration/sync-template-patterns-dedup-perf.integration.test.ts b/tests/integration/sync-template-patterns-dedup-perf.integration.test.ts
index 1887d8d7..72877186 100644
--- a/tests/integration/sync-template-patterns-dedup-perf.integration.test.ts
+++ b/tests/integration/sync-template-patterns-dedup-perf.integration.test.ts
@@ -16,7 +16,10 @@ const PATTERNS_PER_FILE = 20;
 const KEY_COUNT = 10_000;
 const THRESHOLD_MS = 2_000;
 
-function buildFixture(): { patterns: TemplatePatternMatch[]; knownKeys: string[] } {
+function buildFixture(): {
+  patterns: TemplatePatternMatch[];
+  knownKeys: string[];
+} {
   const patterns: TemplatePatternMatch[] = [];
   for (let f = 0; f < FILE_COUNT; f++) {
     for (let p = 0; p < PATTERNS_PER_FILE; p++) {
@@ -48,17 +51,20 @@ describe('resolveTemplatePatterns dedup', () => {
       pattern: 'a.${k}.title',
       filePath: 'base.tsx',
       line: 1,
-      surroundingCode: "t(`a.${k}.title`)",
+      surroundingCode: 't(`a.${k}.title`)',
       matchedFunction: 't',
     };
 
-    const uniqueExtras: TemplatePatternMatch[] = Array.from({ length: UNIQUE_PATTERNS - 1 }, (_, i) => ({
-      pattern: `b.\${k${i}}.title`,
-      filePath: `extra${i}.tsx`,
-      line: i + 1,
-      surroundingCode: `t(\`b.\${k${i}}.title\`)`,
-      matchedFunction: 't',
-    }));
+    const uniqueExtras: TemplatePatternMatch[] = Array.from(
+      { length: UNIQUE_PATTERNS - 1 },
+      (_, i) => ({
+        pattern: `b.\${k${i}}.title`,
+        filePath: `extra${i}.tsx`,
+        line: i + 1,
+        surroundingCode: `t(\`b.\${k${i}}.title\`)`,
+        matchedFunction: 't',
+      })
+    );
 
     const singlePatterns = [base, ...uniqueExtras];
     const dupPatterns = [
@@ -85,7 +91,9 @@ describe('resolveTemplatePatterns dedup', () => {
 
       const start = Date.now();
       const seen = new Set<string>();
-      const deduped = patterns.filter((t) => !seen.has(t.pattern) && seen.add(t.pattern));
+      const deduped = patterns.filter(
+        (t) => !seen.has(t.pattern) && seen.add(t.pattern)
+      );
       const dedupMs = Date.now() - start;
 
       const startSlow = Date.now();
@@ -93,9 +101,13 @@ describe('resolveTemplatePatterns dedup', () => {
       const elapsed = Date.now() - startSlow;
 
       expect(deduped.length).toBeLessThan(patterns.length);
-      console.log(`[bench] patterns: ${patterns.length}, unique: ${seen.size}, keys: ${knownKeys.length}`);
+      console.log(
+        `[bench] patterns: ${patterns.length}, unique: ${seen.size}, keys: ${knownKeys.length}`
+      );
       console.log(`[bench] dedup cost: ${dedupMs}ms`);
-      console.log(`[bench] resolveTemplatePatterns (pre-dedup simulation): ${elapsed}ms`);
+      console.log(
+        `[bench] resolveTemplatePatterns (pre-dedup simulation): ${elapsed}ms`
+      );
     });
 
     it('deduped resolveTemplatePatterns completes in under 2s for 2K-file × 40K-pattern fixture', () => {
@@ -107,7 +119,9 @@ describe('resolveTemplatePatterns dedup', () => {
 
       expect(result.size).toBeGreaterThan(0);
       expect(elapsed).toBeLessThan(THRESHOLD_MS);
-      console.log(`[bench] resolveTemplatePatterns (deduped): ${elapsed}ms, matched keys: ${result.size}`);
+      console.log(
+        `[bench] resolveTemplatePatterns (deduped): ${elapsed}ms, matched keys: ${result.size}`
+      );
     });
   }
 });
diff --git a/tests/integration/sync-template-prep.integration.test.ts b/tests/integration/sync-template-prep.integration.test.ts
index 06827164..c4bf7767 100644
--- a/tests/integration/sync-template-prep.integration.test.ts
+++ b/tests/integration/sync-template-prep.integration.test.ts
@@ -13,7 +13,10 @@ import { FormatRegistry } from '../../src/formats/index';
 import { JsonFormatParser } from '../../src/formats/json';
 import { loadSyncConfig } from '../../src/sync/sync-config';
 import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
-import { createMockConfigService, createMockCacheService } from '../helpers/mock-factories';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
 
 function createServices(): { client: DeepLClient; syncService: SyncService } {
   const client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
@@ -21,7 +24,11 @@ function createServices(): { client: DeepLClient; syncService: SyncService } {
     get: jest.fn(() => ({
       auth: {},
       api: { baseUrl: '', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
       cache: { enabled: false },
       output: { format: 'text', color: true },
       proxy: {},
@@ -29,11 +36,19 @@ function createServices(): { client: DeepLClient; syncService: SyncService } {
     getValue: jest.fn(() => false),
   });
   const mockCache = createMockCacheService();
-  const translationService = new TranslationService(client, mockConfig, mockCache);
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    mockCache
+  );
   const glossaryService = new GlossaryService(client);
   const registry = new FormatRegistry();
   registry.register(new JsonFormatParser());
-  const syncService = new SyncService(translationService, glossaryService, registry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    registry
+  );
   return { client, syncService };
 }
 
@@ -67,7 +82,7 @@ const SOURCE_JSON =
       'features.gamma.title': 'Gamma',
     },
     null,
-    2,
+    2
   ) + '\n';
 
 describe('sync-service template-pattern prep: source files read once per sync', () => {
@@ -92,7 +107,7 @@ describe('sync-service template-pattern prep: source files read once per sync',
   });
 
   it('reads each bucket source file at most once when template patterns are configured', async () => {
-      expect.assertions(1);
+    expect.assertions(1);
     const configPath = path.join(tmpDir, '.deepl-sync.yaml');
     fs.writeFileSync(configPath, CONFIG_YAML, 'utf-8');
     const srcPath = path.join(tmpDir, 'src', 'Features.tsx');
diff --git a/tests/integration/sync-tms-push.integration.test.ts b/tests/integration/sync-tms-push.integration.test.ts
index 1c0293ac..28eb0a3a 100644
--- a/tests/integration/sync-tms-push.integration.test.ts
+++ b/tests/integration/sync-tms-push.integration.test.ts
@@ -24,11 +24,22 @@ import { FormatRegistry } from '../../src/formats/index';
 import { PhpArraysFormatParser } from '../../src/formats/php-arrays';
 import type { ResolvedSyncConfig } from '../../src/sync/sync-config';
 
-import { TMS_BASE, TMS_PROJECT, expectTmsPush, expectTmsPull } from '../helpers/tms-nock';
-
-const FIXTURE_DIR = path.resolve(__dirname, '../fixtures/sync/laravel_php-pipe-plural');
-
-function makeConfig(projectRoot: string, overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+import {
+  TMS_BASE,
+  TMS_PROJECT,
+  expectTmsPush,
+  expectTmsPull,
+} from '../helpers/tms-nock';
+
+const FIXTURE_DIR = path.resolve(
+  __dirname,
+  '../fixtures/sync/laravel_php-pipe-plural'
+);
+
+function makeConfig(
+  projectRoot: string,
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -64,9 +75,17 @@ describe('sync push/pull walker skip-partition integration', () => {
   let projectRoot: string;
 
   beforeEach(() => {
-    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-skip-partition-'));
-    fs.copyFileSync(path.join(FIXTURE_DIR, 'en.php'), path.join(projectRoot, 'en.php'));
-    fs.copyFileSync(path.join(FIXTURE_DIR, 'de.php'), path.join(projectRoot, 'de.php'));
+    projectRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'deepl-sync-skip-partition-')
+    );
+    fs.copyFileSync(
+      path.join(FIXTURE_DIR, 'en.php'),
+      path.join(projectRoot, 'en.php')
+    );
+    fs.copyFileSync(
+      path.join(FIXTURE_DIR, 'de.php'),
+      path.join(projectRoot, 'de.php')
+    );
   });
 
   afterEach(() => {
@@ -85,7 +104,11 @@ describe('sync push/pull walker skip-partition integration', () => {
       expectTmsPush('farewell', 'de', 'Tschüss'),
     ];
 
-    const result = await pushTranslations(makeConfig(projectRoot), makeClient(), makeRegistry());
+    const result = await pushTranslations(
+      makeConfig(projectRoot),
+      makeClient(),
+      makeRegistry()
+    );
 
     expect(result.pushed).toBe(2);
     for (const scope of scopes) {
@@ -112,19 +135,30 @@ describe('sync push/pull walker skip-partition integration', () => {
       days: 'WRONG — pipe plural replacement',
     });
 
-    const result = await pullTranslations(makeConfig(projectRoot), makeClient(), makeRegistry());
+    const result = await pullTranslations(
+      makeConfig(projectRoot),
+      makeClient(),
+      makeRegistry()
+    );
 
     expect(result.pulled).toBeGreaterThanOrEqual(2);
     expect(scope.isDone()).toBe(true);
 
-    const writtenDe = fs.readFileSync(path.join(projectRoot, 'de.php'), 'utf-8');
+    const writtenDe = fs.readFileSync(
+      path.join(projectRoot, 'de.php'),
+      'utf-8'
+    );
     // Pipe-plural values in the target file must be preserved verbatim from
     // the pre-pull target (which matched the source fixture). If the partition
     // regressed, the literal string 'WRONG — pipe plural replacement' would
     // appear in one of the two plural slots.
     expect(writtenDe).not.toContain('WRONG');
-    expect(writtenDe).toContain('{0} No apples|{1} One apple|[2,*] Many apples');
-    expect(writtenDe).toContain('[0,0] No days|[1,6] A few days|[7,*] Full week');
+    expect(writtenDe).toContain(
+      '{0} No apples|{1} One apple|[2,*] Many apples'
+    );
+    expect(writtenDe).toContain(
+      '[0,0] No days|[1,6] A few days|[7,*] Full week'
+    );
     expect(writtenDe).toContain("'greeting' => 'Hallo'");
     expect(writtenDe).toContain("'farewell' => 'Tschüss'");
     expect(nock.isDone()).toBe(true);
@@ -140,7 +174,11 @@ describe('sync push/pull walker skip-partition integration', () => {
         expectTmsPush('farewell', 'de', 'Tschüss'),
       ];
 
-      const result = await pushTranslations(makeConfig(projectRoot), makeClient(), makeRegistry());
+      const result = await pushTranslations(
+        makeConfig(projectRoot),
+        makeClient(),
+        makeRegistry()
+      );
 
       expect(result.pushed).toBe(2);
       for (const scope of scopes) {
@@ -158,7 +196,10 @@ describe('sync push/pull walker skip-partition integration', () => {
     expectTmsPush('farewell', 'fr', 'Tschüss');
     // Add a second target locale with the same target-file content so the
     // walker emits skip records for both locales.
-    fs.copyFileSync(path.join(projectRoot, 'de.php'), path.join(projectRoot, 'fr.php'));
+    fs.copyFileSync(
+      path.join(projectRoot, 'de.php'),
+      path.join(projectRoot, 'fr.php')
+    );
 
     const config = makeConfig(projectRoot, { target_locales: ['de', 'fr'] });
     const result = await pushTranslations(config, makeClient(), makeRegistry());
@@ -168,11 +209,6 @@ describe('sync push/pull walker skip-partition integration', () => {
       .filter((s) => s.reason === 'pipe_pluralization')
       .map((s) => `${s.locale}:${s.key}`)
       .sort();
-    expect(keyed).toEqual([
-      'de:apples',
-      'de:days',
-      'fr:apples',
-      'fr:days',
-    ]);
+    expect(keyed).toEqual(['de:apples', 'de:days', 'fr:apples', 'fr:days']);
   });
 });
diff --git a/tests/integration/sync-tms.integration.test.ts b/tests/integration/sync-tms.integration.test.ts
index d20f2332..6d9aa93f 100644
--- a/tests/integration/sync-tms.integration.test.ts
+++ b/tests/integration/sync-tms.integration.test.ts
@@ -61,8 +61,14 @@ describe('sync push/pull (TMS integration)', () => {
   // ---- Case 1: push happy path ----
   it('push: sends PUT per source key with ApiKey auth, returns pushed count', async () => {
     writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
-    writeJson(tmpDir, 'locales/en.json', { greeting: 'Hello', farewell: 'Goodbye' });
-    writeJson(tmpDir, 'locales/de.json', { greeting: 'Hallo', farewell: 'Auf Wiedersehen' });
+    writeJson(tmpDir, 'locales/en.json', {
+      greeting: 'Hello',
+      farewell: 'Goodbye',
+    });
+    writeJson(tmpDir, 'locales/de.json', {
+      greeting: 'Hallo',
+      farewell: 'Auf Wiedersehen',
+    });
 
     process.env['TMS_API_KEY'] = 'env-key';
 
@@ -70,7 +76,9 @@ describe('sync push/pull (TMS integration)', () => {
     const client = createTmsClient(config.tms!);
 
     const scopes = [
-      expectTmsPush('farewell', 'de', 'Auf Wiedersehen', { auth: { apiKey: 'env-key' } }),
+      expectTmsPush('farewell', 'de', 'Auf Wiedersehen', {
+        auth: { apiKey: 'env-key' },
+      }),
       expectTmsPush('greeting', 'de', 'Hallo', { auth: { apiKey: 'env-key' } }),
     ];
 
@@ -85,8 +93,14 @@ describe('sync push/pull (TMS integration)', () => {
   // ---- Case 2: pull happy path ----
   it('pull: fetches translations, writes target file, updates lockfile with review_status=human_reviewed', async () => {
     writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
-    writeJson(tmpDir, 'locales/en.json', { greeting: 'Hello', farewell: 'Goodbye' });
-    writeJson(tmpDir, 'locales/de.json', { greeting: 'OLD', farewell: 'STALE' });
+    writeJson(tmpDir, 'locales/en.json', {
+      greeting: 'Hello',
+      farewell: 'Goodbye',
+    });
+    writeJson(tmpDir, 'locales/de.json', {
+      greeting: 'OLD',
+      farewell: 'STALE',
+    });
 
     process.env['TMS_API_KEY'] = 'env-key';
 
@@ -96,7 +110,7 @@ describe('sync push/pull (TMS integration)', () => {
     const pullScope = expectTmsPull(
       'de',
       { greeting: 'Hallo (approved)', farewell: 'Tschüss (approved)' },
-      { auth: { apiKey: 'env-key' } },
+      { auth: { apiKey: 'env-key' } }
     );
 
     const result = await pullTranslations(config, client, harness.registry);
@@ -105,18 +119,37 @@ describe('sync push/pull (TMS integration)', () => {
     expect(pullScope.isDone()).toBe(true);
 
     const targetContent = JSON.parse(
-      fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8'),
+      fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8')
     ) as Record<string, string>;
     expect(targetContent['greeting']).toBe('Hallo (approved)');
     expect(targetContent['farewell']).toBe('Tschüss (approved)');
 
     const lockContent = JSON.parse(
-      fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8'),
-    ) as { entries: Record<string, Record<string, { translations: Record<string, { review_status: string; translated_at: string; status: string }> }>> };
+      fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8')
+    ) as {
+      entries: Record<
+        string,
+        Record<
+          string,
+          {
+            translations: Record<
+              string,
+              { review_status: string; translated_at: string; status: string }
+            >;
+          }
+        >
+      >;
+    };
     const bucketEntries = lockContent.entries['locales/en.json']!;
-    expect(bucketEntries['greeting']!.translations['de']!.review_status).toBe('human_reviewed');
-    expect(bucketEntries['greeting']!.translations['de']!.status).toBe('translated');
-    expect(typeof bucketEntries['greeting']!.translations['de']!.translated_at).toBe('string');
+    expect(bucketEntries['greeting']!.translations['de']!.review_status).toBe(
+      'human_reviewed'
+    );
+    expect(bucketEntries['greeting']!.translations['de']!.status).toBe(
+      'translated'
+    );
+    expect(
+      typeof bucketEntries['greeting']!.translations['de']!.translated_at
+    ).toBe('string');
   });
 
   // ---- Case 3: TMS_API_KEY env var precedence over config ----
@@ -130,7 +163,9 @@ describe('sync push/pull (TMS integration)', () => {
     const config = await loadSyncConfig(tmpDir);
     const client = createTmsClient(config.tms!);
 
-    const scope = expectTmsPush('k', 'de', 'Hallo', { auth: { apiKey: 'from-env' } });
+    const scope = expectTmsPush('k', 'de', 'Hallo', {
+      auth: { apiKey: 'from-env' },
+    });
 
     await pushTranslations(config, client, harness.registry);
     expect(scope.isDone()).toBe(true);
@@ -147,7 +182,9 @@ describe('sync push/pull (TMS integration)', () => {
     const config = await loadSyncConfig(tmpDir);
     const client = createTmsClient(config.tms!);
 
-    const scope = expectTmsPush('k', 'de', 'Hallo', { auth: { token: 'the-token' } });
+    const scope = expectTmsPush('k', 'de', 'Hallo', {
+      auth: { token: 'the-token' },
+    });
 
     await pushTranslations(config, client, harness.registry);
     expect(scope.isDone()).toBe(true);
@@ -157,12 +194,14 @@ describe('sync push/pull (TMS integration)', () => {
   it('credential resolution: emits a stderr warning when api_key is sourced from .deepl-sync.yaml', async () => {
     writeSyncConfig(tmpDir, { tms: tmsConfig({ api_key: 'in-config' }) });
 
-    const warn = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    const warn = jest
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
     try {
       const config = await loadSyncConfig(tmpDir);
       createTmsClient(config.tms!);
       expect(warn).toHaveBeenCalledWith(
-        expect.stringMatching(/TMS API key found in config file.*TMS_API_KEY/),
+        expect.stringMatching(/TMS API key found in config file.*TMS_API_KEY/)
       );
     } finally {
       warn.mockRestore();
@@ -180,7 +219,9 @@ describe('sync push/pull (TMS integration)', () => {
       .put(`/api/projects/${TMS_PROJECT}/keys/greeting`)
       .reply(200, {});
 
-    await expect(client.pushKey('greeting', 'de', 'Hallo')).resolves.toBeUndefined();
+    await expect(
+      client.pushKey('greeting', 'de', 'Hallo')
+    ).resolves.toBeUndefined();
     expect(scope.isDone()).toBe(true);
   });
 
@@ -211,11 +252,15 @@ describe('sync push/pull (TMS integration)', () => {
       .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
       .reply(401, { error: 'Unauthorized' });
 
-    await expect(pushTranslations(config, client, harness.registry)).rejects.toThrow(ConfigError);
+    await expect(
+      pushTranslations(config, client, harness.registry)
+    ).rejects.toThrow(ConfigError);
     // Arm the nock scope again (the previous call consumed it) for the second assertion
     nock(TMS_BASE)
       .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
       .reply(401, { error: 'Unauthorized' });
-    await expect(pushTranslations(config, client, harness.registry)).rejects.toThrow(/TMS authentication failed \(401/);
+    await expect(
+      pushTranslations(config, client, harness.registry)
+    ).rejects.toThrow(/TMS authentication failed \(401/);
   });
 });
diff --git a/tests/integration/sync-toml.integration.test.ts b/tests/integration/sync-toml.integration.test.ts
index 10438dd8..3ca9b9f9 100644
--- a/tests/integration/sync-toml.integration.test.ts
+++ b/tests/integration/sync-toml.integration.test.ts
@@ -42,10 +42,13 @@ describe('sync TOML fixture round-trip', () => {
   });
 
   it('translates source.toml and writes de.toml matching the expected fixture', async () => {
-    const source = fs.readFileSync(path.join(FIXTURE_DIR, 'source.toml'), 'utf-8');
+    const source = fs.readFileSync(
+      path.join(FIXTURE_DIR, 'source.toml'),
+      'utf-8'
+    );
     const expected = fs.readFileSync(
       path.join(FIXTURE_DIR, 'expected-after-sync', 'de.toml'),
-      'utf-8',
+      'utf-8'
     );
 
     writeSyncConfig(tmpDir, {
@@ -62,10 +65,26 @@ describe('sync TOML fixture round-trip', () => {
         // Order matches alphabetical sort of keys from TomlFormatParser.extract():
         // farewell, greeting, nav.home, nav.settings
         translations: [
-          { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-          { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-          { text: 'Startseite', detected_source_language: 'EN', billed_characters: 10 },
-          { text: 'Einstellungen', detected_source_language: 'EN', billed_characters: 13 },
+          {
+            text: 'Auf Wiedersehen',
+            detected_source_language: 'EN',
+            billed_characters: 15,
+          },
+          {
+            text: 'Hallo',
+            detected_source_language: 'EN',
+            billed_characters: 5,
+          },
+          {
+            text: 'Startseite',
+            detected_source_language: 'EN',
+            billed_characters: 10,
+          },
+          {
+            text: 'Einstellungen',
+            detected_source_language: 'EN',
+            billed_characters: 13,
+          },
         ],
       });
 
diff --git a/tests/integration/sync-watch-reliability.integration.test.ts b/tests/integration/sync-watch-reliability.integration.test.ts
index 8c06e020..6f6bbed6 100644
--- a/tests/integration/sync-watch-reliability.integration.test.ts
+++ b/tests/integration/sync-watch-reliability.integration.test.ts
@@ -19,7 +19,9 @@ interface StubWatcher extends WatchEventSource {
 }
 
 function createStubWatcher(): StubWatcher {
-  const listeners: Partial<Record<'change' | 'add', Array<(p?: string) => void>>> = {};
+  const listeners: Partial<
+    Record<'change' | 'add', Array<(p?: string) => void>>
+  > = {};
   return {
     on(event, listener) {
       (listeners[event] ??= []).push(listener);
@@ -32,7 +34,11 @@ function createStubWatcher(): StubWatcher {
   };
 }
 
-function deferred<T = void>(): { promise: Promise<T>; resolve: (v: T) => void; reject: (e: unknown) => void } {
+function deferred<T = void>(): {
+  promise: Promise<T>;
+  resolve: (v: T) => void;
+  reject: (e: unknown) => void;
+} {
   let resolve!: (v: T) => void;
   let reject!: (e: unknown) => void;
   const promise = new Promise<T>((res, rej) => {
@@ -52,7 +58,9 @@ describe('watch mode reliability', () => {
   afterEach(() => {
     try {
       fs.rmSync(tmpDir, { recursive: true, force: true });
-    } catch { /* ignore */ }
+    } catch {
+      /* ignore */
+    }
   });
 
   describe('event coalescing (bpah)', () => {
@@ -188,7 +196,7 @@ describe('watch mode reliability', () => {
         observedSignal = signal;
         signalVisible.resolve();
         // long-running sync
-        await new Promise(resolve => setTimeout(resolve, 20));
+        await new Promise((resolve) => setTimeout(resolve, 20));
       });
 
       const watcher = createStubWatcher();
@@ -226,7 +234,7 @@ describe('watch mode reliability', () => {
         fs.writeFileSync(
           path.join(sourceDir, 'en.json'),
           JSON.stringify({ hello: 'Hello' }),
-          'utf-8',
+          'utf-8'
         );
 
         const cancellationSignal = { cancelled: false };
@@ -234,12 +242,23 @@ describe('watch mode reliability', () => {
 
         const matcher = (lang: string) =>
           nock(DEEPL_FREE_API_URL)
-            .post('/v2/translate', (body: Record<string, unknown>) => body['target_lang'] === lang)
+            .post(
+              '/v2/translate',
+              (body: Record<string, unknown>) => body['target_lang'] === lang
+            )
             .reply(200, () => {
               callCounts[lang] = (callCounts[lang] ?? 0) + 1;
               // once the first locale completes, signal cancellation
               cancellationSignal.cancelled = true;
-              return { translations: [{ text: `${lang}-hello`, detected_source_language: 'EN', billed_characters: 5 }] };
+              return {
+                translations: [
+                  {
+                    text: `${lang}-hello`,
+                    detected_source_language: 'EN',
+                    billed_characters: 5,
+                  },
+                ],
+              };
             });
 
         matcher('DE');
@@ -263,7 +282,9 @@ describe('watch mode reliability', () => {
   describe('stale .bak sweep on startup (79zz)', () => {
     let errSpy: jest.SpyInstance;
     beforeEach(() => {
-      errSpy = jest.spyOn(console, 'error').mockImplementation(() => { /* silence Logger.warn */ });
+      errSpy = jest.spyOn(console, 'error').mockImplementation(() => {
+        /* silence Logger.warn */
+      });
     });
     afterEach(() => {
       errSpy.mockRestore();
diff --git a/tests/integration/sync-watch.integration.test.ts b/tests/integration/sync-watch.integration.test.ts
index 83251019..3255bc26 100644
--- a/tests/integration/sync-watch.integration.test.ts
+++ b/tests/integration/sync-watch.integration.test.ts
@@ -1,11 +1,16 @@
-import { attachDebouncedWatchLoop, type WatchEventSource } from '../../src/cli/commands/sync-command';
+import {
+  attachDebouncedWatchLoop,
+  type WatchEventSource,
+} from '../../src/cli/commands/sync-command';
 
 interface StubWatcher extends WatchEventSource {
   emit: (event: 'change' | 'add', file?: string) => void;
 }
 
 function createStubWatcher(): StubWatcher {
-  const listeners: Partial<Record<'change' | 'add', Array<(path?: string) => void>>> = {};
+  const listeners: Partial<
+    Record<'change' | 'add', Array<(path?: string) => void>>
+  > = {};
   return {
     on(event, listener) {
       (listeners[event] ??= []).push(listener);
@@ -76,7 +81,11 @@ describe('attachDebouncedWatchLoop', () => {
     const watcher = createStubWatcher();
     const onChange = jest.fn();
 
-    const handle = attachDebouncedWatchLoop({ watcher, onChange, debounceMs: 200 });
+    const handle = attachDebouncedWatchLoop({
+      watcher,
+      onChange,
+      debounceMs: 200,
+    });
 
     watcher.emit('change');
     jest.advanceTimersByTime(150);
diff --git a/tests/integration/sync-xcstrings.integration.test.ts b/tests/integration/sync-xcstrings.integration.test.ts
index 5173562c..57e86c31 100644
--- a/tests/integration/sync-xcstrings.integration.test.ts
+++ b/tests/integration/sync-xcstrings.integration.test.ts
@@ -26,7 +26,10 @@ import { XcstringsFormatParser } from '../../src/formats/xcstrings';
 import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
 import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
 
-const FIXTURE_DIR = path.resolve(__dirname, '../fixtures/sync/formats/xcstrings');
+const FIXTURE_DIR = path.resolve(
+  __dirname,
+  '../fixtures/sync/formats/xcstrings'
+);
 
 describe('sync xcstrings fixture round-trip', () => {
   let tmpDir: string;
@@ -46,10 +49,13 @@ describe('sync xcstrings fixture round-trip', () => {
   });
 
   it('translates source.xcstrings and writes the de localization in the same file matching the expected fixture', async () => {
-    const source = fs.readFileSync(path.join(FIXTURE_DIR, 'source.xcstrings'), 'utf-8');
+    const source = fs.readFileSync(
+      path.join(FIXTURE_DIR, 'source.xcstrings'),
+      'utf-8'
+    );
     const expected = fs.readFileSync(
       path.join(FIXTURE_DIR, 'expected-after-sync', 'de.xcstrings'),
-      'utf-8',
+      'utf-8'
     );
 
     writeSyncConfig(tmpDir, {
@@ -65,9 +71,21 @@ describe('sync xcstrings fixture round-trip', () => {
         // Order matches alphabetical sort from XcstringsFormatParser.extract():
         // farewell, greeting, welcome
         translations: [
-          { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-          { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-          { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+          {
+            text: 'Auf Wiedersehen',
+            detected_source_language: 'EN',
+            billed_characters: 15,
+          },
+          {
+            text: 'Hallo',
+            detected_source_language: 'EN',
+            billed_characters: 5,
+          },
+          {
+            text: 'Willkommen',
+            detected_source_language: 'EN',
+            billed_characters: 10,
+          },
         ],
       });
 
@@ -87,7 +105,15 @@ describe('sync xcstrings fixture round-trip', () => {
     const parser = new XcstringsFormatParser();
     const enEntries = parser.extract(written, 'en');
     const deEntries = parser.extract(written, 'de');
-    expect(enEntries.map((e) => e.value).sort()).toEqual(['Goodbye', 'Hello', 'Welcome']);
-    expect(deEntries.map((e) => e.value).sort()).toEqual(['Auf Wiedersehen', 'Hallo', 'Willkommen']);
+    expect(enEntries.map((e) => e.value).sort()).toEqual([
+      'Goodbye',
+      'Hello',
+      'Welcome',
+    ]);
+    expect(deEntries.map((e) => e.value).sort()).toEqual([
+      'Auf Wiedersehen',
+      'Hallo',
+      'Willkommen',
+    ]);
   });
 });
diff --git a/tests/integration/sync.integration.test.ts b/tests/integration/sync.integration.test.ts
index 5993c027..ef3123c0 100644
--- a/tests/integration/sync.integration.test.ts
+++ b/tests/integration/sync.integration.test.ts
@@ -24,7 +24,10 @@ import { computeSourceHash } from '../../src/sync/sync-lock';
 import { LOCK_FILE_NAME } from '../../src/sync/types';
 import { ConfigError, ValidationError } from '../../src/utils/errors';
 import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
-import { createMockConfigService, createMockCacheService } from '../helpers/mock-factories';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
 
 function parseNockBody(body: unknown): Record<string, string | string[]> {
   if (typeof body === 'string') {
@@ -36,16 +39,22 @@ function parseNockBody(body: unknown): Record<string, string | string[]> {
 function getTexts(body: unknown): string[] {
   const parsed = parseNockBody(body);
   const text = parsed['text'];
-  return Array.isArray(text) ? text : (text ? [text] : []);
+  return Array.isArray(text) ? text : text ? [text] : [];
 }
 
-function createServices(opts: { withYaml?: boolean; withAndroid?: boolean } = {}) {
+function createServices(
+  opts: { withYaml?: boolean; withAndroid?: boolean } = {}
+) {
   const client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
   const mockConfig = createMockConfigService({
     get: jest.fn(() => ({
       auth: {},
       api: { baseUrl: '', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
       cache: { enabled: false },
       output: { format: 'text', color: true },
       proxy: {},
@@ -53,7 +62,11 @@ function createServices(opts: { withYaml?: boolean; withAndroid?: boolean } = {}
     getValue: jest.fn(() => false),
   });
   const mockCache = createMockCacheService();
-  const translationService = new TranslationService(client, mockConfig, mockCache);
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    mockCache
+  );
   const glossaryService = new GlossaryService(client);
   const registry = new FormatRegistry();
   registry.register(new JsonFormatParser());
@@ -63,7 +76,11 @@ function createServices(opts: { withYaml?: boolean; withAndroid?: boolean } = {}
   if (opts.withAndroid) {
     registry.register(new AndroidXmlFormatParser());
   }
-  const syncService = new SyncService(translationService, glossaryService, registry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    registry
+  );
   return { client, syncService };
 }
 
@@ -87,11 +104,12 @@ buckets:
       - "locales/en.json"
 `;
 
-const SOURCE_JSON = JSON.stringify(
-  { greeting: 'Hello', farewell: 'Goodbye', welcome: 'Welcome' },
-  null,
-  2,
-) + '\n';
+const SOURCE_JSON =
+  JSON.stringify(
+    { greeting: 'Hello', farewell: 'Goodbye', welcome: 'Welcome' },
+    null,
+    2
+  ) + '\n';
 
 describe('Sync Integration', () => {
   let tmpDir: string;
@@ -122,9 +140,21 @@ describe('Sync Integration', () => {
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -152,9 +182,21 @@ describe('Sync Integration', () => {
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -186,9 +228,21 @@ describe('Sync Integration', () => {
         })
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -218,9 +272,21 @@ buckets:
         })
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -230,9 +296,21 @@ buckets:
         })
         .reply(200, {
           translations: [
-            { text: 'Au revoir', detected_source_language: 'EN', billed_characters: 10 },
-            { text: 'Bonjour', detected_source_language: 'EN', billed_characters: 7 },
-            { text: 'Bienvenue', detected_source_language: 'EN', billed_characters: 9 },
+            {
+              text: 'Au revoir',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
+            {
+              text: 'Bonjour',
+              detected_source_language: 'EN',
+              billed_characters: 7,
+            },
+            {
+              text: 'Bienvenue',
+              detected_source_language: 'EN',
+              billed_characters: 9,
+            },
           ],
         });
 
@@ -254,9 +332,21 @@ buckets:
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -269,21 +359,29 @@ buckets:
       writeSourceFile(tmpDir, 'locales/en.json', SOURCE_JSON);
       await doFirstSync();
 
-      const updated = JSON.stringify(
-        { greeting: 'Hi there', farewell: 'Goodbye', welcome: 'Welcome' },
-        null,
-        2,
-      ) + '\n';
+      const updated =
+        JSON.stringify(
+          { greeting: 'Hi there', farewell: 'Goodbye', welcome: 'Welcome' },
+          null,
+          2
+        ) + '\n';
       writeSourceFile(tmpDir, 'locales/en.json', updated);
 
       const scope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const text = body['text'];
-          return text === 'Hi there' || (Array.isArray(text) && text.length === 1 && text[0] === 'Hi there');
+          return (
+            text === 'Hi there' ||
+            (Array.isArray(text) && text.length === 1 && text[0] === 'Hi there')
+          );
         })
         .reply(200, {
           translations: [
-            { text: 'Hallo zusammen', detected_source_language: 'EN', billed_characters: 8 },
+            {
+              text: 'Hallo zusammen',
+              detected_source_language: 'EN',
+              billed_characters: 8,
+            },
           ],
         });
 
@@ -300,21 +398,36 @@ buckets:
       writeSourceFile(tmpDir, 'locales/en.json', SOURCE_JSON);
       await doFirstSync();
 
-      const updated = JSON.stringify(
-        { greeting: 'Hello', farewell: 'Goodbye', welcome: 'Welcome', thanks: 'Thank you' },
-        null,
-        2,
-      ) + '\n';
+      const updated =
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            farewell: 'Goodbye',
+            welcome: 'Welcome',
+            thanks: 'Thank you',
+          },
+          null,
+          2
+        ) + '\n';
       writeSourceFile(tmpDir, 'locales/en.json', updated);
 
       const scope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const text = body['text'];
-          return text === 'Thank you' || (Array.isArray(text) && text.length === 1 && text[0] === 'Thank you');
+          return (
+            text === 'Thank you' ||
+            (Array.isArray(text) &&
+              text.length === 1 &&
+              text[0] === 'Thank you')
+          );
         })
         .reply(200, {
           translations: [
-            { text: 'Danke', detected_source_language: 'EN', billed_characters: 9 },
+            {
+              text: 'Danke',
+              detected_source_language: 'EN',
+              billed_characters: 9,
+            },
           ],
         });
 
@@ -331,11 +444,9 @@ buckets:
       writeSourceFile(tmpDir, 'locales/en.json', SOURCE_JSON);
       await doFirstSync();
 
-      const reduced = JSON.stringify(
-        { greeting: 'Hello', farewell: 'Goodbye' },
-        null,
-        2,
-      ) + '\n';
+      const reduced =
+        JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) +
+        '\n';
       writeSourceFile(tmpDir, 'locales/en.json', reduced);
 
       const config = await loadSyncConfig(tmpDir);
@@ -370,9 +481,21 @@ buckets:
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -396,9 +519,21 @@ buckets:
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -406,7 +541,9 @@ buckets:
       await syncService.sync(configInitial);
 
       // Remove one key from the source and rerun with --frozen.
-      const reducedSource = JSON.stringify({ greeting: 'Hello', welcome: 'Welcome' }, null, 2) + '\n';
+      const reducedSource =
+        JSON.stringify({ greeting: 'Hello', welcome: 'Welcome' }, null, 2) +
+        '\n';
       writeSourceFile(tmpDir, 'locales/en.json', reducedSource);
 
       const configAfter = await loadSyncConfig(tmpDir);
@@ -428,9 +565,21 @@ buckets:
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -479,7 +628,9 @@ buckets:
       const config = await loadSyncConfig(tmpDir);
       await syncService.sync(config, { dryRun: true });
 
-      expect(fs.existsSync(path.join(tmpDir, 'locales', 'de.json'))).toBe(false);
+      expect(fs.existsSync(path.join(tmpDir, 'locales', 'de.json'))).toBe(
+        false
+      );
       expect(fs.existsSync(path.join(tmpDir, LOCK_FILE_NAME))).toBe(false);
     });
 
@@ -507,9 +658,21 @@ buckets:
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -523,9 +686,21 @@ buckets:
         })
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen!', detected_source_language: 'EN', billed_characters: 16 },
-            { text: 'Hallo!', detected_source_language: 'EN', billed_characters: 6 },
-            { text: 'Willkommen!', detected_source_language: 'EN', billed_characters: 11 },
+            {
+              text: 'Auf Wiedersehen!',
+              detected_source_language: 'EN',
+              billed_characters: 16,
+            },
+            {
+              text: 'Hallo!',
+              detected_source_language: 'EN',
+              billed_characters: 6,
+            },
+            {
+              text: 'Willkommen!',
+              detected_source_language: 'EN',
+              billed_characters: 11,
+            },
           ],
         });
 
@@ -547,7 +722,9 @@ buckets:
         .reply(403, { message: 'Invalid API key' });
 
       const config = await loadSyncConfig(tmpDir);
-      await expect(syncService.sync(config)).rejects.toThrow(/Authentication failed/);
+      await expect(syncService.sync(config)).rejects.toThrow(
+        /Authentication failed/
+      );
     });
 
     it('should handle empty source file', async () => {
@@ -583,7 +760,9 @@ buckets:
     });
 
     it('respects a user-configured bak_sweep_max_age_seconds override', async () => {
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -593,7 +772,8 @@ buckets:
       - "locales/en.json"
 sync:
   bak_sweep_max_age_seconds: 60
-`);
+`
+      );
       writeSourceFile(tmpDir, 'locales/en.json', '{}\n');
 
       const staleBak = path.join(tmpDir, 'locales', 'de.json.deepl.bak');
@@ -638,7 +818,9 @@ sync:
 
       expect(fs.existsSync(userBak)).toBe(true);
       expect(fs.readFileSync(userBak, 'utf-8')).toBe('user data');
-      expect(fs.existsSync(path.join(tmpDir, 'locales', 'my-important-notes'))).toBe(false);
+      expect(
+        fs.existsSync(path.join(tmpDir, 'locales', 'my-important-notes'))
+      ).toBe(false);
     });
 
     it('registers a SIGINT/SIGTERM cleanup handler during a non-watch run that unlinks tracked .bak paths', async () => {
@@ -666,7 +848,18 @@ sync:
         .reply(() => {
           observedSigint = process.listenerCount('SIGINT') - sigintBefore;
           observedSigterm = process.listenerCount('SIGTERM') - sigtermBefore;
-          return [200, { translations: [{ text: 'übersetzt', detected_source_language: 'EN', billed_characters: 1 }] }];
+          return [
+            200,
+            {
+              translations: [
+                {
+                  text: 'übersetzt',
+                  detected_source_language: 'EN',
+                  billed_characters: 1,
+                },
+              ],
+            },
+          ];
         });
 
       const config = await loadSyncConfig(tmpDir);
@@ -685,7 +878,9 @@ sync:
     let multiBucketService: SyncService;
 
     beforeEach(() => {
-      multiBucketDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-multi-'));
+      multiBucketDir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-sync-multi-')
+      );
       const services = createServices({ withYaml: true });
       multiBucketClient = services.client;
       multiBucketService = services.syncService;
@@ -713,11 +908,16 @@ buckets:
 `;
       writeYamlConfig(multiBucketDir, multiBucketConfig);
 
-      const jsonContent = JSON.stringify({ title: 'Hello', subtitle: 'World' }, null, 2) + '\n';
+      const jsonContent =
+        JSON.stringify({ title: 'Hello', subtitle: 'World' }, null, 2) + '\n';
       writeSourceFile(multiBucketDir, 'locales/en/messages.json', jsonContent);
 
       const yamlContent = 'nav:\n  home: Home\n  about: About\n';
-      writeSourceFile(multiBucketDir, 'locales/en/navigation.yaml', yamlContent);
+      writeSourceFile(
+        multiBucketDir,
+        'locales/en/navigation.yaml',
+        yamlContent
+      );
 
       const jsonScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
@@ -726,8 +926,16 @@ buckets:
         })
         .reply(200, {
           translations: [
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Welt', detected_source_language: 'EN', billed_characters: 5 },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Welt',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
           ],
         });
 
@@ -738,8 +946,16 @@ buckets:
         })
         .reply(200, {
           translations: [
-            { text: 'Uber', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Startseite', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Uber',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Startseite',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -752,10 +968,20 @@ buckets:
       expect(jsonScope.isDone()).toBe(true);
       expect(yamlScope.isDone()).toBe(true);
 
-      const jsonTargetFile = path.join(multiBucketDir, 'locales', 'de', 'messages.json');
+      const jsonTargetFile = path.join(
+        multiBucketDir,
+        'locales',
+        'de',
+        'messages.json'
+      );
       expect(fs.existsSync(jsonTargetFile)).toBe(true);
 
-      const yamlTargetFile = path.join(multiBucketDir, 'locales', 'de', 'navigation.yaml');
+      const yamlTargetFile = path.join(
+        multiBucketDir,
+        'locales',
+        'de',
+        'navigation.yaml'
+      );
       expect(fs.existsSync(yamlTargetFile)).toBe(true);
 
       const lockPath = path.join(multiBucketDir, LOCK_FILE_NAME);
@@ -781,27 +1007,30 @@ buckets:
 
       // Keys sorted alphabetically by JsonFormatParser: greeting (idx 0), items (idx 1)
       // The ICU string at idx 1 becomes __ICU_PLACEHOLDER_1__ in the main batch.
-      const sourceContent = JSON.stringify(
-        {
-          items: '{count, plural, one {# item} other {# items}}',
-          greeting: 'Hello',
-        },
-        null,
-        2,
-      ) + '\n';
+      const sourceContent =
+        JSON.stringify(
+          {
+            items: '{count, plural, one {# item} other {# items}}',
+            greeting: 'Hello',
+          },
+          null,
+          2
+        ) + '\n';
       writeSourceFile(tmpDir, 'locales/en.json', sourceContent);
 
       // Main batch: "Hello" at idx 0 and the ICU placeholder at idx 1
       const mainScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const texts = getTexts(body);
-          return texts.some(t => t === 'Hello') &&
-                 texts.some(t => t.startsWith('__ICU_PLACEHOLDER_'));
+          return (
+            texts.some((t) => t === 'Hello') &&
+            texts.some((t) => t.startsWith('__ICU_PLACEHOLDER_'))
+          );
         })
         .reply(200, (_uri: string, rawBody: unknown) => {
           const texts = getTexts(rawBody);
           return {
-            translations: texts.map(t => ({
+            translations: texts.map((t) => ({
               text: t.startsWith('__ICU_PLACEHOLDER_') ? t : 'Hallo',
               detected_source_language: 'EN',
               billed_characters: 5,
@@ -814,12 +1043,15 @@ buckets:
       const icuScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const texts = getTexts(body);
-          return texts.length === 2 && !texts.some(t => t.startsWith('__ICU_PLACEHOLDER_'));
+          return (
+            texts.length === 2 &&
+            !texts.some((t) => t.startsWith('__ICU_PLACEHOLDER_'))
+          );
         })
         .reply(200, (_uri: string, rawBody: unknown) => {
           const texts = getTexts(rawBody);
           return {
-            translations: texts.map(t => ({
+            translations: texts.map((t) => ({
               text: t.replace(/item(s?)/, 'Artikel'),
               detected_source_language: 'EN',
               billed_characters: 7,
@@ -884,13 +1116,15 @@ buckets:
       const mainScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const texts = getTexts(body);
-          return texts.some(t => t === 'Hello') &&
-                 texts.some(t => t.startsWith('__ICU_PLACEHOLDER_'));
+          return (
+            texts.some((t) => t === 'Hello') &&
+            texts.some((t) => t.startsWith('__ICU_PLACEHOLDER_'))
+          );
         })
         .reply(200, (_uri: string, rawBody: unknown) => {
           const texts = getTexts(rawBody);
           return {
-            translations: texts.map(t => ({
+            translations: texts.map((t) => ({
               text: t.startsWith('__ICU_PLACEHOLDER_') ? t : 'Hallo',
               detected_source_language: 'EN',
               billed_characters: 5,
@@ -903,18 +1137,24 @@ buckets:
       const icuScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const texts = getTexts(body);
-          return texts.length >= 1 && !texts.some(t => t.startsWith('__ICU_PLACEHOLDER_'));
+          return (
+            texts.length >= 1 &&
+            !texts.some((t) => t.startsWith('__ICU_PLACEHOLDER_'))
+          );
         })
         .reply(200, (_uri: string, rawBody: unknown) => {
           const texts = getTexts(rawBody);
           return {
-            translations: texts.map(t => ({
-              text: t.replace(/widget(s?)/, (_m, s: string) => s ? 'Widgets' : 'Widget'),
+            translations: texts.map((t) => ({
+              text: t.replace(/widget(s?)/, (_m, s: string) =>
+                s ? 'Widgets' : 'Widget'
+              ),
               detected_source_language: 'EN',
               billed_characters: 7,
             })),
           };
-        }).persist();
+        })
+        .persist();
 
       const config = await loadSyncConfig(tmpDir);
       const result = await localSyncService.sync(config);
@@ -936,8 +1176,12 @@ buckets:
       // BEFORE ICU-detect the quantity values go through ICU reassemble and contain
       // "Widget" / "Widgets". If the loop order is swapped, the "one" quantity bypasses
       // ICU detection and the mock's fallback returns "Hallo" — which we reject here.
-      const oneMatch = translatedXml.match(/<item\s+quantity="one"[^>]*>([\s\S]*?)<\/item>/);
-      const otherMatch = translatedXml.match(/<item\s+quantity="other"[^>]*>([\s\S]*?)<\/item>/);
+      const oneMatch = translatedXml.match(
+        /<item\s+quantity="one"[^>]*>([\s\S]*?)<\/item>/
+      );
+      const otherMatch = translatedXml.match(
+        /<item\s+quantity="other"[^>]*>([\s\S]*?)<\/item>/
+      );
       expect(oneMatch).not.toBeNull();
       expect(otherMatch).not.toBeNull();
       expect(oneMatch![1]).toContain('Widget');
@@ -970,17 +1214,18 @@ translation:
 `;
       writeYamlConfig(tmpDir, contextConfig);
 
-      const sourceJson = JSON.stringify(
-        {
-          'hero.title': 'Welcome',
-          'hero.subtitle': 'Start here',
-          'btn.save': 'Save',
-          'table.name': 'Name',
-          'misc': 'Other',
-        },
-        null,
-        2,
-      ) + '\n';
+      const sourceJson =
+        JSON.stringify(
+          {
+            'hero.title': 'Welcome',
+            'hero.subtitle': 'Start here',
+            'btn.save': 'Save',
+            'table.name': 'Name',
+            misc: 'Other',
+          },
+          null,
+          2
+        ) + '\n';
       writeSourceFile(tmpDir, 'locales/en.json', sourceJson);
 
       const tsxContent = `import { t } from 'i18n';
@@ -997,7 +1242,11 @@ export function Page() {
 `;
       writeSourceFile(tmpDir, 'src/components/Page.tsx', tsxContent);
 
-      const translateCalls: Array<{ texts: string[]; context?: string; instructions?: string[] }> = [];
+      const translateCalls: Array<{
+        texts: string[];
+        context?: string;
+        instructions?: string[];
+      }> = [];
 
       nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
@@ -1010,10 +1259,14 @@ export function Page() {
           translateCalls.push({
             texts,
             context: Array.isArray(context) ? context[0] : context,
-            instructions: instructions ? (Array.isArray(instructions) ? instructions : [instructions]) : undefined,
+            instructions: instructions
+              ? Array.isArray(instructions)
+                ? instructions
+                : [instructions]
+              : undefined,
           });
           return {
-            translations: texts.map(t => ({
+            translations: texts.map((t) => ({
               text: t + '_DE',
               detected_source_language: 'EN',
               billed_characters: t.length,
@@ -1030,7 +1283,9 @@ export function Page() {
       expect(result.strategy).toBeDefined();
       expect(result.strategy!.context).toBeGreaterThan(0);
 
-      const contextCalls = translateCalls.filter(c => c.context && c.context.length > 0);
+      const contextCalls = translateCalls.filter(
+        (c) => c.context && c.context.length > 0
+      );
       expect(contextCalls.length).toBeGreaterThan(0);
 
       const targetFile = path.join(tmpDir, 'locales', 'de.json');
@@ -1057,16 +1312,17 @@ context:
 `;
       writeYamlConfig(tmpDir, sectionConfig);
 
-      const sourceJson = JSON.stringify(
-        {
-          'nav.home': 'Home',
-          'nav.about': 'About',
-          'nav.contact': 'Contact',
-          'footer.copyright': 'Copyright',
-        },
-        null,
-        2,
-      ) + '\n';
+      const sourceJson =
+        JSON.stringify(
+          {
+            'nav.home': 'Home',
+            'nav.about': 'About',
+            'nav.contact': 'Contact',
+            'footer.copyright': 'Copyright',
+          },
+          null,
+          2
+        ) + '\n';
       writeSourceFile(tmpDir, 'locales/en.json', sourceJson);
 
       const tsxContent = `import { t } from 'i18n';
@@ -1099,7 +1355,7 @@ export function Layout() {
             context: Array.isArray(context) ? context[0] : context,
           });
           return {
-            translations: texts.map(t => ({
+            translations: texts.map((t) => ({
               text: t + '_DE',
               detected_source_language: 'EN',
               billed_characters: t.length,
@@ -1115,14 +1371,16 @@ export function Layout() {
 
       // Section batching: nav.* keys share section "nav" and should be batched together
       const navBatch = translateCalls.find(
-        c => c.context && c.context.includes('nav') && c.texts.length >= 3,
+        (c) => c.context && c.context.includes('nav') && c.texts.length >= 3
       );
       expect(navBatch).toBeDefined();
-      expect(navBatch!.texts).toEqual(expect.arrayContaining(['Home', 'About', 'Contact']));
+      expect(navBatch!.texts).toEqual(
+        expect.arrayContaining(['Home', 'About', 'Contact'])
+      );
 
       // Footer is a separate section batch
-      const footerBatch = translateCalls.find(
-        c => c.context?.includes('footer'),
+      const footerBatch = translateCalls.find((c) =>
+        c.context?.includes('footer')
       );
       expect(footerBatch).toBeDefined();
       expect(footerBatch!.texts).toContain('Copyright');
@@ -1137,7 +1395,9 @@ export function Layout() {
 
   describe('new locale addition', () => {
     it('should translate all keys for a newly added locale', async () => {
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1145,7 +1405,8 @@ buckets:
   json:
     include:
       - "locales/en.json"
-`);
+`
+      );
       writeSourceFile(tmpDir, 'locales/en.json', SOURCE_JSON);
 
       nock(DEEPL_FREE_API_URL)
@@ -1154,9 +1415,21 @@ buckets:
         })
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -1166,7 +1439,9 @@ buckets:
       expect(fs.existsSync(path.join(tmpDir, 'locales', 'de.json'))).toBe(true);
 
       // Second sync: add fr
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1175,7 +1450,8 @@ buckets:
   json:
     include:
       - "locales/en.json"
-`);
+`
+      );
 
       // Track which target_lang values the API is called with
       const calledLocales: string[] = [];
@@ -1185,12 +1461,26 @@ buckets:
         .reply(200, (_uri: string, rawBody: unknown) => {
           const parsed = parseNockBody(rawBody);
           const targetLang = parsed['target_lang'];
-          calledLocales.push(Array.isArray(targetLang) ? targetLang[0]! : targetLang as string);
+          calledLocales.push(
+            Array.isArray(targetLang) ? targetLang[0]! : (targetLang as string)
+          );
           return {
             translations: [
-              { text: 'Au revoir', detected_source_language: 'EN', billed_characters: 10 },
-              { text: 'Bonjour', detected_source_language: 'EN', billed_characters: 7 },
-              { text: 'Bienvenue', detected_source_language: 'EN', billed_characters: 9 },
+              {
+                text: 'Au revoir',
+                detected_source_language: 'EN',
+                billed_characters: 10,
+              },
+              {
+                text: 'Bonjour',
+                detected_source_language: 'EN',
+                billed_characters: 7,
+              },
+              {
+                text: 'Bienvenue',
+                detected_source_language: 'EN',
+                billed_characters: 9,
+              },
             ],
           };
         });
@@ -1224,27 +1514,48 @@ buckets:
   describe('cost cap (max_characters) — new locale addition', () => {
     // 10 keys, each ~50 chars → ~500 chars total for zh → exceeds cap of 100
     const KEYS_50_CHARS = Object.fromEntries(
-      Array.from({ length: 10 }, (_, i) => [`key${i}`, 'a'.repeat(50)]),
+      Array.from({ length: 10 }, (_, i) => [`key${i}`, 'a'.repeat(50)])
     );
 
-    function seedLockWithDeOnly(dir: string, keys: Record<string, string>): void {
+    function seedLockWithDeOnly(
+      dir: string,
+      keys: Record<string, string>
+    ): void {
       const now = '2026-01-01T00:00:00Z';
       const entries: Record<string, Record<string, unknown>> = {};
       const fileEntries: Record<string, unknown> = {};
       for (const [key, val] of Object.entries(keys)) {
         const hash = computeSourceHash(val);
-        fileEntries[key] = { source_text: val, source_hash: hash, translations: { de: { hash, translated_at: now, status: 'translated' } } };
+        fileEntries[key] = {
+          source_text: val,
+          source_hash: hash,
+          translations: {
+            de: { hash, translated_at: now, status: 'translated' },
+          },
+        };
       }
       entries['locales/en.json'] = fileEntries;
       fs.writeFileSync(
         path.join(dir, LOCK_FILE_NAME),
-        JSON.stringify({ version: 1, generated_at: now, source_locale: 'en', entries, stats: {} }, null, 2) + '\n',
-        'utf-8',
+        JSON.stringify(
+          {
+            version: 1,
+            generated_at: now,
+            source_locale: 'en',
+            entries,
+            stats: {},
+          },
+          null,
+          2
+        ) + '\n',
+        'utf-8'
       );
     }
 
     it('should throw cost-cap ValidationError before any API call when adding a new locale', async () => {
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1255,12 +1566,19 @@ buckets:
   json:
     include:
       - "locales/en.json"
-`);
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify(KEYS_50_CHARS, null, 2) + '\n');
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify(KEYS_50_CHARS, null, 2) + '\n'
+      );
       seedLockWithDeOnly(tmpDir, KEYS_50_CHARS);
 
       // No nock scope — any HTTP call must fail the test
-      nock(DEEPL_FREE_API_URL).post('/v2/translate').reply(200, { translations: [] });
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .reply(200, { translations: [] });
 
       const config = await loadSyncConfig(tmpDir);
       await expect(syncService.sync(config)).rejects.toThrow(ValidationError);
@@ -1270,7 +1588,9 @@ buckets:
     });
 
     it('dry-run estimatedChars matches live-path preflight estimatedChars for new-locale addition', async () => {
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1281,8 +1601,13 @@ buckets:
   json:
     include:
       - "locales/en.json"
-`);
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify(KEYS_50_CHARS, null, 2) + '\n');
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify(KEYS_50_CHARS, null, 2) + '\n'
+      );
       seedLockWithDeOnly(tmpDir, KEYS_50_CHARS);
 
       const config = await loadSyncConfig(tmpDir);
@@ -1294,13 +1619,27 @@ buckets:
       // The live path preflight must compute the same estimate; verify by setting cap just below it
       const configAtCap = await loadSyncConfig(tmpDir);
       (configAtCap as any).sync = { ...configAtCap.sync, max_characters: 499 };
-      await expect(syncService.sync(configAtCap)).rejects.toThrow(ValidationError);
+      await expect(syncService.sync(configAtCap)).rejects.toThrow(
+        ValidationError
+      );
 
       const configAboveCap = await loadSyncConfig(tmpDir);
-      (configAboveCap as any).sync = { ...configAboveCap.sync, max_characters: 500 };
-      nock(DEEPL_FREE_API_URL).post('/v2/translate').times(20).reply(200, {
-        translations: [{ text: 'zh-text', detected_source_language: 'EN', billed_characters: 1 }],
-      });
+      (configAboveCap as any).sync = {
+        ...configAboveCap.sync,
+        max_characters: 500,
+      };
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .times(20)
+        .reply(200, {
+          translations: [
+            {
+              text: 'zh-text',
+              detected_source_language: 'EN',
+              billed_characters: 1,
+            },
+          ],
+        });
       await expect(syncService.sync(configAboveCap)).resolves.not.toThrow();
     });
   });
@@ -1312,7 +1651,11 @@ buckets:
         get: jest.fn(() => ({
           auth: {},
           api: { baseUrl: '', usePro: false },
-          defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+          defaults: {
+            targetLangs: [],
+            formality: 'default',
+            preserveFormatting: false,
+          },
           cache: { enabled: false },
           output: { format: 'text', color: true },
           proxy: {},
@@ -1320,13 +1663,23 @@ buckets:
         getValue: jest.fn(() => false),
       });
       const mockCache = createMockCacheService();
-      const retryTranslation = new TranslationService(retryClient, mockConfig, mockCache);
+      const retryTranslation = new TranslationService(
+        retryClient,
+        mockConfig,
+        mockCache
+      );
       const retryGlossary = new GlossaryService(retryClient);
       const retryRegistry = new FormatRegistry();
       retryRegistry.register(new JsonFormatParser());
-      const retrySyncService = new SyncService(retryTranslation, retryGlossary, retryRegistry);
+      const retrySyncService = new SyncService(
+        retryTranslation,
+        retryGlossary,
+        retryRegistry
+      );
 
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1334,8 +1687,13 @@ buckets:
   json:
     include:
       - "locales/en.json"
-`);
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ hello: 'Hello' }, null, 2) + '\n');
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ hello: 'Hello' }, null, 2) + '\n'
+      );
 
       // First request: 429 with Retry-After: 0
       nock(DEEPL_FREE_API_URL)
@@ -1347,7 +1705,11 @@ buckets:
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
           ],
         });
 
@@ -1371,7 +1733,11 @@ buckets:
         get: jest.fn(() => ({
           auth: {},
           api: { baseUrl: '', usePro: false },
-          defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+          defaults: {
+            targetLangs: [],
+            formality: 'default',
+            preserveFormatting: false,
+          },
           cache: { enabled: false },
           output: { format: 'text', color: true },
           proxy: {},
@@ -1379,14 +1745,26 @@ buckets:
         getValue: jest.fn(() => false),
       });
       const mockCache = createMockCacheService();
-      const retryTranslation = new TranslationService(retryClient, mockConfig, mockCache);
+      const retryTranslation = new TranslationService(
+        retryClient,
+        mockConfig,
+        mockCache
+      );
       const retryGlossary = new GlossaryService(retryClient);
       const retryRegistry = new FormatRegistry();
       retryRegistry.register(new JsonFormatParser());
-      const retrySyncService = new SyncService(retryTranslation, retryGlossary, retryRegistry);
+      const retrySyncService = new SyncService(
+        retryTranslation,
+        retryGlossary,
+        retryRegistry
+      );
 
       writeYamlConfig(tmpDir, BASIC_CONFIG_YAML);
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ hello: 'Hello' }, null, 2) + '\n');
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ hello: 'Hello' }, null, 2) + '\n'
+      );
 
       const scope503 = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
@@ -1424,18 +1802,36 @@ buckets:
 
       // de: 200 with translations.
       const deScope = nock(DEEPL_FREE_API_URL)
-        .post('/v2/translate', (body: Record<string, unknown>) => body['target_lang'] === 'DE')
+        .post(
+          '/v2/translate',
+          (body: Record<string, unknown>) => body['target_lang'] === 'DE'
+        )
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
       // fr: 500 (transient server error — sync catches per-locale, does not throw globally).
       const frScope = nock(DEEPL_FREE_API_URL)
-        .post('/v2/translate', (body: Record<string, unknown>) => body['target_lang'] === 'FR')
+        .post(
+          '/v2/translate',
+          (body: Record<string, unknown>) => body['target_lang'] === 'FR'
+        )
         .reply(500, { message: 'Internal Server Error' });
 
       const config = await loadSyncConfig(tmpDir);
@@ -1459,8 +1855,16 @@ buckets:
 
     it('splits large key sets across multiple POST calls at the 50-key batch boundary', async () => {
       const sourceData: Record<string, string> = {};
-      const batch1: Array<{ text: string; detected_source_language: string; billed_characters: number }> = [];
-      const batch2: Array<{ text: string; detected_source_language: string; billed_characters: number }> = [];
+      const batch1: Array<{
+        text: string;
+        detected_source_language: string;
+        billed_characters: number;
+      }> = [];
+      const batch2: Array<{
+        text: string;
+        detected_source_language: string;
+        billed_characters: number;
+      }> = [];
       for (let i = 0; i < 100; i++) {
         const key = `key_${String(i).padStart(3, '0')}`;
         sourceData[key] = `source ${key}`;
@@ -1474,7 +1878,11 @@ buckets:
       }
 
       writeYamlConfig(tmpDir, BASIC_CONFIG_YAML);
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify(sourceData, null, 2) + '\n');
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify(sourceData, null, 2) + '\n'
+      );
 
       const scope1 = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: unknown) => getTexts(body).length === 50)
@@ -1505,7 +1913,9 @@ buckets:
     // reconstruct() mutates a file shared across locales. A parser regression
     // here would silently corrupt user translation files.
     it('translates en source into a de localization within the same .xcstrings file', async () => {
-      const { XcstringsFormatParser } = jest.requireActual<typeof import('../../src/formats/xcstrings')>('../../src/formats/xcstrings');
+      const { XcstringsFormatParser } = jest.requireActual<
+        typeof import('../../src/formats/xcstrings')
+      >('../../src/formats/xcstrings');
       const xcRegistry = new FormatRegistry();
       xcRegistry.register(new XcstringsFormatParser());
       const xcServices = createServicesWithRegistry(xcRegistry);
@@ -1538,14 +1948,26 @@ buckets:
           },
         },
       };
-      writeSourceFile(tmpDir, 'Localizable.xcstrings', JSON.stringify(xcFile, null, 2) + '\n');
+      writeSourceFile(
+        tmpDir,
+        'Localizable.xcstrings',
+        JSON.stringify(xcFile, null, 2) + '\n'
+      );
 
       nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
           ],
         });
 
@@ -1556,16 +1978,36 @@ buckets:
       expect(result.newKeys).toBe(2);
 
       const written = JSON.parse(
-        fs.readFileSync(path.join(tmpDir, 'Localizable.xcstrings'), 'utf-8'),
-      ) as { strings: Record<string, { localizations: Record<string, { stringUnit: { value: string; state: string } }> }> };
+        fs.readFileSync(path.join(tmpDir, 'Localizable.xcstrings'), 'utf-8')
+      ) as {
+        strings: Record<
+          string,
+          {
+            localizations: Record<
+              string,
+              { stringUnit: { value: string; state: string } }
+            >;
+          }
+        >;
+      };
 
       // en localizations preserved
-      expect(written.strings['greeting']!.localizations['en']!.stringUnit.value).toBe('Hello');
-      expect(written.strings['farewell']!.localizations['en']!.stringUnit.value).toBe('Goodbye');
+      expect(
+        written.strings['greeting']!.localizations['en']!.stringUnit.value
+      ).toBe('Hello');
+      expect(
+        written.strings['farewell']!.localizations['en']!.stringUnit.value
+      ).toBe('Goodbye');
       // de localizations populated
-      expect(written.strings['greeting']!.localizations['de']!.stringUnit.value).toBe('Hallo');
-      expect(written.strings['greeting']!.localizations['de']!.stringUnit.state).toBe('translated');
-      expect(written.strings['farewell']!.localizations['de']!.stringUnit.value).toBe('Auf Wiedersehen');
+      expect(
+        written.strings['greeting']!.localizations['de']!.stringUnit.value
+      ).toBe('Hallo');
+      expect(
+        written.strings['greeting']!.localizations['de']!.stringUnit.state
+      ).toBe('translated');
+      expect(
+        written.strings['farewell']!.localizations['de']!.stringUnit.value
+      ).toBe('Auf Wiedersehen');
 
       xcServices.client.destroy();
     });
@@ -1577,7 +2019,9 @@ buckets:
       poRegistry.register(new PoFormatParser());
       const poServices = createServicesWithRegistry(poRegistry);
 
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1585,7 +2029,8 @@ buckets:
   po:
     include:
       - "locales/en.po"
-`);
+`
+      );
 
       const longSource =
         'This is a very long description that should wrap across multiple lines when reconstructed because gettext prefers shorter lines for readability.';
@@ -1598,7 +2043,7 @@ msgstr ""
 
 msgid "${longSource}"
 msgstr ""
-`,
+`
       );
 
       const longTranslation =
@@ -1608,8 +2053,16 @@ msgstr ""
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Speichern', detected_source_language: 'EN', billed_characters: 4 },
-            { text: longTranslation, detected_source_language: 'EN', billed_characters: longSource.length },
+            {
+              text: 'Speichern',
+              detected_source_language: 'EN',
+              billed_characters: 4,
+            },
+            {
+              text: longTranslation,
+              detected_source_language: 'EN',
+              billed_characters: longSource.length,
+            },
           ],
         });
 
@@ -1626,7 +2079,9 @@ msgstr ""
 
       expect(written).toContain('msgctxt "button/save"');
       expect(written).toContain('msgstr "Speichern"');
-      expect(written).toContain(longTranslation.split(' ').slice(0, 3).join(' '));
+      expect(written).toContain(
+        longTranslation.split(' ').slice(0, 3).join(' ')
+      );
 
       const reparsed = new PoFormatParser().extract(written);
       const byKey = new Map(reparsed.map((e) => [e.key, e.value]));
@@ -1642,7 +2097,9 @@ msgstr ""
       tomlRegistry.register(new TomlFormatParser());
       const tomlServices = createServicesWithRegistry(tomlRegistry);
 
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1650,7 +2107,8 @@ buckets:
   toml:
     include:
       - "locales/en.toml"
-`);
+`
+      );
       writeSourceFile(
         tmpDir,
         'locales/en.toml',
@@ -1659,15 +2117,23 @@ hello = "Hello"
 
 [farewells]
 goodbye = "Goodbye"
-`,
+`
       );
 
       const scope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
+            {
+              text: 'Auf Wiedersehen',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
           ],
         });
 
@@ -1697,7 +2163,9 @@ goodbye = "Goodbye"
       arbRegistry.register(new ArbFormatParser());
       const arbServices = createServicesWithRegistry(arbRegistry);
 
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1705,7 +2173,8 @@ buckets:
   arb:
     include:
       - "locales/en.arb"
-`);
+`
+      );
 
       const sourceArb = {
         greeting: 'Hello, {name}',
@@ -1715,14 +2184,26 @@ buckets:
         },
         welcome: 'Welcome',
       };
-      writeSourceFile(tmpDir, 'locales/en.arb', JSON.stringify(sourceArb, null, 2) + '\n');
+      writeSourceFile(
+        tmpDir,
+        'locales/en.arb',
+        JSON.stringify(sourceArb, null, 2) + '\n'
+      );
 
       const scope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Hallo, {name}', detected_source_language: 'EN', billed_characters: 13 },
-            { text: 'Willkommen', detected_source_language: 'EN', billed_characters: 10 },
+            {
+              text: 'Hallo, {name}',
+              detected_source_language: 'EN',
+              billed_characters: 13,
+            },
+            {
+              text: 'Willkommen',
+              detected_source_language: 'EN',
+              billed_characters: 10,
+            },
           ],
         });
 
@@ -1735,7 +2216,9 @@ buckets:
 
       const targetPath = path.join(tmpDir, 'locales', 'de.arb');
       expect(fs.existsSync(targetPath)).toBe(true);
-      const written = JSON.parse(fs.readFileSync(targetPath, 'utf-8')) as Record<string, unknown>;
+      const written = JSON.parse(
+        fs.readFileSync(targetPath, 'utf-8')
+      ) as Record<string, unknown>;
 
       expect(written['greeting']).toBe('Hallo, {name}');
       expect(written['welcome']).toBe('Willkommen');
@@ -1754,7 +2237,9 @@ buckets:
       iosRegistry.register(new IosStringsFormatParser());
       const iosServices = createServicesWithRegistry(iosRegistry);
 
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1762,21 +2247,30 @@ buckets:
   ios_strings:
     include:
       - "locales/en.strings"
-`);
+`
+      );
       writeSourceFile(
         tmpDir,
         'locales/en.strings',
         `"button_save" = "Save \\"Now\\"";
 "greeting" = "Welcome %@";
-`,
+`
       );
 
       const scope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Jetzt "speichern"', detected_source_language: 'EN', billed_characters: 15 },
-            { text: 'Willkommen %@', detected_source_language: 'EN', billed_characters: 13 },
+            {
+              text: 'Jetzt "speichern"',
+              detected_source_language: 'EN',
+              billed_characters: 15,
+            },
+            {
+              text: 'Willkommen %@',
+              detected_source_language: 'EN',
+              billed_characters: 13,
+            },
           ],
         });
 
@@ -1809,7 +2303,9 @@ buckets:
       propRegistry.register(new PropertiesFormatParser());
       const propServices = createServicesWithRegistry(propRegistry);
 
-      writeYamlConfig(tmpDir, `version: 1
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
 source_locale: en
 target_locales:
   - de
@@ -1817,23 +2313,36 @@ buckets:
   properties:
     include:
       - "locales/en.properties"
-`);
+`
+      );
       writeSourceFile(
         tmpDir,
         'locales/en.properties',
         `greeting=Hello
 formula=x=5
 cafe label=Café
-`,
+`
       );
 
       const scope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
         .reply(200, {
           translations: [
-            { text: 'Café', detected_source_language: 'EN', billed_characters: 4 },
-            { text: 'x=5', detected_source_language: 'EN', billed_characters: 3 },
-            { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
+            {
+              text: 'Café',
+              detected_source_language: 'EN',
+              billed_characters: 4,
+            },
+            {
+              text: 'x=5',
+              detected_source_language: 'EN',
+              billed_characters: 3,
+            },
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
           ],
         });
 
@@ -1864,16 +2373,17 @@ describe('Sync Integration — glossary: auto', () => {
   let client: DeepLClient;
   let syncService: SyncService;
 
-  const sourceWithRepeatedTerm = JSON.stringify(
-    {
-      'button.save': 'Save',
-      'form.save': 'Save',
-      'menu.save': 'Save',
-      greeting: 'Hello',
-    },
-    null,
-    2,
-  ) + '\n';
+  const sourceWithRepeatedTerm =
+    JSON.stringify(
+      {
+        'button.save': 'Save',
+        'form.save': 'Save',
+        'menu.save': 'Save',
+        greeting: 'Hello',
+      },
+      null,
+      2
+    ) + '\n';
 
   const autoGlossaryConfig = `version: 1
 source_locale: en
@@ -1896,7 +2406,8 @@ translation:
 
   afterEach(() => {
     client.destroy();
-    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+    if (fs.existsSync(tmpDir))
+      fs.rmSync(tmpDir, { recursive: true, force: true });
     nock.cleanAll();
   });
 
@@ -1911,8 +2422,16 @@ translation:
       .post('/v2/translate')
       .reply(200, {
         translations: [
-          { text: 'Speichern', detected_source_language: 'EN', billed_characters: 4 },
-          { text: 'Hallo', detected_source_language: 'EN', billed_characters: 5 },
+          {
+            text: 'Speichern',
+            detected_source_language: 'EN',
+            billed_characters: 4,
+          },
+          {
+            text: 'Hallo',
+            detected_source_language: 'EN',
+            billed_characters: 5,
+          },
         ],
       });
 
@@ -1928,7 +2447,9 @@ translation:
         glossary_id: 'gl-test-en-de',
         name: 'deepl-sync-en-de',
         creation_time: '2026-04-19T12:00:00Z',
-        dictionaries: [{ source_lang: 'EN', target_lang: 'DE', entry_count: 1 }],
+        dictionaries: [
+          { source_lang: 'EN', target_lang: 'DE', entry_count: 1 },
+        ],
       });
 
     const config = await loadSyncConfig(tmpDir);
@@ -1962,8 +2483,8 @@ translation:
           farewell: 'Goodbye',
         },
         null,
-        2,
-      ) + '\n',
+        2
+      ) + '\n'
     );
 
     // Pre-seed target file (previous sync's output).
@@ -1978,20 +2499,40 @@ translation:
           greeting: 'Hallo',
         },
         null,
-        2,
-      ) + '\n',
+        2
+      ) + '\n'
     );
 
     const now = '2026-04-19T11:00:00Z';
     const saveHash = computeSourceHash('Save');
     const helloHash = computeSourceHash('Hello');
-    const translatedDe = (hash: string) => ({ hash, translated_at: now, status: 'translated' as const });
+    const translatedDe = (hash: string) => ({
+      hash,
+      translated_at: now,
+      status: 'translated' as const,
+    });
     const seedEntries = {
       'locales/en.json': {
-        'button.save': { source_text: 'Save', source_hash: saveHash, translations: { de: translatedDe(saveHash) } },
-        'form.save': { source_text: 'Save', source_hash: saveHash, translations: { de: translatedDe(saveHash) } },
-        'menu.save': { source_text: 'Save', source_hash: saveHash, translations: { de: translatedDe(saveHash) } },
-        greeting: { source_text: 'Hello', source_hash: helloHash, translations: { de: translatedDe(helloHash) } },
+        'button.save': {
+          source_text: 'Save',
+          source_hash: saveHash,
+          translations: { de: translatedDe(saveHash) },
+        },
+        'form.save': {
+          source_text: 'Save',
+          source_hash: saveHash,
+          translations: { de: translatedDe(saveHash) },
+        },
+        'menu.save': {
+          source_text: 'Save',
+          source_hash: saveHash,
+          translations: { de: translatedDe(saveHash) },
+        },
+        greeting: {
+          source_text: 'Hello',
+          source_hash: helloHash,
+          translations: { de: translatedDe(helloHash) },
+        },
       },
     };
     fs.writeFileSync(
@@ -2007,9 +2548,9 @@ translation:
           stats: { total_keys: 4, total_translations: 4, last_sync: now },
         },
         null,
-        2,
+        2
       ) + '\n',
-      'utf-8',
+      'utf-8'
     );
 
     // The new key "farewell" triggers one translate call for "Goodbye".
@@ -2017,7 +2558,11 @@ translation:
       .post('/v2/translate')
       .reply(200, {
         translations: [
-          { text: 'Auf Wiedersehen', detected_source_language: 'EN', billed_characters: 7 },
+          {
+            text: 'Auf Wiedersehen',
+            detected_source_language: 'EN',
+            billed_characters: 7,
+          },
         ],
       });
 
@@ -2030,7 +2575,9 @@ translation:
             glossary_id: 'gl-existing',
             name: 'deepl-sync-en-de',
             creation_time: '2026-04-18T10:00:00Z',
-            dictionaries: [{ source_lang: 'EN', target_lang: 'DE', entry_count: 1 }],
+            dictionaries: [
+              { source_lang: 'EN', target_lang: 'DE', entry_count: 1 },
+            ],
           },
         ],
       });
@@ -2041,7 +2588,12 @@ translation:
       .query(true)
       .reply(200, {
         dictionaries: [
-          { source_lang: 'EN', target_lang: 'DE', entries: 'Save\tSpeichern', entries_format: 'tsv' },
+          {
+            source_lang: 'EN',
+            target_lang: 'DE',
+            entries: 'Save\tSpeichern',
+            entries_format: 'tsv',
+          },
         ],
       });
 
@@ -2057,7 +2609,9 @@ translation:
     expect(entriesScope.isDone()).toBe(true);
 
     // Lockfile glossary_id preserved — not overwritten, not cleared.
-    const lockContent = JSON.parse(fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8'));
+    const lockContent = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8')
+    );
     expect(lockContent.glossary_ids['en-de']).toBe('gl-existing');
   });
 });
@@ -2083,7 +2637,8 @@ describe('Sync Integration — translation memory', () => {
 
   afterEach(() => {
     client.destroy();
-    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+    if (fs.existsSync(tmpDir))
+      fs.rmSync(tmpDir, { recursive: true, force: true });
     nock.cleanAll();
   });
 
@@ -2116,20 +2671,27 @@ describe('Sync Integration — translation memory', () => {
     body: Record<string, string | string[]>;
   }
 
-  function mockTranslateCapture(capture: CapturedCall[], times: number): nock.Scope {
+  function mockTranslateCapture(
+    capture: CapturedCall[],
+    times: number
+  ): nock.Scope {
     return nock(DEEPL_FREE_API_URL)
       .post('/v2/translate')
       .times(times)
       .reply(200, (_uri: string, rawBody: unknown) => {
         const parsed = parseNockBody(rawBody);
         const targetLangRaw = parsed['target_lang'];
-        const targetLang = Array.isArray(targetLangRaw) ? targetLangRaw[0]! : (targetLangRaw as string);
+        const targetLang = Array.isArray(targetLangRaw)
+          ? targetLangRaw[0]!
+          : (targetLangRaw as string);
         const tmIdRaw = parsed['translation_memory_id'];
         const tmThresholdRaw = parsed['translation_memory_threshold'];
         capture.push({
           targetLang,
-          tmId: Array.isArray(tmIdRaw) ? tmIdRaw[0] : (tmIdRaw),
-          tmThreshold: Array.isArray(tmThresholdRaw) ? tmThresholdRaw[0] : (tmThresholdRaw),
+          tmId: Array.isArray(tmIdRaw) ? tmIdRaw[0] : tmIdRaw,
+          tmThreshold: Array.isArray(tmThresholdRaw)
+            ? tmThresholdRaw[0]
+            : tmThresholdRaw,
           body: parsed,
         });
         const texts = getTexts(rawBody);
@@ -2163,9 +2725,13 @@ buckets:
       - "locales/en.json"
 translation:
   translation_memory: "my-tm"
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       const listScope = mockListTms([
         { id: TM_UUID_MY, name: 'my-tm', source: 'en', target: 'de' },
@@ -2209,16 +2775,25 @@ translation:
   locale_overrides:
     de:
       translation_memory: "de-specific-tm"
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       const listScope = mockListTms(
         [
           { id: TM_UUID_BASE, name: 'base-tm', source: 'en', target: 'de' },
-          { id: TM_UUID_DE_SPECIFIC, name: 'de-specific-tm', source: 'en', target: 'de' },
+          {
+            id: TM_UUID_DE_SPECIFIC,
+            name: 'de-specific-tm',
+            source: 'en',
+            target: 'de',
+          },
         ],
-        2,
+        2
       );
 
       const calls: CapturedCall[] = [];
@@ -2255,16 +2830,20 @@ translation:
       translation_memory: "de-tm"
     fr:
       translation_memory: "fr-tm"
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       const listScope = mockListTms(
         [
           { id: TM_UUID_DE, name: 'de-tm', source: 'en', target: 'de' },
           { id: TM_UUID_FR, name: 'fr-tm', source: 'en', target: 'fr' },
         ],
-        2,
+        2
       );
 
       const calls: CapturedCall[] = [];
@@ -2303,9 +2882,13 @@ translation:
   locale_overrides:
     de:
       translation_memory_threshold: 85
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       const listScope = mockListTms([
         { id: TM_UUID_MY, name: 'my-tm', source: 'en', target: 'de' },
@@ -2338,9 +2921,13 @@ buckets:
 translation:
   translation_memory: "my-tm"
   translation_memory_threshold: 60
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       const listScope = mockListTms([
         { id: TM_UUID_MY, name: 'my-tm', source: 'en', target: 'de' },
@@ -2374,9 +2961,13 @@ buckets:
       - "locales/en.json"
 translation:
   translation_memory: "my-tm"
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       const listScope = mockListTms([
         { id: TM_UUID_MY, name: 'my-tm', source: 'en', target: 'de' },
@@ -2399,7 +2990,11 @@ translation:
   describe('omit-both on no-TM config', () => {
     it('sends neither translation_memory_id nor translation_memory_threshold and makes zero list calls', async () => {
       writeYamlConfig(tmpDir, BASIC_CONFIG_YAML);
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
+      );
 
       const calls: CapturedCall[] = [];
       const translateScope = mockTranslateCapture(calls, 1);
@@ -2415,7 +3010,9 @@ translation:
         expect(call.body['translation_memory_threshold']).toBeUndefined();
       }
 
-      const listMocksAfter = nock.pendingMocks().filter((m) => m.includes('/v3/translation_memories'));
+      const listMocksAfter = nock
+        .pendingMocks()
+        .filter((m) => m.includes('/v3/translation_memories'));
       expect(listMocksAfter).toEqual([]);
       expect(translateScope.isDone()).toBe(true);
     });
@@ -2436,9 +3033,13 @@ buckets:
       - "locales/en.json"
 translation:
   translation_memory: "my-tm"
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       const listScope = mockListTms([
         { id: TM_UUID_MY, name: 'my-tm', source: 'en', target: 'de' },
@@ -2450,7 +3051,7 @@ translation:
       expect(result.success).toBe(true);
 
       const lockContent = JSON.parse(
-        fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8'),
+        fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8')
       ) as Record<string, unknown>;
       expect(lockContent['translation_memory_ids']).toBeUndefined();
       expect(listScope.isDone()).toBe(true);
@@ -2482,19 +3083,25 @@ translation:
   locale_overrides:
     fr:
       translation_memory: "shared"
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       const listScope = mockListTms(
         [{ id: TM_UUID_SHARED, name: 'shared', source: 'en', target: 'de' }],
-        1,
+        1
       );
 
       const config = await loadSyncConfig(tmpDir);
       const caught = await syncService.sync(config).catch((e: unknown) => e);
       expect(caught).toBeInstanceOf(ConfigError);
-      expect((caught as Error).message).toMatch(/does not support the requested language pair/);
+      expect((caught as Error).message).toMatch(
+        /does not support the requested language pair/
+      );
 
       expect(listScope.isDone()).toBe(true);
     });
@@ -2516,13 +3123,17 @@ buckets:
 translation:
   translation_memory: "my-tm"
   translation_memory_threshold: 999
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       await expect(loadSyncConfig(tmpDir)).rejects.toThrow(ConfigError);
       await expect(loadSyncConfig(tmpDir)).rejects.toThrow(
-        /translation\.translation_memory_threshold must be an integer between 0 and 100/,
+        /translation\.translation_memory_threshold must be an integer between 0 and 100/
       );
     });
   });
@@ -2545,9 +3156,13 @@ translation:
   locale_overrides:
     de:
       translation_memory: "de-specific-tm"
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
       // Only the listing is mocked. A /v2/translate request would be unmatched
       // and fail the test, which is the invariant a dry run has to keep.
@@ -2555,9 +3170,14 @@ translation:
       const listScope = mockListTms(
         [
           { id: TM_UUID_MY, name: 'my-tm', source: 'en', target: 'de' },
-          { id: TM_UUID_DE_SPECIFIC, name: 'de-specific-tm', source: 'en', target: 'de' },
+          {
+            id: TM_UUID_DE_SPECIFIC,
+            name: 'de-specific-tm',
+            source: 'en',
+            target: 'de',
+          },
         ],
-        2,
+        2
       );
 
       const config = await loadSyncConfig(tmpDir);
@@ -2584,28 +3204,45 @@ translation:
   locale_overrides:
     fr:
       translation_memory: "de-only"
-`,
+`
+      );
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
       );
-      writeSourceFile(tmpDir, 'locales/en.json', JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n');
 
-      mockListTms([{ id: TM_UUID_DE, name: 'de-only', source: 'en', target: 'de' }]);
+      mockListTms([
+        { id: TM_UUID_DE, name: 'de-only', source: 'en', target: 'de' },
+      ]);
 
       const config = await loadSyncConfig(tmpDir);
-      const caught = await syncService.sync(config, { dryRun: true }).catch((e: unknown) => e);
+      const caught = await syncService
+        .sync(config, { dryRun: true })
+        .catch((e: unknown) => e);
 
       expect(caught).toBeInstanceOf(ConfigError);
-      expect((caught as Error).message).toMatch(/does not support the requested language pair/);
+      expect((caught as Error).message).toMatch(
+        /does not support the requested language pair/
+      );
     });
   });
 });
 
-function createServicesWithRegistry(registry: FormatRegistry): { client: DeepLClient; syncService: SyncService } {
+function createServicesWithRegistry(registry: FormatRegistry): {
+  client: DeepLClient;
+  syncService: SyncService;
+} {
   const client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
   const mockConfig = createMockConfigService({
     get: jest.fn(() => ({
       auth: {},
       api: { baseUrl: '', usePro: false },
-      defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
       cache: { enabled: false },
       output: { format: 'text', color: true },
       proxy: {},
@@ -2613,8 +3250,16 @@ function createServicesWithRegistry(registry: FormatRegistry): { client: DeepLCl
     getValue: jest.fn(() => false),
   });
   const mockCache = createMockCacheService();
-  const translationService = new TranslationService(client, mockConfig, mockCache);
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    mockCache
+  );
   const glossaryService = new GlossaryService(client);
-  const syncService = new SyncService(translationService, glossaryService, registry);
+  const syncService = new SyncService(
+    translationService,
+    glossaryService,
+    registry
+  );
   return { client, syncService };
 }
diff --git a/tests/integration/watch-auto-commit.integration.test.ts b/tests/integration/watch-auto-commit.integration.test.ts
index 9251a890..8787f073 100644
--- a/tests/integration/watch-auto-commit.integration.test.ts
+++ b/tests/integration/watch-auto-commit.integration.test.ts
@@ -54,16 +54,22 @@ describe('Watch auto-commit integration', () => {
 
     // Init a real git repo
     execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
-    execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.email "test@test.com"', {
+      cwd: tmpDir,
+      stdio: 'ignore',
+    });
     execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'ignore' });
 
     // Create an initial commit so HEAD exists
     fs.writeFileSync(path.join(tmpDir, 'README.md'), 'init');
-    execSync('git add . && git commit -m "init"', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git add . && git commit -m "init"', {
+      cwd: tmpDir,
+      stdio: 'ignore',
+    });
 
     watchCommand = new WatchCommand(
       createMockTranslationService(),
-      createMockGlossaryService(),
+      createMockGlossaryService()
     );
   });
 
@@ -96,10 +102,13 @@ describe('Watch auto-commit integration', () => {
     }
 
     // Verify git log shows the commit
-    const log = execSync('git log --oneline -1', { cwd: tmpDir, encoding: 'utf-8' });
+    const log = execSync('git log --oneline -1', {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    });
     expect(log).toContain('chore(i18n): auto-translate file.md to es');
-    expect((Logger.success as jest.Mock)).toHaveBeenCalledWith(
-      expect.stringContaining('Auto-committed'),
+    expect(Logger.success as jest.Mock).toHaveBeenCalledWith(
+      expect.stringContaining('Auto-committed')
     );
   });
 
@@ -120,7 +129,10 @@ describe('Watch auto-commit integration', () => {
       process.chdir(origCwd);
     }
 
-    const log = execSync('git log --oneline -1', { cwd: tmpDir, encoding: 'utf-8' });
+    const log = execSync('git log --oneline -1', {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    });
     expect(log).toContain('chore(i18n): auto-translate file.md to es, fr');
 
     // Both files should be in the commit
@@ -149,8 +161,8 @@ describe('Watch auto-commit integration', () => {
       process.chdir(origCwd);
     }
 
-    expect((Logger.warn as jest.Mock)).toHaveBeenCalledWith(
-      expect.stringContaining('Not a git repository'),
+    expect(Logger.warn as jest.Mock).toHaveBeenCalledWith(
+      expect.stringContaining('Not a git repository')
     );
 
     fs.rmSync(nonGitDir, { recursive: true, force: true });
@@ -170,7 +182,10 @@ describe('Watch auto-commit integration', () => {
     }
 
     // Should only have the initial commit
-    const count = execSync('git rev-list --count HEAD', { cwd: tmpDir, encoding: 'utf-8' }).trim();
+    const count = execSync('git rev-list --count HEAD', {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    }).trim();
     expect(count).toBe('1');
   });
 
@@ -188,9 +203,9 @@ describe('Watch auto-commit integration', () => {
       process.chdir(origCwd);
     }
 
-    expect((Logger.error as jest.Mock)).toHaveBeenCalledWith(
+    expect(Logger.error as jest.Mock).toHaveBeenCalledWith(
       expect.stringContaining('Auto-commit failed'),
-      expect.any(String),
+      expect.any(String)
     );
   });
 });
diff --git a/tests/require-build.ts b/tests/require-build.ts
index 33cd3a14..4e34a10a 100644
--- a/tests/require-build.ts
+++ b/tests/require-build.ts
@@ -14,7 +14,17 @@ const SRC = path.join(ROOT, 'src');
 
 function fail(reason: string, detail: string): never {
   throw new Error(
-    ['', reason, '', detail, '', 'Run:', '', '  npm run build && npm test', ''].join('\n'),
+    [
+      '',
+      reason,
+      '',
+      detail,
+      '',
+      'Run:',
+      '',
+      '  npm run build && npm test',
+      '',
+    ].join('\n')
   );
 }
 
@@ -36,7 +46,7 @@ export default function requireBuild(): void {
   if (!fs.existsSync(CLI_ENTRY)) {
     fail(
       'Tests require a build, but dist/cli/index.js does not exist.',
-      `  Expected: ${CLI_ENTRY}\n\ndist/ is gitignored, so a fresh checkout or a pull has no built output.`,
+      `  Expected: ${CLI_ENTRY}\n\ndist/ is gitignored, so a fresh checkout or a pull has no built output.`
     );
   }
 
@@ -46,7 +56,7 @@ export default function requireBuild(): void {
   if (sourceChangedAt > builtAt) {
     fail(
       'Tests require a current build, but src/ is newer than dist/.',
-      'The suites execute dist/cli/index.js, so they would test the previously\nbuilt CLI and report results that do not describe your changes.',
+      'The suites execute dist/cli/index.js, so they would test the previously\nbuilt CLI and report results that do not describe your changes.'
     );
   }
 }
diff --git a/tests/setup.ts b/tests/setup.ts
index c96272fd..05480479 100644
--- a/tests/setup.ts
+++ b/tests/setup.ts
@@ -23,7 +23,7 @@ afterEach(() => {
     // (e.g., to confirm a cache-hit path skips the network) can opt out by
     // calling `nock.cleanAll()` from their own afterEach before this hook runs.
     throw new Error(
-      `nock had ${pending.length} unasserted pending interceptor(s) at end of test:\n  ${pending.join('\n  ')}`,
+      `nock had ${pending.length} unasserted pending interceptor(s) at end of test:\n  ${pending.join('\n  ')}`
     );
   }
 });
diff --git a/tests/unit/admin-client.test.ts b/tests/unit/admin-client.test.ts
index f8f0df6f..8b2e86f4 100644
--- a/tests/unit/admin-client.test.ts
+++ b/tests/unit/admin-client.test.ts
@@ -45,14 +45,12 @@ describe('AdminClient', () => {
     });
 
     it('should handle response without a key field', async () => {
-      nock(baseUrl)
-        .post('/v2/admin/developer-keys')
-        .reply(200, {
-          key_id: 'existing-key-id',
-          label: 'Some Key',
-          creation_time: '2024-06-01T12:00:00Z',
-          is_deactivated: false,
-        });
+      nock(baseUrl).post('/v2/admin/developer-keys').reply(200, {
+        key_id: 'existing-key-id',
+        label: 'Some Key',
+        creation_time: '2024-06-01T12:00:00Z',
+        is_deactivated: false,
+      });
 
       const result = await client.createApiKey('Some Key');
       expect(result.key).toBeUndefined();
@@ -63,7 +61,10 @@ describe('AdminClient', () => {
   describe('setApiKeyLimit', () => {
     it('should send characters-only limit when STT is not specified', async () => {
       const scope = nock(baseUrl)
-        .put('/v2/admin/developer-keys/limits', { key_id: 'key-1', characters: 1000000 })
+        .put('/v2/admin/developer-keys/limits', {
+          key_id: 'key-1',
+          characters: 1000000,
+        })
         .reply(200);
 
       await client.setApiKeyLimit('key-1', 1000000);
@@ -126,7 +127,10 @@ describe('AdminClient', () => {
             label: 'Voice Key',
             creation_time: '2024-01-01T00:00:00Z',
             is_deactivated: false,
-            usage_limits: { characters: null, speech_to_text_milliseconds: 7200000 },
+            usage_limits: {
+              characters: null,
+              speech_to_text_milliseconds: 7200000,
+            },
           },
         ]);
 
diff --git a/tests/unit/admin-command.test.ts b/tests/unit/admin-command.test.ts
index ff2bcbb5..6f9ec0e9 100644
--- a/tests/unit/admin-command.test.ts
+++ b/tests/unit/admin-command.test.ts
@@ -100,24 +100,39 @@ describe('AdminCommand', () => {
   describe('renameKey', () => {
     it('should call renameApiKey', async () => {
       await command.renameKey('key-1', 'New Label');
-      expect(mockService.renameApiKey).toHaveBeenCalledWith('key-1', 'New Label');
+      expect(mockService.renameApiKey).toHaveBeenCalledWith(
+        'key-1',
+        'New Label'
+      );
     });
   });
 
   describe('setKeyLimit', () => {
     it('should call setApiKeyLimit with number', async () => {
       await command.setKeyLimit('key-1', 1000000);
-      expect(mockService.setApiKeyLimit).toHaveBeenCalledWith('key-1', 1000000, undefined);
+      expect(mockService.setApiKeyLimit).toHaveBeenCalledWith(
+        'key-1',
+        1000000,
+        undefined
+      );
     });
 
     it('should call setApiKeyLimit with null for unlimited', async () => {
       await command.setKeyLimit('key-1', null);
-      expect(mockService.setApiKeyLimit).toHaveBeenCalledWith('key-1', null, undefined);
+      expect(mockService.setApiKeyLimit).toHaveBeenCalledWith(
+        'key-1',
+        null,
+        undefined
+      );
     });
 
     it('should pass sttLimit to service', async () => {
       await command.setKeyLimit('key-1', 500000, 3600000);
-      expect(mockService.setApiKeyLimit).toHaveBeenCalledWith('key-1', 500000, 3600000);
+      expect(mockService.setApiKeyLimit).toHaveBeenCalledWith(
+        'key-1',
+        500000,
+        3600000
+      );
     });
   });
 
@@ -216,7 +231,10 @@ describe('AdminCommand', () => {
           label: 'STT Key',
           creationTime: '2024-01-01T00:00:00Z',
           isDeactivated: false,
-          usageLimits: { characters: 1000000, speechToTextMilliseconds: 3600000 },
+          usageLimits: {
+            characters: 1000000,
+            speechToTextMilliseconds: 3600000,
+          },
         },
       ];
 
@@ -450,7 +468,7 @@ describe('AdminCommand', () => {
               textTranslationCharacters: 2000,
               documentTranslationCharacters: 500,
               textImprovementCharacters: 500,
-          speechToTextMilliseconds: 0,
+              speechToTextMilliseconds: 0,
             },
           },
         ],
@@ -600,20 +618,26 @@ describe('AdminCommand', () => {
 
     it('should propagate renameKey errors from service', async () => {
       mockService.renameApiKey.mockRejectedValue(new Error('Unauthorized'));
-      await expect(command.renameKey('key-x', 'name')).rejects.toThrow('Unauthorized');
+      await expect(command.renameKey('key-x', 'name')).rejects.toThrow(
+        'Unauthorized'
+      );
     });
 
     it('should propagate setKeyLimit errors from service', async () => {
       mockService.setApiKeyLimit.mockRejectedValue(new Error('Bad request'));
-      await expect(command.setKeyLimit('key-x', 100)).rejects.toThrow('Bad request');
+      await expect(command.setKeyLimit('key-x', 100)).rejects.toThrow(
+        'Bad request'
+      );
     });
 
     it('should propagate getUsage errors from service', async () => {
       mockService.getAdminUsage.mockRejectedValue(new Error('Server error'));
-      await expect(command.getUsage({
-        startDate: '2024-01-01',
-        endDate: '2024-01-31',
-      })).rejects.toThrow('Server error');
+      await expect(
+        command.getUsage({
+          startDate: '2024-01-01',
+          endDate: '2024-01-31',
+        })
+      ).rejects.toThrow('Server error');
     });
   });
 
diff --git a/tests/unit/atomic-write.test.ts b/tests/unit/atomic-write.test.ts
index dee9599b..362beee4 100644
--- a/tests/unit/atomic-write.test.ts
+++ b/tests/unit/atomic-write.test.ts
@@ -28,16 +28,24 @@ describe('atomicWriteFile', () => {
   it('should not leave .tmp file after success', async () => {
     const filePath = path.join(tmpDir, 'output.txt');
     await atomicWriteFile(filePath, 'content', 'utf-8');
-    const leftover = fs.readdirSync(tmpDir).filter((f) => f.startsWith('output.txt.tmp.'));
+    const leftover = fs
+      .readdirSync(tmpDir)
+      .filter((f) => f.startsWith('output.txt.tmp.'));
     expect(leftover).toHaveLength(0);
   });
 
   it('should clean up .tmp file after rename failure', async () => {
     const filePath = path.join(tmpDir, 'output.txt');
-    const renameSpy = jest.spyOn(fs.promises, 'rename').mockRejectedValueOnce(new Error('rename failed'));
-
-    await expect(atomicWriteFile(filePath, 'content', 'utf-8')).rejects.toThrow('rename failed');
-    const leftover = fs.readdirSync(tmpDir).filter((f) => f.startsWith('output.txt.tmp.'));
+    const renameSpy = jest
+      .spyOn(fs.promises, 'rename')
+      .mockRejectedValueOnce(new Error('rename failed'));
+
+    await expect(atomicWriteFile(filePath, 'content', 'utf-8')).rejects.toThrow(
+      'rename failed'
+    );
+    const leftover = fs
+      .readdirSync(tmpDir)
+      .filter((f) => f.startsWith('output.txt.tmp.'));
     expect(leftover).toHaveLength(0);
 
     renameSpy.mockRestore();
@@ -82,7 +90,9 @@ describe('atomicWriteFile', () => {
     const writeSpy = jest.spyOn(fs.promises, 'writeFile');
     await atomicWriteFile(filePath, 'data', 'utf-8');
     const tmpPathArg = String(writeSpy.mock.calls[0]?.[0]);
-    expect(tmpPathArg).toMatch(new RegExp(`\\.tmp\\.${process.pid}\\.[a-z0-9]+$`));
+    expect(tmpPathArg).toMatch(
+      new RegExp(`\\.tmp\\.${process.pid}\\.[a-z0-9]+$`)
+    );
     writeSpy.mockRestore();
   });
 });
@@ -107,7 +117,9 @@ describe('atomicWriteFileSync', () => {
   it('should not leave .tmp file after success', () => {
     const filePath = path.join(tmpDir, 'output.txt');
     atomicWriteFileSync(filePath, 'content', 'utf-8');
-    const leftover = fs.readdirSync(tmpDir).filter((f) => f.startsWith('output.txt.tmp.'));
+    const leftover = fs
+      .readdirSync(tmpDir)
+      .filter((f) => f.startsWith('output.txt.tmp.'));
     expect(leftover).toHaveLength(0);
   });
 
@@ -161,17 +173,21 @@ describe('atomic-write crash cleanup', () => {
     const countBefore = __getInFlightTmpCount();
 
     let tmpPathObserved: string | null = null;
-    const writeSpy = jest.spyOn(fs.promises, 'writeFile').mockImplementationOnce(async (p) => {
-      tmpPathObserved = String(p);
-      // Write synchronously under our own hand so the file exists to be
-      // "discovered" by the cleanup helper, simulating a crash between
-      // write and rename.
-      fs.writeFileSync(tmpPathObserved, 'partial');
-      expect(__getInFlightTmpCount()).toBe(countBefore + 1);
-      throw new Error('simulated crash');
-    });
-
-    await expect(atomicWriteFile(filePath, 'content', 'utf-8')).rejects.toThrow('simulated crash');
+    const writeSpy = jest
+      .spyOn(fs.promises, 'writeFile')
+      .mockImplementationOnce(async (p) => {
+        tmpPathObserved = String(p);
+        // Write synchronously under our own hand so the file exists to be
+        // "discovered" by the cleanup helper, simulating a crash between
+        // write and rename.
+        fs.writeFileSync(tmpPathObserved, 'partial');
+        expect(__getInFlightTmpCount()).toBe(countBefore + 1);
+        throw new Error('simulated crash');
+      });
+
+    await expect(atomicWriteFile(filePath, 'content', 'utf-8')).rejects.toThrow(
+      'simulated crash'
+    );
     writeSpy.mockRestore();
 
     expect(tmpPathObserved).not.toBeNull();
@@ -187,23 +203,31 @@ describe('atomic-write crash cleanup', () => {
     // Fire through a real atomicWriteFile call whose underlying writeFile hangs:
     // we'll use the synchronous helper instead. But easier: call the cleanup
     // helper after poking at a private accessor to emulate tracked state.
-    const writeSpy = jest.spyOn(fs.promises, 'writeFile').mockImplementationOnce(async (p) => {
-      const actualTmp = String(p);
-      fs.writeFileSync(actualTmp, 'partial');
-      // At this point the tmp is tracked. Trigger the public cleanup.
-      __cleanupInFlightTmpFiles();
-      expect(fs.existsSync(actualTmp)).toBe(false);
-      throw new Error('abort after cleanup');
-    });
-
-    const run = atomicWriteFile(path.join(tmpDir, 'output.txt'), 'content', 'utf-8');
-    return expect(run).rejects.toThrow('abort after cleanup').then(() => {
-      writeSpy.mockRestore();
-      // Seed tmp file should also have been cleaned if tracked — but it wasn't
-      // tracked (we wrote it ourselves) so it remains. That's expected; the
-      // helper only cleans up registered paths.
-      expect(fs.existsSync(tmpPath)).toBe(true);
-    });
+    const writeSpy = jest
+      .spyOn(fs.promises, 'writeFile')
+      .mockImplementationOnce(async (p) => {
+        const actualTmp = String(p);
+        fs.writeFileSync(actualTmp, 'partial');
+        // At this point the tmp is tracked. Trigger the public cleanup.
+        __cleanupInFlightTmpFiles();
+        expect(fs.existsSync(actualTmp)).toBe(false);
+        throw new Error('abort after cleanup');
+      });
+
+    const run = atomicWriteFile(
+      path.join(tmpDir, 'output.txt'),
+      'content',
+      'utf-8'
+    );
+    return expect(run)
+      .rejects.toThrow('abort after cleanup')
+      .then(() => {
+        writeSpy.mockRestore();
+        // Seed tmp file should also have been cleaned if tracked — but it wasn't
+        // tracked (we wrote it ourselves) so it remains. That's expected; the
+        // helper only cleans up registered paths.
+        expect(fs.existsSync(tmpPath)).toBe(true);
+      });
   });
 
   it('registers SIGINT/SIGTERM listeners while a write is pending and detaches after', async () => {
@@ -213,15 +237,21 @@ describe('atomic-write crash cleanup', () => {
 
     let observedSigint = 0;
     let observedSigterm = 0;
-    const writeSpy = jest.spyOn(fs.promises, 'writeFile').mockImplementationOnce(async (p) => {
-      // Mid-write: signal listeners should be attached.
-      observedSigint = process.listenerCount('SIGINT') - sigintBase;
-      observedSigterm = process.listenerCount('SIGTERM') - sigtermBase;
-      fs.writeFileSync(String(p), 'partial');
-      throw new Error('abort mid-write');
-    });
-
-    const run = atomicWriteFile(path.join(tmpDir, 'output.txt'), 'data', 'utf-8');
+    const writeSpy = jest
+      .spyOn(fs.promises, 'writeFile')
+      .mockImplementationOnce(async (p) => {
+        // Mid-write: signal listeners should be attached.
+        observedSigint = process.listenerCount('SIGINT') - sigintBase;
+        observedSigterm = process.listenerCount('SIGTERM') - sigtermBase;
+        fs.writeFileSync(String(p), 'partial');
+        throw new Error('abort mid-write');
+      });
+
+    const run = atomicWriteFile(
+      path.join(tmpDir, 'output.txt'),
+      'data',
+      'utf-8'
+    );
     await expect(run).rejects.toThrow('abort mid-write');
     writeSpy.mockRestore();
 
diff --git a/tests/unit/auth-command.test.ts b/tests/unit/auth-command.test.ts
index 684f4e68..360358e0 100644
--- a/tests/unit/auth-command.test.ts
+++ b/tests/unit/auth-command.test.ts
@@ -2,8 +2,6 @@
  * Tests for Auth Command
  */
 
- 
-
 import { Command } from 'commander';
 import { AuthCommand } from '../../src/cli/commands/auth';
 import { ConfigService } from '../../src/storage/config';
@@ -15,8 +13,13 @@ import { NetworkError } from '../../src/utils/errors';
 jest.mock('chalk', () => {
   const passthrough = (s: string) => s;
   const obj: Record<string, unknown> & { level: number } = {
-    level: 3, red: passthrough, green: passthrough, blue: passthrough,
-    yellow: passthrough, gray: passthrough, bold: passthrough,
+    level: 3,
+    red: passthrough,
+    green: passthrough,
+    blue: passthrough,
+    yellow: passthrough,
+    gray: passthrough,
+    bold: passthrough,
   };
   return { __esModule: true, default: obj };
 });
@@ -52,27 +55,42 @@ describe('AuthCommand', () => {
   describe('setKey()', () => {
     it('should store API key in config', async () => {
       // Mock DeepL client validation
-      const mockGetUsage = jest.fn().mockResolvedValue({ character: { count: 0, limit: 500000 } });
-      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-        getUsage: mockGetUsage,
-      } as any));
+      const mockGetUsage = jest
+        .fn()
+        .mockResolvedValue({ character: { count: 0, limit: 500000 } });
+      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(
+        () =>
+          ({
+            getUsage: mockGetUsage,
+          }) as any
+      );
 
       await authCommand.setKey('a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx');
 
-      expect(mockConfigService.set).toHaveBeenCalledWith('auth.apiKey', 'a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx');
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'auth.apiKey',
+        'a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx'
+      );
       expect(mockGetUsage).toHaveBeenCalled();
     });
 
     it('should throw error for empty API key', async () => {
-      await expect(authCommand.setKey('')).rejects.toThrow('API key cannot be empty');
+      await expect(authCommand.setKey('')).rejects.toThrow(
+        'API key cannot be empty'
+      );
     });
 
     it('should validate API key with DeepL API', async () => {
       // Mock DeepL client validation
-      const mockGetUsage = jest.fn().mockResolvedValue({ character: { count: 0, limit: 500000 } });
-      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-        getUsage: mockGetUsage,
-      } as any));
+      const mockGetUsage = jest
+        .fn()
+        .mockResolvedValue({ character: { count: 0, limit: 500000 } });
+      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(
+        () =>
+          ({
+            getUsage: mockGetUsage,
+          }) as any
+      );
 
       await authCommand.setKey('a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx');
 
@@ -83,33 +101,55 @@ describe('AuthCommand', () => {
 
     it('should handle config save errors', async () => {
       // Mock DeepL client validation to succeed
-      const mockGetUsage = jest.fn().mockResolvedValue({ character: { count: 0, limit: 500000 } });
-      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-        getUsage: mockGetUsage,
-      } as any));
+      const mockGetUsage = jest
+        .fn()
+        .mockResolvedValue({ character: { count: 0, limit: 500000 } });
+      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(
+        () =>
+          ({
+            getUsage: mockGetUsage,
+          }) as any
+      );
 
-      (mockConfigService.set as jest.Mock).mockImplementationOnce(() => { throw new Error('Failed to save config'); });
+      (mockConfigService.set as jest.Mock).mockImplementationOnce(() => {
+        throw new Error('Failed to save config');
+      });
 
-      await expect(authCommand.setKey('a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx')).rejects.toThrow('Failed to save config');
+      await expect(
+        authCommand.setKey('a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx')
+      ).rejects.toThrow('Failed to save config');
     });
 
     it('should handle non-Error exceptions during validation', async () => {
       // Mock DeepL client to throw non-Error exception
       const mockGetUsage = jest.fn().mockRejectedValue('String error');
-      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-        getUsage: mockGetUsage,
-      } as any));
+      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(
+        () =>
+          ({
+            getUsage: mockGetUsage,
+          }) as any
+      );
 
-      await expect(authCommand.setKey('test-key')).rejects.toThrow('Failed to validate API key');
+      await expect(authCommand.setKey('test-key')).rejects.toThrow(
+        'Failed to validate API key'
+      );
     });
 
     it('should pass HTTP client options through to the validation client', async () => {
-      const mockGetUsage = jest.fn().mockResolvedValue({ character: { count: 0, limit: 500000 } });
-      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-        getUsage: mockGetUsage,
-      } as any));
+      const mockGetUsage = jest
+        .fn()
+        .mockResolvedValue({ character: { count: 0, limit: 500000 } });
+      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(
+        () =>
+          ({
+            getUsage: mockGetUsage,
+          }) as any
+      );
 
-      const cmd = new AuthCommand(mockConfigService, { timeout: 1234, maxRetries: 9 });
+      const cmd = new AuthCommand(mockConfigService, {
+        timeout: 1234,
+        maxRetries: 9,
+      });
       await cmd.setKey('test-key');
 
       expect(DeepLClient).toHaveBeenCalledWith(
@@ -120,12 +160,19 @@ describe('AuthCommand', () => {
 
     it('should handle non-authentication API errors', async () => {
       // Mock DeepL client to throw error without "Authentication failed" message
-      const mockGetUsage = jest.fn().mockRejectedValue(new Error('Network timeout'));
-      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-        getUsage: mockGetUsage,
-      } as any));
+      const mockGetUsage = jest
+        .fn()
+        .mockRejectedValue(new Error('Network timeout'));
+      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(
+        () =>
+          ({
+            getUsage: mockGetUsage,
+          }) as any
+      );
 
-      await expect(authCommand.setKey('test-key')).rejects.toThrow('Network timeout');
+      await expect(authCommand.setKey('test-key')).rejects.toThrow(
+        'Network timeout'
+      );
     });
 
     describe('offline storage', () => {
@@ -133,32 +180,46 @@ describe('AuthCommand', () => {
       // documented way to store a key was closed.
       it('should store the key without contacting the API when verify is false', async () => {
         const mockGetUsage = jest.fn();
-        (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-          getUsage: mockGetUsage,
-        } as any));
+        (
+          DeepLClient as jest.MockedClass<typeof DeepLClient>
+        ).mockImplementation(
+          () =>
+            ({
+              getUsage: mockGetUsage,
+            }) as any
+        );
 
-        await authCommand.setKey('a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx', { verify: false });
+        await authCommand.setKey('a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx', {
+          verify: false,
+        });
 
         expect(mockConfigService.set).toHaveBeenCalledWith(
           'auth.apiKey',
-          'a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx',
+          'a1b2c3d4-e5f6-7890-abcd-ef1234567890:fx'
         );
         expect(mockGetUsage).not.toHaveBeenCalled();
       });
 
       it('should still reject an empty key when verification is skipped', async () => {
         await expect(authCommand.setKey('', { verify: false })).rejects.toThrow(
-          'API key cannot be empty',
+          'API key cannot be empty'
         );
       });
 
       it('should name the offline alternatives when the API is unreachable', async () => {
         const mockGetUsage = jest
           .fn()
-          .mockRejectedValue(new NetworkError('connect ECONNREFUSED 127.0.0.1:443'));
-        (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-          getUsage: mockGetUsage,
-        } as any));
+          .mockRejectedValue(
+            new NetworkError('connect ECONNREFUSED 127.0.0.1:443')
+          );
+        (
+          DeepLClient as jest.MockedClass<typeof DeepLClient>
+        ).mockImplementation(
+          () =>
+            ({
+              getUsage: mockGetUsage,
+            }) as any
+        );
 
         await expect(authCommand.setKey('test-key')).rejects.toMatchObject({
           suggestion: expect.stringContaining('--no-verify'),
@@ -170,7 +231,9 @@ describe('AuthCommand', () => {
 
   describe('getKey()', () => {
     it('should retrieve API key from config', async () => {
-      (mockConfigService.getValue as jest.Mock).mockReturnValueOnce('test-api-key-123');
+      (mockConfigService.getValue as jest.Mock).mockReturnValueOnce(
+        'test-api-key-123'
+      );
 
       const key = await authCommand.getKey();
 
@@ -204,7 +267,9 @@ describe('AuthCommand', () => {
 
     it('should prefer config over environment variable', async () => {
       process.env['DEEPL_API_KEY'] = 'env-api-key';
-      (mockConfigService.getValue as jest.Mock).mockReturnValueOnce('config-api-key');
+      (mockConfigService.getValue as jest.Mock).mockReturnValueOnce(
+        'config-api-key'
+      );
 
       const key = await authCommand.getKey();
 
@@ -222,7 +287,9 @@ describe('AuthCommand', () => {
     });
 
     it('should handle config delete errors', async () => {
-      (mockConfigService.delete as jest.Mock).mockImplementationOnce(() => { throw new Error('Failed to delete'); });
+      (mockConfigService.delete as jest.Mock).mockImplementationOnce(() => {
+        throw new Error('Failed to delete');
+      });
 
       await expect(authCommand.clearKey()).rejects.toThrow('Failed to delete');
     });
@@ -234,7 +301,8 @@ describe('registerAuth - deprecation warning', () => {
   let registerAuth: typeof import('../../src/cli/commands/register-auth').registerAuth;
 
   beforeAll(async () => {
-    registerAuth = (await import('../../src/cli/commands/register-auth')).registerAuth;
+    registerAuth = (await import('../../src/cli/commands/register-auth'))
+      .registerAuth;
   });
 
   beforeEach(() => {
@@ -243,42 +311,68 @@ describe('registerAuth - deprecation warning', () => {
 
   it('should warn when positional API key is passed without --from-stdin', async () => {
     const mockConfigService = createMockConfigService();
-    const mockGetUsage = jest.fn().mockResolvedValue({ character: { count: 0, limit: 500000 } });
-    (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-      getUsage: mockGetUsage,
-    } as any));
+    const mockGetUsage = jest
+      .fn()
+      .mockResolvedValue({ character: { count: 0, limit: 500000 } });
+    (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(
+      () =>
+        ({
+          getUsage: mockGetUsage,
+        }) as any
+    );
 
     const program = new Command();
     program.exitOverride();
     registerAuth(program, {
       getConfigService: () => mockConfigService,
-      handleError: (error: unknown) => { throw error; },
+      handleError: (error: unknown) => {
+        throw error;
+      },
     });
 
-    await program.parseAsync(['node', 'deepl', 'auth', 'set-key', 'test-key-123']);
+    await program.parseAsync([
+      'node',
+      'deepl',
+      'auth',
+      'set-key',
+      'test-key-123',
+    ]);
 
     const { Logger } = await import('../../src/utils/logger');
     expect(Logger.warn).toHaveBeenCalledWith(
-      expect.stringContaining('deprecated'),
+      expect.stringContaining('deprecated')
     );
   });
 
   it('should thread getHttpOptions into the key-validation client', async () => {
     const mockConfigService = createMockConfigService();
-    const mockGetUsage = jest.fn().mockResolvedValue({ character: { count: 0, limit: 500000 } });
-    (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
-      getUsage: mockGetUsage,
-    } as any));
+    const mockGetUsage = jest
+      .fn()
+      .mockResolvedValue({ character: { count: 0, limit: 500000 } });
+    (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(
+      () =>
+        ({
+          getUsage: mockGetUsage,
+        }) as any
+    );
 
     const program = new Command();
     program.exitOverride();
     registerAuth(program, {
       getConfigService: () => mockConfigService,
       getHttpOptions: () => ({ timeout: 55, maxRetries: 1 }),
-      handleError: (error: unknown) => { throw error; },
+      handleError: (error: unknown) => {
+        throw error;
+      },
     });
 
-    await program.parseAsync(['node', 'deepl', 'auth', 'set-key', 'test-key-123']);
+    await program.parseAsync([
+      'node',
+      'deepl',
+      'auth',
+      'set-key',
+      'test-key-123',
+    ]);
 
     expect(DeepLClient).toHaveBeenCalledWith(
       'test-key-123',
diff --git a/tests/unit/cache-backcompat.test.ts b/tests/unit/cache-backcompat.test.ts
index 788fe813..1ea11088 100644
--- a/tests/unit/cache-backcompat.test.ts
+++ b/tests/unit/cache-backcompat.test.ts
@@ -14,7 +14,12 @@ import * as path from 'path';
 import * as os from 'os';
 import { CacheService } from '../../src/storage/cache';
 
-const FIXTURE = path.join(__dirname, '..', 'fixtures', 'cache-better-sqlite3.db');
+const FIXTURE = path.join(
+  __dirname,
+  '..',
+  'fixtures',
+  'cache-better-sqlite3.db'
+);
 
 describe('CacheService better-sqlite3 back-compat', () => {
   let testCacheDir: string;
@@ -22,7 +27,9 @@ describe('CacheService better-sqlite3 back-compat', () => {
   let cache: CacheService | undefined;
 
   beforeEach(() => {
-    testCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-cli-backcompat-'));
+    testCacheDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'deepl-cli-backcompat-')
+    );
     testCachePath = path.join(testCacheDir, 'cache.db');
     fs.copyFileSync(FIXTURE, testCachePath);
   });
@@ -42,7 +49,9 @@ describe('CacheService better-sqlite3 back-compat', () => {
   it('opens the database without treating it as corrupt', () => {
     openFixture();
 
-    const corruptBackups = fs.readdirSync(testCacheDir).filter((f) => f.includes('.corrupt-'));
+    const corruptBackups = fs
+      .readdirSync(testCacheDir)
+      .filter((f) => f.includes('.corrupt-'));
     expect(corruptBackups).toEqual([]);
   });
 
@@ -57,7 +66,9 @@ describe('CacheService better-sqlite3 back-compat', () => {
       text: 'Welt',
       detectedSourceLang: 'en',
     });
-    expect(service.get('write:v1:improve')).toEqual({ text: 'An improved sentence.' });
+    expect(service.get('write:v1:improve')).toEqual({
+      text: 'An improved sentence.',
+    });
   });
 
   it('reports accurate stats for the pre-existing entries', () => {
diff --git a/tests/unit/cache-command.test.ts b/tests/unit/cache-command.test.ts
index dcc9398d..b39e9ce5 100644
--- a/tests/unit/cache-command.test.ts
+++ b/tests/unit/cache-command.test.ts
@@ -5,7 +5,10 @@
 import { CacheCommand } from '../../src/cli/commands/cache';
 import { CacheService } from '../../src/storage/cache';
 import { ConfigService } from '../../src/storage/config';
-import { createMockCacheService, createMockConfigService } from '../helpers/mock-factories';
+import {
+  createMockCacheService,
+  createMockConfigService,
+} from '../helpers/mock-factories';
 
 // Mock CacheService
 jest.mock('../../src/storage/cache');
@@ -122,7 +125,10 @@ describe('CacheCommand', () => {
       const maxSize = 1024 * 1024 * 500; // 500MB
       await cacheCommand.enable(maxSize);
 
-      expect(mockConfigService.set).toHaveBeenCalledWith('cache.maxSize', maxSize);
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'cache.maxSize',
+        maxSize
+      );
       expect(mockCacheService.setMaxSize).toHaveBeenCalledWith(maxSize);
       expect(mockCacheService.enable).toHaveBeenCalledTimes(1);
     });
@@ -132,7 +138,10 @@ describe('CacheCommand', () => {
 
       await cacheCommand.enable();
 
-      expect(mockConfigService.set).not.toHaveBeenCalledWith('cache.maxSize', expect.anything());
+      expect(mockConfigService.set).not.toHaveBeenCalledWith(
+        'cache.maxSize',
+        expect.anything()
+      );
       expect(mockCacheService.setMaxSize).not.toHaveBeenCalled();
       expect(mockCacheService.enable).toHaveBeenCalledTimes(1);
     });
@@ -169,7 +178,10 @@ describe('CacheCommand', () => {
 
       await cacheCommand.disable();
 
-      expect(mockConfigService.set).toHaveBeenCalledWith('cache.enabled', false);
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'cache.enabled',
+        false
+      );
     });
   });
 
@@ -257,8 +269,8 @@ describe('CacheCommand', () => {
   describe('formatStatsTable', () => {
     const stats = {
       entries: 142,
-      totalSize: 25 * 1024 * 1024,   // 25 MB
-      maxSize: 100 * 1024 * 1024,    // 100 MB
+      totalSize: 25 * 1024 * 1024, // 25 MB
+      maxSize: 100 * 1024 * 1024, // 100 MB
       enabled: true,
     };
 
@@ -279,12 +291,19 @@ describe('CacheCommand', () => {
     });
 
     it('should report disabled status', () => {
-      const result = cacheCommand.formatStatsTable({ ...stats, enabled: false });
+      const result = cacheCommand.formatStatsTable({
+        ...stats,
+        enabled: false,
+      });
       expect(result).toContain('disabled');
     });
 
     it('should report 0.0% usage when maxSize is zero', () => {
-      const result = cacheCommand.formatStatsTable({ ...stats, totalSize: 0, maxSize: 0 });
+      const result = cacheCommand.formatStatsTable({
+        ...stats,
+        totalSize: 0,
+        maxSize: 0,
+      });
       expect(result).toContain('0.0%');
     });
   });
diff --git a/tests/unit/cache-corruption-allowlist.test.ts b/tests/unit/cache-corruption-allowlist.test.ts
index 3b67eb15..9eddf906 100644
--- a/tests/unit/cache-corruption-allowlist.test.ts
+++ b/tests/unit/cache-corruption-allowlist.test.ts
@@ -57,7 +57,7 @@ describe('CacheService corruption allowlist', () => {
     const raw = new DatabaseSync(dbPath);
     raw.exec('PRAGMA journal_mode = DELETE');
     raw.exec(
-      'CREATE TABLE cache (key TEXT PRIMARY KEY, value TEXT NOT NULL, timestamp INTEGER NOT NULL, size INTEGER NOT NULL)',
+      'CREATE TABLE cache (key TEXT PRIMARY KEY, value TEXT NOT NULL, timestamp INTEGER NOT NULL, size INTEGER NOT NULL)'
     );
     raw.exec(`INSERT INTO cache VALUES ('k', '"v"', ${Date.now()}, 3)`);
     raw.exec('BEGIN EXCLUSIVE');
@@ -75,7 +75,10 @@ describe('CacheService corruption allowlist', () => {
   });
 
   it('still renames a genuinely corrupt file aside and recreates', () => {
-    fs.writeFileSync(dbPath, 'this is not a sqlite database, padded well past the 16-byte header');
+    fs.writeFileSync(
+      dbPath,
+      'this is not a sqlite database, padded well past the 16-byte header'
+    );
 
     const svc = new CacheService({ dbPath, ttl: 0 });
     svc.set('key', 'value');
@@ -90,7 +93,9 @@ describe('CacheService corruption allowlist', () => {
     // SQLITE_CORRUPT and, unlike a garbage header, leaves sidecars on disk
     // for the recovery path to preserve.
     const raw = new DatabaseSync(dbPath);
-    raw.exec('CREATE TABLE cache (key TEXT PRIMARY KEY, value TEXT, timestamp INTEGER, size INTEGER)');
+    raw.exec(
+      'CREATE TABLE cache (key TEXT PRIMARY KEY, value TEXT, timestamp INTEGER, size INTEGER)'
+    );
     raw.close();
     const buf = fs.readFileSync(dbPath);
     buf.fill(0xde, 100, 600);
@@ -112,13 +117,18 @@ describe('CacheService corruption allowlist', () => {
     for (const ts of [100, 200, 300]) {
       fs.writeFileSync(`${dbPath}.corrupt-${ts}`, 'old backup');
     }
-    fs.writeFileSync(dbPath, 'this is not a sqlite database, padded well past the 16-byte header');
+    fs.writeFileSync(
+      dbPath,
+      'this is not a sqlite database, padded well past the 16-byte header'
+    );
 
     const svc = new CacheService({ dbPath, ttl: 0 });
     svc.close();
 
     const backups = corruptBackups();
-    const timestamps = [...new Set(backups.map((f) => /\.corrupt-(\d+)/.exec(f)![1]))];
+    const timestamps = [
+      ...new Set(backups.map((f) => /\.corrupt-(\d+)/.exec(f)![1])),
+    ];
     expect(timestamps).toHaveLength(3);
     expect(timestamps).not.toContain('100');
   });
diff --git a/tests/unit/cache-loader.test.ts b/tests/unit/cache-loader.test.ts
index 0914dc33..04b4ffb6 100644
--- a/tests/unit/cache-loader.test.ts
+++ b/tests/unit/cache-loader.test.ts
@@ -14,7 +14,10 @@ jest.mock('../../src/utils/logger', () => ({
   },
 }));
 
-import { createCacheServiceGetter, resolveCacheOptions } from '../../src/cli/cache-loader';
+import {
+  createCacheServiceGetter,
+  resolveCacheOptions,
+} from '../../src/cli/cache-loader';
 import { Logger } from '../../src/utils/logger';
 import type { CacheService } from '../../src/storage/cache';
 import type { ConfigService } from '../../src/storage/config';
@@ -33,17 +36,33 @@ function makeError(message: string, code?: string): Error {
 
 describe('resolveCacheOptions', () => {
   it('carries cache.enabled through to the cache service', () => {
-    expect(resolveCacheOptions(fakeConfig({ 'cache.enabled': false }), '/tmp/cache.db').enabled).toBe(false);
-    expect(resolveCacheOptions(fakeConfig({ 'cache.enabled': true }), '/tmp/cache.db').enabled).toBe(true);
+    expect(
+      resolveCacheOptions(
+        fakeConfig({ 'cache.enabled': false }),
+        '/tmp/cache.db'
+      ).enabled
+    ).toBe(false);
+    expect(
+      resolveCacheOptions(
+        fakeConfig({ 'cache.enabled': true }),
+        '/tmp/cache.db'
+      ).enabled
+    ).toBe(true);
   });
 
   it('converts the configured TTL from seconds to milliseconds', () => {
-    const options = resolveCacheOptions(fakeConfig({ 'cache.ttl': 90 }), '/tmp/cache.db');
+    const options = resolveCacheOptions(
+      fakeConfig({ 'cache.ttl': 90 }),
+      '/tmp/cache.db'
+    );
     expect(options.ttl).toBe(90_000);
   });
 
   it('passes the db path and max size through unchanged', () => {
-    const options = resolveCacheOptions(fakeConfig({ 'cache.maxSize': 4096 }), '/tmp/cache.db');
+    const options = resolveCacheOptions(
+      fakeConfig({ 'cache.maxSize': 4096 }),
+      '/tmp/cache.db'
+    );
     expect(options.dbPath).toBe('/tmp/cache.db');
     expect(options.maxSize).toBe(4096);
   });
@@ -94,7 +113,7 @@ describe('createCacheServiceGetter', () => {
   describe('when the dynamic import rejects (e.g. ABI mismatch)', () => {
     const abiError = makeError(
       "The module '/x/better_sqlite3.node' was compiled against a different Node.js version using NODE_MODULE_VERSION 137.",
-      'ERR_DLOPEN_FAILED',
+      'ERR_DLOPEN_FAILED'
     );
 
     it('returns undefined instead of throwing', async () => {
diff --git a/tests/unit/cache-native-failure.test.ts b/tests/unit/cache-native-failure.test.ts
index 73555fc2..1a1ed854 100644
--- a/tests/unit/cache-native-failure.test.ts
+++ b/tests/unit/cache-native-failure.test.ts
@@ -50,7 +50,9 @@ describe('CacheService native-module load failure', () => {
 
   beforeEach(() => {
     jest.clearAllMocks();
-    testCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-cli-native-fail-'));
+    testCacheDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'deepl-cli-native-fail-')
+    );
     testCachePath = path.join(testCacheDir, 'cache.db');
     fs.writeFileSync(testCachePath, dbContent);
     fs.writeFileSync(testCachePath + '-wal', walContent);
@@ -70,16 +72,21 @@ describe('CacheService native-module load failure', () => {
       'ERR_DLOPEN_FAILED (ABI mismatch)',
       makeError(
         "The module '/x/better_sqlite3.node' was compiled against a different Node.js version using NODE_MODULE_VERSION 137. This version of Node.js requires NODE_MODULE_VERSION 127.",
-        'ERR_DLOPEN_FAILED',
+        'ERR_DLOPEN_FAILED'
       ),
     ],
     [
       'ERR_UNKNOWN_BUILTIN_MODULE (missing node:sqlite)',
-      makeError("No such built-in module: node:sqlite", 'ERR_UNKNOWN_BUILTIN_MODULE'),
+      makeError(
+        'No such built-in module: node:sqlite',
+        'ERR_UNKNOWN_BUILTIN_MODULE'
+      ),
     ],
     [
       'NODE_MODULE_VERSION message without a code',
-      makeError('was compiled against a different Node.js version using NODE_MODULE_VERSION 137'),
+      makeError(
+        'was compiled against a different Node.js version using NODE_MODULE_VERSION 137'
+      ),
     ],
     [
       'MODULE_NOT_FOUND (binding removed)',
@@ -89,7 +96,9 @@ describe('CacheService native-module load failure', () => {
     it('rethrows without renaming the database or its sidecars', () => {
       mockConstructorError = error;
 
-      expect(() => new CacheService({ dbPath: testCachePath })).toThrow(error.message);
+      expect(() => new CacheService({ dbPath: testCachePath })).toThrow(
+        error.message
+      );
 
       expect(fs.readFileSync(testCachePath, 'utf-8')).toBe(dbContent);
       expect(fs.readFileSync(testCachePath + '-wal', 'utf-8')).toBe(walContent);
@@ -103,23 +112,30 @@ describe('CacheService native-module load failure', () => {
       expect(() => new CacheService({ dbPath: testCachePath })).toThrow();
 
       expect(Logger.warn).not.toHaveBeenCalledWith(
-        expect.stringContaining('corrupted'),
+        expect.stringContaining('corrupted')
       );
     });
   });
 
   describe('genuine open failure (not a load failure)', () => {
     it('still renames the database aside', () => {
-      mockConstructorError = makeError('file is not a database', 'SQLITE_NOTADB');
+      mockConstructorError = makeError(
+        'file is not a database',
+        'SQLITE_NOTADB'
+      );
 
       // Recreation also fails (the mock always throws), so the constructor
       // rethrows — but the rename-aside must have happened first.
-      expect(() => new CacheService({ dbPath: testCachePath })).toThrow('file is not a database');
+      expect(() => new CacheService({ dbPath: testCachePath })).toThrow(
+        'file is not a database'
+      );
 
       expect(fs.existsSync(testCachePath)).toBe(false);
       const backups = listCorruptBackups();
       expect(backups.some((f) => f.startsWith('cache.db.corrupt-'))).toBe(true);
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('Cache database corrupted'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Cache database corrupted')
+      );
     });
   });
 });
diff --git a/tests/unit/cache-service.test.ts b/tests/unit/cache-service.test.ts
index ef28155c..130895e6 100644
--- a/tests/unit/cache-service.test.ts
+++ b/tests/unit/cache-service.test.ts
@@ -37,7 +37,10 @@ describe('CacheService', () => {
     }
 
     // Create cache service with test path
-    cacheService = new CacheService({ dbPath: testCachePath, maxSize: 1024 * 100 }); // 100KB for tests
+    cacheService = new CacheService({
+      dbPath: testCachePath,
+      maxSize: 1024 * 100,
+    }); // 100KB for tests
   });
 
   afterEach(() => {
@@ -78,7 +81,9 @@ describe('CacheService', () => {
 
     it('should stamp the current schema version on a fresh database', () => {
       const db = (cacheService as any).db;
-      const result = db.prepare('PRAGMA user_version').get() as { user_version: number };
+      const result = db.prepare('PRAGMA user_version').get() as {
+        user_version: number;
+      };
       expect(result.user_version).toBe(2);
     });
 
@@ -95,8 +100,11 @@ describe('CacheService', () => {
       try {
         const reopenedDb = (reopened as any).db;
         expect(
-          (reopenedDb.prepare('PRAGMA user_version').get() as { user_version: number })
-            .user_version,
+          (
+            reopenedDb.prepare('PRAGMA user_version').get() as {
+              user_version: number;
+            }
+          ).user_version
         ).toBe(2);
         expect(reopened.get('preexisting')).toEqual({ text: 'survives' });
       } finally {
@@ -118,7 +126,9 @@ describe('CacheService', () => {
       const reopened = new CacheService({ dbPath: testCachePath });
       try {
         expect(reopened.get('translation:oldhash')).toBeNull();
-        expect(reopened.get('write:samehash')).toEqual({ text: 'still reachable' });
+        expect(reopened.get('write:samehash')).toEqual({
+          text: 'still reachable',
+        });
       } finally {
         reopened.close();
       }
@@ -138,7 +148,9 @@ describe('CacheService', () => {
         // The corrupted original was renamed, not deleted.
         const backups = fs
           .readdirSync(testCacheDir)
-          .filter((f) => f.startsWith(path.basename(testCachePath) + '.corrupt-'));
+          .filter((f) =>
+            f.startsWith(path.basename(testCachePath) + '.corrupt-')
+          );
         expect(backups.length).toBeGreaterThan(0);
       } finally {
         svc.close();
@@ -168,7 +180,10 @@ describe('CacheService', () => {
     it('should handle expired entries', () => {
       jest.useFakeTimers();
       const shortTTL = 100; // 100ms
-      const service = new CacheService({ dbPath: testCachePath, ttl: shortTTL });
+      const service = new CacheService({
+        dbPath: testCachePath,
+        ttl: shortTTL,
+      });
 
       service.set('test-key', { text: 'Hello' });
 
@@ -213,7 +228,9 @@ describe('CacheService', () => {
       cacheService.get('test-key', isMyType);
 
       expect(Logger.warn).toHaveBeenCalledTimes(1);
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('type mismatch'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('type mismatch')
+      );
     });
 
     it('should work without guard (backward compatible)', () => {
@@ -323,7 +340,10 @@ describe('CacheService', () => {
     });
 
     it('should start disabled when constructed with enabled: false', () => {
-      const disabled = new CacheService({ dbPath: path.join(testCacheDir, 'disabled.db'), enabled: false });
+      const disabled = new CacheService({
+        dbPath: path.join(testCacheDir, 'disabled.db'),
+        enabled: false,
+      });
       try {
         expect(disabled.stats().enabled).toBe(false);
       } finally {
@@ -332,7 +352,10 @@ describe('CacheService', () => {
     });
 
     it('should not read or write entries when constructed disabled', () => {
-      const disabled = new CacheService({ dbPath: path.join(testCacheDir, 'disabled-io.db'), enabled: false });
+      const disabled = new CacheService({
+        dbPath: path.join(testCacheDir, 'disabled-io.db'),
+        enabled: false,
+      });
       try {
         disabled.set('test', { text: 'Hello' });
         expect(disabled.get('test')).toBeNull();
@@ -343,7 +366,10 @@ describe('CacheService', () => {
     });
 
     it('should allow enable() to override a disabled start', () => {
-      const disabled = new CacheService({ dbPath: path.join(testCacheDir, 'reenable.db'), enabled: false });
+      const disabled = new CacheService({
+        dbPath: path.join(testCacheDir, 'reenable.db'),
+        enabled: false,
+      });
       try {
         disabled.enable();
         disabled.set('test', { text: 'Hello' });
@@ -563,7 +589,9 @@ describe('CacheService', () => {
     it('should handle concurrent operations', async () => {
       const promises = [];
       for (let i = 0; i < 10; i++) {
-        promises.push(Promise.resolve(cacheService.set(`concurrent-${i}`, { value: i })));
+        promises.push(
+          Promise.resolve(cacheService.set(`concurrent-${i}`, { value: i }))
+        );
       }
 
       await Promise.all(promises);
@@ -574,14 +602,17 @@ describe('CacheService', () => {
 
     it('should truncate cache key in corruption warning to first 8 characters', () => {
       // Use a long SHA-256-like key (64 hex characters)
-      const longKey = 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2';
+      const longKey =
+        'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2';
 
       const db = (cacheService as any).db;
       const timestamp = Date.now();
-      db.prepare(`
+      db.prepare(
+        `
         INSERT INTO cache (key, value, timestamp, size)
         VALUES (?, ?, ?, ?)
-      `).run(longKey, 'not-valid-json{{{', timestamp, 18);
+      `
+      ).run(longKey, 'not-valid-json{{{', timestamp, 18);
 
       const value = cacheService.get(longKey);
       expect(value).toBeNull();
@@ -599,10 +630,12 @@ describe('CacheService', () => {
 
       const db = (cacheService as any).db;
       const timestamp = Date.now();
-      db.prepare(`
+      db.prepare(
+        `
         INSERT INTO cache (key, value, timestamp, size)
         VALUES (?, ?, ?, ?)
-      `).run(shortKey, 'bad-json!!!', timestamp, 11);
+      `
+      ).run(shortKey, 'bad-json!!!', timestamp, 11);
 
       cacheService.get(shortKey);
 
@@ -616,10 +649,12 @@ describe('CacheService', () => {
     it('should log warning when cache corruption is detected (Issue #11)', () => {
       const db = (cacheService as any).db;
       const timestamp = Date.now();
-      db.prepare(`
+      db.prepare(
+        `
         INSERT INTO cache (key, value, timestamp, size)
         VALUES (?, ?, ?, ?)
-      `).run('corrupted-key', 'invalid-json-{', timestamp, 15);
+      `
+      ).run('corrupted-key', 'invalid-json-{', timestamp, 15);
 
       // Attempt to retrieve the corrupted entry
       const value = cacheService.get('corrupted-key');
@@ -861,7 +896,9 @@ describe('CacheService', () => {
       recovered.set('key', { text: 'Hello' });
       expect(recovered.get('key')).toEqual({ text: 'Hello' });
 
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('Cache database corrupted'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Cache database corrupted')
+      );
 
       recovered.close();
     });
@@ -878,10 +915,14 @@ describe('CacheService', () => {
 
       // Old corrupt WAL/SHM content should be gone (SQLite may recreate fresh ones)
       if (fs.existsSync(testCachePath + '-wal')) {
-        expect(fs.readFileSync(testCachePath + '-wal', 'utf8')).not.toBe('OLD WAL GARBAGE DATA');
+        expect(fs.readFileSync(testCachePath + '-wal', 'utf8')).not.toBe(
+          'OLD WAL GARBAGE DATA'
+        );
       }
       if (fs.existsSync(testCachePath + '-shm')) {
-        expect(fs.readFileSync(testCachePath + '-shm', 'utf8')).not.toBe('OLD SHM GARBAGE DATA');
+        expect(fs.readFileSync(testCachePath + '-shm', 'utf8')).not.toBe(
+          'OLD SHM GARBAGE DATA'
+        );
       }
 
       // DB should be functional
@@ -898,7 +939,10 @@ describe('CacheService', () => {
       fs.writeFileSync(testCachePath, 'CORRUPT');
 
       // Make the directory read-only so recreation fails
-      const readOnlyDir = path.join(os.tmpdir(), `deepl-cli-readonly-${Date.now()}`);
+      const readOnlyDir = path.join(
+        os.tmpdir(),
+        `deepl-cli-readonly-${Date.now()}`
+      );
       fs.mkdirSync(readOnlyDir, { recursive: true });
       const readOnlyPath = path.join(readOnlyDir, 'subdir', 'cache.db');
 
diff --git a/tests/unit/cli-did-you-mean.test.ts b/tests/unit/cli-did-you-mean.test.ts
index 3c719a5a..bdb2d6ac 100644
--- a/tests/unit/cli-did-you-mean.test.ts
+++ b/tests/unit/cli-did-you-mean.test.ts
@@ -11,7 +11,11 @@ describe('CLI did-you-mean suggestions', () => {
   // the 10s execSync timeout under full-suite parallelism.
   const cliPath = path.resolve(__dirname, '../../dist/cli/index.js');
 
-  function runCLI(args: string): { stdout: string; stderr: string; exitCode: number } {
+  function runCLI(args: string): {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  } {
     try {
       const stdout = execSync(`node "${cliPath}" ${args}`, {
         encoding: 'utf-8',
@@ -70,9 +74,12 @@ describe('CLI did-you-mean suggestions', () => {
     expect(combined).toContain('Did you mean: deepl translate?');
   });
 
-  it.each(['descibe', 'describe'])('should never suggest the hidden _describe command (%s)', (typo) => {
-    const result = runCLI(typo);
-    const combined = result.stdout + result.stderr;
-    expect(combined).not.toContain('_describe');
-  });
+  it.each(['descibe', 'describe'])(
+    'should never suggest the hidden _describe command (%s)',
+    (typo) => {
+      const result = runCLI(typo);
+      const combined = result.stdout + result.stderr;
+      expect(combined).not.toContain('_describe');
+    }
+  );
 });
diff --git a/tests/unit/cli-no-args-exit.test.ts b/tests/unit/cli-no-args-exit.test.ts
index e0555c88..6883cdef 100644
--- a/tests/unit/cli-no-args-exit.test.ts
+++ b/tests/unit/cli-no-args-exit.test.ts
@@ -22,7 +22,9 @@ describe('CLI no-args exit code', () => {
       });
       expect(output).toContain('deepl');
     } catch (error: any) {
-      fail(`CLI exited with code ${error.status as number}, expected 0. stderr: ${error.stderr as string}`);
+      fail(
+        `CLI exited with code ${error.status as number}, expected 0. stderr: ${error.stderr as string}`
+      );
     }
   });
 
diff --git a/tests/unit/cli-translate-workflow.test.ts b/tests/unit/cli-translate-workflow.test.ts
index ddce0e22..d26039dc 100644
--- a/tests/unit/cli-translate-workflow.test.ts
+++ b/tests/unit/cli-translate-workflow.test.ts
@@ -11,7 +11,11 @@ import { FileTranslationService } from '../../src/services/file-translation.js';
 import { DeepLClient, LanguageInfo } from '../../src/api/deepl-client.js';
 import { ConfigService } from '../../src/storage/config.js';
 import { CacheService } from '../../src/storage/cache.js';
-import { TEST_API_KEY, createMockConfigService, createMockCacheService } from '../helpers';
+import {
+  TEST_API_KEY,
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers';
 
 describe('Translation Workflow Integration', () => {
   const API_KEY = TEST_API_KEY;
@@ -32,13 +36,19 @@ describe('Translation Workflow Integration', () => {
       get: jest.fn(() => ({
         auth: {},
         api: { baseUrl: '', usePro: false },
-        defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: false,
+        },
         cache: { enabled: true },
         output: { format: 'text', color: true },
         proxy: {},
       })),
       getValue: jest.fn((key: string) => {
-        if (key === 'cache.enabled') {return true;}
+        if (key === 'cache.enabled') {
+          return true;
+        }
         return undefined;
       }),
     });
@@ -76,7 +86,9 @@ describe('Translation Workflow Integration', () => {
         detectedSourceLang: 'en',
       });
 
-      const result = await translationService.translate('Hello', { targetLang: 'es' });
+      const result = await translationService.translate('Hello', {
+        targetLang: 'es',
+      });
 
       expect(result.text).toBe('Hola');
       expect(result.detectedSourceLang).toBe('en');
@@ -100,7 +112,11 @@ describe('Translation Workflow Integration', () => {
         getValue: jest.fn(() => true),
       });
 
-      translationService = new TranslationService(client, mockConfig, mockCache);
+      translationService = new TranslationService(
+        client,
+        mockConfig,
+        mockCache
+      );
 
       const translateSpy = jest.spyOn(client, 'translate').mockResolvedValue({
         text: 'Hola',
@@ -172,10 +188,9 @@ describe('Translation Workflow Integration', () => {
         text: 'Hello __VAR_0__',
       });
 
-      const result = await translationService.translate(
-        'Hello ${name}',
-        { targetLang: 'es' }
-      );
+      const result = await translationService.translate('Hello ${name}', {
+        targetLang: 'es',
+      });
 
       expect(result.text).toContain('${name}');
     });
@@ -185,10 +200,9 @@ describe('Translation Workflow Integration', () => {
         text: 'Hello __VAR_0__',
       });
 
-      const result = await translationService.translate(
-        'Hello {name}',
-        { targetLang: 'es' }
-      );
+      const result = await translationService.translate('Hello {name}', {
+        targetLang: 'es',
+      });
 
       expect(result.text).toContain('{name}');
     });
@@ -251,7 +265,9 @@ describe('Translation Workflow Integration', () => {
 
       const translateSpy = jest.spyOn(client, 'translate');
 
-      const result = await translationService.translate('Hello', { targetLang: 'es' });
+      const result = await translationService.translate('Hello', {
+        targetLang: 'es',
+      });
 
       expect(result.text).toBe('Hola (cached)');
       expect(translateSpy).not.toHaveBeenCalled(); // API not called
@@ -272,12 +288,18 @@ describe('Translation Workflow Integration', () => {
       mockConfig = {
         get: () => ({ defaults: {} }),
         getValue: (key: string) => {
-          if (key === 'cache.enabled') {return false;}
+          if (key === 'cache.enabled') {
+            return false;
+          }
           return undefined;
         },
       } as ConfigService;
 
-      translationService = new TranslationService(client, mockConfig, mockCache);
+      translationService = new TranslationService(
+        client,
+        mockConfig,
+        mockCache
+      );
 
       jest.spyOn(client, 'translate').mockResolvedValue({
         text: 'Hola',
@@ -307,15 +329,17 @@ describe('Translation Workflow Integration', () => {
 
   describe('TranslationService - Multi-Target Translation', () => {
     it('should translate to multiple languages in parallel', async () => {
-      jest.spyOn(client, 'translate')
+      jest
+        .spyOn(client, 'translate')
         .mockResolvedValueOnce({ text: 'Hola' })
         .mockResolvedValueOnce({ text: 'Bonjour' })
         .mockResolvedValueOnce({ text: 'Hallo' });
 
-      const results = await translationService.translateToMultiple(
-        'Hello',
-        ['es', 'fr', 'de']
-      );
+      const results = await translationService.translateToMultiple('Hello', [
+        'es',
+        'fr',
+        'de',
+      ]);
 
       expect(results).toHaveLength(3);
       expect(results[0]).toEqual({ targetLang: 'es', text: 'Hola' });
@@ -330,16 +354,16 @@ describe('Translation Workflow Integration', () => {
     });
 
     it('should pass skipCache option to underlying translate calls', async () => {
-      const translateSpy = jest.spyOn(translationService, 'translate').mockResolvedValue({
-        text: 'Hola',
+      const translateSpy = jest
+        .spyOn(translationService, 'translate')
+        .mockResolvedValue({
+          text: 'Hola',
+        });
+
+      await translationService.translateToMultiple('Hello', ['es'], {
+        skipCache: true,
       });
 
-      await translationService.translateToMultiple(
-        'Hello',
-        ['es'],
-        { skipCache: true }
-      );
-
       expect(translateSpy).toHaveBeenCalledWith(
         'Hello',
         expect.objectContaining({ targetLang: 'es' }),
@@ -350,10 +374,9 @@ describe('Translation Workflow Integration', () => {
 
   describe('TranslationService - Batch Translation', () => {
     it('should translate multiple texts in batch', async () => {
-      jest.spyOn(client, 'translateBatch').mockResolvedValue([
-        { text: 'Hola' },
-        { text: 'Adiós' },
-      ]);
+      jest
+        .spyOn(client, 'translateBatch')
+        .mockResolvedValue([{ text: 'Hola' }, { text: 'Adiós' }]);
 
       const results = await translationService.translateBatch(
         ['Hello', 'Goodbye'],
@@ -366,7 +389,9 @@ describe('Translation Workflow Integration', () => {
     });
 
     it('should return empty array for empty input', async () => {
-      const results = await translationService.translateBatch([], { targetLang: 'es' });
+      const results = await translationService.translateBatch([], {
+        targetLang: 'es',
+      });
       expect(results).toEqual([]);
     });
 
@@ -375,9 +400,9 @@ describe('Translation Workflow Integration', () => {
         .mockReturnValueOnce({ text: 'Hola (cached)' })
         .mockReturnValueOnce(null);
 
-      jest.spyOn(client, 'translateBatch').mockResolvedValue([
-        { text: 'Adiós' },
-      ]);
+      jest
+        .spyOn(client, 'translateBatch')
+        .mockResolvedValue([{ text: 'Adiós' }]);
 
       const results = await translationService.translateBatch(
         ['Hello', 'Goodbye'],
@@ -396,21 +421,21 @@ describe('Translation Workflow Integration', () => {
     });
 
     it('should cache newly translated results', async () => {
-      jest.spyOn(client, 'translateBatch').mockResolvedValue([
-        { text: 'Hola' },
-        { text: 'Adiós' },
-      ]);
+      jest
+        .spyOn(client, 'translateBatch')
+        .mockResolvedValue([{ text: 'Hola' }, { text: 'Adiós' }]);
 
-      await translationService.translateBatch(
-        ['Hello', 'Goodbye'],
-        { targetLang: 'es' }
-      );
+      await translationService.translateBatch(['Hello', 'Goodbye'], {
+        targetLang: 'es',
+      });
 
       expect(mockCache.set).toHaveBeenCalledTimes(2);
     });
 
     it('should handle batch API errors gracefully', async () => {
-      jest.spyOn(client, 'translateBatch').mockRejectedValue(new Error('API error'));
+      jest
+        .spyOn(client, 'translateBatch')
+        .mockRejectedValue(new Error('API error'));
 
       await expect(
         translationService.translateBatch(['Hello'], { targetLang: 'es' })
@@ -421,11 +446,18 @@ describe('Translation Workflow Integration', () => {
       // Create 60 unique texts to avoid cache key collisions
       const texts = Array.from({ length: 60 }, (_, i) => `Hello ${i}`);
 
-      jest.spyOn(client, 'translateBatch')
-        .mockResolvedValueOnce(Array.from({ length: 50 }, (_, i) => ({ text: `Hola ${i}` })))
-        .mockResolvedValueOnce(Array.from({ length: 10 }, (_, i) => ({ text: `Hola ${i + 50}` })));
+      jest
+        .spyOn(client, 'translateBatch')
+        .mockResolvedValueOnce(
+          Array.from({ length: 50 }, (_, i) => ({ text: `Hola ${i}` }))
+        )
+        .mockResolvedValueOnce(
+          Array.from({ length: 10 }, (_, i) => ({ text: `Hola ${i + 50}` }))
+        );
 
-      const results = await translationService.translateBatch(texts, { targetLang: 'es' });
+      const results = await translationService.translateBatch(texts, {
+        targetLang: 'es',
+      });
 
       expect(results).toHaveLength(60);
       expect(client.translateBatch).toHaveBeenCalledTimes(2);
@@ -453,9 +485,12 @@ describe('Translation Workflow Integration', () => {
         { language: 'de', name: 'German' },
       ];
 
-      jest.spyOn(client, 'getSupportedLanguages').mockResolvedValue(mockLanguages);
+      jest
+        .spyOn(client, 'getSupportedLanguages')
+        .mockResolvedValue(mockLanguages);
 
-      const languages = await translationService.getSupportedLanguages('source');
+      const languages =
+        await translationService.getSupportedLanguages('source');
 
       expect(languages).toEqual(mockLanguages);
     });
@@ -466,17 +501,24 @@ describe('Translation Workflow Integration', () => {
         { language: 'fr', name: 'French' },
       ];
 
-      jest.spyOn(client, 'getSupportedLanguages').mockResolvedValue(mockLanguages);
+      jest
+        .spyOn(client, 'getSupportedLanguages')
+        .mockResolvedValue(mockLanguages);
 
-      const languages = await translationService.getSupportedLanguages('target');
+      const languages =
+        await translationService.getSupportedLanguages('target');
 
       expect(languages).toEqual(mockLanguages);
     });
 
     it('should cache language results for 24 hours', async () => {
-      const mockLanguages: LanguageInfo[] = [{ language: 'en', name: 'English' }];
+      const mockLanguages: LanguageInfo[] = [
+        { language: 'en', name: 'English' },
+      ];
 
-      const getSpy = jest.spyOn(client, 'getSupportedLanguages').mockResolvedValue(mockLanguages);
+      const getSpy = jest
+        .spyOn(client, 'getSupportedLanguages')
+        .mockResolvedValue(mockLanguages);
 
       // First call
       await translationService.getSupportedLanguages('source');
@@ -499,11 +541,9 @@ describe('Translation Workflow Integration', () => {
         text: 'Hola mundo',
       });
 
-      await fileTranslationService.translateFile(
-        inputPath,
-        outputPath,
-        { targetLang: 'es' }
-      );
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       expect(fs.existsSync(outputPath)).toBe(true);
       const output = fs.readFileSync(outputPath, 'utf-8');
@@ -520,11 +560,9 @@ describe('Translation Workflow Integration', () => {
         text: '# Hola\n\nMundo',
       });
 
-      await fileTranslationService.translateFile(
-        inputPath,
-        outputPath,
-        { targetLang: 'es' }
-      );
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       expect(fs.existsSync(outputPath)).toBe(true);
     });
@@ -539,11 +577,9 @@ describe('Translation Workflow Integration', () => {
         text: 'Hola',
       });
 
-      await fileTranslationService.translateFile(
-        inputPath,
-        outputPath,
-        { targetLang: 'es' }
-      );
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       expect(fs.existsSync(outputPath)).toBe(true);
     });
@@ -563,11 +599,9 @@ describe('Translation Workflow Integration', () => {
       fs.writeFileSync(inputPath, Buffer.from([0x89, 0x50, 0x4e, 0x47]));
 
       await expect(
-        fileTranslationService.translateFile(
-          inputPath,
-          '/tmp/output.txt',
-          { targetLang: 'es' }
-        )
+        fileTranslationService.translateFile(inputPath, '/tmp/output.txt', {
+          targetLang: 'es',
+        })
       ).rejects.toThrow('Unsupported file type');
     });
 
@@ -576,11 +610,9 @@ describe('Translation Workflow Integration', () => {
       fs.writeFileSync(inputPath, '');
 
       await expect(
-        fileTranslationService.translateFile(
-          inputPath,
-          '/tmp/output.txt',
-          { targetLang: 'es' }
-        )
+        fileTranslationService.translateFile(inputPath, '/tmp/output.txt', {
+          targetLang: 'es',
+        })
       ).rejects.toThrow('Cannot translate empty file');
     });
 
@@ -590,9 +622,11 @@ describe('Translation Workflow Integration', () => {
 
       fs.writeFileSync(inputPath, 'Use `console.log()`');
 
-      const translateSpy = jest.spyOn(translationService, 'translate').mockResolvedValue({
-        text: 'Use `console.log()`',
-      });
+      const translateSpy = jest
+        .spyOn(translationService, 'translate')
+        .mockResolvedValue({
+          text: 'Use `console.log()`',
+        });
 
       await fileTranslationService.translateFile(
         inputPath,
@@ -678,10 +712,7 @@ describe('Translation Workflow Integration', () => {
       fs.writeFileSync(inputPath, Buffer.from([0x89, 0x50]));
 
       await expect(
-        fileTranslationService.translateFileToMultiple(
-          inputPath,
-          ['es']
-        )
+        fileTranslationService.translateFileToMultiple(inputPath, ['es'])
       ).rejects.toThrow('Unsupported file type');
     });
 
@@ -690,10 +721,7 @@ describe('Translation Workflow Integration', () => {
       fs.writeFileSync(inputPath, '');
 
       await expect(
-        fileTranslationService.translateFileToMultiple(
-          inputPath,
-          ['es']
-        )
+        fileTranslationService.translateFileToMultiple(inputPath, ['es'])
       ).rejects.toThrow('Cannot translate empty file');
     });
   });
diff --git a/tests/unit/cli.test.ts b/tests/unit/cli.test.ts
index f5982fc3..0bf94ad3 100644
--- a/tests/unit/cli.test.ts
+++ b/tests/unit/cli.test.ts
@@ -30,7 +30,9 @@ describe('CLI Entry Point', () => {
     program = new Command();
     program
       .name('deepl')
-      .description('DeepL CLI - Next-generation translation tool powered by DeepL API')
+      .description(
+        'DeepL CLI - Next-generation translation tool powered by DeepL API'
+      )
       .version('0.1.0');
 
     // Register commands (simulating the actual CLI structure)
@@ -58,13 +60,16 @@ describe('CLI Entry Point', () => {
 
   describe('output.color config', () => {
     let testConfigDir: string;
-     
+
     let chalk: { level: number };
 
     beforeEach(() => {
       chalk = jest.requireMock<{ default: { level: number } }>('chalk').default;
       chalk.level = 3;
-      testConfigDir = path.join(os.tmpdir(), `.deepl-cli-test-color-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      testConfigDir = path.join(
+        os.tmpdir(),
+        `.deepl-cli-test-color-${Date.now()}-${Math.random().toString(36).slice(2)}`
+      );
       fs.mkdirSync(testConfigDir, { recursive: true });
     });
 
@@ -76,15 +81,25 @@ describe('CLI Entry Point', () => {
 
     it('should set chalk.level to 0 when output.color is false', () => {
       const configPath = path.join(testConfigDir, 'config.json');
-      fs.writeFileSync(configPath, JSON.stringify({
-        auth: {},
-        api: { baseUrl: 'https://api.deepl.com', usePro: true },
-        defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
-        cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
-        output: { format: 'text', verbose: false, color: false },
-        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
-
-      }, null, 2));
+      fs.writeFileSync(
+        configPath,
+        JSON.stringify(
+          {
+            auth: {},
+            api: { baseUrl: 'https://api.deepl.com', usePro: true },
+            defaults: {
+              targetLangs: [],
+              formality: 'default',
+              preserveFormatting: true,
+            },
+            cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
+            output: { format: 'text', verbose: false, color: false },
+            watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+          },
+          null,
+          2
+        )
+      );
 
       const configService = new ConfigService(configPath);
       const colorEnabled = configService.getValue<boolean>('output.color');
@@ -101,15 +116,25 @@ describe('CLI Entry Point', () => {
 
     it('should not change chalk.level when output.color is true', () => {
       const configPath = path.join(testConfigDir, 'config.json');
-      fs.writeFileSync(configPath, JSON.stringify({
-        auth: {},
-        api: { baseUrl: 'https://api.deepl.com', usePro: true },
-        defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
-        cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
-        output: { format: 'text', verbose: false, color: true },
-        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
-
-      }, null, 2));
+      fs.writeFileSync(
+        configPath,
+        JSON.stringify(
+          {
+            auth: {},
+            api: { baseUrl: 'https://api.deepl.com', usePro: true },
+            defaults: {
+              targetLangs: [],
+              formality: 'default',
+              preserveFormatting: true,
+            },
+            cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
+            output: { format: 'text', verbose: false, color: true },
+            watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+          },
+          null,
+          2
+        )
+      );
 
       const configService = new ConfigService(configPath);
       const colorEnabled = configService.getValue<boolean>('output.color');
diff --git a/tests/unit/cli/node-version-check.test.ts b/tests/unit/cli/node-version-check.test.ts
index b497ea11..6b59f407 100644
--- a/tests/unit/cli/node-version-check.test.ts
+++ b/tests/unit/cli/node-version-check.test.ts
@@ -34,7 +34,9 @@ describe('node-version-check', () => {
       const exitSpy = jest
         .spyOn(process, 'exit')
         .mockImplementation((() => undefined) as never);
-      const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+      const errorSpy = jest
+        .spyOn(console, 'error')
+        .mockImplementation(() => undefined);
 
       assertSupportedNodeVersion('22.0.0');
 
diff --git a/tests/unit/cli/register-sync-audit-lazy.test.ts b/tests/unit/cli/register-sync-audit-lazy.test.ts
index a353bc31..cf2524a4 100644
--- a/tests/unit/cli/register-sync-audit-lazy.test.ts
+++ b/tests/unit/cli/register-sync-audit-lazy.test.ts
@@ -13,9 +13,8 @@ import { Command } from 'commander';
 
 describe('registerSyncAudit lazy loading', () => {
   it('does not load sync-bucket-walker at registration time', async () => {
-    const { registerSyncAudit } = await import(
-      '../../../src/cli/commands/sync/register-sync-audit'
-    );
+    const { registerSyncAudit } =
+      await import('../../../src/cli/commands/sync/register-sync-audit');
 
     const program = new Command();
     registerSyncAudit(program, { handleError: jest.fn() as never });
diff --git a/tests/unit/cli/register-sync-force-help.test.ts b/tests/unit/cli/register-sync-force-help.test.ts
index a713e22b..70041e0e 100644
--- a/tests/unit/cli/register-sync-force-help.test.ts
+++ b/tests/unit/cli/register-sync-force-help.test.ts
@@ -28,8 +28,11 @@ function getForceOption() {
   registerSync(program, makeDeps());
   const sync = program.commands.find((c) => c.name() === 'sync');
   if (!sync) throw new Error('sync command not registered');
-  const opts = (sync as unknown as { options: Array<{ flags: string; description: string }> })
-    .options;
+  const opts = (
+    sync as unknown as {
+      options: Array<{ flags: string; description: string }>;
+    }
+  ).options;
   const opt = opts.find((o) => o.flags === '--force');
   if (!opt) throw new Error('--force option not found');
   return opt;
diff --git a/tests/unit/cli/register-sync-init.test.ts b/tests/unit/cli/register-sync-init.test.ts
index 6e827d5e..a0df8c4c 100644
--- a/tests/unit/cli/register-sync-init.test.ts
+++ b/tests/unit/cli/register-sync-init.test.ts
@@ -69,12 +69,16 @@ describe('deepl sync init flag vocabulary', () => {
     const deps = makeDeps(handleError);
     await runSyncInit(
       [
-        '--source-locale', 'en',
-        '--target-locales', 'de,fr',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de,fr',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ],
-      deps,
+      deps
     );
     expect(handleError).not.toHaveBeenCalled();
     expect(fs.existsSync(path.join(tmpDir, '.deepl-sync.yaml'))).toBe(true);
@@ -84,36 +88,51 @@ describe('deepl sync init flag vocabulary', () => {
   it.each([
     ['--source-lang', 'en'],
     ['--target-langs', 'de,fr'],
-  ])('rejects the removed %s alias as an unknown option', async (flag, value) => {
-    const deps = makeDeps(handleError);
-    await expect(
-      runSyncInit(
-        [
-          '--source-locale', 'en',
-          '--target-locales', 'de,fr',
-          '--file-format', 'json',
-          '--path', 'locales/en.json',
-          flag, value,
-        ],
-        deps,
-      ),
-    ).rejects.toThrow(new RegExp(`unknown option '${flag}'`));
-    expect(fs.existsSync(path.join(tmpDir, '.deepl-sync.yaml'))).toBe(false);
-  });
+  ])(
+    'rejects the removed %s alias as an unknown option',
+    async (flag, value) => {
+      const deps = makeDeps(handleError);
+      await expect(
+        runSyncInit(
+          [
+            '--source-locale',
+            'en',
+            '--target-locales',
+            'de,fr',
+            '--file-format',
+            'json',
+            '--path',
+            'locales/en.json',
+            flag,
+            value,
+          ],
+          deps
+        )
+      ).rejects.toThrow(new RegExp(`unknown option '${flag}'`));
+      expect(fs.existsSync(path.join(tmpDir, '.deepl-sync.yaml'))).toBe(false);
+    }
+  );
 
   it('no longer emits a deprecation warning for the canonical flags', async () => {
     const deps = makeDeps(handleError);
     await runSyncInit(
       [
-        '--source-locale', 'en',
-        '--target-locales', 'de',
-        '--file-format', 'json',
-        '--path', 'locales/en.json',
+        '--source-locale',
+        'en',
+        '--target-locales',
+        'de',
+        '--file-format',
+        'json',
+        '--path',
+        'locales/en.json',
       ],
-      deps,
+      deps
     );
     expect(handleError).not.toHaveBeenCalled();
-    const yaml = fs.readFileSync(path.join(tmpDir, '.deepl-sync.yaml'), 'utf-8');
+    const yaml = fs.readFileSync(
+      path.join(tmpDir, '.deepl-sync.yaml'),
+      'utf-8'
+    );
     expect(yaml).toMatch(/source_locale:\s*en/);
     expect(stderrText()).not.toMatch(/\[deprecated\]/);
   });
diff --git a/tests/unit/cli/register-sync-root.test.ts b/tests/unit/cli/register-sync-root.test.ts
index 6ea0a770..4adc6673 100644
--- a/tests/unit/cli/register-sync-root.test.ts
+++ b/tests/unit/cli/register-sync-root.test.ts
@@ -11,7 +11,9 @@ import { ValidationError } from '../../../src/utils/errors';
 import type { ServiceDeps } from '../../../src/cli/commands/service-factory';
 
 jest.mock('../../../src/cli/commands/service-factory', () => {
-  const actual = jest.requireActual('../../../src/cli/commands/service-factory');
+  const actual = jest.requireActual(
+    '../../../src/cli/commands/service-factory'
+  );
   return {
     ...(actual as object),
     createSyncCommand: jest.fn(),
@@ -71,7 +73,7 @@ describe('deepl sync --context hard-error', () => {
             lockUpdated: false,
           });
         }),
-      }),
+      })
     );
   });
 
@@ -83,7 +85,9 @@ describe('deepl sync --context hard-error', () => {
     expect(err).toBeInstanceOf(ValidationError);
     expect(err.exitCode).toBe(6);
     expect(err.message).toMatch(/--context is not a `deepl sync` flag/);
-    expect(err.message).toMatch(/`deepl translate --context "<text>"` takes a string/);
+    expect(err.message).toMatch(
+      /`deepl translate --context "<text>"` takes a string/
+    );
     expect(err.suggestion).toMatch(/--scan-context \/ --no-scan-context/);
     expect(mockCreateSyncCommand).not.toHaveBeenCalled();
   });
diff --git a/tests/unit/cli/register-sync-scan-context-help.test.ts b/tests/unit/cli/register-sync-scan-context-help.test.ts
index 5ee07297..0692c7c7 100644
--- a/tests/unit/cli/register-sync-scan-context-help.test.ts
+++ b/tests/unit/cli/register-sync-scan-context-help.test.ts
@@ -30,8 +30,9 @@ function getSyncCommand(): Command {
 }
 
 function findOption(cmd: Command, flag: string) {
-  const opts = (cmd as unknown as { options: Array<{ flags: string; description: string }> })
-    .options;
+  const opts = (
+    cmd as unknown as { options: Array<{ flags: string; description: string }> }
+  ).options;
   return opts.find((o) => o.flags === flag);
 }
 
diff --git a/tests/unit/cli/register-sync-tms-help.test.ts b/tests/unit/cli/register-sync-tms-help.test.ts
index d62c0666..8ba26473 100644
--- a/tests/unit/cli/register-sync-tms-help.test.ts
+++ b/tests/unit/cli/register-sync-tms-help.test.ts
@@ -29,7 +29,11 @@ function renderHelp(name: 'push' | 'pull'): string {
   const sub = sync.commands.find((c) => c.name() === name);
   if (!sub) throw new Error(`sync ${name} command not registered`);
   let captured = '';
-  sub.configureOutput({ writeOut: (s: string) => { captured += s; } });
+  sub.configureOutput({
+    writeOut: (s: string) => {
+      captured += s;
+    },
+  });
   sub.outputHelp();
   return captured;
 }
diff --git a/tests/unit/cli/register-sync.commander-snapshot.test.ts b/tests/unit/cli/register-sync.commander-snapshot.test.ts
index e5315c3b..18601b77 100644
--- a/tests/unit/cli/register-sync.commander-snapshot.test.ts
+++ b/tests/unit/cli/register-sync.commander-snapshot.test.ts
@@ -108,7 +108,9 @@ describe('register-sync commander tree', () => {
     };
     registerSync(program, deps);
     const syncCmd = program.commands.find((c) => c.name() === 'sync');
-    const legacy = syncCmd?.commands.find((c) => c.name() === 'glossary-report');
+    const legacy = syncCmd?.commands.find(
+      (c) => c.name() === 'glossary-report'
+    );
     expect(legacy).toBeDefined();
   });
 
@@ -208,230 +210,246 @@ const FORMAT_OPT: OptionSnapshot = {
 const EXPECTED: CommandSnapshot = {
   name: 'sync',
   description: 'Synchronize translation files using .deepl-sync.yaml config',
-  options: ([
-    {
-      flags: '--auto-commit',
-      description: 'Auto-commit translated files after sync',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--batch',
-      description: 'Force batch mode (fastest, no context or instructions)',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--ci',
-      description: 'Alias for --frozen',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--concurrency <number>',
-      description: 'Max parallel locale translations (default: 5)',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: true,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--context',
-      description: '',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--debounce <ms>',
-      description: 'Debounce delay for watch mode (default: 500ms)',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: true,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    PARENT_DRY_RUN,
-    {
-      flags: '--flag-for-review',
-      description: 'Mark translations as machine_translated in lock file for human review',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--force',
-      description:
-        'Retranslate all strings, ignoring the lock file. WARNING: also bypasses the sync.max_characters cost-cap preflight — this can rebill every translated key and incur unexpected API costs. Prefer --dry-run first to see the character estimate.',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    FORMAT_OPT,
-    {
-      flags: '--formality <level>',
-      description: 'Override formality level',
-      defaultValue: undefined,
-      negate: false,
-      choices: ['default', 'more', 'less', 'prefer_more', 'prefer_less', 'formal', 'informal'],
-      required: true,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--frozen',
-      description: 'Fail if any strings need translation (for CI)',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--glossary <name-or-id>',
-      description: 'Override glossary for all buckets',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: true,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--locale <locales>',
-      description: 'Limit to specific target locales (comma-separated)',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: true,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--model-type <type>',
-      description: 'Override model type',
-      defaultValue: undefined,
-      negate: false,
-      choices: ['quality_optimized', 'prefer_quality_optimized', 'latency_optimized'],
-      required: true,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--no-batch',
-      description:
-        'Force per-key mode (slowest, individual context per key). Default: section-batched context',
-      defaultValue: undefined,
-      negate: true,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--no-context',
-      description: '',
-      defaultValue: undefined,
-      negate: true,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--no-scan-context',
-      description:
-        'Disable source-code context scanning for this run. Overrides context.enabled only; other context.* settings in .deepl-sync.yaml are preserved.',
-      defaultValue: undefined,
-      negate: true,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '--scan-context',
-      description: 'Scan source code for context (key paths, HTML element types)',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    PARENT_SYNC_CONFIG_OPT,
-    {
-      flags: '--watch',
-      description: 'Watch source files and auto-sync on changes',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-    {
-      flags: '-y, --yes',
-      description: 'Skip --force confirmation prompt (required when CI=true)',
-      defaultValue: undefined,
-      negate: false,
-      choices: undefined,
-      required: false,
-      optional: false,
-      variadic: false,
-      mandatory: false,
-    },
-  ] as OptionSnapshot[]).sort((a, b) => a.flags.localeCompare(b.flags)),
+  options: (
+    [
+      {
+        flags: '--auto-commit',
+        description: 'Auto-commit translated files after sync',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--batch',
+        description: 'Force batch mode (fastest, no context or instructions)',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--ci',
+        description: 'Alias for --frozen',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--concurrency <number>',
+        description: 'Max parallel locale translations (default: 5)',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: true,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--context',
+        description: '',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--debounce <ms>',
+        description: 'Debounce delay for watch mode (default: 500ms)',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: true,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      PARENT_DRY_RUN,
+      {
+        flags: '--flag-for-review',
+        description:
+          'Mark translations as machine_translated in lock file for human review',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--force',
+        description:
+          'Retranslate all strings, ignoring the lock file. WARNING: also bypasses the sync.max_characters cost-cap preflight — this can rebill every translated key and incur unexpected API costs. Prefer --dry-run first to see the character estimate.',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      FORMAT_OPT,
+      {
+        flags: '--formality <level>',
+        description: 'Override formality level',
+        defaultValue: undefined,
+        negate: false,
+        choices: [
+          'default',
+          'more',
+          'less',
+          'prefer_more',
+          'prefer_less',
+          'formal',
+          'informal',
+        ],
+        required: true,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--frozen',
+        description: 'Fail if any strings need translation (for CI)',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--glossary <name-or-id>',
+        description: 'Override glossary for all buckets',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: true,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--locale <locales>',
+        description: 'Limit to specific target locales (comma-separated)',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: true,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--model-type <type>',
+        description: 'Override model type',
+        defaultValue: undefined,
+        negate: false,
+        choices: [
+          'quality_optimized',
+          'prefer_quality_optimized',
+          'latency_optimized',
+        ],
+        required: true,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--no-batch',
+        description:
+          'Force per-key mode (slowest, individual context per key). Default: section-batched context',
+        defaultValue: undefined,
+        negate: true,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--no-context',
+        description: '',
+        defaultValue: undefined,
+        negate: true,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--no-scan-context',
+        description:
+          'Disable source-code context scanning for this run. Overrides context.enabled only; other context.* settings in .deepl-sync.yaml are preserved.',
+        defaultValue: undefined,
+        negate: true,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '--scan-context',
+        description:
+          'Scan source code for context (key paths, HTML element types)',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      PARENT_SYNC_CONFIG_OPT,
+      {
+        flags: '--watch',
+        description: 'Watch source files and auto-sync on changes',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+      {
+        flags: '-y, --yes',
+        description: 'Skip --force confirmation prompt (required when CI=true)',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
+    ] as OptionSnapshot[]
+  ).sort((a, b) => a.flags.localeCompare(b.flags)),
   subcommands: [
     {
       name: 'audit',
       description:
         'Analyze translation consistency and detect terminology inconsistencies',
       options: [FORMAT_OPT, SYNC_CONFIG_OPT].sort((a, b) =>
-        a.flags.localeCompare(b.flags),
+        a.flags.localeCompare(b.flags)
       ),
       subcommands: [],
     },
@@ -533,7 +551,7 @@ const EXPECTED: CommandSnapshot = {
       name: 'pull',
       description: 'Pull approved translations from a TMS',
       options: [FORMAT_OPT, LOCALE_FILTER_OPT, SYNC_CONFIG_OPT].sort((a, b) =>
-        a.flags.localeCompare(b.flags),
+        a.flags.localeCompare(b.flags)
       ),
       subcommands: [],
     },
@@ -541,25 +559,23 @@ const EXPECTED: CommandSnapshot = {
       name: 'push',
       description: 'Push translations to a TMS for human review',
       options: [FORMAT_OPT, LOCALE_FILTER_OPT, SYNC_CONFIG_OPT].sort((a, b) =>
-        a.flags.localeCompare(b.flags),
+        a.flags.localeCompare(b.flags)
       ),
       subcommands: [],
     },
     {
       name: 'resolve',
       description: 'Resolve git merge conflicts in .deepl-sync.lock',
-      options: [
-        FORMAT_OPT,
-        RESOLVE_DRY_RUN,
-        SYNC_CONFIG_OPT,
-      ].sort((a, b) => a.flags.localeCompare(b.flags)),
+      options: [FORMAT_OPT, RESOLVE_DRY_RUN, SYNC_CONFIG_OPT].sort((a, b) =>
+        a.flags.localeCompare(b.flags)
+      ),
       subcommands: [],
     },
     {
       name: 'status',
       description: 'Show translation coverage status',
       options: [FORMAT_OPT, LOCALE_FILTER_OPT, SYNC_CONFIG_OPT].sort((a, b) =>
-        a.flags.localeCompare(b.flags),
+        a.flags.localeCompare(b.flags)
       ),
       subcommands: [],
     },
@@ -567,7 +583,7 @@ const EXPECTED: CommandSnapshot = {
       name: 'validate',
       description: 'Validate translations for quality issues',
       options: [FORMAT_OPT, LOCALE_FILTER_OPT, SYNC_CONFIG_OPT].sort((a, b) =>
-        a.flags.localeCompare(b.flags),
+        a.flags.localeCompare(b.flags)
       ),
       subcommands: [],
     },
diff --git a/tests/unit/cli/sync-options.test.ts b/tests/unit/cli/sync-options.test.ts
index 96c78588..b2c1fadd 100644
--- a/tests/unit/cli/sync-options.test.ts
+++ b/tests/unit/cli/sync-options.test.ts
@@ -15,7 +15,9 @@ describe('sync-options', () => {
 
   describe('resolveLocale', () => {
     it('prefers the subcommand value', () => {
-      expect(resolveLocale({ locale: 'de' }, childOf({ locale: 'fr' }))).toBe('de');
+      expect(resolveLocale({ locale: 'de' }, childOf({ locale: 'fr' }))).toBe(
+        'de'
+      );
     });
 
     it('falls back to the parent value', () => {
@@ -29,13 +31,18 @@ describe('sync-options', () => {
 
   describe('resolveSyncConfig', () => {
     it('prefers the subcommand value', () => {
-      expect(resolveSyncConfig({ syncConfig: 'a.yaml' }, childOf({ syncConfig: 'b.yaml' }))).toBe(
-        'a.yaml',
-      );
+      expect(
+        resolveSyncConfig(
+          { syncConfig: 'a.yaml' },
+          childOf({ syncConfig: 'b.yaml' })
+        )
+      ).toBe('a.yaml');
     });
 
     it('falls back to the parent value', () => {
-      expect(resolveSyncConfig({}, childOf({ syncConfig: 'b.yaml' }))).toBe('b.yaml');
+      expect(resolveSyncConfig({}, childOf({ syncConfig: 'b.yaml' }))).toBe(
+        'b.yaml'
+      );
     });
 
     it('returns undefined when neither scope has a value', () => {
diff --git a/tests/unit/completion-command.test.ts b/tests/unit/completion-command.test.ts
index c7439324..6d598a74 100644
--- a/tests/unit/completion-command.test.ts
+++ b/tests/unit/completion-command.test.ts
@@ -24,25 +24,13 @@ describe('CompletionCommand', () => {
     const authCmd = program
       .command('auth')
       .description('Manage authentication');
-    authCmd
-      .command('set-key')
-      .description('Set API key');
-    authCmd
-      .command('show')
-      .description('Show current API key');
-    authCmd
-      .command('clear')
-      .description('Remove API key');
-
-    const cacheCmd = program
-      .command('cache')
-      .description('Manage cache');
-    cacheCmd
-      .command('stats')
-      .description('Show cache statistics');
-    cacheCmd
-      .command('clear')
-      .description('Clear cached translations');
+    authCmd.command('set-key').description('Set API key');
+    authCmd.command('show').description('Show current API key');
+    authCmd.command('clear').description('Remove API key');
+
+    const cacheCmd = program.command('cache').description('Manage cache');
+    cacheCmd.command('stats').description('Show cache statistics');
+    cacheCmd.command('clear').description('Clear cached translations');
 
     completionCommand = new CompletionCommand(program);
   });
@@ -168,9 +156,15 @@ describe('CompletionCommand', () => {
   describe('fish completion', () => {
     it('should include top-level commands', () => {
       const script = completionCommand.generate('fish');
-      expect(script).toContain("complete -c deepl -n '__fish_use_subcommand' -a 'translate'");
-      expect(script).toContain("complete -c deepl -n '__fish_use_subcommand' -a 'auth'");
-      expect(script).toContain("complete -c deepl -n '__fish_use_subcommand' -a 'cache'");
+      expect(script).toContain(
+        "complete -c deepl -n '__fish_use_subcommand' -a 'translate'"
+      );
+      expect(script).toContain(
+        "complete -c deepl -n '__fish_use_subcommand' -a 'auth'"
+      );
+      expect(script).toContain(
+        "complete -c deepl -n '__fish_use_subcommand' -a 'cache'"
+      );
     });
 
     it('should include command descriptions', () => {
@@ -194,7 +188,7 @@ describe('CompletionCommand', () => {
 
     it('should include subcommands scoped to parent command', () => {
       const script = completionCommand.generate('fish');
-      expect(script).toContain("__fish_seen_subcommand_from auth");
+      expect(script).toContain('__fish_seen_subcommand_from auth');
       expect(script).toContain("-a 'set-key'");
       expect(script).toContain("-a 'show'");
     });
@@ -280,17 +274,20 @@ describe('CompletionCommand', () => {
   describe('hidden commands', () => {
     // Hidden commands are internal surface; offering them in tab-completion
     // publishes them to end users.
-    it.each(['bash', 'zsh', 'fish'] as const)('omits hidden commands from %s completions', (shell) => {
-      const program = new Command();
-      program.name('deepl');
-      program.command('translate').description('Translate text');
-      program.command('_internal', { hidden: true }).description('Internal');
-
-      const script = new CompletionCommand(program).generate(shell);
-
-      expect(script).toContain('translate');
-      expect(script).not.toContain('_internal');
-    });
+    it.each(['bash', 'zsh', 'fish'] as const)(
+      'omits hidden commands from %s completions',
+      (shell) => {
+        const program = new Command();
+        program.name('deepl');
+        program.command('translate').description('Translate text');
+        program.command('_internal', { hidden: true }).description('Internal');
+
+        const script = new CompletionCommand(program).generate(shell);
+
+        expect(script).toContain('translate');
+        expect(script).not.toContain('_internal');
+      }
+    );
 
     it('omits hidden subcommands', () => {
       const program = new Command();
diff --git a/tests/unit/concurrency-limiting.test.ts b/tests/unit/concurrency-limiting.test.ts
index 5ceb4be3..d33dbb50 100644
--- a/tests/unit/concurrency-limiting.test.ts
+++ b/tests/unit/concurrency-limiting.test.ts
@@ -14,7 +14,7 @@ import { mapWithConcurrency } from '../../src/utils/concurrency';
 /** Runs `total` tasks through `schedule` and reports the peak overlap. */
 async function measurePeakConcurrency(
   total: number,
-  schedule: (task: () => Promise<void>) => Promise<unknown>,
+  schedule: (task: () => Promise<void>) => Promise<unknown>
 ): Promise<number> {
   let active = 0;
   let peak = 0;
@@ -42,13 +42,16 @@ describe('concurrency limiting', () => {
       expect(() => pLimit(NaN)).toThrow();
     });
 
-    it.each([1, 2, 3])('should never exceed a concurrency of %i', async (concurrency) => {
-      const limit = pLimit(concurrency);
+    it.each([1, 2, 3])(
+      'should never exceed a concurrency of %i',
+      async (concurrency) => {
+        const limit = pLimit(concurrency);
 
-      const peak = await measurePeakConcurrency(9, (task) => limit(task));
+        const peak = await measurePeakConcurrency(9, (task) => limit(task));
 
-      expect(peak).toBeLessThanOrEqual(concurrency);
-    });
+        expect(peak).toBeLessThanOrEqual(concurrency);
+      }
+    );
   });
 
   describe('fast-glob is the real implementation', () => {
@@ -83,7 +86,7 @@ describe('concurrency limiting', () => {
           await new Promise((resolve) => setTimeout(resolve, 10));
           active--;
         },
-        3,
+        3
       );
 
       expect(peak).toBeLessThanOrEqual(3);
@@ -98,21 +101,32 @@ describe('concurrency limiting', () => {
       ['negative', -3],
       ['NaN', NaN],
       ['fractional', 0.5],
-    ])('should still process every item when concurrency is %s', async (_label, concurrency) => {
-      const items = [1, 2, 3, 4];
-      let processed = 0;
-
-      const result = await mapWithConcurrency(items, async (n) => {
-        processed++;
-        return n * 2;
-      }, concurrency);
-
-      expect(processed).toBe(items.length);
-      expect(result).toEqual([2, 4, 6, 8]);
-    });
+    ])(
+      'should still process every item when concurrency is %s',
+      async (_label, concurrency) => {
+        const items = [1, 2, 3, 4];
+        let processed = 0;
+
+        const result = await mapWithConcurrency(
+          items,
+          async (n) => {
+            processed++;
+            return n * 2;
+          },
+          concurrency
+        );
+
+        expect(processed).toBe(items.length);
+        expect(result).toEqual([2, 4, 6, 8]);
+      }
+    );
 
     it('should treat a huge concurrency as bounded by the item count', async () => {
-      const result = await mapWithConcurrency([1, 2], async (n) => n, Number.MAX_SAFE_INTEGER);
+      const result = await mapWithConcurrency(
+        [1, 2],
+        async (n) => n,
+        Number.MAX_SAFE_INTEGER
+      );
 
       expect(result).toEqual([1, 2]);
     });
@@ -121,9 +135,13 @@ describe('concurrency limiting', () => {
       const boom = new Error('worker failed');
 
       await expect(
-        mapWithConcurrency([1, 2, 3], async () => {
-          throw boom;
-        }, 2),
+        mapWithConcurrency(
+          [1, 2, 3],
+          async () => {
+            throw boom;
+          },
+          2
+        )
       ).rejects.toThrow('worker failed');
     });
   });
diff --git a/tests/unit/concurrency.test.ts b/tests/unit/concurrency.test.ts
index abc555da..945c0f25 100644
--- a/tests/unit/concurrency.test.ts
+++ b/tests/unit/concurrency.test.ts
@@ -1,4 +1,7 @@
-import { mapWithConcurrency, MULTI_TARGET_CONCURRENCY } from '../../src/utils/concurrency';
+import {
+  mapWithConcurrency,
+  MULTI_TARGET_CONCURRENCY,
+} from '../../src/utils/concurrency';
 
 describe('mapWithConcurrency', () => {
   it('should preserve result ordering', async () => {
@@ -6,7 +9,7 @@ describe('mapWithConcurrency', () => {
     const results = await mapWithConcurrency(
       items,
       async (ms) => {
-        await new Promise(r => setTimeout(r, ms));
+        await new Promise((r) => setTimeout(r, ms));
         return `done-${ms}`;
       },
       3
@@ -25,7 +28,7 @@ describe('mapWithConcurrency', () => {
       async (item) => {
         inflight++;
         maxInflight = Math.max(maxInflight, inflight);
-        await new Promise(r => setTimeout(r, 10));
+        await new Promise((r) => setTimeout(r, 10));
         inflight--;
         return item;
       },
@@ -37,11 +40,7 @@ describe('mapWithConcurrency', () => {
   });
 
   it('should handle empty array', async () => {
-    const results = await mapWithConcurrency(
-      [],
-      async () => 'never',
-      5
-    );
+    const results = await mapWithConcurrency([], async () => 'never', 5);
     expect(results).toEqual([]);
   });
 
@@ -76,7 +75,7 @@ describe('mapWithConcurrency', () => {
       async (item) => {
         inflight++;
         maxInflight = Math.max(maxInflight, inflight);
-        await new Promise(r => setTimeout(r, 10));
+        await new Promise((r) => setTimeout(r, 10));
         inflight--;
         return item;
       },
diff --git a/tests/unit/config-command.test.ts b/tests/unit/config-command.test.ts
index 83fd8f79..7b818555 100644
--- a/tests/unit/config-command.test.ts
+++ b/tests/unit/config-command.test.ts
@@ -2,8 +2,6 @@
  * Tests for Config Command
  */
 
- 
-
 import { ConfigCommand } from '../../src/cli/commands/config';
 import { ConfigService } from '../../src/storage/config';
 import { createMockConfigService } from '../helpers/mock-factories';
@@ -30,7 +28,9 @@ describe('ConfigCommand', () => {
       const value = await configCommand.get('defaults.sourceLang');
 
       expect(value).toBe('es');
-      expect(mockConfigService.getValue).toHaveBeenCalledWith('defaults.sourceLang');
+      expect(mockConfigService.getValue).toHaveBeenCalledWith(
+        'defaults.sourceLang'
+      );
     });
 
     it('should return undefined for non-existent key', async () => {
@@ -52,7 +52,6 @@ describe('ConfigCommand', () => {
         cache: { enabled: true, maxSize: 1024, ttl: 2592000 },
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
-
       });
 
       const config = await configCommand.get();
@@ -66,14 +65,18 @@ describe('ConfigCommand', () => {
       (mockConfigService.get as jest.Mock).mockReturnValueOnce({
         auth: { apiKey: 'super-secret-key-123' },
         api: { baseUrl: 'https://api.deepl.com/v2', usePro: true },
-        defaults: { sourceLang: undefined, targetLangs: [], formality: 'default', preserveFormatting: true },
+        defaults: {
+          sourceLang: undefined,
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
         cache: { enabled: true, maxSize: 1024, ttl: 2592000 },
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
-
       });
 
-      const config = await configCommand.get() as Record<string, unknown>;
+      const config = (await configCommand.get()) as Record<string, unknown>;
 
       expect(JSON.stringify(config)).not.toContain('super-secret-key-123');
       const auth = config['auth'] as Record<string, unknown>;
@@ -85,19 +88,28 @@ describe('ConfigCommand', () => {
     it('should set config value', async () => {
       await configCommand.set('defaults.sourceLang', 'en');
 
-      expect(mockConfigService.set).toHaveBeenCalledWith('defaults.sourceLang', 'en');
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'defaults.sourceLang',
+        'en'
+      );
     });
 
     it('should set array values', async () => {
       await configCommand.set('defaults.targetLangs', 'es,fr,de');
 
-      expect(mockConfigService.set).toHaveBeenCalledWith('defaults.targetLangs', ['es', 'fr', 'de']);
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'defaults.targetLangs',
+        ['es', 'fr', 'de']
+      );
     });
 
     it('should set boolean values', async () => {
       await configCommand.set('cache.enabled', 'false');
 
-      expect(mockConfigService.set).toHaveBeenCalledWith('cache.enabled', false);
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'cache.enabled',
+        false
+      );
     });
 
     it('should coerce "true" to boolean true for known boolean keys', async () => {
@@ -146,7 +158,10 @@ describe('ConfigCommand', () => {
 
     it('should not coerce "false" to boolean for non-boolean keys', async () => {
       await configCommand.set('auth.apiKey', 'false');
-      expect(mockConfigService.set).toHaveBeenCalledWith('auth.apiKey', 'false');
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'auth.apiKey',
+        'false'
+      );
     });
 
     it('should set number values', async () => {
@@ -167,24 +182,36 @@ describe('ConfigCommand', () => {
 
     it('should not coerce numeric strings for non-numeric keys', async () => {
       await configCommand.set('auth.apiKey', '12345');
-      expect(mockConfigService.set).toHaveBeenCalledWith('auth.apiKey', '12345');
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'auth.apiKey',
+        '12345'
+      );
     });
 
     it('should pass non-boolean strings through for boolean keys', async () => {
       await configCommand.set('cache.enabled', 'yes');
-      expect(mockConfigService.set).toHaveBeenCalledWith('cache.enabled', 'yes');
+      expect(mockConfigService.set).toHaveBeenCalledWith(
+        'cache.enabled',
+        'yes'
+      );
     });
 
     it('should throw error for invalid key', async () => {
-      (mockConfigService.set as jest.Mock).mockImplementationOnce(() => { throw new Error('Invalid config key'); });
+      (mockConfigService.set as jest.Mock).mockImplementationOnce(() => {
+        throw new Error('Invalid config key');
+      });
 
-      await expect(
-        configCommand.set('invalid.key', 'value')
-      ).rejects.toThrow('Invalid config key');
+      await expect(configCommand.set('invalid.key', 'value')).rejects.toThrow(
+        'Invalid config key'
+      );
     });
 
     it('should throw error for invalid value', async () => {
-      (mockConfigService.set as jest.Mock).mockImplementationOnce(() => { throw new Error('Invalid language code "invalid" for "defaults.sourceLang". Run: deepl languages to see valid codes'); });
+      (mockConfigService.set as jest.Mock).mockImplementationOnce(() => {
+        throw new Error(
+          'Invalid language code "invalid" for "defaults.sourceLang". Run: deepl languages to see valid codes'
+        );
+      });
 
       await expect(
         configCommand.set('defaults.sourceLang', 'invalid')
@@ -206,7 +233,6 @@ describe('ConfigCommand', () => {
         cache: { enabled: true, maxSize: 1024, ttl: 2592000 },
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
-
       });
 
       const config = await configCommand.list();
@@ -229,7 +255,6 @@ describe('ConfigCommand', () => {
         cache: { enabled: true, maxSize: 1024, ttl: 2592000 },
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
-
       });
 
       const config = await configCommand.list();
@@ -250,7 +275,6 @@ describe('ConfigCommand', () => {
         cache: { enabled: true, maxSize: 1024, ttl: 2592000 },
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
-
       });
 
       const config = await configCommand.list();
@@ -267,7 +291,10 @@ describe('ConfigCommand', () => {
     });
 
     it('should show (not set) for undefined value', () => {
-      const result = configCommand.formatValue('defaults.sourceLang', undefined);
+      const result = configCommand.formatValue(
+        'defaults.sourceLang',
+        undefined
+      );
       expect(result).toBe('defaults.sourceLang = (not set)');
     });
 
@@ -319,7 +346,9 @@ describe('ConfigCommand', () => {
     });
 
     it('should handle reset errors', async () => {
-      (mockConfigService.clear as jest.Mock).mockImplementationOnce(() => { throw new Error('Failed to reset'); });
+      (mockConfigService.clear as jest.Mock).mockImplementationOnce(() => {
+        throw new Error('Failed to reset');
+      });
 
       await expect(configCommand.reset()).rejects.toThrow('Failed to reset');
     });
diff --git a/tests/unit/config-service.test.ts b/tests/unit/config-service.test.ts
index fba66749..73aaba82 100644
--- a/tests/unit/config-service.test.ts
+++ b/tests/unit/config-service.test.ts
@@ -58,7 +58,7 @@ describe('ConfigService', () => {
 
       // This would be a TypeScript error: Cannot assign to 'targetLangs' because it is a read-only property
       // But in JavaScript runtime, the object is still mutable
-       
+
       (config1 as any).defaults.targetLangs.push('es');
 
       const config2 = configService.get();
@@ -66,7 +66,7 @@ describe('ConfigService', () => {
       expect(config2.defaults.targetLangs).toEqual(['es']);
 
       // Clean up for other tests
-       
+
       (config2 as any).defaults.targetLangs.pop();
     });
   });
@@ -240,13 +240,17 @@ describe('ConfigService', () => {
     it('should validate formality values', () => {
       expect(() => {
         configService.set('defaults.formality', 'invalid');
-      }).toThrow(/Invalid formality "invalid" for "defaults\.formality"\. Valid values:/);
+      }).toThrow(
+        /Invalid formality "invalid" for "defaults\.formality"\. Valid values:/
+      );
     });
 
     it('should validate output format', () => {
       expect(() => {
         configService.set('output.format', 'invalid');
-      }).toThrow(/Invalid output format "invalid" for "output\.format"\. Valid values:/);
+      }).toThrow(
+        /Invalid output format "invalid" for "output\.format"\. Valid values:/
+      );
     });
 
     it('should validate cache size is positive', () => {
@@ -257,7 +261,6 @@ describe('ConfigService', () => {
 
     it('should validate boolean values', () => {
       expect(() => {
-
         configService.set('cache.enabled', 'yes');
       }).toThrow(/Expected boolean for "cache\.enabled"\. Use true or false\./);
     });
@@ -332,7 +335,10 @@ describe('ConfigService', () => {
     });
 
     it('should write config file with mode 0o600', () => {
-      const uniqueDir = path.join(os.tmpdir(), `deepl-perm-test-file-${Date.now()}`);
+      const uniqueDir = path.join(
+        os.tmpdir(),
+        `deepl-perm-test-file-${Date.now()}`
+      );
       const configPath = path.join(uniqueDir, 'config.json');
 
       const service = new ConfigService(configPath);
@@ -350,7 +356,9 @@ describe('ConfigService', () => {
       // The API key is written in plaintext, so the intermediate file must not
       // land on a path anyone else could have prepared in advance.
       it('should not write through a symlink planted at the predictable temp path', () => {
-        const uniqueDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-tmp-safety-'));
+        const uniqueDir = fs.mkdtempSync(
+          path.join(os.tmpdir(), 'deepl-tmp-safety-')
+        );
         const configPath = path.join(uniqueDir, 'config.json');
         const stolenPath = path.join(uniqueDir, 'stolen.txt');
         fs.symlinkSync(stolenPath, `${configPath}.tmp`);
@@ -360,13 +368,17 @@ describe('ConfigService', () => {
 
         expect(fs.existsSync(stolenPath)).toBe(false);
         expect(fs.lstatSync(configPath).isSymbolicLink()).toBe(false);
-        expect(fs.readFileSync(configPath, 'utf-8')).toContain('secret-key-value');
+        expect(fs.readFileSync(configPath, 'utf-8')).toContain(
+          'secret-key-value'
+        );
 
         fs.rmSync(uniqueDir, { recursive: true, force: true });
       });
 
       it('should not write to the predictable temp path even when it is free', () => {
-        const uniqueDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-tmp-unique-'));
+        const uniqueDir = fs.mkdtempSync(
+          path.join(os.tmpdir(), 'deepl-tmp-unique-')
+        );
         const configPath = path.join(uniqueDir, 'config.json');
         const predictablePath = `${configPath}.tmp`;
         fs.writeFileSync(predictablePath, 'planted', 'utf-8');
@@ -382,7 +394,9 @@ describe('ConfigService', () => {
       });
 
       it('should leave no temp file behind after a successful write', () => {
-        const uniqueDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-tmp-clean-'));
+        const uniqueDir = fs.mkdtempSync(
+          path.join(os.tmpdir(), 'deepl-tmp-clean-')
+        );
         const configPath = path.join(uniqueDir, 'config.json');
 
         const service = new ConfigService(configPath);
@@ -401,7 +415,11 @@ describe('ConfigService', () => {
       const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
 
       // Write invalid JSON to a config file so loading fails during JSON.parse
-      const badConfigPath = path.join(os.tmpdir(), `deepl-bad-config-${Date.now()}`, 'config.json');
+      const badConfigPath = path.join(
+        os.tmpdir(),
+        `deepl-bad-config-${Date.now()}`,
+        'config.json'
+      );
       const badConfigDir = path.dirname(badConfigPath);
       fs.mkdirSync(badConfigDir, { recursive: true });
       fs.writeFileSync(badConfigPath, '{ invalid json !!!');
@@ -548,8 +566,12 @@ describe('ConfigService', () => {
     });
 
     it('delete() should reject constructor and prototype segments', () => {
-      expect(() => configService.delete('constructor.polluted')).toThrow('Invalid path');
-      expect(() => configService.delete('auth.prototype')).toThrow('Invalid path');
+      expect(() => configService.delete('constructor.polluted')).toThrow(
+        'Invalid path'
+      );
+      expect(() => configService.delete('auth.prototype')).toThrow(
+        'Invalid path'
+      );
     });
 
     it('delete() should not walk inherited properties', () => {
diff --git a/tests/unit/confirm.test.ts b/tests/unit/confirm.test.ts
index 40666061..c9f76b34 100644
--- a/tests/unit/confirm.test.ts
+++ b/tests/unit/confirm.test.ts
@@ -40,116 +40,143 @@ describe('confirm()', () => {
     });
 
     it('should return true when user answers "y"', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('y');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('y');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(true);
     });
 
     it('should return true when user answers "yes"', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('yes');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('yes');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(true);
     });
 
     it('should return true when user answers "Y"', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('Y');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('Y');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(true);
     });
 
     it('should return true when user answers "YES"', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('YES');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('YES');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(true);
     });
 
     it('should return false when user answers "n"', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('n');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('n');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(false);
     });
 
     it('should return false when user answers "no"', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('no');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('no');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(false);
     });
 
     it('should return false when user presses enter (empty input)', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(false);
     });
 
     it('should return false for arbitrary text', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('maybe');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('maybe');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(false);
     });
 
     it('should trim whitespace from answer', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('  y  ');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('  y  ');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
       expect(result).toBe(true);
     });
 
     it('should use default prompt message', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('n');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('n');
+        }
+      );
 
       await confirm({ _createInterface: mockCreateInterface });
 
       expect(mockRl.question).toHaveBeenCalledWith(
         'Are you sure? [y/N] ',
-        expect.any(Function),
+        expect.any(Function)
       );
     });
 
     it('should use custom prompt message', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('n');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('n');
+        }
+      );
 
-      await confirm({ message: 'Delete everything?', _createInterface: mockCreateInterface });
+      await confirm({
+        message: 'Delete everything?',
+        _createInterface: mockCreateInterface,
+      });
 
       expect(mockRl.question).toHaveBeenCalledWith(
         'Delete everything? [y/N] ',
-        expect.any(Function),
+        expect.any(Function)
       );
     });
 
     it('should close readline interface after answer', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('y');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('y');
+        }
+      );
 
       await confirm({ _createInterface: mockCreateInterface });
 
@@ -157,9 +184,11 @@ describe('confirm()', () => {
     });
 
     it('should create readline with stdin and stderr', async () => {
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('n');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('n');
+        }
+      );
 
       await confirm({ _createInterface: mockCreateInterface });
 
@@ -187,7 +216,10 @@ describe('confirm()', () => {
     });
 
     it('should return false regardless of message option', async () => {
-      const result = await confirm({ message: 'Delete everything?', _createInterface: mockCreateInterface });
+      const result = await confirm({
+        message: 'Delete everything?',
+        _createInterface: mockCreateInterface,
+      });
 
       expect(result).toBe(false);
       expect(mockCreateInterface).not.toHaveBeenCalled();
@@ -216,9 +248,11 @@ describe('confirm()', () => {
       setNoInput(true);
       setNoInput(false);
 
-      mockRl.question.mockImplementation((_prompt: string, cb: (answer: string) => void) => {
-        cb('y');
-      });
+      mockRl.question.mockImplementation(
+        (_prompt: string, cb: (answer: string) => void) => {
+          cb('y');
+        }
+      );
 
       const result = await confirm({ _createInterface: mockCreateInterface });
 
diff --git a/tests/unit/deepl-client-document.test.ts b/tests/unit/deepl-client-document.test.ts
index ed1c206a..e7c8ad69 100644
--- a/tests/unit/deepl-client-document.test.ts
+++ b/tests/unit/deepl-client-document.test.ts
@@ -210,7 +210,9 @@ describe('DeepLClient - Document Translation', () => {
           targetLang: 'es',
           // filename missing
         } as any)
-      ).rejects.toThrow('filename is required when uploading document as Buffer');
+      ).rejects.toThrow(
+        'filename is required when uploading document as Buffer'
+      );
     });
 
     it('should throw error if file is empty', async () => {
diff --git a/tests/unit/deepl-client-lazy.test.ts b/tests/unit/deepl-client-lazy.test.ts
index 2d10774e..c9aaa53a 100644
--- a/tests/unit/deepl-client-lazy.test.ts
+++ b/tests/unit/deepl-client-lazy.test.ts
@@ -17,14 +17,14 @@ describe('DeepLClient lazy sub-client construction', () => {
   });
 
   it('should still validate API key eagerly', () => {
-     
-    const { DeepLClient } = require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
+    const { DeepLClient } =
+      require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
     expect(() => new DeepLClient('')).toThrow('API key is required');
   });
 
   it('should construct sub-clients lazily on first method call', async () => {
-     
-    const { DeepLClient } = require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
+    const { DeepLClient } =
+      require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
     const client = new DeepLClient(apiKey);
 
     // At this point, only static validation ran (no HttpClient instance created).
@@ -38,9 +38,11 @@ describe('DeepLClient lazy sub-client construction', () => {
     expect((client as any)._adminClient).toBeUndefined();
 
     // Now make a translate call - this should create TranslationClient
-    nock(baseUrl).post('/v2/translate').reply(200, {
-      translations: [{ text: 'Hola', detected_source_language: 'EN' }],
-    });
+    nock(baseUrl)
+      .post('/v2/translate')
+      .reply(200, {
+        translations: [{ text: 'Hola', detected_source_language: 'EN' }],
+      });
 
     await client.translate('Hello', { targetLang: 'es' });
 
@@ -54,19 +56,23 @@ describe('DeepLClient lazy sub-client construction', () => {
   });
 
   it('should reuse sub-client on subsequent calls', async () => {
-     
-    const { DeepLClient } = require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
+    const { DeepLClient } =
+      require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
     const client = new DeepLClient(apiKey);
 
-    nock(baseUrl).post('/v2/translate').reply(200, {
-      translations: [{ text: 'Hola', detected_source_language: 'EN' }],
-    });
+    nock(baseUrl)
+      .post('/v2/translate')
+      .reply(200, {
+        translations: [{ text: 'Hola', detected_source_language: 'EN' }],
+      });
     await client.translate('Hello', { targetLang: 'es' });
     const firstClient = (client as any)._translationClient;
 
-    nock(baseUrl).post('/v2/translate').reply(200, {
-      translations: [{ text: 'Bonjour', detected_source_language: 'EN' }],
-    });
+    nock(baseUrl)
+      .post('/v2/translate')
+      .reply(200, {
+        translations: [{ text: 'Bonjour', detected_source_language: 'EN' }],
+      });
     await client.translate('Hello', { targetLang: 'fr' });
     const secondClient = (client as any)._translationClient;
 
@@ -74,8 +80,8 @@ describe('DeepLClient lazy sub-client construction', () => {
   });
 
   it('should construct GlossaryClient lazily on glossary method call', async () => {
-     
-    const { DeepLClient } = require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
+    const { DeepLClient } =
+      require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
     const client = new DeepLClient(apiKey);
 
     expect((client as any)._glossaryClient).toBeUndefined();
@@ -88,15 +94,17 @@ describe('DeepLClient lazy sub-client construction', () => {
   });
 
   it('should construct WriteClient lazily on improveText call', async () => {
-     
-    const { DeepLClient } = require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
+    const { DeepLClient } =
+      require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
     const client = new DeepLClient(apiKey);
 
     expect((client as any)._writeClient).toBeUndefined();
 
-    nock(baseUrl).post('/v2/write/rephrase').reply(200, {
-      improvements: [{ text: 'Improved.', target_language: 'en-US' }],
-    });
+    nock(baseUrl)
+      .post('/v2/write/rephrase')
+      .reply(200, {
+        improvements: [{ text: 'Improved.', target_language: 'en-US' }],
+      });
     await client.improveText('Test.', { targetLang: 'en-us' });
 
     expect((client as any)._writeClient).not.toBeNull();
@@ -104,8 +112,8 @@ describe('DeepLClient lazy sub-client construction', () => {
   });
 
   it('should construct AdminClient lazily on listApiKeys call', async () => {
-     
-    const { DeepLClient } = require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
+    const { DeepLClient } =
+      require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
     const client = new DeepLClient(apiKey);
 
     expect((client as any)._adminClient).toBeUndefined();
@@ -118,8 +126,8 @@ describe('DeepLClient lazy sub-client construction', () => {
   });
 
   it('should construct StyleRulesClient lazily on getStyleRules call', async () => {
-     
-    const { DeepLClient } = require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
+    const { DeepLClient } =
+      require('../../src/api/deepl-client') as typeof import('../../src/api/deepl-client');
     const client = new DeepLClient(apiKey);
 
     expect((client as any)._styleRulesClient).toBeUndefined();
diff --git a/tests/unit/deepl-client.test.ts b/tests/unit/deepl-client.test.ts
index 293a1d2c..4b8b8e08 100644
--- a/tests/unit/deepl-client.test.ts
+++ b/tests/unit/deepl-client.test.ts
@@ -13,7 +13,9 @@ describe('DeepLClient', () => {
   const baseUrl = 'https://api-free.deepl.com';
 
   beforeEach(() => {
-    jest.spyOn(HttpClient.prototype, 'sleep' as any).mockResolvedValue(undefined);
+    jest
+      .spyOn(HttpClient.prototype, 'sleep' as any)
+      .mockResolvedValue(undefined);
     client = new DeepLClient(apiKey);
     nock.cleanAll();
   });
@@ -68,7 +70,9 @@ describe('DeepLClient', () => {
     });
 
     it('should include cli version and node version in User-Agent', () => {
-      expect(USER_AGENT).toMatch(/^deepl-cli\/\d+\.\d+\.\d+ node\/\d+\.\d+\.\d+$/);
+      expect(USER_AGENT).toMatch(
+        /^deepl-cli\/\d+\.\d+\.\d+ node\/\d+\.\d+\.\d+$/
+      );
     });
   });
 
@@ -96,7 +100,6 @@ describe('DeepLClient', () => {
     it('should include source language when specified', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.source_lang === 'EN';
         })
         .reply(200, {
@@ -119,7 +122,6 @@ describe('DeepLClient', () => {
     it('should handle formality parameter', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.formality === 'more';
         })
         .reply(200, {
@@ -137,7 +139,6 @@ describe('DeepLClient', () => {
     it('should handle glossary parameter', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.glossary_id === 'glossary-123';
         })
         .reply(200, {
@@ -155,7 +156,6 @@ describe('DeepLClient', () => {
     it('should handle preserve_formatting option', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.preserve_formatting === '1';
         })
         .reply(200, {
@@ -173,7 +173,6 @@ describe('DeepLClient', () => {
     it('should handle context parameter', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.context === 'API documentation';
         })
         .reply(200, {
@@ -191,7 +190,6 @@ describe('DeepLClient', () => {
     it('should handle split_sentences parameter', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.split_sentences === 'nonewlines';
         })
         .reply(200, {
@@ -209,7 +207,6 @@ describe('DeepLClient', () => {
     it('should map split_sentences "on" to API value "1"', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.split_sentences === '1';
         })
         .reply(200, {
@@ -227,7 +224,6 @@ describe('DeepLClient', () => {
     it('should map split_sentences "off" to API value "0"', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.split_sentences === '0';
         })
         .reply(200, {
@@ -245,7 +241,6 @@ describe('DeepLClient', () => {
     it('should handle tag_handling parameter', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.tag_handling === 'xml';
         })
         .reply(200, {
@@ -263,7 +258,6 @@ describe('DeepLClient', () => {
     it('should send show_billed_characters parameter when enabled', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.show_billed_characters === '1';
         })
         .reply(200, {
@@ -309,7 +303,6 @@ describe('DeepLClient', () => {
     it('should not send show_billed_characters when not requested', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.show_billed_characters === undefined;
         })
         .reply(200, {
@@ -331,7 +324,6 @@ describe('DeepLClient', () => {
     it('should never send the retired enable_beta_languages parameter', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.enable_beta_languages === undefined;
         })
         .reply(200, {
@@ -353,7 +345,6 @@ describe('DeepLClient', () => {
     it('should send outline_detection parameter when set to true', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.outline_detection === '1';
         })
         .reply(200, {
@@ -372,7 +363,6 @@ describe('DeepLClient', () => {
     it('should send outline_detection parameter when set to false', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.outline_detection === '0';
         })
         .reply(200, {
@@ -391,7 +381,6 @@ describe('DeepLClient', () => {
     it('should send splitting_tags parameter as comma-separated string', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.splitting_tags === 'br,hr,div';
         })
         .reply(200, {
@@ -410,7 +399,6 @@ describe('DeepLClient', () => {
     it('should send non_splitting_tags parameter as comma-separated string', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.non_splitting_tags === 'code,pre,kbd';
         })
         .reply(200, {
@@ -429,7 +417,6 @@ describe('DeepLClient', () => {
     it('should send ignore_tags parameter as comma-separated string', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.ignore_tags === 'script,style,noscript';
         })
         .reply(200, {
@@ -448,14 +435,12 @@ describe('DeepLClient', () => {
     it('should send all XML tag handling parameters together', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
-          return body.outline_detection === '0' &&
-             
+          return (
+            body.outline_detection === '0' &&
             body.splitting_tags === 'br,hr' &&
-             
             body.non_splitting_tags === 'code,pre' &&
-             
-            body.ignore_tags === 'script,style';
+            body.ignore_tags === 'script,style'
+          );
         })
         .reply(200, {
           translations: [{ text: '<p>Hola</p>' }],
@@ -476,14 +461,12 @@ describe('DeepLClient', () => {
     it('should send custom_instructions parameter as array', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
-          return Array.isArray(body.custom_instructions) &&
-             
+          return (
+            Array.isArray(body.custom_instructions) &&
             body.custom_instructions.length === 2 &&
-             
             body.custom_instructions[0] === 'Use informal tone' &&
-             
-            body.custom_instructions[1] === 'Preserve brand names';
+            body.custom_instructions[1] === 'Preserve brand names'
+          );
         })
         .reply(200, {
           translations: [{ text: 'Hola mundo' }],
@@ -500,7 +483,6 @@ describe('DeepLClient', () => {
     it('should not send custom_instructions when not specified', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.custom_instructions === undefined;
         })
         .reply(200, {
@@ -517,18 +499,14 @@ describe('DeepLClient', () => {
     it('should send custom_instructions in batch translation', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
-          return Array.isArray(body.custom_instructions) &&
-             
+          return (
+            Array.isArray(body.custom_instructions) &&
             body.custom_instructions[0] === 'Keep it short' &&
-             
-            body.custom_instructions[1] === 'Preserve names';
+            body.custom_instructions[1] === 'Preserve names'
+          );
         })
         .reply(200, {
-          translations: [
-            { text: 'Hola' },
-            { text: 'Mundo' },
-          ],
+          translations: [{ text: 'Hola' }, { text: 'Mundo' }],
         });
 
       await client.translateBatch(['Hello', 'World'], {
@@ -541,11 +519,9 @@ describe('DeepLClient', () => {
 
     it('should throw error for invalid target language', async () => {
       await expect(
-         
         client.translate('Hello', { targetLang: 'invalid' as any })
       ).rejects.toThrow();
     });
-
   });
 
   describe('error handling', () => {
@@ -576,9 +552,7 @@ describe('DeepLClient', () => {
       });
 
       it('should handle 456 quota exceeded error', async () => {
-        nock(baseUrl)
-          .post(path)
-          .reply(456, { message: 'Quota exceeded' });
+        nock(baseUrl).post(path).reply(456, { message: 'Quota exceeded' });
 
         await expect(call(client)).rejects.toThrow('Quota exceeded');
       });
@@ -597,24 +571,22 @@ describe('DeepLClient', () => {
           .post(path)
           .reply(503, { message: 'Service temporarily unavailable' });
 
-        await expect(call(client)).rejects.toThrow('Service temporarily unavailable');
+        await expect(call(client)).rejects.toThrow(
+          'Service temporarily unavailable'
+        );
       });
 
       it('should handle network errors', async () => {
-        nock(baseUrl)
-          .post(path)
-          .replyWithError('Network error');
+        nock(baseUrl).post(path).replyWithError('Network error');
 
         await expect(call(client)).rejects.toThrow();
       });
     });
 
     it('should throw classified AuthError for 403, not raw AxiosError', async () => {
-      nock(baseUrl)
-        .post('/v2/translate')
-        .reply(403, {
-          message: 'Forbidden',
-        });
+      nock(baseUrl).post('/v2/translate').reply(403, {
+        message: 'Forbidden',
+      });
 
       try {
         await client.translate('Hello', { targetLang: 'es' });
@@ -635,8 +607,12 @@ describe('DeepLClient', () => {
       const maliciousBody = { message: '\x1b[2J\x1b[0;0HCredentials stolen' };
       nock(baseUrl).post('/v2/translate').reply(400, maliciousBody);
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
-        expect.objectContaining({ message: expect.not.stringContaining('\x1b') }),
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(
+        expect.objectContaining({
+          message: expect.not.stringContaining('\x1b'),
+        })
       );
     });
 
@@ -644,8 +620,12 @@ describe('DeepLClient', () => {
       const maliciousBody = { message: '\x1b[31mInternal failure\x1b[0m' };
       nock(baseUrl).post('/v2/translate').reply(500, maliciousBody);
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
-        expect.objectContaining({ message: expect.not.stringContaining('\x1b') }),
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(
+        expect.objectContaining({
+          message: expect.not.stringContaining('\x1b'),
+        })
       );
     });
 
@@ -653,17 +633,19 @@ describe('DeepLClient', () => {
       const maliciousBody = { message: 'OK\u202EStolen' };
       nock(baseUrl).post('/v2/translate').reply(400, maliciousBody);
 
-      await expect(client.translate('Hello', { targetLang: 'es' })).rejects.toThrow(
-        expect.objectContaining({ message: expect.not.stringContaining('\u202E') }),
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(
+        expect.objectContaining({
+          message: expect.not.stringContaining('\u202E'),
+        })
       );
     });
 
     it('should throw classified QuotaError for 456, not raw AxiosError', async () => {
-      nock(baseUrl)
-        .post('/v2/translate')
-        .reply(456, {
-          message: 'Quota exceeded',
-        });
+      nock(baseUrl).post('/v2/translate').reply(456, {
+        message: 'Quota exceeded',
+      });
 
       try {
         await client.translate('Hello', { targetLang: 'es' });
@@ -674,12 +656,9 @@ describe('DeepLClient', () => {
     });
 
     it('should throw classified RateLimitError for 429, not raw AxiosError', async () => {
-      nock(baseUrl)
-        .post('/v2/translate')
-        .times(4)
-        .reply(429, {
-          message: 'Too many requests',
-        });
+      nock(baseUrl).post('/v2/translate').times(4).reply(429, {
+        message: 'Too many requests',
+      });
 
       try {
         await client.translate('Hello', { targetLang: 'es' });
@@ -690,9 +669,7 @@ describe('DeepLClient', () => {
     });
 
     it('should handle invalid JSON response', async () => {
-      nock(baseUrl)
-        .post('/v2/translate')
-        .reply(200, 'Invalid JSON');
+      nock(baseUrl).post('/v2/translate').reply(200, 'Invalid JSON');
 
       await expect(
         client.translate('Hello', { targetLang: 'es' })
@@ -700,9 +677,7 @@ describe('DeepLClient', () => {
     });
 
     it('should handle missing translations in response', async () => {
-      nock(baseUrl)
-        .post('/v2/translate')
-        .reply(200, {});
+      nock(baseUrl).post('/v2/translate').reply(200, {});
 
       await expect(
         client.translate('Hello', { targetLang: 'es' })
@@ -712,12 +687,10 @@ describe('DeepLClient', () => {
 
   describe('getUsage()', () => {
     it('should return usage statistics', async () => {
-      nock(baseUrl)
-        .get('/v2/usage')
-        .reply(200, {
-          character_count: 12345,
-          character_limit: 500000,
-        });
+      nock(baseUrl).get('/v2/usage').reply(200, {
+        character_count: 12345,
+        character_limit: 500000,
+      });
 
       const usage = await client.getUsage();
 
@@ -726,22 +699,18 @@ describe('DeepLClient', () => {
     });
 
     it('should handle usage API errors', async () => {
-      nock(baseUrl)
-        .get('/v2/usage')
-        .reply(403);
+      nock(baseUrl).get('/v2/usage').reply(403);
 
       await expect(client.getUsage()).rejects.toThrow();
     });
 
     it('should ignore the deprecated speech_to_text_milliseconds_* fields', async () => {
-      nock(baseUrl)
-        .get('/v2/usage')
-        .reply(200, {
-          character_count: 12345,
-          character_limit: 500000,
-          speech_to_text_milliseconds_count: 0,
-          speech_to_text_milliseconds_limit: 0,
-        });
+      nock(baseUrl).get('/v2/usage').reply(200, {
+        character_count: 12345,
+        character_limit: 500000,
+        speech_to_text_milliseconds_count: 0,
+        speech_to_text_milliseconds_limit: 0,
+      });
 
       const usage = await client.getUsage();
 
@@ -757,8 +726,17 @@ describe('DeepLClient', () => {
           character_count: 12345,
           character_limit: 500000,
           products: [
-            { product_type: 'translate', character_count: 10000, api_key_character_count: 10000 },
-            { product_type: 'speech_to_text', character_count: 120000, api_key_character_count: 120000, billing_unit: 'milliseconds' },
+            {
+              product_type: 'translate',
+              character_count: 10000,
+              api_key_character_count: 10000,
+            },
+            {
+              product_type: 'speech_to_text',
+              character_count: 120000,
+              api_key_character_count: 120000,
+              billing_unit: 'milliseconds',
+            },
           ],
         });
 
@@ -770,7 +748,6 @@ describe('DeepLClient', () => {
       expect(products[1]!.productType).toBe('speech_to_text');
       expect(products[1]!.billingUnit).toBe('milliseconds');
     });
-
   });
 
   describe('getSupportedLanguages()', () => {
@@ -779,9 +756,24 @@ describe('DeepLClient', () => {
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
-          { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
-          { lang: 'en-gb', name: 'English (British)', usable_as_source: false, usable_as_target: true },
+          {
+            lang: 'en',
+            name: 'English',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'es',
+            name: 'Spanish',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'en-gb',
+            name: 'English (British)',
+            usable_as_source: false,
+            usable_as_target: true,
+          },
         ]);
 
       const languages = await client.getSupportedLanguages('source');
@@ -797,8 +789,18 @@ describe('DeepLClient', () => {
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'es', name: 'Spanish', usable_as_source: true, usable_as_target: true },
-          { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
+          {
+            lang: 'es',
+            name: 'Spanish',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'fr',
+            name: 'French',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
         ]);
 
       const languages = await client.getSupportedLanguages('target');
@@ -812,8 +814,18 @@ describe('DeepLClient', () => {
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
-          { lang: 'xx', name: 'Source Only', usable_as_source: true, usable_as_target: false },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'xx',
+            name: 'Source Only',
+            usable_as_source: true,
+            usable_as_target: false,
+          },
         ]);
 
       const languages = await client.getSupportedLanguages('target');
@@ -852,9 +864,15 @@ describe('DeepLClient', () => {
 
       const languages = await client.getSupportedLanguages('target');
 
-      expect(languages.find(l => l.language === 'de')?.supportsFormality).toBe(true);
-      expect(languages.find(l => l.language === 'ja')?.supportsFormality).toBe(true);
-      expect(languages.find(l => l.language === 'ko')?.supportsFormality).toBe(false);
+      expect(
+        languages.find((l) => l.language === 'de')?.supportsFormality
+      ).toBe(true);
+      expect(
+        languages.find((l) => l.language === 'ja')?.supportsFormality
+      ).toBe(true);
+      expect(
+        languages.find((l) => l.language === 'ko')?.supportsFormality
+      ).toBe(false);
     });
 
     it('should report formality for every target the response describes', async () => {
@@ -864,8 +882,18 @@ describe('DeepLClient', () => {
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'de', name: 'German', usable_as_target: true, features: { formality: { status: 'stable' } } },
-          { lang: 'sw', name: 'Swahili', usable_as_target: true, features: { tag_handling: { status: 'stable' } } },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_target: true,
+            features: { formality: { status: 'stable' } },
+          },
+          {
+            lang: 'sw',
+            name: 'Swahili',
+            usable_as_target: true,
+            features: { tag_handling: { status: 'stable' } },
+          },
         ]);
 
       const languages = await client.getSupportedLanguages('target');
@@ -882,9 +910,7 @@ describe('DeepLClient', () => {
       nock(baseUrl)
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
-        .reply(200, [
-          { lang: 'de', name: 'German', usable_as_target: true },
-        ]);
+        .reply(200, [{ lang: 'de', name: 'German', usable_as_target: true }]);
 
       const languages = await client.getSupportedLanguages('target');
 
@@ -896,7 +922,12 @@ describe('DeepLClient', () => {
         .get('/v3/languages')
         .query({ resource: 'translate_text' })
         .reply(200, [
-          { lang: 'de', name: 'German', usable_as_source: true, features: { formality: { status: 'stable' } } },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            features: { formality: { status: 'stable' } },
+          },
         ]);
 
       const languages = await client.getSupportedLanguages('source');
@@ -910,9 +941,7 @@ describe('DeepLClient', () => {
         .query({ resource: 'translate_text' })
         .reply(500);
 
-      await expect(
-        client.getSupportedLanguages('source')
-      ).rejects.toThrow();
+      await expect(client.getSupportedLanguages('source')).rejects.toThrow();
     });
   });
 
@@ -943,10 +972,7 @@ describe('DeepLClient', () => {
     });
 
     it('should give up after max retries', async () => {
-      nock(baseUrl)
-        .get('/v2/usage')
-        .times(4)
-        .reply(503);
+      nock(baseUrl).get('/v2/usage').times(4).reply(503);
 
       await expect(client.getUsage()).rejects.toThrow();
     });
@@ -1103,7 +1129,9 @@ describe('DeepLClient', () => {
       nock('https://custom.api.com')
         .post('/v2/translate')
         .reply(200, { translations: [{ text: 'Hola' }] });
-      const result = await customClient.translate('Hello', { targetLang: 'es' });
+      const result = await customClient.translate('Hello', {
+        targetLang: 'es',
+      });
       expect(result.text).toBe('Hola');
     });
 
@@ -1172,7 +1200,7 @@ describe('DeepLClient', () => {
           },
         });
         expect(warnSpy).toHaveBeenCalledWith(
-          expect.stringMatching(/routing HTTPS traffic.*via HTTP proxy/i),
+          expect.stringMatching(/routing HTTPS traffic.*via HTTP proxy/i)
         );
       } finally {
         warnSpy.mockRestore();
@@ -1190,7 +1218,7 @@ describe('DeepLClient', () => {
           },
         });
         expect(warnSpy).not.toHaveBeenCalledWith(
-          expect.stringMatching(/routing HTTPS traffic.*via HTTP proxy/i),
+          expect.stringMatching(/routing HTTPS traffic.*via HTTP proxy/i)
         );
       } finally {
         warnSpy.mockRestore();
@@ -1304,7 +1332,6 @@ describe('DeepLClient', () => {
       it('should apply simple writing style', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.writing_style === 'simple';
           })
           .reply(200, {
@@ -1328,7 +1355,6 @@ describe('DeepLClient', () => {
       it('should apply business writing style', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.writing_style === 'business';
           })
           .reply(200, {
@@ -1352,7 +1378,6 @@ describe('DeepLClient', () => {
       it('should apply academic writing style', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.writing_style === 'academic';
           })
           .reply(200, {
@@ -1376,7 +1401,6 @@ describe('DeepLClient', () => {
       it('should apply casual writing style', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.writing_style === 'casual';
           })
           .reply(200, {
@@ -1402,7 +1426,6 @@ describe('DeepLClient', () => {
       it('should apply enthusiastic tone', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.tone === 'enthusiastic';
           })
           .reply(200, {
@@ -1426,7 +1449,6 @@ describe('DeepLClient', () => {
       it('should apply friendly tone', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.tone === 'friendly';
           })
           .reply(200, {
@@ -1450,7 +1472,6 @@ describe('DeepLClient', () => {
       it('should apply confident tone', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.tone === 'confident';
           })
           .reply(200, {
@@ -1474,7 +1495,6 @@ describe('DeepLClient', () => {
       it('should apply diplomatic tone', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.tone === 'diplomatic';
           })
           .reply(200, {
@@ -1500,7 +1520,6 @@ describe('DeepLClient', () => {
       it('should work with only target language', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return !body.writing_style && !body.tone;
           })
           .reply(200, {
@@ -1665,7 +1684,6 @@ describe('DeepLClient', () => {
       it('should apply prefer_simple writing style', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.writing_style === 'prefer_simple';
           })
           .reply(200, {
@@ -1689,7 +1707,6 @@ describe('DeepLClient', () => {
       it('should apply prefer_enthusiastic tone', async () => {
         nock(baseUrl)
           .post('/v2/write/rephrase', (body) => {
-             
             return body.tone === 'prefer_enthusiastic';
           })
           .reply(200, {
@@ -1717,7 +1734,7 @@ describe('DeepLClient', () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
           // Verify multiple text parameters are sent
-           
+
           return Array.isArray(body.text) && body.text.length === 3;
         })
         .reply(200, {
@@ -1777,18 +1794,14 @@ describe('DeepLClient', () => {
     it('should include all translation options in batch request', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
-          return body.source_lang === 'EN' &&
-             
+          return (
+            body.source_lang === 'EN' &&
             body.formality === 'more' &&
-             
-            body.glossary_id === 'test-glossary';
+            body.glossary_id === 'test-glossary'
+          );
         })
         .reply(200, {
-          translations: [
-            { text: 'Hola' },
-            { text: 'Adiós' },
-          ],
+          translations: [{ text: 'Hola' }, { text: 'Adiós' }],
         });
 
       await client.translateBatch(['Hello', 'Goodbye'], {
@@ -1802,11 +1815,9 @@ describe('DeepLClient', () => {
     });
 
     it('should handle API errors in batch translation', async () => {
-      nock(baseUrl)
-        .post('/v2/translate')
-        .reply(403, {
-          message: 'Authorization failed',
-        });
+      nock(baseUrl).post('/v2/translate').reply(403, {
+        message: 'Authorization failed',
+      });
 
       await expect(
         client.translateBatch(['Hello', 'Goodbye'], { targetLang: 'es' })
@@ -1871,7 +1882,6 @@ describe('DeepLClient', () => {
     it('should send show_billed_characters in batch translation', async () => {
       nock(baseUrl)
         .post('/v2/translate', (body) => {
-           
           return body.show_billed_characters === '1';
         })
         .reply(200, {
@@ -1932,9 +1942,24 @@ describe('DeepLClient', () => {
         .get('/v3/languages')
         .query({ resource: 'glossary' })
         .reply(200, [
-          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
-          { lang: 'fr', name: 'French', usable_as_source: true, usable_as_target: true },
+          {
+            lang: 'en',
+            name: 'English',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'fr',
+            name: 'French',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
         ]);
 
       const pairs = await client.getGlossaryLanguages();
@@ -1952,8 +1977,18 @@ describe('DeepLClient', () => {
         .get('/v3/languages')
         .query({ resource: 'glossary' })
         .reply(200, [
-          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
-          { lang: 'xx', name: 'Target Only', usable_as_source: false, usable_as_target: true },
+          {
+            lang: 'en',
+            name: 'English',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'xx',
+            name: 'Target Only',
+            usable_as_source: false,
+            usable_as_target: true,
+          },
         ]);
 
       const pairs = await client.getGlossaryLanguages();
@@ -1966,8 +2001,18 @@ describe('DeepLClient', () => {
         .get('/v3/languages')
         .query({ resource: 'glossary' })
         .reply(200, [
-          { lang: 'EN', name: 'English', usable_as_source: true, usable_as_target: false },
-          { lang: 'DE', name: 'German', usable_as_source: false, usable_as_target: true },
+          {
+            lang: 'EN',
+            name: 'English',
+            usable_as_source: true,
+            usable_as_target: false,
+          },
+          {
+            lang: 'DE',
+            name: 'German',
+            usable_as_source: false,
+            usable_as_target: true,
+          },
         ]);
 
       const pairs = await client.getGlossaryLanguages();
@@ -1994,7 +2039,9 @@ describe('DeepLClient', () => {
           message: 'Authentication failed',
         });
 
-      await expect(client.getGlossaryLanguages()).rejects.toThrow('Authentication failed');
+      await expect(client.getGlossaryLanguages()).rejects.toThrow(
+        'Authentication failed'
+      );
     });
 
     it('should handle network errors', async () => {
@@ -2105,9 +2152,15 @@ describe('DeepLClient', () => {
               version: 1,
               creation_time: '2024-01-01T00:00:00Z',
               updated_time: '2024-01-02T00:00:00Z',
-              configured_rules: { punctuation: { quotation_mark: 'use_guillemets' } },
+              configured_rules: {
+                punctuation: { quotation_mark: 'use_guillemets' },
+              },
               custom_instructions: [
-                { label: 'Instruction 1', prompt: 'Do this', source_language: 'en' },
+                {
+                  label: 'Instruction 1',
+                  prompt: 'Do this',
+                  source_language: 'en',
+                },
               ],
             },
           ],
@@ -2117,7 +2170,9 @@ describe('DeepLClient', () => {
 
       expect(rules).toHaveLength(1);
       const detailed = rules[0] as any;
-      expect(detailed.configuredRules).toEqual({ punctuation: { quotation_mark: 'use_guillemets' } });
+      expect(detailed.configuredRules).toEqual({
+        punctuation: { quotation_mark: 'use_guillemets' },
+      });
       expect(detailed.customInstructions).toEqual([
         { label: 'Instruction 1', prompt: 'Do this', sourceLanguage: 'en' },
       ]);
@@ -2137,11 +2192,9 @@ describe('DeepLClient', () => {
     });
 
     it('should handle empty results', async () => {
-      nock(baseUrl)
-        .get('/v3/style_rules')
-        .reply(200, {
-          style_rules: [],
-        });
+      nock(baseUrl).get('/v3/style_rules').reply(200, {
+        style_rules: [],
+      });
 
       const rules = await client.getStyleRules();
 
@@ -2149,13 +2202,13 @@ describe('DeepLClient', () => {
     });
 
     it('should handle API errors', async () => {
-      nock(baseUrl)
-        .get('/v3/style_rules')
-        .reply(403, {
-          message: 'Authentication failed',
-        });
+      nock(baseUrl).get('/v3/style_rules').reply(403, {
+        message: 'Authentication failed',
+      });
 
-      await expect(client.getStyleRules()).rejects.toThrow('Authentication failed');
+      await expect(client.getStyleRules()).rejects.toThrow(
+        'Authentication failed'
+      );
     });
   });
 
@@ -2167,7 +2220,9 @@ describe('DeepLClient', () => {
           return params.get('tag_handling_version') === 'v2';
         })
         .reply(200, {
-          translations: [{ text: '<p>Hola</p>', detected_source_language: 'EN' }],
+          translations: [
+            { text: '<p>Hola</p>', detected_source_language: 'EN' },
+          ],
         });
 
       await client.translate('<p>Hello</p>', {
@@ -2201,7 +2256,9 @@ describe('DeepLClient', () => {
           return params.get('tag_handling_version') === 'v2';
         })
         .reply(200, {
-          translations: [{ text: '<p>Hola</p>', detected_source_language: 'EN' }],
+          translations: [
+            { text: '<p>Hola</p>', detected_source_language: 'EN' },
+          ],
         });
 
       await client.translate('<p>Hello</p>', {
@@ -2219,7 +2276,9 @@ describe('DeepLClient', () => {
           return params.get('tag_handling_version') === 'v1';
         })
         .reply(200, {
-          translations: [{ text: '<p>Hola</p>', detected_source_language: 'EN' }],
+          translations: [
+            { text: '<p>Hola</p>', detected_source_language: 'EN' },
+          ],
         });
 
       await client.translate('<p>Hello</p>', {
@@ -2260,9 +2319,7 @@ describe('DeepLClient', () => {
       });
 
       it('should handle empty list', async () => {
-        nock(baseUrl)
-          .get('/v2/admin/developer-keys')
-          .reply(200, []);
+        nock(baseUrl).get('/v2/admin/developer-keys').reply(200, []);
 
         const keys = await client.listApiKeys();
         expect(keys).toHaveLength(0);
@@ -2273,7 +2330,9 @@ describe('DeepLClient', () => {
           .get('/v2/admin/developer-keys')
           .reply(403, { message: 'Authentication failed' });
 
-        await expect(client.listApiKeys()).rejects.toThrow('Authentication failed');
+        await expect(client.listApiKeys()).rejects.toThrow(
+          'Authentication failed'
+        );
       });
     });
 
@@ -2294,14 +2353,12 @@ describe('DeepLClient', () => {
       });
 
       it('should create a key without label', async () => {
-        nock(baseUrl)
-          .post('/v2/admin/developer-keys', {})
-          .reply(200, {
-            key_id: 'key-new',
-            label: '',
-            creation_time: '2024-01-01T00:00:00Z',
-            is_deactivated: false,
-          });
+        nock(baseUrl).post('/v2/admin/developer-keys', {}).reply(200, {
+          key_id: 'key-new',
+          label: '',
+          creation_time: '2024-01-01T00:00:00Z',
+          is_deactivated: false,
+        });
 
         const key = await client.createApiKey();
         expect(key.keyId).toBe('key-new');
@@ -2321,28 +2378,43 @@ describe('DeepLClient', () => {
     describe('renameApiKey', () => {
       it('should rename a key', async () => {
         nock(baseUrl)
-          .put('/v2/admin/developer-keys/label', { key_id: 'key-1', label: 'New Name' })
+          .put('/v2/admin/developer-keys/label', {
+            key_id: 'key-1',
+            label: 'New Name',
+          })
           .reply(204);
 
-        await expect(client.renameApiKey('key-1', 'New Name')).resolves.toBeUndefined();
+        await expect(
+          client.renameApiKey('key-1', 'New Name')
+        ).resolves.toBeUndefined();
       });
     });
 
     describe('setApiKeyLimit', () => {
       it('should set a character limit', async () => {
         nock(baseUrl)
-          .put('/v2/admin/developer-keys/limits', { key_id: 'key-1', characters: 500000 })
+          .put('/v2/admin/developer-keys/limits', {
+            key_id: 'key-1',
+            characters: 500000,
+          })
           .reply(204);
 
-        await expect(client.setApiKeyLimit('key-1', 500000)).resolves.toBeUndefined();
+        await expect(
+          client.setApiKeyLimit('key-1', 500000)
+        ).resolves.toBeUndefined();
       });
 
       it('should remove limit with null', async () => {
         nock(baseUrl)
-          .put('/v2/admin/developer-keys/limits', { key_id: 'key-1', characters: null })
+          .put('/v2/admin/developer-keys/limits', {
+            key_id: 'key-1',
+            characters: null,
+          })
           .reply(204);
 
-        await expect(client.setApiKeyLimit('key-1', null)).resolves.toBeUndefined();
+        await expect(
+          client.setApiKeyLimit('key-1', null)
+        ).resolves.toBeUndefined();
       });
     });
 
@@ -2381,7 +2453,11 @@ describe('DeepLClient', () => {
       it('should pass group_by parameter', async () => {
         nock(baseUrl)
           .get('/v2/admin/analytics')
-          .query({ start_date: '2024-01-01', end_date: '2024-01-31', group_by: 'key' })
+          .query({
+            start_date: '2024-01-01',
+            end_date: '2024-01-31',
+            group_by: 'key',
+          })
           .reply(200, {
             usage_report: {
               total_usage: {
diff --git a/tests/unit/detect-command.test.ts b/tests/unit/detect-command.test.ts
index 732fefd3..cafc0e60 100644
--- a/tests/unit/detect-command.test.ts
+++ b/tests/unit/detect-command.test.ts
@@ -2,8 +2,6 @@
  * Tests for Detect Command
  */
 
- 
-
 import { DetectCommand } from '../../src/cli/commands/detect';
 import { createMockDetectService } from '../helpers/mock-factories';
 
@@ -45,17 +43,20 @@ describe('DetectCommand', () => {
       { text: 'Bonjour le monde', code: 'fr', name: 'French' },
       { text: 'Hallo Welt', code: 'de', name: 'German' },
       { text: 'こんにちは世界', code: 'ja', name: 'Japanese' },
-    ])('should detect $name ($code) from text', async ({ text, code, name }) => {
-      mockService.detect = jest.fn().mockResolvedValue({
-        detectedLanguage: code,
-        languageName: name,
-      });
+    ])(
+      'should detect $name ($code) from text',
+      async ({ text, code, name }) => {
+        mockService.detect = jest.fn().mockResolvedValue({
+          detectedLanguage: code,
+          languageName: name,
+        });
 
-      const result = await detectCommand.detect(text);
+        const result = await detectCommand.detect(text);
 
-      expect(result.detectedLanguage).toBe(code);
-      expect(result.languageName).toBe(name);
-    });
+        expect(result.detectedLanguage).toBe(code);
+        expect(result.languageName).toBe(name);
+      }
+    );
 
     it('should delegate to service', async () => {
       await detectCommand.detect('Bonjour');
@@ -67,9 +68,11 @@ describe('DetectCommand', () => {
       { scenario: 'empty text', input: '' },
       { scenario: 'whitespace-only text', input: '   ' },
     ])('should throw error for $scenario', async ({ input }) => {
-      mockService.detect = jest.fn().mockRejectedValue(
-        new Error('Text cannot be empty. Provide text to detect language.')
-      );
+      mockService.detect = jest
+        .fn()
+        .mockRejectedValue(
+          new Error('Text cannot be empty. Provide text to detect language.')
+        );
 
       await expect(detectCommand.detect(input)).rejects.toThrow(
         'Text cannot be empty'
@@ -77,9 +80,13 @@ describe('DetectCommand', () => {
     });
 
     it('should throw error when API returns no detected language', async () => {
-      mockService.detect = jest.fn().mockRejectedValue(
-        new Error('Could not detect source language. The text may be too short or ambiguous.')
-      );
+      mockService.detect = jest
+        .fn()
+        .mockRejectedValue(
+          new Error(
+            'Could not detect source language. The text may be too short or ambiguous.'
+          )
+        );
 
       await expect(detectCommand.detect('x')).rejects.toThrow(
         'Could not detect source language'
@@ -87,17 +94,17 @@ describe('DetectCommand', () => {
     });
 
     it('should handle API errors', async () => {
-      mockService.detect = jest.fn().mockRejectedValue(
-        new Error('API error')
-      );
+      mockService.detect = jest.fn().mockRejectedValue(new Error('API error'));
 
-      await expect(detectCommand.detect('Bonjour')).rejects.toThrow('API error');
+      await expect(detectCommand.detect('Bonjour')).rejects.toThrow(
+        'API error'
+      );
     });
 
     it('should handle authentication errors', async () => {
-      mockService.detect = jest.fn().mockRejectedValue(
-        new Error('Authentication failed: Invalid API key')
-      );
+      mockService.detect = jest
+        .fn()
+        .mockRejectedValue(new Error('Authentication failed: Invalid API key'));
 
       await expect(detectCommand.detect('Bonjour')).rejects.toThrow(
         'Authentication failed: Invalid API key'
@@ -105,9 +112,9 @@ describe('DetectCommand', () => {
     });
 
     it('should handle quota exceeded errors', async () => {
-      mockService.detect = jest.fn().mockRejectedValue(
-        new Error('Quota exceeded')
-      );
+      mockService.detect = jest
+        .fn()
+        .mockRejectedValue(new Error('Quota exceeded'));
 
       await expect(detectCommand.detect('Bonjour')).rejects.toThrow(
         'Quota exceeded'
@@ -141,16 +148,27 @@ describe('DetectCommand', () => {
 
   describe('formatPlain()', () => {
     it.each([
-      { code: 'fr', name: 'French', expected: 'Detected language: French (fr)' },
-      { code: 'de', name: 'German', expected: 'Detected language: German (de)' },
-    ])('should format $name ($code) as plain text', ({ code, name, expected }) => {
-      const output = detectCommand.formatPlain({
-        detectedLanguage: code as any,
-        languageName: name,
-      });
-
-      expect(output).toBe(expected);
-    });
+      {
+        code: 'fr',
+        name: 'French',
+        expected: 'Detected language: French (fr)',
+      },
+      {
+        code: 'de',
+        name: 'German',
+        expected: 'Detected language: German (de)',
+      },
+    ])(
+      'should format $name ($code) as plain text',
+      ({ code, name, expected }) => {
+        const output = detectCommand.formatPlain({
+          detectedLanguage: code as any,
+          languageName: name,
+        });
+
+        expect(output).toBe(expected);
+      }
+    );
   });
 
   describe('formatJson()', () => {
diff --git a/tests/unit/detect-service.test.ts b/tests/unit/detect-service.test.ts
index 0d5e72c7..68164ffb 100644
--- a/tests/unit/detect-service.test.ts
+++ b/tests/unit/detect-service.test.ts
@@ -73,7 +73,9 @@ describe('DetectService', () => {
     });
     const service = new DetectService(mockClient);
 
-    await expect(service.detect('x')).rejects.toThrow('Could not detect source language');
+    await expect(service.detect('x')).rejects.toThrow(
+      'Could not detect source language'
+    );
   });
 
   it('should propagate API errors', async () => {
diff --git a/tests/unit/directory-translation-handler.test.ts b/tests/unit/directory-translation-handler.test.ts
index e91c362d..c4dfcbef 100644
--- a/tests/unit/directory-translation-handler.test.ts
+++ b/tests/unit/directory-translation-handler.test.ts
@@ -19,15 +19,24 @@ import { DirectoryTranslationHandler } from '../../src/cli/commands/translate/di
 import { BatchTranslationService } from '../../src/services/batch-translation';
 import { ValidationError } from '../../src/utils/errors';
 import { Logger } from '../../src/utils/logger';
-import type { HandlerContext, TranslateOptions } from '../../src/cli/commands/translate/types';
+import type {
+  HandlerContext,
+  TranslateOptions,
+} from '../../src/cli/commands/translate/types';
 
 jest.mock('../../src/services/translation');
 
 jest.mock('ora', () => {
   const mockSpinner = {
-    start: jest.fn(function(this: any) { return this; }),
-    succeed: jest.fn(function(this: any) { return this; }),
-    fail: jest.fn(function(this: any) { return this; }),
+    start: jest.fn(function (this: any) {
+      return this;
+    }),
+    succeed: jest.fn(function (this: any) {
+      return this;
+    }),
+    fail: jest.fn(function (this: any) {
+      return this;
+    }),
     text: '',
   };
   return jest.fn(() => mockSpinner);
@@ -85,7 +94,11 @@ describe('FileTranslationService – directory/multi-target handler', () => {
         { targetLang: 'es', text: 'Hola mundo' },
       ]);
 
-      const results = await service.translateFileToMultiple(inputPath, ['de', 'fr', 'es']);
+      const results = await service.translateFileToMultiple(inputPath, [
+        'de',
+        'fr',
+        'es',
+      ]);
 
       expect(results).toHaveLength(3);
       expect(results[0]?.targetLang).toBe('de');
@@ -115,7 +128,9 @@ describe('FileTranslationService – directory/multi-target handler', () => {
       expect(results[1]?.outputPath).toBe(path.join(outputDir, 'doc.ja.txt'));
 
       expect(fs.readFileSync(results[0]!.outputPath!, 'utf-8')).toBe('Hallo');
-      expect(fs.readFileSync(results[1]!.outputPath!, 'utf-8')).toBe('こんにちは');
+      expect(fs.readFileSync(results[1]!.outputPath!, 'utf-8')).toBe(
+        'こんにちは'
+      );
     });
 
     it('should create output directory if it does not exist', async () => {
@@ -128,7 +143,9 @@ describe('FileTranslationService – directory/multi-target handler', () => {
 
       const nested = path.join(testDir, 'a', 'b', 'c');
 
-      await service.translateFileToMultiple(inputPath, ['es'], { outputDir: nested });
+      await service.translateFileToMultiple(inputPath, ['es'], {
+        outputDir: nested,
+      });
 
       expect(fs.existsSync(path.join(nested, 'file.es.txt'))).toBe(true);
     });
@@ -154,11 +171,9 @@ describe('FileTranslationService – directory/multi-target handler', () => {
         { targetLang: 'fr', text: '# Bonjour' },
       ]);
 
-      const results = await service.translateFileToMultiple(
-        inputPath,
-        ['fr'],
-        { outputDir: testDir }
-      );
+      const results = await service.translateFileToMultiple(inputPath, ['fr'], {
+        outputDir: testDir,
+      });
 
       expect(results[0]?.outputPath).toBe(path.join(testDir, 'readme.fr.md'));
     });
@@ -216,10 +231,13 @@ describe('FileTranslationService – directory/multi-target handler', () => {
       fs.writeFileSync(inputPath, JSON.stringify({ key: 'Hello' }, null, 2));
 
       // The structured service is lazily loaded; mock translateBatch for it
-      mockTranslationService.translateBatch.mockImplementation(async (_texts, opts) => {
-        if (opts.targetLang === 'de') return [{ text: 'Hallo', detectedSourceLang: 'en' }];
-        return [];
-      });
+      mockTranslationService.translateBatch.mockImplementation(
+        async (_texts, opts) => {
+          if (opts.targetLang === 'de')
+            return [{ text: 'Hallo', detectedSourceLang: 'en' }];
+          return [];
+        }
+      );
 
       const results = await service.translateFileToMultiple(inputPath, ['de']);
 
@@ -278,7 +296,9 @@ describe('DirectoryTranslationHandler', () => {
     const translateUtilsMock = jest.requireMock(
       '../../src/cli/commands/translate/translate-utils'
     );
-    translateUtilsMock.buildTranslationOptions.mockReturnValue({ targetLang: 'de' });
+    translateUtilsMock.buildTranslationOptions.mockReturnValue({
+      targetLang: 'de',
+    });
 
     mockBatchService = {
       translateDirectory: jest.fn().mockResolvedValue({
@@ -297,7 +317,8 @@ describe('DirectoryTranslationHandler', () => {
     ctx = {
       translationService: createMockTranslationService(),
       fileTranslationService: createMockFileTranslationService(),
-      batchTranslationService: mockBatchService as unknown as BatchTranslationService,
+      batchTranslationService:
+        mockBatchService as unknown as BatchTranslationService,
       documentTranslationService: createMockDocumentTranslationService(),
       glossaryService: createMockGlossaryService(),
       config: createMockConfigService(),
@@ -321,15 +342,17 @@ describe('DirectoryTranslationHandler', () => {
     it('should throw ValidationError when output is not provided', async () => {
       const options: TranslateOptions = { to: 'de' };
 
-      await expect(handler.translateDirectory('/some/dir', options))
-        .rejects.toThrow(ValidationError);
+      await expect(
+        handler.translateDirectory('/some/dir', options)
+      ).rejects.toThrow(ValidationError);
     });
 
     it('should include helpful message about --output flag', async () => {
       const options: TranslateOptions = { to: 'de' };
 
-      await expect(handler.translateDirectory('/some/dir', options))
-        .rejects.toThrow('Output directory is required');
+      await expect(
+        handler.translateDirectory('/some/dir', options)
+      ).rejects.toThrow('Output directory is required');
     });
   });
 
@@ -442,7 +465,7 @@ describe('DirectoryTranslationHandler', () => {
 
       expect(validateTranslationLanguages).toHaveBeenCalledWith(
         ['de', 'fr'],
-        expect.anything(),
+        expect.anything()
       );
     });
 
@@ -452,9 +475,13 @@ describe('DirectoryTranslationHandler', () => {
       // every file failed for its own reason gets.
       mockBatchService.translateDirectory.mockResolvedValue({
         successful: [],
-        failed: [{ file: 'a.txt', error: "Value for 'target_lang' not supported." }],
+        failed: [
+          { file: 'a.txt', error: "Value for 'target_lang' not supported." },
+        ],
         skipped: [],
-        requestRejected: new ValidationError("Value for 'target_lang' not supported."),
+        requestRejected: new ValidationError(
+          "Value for 'target_lang' not supported."
+        ),
       });
       mockBatchService.getStatistics.mockReturnValue({
         total: 1,
@@ -545,7 +572,10 @@ describe('DirectoryTranslationHandler', () => {
           skipped: [],
         }),
         getStatistics: jest.fn().mockReturnValue({
-          total: 1, successful: 1, failed: 0, skipped: 0,
+          total: 1,
+          successful: 1,
+          failed: 0,
+          skipped: 0,
         }),
       }));
 
@@ -556,10 +586,10 @@ describe('DirectoryTranslationHandler', () => {
 
       await handler.translateDirectory('/some/dir', options);
 
-      expect(MockedBTS).toHaveBeenCalledWith(
-        ctx.fileTranslationService,
-        { concurrency: 10, translationService: ctx.translationService }
-      );
+      expect(MockedBTS).toHaveBeenCalledWith(ctx.fileTranslationService, {
+        concurrency: 10,
+        translationService: ctx.translationService,
+      });
     });
 
     it('should not create new BatchTranslationService when concurrency is not set', async () => {
@@ -760,23 +790,27 @@ describe('DirectoryTranslationHandler', () => {
       const error = new Error('Translation service unavailable');
       mockBatchService.translateDirectory.mockRejectedValue(error);
 
-      await expect(handler.translateDirectory('/some/dir', baseOptions))
-        .rejects.toThrow('Translation service unavailable');
+      await expect(
+        handler.translateDirectory('/some/dir', baseOptions)
+      ).rejects.toThrow('Translation service unavailable');
     });
 
     it('should rethrow the exact error instance', async () => {
       const error = new Error('Specific error');
       mockBatchService.translateDirectory.mockRejectedValue(error);
 
-      await expect(handler.translateDirectory('/some/dir', baseOptions))
-        .rejects.toBe(error);
+      await expect(
+        handler.translateDirectory('/some/dir', baseOptions)
+      ).rejects.toBe(error);
     });
   });
 
   describe('spinner behavior', () => {
     function setupSpinnerMock() {
       const mockSpinner = {
-        start: jest.fn(function(this: any) { return this; }),
+        start: jest.fn(function (this: any) {
+          return this;
+        }),
         succeed: jest.fn(),
         fail: jest.fn(),
         text: '',
@@ -791,8 +825,9 @@ describe('DirectoryTranslationHandler', () => {
       (Logger.shouldShowSpinner as jest.Mock).mockReturnValue(true);
       mockBatchService.translateDirectory.mockRejectedValue(new Error('fail'));
 
-      await expect(handler.translateDirectory('/some/dir', baseOptions))
-        .rejects.toThrow('fail');
+      await expect(
+        handler.translateDirectory('/some/dir', baseOptions)
+      ).rejects.toThrow('fail');
 
       expect(mockSpinner.fail).toHaveBeenCalledWith('Translation failed');
     });
@@ -831,7 +866,10 @@ describe('DirectoryTranslationHandler', () => {
 
       await handler.translateDirectory('/some/dir', baseOptions);
 
-      expect(removeListenerSpy).toHaveBeenCalledWith('SIGINT', expect.any(Function));
+      expect(removeListenerSpy).toHaveBeenCalledWith(
+        'SIGINT',
+        expect.any(Function)
+      );
       removeListenerSpy.mockRestore();
     });
 
@@ -839,10 +877,14 @@ describe('DirectoryTranslationHandler', () => {
       const removeListenerSpy = jest.spyOn(process, 'removeListener');
       mockBatchService.translateDirectory.mockRejectedValue(new Error('fail'));
 
-      await expect(handler.translateDirectory('/some/dir', baseOptions))
-        .rejects.toThrow();
+      await expect(
+        handler.translateDirectory('/some/dir', baseOptions)
+      ).rejects.toThrow();
 
-      expect(removeListenerSpy).toHaveBeenCalledWith('SIGINT', expect.any(Function));
+      expect(removeListenerSpy).toHaveBeenCalledWith(
+        'SIGINT',
+        expect.any(Function)
+      );
       removeListenerSpy.mockRestore();
     });
 
@@ -852,9 +894,11 @@ describe('DirectoryTranslationHandler', () => {
 
       await handler.translateDirectory('/some/dir', baseOptions);
 
-      const sigintOnCall = onSpy.mock.calls.find(call => call[0] === 'SIGINT');
+      const sigintOnCall = onSpy.mock.calls.find(
+        (call) => call[0] === 'SIGINT'
+      );
       const sigintRemoveCall = removeListenerSpy.mock.calls.find(
-        call => call[0] === 'SIGINT'
+        (call) => call[0] === 'SIGINT'
       );
 
       expect(sigintOnCall).toBeDefined();
diff --git a/tests/unit/docs/documented-surface.test.ts b/tests/unit/docs/documented-surface.test.ts
index f41bf5b4..a5a35a1f 100644
--- a/tests/unit/docs/documented-surface.test.ts
+++ b/tests/unit/docs/documented-surface.test.ts
@@ -18,10 +18,21 @@ interface DescribedCommand {
 
 const ROOT = path.join(__dirname, '..', '..', '..');
 const CLI_ENTRY = path.join(ROOT, 'dist', 'cli', 'index.js');
-const DOCS = ['README.md', 'docs/API.md', 'docs/SYNC.md', 'docs/TROUBLESHOOTING.md'];
+const DOCS = [
+  'README.md',
+  'docs/API.md',
+  'docs/SYNC.md',
+  'docs/TROUBLESHOOTING.md',
+];
 
 /** Deliberate misspellings used to demonstrate did-you-mean suggestions. */
-const TYPO_EXAMPLES = new Set(['transalte', 'translte', 'glossry', 'conifg', 'descibe']);
+const TYPO_EXAMPLES = new Set([
+  'transalte',
+  'translte',
+  'glossry',
+  'conifg',
+  'descibe',
+]);
 
 const LANGUAGE_CODES = getAllLanguageCodes();
 
@@ -30,9 +41,13 @@ function longFlags(options: { flags: string }[]): string[] {
 }
 
 function describeSurface(): DescribedCommand {
-  const raw = execFileSync(process.execPath, [CLI_ENTRY, '_describe', '--format', 'json'], {
-    encoding: 'utf-8',
-  });
+  const raw = execFileSync(
+    process.execPath,
+    [CLI_ENTRY, '_describe', '--format', 'json'],
+    {
+      encoding: 'utf-8',
+    }
+  );
   return JSON.parse(raw) as DescribedCommand;
 }
 
@@ -42,14 +57,19 @@ describe('documented CLI surface', () => {
 
   beforeAll(() => {
     surface = describeSurface();
-    globalFlags = new Set([...longFlags(surface.options), '--help', '--version']);
+    globalFlags = new Set([
+      ...longFlags(surface.options),
+      '--help',
+      '--version',
+    ]);
   });
 
   function resolveCommand(tokens: string[]): DescribedCommand | undefined {
     let current: DescribedCommand | undefined = surface;
     for (const token of tokens) {
       current = current?.commands.find(
-        (candidate) => candidate.name === token || candidate.aliases.includes(token),
+        (candidate) =>
+          candidate.name === token || candidate.aliases.includes(token)
       );
       if (!current) return undefined;
     }
@@ -78,7 +98,9 @@ describe('documented CLI surface', () => {
     let documented: string[];
 
     beforeAll(() => {
-      documented = invocations(fs.readFileSync(path.join(ROOT, docPath), 'utf-8'));
+      documented = invocations(
+        fs.readFileSync(path.join(ROOT, docPath), 'utf-8')
+      );
     });
 
     it('documents at least one invocation', () => {
@@ -89,7 +111,10 @@ describe('documented CLI surface', () => {
       const unknown = documented.filter((invocation) => {
         const tokens = commandTokens(invocation);
         if (tokens.length === 0 || TYPO_EXAMPLES.has(tokens[0]!)) return false;
-        return resolveCommand(tokens) === undefined && resolveCommand([tokens[0]!]) === undefined;
+        return (
+          resolveCommand(tokens) === undefined &&
+          resolveCommand([tokens[0]!]) === undefined
+        );
       });
 
       expect(unknown).toEqual([]);
@@ -105,12 +130,16 @@ describe('documented CLI surface', () => {
         const command = resolveCommand(tokens) ?? resolveCommand([tokens[0]!]);
         if (!command) continue;
 
-        const accepted = new Set([...longFlags(command.options), ...globalFlags]);
+        const accepted = new Set([
+          ...longFlags(command.options),
+          ...globalFlags,
+        ]);
         // A flag may belong to a subcommand named after the first flag-free
         // tokens, so accept anything the parent chain declares too.
         for (let depth = 1; depth < tokens.length; depth++) {
           const ancestor = resolveCommand(tokens.slice(0, depth));
-          if (ancestor) longFlags(ancestor.options).forEach((flag) => accepted.add(flag));
+          if (ancestor)
+            longFlags(ancestor.options).forEach((flag) => accepted.add(flag));
         }
 
         for (const flag of invocation.match(/--[a-z0-9-]+/g) ?? []) {
@@ -129,7 +158,9 @@ describe('documented CLI surface', () => {
       // and copying it into a script that compares codes gives a wrong answer.
       // Matched against the registry so markdown badges like `[![CI](...)]` and
       // labels that are not languages are left alone.
-      const lines = fs.readFileSync(path.join(ROOT, docPath), 'utf-8').split('\n');
+      const lines = fs
+        .readFileSync(path.join(ROOT, docPath), 'utf-8')
+        .split('\n');
       const offenders: string[] = [];
 
       for (const line of lines) {
@@ -185,7 +216,7 @@ describe('documented CLI surface', () => {
 
     it('lists no command the CLI does not provide', () => {
       const unknown = [...groupedCommands()].filter(
-        (name) => resolveCommand([name]) === undefined,
+        (name) => resolveCommand([name]) === undefined
       );
 
       expect(unknown).toEqual([]);
diff --git a/tests/unit/docs/sync-terminology.test.ts b/tests/unit/docs/sync-terminology.test.ts
index 41cefe5c..4d71e764 100644
--- a/tests/unit/docs/sync-terminology.test.ts
+++ b/tests/unit/docs/sync-terminology.test.ts
@@ -43,7 +43,7 @@ function stripExemptRegions(source: string): string {
   // Blank out fenced code blocks while preserving line count so failure
   // messages cite the real line number in the source doc.
   let out = source.replace(/```[\s\S]*?```/g, (match) =>
-    match.replace(/[^\n]/g, ''),
+    match.replace(/[^\n]/g, '')
   );
   // Drop inline code spans (single-line, so line count is unaffected).
   out = out.replace(/`[^`\n]*`/g, '');
@@ -69,7 +69,7 @@ describe('sync terminology regression', () => {
           proseLines.forEach((line, idx) => {
             if (pattern.test(line)) {
               const tolerated = TOLERATED.some(
-                (t) => t.doc === rel && line.includes(t.snippet),
+                (t) => t.doc === rel && line.includes(t.snippet)
               );
               if (!tolerated) {
                 hits.push(`  ${rel}:${idx + 1}: ${line.trim()}`);
diff --git a/tests/unit/document-client.test.ts b/tests/unit/document-client.test.ts
index b0ae55d6..891ad0cc 100644
--- a/tests/unit/document-client.test.ts
+++ b/tests/unit/document-client.test.ts
@@ -25,7 +25,9 @@ describe('DocumentClient', () => {
     jest.spyOn(axios, 'isAxiosError').mockReturnValue(false);
 
     client = new DocumentClient('test-api-key');
-    jest.spyOn(HttpClient.prototype, 'sleep' as any).mockResolvedValue(undefined);
+    jest
+      .spyOn(HttpClient.prototype, 'sleep' as any)
+      .mockResolvedValue(undefined);
   });
 
   afterAll(() => {
@@ -45,7 +47,7 @@ describe('DocumentClient', () => {
       expect(mockedAxios.create).toHaveBeenCalledWith(
         expect.objectContaining({
           baseURL: 'https://api-free.deepl.com',
-        }),
+        })
       );
     });
 
@@ -54,7 +56,7 @@ describe('DocumentClient', () => {
       expect(mockedAxios.create).toHaveBeenCalledWith(
         expect.objectContaining({
           baseURL: 'https://api.deepl.com',
-        }),
+        })
       );
     });
   });
@@ -81,7 +83,7 @@ describe('DocumentClient', () => {
         expect.objectContaining({
           method: 'POST',
           url: '/v2/document',
-        }),
+        })
       );
     });
 
@@ -135,10 +137,15 @@ describe('DocumentClient', () => {
 
       const getMultipartBody = (): string => {
         const call = mockAxiosInstance.request.mock.calls[0]?.[0];
-        return (call?.data?.getBuffer?.() as Buffer | undefined)?.toString('utf8') ?? '';
+        return (
+          (call?.data?.getBuffer?.() as Buffer | undefined)?.toString('utf8') ??
+          ''
+        );
       };
 
-      const upload = async (options: Record<string, unknown>): Promise<void> => {
+      const upload = async (
+        options: Record<string, unknown>
+      ): Promise<void> => {
         await client.uploadDocument(Buffer.from('content'), {
           targetLang: 'de',
           filename: 'doc.txt',
@@ -187,13 +194,15 @@ describe('DocumentClient', () => {
 
       it('should reject more than five glossaries before uploading', async () => {
         await expect(
-          upload({ glossaryIds: [A, B, A, B, A, B] }),
+          upload({ glossaryIds: [A, B, A, B, A, B] })
         ).rejects.toThrow(/maximum of 5 glossaries/);
         expect(mockAxiosInstance.request).not.toHaveBeenCalled();
       });
 
       it('should reject glossaryId combined with glossaryIds', async () => {
-        await expect(upload({ glossaryId: A, glossaryIds: [B] })).rejects.toThrow(/Cannot combine/);
+        await expect(
+          upload({ glossaryId: A, glossaryIds: [B] })
+        ).rejects.toThrow(/Cannot combine/);
         expect(mockAxiosInstance.request).not.toHaveBeenCalled();
       });
     });
@@ -284,7 +293,11 @@ describe('DocumentClient', () => {
     it('should handle API errors', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 429, data: { message: 'Too many requests' }, headers: {} },
+        response: {
+          status: 429,
+          data: { message: 'Too many requests' },
+          headers: {},
+        },
         message: 'Rate limited',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -315,14 +328,18 @@ describe('DocumentClient', () => {
         expect.objectContaining({
           method: 'POST',
           url: '/v2/document/doc-123/result',
-        }),
+        })
       );
     });
 
     it('should handle API errors during download', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 503, data: { message: 'Service unavailable' }, headers: {} },
+        response: {
+          status: 503,
+          data: { message: 'Service unavailable' },
+          headers: {},
+        },
         message: 'Unavailable',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -377,25 +394,33 @@ describe('DocumentClient', () => {
         headers: {},
       });
 
-      await client.downloadDocument({ documentId: 'doc-1', documentKey: 'key-1' });
+      await client.downloadDocument({
+        documentId: 'doc-1',
+        documentKey: 'key-1',
+      });
 
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
-        expect.objectContaining({ timeout: 300000 }),
+        expect.objectContaining({ timeout: 300000 })
       );
     });
 
     it('should honour an explicitly configured timeout larger than the transfer default', async () => {
-      const slowClient = new DocumentClient('test-api-key', { timeout: 600000 });
+      const slowClient = new DocumentClient('test-api-key', {
+        timeout: 600000,
+      });
       mockAxiosInstance.request.mockResolvedValue({
         data: Buffer.from('content'),
         status: 200,
         headers: {},
       });
 
-      await slowClient.downloadDocument({ documentId: 'doc-1', documentKey: 'key-1' });
+      await slowClient.downloadDocument({
+        documentId: 'doc-1',
+        documentKey: 'key-1',
+      });
 
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
-        expect.objectContaining({ timeout: 600000 }),
+        expect.objectContaining({ timeout: 600000 })
       );
       slowClient.destroy();
     });
@@ -407,10 +432,13 @@ describe('DocumentClient', () => {
         headers: {},
       });
 
-      await client.getDocumentStatus({ documentId: 'doc-1', documentKey: 'key-1' });
+      await client.getDocumentStatus({
+        documentId: 'doc-1',
+        documentKey: 'key-1',
+      });
 
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
-        expect.objectContaining({ timeout: 30000 }),
+        expect.objectContaining({ timeout: 30000 })
       );
     });
   });
diff --git a/tests/unit/document-translation-handler.test.ts b/tests/unit/document-translation-handler.test.ts
index 03b9fb73..4b0611d9 100644
--- a/tests/unit/document-translation-handler.test.ts
+++ b/tests/unit/document-translation-handler.test.ts
@@ -1,5 +1,8 @@
 import { DocumentTranslationHandler } from '../../src/cli/commands/translate/document-translation-handler';
-import type { HandlerContext, TranslateOptions } from '../../src/cli/commands/translate/types';
+import type {
+  HandlerContext,
+  TranslateOptions,
+} from '../../src/cli/commands/translate/types';
 import { ValidationError } from '../../src/utils/errors';
 import {
   createMockTranslationService,
@@ -21,9 +24,15 @@ jest.mock('../../src/utils/logger', () => ({
 }));
 
 const mockSpinner = {
-  start: jest.fn(function(this: any) { return this; }),
-  succeed: jest.fn(function(this: any) { return this; }),
-  fail: jest.fn(function(this: any) { return this; }),
+  start: jest.fn(function (this: any) {
+    return this;
+  }),
+  succeed: jest.fn(function (this: any) {
+    return this;
+  }),
+  fail: jest.fn(function (this: any) {
+    return this;
+  }),
   text: '',
 };
 jest.mock('ora', () => {
@@ -37,7 +46,11 @@ function createMockHandlerContext() {
   const fileTranslationService = createMockFileTranslationService();
   const batchTranslationService = {} as jest.Mocked<BatchTranslationService>;
   const documentTranslationService = createMockDocumentTranslationService({
-    translateDocument: jest.fn().mockResolvedValue({ success: true, outputPath: '/tmp/output.pdf', billedCharacters: 100 }),
+    translateDocument: jest.fn().mockResolvedValue({
+      success: true,
+      outputPath: '/tmp/output.pdf',
+      billedCharacters: 100,
+    }),
   });
   const glossaryService = createMockGlossaryService();
   const config = createMockConfigService({
@@ -56,10 +69,22 @@ function createMockHandlerContext() {
     config,
   };
 
-  return { ctx, mocks: { translationService, fileTranslationService, batchTranslationService, documentTranslationService, glossaryService, config } };
+  return {
+    ctx,
+    mocks: {
+      translationService,
+      fileTranslationService,
+      batchTranslationService,
+      documentTranslationService,
+      glossaryService,
+      config,
+    },
+  };
 }
 
-function defaultOptions(overrides: Partial<TranslateOptions> = {}): TranslateOptions {
+function defaultOptions(
+  overrides: Partial<TranslateOptions> = {}
+): TranslateOptions {
   return { to: 'de', output: '/tmp/output.pdf', cache: true, ...overrides };
 }
 
@@ -69,9 +94,15 @@ describe('DocumentTranslationHandler', () => {
 
   beforeEach(() => {
     jest.clearAllMocks();
-    mockSpinner.start.mockImplementation(function(this: any) { return this; });
-    mockSpinner.succeed.mockImplementation(function(this: any) { return this; });
-    mockSpinner.fail.mockImplementation(function(this: any) { return this; });
+    mockSpinner.start.mockImplementation(function (this: any) {
+      return this;
+    });
+    mockSpinner.succeed.mockImplementation(function (this: any) {
+      return this;
+    });
+    mockSpinner.fail.mockImplementation(function (this: any) {
+      return this;
+    });
     mockSpinner.text = '';
     mockedOra.mockReturnValue(mockSpinner as any);
 
@@ -88,19 +119,30 @@ describe('DocumentTranslationHandler', () => {
   describe('translateDocument()', () => {
     it('should throw ValidationError for stdout output', async () => {
       await expect(
-        handler.translateDocument('/tmp/doc.pdf', defaultOptions({ output: '-' }))
+        handler.translateDocument(
+          '/tmp/doc.pdf',
+          defaultOptions({ output: '-' })
+        )
       ).rejects.toThrow(ValidationError);
       await expect(
-        handler.translateDocument('/tmp/doc.pdf', defaultOptions({ output: '-' }))
+        handler.translateDocument(
+          '/tmp/doc.pdf',
+          defaultOptions({ output: '-' })
+        )
       ).rejects.toThrow('Cannot stream binary document translation to stdout');
     });
 
     it('should call warnIgnoredOptions with supported set', async () => {
       const { Logger: MockLogger } = jest.requireMock('../../src/utils/logger');
 
-      await handler.translateDocument('/tmp/doc.pdf', defaultOptions({ splitSentences: 'on' }));
+      await handler.translateDocument(
+        '/tmp/doc.pdf',
+        defaultOptions({ splitSentences: 'on' })
+      );
 
-      expect(MockLogger.warn).toHaveBeenCalledWith(expect.stringContaining('document'));
+      expect(MockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('document')
+      );
     });
 
     describe('glossaries', () => {
@@ -111,9 +153,10 @@ describe('DocumentTranslationHandler', () => {
         mocks.glossaryService.resolveGlossaryId.mockImplementation(
           async (nameOrId: string) => {
             const id = mapping[nameOrId];
-            if (!id) throw new ValidationError(`Glossary "${nameOrId}" not found`);
+            if (!id)
+              throw new ValidationError(`Glossary "${nameOrId}" not found`);
             return id;
-          },
+          }
         );
       };
 
@@ -122,16 +165,19 @@ describe('DocumentTranslationHandler', () => {
 
         await handler.translateDocument(
           '/tmp/doc.pdf',
-          defaultOptions({ from: 'en', glossary: ['base-terms'] }),
+          defaultOptions({ from: 'en', glossary: ['base-terms'] })
         );
 
-        expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalledWith(
+        expect(
+          mocks.documentTranslationService.translateDocument
+        ).toHaveBeenCalledWith(
           '/tmp/doc.pdf',
           '/tmp/output.pdf',
           expect.objectContaining({ glossaryId: A }),
-          expect.any(Function),
+          expect.any(Function)
         );
-        const passed = mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
+        const passed =
+          mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
         expect(passed?.glossaryIds).toBeUndefined();
       });
 
@@ -140,16 +186,22 @@ describe('DocumentTranslationHandler', () => {
 
         await handler.translateDocument(
           '/tmp/doc.pdf',
-          defaultOptions({ from: 'en', glossary: ['base-terms', 'project-overrides'] }),
+          defaultOptions({
+            from: 'en',
+            glossary: ['base-terms', 'project-overrides'],
+          })
         );
 
-        expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalledWith(
+        expect(
+          mocks.documentTranslationService.translateDocument
+        ).toHaveBeenCalledWith(
           '/tmp/doc.pdf',
           '/tmp/output.pdf',
           expect.objectContaining({ glossaryIds: [A, B] }),
-          expect.any(Function),
+          expect.any(Function)
         );
-        const passed = mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
+        const passed =
+          mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
         expect(passed?.glossaryId).toBeUndefined();
       });
 
@@ -158,28 +210,39 @@ describe('DocumentTranslationHandler', () => {
 
         await handler.translateDocument(
           '/tmp/doc.pdf',
-          defaultOptions({ from: 'en', glossary: ['project-overrides', 'base-terms'] }),
+          defaultOptions({
+            from: 'en',
+            glossary: ['project-overrides', 'base-terms'],
+          })
         );
 
-        expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalledWith(
+        expect(
+          mocks.documentTranslationService.translateDocument
+        ).toHaveBeenCalledWith(
           '/tmp/doc.pdf',
           '/tmp/output.pdf',
           expect.objectContaining({ glossaryIds: [B, A] }),
-          expect.any(Function),
+          expect.any(Function)
         );
       });
 
       it('should no longer warn that document mode ignores --glossary', async () => {
-        const { Logger: MockLogger } = jest.requireMock('../../src/utils/logger');
+        const { Logger: MockLogger } = jest.requireMock(
+          '../../src/utils/logger'
+        );
         resolveTo({ 'base-terms': A });
 
         await handler.translateDocument(
           '/tmp/doc.pdf',
-          defaultOptions({ from: 'en', glossary: ['base-terms'] }),
+          defaultOptions({ from: 'en', glossary: ['base-terms'] })
         );
 
-        const warnings = MockLogger.warn.mock.calls.map((call: unknown[]) => String(call[0]));
-        expect(warnings.some((w: string) => w.includes('--glossary'))).toBe(false);
+        const warnings = MockLogger.warn.mock.calls.map((call: unknown[]) =>
+          String(call[0])
+        );
+        expect(warnings.some((w: string) => w.includes('--glossary'))).toBe(
+          false
+        );
       });
 
       /** The API rejects a document glossary without source_lang. */
@@ -188,20 +251,30 @@ describe('DocumentTranslationHandler', () => {
         resolveTo({ 'base-terms': A });
 
         await expect(
-          handler.translateDocument('/tmp/doc.pdf', defaultOptions({ glossary: ['base-terms'] })),
+          handler.translateDocument(
+            '/tmp/doc.pdf',
+            defaultOptions({ glossary: ['base-terms'] })
+          )
         ).rejects.toThrow(ValidationError);
         try {
-          await handler.translateDocument('/tmp/doc.pdf', defaultOptions({ glossary: ['base-terms'] }));
+          await handler.translateDocument(
+            '/tmp/doc.pdf',
+            defaultOptions({ glossary: ['base-terms'] })
+          );
         } catch (error) {
           expect((error as ValidationError).message).toContain('--from');
         }
-        expect(mocks.documentTranslationService.translateDocument).not.toHaveBeenCalled();
+        expect(
+          mocks.documentTranslationService.translateDocument
+        ).not.toHaveBeenCalled();
       });
 
       it('should not require --from when no glossary is given', async () => {
         await handler.translateDocument('/tmp/doc.pdf', defaultOptions());
 
-        expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalled();
+        expect(
+          mocks.documentTranslationService.translateDocument
+        ).toHaveBeenCalled();
       });
 
       it('should fail without uploading when a glossary name does not resolve', async () => {
@@ -210,16 +283,25 @@ describe('DocumentTranslationHandler', () => {
         await expect(
           handler.translateDocument(
             '/tmp/doc.pdf',
-            defaultOptions({ from: 'en', glossary: ['base-terms', 'no-such-glossary'] }),
-          ),
+            defaultOptions({
+              from: 'en',
+              glossary: ['base-terms', 'no-such-glossary'],
+            })
+          )
         ).rejects.toThrow(/no-such-glossary/);
-        expect(mocks.documentTranslationService.translateDocument).not.toHaveBeenCalled();
+        expect(
+          mocks.documentTranslationService.translateDocument
+        ).not.toHaveBeenCalled();
       });
 
       it('should send no glossary params when the flag is absent', async () => {
-        await handler.translateDocument('/tmp/doc.pdf', defaultOptions({ from: 'en' }));
+        await handler.translateDocument(
+          '/tmp/doc.pdf',
+          defaultOptions({ from: 'en' })
+        );
 
-        const passed = mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
+        const passed =
+          mocks.documentTranslationService.translateDocument.mock.calls[0]?.[2];
         expect(passed?.glossaryId).toBeUndefined();
         expect(passed?.glossaryIds).toBeUndefined();
         expect(mocks.glossaryService.resolveGlossaryId).not.toHaveBeenCalled();
@@ -227,9 +309,14 @@ describe('DocumentTranslationHandler', () => {
     });
 
     it('should pass outputFormat through', async () => {
-      await handler.translateDocument('/tmp/doc.pdf', defaultOptions({ outputFormat: 'pdf' }));
+      await handler.translateDocument(
+        '/tmp/doc.pdf',
+        defaultOptions({ outputFormat: 'pdf' })
+      );
 
-      expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalledWith(
+      expect(
+        mocks.documentTranslationService.translateDocument
+      ).toHaveBeenCalledWith(
         '/tmp/doc.pdf',
         '/tmp/output.pdf',
         expect.objectContaining({ outputFormat: 'pdf' }),
@@ -238,9 +325,14 @@ describe('DocumentTranslationHandler', () => {
     });
 
     it('should set enableDocumentMinification when enableMinification is true', async () => {
-      await handler.translateDocument('/tmp/doc.pdf', defaultOptions({ enableMinification: true }));
+      await handler.translateDocument(
+        '/tmp/doc.pdf',
+        defaultOptions({ enableMinification: true })
+      );
 
-      expect(mocks.documentTranslationService.translateDocument).toHaveBeenCalledWith(
+      expect(
+        mocks.documentTranslationService.translateDocument
+      ).toHaveBeenCalledWith(
         '/tmp/doc.pdf',
         '/tmp/output.pdf',
         expect.objectContaining({ enableDocumentMinification: true }),
@@ -249,7 +341,10 @@ describe('DocumentTranslationHandler', () => {
     });
 
     it('should return success message with billed characters', async () => {
-      const result = await handler.translateDocument('/tmp/doc.pdf', defaultOptions());
+      const result = await handler.translateDocument(
+        '/tmp/doc.pdf',
+        defaultOptions()
+      );
 
       expect(result).toContain('Translated /tmp/doc.pdf -> /tmp/output.pdf');
       expect(result).toContain('Billed characters: 100');
@@ -258,18 +353,24 @@ describe('DocumentTranslationHandler', () => {
     it('should call spinner.succeed on success', async () => {
       await handler.translateDocument('/tmp/doc.pdf', defaultOptions());
 
-      expect(mockSpinner.succeed).toHaveBeenCalledWith('Document translated successfully!');
+      expect(mockSpinner.succeed).toHaveBeenCalledWith(
+        'Document translated successfully!'
+      );
     });
 
     it('should call spinner.fail on error and rethrow', async () => {
       const error = new Error('API failure');
-      mocks.documentTranslationService.translateDocument.mockRejectedValue(error);
+      mocks.documentTranslationService.translateDocument.mockRejectedValue(
+        error
+      );
 
       await expect(
         handler.translateDocument('/tmp/doc.pdf', defaultOptions())
       ).rejects.toThrow('API failure');
 
-      expect(mockSpinner.fail).toHaveBeenCalledWith('Document translation failed');
+      expect(mockSpinner.fail).toHaveBeenCalledWith(
+        'Document translation failed'
+      );
     });
 
     it('should not include billed characters when not provided', async () => {
@@ -278,7 +379,10 @@ describe('DocumentTranslationHandler', () => {
         outputPath: '/tmp/output.pdf',
       });
 
-      const result = await handler.translateDocument('/tmp/doc.pdf', defaultOptions());
+      const result = await handler.translateDocument(
+        '/tmp/doc.pdf',
+        defaultOptions()
+      );
 
       expect(result).toContain('Translated /tmp/doc.pdf -> /tmp/output.pdf');
       expect(result).not.toContain('Billed characters');
diff --git a/tests/unit/document-translation-service.test.ts b/tests/unit/document-translation-service.test.ts
index 2da46573..22428dd0 100644
--- a/tests/unit/document-translation-service.test.ts
+++ b/tests/unit/document-translation-service.test.ts
@@ -3,7 +3,10 @@
  * Tests for complete document translation workflow with polling
  */
 
-import { DocumentTranslationService, MAX_DOCUMENT_FILE_SIZE } from '../../src/services/document-translation.js';
+import {
+  DocumentTranslationService,
+  MAX_DOCUMENT_FILE_SIZE,
+} from '../../src/services/document-translation.js';
 import { DeepLClient } from '../../src/api/deepl-client.js';
 
 // Mock the DeepL client
@@ -71,7 +74,8 @@ describe('DocumentTranslationService', () => {
         documentKey: 'key-456',
       });
 
-      mockClient.getDocumentStatus = jest.fn()
+      mockClient.getDocumentStatus = jest
+        .fn()
         .mockResolvedValueOnce({
           documentId: 'doc-123',
           status: 'queued',
@@ -87,7 +91,9 @@ describe('DocumentTranslationService', () => {
           billedCharacters: 500,
         });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(translatedBuffer);
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(translatedBuffer);
 
       const result = await service.translateDocument(inputPath, outputPath, {
         targetLang: 'es',
@@ -120,7 +126,9 @@ describe('DocumentTranslationService', () => {
     });
 
     it('should throw error if input file does not exist', async () => {
-      const enoentErr = new Error('ENOENT: no such file or directory') as Error & { code: string };
+      const enoentErr = new Error(
+        'ENOENT: no such file or directory'
+      ) as Error & { code: string };
       enoentErr.code = 'ENOENT';
       mockStat.mockRejectedValue(enoentErr);
 
@@ -169,7 +177,8 @@ describe('DocumentTranslationService', () => {
         documentKey: 'key-456',
       });
 
-      mockClient.getDocumentStatus = jest.fn()
+      mockClient.getDocumentStatus = jest
+        .fn()
         .mockResolvedValueOnce({
           documentId: 'doc-123',
           status: 'queued',
@@ -184,11 +193,18 @@ describe('DocumentTranslationService', () => {
           status: 'done',
         });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(Buffer.from('translated'));
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(Buffer.from('translated'));
 
-      await service.translateDocument(inputPath, outputPath, {
-        targetLang: 'es',
-      }, progressCallback);
+      await service.translateDocument(
+        inputPath,
+        outputPath,
+        {
+          targetLang: 'es',
+        },
+        progressCallback
+      );
 
       expect(progressCallback).toHaveBeenCalledWith({
         status: 'queued',
@@ -225,14 +241,17 @@ describe('DocumentTranslationService', () => {
       });
 
       // Mock multiple polling attempts
-      mockClient.getDocumentStatus = jest.fn()
+      mockClient.getDocumentStatus = jest
+        .fn()
         .mockResolvedValueOnce({ documentId: 'doc-123', status: 'queued' })
         .mockResolvedValueOnce({ documentId: 'doc-123', status: 'queued' })
         .mockResolvedValueOnce({ documentId: 'doc-123', status: 'translating' })
         .mockResolvedValueOnce({ documentId: 'doc-123', status: 'translating' })
         .mockResolvedValueOnce({ documentId: 'doc-123', status: 'done' });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(Buffer.from('translated'));
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(Buffer.from('translated'));
 
       await service.translateDocument(inputPath, outputPath, {
         targetLang: 'es',
@@ -262,7 +281,9 @@ describe('DocumentTranslationService', () => {
         billedCharacters: 500,
       });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(translatedBuffer);
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(translatedBuffer);
 
       await service.translateDocument(inputPath, outputPath, {
         targetLang: 'es',
@@ -299,7 +320,9 @@ describe('DocumentTranslationService', () => {
         billedCharacters: 300,
       });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(translatedBuffer);
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(translatedBuffer);
 
       await service.translateDocument(inputPath, outputPath, {
         targetLang: 'es',
@@ -332,7 +355,9 @@ describe('DocumentTranslationService', () => {
         status: 'done',
       });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(translatedBuffer);
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(translatedBuffer);
 
       await service.translateDocument(inputPath, outputPath, {
         targetLang: 'es',
@@ -368,7 +393,9 @@ describe('DocumentTranslationService', () => {
         status: 'done',
       });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(translatedBuffer);
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(translatedBuffer);
 
       await service.translateDocument(inputPath, outputPath, {
         targetLang: 'es',
@@ -395,7 +422,9 @@ describe('DocumentTranslationService', () => {
           targetLang: 'es',
           enableDocumentMinification: true,
         })
-      ).rejects.toThrow('Document minification is only supported for PPTX and DOCX files');
+      ).rejects.toThrow(
+        'Document minification is only supported for PPTX and DOCX files'
+      );
 
       // uploadDocument should NOT have been called
       expect(mockClient.uploadDocument).not.toHaveBeenCalled();
@@ -410,7 +439,9 @@ describe('DocumentTranslationService', () => {
           targetLang: 'es',
           enableDocumentMinification: true,
         })
-      ).rejects.toThrow('Document minification is only supported for PPTX and DOCX files');
+      ).rejects.toThrow(
+        'Document minification is only supported for PPTX and DOCX files'
+      );
 
       expect(mockClient.uploadDocument).not.toHaveBeenCalled();
     });
@@ -424,7 +455,9 @@ describe('DocumentTranslationService', () => {
           targetLang: 'es',
           enableDocumentMinification: true,
         })
-      ).rejects.toThrow('Document minification is only supported for PPTX and DOCX files');
+      ).rejects.toThrow(
+        'Document minification is only supported for PPTX and DOCX files'
+      );
 
       expect(mockClient.uploadDocument).not.toHaveBeenCalled();
     });
@@ -434,7 +467,9 @@ describe('DocumentTranslationService', () => {
       const outputPath = '/test/output.es.pdf';
 
       mockSafeReadFile.mockRejectedValue(
-        new Error(`Symlinks are not supported for security reasons: ${inputPath}`)
+        new Error(
+          `Symlinks are not supported for security reasons: ${inputPath}`
+        )
       );
 
       await expect(
@@ -472,7 +507,9 @@ describe('DocumentTranslationService', () => {
         service.translateDocument(inputPath, outputPath, {
           targetLang: 'es',
         })
-      ).rejects.toThrow('File size (100.0 MB) exceeds the maximum allowed size of 30 MB');
+      ).rejects.toThrow(
+        'File size (100.0 MB) exceeds the maximum allowed size of 30 MB'
+      );
 
       expect(mockClient.uploadDocument).not.toHaveBeenCalled();
     });
@@ -496,7 +533,9 @@ describe('DocumentTranslationService', () => {
         billedCharacters: 200,
       });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(Buffer.from('translated'));
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(Buffer.from('translated'));
 
       const result = await service.translateDocument(inputPath, outputPath, {
         targetLang: 'es',
@@ -524,7 +563,9 @@ describe('DocumentTranslationService', () => {
         status: 'done',
       });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(Buffer.from('translated'));
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(Buffer.from('translated'));
 
       const result = await service.translateDocument(inputPath, outputPath, {
         targetLang: 'es',
@@ -544,7 +585,9 @@ describe('DocumentTranslationService', () => {
         service.translateDocument(inputPath, outputPath, {
           targetLang: 'es',
         })
-      ).rejects.toThrow('https://developers.deepl.com/docs/api-reference/document');
+      ).rejects.toThrow(
+        'https://developers.deepl.com/docs/api-reference/document'
+      );
 
       expect(mockClient.uploadDocument).not.toHaveBeenCalled();
     });
@@ -641,16 +684,15 @@ describe('DocumentTranslationService', () => {
       const abortController = new AbortController();
 
       // Mock getDocumentStatus to return "translating" and then abort after first call
-      mockClient.getDocumentStatus = jest.fn()
-        .mockImplementation(() => {
-          // Abort after first status check
-          abortController.abort();
-          return Promise.resolve({
-            documentId: 'doc-123',
-            status: 'translating',
-            secondsRemaining: 10,
-          });
+      mockClient.getDocumentStatus = jest.fn().mockImplementation(() => {
+        // Abort after first status check
+        abortController.abort();
+        return Promise.resolve({
+          documentId: 'doc-123',
+          status: 'translating',
+          secondsRemaining: 10,
         });
+      });
 
       await expect(
         service.translateDocument(
@@ -728,7 +770,9 @@ describe('DocumentTranslationService', () => {
         billedCharacters: 100,
       });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(translatedBuffer);
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(translatedBuffer);
 
       // Create AbortController but don't abort
       const abortController = new AbortController();
@@ -748,7 +792,10 @@ describe('DocumentTranslationService', () => {
       });
 
       expect(mockClient.downloadDocument).toHaveBeenCalled();
-      expect(mockAtomicWriteFile).toHaveBeenCalledWith(outputPath, translatedBuffer);
+      expect(mockAtomicWriteFile).toHaveBeenCalledWith(
+        outputPath,
+        translatedBuffer
+      );
     });
 
     it('should work without AbortSignal (backward compatibility)', async () => {
@@ -769,14 +816,14 @@ describe('DocumentTranslationService', () => {
         status: 'done',
       });
 
-      mockClient.downloadDocument = jest.fn().mockResolvedValue(translatedBuffer);
+      mockClient.downloadDocument = jest
+        .fn()
+        .mockResolvedValue(translatedBuffer);
 
       // Call without serviceOptions (no AbortSignal)
-      const result = await service.translateDocument(
-        inputPath,
-        outputPath,
-        { targetLang: 'es' }
-      );
+      const result = await service.translateDocument(inputPath, outputPath, {
+        targetLang: 'es',
+      });
 
       expect(result).toEqual({
         success: true,
diff --git a/tests/unit/dry-run.test.ts b/tests/unit/dry-run.test.ts
index 0d554e28..41202731 100644
--- a/tests/unit/dry-run.test.ts
+++ b/tests/unit/dry-run.test.ts
@@ -73,7 +73,8 @@ describe('--dry-run flag', () => {
       const testFile = path.join(tmpDir, 'test-translate.txt');
       fs.writeFileSync(testFile, 'Hello world');
 
-      const { registerTranslate } = await import('../../src/cli/commands/register-translate');
+      const { registerTranslate } =
+        await import('../../src/cli/commands/register-translate');
 
       const program = new Command();
       const mockDeps = {
@@ -88,9 +89,14 @@ describe('--dry-run flag', () => {
       registerTranslate(program, mockDeps as any);
 
       await program.parseAsync([
-        'node', 'deepl', 'translate', testFile,
-        '--to', 'es',
-        '--output', '/tmp/out.txt',
+        'node',
+        'deepl',
+        'translate',
+        testFile,
+        '--to',
+        'es',
+        '--output',
+        '/tmp/out.txt',
         '--dry-run',
       ]);
 
@@ -111,7 +117,8 @@ describe('--dry-run flag', () => {
       }
       fs.writeFileSync(path.join(subDir, 'a.txt'), 'content');
 
-      const { registerTranslate } = await import('../../src/cli/commands/register-translate');
+      const { registerTranslate } =
+        await import('../../src/cli/commands/register-translate');
 
       const program = new Command();
       const mockDeps = {
@@ -126,10 +133,16 @@ describe('--dry-run flag', () => {
       registerTranslate(program, mockDeps as any);
 
       await program.parseAsync([
-        'node', 'deepl', 'translate', subDir,
-        '--to', 'de,fr',
-        '--output', '/tmp/out',
-        '--pattern', '*.txt',
+        'node',
+        'deepl',
+        'translate',
+        subDir,
+        '--to',
+        'de,fr',
+        '--output',
+        '/tmp/out',
+        '--pattern',
+        '*.txt',
         '--dry-run',
       ]);
 
@@ -148,7 +161,8 @@ describe('--dry-run flag', () => {
       const testFile = path.join(tmpDir, 'test-src-lang.txt');
       fs.writeFileSync(testFile, 'Bonjour');
 
-      const { registerTranslate } = await import('../../src/cli/commands/register-translate');
+      const { registerTranslate } =
+        await import('../../src/cli/commands/register-translate');
 
       const program = new Command();
       const mockDeps = {
@@ -163,10 +177,16 @@ describe('--dry-run flag', () => {
       registerTranslate(program, mockDeps as any);
 
       await program.parseAsync([
-        'node', 'deepl', 'translate', testFile,
-        '--to', 'en',
-        '--from', 'fr',
-        '--output', '/tmp/out.txt',
+        'node',
+        'deepl',
+        'translate',
+        testFile,
+        '--to',
+        'en',
+        '--from',
+        'fr',
+        '--output',
+        '/tmp/out.txt',
         '--dry-run',
       ]);
 
@@ -175,7 +195,8 @@ describe('--dry-run flag', () => {
     });
 
     it('should activate dry-run for plain text translation', async () => {
-      const { registerTranslate } = await import('../../src/cli/commands/register-translate');
+      const { registerTranslate } =
+        await import('../../src/cli/commands/register-translate');
 
       const program = new Command();
 
@@ -191,14 +212,19 @@ describe('--dry-run flag', () => {
       registerTranslate(program, mockDeps as any);
 
       await program.parseAsync([
-        'node', 'deepl', 'translate', 'Hello world',
-        '--to', 'es',
+        'node',
+        'deepl',
+        'translate',
+        'Hello world',
+        '--to',
+        'es',
         '--dry-run',
       ]);
 
       const outputCalls = mockLogger.output.mock.calls;
       const hasDryRun = outputCalls.some(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[dry-run]')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('[dry-run]')
       );
       expect(hasDryRun).toBe(true);
       const outputStr = outputCalls.map((c: unknown[]) => c[0]).join('\n');
@@ -209,7 +235,8 @@ describe('--dry-run flag', () => {
 
   describe('glossary delete --dry-run', () => {
     it('should show dry-run message without deleting', async () => {
-      const { registerGlossary } = await import('../../src/cli/commands/register-glossary');
+      const { registerGlossary } =
+        await import('../../src/cli/commands/register-glossary');
 
       const program = new Command();
       const mockDeps = {
@@ -220,7 +247,11 @@ describe('--dry-run flag', () => {
       registerGlossary(program, mockDeps);
 
       await program.parseAsync([
-        'node', 'deepl', 'glossary', 'delete', 'my-glossary',
+        'node',
+        'deepl',
+        'glossary',
+        'delete',
+        'my-glossary',
         '--dry-run',
       ]);
 
@@ -236,7 +267,8 @@ describe('--dry-run flag', () => {
 
   describe('cache clear --dry-run', () => {
     it('should show cache stats without clearing', async () => {
-      const { registerCache } = await import('../../src/cli/commands/register-cache');
+      const { registerCache } =
+        await import('../../src/cli/commands/register-cache');
 
       const program = new Command();
       const mockCacheService = {
@@ -258,7 +290,10 @@ describe('--dry-run flag', () => {
       registerCache(program, mockDeps as any);
 
       await program.parseAsync([
-        'node', 'deepl', 'cache', 'clear',
+        'node',
+        'deepl',
+        'cache',
+        'clear',
         '--dry-run',
       ]);
 
@@ -277,7 +312,8 @@ describe('--dry-run flag', () => {
         fs.mkdirSync(watchDir, { recursive: true });
       }
 
-      const { registerWatch } = await import('../../src/cli/commands/register-watch');
+      const { registerWatch } =
+        await import('../../src/cli/commands/register-watch');
 
       const program = new Command();
       const mockDeps = {
@@ -290,8 +326,12 @@ describe('--dry-run flag', () => {
       registerWatch(program, mockDeps as any);
 
       await program.parseAsync([
-        'node', 'deepl', 'watch', watchDir,
-        '--to', 'es,fr',
+        'node',
+        'deepl',
+        'watch',
+        watchDir,
+        '--to',
+        'es,fr',
         '--dry-run',
       ]);
 
@@ -312,7 +352,8 @@ describe('--dry-run flag', () => {
         fs.mkdirSync(watchDir, { recursive: true });
       }
 
-      const { registerWatch } = await import('../../src/cli/commands/register-watch');
+      const { registerWatch } =
+        await import('../../src/cli/commands/register-watch');
 
       const program = new Command();
       const mockDeps = {
@@ -325,9 +366,14 @@ describe('--dry-run flag', () => {
       registerWatch(program, mockDeps as any);
 
       await program.parseAsync([
-        'node', 'deepl', 'watch', watchDir,
-        '--to', 'de',
-        '--pattern', '*.json',
+        'node',
+        'deepl',
+        'watch',
+        watchDir,
+        '--to',
+        'de',
+        '--pattern',
+        '*.json',
         '--auto-commit',
         '--dry-run',
       ]);
@@ -341,7 +387,8 @@ describe('--dry-run flag', () => {
       const watchFile = path.join(tmpDir, 'watch-single.txt');
       fs.writeFileSync(watchFile, 'content');
 
-      const { registerWatch } = await import('../../src/cli/commands/register-watch');
+      const { registerWatch } =
+        await import('../../src/cli/commands/register-watch');
 
       const program = new Command();
       const mockDeps = {
@@ -354,9 +401,14 @@ describe('--dry-run flag', () => {
       registerWatch(program, mockDeps as any);
 
       await program.parseAsync([
-        'node', 'deepl', 'watch', watchFile,
-        '--to', 'ja',
-        '--output', '/tmp/translations',
+        'node',
+        'deepl',
+        'watch',
+        watchFile,
+        '--to',
+        'ja',
+        '--output',
+        '/tmp/translations',
         '--dry-run',
       ]);
 
diff --git a/tests/unit/error-suggestions.test.ts b/tests/unit/error-suggestions.test.ts
index 4dd60ebe..7e547246 100644
--- a/tests/unit/error-suggestions.test.ts
+++ b/tests/unit/error-suggestions.test.ts
@@ -31,7 +31,9 @@ describe('Error suggestions', () => {
   describe('AuthError', () => {
     it('should have a default suggestion about setting the API key', () => {
       const error = new AuthError('Authentication failed');
-      expect(error.suggestion).toBe('Run: deepl init (setup wizard) or deepl auth set-key <your-api-key>');
+      expect(error.suggestion).toBe(
+        'Run: deepl init (setup wizard) or deepl auth set-key <your-api-key>'
+      );
     });
 
     it('should allow overriding the default suggestion', () => {
@@ -106,7 +108,10 @@ describe('Error suggestions', () => {
 
   describe('ValidationError', () => {
     it('should support optional suggestion', () => {
-      const error = new ValidationError('Invalid language', 'Run: deepl languages');
+      const error = new ValidationError(
+        'Invalid language',
+        'Run: deepl languages'
+      );
       expect(error.suggestion).toBe('Run: deepl languages');
     });
 
@@ -123,7 +128,10 @@ describe('Error suggestions', () => {
 
   describe('ConfigError', () => {
     it('should support optional suggestion', () => {
-      const error = new ConfigError('Config missing', 'Run: deepl config set ...');
+      const error = new ConfigError(
+        'Config missing',
+        'Run: deepl config set ...'
+      );
       expect(error.suggestion).toBe('Run: deepl config set ...');
     });
 
@@ -150,51 +158,44 @@ describe('HttpClient.handleError suggestions', () => {
     nock.cleanAll();
   });
 
-  async function createClientAndTranslate(statusCode: number, body: Record<string, unknown> = {}) {
+  async function createClientAndTranslate(
+    statusCode: number,
+    body: Record<string, unknown> = {}
+  ) {
     const { DeepLClient } = await import('../../src/api/deepl-client');
     const client = new DeepLClient('test-api-key', { maxRetries: 0 });
 
-    nock(baseUrl)
-      .post('/v2/translate')
-      .reply(statusCode, body);
+    nock(baseUrl).post('/v2/translate').reply(statusCode, body);
 
     return client.translate('Hello', { targetLang: 'es' });
   }
 
   it('should include suggestion for HTTP 403 (auth error)', async () => {
-    await expect(createClientAndTranslate(403))
-      .rejects
-      .toMatchObject({
-        message: expect.stringContaining('Authentication failed'),
-        suggestion: expect.stringContaining('deepl auth set-key'),
-      });
+    await expect(createClientAndTranslate(403)).rejects.toMatchObject({
+      message: expect.stringContaining('Authentication failed'),
+      suggestion: expect.stringContaining('deepl auth set-key'),
+    });
   });
 
   it('should include suggestion for HTTP 456 (quota exceeded)', async () => {
-    await expect(createClientAndTranslate(456))
-      .rejects
-      .toMatchObject({
-        message: expect.stringContaining('Quota exceeded'),
-        suggestion: expect.stringContaining('deepl usage'),
-      });
+    await expect(createClientAndTranslate(456)).rejects.toMatchObject({
+      message: expect.stringContaining('Quota exceeded'),
+      suggestion: expect.stringContaining('deepl usage'),
+    });
   });
 
   it('should include suggestion for HTTP 429 (rate limit)', async () => {
-    await expect(createClientAndTranslate(429))
-      .rejects
-      .toMatchObject({
-        message: expect.stringContaining('Rate limit exceeded'),
-        suggestion: expect.stringContaining('Wait a moment'),
-      });
+    await expect(createClientAndTranslate(429)).rejects.toMatchObject({
+      message: expect.stringContaining('Rate limit exceeded'),
+      suggestion: expect.stringContaining('Wait a moment'),
+    });
   });
 
   it('should include suggestion for HTTP 503 (service unavailable)', async () => {
-    await expect(createClientAndTranslate(503))
-      .rejects
-      .toMatchObject({
-        message: expect.stringContaining('Service temporarily unavailable'),
-        suggestion: expect.stringContaining('internet connection'),
-      });
+    await expect(createClientAndTranslate(503)).rejects.toMatchObject({
+      message: expect.stringContaining('Service temporarily unavailable'),
+      suggestion: expect.stringContaining('internet connection'),
+    });
   });
 
   it('should wrap unrecognized 4xx errors with ValidationError', async () => {
@@ -205,9 +206,9 @@ describe('HttpClient.handleError suggestions', () => {
       .post('/v2/translate')
       .reply(422, { message: 'Unprocessable Entity' });
 
-    await expect(client.translate('Hello', { targetLang: 'es' }))
-      .rejects
-      .toBeInstanceOf(ValidationError);
+    await expect(
+      client.translate('Hello', { targetLang: 'es' })
+    ).rejects.toBeInstanceOf(ValidationError);
   });
 
   it('should wrap network-level errors with NetworkError and suggestion', async () => {
@@ -221,11 +222,11 @@ describe('HttpClient.handleError suggestions', () => {
       .post('/v2/translate')
       .replyWithError('connect ECONNREFUSED 127.0.0.1:1');
 
-    await expect(client.translate('Hello', { targetLang: 'es' }))
-      .rejects
-      .toMatchObject({
-        message: expect.stringContaining('ECONNREFUSED'),
-        suggestion: expect.stringContaining('internet connection'),
-      });
+    await expect(
+      client.translate('Hello', { targetLang: 'es' })
+    ).rejects.toMatchObject({
+      message: expect.stringContaining('ECONNREFUSED'),
+      suggestion: expect.stringContaining('internet connection'),
+    });
   });
 });
diff --git a/tests/unit/errors.test.ts b/tests/unit/errors.test.ts
index 23e0905c..8554df47 100644
--- a/tests/unit/errors.test.ts
+++ b/tests/unit/errors.test.ts
@@ -74,7 +74,10 @@ describe('SyncPartialFailureError', () => {
   });
 
   it('exposes the custom suggestion when provided', () => {
-    const err = new SyncPartialFailureError('some locales failed', 'do the thing');
+    const err = new SyncPartialFailureError(
+      'some locales failed',
+      'do the thing'
+    );
     expect(err.suggestion).toBe('do the thing');
   });
 
diff --git a/tests/unit/exit-codes.test.ts b/tests/unit/exit-codes.test.ts
index e7605783..5000e90e 100644
--- a/tests/unit/exit-codes.test.ts
+++ b/tests/unit/exit-codes.test.ts
@@ -3,7 +3,11 @@
  * Tests for exit code classification and retry logic
  */
 
-import { ExitCode, exitCodeForError, isRetryableError } from '../../src/utils/exit-codes';
+import {
+  ExitCode,
+  exitCodeForError,
+  isRetryableError,
+} from '../../src/utils/exit-codes';
 import { AuthError } from '../../src/utils/errors';
 import { Logger } from '../../src/utils/logger';
 
@@ -49,7 +53,11 @@ describe('ExitCode', () => {
 
       // QuotaError classification
       ['quota exceeded', 'Quota exceeded', ExitCode.QuotaError],
-      ['character limit reached', 'Character limit reached', ExitCode.QuotaError],
+      [
+        'character limit reached',
+        'Character limit reached',
+        ExitCode.QuotaError,
+      ],
       ['HTTP 456', 'HTTP 456 error', ExitCode.QuotaError],
 
       // NetworkError classification
@@ -59,45 +67,109 @@ describe('ExitCode', () => {
       ['ETIMEDOUT', 'connect ETIMEDOUT', ExitCode.NetworkError],
       ['socket hang up', 'socket hang up', ExitCode.NetworkError],
       ['network error phrase', 'Network error occurred', ExitCode.NetworkError],
-      ['connection refused phrase', 'Connection refused', ExitCode.NetworkError],
-      ['connection reset phrase', 'Connection reset by peer', ExitCode.NetworkError],
-      ['connection timed out phrase', 'Connection timed out', ExitCode.NetworkError],
+      [
+        'connection refused phrase',
+        'Connection refused',
+        ExitCode.NetworkError,
+      ],
+      [
+        'connection reset phrase',
+        'Connection reset by peer',
+        ExitCode.NetworkError,
+      ],
+      [
+        'connection timed out phrase',
+        'Connection timed out',
+        ExitCode.NetworkError,
+      ],
       ['network timeout phrase', 'Network timeout', ExitCode.NetworkError],
-      ['service unavailable', 'Service temporarily unavailable', ExitCode.NetworkError],
+      [
+        'service unavailable',
+        'Service temporarily unavailable',
+        ExitCode.NetworkError,
+      ],
       ['HTTP 503', 'HTTP 503 error', ExitCode.NetworkError],
 
       // InvalidInput classification
       ['cannot be empty', 'Text cannot be empty', ExitCode.InvalidInput],
       ['file not found', 'File not found', ExitCode.InvalidInput],
       ['path not found', 'Path not found: /tmp/missing', ExitCode.InvalidInput],
-      ['directory not found', 'Directory not found: /tmp/dir', ExitCode.InvalidInput],
-      ['not found in glossary', 'Term not found in glossary', ExitCode.InvalidInput],
+      [
+        'directory not found',
+        'Directory not found: /tmp/dir',
+        ExitCode.InvalidInput,
+      ],
+      [
+        'not found in glossary',
+        'Term not found in glossary',
+        ExitCode.InvalidInput,
+      ],
       ['unsupported format', 'Unsupported format', ExitCode.InvalidInput],
-      ['unsupported language', 'Unsupported language: xx', ExitCode.InvalidInput],
-      ['not supported for', 'Formality not supported for EN', ExitCode.InvalidInput],
-      ['not supported in', 'Feature not supported in free plan', ExitCode.InvalidInput],
-      ['invalid target language', 'Invalid target language', ExitCode.InvalidInput],
-      ['invalid source language', 'Invalid source language: xx', ExitCode.InvalidInput],
-      ['invalid language code', 'Invalid language code: zz', ExitCode.InvalidInput],
+      [
+        'unsupported language',
+        'Unsupported language: xx',
+        ExitCode.InvalidInput,
+      ],
+      [
+        'not supported for',
+        'Formality not supported for EN',
+        ExitCode.InvalidInput,
+      ],
+      [
+        'not supported in',
+        'Feature not supported in free plan',
+        ExitCode.InvalidInput,
+      ],
+      [
+        'invalid target language',
+        'Invalid target language',
+        ExitCode.InvalidInput,
+      ],
+      [
+        'invalid source language',
+        'Invalid source language: xx',
+        ExitCode.InvalidInput,
+      ],
+      [
+        'invalid language code',
+        'Invalid language code: zz',
+        ExitCode.InvalidInput,
+      ],
       ['invalid glossary', 'Invalid glossary ID', ExitCode.InvalidInput],
       ['invalid hook', 'Invalid hook script', ExitCode.InvalidInput],
       ['invalid url', 'Invalid URL provided', ExitCode.InvalidInput],
       ['invalid size', 'Invalid size: exceeds limit', ExitCode.InvalidInput],
       ['"is required"', 'Target language is required', ExitCode.InvalidInput],
-      ['cannot specify both', 'Cannot specify both --source and --auto-detect', ExitCode.InvalidInput],
+      [
+        'cannot specify both',
+        'Cannot specify both --source and --auto-detect',
+        ExitCode.InvalidInput,
+      ],
 
       // ConfigError classification
       ['failed to load config', 'Failed to load config', ExitCode.ConfigError],
       ['config file', 'Config file corrupted', ExitCode.ConfigError],
-      ['config directory', 'Config directory not writable', ExitCode.ConfigError],
-      ['configuration file', 'Configuration file missing', ExitCode.ConfigError],
-      ['configuration error', 'Configuration error: invalid JSON', ExitCode.ConfigError],
+      [
+        'config directory',
+        'Config directory not writable',
+        ExitCode.ConfigError,
+      ],
+      [
+        'configuration file',
+        'Configuration file missing',
+        ExitCode.ConfigError,
+      ],
+      [
+        'configuration error',
+        'Configuration error: invalid JSON',
+        ExitCode.ConfigError,
+      ],
       ['failed to save config', 'Failed to save config', ExitCode.ConfigError],
     ])(
       'should classify %s error message "%s" → exit code %i',
       (_, message, expectedCode) => {
         expect(exitCodeForError(new Error(message))).toBe(expectedCode);
-      },
+      }
     );
 
     describe('priority ordering', () => {
@@ -113,17 +185,29 @@ describe('ExitCode', () => {
     });
 
     it.each<[string, string]>([
-      ['bare "connection" without qualifying phrase', 'Database connection pool exhausted'],
+      [
+        'bare "connection" without qualifying phrase',
+        'Database connection pool exhausted',
+      ],
       ['bare "timeout" without qualifying phrase', 'Lock acquisition timeout'],
-      ['bare "required" without "is required"', 'All fields required by the API'],
+      [
+        'bare "required" without "is required"',
+        'All fields required by the API',
+      ],
       ['bare "config" in unrelated context', 'The config value was updated'],
-      ['ambiguous "Database connection required for config"', 'Database connection required for config'],
-      ['ambiguous "timeout waiting for required resource"', 'timeout waiting for required resource'],
+      [
+        'ambiguous "Database connection required for config"',
+        'Database connection required for config',
+      ],
+      [
+        'ambiguous "timeout waiting for required resource"',
+        'timeout waiting for required resource',
+      ],
       ['ambiguous "connection pool required"', 'connection pool required'],
       ['429 embedded in other numbers', 'Error code 14291'],
       ['503 embedded in other numbers', 'Reference ID: 50312'],
       ['456 embedded in other numbers', 'Transaction 45678 failed'],
-      ['bare "not found"', 'Method not found in proxy', ],
+      ['bare "not found"', 'Method not found in proxy'],
       ['bare "invalid"', 'Invalid state: connection pool exhausted'],
       ['bare "unsupported"', 'Unsupported encoding utf-32'],
       ['bare "expected"', 'Expected closing bracket at position 42'],
@@ -131,17 +215,16 @@ describe('ExitCode', () => {
       ['unknown message', 'Something went wrong'],
       ['empty message', ''],
       ['truly generic error', 'Something broke'],
-    ])(
-      'should fall back to GeneralError for %s ("%s")',
-      (_, message) => {
-        expect(exitCodeForError(new Error(message))).toBe(ExitCode.GeneralError);
-      },
-    );
+    ])('should fall back to GeneralError for %s ("%s")', (_, message) => {
+      expect(exitCodeForError(new Error(message))).toBe(ExitCode.GeneralError);
+    });
 
     it('should log verbose warning when classifyByMessage is invoked', () => {
       const verboseSpy = jest.spyOn(Logger, 'verbose').mockImplementation();
       exitCodeForError(new Error('some unknown error'));
-      expect(verboseSpy).toHaveBeenCalledWith(expect.stringContaining('Untyped error'));
+      expect(verboseSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Untyped error')
+      );
       verboseSpy.mockRestore();
     });
 
@@ -164,11 +247,8 @@ describe('ExitCode', () => {
       ['general errors', ExitCode.GeneralError, false],
       ['check failed', ExitCode.CheckFailed, false],
       ['success', ExitCode.Success, false],
-    ])(
-      'should mark %s (code %i) as retryable=%s',
-      (_, exitCode, expected) => {
-        expect(isRetryableError(exitCode)).toBe(expected);
-      },
-    );
+    ])('should mark %s (code %i) as retryable=%s', (_, exitCode, expected) => {
+      expect(isRetryableError(exitCode)).toBe(expected);
+    });
   });
 });
diff --git a/tests/unit/file-translation-handler.test.ts b/tests/unit/file-translation-handler.test.ts
index 9b9e393e..14b32685 100644
--- a/tests/unit/file-translation-handler.test.ts
+++ b/tests/unit/file-translation-handler.test.ts
@@ -1,6 +1,9 @@
 import { FileTranslationHandler } from '../../src/cli/commands/translate/file-translation-handler';
 import { DocumentTranslationHandler } from '../../src/cli/commands/translate/document-translation-handler';
-import type { HandlerContext, TranslateOptions } from '../../src/cli/commands/translate/types';
+import type {
+  HandlerContext,
+  TranslateOptions,
+} from '../../src/cli/commands/translate/types';
 import { ValidationError } from '../../src/utils/errors';
 import {
   createMockTranslationService,
@@ -38,7 +41,9 @@ jest.mock('../../src/utils/logger', () => ({
 }));
 
 jest.mock('../../src/cli/commands/translate/translate-utils', () => {
-  const actual = jest.requireActual('../../src/cli/commands/translate/translate-utils');
+  const actual = jest.requireActual(
+    '../../src/cli/commands/translate/translate-utils'
+  );
   return {
     ...actual,
     isTextBasedFile: jest.fn().mockReturnValue(false),
@@ -49,16 +54,31 @@ jest.mock('../../src/cli/commands/translate/translate-utils', () => {
 
 import * as fs from 'fs';
 import { safeReadFileSync } from '../../src/utils/safe-read-file';
-import { isTextBasedFile, isStructuredFile, getFileSize, SAFE_TEXT_SIZE_LIMIT } from '../../src/cli/commands/translate/translate-utils';
-
-const mockedIsTextBasedFile = isTextBasedFile as jest.MockedFunction<typeof isTextBasedFile>;
-const mockedIsStructuredFile = isStructuredFile as jest.MockedFunction<typeof isStructuredFile>;
-const mockedGetFileSize = getFileSize as jest.MockedFunction<typeof getFileSize>;
-const mockedSafeReadFileSync = jest.mocked(safeReadFileSync) as unknown as jest.Mock;
+import {
+  isTextBasedFile,
+  isStructuredFile,
+  getFileSize,
+  SAFE_TEXT_SIZE_LIMIT,
+} from '../../src/cli/commands/translate/translate-utils';
+
+const mockedIsTextBasedFile = isTextBasedFile as jest.MockedFunction<
+  typeof isTextBasedFile
+>;
+const mockedIsStructuredFile = isStructuredFile as jest.MockedFunction<
+  typeof isStructuredFile
+>;
+const mockedGetFileSize = getFileSize as jest.MockedFunction<
+  typeof getFileSize
+>;
+const mockedSafeReadFileSync = jest.mocked(
+  safeReadFileSync
+) as unknown as jest.Mock;
 
 function createMockHandlerContext() {
   const translationService = createMockTranslationService({
-    translate: jest.fn().mockResolvedValue({ text: 'translated', detectedSourceLang: 'en' }),
+    translate: jest
+      .fn()
+      .mockResolvedValue({ text: 'translated', detectedSourceLang: 'en' }),
   });
   const fileTranslationService = createMockFileTranslationService();
   const batchTranslationService = {} as jest.Mocked<BatchTranslationService>;
@@ -80,10 +100,22 @@ function createMockHandlerContext() {
     config,
   };
 
-  return { ctx, mocks: { translationService, fileTranslationService, batchTranslationService, documentTranslationService, glossaryService, config } };
+  return {
+    ctx,
+    mocks: {
+      translationService,
+      fileTranslationService,
+      batchTranslationService,
+      documentTranslationService,
+      glossaryService,
+      config,
+    },
+  };
 }
 
-function defaultOptions(overrides: Partial<TranslateOptions> = {}): TranslateOptions {
+function defaultOptions(
+  overrides: Partial<TranslateOptions> = {}
+): TranslateOptions {
   return { to: 'de', output: '/tmp/output.txt', cache: true, ...overrides };
 }
 
@@ -105,7 +137,9 @@ describe('FileTranslationHandler', () => {
     mocks = result.mocks;
 
     mockDocHandler = {
-      translateDocument: jest.fn().mockResolvedValue('Translated doc.pdf -> /tmp/output.pdf'),
+      translateDocument: jest
+        .fn()
+        .mockResolvedValue('Translated doc.pdf -> /tmp/output.pdf'),
       ctx: result.ctx,
     };
 
@@ -131,22 +165,37 @@ describe('FileTranslationHandler', () => {
 
     it('should throw ValidationError for multi-target with stdout output', async () => {
       await expect(
-        handler.translateFile('/tmp/file.txt', defaultOptions({ to: 'de,fr', output: '-' }))
+        handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({ to: 'de,fr', output: '-' })
+        )
       ).rejects.toThrow(ValidationError);
       await expect(
-        handler.translateFile('/tmp/file.txt', defaultOptions({ to: 'de,fr', output: '-' }))
+        handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({ to: 'de,fr', output: '-' })
+        )
       ).rejects.toThrow('Cannot use --output - with multiple target languages');
     });
 
     it('should call fileTranslationService.translateFileToMultiple for multi-target', async () => {
       mocks.fileTranslationService.translateFileToMultiple.mockResolvedValue([
         { targetLang: 'de', text: 'Hallo', outputPath: '/tmp/out/file.de.txt' },
-        { targetLang: 'fr', text: 'Bonjour', outputPath: '/tmp/out/file.fr.txt' },
+        {
+          targetLang: 'fr',
+          text: 'Bonjour',
+          outputPath: '/tmp/out/file.fr.txt',
+        },
       ]);
 
-      const result = await handler.translateFile('/tmp/file.txt', defaultOptions({ to: 'de,fr', output: '/tmp/out' }));
+      const result = await handler.translateFile(
+        '/tmp/file.txt',
+        defaultOptions({ to: 'de,fr', output: '/tmp/out' })
+      );
 
-      expect(mocks.fileTranslationService.translateFileToMultiple).toHaveBeenCalled();
+      expect(
+        mocks.fileTranslationService.translateFileToMultiple
+      ).toHaveBeenCalled();
       expect(result).toContain('2 languages');
     });
 
@@ -155,90 +204,172 @@ describe('FileTranslationHandler', () => {
 
       beforeEach(() => {
         mocks.fileTranslationService.translateFileToMultiple.mockResolvedValue([
-          { targetLang: 'de', text: 'Hallo', outputPath: '/tmp/out/file.de.txt' },
-          { targetLang: 'fr', text: 'Bonjour', outputPath: '/tmp/out/file.fr.txt' },
+          {
+            targetLang: 'de',
+            text: 'Hallo',
+            outputPath: '/tmp/out/file.de.txt',
+          },
+          {
+            targetLang: 'fr',
+            text: 'Bonjour',
+            outputPath: '/tmp/out/file.fr.txt',
+          },
         ]);
       });
 
       it('throws ValidationError for --glossary without --from in multi-target', async () => {
         const err = await handler
-          .translateFile('/tmp/file.txt', defaultOptions({ to: 'de,fr', output: '/tmp/out', glossary: ['my-glossary'] }))
-          .catch(e => e);
+          .translateFile(
+            '/tmp/file.txt',
+            defaultOptions({
+              to: 'de,fr',
+              output: '/tmp/out',
+              glossary: ['my-glossary'],
+            })
+          )
+          .catch((e) => e);
         expect(err).toBeInstanceOf(ValidationError);
-        expect((err as Error).message).toContain('Source language (--from) is required');
+        expect((err as Error).message).toContain(
+          'Source language (--from) is required'
+        );
       });
 
       it('throws ValidationError for --translation-memory without --from in multi-target', async () => {
         const err = await handler
-          .translateFile('/tmp/file.txt', defaultOptions({ to: 'de,fr', output: '/tmp/out', translationMemory: 'my-tm' }))
-          .catch(e => e);
+          .translateFile(
+            '/tmp/file.txt',
+            defaultOptions({
+              to: 'de,fr',
+              output: '/tmp/out',
+              translationMemory: 'my-tm',
+            })
+          )
+          .catch((e) => e);
         expect(err).toBeInstanceOf(ValidationError);
         expect((err as ValidationError).exitCode).toBe(6);
-        expect((err as Error).message).toContain('--from is required when using --translation-memory');
+        expect((err as Error).message).toContain(
+          '--from is required when using --translation-memory'
+        );
       });
 
       it('throws ValidationError for multi-target TM + latency_optimized model', async () => {
         const err = await handler
-          .translateFile('/tmp/file.txt', defaultOptions({
-            to: 'de,fr', output: '/tmp/out',
-            from: 'en', translationMemory: 'my-tm', modelType: 'latency_optimized',
-          }))
-          .catch(e => e);
+          .translateFile(
+            '/tmp/file.txt',
+            defaultOptions({
+              to: 'de,fr',
+              output: '/tmp/out',
+              from: 'en',
+              translationMemory: 'my-tm',
+              modelType: 'latency_optimized',
+            })
+          )
+          .catch((e) => e);
         expect(err).toBeInstanceOf(ValidationError);
-        expect((err as Error).message).toContain('requires quality_optimized model type');
+        expect((err as Error).message).toContain(
+          'requires quality_optimized model type'
+        );
       });
 
       it('resolves glossary name to ID and passes it to translateFileToMultiple', async () => {
-        mocks.glossaryService.resolveGlossaryId.mockResolvedValue('glossary-abc-123');
+        mocks.glossaryService.resolveGlossaryId.mockResolvedValue(
+          'glossary-abc-123'
+        );
 
-        await handler.translateFile('/tmp/file.txt', defaultOptions({
-          to: 'de,fr', output: '/tmp/out',
-          from: 'en', glossary: ['my-glossary'],
-        }));
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({
+            to: 'de,fr',
+            output: '/tmp/out',
+            from: 'en',
+            glossary: ['my-glossary'],
+          })
+        );
 
-        expect(mocks.glossaryService.resolveGlossaryId).toHaveBeenCalledTimes(1);
-        expect(mocks.glossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', { from: 'en', targets: ['de', 'fr'] });
-        const call = mocks.fileTranslationService.translateFileToMultiple.mock.calls[0]!;
-        expect(call[2]).toEqual(expect.objectContaining({ glossaryId: 'glossary-abc-123' }));
+        expect(mocks.glossaryService.resolveGlossaryId).toHaveBeenCalledTimes(
+          1
+        );
+        expect(mocks.glossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+          'my-glossary',
+          { from: 'en', targets: ['de', 'fr'] }
+        );
+        const call =
+          mocks.fileTranslationService.translateFileToMultiple.mock.calls[0]!;
+        expect(call[2]).toEqual(
+          expect.objectContaining({ glossaryId: 'glossary-abc-123' })
+        );
       });
 
       it('TM UUID fast-path in multi-target: passes UUID through, skips listTranslationMemories, sets quality_optimized', async () => {
-        await handler.translateFile('/tmp/file.txt', defaultOptions({
-          to: 'de,fr', output: '/tmp/out',
-          from: 'en', translationMemory: TM_UUID,
-        }));
-
-        expect(mocks.translationService.listTranslationMemories).not.toHaveBeenCalled();
-        const call = mocks.fileTranslationService.translateFileToMultiple.mock.calls[0]!;
-        expect(call[2]).toEqual(expect.objectContaining({
-          translationMemoryId: TM_UUID,
-          modelType: 'quality_optimized',
-        }));
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({
+            to: 'de,fr',
+            output: '/tmp/out',
+            from: 'en',
+            translationMemory: TM_UUID,
+          })
+        );
+
+        expect(
+          mocks.translationService.listTranslationMemories
+        ).not.toHaveBeenCalled();
+        const call =
+          mocks.fileTranslationService.translateFileToMultiple.mock.calls[0]!;
+        expect(call[2]).toEqual(
+          expect.objectContaining({
+            translationMemoryId: TM_UUID,
+            modelType: 'quality_optimized',
+          })
+        );
       });
 
       it('TM UUID + --tm-threshold passes through as translationMemoryThreshold in multi-target', async () => {
-        await handler.translateFile('/tmp/file.txt', defaultOptions({
-          to: 'de,fr', output: '/tmp/out',
-          from: 'en', translationMemory: TM_UUID, tmThreshold: 85,
-        }));
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({
+            to: 'de,fr',
+            output: '/tmp/out',
+            from: 'en',
+            translationMemory: TM_UUID,
+            tmThreshold: 85,
+          })
+        );
 
-        const call = mocks.fileTranslationService.translateFileToMultiple.mock.calls[0]!;
-        expect(call[2]).toEqual(expect.objectContaining({ translationMemoryThreshold: 85 }));
+        const call =
+          mocks.fileTranslationService.translateFileToMultiple.mock.calls[0]!;
+        expect(call[2]).toEqual(
+          expect.objectContaining({ translationMemoryThreshold: 85 })
+        );
       });
 
       it('TM name resolution in multi-target: surfaces clean pair-check error when TM target_lang does not match all requested targets', async () => {
         mocks.translationService.listTranslationMemories.mockResolvedValue([
-          { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+          {
+            translation_memory_id: TM_UUID,
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+          },
         ]);
 
         const err = await handler
-          .translateFile('/tmp/file.txt', defaultOptions({
-            to: 'de,fr', output: '/tmp/out',
-            from: 'en', translationMemory: 'my-tm',
-          }))
-          .catch(e => e);
-        expect((err as Error).message).toContain('does not support the requested language pair');
-        expect(mocks.fileTranslationService.translateFileToMultiple).not.toHaveBeenCalled();
+          .translateFile(
+            '/tmp/file.txt',
+            defaultOptions({
+              to: 'de,fr',
+              output: '/tmp/out',
+              from: 'en',
+              translationMemory: 'my-tm',
+            })
+          )
+          .catch((e) => e);
+        expect((err as Error).message).toContain(
+          'does not support the requested language pair'
+        );
+        expect(
+          mocks.fileTranslationService.translateFileToMultiple
+        ).not.toHaveBeenCalled();
       });
     });
 
@@ -247,7 +378,10 @@ describe('FileTranslationHandler', () => {
       mockedGetFileSize.mockReturnValue(50);
       mockedSafeReadFileSync.mockReturnValue('file content');
 
-      const result = await handler.translateFile('/tmp/file.txt', defaultOptions());
+      const result = await handler.translateFile(
+        '/tmp/file.txt',
+        defaultOptions()
+      );
 
       expect(mocks.translationService.translate).toHaveBeenCalledWith(
         'file content',
@@ -260,9 +394,14 @@ describe('FileTranslationHandler', () => {
     it('should use document API with warning for large text-based files when document supported', async () => {
       mockedIsTextBasedFile.mockReturnValue(true);
       mockedGetFileSize.mockReturnValue(SAFE_TEXT_SIZE_LIMIT + 1);
-      mocks.documentTranslationService.isDocumentSupported.mockReturnValue(true);
+      mocks.documentTranslationService.isDocumentSupported.mockReturnValue(
+        true
+      );
 
-      const result = await handler.translateFile('/tmp/file.txt', defaultOptions());
+      const result = await handler.translateFile(
+        '/tmp/file.txt',
+        defaultOptions()
+      );
 
       expect(mockDocHandler.translateDocument).toHaveBeenCalled();
       expect(result).toContain('100 KiB');
@@ -273,7 +412,10 @@ describe('FileTranslationHandler', () => {
       mockedGetFileSize.mockReturnValue(50);
       mockedIsStructuredFile.mockReturnValue(true);
 
-      const result = await handler.translateFile('/tmp/file.json', defaultOptions());
+      const result = await handler.translateFile(
+        '/tmp/file.json',
+        defaultOptions()
+      );
 
       expect(mocks.fileTranslationService.translateFile).toHaveBeenCalled();
       expect(result).toContain('Translated');
@@ -281,11 +423,16 @@ describe('FileTranslationHandler', () => {
 
     it('should use documentHandler for document-supported files', async () => {
       mockedIsTextBasedFile.mockReturnValue(false);
-      mocks.documentTranslationService.isDocumentSupported.mockReturnValue(true);
+      mocks.documentTranslationService.isDocumentSupported.mockReturnValue(
+        true
+      );
 
       await handler.translateFile('/tmp/doc.pdf', defaultOptions());
 
-      expect(mockDocHandler.translateDocument).toHaveBeenCalledWith('/tmp/doc.pdf', defaultOptions());
+      expect(mockDocHandler.translateDocument).toHaveBeenCalledWith(
+        '/tmp/doc.pdf',
+        defaultOptions()
+      );
     });
 
     it('should write to stdout when output is "-"', async () => {
@@ -294,9 +441,14 @@ describe('FileTranslationHandler', () => {
       mockedIsStructuredFile.mockReturnValue(false);
       mockedSafeReadFileSync.mockReturnValue('file content');
 
-      const stdoutWrite = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+      const stdoutWrite = jest
+        .spyOn(process.stdout, 'write')
+        .mockImplementation(() => true);
 
-      const result = await handler.translateFile('/tmp/file.txt', defaultOptions({ output: '-' }));
+      const result = await handler.translateFile(
+        '/tmp/file.txt',
+        defaultOptions({ output: '-' })
+      );
 
       expect(stdoutWrite).toHaveBeenCalledWith('translated');
       expect(result).toBe('');
@@ -310,10 +462,16 @@ describe('FileTranslationHandler', () => {
       mocks.glossaryService.resolveGlossaryId.mockResolvedValue('glossary-123');
 
       await expect(
-        handler.translateFile('/tmp/file.txt', defaultOptions({ glossary: ['my-glossary'] }))
+        handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({ glossary: ['my-glossary'] })
+        )
       ).rejects.toThrow(ValidationError);
       await expect(
-        handler.translateFile('/tmp/file.txt', defaultOptions({ glossary: ['my-glossary'] }))
+        handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({ glossary: ['my-glossary'] })
+        )
       ).rejects.toThrow('Source language (--from) is required');
     });
 
@@ -332,9 +490,14 @@ describe('FileTranslationHandler', () => {
 
     it('should fall back to fileTranslationService.translateFile for non-text non-document files', async () => {
       mockedIsTextBasedFile.mockReturnValue(false);
-      mocks.documentTranslationService.isDocumentSupported.mockReturnValue(false);
+      mocks.documentTranslationService.isDocumentSupported.mockReturnValue(
+        false
+      );
 
-      const result = await handler.translateFile('/tmp/file.xyz', defaultOptions());
+      const result = await handler.translateFile(
+        '/tmp/file.xyz',
+        defaultOptions()
+      );
 
       expect(mocks.fileTranslationService.translateFile).toHaveBeenCalledWith(
         '/tmp/file.xyz',
@@ -355,34 +518,57 @@ describe('FileTranslationHandler', () => {
 
       it('throws ValidationError (exit 6) when --translation-memory used without --from', async () => {
         const err = await handler
-          .translateFile('/tmp/file.txt', defaultOptions({ translationMemory: 'my-tm' }))
-          .catch(e => e);
+          .translateFile(
+            '/tmp/file.txt',
+            defaultOptions({ translationMemory: 'my-tm' })
+          )
+          .catch((e) => e);
         expect(err).toBeInstanceOf(ValidationError);
         expect((err as ValidationError).exitCode).toBe(6);
-        expect((err as Error).message).toContain('--from is required when using --translation-memory');
+        expect((err as Error).message).toContain(
+          '--from is required when using --translation-memory'
+        );
       });
 
       it('throws ValidationError (exit 6) when combined with latency_optimized', async () => {
         const err = await handler
-          .translateFile('/tmp/file.txt', defaultOptions({
-            from: 'en', translationMemory: 'my-tm', modelType: 'latency_optimized',
-          }))
-          .catch(e => e);
+          .translateFile(
+            '/tmp/file.txt',
+            defaultOptions({
+              from: 'en',
+              translationMemory: 'my-tm',
+              modelType: 'latency_optimized',
+            })
+          )
+          .catch((e) => e);
         expect(err).toBeInstanceOf(ValidationError);
         expect((err as ValidationError).exitCode).toBe(6);
-        expect((err as Error).message).toContain('requires quality_optimized model type');
+        expect((err as Error).message).toContain(
+          'requires quality_optimized model type'
+        );
       });
 
       it('resolves TM name and passes resolved UUID to translate() for small text files', async () => {
         mocks.translationService.listTranslationMemories.mockResolvedValue([
-          { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+          {
+            translation_memory_id: TM_UUID,
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+          },
         ]);
 
-        await handler.translateFile('/tmp/file.txt', defaultOptions({
-          from: 'en', translationMemory: 'my-tm',
-        }));
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({
+            from: 'en',
+            translationMemory: 'my-tm',
+          })
+        );
 
-        expect(mocks.translationService.listTranslationMemories).toHaveBeenCalledTimes(1);
+        expect(
+          mocks.translationService.listTranslationMemories
+        ).toHaveBeenCalledTimes(1);
         expect(mocks.translationService.translate).toHaveBeenCalledWith(
           'file content',
           expect.objectContaining({
@@ -397,14 +583,25 @@ describe('FileTranslationHandler', () => {
       it('resolves TM name and passes resolved UUID to fileTranslationService.translateFile for structured files', async () => {
         mockedIsStructuredFile.mockReturnValue(true);
         mocks.translationService.listTranslationMemories.mockResolvedValue([
-          { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+          {
+            translation_memory_id: TM_UUID,
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+          },
         ]);
 
-        await handler.translateFile('/tmp/file.json', defaultOptions({
-          from: 'en', translationMemory: 'my-tm',
-        }));
+        await handler.translateFile(
+          '/tmp/file.json',
+          defaultOptions({
+            from: 'en',
+            translationMemory: 'my-tm',
+          })
+        );
 
-        expect(mocks.translationService.listTranslationMemories).toHaveBeenCalledTimes(1);
+        expect(
+          mocks.translationService.listTranslationMemories
+        ).toHaveBeenCalledTimes(1);
         expect(mocks.fileTranslationService.translateFile).toHaveBeenCalledWith(
           '/tmp/file.json',
           '/tmp/output.txt',
@@ -418,12 +615,22 @@ describe('FileTranslationHandler', () => {
 
       it('passes --tm-threshold through as translationMemoryThreshold', async () => {
         mocks.translationService.listTranslationMemories.mockResolvedValue([
-          { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+          {
+            translation_memory_id: TM_UUID,
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+          },
         ]);
 
-        await handler.translateFile('/tmp/file.txt', defaultOptions({
-          from: 'en', translationMemory: 'my-tm', tmThreshold: 85,
-        }));
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({
+            from: 'en',
+            translationMemory: 'my-tm',
+            tmThreshold: 85,
+          })
+        );
 
         expect(mocks.translationService.translate).toHaveBeenCalledWith(
           'file content',
@@ -433,11 +640,17 @@ describe('FileTranslationHandler', () => {
       });
 
       it('UUID fast-path: does NOT call listTranslationMemories when a UUID is passed', async () => {
-        await handler.translateFile('/tmp/file.txt', defaultOptions({
-          from: 'en', translationMemory: TM_UUID,
-        }));
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({
+            from: 'en',
+            translationMemory: TM_UUID,
+          })
+        );
 
-        expect(mocks.translationService.listTranslationMemories).not.toHaveBeenCalled();
+        expect(
+          mocks.translationService.listTranslationMemories
+        ).not.toHaveBeenCalled();
         expect(mocks.translationService.translate).toHaveBeenCalledWith(
           'file content',
           expect.objectContaining({ translationMemoryId: TM_UUID }),
@@ -447,12 +660,21 @@ describe('FileTranslationHandler', () => {
 
       it('forces modelType=quality_optimized when --translation-memory set and no --model-type given', async () => {
         mocks.translationService.listTranslationMemories.mockResolvedValue([
-          { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+          {
+            translation_memory_id: TM_UUID,
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+          },
         ]);
 
-        await handler.translateFile('/tmp/file.txt', defaultOptions({
-          from: 'en', translationMemory: 'my-tm',
-        }));
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({
+            from: 'en',
+            translationMemory: 'my-tm',
+          })
+        );
 
         expect(mocks.translationService.translate).toHaveBeenCalledWith(
           'file content',
diff --git a/tests/unit/file-translation-service.test.ts b/tests/unit/file-translation-service.test.ts
index 00c53a17..531c8abb 100644
--- a/tests/unit/file-translation-service.test.ts
+++ b/tests/unit/file-translation-service.test.ts
@@ -98,9 +98,14 @@ describe('FileTranslationService', () => {
         detectedSourceLang: 'en',
       });
 
-      await fileTranslationService.translateFile(inputPath, outputPath, {
-        targetLang: 'es',
-      }, { preserveCode: true });
+      await fileTranslationService.translateFile(
+        inputPath,
+        outputPath,
+        {
+          targetLang: 'es',
+        },
+        { preserveCode: true }
+      );
 
       const output = fs.readFileSync(outputPath, 'utf-8');
       expect(output).toContain('```js\nconst x = 1;\n```');
@@ -302,7 +307,9 @@ describe('FileTranslationService', () => {
     let stdoutWriteSpy: jest.SpyInstance;
 
     beforeEach(() => {
-      stdoutWriteSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+      stdoutWriteSpy = jest
+        .spyOn(process.stdout, 'write')
+        .mockImplementation(() => true);
     });
 
     afterEach(() => {
diff --git a/tests/unit/formats-android-cdata.test.ts b/tests/unit/formats-android-cdata.test.ts
index 1174b5c8..34238989 100644
--- a/tests/unit/formats-android-cdata.test.ts
+++ b/tests/unit/formats-android-cdata.test.ts
@@ -36,7 +36,9 @@ describe('Android XML CDATA safety', () => {
       translation: e.key === 'body' ? BREAKOUT : e.value,
     }));
 
-    expect(() => parser.reconstruct(WITH_CDATA, translated)).toThrow(ValidationError);
+    expect(() => parser.reconstruct(WITH_CDATA, translated)).toThrow(
+      ValidationError
+    );
     expect(() => parser.reconstruct(WITH_CDATA, translated)).toThrow(/CDATA/);
   });
 
@@ -47,8 +49,11 @@ describe('Android XML CDATA safety', () => {
     expect(() =>
       parser.reconstruct(
         WITH_CDATA,
-        entries.map((e) => ({ ...e, translation: e.key === 'body' ? 'array]]> end' : e.value })),
-      ),
+        entries.map((e) => ({
+          ...e,
+          translation: e.key === 'body' ? 'array]]> end' : e.value,
+        }))
+      )
     ).toThrow(/"\]\]>"/);
   });
 
@@ -72,11 +77,14 @@ describe('Android XML CDATA safety', () => {
           metadata: {
             plurals: [
               { quantity: 'one', value: '<b>1</b> Element' },
-              { quantity: 'other', value: `]]><string name="injected">x</string><![CDATA[` },
+              {
+                quantity: 'other',
+                value: `]]><string name="injected">x</string><![CDATA[`,
+              },
             ],
           },
         },
-      ]),
+      ])
     ).toThrow(ValidationError);
   });
 
@@ -92,8 +100,12 @@ describe('Android XML CDATA safety', () => {
 
     expect(() =>
       parser.reconstruct(xml, [
-        { key: 'labels.0', value: 'Less < More', translation: ']]></item><item>injected<![CDATA[' },
-      ]),
+        {
+          key: 'labels.0',
+          value: 'Less < More',
+          translation: ']]></item><item>injected<![CDATA[',
+        },
+      ])
     ).toThrow(ValidationError);
   });
 
@@ -110,9 +122,9 @@ describe('Android XML CDATA safety', () => {
     ]);
 
     expect(out).toContain('array]]&gt; end');
-    expect(new Map(parser.extract(out).map((e) => [e.key, e.value])).get('plain')).toBe(
-      'array]]> end',
-    );
+    expect(
+      new Map(parser.extract(out).map((e) => [e.key, e.value])).get('plain')
+    ).toBe('array]]> end');
   });
 
   it('should keep CDATA output well-formed for ordinary translations', () => {
@@ -121,13 +133,16 @@ describe('Android XML CDATA safety', () => {
 
     const out = parser.reconstruct(
       WITH_CDATA,
-      entries.map((e) => ({ ...e, translation: e.key === 'body' ? '<b>Fett</b> Text' : e.value })),
+      entries.map((e) => ({
+        ...e,
+        translation: e.key === 'body' ? '<b>Fett</b> Text' : e.value,
+      }))
     );
 
     expect(out).toContain('<![CDATA[<b>Fett</b> Text]]>');
-    expect(new Map(parser.extract(out).map((e) => [e.key, e.value])).get('body')).toBe(
-      '<b>Fett</b> Text',
-    );
+    expect(
+      new Map(parser.extract(out).map((e) => [e.key, e.value])).get('body')
+    ).toBe('<b>Fett</b> Text');
   });
 
   it('should never re-extract more entries than the template declares', () => {
@@ -136,7 +151,10 @@ describe('Android XML CDATA safety', () => {
 
     const out = parser.reconstruct(
       WITH_CDATA,
-      entries.map((e) => ({ ...e, translation: e.key === 'body' ? '<i>x</i>' : e.value })),
+      entries.map((e) => ({
+        ...e,
+        translation: e.key === 'body' ? '<i>x</i>' : e.value,
+      }))
     );
 
     expect(parser.extract(out)).toHaveLength(entries.length);
diff --git a/tests/unit/formats-crlf.test.ts b/tests/unit/formats-crlf.test.ts
index 413ec27a..fed6eb18 100644
--- a/tests/unit/formats-crlf.test.ts
+++ b/tests/unit/formats-crlf.test.ts
@@ -25,7 +25,8 @@ const CASES: LineBasedCase[] = [
   {
     label: 'PO',
     parser: () => new PoFormatParser(),
-    source: 'msgid "greeting"\nmsgstr "Hello"\n\nmsgid "farewell"\nmsgstr "Goodbye"\n',
+    source:
+      'msgid "greeting"\nmsgstr "Hello"\n\nmsgid "farewell"\nmsgstr "Goodbye"\n',
     expectedKeys: ['greeting', 'farewell'],
   },
   {
@@ -53,16 +54,24 @@ describe('line-based parsers with CRLF line endings', () => {
     const crlf = source.replace(/\n/g, '\r\n');
 
     it('should extract the same keys from LF and CRLF sources', () => {
-      const fromLf = parser().extract(source).map((e) => e.key);
-      const fromCrlf = parser().extract(crlf).map((e) => e.key);
+      const fromLf = parser()
+        .extract(source)
+        .map((e) => e.key);
+      const fromCrlf = parser()
+        .extract(crlf)
+        .map((e) => e.key);
 
       expect(fromLf).toEqual(expect.arrayContaining(expectedKeys));
       expect(fromCrlf).toEqual(fromLf);
     });
 
     it('should extract the same values from LF and CRLF sources', () => {
-      const fromLf = parser().extract(source).map((e) => e.value);
-      const fromCrlf = parser().extract(crlf).map((e) => e.value);
+      const fromLf = parser()
+        .extract(source)
+        .map((e) => e.value);
+      const fromCrlf = parser()
+        .extract(crlf)
+        .map((e) => e.value);
 
       expect(fromCrlf).toEqual(fromLf);
       // A stray \r must not survive into an extracted value.
@@ -79,7 +88,10 @@ describe('line-based parsers with CRLF line endings', () => {
 
     it('should reconstruct a CRLF source without losing entries', () => {
       const entries = parser().extract(crlf);
-      const translated = entries.map((e) => ({ ...e, translation: `[de]${e.value}` }));
+      const translated = entries.map((e) => ({
+        ...e,
+        translation: `[de]${e.value}`,
+      }));
 
       const out = parser().reconstruct(crlf, translated);
       const reExtracted = parser().extract(out);
diff --git a/tests/unit/formats-roundtrip.test.ts b/tests/unit/formats-roundtrip.test.ts
index de5338ef..ff7bc53e 100644
--- a/tests/unit/formats-roundtrip.test.ts
+++ b/tests/unit/formats-roundtrip.test.ts
@@ -32,7 +32,7 @@ describe('parser round-trip stability', () => {
 
       const out = parser.reconstruct(
         source,
-        entries.map((e) => ({ ...e, translation: e.value })),
+        entries.map((e) => ({ ...e, translation: e.value }))
       );
 
       expect(out).not.toContain('&amp;amp;');
@@ -49,9 +49,14 @@ describe('parser round-trip stability', () => {
         // Identity "translation": any drift is the parser's, not the engine's.
         content = parser.reconstruct(
           content,
-          entries.map((e) => ({ ...e, translation: e.value })),
+          entries.map((e) => ({ ...e, translation: e.value }))
+        );
+        seen.push(
+          parser
+            .extract(content)
+            .map((e) => `${e.key}=${e.value}`)
+            .join('|')
         );
-        seen.push(parser.extract(content).map((e) => `${e.key}=${e.value}`).join('|'));
       }
 
       expect(seen[1]).toBe(seen[0]);
@@ -69,7 +74,7 @@ describe('parser round-trip stability', () => {
 
       const out = parser.reconstruct(
         source,
-        entries.map((e) => ({ ...e, translation: 'Hello 😀 world' })),
+        entries.map((e) => ({ ...e, translation: 'Hello 😀 world' }))
       );
 
       // A lone high surrogate (\ud83d with no \ude00) is malformed and
@@ -81,7 +86,9 @@ describe('parser round-trip stability', () => {
       const parser = new PropertiesFormatParser();
       const withEmoji = parser.reconstruct(
         source,
-        parser.extract(source).map((e) => ({ ...e, translation: 'Hello 😀 world' })),
+        parser
+          .extract(source)
+          .map((e) => ({ ...e, translation: 'Hello 😀 world' }))
       );
 
       const reExtracted = parser.extract(withEmoji);
@@ -93,7 +100,9 @@ describe('parser round-trip stability', () => {
       const parser = new PropertiesFormatParser();
       const withUmlaut = parser.reconstruct(
         source,
-        parser.extract(source).map((e) => ({ ...e, translation: 'Grüße, Welt' })),
+        parser
+          .extract(source)
+          .map((e) => ({ ...e, translation: 'Grüße, Welt' }))
       );
 
       expect(parser.extract(withUmlaut)[0]?.value).toBe('Grüße, Welt');
@@ -105,7 +114,7 @@ describe('parser round-trip stability', () => {
       for (const translation of [' padded', '  two leading', ' ', ' x ']) {
         const out = parser.reconstruct(
           source,
-          parser.extract(source).map((e) => ({ ...e, translation })),
+          parser.extract(source).map((e) => ({ ...e, translation }))
         );
 
         // An unescaped leading space is trimmed by the value parser (per the
diff --git a/tests/unit/formats-toml-sections.test.ts b/tests/unit/formats-toml-sections.test.ts
index 4c3caacb..97011848 100644
--- a/tests/unit/formats-toml-sections.test.ts
+++ b/tests/unit/formats-toml-sections.test.ts
@@ -17,10 +17,17 @@ describe('TOML section handling for new keys', () => {
 
     const out = parser.reconstruct(sectioned, [
       { key: 'messages.greeting', value: 'Hello', translation: 'Hallo' },
-      { key: 'messages.farewell', value: 'Goodbye', translation: 'Auf Wiedersehen' },
+      {
+        key: 'messages.farewell',
+        value: 'Goodbye',
+        translation: 'Auf Wiedersehen',
+      },
     ]);
 
-    const keys = parser.extract(out).map((e) => e.key).sort();
+    const keys = parser
+      .extract(out)
+      .map((e) => e.key)
+      .sort();
     expect(keys).toEqual(['messages.farewell', 'messages.greeting']);
     expect(out).not.toContain('messages.messages');
   });
@@ -30,7 +37,11 @@ describe('TOML section handling for new keys', () => {
 
     const out = parser.reconstruct(sectioned, [
       { key: 'messages.greeting', value: 'Hello', translation: 'Hallo' },
-      { key: 'messages.farewell', value: 'Goodbye', translation: 'Auf Wiedersehen' },
+      {
+        key: 'messages.farewell',
+        value: 'Goodbye',
+        translation: 'Auf Wiedersehen',
+      },
     ]);
 
     // A duplicated section header or doubled path throws here.
@@ -41,7 +52,11 @@ describe('TOML section handling for new keys', () => {
     const parser = new TomlFormatParser();
     const entries = [
       { key: 'messages.greeting', value: 'Hello', translation: 'Hallo' },
-      { key: 'messages.farewell', value: 'Goodbye', translation: 'Auf Wiedersehen' },
+      {
+        key: 'messages.farewell',
+        value: 'Goodbye',
+        translation: 'Auf Wiedersehen',
+      },
     ];
 
     const first = parser.reconstruct(sectioned, entries);
@@ -59,7 +74,12 @@ describe('TOML section handling for new keys', () => {
       { key: 'farewell', value: 'Goodbye', translation: 'Auf Wiedersehen' },
     ]);
 
-    expect(parser.extract(out).map((e) => e.key).sort()).toEqual(['farewell', 'greeting']);
+    expect(
+      parser
+        .extract(out)
+        .map((e) => e.key)
+        .sort()
+    ).toEqual(['farewell', 'greeting']);
   });
 
   describe('multi-line string blocks', () => {
@@ -82,7 +102,10 @@ describe('TOML section handling for new keys', () => {
 
       const out = parser.reconstruct(
         multiline,
-        entries.map((e) => ({ ...e, translation: e.key === 'greeting' ? 'Hallo' : e.value })),
+        entries.map((e) => ({
+          ...e,
+          translation: e.key === 'greeting' ? 'Hallo' : e.value,
+        }))
       );
 
       expect(out).toContain('setting = "this looks like a key"');
@@ -95,11 +118,19 @@ describe('TOML section handling for new keys', () => {
 
       const out = parser.reconstruct(
         multiline,
-        entries.map((e) => ({ ...e, translation: e.key === 'greeting' ? 'Hallo' : e.value })),
+        entries.map((e) => ({
+          ...e,
+          translation: e.key === 'greeting' ? 'Hallo' : e.value,
+        }))
       );
 
       expect(() => parser.extract(out)).not.toThrow();
-      expect(parser.extract(out).map((e) => e.key).sort()).toEqual(['greeting', 'intro']);
+      expect(
+        parser
+          .extract(out)
+          .map((e) => e.key)
+          .sort()
+      ).toEqual(['greeting', 'intro']);
     });
 
     it('should still translate ordinary keys alongside a multi-line block', () => {
@@ -108,7 +139,10 @@ describe('TOML section handling for new keys', () => {
 
       const out = parser.reconstruct(
         multiline,
-        entries.map((e) => ({ ...e, translation: e.key === 'greeting' ? 'Hallo' : e.value })),
+        entries.map((e) => ({
+          ...e,
+          translation: e.key === 'greeting' ? 'Hallo' : e.value,
+        }))
       );
 
       const byKey = new Map(parser.extract(out).map((e) => [e.key, e.value]));
@@ -122,11 +156,18 @@ describe('TOML section handling for new keys', () => {
 
       const out = parser.reconstruct(
         source,
-        entries.map((e) => ({ ...e, translation: e.key === 'greeting' ? 'Hallo' : e.value })),
+        entries.map((e) => ({
+          ...e,
+          translation: e.key === 'greeting' ? 'Hallo' : e.value,
+        }))
       );
 
       expect(() => parser.extract(out)).not.toThrow();
-      expect(new Map(parser.extract(out).map((e) => [e.key, e.value])).get('greeting')).toBe('Hallo');
+      expect(
+        new Map(parser.extract(out).map((e) => [e.key, e.value])).get(
+          'greeting'
+        )
+      ).toBe('Hallo');
     });
   });
 
@@ -135,10 +176,17 @@ describe('TOML section handling for new keys', () => {
 
     const out = parser.reconstruct(sectioned, [
       { key: 'messages.greeting', value: 'Hello', translation: 'Hallo' },
-      { key: 'errors.notFound', value: 'Not found', translation: 'Nicht gefunden' },
+      {
+        key: 'errors.notFound',
+        value: 'Not found',
+        translation: 'Nicht gefunden',
+      },
     ]);
 
-    const keys = parser.extract(out).map((e) => e.key).sort();
+    const keys = parser
+      .extract(out)
+      .map((e) => e.key)
+      .sort();
     expect(keys).toEqual(['errors.notFound', 'messages.greeting']);
   });
 });
diff --git a/tests/unit/formats-xcstrings-arb.test.ts b/tests/unit/formats-xcstrings-arb.test.ts
index d2ff0de7..aff39517 100644
--- a/tests/unit/formats-xcstrings-arb.test.ts
+++ b/tests/unit/formats-xcstrings-arb.test.ts
@@ -21,20 +21,26 @@ describe('Xcode String Catalog localizations', () => {
             de: {
               variations: {
                 plural: {
-                  one: { stringUnit: { state: 'translated', value: '%lld Artikel' } },
-                  other: { stringUnit: { state: 'translated', value: '%lld Artikel' } },
+                  one: {
+                    stringUnit: { state: 'translated', value: '%lld Artikel' },
+                  },
+                  other: {
+                    stringUnit: { state: 'translated', value: '%lld Artikel' },
+                  },
                 },
               },
             },
           },
         },
         greeting: {
-          localizations: { en: { stringUnit: { state: 'translated', value: 'Hello' } } },
+          localizations: {
+            en: { stringUnit: { state: 'translated', value: 'Hello' } },
+          },
         },
       },
     },
     null,
-    2,
+    2
   );
 
   it('should not destroy plural variations of the key being translated', () => {
@@ -45,13 +51,18 @@ describe('Xcode String Catalog localizations', () => {
     const out = parser.reconstruct(
       withVariations,
       [{ key: 'item_count', value: '%lld items', translation: '%lld Artikel' }],
-      'de',
+      'de'
     );
 
     const parsed = JSON.parse(out) as {
-      strings: Record<string, { localizations?: Record<string, Record<string, unknown>> }>;
+      strings: Record<
+        string,
+        { localizations?: Record<string, Record<string, unknown>> }
+      >;
     };
-    expect(parsed.strings['item_count']?.localizations?.['de']?.['variations']).toBeDefined();
+    expect(
+      parsed.strings['item_count']?.localizations?.['de']?.['variations']
+    ).toBeDefined();
   });
 
   it('should not destroy variations of an untranslated key', () => {
@@ -60,13 +71,18 @@ describe('Xcode String Catalog localizations', () => {
     const out = parser.reconstruct(
       withVariations,
       [{ key: 'greeting', value: 'Hello', translation: 'Hallo' }],
-      'de',
+      'de'
     );
 
     const parsed = JSON.parse(out) as {
-      strings: Record<string, { localizations?: Record<string, Record<string, unknown>> }>;
+      strings: Record<
+        string,
+        { localizations?: Record<string, Record<string, unknown>> }
+      >;
     };
-    expect(parsed.strings['item_count']?.localizations?.['de']?.['variations']).toBeDefined();
+    expect(
+      parsed.strings['item_count']?.localizations?.['de']?.['variations']
+    ).toBeDefined();
   });
 
   it('should still write the translation for the requested key', () => {
@@ -75,7 +91,7 @@ describe('Xcode String Catalog localizations', () => {
     const out = parser.reconstruct(
       withVariations,
       [{ key: 'greeting', value: 'Hello', translation: 'Hallo' }],
-      'de',
+      'de'
     );
 
     const parsed = JSON.parse(out) as {
@@ -84,7 +100,9 @@ describe('Xcode String Catalog localizations', () => {
         { localizations?: Record<string, { stringUnit?: { value?: string } }> }
       >;
     };
-    expect(parsed.strings['greeting']?.localizations?.['de']?.stringUnit?.value).toBe('Hallo');
+    expect(
+      parsed.strings['greeting']?.localizations?.['de']?.stringUnit?.value
+    ).toBe('Hallo');
   });
 
   it('should leave other locales untouched', () => {
@@ -93,7 +111,7 @@ describe('Xcode String Catalog localizations', () => {
     const out = parser.reconstruct(
       withVariations,
       [{ key: 'greeting', value: 'Hello', translation: 'Hallo' }],
-      'de',
+      'de'
     );
 
     const parsed = JSON.parse(out) as {
@@ -102,12 +120,18 @@ describe('Xcode String Catalog localizations', () => {
         { localizations?: Record<string, { stringUnit?: { value?: string } }> }
       >;
     };
-    expect(parsed.strings['greeting']?.localizations?.['en']?.stringUnit?.value).toBe('Hello');
+    expect(
+      parsed.strings['greeting']?.localizations?.['en']?.stringUnit?.value
+    ).toBe('Hello');
   });
 });
 
 describe('ARB byte-order mark', () => {
-  const body = JSON.stringify({ greeting: 'Hello', '@greeting': { description: 'A greeting' } }, null, 2);
+  const body = JSON.stringify(
+    { greeting: 'Hello', '@greeting': { description: 'A greeting' } },
+    null,
+    2
+  );
 
   it('should extract from a BOM-prefixed file', () => {
     const entries = new ArbFormatParser().extract('' + body);
@@ -131,7 +155,9 @@ describe('ARB byte-order mark', () => {
     const parser = new ArbFormatParser();
 
     const withoutBom = parser.extract(body).map((e) => `${e.key}=${e.value}`);
-    const withBom = parser.extract('' + body).map((e) => `${e.key}=${e.value}`);
+    const withBom = parser
+      .extract('' + body)
+      .map((e) => `${e.key}=${e.value}`);
 
     expect(withBom).toEqual(withoutBom);
   });
diff --git a/tests/unit/formats-xliff-attributes.test.ts b/tests/unit/formats-xliff-attributes.test.ts
index 8661e71d..4fe117d6 100644
--- a/tests/unit/formats-xliff-attributes.test.ts
+++ b/tests/unit/formats-xliff-attributes.test.ts
@@ -50,7 +50,10 @@ describe('XLIFF elements with attributes', () => {
     it('should not delete the unit on reconstruct', () => {
       const parser = new XliffFormatParser();
       const entries = parser.extract(V20_WITH_STATE);
-      const translated = entries.map((e) => ({ ...e, translation: 'Guten Tag' }));
+      const translated = entries.map((e) => ({
+        ...e,
+        translation: 'Guten Tag',
+      }));
 
       const out = parser.reconstruct(V20_WITH_STATE, translated);
 
@@ -65,7 +68,7 @@ describe('XLIFF elements with attributes', () => {
 
       const out = parser.reconstruct(
         V20_WITH_STATE,
-        entries.map((e) => ({ ...e, translation: 'Guten Tag' })),
+        entries.map((e) => ({ ...e, translation: 'Guten Tag' }))
       );
 
       expect(out).toContain('state="initial"');
@@ -79,7 +82,7 @@ describe('XLIFF elements with attributes', () => {
 
       const out = parser.reconstruct(
         V12_WITH_STATE,
-        entries.map((e) => ({ ...e, translation: 'Guten Tag' })),
+        entries.map((e) => ({ ...e, translation: 'Guten Tag' }))
       );
 
       const targetOpenTags = out.match(/<target[\s>]/g) ?? [];
@@ -94,7 +97,7 @@ describe('XLIFF elements with attributes', () => {
 
       const out = parser.reconstruct(
         V12_WITH_STATE,
-        entries.map((e) => ({ ...e, translation: 'Guten Tag' })),
+        entries.map((e) => ({ ...e, translation: 'Guten Tag' }))
       );
 
       expect(out).toContain('state="needs-translation"');
diff --git a/tests/unit/formats/android-xml.test.ts b/tests/unit/formats/android-xml.test.ts
index e865eb1d..e024546c 100644
--- a/tests/unit/formats/android-xml.test.ts
+++ b/tests/unit/formats/android-xml.test.ts
@@ -22,7 +22,11 @@ describe('android-xml parser', () => {
       expect(entries[0]!.value).toBe('C:\\Users\\test');
 
       const translated: TranslatedEntry[] = [
-        { key: 'path', value: 'C:\\Users\\test', translation: 'C:\\Users\\test' },
+        {
+          key: 'path',
+          value: 'C:\\Users\\test',
+          translation: 'C:\\Users\\test',
+        },
       ];
       const result = parser.reconstruct(xml, translated);
       expect(result).toContain('C:\\\\Users\\\\test');
@@ -173,8 +177,12 @@ describe('android-xml parser', () => {
       ];
 
       const result = parser.reconstruct(xml, translated);
-      expect(result).toContain('<item quantity="one"><![CDATA[1 < Element]]></item>');
-      expect(result).toContain('<item quantity="other"><![CDATA[%d < Elemente]]></item>');
+      expect(result).toContain(
+        '<item quantity="one"><![CDATA[1 < Element]]></item>'
+      );
+      expect(result).toContain(
+        '<item quantity="other"><![CDATA[%d < Elemente]]></item>'
+      );
     });
 
     it('should preserve CDATA wrappers for string-array items during extract and reconstruct', () => {
@@ -193,8 +201,16 @@ describe('android-xml parser', () => {
       ]);
 
       const translated: TranslatedEntry[] = [
-        { key: 'labels.0', value: 'Less < More', translation: 'Weniger < Mehr' },
-        { key: 'labels.1', value: 'Rock & Roll', translation: 'Rock & Roll DE' },
+        {
+          key: 'labels.0',
+          value: 'Less < More',
+          translation: 'Weniger < Mehr',
+        },
+        {
+          key: 'labels.1',
+          value: 'Rock & Roll',
+          translation: 'Rock & Roll DE',
+        },
       ];
 
       const result = parser.reconstruct(xml, translated);
@@ -343,7 +359,9 @@ describe('android-xml parser', () => {
       const head = '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n';
       const opener =
         '    <string name="k">v\n    <plurals name="p">\n    <string-array name="a">\n';
-      return head + opener.repeat(Math.ceil((bytes - head.length) / opener.length));
+      return (
+        head + opener.repeat(Math.ceil((bytes - head.length) / opener.length))
+      );
     }
 
     const content = unclosedOpeners(4 * 1024 * 1024);
diff --git a/tests/unit/formats/arb.test.ts b/tests/unit/formats/arb.test.ts
index 0626b0e7..90f51a21 100644
--- a/tests/unit/formats/arb.test.ts
+++ b/tests/unit/formats/arb.test.ts
@@ -13,14 +13,19 @@ describe('arb parser', () => {
 
   describe('reconstruct removes deleted keys', () => {
     it('should remove keys and their @metadata when absent from entries', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 'A greeting' },
-        farewell: 'Goodbye',
-        '@farewell': { description: 'A farewell' },
-        deleted_key: 'Remove me',
-        '@deleted_key': { description: 'Should be removed' },
-      }, null, 2) + '\n';
+      const content =
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            '@greeting': { description: 'A greeting' },
+            farewell: 'Goodbye',
+            '@farewell': { description: 'A farewell' },
+            deleted_key: 'Remove me',
+            '@deleted_key': { description: 'Should be removed' },
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
@@ -38,9 +43,14 @@ describe('arb parser', () => {
 
   describe('reconstruct inserts new keys', () => {
     it('should add keys not present in the template', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-      }, null, 2) + '\n';
+      const content =
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
@@ -56,12 +66,17 @@ describe('arb parser', () => {
 
   describe('reconstruct() applies translations to existing keys', () => {
     it('should update values for all existing keys', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 'A greeting' },
-        farewell: 'Goodbye',
-        '@farewell': { description: 'A farewell' },
-      }, null, 2) + '\n';
+      const content =
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            '@greeting': { description: 'A greeting' },
+            farewell: 'Goodbye',
+            '@farewell': { description: 'A farewell' },
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Bonjour' },
@@ -77,12 +92,17 @@ describe('arb parser', () => {
 
   describe('reconstruct() preserves @metadata entries', () => {
     it('should keep @metadata for keys that are present in entries', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 'A greeting', type: 'text' },
-        farewell: 'Goodbye',
-        '@farewell': { description: 'A farewell' },
-      }, null, 2) + '\n';
+      const content =
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            '@greeting': { description: 'A greeting', type: 'text' },
+            farewell: 'Goodbye',
+            '@farewell': { description: 'A farewell' },
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
@@ -91,17 +111,25 @@ describe('arb parser', () => {
 
       const result = parser.reconstruct(content, entries);
       const parsed = JSON.parse(result);
-      expect(parsed['@greeting']).toEqual({ description: 'A greeting', type: 'text' });
+      expect(parsed['@greeting']).toEqual({
+        description: 'A greeting',
+        type: 'text',
+      });
       expect(parsed['@farewell']).toEqual({ description: 'A farewell' });
     });
 
     it('should remove @metadata for deleted keys but keep @metadata for retained keys', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 'A greeting' },
-        deleted: 'Remove',
-        '@deleted': { description: 'Will be removed' },
-      }, null, 2) + '\n';
+      const content =
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            '@greeting': { description: 'A greeting' },
+            deleted: 'Remove',
+            '@deleted': { description: 'Will be removed' },
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
@@ -118,11 +146,16 @@ describe('arb parser', () => {
 
   describe('reconstruct() preserves @@locale and top-level @ keys', () => {
     it('should preserve @@locale when present', () => {
-      const content = JSON.stringify({
-        '@@locale': 'en',
-        greeting: 'Hello',
-        '@greeting': { description: 'A greeting' },
-      }, null, 2) + '\n';
+      const content =
+        JSON.stringify(
+          {
+            '@@locale': 'en',
+            greeting: 'Hello',
+            '@greeting': { description: 'A greeting' },
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
@@ -137,53 +170,76 @@ describe('arb parser', () => {
 
   describe('extract() with @-prefixed keys', () => {
     it('should skip @@locale entry during extraction', () => {
-      const content = JSON.stringify({
-        '@@locale': 'en',
-        greeting: 'Hello',
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          '@@locale': 'en',
+          greeting: 'Hello',
+        },
+        null,
+        2
+      );
       const entries = parser.extract(content);
       expect(entries).toHaveLength(1);
       expect(entries[0]!.key).toBe('greeting');
     });
 
     it('should skip @metadata keys during extraction', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 'A greeting' },
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          '@greeting': { description: 'A greeting' },
+        },
+        null,
+        2
+      );
       const entries = parser.extract(content);
       expect(entries).toHaveLength(1);
       expect(entries[0]!.key).toBe('greeting');
     });
 
     it('should skip non-string values during extraction', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        count: 42,
-        flag: true,
-        nested: { inner: 'val' },
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          count: 42,
+          flag: true,
+          nested: { inner: 'val' },
+        },
+        null,
+        2
+      );
       const entries = parser.extract(content);
       expect(entries).toHaveLength(1);
       expect(entries[0]!.key).toBe('greeting');
     });
 
     it('should attach @key metadata and description as context', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 'Used on the home page', type: 'text' },
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          '@greeting': { description: 'Used on the home page', type: 'text' },
+        },
+        null,
+        2
+      );
       const entries = parser.extract(content);
       expect(entries).toHaveLength(1);
       expect(entries[0]!.context).toBe('Used on the home page');
-      expect(entries[0]!.metadata).toEqual({ description: 'Used on the home page', type: 'text' });
+      expect(entries[0]!.metadata).toEqual({
+        description: 'Used on the home page',
+        type: 'text',
+      });
     });
 
     it('should set metadata without context when @key has no description field', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { type: 'text', placeholders: {} },
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          '@greeting': { type: 'text', placeholders: {} },
+        },
+        null,
+        2
+      );
       const entries = parser.extract(content);
       expect(entries).toHaveLength(1);
       expect(entries[0]!.context).toBeUndefined();
@@ -191,10 +247,14 @@ describe('arb parser', () => {
     });
 
     it('should handle entry with no @metadata at all', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        farewell: 'Goodbye',
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          farewell: 'Goodbye',
+        },
+        null,
+        2
+      );
       const entries = parser.extract(content);
       expect(entries).toHaveLength(2);
       expect(entries[0]!.metadata).toBeUndefined();
@@ -202,10 +262,14 @@ describe('arb parser', () => {
     });
 
     it('should skip @metadata that is not an object (string value)', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': 'not an object',
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          '@greeting': 'not an object',
+        },
+        null,
+        2
+      );
       const entries = parser.extract(content);
       expect(entries).toHaveLength(1);
       expect(entries[0]!.metadata).toBeUndefined();
@@ -221,27 +285,39 @@ describe('arb parser', () => {
 
   describe('extractContext()', () => {
     it('should return description from @key metadata', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 'A welcome message' },
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          '@greeting': { description: 'A welcome message' },
+        },
+        null,
+        2
+      );
       const result = parser.extractContext(content, 'greeting');
       expect(result).toBe('A welcome message');
     });
 
     it('should return undefined when @key has no description', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { type: 'text' },
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          '@greeting': { type: 'text' },
+        },
+        null,
+        2
+      );
       const result = parser.extractContext(content, 'greeting');
       expect(result).toBeUndefined();
     });
 
     it('should return undefined when @key does not exist', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+        },
+        null,
+        2
+      );
       const result = parser.extractContext(content, 'greeting');
       expect(result).toBeUndefined();
     });
@@ -253,19 +329,27 @@ describe('arb parser', () => {
     });
 
     it('should return undefined when @key is a string not an object', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': 'just a string',
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          '@greeting': 'just a string',
+        },
+        null,
+        2
+      );
       const result = parser.extractContext(content, 'greeting');
       expect(result).toBeUndefined();
     });
 
     it('should return undefined when description is not a string', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 42 },
-      }, null, 2);
+      const content = JSON.stringify(
+        {
+          greeting: 'Hello',
+          '@greeting': { description: 42 },
+        },
+        null,
+        2
+      );
       const result = parser.extractContext(content, 'greeting');
       expect(result).toBeUndefined();
     });
@@ -301,10 +385,15 @@ describe('arb parser', () => {
     });
 
     it('should handle reconstruct with key absent from original (no translation match)', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        farewell: 'Goodbye',
-      }, null, 2) + '\n';
+      const content =
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            farewell: 'Goodbye',
+          },
+          null,
+          2
+        ) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
       ];
@@ -315,11 +404,16 @@ describe('arb parser', () => {
     });
 
     it('should handle reconstruct where deleted key has no @metadata', () => {
-      const content = JSON.stringify({
-        greeting: 'Hello',
-        '@greeting': { description: 'A greeting' },
-        orphan: 'No meta',
-      }, null, 2) + '\n';
+      const content =
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            '@greeting': { description: 'A greeting' },
+            orphan: 'No meta',
+          },
+          null,
+          2
+        ) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
       ];
diff --git a/tests/unit/formats/detect-indent.test.ts b/tests/unit/formats/detect-indent.test.ts
index 66b3c883..7dedc4b8 100644
--- a/tests/unit/formats/detect-indent.test.ts
+++ b/tests/unit/formats/detect-indent.test.ts
@@ -28,7 +28,9 @@ describe('detectIndent shared usage', () => {
     const entries: TranslatedEntry[] = [
       { key: 'greeting', value: 'Hello', translation: 'Hallo' },
     ];
-    expect(parser.reconstruct(original, entries)).toBe('{\n    "greeting": "Hallo"\n}\n');
+    expect(parser.reconstruct(original, entries)).toBe(
+      '{\n    "greeting": "Hallo"\n}\n'
+    );
   });
 
   it('preserves indentation round-trip in the ARB parser', () => {
@@ -37,7 +39,9 @@ describe('detectIndent shared usage', () => {
     const entries: TranslatedEntry[] = [
       { key: 'greeting', value: 'Hello', translation: 'Hallo' },
     ];
-    expect(parser.reconstruct(original, entries)).toBe('{\n\t"greeting": "Hallo"\n}\n');
+    expect(parser.reconstruct(original, entries)).toBe(
+      '{\n\t"greeting": "Hallo"\n}\n'
+    );
   });
 
   it('preserves indentation round-trip in the xcstrings parser', () => {
@@ -47,11 +51,15 @@ describe('detectIndent shared usage', () => {
         sourceLanguage: 'en',
         version: '1.0',
         strings: {
-          hi: { localizations: { en: { stringUnit: { state: 'translated', value: 'Hi' } } } },
+          hi: {
+            localizations: {
+              en: { stringUnit: { state: 'translated', value: 'Hi' } },
+            },
+          },
         },
       },
       null,
-      4,
+      4
     );
     const entries: TranslatedEntry[] = [
       { key: 'hi', value: 'Hi', translation: 'Hallo' },
@@ -64,7 +72,10 @@ describe('detectIndent shared usage', () => {
     const parser = new YamlFormatParser();
     const original = 'greeting: Hello\nfarewell: Goodbye\n';
     const entries = parser.extract(original);
-    const translated: TranslatedEntry[] = entries.map(e => ({ ...e, translation: e.value }));
+    const translated: TranslatedEntry[] = entries.map((e) => ({
+      ...e,
+      translation: e.value,
+    }));
     const result = parser.reconstruct(original, translated);
     expect(parser.extract(result)).toHaveLength(entries.length);
   });
diff --git a/tests/unit/formats/format-registry.test.ts b/tests/unit/formats/format-registry.test.ts
index 08d0aed1..a9f358a6 100644
--- a/tests/unit/formats/format-registry.test.ts
+++ b/tests/unit/formats/format-registry.test.ts
@@ -1,4 +1,8 @@
-import { FormatRegistry, SUPPORTED_FORMAT_KEYS, createDefaultRegistry } from '../../../src/formats/index';
+import {
+  FormatRegistry,
+  SUPPORTED_FORMAT_KEYS,
+  createDefaultRegistry,
+} from '../../../src/formats/index';
 import type { FormatParser } from '../../../src/formats/format';
 
 function createStubParser(overrides: Partial<FormatParser> = {}): FormatParser {
@@ -30,7 +34,10 @@ describe('FormatRegistry', () => {
   });
 
   it('should handle multiple extensions per parser', () => {
-    const parser = createStubParser({ name: 'YAML', extensions: ['.yaml', '.yml'] });
+    const parser = createStubParser({
+      name: 'YAML',
+      extensions: ['.yaml', '.yml'],
+    });
     registry.register(parser);
     expect(registry.getParser('.yaml')).toBe(parser);
     expect(registry.getParser('.yml')).toBe(parser);
@@ -44,8 +51,14 @@ describe('FormatRegistry', () => {
   });
 
   it('should overwrite existing parser for same extension', () => {
-    const parser1 = createStubParser({ name: 'Parser1', extensions: ['.json'] });
-    const parser2 = createStubParser({ name: 'Parser2', extensions: ['.json'] });
+    const parser1 = createStubParser({
+      name: 'Parser1',
+      extensions: ['.json'],
+    });
+    const parser2 = createStubParser({
+      name: 'Parser2',
+      extensions: ['.json'],
+    });
     registry.register(parser1);
     registry.register(parser2);
     expect(registry.getParser('.json')).toBe(parser2);
@@ -55,7 +68,9 @@ describe('FormatRegistry', () => {
     registry.register(createStubParser({ extensions: ['.json'] }));
     registry.register(createStubParser({ extensions: ['.yaml', '.yml'] }));
     const extensions = registry.getSupportedExtensions();
-    expect(extensions).toEqual(expect.arrayContaining(['.json', '.yaml', '.yml']));
+    expect(extensions).toEqual(
+      expect.arrayContaining(['.json', '.yaml', '.yml'])
+    );
     expect(extensions).toHaveLength(3);
   });
 
@@ -84,25 +99,47 @@ describe('createDefaultRegistry', () => {
     expect(registry.getParserByFormatKey('json')?.name).toBe('JSON i18n');
     expect(registry.getParserByFormatKey('yaml')?.name).toBe('YAML');
     expect(registry.getParserByFormatKey('po')?.name).toBe('PO (gettext)');
-    expect(registry.getParserByFormatKey('android_xml')?.name).toBe('Android XML');
-    expect(registry.getParserByFormatKey('ios_strings')?.name).toBe('iOS Strings');
+    expect(registry.getParserByFormatKey('android_xml')?.name).toBe(
+      'Android XML'
+    );
+    expect(registry.getParserByFormatKey('ios_strings')?.name).toBe(
+      'iOS Strings'
+    );
     expect(registry.getParserByFormatKey('arb')?.name).toBe('ARB (Flutter)');
     expect(registry.getParserByFormatKey('xliff')?.name).toBe('XLIFF');
     expect(registry.getParserByFormatKey('toml')?.name).toBe('TOML i18n');
-    expect(registry.getParserByFormatKey('properties')?.name).toBe('Java Properties');
-    expect(registry.getParserByFormatKey('xcstrings')?.name).toBe('Xcode String Catalog');
+    expect(registry.getParserByFormatKey('properties')?.name).toBe(
+      'Java Properties'
+    );
+    expect(registry.getParserByFormatKey('xcstrings')?.name).toBe(
+      'Xcode String Catalog'
+    );
   });
 });
 
 describe('SUPPORTED_FORMAT_KEYS', () => {
   it('matches the config keys registered in the default registry', async () => {
     const registry = await createDefaultRegistry();
-    expect([...SUPPORTED_FORMAT_KEYS].sort()).toEqual(registry.getFormatKeys().sort());
+    expect([...SUPPORTED_FORMAT_KEYS].sort()).toEqual(
+      registry.getFormatKeys().sort()
+    );
   });
 
   it('covers every parser extension in a single source of truth', () => {
     expect([...SUPPORTED_FORMAT_KEYS].sort()).toEqual(
-      ['android_xml', 'arb', 'ios_strings', 'json', 'laravel_php', 'po', 'properties', 'toml', 'xcstrings', 'xliff', 'yaml'].sort(),
+      [
+        'android_xml',
+        'arb',
+        'ios_strings',
+        'json',
+        'laravel_php',
+        'po',
+        'properties',
+        'toml',
+        'xcstrings',
+        'xliff',
+        'yaml',
+      ].sort()
     );
   });
 });
diff --git a/tests/unit/formats/ios-strings.test.ts b/tests/unit/formats/ios-strings.test.ts
index 548bec81..2f4d388f 100644
--- a/tests/unit/formats/ios-strings.test.ts
+++ b/tests/unit/formats/ios-strings.test.ts
@@ -38,10 +38,9 @@ describe('ios-strings parser', () => {
     });
 
     it('should preserve non-entry, non-comment lines', () => {
-      const content = [
-        '"greeting" = "Hello";',
-        '"deleted" = "Gone";',
-      ].join('\n');
+      const content = ['"greeting" = "Hello";', '"deleted" = "Gone";'].join(
+        '\n'
+      );
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
@@ -101,8 +100,8 @@ describe('ios-strings parser', () => {
       const content = '"greeting" = "Hello";\n"farewell" = "Goodbye";\n';
       const entries = parser.extract(content);
       expect(entries).toHaveLength(2);
-      expect(entries.find(e => e.key === 'greeting')!.value).toBe('Hello');
-      expect(entries.find(e => e.key === 'farewell')!.value).toBe('Goodbye');
+      expect(entries.find((e) => e.key === 'greeting')!.value).toBe('Hello');
+      expect(entries.find((e) => e.key === 'farewell')!.value).toBe('Goodbye');
     });
 
     it('should attach block comments as metadata', () => {
@@ -127,7 +126,9 @@ describe('ios-strings parser', () => {
       ].join('\n');
       const entries = parser.extract(content);
       expect(entries).toHaveLength(1);
-      expect(entries[0]!.metadata).toEqual({ comment: 'This is a\n   multi-line comment' });
+      expect(entries[0]!.metadata).toEqual({
+        comment: 'This is a\n   multi-line comment',
+      });
     });
 
     it('should handle block comment spanning three or more lines', () => {
@@ -183,7 +184,7 @@ describe('ios-strings parser', () => {
     it('should extract entries in source-file order (consumers sort downstream)', () => {
       const content = '"zebra" = "Z";\n"alpha" = "A";\n"middle" = "M";\n';
       const entries = parser.extract(content);
-      expect(entries.map(e => e.key)).toEqual(['zebra', 'alpha', 'middle']);
+      expect(entries.map((e) => e.key)).toEqual(['zebra', 'alpha', 'middle']);
     });
   });
 
@@ -209,10 +210,7 @@ describe('ios-strings parser', () => {
     });
 
     it('should preserve line comments for kept keys', () => {
-      const content = [
-        '// A line comment',
-        '"greeting" = "Hello";',
-      ].join('\n');
+      const content = ['// A line comment', '"greeting" = "Hello";'].join('\n');
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
@@ -458,10 +456,9 @@ describe('ios-strings parser', () => {
 
   describe('reconstruct flush trailing pending comments', () => {
     it('should flush trailing comments at end of file', () => {
-      const content = [
-        '"greeting" = "Hello";',
-        '// trailing comment',
-      ].join('\n');
+      const content = ['"greeting" = "Hello";', '// trailing comment'].join(
+        '\n'
+      );
 
       const entries: TranslatedEntry[] = [
         { key: 'greeting', value: 'Hello', translation: 'Hola' },
diff --git a/tests/unit/formats/json.test.ts b/tests/unit/formats/json.test.ts
index 3da07ef2..a302308b 100644
--- a/tests/unit/formats/json.test.ts
+++ b/tests/unit/formats/json.test.ts
@@ -6,16 +6,21 @@ const parser = new JsonFormatParser();
 describe('JsonFormatParser', () => {
   describe('extract()', () => {
     it('should extract flat key-value pairs', () => {
-      const result = parser.extract('{"greeting":"Hello","farewell":"Goodbye"}');
+      const result = parser.extract(
+        '{"greeting":"Hello","farewell":"Goodbye"}'
+      );
       expect(result).toHaveLength(2);
-      expect(result.find(e => e.key === 'farewell')!.value).toBe('Goodbye');
-      expect(result.find(e => e.key === 'greeting')!.value).toBe('Hello');
+      expect(result.find((e) => e.key === 'farewell')!.value).toBe('Goodbye');
+      expect(result.find((e) => e.key === 'greeting')!.value).toBe('Hello');
     });
 
     it('should extract nested objects with dot-path keys', () => {
       const result = parser.extract('{"nav":{"home":"Home","about":"About"}}');
       expect(result).toHaveLength(2);
-      expect(result.map(e => e.key).sort()).toEqual(['nav.about', 'nav.home']);
+      expect(result.map((e) => e.key).sort()).toEqual([
+        'nav.about',
+        'nav.home',
+      ]);
     });
 
     it('should skip non-string values', () => {
@@ -28,14 +33,18 @@ describe('JsonFormatParser', () => {
   describe('reconstruct()', () => {
     it('should replace values with translations', () => {
       const original = '{\n  "greeting": "Hello"\n}\n';
-      const entries: TranslatedEntry[] = [{ key: 'greeting', value: 'Hello', translation: 'Hallo' }];
+      const entries: TranslatedEntry[] = [
+        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+      ];
       const result = parser.reconstruct(original, entries);
       expect(JSON.parse(result)).toEqual({ greeting: 'Hallo' });
     });
 
     it('should preserve indentation', () => {
       const original = '{\n  "key": "value"\n}\n';
-      const entries: TranslatedEntry[] = [{ key: 'key', value: 'value', translation: 'valor' }];
+      const entries: TranslatedEntry[] = [
+        { key: 'key', value: 'value', translation: 'valor' },
+      ];
       const result = parser.reconstruct(original, entries);
       expect(result).toBe('{\n  "key": "valor"\n}\n');
     });
@@ -60,7 +69,9 @@ describe('JsonFormatParser', () => {
       ];
       const result = parser.reconstruct(original, entries);
       const parsed = JSON.parse(result) as Record<string, unknown>;
-      expect((parsed['nav'] as Record<string, string>)['about']).toBe('Uber uns');
+      expect((parsed['nav'] as Record<string, string>)['about']).toBe(
+        'Uber uns'
+      );
     });
 
     it('should REMOVE deleted keys not in entries', () => {
@@ -117,15 +128,20 @@ describe('JsonFormatParser', () => {
     });
 
     it('should remove nested keys and clean up empty parent objects', () => {
-      const original = JSON.stringify({
-        nav: {
-          home: 'Home',
-          about: 'About',
-        },
-        footer: {
-          copyright: 'Copyright',
-        },
-      }, null, 2) + '\n';
+      const original =
+        JSON.stringify(
+          {
+            nav: {
+              home: 'Home',
+              about: 'About',
+            },
+            footer: {
+              copyright: 'Copyright',
+            },
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'nav.home', value: 'Home', translation: 'Startseite' },
@@ -140,13 +156,18 @@ describe('JsonFormatParser', () => {
     });
 
     it('should remove only the deleted key and keep siblings', () => {
-      const original = JSON.stringify({
-        nav: {
-          home: 'Home',
-          about: 'About',
-          contact: 'Contact',
-        },
-      }, null, 2) + '\n';
+      const original =
+        JSON.stringify(
+          {
+            nav: {
+              home: 'Home',
+              about: 'About',
+              contact: 'Contact',
+            },
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'nav.home', value: 'Home', translation: 'Inicio' },
@@ -172,7 +193,10 @@ describe('JsonFormatParser', () => {
     it('should preserve content with identity translations', () => {
       const original = '{\n  "a": "Hello",\n  "b": "World"\n}\n';
       const entries = parser.extract(original);
-      const translated: TranslatedEntry[] = entries.map(e => ({ ...e, translation: e.value }));
+      const translated: TranslatedEntry[] = entries.map((e) => ({
+        ...e,
+        translation: e.value,
+      }));
       const result = parser.reconstruct(original, translated);
       expect(result).toBe(original);
     });
@@ -213,10 +237,10 @@ describe('JsonFormatParser', () => {
       const result = parser.extract(json);
 
       expect(warnSpy).toHaveBeenCalledWith(
-        expect.stringContaining('duplicate keys: greeting'),
+        expect.stringContaining('duplicate keys: greeting')
       );
       expect(result).toHaveLength(2);
-      expect(result.find(e => e.key === 'greeting')!.value).toBe('Hi');
+      expect(result.find((e) => e.key === 'greeting')!.value).toBe('Hi');
     });
 
     it('should warn on duplicate keys in nested objects', () => {
@@ -224,7 +248,7 @@ describe('JsonFormatParser', () => {
       parser.extract(json);
 
       expect(warnSpy).toHaveBeenCalledWith(
-        expect.stringContaining('duplicate keys: home'),
+        expect.stringContaining('duplicate keys: home')
       );
     });
 
@@ -254,7 +278,7 @@ describe('JsonFormatParser', () => {
       parser.extract(json);
 
       expect(warnSpy).toHaveBeenCalledWith(
-        expect.stringContaining('duplicate keys'),
+        expect.stringContaining('duplicate keys')
       );
     });
 
@@ -343,7 +367,12 @@ describe('JsonFormatParser', () => {
     });
 
     it('should apply translations to nested objects inside arrays', () => {
-      const original = JSON.stringify({ list: [{ name: 'Alice' }, { name: 'Bob' }] }, null, 2) + '\n';
+      const original =
+        JSON.stringify(
+          { list: [{ name: 'Alice' }, { name: 'Bob' }] },
+          null,
+          2
+        ) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'list.0.name', value: 'Alice', translation: 'Alicia' },
         { key: 'list.1.name', value: 'Bob', translation: 'Roberto' },
@@ -355,7 +384,8 @@ describe('JsonFormatParser', () => {
     });
 
     it('should not apply translation to array string item when not in translations', () => {
-      const original = JSON.stringify({ items: ['keep', 'also_keep'] }, null, 2) + '\n';
+      const original =
+        JSON.stringify({ items: ['keep', 'also_keep'] }, null, 2) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'items.0', value: 'keep', translation: 'kept' },
       ];
@@ -368,14 +398,19 @@ describe('JsonFormatParser', () => {
 
   describe('reconstruct() removeDeletedKeys nested cleanup', () => {
     it('should remove deeply nested empty parent objects after key removal', () => {
-      const original = JSON.stringify({
-        a: {
-          b: {
-            c: 'deep value',
+      const original =
+        JSON.stringify(
+          {
+            a: {
+              b: {
+                c: 'deep value',
+              },
+            },
+            keep: 'yes',
           },
-        },
-        keep: 'yes',
-      }, null, 2) + '\n';
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'keep', value: 'yes', translation: 'ja' },
@@ -388,10 +423,15 @@ describe('JsonFormatParser', () => {
     });
 
     it('should not remove array values via removeDeletedKeys', () => {
-      const original = JSON.stringify({
-        items: ['one', 'two'],
-        label: 'test',
-      }, null, 2) + '\n';
+      const original =
+        JSON.stringify(
+          {
+            items: ['one', 'two'],
+            label: 'test',
+          },
+          null,
+          2
+        ) + '\n';
 
       const entries: TranslatedEntry[] = [
         { key: 'items.0', value: 'one', translation: 'uno' },
@@ -417,9 +457,14 @@ describe('JsonFormatParser', () => {
     });
 
     it('should handle setKey where intermediate path already exists as object', () => {
-      const original = JSON.stringify({
-        nav: { home: 'Home' },
-      }, null, 2) + '\n';
+      const original =
+        JSON.stringify(
+          {
+            nav: { home: 'Home' },
+          },
+          null,
+          2
+        ) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'nav.home', value: 'Home', translation: 'Inicio' },
         { key: 'nav.about', value: 'About', translation: 'Acerca' },
@@ -445,7 +490,8 @@ describe('JsonFormatParser', () => {
     });
 
     it('should handle setKey when intermediate path is null', () => {
-      const original = JSON.stringify({ parent: null, other: 'val' }, null, 2) + '\n';
+      const original =
+        JSON.stringify({ parent: null, other: 'val' }, null, 2) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'other', value: 'val', translation: 'valor' },
         { key: 'parent.child', value: 'x', translation: 'y' },
@@ -489,7 +535,8 @@ describe('JsonFormatParser', () => {
     });
 
     it('should apply translations to top-level array with nested objects', () => {
-      const original = JSON.stringify([{ name: 'Alice' }, { name: 'Bob' }], null, 2) + '\n';
+      const original =
+        JSON.stringify([{ name: 'Alice' }, { name: 'Bob' }], null, 2) + '\n';
       const entries: TranslatedEntry[] = [
         { key: '0.name', value: 'Alice', translation: 'Alicia' },
         { key: '1.name', value: 'Bob', translation: 'Roberto' },
@@ -525,19 +572,24 @@ describe('JsonFormatParser', () => {
     });
 
     it('should reconstruct flat dotted keys without nesting', () => {
-      const original = '{\n  "section.key": "Value",\n  "section.other": "Other"\n}\n';
+      const original =
+        '{\n  "section.key": "Value",\n  "section.other": "Other"\n}\n';
       const entries: TranslatedEntry[] = [
         { key: 'section.key', value: 'Value', translation: 'Wert' },
         { key: 'section.other', value: 'Other', translation: 'Andere' },
       ];
       const result = parser.reconstruct(original, entries);
       const parsed = JSON.parse(result);
-      expect(parsed).toEqual({ 'section.key': 'Wert', 'section.other': 'Andere' });
+      expect(parsed).toEqual({
+        'section.key': 'Wert',
+        'section.other': 'Andere',
+      });
       expect(parsed).not.toHaveProperty('section');
     });
 
     it('should preserve nested keys as nested', () => {
-      const original = JSON.stringify({ section: { key: 'Value' } }, null, 2) + '\n';
+      const original =
+        JSON.stringify({ section: { key: 'Value' } }, null, 2) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'section.key', value: 'Value', translation: 'Wert' },
       ];
@@ -548,13 +600,22 @@ describe('JsonFormatParser', () => {
     });
 
     it('should handle mixed flat and nested keys', () => {
-      const original = JSON.stringify({
-        'flat.key': 'Flat Value',
-        nested: { key: 'Nested Value' },
-      }, null, 2) + '\n';
+      const original =
+        JSON.stringify(
+          {
+            'flat.key': 'Flat Value',
+            nested: { key: 'Nested Value' },
+          },
+          null,
+          2
+        ) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'flat.key', value: 'Flat Value', translation: 'Flacher Wert' },
-        { key: 'nested.key', value: 'Nested Value', translation: 'Verschachtelter Wert' },
+        {
+          key: 'nested.key',
+          value: 'Nested Value',
+          translation: 'Verschachtelter Wert',
+        },
       ];
       const result = parser.reconstruct(original, entries);
       const parsed = JSON.parse(result);
@@ -564,9 +625,13 @@ describe('JsonFormatParser', () => {
     });
 
     it('should round-trip flat dotted keys with identity translations', () => {
-      const original = '{\n  "app.title": "My App",\n  "app.version": "1.0"\n}\n';
+      const original =
+        '{\n  "app.title": "My App",\n  "app.version": "1.0"\n}\n';
       const entries = parser.extract(original);
-      const translated: TranslatedEntry[] = entries.map(e => ({ ...e, translation: e.value }));
+      const translated: TranslatedEntry[] = entries.map((e) => ({
+        ...e,
+        translation: e.value,
+      }));
       const result = parser.reconstruct(original, translated);
       expect(result).toBe(original);
     });
@@ -585,7 +650,8 @@ describe('JsonFormatParser', () => {
     });
 
     it('should remove deleted flat dotted keys', () => {
-      const original = '{\n  "section.keep": "Keep",\n  "section.remove": "Remove"\n}\n';
+      const original =
+        '{\n  "section.keep": "Keep",\n  "section.remove": "Remove"\n}\n';
       const entries: TranslatedEntry[] = [
         { key: 'section.keep', value: 'Keep', translation: 'Behalten' },
       ];
@@ -596,9 +662,14 @@ describe('JsonFormatParser', () => {
     });
 
     it('should handle flat dotted keys inside nested objects', () => {
-      const original = JSON.stringify({
-        outer: { 'inner.key': 'Value' },
-      }, null, 2) + '\n';
+      const original =
+        JSON.stringify(
+          {
+            outer: { 'inner.key': 'Value' },
+          },
+          null,
+          2
+        ) + '\n';
       const entries: TranslatedEntry[] = [
         { key: 'outer.inner.key', value: 'Value', translation: 'Wert' },
       ];
diff --git a/tests/unit/formats/php-arrays.test.ts b/tests/unit/formats/php-arrays.test.ts
index b799f855..c4788311 100644
--- a/tests/unit/formats/php-arrays.test.ts
+++ b/tests/unit/formats/php-arrays.test.ts
@@ -14,7 +14,9 @@ const parser = new PhpArraysFormatParser();
 describe('PhpArraysFormatParser', () => {
   it('is registered in the default registry under laravel_php', async () => {
     const registry = await createDefaultRegistry();
-    expect(registry.getParserByFormatKey('laravel_php')?.name).toBe('Laravel PHP arrays');
+    expect(registry.getParserByFormatKey('laravel_php')?.name).toBe(
+      'Laravel PHP arrays'
+    );
     expect(registry.getSupportedExtensions()).toContain('.php');
   });
 
@@ -58,7 +60,9 @@ return [
 `;
       const entries = parser.extract(content);
       const map = Object.fromEntries(entries.map((e) => [e.key, e.value]));
-      expect(map['auth.failed']).toBe('These credentials do not match our records.');
+      expect(map['auth.failed']).toBe(
+        'These credentials do not match our records.'
+      );
       expect(map['auth.password']).toBe('The password is incorrect.');
       expect(map['welcome']).toBe('Welcome');
       expect(entries).toHaveLength(3);
@@ -84,7 +88,7 @@ return [
       expect(entries[0]?.value).toBe('Welcome :name, you have :count messages');
     });
 
-    it('decodes single-quoted escape sequences (\\\\\' and \\\\\\\\)', () => {
+    it("decodes single-quoted escape sequences (\\\\' and \\\\\\\\)", () => {
       const content = `<?php return ['msg' => 'It\\'s a back\\\\slash'];`;
       const entries = parser.extract(content);
       expect(entries[0]?.value).toBe("It's a back\\slash");
@@ -208,19 +212,29 @@ EOT
     });
 
     it('emits a Logger.warn naming the dot-path key when tagging', () => {
-      const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+      const warnSpy = jest
+        .spyOn(Logger, 'warn')
+        .mockImplementation(() => undefined);
       try {
-        parser.extract(`<?php return ['nav' => ['items' => '{0}none|{1}one|[2,*]many']];`);
+        parser.extract(
+          `<?php return ['nav' => ['items' => '{0}none|{1}one|[2,*]many']];`
+        );
         expect(warnSpy).toHaveBeenCalledTimes(1);
-        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('nav.items'));
-        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('pipe-pluralization'));
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('nav.items')
+        );
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('pipe-pluralization')
+        );
       } finally {
         warnSpy.mockRestore();
       }
     });
 
     it('does not warn for plain translatable strings', () => {
-      const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+      const warnSpy = jest
+        .spyOn(Logger, 'warn')
+        .mockImplementation(() => undefined);
       try {
         parser.extract(`<?php return ['hello' => 'Hello, world'];`);
         expect(warnSpy).not.toHaveBeenCalled();
@@ -258,7 +272,9 @@ EOT
       let deeper = `'x'`;
       for (let i = 0; i < 32; i++) deeper = `['k${i}' => ${deeper}]`;
       const tooDeep = `<?php return ['root' => ${deeper}];`;
-      expect(() => defaultParser.extract(tooDeep)).toThrow(PhpArraysCapExceededError);
+      expect(() => defaultParser.extract(tooDeep)).toThrow(
+        PhpArraysCapExceededError
+      );
     });
 
     it('cap-exceeded error names the dot-path where the limit was hit', () => {
@@ -356,7 +372,9 @@ return [
       const out = parser.reconstruct(content, [
         { key: 'b', value: 'two', translation: 'zwei' },
       ]);
-      expect(out).toBe(`<?php return ['a' => 'one', 'b' => 'zwei', 'c' => 'three'];`);
+      expect(out).toBe(
+        `<?php return ['a' => 'one', 'b' => 'zwei', 'c' => 'three'];`
+      );
     });
 
     it('silently skips keys that are not present in the source (no insertion)', () => {
@@ -404,7 +422,9 @@ return [
         { key: 'a', value: 'one', translation: 'uno' },
         { key: 'b.c', value: 'two', translation: 'dos' },
       ]);
-      expect(out).toBe(`<?php return array('a' => 'uno', 'b' => array('c' => 'dos'));`);
+      expect(out).toBe(
+        `<?php return array('a' => 'uno', 'b' => array('c' => 'dos'));`
+      );
     });
 
     it('handles multiple replacements on the same line via descending-offset rewrite', () => {
@@ -425,7 +445,9 @@ return [
     ],
 ];
 `;
-      const entries = parser.extract(content).map((e) => ({ ...e, translation: e.value }));
+      const entries = parser
+        .extract(content)
+        .map((e) => ({ ...e, translation: e.value }));
       expect(parser.reconstruct(content, entries)).toBe(content);
     });
 
@@ -442,14 +464,16 @@ return [
       const out = parser.reconstruct(content, [
         { key: 'bye', value: 'さようなら', translation: 'Auf Wiedersehen' },
       ]);
-      expect(out).toBe(`<?php return ['hi' => '日本語', 'bye' => 'Auf Wiedersehen'];`);
+      expect(out).toBe(
+        `<?php return ['hi' => '日本語', 'bye' => 'Auf Wiedersehen'];`
+      );
     });
 
     it('throws ValidationError when the file has no return array', () => {
       expect(() =>
         parser.reconstruct(`<?php echo 'hi';`, [
           { key: 'x', value: 'x', translation: 'y' },
-        ]),
+        ])
       ).toThrow(ValidationError);
     });
   });
@@ -457,7 +481,7 @@ return [
   describe('15-fixture corpus', () => {
     const FIXTURES_DIR = path.resolve(
       __dirname,
-      '../../fixtures/sync/formats/laravel-php',
+      '../../fixtures/sync/formats/laravel-php'
     );
     const load = (name: string): string =>
       fs.readFileSync(path.join(FIXTURES_DIR, name), 'utf-8');
@@ -534,8 +558,16 @@ return [
         // downstream diff/translate logic is responsible for choosing a
         // resolution strategy (currently last-write-wins via Map semantics).
         expect(map['user.name']).toBeDefined();
-        expect(entries.some((e) => e.key === 'user.name' && e.value === 'Literal dot key')).toBe(true);
-        expect(entries.some((e) => e.key === 'user.name' && e.value === 'Nested under user.name')).toBe(true);
+        expect(
+          entries.some(
+            (e) => e.key === 'user.name' && e.value === 'Literal dot key'
+          )
+        ).toBe(true);
+        expect(
+          entries.some(
+            (e) => e.key === 'user.name' && e.value === 'Nested under user.name'
+          )
+        ).toBe(true);
       });
 
       it('12: `"\\$100"` and `"\\${currency}"` decode to literal `$`', () => {
@@ -558,7 +590,9 @@ return [
       });
 
       it('15: PHPDoc, block comments, and irregular whitespace produce normal extract', () => {
-        const entries = parser.extract(load('15-irregular-whitespace-and-comments.php'));
+        const entries = parser.extract(
+          load('15-irregular-whitespace-and-comments.php')
+        );
         const map = Object.fromEntries(entries.map((e) => [e.key, e.value]));
         expect(map['hello']).toBe('Hello');
         expect(map['bye']).toBe('Goodbye');
@@ -582,7 +616,7 @@ return [
       // because TranslatedEntry[] is keyed on the dot-path, so one location's
       // translation overwrites the other's. Covered separately below.
       const BYTE_EQUAL_FIXTURES = ACCEPT_FIXTURES.filter(
-        (n) => n !== '11-dot-key-vs-nested.php',
+        (n) => n !== '11-dot-key-vs-nested.php'
       );
       for (const name of BYTE_EQUAL_FIXTURES) {
         it(`reconstructs ${name} byte-identically`, () => {
@@ -620,25 +654,27 @@ return [
         // Irregular inner whitespace preserved around the rewritten key
         expect(out).toContain(`'hello'   =>   'Hallo',    // trailing`);
         // Everything besides the rewritten value stays identical
-        expect(out.length).toBe(content.length + ('Hallo'.length - 'Hello'.length));
+        expect(out.length).toBe(
+          content.length + ('Hallo'.length - 'Hello'.length)
+        );
       });
     });
   });
 
   describe('supply-chain + runtime safety', () => {
     const phpParserDir = path.dirname(
-      require.resolve('php-parser/package.json'),
+      require.resolve('php-parser/package.json')
     );
     const distBundle = fs.readFileSync(
       path.join(phpParserDir, 'dist', 'php-parser.js'),
-      'utf-8',
+      'utf-8'
     );
     const distMinBundle = fs.readFileSync(
       path.join(phpParserDir, 'dist', 'php-parser.min.js'),
-      'utf-8',
+      'utf-8'
     );
     const packageJson = JSON.parse(
-      fs.readFileSync(path.join(phpParserDir, 'package.json'), 'utf-8'),
+      fs.readFileSync(path.join(phpParserDir, 'package.json'), 'utf-8')
     ) as {
       dependencies?: Record<string, string>;
       scripts?: Record<string, string>;
@@ -673,10 +709,7 @@ return [
         `from "${CHILD_PROCESS_TOKEN}"`,
         new RegExp(`from\\s+["']${CHILD_PROCESS_TOKEN}["']`),
       ],
-      [
-        `from "${VM_TOKEN}"`,
-        new RegExp(`from\\s+["']${VM_TOKEN}["']`),
-      ],
+      [`from "${VM_TOKEN}"`, new RegExp(`from\\s+["']${VM_TOKEN}["']`)],
       [EVAL_TOKEN, new RegExp(`\\b${EVAL_TOKEN}\\s*\\(`)],
       [
         `new ${NEW_FUNCTION_TOKEN}(`,
@@ -716,7 +749,7 @@ return [
     it(`exercising extract and reconstruct does not load ${CHILD_PROCESS_TOKEN} or ${VM_TOKEN} into require.cache`, () => {
       const fresh = new PhpArraysFormatParser();
       fresh.extract(
-        `<?php return ['a' => 'Hello', 'nested' => ['b' => 'World']];`,
+        `<?php return ['a' => 'Hello', 'nested' => ['b' => 'World']];`
       );
       fresh.reconstruct(`<?php return ['a' => 'Hello'];`, [
         { key: 'a', value: 'Hello', translation: 'Hola' },
@@ -724,9 +757,11 @@ return [
 
       const cacheKeys = Object.keys(require.cache);
       const cpPattern = new RegExp(
-        `(?:^|[\\/\\\\])${CHILD_PROCESS_TOKEN}(?:[\\/\\\\.]|$)`,
+        `(?:^|[\\/\\\\])${CHILD_PROCESS_TOKEN}(?:[\\/\\\\.]|$)`
+      );
+      const vmPattern = new RegExp(
+        `(?:^|[\\/\\\\])${VM_TOKEN}(?:[\\/\\\\.]|$)`
       );
-      const vmPattern = new RegExp(`(?:^|[\\/\\\\])${VM_TOKEN}(?:[\\/\\\\.]|$)`);
       expect(cacheKeys.find((k) => cpPattern.test(k))).toBeUndefined();
       expect(cacheKeys.find((k) => vmPattern.test(k))).toBeUndefined();
     });
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index 95eab310..9dbf9935 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -14,10 +14,7 @@ describe('PoFormatParser extract (unquote)', () => {
   const parser = new PoFormatParser();
 
   it('should decode literal backslash-n (\\\\n in PO) as backslash + n, not newline', () => {
-    const po = [
-      'msgid "path\\\\nname"',
-      'msgstr ""',
-    ].join('\n');
+    const po = ['msgid "path\\\\nname"', 'msgstr ""'].join('\n');
 
     const entries = parser.extract(po);
     expect(entries).toHaveLength(1);
@@ -30,10 +27,7 @@ describe('PoFormatParser extract (msgid with #)', () => {
   const parser = new PoFormatParser();
 
   it('should not confuse # in msgid with msgctxt separator', () => {
-    const po = [
-      'msgid "error#404"',
-      'msgstr "Not Found"',
-    ].join('\n');
+    const po = ['msgid "error#404"', 'msgstr "Not Found"'].join('\n');
 
     const entries = parser.extract(po);
     expect(entries).toHaveLength(1);
@@ -78,10 +72,7 @@ describe('PoFormatParser reconstruct', () => {
   });
 
   it('should append new entries not present in template', () => {
-    const template = [
-      'msgid "greeting"',
-      'msgstr "Hallo"',
-    ].join('\n');
+    const template = ['msgid "greeting"', 'msgstr "Hallo"'].join('\n');
 
     const entries: TranslatedEntry[] = [
       { key: 'greeting', value: 'Hello', translation: 'Hallo' },
@@ -94,8 +85,8 @@ describe('PoFormatParser reconstruct', () => {
     expect(result).toContain('msgid "new_key"');
     expect(result).toContain('msgstr "Neuer Text"');
     const lines = result.split('\n');
-    const newKeyIdx = lines.findIndex(l => l.includes('"new_key"'));
-    const greetingIdx = lines.findIndex(l => l.includes('"greeting"'));
+    const newKeyIdx = lines.findIndex((l) => l.includes('"new_key"'));
+    const greetingIdx = lines.findIndex((l) => l.includes('"greeting"'));
     expect(newKeyIdx).toBeGreaterThan(greetingIdx);
   });
 
@@ -139,7 +130,9 @@ describe('PoFormatParser reconstruct', () => {
 
     const result = parser.reconstruct(template, entries);
 
-    expect(result).toContain('msgstr "Content-Type: text/plain; charset=UTF-8\\n"');
+    expect(result).toContain(
+      'msgstr "Content-Type: text/plain; charset=UTF-8\\n"'
+    );
     expect(result).toContain('msgstr "Updated Hallo"');
   });
 
@@ -167,11 +160,7 @@ describe('PoFormatParser reconstruct', () => {
   });
 
   it('should remove fuzzy flag when providing a fresh translation', () => {
-    const template = [
-      '#, fuzzy',
-      'msgid "greeting"',
-      'msgstr ""',
-    ].join('\n');
+    const template = ['#, fuzzy', 'msgid "greeting"', 'msgstr ""'].join('\n');
 
     const entries: TranslatedEntry[] = [
       { key: 'greeting', value: 'Hello', translation: 'Hallo' },
@@ -202,12 +191,10 @@ describe('PoFormatParser reconstruct', () => {
   });
 
   it('should use continuation line format for long msgstr with newlines', () => {
-    const template = [
-      'msgid "long_message"',
-      'msgstr ""',
-    ].join('\n');
+    const template = ['msgid "long_message"', 'msgstr ""'].join('\n');
 
-    const longTranslation = 'First line of the translated message\nSecond line of the translated message\nThird line';
+    const longTranslation =
+      'First line of the translated message\nSecond line of the translated message\nThird line';
 
     const entries: TranslatedEntry[] = [
       { key: 'long_message', value: 'source', translation: longTranslation },
@@ -223,10 +210,7 @@ describe('PoFormatParser reconstruct', () => {
   });
 
   it('should use single-line format for short msgstr without newlines', () => {
-    const template = [
-      'msgid "greeting"',
-      'msgstr ""',
-    ].join('\n');
+    const template = ['msgid "greeting"', 'msgstr ""'].join('\n');
 
     const entries: TranslatedEntry[] = [
       { key: 'greeting', value: 'Hello', translation: 'Hallo' },
@@ -279,7 +263,8 @@ describe('PoFormatParser — parsing coverage', () => {
   });
 
   it('should skip obsolete entries (#~)', () => {
-    const po = '#~ msgid "old"\n#~ msgstr "ancient"\nmsgid "key"\nmsgstr "value"\n';
+    const po =
+      '#~ msgid "old"\n#~ msgstr "ancient"\nmsgid "key"\nmsgstr "value"\n';
     const entries = parser.extract(po);
     expect(entries).toHaveLength(1);
     expect(entries[0]!.key).toBe('key');
@@ -293,12 +278,13 @@ describe('PoFormatParser — parsing coverage', () => {
   });
 
   it('should parse msgid_plural and msgstr[N]', () => {
-    const po = [
-      'msgid "item"',
-      'msgid_plural "items"',
-      'msgstr[0] "Artikel"',
-      'msgstr[1] "Artikel"',
-    ].join('\n') + '\n';
+    const po =
+      [
+        'msgid "item"',
+        'msgid_plural "items"',
+        'msgstr[0] "Artikel"',
+        'msgstr[1] "Artikel"',
+      ].join('\n') + '\n';
     const entries = parser.extract(po);
     expect(entries).toHaveLength(1);
     expect(entries[0]!.metadata).toBeDefined();
@@ -306,60 +292,52 @@ describe('PoFormatParser — parsing coverage', () => {
   });
 
   it('should handle multi-line continuation strings', () => {
-    const po = [
-      'msgid ""',
-      '"Hello "',
-      '"World"',
-      'msgstr "Hallo Welt"',
-    ].join('\n') + '\n';
+    const po =
+      ['msgid ""', '"Hello "', '"World"', 'msgstr "Hallo Welt"'].join('\n') +
+      '\n';
     const entries = parser.extract(po);
     expect(entries).toHaveLength(1);
     expect(entries[0]!.value).toBe('Hello World');
   });
 
   it('should handle continuation for msgctxt', () => {
-    const po = [
-      'msgctxt ""',
-      '"menu"',
-      'msgid "file"',
-      'msgstr "Datei"',
-    ].join('\n') + '\n';
+    const po =
+      ['msgctxt ""', '"menu"', 'msgid "file"', 'msgstr "Datei"'].join('\n') +
+      '\n';
     const entries = parser.extract(po);
     expect(entries).toHaveLength(1);
   });
 
   it('should handle continuation for msgid_plural', () => {
-    const po = [
-      'msgid "item"',
-      'msgid_plural ""',
-      '"items"',
-      'msgstr[0] "Artikel"',
-      'msgstr[1] "Artikel"',
-    ].join('\n') + '\n';
+    const po =
+      [
+        'msgid "item"',
+        'msgid_plural ""',
+        '"items"',
+        'msgstr[0] "Artikel"',
+        'msgstr[1] "Artikel"',
+      ].join('\n') + '\n';
     const entries = parser.extract(po);
     expect(entries[0]!.metadata!['msgid_plural']).toBe('items');
   });
 
   it('should handle continuation for msgstr', () => {
-    const po = [
-      'msgid "greeting"',
-      'msgstr ""',
-      '"Hallo "',
-      '"Welt"',
-    ].join('\n') + '\n';
+    const po =
+      ['msgid "greeting"', 'msgstr ""', '"Hallo "', '"Welt"'].join('\n') + '\n';
     const entries = parser.extract(po);
     expect(entries[0]!.value).toBe('greeting');
   });
 
   it('should handle continuation for msgstr[N]', () => {
-    const po = [
-      'msgid "item"',
-      'msgid_plural "items"',
-      'msgstr[0] ""',
-      '"Artikel"',
-      'msgstr[1] ""',
-      '"Artikel"',
-    ].join('\n') + '\n';
+    const po =
+      [
+        'msgid "item"',
+        'msgid_plural "items"',
+        'msgstr[0] ""',
+        '"Artikel"',
+        'msgstr[1] ""',
+        '"Artikel"',
+      ].join('\n') + '\n';
     const entries = parser.extract(po);
     expect(entries).toHaveLength(1);
   });
@@ -369,13 +347,14 @@ describe('PoFormatParser — reconstruct coverage', () => {
   const parser = new PoFormatParser();
 
   it('should remove deleted entries from output', () => {
-    const po = [
-      'msgid "keep"',
-      'msgstr "Keep"',
-      '',
-      'msgid "delete"',
-      'msgstr "Delete"',
-    ].join('\n') + '\n';
+    const po =
+      [
+        'msgid "keep"',
+        'msgstr "Keep"',
+        '',
+        'msgid "delete"',
+        'msgstr "Delete"',
+      ].join('\n') + '\n';
     const entries: TranslatedEntry[] = [
       { key: 'keep', value: 'keep', translation: 'Behalten' },
     ];
@@ -385,11 +364,8 @@ describe('PoFormatParser — reconstruct coverage', () => {
   });
 
   it('should reconstruct entries with msgctxt', () => {
-    const po = [
-      'msgctxt "menu"',
-      'msgid "file"',
-      'msgstr "File"',
-    ].join('\n') + '\n';
+    const po =
+      ['msgctxt "menu"', 'msgid "file"', 'msgstr "File"'].join('\n') + '\n';
     const entries: TranslatedEntry[] = [
       { key: 'menu\x04file', value: 'file', translation: 'Datei' },
     ];
@@ -398,12 +374,13 @@ describe('PoFormatParser — reconstruct coverage', () => {
   });
 
   it('should reconstruct plural entries', () => {
-    const po = [
-      'msgid "item"',
-      'msgid_plural "items"',
-      'msgstr[0] "item"',
-      'msgstr[1] "items"',
-    ].join('\n') + '\n';
+    const po =
+      [
+        'msgid "item"',
+        'msgid_plural "items"',
+        'msgstr[0] "item"',
+        'msgstr[1] "items"',
+      ].join('\n') + '\n';
     const entries: TranslatedEntry[] = [
       {
         key: 'item',
@@ -421,11 +398,8 @@ describe('PoFormatParser — reconstruct coverage', () => {
   });
 
   it('should remove fuzzy flag when translation is provided', () => {
-    const po = [
-      '#, fuzzy',
-      'msgid "greeting"',
-      'msgstr "old"',
-    ].join('\n') + '\n';
+    const po =
+      ['#, fuzzy', 'msgid "greeting"', 'msgstr "old"'].join('\n') + '\n';
     const entries: TranslatedEntry[] = [
       { key: 'greeting', value: 'greeting', translation: 'Hallo' },
     ];
@@ -435,11 +409,10 @@ describe('PoFormatParser — reconstruct coverage', () => {
   });
 
   it('should preserve non-fuzzy flags', () => {
-    const po = [
-      '#, python-format',
-      'msgid "count: %d"',
-      'msgstr "Anzahl: %d"',
-    ].join('\n') + '\n';
+    const po =
+      ['#, python-format', 'msgid "count: %d"', 'msgstr "Anzahl: %d"'].join(
+        '\n'
+      ) + '\n';
     const entries: TranslatedEntry[] = [
       { key: 'count: %d', value: 'count: %d', translation: 'Anzahl: %d' },
     ];
diff --git a/tests/unit/formats/properties.test.ts b/tests/unit/formats/properties.test.ts
index db71a023..aea49fcb 100644
--- a/tests/unit/formats/properties.test.ts
+++ b/tests/unit/formats/properties.test.ts
@@ -15,15 +15,15 @@ describe('PropertiesFormatParser', () => {
       const content = 'greeting=Hello\nfarewell=Goodbye\n';
       const entries = parser.extract(content);
       expect(entries).toHaveLength(2);
-      expect(entries.find(e => e.key === 'farewell')!.value).toBe('Goodbye');
-      expect(entries.find(e => e.key === 'greeting')!.value).toBe('Hello');
+      expect(entries.find((e) => e.key === 'farewell')!.value).toBe('Goodbye');
+      expect(entries.find((e) => e.key === 'greeting')!.value).toBe('Hello');
     });
 
     it('should handle key: value separator', () => {
       const content = 'greeting: Hello\nfarewell: Goodbye\n';
       const entries = parser.extract(content);
       expect(entries).toHaveLength(2);
-      expect(entries.find(e => e.key === 'farewell')!.value).toBe('Goodbye');
+      expect(entries.find((e) => e.key === 'farewell')!.value).toBe('Goodbye');
     });
 
     it('should handle spaces around separator', () => {
@@ -34,7 +34,8 @@ describe('PropertiesFormatParser', () => {
     });
 
     it('should skip comment lines', () => {
-      const content = '# This is a comment\ngreeting=Hello\n! Another comment\nfarewell=Goodbye\n';
+      const content =
+        '# This is a comment\ngreeting=Hello\n! Another comment\nfarewell=Goodbye\n';
       const entries = parser.extract(content);
       expect(entries).toHaveLength(2);
     });
@@ -132,7 +133,7 @@ describe('PropertiesFormatParser', () => {
       const result = parser.reconstruct(content, entries);
       expect(result).toContain('greeting=Hallo Welt');
       const lines = result.split('\n');
-      const greetingLine = lines.find(l => l.startsWith('greeting='));
+      const greetingLine = lines.find((l) => l.startsWith('greeting='));
       expect(greetingLine).toBe('greeting=Hallo Welt');
     });
 
@@ -197,7 +198,11 @@ describe('PropertiesFormatParser', () => {
     it('should handle line continuations in reconstruct', () => {
       const content = 'long=This is \\\n    a continued \\\n    line\n';
       const entries: TranslatedEntry[] = [
-        { key: 'long', value: 'This is a continued line', translation: 'Translated' },
+        {
+          key: 'long',
+          value: 'This is a continued line',
+          translation: 'Translated',
+        },
       ];
       const result = parser.reconstruct(content, entries);
       expect(result).toContain('long=Translated');
diff --git a/tests/unit/formats/toml.test.ts b/tests/unit/formats/toml.test.ts
index 900dd1b3..8b35b938 100644
--- a/tests/unit/formats/toml.test.ts
+++ b/tests/unit/formats/toml.test.ts
@@ -15,15 +15,18 @@ describe('TomlFormatParser', () => {
       const content = 'greeting = "Hello"\nfarewell = "Goodbye"\n';
       const entries = parser.extract(content);
       expect(entries).toHaveLength(2);
-      expect(entries.find(e => e.key === 'greeting')!.value).toBe('Hello');
-      expect(entries.find(e => e.key === 'farewell')!.value).toBe('Goodbye');
+      expect(entries.find((e) => e.key === 'greeting')!.value).toBe('Hello');
+      expect(entries.find((e) => e.key === 'farewell')!.value).toBe('Goodbye');
     });
 
     it('should extract nested table keys with dot paths', () => {
       const content = '[nav]\nhome = "Home"\nabout = "About"\n';
       const entries = parser.extract(content);
       expect(entries).toHaveLength(2);
-      expect(entries.map(e => e.key).sort()).toEqual(['nav.about', 'nav.home']);
+      expect(entries.map((e) => e.key).sort()).toEqual([
+        'nav.about',
+        'nav.home',
+      ]);
     });
 
     it('should skip non-string values', () => {
@@ -39,17 +42,22 @@ describe('TomlFormatParser', () => {
     });
 
     it('should handle go-i18n style deeply nested tables', () => {
-      const content = [
-        '[messages]',
-        '[messages.greeting]',
-        'other = "Hello, {{.Name}}!"',
-        '[messages.farewell]',
-        'other = "Goodbye"',
-      ].join('\n') + '\n';
+      const content =
+        [
+          '[messages]',
+          '[messages.greeting]',
+          'other = "Hello, {{.Name}}!"',
+          '[messages.farewell]',
+          'other = "Goodbye"',
+        ].join('\n') + '\n';
       const entries = parser.extract(content);
       expect(entries).toHaveLength(2);
-      expect(entries.find(e => e.key === 'messages.greeting.other')!.value).toBe('Hello, {{.Name}}!');
-      expect(entries.find(e => e.key === 'messages.farewell.other')!.value).toBe('Goodbye');
+      expect(
+        entries.find((e) => e.key === 'messages.greeting.other')!.value
+      ).toBe('Hello, {{.Name}}!');
+      expect(
+        entries.find((e) => e.key === 'messages.farewell.other')!.value
+      ).toBe('Goodbye');
     });
   });
 
@@ -132,23 +140,21 @@ describe('TomlFormatParser', () => {
         { key: 'home.title', value: 'Home', translation: 'Startseite' },
         { key: 'about.title', value: 'About', translation: 'Über uns' },
       ]);
-      expect(result).toBe([
-        '[home]',
-        'title = "Startseite"',
-        '',
-        '',
-        '[about]',
-        'title = "Über uns"',
-        '',
-      ].join('\n'));
+      expect(result).toBe(
+        [
+          '[home]',
+          'title = "Startseite"',
+          '',
+          '',
+          '[about]',
+          'title = "Über uns"',
+          '',
+        ].join('\n')
+      );
     });
 
     it('preserves double-quoted vs literal (single-quoted) values per-entry', () => {
-      const content = [
-        'dq = "double"',
-        "lit = 'literal'",
-        '',
-      ].join('\n');
+      const content = ['dq = "double"', "lit = 'literal'", ''].join('\n');
       const result = parser.reconstruct(content, [
         { key: 'dq', value: 'double', translation: 'doppel' },
         { key: 'lit', value: 'literal', translation: 'wörtlich' },
@@ -194,7 +200,7 @@ describe('TomlFormatParser', () => {
       expect(result).toBe('msg = "She said \\"hello\\""\n');
     });
 
-    it('falls back from literal to double-quoted when translation contains `\\\'`', () => {
+    it("falls back from literal to double-quoted when translation contains `\\'`", () => {
       const content = "msg = 'hi'\n";
       const result = parser.reconstruct(content, [
         { key: 'msg', value: 'hi', translation: "It's fine" },
@@ -247,7 +253,9 @@ describe('TomlFormatParser', () => {
       expect(result).toContain('existing = "a"');
       expect(result).toContain('brand_new = "neu"');
       // New key appears AFTER the existing entry, not before.
-      expect(result.indexOf('existing')).toBeLessThan(result.indexOf('brand_new'));
+      expect(result.indexOf('existing')).toBeLessThan(
+        result.indexOf('brand_new')
+      );
     });
 
     it('is byte-equal when reconstruct keeps values identical to extract', () => {
diff --git a/tests/unit/formats/xcstrings.test.ts b/tests/unit/formats/xcstrings.test.ts
index b4f24eb1..3354c1e3 100644
--- a/tests/unit/formats/xcstrings.test.ts
+++ b/tests/unit/formats/xcstrings.test.ts
@@ -3,24 +3,29 @@ import type { TranslatedEntry } from '../../../src/formats/format';
 
 const parser = new XcstringsFormatParser();
 
-const SAMPLE = JSON.stringify({
-  sourceLanguage: 'en',
-  version: '1.0',
-  strings: {
-    greeting: {
-      comment: 'Welcome screen title',
-      localizations: {
-        en: { stringUnit: { state: 'translated', value: 'Hello' } },
-        de: { stringUnit: { state: 'translated', value: 'Hallo' } },
-      },
-    },
-    farewell: {
-      localizations: {
-        en: { stringUnit: { state: 'translated', value: 'Goodbye' } },
+const SAMPLE =
+  JSON.stringify(
+    {
+      sourceLanguage: 'en',
+      version: '1.0',
+      strings: {
+        greeting: {
+          comment: 'Welcome screen title',
+          localizations: {
+            en: { stringUnit: { state: 'translated', value: 'Hello' } },
+            de: { stringUnit: { state: 'translated', value: 'Hallo' } },
+          },
+        },
+        farewell: {
+          localizations: {
+            en: { stringUnit: { state: 'translated', value: 'Goodbye' } },
+          },
+        },
       },
     },
-  },
-}, null, 2) + '\n';
+    null,
+    2
+  ) + '\n';
 
 describe('XcstringsFormatParser', () => {
   it('should have multiLocale set to true', () => {
@@ -31,8 +36,8 @@ describe('XcstringsFormatParser', () => {
     it('should extract entries for a specific locale', () => {
       const result = parser.extract(SAMPLE, 'en');
       expect(result).toHaveLength(2);
-      expect(result.find(e => e.key === 'farewell')!.value).toBe('Goodbye');
-      expect(result.find(e => e.key === 'greeting')!.value).toBe('Hello');
+      expect(result.find((e) => e.key === 'farewell')!.value).toBe('Goodbye');
+      expect(result.find((e) => e.key === 'greeting')!.value).toBe('Hello');
     });
 
     it('should return empty array when locale is not provided', () => {
@@ -54,14 +59,14 @@ describe('XcstringsFormatParser', () => {
 
     it('should preserve comment as context and metadata', () => {
       const result = parser.extract(SAMPLE, 'en');
-      const greeting = result.find(e => e.key === 'greeting');
+      const greeting = result.find((e) => e.key === 'greeting');
       expect(greeting!.context).toBe('Welcome screen title');
       expect(greeting!.metadata).toEqual({ comment: 'Welcome screen title' });
     });
 
     it('should not set context when no comment exists', () => {
       const result = parser.extract(SAMPLE, 'en');
-      const farewell = result.find(e => e.key === 'farewell');
+      const farewell = result.find((e) => e.key === 'farewell');
       expect(farewell!.context).toBeUndefined();
       expect(farewell!.metadata).toBeUndefined();
     });
@@ -71,17 +76,37 @@ describe('XcstringsFormatParser', () => {
         sourceLanguage: 'en',
         version: '1.0',
         strings: {
-          zebra: { localizations: { en: { stringUnit: { state: 'translated', value: 'Z' } } } },
-          apple: { localizations: { en: { stringUnit: { state: 'translated', value: 'A' } } } },
-          mango: { localizations: { en: { stringUnit: { state: 'translated', value: 'M' } } } },
+          zebra: {
+            localizations: {
+              en: { stringUnit: { state: 'translated', value: 'Z' } },
+            },
+          },
+          apple: {
+            localizations: {
+              en: { stringUnit: { state: 'translated', value: 'A' } },
+            },
+          },
+          mango: {
+            localizations: {
+              en: { stringUnit: { state: 'translated', value: 'M' } },
+            },
+          },
         },
       });
       const result = parser.extract(content, 'en');
-      expect(result.map(e => e.key).sort()).toEqual(['apple', 'mango', 'zebra']);
+      expect(result.map((e) => e.key).sort()).toEqual([
+        'apple',
+        'mango',
+        'zebra',
+      ]);
     });
 
     it('should handle empty strings object', () => {
-      const content = JSON.stringify({ sourceLanguage: 'en', version: '1.0', strings: {} });
+      const content = JSON.stringify({
+        sourceLanguage: 'en',
+        version: '1.0',
+        strings: {},
+      });
       const result = parser.extract(content, 'en');
       expect(result).toEqual([]);
     });
@@ -91,7 +116,11 @@ describe('XcstringsFormatParser', () => {
         sourceLanguage: 'en',
         version: '1.0',
         strings: {
-          has_unit: { localizations: { en: { stringUnit: { state: 'translated', value: 'Yes' } } } },
+          has_unit: {
+            localizations: {
+              en: { stringUnit: { state: 'translated', value: 'Yes' } },
+            },
+          },
           no_unit: { localizations: { en: {} } },
         },
       });
@@ -109,8 +138,12 @@ describe('XcstringsFormatParser', () => {
       ];
       const result = parser.reconstruct(SAMPLE, entries, 'fr');
       const data = JSON.parse(result);
-      expect(data.strings.greeting.localizations.fr.stringUnit.value).toBe('Bonjour');
-      expect(data.strings.farewell.localizations.fr.stringUnit.value).toBe('Au revoir');
+      expect(data.strings.greeting.localizations.fr.stringUnit.value).toBe(
+        'Bonjour'
+      );
+      expect(data.strings.farewell.localizations.fr.stringUnit.value).toBe(
+        'Au revoir'
+      );
     });
 
     it('should set state to translated', () => {
@@ -119,7 +152,9 @@ describe('XcstringsFormatParser', () => {
       ];
       const result = parser.reconstruct(SAMPLE, entries, 'es');
       const data = JSON.parse(result);
-      expect(data.strings.greeting.localizations.es.stringUnit.state).toBe('translated');
+      expect(data.strings.greeting.localizations.es.stringUnit.state).toBe(
+        'translated'
+      );
     });
 
     it('should preserve existing localizations for other locales', () => {
@@ -128,9 +163,15 @@ describe('XcstringsFormatParser', () => {
       ];
       const result = parser.reconstruct(SAMPLE, entries, 'fr');
       const data = JSON.parse(result);
-      expect(data.strings.greeting.localizations.en.stringUnit.value).toBe('Hello');
-      expect(data.strings.greeting.localizations.de.stringUnit.value).toBe('Hallo');
-      expect(data.strings.greeting.localizations.fr.stringUnit.value).toBe('Bonjour');
+      expect(data.strings.greeting.localizations.en.stringUnit.value).toBe(
+        'Hello'
+      );
+      expect(data.strings.greeting.localizations.de.stringUnit.value).toBe(
+        'Hallo'
+      );
+      expect(data.strings.greeting.localizations.fr.stringUnit.value).toBe(
+        'Bonjour'
+      );
     });
 
     it('should create localizations structure when absent', () => {
@@ -144,7 +185,9 @@ describe('XcstringsFormatParser', () => {
       ];
       const result = parser.reconstruct(content, entries, 'de');
       const data = JSON.parse(result);
-      expect(data.strings.new_key.localizations.de.stringUnit.value).toBe('Neu');
+      expect(data.strings.new_key.localizations.de.stringUnit.value).toBe(
+        'Neu'
+      );
     });
 
     it('should preserve comments on string definitions', () => {
@@ -167,14 +210,24 @@ describe('XcstringsFormatParser', () => {
     });
 
     it('should preserve indentation style', () => {
-      const tabIndented = JSON.stringify({ sourceLanguage: 'en', version: '1.0', strings: {} }, null, '\t') + '\n';
+      const tabIndented =
+        JSON.stringify(
+          { sourceLanguage: 'en', version: '1.0', strings: {} },
+          null,
+          '\t'
+        ) + '\n';
       const entries: TranslatedEntry[] = [];
       const result = parser.reconstruct(tabIndented, entries, 'de');
       expect(result).toContain('\t');
     });
 
     it('should preserve trailing newline', () => {
-      const withNewline = JSON.stringify({ sourceLanguage: 'en', version: '1.0', strings: {} }, null, 2) + '\n';
+      const withNewline =
+        JSON.stringify(
+          { sourceLanguage: 'en', version: '1.0', strings: {} },
+          null,
+          2
+        ) + '\n';
       const result = parser.reconstruct(withNewline, [], 'de');
       expect(result.endsWith('\n')).toBe(true);
     });
@@ -198,24 +251,40 @@ describe('XcstringsFormatParser', () => {
       const extracted = parser.extract(reconstructed, 'fr');
 
       expect(extracted).toHaveLength(2);
-      expect(extracted.find(e => e.key === 'greeting')!.value).toBe('Bonjour');
-      expect(extracted.find(e => e.key === 'farewell')!.value).toBe('Au revoir');
+      expect(extracted.find((e) => e.key === 'greeting')!.value).toBe(
+        'Bonjour'
+      );
+      expect(extracted.find((e) => e.key === 'farewell')!.value).toBe(
+        'Au revoir'
+      );
     });
 
     it('should chain reconstructs for multiple locales', () => {
       let content = SAMPLE;
-      content = parser.reconstruct(content, [
-        { key: 'greeting', value: 'Hello', translation: 'Hola' },
-      ], 'es');
-      content = parser.reconstruct(content, [
-        { key: 'greeting', value: 'Hello', translation: 'Bonjour' },
-      ], 'fr');
+      content = parser.reconstruct(
+        content,
+        [{ key: 'greeting', value: 'Hello', translation: 'Hola' }],
+        'es'
+      );
+      content = parser.reconstruct(
+        content,
+        [{ key: 'greeting', value: 'Hello', translation: 'Bonjour' }],
+        'fr'
+      );
 
       const data = JSON.parse(content);
-      expect(data.strings.greeting.localizations.en.stringUnit.value).toBe('Hello');
-      expect(data.strings.greeting.localizations.de.stringUnit.value).toBe('Hallo');
-      expect(data.strings.greeting.localizations.es.stringUnit.value).toBe('Hola');
-      expect(data.strings.greeting.localizations.fr.stringUnit.value).toBe('Bonjour');
+      expect(data.strings.greeting.localizations.en.stringUnit.value).toBe(
+        'Hello'
+      );
+      expect(data.strings.greeting.localizations.de.stringUnit.value).toBe(
+        'Hallo'
+      );
+      expect(data.strings.greeting.localizations.es.stringUnit.value).toBe(
+        'Hola'
+      );
+      expect(data.strings.greeting.localizations.fr.stringUnit.value).toBe(
+        'Bonjour'
+      );
     });
   });
 });
diff --git a/tests/unit/formats/xliff.test.ts b/tests/unit/formats/xliff.test.ts
index 1f334b71..a5ca7ad1 100644
--- a/tests/unit/formats/xliff.test.ts
+++ b/tests/unit/formats/xliff.test.ts
@@ -363,7 +363,9 @@ describe('xliff parser', () => {
 <xliff version="1.2"><file source-language="en"><body>
 <trans-unit id="a"><source><![CDATA[<b>bold</b>]]></source></trans-unit>
 </body></file></xliff>`;
-      expect(() => parser.extract(xliff)).toThrow(/<source> \/ <target> elements containing CDATA/);
+      expect(() => parser.extract(xliff)).toThrow(
+        /<source> \/ <target> elements containing CDATA/
+      );
     });
 
     it('rejects CDATA inside <target> with ValidationError', () => {
@@ -371,7 +373,9 @@ describe('xliff parser', () => {
 <xliff version="1.2"><file source-language="en" target-language="de"><body>
 <trans-unit id="a"><source>Hello</source><target><![CDATA[<b>Hallo</b>]]></target></trans-unit>
 </body></file></xliff>`;
-      expect(() => parser.extract(xliff)).toThrow(/<source> \/ <target> elements containing CDATA/);
+      expect(() => parser.extract(xliff)).toThrow(
+        /<source> \/ <target> elements containing CDATA/
+      );
     });
 
     it('accepts CDATA elsewhere (e.g. <note>)', () => {
@@ -429,7 +433,9 @@ describe('xliff parser', () => {
         version === '2.0'
           ? '      <unit id="k"><segment><source>v</source>\n'
           : '      <trans-unit id="k"><source>v</source>\n';
-      return head + opener.repeat(Math.ceil((bytes - head.length) / opener.length));
+      return (
+        head + opener.repeat(Math.ceil((bytes - head.length) / opener.length))
+      );
     }
 
     const v12 = unclosedOpeners(4 * 1024 * 1024, '1.2');
diff --git a/tests/unit/formats/xml-scan.test.ts b/tests/unit/formats/xml-scan.test.ts
index 086df499..f52eb25c 100644
--- a/tests/unit/formats/xml-scan.test.ts
+++ b/tests/unit/formats/xml-scan.test.ts
@@ -13,9 +13,14 @@ const TAG: ElementPattern = {
 describe('xml-scan', () => {
   describe('scanElements', () => {
     it('should return elements in document order with their parts split out', () => {
-      const elements = scanElements('a<tag id="x">one</tag>b<tag>two</tag>', TAG);
+      const elements = scanElements(
+        'a<tag id="x">one</tag>b<tag>two</tag>',
+        TAG
+      );
 
-      expect(elements.map((e) => [e.groups[0], e.inner, e.openTag, e.closeTag])).toEqual([
+      expect(
+        elements.map((e) => [e.groups[0], e.inner, e.openTag, e.closeTag])
+      ).toEqual([
         ['x', 'one', '<tag id="x">', '</tag>'],
         [undefined, 'two', '<tag>', '</tag>'],
       ]);
@@ -53,7 +58,9 @@ describe('xml-scan', () => {
 
   describe('findElement', () => {
     it('should return the first match', () => {
-      expect(findElement('x<tag>one</tag><tag>two</tag>', TAG)?.inner).toBe('one');
+      expect(findElement('x<tag>one</tag><tag>two</tag>', TAG)?.inner).toBe(
+        'one'
+      );
     });
 
     it('should return undefined when there is no match', () => {
@@ -63,21 +70,29 @@ describe('xml-scan', () => {
 
   describe('replaceElements', () => {
     it('should return the input unchanged when nothing matches', () => {
-      expect(replaceElements('<other>one</other>', TAG, () => 'x')).toBe('<other>one</other>');
+      expect(replaceElements('<other>one</other>', TAG, () => 'x')).toBe(
+        '<other>one</other>'
+      );
     });
 
     it('should rewrite matched elements in place', () => {
-      expect(replaceElements('a<tag>one</tag>b<tag>two</tag>', TAG, (e) => `[${e.inner}]`)).toBe(
-        'a[one]b[two]',
-      );
+      expect(
+        replaceElements(
+          'a<tag>one</tag>b<tag>two</tag>',
+          TAG,
+          (e) => `[${e.inner}]`
+        )
+      ).toBe('a[one]b[two]');
     });
 
     it('should drop an element with its indentation and trailing whitespace', () => {
       const content = 'x\n    <tag>one</tag>\n    <tag>two</tag>\n';
 
-      expect(replaceElements(content, TAG, (e) => (e.inner === 'one' ? null : e.text))).toBe(
-        'x\n<tag>two</tag>\n',
-      );
+      expect(
+        replaceElements(content, TAG, (e) =>
+          e.inner === 'one' ? null : e.text
+        )
+      ).toBe('x\n<tag>two</tag>\n');
     });
 
     it('should drop consecutive elements without reaching past the previous drop', () => {
diff --git a/tests/unit/formats/yaml.test.ts b/tests/unit/formats/yaml.test.ts
index deccfb52..efcd8bb7 100644
--- a/tests/unit/formats/yaml.test.ts
+++ b/tests/unit/formats/yaml.test.ts
@@ -99,7 +99,7 @@ describe('yaml parser', () => {
       const yaml = 'list:\n  - name: Alice\n    role: admin\n';
       const entries = parser.extract(yaml);
       expect(entries).toHaveLength(2);
-      const keys = entries.map(e => e.key);
+      const keys = entries.map((e) => e.key);
       expect(keys).toContain('list\x000\x00name');
       expect(keys).toContain('list\x000\x00role');
     });
@@ -110,8 +110,8 @@ describe('yaml parser', () => {
       const yaml = 'base: &anchor "hello"\nalias: *anchor\n';
       const entries = parser.extract(yaml);
       expect(entries).toHaveLength(2);
-      const baseEntry = entries.find(e => e.key === 'base');
-      const aliasEntry = entries.find(e => e.key === 'alias');
+      const baseEntry = entries.find((e) => e.key === 'base');
+      const aliasEntry = entries.find((e) => e.key === 'alias');
       expect(baseEntry).toBeDefined();
       expect(baseEntry!.value).toBe('hello');
       expect(aliasEntry).toBeDefined();
@@ -204,7 +204,7 @@ describe('yaml parser', () => {
     it('should walk into nested sequences within sequences', () => {
       const yaml = 'matrix:\n  - - a\n    - b\n  - - c\n';
       const entries = parser.extract(yaml);
-      const keys = entries.map(e => e.key);
+      const keys = entries.map((e) => e.key);
       expect(keys).toContain('matrix\x000\x000');
       expect(keys).toContain('matrix\x000\x001');
       expect(keys).toContain('matrix\x001\x000');
@@ -214,7 +214,7 @@ describe('yaml parser', () => {
       const yaml = 'items:\n  - title: First\n  - title: Second\n';
       const entries = parser.extract(yaml);
       expect(entries).toHaveLength(2);
-      const keys = entries.map(e => e.key);
+      const keys = entries.map((e) => e.key);
       expect(keys).toContain('items\x000\x00title');
       expect(keys).toContain('items\x001\x00title');
     });
@@ -222,16 +222,17 @@ describe('yaml parser', () => {
 
   describe('aliases resolving to collections', () => {
     it('should extract aliased map content only at its anchor site', () => {
-      const yaml = 'defaults: &defaults\n  color: red\n  size: large\ntheme: *defaults\n';
+      const yaml =
+        'defaults: &defaults\n  color: red\n  size: large\ntheme: *defaults\n';
       const entries = parser.extract(yaml);
-      const keys = entries.map(e => e.key);
+      const keys = entries.map((e) => e.key);
       expect(keys).toEqual(['defaults\0color', 'defaults\0size']);
     });
 
     it('should extract aliased map content in a sequence only at its anchor site', () => {
       const yaml = 'base: &base\n  x: hello\nitems:\n  - *base\n';
       const entries = parser.extract(yaml);
-      const keys = entries.map(e => e.key);
+      const keys = entries.map((e) => e.key);
       expect(keys).toEqual(['base\0x']);
     });
 
@@ -268,9 +269,12 @@ describe('yaml parser', () => {
         '',
       ].join('\n');
       const extracted = parser.extract(yaml);
-      expect(extracted.map(e => e.key)).toEqual(['defaults\0color', 'theme\0name']);
+      expect(extracted.map((e) => e.key)).toEqual([
+        'defaults\0color',
+        'theme\0name',
+      ]);
 
-      const entries: TranslatedEntry[] = extracted.map(e => ({
+      const entries: TranslatedEntry[] = extracted.map((e) => ({
         ...e,
         translation: e.value === 'red' ? 'rojo' : 'Oscuro',
       }));
@@ -347,7 +351,8 @@ describe('yaml parser', () => {
     });
 
     it('should walk alias resolving to scalar in map value and delete it', () => {
-      const yaml = 'base: &anchor hello\nkept: world\nalias1: *anchor\nalias2: *anchor\n';
+      const yaml =
+        'base: &anchor hello\nkept: world\nalias1: *anchor\nalias2: *anchor\n';
       const entries: TranslatedEntry[] = [
         { key: 'kept', value: 'world', translation: 'mundo' },
       ];
@@ -371,11 +376,11 @@ describe('yaml parser', () => {
     it('should handle alias in sequence resolving to scalar in extract', () => {
       const yaml = 'base: &val hello\nitems:\n  - *val\n  - extra\n';
       const entries = parser.extract(yaml);
-      const keys = entries.map(e => e.key);
+      const keys = entries.map((e) => e.key);
       expect(keys).toContain('base');
       expect(keys).toContain('items\x000');
       expect(keys).toContain('items\x001');
-      expect(entries.find(e => e.key === 'items\x000')!.value).toBe('hello');
+      expect(entries.find((e) => e.key === 'items\x000')!.value).toBe('hello');
     });
 
     it('should walk alias resolving to scalar in seq during walkDoc and delete it', () => {
@@ -395,7 +400,9 @@ describe('yaml parser', () => {
     const aliasBomb = (): string => {
       const lines = ['level0: &level0 [a, b, c, d]'];
       for (let i = 1; i <= 12; i++) {
-        const refs = Array.from({ length: 9 }, () => `*level${i - 1}`).join(', ');
+        const refs = Array.from({ length: 9 }, () => `*level${i - 1}`).join(
+          ', '
+        );
         lines.push(`level${i}: &level${i} [${refs}]`);
       }
       return `${lines.join('\n')}\n`;
@@ -411,7 +418,7 @@ describe('yaml parser', () => {
 
     it('should extract nested alias fan-out without expanding it', () => {
       const entries = parser.extract(aliasBomb());
-      expect(entries.map(e => e.key)).toEqual([
+      expect(entries.map((e) => e.key)).toEqual([
         'level0\x000',
         'level0\x001',
         'level0\x002',
@@ -423,7 +430,7 @@ describe('yaml parser', () => {
       const yaml = aliasBomb();
       const entries: TranslatedEntry[] = parser
         .extract(yaml)
-        .map(e => ({ ...e, translation: e.value.toUpperCase() }));
+        .map((e) => ({ ...e, translation: e.value.toUpperCase() }));
       const result = parser.reconstruct(yaml, entries);
       expect(result).toContain('&level0');
       expect(result).toContain('*level11');
@@ -442,7 +449,7 @@ describe('yaml parser', () => {
 
       const entries = parser.extract(yaml);
       expect(entries).toHaveLength(500);
-      expect(entries.every(e => e.key.startsWith('big\0'))).toBe(true);
+      expect(entries.every((e) => e.key.startsWith('big\0'))).toBe(true);
     });
 
     it('should extract nothing from a self-referential anchor', () => {
@@ -458,14 +465,16 @@ describe('yaml parser', () => {
     it('should still extract a document that reuses one anchor many times', () => {
       const entries = parser.extract(anchorReusedManyTimes());
       expect(entries).toHaveLength(201);
-      expect(entries.every(e => e.value === 'shared')).toBe(true);
+      expect(entries.every((e) => e.value === 'shared')).toBe(true);
     });
 
     it('should still round-trip a document that reuses one anchor many times', () => {
       const yaml = anchorReusedManyTimes();
-      const entries: TranslatedEntry[] = parser
-        .extract(yaml)
-        .map(e => ({ key: e.key, value: e.value, translation: 'compartido' }));
+      const entries: TranslatedEntry[] = parser.extract(yaml).map((e) => ({
+        key: e.key,
+        value: e.value,
+        translation: 'compartido',
+      }));
       const result = parser.reconstruct(yaml, entries);
       expect(result).toContain('compartido');
       expect(result).toContain('key199');
@@ -501,7 +510,9 @@ describe('yaml parser', () => {
 
       const result = parser.reconstruct(yaml, entries);
       const roundTripped = parser.extract(result);
-      expect(roundTripped).toEqual(entries.map(e => ({ key: e.key, value: e.translation })));
+      expect(roundTripped).toEqual(
+        entries.map((e) => ({ key: e.key, value: e.translation }))
+      );
     });
   });
 
diff --git a/tests/unit/formatters.test.ts b/tests/unit/formatters.test.ts
index 9ebda438..f2c12515 100644
--- a/tests/unit/formatters.test.ts
+++ b/tests/unit/formatters.test.ts
@@ -442,22 +442,14 @@ describe('formatters', () => {
     });
 
     it('should set changes to 0 when text is unchanged', () => {
-      const output = formatWriteJson(
-        'This is good.',
-        'This is good.',
-        'en-US'
-      );
+      const output = formatWriteJson('This is good.', 'This is good.', 'en-US');
       const parsed = JSON.parse(output);
 
       expect(parsed.changes).toBe(0);
     });
 
     it('should set changes to 1 when text is changed', () => {
-      const output = formatWriteJson(
-        'Original',
-        'Improved',
-        'en-US'
-      );
+      const output = formatWriteJson('Original', 'Improved', 'en-US');
       const parsed = JSON.parse(output);
 
       expect(parsed.changes).toBe(1);
diff --git a/tests/unit/generate-language-registry.test.ts b/tests/unit/generate-language-registry.test.ts
index b09fcdf1..9c4d0dca 100644
--- a/tests/unit/generate-language-registry.test.ts
+++ b/tests/unit/generate-language-registry.test.ts
@@ -12,12 +12,18 @@ import { spawnSync } from 'child_process';
 import * as path from 'path';
 import { pathToFileURL } from 'url';
 
-const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'generate-language-registry.mjs');
+const SCRIPT = path.join(
+  __dirname,
+  '..',
+  '..',
+  'scripts',
+  'generate-language-registry.mjs'
+);
 
 /** Renders `entries`/`writeTargets` and reports either the output or the rejection. */
 function render(
   entries: Array<Record<string, unknown>>,
-  writeTargets: string[] = ['de'],
+  writeTargets: string[] = ['de']
 ): { ok: boolean; output: string } {
   const source = `
     const gen = await import(${JSON.stringify(SCRIPT)});
@@ -28,25 +34,41 @@ function render(
       process.stdout.write('ERR\\n' + error.message);
     }
   `;
-  const result = spawnSync('node', ['--input-type=module', '-e', source], { encoding: 'utf-8' });
+  const result = spawnSync('node', ['--input-type=module', '-e', source], {
+    encoding: 'utf-8',
+  });
   const stdout = result.stdout ?? '';
-  return { ok: stdout.startsWith('OK'), output: stdout.slice(stdout.indexOf('\n') + 1) };
+  return {
+    ok: stdout.startsWith('OK'),
+    output: stdout.slice(stdout.indexOf('\n') + 1),
+  };
 }
 
 describe('generate-language-registry', () => {
   describe('benign responses', () => {
     it('should render an entry as a single-quoted literal', () => {
-      const { ok, output } = render([{ code: 'de', name: 'German', category: 'core' }]);
+      const { ok, output } = render([
+        { code: 'de', name: 'German', category: 'core' },
+      ]);
 
       expect(ok).toBe(true);
-      expect(output).toContain("{ code: 'de', name: 'German', category: 'core' },");
+      expect(output).toContain(
+        "{ code: 'de', name: 'German', category: 'core' },"
+      );
       expect(output).toContain("  'de',");
     });
 
     it('should mark a target-only entry', () => {
       const { ok, output } = render(
-        [{ code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true }],
-        ['en-gb'],
+        [
+          {
+            code: 'en-gb',
+            name: 'English (British)',
+            category: 'regional',
+            targetOnly: true,
+          },
+        ],
+        ['en-gb']
       );
 
       expect(ok).toBe(true);
@@ -54,7 +76,11 @@ describe('generate-language-registry', () => {
     });
 
     it('should accept the punctuation real display names use', () => {
-      for (const name of ['Norwegian (bokmål)', 'Kurdish (Sorani)', 'Chinese (simplified)']) {
+      for (const name of [
+        'Norwegian (bokmål)',
+        'Kurdish (Sorani)',
+        'Chinese (simplified)',
+      ]) {
         expect(render([{ code: 'nb', name, category: 'core' }]).ok).toBe(true);
       }
     });
@@ -75,41 +101,54 @@ describe('generate-language-registry', () => {
     });
 
     it('should reject a display name carrying a quote or comment marker', () => {
-      const { ok, output } = render([{ code: 'de', name: "Ger'; eval('x'); //", category: 'core' }]);
+      const { ok, output } = render([
+        { code: 'de', name: "Ger'; eval('x'); //", category: 'core' },
+      ]);
 
       expect(ok).toBe(false);
       expect(output).toMatch(/refusing to write display name/);
     });
 
-    it.each([['newline', 'German\nExtra'], ['backslash', 'German\\']])(
-      'should reject a display name containing a %s',
-      (_label, name) => {
-        expect(render([{ code: 'de', name, category: 'core' }]).ok).toBe(false);
-      },
-    );
+    it.each([
+      ['newline', 'German\nExtra'],
+      ['backslash', 'German\\'],
+    ])('should reject a display name containing a %s', (_label, name) => {
+      expect(render([{ code: 'de', name, category: 'core' }]).ok).toBe(false);
+    });
 
     it('should reject a category outside the three tiers', () => {
-      const { ok, output } = render([{ code: 'de', name: 'German', category: "core'; eval('x')" }]);
+      const { ok, output } = render([
+        { code: 'de', name: 'German', category: "core'; eval('x')" },
+      ]);
 
       expect(ok).toBe(false);
       expect(output).toMatch(/unexpected category/);
     });
 
     it('should reject a non-string code or name', () => {
-      expect(render([{ code: 42, name: 'X', category: 'core' }]).ok).toBe(false);
-      expect(render([{ code: 'de', name: 42, category: 'core' }]).ok).toBe(false);
+      expect(render([{ code: 42, name: 'X', category: 'core' }]).ok).toBe(
+        false
+      );
+      expect(render([{ code: 'de', name: 42, category: 'core' }]).ok).toBe(
+        false
+      );
     });
 
     it('should reject a Write target that is not a language tag', () => {
-      const { ok } = render([{ code: 'de', name: 'German', category: 'core' }], [
-        "de' ], evil = [",
-      ]);
+      const { ok } = render(
+        [{ code: 'de', name: 'German', category: 'core' }],
+        ["de' ], evil = ["]
+      );
 
       // The Write list is validated in main(); rendering it quotes the value so
       // it cannot escape the literal even when reached directly.
       expect(ok).toBe(true);
-      expect(render([{ code: 'de', name: 'German', category: 'core' }], ["de' ], evil = ["]).output)
-        .toContain("'de\\' ], evil = ['");
+      expect(
+        render(
+          [{ code: 'de', name: 'German', category: 'core' }],
+          ["de' ], evil = ["]
+        ).output
+      ).toContain("'de\\' ], evil = ['");
     });
   });
 
@@ -121,12 +160,16 @@ describe('generate-language-registry', () => {
         __dirname,
         '..',
         'fixtures',
-        'throwing-fetch.mjs',
+        'throwing-fetch.mjs'
+      );
+      const result = spawnSync(
+        'node',
+        ['--import', pathToFileURL(preload).href, SCRIPT],
+        {
+          encoding: 'utf-8',
+          env: { ...process.env, DEEPL_API_KEY: 'test-key-for-generator:fx' },
+        }
       );
-      const result = spawnSync('node', ['--import', pathToFileURL(preload).href, SCRIPT], {
-        encoding: 'utf-8',
-        env: { ...process.env, DEEPL_API_KEY: 'test-key-for-generator:fx' },
-      });
 
       expect(result.status).toBe(1);
       expect(result.stderr).toContain('error: simulated transport failure');
diff --git a/tests/unit/glossary-client.test.ts b/tests/unit/glossary-client.test.ts
index b891b9a5..794dd128 100644
--- a/tests/unit/glossary-client.test.ts
+++ b/tests/unit/glossary-client.test.ts
@@ -44,9 +44,24 @@ describe('GlossaryClient', () => {
     it('should derive language pairs from the v3 role-flagged list', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [
-          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: false },
-          { lang: 'de', name: 'German', usable_as_source: false, usable_as_target: true },
-          { lang: 'fr', name: 'French', usable_as_source: false, usable_as_target: true },
+          {
+            lang: 'en',
+            name: 'English',
+            usable_as_source: true,
+            usable_as_target: false,
+          },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: false,
+            usable_as_target: true,
+          },
+          {
+            lang: 'fr',
+            name: 'French',
+            usable_as_source: false,
+            usable_as_target: true,
+          },
         ],
         status: 200,
         headers: {},
@@ -63,7 +78,7 @@ describe('GlossaryClient', () => {
           method: 'GET',
           url: '/v3/languages',
           params: { resource: 'glossary' },
-        }),
+        })
       );
     });
 
@@ -83,15 +98,25 @@ describe('GlossaryClient', () => {
         expect.arrayContaining([
           { sourceLang: 'en', targetLang: 'de' },
           { sourceLang: 'de', targetLang: 'en' },
-        ]),
+        ])
       );
     });
 
     it('should exclude identity pairs', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [
-          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+          {
+            lang: 'en',
+            name: 'English',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
         ],
         status: 200,
         headers: {},
@@ -178,7 +203,11 @@ describe('GlossaryClient', () => {
     it('should handle API errors', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 400, data: { message: 'Bad request' }, headers: {} },
+        response: {
+          status: 400,
+          data: { message: 'Bad request' },
+          headers: {},
+        },
         message: 'Bad request',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -198,7 +227,9 @@ describe('GlossaryClient', () => {
             {
               glossary_id: 'g-1',
               name: 'Glossary 1',
-              dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 5 }],
+              dictionaries: [
+                { source_lang: 'en', target_lang: 'de', entry_count: 5 },
+              ],
               creation_time: '2024-01-01T00:00:00Z',
             },
           ],
@@ -215,7 +246,9 @@ describe('GlossaryClient', () => {
 
     it('should not warn about unrelated empty-dictionary glossaries during list scans', async () => {
       const { Logger } = await import('../../src/utils/logger.js');
-      const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+      const warnSpy = jest
+        .spyOn(Logger, 'warn')
+        .mockImplementation(() => undefined);
       try {
         mockAxiosInstance.request.mockResolvedValue({
           data: {
@@ -269,7 +302,11 @@ describe('GlossaryClient', () => {
       expect.assertions(2);
       const axiosError = Object.assign(new Error('Request failed'), {
         isAxiosError: true,
-        response: { status: 403, data: { message: 'Invalid API key' }, headers: {} },
+        response: {
+          status: 403,
+          data: { message: 'Invalid API key' },
+          headers: {},
+        },
         config: {},
       });
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -291,7 +328,9 @@ describe('GlossaryClient', () => {
         data: {
           glossary_id: 'g-123',
           name: 'Test',
-          dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 3 }],
+          dictionaries: [
+            { source_lang: 'en', target_lang: 'de', entry_count: 3 },
+          ],
           creation_time: '2024-01-01T00:00:00Z',
         },
         status: 200,
@@ -304,7 +343,9 @@ describe('GlossaryClient', () => {
     });
 
     it('should throw for invalid glossary ID format', async () => {
-      await expect(client.getGlossary('invalid id!')).rejects.toThrow('Invalid glossary ID format');
+      await expect(client.getGlossary('invalid id!')).rejects.toThrow(
+        'Invalid glossary ID format'
+      );
     });
   });
 
@@ -320,7 +361,9 @@ describe('GlossaryClient', () => {
     });
 
     it('should throw for invalid glossary ID format', async () => {
-      await expect(client.deleteGlossary('bad id!')).rejects.toThrow('Invalid glossary ID format');
+      await expect(client.deleteGlossary('bad id!')).rejects.toThrow(
+        'Invalid glossary ID format'
+      );
     });
   });
 
@@ -328,12 +371,14 @@ describe('GlossaryClient', () => {
     it('should return entries string', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          dictionaries: [{
-            source_lang: 'en',
-            target_lang: 'de',
-            entries: 'hello\tHallo\nworld\tWelt',
-            entries_format: 'tsv',
-          }],
+          dictionaries: [
+            {
+              source_lang: 'en',
+              target_lang: 'de',
+              entries: 'hello\tHallo\nworld\tWelt',
+              entries_format: 'tsv',
+            },
+          ],
         },
         status: 200,
         headers: {},
@@ -392,7 +437,12 @@ describe('GlossaryClient', () => {
       });
 
       await expect(
-        client.replaceGlossaryDictionary('g-123', 'en', 'de', 'replaced\tErsetzt')
+        client.replaceGlossaryDictionary(
+          'g-123',
+          'en',
+          'de',
+          'replaced\tErsetzt'
+        )
       ).resolves.toBeUndefined();
     });
   });
@@ -411,9 +461,9 @@ describe('GlossaryClient', () => {
     });
 
     it('should throw when no updates provided', async () => {
-      await expect(
-        client.updateGlossary('g-123', {})
-      ).rejects.toThrow('At least one of name or dictionaries must be provided');
+      await expect(client.updateGlossary('g-123', {})).rejects.toThrow(
+        'At least one of name or dictionaries must be provided'
+      );
     });
 
     it('should throw for invalid glossary ID', async () => {
diff --git a/tests/unit/glossary-command.test.ts b/tests/unit/glossary-command.test.ts
index 28d7eaca..6fc8283f 100644
--- a/tests/unit/glossary-command.test.ts
+++ b/tests/unit/glossary-command.test.ts
@@ -2,8 +2,6 @@
  * Tests for Glossary Command
  */
 
- 
-
 import { GlossaryCommand } from '../../src/cli/commands/glossary';
 import { GlossaryService } from '../../src/services/glossary';
 import { GlossaryInfo } from '../../src/types/glossary.js';
@@ -32,11 +30,13 @@ describe('GlossaryCommand', () => {
     name: 'Tech Terms',
     source_lang: 'en',
     target_langs: ['es'],
-    dictionaries: [{
-      source_lang: 'en',
-      target_lang: 'es',
-      entry_count: 10,
-    }],
+    dictionaries: [
+      {
+        source_lang: 'en',
+        target_lang: 'es',
+        entry_count: 10,
+      },
+    ],
     creation_time: '2024-01-15T10:30:00Z',
   };
 
@@ -50,7 +50,9 @@ describe('GlossaryCommand', () => {
       getGlossary: jest.fn().mockResolvedValue(mockGlossary),
       getGlossaryByName: jest.fn().mockResolvedValue(mockGlossary),
       deleteGlossary: jest.fn().mockResolvedValue(undefined),
-      getGlossaryEntries: jest.fn().mockResolvedValue({ hello: 'hola', world: 'mundo' }),
+      getGlossaryEntries: jest
+        .fn()
+        .mockResolvedValue({ hello: 'hola', world: 'mundo' }),
       getGlossaryLanguages: jest.fn().mockResolvedValue([]),
       addEntry: jest.fn().mockResolvedValue(mockGlossary),
       updateEntry: jest.fn().mockResolvedValue(mockGlossary),
@@ -64,16 +66,28 @@ describe('GlossaryCommand', () => {
   describe('create()', () => {
     beforeEach(() => {
       (fs.existsSync as jest.Mock).mockReturnValue(true);
-      (fs.readFileSync as jest.Mock).mockReturnValue('hello\thola\nworld\tmundo');
-      (fs.lstatSync as jest.Mock).mockReturnValue({ isSymbolicLink: () => false });
+      (fs.readFileSync as jest.Mock).mockReturnValue(
+        'hello\thola\nworld\tmundo'
+      );
+      (fs.lstatSync as jest.Mock).mockReturnValue({
+        isSymbolicLink: () => false,
+      });
     });
 
     it('should create glossary from TSV file', async () => {
-      const result = await glossaryCommand.create('Tech Terms', 'en', ['es'], '/path/to/glossary.tsv');
+      const result = await glossaryCommand.create(
+        'Tech Terms',
+        'en',
+        ['es'],
+        '/path/to/glossary.tsv'
+      );
 
       expect(result).toEqual(mockGlossary);
       expect(fs.existsSync).toHaveBeenCalledWith('/path/to/glossary.tsv');
-      expect(fs.readFileSync).toHaveBeenCalledWith('/path/to/glossary.tsv', 'utf-8');
+      expect(fs.readFileSync).toHaveBeenCalledWith(
+        '/path/to/glossary.tsv',
+        'utf-8'
+      );
       expect(mockGlossaryService.createGlossaryFromTSV).toHaveBeenCalledWith(
         'Tech Terms',
         'en',
@@ -86,7 +100,12 @@ describe('GlossaryCommand', () => {
       (fs.existsSync as jest.Mock).mockReturnValue(false);
 
       await expect(
-        glossaryCommand.create('Tech Terms', 'en', ['es'], '/path/to/missing.tsv')
+        glossaryCommand.create(
+          'Tech Terms',
+          'en',
+          ['es'],
+          '/path/to/missing.tsv'
+        )
       ).rejects.toThrow('File not found');
     });
 
@@ -99,26 +118,43 @@ describe('GlossaryCommand', () => {
     });
 
     it('should handle glossary service errors', async () => {
-      (mockGlossaryService.createGlossaryFromTSV as jest.Mock).mockRejectedValueOnce(
-        new Error('Invalid glossary format')
-      );
+      (
+        mockGlossaryService.createGlossaryFromTSV as jest.Mock
+      ).mockRejectedValueOnce(new Error('Invalid glossary format'));
 
       await expect(
-        glossaryCommand.create('Tech Terms', 'en', ['es'], '/path/to/glossary.tsv')
+        glossaryCommand.create(
+          'Tech Terms',
+          'en',
+          ['es'],
+          '/path/to/glossary.tsv'
+        )
       ).rejects.toThrow('Invalid glossary format');
     });
 
     it('should reject symlinks for security', async () => {
       (fs.existsSync as jest.Mock).mockReturnValue(true);
-      (fs.lstatSync as jest.Mock).mockReturnValue({ isSymbolicLink: () => true });
+      (fs.lstatSync as jest.Mock).mockReturnValue({
+        isSymbolicLink: () => true,
+      });
 
       await expect(
-        glossaryCommand.create('Tech Terms', 'en', ['es'], '/path/to/symlink.tsv')
+        glossaryCommand.create(
+          'Tech Terms',
+          'en',
+          ['es'],
+          '/path/to/symlink.tsv'
+        )
       ).rejects.toThrow('Symlinks are not supported for security reasons');
     });
 
     it('should support multiple target languages', async () => {
-      const result = await glossaryCommand.create('Multi Terms', 'en', ['es', 'fr', 'de'], '/path/to/glossary.tsv');
+      const result = await glossaryCommand.create(
+        'Multi Terms',
+        'en',
+        ['es', 'fr', 'de'],
+        '/path/to/glossary.tsv'
+      );
 
       expect(result).toEqual(mockGlossary);
       expect(mockGlossaryService.createGlossaryFromTSV).toHaveBeenCalledWith(
@@ -139,7 +175,9 @@ describe('GlossaryCommand', () => {
     });
 
     it('should return empty array when no glossaries exist', async () => {
-      (mockGlossaryService.listGlossaries as jest.Mock).mockResolvedValueOnce([]);
+      (mockGlossaryService.listGlossaries as jest.Mock).mockResolvedValueOnce(
+        []
+      );
 
       const result = await glossaryCommand.list();
 
@@ -152,7 +190,9 @@ describe('GlossaryCommand', () => {
       const result = await glossaryCommand.show('123-456-789');
 
       expect(result).toEqual(mockGlossary);
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
     });
 
     it('should fallback to get by name if ID fails', async () => {
@@ -162,8 +202,12 @@ describe('GlossaryCommand', () => {
 
       const result = await glossaryCommand.show('Tech Terms');
 
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('Tech Terms');
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
       expect(result).toEqual(mockGlossary);
     });
 
@@ -171,9 +215,13 @@ describe('GlossaryCommand', () => {
       (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
         new Error('Not found')
       );
-      (mockGlossaryService.getGlossaryByName as jest.Mock).mockResolvedValueOnce(null);
+      (
+        mockGlossaryService.getGlossaryByName as jest.Mock
+      ).mockResolvedValueOnce(null);
 
-      await expect(glossaryCommand.show('NonExistent')).rejects.toThrow('Glossary not found');
+      await expect(glossaryCommand.show('NonExistent')).rejects.toThrow(
+        'Glossary not found'
+      );
     });
   });
 
@@ -181,8 +229,12 @@ describe('GlossaryCommand', () => {
     it('should delete glossary by ID', async () => {
       await glossaryCommand.delete('123-456-789');
 
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
-      expect(mockGlossaryService.deleteGlossary).toHaveBeenCalledWith('123-456-789');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
+      expect(mockGlossaryService.deleteGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
     });
 
     it('should delete glossary by name', async () => {
@@ -192,15 +244,25 @@ describe('GlossaryCommand', () => {
 
       await glossaryCommand.delete('Tech Terms');
 
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
-      expect(mockGlossaryService.deleteGlossary).toHaveBeenCalledWith('123-456-789');
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
+      expect(mockGlossaryService.deleteGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
     });
 
     it('should propagate error when glossary not found for deletion', async () => {
-      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(new Error('Not found'));
-      (mockGlossaryService.getGlossaryByName as jest.Mock).mockResolvedValueOnce(null);
+      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
+        new Error('Not found')
+      );
+      (
+        mockGlossaryService.getGlossaryByName as jest.Mock
+      ).mockResolvedValueOnce(null);
 
-      await expect(glossaryCommand.delete('NonExistent')).rejects.toThrow('Glossary not found');
+      await expect(glossaryCommand.delete('NonExistent')).rejects.toThrow(
+        'Glossary not found'
+      );
     });
 
     it('should handle delete service errors', async () => {
@@ -208,7 +270,9 @@ describe('GlossaryCommand', () => {
         new Error('Permission denied')
       );
 
-      await expect(glossaryCommand.delete('123-456-789')).rejects.toThrow('Permission denied');
+      await expect(glossaryCommand.delete('123-456-789')).rejects.toThrow(
+        'Permission denied'
+      );
     });
   });
 
@@ -217,8 +281,14 @@ describe('GlossaryCommand', () => {
       const result = await glossaryCommand.entries('123-456-789');
 
       expect(result).toEqual({ hello: 'hola', world: 'mundo' });
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
-      expect(mockGlossaryService.getGlossaryEntries).toHaveBeenCalledWith('123-456-789', 'en', 'es');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
+      expect(mockGlossaryService.getGlossaryEntries).toHaveBeenCalledWith(
+        '123-456-789',
+        'en',
+        'es'
+      );
     });
 
     it('should get entries with explicit target language', async () => {
@@ -233,22 +303,36 @@ describe('GlossaryCommand', () => {
         ],
         creation_time: '2024-01-15T10:30:00Z',
       };
-      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(multilingualGlossary);
+      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(
+        multilingualGlossary
+      );
 
       const result = await glossaryCommand.entries('multi-123', 'fr');
 
       expect(result).toEqual({ hello: 'hola', world: 'mundo' });
-      expect(mockGlossaryService.getGlossaryEntries).toHaveBeenCalledWith('multi-123', 'en', 'fr');
+      expect(mockGlossaryService.getGlossaryEntries).toHaveBeenCalledWith(
+        'multi-123',
+        'en',
+        'fr'
+      );
     });
 
     it('should get entries by glossary name', async () => {
-      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(new Error('Not found'));
+      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
+        new Error('Not found')
+      );
 
       const result = await glossaryCommand.entries('Tech Terms');
 
       expect(result).toEqual({ hello: 'hola', world: 'mundo' });
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
-      expect(mockGlossaryService.getGlossaryEntries).toHaveBeenCalledWith('123-456-789', 'en', 'es');
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
+      expect(mockGlossaryService.getGlossaryEntries).toHaveBeenCalledWith(
+        '123-456-789',
+        'en',
+        'es'
+      );
     });
   });
 
@@ -258,7 +342,9 @@ describe('GlossaryCommand', () => {
         { sourceLang: 'en', targetLang: 'es' },
         { sourceLang: 'de', targetLang: 'en' },
       ];
-      (mockGlossaryService.getGlossaryLanguages as jest.Mock).mockResolvedValue(mockPairs);
+      (mockGlossaryService.getGlossaryLanguages as jest.Mock).mockResolvedValue(
+        mockPairs
+      );
 
       const result = await glossaryCommand.listLanguages();
 
@@ -273,18 +359,36 @@ describe('GlossaryCommand', () => {
 
       await glossaryCommand.addEntry('123-456-789', 'hello', 'hola');
 
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
-      expect(mockGlossaryService.addEntry).toHaveBeenCalledWith('123-456-789', 'en', 'es', 'hello', 'hola');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
+      expect(mockGlossaryService.addEntry).toHaveBeenCalledWith(
+        '123-456-789',
+        'en',
+        'es',
+        'hello',
+        'hola'
+      );
     });
 
     it('should add entry to glossary by name', async () => {
-      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(new Error('Not found'));
+      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
+        new Error('Not found')
+      );
       (mockGlossaryService.addEntry as jest.Mock).mockResolvedValue(undefined);
 
       await glossaryCommand.addEntry('Tech Terms', 'hello', 'hola');
 
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
-      expect(mockGlossaryService.addEntry).toHaveBeenCalledWith('123-456-789', 'en', 'es', 'hello', 'hola');
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
+      expect(mockGlossaryService.addEntry).toHaveBeenCalledWith(
+        '123-456-789',
+        'en',
+        'es',
+        'hello',
+        'hola'
+      );
     });
 
     it('should add entry with explicit target language for multilingual glossary', async () => {
@@ -299,12 +403,20 @@ describe('GlossaryCommand', () => {
         ],
         creation_time: '2024-01-15T10:30:00Z',
       };
-      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(multilingualGlossary);
+      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(
+        multilingualGlossary
+      );
       (mockGlossaryService.addEntry as jest.Mock).mockResolvedValue(undefined);
 
       await glossaryCommand.addEntry('multi-123', 'hello', 'bonjour', 'fr');
 
-      expect(mockGlossaryService.addEntry).toHaveBeenCalledWith('multi-123', 'en', 'fr', 'hello', 'bonjour');
+      expect(mockGlossaryService.addEntry).toHaveBeenCalledWith(
+        'multi-123',
+        'en',
+        'fr',
+        'hello',
+        'bonjour'
+      );
     });
 
     it('should handle addEntry service errors', async () => {
@@ -320,22 +432,44 @@ describe('GlossaryCommand', () => {
 
   describe('updateEntry()', () => {
     it('should update entry in glossary by ID', async () => {
-      (mockGlossaryService.updateEntry as jest.Mock).mockResolvedValue(undefined);
+      (mockGlossaryService.updateEntry as jest.Mock).mockResolvedValue(
+        undefined
+      );
 
       await glossaryCommand.updateEntry('123-456-789', 'hello', 'hola updated');
 
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
-      expect(mockGlossaryService.updateEntry).toHaveBeenCalledWith('123-456-789', 'en', 'es', 'hello', 'hola updated');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
+      expect(mockGlossaryService.updateEntry).toHaveBeenCalledWith(
+        '123-456-789',
+        'en',
+        'es',
+        'hello',
+        'hola updated'
+      );
     });
 
     it('should update entry in glossary by name', async () => {
-      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(new Error('Not found'));
-      (mockGlossaryService.updateEntry as jest.Mock).mockResolvedValue(undefined);
+      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
+        new Error('Not found')
+      );
+      (mockGlossaryService.updateEntry as jest.Mock).mockResolvedValue(
+        undefined
+      );
 
       await glossaryCommand.updateEntry('Tech Terms', 'hello', 'hola updated');
 
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
-      expect(mockGlossaryService.updateEntry).toHaveBeenCalledWith('123-456-789', 'en', 'es', 'hello', 'hola updated');
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
+      expect(mockGlossaryService.updateEntry).toHaveBeenCalledWith(
+        '123-456-789',
+        'en',
+        'es',
+        'hello',
+        'hola updated'
+      );
     });
 
     it('should update entry with explicit target language for multilingual glossary', async () => {
@@ -350,33 +484,68 @@ describe('GlossaryCommand', () => {
         ],
         creation_time: '2024-01-15T10:30:00Z',
       };
-      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(multilingualGlossary);
-      (mockGlossaryService.updateEntry as jest.Mock).mockResolvedValue(undefined);
+      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(
+        multilingualGlossary
+      );
+      (mockGlossaryService.updateEntry as jest.Mock).mockResolvedValue(
+        undefined
+      );
 
-      await glossaryCommand.updateEntry('multi-123', 'hello', 'bonjour updated', 'fr');
+      await glossaryCommand.updateEntry(
+        'multi-123',
+        'hello',
+        'bonjour updated',
+        'fr'
+      );
 
-      expect(mockGlossaryService.updateEntry).toHaveBeenCalledWith('multi-123', 'en', 'fr', 'hello', 'bonjour updated');
+      expect(mockGlossaryService.updateEntry).toHaveBeenCalledWith(
+        'multi-123',
+        'en',
+        'fr',
+        'hello',
+        'bonjour updated'
+      );
     });
   });
 
   describe('removeEntry()', () => {
     it('should remove entry from glossary by ID', async () => {
-      (mockGlossaryService.removeEntry as jest.Mock).mockResolvedValue(undefined);
+      (mockGlossaryService.removeEntry as jest.Mock).mockResolvedValue(
+        undefined
+      );
 
       await glossaryCommand.removeEntry('123-456-789', 'hello');
 
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
-      expect(mockGlossaryService.removeEntry).toHaveBeenCalledWith('123-456-789', 'en', 'es', 'hello');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
+      expect(mockGlossaryService.removeEntry).toHaveBeenCalledWith(
+        '123-456-789',
+        'en',
+        'es',
+        'hello'
+      );
     });
 
     it('should remove entry from glossary by name', async () => {
-      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(new Error('Not found'));
-      (mockGlossaryService.removeEntry as jest.Mock).mockResolvedValue(undefined);
+      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
+        new Error('Not found')
+      );
+      (mockGlossaryService.removeEntry as jest.Mock).mockResolvedValue(
+        undefined
+      );
 
       await glossaryCommand.removeEntry('Tech Terms', 'hello');
 
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
-      expect(mockGlossaryService.removeEntry).toHaveBeenCalledWith('123-456-789', 'en', 'es', 'hello');
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
+      expect(mockGlossaryService.removeEntry).toHaveBeenCalledWith(
+        '123-456-789',
+        'en',
+        'es',
+        'hello'
+      );
     });
 
     it('should remove entry with explicit target language for multilingual glossary', async () => {
@@ -391,33 +560,58 @@ describe('GlossaryCommand', () => {
         ],
         creation_time: '2024-01-15T10:30:00Z',
       };
-      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(multilingualGlossary);
-      (mockGlossaryService.removeEntry as jest.Mock).mockResolvedValue(undefined);
+      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(
+        multilingualGlossary
+      );
+      (mockGlossaryService.removeEntry as jest.Mock).mockResolvedValue(
+        undefined
+      );
 
       await glossaryCommand.removeEntry('multi-123', 'hello', 'fr');
 
-      expect(mockGlossaryService.removeEntry).toHaveBeenCalledWith('multi-123', 'en', 'fr', 'hello');
+      expect(mockGlossaryService.removeEntry).toHaveBeenCalledWith(
+        'multi-123',
+        'en',
+        'fr',
+        'hello'
+      );
     });
   });
 
   describe('rename()', () => {
     it('should rename glossary by ID', async () => {
-      (mockGlossaryService.renameGlossary as jest.Mock).mockResolvedValue(undefined);
+      (mockGlossaryService.renameGlossary as jest.Mock).mockResolvedValue(
+        undefined
+      );
 
       await glossaryCommand.rename('123-456-789', 'New Name');
 
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
-      expect(mockGlossaryService.renameGlossary).toHaveBeenCalledWith('123-456-789', 'New Name');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
+      expect(mockGlossaryService.renameGlossary).toHaveBeenCalledWith(
+        '123-456-789',
+        'New Name'
+      );
     });
 
     it('should rename glossary by name', async () => {
-      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(new Error('Not found'));
-      (mockGlossaryService.renameGlossary as jest.Mock).mockResolvedValue(undefined);
+      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
+        new Error('Not found')
+      );
+      (mockGlossaryService.renameGlossary as jest.Mock).mockResolvedValue(
+        undefined
+      );
 
       await glossaryCommand.rename('Tech Terms', 'New Name');
 
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
-      expect(mockGlossaryService.renameGlossary).toHaveBeenCalledWith('123-456-789', 'New Name');
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
+      expect(mockGlossaryService.renameGlossary).toHaveBeenCalledWith(
+        '123-456-789',
+        'New Name'
+      );
     });
 
     it('should handle rename errors', async () => {
@@ -544,7 +738,10 @@ describe('GlossaryCommand', () => {
         creation_time: '2024-02-01T08:00:00Z',
       };
 
-      const result = glossaryCommand.formatGlossaryList([mockGlossary, secondGlossary]);
+      const result = glossaryCommand.formatGlossaryList([
+        mockGlossary,
+        secondGlossary,
+      ]);
 
       expect(result).toContain('Tech Terms');
       expect(result).toContain('Medical Terms');
@@ -569,17 +766,31 @@ describe('GlossaryCommand', () => {
   describe('replaceDictionary()', () => {
     beforeEach(() => {
       (fs.existsSync as jest.Mock).mockReturnValue(true);
-      (fs.readFileSync as jest.Mock).mockReturnValue('hello\thola\nworld\tmundo');
-      (fs.lstatSync as jest.Mock).mockReturnValue({ isSymbolicLink: () => false });
-      mockGlossaryService.replaceGlossaryDictionary = jest.fn().mockResolvedValue(undefined);
+      (fs.readFileSync as jest.Mock).mockReturnValue(
+        'hello\thola\nworld\tmundo'
+      );
+      (fs.lstatSync as jest.Mock).mockReturnValue({
+        isSymbolicLink: () => false,
+      });
+      mockGlossaryService.replaceGlossaryDictionary = jest
+        .fn()
+        .mockResolvedValue(undefined);
     });
 
     it('should replace dictionary entries from file', async () => {
-      await glossaryCommand.replaceDictionary('123-456-789', 'es', '/path/to/glossary.tsv');
+      await glossaryCommand.replaceDictionary(
+        '123-456-789',
+        'es',
+        '/path/to/glossary.tsv'
+      );
 
       expect(fs.existsSync).toHaveBeenCalledWith('/path/to/glossary.tsv');
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
-      expect(mockGlossaryService.replaceGlossaryDictionary).toHaveBeenCalledWith(
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
+      expect(
+        mockGlossaryService.replaceGlossaryDictionary
+      ).toHaveBeenCalledWith(
         '123-456-789',
         'en',
         'es',
@@ -591,25 +802,45 @@ describe('GlossaryCommand', () => {
       (fs.existsSync as jest.Mock).mockReturnValue(false);
 
       await expect(
-        glossaryCommand.replaceDictionary('123-456-789', 'es', '/path/to/missing.tsv')
+        glossaryCommand.replaceDictionary(
+          '123-456-789',
+          'es',
+          '/path/to/missing.tsv'
+        )
       ).rejects.toThrow('File not found: /path/to/missing.tsv');
     });
 
     it('should reject symlinks for security', async () => {
-      (fs.lstatSync as jest.Mock).mockReturnValue({ isSymbolicLink: () => true });
+      (fs.lstatSync as jest.Mock).mockReturnValue({
+        isSymbolicLink: () => true,
+      });
 
       await expect(
-        glossaryCommand.replaceDictionary('123-456-789', 'es', '/path/to/symlink.tsv')
+        glossaryCommand.replaceDictionary(
+          '123-456-789',
+          'es',
+          '/path/to/symlink.tsv'
+        )
       ).rejects.toThrow('Symlinks are not supported for security reasons');
     });
 
     it('should resolve glossary by name for replaceDictionary', async () => {
-      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(new Error('Not found'));
+      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
+        new Error('Not found')
+      );
 
-      await glossaryCommand.replaceDictionary('Tech Terms', 'es', '/path/to/glossary.tsv');
+      await glossaryCommand.replaceDictionary(
+        'Tech Terms',
+        'es',
+        '/path/to/glossary.tsv'
+      );
 
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
-      expect(mockGlossaryService.replaceGlossaryDictionary).toHaveBeenCalledWith(
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
+      expect(
+        mockGlossaryService.replaceGlossaryDictionary
+      ).toHaveBeenCalledWith(
         '123-456-789',
         'en',
         'es',
@@ -620,13 +851,17 @@ describe('GlossaryCommand', () => {
 
   describe('deleteDictionary()', () => {
     beforeEach(() => {
-      mockGlossaryService.deleteGlossaryDictionary = jest.fn().mockResolvedValue(undefined);
+      mockGlossaryService.deleteGlossaryDictionary = jest
+        .fn()
+        .mockResolvedValue(undefined);
     });
 
     it('should delete dictionary by glossary ID and target language', async () => {
       await glossaryCommand.deleteDictionary('123-456-789', 'es');
 
-      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith('123-456-789');
+      expect(mockGlossaryService.getGlossary).toHaveBeenCalledWith(
+        '123-456-789'
+      );
       expect(mockGlossaryService.deleteGlossaryDictionary).toHaveBeenCalledWith(
         '123-456-789',
         'en',
@@ -635,11 +870,15 @@ describe('GlossaryCommand', () => {
     });
 
     it('should delete dictionary by glossary name and target language', async () => {
-      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(new Error('Not found'));
+      (mockGlossaryService.getGlossary as jest.Mock).mockRejectedValueOnce(
+        new Error('Not found')
+      );
 
       await glossaryCommand.deleteDictionary('Tech Terms', 'es');
 
-      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith('Tech Terms');
+      expect(mockGlossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'Tech Terms'
+      );
       expect(mockGlossaryService.deleteGlossaryDictionary).toHaveBeenCalledWith(
         '123-456-789',
         'en',
@@ -648,9 +887,9 @@ describe('GlossaryCommand', () => {
     });
 
     it('should handle delete dictionary service errors', async () => {
-      mockGlossaryService.deleteGlossaryDictionary = jest.fn().mockRejectedValueOnce(
-        new Error('Dictionary not found')
-      );
+      mockGlossaryService.deleteGlossaryDictionary = jest
+        .fn()
+        .mockRejectedValueOnce(new Error('Dictionary not found'));
 
       await expect(
         glossaryCommand.deleteDictionary('123-456-789', 'fr')
@@ -737,7 +976,9 @@ describe('GlossaryCommand', () => {
     });
 
     it('should produce valid JSON for empty glossary list', async () => {
-      (mockGlossaryService.listGlossaries as jest.Mock).mockResolvedValueOnce([]);
+      (mockGlossaryService.listGlossaries as jest.Mock).mockResolvedValueOnce(
+        []
+      );
       const glossaries = await glossaryCommand.list();
       const json = JSON.stringify(glossaries, null, 2);
       const parsed = JSON.parse(json);
@@ -756,7 +997,9 @@ describe('GlossaryCommand', () => {
         ],
         creation_time: '2024-01-15T10:30:00Z',
       };
-      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(multiGlossary);
+      (mockGlossaryService.getGlossary as jest.Mock).mockResolvedValueOnce(
+        multiGlossary
+      );
 
       const glossary = await glossaryCommand.show('multi-123');
       const json = JSON.stringify(glossary, null, 2);
diff --git a/tests/unit/glossary-params.test.ts b/tests/unit/glossary-params.test.ts
index ff76014f..50921455 100644
--- a/tests/unit/glossary-params.test.ts
+++ b/tests/unit/glossary-params.test.ts
@@ -25,15 +25,21 @@ describe('resolveGlossaryWireParams', () => {
   });
 
   it('should send a lone glossaryId as glossary_id', () => {
-    expect(resolveGlossaryWireParams({ glossaryId: A })).toEqual({ glossary_id: A });
+    expect(resolveGlossaryWireParams({ glossaryId: A })).toEqual({
+      glossary_id: A,
+    });
   });
 
   it('should send a single-entry glossaryIds list as glossary_id', () => {
-    expect(resolveGlossaryWireParams({ glossaryIds: [A] })).toEqual({ glossary_id: A });
+    expect(resolveGlossaryWireParams({ glossaryIds: [A] })).toEqual({
+      glossary_id: A,
+    });
   });
 
   it('should send two or more IDs as glossary_ids', () => {
-    expect(resolveGlossaryWireParams({ glossaryIds: [A, B] })).toEqual({ glossary_ids: [A, B] });
+    expect(resolveGlossaryWireParams({ glossaryIds: [A, B] })).toEqual({
+      glossary_ids: [A, B],
+    });
   });
 
   it('should preserve the caller order rather than sorting it', () => {
@@ -45,26 +51,32 @@ describe('resolveGlossaryWireParams', () => {
   it('should accept exactly the maximum number of glossaries', () => {
     const ids = [A, B, C, A, B];
     expect(ids).toHaveLength(MAX_GLOSSARIES_PER_REQUEST);
-    expect(resolveGlossaryWireParams({ glossaryIds: ids })).toEqual({ glossary_ids: ids });
+    expect(resolveGlossaryWireParams({ glossaryIds: ids })).toEqual({
+      glossary_ids: ids,
+    });
   });
 
   it('should reject more than the maximum number of glossaries', () => {
     expect.assertions(3);
     const ids = [A, B, C, A, B, C];
-    expect(() => resolveGlossaryWireParams({ glossaryIds: ids })).toThrow(ValidationError);
+    expect(() => resolveGlossaryWireParams({ glossaryIds: ids })).toThrow(
+      ValidationError
+    );
     try {
       resolveGlossaryWireParams({ glossaryIds: ids });
     } catch (error) {
-      expect((error as ValidationError).message).toContain('maximum of 5 glossaries');
+      expect((error as ValidationError).message).toContain(
+        'maximum of 5 glossaries'
+      );
       expect((error as ValidationError).message).toContain('got 6');
     }
   });
 
   it('should reject glossaryId combined with glossaryIds, which the API refuses', () => {
     expect.assertions(2);
-    expect(() => resolveGlossaryWireParams({ glossaryId: A, glossaryIds: [B] })).toThrow(
-      ValidationError,
-    );
+    expect(() =>
+      resolveGlossaryWireParams({ glossaryId: A, glossaryIds: [B] })
+    ).toThrow(ValidationError);
     try {
       resolveGlossaryWireParams({ glossaryId: A, glossaryIds: [B] });
     } catch (error) {
@@ -73,7 +85,9 @@ describe('resolveGlossaryWireParams', () => {
   });
 
   it('should ignore an empty glossaryIds list alongside glossaryId', () => {
-    expect(resolveGlossaryWireParams({ glossaryId: A, glossaryIds: [] })).toEqual({
+    expect(
+      resolveGlossaryWireParams({ glossaryId: A, glossaryIds: [] })
+    ).toEqual({
       glossary_id: A,
     });
   });
@@ -101,7 +115,8 @@ describe('hasGlossarySelection', () => {
 });
 
 describe('applyGlossarySourceLang', () => {
-  const example = 'Example: deepl translate --from en --to es --glossary g "Hello"';
+  const example =
+    'Example: deepl translate --from en --to es --glossary g "Hello"';
 
   it('should leave an explicit --from alone', () => {
     const options = { glossary: ['terms'], from: 'de' };
@@ -112,23 +127,27 @@ describe('applyGlossarySourceLang', () => {
   it('should fall back to the configured source language', () => {
     // The request carries source_lang either way, so a missing flag is not on
     // its own a reason to reject.
-    const options: { glossary: string[]; from?: string } = { glossary: ['terms'] };
+    const options: { glossary: string[]; from?: string } = {
+      glossary: ['terms'],
+    };
     applyGlossarySourceLang(options, 'EN', example);
     expect(options.from).toBe('en');
   });
 
   it('should throw only when neither the flag nor the config supplies one', () => {
-    expect(() => applyGlossarySourceLang({ glossary: ['terms'] }, undefined, example)).toThrow(
-      ValidationError,
-    );
-    expect(() => applyGlossarySourceLang({ glossary: ['terms'] }, undefined, example)).toThrow(
-      'Source language (--from) is required when using a glossary',
-    );
+    expect(() =>
+      applyGlossarySourceLang({ glossary: ['terms'] }, undefined, example)
+    ).toThrow(ValidationError);
+    expect(() =>
+      applyGlossarySourceLang({ glossary: ['terms'] }, undefined, example)
+    ).toThrow('Source language (--from) is required when using a glossary');
   });
 
   it('should do nothing when no glossary is selected', () => {
     const options: { glossary?: string[]; from?: string } = { glossary: [] };
-    expect(() => applyGlossarySourceLang(options, undefined, example)).not.toThrow();
+    expect(() =>
+      applyGlossarySourceLang(options, undefined, example)
+    ).not.toThrow();
     expect(options.from).toBeUndefined();
   });
 
diff --git a/tests/unit/glossary-service.test.ts b/tests/unit/glossary-service.test.ts
index b5256b1c..c8479680 100644
--- a/tests/unit/glossary-service.test.ts
+++ b/tests/unit/glossary-service.test.ts
@@ -29,9 +29,9 @@ describe('GlossaryService', () => {
   describe('createGlossary()', () => {
     it('should create a glossary from entries', async () => {
       const entries = {
-        'API': 'API',
-        'REST': 'REST',
-        'Hello': 'Hola',
+        API: 'API',
+        REST: 'REST',
+        Hello: 'Hola',
       };
 
       mockDeepLClient.createGlossary.mockResolvedValue({
@@ -39,11 +39,13 @@ describe('GlossaryService', () => {
         name: 'tech-terms',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -87,11 +89,13 @@ describe('GlossaryService', () => {
         name: 'test',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -113,11 +117,13 @@ describe('GlossaryService', () => {
         name: 'test',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -139,11 +145,13 @@ describe('GlossaryService', () => {
         name: 'test',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -166,11 +174,13 @@ describe('GlossaryService', () => {
           name: 'tech-terms',
           source_lang: 'en',
           target_langs: ['es'],
-          dictionaries: [{
-            source_lang: 'en',
-            target_lang: 'es',
-            entry_count: 10,
-          }],
+          dictionaries: [
+            {
+              source_lang: 'en',
+              target_lang: 'es',
+              entry_count: 10,
+            },
+          ],
           creation_time: '2024-01-01T00:00:00Z',
         },
         {
@@ -178,11 +188,13 @@ describe('GlossaryService', () => {
           name: 'legal-terms',
           source_lang: 'en',
           target_langs: ['de'],
-          dictionaries: [{
-            source_lang: 'en',
-            target_lang: 'de',
-            entry_count: 25,
-          }],
+          dictionaries: [
+            {
+              source_lang: 'en',
+              target_lang: 'de',
+              entry_count: 25,
+            },
+          ],
           creation_time: '2024-01-02T00:00:00Z',
         },
       ]);
@@ -210,11 +222,13 @@ describe('GlossaryService', () => {
         name: 'tech-terms',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 10,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 10,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -230,9 +244,9 @@ describe('GlossaryService', () => {
         new Error('Glossary not found')
       );
 
-      await expect(
-        glossaryService.getGlossary('non-existent')
-      ).rejects.toThrow('Glossary not found');
+      await expect(glossaryService.getGlossary('non-existent')).rejects.toThrow(
+        'Glossary not found'
+      );
     });
   });
 
@@ -244,11 +258,13 @@ describe('GlossaryService', () => {
           name: 'tech-terms',
           source_lang: 'en',
           target_langs: ['es'],
-          dictionaries: [{
-            source_lang: 'en',
-            target_lang: 'es',
-            entry_count: 10,
-          }],
+          dictionaries: [
+            {
+              source_lang: 'en',
+              target_lang: 'es',
+              entry_count: 10,
+            },
+          ],
           creation_time: '2024-01-01T00:00:00Z',
         },
       ]);
@@ -269,7 +285,9 @@ describe('GlossaryService', () => {
 
     it('should warn when the matched glossary itself has empty dictionaries', async () => {
       const { Logger } = await import('../../src/utils/logger.js');
-      const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+      const warnSpy = jest
+        .spyOn(Logger, 'warn')
+        .mockImplementation(() => undefined);
       try {
         mockDeepLClient.listGlossaries.mockResolvedValue([
           {
@@ -282,10 +300,13 @@ describe('GlossaryService', () => {
           },
         ]);
 
-        const glossary = await glossaryService.getGlossaryByName('still-processing');
+        const glossary =
+          await glossaryService.getGlossaryByName('still-processing');
 
         expect(glossary?.glossary_id).toBe('empty-123');
-        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('empty dictionaries'));
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('empty dictionaries')
+        );
       } finally {
         warnSpy.mockRestore();
       }
@@ -309,11 +330,13 @@ describe('GlossaryService', () => {
           name: 'tech-terms',
           source_lang: 'en',
           target_langs: ['es'],
-          dictionaries: [{
-            source_lang: 'en',
-            target_lang: 'es',
-            entry_count: 10,
-          }],
+          dictionaries: [
+            {
+              source_lang: 'en',
+              target_lang: 'es',
+              entry_count: 10,
+            },
+          ],
           creation_time: '2024-01-01T00:00:00Z',
         },
       ]);
@@ -342,48 +365,61 @@ describe('GlossaryService', () => {
     });
 
     describe('language-pair preflight', () => {
-      const listing = (dictionaries: Array<{ source_lang: string; target_lang: string }>) => [
+      const listing = (
+        dictionaries: Array<{ source_lang: string; target_lang: string }>
+      ) => [
         {
           glossary_id: 'found-glossary-id',
           name: 'tech-terms',
           source_lang: dictionaries[0]!.source_lang,
-          target_langs: dictionaries.map(d => d.target_lang),
-          dictionaries: dictionaries.map(d => ({ ...d, entry_count: 1 })),
+          target_langs: dictionaries.map((d) => d.target_lang),
+          dictionaries: dictionaries.map((d) => ({ ...d, entry_count: 1 })),
           creation_time: '2024-01-01T00:00:00Z',
         },
       ];
 
       it('should resolve when a dictionary covers the requested pair', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'en', target_lang: 'es' }]) as never,
+          listing([{ source_lang: 'en', target_lang: 'es' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['es'],
+          })
         ).resolves.toBe('found-glossary-id');
       });
 
       it('should reject when no dictionary covers the requested target', async () => {
         expect.assertions(2);
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'en', target_lang: 'es' }]) as never,
+          listing([{ source_lang: 'en', target_lang: 'es' }]) as never
         );
 
         try {
-          await glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['de'] });
+          await glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['de'],
+          });
         } catch (error) {
-          expect((error as Error).message).toContain('does not support the requested language pair');
+          expect((error as Error).message).toContain(
+            'does not support the requested language pair'
+          );
           expect((error as ConfigError).suggestion).toContain('en→es');
         }
       });
 
       it('should reject when the source language does not match', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'en', target_lang: 'es' }]) as never,
+          listing([{ source_lang: 'en', target_lang: 'es' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'de', targets: ['es'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'de',
+            targets: ['es'],
+          })
         ).rejects.toThrow('does not support the requested language pair');
       });
 
@@ -392,14 +428,20 @@ describe('GlossaryService', () => {
           listing([
             { source_lang: 'en', target_lang: 'es' },
             { source_lang: 'en', target_lang: 'fr' },
-          ]) as never,
+          ]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es', 'fr'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['es', 'fr'],
+          })
         ).resolves.toBe('found-glossary-id');
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es', 'de'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['es', 'de'],
+          })
         ).rejects.toThrow('does not support the requested language pair');
       });
 
@@ -409,11 +451,14 @@ describe('GlossaryService', () => {
           listing([
             { source_lang: 'en', target_lang: 'es' },
             { source_lang: 'de', target_lang: 'fr' },
-          ]) as never,
+          ]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['fr'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['fr'],
+          })
         ).rejects.toThrow('does not support the requested language pair');
       });
 
@@ -422,33 +467,42 @@ describe('GlossaryService', () => {
         // variants, so de→en has to cover de→en-us or glossaries become
         // unusable for the variants DeepL steers users towards.
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'de', target_lang: 'en' }]) as never,
+          listing([{ source_lang: 'de', target_lang: 'en' }]) as never
         );
 
         for (const target of ['en-us', 'en-gb'] as const) {
           await expect(
-            glossaryService.resolveGlossaryId('tech-terms', { from: 'de', targets: [target] }),
+            glossaryService.resolveGlossaryId('tech-terms', {
+              from: 'de',
+              targets: [target],
+            })
           ).resolves.toBe('found-glossary-id');
         }
       });
 
       it('should treat a regional --from as covered by a base-language dictionary', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'pt', target_lang: 'de' }]) as never,
+          listing([{ source_lang: 'pt', target_lang: 'de' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'pt-br', targets: ['de'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'pt-br',
+            targets: ['de'],
+          })
         ).resolves.toBe('found-glossary-id');
       });
 
       it('should still reject a pair no dictionary covers even across regions', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'de', target_lang: 'en' }]) as never,
+          listing([{ source_lang: 'de', target_lang: 'en' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'de', targets: ['pt-br'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'de',
+            targets: ['pt-br'],
+          })
         ).rejects.toThrow('does not support the requested language pair');
       });
 
@@ -458,41 +512,53 @@ describe('GlossaryService', () => {
         // both sides on their base language would make a pt-br dictionary satisfy
         // pt-pt, which is a different language pair.
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'en', target_lang: 'pt-br' }]) as never,
+          listing([{ source_lang: 'en', target_lang: 'pt-br' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['pt-pt'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['pt-pt'],
+          })
         ).rejects.toThrow('does not support the requested language pair');
       });
 
       it('should not let a regional dictionary source cover a different region', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'pt-br', target_lang: 'de' }]) as never,
+          listing([{ source_lang: 'pt-br', target_lang: 'de' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'pt-pt', targets: ['de'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'pt-pt',
+            targets: ['de'],
+          })
         ).rejects.toThrow('does not support the requested language pair');
       });
 
       it('should still match a regional dictionary asked for exactly', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'en', target_lang: 'pt-br' }]) as never,
+          listing([{ source_lang: 'en', target_lang: 'pt-br' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['pt-br'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['pt-br'],
+          })
         ).resolves.toBe('found-glossary-id');
       });
 
       it('should compare languages case-insensitively', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'EN', target_lang: 'ES' }]) as never,
+          listing([{ source_lang: 'EN', target_lang: 'ES' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['es'],
+          })
         ).resolves.toBe('found-glossary-id');
       });
 
@@ -500,7 +566,10 @@ describe('GlossaryService', () => {
         const uuid = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
 
         await expect(
-          glossaryService.resolveGlossaryId(uuid, { from: 'en', targets: ['de'] }),
+          glossaryService.resolveGlossaryId(uuid, {
+            from: 'en',
+            targets: ['de'],
+          })
         ).resolves.toBe(uuid);
         expect(mockDeepLClient.listGlossaries).not.toHaveBeenCalled();
       });
@@ -518,20 +587,29 @@ describe('GlossaryService', () => {
         ] as never);
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['de'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['de'],
+          })
         ).resolves.toBe('empty-glossary-id');
       });
 
       it('should not let a cached resolution skip the check for a different pair', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue(
-          listing([{ source_lang: 'en', target_lang: 'es' }]) as never,
+          listing([{ source_lang: 'en', target_lang: 'es' }]) as never
         );
 
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['es'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['es'],
+          })
         ).resolves.toBe('found-glossary-id');
         await expect(
-          glossaryService.resolveGlossaryId('tech-terms', { from: 'en', targets: ['de'] }),
+          glossaryService.resolveGlossaryId('tech-terms', {
+            from: 'en',
+            targets: ['de'],
+          })
         ).rejects.toThrow('does not support the requested language pair');
       });
     });
@@ -543,7 +621,9 @@ describe('GlossaryService', () => {
           name: 'tech-terms',
           source_lang: 'en',
           target_langs: ['es'],
-          dictionaries: [{ source_lang: 'en', target_lang: 'es', entry_count: 1 }],
+          dictionaries: [
+            { source_lang: 'en', target_lang: 'es', entry_count: 1 },
+          ],
           creation_time: '2024-01-01T00:00:00Z',
         },
       ]);
@@ -553,7 +633,9 @@ describe('GlossaryService', () => {
       await glossaryService.resolveGlossaryId('tech-terms');
 
       expect(spy).toHaveBeenCalledWith(
-        expect.stringContaining('Resolved glossary "tech-terms" -> resolved-glossary-id')
+        expect.stringContaining(
+          'Resolved glossary "tech-terms" -> resolved-glossary-id'
+        )
       );
       spy.mockRestore();
     });
@@ -564,7 +646,13 @@ describe('GlossaryService', () => {
         name: 'tech-terms',
         source_lang: 'en' as const,
         target_langs: ['es' as const],
-        dictionaries: [{ source_lang: 'en' as const, target_lang: 'es' as const, entry_count: 1 }],
+        dictionaries: [
+          {
+            source_lang: 'en' as const,
+            target_lang: 'es' as const,
+            entry_count: 1,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       };
 
@@ -591,7 +679,9 @@ describe('GlossaryService', () => {
         await glossaryService.resolveGlossaryId('tech-terms');
 
         expect(spy).toHaveBeenCalledWith(
-          expect.stringContaining('Glossary cache hit: "tech-terms" -> resolved-glossary-id'),
+          expect.stringContaining(
+            'Glossary cache hit: "tech-terms" -> resolved-glossary-id'
+          )
         );
         spy.mockRestore();
       });
@@ -637,7 +727,13 @@ describe('GlossaryService', () => {
         name: 'tech-terms',
         source_lang: 'en' as const,
         target_langs: ['es' as const],
-        dictionaries: [{ source_lang: 'en' as const, target_lang: 'es' as const, entry_count: 1 }],
+        dictionaries: [
+          {
+            source_lang: 'en' as const,
+            target_lang: 'es' as const,
+            entry_count: 1,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       };
 
@@ -688,7 +784,9 @@ describe('GlossaryService', () => {
         });
 
         await glossaryService.getGlossaryByName('tech-terms');
-        await glossaryService.createGlossary('brand-new', 'en', ['es'], { a: 'b' });
+        await glossaryService.createGlossary('brand-new', 'en', ['es'], {
+          a: 'b',
+        });
         await glossaryService.getGlossaryByName('tech-terms');
 
         expect(mockDeepLClient.listGlossaries).toHaveBeenCalledTimes(2);
@@ -701,27 +799,41 @@ describe('GlossaryService', () => {
         name: 'prod-gloss',
         source_lang: 'en' as const,
         target_langs: ['es' as const],
-        dictionaries: [{ source_lang: 'en' as const, target_lang: 'es' as const, entry_count: 1 }],
+        dictionaries: [
+          {
+            source_lang: 'en' as const,
+            target_lang: 'es' as const,
+            entry_count: 1,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       };
 
       it('treats a glossary whose name contains a zero-width space as non-existent (silent skip)', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue([
-          { ...cleanGlossary, glossary_id: 'poisoned-id', name: 'prod-gloss\u200B' },
+          {
+            ...cleanGlossary,
+            glossary_id: 'poisoned-id',
+            name: 'prod-gloss\u200B',
+          },
         ]);
 
         await expect(
-          glossaryService.resolveGlossaryId('prod-gloss\u200B'),
+          glossaryService.resolveGlossaryId('prod-gloss\u200B')
         ).rejects.toThrow(/not found/);
       });
 
       it('treats a glossary whose name contains an ASCII control char as non-existent (silent skip)', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue([
-          { ...cleanGlossary, glossary_id: 'poisoned-id', name: 'prod-gloss\x00' },
+          {
+            ...cleanGlossary,
+            glossary_id: 'poisoned-id',
+            name: 'prod-gloss\x00',
+          },
         ]);
 
         await expect(
-          glossaryService.resolveGlossaryId('prod-gloss\x00'),
+          glossaryService.resolveGlossaryId('prod-gloss\x00')
         ).rejects.toThrow(/not found/);
       });
 
@@ -766,7 +878,11 @@ describe('GlossaryService', () => {
       it('legit unambiguous name still resolves even when a filtered sibling exists', async () => {
         mockDeepLClient.listGlossaries.mockResolvedValue([
           { ...cleanGlossary, glossary_id: 'legit-id', name: 'prod-gloss' },
-          { ...cleanGlossary, glossary_id: 'poisoned-id', name: 'prod-gloss\x00' },
+          {
+            ...cleanGlossary,
+            glossary_id: 'poisoned-id',
+            name: 'prod-gloss\x00',
+          },
         ]);
 
         const resolved = await glossaryService.resolveGlossaryId('prod-gloss');
@@ -802,23 +918,39 @@ describe('GlossaryService', () => {
         'API\tAPI\nREST\tREST\nHello\tHola'
       );
 
-      const entries = await glossaryService.getGlossaryEntries('test-123', 'en', 'es');
+      const entries = await glossaryService.getGlossaryEntries(
+        'test-123',
+        'en',
+        'es'
+      );
 
       expect(entries).toEqual({
         API: 'API',
         REST: 'REST',
         Hello: 'Hola',
       });
-      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith('test-123', 'en', 'es');
+      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith(
+        'test-123',
+        'en',
+        'es'
+      );
     });
 
     it('should handle empty glossary', async () => {
       mockDeepLClient.getGlossaryEntries.mockResolvedValue('');
 
-      const entries = await glossaryService.getGlossaryEntries('test-123', 'en', 'es');
+      const entries = await glossaryService.getGlossaryEntries(
+        'test-123',
+        'en',
+        'es'
+      );
 
       expect(entries).toEqual({});
-      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith('test-123', 'en', 'es');
+      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith(
+        'test-123',
+        'en',
+        'es'
+      );
     });
   });
 
@@ -959,14 +1091,20 @@ describe('GlossaryService', () => {
   describe('addEntry()', () => {
     it('should add a new entry to glossary', async () => {
       // Mock getting existing entries
-      mockDeepLClient.getGlossaryEntries.mockResolvedValue('API\tAPI\nREST\tREST');
+      mockDeepLClient.getGlossaryEntries.mockResolvedValue(
+        'API\tAPI\nREST\tREST'
+      );
 
       // Mock updating glossary entries
       mockDeepLClient.updateGlossaryEntries.mockResolvedValue(undefined);
 
       await glossaryService.addEntry('test-123', 'en', 'es', 'Hello', 'Hola');
 
-      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith('test-123', 'en', 'es');
+      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith(
+        'test-123',
+        'en',
+        'es'
+      );
       expect(mockDeepLClient.updateGlossaryEntries).toHaveBeenCalledWith(
         'test-123',
         'en',
@@ -976,7 +1114,9 @@ describe('GlossaryService', () => {
     });
 
     it('should throw error if entry already exists', async () => {
-      mockDeepLClient.getGlossaryEntries.mockResolvedValue('API\tAPI\nREST\tREST');
+      mockDeepLClient.getGlossaryEntries.mockResolvedValue(
+        'API\tAPI\nREST\tREST'
+      );
 
       await expect(
         glossaryService.addEntry('test-123', 'en', 'es', 'API', 'Interface')
@@ -1021,12 +1161,24 @@ describe('GlossaryService', () => {
 
   describe('updateEntry()', () => {
     it('should update an existing entry', async () => {
-      mockDeepLClient.getGlossaryEntries.mockResolvedValue('API\tAPI\nREST\tREST');
+      mockDeepLClient.getGlossaryEntries.mockResolvedValue(
+        'API\tAPI\nREST\tREST'
+      );
       mockDeepLClient.updateGlossaryEntries.mockResolvedValue(undefined);
 
-      await glossaryService.updateEntry('test-123', 'en', 'es', 'API', 'Interface');
+      await glossaryService.updateEntry(
+        'test-123',
+        'en',
+        'es',
+        'API',
+        'Interface'
+      );
 
-      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith('test-123', 'en', 'es');
+      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith(
+        'test-123',
+        'en',
+        'es'
+      );
       expect(mockDeepLClient.updateGlossaryEntries).toHaveBeenCalledWith(
         'test-123',
         'en',
@@ -1036,10 +1188,18 @@ describe('GlossaryService', () => {
     });
 
     it('should throw error if entry does not exist', async () => {
-      mockDeepLClient.getGlossaryEntries.mockResolvedValue('API\tAPI\nREST\tREST');
+      mockDeepLClient.getGlossaryEntries.mockResolvedValue(
+        'API\tAPI\nREST\tREST'
+      );
 
       await expect(
-        glossaryService.updateEntry('test-123', 'en', 'es', 'NonExistent', 'target')
+        glossaryService.updateEntry(
+          'test-123',
+          'en',
+          'es',
+          'NonExistent',
+          'target'
+        )
       ).rejects.toThrow('Entry "NonExistent" not found in glossary');
     });
 
@@ -1059,7 +1219,13 @@ describe('GlossaryService', () => {
       mockDeepLClient.getGlossaryEntries.mockResolvedValue('API\tAPI');
 
       await expect(
-        glossaryService.updateEntry('test-123', 'en', 'es', 'API', 'Inter\tface')
+        glossaryService.updateEntry(
+          'test-123',
+          'en',
+          'es',
+          'API',
+          'Inter\tface'
+        )
       ).rejects.toThrow(/tab/i);
       expect(mockDeepLClient.updateGlossaryEntries).not.toHaveBeenCalled();
     });
@@ -1068,19 +1234,31 @@ describe('GlossaryService', () => {
       mockDeepLClient.getGlossaryEntries.mockResolvedValue('API\tAPI');
 
       await expect(
-        glossaryService.updateEntry('test-123', 'en', 'es', 'API', 'Inter\nface')
+        glossaryService.updateEntry(
+          'test-123',
+          'en',
+          'es',
+          'API',
+          'Inter\nface'
+        )
       ).rejects.toThrow(/newline/i);
     });
   });
 
   describe('removeEntry()', () => {
     it('should remove an entry from glossary', async () => {
-      mockDeepLClient.getGlossaryEntries.mockResolvedValue('API\tAPI\nREST\tREST\nHello\tHola');
+      mockDeepLClient.getGlossaryEntries.mockResolvedValue(
+        'API\tAPI\nREST\tREST\nHello\tHola'
+      );
       mockDeepLClient.updateGlossaryEntries.mockResolvedValue(undefined);
 
       await glossaryService.removeEntry('test-123', 'en', 'es', 'Hello');
 
-      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith('test-123', 'en', 'es');
+      expect(mockDeepLClient.getGlossaryEntries).toHaveBeenCalledWith(
+        'test-123',
+        'en',
+        'es'
+      );
       expect(mockDeepLClient.updateGlossaryEntries).toHaveBeenCalledWith(
         'test-123',
         'en',
@@ -1090,7 +1268,9 @@ describe('GlossaryService', () => {
     });
 
     it('should throw error if entry does not exist', async () => {
-      mockDeepLClient.getGlossaryEntries.mockResolvedValue('API\tAPI\nREST\tREST');
+      mockDeepLClient.getGlossaryEntries.mockResolvedValue(
+        'API\tAPI\nREST\tREST'
+      );
 
       await expect(
         glossaryService.removeEntry('test-123', 'en', 'es', 'NonExistent')
@@ -1108,7 +1288,9 @@ describe('GlossaryService', () => {
 
       await expect(
         glossaryService.removeEntry('test-123', 'en', 'es', 'API')
-      ).rejects.toThrow('Cannot remove last entry from glossary. Delete the glossary instead.');
+      ).rejects.toThrow(
+        'Cannot remove last entry from glossary. Delete the glossary instead.'
+      );
     });
   });
 
@@ -1119,11 +1301,13 @@ describe('GlossaryService', () => {
         name: 'old-name',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -1132,27 +1316,33 @@ describe('GlossaryService', () => {
       await glossaryService.updateGlossary('test-123', { name: 'new-name' });
 
       expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith('test-123');
-      expect(mockDeepLClient.updateGlossary).toHaveBeenCalledWith('test-123', { name: 'new-name' });
+      expect(mockDeepLClient.updateGlossary).toHaveBeenCalledWith('test-123', {
+        name: 'new-name',
+      });
     });
 
     it('should update dictionaries only', async () => {
       mockDeepLClient.updateGlossary.mockResolvedValue(undefined);
 
       await glossaryService.updateGlossary('test-123', {
-        dictionaries: [{
-          sourceLang: 'en',
-          targetLang: 'es',
-          entries: { Hello: 'Hola' },
-        }],
+        dictionaries: [
+          {
+            sourceLang: 'en',
+            targetLang: 'es',
+            entries: { Hello: 'Hola' },
+          },
+        ],
       });
 
       expect(mockDeepLClient.updateGlossary).toHaveBeenCalledWith('test-123', {
-        dictionaries: [{
-          source_lang: 'EN',
-          target_lang: 'ES',
-          entries: 'Hello\tHola',
-          entries_format: 'tsv',
-        }],
+        dictionaries: [
+          {
+            source_lang: 'EN',
+            target_lang: 'ES',
+            entries: 'Hello\tHola',
+            entries_format: 'tsv',
+          },
+        ],
       });
     });
 
@@ -1162,11 +1352,13 @@ describe('GlossaryService', () => {
         name: 'old-name',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -1174,28 +1366,34 @@ describe('GlossaryService', () => {
 
       await glossaryService.updateGlossary('test-123', {
         name: 'new-name',
-        dictionaries: [{
-          sourceLang: 'en',
-          targetLang: 'es',
-          entries: { Hello: 'Hola', World: 'Mundo' },
-        }],
+        dictionaries: [
+          {
+            sourceLang: 'en',
+            targetLang: 'es',
+            entries: { Hello: 'Hola', World: 'Mundo' },
+          },
+        ],
       });
 
       expect(mockDeepLClient.updateGlossary).toHaveBeenCalledWith('test-123', {
         name: 'new-name',
-        dictionaries: [{
-          source_lang: 'EN',
-          target_lang: 'ES',
-          entries: 'Hello\tHola\nWorld\tMundo',
-          entries_format: 'tsv',
-        }],
+        dictionaries: [
+          {
+            source_lang: 'EN',
+            target_lang: 'ES',
+            entries: 'Hello\tHola\nWorld\tMundo',
+            entries_format: 'tsv',
+          },
+        ],
       });
     });
 
     it('should throw when neither name nor dictionaries provided', async () => {
       await expect(
         glossaryService.updateGlossary('test-123', {})
-      ).rejects.toThrow('At least one of name or dictionaries must be provided');
+      ).rejects.toThrow(
+        'At least one of name or dictionaries must be provided'
+      );
     });
 
     it('should validate new name is not empty', async () => {
@@ -1210,11 +1408,13 @@ describe('GlossaryService', () => {
         name: 'same-name',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -1241,11 +1441,13 @@ describe('GlossaryService', () => {
         name: 'old-name',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -1254,7 +1456,9 @@ describe('GlossaryService', () => {
       await glossaryService.renameGlossary('test-123', 'new-name');
 
       expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith('test-123');
-      expect(mockDeepLClient.updateGlossary).toHaveBeenCalledWith('test-123', { name: 'new-name' });
+      expect(mockDeepLClient.updateGlossary).toHaveBeenCalledWith('test-123', {
+        name: 'new-name',
+      });
     });
 
     it('should validate new name is not empty', async () => {
@@ -1269,11 +1473,13 @@ describe('GlossaryService', () => {
         name: 'same-name',
         source_lang: 'en',
         target_langs: ['es'],
-        dictionaries: [{
-          source_lang: 'en',
-          target_lang: 'es',
-          entry_count: 3,
-        }],
+        dictionaries: [
+          {
+            source_lang: 'en',
+            target_lang: 'es',
+            entry_count: 3,
+          },
+        ],
         creation_time: '2024-01-01T00:00:00Z',
       });
 
@@ -1323,9 +1529,15 @@ describe('GlossaryService', () => {
 
       mockDeepLClient.deleteGlossaryDictionary.mockResolvedValue(undefined);
 
-      await glossaryService.deleteGlossaryDictionary('multi-gloss-123', 'en', 'fr');
+      await glossaryService.deleteGlossaryDictionary(
+        'multi-gloss-123',
+        'en',
+        'fr'
+      );
 
-      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith('multi-gloss-123');
+      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith(
+        'multi-gloss-123'
+      );
       expect(mockDeepLClient.deleteGlossaryDictionary).toHaveBeenCalledWith(
         'multi-gloss-123',
         'en',
@@ -1352,9 +1564,13 @@ describe('GlossaryService', () => {
 
       await expect(
         glossaryService.deleteGlossaryDictionary('single-gloss-123', 'en', 'es')
-      ).rejects.toThrow('Cannot delete dictionary from single-language glossary. Delete the entire glossary instead.');
+      ).rejects.toThrow(
+        'Cannot delete dictionary from single-language glossary. Delete the entire glossary instead.'
+      );
 
-      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith('single-gloss-123');
+      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith(
+        'single-gloss-123'
+      );
       expect(mockDeepLClient.deleteGlossaryDictionary).not.toHaveBeenCalled();
     });
 
@@ -1378,7 +1594,9 @@ describe('GlossaryService', () => {
 
       await expect(
         glossaryService.deleteGlossaryDictionary('last-dict-123', 'en', 'es')
-      ).rejects.toThrow('Cannot delete last dictionary from glossary. Delete the entire glossary instead.');
+      ).rejects.toThrow(
+        'Cannot delete last dictionary from glossary. Delete the entire glossary instead.'
+      );
 
       expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith('last-dict-123');
       expect(mockDeepLClient.deleteGlossaryDictionary).not.toHaveBeenCalled();
@@ -1410,7 +1628,9 @@ describe('GlossaryService', () => {
         glossaryService.deleteGlossaryDictionary('multi-gloss-123', 'en', 'de')
       ).rejects.toThrow('Dictionary en-de not found in glossary');
 
-      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith('multi-gloss-123');
+      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith(
+        'multi-gloss-123'
+      );
       expect(mockDeepLClient.deleteGlossaryDictionary).not.toHaveBeenCalled();
     });
 
@@ -1461,9 +1681,15 @@ describe('GlossaryService', () => {
       mockDeepLClient.deleteGlossaryDictionary.mockResolvedValue(undefined);
 
       // Request with lowercase codes should still match uppercase dictionary entries
-      await glossaryService.deleteGlossaryDictionary('multi-gloss-123', 'en', 'fr');
+      await glossaryService.deleteGlossaryDictionary(
+        'multi-gloss-123',
+        'en',
+        'fr'
+      );
 
-      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith('multi-gloss-123');
+      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith(
+        'multi-gloss-123'
+      );
       expect(mockDeepLClient.deleteGlossaryDictionary).toHaveBeenCalledWith(
         'multi-gloss-123',
         'en',
@@ -1514,7 +1740,9 @@ describe('GlossaryService', () => {
         glossaryService.deleteGlossaryDictionary('multi-gloss-123', 'en', 'fr')
       ).rejects.toThrow('Dictionary deletion failed');
 
-      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith('multi-gloss-123');
+      expect(mockDeepLClient.getGlossary).toHaveBeenCalledWith(
+        'multi-gloss-123'
+      );
       expect(mockDeepLClient.deleteGlossaryDictionary).toHaveBeenCalledWith(
         'multi-gloss-123',
         'en',
@@ -1528,23 +1756,39 @@ describe('GlossaryService', () => {
       mockDeepLClient.replaceGlossaryDictionary.mockResolvedValue(undefined);
 
       await glossaryService.replaceGlossaryDictionary(
-        'glossary-123', 'en', 'es', 'hello\thola\nworld\tmundo'
+        'glossary-123',
+        'en',
+        'es',
+        'hello\thola\nworld\tmundo'
       );
 
       expect(mockDeepLClient.replaceGlossaryDictionary).toHaveBeenCalledWith(
-        'glossary-123', 'en', 'es', 'hello\thola\nworld\tmundo'
+        'glossary-123',
+        'en',
+        'es',
+        'hello\thola\nworld\tmundo'
       );
     });
 
     it('should reject empty TSV content', async () => {
       await expect(
-        glossaryService.replaceGlossaryDictionary('glossary-123', 'en', 'es', '')
+        glossaryService.replaceGlossaryDictionary(
+          'glossary-123',
+          'en',
+          'es',
+          ''
+        )
       ).rejects.toThrow('No valid entries found');
     });
 
     it('should reject TSV with only invalid lines', async () => {
       await expect(
-        glossaryService.replaceGlossaryDictionary('glossary-123', 'en', 'es', 'invalid-no-tab')
+        glossaryService.replaceGlossaryDictionary(
+          'glossary-123',
+          'en',
+          'es',
+          'invalid-no-tab'
+        )
       ).rejects.toThrow('No valid entries found');
     });
 
@@ -1555,7 +1799,10 @@ describe('GlossaryService', () => {
 
       await expect(
         glossaryService.replaceGlossaryDictionary(
-          'glossary-123', 'en', 'es', 'hello\thola'
+          'glossary-123',
+          'en',
+          'es',
+          'hello\thola'
         )
       ).rejects.toThrow('API error');
     });
diff --git a/tests/unit/hermetic-deepl.test.ts b/tests/unit/hermetic-deepl.test.ts
index 1219dae7..00a96521 100644
--- a/tests/unit/hermetic-deepl.test.ts
+++ b/tests/unit/hermetic-deepl.test.ts
@@ -16,13 +16,15 @@ describe('hermetic deepl shim', () => {
       shell: '/bin/sh',
     }).trim();
 
-    expect(resolved).toBe(path.join(process.env['DEEPL_CLI_TEST_SHIM']!, 'deepl'));
+    expect(resolved).toBe(
+      path.join(process.env['DEEPL_CLI_TEST_SHIM']!, 'deepl')
+    );
   });
 
   it('executes the built CLI from this tree', () => {
     const version = execSync('deepl --version', { encoding: 'utf-8' }).trim();
     const pkg = JSON.parse(
-      fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'),
+      fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8')
     ) as { version: string };
 
     expect(version).toBe(pkg.version);
@@ -35,7 +37,7 @@ describe('hermetic deepl shim', () => {
       'does not carry %s in the inherited environment',
       (name) => {
         expect(process.env[name]).toBeUndefined();
-      },
+      }
     );
 
     it('points DEEPL_CONFIG_DIR at a temporary directory, not the real one', () => {
diff --git a/tests/unit/hooks-command.test.ts b/tests/unit/hooks-command.test.ts
index 86875e16..2340c2c2 100644
--- a/tests/unit/hooks-command.test.ts
+++ b/tests/unit/hooks-command.test.ts
@@ -40,9 +40,9 @@ describe('HooksCommand', () => {
     } as any;
 
     // Mock the constructor to return our mock service
-    (GitHooksService as jest.MockedClass<typeof GitHooksService>).mockImplementation(
-      () => mockGitHooksService
-    );
+    (
+      GitHooksService as jest.MockedClass<typeof GitHooksService>
+    ).mockImplementation(() => mockGitHooksService);
   });
 
   describe('constructor', () => {
@@ -95,7 +95,9 @@ describe('HooksCommand', () => {
 
       const result = command.install('pre-commit');
 
-      expect(result).toContain('backed up to: /path/to/.git/hooks/pre-commit.backup');
+      expect(result).toContain(
+        'backed up to: /path/to/.git/hooks/pre-commit.backup'
+      );
     });
 
     it('should install pre-push hook', () => {
@@ -233,18 +235,24 @@ describe('HooksCommand', () => {
 
   describe('showPath()', () => {
     it('should show pre-commit hook path', () => {
-      mockGitHooksService.getHookPath.mockReturnValue('/path/to/.git/hooks/pre-commit');
+      mockGitHooksService.getHookPath.mockReturnValue(
+        '/path/to/.git/hooks/pre-commit'
+      );
       const command = new HooksCommand('/path/to/.git');
 
       const result = command.showPath('pre-commit');
 
-      expect(mockGitHooksService.getHookPath).toHaveBeenCalledWith('pre-commit');
+      expect(mockGitHooksService.getHookPath).toHaveBeenCalledWith(
+        'pre-commit'
+      );
       expect(result).toContain('Hook path:');
       expect(result).toContain('/path/to/.git/hooks/pre-commit');
     });
 
     it('should show pre-push hook path', () => {
-      mockGitHooksService.getHookPath.mockReturnValue('/path/to/.git/hooks/pre-push');
+      mockGitHooksService.getHookPath.mockReturnValue(
+        '/path/to/.git/hooks/pre-push'
+      );
       const command = new HooksCommand('/path/to/.git');
 
       const result = command.showPath('pre-push');
@@ -260,7 +268,9 @@ describe('HooksCommand', () => {
 
       const command = new HooksCommand();
 
-      expect(() => command.showPath('pre-commit')).toThrow('Not in a git repository');
+      expect(() => command.showPath('pre-commit')).toThrow(
+        'Not in a git repository'
+      );
     });
 
     it('should propagate errors from GitHooksService', () => {
@@ -269,7 +279,9 @@ describe('HooksCommand', () => {
       });
       const command = new HooksCommand('/path/to/.git');
 
-      expect(() => command.showPath('pre-commit' as any)).toThrow('Invalid hook type');
+      expect(() => command.showPath('pre-commit' as any)).toThrow(
+        'Invalid hook type'
+      );
     });
   });
 
diff --git a/tests/unit/http-client.test.ts b/tests/unit/http-client.test.ts
index b00c2592..bd37ce03 100644
--- a/tests/unit/http-client.test.ts
+++ b/tests/unit/http-client.test.ts
@@ -21,7 +21,12 @@ describe('HttpClient', () => {
   beforeEach(() => {
     jest.useFakeTimers({ advanceTimers: true });
     client = new TestHttpClient(apiKey, { maxRetries: 3 });
-    sleepSpy = jest.spyOn(client as unknown as { sleep: (ms: number) => Promise<void> }, 'sleep').mockResolvedValue();
+    sleepSpy = jest
+      .spyOn(
+        client as unknown as { sleep: (ms: number) => Promise<void> },
+        'sleep'
+      )
+      .mockResolvedValue();
     nock.cleanAll();
   });
 
@@ -48,7 +53,9 @@ describe('HttpClient', () => {
     });
 
     it('should return undefined for invalid Retry-After value', () => {
-      expect(client.callParseRetryAfter('not-a-number-or-date')).toBeUndefined();
+      expect(
+        client.callParseRetryAfter('not-a-number-or-date')
+      ).toBeUndefined();
     });
 
     it('should parse HTTP date format Retry-After', () => {
@@ -79,9 +86,7 @@ describe('HttpClient', () => {
       nock(baseUrl)
         .get('/v2/test')
         .reply(429, { message: 'Too many requests' }, { 'Retry-After': '5' });
-      nock(baseUrl)
-        .get('/v2/test')
-        .reply(200, { result: 'ok' });
+      nock(baseUrl).get('/v2/test').reply(200, { result: 'ok' });
 
       const result = await client.get<{ result: string }>('/v2/test');
 
@@ -94,9 +99,7 @@ describe('HttpClient', () => {
       nock(baseUrl)
         .get('/v2/test')
         .reply(429, { message: 'Too many requests' }, { 'Retry-After': '0' });
-      nock(baseUrl)
-        .get('/v2/test')
-        .reply(200, { result: 'ok' });
+      nock(baseUrl).get('/v2/test').reply(200, { result: 'ok' });
 
       const result = await client.get<{ result: string }>('/v2/test');
 
@@ -109,9 +112,7 @@ describe('HttpClient', () => {
       nock(baseUrl)
         .get('/v2/test')
         .reply(429, { message: 'Too many requests' });
-      nock(baseUrl)
-        .get('/v2/test')
-        .reply(200, { result: 'ok' });
+      nock(baseUrl).get('/v2/test').reply(200, { result: 'ok' });
 
       const result = await client.get<{ result: string }>('/v2/test');
 
@@ -127,9 +128,7 @@ describe('HttpClient', () => {
       nock(baseUrl)
         .get('/v2/test')
         .reply(429, { message: 'Too many requests' }, { 'Retry-After': '300' });
-      nock(baseUrl)
-        .get('/v2/test')
-        .reply(200, { result: 'ok' });
+      nock(baseUrl).get('/v2/test').reply(200, { result: 'ok' });
 
       const result = await client.get<{ result: string }>('/v2/test');
 
@@ -141,10 +140,12 @@ describe('HttpClient', () => {
     it('should fall back to jittered exponential backoff on invalid Retry-After', async () => {
       nock(baseUrl)
         .get('/v2/test')
-        .reply(429, { message: 'Too many requests' }, { 'Retry-After': 'garbage' });
-      nock(baseUrl)
-        .get('/v2/test')
-        .reply(200, { result: 'ok' });
+        .reply(
+          429,
+          { message: 'Too many requests' },
+          { 'Retry-After': 'garbage' }
+        );
+      nock(baseUrl).get('/v2/test').reply(200, { result: 'ok' });
 
       const result = await client.get<{ result: string }>('/v2/test');
 
@@ -159,10 +160,12 @@ describe('HttpClient', () => {
       const futureDate = new Date(Date.now() + 10000);
       nock(baseUrl)
         .get('/v2/test')
-        .reply(429, { message: 'Too many requests' }, { 'Retry-After': futureDate.toUTCString() });
-      nock(baseUrl)
-        .get('/v2/test')
-        .reply(200, { result: 'ok' });
+        .reply(
+          429,
+          { message: 'Too many requests' },
+          { 'Retry-After': futureDate.toUTCString() }
+        );
+      nock(baseUrl).get('/v2/test').reply(200, { result: 'ok' });
 
       const result = await client.get<{ result: string }>('/v2/test');
 
@@ -183,9 +186,7 @@ describe('HttpClient', () => {
       nock(baseUrl)
         .get('/v2/test')
         .reply(429, { message: 'Too many requests' });
-      nock(baseUrl)
-        .get('/v2/test')
-        .reply(200, { result: 'ok' });
+      nock(baseUrl).get('/v2/test').reply(200, { result: 'ok' });
 
       const result = await client.get<{ result: string }>('/v2/test');
 
@@ -215,11 +216,11 @@ describe('HttpClient', () => {
     });
 
     it('should still throw immediately on other 4xx errors', async () => {
-      nock(baseUrl)
-        .get('/v2/test')
-        .reply(403, { message: 'Forbidden' });
+      nock(baseUrl).get('/v2/test').reply(403, { message: 'Forbidden' });
 
-      await expect(client.get('/v2/test')).rejects.toThrow('Authentication failed');
+      await expect(client.get('/v2/test')).rejects.toThrow(
+        'Authentication failed'
+      );
       expect(sleepSpy).not.toHaveBeenCalled();
     });
   });
@@ -241,7 +242,9 @@ describe('HttpClient', () => {
         .times(4)
         .reply(500, { message: 'Internal Server Error' });
 
-      await expect(client.get('/v2/test')).rejects.toThrow(/Server error \(500\)/);
+      await expect(client.get('/v2/test')).rejects.toThrow(
+        /Server error \(500\)/
+      );
     });
   });
 
@@ -287,17 +290,28 @@ describe('HttpClient', () => {
         fail('Expected error');
       } catch (error) {
         expect(error).toBeInstanceOf(NetworkError);
-        expect((error as Error).message).toContain('Service temporarily unavailable');
+        expect((error as Error).message).toContain(
+          'Service temporarily unavailable'
+        );
       }
     });
   });
 
   describe('NO_PROXY', () => {
-    const PROXY_VARS = ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy', 'NO_PROXY', 'no_proxy'];
+    const PROXY_VARS = [
+      'HTTP_PROXY',
+      'http_proxy',
+      'HTTPS_PROXY',
+      'https_proxy',
+      'NO_PROXY',
+      'no_proxy',
+    ];
     let saved: Record<string, string | undefined>;
 
     beforeEach(() => {
-      saved = Object.fromEntries(PROXY_VARS.map((name) => [name, process.env[name]]));
+      saved = Object.fromEntries(
+        PROXY_VARS.map((name) => [name, process.env[name]])
+      );
       PROXY_VARS.forEach((name) => delete process.env[name]);
       process.env['HTTPS_PROXY'] = 'http://proxy.example.com:8080';
     });
@@ -314,14 +328,17 @@ describe('HttpClient', () => {
 
     function proxyFor(baseUrl: string): unknown {
       const instance = new TestHttpClient(apiKey, { baseUrl });
-      return (instance as unknown as { client: { defaults: { proxy?: unknown } } }).client.defaults
-        .proxy;
+      return (
+        instance as unknown as { client: { defaults: { proxy?: unknown } } }
+      ).client.defaults.proxy;
     }
 
     it('uses the proxy when NO_PROXY does not match', () => {
       process.env['NO_PROXY'] = 'example.org';
 
-      expect(proxyFor('https://api.deepl.com')).toMatchObject({ host: 'proxy.example.com' });
+      expect(proxyFor('https://api.deepl.com')).toMatchObject({
+        host: 'proxy.example.com',
+      });
     });
 
     it.each([
@@ -330,7 +347,11 @@ describe('HttpClient', () => {
       ['leading dot subdomain', '.deepl.com', 'https://api.deepl.com'],
       ['star-dot subdomain', '*.deepl.com', 'https://api.deepl.com'],
       ['host with matching port', 'localhost:8080', 'http://localhost:8080'],
-      ['entry among several', 'foo.test,api.deepl.com,bar.test', 'https://api.deepl.com'],
+      [
+        'entry among several',
+        'foo.test,api.deepl.com,bar.test',
+        'https://api.deepl.com',
+      ],
       ['case-insensitive', 'API.DeepL.com', 'https://api.deepl.com'],
     ])('bypasses the proxy for %s', (_label, noProxy, target) => {
       process.env['NO_PROXY'] = noProxy;
@@ -341,7 +362,9 @@ describe('HttpClient', () => {
     it('does not bypass when only the port differs', () => {
       process.env['NO_PROXY'] = 'localhost:9999';
 
-      expect(proxyFor('http://localhost:8080')).toMatchObject({ host: 'proxy.example.com' });
+      expect(proxyFor('http://localhost:8080')).toMatchObject({
+        host: 'proxy.example.com',
+      });
     });
 
     it('honours the lowercase no_proxy spelling', () => {
diff --git a/tests/unit/http-retry-policy.test.ts b/tests/unit/http-retry-policy.test.ts
index f9daf055..c708123f 100644
--- a/tests/unit/http-retry-policy.test.ts
+++ b/tests/unit/http-retry-policy.test.ts
@@ -53,7 +53,10 @@ describe('HttpClient retry policy', () => {
       ...options,
     });
     sleepSpy = jest
-      .spyOn(client as unknown as { sleep: (ms: number) => Promise<void> }, 'sleep')
+      .spyOn(
+        client as unknown as { sleep: (ms: number) => Promise<void> },
+        'sleep'
+      )
       .mockResolvedValue();
     clients.push(client);
     return client;
@@ -99,9 +102,9 @@ describe('HttpClient retry policy', () => {
         .reply(200, { translations: [{ text: 'Hola' }] });
       const requests = countRequests(scope);
 
-      await expect(makeClient().post('/v2/translate', { text: 'Hello' })).rejects.toThrow(
-        NetworkError
-      );
+      await expect(
+        makeClient().post('/v2/translate', { text: 'Hello' })
+      ).rejects.toThrow(NetworkError);
 
       expect(requests()).toBe(1);
     });
@@ -142,9 +145,9 @@ describe('HttpClient retry policy', () => {
         .reply(200, {});
       const requests = countRequests(scope);
 
-      await expect(makeClient().put('/v3/glossaries/g-1', { name: 'x' })).rejects.toThrow(
-        NetworkError
-      );
+      await expect(
+        makeClient().put('/v3/glossaries/g-1', { name: 'x' })
+      ).rejects.toThrow(NetworkError);
 
       expect(requests()).toBe(4);
     });
@@ -152,7 +155,10 @@ describe('HttpClient retry policy', () => {
 
   describe('server errors', () => {
     it('retries a 500 on an idempotent GET', async () => {
-      const scope = nock(BASE_URL).get('/v2/usage').times(4).reply(500, { message: 'boom' });
+      const scope = nock(BASE_URL)
+        .get('/v2/usage')
+        .times(4)
+        .reply(500, { message: 'boom' });
       const requests = countRequests(scope);
 
       await expect(makeClient().get('/v2/usage')).rejects.toThrow(NetworkError);
@@ -167,9 +173,9 @@ describe('HttpClient retry policy', () => {
         .reply(500, { message: 'boom' });
       const requests = countRequests(scope);
 
-      await expect(makeClient().post('/v2/translate', { text: 'Hello' })).rejects.toThrow(
-        /Server error \(500\)/
-      );
+      await expect(
+        makeClient().post('/v2/translate', { text: 'Hello' })
+      ).rejects.toThrow(/Server error \(500\)/);
 
       expect(requests()).toBe(1);
     });
@@ -181,9 +187,9 @@ describe('HttpClient retry policy', () => {
         .reply(503, { message: 'Service Unavailable' });
       const requests = countRequests(scope);
 
-      await expect(makeClient().post('/v2/translate', { text: 'Hello' })).rejects.toThrow(
-        /Service temporarily unavailable/
-      );
+      await expect(
+        makeClient().post('/v2/translate', { text: 'Hello' })
+      ).rejects.toThrow(/Service temporarily unavailable/);
 
       expect(requests()).toBe(1);
     });
@@ -221,9 +227,9 @@ describe('HttpClient retry policy', () => {
         .reply(429, { message: 'Too many requests' });
       const requests = countRequests(scope);
 
-      await expect(makeClient().post('/v2/translate', { text: 'Hello' })).rejects.toThrow(
-        RateLimitError
-      );
+      await expect(
+        makeClient().post('/v2/translate', { text: 'Hello' })
+      ).rejects.toThrow(RateLimitError);
 
       expect(requests()).toBe(4);
     });
@@ -231,7 +237,10 @@ describe('HttpClient retry policy', () => {
 
   describe('401 handling', () => {
     it('maps 401 to AuthError without retrying', async () => {
-      const scope = nock(BASE_URL).get('/v2/usage').times(4).reply(401, { message: 'Unauthorized' });
+      const scope = nock(BASE_URL)
+        .get('/v2/usage')
+        .times(4)
+        .reply(401, { message: 'Unauthorized' });
       const requests = countRequests(scope);
 
       const error = await makeClient()
@@ -253,7 +262,11 @@ describe('HttpClient retry policy', () => {
         .reply(200, {});
       const requests = countRequests(scope);
 
-      const client = makeClient({ timeout: 200, maxRetries: 5, totalTimeout: 500 });
+      const client = makeClient({
+        timeout: 200,
+        maxRetries: 5,
+        totalTimeout: 500,
+      });
       const start = Date.now();
       await expect(client.get('/v2/usage')).rejects.toThrow(NetworkError);
       const elapsed = Date.now() - start;
@@ -272,7 +285,11 @@ describe('HttpClient retry policy', () => {
         .reply(200, {});
       const requests = countRequests(scope);
 
-      const client = makeClient({ timeout: 200, maxRetries: 5, totalTimeout: undefined });
+      const client = makeClient({
+        timeout: 200,
+        maxRetries: 5,
+        totalTimeout: undefined,
+      });
       await expect(client.get('/v2/usage')).rejects.toThrow(NetworkError);
 
       // Default budget is twice the timeout, so far short of six attempts.
@@ -286,12 +303,14 @@ describe('HttpClient retry policy', () => {
       const scope = nock(BASE_URL)
         .post('/v2/translate')
         .times(4)
-        .replyWithError(transportError('ECONNREFUSED', 'connect ECONNREFUSED 127.0.0.1:443'));
+        .replyWithError(
+          transportError('ECONNREFUSED', 'connect ECONNREFUSED 127.0.0.1:443')
+        );
       const requests = countRequests(scope);
 
-      await expect(makeClient().post('/v2/translate', { text: 'Hello' })).rejects.toThrow(
-        NetworkError
-      );
+      await expect(
+        makeClient().post('/v2/translate', { text: 'Hello' })
+      ).rejects.toThrow(NetworkError);
 
       expect(requests()).toBe(4);
     });
@@ -300,12 +319,17 @@ describe('HttpClient retry policy', () => {
       const scope = nock(BASE_URL)
         .post('/v2/translate')
         .times(4)
-        .replyWithError(transportError('ENOTFOUND', 'getaddrinfo ENOTFOUND api-free.deepl.com'));
+        .replyWithError(
+          transportError(
+            'ENOTFOUND',
+            'getaddrinfo ENOTFOUND api-free.deepl.com'
+          )
+        );
       const requests = countRequests(scope);
 
-      await expect(makeClient().post('/v2/translate', { text: 'Hello' })).rejects.toThrow(
-        NetworkError
-      );
+      await expect(
+        makeClient().post('/v2/translate', { text: 'Hello' })
+      ).rejects.toThrow(NetworkError);
 
       expect(requests()).toBe(4);
     });
@@ -317,9 +341,9 @@ describe('HttpClient retry policy', () => {
         .replyWithError(transportError('ECONNRESET', 'socket hang up'));
       const requests = countRequests(scope);
 
-      await expect(makeClient().post('/v2/translate', { text: 'Hello' })).rejects.toThrow(
-        NetworkError
-      );
+      await expect(
+        makeClient().post('/v2/translate', { text: 'Hello' })
+      ).rejects.toThrow(NetworkError);
 
       expect(requests()).toBe(1);
     });
@@ -333,11 +357,15 @@ describe('HttpClient retry policy', () => {
         .post('/v2/translate', { text: 'Hello' })
         .catch((e: unknown) => e);
 
-      expect((error as Error).message).not.toMatch(/Network error: Network error/);
+      expect((error as Error).message).not.toMatch(
+        /Network error: Network error/
+      );
     });
 
     it('leaves an already-classified error untouched', () => {
-      const classified = new ValidationError('API error: Tone is not supported');
+      const classified = new ValidationError(
+        'API error: Tone is not supported'
+      );
 
       expect(makeClient().classify(classified)).toBe(classified);
     });
diff --git a/tests/unit/icu-surrounding-text.test.ts b/tests/unit/icu-surrounding-text.test.ts
index 0f086daf..e9451457 100644
--- a/tests/unit/icu-surrounding-text.test.ts
+++ b/tests/unit/icu-surrounding-text.test.ts
@@ -14,7 +14,8 @@
 import { parseIcu } from '../../src/utils/icu-preservation';
 
 describe('ICU with surrounding text', () => {
-  const LEADING = 'You have {count, plural, one {# item} other {# items}} in your cart.';
+  const LEADING =
+    'You have {count, plural, one {# item} other {# items}} in your cart.';
 
   it('should recognise a message with leading text as ICU', () => {
     expect(parseIcu(LEADING).isIcu).toBe(true);
@@ -66,7 +67,9 @@ describe('ICU with surrounding text', () => {
     const result = parseIcu(trailing);
 
     expect(result.isIcu).toBe(true);
-    expect(result.reassemble(result.segments.map((s) => s.text))).toBe(trailing);
+    expect(result.reassemble(result.segments.map((s) => s.text))).toBe(
+      trailing
+    );
   });
 
   it('should not treat an ordinary string as ICU', () => {
diff --git a/tests/unit/init-command.test.ts b/tests/unit/init-command.test.ts
index a0d1b381..0cbae434 100644
--- a/tests/unit/init-command.test.ts
+++ b/tests/unit/init-command.test.ts
@@ -24,7 +24,10 @@ describe('InitCommand', () => {
   const baseUrl = 'https://api.deepl.com';
 
   beforeEach(() => {
-    testConfigDir = path.join(os.tmpdir(), `.deepl-cli-test-init-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    testConfigDir = path.join(
+      os.tmpdir(),
+      `.deepl-cli-test-init-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
     fs.mkdirSync(testConfigDir, { recursive: true });
     const configPath = path.join(testConfigDir, 'config.json');
     configService = new ConfigService(configPath);
@@ -89,9 +92,7 @@ describe('InitCommand', () => {
   it('should throw on invalid API key', async () => {
     mockPassword.mockResolvedValueOnce('bad-key');
 
-    nock(baseUrl)
-      .get('/v2/usage')
-      .reply(403, { message: 'Forbidden' });
+    nock(baseUrl).get('/v2/usage').reply(403, { message: 'Forbidden' });
 
     const { InitCommand } = await import('../../src/cli/commands/init');
     const cmd = new InitCommand(configService);
diff --git a/tests/unit/language-registry.test.ts b/tests/unit/language-registry.test.ts
index 08c14295..9e60e864 100644
--- a/tests/unit/language-registry.test.ts
+++ b/tests/unit/language-registry.test.ts
@@ -10,7 +10,10 @@ import {
   deriveLanguageEntry,
   looksLikeLanguageTag,
 } from '../../src/data/language-registry';
-import { ENTRIES, WRITE_TARGET_LANGUAGES } from '../../src/data/language-entries';
+import {
+  ENTRIES,
+  WRITE_TARGET_LANGUAGES,
+} from '../../src/data/language-entries';
 import type { Language } from '../../src/types/common';
 
 /**
@@ -25,7 +28,8 @@ import type { Language } from '../../src/types/common';
  * lost most of its languages.
  */
 const TIERS = ['core', 'regional', 'extended'] as const;
-const entriesIn = (category: string) => ENTRIES.filter(e => e.category === category);
+const entriesIn = (category: string) =>
+  ENTRIES.filter((e) => e.category === category);
 
 /** Floors chosen well under today's 125/32/11/82 and well over an empty file. */
 const MIN_TOTAL = 100;
@@ -47,14 +51,30 @@ describe('Language Registry', () => {
       expect(LANGUAGE_REGISTRY.size).toBeGreaterThanOrEqual(MIN_TOTAL);
     });
 
-    it.each(TIERS)('should hold a plausible number of %s languages', category => {
-      expect(entriesIn(category).length).toBeGreaterThanOrEqual(MIN_PER_TIER[category]);
-    });
+    it.each(TIERS)(
+      'should hold a plausible number of %s languages',
+      (category) => {
+        expect(entriesIn(category).length).toBeGreaterThanOrEqual(
+          MIN_PER_TIER[category]
+        );
+      }
+    );
 
     it('should still contain a representative language from every tier', () => {
       // Named codes, so losing a whole tier or a common language is caught even
       // if the totals stay plausible.
-      for (const code of ['en', 'de', 'ja', 'zh', 'en-gb', 'pt-br', 'zh-hans', 'hi', 'sw', 'th']) {
+      for (const code of [
+        'en',
+        'de',
+        'ja',
+        'zh',
+        'en-gb',
+        'pt-br',
+        'zh-hans',
+        'hi',
+        'sw',
+        'th',
+      ]) {
         expect(LANGUAGE_REGISTRY.has(code)).toBe(true);
       }
     });
@@ -65,38 +85,43 @@ describe('Language Registry', () => {
       expect(unique.size).toBe(codes.length);
     });
 
-    it.each(TIERS)('should contain every %s language from the snapshot', category => {
-      const inRegistry = Array.from(LANGUAGE_REGISTRY.values()).filter(
-        e => e.category === category,
-      );
-      expect(inRegistry.length).toBe(entriesIn(category).length);
-      expect(inRegistry.length).toBeGreaterThan(0);
-    });
+    it.each(TIERS)(
+      'should contain every %s language from the snapshot',
+      (category) => {
+        const inRegistry = Array.from(LANGUAGE_REGISTRY.values()).filter(
+          (e) => e.category === category
+        );
+        expect(inRegistry.length).toBe(entriesIn(category).length);
+        expect(inRegistry.length).toBeGreaterThan(0);
+      }
+    );
 
     it('should place every entry in exactly one known tier', () => {
-      expect(TIERS.map(entriesIn).reduce((sum, group) => sum + group.length, 0)).toBe(
-        ENTRIES.length,
-      );
+      expect(
+        TIERS.map(entriesIn).reduce((sum, group) => sum + group.length, 0)
+      ).toBe(ENTRIES.length);
     });
 
-
-
     it('should mark regional variants as targetOnly', () => {
-      const regional = Array.from(LANGUAGE_REGISTRY.values()).filter(e => e.category === 'regional');
-      regional.forEach(entry => {
+      const regional = Array.from(LANGUAGE_REGISTRY.values()).filter(
+        (e) => e.category === 'regional'
+      );
+      regional.forEach((entry) => {
         expect(entry.targetOnly).toBe(true);
       });
     });
 
     it('should not mark core or extended languages as targetOnly', () => {
-      const nonRegional = Array.from(LANGUAGE_REGISTRY.values()).filter(e => e.category !== 'regional');
-      nonRegional.forEach(entry => {
+      const nonRegional = Array.from(LANGUAGE_REGISTRY.values()).filter(
+        (e) => e.category !== 'regional'
+      );
+      nonRegional.forEach((entry) => {
         expect(entry.targetOnly).toBeUndefined();
       });
     });
 
     it('should have non-empty names for all entries', () => {
-      LANGUAGE_REGISTRY.forEach(entry => {
+      LANGUAGE_REGISTRY.forEach((entry) => {
         expect(entry.name.length).toBeGreaterThan(0);
       });
     });
@@ -110,24 +135,64 @@ describe('Language Registry', () => {
 
   describe('specific language entries', () => {
     it('should include known core languages', () => {
-      expect(LANGUAGE_REGISTRY.get('en')).toEqual({ code: 'en', name: 'English', category: 'core' });
-      expect(LANGUAGE_REGISTRY.get('de')).toEqual({ code: 'de', name: 'German', category: 'core' });
-      expect(LANGUAGE_REGISTRY.get('ja')).toEqual({ code: 'ja', name: 'Japanese', category: 'core' });
+      expect(LANGUAGE_REGISTRY.get('en')).toEqual({
+        code: 'en',
+        name: 'English',
+        category: 'core',
+      });
+      expect(LANGUAGE_REGISTRY.get('de')).toEqual({
+        code: 'de',
+        name: 'German',
+        category: 'core',
+      });
+      expect(LANGUAGE_REGISTRY.get('ja')).toEqual({
+        code: 'ja',
+        name: 'Japanese',
+        category: 'core',
+      });
     });
 
     it('should include known regional variants', () => {
-      expect(LANGUAGE_REGISTRY.get('en-gb')).toEqual({ code: 'en-gb', name: 'English (British)', category: 'regional', targetOnly: true });
-      expect(LANGUAGE_REGISTRY.get('pt-br')).toEqual({ code: 'pt-br', name: 'Portuguese (Brazilian)', category: 'regional', targetOnly: true });
+      expect(LANGUAGE_REGISTRY.get('en-gb')).toEqual({
+        code: 'en-gb',
+        name: 'English (British)',
+        category: 'regional',
+        targetOnly: true,
+      });
+      expect(LANGUAGE_REGISTRY.get('pt-br')).toEqual({
+        code: 'pt-br',
+        name: 'Portuguese (Brazilian)',
+        category: 'regional',
+        targetOnly: true,
+      });
     });
 
     it('should include known extended languages', () => {
-      expect(LANGUAGE_REGISTRY.get('hi')).toEqual({ code: 'hi', name: 'Hindi', category: 'extended' });
-      expect(LANGUAGE_REGISTRY.get('sw')).toEqual({ code: 'sw', name: 'Swahili', category: 'extended' });
+      expect(LANGUAGE_REGISTRY.get('hi')).toEqual({
+        code: 'hi',
+        name: 'Hindi',
+        category: 'extended',
+      });
+      expect(LANGUAGE_REGISTRY.get('sw')).toEqual({
+        code: 'sw',
+        name: 'Swahili',
+        category: 'extended',
+      });
     });
 
     it('should include the regional variants of German and French', () => {
-      expect(LANGUAGE_REGISTRY.get('de-ch')).toEqual({ code: 'de-ch', name: 'German (Swiss)', category: 'regional', targetOnly: true });
-      expect(LANGUAGE_REGISTRY.get('fr-ca')).toEqual({ code: 'fr-ca', name: 'French (Canadian)', category: 'regional', targetOnly: true });
+      expect(LANGUAGE_REGISTRY.get('de-ch')).toEqual({
+        code: 'de-ch',
+        name: 'German (Swiss)',
+        category: 'regional',
+        targetOnly: true,
+      });
+      expect(LANGUAGE_REGISTRY.get('fr-ca')).toEqual({
+        code: 'fr-ca',
+        name: 'French (Canadian)',
+        category: 'regional',
+        targetOnly: true,
+      });
     });
 
     it('should carry the API name even where it duplicates a bare code', () => {
@@ -204,7 +269,7 @@ describe('Language Registry', () => {
   describe('getSourceLanguages()', () => {
     it('should exclude target-only languages', () => {
       const sources = getSourceLanguages();
-      const codes = sources.map(e => e.code);
+      const codes = sources.map((e) => e.code);
       expect(codes).not.toContain('en-gb');
       expect(codes).not.toContain('en-us');
       expect(codes).not.toContain('pt-br');
@@ -213,7 +278,7 @@ describe('Language Registry', () => {
 
     it('should include core and extended languages', () => {
       const sources = getSourceLanguages();
-      const codes = sources.map(e => e.code);
+      const codes = sources.map((e) => e.code);
       expect(codes).toContain('en');
       expect(codes).toContain('de');
       expect(codes).toContain('hi');
@@ -221,7 +286,9 @@ describe('Language Registry', () => {
     });
 
     it('should return every language that is not target-only', () => {
-      const targetOnly = ENTRIES.filter(e => 'targetOnly' in e && e.targetOnly).length;
+      const targetOnly = ENTRIES.filter(
+        (e) => 'targetOnly' in e && e.targetOnly
+      ).length;
       expect(getSourceLanguages().length).toBe(ENTRIES.length - targetOnly);
       expect(targetOnly).toBeGreaterThan(0);
     });
@@ -234,7 +301,7 @@ describe('Language Registry', () => {
 
     it('should include regional variants', () => {
       const targets = getTargetLanguages();
-      const codes = targets.map(e => e.code);
+      const codes = targets.map((e) => e.code);
       expect(codes).toContain('en-gb');
       expect(codes).toContain('en-us');
       expect(codes).toContain('pt-br');
@@ -264,7 +331,7 @@ describe('Language Registry', () => {
 
     it('should only contain extended language codes', () => {
       const codes = getExtendedLanguageCodes();
-      codes.forEach(code => {
+      codes.forEach((code) => {
         const entry = LANGUAGE_REGISTRY.get(code);
         expect(entry?.category).toBe('extended');
       });
@@ -284,12 +351,16 @@ describe('Language Registry', () => {
 
     it('should be lowercase and sorted, matching how the generator emits it', () => {
       const codes = [...WRITE_TARGET_LANGUAGES];
-      expect(codes).toEqual(codes.map(c => c.toLowerCase()));
-      expect(codes).toEqual([...codes].sort((a, b) => a.localeCompare(b, 'en')));
+      expect(codes).toEqual(codes.map((c) => c.toLowerCase()));
+      expect(codes).toEqual(
+        [...codes].sort((a, b) => a.localeCompare(b, 'en'))
+      );
     });
 
     it('should have no duplicates', () => {
-      expect(new Set(WRITE_TARGET_LANGUAGES).size).toBe(WRITE_TARGET_LANGUAGES.length);
+      expect(new Set(WRITE_TARGET_LANGUAGES).size).toBe(
+        WRITE_TARGET_LANGUAGES.length
+      );
     });
 
     it('should only contain languages the translate snapshot also knows', () => {
@@ -301,7 +372,7 @@ describe('Language Registry', () => {
     });
 
     it('should be a subset of the target languages', () => {
-      const targets = new Set(getTargetLanguages().map(e => e.code));
+      const targets = new Set(getTargetLanguages().map((e) => e.code));
       for (const code of WRITE_TARGET_LANGUAGES) {
         expect(targets.has(code)).toBe(true);
       }
@@ -318,7 +389,7 @@ describe('Language Registry', () => {
           name: 'German',
           usable_as_source: true,
           features: { glossary: stable, formality: stable },
-        }),
+        })
       ).toEqual({ code: 'de', name: 'German', category: 'core' });
     });
 
@@ -329,8 +400,13 @@ describe('Language Registry', () => {
           name: 'German (Swiss)',
           usable_as_source: false,
           features: { glossary: stable, formality: stable },
-        }),
-      ).toEqual({ code: 'de-ch', name: 'German (Swiss)', category: 'regional', targetOnly: true });
+        })
+      ).toEqual({
+        code: 'de-ch',
+        name: 'German (Swiss)',
+        category: 'regional',
+        targetOnly: true,
+      });
     });
 
     it('should classify a language without glossary support as extended', () => {
@@ -340,7 +416,7 @@ describe('Language Registry', () => {
           name: 'Hindi',
           usable_as_source: true,
           features: { tag_handling: stable },
-        }),
+        })
       ).toEqual({ code: 'hi', name: 'Hindi', category: 'extended' });
     });
 
@@ -353,7 +429,7 @@ describe('Language Registry', () => {
           name: 'Hindi',
           usable_as_source: true,
           features: {},
-        }).category,
+        }).category
       ).toBe('extended');
     });
 
@@ -363,23 +439,41 @@ describe('Language Registry', () => {
       // Tiering it by source usability instead leaves the judgement to the API,
       // which is the same choice the --features table makes.
       expect(
-        deriveLanguageEntry({ lang: 'xx', name: 'Test', usable_as_source: true }).category,
+        deriveLanguageEntry({
+          lang: 'xx',
+          name: 'Test',
+          usable_as_source: true,
+        }).category
       ).toBe('core');
       expect(
-        deriveLanguageEntry({ lang: 'xx', name: 'Test', usable_as_source: false }).category,
+        deriveLanguageEntry({
+          lang: 'xx',
+          name: 'Test',
+          usable_as_source: false,
+        }).category
       ).toBe('regional');
     });
 
     it('should lowercase the code', () => {
-      expect(deriveLanguageEntry({ lang: 'ZH-Hans', name: 'Chinese' }).code).toBe('zh-hans');
+      expect(
+        deriveLanguageEntry({ lang: 'ZH-Hans', name: 'Chinese' }).code
+      ).toBe('zh-hans');
     });
 
     it('should mark targetOnly whenever the language is not source-usable', () => {
       expect(
-        deriveLanguageEntry({ lang: 'th', name: 'Thai', usable_as_source: false }).targetOnly,
+        deriveLanguageEntry({
+          lang: 'th',
+          name: 'Thai',
+          usable_as_source: false,
+        }).targetOnly
       ).toBe(true);
       expect(
-        deriveLanguageEntry({ lang: 'th', name: 'Thai', usable_as_source: true }).targetOnly,
+        deriveLanguageEntry({
+          lang: 'th',
+          name: 'Thai',
+          usable_as_source: true,
+        }).targetOnly
       ).toBeUndefined();
     });
 
@@ -393,7 +487,7 @@ describe('Language Registry', () => {
           name: de.name,
           usable_as_source: true,
           features: { glossary: { status: 'stable' } },
-        }),
+        })
       ).toEqual(de);
     });
   });
@@ -405,7 +499,7 @@ describe('Language Registry', () => {
      */
     it('should cover the regional variants a hand-written union had missed', () => {
       const codes: Language[] = ['de-ch', 'de-de', 'fr-ca', 'fr-fr'];
-      codes.forEach(code => expect(isValidLanguage(code)).toBe(true));
+      codes.forEach((code) => expect(isValidLanguage(code)).toBe(true));
     });
 
     it('should still exclude a code the snapshot does not list', () => {
@@ -419,22 +513,22 @@ describe('Language Registry', () => {
   describe('looksLikeLanguageTag()', () => {
     it.each(['de', 'ace', 'de-ch', 'en-gb', 'es-419', 'zh-hans', 'bho'])(
       'should accept the well-formed tag %s',
-      code => {
+      (code) => {
         expect(looksLikeLanguageTag(code)).toBe(true);
-      },
+      }
     );
 
     it.each(['grman', 'g', '', 'de_CH', 'de-', '-de', 'de-ch-extra', 'DE'])(
       'should reject the malformed tag %s',
-      code => {
+      (code) => {
         expect(looksLikeLanguageTag(code)).toBe(false);
-      },
+      }
     );
   });
 
   describe('formality support', () => {
     it('should not carry formality data; GET /v3/languages reports it as features.formality', () => {
-      LANGUAGE_REGISTRY.forEach(entry => {
+      LANGUAGE_REGISTRY.forEach((entry) => {
         expect(entry).not.toHaveProperty('supportsFormality');
       });
     });
diff --git a/tests/unit/languages-command.test.ts b/tests/unit/languages-command.test.ts
index b1d35521..f2a61384 100644
--- a/tests/unit/languages-command.test.ts
+++ b/tests/unit/languages-command.test.ts
@@ -111,7 +111,10 @@ describe('LanguagesCommand', () => {
 
   describe('formatLanguages()', () => {
     it('should format source languages with header', () => {
-      const formatted = languagesCommand.formatLanguages(mockSourceLanguages, 'source');
+      const formatted = languagesCommand.formatLanguages(
+        mockSourceLanguages,
+        'source'
+      );
 
       expect(formatted).toContain('Source Languages:');
       expect(formatted).toContain('en');
@@ -121,7 +124,10 @@ describe('LanguagesCommand', () => {
     });
 
     it('should format target languages with header', () => {
-      const formatted = languagesCommand.formatLanguages(mockTargetLanguages, 'target');
+      const formatted = languagesCommand.formatLanguages(
+        mockTargetLanguages,
+        'target'
+      );
 
       expect(formatted).toContain('Target Languages:');
       expect(formatted).toContain('en-us');
@@ -131,7 +137,10 @@ describe('LanguagesCommand', () => {
     });
 
     it('should include extended languages section', () => {
-      const formatted = languagesCommand.formatLanguages(mockSourceLanguages, 'source');
+      const formatted = languagesCommand.formatLanguages(
+        mockSourceLanguages,
+        'source'
+      );
 
       expect(formatted).toContain('Extended Languages');
       expect(formatted).toContain('quality_optimized only');
@@ -149,11 +158,14 @@ describe('LanguagesCommand', () => {
     });
 
     it('should align language codes and names properly', () => {
-      const formatted = languagesCommand.formatLanguages(mockSourceLanguages, 'source');
+      const formatted = languagesCommand.formatLanguages(
+        mockSourceLanguages,
+        'source'
+      );
       const lines = formatted.split('\n');
 
       const languageLines = lines.slice(1);
-      languageLines.forEach(line => {
+      languageLines.forEach((line) => {
         if (line.trim() && !line.includes('Extended Languages')) {
           expect(line).toMatch(/^\s+\S+\s+.+$/);
         }
@@ -161,8 +173,14 @@ describe('LanguagesCommand', () => {
     });
 
     it('should format both types correctly', () => {
-      const sourceFormatted = languagesCommand.formatLanguages(mockSourceLanguages, 'source');
-      const targetFormatted = languagesCommand.formatLanguages(mockTargetLanguages, 'target');
+      const sourceFormatted = languagesCommand.formatLanguages(
+        mockSourceLanguages,
+        'source'
+      );
+      const targetFormatted = languagesCommand.formatLanguages(
+        mockTargetLanguages,
+        'target'
+      );
 
       expect(sourceFormatted).toContain('Source Languages:');
       expect(targetFormatted).toContain('Target Languages:');
@@ -200,32 +218,33 @@ describe('LanguagesCommand', () => {
 
   describe('mergeWithRegistry()', () => {
     it('should use API names when available', () => {
-      const apiLangs: LanguageInfo[] = [
-        { language: 'de', name: 'Deutsch' },
-      ];
+      const apiLangs: LanguageInfo[] = [{ language: 'de', name: 'Deutsch' }];
       const merged = languagesCommand.mergeWithRegistry(apiLangs, 'source');
-      const de = merged.find(e => e.code === 'de');
+      const de = merged.find((e) => e.code === 'de');
       expect(de?.name).toBe('Deutsch');
     });
 
     it('should fall back to registry names for languages not in API response', () => {
       const merged = languagesCommand.mergeWithRegistry([], 'source');
-      const hi = merged.find(e => e.code === 'hi');
+      const hi = merged.find((e) => e.code === 'hi');
       expect(hi?.name).toBe('Hindi');
     });
 
     it('should include all registry languages', () => {
-      const merged = languagesCommand.mergeWithRegistry(mockSourceLanguages, 'source');
+      const merged = languagesCommand.mergeWithRegistry(
+        mockSourceLanguages,
+        'source'
+      );
       expect(merged.length).toBeGreaterThan(mockSourceLanguages.length);
-      expect(merged.some(e => e.code === 'hi')).toBe(true);
-      expect(merged.some(e => e.code === 'sw')).toBe(true);
+      expect(merged.some((e) => e.code === 'hi')).toBe(true);
+      expect(merged.some((e) => e.code === 'sw')).toBe(true);
     });
 
     it('should correctly categorize languages', () => {
       const merged = languagesCommand.mergeWithRegistry([], 'target');
-      const enGb = merged.find(e => e.code === 'en-gb');
-      const en = merged.find(e => e.code === 'en');
-      const hi = merged.find(e => e.code === 'hi');
+      const enGb = merged.find((e) => e.code === 'en-gb');
+      const en = merged.find((e) => e.code === 'en');
+      const hi = merged.find((e) => e.code === 'hi');
 
       expect(enGb?.category).toBe('regional');
       expect(en?.category).toBe('core');
@@ -243,15 +262,27 @@ describe('LanguagesCommand', () => {
       const entries = [
         { code: 'en', name: 'English', category: 'core' as const },
         { code: 'hi', name: 'Hindi', category: 'extended' as const },
-        { code: 'en-gb', name: 'English (British)', category: 'regional' as const },
+        {
+          code: 'en-gb',
+          name: 'English (British)',
+          category: 'regional' as const,
+        },
       ];
-      const formatted = languagesCommand.formatDisplayEntries(entries, 'target');
+      const formatted = languagesCommand.formatDisplayEntries(
+        entries,
+        'target'
+      );
       const lines = formatted.split('\n');
 
-      const enLine = lines.findIndex(l => l.includes('en') && !l.includes('en-gb') && !l.includes('Extended'));
-      const enGbLine = lines.findIndex(l => l.includes('en-gb'));
-      const extHeader = lines.findIndex(l => l.includes('Extended Languages'));
-      const hiLine = lines.findIndex(l => l.includes('Hindi'));
+      const enLine = lines.findIndex(
+        (l) =>
+          l.includes('en') && !l.includes('en-gb') && !l.includes('Extended')
+      );
+      const enGbLine = lines.findIndex((l) => l.includes('en-gb'));
+      const extHeader = lines.findIndex((l) =>
+        l.includes('Extended Languages')
+      );
+      const hiLine = lines.findIndex((l) => l.includes('Hindi'));
 
       expect(enLine).toBeLessThan(extHeader);
       expect(enGbLine).toBeLessThan(extHeader);
@@ -268,7 +299,7 @@ describe('LanguagesCommand', () => {
     it('should strip control characters from a language name in text output', () => {
       const formatted = languagesCommand.formatDisplayEntries(
         [{ code: 'de', name: HOSTILE_NAME, category: 'core' as const }],
-        'target',
+        'target'
       );
 
       expect(formatted).not.toContain('\u001b');
@@ -279,7 +310,7 @@ describe('LanguagesCommand', () => {
     it('should strip control characters from an extended-tier language name', () => {
       const formatted = languagesCommand.formatDisplayEntries(
         [{ code: 'hi', name: HOSTILE_NAME, category: 'extended' as const }],
-        'target',
+        'target'
       );
 
       expect(formatted).not.toContain('\u001b');
@@ -288,7 +319,7 @@ describe('LanguagesCommand', () => {
     it('should strip control characters from a language name in table output', () => {
       const formatted = languagesCommand.formatLanguagesTable(
         [{ language: 'de' as const, name: HOSTILE_NAME }],
-        'target',
+        'target'
       );
 
       // cli-table3 colours its own borders, so the assertion is about the cell:
@@ -306,10 +337,15 @@ describe('LanguagesCommand', () => {
             category: 'core' as const,
             features: { 'glo\u001b[2Kssary': { status: 'be\u001b[2Kta' } },
           },
-          { code: 'fr', name: 'French', category: 'core' as const, features: {} },
+          {
+            code: 'fr',
+            name: 'French',
+            category: 'core' as const,
+            features: {},
+          },
         ],
         'target',
-        true,
+        true
       );
 
       expect(formatted).not.toContain('\u001b');
@@ -357,9 +393,16 @@ describe('LanguagesCommand', () => {
     it('should show [F] marker for target languages that support formality', () => {
       const targetLangsWithFormality: LanguageInfo[] = [
         { language: 'de', name: 'German', supportsFormality: true },
-        { language: 'en-us', name: 'English (American)', supportsFormality: false },
+        {
+          language: 'en-us',
+          name: 'English (American)',
+          supportsFormality: false,
+        },
       ];
-      const formatted = languagesCommand.formatLanguages(targetLangsWithFormality, 'target');
+      const formatted = languagesCommand.formatLanguages(
+        targetLangsWithFormality,
+        'target'
+      );
 
       expect(formatted).toContain('German');
       expect(formatted).toContain('[F]');
@@ -367,10 +410,19 @@ describe('LanguagesCommand', () => {
 
     it('should not show [F] for languages that do not support formality', () => {
       const targetLangsWithFormality: LanguageInfo[] = [
-        { language: 'en-us', name: 'English (American)', supportsFormality: false },
+        {
+          language: 'en-us',
+          name: 'English (American)',
+          supportsFormality: false,
+        },
       ];
-      const formatted = languagesCommand.formatLanguages(targetLangsWithFormality, 'target');
-      const enUsLine = formatted.split('\n').find(l => l.includes('English (American)'));
+      const formatted = languagesCommand.formatLanguages(
+        targetLangsWithFormality,
+        'target'
+      );
+      const enUsLine = formatted
+        .split('\n')
+        .find((l) => l.includes('English (American)'));
 
       expect(enUsLine).not.toContain('[F]');
     });
@@ -379,7 +431,10 @@ describe('LanguagesCommand', () => {
       const targetLangsWithFormality: LanguageInfo[] = [
         { language: 'de', name: 'German', supportsFormality: true },
       ];
-      const formatted = languagesCommand.formatLanguages(targetLangsWithFormality, 'target');
+      const formatted = languagesCommand.formatLanguages(
+        targetLangsWithFormality,
+        'target'
+      );
 
       expect(formatted).toContain('[F] = supports formality parameter');
     });
@@ -397,12 +452,16 @@ describe('LanguagesCommand', () => {
       const apiLangs: LanguageInfo[] = [
         { language: 'de', name: 'German', supportsFormality: true },
         { language: 'fr', name: 'French', supportsFormality: true },
-        { language: 'en-us', name: 'English (American)', supportsFormality: false },
+        {
+          language: 'en-us',
+          name: 'English (American)',
+          supportsFormality: false,
+        },
       ];
       const merged = languagesCommand.mergeWithRegistry(apiLangs, 'target');
 
-      const de = merged.find(e => e.code === 'de');
-      const enUs = merged.find(e => e.code === 'en-us');
+      const de = merged.find((e) => e.code === 'de');
+      const enUs = merged.find((e) => e.code === 'en-us');
       expect(de?.supportsFormality).toBe(true);
       expect(enUs?.supportsFormality).toBe(false);
     });
@@ -413,14 +472,17 @@ describe('LanguagesCommand', () => {
       ];
       const merged = languagesCommand.mergeWithRegistry(apiLangs, 'target');
 
-      const hi = merged.find(e => e.code === 'hi');
+      const hi = merged.find((e) => e.code === 'hi');
       expect(hi?.supportsFormality).toBeUndefined();
     });
   });
 
   describe('formatLanguagesTable', () => {
     it('should render Code/Name/Category headers and rows for source languages', () => {
-      const result = languagesCommand.formatLanguagesTable(mockSourceLanguages, 'source');
+      const result = languagesCommand.formatLanguagesTable(
+        mockSourceLanguages,
+        'source'
+      );
       expect(result).toContain('Source Languages:');
       expect(result).toContain('Code');
       expect(result).toContain('Name');
@@ -431,7 +493,11 @@ describe('LanguagesCommand', () => {
     it('should add a Formality column when any target language reports it', () => {
       const targets: LanguageInfo[] = [
         { language: 'de', name: 'German', supportsFormality: true },
-        { language: 'en-us', name: 'English (American)', supportsFormality: false },
+        {
+          language: 'en-us',
+          name: 'English (American)',
+          supportsFormality: false,
+        },
       ];
       const result = languagesCommand.formatLanguagesTable(targets, 'target');
       expect(result).toContain('Target Languages:');
@@ -454,10 +520,13 @@ describe('LanguagesCommand', () => {
 
   describe('formatAllLanguagesTable', () => {
     it('should join the source and target tables with a blank line', () => {
-      const result = languagesCommand.formatAllLanguagesTable(mockSourceLanguages, [
-        { language: 'de', name: 'German' },
-        { language: 'fr', name: 'French' },
-      ]);
+      const result = languagesCommand.formatAllLanguagesTable(
+        mockSourceLanguages,
+        [
+          { language: 'de', name: 'German' },
+          { language: 'fr', name: 'French' },
+        ]
+      );
       expect(result).toContain('Source Languages:');
       expect(result).toContain('Target Languages:');
       // The two sections are separated by at least one blank line.
@@ -476,7 +545,7 @@ describe('LanguagesCommand', () => {
         },
       ];
       const merged = languagesCommand.mergeWithRegistry(apiLangs, 'target');
-      const entry = merged.find(e => e.code === 'xx-yy');
+      const entry = merged.find((e) => e.code === 'xx-yy');
 
       expect(entry).toBeDefined();
       expect(entry!.name).toBe('Testish (Regional)');
@@ -497,17 +566,17 @@ describe('LanguagesCommand', () => {
       ];
       const merged = languagesCommand.mergeWithRegistry(apiLangs, 'target');
 
-      expect(merged.find(e => e.code === 'xx')!.category).toBe('extended');
-      expect(merged.find(e => e.code === 'yy')!.category).toBe('core');
+      expect(merged.find((e) => e.code === 'xx')!.category).toBe('extended');
+      expect(merged.find((e) => e.code === 'yy')!.category).toBe('core');
     });
 
     it('should keep snapshot languages the API omits', () => {
       const merged = languagesCommand.mergeWithRegistry(
         [{ language: 'de', name: 'German' }],
-        'target',
+        'target'
       );
 
-      expect(merged.find(e => e.code === 'ja')).toBeDefined();
+      expect(merged.find((e) => e.code === 'ja')).toBeDefined();
       expect(merged.length).toBeGreaterThan(100);
     });
 
@@ -516,11 +585,11 @@ describe('LanguagesCommand', () => {
       // union trusts whichever list it is handed for that role.
       const sourceMerged = languagesCommand.mergeWithRegistry(
         [{ language: 'xx' as LanguageInfo['language'], name: 'Testish' }],
-        'source',
+        'source'
       );
 
-      expect(sourceMerged.find(e => e.code === 'xx')).toBeDefined();
-      expect(sourceMerged.find(e => e.code === 'en-gb')).toBeUndefined();
+      expect(sourceMerged.find((e) => e.code === 'xx')).toBeDefined();
+      expect(sourceMerged.find((e) => e.code === 'en-gb')).toBeUndefined();
     });
   });
 
@@ -529,10 +598,16 @@ describe('LanguagesCommand', () => {
       // LanguageInfo carries no usable_as_source, so the subtag is the only
       // signal available; asserted because nothing else pins this guess.
       const merged = languagesCommand.mergeWithRegistry(
-        [{ language: 'de-ch', name: 'German (Swiss)', features: { glossary: { status: 'stable' } } }],
-        'target',
+        [
+          {
+            language: 'de-ch',
+            name: 'German (Swiss)',
+            features: { glossary: { status: 'stable' } },
+          },
+        ],
+        'target'
       );
-      const entry = merged.find(e => e.code === 'de-ch');
+      const entry = merged.find((e) => e.code === 'de-ch');
 
       expect(entry).toBeDefined();
       expect(entry!.category).toBe('regional');
@@ -540,27 +615,39 @@ describe('LanguagesCommand', () => {
 
     it('should treat a bare code with glossary support as core', () => {
       const merged = languagesCommand.mergeWithRegistry(
-        [{ language: 'xx' as never, name: 'Novel', features: { glossary: { status: 'stable' } } }],
-        'target',
+        [
+          {
+            language: 'xx' as never,
+            name: 'Novel',
+            features: { glossary: { status: 'stable' } },
+          },
+        ],
+        'target'
       );
 
-      expect(merged.find(e => e.code === 'xx')!.category).toBe('core');
+      expect(merged.find((e) => e.code === 'xx')!.category).toBe('core');
     });
 
     it('should treat a code without glossary support as extended', () => {
       const merged = languagesCommand.mergeWithRegistry(
-        [{ language: 'yy' as never, name: 'Other', features: { tag_handling: { status: 'stable' } } }],
-        'target',
+        [
+          {
+            language: 'yy' as never,
+            name: 'Other',
+            features: { tag_handling: { status: 'stable' } },
+          },
+        ],
+        'target'
       );
 
-      expect(merged.find(e => e.code === 'yy')!.category).toBe('extended');
+      expect(merged.find((e) => e.code === 'yy')!.category).toBe('extended');
     });
   });
 
   describe('partitionFeatureKeys()', () => {
     const entry = (
       code: string,
-      features?: Record<string, { status: string }>,
+      features?: Record<string, { status: string }>
     ): LanguageDisplayEntry => ({
       code,
       name: code.toUpperCase(),
@@ -595,7 +682,10 @@ describe('LanguagesCommand', () => {
         formality: { status: 'stable' },
         glossary: { status: 'stable' },
       };
-      const { columns } = partitionFeatureKeys([entry('de', all), entry('hi', {})]);
+      const { columns } = partitionFeatureKeys([
+        entry('de', all),
+        entry('hi', {}),
+      ]);
 
       expect(columns).toEqual([
         'formality',
@@ -658,9 +748,13 @@ describe('LanguagesCommand', () => {
     ];
 
     it('should list supported features per language in text output', () => {
-      const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
-      const de = formatted.split('\n').find(l => l.includes('German'));
-      const pt = formatted.split('\n').find(l => l.includes('Portuguese'));
+      const formatted = languagesCommand.formatDisplayEntries(
+        displayEntries,
+        'target',
+        true
+      );
+      const de = formatted.split('\n').find((l) => l.includes('German'));
+      const pt = formatted.split('\n').find((l) => l.includes('Portuguese'));
 
       expect(de).toContain('formality');
       expect(de).toContain('style rules');
@@ -669,29 +763,50 @@ describe('LanguagesCommand', () => {
     });
 
     it('should note the features every listed language shares', () => {
-      const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
+      const formatted = languagesCommand.formatDisplayEntries(
+        displayEntries,
+        'target',
+        true
+      );
 
-      expect(formatted).toContain('All listed languages also support: tag handling.');
+      expect(formatted).toContain(
+        'All listed languages also support: tag handling.'
+      );
     });
 
     it('should not claim a language supports nothing when the footer credits it', () => {
-      const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
-      const hi = formatted.split('\n').find(l => l.includes('Hindi'));
+      const formatted = languagesCommand.formatDisplayEntries(
+        displayEntries,
+        'target',
+        true
+      );
+      const hi = formatted.split('\n').find((l) => l.includes('Hindi'));
 
       // Hindi supports none of the discriminating columns but does support the
       // uniform one, which the footer reports -- "none" would contradict it.
       expect(hi).not.toContain('none');
-      expect(formatted).toContain('All listed languages also support: tag handling.');
+      expect(formatted).toContain(
+        'All listed languages also support: tag handling.'
+      );
     });
 
     it('should mark a language the response credits with no features at all', () => {
       const entries: LanguageDisplayEntry[] = [
-        { code: 'de', name: 'German', category: 'core', features: { glossary: { status: 'stable' } } },
+        {
+          code: 'de',
+          name: 'German',
+          category: 'core',
+          features: { glossary: { status: 'stable' } },
+        },
         { code: 'hi', name: 'Hindi', category: 'extended', features: {} },
       ];
 
-      const formatted = languagesCommand.formatDisplayEntries(entries, 'target', true);
-      const hi = formatted.split('\n').find(l => l.includes('Hindi'));
+      const formatted = languagesCommand.formatDisplayEntries(
+        entries,
+        'target',
+        true
+      );
+      const hi = formatted.split('\n').find((l) => l.includes('Hindi'));
 
       expect(hi).toContain('none');
     });
@@ -706,41 +821,73 @@ describe('LanguagesCommand', () => {
           features: { style_rules: { status: 'stable' } },
         },
       ];
-      const formatted = languagesCommand.formatDisplayEntries(entries, 'target', true);
-      const th = formatted.split('\n').find(l => l.includes('Thai'));
+      const formatted = languagesCommand.formatDisplayEntries(
+        entries,
+        'target',
+        true
+      );
+      const th = formatted.split('\n').find((l) => l.includes('Thai'));
 
       expect(th).toContain('style rules');
     });
 
     it('should drop the [F] marker and legend when features are shown', () => {
-      const formatted = languagesCommand.formatDisplayEntries(displayEntries, 'target', true);
+      const formatted = languagesCommand.formatDisplayEntries(
+        displayEntries,
+        'target',
+        true
+      );
 
       expect(formatted).not.toContain('[F]');
     });
 
     it('should label a non-stable status instead of yes', () => {
       const entries: LanguageDisplayEntry[] = [
-        { code: 'de', name: 'German', category: 'core', features: { glossary: { status: 'beta' } } },
+        {
+          code: 'de',
+          name: 'German',
+          category: 'core',
+          features: { glossary: { status: 'beta' } },
+        },
         { code: 'hi', name: 'Hindi', category: 'extended', features: {} },
       ];
-      const formatted = languagesCommand.formatDisplayEntries(entries, 'target', true);
-      const de = formatted.split('\n').find(l => l.includes('German'));
+      const formatted = languagesCommand.formatDisplayEntries(
+        entries,
+        'target',
+        true
+      );
+      const de = formatted.split('\n').find((l) => l.includes('German'));
 
       expect(de).toContain('glossary (beta)');
     });
 
     it('should fall back to the default rendering when no entry reports features', () => {
       const noFeatures: LanguageDisplayEntry[] = [
-        { code: 'de', name: 'German', category: 'core', supportsFormality: true },
+        {
+          code: 'de',
+          name: 'German',
+          category: 'core',
+          supportsFormality: true,
+        },
       ];
-      const withFlag = languagesCommand.formatDisplayEntries(noFeatures, 'target', true);
-      const without = languagesCommand.formatDisplayEntries(noFeatures, 'target');
+      const withFlag = languagesCommand.formatDisplayEntries(
+        noFeatures,
+        'target',
+        true
+      );
+      const without = languagesCommand.formatDisplayEntries(
+        noFeatures,
+        'target'
+      );
 
       expect(withFlag).toBe(without);
     });
 
     it('should leave default text output untouched when features are not requested', () => {
-      const withFlagOff = languagesCommand.formatDisplayEntries(displayEntries, 'target');
+      const withFlagOff = languagesCommand.formatDisplayEntries(
+        displayEntries,
+        'target'
+      );
 
       expect(withFlagOff).toContain('[F]');
       expect(withFlagOff).not.toContain('tag handling');
@@ -755,7 +902,11 @@ describe('LanguagesCommand', () => {
           features: { glossary: { status: 'stable' } },
         },
       ];
-      const formatted = languagesCommand.formatLanguages(apiLangs, 'target', true);
+      const formatted = languagesCommand.formatLanguages(
+        apiLangs,
+        'target',
+        true
+      );
 
       // Asserted on the footer line specifically: the section header for extended
       // languages also contains the word "glossary", so a bare toContain would
@@ -769,7 +920,10 @@ describe('LanguagesCommand', () => {
           language: 'de',
           name: 'German',
           supportsFormality: true,
-          features: { glossary: { status: 'stable' }, formality: { status: 'stable' } },
+          features: {
+            glossary: { status: 'stable' },
+            formality: { status: 'stable' },
+          },
         },
         {
           language: 'pt',
@@ -778,25 +932,38 @@ describe('LanguagesCommand', () => {
           features: { glossary: { status: 'stable' } },
         },
       ];
-      const formatted = languagesCommand.formatLanguages(apiLangs, 'target', true);
-      const zulu = formatted.split('\n').find(l => l.includes('Zulu'));
+      const formatted = languagesCommand.formatLanguages(
+        apiLangs,
+        'target',
+        true
+      );
+      const zulu = formatted.split('\n').find((l) => l.includes('Zulu'));
 
       expect(zulu).toContain('no feature data');
       expect(zulu).not.toContain('none');
     });
 
     it('should add a column per discriminating feature in table output', () => {
-      const table = languagesCommand.formatDisplayEntriesTable(displayEntries, 'target', true);
+      const table = languagesCommand.formatDisplayEntriesTable(
+        displayEntries,
+        'target',
+        true
+      );
 
       expect(table).toContain('Formality');
       expect(table).toContain('Glossary');
       expect(table).toContain('Style Rules');
       expect(table).not.toContain('Tag Handling');
-      expect(table).toContain('All listed languages also support: tag handling.');
+      expect(table).toContain(
+        'All listed languages also support: tag handling.'
+      );
     });
 
     it('should not add feature columns to table output by default', () => {
-      const table = languagesCommand.formatDisplayEntriesTable(displayEntries, 'target');
+      const table = languagesCommand.formatDisplayEntriesTable(
+        displayEntries,
+        'target'
+      );
 
       expect(table).not.toContain('Glossary');
       expect(table).toContain('Formality');
diff --git a/tests/unit/languages-service.test.ts b/tests/unit/languages-service.test.ts
index 6326e0da..a580c56e 100644
--- a/tests/unit/languages-service.test.ts
+++ b/tests/unit/languages-service.test.ts
@@ -39,11 +39,15 @@ describe('LanguagesService', () => {
 
   it('should propagate errors from client', async () => {
     const mockClient = createMockDeepLClient({
-      getSupportedLanguages: jest.fn().mockRejectedValue(new Error('API error')),
+      getSupportedLanguages: jest
+        .fn()
+        .mockRejectedValue(new Error('API error')),
     });
     const service = new LanguagesService(mockClient);
 
-    await expect(service.getSupportedLanguages('source')).rejects.toThrow('API error');
+    await expect(service.getSupportedLanguages('source')).rejects.toThrow(
+      'API error'
+    );
   });
 
   it('should report hasClient correctly', () => {
diff --git a/tests/unit/logger.test.ts b/tests/unit/logger.test.ts
index c6764ad8..468ed365 100644
--- a/tests/unit/logger.test.ts
+++ b/tests/unit/logger.test.ts
@@ -174,7 +174,9 @@ describe('Logger', () => {
     });
 
     it('should redact &token= query parameter from URLs', () => {
-      Logger.verbose('https://api.deepl.com/ws?lang=en&token=abc123-secret&format=text');
+      Logger.verbose(
+        'https://api.deepl.com/ws?lang=en&token=abc123-secret&format=text'
+      );
       expect(consoleErrorSpy).toHaveBeenCalledWith(
         'https://api.deepl.com/ws?lang=en&token=[REDACTED]&format=text'
       );
@@ -189,9 +191,7 @@ describe('Logger', () => {
 
     it('should redact DeepL-Auth-Key case-insensitively', () => {
       Logger.verbose('deepl-auth-key MY-KEY:fx');
-      expect(consoleErrorSpy).toHaveBeenCalledWith(
-        'DeepL-Auth-Key [REDACTED]'
-      );
+      expect(consoleErrorSpy).toHaveBeenCalledWith('DeepL-Auth-Key [REDACTED]');
     });
 
     it('should redact X-Api-Key header values', () => {
@@ -210,13 +210,13 @@ describe('Logger', () => {
 
     it('should redact X-Api-Key case-insensitively', () => {
       Logger.verbose('x-api-key: MY-SECRET');
-      expect(consoleErrorSpy).toHaveBeenCalledWith(
-        'X-Api-Key: [REDACTED]'
-      );
+      expect(consoleErrorSpy).toHaveBeenCalledWith('X-Api-Key: [REDACTED]');
     });
 
     it('should redact ?api_key= query parameter from URLs', () => {
-      Logger.verbose('https://tms.example.com/projects?api_key=abc123&format=json');
+      Logger.verbose(
+        'https://tms.example.com/projects?api_key=abc123&format=json'
+      );
       expect(consoleErrorSpy).toHaveBeenCalledWith(
         'https://tms.example.com/projects?api_key=[REDACTED]&format=json'
       );
@@ -499,7 +499,7 @@ describe('Logger', () => {
     it('should not redact when TMS_API_KEY is not set', () => {
       Logger.info('Generic message without any TMS values');
       expect(consoleErrorSpy).toHaveBeenCalledWith(
-        'Generic message without any TMS values',
+        'Generic message without any TMS values'
       );
     });
 
@@ -558,7 +558,7 @@ describe('Logger', () => {
       process.env['TMS_TOKEN'] = 'test-tms-token-67890';
       try {
         Logger.info(
-          'deepl=deepl-key-abc:fx tmsKey=test-tms-api-key-12345 tmsTok=test-tms-token-67890 url?token=qp-secret DeepL-Auth-Key deepl-key-abc:fx Authorization: Bearer jwt.abc',
+          'deepl=deepl-key-abc:fx tmsKey=test-tms-api-key-12345 tmsTok=test-tms-token-67890 url?token=qp-secret DeepL-Auth-Key deepl-key-abc:fx Authorization: Bearer jwt.abc'
         );
         const logged = consoleErrorSpy.mock.calls[0]?.[0] as string;
         expect(logged).not.toContain('deepl-key-abc:fx');
@@ -599,10 +599,15 @@ describe('Logger', () => {
     });
 
     it('should guard against circular references', () => {
-      const obj: Record<string, unknown> = { url: 'https://host?token=loop-secret' };
+      const obj: Record<string, unknown> = {
+        url: 'https://host?token=loop-secret',
+      };
       obj['self'] = obj;
       Logger.error(obj);
-      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Record<string, unknown>;
+      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Record<
+        string,
+        unknown
+      >;
       expect(logged['url']).toBe('https://host?token=[REDACTED]');
       expect(logged['self']).toBe('[Circular]');
     });
@@ -620,13 +625,17 @@ describe('Logger', () => {
 
     it('should redact extra properties attached to an Error', () => {
       const err = new Error('boom') as Error & { config?: unknown };
-      err.config = { headers: { Authorization: 'Authorization: ApiKey axios-secret' } };
+      err.config = {
+        headers: { Authorization: 'Authorization: ApiKey axios-secret' },
+      };
       Logger.error(err);
       const logged = consoleErrorSpy.mock.calls[0]?.[0] as Error & {
         config?: { headers?: { Authorization?: string } };
       };
       expect(logged).toBeInstanceOf(Error);
-      expect(logged.config?.headers?.Authorization).toBe('Authorization: ApiKey [REDACTED]');
+      expect(logged.config?.headers?.Authorization).toBe(
+        'Authorization: ApiKey [REDACTED]'
+      );
     });
 
     it('should pass non-plain objects through unchanged', () => {
@@ -643,7 +652,10 @@ describe('Logger', () => {
       const obj = Object.create(null) as Record<string, unknown>;
       obj['url'] = 'https://host?api_key=np-secret';
       Logger.error(obj);
-      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Record<string, unknown>;
+      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Record<
+        string,
+        unknown
+      >;
       expect(logged['url']).toBe('https://host?api_key=[REDACTED]');
     });
   });
diff --git a/tests/unit/package-manifest.test.ts b/tests/unit/package-manifest.test.ts
index f8077b9d..f38ec230 100644
--- a/tests/unit/package-manifest.test.ts
+++ b/tests/unit/package-manifest.test.ts
@@ -76,7 +76,9 @@ describe('package.json manifest', () => {
     });
 
     it('should point bin at a path inside dist', () => {
-      expect(Object.values(pkg.bin).every((target) => target.startsWith('dist/'))).toBe(true);
+      expect(
+        Object.values(pkg.bin).every((target) => target.startsWith('dist/'))
+      ).toBe(true);
     });
   });
 
@@ -84,10 +86,13 @@ describe('package.json manifest', () => {
     // Consumers install dependencies only. A package imported by src/ but
     // declared under devDependencies resolves in this tree and fails on every
     // real install, and dependency ranges cannot be changed after publish.
-    it.each(['@inquirer/prompts', 'diff'])('should declare %s as a runtime dependency', (name) => {
-      expect(pkg.dependencies[name]).toBeDefined();
-      expect(pkg.devDependencies[name]).toBeUndefined();
-    });
+    it.each(['@inquirer/prompts', 'diff'])(
+      'should declare %s as a runtime dependency',
+      (name) => {
+        expect(pkg.dependencies[name]).toBeDefined();
+        expect(pkg.devDependencies[name]).toBeUndefined();
+      }
+    );
 
     it('should not declare packages that no source file imports', () => {
       expect(pkg.dependencies['inquirer']).toBeUndefined();
@@ -126,8 +131,17 @@ describe('package.json manifest', () => {
      * -- which `deepl --help` never exercises, because the bin has its own entry.
      */
     /** Imported in a real Node ESM process; jest's CJS transform cannot load it. */
-    const importEntry = (): { status: number; stdout: string; stderr: string } => {
-      const entry = path.join(__dirname, '..', '..', pkg.main ?? 'dist/index.js');
+    const importEntry = (): {
+      status: number;
+      stdout: string;
+      stderr: string;
+    } => {
+      const entry = path.join(
+        __dirname,
+        '..',
+        '..',
+        pkg.main ?? 'dist/index.js'
+      );
       const result = spawnSync(
         'node',
         [
@@ -136,7 +150,7 @@ describe('package.json manifest', () => {
           `const m = await import(${JSON.stringify(entry)});` +
             'process.stdout.write(Object.keys(m).sort().join(","));',
         ],
-        { encoding: 'utf-8' },
+        { encoding: 'utf-8' }
       );
       return {
         status: result.status ?? 1,
@@ -148,7 +162,9 @@ describe('package.json manifest', () => {
     it('should be importable', () => {
       const result = importEntry();
 
-      expect(result.stderr).not.toMatch(/ERR_UNSUPPORTED_DIR_IMPORT|ERR_MODULE_NOT_FOUND/);
+      expect(result.stderr).not.toMatch(
+        /ERR_UNSUPPORTED_DIR_IMPORT|ERR_MODULE_NOT_FOUND/
+      );
       expect(result.status).toBe(0);
     });
 
@@ -162,13 +178,15 @@ describe('package.json manifest', () => {
     it('should declare no directory specifiers in the emitted entry chain', () => {
       const distDir = path.join(__dirname, '..', '..', 'dist');
       const emitted = ['index.js', 'index.d.ts', path.join('types', 'index.js')]
-        .map(file => path.join(distDir, file))
-        .filter(file => fs.existsSync(file));
+        .map((file) => path.join(distDir, file))
+        .filter((file) => fs.existsSync(file));
 
       expect(emitted.length).toBeGreaterThan(0);
       for (const file of emitted) {
         const source = fs.readFileSync(file, 'utf-8');
-        const specifiers = [...source.matchAll(/from\s+'(\.[^']*)'/g)].map(match => match[1]!);
+        const specifiers = [...source.matchAll(/from\s+'(\.[^']*)'/g)].map(
+          (match) => match[1]!
+        );
         for (const specifier of specifiers) {
           expect(specifier).toMatch(/\.js$/);
         }
diff --git a/tests/unit/paths.test.ts b/tests/unit/paths.test.ts
index 8bb8b5d3..b28b6300 100644
--- a/tests/unit/paths.test.ts
+++ b/tests/unit/paths.test.ts
@@ -4,7 +4,9 @@ import * as os from 'os';
 import { resolvePaths } from '../../src/utils/paths';
 
 jest.mock('fs');
-const mockExistsSync = fs.existsSync as jest.MockedFunction<typeof fs.existsSync>;
+const mockExistsSync = fs.existsSync as jest.MockedFunction<
+  typeof fs.existsSync
+>;
 
 const HOME = os.homedir();
 
@@ -99,9 +101,13 @@ describe('resolvePaths', () => {
     const paths = resolvePaths();
 
     expect(paths.configDir).toBe(path.join(HOME, '.config', 'deepl-cli'));
-    expect(paths.configFile).toBe(path.join(HOME, '.config', 'deepl-cli', 'config.json'));
+    expect(paths.configFile).toBe(
+      path.join(HOME, '.config', 'deepl-cli', 'config.json')
+    );
     expect(paths.cacheDir).toBe(path.join(HOME, '.cache', 'deepl-cli'));
-    expect(paths.cacheFile).toBe(path.join(HOME, '.cache', 'deepl-cli', 'cache.db'));
+    expect(paths.cacheFile).toBe(
+      path.join(HOME, '.cache', 'deepl-cli', 'cache.db')
+    );
   });
 
   it('prefers legacy dir over XDG vars', () => {
diff --git a/tests/unit/prototype-key-safety.test.ts b/tests/unit/prototype-key-safety.test.ts
index d81d58be..e62b1acc 100644
--- a/tests/unit/prototype-key-safety.test.ts
+++ b/tests/unit/prototype-key-safety.test.ts
@@ -21,7 +21,14 @@ import { GlossaryService } from '../../src/services/glossary';
 import { sortedKeysReplacer } from '../../src/sync/sync-lock';
 import { Logger } from '../../src/utils/logger';
 
-const PROTO_KEYS = ['__proto__', 'constructor', 'prototype', 'toString', 'valueOf', 'hasOwnProperty'];
+const PROTO_KEYS = [
+  '__proto__',
+  'constructor',
+  'prototype',
+  'toString',
+  'valueOf',
+  'hasOwnProperty',
+];
 
 describe('prototype-named key safety', () => {
   afterEach(() => {
@@ -33,7 +40,7 @@ describe('prototype-named key safety', () => {
 
   /** Reads a probe off a fresh object without tripping index-signature rules. */
   function probeOnFreshObject(name: string): unknown {
-    return (({}) as Record<string, unknown>)[name];
+    return ({} as Record<string, unknown>)[name];
   }
 
   describe('JsonFormatParser', () => {
@@ -49,7 +56,9 @@ describe('prototype-named key safety', () => {
       parser.reconstruct('{}', translated);
 
       expect(probeOnFreshObject('polluted')).toBeUndefined();
-      expect((([] as unknown) as Record<string, unknown>)['polluted']).toBeUndefined();
+      expect(
+        ([] as unknown as Record<string, unknown>)['polluted']
+      ).toBeUndefined();
     });
 
     it('should round-trip a literal toString key as ordinary data', () => {
@@ -69,58 +78,73 @@ describe('prototype-named key safety', () => {
       expect(parsed['greeting']).toBe('Hallo');
     });
 
-    it.each(PROTO_KEYS)('should round-trip a %s key present in the entry list', (key) => {
-      const parser = new JsonFormatParser();
-      // Note: a key absent from the entry list is pruned by removeDeletedKeys,
-      // which is intended behaviour — so the key under test must be supplied.
-      const target = `{"greeting":"Hallo",${JSON.stringify(key)}:"alt"}`;
-
-      const out = parser.reconstruct(target, [
-        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
-        { key, value: 'Source', translation: 'vorhanden' },
-      ]);
-
-      const parsed = JSON.parse(out) as Record<string, unknown>;
-      expect(Object.hasOwn(parsed, key)).toBe(true);
-      expect(parsed[key]).toBe('vorhanden');
-    });
+    it.each(PROTO_KEYS)(
+      'should round-trip a %s key present in the entry list',
+      (key) => {
+        const parser = new JsonFormatParser();
+        // Note: a key absent from the entry list is pruned by removeDeletedKeys,
+        // which is intended behaviour — so the key under test must be supplied.
+        const target = `{"greeting":"Hallo",${JSON.stringify(key)}:"alt"}`;
+
+        const out = parser.reconstruct(target, [
+          { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+          { key, value: 'Source', translation: 'vorhanden' },
+        ]);
+
+        const parsed = JSON.parse(out) as Record<string, unknown>;
+        expect(Object.hasOwn(parsed, key)).toBe(true);
+        expect(parsed[key]).toBe('vorhanden');
+      }
+    );
 
     // The cases above reconstruct a key the target already holds. Inserting a
     // key the target lacks is a different code path, and the one where plain
     // assignment silently drops the translation instead of polluting: on a
     // fresh {}, obj['__proto__'] = v retargets that object's prototype, so a
     // negative "was Object.prototype polluted" assertion still passes.
-    it.each(PROTO_KEYS)('should insert a %s key absent from the target as own data', (key) => {
-      const parser = new JsonFormatParser();
-
-      const out = parser.reconstruct('{"greeting":"Hallo"}', [
-        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
-        { key, value: 'Source', translation: 'eingefuegt' },
-      ]);
-
-      const parsed = JSON.parse(out) as Record<string, unknown>;
-      expect(Object.hasOwn(parsed, key)).toBe(true);
-      expect(parsed[key]).toBe('eingefuegt');
-      expect(probeOnFreshObject('eingefuegt')).toBeUndefined();
-    });
+    it.each(PROTO_KEYS)(
+      'should insert a %s key absent from the target as own data',
+      (key) => {
+        const parser = new JsonFormatParser();
+
+        const out = parser.reconstruct('{"greeting":"Hallo"}', [
+          { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+          { key, value: 'Source', translation: 'eingefuegt' },
+        ]);
+
+        const parsed = JSON.parse(out) as Record<string, unknown>;
+        expect(Object.hasOwn(parsed, key)).toBe(true);
+        expect(parsed[key]).toBe('eingefuegt');
+        expect(probeOnFreshObject('eingefuegt')).toBeUndefined();
+      }
+    );
 
     it('should insert a nested key under __proto__ as own data', () => {
       const parser = new JsonFormatParser();
 
       const out = parser.reconstruct('{"greeting":"Hallo"}', [
         { key: 'greeting', value: 'Hello', translation: 'Hallo' },
-        { key: '__proto__.nested', value: 'Source', translation: 'verschachtelt' },
+        {
+          key: '__proto__.nested',
+          value: 'Source',
+          translation: 'verschachtelt',
+        },
       ]);
 
       const parsed = JSON.parse(out) as Record<string, unknown>;
       expect(Object.hasOwn(parsed, '__proto__')).toBe(true);
-      expect((parsed['__proto__'] as Record<string, unknown>)['nested']).toBe('verschachtelt');
+      expect((parsed['__proto__'] as Record<string, unknown>)['nested']).toBe(
+        'verschachtelt'
+      );
     });
   });
 
   describe('sanitizePullKeysResponse', () => {
     it('should return an object with no inherited members', () => {
-      const raw = JSON.parse('{"greeting": "Hallo"}') as Record<string, unknown>;
+      const raw = JSON.parse('{"greeting": "Hallo"}') as Record<
+        string,
+        unknown
+      >;
 
       const result = sanitizePullKeysResponse(raw);
 
@@ -128,17 +152,25 @@ describe('prototype-named key safety', () => {
       expect(Object.getPrototypeOf(result)).toBeNull();
     });
 
-    it.each(PROTO_KEYS)('should report %s as absent when the TMS export is empty', (key) => {
-      const result = sanitizePullKeysResponse(JSON.parse('{}') as Record<string, unknown>);
-
-      // The bug: result[key] returned an inherited function, so callers
-      // treated the key as freshly approved and discarded the real translation.
-      expect(result[key]).toBeUndefined();
-      expect(Object.hasOwn(result, key)).toBe(false);
-    });
+    it.each(PROTO_KEYS)(
+      'should report %s as absent when the TMS export is empty',
+      (key) => {
+        const result = sanitizePullKeysResponse(
+          JSON.parse('{}') as Record<string, unknown>
+        );
+
+        // The bug: result[key] returned an inherited function, so callers
+        // treated the key as freshly approved and discarded the real translation.
+        expect(result[key]).toBeUndefined();
+        expect(Object.hasOwn(result, key)).toBe(false);
+      }
+    );
 
     it('should retain a genuine translation for a prototype-named key', () => {
-      const raw = JSON.parse('{"toString": "In Text umwandeln"}') as Record<string, unknown>;
+      const raw = JSON.parse('{"toString": "In Text umwandeln"}') as Record<
+        string,
+        unknown
+      >;
 
       const result = sanitizePullKeysResponse(raw);
 
@@ -148,32 +180,45 @@ describe('prototype-named key safety', () => {
   });
 
   describe('GlossaryService.tsvToEntries', () => {
-    it.each(PROTO_KEYS)('should keep a %s source term instead of dropping it', (key) => {
-      const tsv = `hello\tHallo\n${key}\tPrototyp\nworld\tWelt\n`;
+    it.each(PROTO_KEYS)(
+      'should keep a %s source term instead of dropping it',
+      (key) => {
+        const tsv = `hello\tHallo\n${key}\tPrototyp\nworld\tWelt\n`;
 
-      const entries = GlossaryService.tsvToEntries(tsv);
+        const entries = GlossaryService.tsvToEntries(tsv);
 
-      expect(Object.keys(entries).sort()).toEqual([key, 'hello', 'world'].sort());
-      expect(entries[key]).toBe('Prototyp');
-    });
+        expect(Object.keys(entries).sort()).toEqual(
+          [key, 'hello', 'world'].sort()
+        );
+        expect(entries[key]).toBe('Prototyp');
+      }
+    );
 
     it('should not report a prototype-named term as a duplicate', () => {
-      const warn = jest.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+      const warn = jest
+        .spyOn(Logger, 'warn')
+        .mockImplementation(() => undefined);
       try {
         GlossaryService.tsvToEntries('toString\tIn Text umwandeln\n');
 
-        expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('Duplicate source'));
+        expect(warn).not.toHaveBeenCalledWith(
+          expect.stringContaining('Duplicate source')
+        );
       } finally {
         warn.mockRestore();
       }
     });
 
     it('should still report a genuine duplicate', () => {
-      const warn = jest.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+      const warn = jest
+        .spyOn(Logger, 'warn')
+        .mockImplementation(() => undefined);
       try {
         GlossaryService.tsvToEntries('hello\tHallo\nhello\tGuten Tag\n');
 
-        expect(warn).toHaveBeenCalledWith(expect.stringContaining('Duplicate source'));
+        expect(warn).toHaveBeenCalledWith(
+          expect.stringContaining('Duplicate source')
+        );
       } finally {
         warn.mockRestore();
       }
@@ -181,18 +226,25 @@ describe('prototype-named key safety', () => {
   });
 
   describe('sortedKeysReplacer', () => {
-    it.each(PROTO_KEYS)('should preserve a %s lockfile key when sorting', (key) => {
-      // Built by JSON.parse so the prototype-named key is a real own property.
-      const src = JSON.parse(`{"zebra": 1, ${JSON.stringify(key)}: 2, "alpha": 3}`) as Record<
-        string,
-        unknown
-      >;
-
-      const out = sortedKeysReplacer('entries', src) as Record<string, unknown>;
-
-      expect(Object.hasOwn(out, key)).toBe(true);
-      expect(out[key]).toBe(2);
-      expect(JSON.parse(JSON.stringify(out)) as Record<string, unknown>).toHaveProperty(key, 2);
-    });
+    it.each(PROTO_KEYS)(
+      'should preserve a %s lockfile key when sorting',
+      (key) => {
+        // Built by JSON.parse so the prototype-named key is a real own property.
+        const src = JSON.parse(
+          `{"zebra": 1, ${JSON.stringify(key)}: 2, "alpha": 3}`
+        ) as Record<string, unknown>;
+
+        const out = sortedKeysReplacer('entries', src) as Record<
+          string,
+          unknown
+        >;
+
+        expect(Object.hasOwn(out, key)).toBe(true);
+        expect(out[key]).toBe(2);
+        expect(
+          JSON.parse(JSON.stringify(out)) as Record<string, unknown>
+        ).toHaveProperty(key, 2);
+      }
+    );
   });
 });
diff --git a/tests/unit/read-stdin.test.ts b/tests/unit/read-stdin.test.ts
index eec76f85..b9bb119b 100644
--- a/tests/unit/read-stdin.test.ts
+++ b/tests/unit/read-stdin.test.ts
@@ -9,7 +9,10 @@ describe('readStdin', () => {
   });
 
   afterEach(() => {
-    Object.defineProperty(process, 'stdin', { value: originalStdin, writable: true });
+    Object.defineProperty(process, 'stdin', {
+      value: originalStdin,
+      writable: true,
+    });
   });
 
   function mockStdin(): PassThrough {
@@ -59,7 +62,9 @@ describe('readStdin', () => {
     stream.end();
 
     await expect(promise).rejects.toThrow(ValidationError);
-    await expect(promise).rejects.toThrow('Input exceeds maximum size of 128KB');
+    await expect(promise).rejects.toThrow(
+      'Input exceeds maximum size of 128KB'
+    );
   });
 
   it('should reject on stdin error', async () => {
diff --git a/tests/unit/register-admin.test.ts b/tests/unit/register-admin.test.ts
index 480a5751..b3ac1134 100644
--- a/tests/unit/register-admin.test.ts
+++ b/tests/unit/register-admin.test.ts
@@ -42,7 +42,9 @@ import { createAdminCommand } from '../../src/cli/commands/service-factory';
 import { confirm } from '../../src/utils/confirm';
 
 const mockLogger = Logger as jest.Mocked<typeof Logger>;
-const mockCreateAdmin = createAdminCommand as jest.MockedFunction<typeof createAdminCommand>;
+const mockCreateAdmin = createAdminCommand as jest.MockedFunction<
+  typeof createAdminCommand
+>;
 const mockConfirm = confirm as jest.MockedFunction<typeof confirm>;
 
 describe('registerAdmin', () => {
@@ -84,7 +86,15 @@ describe('registerAdmin', () => {
       const keys = [{ keyId: 'k1' }];
       mockAdmin.listKeys.mockResolvedValue(keys);
 
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'list', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'list',
+        '--format',
+        'json',
+      ]);
 
       expect(mockAdmin.formatJson).toHaveBeenCalledWith(keys);
       expect(mockLogger.output).toHaveBeenCalledWith('{"json":true}');
@@ -117,7 +127,15 @@ describe('registerAdmin', () => {
       const key = { keyId: 'new-key', label: 'My Key' };
       mockAdmin.createKey.mockResolvedValue(key);
 
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'create', '--label', 'My Key']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'create',
+        '--label',
+        'My Key',
+      ]);
 
       expect(mockAdmin.createKey).toHaveBeenCalledWith('My Key');
     });
@@ -126,7 +144,15 @@ describe('registerAdmin', () => {
       const key = { keyId: 'new-key' };
       mockAdmin.createKey.mockResolvedValue(key);
 
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'create', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'create',
+        '--format',
+        'json',
+      ]);
 
       expect(mockAdmin.formatJson).toHaveBeenCalledWith(key);
       expect(mockLogger.output).toHaveBeenCalledWith('{"json":true}');
@@ -145,7 +171,15 @@ describe('registerAdmin', () => {
 
   describe('admin keys deactivate', () => {
     it('should deactivate key with --yes flag (skip confirmation)', async () => {
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'deactivate', 'key-99', '--yes']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'deactivate',
+        'key-99',
+        '--yes',
+      ]);
 
       expect(mockAdmin.deactivateKey).toHaveBeenCalledWith('key-99');
       expect(mockLogger.success).toHaveBeenCalled();
@@ -154,7 +188,14 @@ describe('registerAdmin', () => {
     it('should deactivate key after user confirms', async () => {
       mockConfirm.mockResolvedValue(true);
 
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'deactivate', 'key-42']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'deactivate',
+        'key-42',
+      ]);
 
       expect(mockConfirm).toHaveBeenCalledWith({
         message: 'Deactivate API key "key-42"? This action is permanent.',
@@ -165,7 +206,14 @@ describe('registerAdmin', () => {
     it('should abort when user declines confirmation', async () => {
       mockConfirm.mockResolvedValue(false);
 
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'deactivate', 'key-42']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'deactivate',
+        'key-42',
+      ]);
 
       expect(mockLogger.info).toHaveBeenCalledWith('Aborted.');
       expect(mockAdmin.deactivateKey).not.toHaveBeenCalled();
@@ -175,7 +223,15 @@ describe('registerAdmin', () => {
       const err = new Error('deactivate failed');
       mockAdmin.deactivateKey.mockRejectedValue(err);
 
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'deactivate', 'key-1', '-y']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'deactivate',
+        'key-1',
+        '-y',
+      ]);
 
       expect(handleError).toHaveBeenCalledWith(err);
     });
@@ -183,7 +239,15 @@ describe('registerAdmin', () => {
 
   describe('admin keys rename', () => {
     it('should rename a key', async () => {
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'rename', 'key-5', 'New Label']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'rename',
+        'key-5',
+        'New Label',
+      ]);
 
       expect(mockCreateAdmin).toHaveBeenCalledWith(mockCreateDeepLClient);
       expect(mockAdmin.renameKey).toHaveBeenCalledWith('key-5', 'New Label');
@@ -194,7 +258,15 @@ describe('registerAdmin', () => {
       const err = new Error('rename failed');
       mockAdmin.renameKey.mockRejectedValue(err);
 
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'rename', 'key-5', 'label']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'rename',
+        'key-5',
+        'label',
+      ]);
 
       expect(handleError).toHaveBeenCalledWith(err);
     });
@@ -202,24 +274,58 @@ describe('registerAdmin', () => {
 
   describe('admin keys set-limit', () => {
     it('should set a numeric character limit', async () => {
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'set-limit', 'key-7', '500000']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'set-limit',
+        'key-7',
+        '500000',
+      ]);
 
-      expect(mockAdmin.setKeyLimit).toHaveBeenCalledWith('key-7', 500000, undefined);
+      expect(mockAdmin.setKeyLimit).toHaveBeenCalledWith(
+        'key-7',
+        500000,
+        undefined
+      );
       expect(mockLogger.success).toHaveBeenCalled();
     });
 
     it('should set unlimited limit', async () => {
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'set-limit', 'key-7', 'unlimited']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'set-limit',
+        'key-7',
+        'unlimited',
+      ]);
 
-      expect(mockAdmin.setKeyLimit).toHaveBeenCalledWith('key-7', null, undefined);
+      expect(mockAdmin.setKeyLimit).toHaveBeenCalledWith(
+        'key-7',
+        null,
+        undefined
+      );
       expect(mockLogger.success).toHaveBeenCalled();
     });
 
     it('should call handleError for non-numeric characters value', async () => {
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'set-limit', 'key-7', 'abc']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'set-limit',
+        'key-7',
+        'abc',
+      ]);
 
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: 'Characters must be a number or "unlimited"' }),
+        expect.objectContaining({
+          message: 'Characters must be a number or "unlimited"',
+        })
       );
     });
 
@@ -227,7 +333,15 @@ describe('registerAdmin', () => {
       const err = new Error('set-limit failed');
       mockAdmin.setKeyLimit.mockRejectedValue(err);
 
-      await program.parseAsync(['node', 'test', 'admin', 'keys', 'set-limit', 'key-7', '100']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'admin',
+        'keys',
+        'set-limit',
+        'key-7',
+        '100',
+      ]);
 
       expect(handleError).toHaveBeenCalledWith(err);
     });
@@ -239,8 +353,14 @@ describe('registerAdmin', () => {
       mockAdmin.getUsage.mockResolvedValue(report);
 
       await program.parseAsync([
-        'node', 'test', 'admin', 'usage',
-        '--start', '2024-01-01', '--end', '2024-01-31',
+        'node',
+        'test',
+        'admin',
+        'usage',
+        '--start',
+        '2024-01-01',
+        '--end',
+        '2024-01-31',
       ]);
 
       expect(mockCreateAdmin).toHaveBeenCalledWith(mockCreateDeepLClient);
@@ -258,9 +378,16 @@ describe('registerAdmin', () => {
       mockAdmin.getUsage.mockResolvedValue(report);
 
       await program.parseAsync([
-        'node', 'test', 'admin', 'usage',
-        '--start', '2024-02-01', '--end', '2024-02-28',
-        '--format', 'json',
+        'node',
+        'test',
+        'admin',
+        'usage',
+        '--start',
+        '2024-02-01',
+        '--end',
+        '2024-02-28',
+        '--format',
+        'json',
       ]);
 
       expect(mockAdmin.formatJson).toHaveBeenCalledWith(report);
@@ -271,13 +398,20 @@ describe('registerAdmin', () => {
       mockAdmin.getUsage.mockResolvedValue({});
 
       await program.parseAsync([
-        'node', 'test', 'admin', 'usage',
-        '--start', '2024-01-01', '--end', '2024-01-31',
-        '--group-by', 'key',
+        'node',
+        'test',
+        'admin',
+        'usage',
+        '--start',
+        '2024-01-01',
+        '--end',
+        '2024-01-31',
+        '--group-by',
+        'key',
       ]);
 
       expect(mockAdmin.getUsage).toHaveBeenCalledWith(
-        expect.objectContaining({ groupBy: 'key' }),
+        expect.objectContaining({ groupBy: 'key' })
       );
     });
 
@@ -286,8 +420,14 @@ describe('registerAdmin', () => {
       mockAdmin.getUsage.mockRejectedValue(err);
 
       await program.parseAsync([
-        'node', 'test', 'admin', 'usage',
-        '--start', '2024-01-01', '--end', '2024-01-31',
+        'node',
+        'test',
+        'admin',
+        'usage',
+        '--start',
+        '2024-01-01',
+        '--end',
+        '2024-01-31',
       ]);
 
       expect(handleError).toHaveBeenCalledWith(err);
diff --git a/tests/unit/register-cache-registration.test.ts b/tests/unit/register-cache-registration.test.ts
index 4535a6f6..c8a6fb68 100644
--- a/tests/unit/register-cache-registration.test.ts
+++ b/tests/unit/register-cache-registration.test.ts
@@ -1,4 +1,3 @@
- 
 import { Command } from 'commander';
 
 jest.mock('chalk', () => {
@@ -34,13 +33,24 @@ const mockCacheCommandInstance = {
   disable: jest.fn(),
 };
 
-async function withTTY<T>(value: boolean, fn: () => Promise<T> | T): Promise<T> {
+async function withTTY<T>(
+  value: boolean,
+  fn: () => Promise<T> | T
+): Promise<T> {
   const original = process.stdout.isTTY;
-  Object.defineProperty(process.stdout, 'isTTY', { value, configurable: true, writable: true });
+  Object.defineProperty(process.stdout, 'isTTY', {
+    value,
+    configurable: true,
+    writable: true,
+  });
   try {
     return await fn();
   } finally {
-    Object.defineProperty(process.stdout, 'isTTY', { value: original, configurable: true, writable: true });
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: original,
+      configurable: true,
+      writable: true,
+    });
   }
 }
 
@@ -55,11 +65,17 @@ jest.mock('../../src/utils/confirm', () => ({
 
 jest.mock('../../src/utils/parse-size', () => ({
   parseSize: jest.fn().mockImplementation((s: string) => {
-    if (s === '100M') { return 104857600; }
-    if (s === '1G') { return 1073741824; }
+    if (s === '100M') {
+      return 104857600;
+    }
+    if (s === '1G') {
+      return 1073741824;
+    }
     return parseInt(s, 10);
   }),
-  formatSize: jest.fn().mockImplementation((n: number) => `${(n / (1024 * 1024)).toFixed(0)} MB`),
+  formatSize: jest
+    .fn()
+    .mockImplementation((n: number) => `${(n / (1024 * 1024)).toFixed(0)} MB`),
 }));
 
 import { registerCache } from '../../src/cli/commands/register-cache';
@@ -74,7 +90,9 @@ describe('registerCache', () => {
   beforeEach(() => {
     jest.clearAllMocks();
     const { CacheCommand } = require('../../src/cli/commands/cache');
-    (CacheCommand as jest.Mock).mockImplementation(() => mockCacheCommandInstance);
+    (CacheCommand as jest.Mock).mockImplementation(
+      () => mockCacheCommandInstance
+    );
 
     program = new Command();
     program.exitOverride();
@@ -95,46 +113,94 @@ describe('registerCache', () => {
     });
 
     it('should call handleError on failure', async () => {
-      mockCacheCommandInstance.stats.mockRejectedValue(new Error('stats failed'));
+      mockCacheCommandInstance.stats.mockRejectedValue(
+        new Error('stats failed')
+      );
       await program.parseAsync(['node', 'test', 'cache', 'stats']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'stats failed' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'stats failed' })
+      );
     });
 
     it('should output JSON with --format json', async () => {
-      const stats = { entries: 10, totalSize: 5000, maxSize: 1048576, enabled: true };
+      const stats = {
+        entries: 10,
+        totalSize: 5000,
+        maxSize: 1048576,
+        enabled: true,
+      };
       mockCacheCommandInstance.stats.mockResolvedValue(stats);
-      await program.parseAsync(['node', 'test', 'cache', 'stats', '--format', 'json']);
-      expect(Logger.output).toHaveBeenCalledWith(JSON.stringify(stats, null, 2));
+      await program.parseAsync([
+        'node',
+        'test',
+        'cache',
+        'stats',
+        '--format',
+        'json',
+      ]);
+      expect(Logger.output).toHaveBeenCalledWith(
+        JSON.stringify(stats, null, 2)
+      );
       expect(mockCacheCommandInstance.formatStats).not.toHaveBeenCalled();
     });
 
     it('should render cli-table3 output when --format table and stdout is a TTY', async () => {
-      const stats = { entries: 10, totalSize: 5000, maxSize: 1048576, enabled: true };
+      const stats = {
+        entries: 10,
+        totalSize: 5000,
+        maxSize: 1048576,
+        enabled: true,
+      };
       mockCacheCommandInstance.stats.mockResolvedValue(stats);
       mockCacheCommandInstance.formatStatsTable.mockReturnValue('stats-table');
 
       await withTTY(true, async () => {
-        await program.parseAsync(['node', 'test', 'cache', 'stats', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'cache',
+          'stats',
+          '--format',
+          'table',
+        ]);
       });
 
-      expect(mockCacheCommandInstance.formatStatsTable).toHaveBeenCalledWith(stats);
+      expect(mockCacheCommandInstance.formatStatsTable).toHaveBeenCalledWith(
+        stats
+      );
       expect(mockCacheCommandInstance.formatStats).not.toHaveBeenCalled();
       expect(Logger.output).toHaveBeenCalledWith('stats-table');
-      expect(Logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
+      expect(Logger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining('non-TTY')
+      );
     });
 
     it('should fall back to plain text with a warn when --format table in non-TTY', async () => {
-      const stats = { entries: 10, totalSize: 5000, maxSize: 1048576, enabled: true };
+      const stats = {
+        entries: 10,
+        totalSize: 5000,
+        maxSize: 1048576,
+        enabled: true,
+      };
       mockCacheCommandInstance.stats.mockResolvedValue(stats);
       mockCacheCommandInstance.formatStats.mockReturnValue('plain stats');
 
       await withTTY(false, async () => {
-        await program.parseAsync(['node', 'test', 'cache', 'stats', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'cache',
+          'stats',
+          '--format',
+          'table',
+        ]);
       });
 
       expect(mockCacheCommandInstance.formatStatsTable).not.toHaveBeenCalled();
       expect(mockCacheCommandInstance.formatStats).toHaveBeenCalledWith(stats);
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('non-TTY')
+      );
       expect(Logger.output).toHaveBeenCalledWith('plain stats');
     });
   });
@@ -145,15 +211,20 @@ describe('registerCache', () => {
       ['clear', ['cache', 'clear', '--yes']],
       ['enable', ['cache', 'enable']],
       ['disable', ['cache', 'disable']],
-    ])('cache %s reports a clear error when getCacheService resolves undefined', async (_name, args) => {
-      getCacheService.mockResolvedValue(undefined);
-      await program.parseAsync(['node', 'test', ...args]);
-      expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringMatching(/cache.*unavailable/i) }),
-      );
-      const { CacheCommand } = require('../../src/cli/commands/cache');
-      expect(CacheCommand as jest.Mock).not.toHaveBeenCalled();
-    });
+    ])(
+      'cache %s reports a clear error when getCacheService resolves undefined',
+      async (_name, args) => {
+        getCacheService.mockResolvedValue(undefined);
+        await program.parseAsync(['node', 'test', ...args]);
+        expect(handleError).toHaveBeenCalledWith(
+          expect.objectContaining({
+            message: expect.stringMatching(/cache.*unavailable/i),
+          })
+        );
+        const { CacheCommand } = require('../../src/cli/commands/cache');
+        expect(CacheCommand as jest.Mock).not.toHaveBeenCalled();
+      }
+    );
   });
 
   describe('cache clear', () => {
@@ -162,7 +233,9 @@ describe('registerCache', () => {
       await program.parseAsync(['node', 'test', 'cache', 'clear', '--yes']);
       expect(mockConfirm).not.toHaveBeenCalled();
       expect(mockCacheCommandInstance.clear).toHaveBeenCalled();
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Cache cleared'));
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Cache cleared')
+      );
     });
 
     it('should prompt and clear when confirmed', async () => {
@@ -186,13 +259,19 @@ describe('registerCache', () => {
       mockCacheCommandInstance.stats.mockResolvedValue(stats);
       await program.parseAsync(['node', 'test', 'cache', 'clear', '--dry-run']);
       expect(mockCacheCommandInstance.clear).not.toHaveBeenCalled();
-      expect(Logger.output).toHaveBeenCalledWith(expect.stringContaining('dry-run'));
+      expect(Logger.output).toHaveBeenCalledWith(
+        expect.stringContaining('dry-run')
+      );
     });
 
     it('should call handleError on failure', async () => {
-      mockCacheCommandInstance.clear.mockRejectedValue(new Error('clear failed'));
+      mockCacheCommandInstance.clear.mockRejectedValue(
+        new Error('clear failed')
+      );
       await program.parseAsync(['node', 'test', 'cache', 'clear', '-y']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'clear failed' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'clear failed' })
+      );
     });
   });
 
@@ -201,21 +280,38 @@ describe('registerCache', () => {
       mockCacheCommandInstance.enable.mockResolvedValue(undefined);
       await program.parseAsync(['node', 'test', 'cache', 'enable']);
       expect(mockCacheCommandInstance.enable).toHaveBeenCalledWith(undefined);
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Cache enabled'));
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Cache enabled')
+      );
     });
 
     it('should enable cache with --max-size', async () => {
       mockCacheCommandInstance.enable.mockResolvedValue(undefined);
-      await program.parseAsync(['node', 'test', 'cache', 'enable', '--max-size', '100M']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'cache',
+        'enable',
+        '--max-size',
+        '100M',
+      ]);
       expect(mockCacheCommandInstance.enable).toHaveBeenCalledWith(104857600);
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Cache enabled'));
-      expect(Logger.info).toHaveBeenCalledWith(expect.stringContaining('Max size'));
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Cache enabled')
+      );
+      expect(Logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('Max size')
+      );
     });
 
     it('should call handleError on failure', async () => {
-      mockCacheCommandInstance.enable.mockRejectedValue(new Error('enable failed'));
+      mockCacheCommandInstance.enable.mockRejectedValue(
+        new Error('enable failed')
+      );
       await program.parseAsync(['node', 'test', 'cache', 'enable']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'enable failed' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'enable failed' })
+      );
     });
   });
 
@@ -224,13 +320,19 @@ describe('registerCache', () => {
       mockCacheCommandInstance.disable.mockResolvedValue(undefined);
       await program.parseAsync(['node', 'test', 'cache', 'disable']);
       expect(mockCacheCommandInstance.disable).toHaveBeenCalled();
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Cache disabled'));
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Cache disabled')
+      );
     });
 
     it('should call handleError on failure', async () => {
-      mockCacheCommandInstance.disable.mockRejectedValue(new Error('disable failed'));
+      mockCacheCommandInstance.disable.mockRejectedValue(
+        new Error('disable failed')
+      );
       await program.parseAsync(['node', 'test', 'cache', 'disable']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'disable failed' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'disable failed' })
+      );
     });
   });
 });
diff --git a/tests/unit/register-commands-group1.test.ts b/tests/unit/register-commands-group1.test.ts
index b090bd6c..a6489816 100644
--- a/tests/unit/register-commands-group1.test.ts
+++ b/tests/unit/register-commands-group1.test.ts
@@ -3,8 +3,6 @@
  *   register-auth, register-usage, register-completion, register-style-rules
  */
 
- 
-
 import { Command } from 'commander';
 
 // ── Mock chalk ──────────────────────────────────────────────────────────────
@@ -140,7 +138,10 @@ function resetAllMockImplementations() {
   mockClearKey.mockResolvedValue(undefined);
 
   // Usage mock functions
-  mockUsageGetUsage.mockResolvedValue({ characterCount: 100, characterLimit: 500000 });
+  mockUsageGetUsage.mockResolvedValue({
+    characterCount: 100,
+    characterLimit: 500000,
+  });
   mockUsageFormatUsage.mockReturnValue('Usage: 100/500000');
 
   // Style rules mock functions
@@ -161,8 +162,12 @@ function resetAllMockImplementations() {
   const { TranslationService } = require('../../src/services/translation');
   TranslationService.mockImplementation(() => mockTranslationServiceObj);
 
-  const { DocumentTranslationService } = require('../../src/services/document-translation');
-  DocumentTranslationService.mockImplementation(() => mockDocTranslationServiceObj);
+  const {
+    DocumentTranslationService,
+  } = require('../../src/services/document-translation');
+  DocumentTranslationService.mockImplementation(
+    () => mockDocTranslationServiceObj
+  );
 
   const { AdminService } = require('../../src/services/admin');
   AdminService.mockImplementation(() => mockAdminServiceObj);
@@ -248,7 +253,8 @@ describe('service-factory', () => {
   });
 
   it('createGlossaryCommand should create client, GlossaryService, and GlossaryCommand', async () => {
-    const { createGlossaryCommand } = await import('../../src/cli/commands/service-factory');
+    const { createGlossaryCommand } =
+      await import('../../src/cli/commands/service-factory');
     const cmd = await createGlossaryCommand(createDeepLClient);
 
     expect(createDeepLClient).toHaveBeenCalledWith();
@@ -260,7 +266,8 @@ describe('service-factory', () => {
   });
 
   it('createAdminCommand should create client, AdminService, and AdminCommand', async () => {
-    const { createAdminCommand } = await import('../../src/cli/commands/service-factory');
+    const { createAdminCommand } =
+      await import('../../src/cli/commands/service-factory');
     const cmd = await createAdminCommand(createDeepLClient);
 
     expect(createDeepLClient).toHaveBeenCalledWith();
@@ -272,7 +279,8 @@ describe('service-factory', () => {
   });
 
   it('createWriteCommand should create client, WriteService, and WriteCommand', async () => {
-    const { createWriteCommand } = await import('../../src/cli/commands/service-factory');
+    const { createWriteCommand } =
+      await import('../../src/cli/commands/service-factory');
     const cmd = await createWriteCommand({
       createDeepLClient,
       getConfigService: () => mockConfigService as any,
@@ -281,14 +289,19 @@ describe('service-factory', () => {
 
     expect(createDeepLClient).toHaveBeenCalledWith();
     const { WriteService } = require('../../src/services/write');
-    expect(WriteService).toHaveBeenCalledWith(mockClient, mockConfigService, mockCacheService);
+    expect(WriteService).toHaveBeenCalledWith(
+      mockClient,
+      mockConfigService,
+      mockCacheService
+    );
     const { WriteCommand } = require('../../src/cli/commands/write');
     expect(WriteCommand).toHaveBeenCalledWith(mockWriteServiceObj);
     expect(cmd).toBe(mockWriteCmdObj);
   });
 
   it('createStyleRulesCommand should create client, StyleRulesService, and StyleRulesCommand', async () => {
-    const { createStyleRulesCommand } = await import('../../src/cli/commands/service-factory');
+    const { createStyleRulesCommand } =
+      await import('../../src/cli/commands/service-factory');
     const cmd = await createStyleRulesCommand(createDeepLClient);
 
     expect(createDeepLClient).toHaveBeenCalledWith();
@@ -300,7 +313,8 @@ describe('service-factory', () => {
   });
 
   it('createUsageCommand should create client, UsageService, and UsageCommand', async () => {
-    const { createUsageCommand } = await import('../../src/cli/commands/service-factory');
+    const { createUsageCommand } =
+      await import('../../src/cli/commands/service-factory');
     const cmd = await createUsageCommand(createDeepLClient);
 
     expect(createDeepLClient).toHaveBeenCalledWith();
@@ -315,7 +329,8 @@ describe('service-factory', () => {
     const getConfigService = jest.fn().mockReturnValue(mockConfigService);
     const getCacheService = jest.fn().mockResolvedValue(mockCacheService);
 
-    const { createTranslateCommand } = await import('../../src/cli/commands/service-factory');
+    const { createTranslateCommand } =
+      await import('../../src/cli/commands/service-factory');
     const cmd = await createTranslateCommand({
       createDeepLClient,
       getConfigService,
@@ -326,8 +341,14 @@ describe('service-factory', () => {
     expect(getConfigService).toHaveBeenCalled();
     expect(getCacheService).toHaveBeenCalled();
     const { TranslationService } = require('../../src/services/translation');
-    expect(TranslationService).toHaveBeenCalledWith(mockClient, mockConfigService, mockCacheService);
-    const { DocumentTranslationService } = require('../../src/services/document-translation');
+    expect(TranslationService).toHaveBeenCalledWith(
+      mockClient,
+      mockConfigService,
+      mockCacheService
+    );
+    const {
+      DocumentTranslationService,
+    } = require('../../src/services/document-translation');
     expect(DocumentTranslationService).toHaveBeenCalledWith(mockClient);
     const { GlossaryService } = require('../../src/services/glossary');
     expect(GlossaryService).toHaveBeenCalledWith(mockClient);
@@ -336,20 +357,21 @@ describe('service-factory', () => {
       mockTranslationServiceObj,
       mockDocTranslationServiceObj,
       mockGlossaryServiceObj,
-      mockConfigService,
+      mockConfigService
     );
     expect(cmd).toBe(mockTranslateCmdObj);
   });
 
   it('createTranslateCommand should forward overrideBaseUrl', async () => {
-    const { createTranslateCommand } = await import('../../src/cli/commands/service-factory');
+    const { createTranslateCommand } =
+      await import('../../src/cli/commands/service-factory');
     await createTranslateCommand(
       {
         createDeepLClient,
         getConfigService: jest.fn().mockReturnValue(mockConfigService),
         getCacheService: jest.fn().mockResolvedValue(mockCacheService),
       },
-      'http://localhost:9999',
+      'http://localhost:9999'
     );
 
     expect(createDeepLClient).toHaveBeenCalledWith('http://localhost:9999');
@@ -359,7 +381,8 @@ describe('service-factory', () => {
     const getConfigService = jest.fn().mockReturnValue(mockConfigService);
     const getCacheService = jest.fn().mockResolvedValue(mockCacheService);
 
-    const { createWatchCommand } = await import('../../src/cli/commands/service-factory');
+    const { createWatchCommand } =
+      await import('../../src/cli/commands/service-factory');
     const cmd = await createWatchCommand({
       createDeepLClient,
       getConfigService,
@@ -368,7 +391,11 @@ describe('service-factory', () => {
 
     expect(createDeepLClient).toHaveBeenCalledWith();
     const { TranslationService } = require('../../src/services/translation');
-    expect(TranslationService).toHaveBeenCalledWith(mockClient, mockConfigService, mockCacheService);
+    expect(TranslationService).toHaveBeenCalledWith(
+      mockClient,
+      mockConfigService,
+      mockCacheService
+    );
     const { GlossaryService } = require('../../src/services/glossary');
     expect(GlossaryService).toHaveBeenCalledWith(mockClient);
     const { WatchCommand } = require('../../src/cli/commands/watch');
@@ -377,14 +404,17 @@ describe('service-factory', () => {
     expect(WatchCommand).toHaveBeenCalledWith(
       mockTranslationServiceObj,
       mockGlossaryServiceObj,
-      mockConfigService,
+      mockConfigService
     );
     expect(cmd).toBe(mockWatchCmdObj);
   });
 
   it('createVoiceCommand should wire up VoiceClient, VoiceService, and VoiceCommand', async () => {
-    const getApiKeyAndOptions = jest.fn().mockReturnValue({ apiKey: 'test-key', options: { usePro: true } });
-    const { createVoiceCommand } = await import('../../src/cli/commands/service-factory');
+    const getApiKeyAndOptions = jest
+      .fn()
+      .mockReturnValue({ apiKey: 'test-key', options: { usePro: true } });
+    const { createVoiceCommand } =
+      await import('../../src/cli/commands/service-factory');
     const cmd = await createVoiceCommand(getApiKeyAndOptions);
 
     expect(getApiKeyAndOptions).toHaveBeenCalled();
@@ -429,7 +459,8 @@ describe('registerAuth', () => {
   });
 
   async function loadAndRegister() {
-    const { registerAuth } = await import('../../src/cli/commands/register-auth');
+    const { registerAuth } =
+      await import('../../src/cli/commands/register-auth');
     registerAuth(program, { getConfigService, handleError } as any);
   }
 
@@ -461,15 +492,27 @@ describe('registerAuth', () => {
     await loadAndRegister();
     await program.parseAsync(['node', 'test', 'auth', 'show']);
 
-    expect(mockLogger.output).toHaveBeenCalledWith(expect.stringContaining('No API key set'));
+    expect(mockLogger.output).toHaveBeenCalledWith(
+      expect.stringContaining('No API key set')
+    );
   });
 
   it('auth set-key should save and report success', async () => {
     await loadAndRegister();
-    await program.parseAsync(['node', 'test', 'auth', 'set-key', 'my-api-key-12345']);
+    await program.parseAsync([
+      'node',
+      'test',
+      'auth',
+      'set-key',
+      'my-api-key-12345',
+    ]);
 
-    expect(mockSetKey).toHaveBeenCalledWith('my-api-key-12345', { verify: true });
-    expect(mockLogger.success).toHaveBeenCalledWith(expect.stringContaining('API key saved'));
+    expect(mockSetKey).toHaveBeenCalledWith('my-api-key-12345', {
+      verify: true,
+    });
+    expect(mockLogger.success).toHaveBeenCalledWith(
+      expect.stringContaining('API key saved')
+    );
   });
 
   it('auth set-key should call handleError on failure', async () => {
@@ -478,7 +521,7 @@ describe('registerAuth', () => {
 
     await loadAndRegister();
     await expect(
-      program.parseAsync(['node', 'test', 'auth', 'set-key', 'bad-key']),
+      program.parseAsync(['node', 'test', 'auth', 'set-key', 'bad-key'])
     ).rejects.toThrow('Validation failed');
 
     expect(handleError).toHaveBeenCalledWith(setKeyError);
@@ -489,7 +532,9 @@ describe('registerAuth', () => {
     await program.parseAsync(['node', 'test', 'auth', 'clear']);
 
     expect(mockClearKey).toHaveBeenCalled();
-    expect(mockLogger.success).toHaveBeenCalledWith(expect.stringContaining('API key removed'));
+    expect(mockLogger.success).toHaveBeenCalledWith(
+      expect.stringContaining('API key removed')
+    );
   });
 
   it('auth clear should call handleError on failure', async () => {
@@ -498,7 +543,7 @@ describe('registerAuth', () => {
 
     await loadAndRegister();
     await expect(
-      program.parseAsync(['node', 'test', 'auth', 'clear']),
+      program.parseAsync(['node', 'test', 'auth', 'clear'])
     ).rejects.toThrow('Config write failure');
 
     expect(handleError).toHaveBeenCalledWith(clearError);
@@ -510,7 +555,7 @@ describe('registerAuth', () => {
 
     await loadAndRegister();
     await expect(
-      program.parseAsync(['node', 'test', 'auth', 'show']),
+      program.parseAsync(['node', 'test', 'auth', 'show'])
     ).rejects.toThrow('Read failure');
 
     expect(handleError).toHaveBeenCalledWith(showError);
@@ -538,7 +583,8 @@ describe('registerUsage', () => {
   });
 
   async function loadAndRegister() {
-    const { registerUsage } = await import('../../src/cli/commands/register-usage');
+    const { registerUsage } =
+      await import('../../src/cli/commands/register-usage');
     registerUsage(program, { createDeepLClient, handleError } as any);
   }
 
@@ -547,7 +593,10 @@ describe('registerUsage', () => {
     await program.parseAsync(['node', 'test', 'usage']);
 
     expect(mockUsageGetUsage).toHaveBeenCalled();
-    expect(mockUsageFormatUsage).toHaveBeenCalledWith({ characterCount: 100, characterLimit: 500000 });
+    expect(mockUsageFormatUsage).toHaveBeenCalledWith({
+      characterCount: 100,
+      characterLimit: 500000,
+    });
     expect(mockLogger.output).toHaveBeenCalledWith('Usage: 100/500000');
   });
 
@@ -556,9 +605,9 @@ describe('registerUsage', () => {
     mockUsageGetUsage.mockRejectedValue(usageError);
 
     await loadAndRegister();
-    await expect(
-      program.parseAsync(['node', 'test', 'usage']),
-    ).rejects.toThrow('API unavailable');
+    await expect(program.parseAsync(['node', 'test', 'usage'])).rejects.toThrow(
+      'API unavailable'
+    );
 
     expect(handleError).toHaveBeenCalledWith(usageError);
   });
@@ -583,17 +632,21 @@ describe('registerCompletion', () => {
   });
 
   async function loadAndRegister() {
-    const { registerCompletion } = await import('../../src/cli/commands/register-completion');
+    const { registerCompletion } =
+      await import('../../src/cli/commands/register-completion');
     registerCompletion(program, { handleError } as any);
   }
 
-  it.each(['bash', 'zsh', 'fish'])('should generate completion script for %s', async (shell) => {
-    await loadAndRegister();
-    await program.parseAsync(['node', 'test', 'completion', shell]);
+  it.each(['bash', 'zsh', 'fish'])(
+    'should generate completion script for %s',
+    async (shell) => {
+      await loadAndRegister();
+      await program.parseAsync(['node', 'test', 'completion', shell]);
 
-    expect(mockCompletionGenerate).toHaveBeenCalledWith(shell);
-    expect(mockLogger.output).toHaveBeenCalledWith('# completion script');
-  });
+      expect(mockCompletionGenerate).toHaveBeenCalledWith(shell);
+      expect(mockLogger.output).toHaveBeenCalledWith('# completion script');
+    }
+  );
 
   it('should handle case-insensitive shell names', async () => {
     await loadAndRegister();
@@ -606,11 +659,13 @@ describe('registerCompletion', () => {
   it('should call handleError for unsupported shell', async () => {
     await loadAndRegister();
     await expect(
-      program.parseAsync(['node', 'test', 'completion', 'powershell']),
+      program.parseAsync(['node', 'test', 'completion', 'powershell'])
     ).rejects.toThrow('Unsupported shell');
 
     expect(handleError).toHaveBeenCalledWith(
-      expect.objectContaining({ message: expect.stringContaining('Unsupported shell') }),
+      expect.objectContaining({
+        message: expect.stringContaining('Unsupported shell'),
+      })
     );
   });
 
@@ -652,7 +707,8 @@ describe('registerStyleRules', () => {
   });
 
   async function loadAndRegister() {
-    const { registerStyleRules } = await import('../../src/cli/commands/register-style-rules');
+    const { registerStyleRules } =
+      await import('../../src/cli/commands/register-style-rules');
     registerStyleRules(program, { createDeepLClient, handleError } as any);
   }
 
@@ -667,7 +723,14 @@ describe('registerStyleRules', () => {
 
   it('style-rules list --format json should display JSON output', async () => {
     await loadAndRegister();
-    await program.parseAsync(['node', 'test', 'style-rules', 'list', '--format', 'json']);
+    await program.parseAsync([
+      'node',
+      'test',
+      'style-rules',
+      'list',
+      '--format',
+      'json',
+    ]);
 
     expect(mockStyleRulesList).toHaveBeenCalled();
     expect(mockStyleRulesFormatJson).toHaveBeenCalledWith([]);
@@ -676,23 +739,34 @@ describe('registerStyleRules', () => {
 
   it('style-rules list --detailed should pass detailed option', async () => {
     await loadAndRegister();
-    await program.parseAsync(['node', 'test', 'style-rules', 'list', '--detailed']);
+    await program.parseAsync([
+      'node',
+      'test',
+      'style-rules',
+      'list',
+      '--detailed',
+    ]);
 
     expect(mockStyleRulesList).toHaveBeenCalledWith(
-      expect.objectContaining({ detailed: true }),
+      expect.objectContaining({ detailed: true })
     );
   });
 
   it('style-rules list should pass pagination options', async () => {
     await loadAndRegister();
     await program.parseAsync([
-      'node', 'test', 'style-rules', 'list',
-      '--page', '2',
-      '--page-size', '10',
+      'node',
+      'test',
+      'style-rules',
+      'list',
+      '--page',
+      '2',
+      '--page-size',
+      '10',
     ]);
 
     expect(mockStyleRulesList).toHaveBeenCalledWith(
-      expect.objectContaining({ page: 2, pageSize: 10 }),
+      expect.objectContaining({ page: 2, pageSize: 10 })
     );
   });
 
@@ -702,7 +776,7 @@ describe('registerStyleRules', () => {
 
     await loadAndRegister();
     await expect(
-      program.parseAsync(['node', 'test', 'style-rules', 'list']),
+      program.parseAsync(['node', 'test', 'style-rules', 'list'])
     ).rejects.toThrow('Pro API required');
 
     expect(handleError).toHaveBeenCalledWith(apiError);
diff --git a/tests/unit/register-config.test.ts b/tests/unit/register-config.test.ts
index 5968629d..bca1ca69 100644
--- a/tests/unit/register-config.test.ts
+++ b/tests/unit/register-config.test.ts
@@ -1,4 +1,3 @@
- 
 import { Command } from 'commander';
 
 jest.mock('chalk', () => {
@@ -53,7 +52,9 @@ describe('registerConfig', () => {
     jest.clearAllMocks();
     // Re-setup the ConfigCommand constructor after clearAllMocks
     const { ConfigCommand } = require('../../src/cli/commands/config');
-    (ConfigCommand as jest.Mock).mockImplementation(() => mockConfigCommandInstance);
+    (ConfigCommand as jest.Mock).mockImplementation(
+      () => mockConfigCommandInstance
+    );
 
     program = new Command();
     program.exitOverride();
@@ -64,9 +65,17 @@ describe('registerConfig', () => {
   describe('config get', () => {
     it('should get and output a config value', async () => {
       mockConfigCommandInstance.get.mockResolvedValue('some-value');
-      await program.parseAsync(['node', 'test', 'config', 'get', 'auth.apiKey']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'config',
+        'get',
+        'auth.apiKey',
+      ]);
       expect(mockConfigCommandInstance.get).toHaveBeenCalledWith('auth.apiKey');
-      expect(Logger.output).toHaveBeenCalledWith(JSON.stringify('some-value', null, 2));
+      expect(Logger.output).toHaveBeenCalledWith(
+        JSON.stringify('some-value', null, 2)
+      );
     });
 
     it('should handle get with no key', async () => {
@@ -84,30 +93,60 @@ describe('registerConfig', () => {
     it('should call handleError on failure', async () => {
       mockConfigCommandInstance.get.mockRejectedValue(new Error('get failed'));
       await program.parseAsync(['node', 'test', 'config', 'get', 'key']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'get failed' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'get failed' })
+      );
     });
   });
 
   describe('config set', () => {
     it('should set a config value', async () => {
       mockConfigCommandInstance.set.mockResolvedValue(undefined);
-      await program.parseAsync(['node', 'test', 'config', 'set', 'api.usePro', 'true']);
-      expect(mockConfigCommandInstance.set).toHaveBeenCalledWith('api.usePro', 'true');
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Set api.usePro = true'));
+      await program.parseAsync([
+        'node',
+        'test',
+        'config',
+        'set',
+        'api.usePro',
+        'true',
+      ]);
+      expect(mockConfigCommandInstance.set).toHaveBeenCalledWith(
+        'api.usePro',
+        'true'
+      );
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Set api.usePro = true')
+      );
     });
 
     it('should mask API key in success message', async () => {
       mockConfigCommandInstance.set.mockResolvedValue(undefined);
-      await program.parseAsync(['node', 'test', 'config', 'set', 'auth.apiKey', 'super-secret-key-123']);
-      expect(mockConfigCommandInstance.set).toHaveBeenCalledWith('auth.apiKey', 'super-secret-key-123');
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('supe...-123'));
-      expect(Logger.success).not.toHaveBeenCalledWith(expect.stringContaining('super-secret-key-123'));
+      await program.parseAsync([
+        'node',
+        'test',
+        'config',
+        'set',
+        'auth.apiKey',
+        'super-secret-key-123',
+      ]);
+      expect(mockConfigCommandInstance.set).toHaveBeenCalledWith(
+        'auth.apiKey',
+        'super-secret-key-123'
+      );
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('supe...-123')
+      );
+      expect(Logger.success).not.toHaveBeenCalledWith(
+        expect.stringContaining('super-secret-key-123')
+      );
     });
 
     it('should call handleError on failure', async () => {
       mockConfigCommandInstance.set.mockRejectedValue(new Error('set failed'));
       await program.parseAsync(['node', 'test', 'config', 'set', 'key', 'val']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'set failed' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'set failed' })
+      );
     });
   });
 
@@ -117,13 +156,19 @@ describe('registerConfig', () => {
       mockConfigCommandInstance.list.mockResolvedValue(config);
       await program.parseAsync(['node', 'test', 'config', 'list']);
       expect(mockConfigCommandInstance.list).toHaveBeenCalled();
-      expect(Logger.output).toHaveBeenCalledWith(JSON.stringify(config, null, 2));
+      expect(Logger.output).toHaveBeenCalledWith(
+        JSON.stringify(config, null, 2)
+      );
     });
 
     it('should call handleError on failure', async () => {
-      mockConfigCommandInstance.list.mockRejectedValue(new Error('list failed'));
+      mockConfigCommandInstance.list.mockRejectedValue(
+        new Error('list failed')
+      );
       await program.parseAsync(['node', 'test', 'config', 'list']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'list failed' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'list failed' })
+      );
     });
   });
 
@@ -133,7 +178,9 @@ describe('registerConfig', () => {
       await program.parseAsync(['node', 'test', 'config', 'reset', '--yes']);
       expect(mockConfirm).not.toHaveBeenCalled();
       expect(mockConfigCommandInstance.reset).toHaveBeenCalled();
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Configuration reset'));
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Configuration reset')
+      );
     });
 
     it('should prompt and proceed if confirmed', async () => {
@@ -153,9 +200,13 @@ describe('registerConfig', () => {
     });
 
     it('should call handleError on failure', async () => {
-      mockConfigCommandInstance.reset.mockRejectedValue(new Error('reset failed'));
+      mockConfigCommandInstance.reset.mockRejectedValue(
+        new Error('reset failed')
+      );
       await program.parseAsync(['node', 'test', 'config', 'reset', '-y']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'reset failed' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'reset failed' })
+      );
     });
   });
 });
diff --git a/tests/unit/register-correct.test.ts b/tests/unit/register-correct.test.ts
index 4a098310..b9157fb8 100644
--- a/tests/unit/register-correct.test.ts
+++ b/tests/unit/register-correct.test.ts
@@ -74,7 +74,12 @@ describe('registerCorrect', () => {
     createDeepLClient = jest.fn();
     getConfigService = jest.fn();
     getCacheService = jest.fn();
-    registerCorrect(program, { createDeepLClient, getConfigService, getCacheService, handleError });
+    registerCorrect(program, {
+      createDeepLClient,
+      getConfigService,
+      getCacheService,
+      handleError,
+    });
   });
 
   afterEach(() => {
@@ -83,22 +88,31 @@ describe('registerCorrect', () => {
 
   describe('registration', () => {
     it('registers correct with c as an alias', () => {
-      const correctCmd = program.commands.find(c => c.name() === 'correct')!;
+      const correctCmd = program.commands.find((c) => c.name() === 'correct')!;
       expect(correctCmd).toBeDefined();
       expect(correctCmd.aliases()).toContain('c');
     });
 
     it('does not register --style or --tone', () => {
-      const correctCmd = program.commands.find(c => c.name() === 'correct')!;
-      const longFlags = correctCmd.options.map(o => o.long);
+      const correctCmd = program.commands.find((c) => c.name() === 'correct')!;
+      const longFlags = correctCmd.options.map((o) => o.long);
       expect(longFlags).not.toContain('--style');
       expect(longFlags).not.toContain('--tone');
-      expect(longFlags).toEqual(expect.arrayContaining(['--lang', '--check', '--fix', '--diff']));
+      expect(longFlags).toEqual(
+        expect.arrayContaining(['--lang', '--check', '--fix', '--diff'])
+      );
     });
 
     it('rejects --style as an unknown option', async () => {
       await expect(
-        program.parseAsync(['node', 'test', 'correct', 'Hello', '--style', 'business'])
+        program.parseAsync([
+          'node',
+          'test',
+          'correct',
+          'Hello',
+          '--style',
+          'business',
+        ])
       ).rejects.toThrow(/unknown option/i);
     });
   });
@@ -109,7 +123,11 @@ describe('registerCorrect', () => {
       await program.parseAsync(['node', 'test', 'correct', 'This is an test.']);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'This is an test.',
-        expect.objectContaining({ correct: true, style: undefined, tone: undefined }),
+        expect.objectContaining({
+          correct: true,
+          style: undefined,
+          tone: undefined,
+        })
       );
       expect(Logger.output).toHaveBeenCalledWith('This is a test.');
     });
@@ -119,64 +137,122 @@ describe('registerCorrect', () => {
       await program.parseAsync(['node', 'test', 'c', 'Hello']);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ correct: true }),
+        expect.objectContaining({ correct: true })
       );
     });
 
     it('normalizes --lang casing to the canonical code', async () => {
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'correct', 'Hello', '--lang', 'EN-us']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'correct',
+        'Hello',
+        '--lang',
+        'EN-us',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'en-us' }),
+        expect.objectContaining({ lang: 'en-us' })
       );
     });
 
     it('accepts --to as an alias of --lang', async () => {
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'correct', 'Hello', '--to', 'de']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'correct',
+        'Hello',
+        '--to',
+        'de',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'de' }),
+        expect.objectContaining({ lang: 'de' })
       );
     });
   });
 
   describe('validation', () => {
     it('rejects an invalid language code', async () => {
-      await program.parseAsync(['node', 'test', 'correct', 'Hello', '--lang', 'invalid']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'correct',
+        'Hello',
+        '--lang',
+        'invalid',
+      ]);
       expect(handleError).toHaveBeenCalledWith(expect.any(ValidationError));
       expect(mockWriteCommand.improve).not.toHaveBeenCalled();
     });
 
     it('rejects conflicting --to and --lang values', async () => {
-      await program.parseAsync(['node', 'test', 'correct', 'Hello', '--to', 'de', '--lang', 'fr']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'correct',
+        'Hello',
+        '--to',
+        'de',
+        '--lang',
+        'fr',
+      ]);
       expect(handleError).toHaveBeenCalledWith(expect.any(ValidationError));
     });
 
     it('requires a file path for --fix', async () => {
       mockExistsSync.mockReturnValue(false);
-      await program.parseAsync(['node', 'test', 'correct', 'not-a-file', '--fix']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'correct',
+        'not-a-file',
+        '--fix',
+      ]);
       expect(handleError).toHaveBeenCalledWith(expect.any(ValidationError));
     });
   });
 
   describe('--check', () => {
     it('sets exit code 8 and reports correction needed', async () => {
-      mockWriteCommand.checkText.mockResolvedValue({ needsImprovement: true, changes: 2 });
-      await program.parseAsync(['node', 'test', 'correct', 'This is an test.', '--check']);
+      mockWriteCommand.checkText.mockResolvedValue({
+        needsImprovement: true,
+        changes: 2,
+      });
+      await program.parseAsync([
+        'node',
+        'test',
+        'correct',
+        'This is an test.',
+        '--check',
+      ]);
       expect(mockWriteCommand.checkText).toHaveBeenCalledWith(
         'This is an test.',
-        expect.objectContaining({ correct: true }),
+        expect.objectContaining({ correct: true })
+      );
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('needs correction')
       );
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('needs correction'));
       expect(process.exitCode).toBe(8);
     });
 
     it('exits clean when no corrections are needed', async () => {
-      mockWriteCommand.checkText.mockResolvedValue({ needsImprovement: false, changes: 0 });
-      await program.parseAsync(['node', 'test', 'correct', 'This is a test.', '--check']);
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Text looks good'));
+      mockWriteCommand.checkText.mockResolvedValue({
+        needsImprovement: false,
+        changes: 0,
+      });
+      await program.parseAsync([
+        'node',
+        'test',
+        'correct',
+        'This is a test.',
+        '--check',
+      ]);
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Text looks good')
+      );
       expect(process.exitCode).toBeUndefined();
     });
   });
@@ -184,20 +260,32 @@ describe('registerCorrect', () => {
   describe('--fix', () => {
     it('reports corrected file on fix', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.autoFixFile.mockResolvedValue({ fixed: true, filePath: '/tmp/f.txt', changes: 3 });
+      mockWriteCommand.autoFixFile.mockResolvedValue({
+        fixed: true,
+        filePath: '/tmp/f.txt',
+        changes: 3,
+      });
       await program.parseAsync(['node', 'test', 'correct', 'f.txt', '--fix']);
       expect(mockWriteCommand.autoFixFile).toHaveBeenCalledWith(
         'f.txt',
-        expect.objectContaining({ correct: true }),
+        expect.objectContaining({ correct: true })
+      );
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('File corrected')
       );
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('File corrected'));
     });
 
     it('reports when no corrections are needed', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.autoFixFile.mockResolvedValue({ fixed: false, filePath: '/tmp/f.txt', changes: 0 });
+      mockWriteCommand.autoFixFile.mockResolvedValue({
+        fixed: false,
+        filePath: '/tmp/f.txt',
+        changes: 0,
+      });
       await program.parseAsync(['node', 'test', 'correct', 'f.txt', '--fix']);
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('No corrections needed'));
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('No corrections needed')
+      );
     });
   });
 });
diff --git a/tests/unit/register-glossary.test.ts b/tests/unit/register-glossary.test.ts
index d6349ca5..4a8c32eb 100644
--- a/tests/unit/register-glossary.test.ts
+++ b/tests/unit/register-glossary.test.ts
@@ -1,4 +1,3 @@
- 
 import { Command } from 'commander';
 import { registerGlossary } from '../../src/cli/commands/register-glossary';
 import { createGlossaryCommand } from '../../src/cli/commands/service-factory';
@@ -34,7 +33,9 @@ import * as realFs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 
-const mockCreateGlossaryCommand = createGlossaryCommand as jest.MockedFunction<typeof createGlossaryCommand>;
+const mockCreateGlossaryCommand = createGlossaryCommand as jest.MockedFunction<
+  typeof createGlossaryCommand
+>;
 
 function makeProgram() {
   const program = new Command();
@@ -81,11 +82,30 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'create', 'my-terms', 'en', 'de', 'terms.tsv']);
-
-      expect(mock.create).toHaveBeenCalledWith('my-terms', 'en', ['de'], 'terms.tsv');
-      expect(Logger.output).toHaveBeenCalledWith(expect.stringContaining('Glossary created successfully'));
-      expect(mock.formatGlossaryInfo).toHaveBeenCalledWith({ id: '1', name: 'test' });
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'create',
+        'my-terms',
+        'en',
+        'de',
+        'terms.tsv',
+      ]);
+
+      expect(mock.create).toHaveBeenCalledWith(
+        'my-terms',
+        'en',
+        ['de'],
+        'terms.tsv'
+      );
+      expect(Logger.output).toHaveBeenCalledWith(
+        expect.stringContaining('Glossary created successfully')
+      );
+      expect(mock.formatGlossaryInfo).toHaveBeenCalledWith({
+        id: '1',
+        name: 'test',
+      });
       expect(Logger.output).toHaveBeenCalledWith('glossary-info');
     });
 
@@ -95,9 +115,23 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'create', 'my-terms', 'en', 'de,fr,es', 'terms.tsv']);
-
-      expect(mock.create).toHaveBeenCalledWith('my-terms', 'en', ['de', 'fr', 'es'], 'terms.tsv');
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'create',
+        'my-terms',
+        'en',
+        'de,fr,es',
+        'terms.tsv',
+      ]);
+
+      expect(mock.create).toHaveBeenCalledWith(
+        'my-terms',
+        'en',
+        ['de', 'fr', 'es'],
+        'terms.tsv'
+      );
     });
 
     it('should trim whitespace from comma-separated target languages', async () => {
@@ -106,9 +140,23 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'create', 'my-terms', 'en', 'de, fr, es', 'terms.tsv']);
-
-      expect(mock.create).toHaveBeenCalledWith('my-terms', 'en', ['de', 'fr', 'es'], 'terms.tsv');
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'create',
+        'my-terms',
+        'en',
+        'de, fr, es',
+        'terms.tsv',
+      ]);
+
+      expect(mock.create).toHaveBeenCalledWith(
+        'my-terms',
+        'en',
+        ['de', 'fr', 'es'],
+        'terms.tsv'
+      );
     });
 
     it('should handle single target language without comma', async () => {
@@ -117,9 +165,23 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'create', 'my-terms', 'en', 'de', 'terms.tsv']);
-
-      expect(mock.create).toHaveBeenCalledWith('my-terms', 'en', ['de'], 'terms.tsv');
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'create',
+        'my-terms',
+        'en',
+        'de',
+        'terms.tsv',
+      ]);
+
+      expect(mock.create).toHaveBeenCalledWith(
+        'my-terms',
+        'en',
+        ['de'],
+        'terms.tsv'
+      );
     });
 
     it('should call handleError on failure', async () => {
@@ -128,7 +190,16 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'create', 'name', 'en', 'de', 'file.tsv'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'create',
+          'name',
+          'en',
+          'de',
+          'file.tsv',
+        ])
       ).rejects.toThrow('create failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
@@ -167,10 +238,19 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'show', 'my-terms']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'show',
+        'my-terms',
+      ]);
 
       expect(mock.show).toHaveBeenCalledWith('my-terms');
-      expect(mock.formatGlossaryInfo).toHaveBeenCalledWith({ id: '1', name: 'test' });
+      expect(mock.formatGlossaryInfo).toHaveBeenCalledWith({
+        id: '1',
+        name: 'test',
+      });
       expect(Logger.output).toHaveBeenCalledWith('glossary-info');
     });
 
@@ -193,7 +273,13 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'entries', 'my-terms']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'entries',
+        'my-terms',
+      ]);
 
       expect(mock.entries).toHaveBeenCalledWith('my-terms', undefined);
       expect(mock.formatEntries).toHaveBeenCalledWith([['hello', 'hallo']]);
@@ -206,7 +292,15 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'entries', 'my-terms', '--target-lang', 'de']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'entries',
+        'my-terms',
+        '--target-lang',
+        'de',
+      ]);
 
       expect(mock.entries).toHaveBeenCalledWith('my-terms', 'de');
     });
@@ -230,7 +324,14 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'delete', 'my-terms', '--yes']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'delete',
+        'my-terms',
+        '--yes',
+      ]);
 
       expect(mock.delete).toHaveBeenCalledWith('my-terms');
       expect(Logger.success).toHaveBeenCalled();
@@ -239,7 +340,14 @@ describe('registerGlossary', () => {
     it('should output dry-run message with --dry-run flag', async () => {
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'delete', 'my-terms', '--dry-run']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'delete',
+        'my-terms',
+        '--dry-run',
+      ]);
 
       expect(Logger.output).toHaveBeenCalled();
       const outputArg = (Logger.output as jest.Mock).mock.calls[0][0] as string;
@@ -253,7 +361,13 @@ describe('registerGlossary', () => {
       (confirm as jest.Mock).mockResolvedValue(false);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'delete', 'my-terms']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'delete',
+        'my-terms',
+      ]);
 
       expect(Logger.info).toHaveBeenCalledWith('Aborted.');
       expect(mockCreateGlossaryCommand).not.toHaveBeenCalled();
@@ -267,7 +381,13 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'delete', 'my-terms']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'delete',
+        'my-terms',
+      ]);
 
       expect(confirm).toHaveBeenCalled();
       expect(mock.delete).toHaveBeenCalledWith('my-terms');
@@ -280,7 +400,14 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'delete', 'my-terms', '--yes'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'delete',
+          'my-terms',
+          '--yes',
+        ])
       ).rejects.toThrow('delete failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
@@ -296,7 +423,9 @@ describe('registerGlossary', () => {
       await program.parseAsync(['node', 'test', 'glossary', 'languages']);
 
       expect(mock.listLanguages).toHaveBeenCalled();
-      expect(mock.formatLanguagePairs).toHaveBeenCalledWith([{ source: 'en', target: 'de' }]);
+      expect(mock.formatLanguagePairs).toHaveBeenCalledWith([
+        { source: 'en', target: 'de' },
+      ]);
       expect(Logger.output).toHaveBeenCalledWith('language-pairs');
     });
 
@@ -319,9 +448,22 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'add-entry', 'my-terms', 'hello', 'hallo']);
-
-      expect(mock.addEntry).toHaveBeenCalledWith('my-terms', 'hello', 'hallo', undefined);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'add-entry',
+        'my-terms',
+        'hello',
+        'hallo',
+      ]);
+
+      expect(mock.addEntry).toHaveBeenCalledWith(
+        'my-terms',
+        'hello',
+        'hallo',
+        undefined
+      );
       expect(Logger.success).toHaveBeenCalled();
     });
 
@@ -331,9 +473,24 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'add-entry', 'my-terms', 'hello', 'hallo', '--target-lang', 'de']);
-
-      expect(mock.addEntry).toHaveBeenCalledWith('my-terms', 'hello', 'hallo', 'de');
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'add-entry',
+        'my-terms',
+        'hello',
+        'hallo',
+        '--target-lang',
+        'de',
+      ]);
+
+      expect(mock.addEntry).toHaveBeenCalledWith(
+        'my-terms',
+        'hello',
+        'hallo',
+        'de'
+      );
     });
 
     it('should call handleError on failure', async () => {
@@ -342,7 +499,15 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'add-entry', 'my-terms', 'hello', 'hallo'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'add-entry',
+          'my-terms',
+          'hello',
+          'hallo',
+        ])
       ).rejects.toThrow('add-entry failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
@@ -355,9 +520,22 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'update-entry', 'my-terms', 'hello', 'hi']);
-
-      expect(mock.updateEntry).toHaveBeenCalledWith('my-terms', 'hello', 'hi', undefined);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'update-entry',
+        'my-terms',
+        'hello',
+        'hi',
+      ]);
+
+      expect(mock.updateEntry).toHaveBeenCalledWith(
+        'my-terms',
+        'hello',
+        'hi',
+        undefined
+      );
       expect(Logger.success).toHaveBeenCalled();
     });
 
@@ -367,9 +545,24 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'update-entry', 'my-terms', 'hello', 'hi', '--target-lang', 'de']);
-
-      expect(mock.updateEntry).toHaveBeenCalledWith('my-terms', 'hello', 'hi', 'de');
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'update-entry',
+        'my-terms',
+        'hello',
+        'hi',
+        '--target-lang',
+        'de',
+      ]);
+
+      expect(mock.updateEntry).toHaveBeenCalledWith(
+        'my-terms',
+        'hello',
+        'hi',
+        'de'
+      );
     });
 
     it('should call handleError on failure', async () => {
@@ -378,7 +571,15 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'update-entry', 'my-terms', 'hello', 'hi'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'update-entry',
+          'my-terms',
+          'hello',
+          'hi',
+        ])
       ).rejects.toThrow('update-entry failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
@@ -391,9 +592,20 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'remove-entry', 'my-terms', 'hello']);
-
-      expect(mock.removeEntry).toHaveBeenCalledWith('my-terms', 'hello', undefined);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'remove-entry',
+        'my-terms',
+        'hello',
+      ]);
+
+      expect(mock.removeEntry).toHaveBeenCalledWith(
+        'my-terms',
+        'hello',
+        undefined
+      );
       expect(Logger.success).toHaveBeenCalled();
     });
 
@@ -403,7 +615,16 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'remove-entry', 'my-terms', 'hello', '--target-lang', 'de']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'remove-entry',
+        'my-terms',
+        'hello',
+        '--target-lang',
+        'de',
+      ]);
 
       expect(mock.removeEntry).toHaveBeenCalledWith('my-terms', 'hello', 'de');
     });
@@ -414,7 +635,14 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'remove-entry', 'my-terms', 'hello'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'remove-entry',
+          'my-terms',
+          'hello',
+        ])
       ).rejects.toThrow('remove-entry failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
@@ -427,7 +655,14 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'rename', 'old-name', 'new-name']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'rename',
+        'old-name',
+        'new-name',
+      ]);
 
       expect(mock.rename).toHaveBeenCalledWith('old-name', 'new-name');
       expect(Logger.success).toHaveBeenCalled();
@@ -439,7 +674,14 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'rename', 'old-name', 'new-name'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'rename',
+          'old-name',
+          'new-name',
+        ])
       ).rejects.toThrow('rename failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
@@ -451,7 +693,9 @@ describe('registerGlossary', () => {
     let emptyFile: string;
 
     beforeEach(() => {
-      tmpDir = realFs.mkdtempSync(path.join(os.tmpdir(), 'deepl-glossary-test-'));
+      tmpDir = realFs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-glossary-test-')
+      );
       tsvFile = path.join(tmpDir, 'entries.tsv');
       emptyFile = path.join(tmpDir, 'empty.tsv');
       realFs.writeFileSync(tsvFile, 'hello\thola\nworld\tmundo\n', 'utf-8');
@@ -467,7 +711,9 @@ describe('registerGlossary', () => {
 
       await expect(
         program.parseAsync(['node', 'test', 'glossary', 'update', 'my-terms'])
-      ).rejects.toThrow('At least one of --name or --file (with --target-lang) must be provided');
+      ).rejects.toThrow(
+        'At least one of --name or --file (with --target-lang) must be provided'
+      );
       expect(handleError).toHaveBeenCalled();
     });
 
@@ -475,7 +721,15 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'update', 'my-terms', '--file', tsvFile])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'update',
+          'my-terms',
+          '--file',
+          tsvFile,
+        ])
       ).rejects.toThrow('--target-lang is required when using --file');
       expect(handleError).toHaveBeenCalled();
     });
@@ -485,7 +739,17 @@ describe('registerGlossary', () => {
       const missing = path.join(tmpDir, 'missing.tsv');
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'update', 'my-terms', '--file', missing, '--target-lang', 'de'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'update',
+          'my-terms',
+          '--file',
+          missing,
+          '--target-lang',
+          'de',
+        ])
       ).rejects.toThrow(`File not found: ${missing}`);
       expect(handleError).toHaveBeenCalled();
     });
@@ -496,7 +760,17 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'update', 'my-terms', '--file', emptyFile, '--target-lang', 'de'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'update',
+          'my-terms',
+          '--file',
+          emptyFile,
+          '--target-lang',
+          'de',
+        ])
       ).rejects.toThrow('No valid entries found in file');
       expect(handleError).toHaveBeenCalled();
     });
@@ -507,9 +781,19 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'update', 'my-terms', '--name', 'new-name']);
-
-      expect(mock.update).toHaveBeenCalledWith('my-terms', { name: 'new-name' });
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'update',
+        'my-terms',
+        '--name',
+        'new-name',
+      ]);
+
+      expect(mock.update).toHaveBeenCalledWith('my-terms', {
+        name: 'new-name',
+      });
       expect(Logger.success).toHaveBeenCalled();
       const successMsg = (Logger.success as jest.Mock).mock.calls[0][0];
       expect(successMsg).toContain('renamed');
@@ -521,13 +805,28 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'update', 'my-terms', '--file', tsvFile, '--target-lang', 'de']);
-
-      expect(mock.update).toHaveBeenCalledWith('my-terms', expect.objectContaining({
-        dictionaries: [expect.objectContaining({
-          targetLang: 'de',
-        })],
-      }));
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'update',
+        'my-terms',
+        '--file',
+        tsvFile,
+        '--target-lang',
+        'de',
+      ]);
+
+      expect(mock.update).toHaveBeenCalledWith(
+        'my-terms',
+        expect.objectContaining({
+          dictionaries: [
+            expect.objectContaining({
+              targetLang: 'de',
+            }),
+          ],
+        })
+      );
       expect(Logger.success).toHaveBeenCalled();
       const successMsg = (Logger.success as jest.Mock).mock.calls[0][0];
       expect(successMsg).toContain('dictionary updated');
@@ -539,14 +838,31 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'update', 'my-terms', '--name', 'new-name', '--file', tsvFile, '--target-lang', 'de']);
-
-      expect(mock.update).toHaveBeenCalledWith('my-terms', expect.objectContaining({
-        name: 'new-name',
-        dictionaries: [expect.objectContaining({
-          targetLang: 'de',
-        })],
-      }));
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'update',
+        'my-terms',
+        '--name',
+        'new-name',
+        '--file',
+        tsvFile,
+        '--target-lang',
+        'de',
+      ]);
+
+      expect(mock.update).toHaveBeenCalledWith(
+        'my-terms',
+        expect.objectContaining({
+          name: 'new-name',
+          dictionaries: [
+            expect.objectContaining({
+              targetLang: 'de',
+            }),
+          ],
+        })
+      );
       expect(Logger.success).toHaveBeenCalled();
       const successMsg = (Logger.success as jest.Mock).mock.calls[0][0];
       expect(successMsg).toContain('renamed');
@@ -561,7 +877,15 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'update', 'my-terms', '--name', 'new'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'update',
+          'my-terms',
+          '--name',
+          'new',
+        ])
       ).rejects.toThrow('update failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
@@ -574,9 +898,21 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'replace-dictionary', 'my-terms', 'de', 'new.tsv']);
-
-      expect(mock.replaceDictionary).toHaveBeenCalledWith('my-terms', 'de', 'new.tsv');
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'replace-dictionary',
+        'my-terms',
+        'de',
+        'new.tsv',
+      ]);
+
+      expect(mock.replaceDictionary).toHaveBeenCalledWith(
+        'my-terms',
+        'de',
+        'new.tsv'
+      );
       expect(Logger.success).toHaveBeenCalled();
     });
 
@@ -586,7 +922,15 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'replace-dictionary', 'my-terms', 'de', 'new.tsv'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'replace-dictionary',
+          'my-terms',
+          'de',
+          'new.tsv',
+        ])
       ).rejects.toThrow('replace failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
@@ -599,7 +943,15 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'delete-dictionary', 'my-terms', 'de', '--yes']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'delete-dictionary',
+        'my-terms',
+        'de',
+        '--yes',
+      ]);
 
       expect(mock.deleteDictionary).toHaveBeenCalledWith('my-terms', 'de');
       expect(Logger.success).toHaveBeenCalled();
@@ -610,7 +962,14 @@ describe('registerGlossary', () => {
       (confirm as jest.Mock).mockResolvedValue(false);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'delete-dictionary', 'my-terms', 'de']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'delete-dictionary',
+        'my-terms',
+        'de',
+      ]);
 
       expect(Logger.info).toHaveBeenCalledWith('Aborted.');
       expect(mockCreateGlossaryCommand).not.toHaveBeenCalled();
@@ -624,7 +983,14 @@ describe('registerGlossary', () => {
       mockCreateGlossaryCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'glossary', 'delete-dictionary', 'my-terms', 'de']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'glossary',
+        'delete-dictionary',
+        'my-terms',
+        'de',
+      ]);
 
       expect(confirm).toHaveBeenCalled();
       expect(mock.deleteDictionary).toHaveBeenCalledWith('my-terms', 'de');
@@ -637,7 +1003,15 @@ describe('registerGlossary', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'glossary', 'delete-dictionary', 'my-terms', 'de', '--yes'])
+        program.parseAsync([
+          'node',
+          'test',
+          'glossary',
+          'delete-dictionary',
+          'my-terms',
+          'de',
+          '--yes',
+        ])
       ).rejects.toThrow('delete-dict failed');
       expect(handleError).toHaveBeenCalledWith(error);
     });
diff --git a/tests/unit/register-hooks.test.ts b/tests/unit/register-hooks.test.ts
index 5b906de6..1e1e3902 100644
--- a/tests/unit/register-hooks.test.ts
+++ b/tests/unit/register-hooks.test.ts
@@ -1,4 +1,3 @@
- 
 import { Command } from 'commander';
 import { registerHooks } from '../../src/cli/commands/register-hooks';
 import { Logger } from '../../src/utils/logger';
@@ -46,7 +45,13 @@ describe('registerHooks', () => {
       mockHooksCommand.install.mockReturnValue('Installed pre-commit hook');
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'hooks', 'install', 'pre-commit']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'hooks',
+        'install',
+        'pre-commit',
+      ]);
 
       expect(mockHooksCommand.install).toHaveBeenCalledWith('pre-commit');
       expect(Logger.output).toHaveBeenCalledWith('Installed pre-commit hook');
@@ -70,7 +75,13 @@ describe('registerHooks', () => {
       mockHooksCommand.uninstall.mockReturnValue('Uninstalled pre-commit hook');
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'hooks', 'uninstall', 'pre-commit']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'hooks',
+        'uninstall',
+        'pre-commit',
+      ]);
 
       expect(mockHooksCommand.uninstall).toHaveBeenCalledWith('pre-commit');
       expect(Logger.output).toHaveBeenCalledWith('Uninstalled pre-commit hook');
@@ -91,13 +102,17 @@ describe('registerHooks', () => {
 
   describe('hooks list', () => {
     it('should list hooks and output result', async () => {
-      mockHooksCommand.list.mockReturnValue('Git Hooks Status:\n  pre-commit installed');
+      mockHooksCommand.list.mockReturnValue(
+        'Git Hooks Status:\n  pre-commit installed'
+      );
       const { program } = makeProgram();
 
       await program.parseAsync(['node', 'test', 'hooks', 'list']);
 
       expect(mockHooksCommand.list).toHaveBeenCalled();
-      expect(Logger.output).toHaveBeenCalledWith('Git Hooks Status:\n  pre-commit installed');
+      expect(Logger.output).toHaveBeenCalledWith(
+        'Git Hooks Status:\n  pre-commit installed'
+      );
     });
 
     it('should call handleError on failure', async () => {
@@ -115,13 +130,17 @@ describe('registerHooks', () => {
 
   describe('hooks path', () => {
     it('should show hook path and output result', async () => {
-      mockHooksCommand.showPath.mockReturnValue('Hook path: /repo/.git/hooks/pre-commit');
+      mockHooksCommand.showPath.mockReturnValue(
+        'Hook path: /repo/.git/hooks/pre-commit'
+      );
       const { program } = makeProgram();
 
       await program.parseAsync(['node', 'test', 'hooks', 'path', 'pre-commit']);
 
       expect(mockHooksCommand.showPath).toHaveBeenCalledWith('pre-commit');
-      expect(Logger.output).toHaveBeenCalledWith('Hook path: /repo/.git/hooks/pre-commit');
+      expect(Logger.output).toHaveBeenCalledWith(
+        'Hook path: /repo/.git/hooks/pre-commit'
+      );
     });
 
     it('should call handleError on failure', async () => {
diff --git a/tests/unit/register-init.test.ts b/tests/unit/register-init.test.ts
index 696d91eb..af1b8ce9 100644
--- a/tests/unit/register-init.test.ts
+++ b/tests/unit/register-init.test.ts
@@ -48,12 +48,17 @@ describe('registerInit', () => {
     registerInit(program, {
       getConfigService: () => configService,
       getHttpOptions: () => ({ timeout: 42, maxRetries: 2 }),
-      handleError: ((error: unknown) => { throw error; }),
+      handleError: (error: unknown) => {
+        throw error;
+      },
     });
 
     await program.parseAsync(['node', 'deepl', 'init']);
 
-    expect(InitCommand).toHaveBeenCalledWith(configService, { timeout: 42, maxRetries: 2 });
+    expect(InitCommand).toHaveBeenCalledWith(configService, {
+      timeout: 42,
+      maxRetries: 2,
+    });
   });
 
   it('should construct InitCommand without options when getHttpOptions is absent', async () => {
@@ -63,7 +68,9 @@ describe('registerInit', () => {
 
     registerInit(program, {
       getConfigService: () => configService,
-      handleError: ((error: unknown) => { throw error; }),
+      handleError: (error: unknown) => {
+        throw error;
+      },
     });
 
     await program.parseAsync(['node', 'deepl', 'init']);
@@ -87,8 +94,10 @@ describe('registerInit', () => {
     expect(InitCommand).not.toHaveBeenCalled();
     expect(handleError).toHaveBeenCalledWith(
       expect.objectContaining({
-        message: expect.stringContaining('not supported in non-interactive mode'),
-      }),
+        message: expect.stringContaining(
+          'not supported in non-interactive mode'
+        ),
+      })
     );
   });
 });
diff --git a/tests/unit/register-languages.test.ts b/tests/unit/register-languages.test.ts
index c8f20e5b..7736dd36 100644
--- a/tests/unit/register-languages.test.ts
+++ b/tests/unit/register-languages.test.ts
@@ -1,4 +1,3 @@
- 
 import { Command } from 'commander';
 
 jest.mock('chalk', () => {
@@ -34,18 +33,31 @@ const mockLanguagesCommandInstance = {
   formatAllLanguagesTable: jest.fn().mockReturnValue('all-languages-table'),
 };
 
-async function withTTY<T>(value: boolean, fn: () => Promise<T> | T): Promise<T> {
+async function withTTY<T>(
+  value: boolean,
+  fn: () => Promise<T> | T
+): Promise<T> {
   const original = process.stdout.isTTY;
-  Object.defineProperty(process.stdout, 'isTTY', { value, configurable: true, writable: true });
+  Object.defineProperty(process.stdout, 'isTTY', {
+    value,
+    configurable: true,
+    writable: true,
+  });
   try {
     return await fn();
   } finally {
-    Object.defineProperty(process.stdout, 'isTTY', { value: original, configurable: true, writable: true });
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: original,
+      configurable: true,
+      writable: true,
+    });
   }
 }
 
 jest.mock('../../src/cli/commands/languages', () => ({
-  LanguagesCommand: jest.fn().mockImplementation(() => mockLanguagesCommandInstance),
+  LanguagesCommand: jest
+    .fn()
+    .mockImplementation(() => mockLanguagesCommandInstance),
 }));
 
 import { registerLanguages } from '../../src/cli/commands/register-languages';
@@ -62,7 +74,9 @@ describe('registerLanguages', () => {
   beforeEach(() => {
     jest.clearAllMocks();
     const { LanguagesCommand } = require('../../src/cli/commands/languages');
-    (LanguagesCommand as jest.Mock).mockImplementation(() => mockLanguagesCommandInstance);
+    (LanguagesCommand as jest.Mock).mockImplementation(
+      () => mockLanguagesCommandInstance
+    );
 
     process.env = { ...origEnv };
     delete process.env['DEEPL_API_KEY'];
@@ -71,7 +85,11 @@ describe('registerLanguages', () => {
     createDeepLClient = jest.fn().mockResolvedValue({});
     mockGetValue = jest.fn().mockReturnValue(undefined);
     getConfigService = jest.fn().mockReturnValue({ getValue: mockGetValue });
-    registerLanguages(program, { getConfigService, createDeepLClient, handleError });
+    registerLanguages(program, {
+      getConfigService,
+      createDeepLClient,
+      handleError,
+    });
   });
 
   afterAll(() => {
@@ -86,111 +104,234 @@ describe('registerLanguages', () => {
     it('should show all languages by default', async () => {
       const sources = [{ code: 'en', name: 'English' }];
       const targets = [{ code: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
-      mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('all languages');
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
+      mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue(
+        'all languages'
+      );
       await program.parseAsync(['node', 'test', 'languages']);
       expect(createDeepLClient).toHaveBeenCalled();
-      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets, false);
+      expect(
+        mockLanguagesCommandInstance.formatAllLanguages
+      ).toHaveBeenCalledWith(sources, targets, false);
       expect(Logger.output).toHaveBeenCalledWith('all languages');
     });
 
     it('should show only source languages with --source', async () => {
       const sources = [{ code: 'en', name: 'English' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.formatLanguages.mockReturnValue('source list');
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.formatLanguages.mockReturnValue(
+        'source list'
+      );
       await program.parseAsync(['node', 'test', 'languages', '--source']);
-      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(sources, 'source', false);
+      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(
+        sources,
+        'source',
+        false
+      );
       expect(Logger.output).toHaveBeenCalledWith('source list');
     });
 
     it('should show only target languages with --target', async () => {
       const targets = [{ code: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
-      mockLanguagesCommandInstance.formatLanguages.mockReturnValue('target list');
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
+      mockLanguagesCommandInstance.formatLanguages.mockReturnValue(
+        'target list'
+      );
       await program.parseAsync(['node', 'test', 'languages', '--target']);
-      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(targets, 'target', false);
+      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(
+        targets,
+        'target',
+        false
+      );
       expect(Logger.output).toHaveBeenCalledWith('target list');
     });
 
     it('should show all when both --source and --target are given', async () => {
       const sources = [{ code: 'en', name: 'English' }];
       const targets = [{ code: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
       mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('all');
-      await program.parseAsync(['node', 'test', 'languages', '--source', '--target']);
-      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets, false);
+      await program.parseAsync([
+        'node',
+        'test',
+        'languages',
+        '--source',
+        '--target',
+      ]);
+      expect(
+        mockLanguagesCommandInstance.formatAllLanguages
+      ).toHaveBeenCalledWith(sources, targets, false);
     });
 
     it('should output JSON for source languages with --format json --source', async () => {
       const sources = [{ language: 'en', name: 'English' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      await program.parseAsync(['node', 'test', 'languages', '--source', '--format', 'json']);
-      expect(Logger.output).toHaveBeenCalledWith(JSON.stringify(sources, null, 2));
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      await program.parseAsync([
+        'node',
+        'test',
+        'languages',
+        '--source',
+        '--format',
+        'json',
+      ]);
+      expect(Logger.output).toHaveBeenCalledWith(
+        JSON.stringify(sources, null, 2)
+      );
     });
 
     it('should output JSON for target languages with --format json --target', async () => {
       const targets = [{ language: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
-      await program.parseAsync(['node', 'test', 'languages', '--target', '--format', 'json']);
-      expect(Logger.output).toHaveBeenCalledWith(JSON.stringify(targets, null, 2));
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
+      await program.parseAsync([
+        'node',
+        'test',
+        'languages',
+        '--target',
+        '--format',
+        'json',
+      ]);
+      expect(Logger.output).toHaveBeenCalledWith(
+        JSON.stringify(targets, null, 2)
+      );
     });
 
     it('should output JSON for all languages with --format json', async () => {
       const sources = [{ language: 'en', name: 'English' }];
       const targets = [{ language: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
-      await program.parseAsync(['node', 'test', 'languages', '--format', 'json']);
-      const expected = JSON.stringify({ source: sources, target: targets }, null, 2);
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
+      await program.parseAsync([
+        'node',
+        'test',
+        'languages',
+        '--format',
+        'json',
+      ]);
+      const expected = JSON.stringify(
+        { source: sources, target: targets },
+        null,
+        2
+      );
       expect(Logger.output).toHaveBeenCalledWith(expected);
     });
 
     it('should render cli-table3 output for all languages when --format table and stdout is a TTY', async () => {
       const sources = [{ language: 'en', name: 'English' }];
       const targets = [{ language: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
-      mockLanguagesCommandInstance.formatAllLanguagesTable.mockReturnValue('all-languages-table');
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
+      mockLanguagesCommandInstance.formatAllLanguagesTable.mockReturnValue(
+        'all-languages-table'
+      );
 
       await withTTY(true, async () => {
-        await program.parseAsync(['node', 'test', 'languages', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'languages',
+          '--format',
+          'table',
+        ]);
       });
 
-      expect(mockLanguagesCommandInstance.formatAllLanguagesTable).toHaveBeenCalledWith(sources, targets, false);
-      expect(mockLanguagesCommandInstance.formatAllLanguages).not.toHaveBeenCalled();
+      expect(
+        mockLanguagesCommandInstance.formatAllLanguagesTable
+      ).toHaveBeenCalledWith(sources, targets, false);
+      expect(
+        mockLanguagesCommandInstance.formatAllLanguages
+      ).not.toHaveBeenCalled();
       expect(Logger.output).toHaveBeenCalledWith('all-languages-table');
-      expect(Logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
+      expect(Logger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining('non-TTY')
+      );
     });
 
     it('should render the source-only table when --format table --source on a TTY', async () => {
       const sources = [{ language: 'en', name: 'English' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.formatLanguagesTable.mockReturnValue('languages-table');
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.formatLanguagesTable.mockReturnValue(
+        'languages-table'
+      );
 
       await withTTY(true, async () => {
-        await program.parseAsync(['node', 'test', 'languages', '--source', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'languages',
+          '--source',
+          '--format',
+          'table',
+        ]);
       });
 
-      expect(mockLanguagesCommandInstance.formatLanguagesTable).toHaveBeenCalledWith(sources, 'source', false);
-      expect(mockLanguagesCommandInstance.formatLanguages).not.toHaveBeenCalled();
+      expect(
+        mockLanguagesCommandInstance.formatLanguagesTable
+      ).toHaveBeenCalledWith(sources, 'source', false);
+      expect(
+        mockLanguagesCommandInstance.formatLanguages
+      ).not.toHaveBeenCalled();
     });
 
     it('should fall back to plain text with a warn when --format table in non-TTY', async () => {
       const sources = [{ language: 'en', name: 'English' }];
       const targets = [{ language: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
-      mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('plain text');
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
+      mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue(
+        'plain text'
+      );
 
       await withTTY(false, async () => {
-        await program.parseAsync(['node', 'test', 'languages', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'languages',
+          '--format',
+          'table',
+        ]);
       });
 
-      expect(mockLanguagesCommandInstance.formatAllLanguagesTable).not.toHaveBeenCalled();
-      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets, false);
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
+      expect(
+        mockLanguagesCommandInstance.formatAllLanguagesTable
+      ).not.toHaveBeenCalled();
+      expect(
+        mockLanguagesCommandInstance.formatAllLanguages
+      ).toHaveBeenCalledWith(sources, targets, false);
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('non-TTY')
+      );
       expect(Logger.output).toHaveBeenCalledWith('plain text');
     });
   });
@@ -203,73 +344,153 @@ describe('registerLanguages', () => {
     it('should request the feature matrix for the combined listing', async () => {
       const sources = [{ language: 'en', name: 'English' }];
       const targets = [{ language: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
       mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('all');
 
       await program.parseAsync(['node', 'test', 'languages', '--features']);
 
-      expect(mockLanguagesCommandInstance.formatAllLanguages).toHaveBeenCalledWith(sources, targets, true);
+      expect(
+        mockLanguagesCommandInstance.formatAllLanguages
+      ).toHaveBeenCalledWith(sources, targets, true);
     });
 
     it('should request the feature matrix for a single-role listing', async () => {
       const targets = [{ language: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
-      mockLanguagesCommandInstance.formatLanguages.mockReturnValue('target list');
-
-      await program.parseAsync(['node', 'test', 'languages', '--target', '--features']);
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
+      mockLanguagesCommandInstance.formatLanguages.mockReturnValue(
+        'target list'
+      );
 
-      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(targets, 'target', true);
+      await program.parseAsync([
+        'node',
+        'test',
+        'languages',
+        '--target',
+        '--features',
+      ]);
+
+      expect(mockLanguagesCommandInstance.formatLanguages).toHaveBeenCalledWith(
+        targets,
+        'target',
+        true
+      );
     });
 
     it('should request the feature matrix for table output', async () => {
       const sources = [{ language: 'en', name: 'English' }];
       const targets = [{ language: 'de', name: 'German' }];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
 
       await withTTY(true, async () => {
-        await program.parseAsync(['node', 'test', 'languages', '--features', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'languages',
+          '--features',
+          '--format',
+          'table',
+        ]);
       });
 
-      expect(mockLanguagesCommandInstance.formatAllLanguagesTable).toHaveBeenCalledWith(sources, targets, true);
+      expect(
+        mockLanguagesCommandInstance.formatAllLanguagesTable
+      ).toHaveBeenCalledWith(sources, targets, true);
     });
 
     it('should include features in JSON output when requested', async () => {
       const targets = [
-        { language: 'de', name: 'German', features: { glossary: { status: 'stable' } } },
+        {
+          language: 'de',
+          name: 'German',
+          features: { glossary: { status: 'stable' } },
+        },
       ];
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
 
-      await program.parseAsync(['node', 'test', 'languages', '--target', '--features', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'languages',
+        '--target',
+        '--features',
+        '--format',
+        'json',
+      ]);
 
-      expect(Logger.output).toHaveBeenCalledWith(JSON.stringify(targets, null, 2));
+      expect(Logger.output).toHaveBeenCalledWith(
+        JSON.stringify(targets, null, 2)
+      );
     });
 
     it('should strip features from JSON output when not requested', async () => {
       const targets = [
-        { language: 'de', name: 'German', features: { glossary: { status: 'stable' } } },
+        {
+          language: 'de',
+          name: 'German',
+          features: { glossary: { status: 'stable' } },
+        },
       ];
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
 
-      await program.parseAsync(['node', 'test', 'languages', '--target', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'languages',
+        '--target',
+        '--format',
+        'json',
+      ]);
 
       expect(Logger.output).toHaveBeenCalledWith(
-        JSON.stringify([{ language: 'de', name: 'German' }], null, 2),
+        JSON.stringify([{ language: 'de', name: 'German' }], null, 2)
       );
     });
 
     it('should strip features from both roles of the combined JSON output', async () => {
       const sources = [
-        { language: 'en', name: 'English', features: { glossary: { status: 'stable' } } },
+        {
+          language: 'en',
+          name: 'English',
+          features: { glossary: { status: 'stable' } },
+        },
       ];
       const targets = [
-        { language: 'de', name: 'German', features: { glossary: { status: 'stable' } } },
+        {
+          language: 'de',
+          name: 'German',
+          features: { glossary: { status: 'stable' } },
+        },
       ];
-      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(sources);
-      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(targets);
+      mockLanguagesCommandInstance.getSourceLanguages.mockResolvedValue(
+        sources
+      );
+      mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue(
+        targets
+      );
 
-      await program.parseAsync(['node', 'test', 'languages', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'languages',
+        '--format',
+        'json',
+      ]);
 
       expect(Logger.output).toHaveBeenCalledWith(
         JSON.stringify(
@@ -278,8 +499,8 @@ describe('registerLanguages', () => {
             target: [{ language: 'de', name: 'German' }],
           },
           null,
-          2,
-        ),
+          2
+        )
       );
     });
   });
@@ -301,7 +522,9 @@ describe('registerLanguages', () => {
       mockLanguagesCommandInstance.getTargetLanguages.mockResolvedValue([]);
       mockLanguagesCommandInstance.formatAllLanguages.mockReturnValue('local');
       await program.parseAsync(['node', 'test', 'languages']);
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('No API key'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('No API key')
+      );
       expect(createDeepLClient).not.toHaveBeenCalled();
       expect(Logger.output).toHaveBeenCalledWith('local');
     });
@@ -313,7 +536,9 @@ describe('registerLanguages', () => {
 
       await program.parseAsync(['node', 'test', 'languages', '--features']);
 
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('--features needs an API key'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('--features needs an API key')
+      );
     });
 
     it('should not mention --features when the flag is absent', async () => {
@@ -323,7 +548,9 @@ describe('registerLanguages', () => {
 
       await program.parseAsync(['node', 'test', 'languages']);
 
-      expect(Logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('--features'));
+      expect(Logger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining('--features')
+      );
     });
   });
 
@@ -333,7 +560,7 @@ describe('registerLanguages', () => {
       createDeepLClient.mockRejectedValue(new Error('connection failed'));
       await program.parseAsync(['node', 'test', 'languages']);
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: 'connection failed' }),
+        expect.objectContaining({ message: 'connection failed' })
       );
     });
   });
diff --git a/tests/unit/register-style-rules.test.ts b/tests/unit/register-style-rules.test.ts
index 835994af..043c06e7 100644
--- a/tests/unit/register-style-rules.test.ts
+++ b/tests/unit/register-style-rules.test.ts
@@ -30,7 +30,10 @@ jest.mock('chalk', () => ({
   yellow: (t: string) => t,
 }));
 
-const mockCreateStyleRulesCommand = createStyleRulesCommand as jest.MockedFunction<typeof createStyleRulesCommand>;
+const mockCreateStyleRulesCommand =
+  createStyleRulesCommand as jest.MockedFunction<
+    typeof createStyleRulesCommand
+  >;
 
 const SAMPLE_RULE = {
   styleId: 'sr-1',
@@ -66,9 +69,15 @@ function makeMockStyleRulesCmd() {
     update: jest.fn().mockResolvedValue(SAMPLE_RULE),
     delete: jest.fn().mockResolvedValue(undefined),
     replaceRules: jest.fn().mockResolvedValue(SAMPLE_DETAILED),
-    listInstructions: jest.fn().mockResolvedValue([{ label: 'tone', prompt: 'Be formal' }]),
-    addInstruction: jest.fn().mockResolvedValue({ label: 'tone', prompt: 'Be formal' }),
-    updateInstruction: jest.fn().mockResolvedValue({ label: 'tone', prompt: 'Be friendlier' }),
+    listInstructions: jest
+      .fn()
+      .mockResolvedValue([{ label: 'tone', prompt: 'Be formal' }]),
+    addInstruction: jest
+      .fn()
+      .mockResolvedValue({ label: 'tone', prompt: 'Be formal' }),
+    updateInstruction: jest
+      .fn()
+      .mockResolvedValue({ label: 'tone', prompt: 'Be friendlier' }),
     removeInstruction: jest.fn().mockResolvedValue(undefined),
     formatStyleRulesList: jest.fn().mockReturnValue('rules-list-text'),
     formatStyleRulesJson: jest.fn().mockReturnValue('[]'),
@@ -76,19 +85,34 @@ function makeMockStyleRulesCmd() {
     formatStyleRule: jest.fn().mockReturnValue('rule-text'),
     formatStyleRuleJson: jest.fn().mockReturnValue('{}'),
     formatCustomInstruction: jest.fn().mockReturnValue('instruction-text'),
-    formatCustomInstructionsList: jest.fn().mockReturnValue('instructions-list-text'),
-    formatCustomInstructionsTable: jest.fn().mockReturnValue('instructions-list-table'),
+    formatCustomInstructionsList: jest
+      .fn()
+      .mockReturnValue('instructions-list-text'),
+    formatCustomInstructionsTable: jest
+      .fn()
+      .mockReturnValue('instructions-list-table'),
     formatCustomInstructionJson: jest.fn().mockReturnValue('{}'),
   };
 }
 
-async function withTTY<T>(value: boolean, fn: () => Promise<T> | T): Promise<T> {
+async function withTTY<T>(
+  value: boolean,
+  fn: () => Promise<T> | T
+): Promise<T> {
   const original = process.stdout.isTTY;
-  Object.defineProperty(process.stdout, 'isTTY', { value, configurable: true, writable: true });
+  Object.defineProperty(process.stdout, 'isTTY', {
+    value,
+    configurable: true,
+    writable: true,
+  });
   try {
     return await fn();
   } finally {
-    Object.defineProperty(process.stdout, 'isTTY', { value: original, configurable: true, writable: true });
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: original,
+      configurable: true,
+      writable: true,
+    });
   }
 }
 
@@ -115,7 +139,14 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'list', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'list',
+        '--format',
+        'json',
+      ]);
 
       expect(mock.formatStyleRulesJson).toHaveBeenCalledWith([SAMPLE_RULE]);
     });
@@ -136,7 +167,14 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await withTTY(true, async () => {
-        await program.parseAsync(['node', 'test', 'style-rules', 'list', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'style-rules',
+          'list',
+          '--format',
+          'table',
+        ]);
       });
 
       expect(mock.formatStyleRulesTable).toHaveBeenCalledWith([SAMPLE_RULE]);
@@ -151,12 +189,21 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await withTTY(false, async () => {
-        await program.parseAsync(['node', 'test', 'style-rules', 'list', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'style-rules',
+          'list',
+          '--format',
+          'table',
+        ]);
       });
 
       expect(mock.formatStyleRulesTable).not.toHaveBeenCalled();
       expect(mock.formatStyleRulesList).toHaveBeenCalledWith([SAMPLE_RULE]);
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('non-TTY')
+      );
       expect(Logger.output).toHaveBeenCalledWith('rules-list-text');
     });
   });
@@ -167,7 +214,16 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'create', '--name', 'X', '--language', 'en']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'create',
+        '--name',
+        'X',
+        '--language',
+        'en',
+      ]);
 
       expect(mock.create).toHaveBeenCalledWith({ name: 'X', language: 'en' });
       expect(Logger.success).toHaveBeenCalled();
@@ -179,13 +235,21 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'create',
-        '--name', 'X', '--language', 'en',
-        '--rules', '{"punctuation":{"quotation_mark":"use_guillemets"}}',
+        'node',
+        'test',
+        'style-rules',
+        'create',
+        '--name',
+        'X',
+        '--language',
+        'en',
+        '--rules',
+        '{"punctuation":{"quotation_mark":"use_guillemets"}}',
       ]);
 
       expect(mock.create).toHaveBeenCalledWith({
-        name: 'X', language: 'en',
+        name: 'X',
+        language: 'en',
         configuredRules: { punctuation: { quotation_mark: 'use_guillemets' } },
       });
     });
@@ -197,8 +261,16 @@ describe('registerStyleRules', () => {
 
       await expect(
         program.parseAsync([
-          'node', 'test', 'style-rules', 'create',
-          '--name', 'X', '--language', 'en', '--rules', '{garbage',
+          'node',
+          'test',
+          'style-rules',
+          'create',
+          '--name',
+          'X',
+          '--language',
+          'en',
+          '--rules',
+          '{garbage',
         ])
       ).rejects.toThrow();
       expect(handleError).toHaveBeenCalled();
@@ -211,12 +283,22 @@ describe('registerStyleRules', () => {
 
       await expect(
         program.parseAsync([
-          'node', 'test', 'style-rules', 'create',
-          '--name', 'X', '--language', 'en', '--rules', '["rule_a"]',
+          'node',
+          'test',
+          'style-rules',
+          'create',
+          '--name',
+          'X',
+          '--language',
+          'en',
+          '--rules',
+          '["rule_a"]',
         ])
       ).rejects.toThrow();
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('JSON object of category') }),
+        expect.objectContaining({
+          message: expect.stringContaining('JSON object of category'),
+        })
       );
     });
 
@@ -227,12 +309,22 @@ describe('registerStyleRules', () => {
 
       await expect(
         program.parseAsync([
-          'node', 'test', 'style-rules', 'create',
-          '--name', 'X', '--language', 'en', '--rules', '{"punctuation":"wrong"}',
+          'node',
+          'test',
+          'style-rules',
+          'create',
+          '--name',
+          'X',
+          '--language',
+          'en',
+          '--rules',
+          '{"punctuation":"wrong"}',
         ])
       ).rejects.toThrow();
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('category "punctuation"') }),
+        expect.objectContaining({
+          message: expect.stringContaining('category "punctuation"'),
+        })
       );
     });
 
@@ -243,12 +335,20 @@ describe('registerStyleRules', () => {
 
       await expect(
         program.parseAsync([
-          'node', 'test', 'style-rules', 'create',
-          '--name', 'X', '--language', 'en', '--rules', '{"x":{"y":42}}',
+          'node',
+          'test',
+          'style-rules',
+          'create',
+          '--name',
+          'X',
+          '--language',
+          'en',
+          '--rules',
+          '{"x":{"y":42}}',
         ])
       ).rejects.toThrow();
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('"x.y"') }),
+        expect.objectContaining({ message: expect.stringContaining('"x.y"') })
       );
     });
 
@@ -258,8 +358,16 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'create',
-        '--name', 'X', '--language', 'en', '--format', 'json',
+        'node',
+        'test',
+        'style-rules',
+        'create',
+        '--name',
+        'X',
+        '--language',
+        'en',
+        '--format',
+        'json',
       ]);
 
       expect(mock.formatStyleRuleJson).toHaveBeenCalledWith(SAMPLE_RULE);
@@ -283,7 +391,14 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'show', 'sr-1', '--detailed']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'show',
+        'sr-1',
+        '--detailed',
+      ]);
 
       expect(mock.show).toHaveBeenCalledWith('sr-1', true);
     });
@@ -293,7 +408,15 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'show', 'sr-1', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'show',
+        'sr-1',
+        '--format',
+        'json',
+      ]);
 
       expect(mock.formatStyleRuleJson).toHaveBeenCalledWith(SAMPLE_RULE);
     });
@@ -315,7 +438,15 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'update', 'sr-1', '--name', 'Renamed']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'update',
+        'sr-1',
+        '--name',
+        'Renamed',
+      ]);
 
       expect(mock.update).toHaveBeenCalledWith('sr-1', { name: 'Renamed' });
       expect(mock.replaceRules).not.toHaveBeenCalled();
@@ -328,8 +459,13 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'update', 'sr-1',
-        '--rules', '{"punctuation":{"quotation_mark":"use_guillemets"}}',
+        'node',
+        'test',
+        'style-rules',
+        'update',
+        'sr-1',
+        '--rules',
+        '{"punctuation":{"quotation_mark":"use_guillemets"}}',
       ]);
 
       expect(mock.update).not.toHaveBeenCalled();
@@ -344,8 +480,15 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'update', 'sr-1',
-        '--name', 'New', '--rules', '{"x":{"y":"z"}}',
+        'node',
+        'test',
+        'style-rules',
+        'update',
+        'sr-1',
+        '--name',
+        'New',
+        '--rules',
+        '{"x":{"y":"z"}}',
       ]);
 
       expect(mock.update).toHaveBeenCalledWith('sr-1', { name: 'New' });
@@ -369,8 +512,15 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'update', 'sr-1',
-        '--name', 'X', '--format', 'json',
+        'node',
+        'test',
+        'style-rules',
+        'update',
+        'sr-1',
+        '--name',
+        'X',
+        '--format',
+        'json',
       ]);
 
       expect(mock.formatStyleRuleJson).toHaveBeenCalled();
@@ -383,7 +533,14 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'delete', 'sr-1', '--yes']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'delete',
+        'sr-1',
+        '--yes',
+      ]);
 
       expect(mock.delete).toHaveBeenCalledWith('sr-1');
       expect(Logger.success).toHaveBeenCalled();
@@ -394,10 +551,19 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'delete', 'sr-1', '--dry-run']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'delete',
+        'sr-1',
+        '--dry-run',
+      ]);
 
       expect(mock.delete).not.toHaveBeenCalled();
-      expect(Logger.output).toHaveBeenCalledWith(expect.stringContaining('[dry-run]'));
+      expect(Logger.output).toHaveBeenCalledWith(
+        expect.stringContaining('[dry-run]')
+      );
     });
 
     it('should abort on declined confirmation', async () => {
@@ -408,7 +574,13 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'delete', 'sr-1']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'delete',
+        'sr-1',
+      ]);
 
       expect(mock.delete).not.toHaveBeenCalled();
       expect(Logger.info).toHaveBeenCalledWith('Aborted.');
@@ -422,7 +594,13 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'delete', 'sr-1']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'delete',
+        'sr-1',
+      ]);
 
       expect(mock.delete).toHaveBeenCalledWith('sr-1');
     });
@@ -434,7 +612,13 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'instructions', 'sr-1']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'instructions',
+        'sr-1',
+      ]);
 
       expect(mock.listInstructions).toHaveBeenCalledWith('sr-1');
       expect(mock.formatCustomInstructionsList).toHaveBeenCalled();
@@ -445,7 +629,15 @@ describe('registerStyleRules', () => {
       mockCreateStyleRulesCommand.mockResolvedValue(mock as any);
       const { program } = makeProgram();
 
-      await program.parseAsync(['node', 'test', 'style-rules', 'instructions', 'sr-1', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'style-rules',
+        'instructions',
+        'sr-1',
+        '--format',
+        'json',
+      ]);
 
       expect(mock.formatCustomInstructionJson).toHaveBeenCalled();
     });
@@ -456,7 +648,15 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await withTTY(true, async () => {
-        await program.parseAsync(['node', 'test', 'style-rules', 'instructions', 'sr-1', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'style-rules',
+          'instructions',
+          'sr-1',
+          '--format',
+          'table',
+        ]);
       });
 
       expect(mock.formatCustomInstructionsTable).toHaveBeenCalled();
@@ -471,12 +671,22 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await withTTY(false, async () => {
-        await program.parseAsync(['node', 'test', 'style-rules', 'instructions', 'sr-1', '--format', 'table']);
+        await program.parseAsync([
+          'node',
+          'test',
+          'style-rules',
+          'instructions',
+          'sr-1',
+          '--format',
+          'table',
+        ]);
       });
 
       expect(mock.formatCustomInstructionsTable).not.toHaveBeenCalled();
       expect(mock.formatCustomInstructionsList).toHaveBeenCalled();
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('non-TTY')
+      );
       expect(Logger.output).toHaveBeenCalledWith('instructions-list-text');
     });
 
@@ -485,7 +695,13 @@ describe('registerStyleRules', () => {
       const { program, handleError } = makeProgram();
 
       await expect(
-        program.parseAsync(['node', 'test', 'style-rules', 'instructions', 'sr-1'])
+        program.parseAsync([
+          'node',
+          'test',
+          'style-rules',
+          'instructions',
+          'sr-1',
+        ])
       ).rejects.toThrow('404');
       expect(handleError).toHaveBeenCalled();
     });
@@ -498,10 +714,19 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'add-instruction', 'sr-1', 'tone', 'Be formal',
+        'node',
+        'test',
+        'style-rules',
+        'add-instruction',
+        'sr-1',
+        'tone',
+        'Be formal',
       ]);
 
-      expect(mock.addInstruction).toHaveBeenCalledWith('sr-1', { label: 'tone', prompt: 'Be formal' });
+      expect(mock.addInstruction).toHaveBeenCalledWith('sr-1', {
+        label: 'tone',
+        prompt: 'Be formal',
+      });
     });
 
     it('should pass --source-language through', async () => {
@@ -510,12 +735,21 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'add-instruction', 'sr-1', 'tone', 'Be formal',
-        '--source-language', 'en',
+        'node',
+        'test',
+        'style-rules',
+        'add-instruction',
+        'sr-1',
+        'tone',
+        'Be formal',
+        '--source-language',
+        'en',
       ]);
 
       expect(mock.addInstruction).toHaveBeenCalledWith('sr-1', {
-        label: 'tone', prompt: 'Be formal', sourceLanguage: 'en',
+        label: 'tone',
+        prompt: 'Be formal',
+        sourceLanguage: 'en',
       });
     });
 
@@ -525,8 +759,15 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'add-instruction', 'sr-1', 'tone', 'Be formal',
-        '--format', 'json',
+        'node',
+        'test',
+        'style-rules',
+        'add-instruction',
+        'sr-1',
+        'tone',
+        'Be formal',
+        '--format',
+        'json',
       ]);
 
       expect(mock.formatCustomInstructionJson).toHaveBeenCalled();
@@ -540,10 +781,18 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'update-instruction', 'sr-1', 'tone', 'Be friendlier',
+        'node',
+        'test',
+        'style-rules',
+        'update-instruction',
+        'sr-1',
+        'tone',
+        'Be friendlier',
       ]);
 
-      expect(mock.updateInstruction).toHaveBeenCalledWith('sr-1', 'tone', { prompt: 'Be friendlier' });
+      expect(mock.updateInstruction).toHaveBeenCalledWith('sr-1', 'tone', {
+        prompt: 'Be friendlier',
+      });
     });
 
     it('should pass --source-language through', async () => {
@@ -552,12 +801,20 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'update-instruction', 'sr-1', 'tone', 'Be friendlier',
-        '--source-language', 'en',
+        'node',
+        'test',
+        'style-rules',
+        'update-instruction',
+        'sr-1',
+        'tone',
+        'Be friendlier',
+        '--source-language',
+        'en',
       ]);
 
       expect(mock.updateInstruction).toHaveBeenCalledWith('sr-1', 'tone', {
-        prompt: 'Be friendlier', sourceLanguage: 'en',
+        prompt: 'Be friendlier',
+        sourceLanguage: 'en',
       });
     });
 
@@ -567,8 +824,15 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'update-instruction', 'sr-1', 'tone', 'New',
-        '--format', 'json',
+        'node',
+        'test',
+        'style-rules',
+        'update-instruction',
+        'sr-1',
+        'tone',
+        'New',
+        '--format',
+        'json',
       ]);
 
       expect(mock.formatCustomInstructionJson).toHaveBeenCalled();
@@ -582,7 +846,13 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'remove-instruction', 'sr-1', 'tone', '--yes',
+        'node',
+        'test',
+        'style-rules',
+        'remove-instruction',
+        'sr-1',
+        'tone',
+        '--yes',
       ]);
 
       expect(mock.removeInstruction).toHaveBeenCalledWith('sr-1', 'tone');
@@ -595,11 +865,19 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'remove-instruction', 'sr-1', 'tone', '--dry-run',
+        'node',
+        'test',
+        'style-rules',
+        'remove-instruction',
+        'sr-1',
+        'tone',
+        '--dry-run',
       ]);
 
       expect(mock.removeInstruction).not.toHaveBeenCalled();
-      expect(Logger.output).toHaveBeenCalledWith(expect.stringContaining('[dry-run]'));
+      expect(Logger.output).toHaveBeenCalledWith(
+        expect.stringContaining('[dry-run]')
+      );
     });
 
     it('should abort on declined confirmation', async () => {
@@ -611,7 +889,12 @@ describe('registerStyleRules', () => {
       const { program } = makeProgram();
 
       await program.parseAsync([
-        'node', 'test', 'style-rules', 'remove-instruction', 'sr-1', 'tone',
+        'node',
+        'test',
+        'style-rules',
+        'remove-instruction',
+        'sr-1',
+        'tone',
       ]);
 
       expect(mock.removeInstruction).not.toHaveBeenCalled();
diff --git a/tests/unit/register-translate.test.ts b/tests/unit/register-translate.test.ts
index 5d0a5557..f50eda50 100644
--- a/tests/unit/register-translate.test.ts
+++ b/tests/unit/register-translate.test.ts
@@ -41,13 +41,16 @@ function setupProgram(): { program: Command; deps: Deps } {
     }),
     getApiKeyOrThrow: jest.fn(),
   };
-  registerTranslate(program, deps as unknown as Parameters<typeof registerTranslate>[1]);
+  registerTranslate(
+    program,
+    deps as unknown as Parameters<typeof registerTranslate>[1]
+  );
   return { program, deps };
 }
 
 function getOption(program: Command, long: string): Option {
-  const translateCmd = program.commands.find(c => c.name() === 'translate')!;
-  return translateCmd.options.find(o => o.long === long)!;
+  const translateCmd = program.commands.find((c) => c.name() === 'translate')!;
+  return translateCmd.options.find((o) => o.long === long)!;
 }
 
 describe('registerTranslate', () => {
@@ -59,14 +62,22 @@ describe('registerTranslate', () => {
 
   describe('alias', () => {
     it('registers t as an alias of translate', () => {
-      const translateCmd = program.commands.find(c => c.name() === 'translate')!;
+      const translateCmd = program.commands.find(
+        (c) => c.name() === 'translate'
+      )!;
       expect(translateCmd.aliases()).toContain('t');
     });
 
     it('shows the alias in help output', () => {
-      const translateCmd = program.commands.find(c => c.name() === 'translate')!;
+      const translateCmd = program.commands.find(
+        (c) => c.name() === 'translate'
+      )!;
       let helpOutput = '';
-      translateCmd.configureOutput({ writeOut: (str: string) => { helpOutput += str; } });
+      translateCmd.configureOutput({
+        writeOut: (str: string) => {
+          helpOutput += str;
+        },
+      });
       translateCmd.outputHelp();
       expect(helpOutput).toContain('translate|t');
     });
@@ -74,18 +85,30 @@ describe('registerTranslate', () => {
 
   describe('--output-format option', () => {
     it('should only accept docx as a valid choice', () => {
-      const translateCmd = program.commands.find(c => c.name() === 'translate')!;
-      const outputFormatOpt = translateCmd.options.find(o => o.long === '--output-format')!;
+      const translateCmd = program.commands.find(
+        (c) => c.name() === 'translate'
+      )!;
+      const outputFormatOpt = translateCmd.options.find(
+        (o) => o.long === '--output-format'
+      )!;
       expect(outputFormatOpt.argChoices).toEqual(['docx']);
     });
 
     it('should have correct help example showing PDF to DOCX conversion', () => {
-      const translateCmd = program.commands.find(c => c.name() === 'translate')!;
+      const translateCmd = program.commands.find(
+        (c) => c.name() === 'translate'
+      )!;
       let helpOutput = '';
-      translateCmd.configureOutput({ writeOut: (str: string) => { helpOutput += str; } });
+      translateCmd.configureOutput({
+        writeOut: (str: string) => {
+          helpOutput += str;
+        },
+      });
       translateCmd.outputHelp();
       expect(helpOutput).toContain('report.pdf --to de --output-format docx');
-      expect(helpOutput).not.toContain('report.docx --to de --output-format pdf');
+      expect(helpOutput).not.toContain(
+        'report.docx --to de --output-format pdf'
+      );
     });
   });
 
@@ -105,11 +128,13 @@ describe('registerTranslate', () => {
   });
 
   describe('--tm-threshold strict coercer', () => {
-    const coercerOf = (p: Command): (raw: string) => number => {
+    const coercerOf = (p: Command): ((raw: string) => number) => {
       const opt = getOption(p, '--tm-threshold');
-      const parseArg = (opt as unknown as {
-        parseArg: (raw: string, prev: number) => number;
-      }).parseArg;
+      const parseArg = (
+        opt as unknown as {
+          parseArg: (raw: string, prev: number) => number;
+        }
+      ).parseArg;
       return (raw: string) => parseArg(raw, 0);
     };
 
@@ -123,21 +148,25 @@ describe('registerTranslate', () => {
       expect(coercerOf(program)(raw)).toBe(expected);
     });
 
-    it.each([
-      ['80abc'],
-      ['0x40'],
-      ['1e2'],
-      ['50.5'],
-      [''],
-      ['abc'],
-    ])('rejects non-integer string %p with ValidationError', (raw) => {
-      expect(() => coercerOf(program)(raw)).toThrow(ValidationError);
-    });
+    it.each([['80abc'], ['0x40'], ['1e2'], ['50.5'], [''], ['abc']])(
+      'rejects non-integer string %p with ValidationError',
+      (raw) => {
+        expect(() => coercerOf(program)(raw)).toThrow(ValidationError);
+      }
+    );
   });
 
   describe('action-handler validation (before dry-run)', () => {
-    const baseArgs = (extra: string[]): string[] =>
-      ['node', 'cli', 'translate', 'hello', '--to', 'de', '--dry-run', ...extra];
+    const baseArgs = (extra: string[]): string[] => [
+      'node',
+      'cli',
+      'translate',
+      'hello',
+      '--to',
+      'de',
+      '--dry-run',
+      ...extra,
+    ];
 
     it('orphan --tm-threshold throws ValidationError (exit 6)', async () => {
       const { program: p, deps } = setupProgram();
@@ -145,25 +174,31 @@ describe('registerTranslate', () => {
       expect(deps.handleError).toHaveBeenCalledTimes(1);
       const err = deps.handleError.mock.calls[0]![0] as ValidationError;
       expect(err).toBeInstanceOf(ValidationError);
-      expect(err.message).toContain('--tm-threshold requires --translation-memory');
+      expect(err.message).toContain(
+        '--tm-threshold requires --translation-memory'
+      );
       expect(err.exitCode).toBe(6);
     });
 
     it('rejects threshold 101 via range guard (exit 6 with suggestion)', async () => {
       const { program: p, deps } = setupProgram();
-      await p.parseAsync(baseArgs(['--translation-memory', 'my-tm', '--tm-threshold', '101']));
+      await p.parseAsync(
+        baseArgs(['--translation-memory', 'my-tm', '--tm-threshold', '101'])
+      );
       expect(deps.handleError).toHaveBeenCalledTimes(1);
       const err = deps.handleError.mock.calls[0]![0] as ValidationError;
       expect(err).toBeInstanceOf(ValidationError);
       expect(err.message).toContain('got: 101');
       expect(err.suggestion).toBe(
-        'Use a value between 0 and 100, or omit --tm-threshold to use the default (75).',
+        'Use a value between 0 and 100, or omit --tm-threshold to use the default (75).'
       );
     });
 
     it('rejects threshold -1 via range guard', async () => {
       const { program: p, deps } = setupProgram();
-      await p.parseAsync(baseArgs(['--translation-memory', 'my-tm', '--tm-threshold', '-1']));
+      await p.parseAsync(
+        baseArgs(['--translation-memory', 'my-tm', '--tm-threshold', '-1'])
+      );
       expect(deps.handleError).toHaveBeenCalledTimes(1);
       const err = deps.handleError.mock.calls[0]![0] as ValidationError;
       expect(err.message).toContain('got: -1');
@@ -171,22 +206,30 @@ describe('registerTranslate', () => {
 
     it('accepts threshold 0 (boundary)', async () => {
       const { program: p, deps } = setupProgram();
-      await p.parseAsync(baseArgs(['--translation-memory', 'my-tm', '--tm-threshold', '0']));
+      await p.parseAsync(
+        baseArgs(['--translation-memory', 'my-tm', '--tm-threshold', '0'])
+      );
       expect(deps.handleError).not.toHaveBeenCalled();
     });
 
     it('accepts threshold 100 (boundary)', async () => {
       const { program: p, deps } = setupProgram();
-      await p.parseAsync(baseArgs(['--translation-memory', 'my-tm', '--tm-threshold', '100']));
+      await p.parseAsync(
+        baseArgs(['--translation-memory', 'my-tm', '--tm-threshold', '100'])
+      );
       expect(deps.handleError).not.toHaveBeenCalled();
     });
 
     it('rejects --translation-memory with --model-type latency_optimized', async () => {
       const { program: p, deps } = setupProgram();
-      await p.parseAsync(baseArgs([
-        '--translation-memory', 'my-tm',
-        '--model-type', 'latency_optimized',
-      ]));
+      await p.parseAsync(
+        baseArgs([
+          '--translation-memory',
+          'my-tm',
+          '--model-type',
+          'latency_optimized',
+        ])
+      );
       expect(deps.handleError).toHaveBeenCalledTimes(1);
       const err = deps.handleError.mock.calls[0]![0] as ValidationError;
       expect(err).toBeInstanceOf(ValidationError);
@@ -196,10 +239,14 @@ describe('registerTranslate', () => {
 
     it('rejects --translation-memory with --model-type prefer_quality_optimized', async () => {
       const { program: p, deps } = setupProgram();
-      await p.parseAsync(baseArgs([
-        '--translation-memory', 'my-tm',
-        '--model-type', 'prefer_quality_optimized',
-      ]));
+      await p.parseAsync(
+        baseArgs([
+          '--translation-memory',
+          'my-tm',
+          '--model-type',
+          'prefer_quality_optimized',
+        ])
+      );
       expect(deps.handleError).toHaveBeenCalledTimes(1);
       const err = deps.handleError.mock.calls[0]![0] as ValidationError;
       expect(err.message).toContain('requires quality_optimized model type');
@@ -207,10 +254,14 @@ describe('registerTranslate', () => {
 
     it('accepts --translation-memory with --model-type quality_optimized', async () => {
       const { program: p, deps } = setupProgram();
-      await p.parseAsync(baseArgs([
-        '--translation-memory', 'my-tm',
-        '--model-type', 'quality_optimized',
-      ]));
+      await p.parseAsync(
+        baseArgs([
+          '--translation-memory',
+          'my-tm',
+          '--model-type',
+          'quality_optimized',
+        ])
+      );
       expect(deps.handleError).not.toHaveBeenCalled();
     });
 
@@ -233,35 +284,55 @@ describe('registerTranslate', () => {
     it('emits translation-memory, threshold, and forced-model lines when TM set', async () => {
       const { program: p } = setupProgram();
       await p.parseAsync([
-        'node', 'cli', 'translate', 'hello',
-        '--to', 'de', '--dry-run',
-        '--translation-memory', 'my-tm',
-        '--tm-threshold', '80',
+        'node',
+        'cli',
+        'translate',
+        'hello',
+        '--to',
+        'de',
+        '--dry-run',
+        '--translation-memory',
+        'my-tm',
+        '--tm-threshold',
+        '80',
       ]);
-      const out = Logger.output.mock.calls.map(c => c[0]).join('\n');
+      const out = Logger.output.mock.calls.map((c) => c[0]).join('\n');
       expect(out).toContain('[dry-run] Translation memory: my-tm');
       expect(out).toContain('[dry-run] Match threshold: 80');
-      expect(out).toContain('[dry-run] Model: quality_optimized (forced by --translation-memory)');
+      expect(out).toContain(
+        '[dry-run] Model: quality_optimized (forced by --translation-memory)'
+      );
     });
 
     it('uses default threshold 75 when --tm-threshold not provided', async () => {
       const { program: p } = setupProgram();
       await p.parseAsync([
-        'node', 'cli', 'translate', 'hello',
-        '--to', 'de', '--dry-run',
-        '--translation-memory', 'my-tm',
+        'node',
+        'cli',
+        'translate',
+        'hello',
+        '--to',
+        'de',
+        '--dry-run',
+        '--translation-memory',
+        'my-tm',
       ]);
-      const out = Logger.output.mock.calls.map(c => c[0]).join('\n');
+      const out = Logger.output.mock.calls.map((c) => c[0]).join('\n');
       expect(out).toContain('[dry-run] Match threshold: 75');
     });
 
     it('does not emit translation-memory lines when flag absent', async () => {
       const { program: p } = setupProgram();
       await p.parseAsync([
-        'node', 'cli', 'translate', 'hello',
-        '--to', 'de', '--dry-run',
+        'node',
+        'cli',
+        'translate',
+        'hello',
+        '--to',
+        'de',
+        '--dry-run',
       ]);
-      const out = Logger.output.mock.calls.map(c => c[0]).join('\n');
+      const out = Logger.output.mock.calls.map((c) => c[0]).join('\n');
       expect(out).not.toContain('[dry-run] Translation memory');
       expect(out).not.toContain('[dry-run] Match threshold');
     });
diff --git a/tests/unit/register-usage.test.ts b/tests/unit/register-usage.test.ts
index 33831434..1d41d39e 100644
--- a/tests/unit/register-usage.test.ts
+++ b/tests/unit/register-usage.test.ts
@@ -24,15 +24,28 @@ import { registerUsage } from '../../src/cli/commands/register-usage';
 import { createUsageCommand } from '../../src/cli/commands/service-factory';
 import { Logger } from '../../src/utils/logger';
 
-const mockCreateUsageCommand = createUsageCommand as jest.MockedFunction<typeof createUsageCommand>;
-
-async function withTTY<T>(value: boolean, fn: () => Promise<T> | T): Promise<T> {
+const mockCreateUsageCommand = createUsageCommand as jest.MockedFunction<
+  typeof createUsageCommand
+>;
+
+async function withTTY<T>(
+  value: boolean,
+  fn: () => Promise<T> | T
+): Promise<T> {
   const original = process.stdout.isTTY;
-  Object.defineProperty(process.stdout, 'isTTY', { value, configurable: true, writable: true });
+  Object.defineProperty(process.stdout, 'isTTY', {
+    value,
+    configurable: true,
+    writable: true,
+  });
   try {
     return await fn();
   } finally {
-    Object.defineProperty(process.stdout, 'isTTY', { value: original, configurable: true, writable: true });
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: original,
+      configurable: true,
+      writable: true,
+    });
   }
 }
 
@@ -80,10 +93,14 @@ describe('registerUsage', () => {
       await program.parseAsync(['node', 'test', 'usage', '--format', 'table']);
     });
 
-    expect(mockUsageCommandInstance.formatUsageTable).toHaveBeenCalledWith(usage);
+    expect(mockUsageCommandInstance.formatUsageTable).toHaveBeenCalledWith(
+      usage
+    );
     expect(mockUsageCommandInstance.formatUsage).not.toHaveBeenCalled();
     expect(Logger.output).toHaveBeenCalledWith('usage-table');
-    expect(Logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
+    expect(Logger.warn).not.toHaveBeenCalledWith(
+      expect.stringContaining('non-TTY')
+    );
   });
 
   it('should fall back to plain text with a warn when --format table in non-TTY', async () => {
@@ -97,7 +114,9 @@ describe('registerUsage', () => {
 
     expect(mockUsageCommandInstance.formatUsageTable).not.toHaveBeenCalled();
     expect(mockUsageCommandInstance.formatUsage).toHaveBeenCalledWith(usage);
-    expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('non-TTY'));
+    expect(Logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('non-TTY')
+    );
     expect(Logger.output).toHaveBeenCalledWith('plain usage');
   });
 
@@ -106,6 +125,8 @@ describe('registerUsage', () => {
 
     await program.parseAsync(['node', 'test', 'usage']);
 
-    expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'boom' }));
+    expect(handleError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'boom' })
+    );
   });
 });
diff --git a/tests/unit/register-voice.test.ts b/tests/unit/register-voice.test.ts
index 2556c1f8..3a967f40 100644
--- a/tests/unit/register-voice.test.ts
+++ b/tests/unit/register-voice.test.ts
@@ -1,5 +1,3 @@
- 
-
 import { Command } from 'commander';
 
 // ── Mock chalk ──────────────────────────────────────────────────────────────
@@ -63,7 +61,9 @@ function resetAllMockImplementations() {
   mockTranslate.mockResolvedValue('Translated audio text');
   mockTranslateFromStdin.mockResolvedValue('Translated stdin text');
 
-  const { createVoiceCommand } = require('../../src/cli/commands/service-factory');
+  const {
+    createVoiceCommand,
+  } = require('../../src/cli/commands/service-factory');
   createVoiceCommand.mockResolvedValue(mockVoiceCmdObj);
 }
 
@@ -76,7 +76,9 @@ describe('registerVoice', () => {
   beforeEach(() => {
     resetAllMockImplementations();
     mockResolveGlossaryId.mockReset();
-    mockResolveGlossaryId.mockImplementation((id: string) => Promise.resolve(id));
+    mockResolveGlossaryId.mockImplementation((id: string) =>
+      Promise.resolve(id)
+    );
 
     program = new Command();
     program.exitOverride();
@@ -91,26 +93,40 @@ describe('registerVoice', () => {
   });
 
   async function loadAndRegister() {
-    const { registerVoice } = await import('../../src/cli/commands/register-voice');
-    registerVoice(program, { getApiKeyAndOptions, createDeepLClient, handleError } as any);
+    const { registerVoice } =
+      await import('../../src/cli/commands/register-voice');
+    registerVoice(program, {
+      getApiKeyAndOptions,
+      createDeepLClient,
+      handleError,
+    } as any);
   }
 
   it('should throw error when --to is missing', async () => {
     await loadAndRegister();
     await expect(
-      program.parseAsync(['node', 'test', 'voice', 'recording.ogg']),
+      program.parseAsync(['node', 'test', 'voice', 'recording.ogg'])
     ).rejects.toThrow(/required option.*--to/i);
   });
 
   it('should call translate for file argument and Logger.output the result', async () => {
     await loadAndRegister();
-    await program.parseAsync(['node', 'test', 'voice', 'recording.ogg', '--to', 'de']);
+    await program.parseAsync([
+      'node',
+      'test',
+      'voice',
+      'recording.ogg',
+      '--to',
+      'de',
+    ]);
 
-    const { createVoiceCommand } = require('../../src/cli/commands/service-factory');
+    const {
+      createVoiceCommand,
+    } = require('../../src/cli/commands/service-factory');
     expect(createVoiceCommand).toHaveBeenCalledWith(getApiKeyAndOptions);
     expect(mockTranslate).toHaveBeenCalledWith(
       'recording.ogg',
-      expect.objectContaining({ to: 'de' }),
+      expect.objectContaining({ to: 'de' })
     );
     expect(mockLogger.output).toHaveBeenCalledWith('Translated audio text');
   });
@@ -120,7 +136,7 @@ describe('registerVoice', () => {
     await program.parseAsync(['node', 'test', 'voice', '-', '--to', 'es']);
 
     expect(mockTranslateFromStdin).toHaveBeenCalledWith(
-      expect.objectContaining({ to: 'es' }),
+      expect.objectContaining({ to: 'es' })
     );
     expect(mockLogger.output).toHaveBeenCalledWith('Translated stdin text');
   });
@@ -131,7 +147,14 @@ describe('registerVoice', () => {
 
     await loadAndRegister();
     await expect(
-      program.parseAsync(['node', 'test', 'voice', 'recording.ogg', '--to', 'de']),
+      program.parseAsync([
+        'node',
+        'test',
+        'voice',
+        'recording.ogg',
+        '--to',
+        'de',
+      ])
     ).rejects.toThrow('Voice API unavailable');
 
     expect(handleError).toHaveBeenCalledWith(translateError);
@@ -140,16 +163,27 @@ describe('registerVoice', () => {
   it('should pass format and other options through correctly', async () => {
     await loadAndRegister();
     await program.parseAsync([
-      'node', 'test', 'voice', 'recording.ogg',
-      '--to', 'de',
-      '--from', 'en',
-      '--formality', 'more',
-      '--glossary', 'gloss-123',
-      '--content-type', 'audio/ogg',
-      '--chunk-size', '8000',
-      '--chunk-interval', '300',
+      'node',
+      'test',
+      'voice',
+      'recording.ogg',
+      '--to',
+      'de',
+      '--from',
+      'en',
+      '--formality',
+      'more',
+      '--glossary',
+      'gloss-123',
+      '--content-type',
+      'audio/ogg',
+      '--chunk-size',
+      '8000',
+      '--chunk-interval',
+      '300',
       '--no-stream',
-      '--format', 'json',
+      '--format',
+      'json',
     ]);
 
     expect(mockTranslate).toHaveBeenCalledWith(
@@ -164,7 +198,7 @@ describe('registerVoice', () => {
         chunkInterval: 300,
         stream: false,
         format: 'json',
-      }),
+      })
     );
   });
 
@@ -177,17 +211,35 @@ describe('registerVoice', () => {
     ])('should reject %s --chunk-size (%s)', async (_label, value) => {
       await loadAndRegister();
       await expect(
-        program.parseAsync(['node', 'test', 'voice', 'recording.ogg', '--to', 'de', '--chunk-size', value]),
+        program.parseAsync([
+          'node',
+          'test',
+          'voice',
+          'recording.ogg',
+          '--to',
+          'de',
+          '--chunk-size',
+          value,
+        ])
       ).rejects.toThrow(/chunk-size/i);
     });
 
     it('should accept valid --chunk-size', async () => {
       await loadAndRegister();
-      await program.parseAsync(['node', 'test', 'voice', 'recording.ogg', '--to', 'de', '--chunk-size', '3200']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'voice',
+        'recording.ogg',
+        '--to',
+        'de',
+        '--chunk-size',
+        '3200',
+      ]);
 
       expect(mockTranslate).toHaveBeenCalledWith(
         'recording.ogg',
-        expect.objectContaining({ chunkSize: 3200 }),
+        expect.objectContaining({ chunkSize: 3200 })
       );
     });
 
@@ -199,17 +251,35 @@ describe('registerVoice', () => {
     ])('should reject %s --chunk-interval (%s)', async (_label, value) => {
       await loadAndRegister();
       await expect(
-        program.parseAsync(['node', 'test', 'voice', 'recording.ogg', '--to', 'de', '--chunk-interval', value]),
+        program.parseAsync([
+          'node',
+          'test',
+          'voice',
+          'recording.ogg',
+          '--to',
+          'de',
+          '--chunk-interval',
+          value,
+        ])
       ).rejects.toThrow(/chunk-interval/i);
     });
 
     it('should accept valid --chunk-interval', async () => {
       await loadAndRegister();
-      await program.parseAsync(['node', 'test', 'voice', 'recording.ogg', '--to', 'de', '--chunk-interval', '100']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'voice',
+        'recording.ogg',
+        '--to',
+        'de',
+        '--chunk-interval',
+        '100',
+      ]);
 
       expect(mockTranslate).toHaveBeenCalledWith(
         'recording.ogg',
-        expect.objectContaining({ chunkInterval: 100 }),
+        expect.objectContaining({ chunkInterval: 100 })
       );
     });
 
@@ -217,24 +287,48 @@ describe('registerVoice', () => {
       ['non-numeric', 'abc'],
       ['negative', '-1'],
       ['excessively large', '101'],
-    ])('should reject %s --max-reconnect-attempts (%s)', async (_label, value) => {
-      await loadAndRegister();
-      await expect(
-        program.parseAsync(['node', 'test', 'voice', 'recording.ogg', '--to', 'de', '--max-reconnect-attempts', value]),
-      ).rejects.toThrow(/max-reconnect-attempts/i);
-    });
+    ])(
+      'should reject %s --max-reconnect-attempts (%s)',
+      async (_label, value) => {
+        await loadAndRegister();
+        await expect(
+          program.parseAsync([
+            'node',
+            'test',
+            'voice',
+            'recording.ogg',
+            '--to',
+            'de',
+            '--max-reconnect-attempts',
+            value,
+          ])
+        ).rejects.toThrow(/max-reconnect-attempts/i);
+      }
+    );
 
     it.each([
       ['zero (disable reconnection)', '0', 0],
       ['valid', '5', 5],
-    ])('should accept %s --max-reconnect-attempts (%s)', async (_label, value, expected) => {
-      await loadAndRegister();
-      await program.parseAsync(['node', 'test', 'voice', 'recording.ogg', '--to', 'de', '--max-reconnect-attempts', value]);
-
-      expect(mockTranslate).toHaveBeenCalledWith(
-        'recording.ogg',
-        expect.objectContaining({ maxReconnectAttempts: expected }),
-      );
-    });
+    ])(
+      'should accept %s --max-reconnect-attempts (%s)',
+      async (_label, value, expected) => {
+        await loadAndRegister();
+        await program.parseAsync([
+          'node',
+          'test',
+          'voice',
+          'recording.ogg',
+          '--to',
+          'de',
+          '--max-reconnect-attempts',
+          value,
+        ]);
+
+        expect(mockTranslate).toHaveBeenCalledWith(
+          'recording.ogg',
+          expect.objectContaining({ maxReconnectAttempts: expected })
+        );
+      }
+    );
   });
 });
diff --git a/tests/unit/register-write.test.ts b/tests/unit/register-write.test.ts
index 01229654..58e419cf 100644
--- a/tests/unit/register-write.test.ts
+++ b/tests/unit/register-write.test.ts
@@ -74,7 +74,12 @@ describe('registerWrite', () => {
     createDeepLClient = jest.fn();
     getConfigService = jest.fn();
     getCacheService = jest.fn();
-    registerWrite(program, { createDeepLClient, getConfigService, getCacheService, handleError });
+    registerWrite(program, {
+      createDeepLClient,
+      getConfigService,
+      getCacheService,
+      handleError,
+    });
   });
 
   afterEach(() => {
@@ -83,14 +88,17 @@ describe('registerWrite', () => {
 
   describe('alias', () => {
     it('registers w as an alias of write', () => {
-      const writeCmd = program.commands.find(c => c.name() === 'write')!;
+      const writeCmd = program.commands.find((c) => c.name() === 'write')!;
       expect(writeCmd.aliases()).toContain('w');
     });
 
     it('dispatches w to the write action', async () => {
       mockWriteCommand.improve.mockResolvedValue('Improved text');
       await program.parseAsync(['node', 'test', 'w', 'Hello world']);
-      expect(mockWriteCommand.improve).toHaveBeenCalledWith('Hello world', expect.any(Object));
+      expect(mockWriteCommand.improve).toHaveBeenCalledWith(
+        'Hello world',
+        expect.any(Object)
+      );
       expect(Logger.output).toHaveBeenCalledWith('Improved text');
     });
   });
@@ -99,71 +107,129 @@ describe('registerWrite', () => {
     it('should improve text and output result', async () => {
       mockWriteCommand.improve.mockResolvedValue('Improved text');
       await program.parseAsync(['node', 'test', 'write', 'Hello world']);
-      expect(mockWriteCommand.improve).toHaveBeenCalledWith('Hello world', expect.any(Object));
+      expect(mockWriteCommand.improve).toHaveBeenCalledWith(
+        'Hello world',
+        expect.any(Object)
+      );
       expect(Logger.output).toHaveBeenCalledWith('Improved text');
     });
 
     it('should pass lang option via --lang', async () => {
       mockWriteCommand.improve.mockResolvedValue('Hallo');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'de']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--lang',
+        'de',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'de' }),
+        expect.objectContaining({ lang: 'de' })
       );
     });
 
     it('should pass style option', async () => {
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--style', 'business']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--style',
+        'business',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ style: 'business' }),
+        expect.objectContaining({ style: 'business' })
       );
     });
 
     it('should pass tone option', async () => {
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--tone', 'friendly']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--tone',
+        'friendly',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ tone: 'friendly' }),
+        expect.objectContaining({ tone: 'friendly' })
       );
     });
 
     it('should map -l short flag to --lang', async () => {
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '-l', 'en-US']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '-l',
+        'en-US',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'en-us' }),
+        expect.objectContaining({ lang: 'en-us' })
       );
     });
 
     it('should accept --to as a long-only alias of --lang', async () => {
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--to', 'de']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--to',
+        'de',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'de' }),
+        expect.objectContaining({ lang: 'de' })
       );
     });
 
     it('should accept --to and --lang when they carry the same value', async () => {
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--to', 'de', '--lang', 'de']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--to',
+        'de',
+        '--lang',
+        'de',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'de' }),
+        expect.objectContaining({ lang: 'de' })
       );
       expect(handleError).not.toHaveBeenCalled();
     });
 
     it('should reject --to and --lang when they carry different values', async () => {
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--to', 'de', '--lang', 'fr']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--to',
+        'de',
+        '--lang',
+        'fr',
+      ]);
       expect(handleError).toHaveBeenCalledWith(
         expect.objectContaining({
-          message: expect.stringContaining('Cannot specify both --to and --lang with different values'),
-        }),
+          message: expect.stringContaining(
+            'Cannot specify both --to and --lang with different values'
+          ),
+        })
       );
     });
 
@@ -171,45 +237,79 @@ describe('registerWrite', () => {
       // write does not own -t; commander should leave it unparsed or reject it,
       // not treat it as an alias for --to. If this test starts passing with
       // lang='en', it means we accidentally bound -t here.
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '-t', 'en']).catch(() => undefined);
+      await program
+        .parseAsync(['node', 'test', 'write', 'Hello', '-t', 'en'])
+        .catch(() => undefined);
       expect(mockWriteCommand.improve).not.toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'en' }),
+        expect.objectContaining({ lang: 'en' })
       );
     });
 
     it('should accept --tone as long flag only', async () => {
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--tone', 'friendly']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--tone',
+        'friendly',
+      ]);
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ tone: 'friendly' }),
+        expect.objectContaining({ tone: 'friendly' })
       );
     });
   });
 
   describe('validation', () => {
     it('should reject a code that is not shaped like a language tag', async () => {
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'de_ch']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--lang',
+        'de_ch',
+      ]);
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('Invalid language code') }),
+        expect.objectContaining({
+          message: expect.stringContaining('Invalid language code'),
+        })
       );
     });
 
     it('should defer a well-formed code the bundled list does not have', async () => {
       // The bundled list is a snapshot, so a well-formed code it does not list
       // goes through with a warning that still names the bundled set.
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'xx']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--lang',
+        'xx',
+      ]);
 
       expect(handleError).not.toHaveBeenCalled();
       expect(mockWriteCommand.improve).toHaveBeenCalled();
-      const warning = (Logger.warn as jest.Mock).mock.calls.map(c => String(c[0])).join('\n');
+      const warning = (Logger.warn as jest.Mock).mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(warning).toContain('not in the bundled Write language list');
       expect(warning).toContain(WRITE_TARGET_LANGUAGES.join(', '));
     });
 
     it('should enumerate every supported language when rejecting malformed input', async () => {
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', 'nope_nope']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--lang',
+        'nope_nope',
+      ]);
       const error = handleError.mock.calls[0]?.[0] as Error;
       // Asserted as the joined list: individual codes like 'de' occur inside
       // ordinary words in the message, so per-code checks cannot fail.
@@ -221,21 +321,38 @@ describe('registerWrite', () => {
         jest.clearAllMocks();
         mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
         mockWriteCommand.improve.mockResolvedValue('ok');
-        await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', code]);
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'Hello',
+          '--lang',
+          code,
+        ]);
         expect(handleError).not.toHaveBeenCalled();
       }
     });
 
-    it.each(['ja', 'ko', 'zh', 'zh-hans'])('should accept new target language %s', async (lang) => {
-      mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
-      mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', lang]);
-      expect(mockWriteCommand.improve).toHaveBeenCalledWith(
-        'Hello',
-        expect.objectContaining({ lang }),
-      );
-      expect(handleError).not.toHaveBeenCalled();
-    });
+    it.each(['ja', 'ko', 'zh', 'zh-hans'])(
+      'should accept new target language %s',
+      async (lang) => {
+        mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
+        mockWriteCommand.improve.mockResolvedValue('ok');
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'Hello',
+          '--lang',
+          lang,
+        ]);
+        expect(mockWriteCommand.improve).toHaveBeenCalledWith(
+          'Hello',
+          expect.objectContaining({ lang })
+        );
+        expect(handleError).not.toHaveBeenCalled();
+      }
+    );
 
     // `deepl languages` prints lowercase codes and `translate --to` lowercases
     // before validating, so write rejecting them made the CLI's own output
@@ -247,94 +364,201 @@ describe('registerWrite', () => {
       ['pt-br', 'pt-br'],
       ['zh-Hans', 'zh-hans'],
       ['DE', 'de'],
-    ])('should accept --lang %s and normalize it to %s', async (input, canonical) => {
-      mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
-      mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--lang', input]);
-      expect(handleError).not.toHaveBeenCalled();
-      expect(mockWriteCommand.improve).toHaveBeenCalledWith(
-        'Hello',
-        expect.objectContaining({ lang: canonical }),
-      );
-    });
+    ])(
+      'should accept --lang %s and normalize it to %s',
+      async (input, canonical) => {
+        mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
+        mockWriteCommand.improve.mockResolvedValue('ok');
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'Hello',
+          '--lang',
+          input,
+        ]);
+        expect(handleError).not.toHaveBeenCalled();
+        expect(mockWriteCommand.improve).toHaveBeenCalledWith(
+          'Hello',
+          expect.objectContaining({ lang: canonical })
+        );
+      }
+    );
 
     it('should accept the same casing via --to as via --lang', async () => {
       mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
       mockWriteCommand.improve.mockResolvedValue('ok');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--to', 'pt-br']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--to',
+        'pt-br',
+      ]);
       expect(handleError).not.toHaveBeenCalled();
       expect(mockWriteCommand.improve).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ lang: 'pt-br' }),
+        expect.objectContaining({ lang: 'pt-br' })
       );
     });
 
     it('should reject both --style and --tone', async () => {
       await program.parseAsync([
-        'node', 'test', 'write', 'Hello', '--style', 'business', '--tone', 'friendly',
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--style',
+        'business',
+        '--tone',
+        'friendly',
       ]);
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('Cannot specify both') }),
+        expect.objectContaining({
+          message: expect.stringContaining('Cannot specify both'),
+        })
       );
     });
 
     it('should reject invalid style value', async () => {
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--style', 'fancy']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--style',
+        'fancy',
+      ]);
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('Invalid writing style: fancy') }),
+        expect.objectContaining({
+          message: expect.stringContaining('Invalid writing style: fancy'),
+        })
       );
     });
 
     it('should accept all valid style values', async () => {
-      const validStyles = ['default', 'simple', 'business', 'academic', 'casual', 'prefer_simple', 'prefer_business', 'prefer_academic', 'prefer_casual'];
+      const validStyles = [
+        'default',
+        'simple',
+        'business',
+        'academic',
+        'casual',
+        'prefer_simple',
+        'prefer_business',
+        'prefer_academic',
+        'prefer_casual',
+      ];
       for (const style of validStyles) {
         jest.clearAllMocks();
         mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
         mockWriteCommand.improve.mockResolvedValue('ok');
-        await program.parseAsync(['node', 'test', 'write', 'Hello', '--style', style]);
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'Hello',
+          '--style',
+          style,
+        ]);
         expect(handleError).not.toHaveBeenCalled();
       }
     });
 
     it('should reject invalid tone value', async () => {
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--tone', 'angry']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--tone',
+        'angry',
+      ]);
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('Invalid tone: angry') }),
+        expect.objectContaining({
+          message: expect.stringContaining('Invalid tone: angry'),
+        })
       );
     });
 
     it('should accept all valid tone values', async () => {
-      const validTones = ['default', 'enthusiastic', 'friendly', 'confident', 'diplomatic', 'prefer_enthusiastic', 'prefer_friendly', 'prefer_confident', 'prefer_diplomatic'];
+      const validTones = [
+        'default',
+        'enthusiastic',
+        'friendly',
+        'confident',
+        'diplomatic',
+        'prefer_enthusiastic',
+        'prefer_friendly',
+        'prefer_confident',
+        'prefer_diplomatic',
+      ];
       for (const tone of validTones) {
         jest.clearAllMocks();
         mockCreateWriteCommand.mockResolvedValue(mockWriteCommand);
         mockWriteCommand.improve.mockResolvedValue('ok');
-        await program.parseAsync(['node', 'test', 'write', 'Hello', '--tone', tone]);
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'Hello',
+          '--tone',
+          tone,
+        ]);
         expect(handleError).not.toHaveBeenCalled();
       }
     });
 
     it('should warn when --backup is used without --fix', async () => {
       mockWriteCommand.improve.mockResolvedValue('Improved text');
-      await program.parseAsync(['node', 'test', 'write', 'Some text', '--backup']);
-      expect(Logger.warn).toHaveBeenCalledWith('--backup has no effect without --fix');
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Some text',
+        '--backup',
+      ]);
+      expect(Logger.warn).toHaveBeenCalledWith(
+        '--backup has no effect without --fix'
+      );
     });
 
     it('should reject unsupported format', async () => {
       await expect(
-        program.parseAsync(['node', 'test', 'write', 'Hello', '--format', 'table']),
+        program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'Hello',
+          '--format',
+          'table',
+        ])
       ).rejects.toThrow(/invalid.*Allowed choices are text, json/);
     });
 
     it('should reject unknown format values', async () => {
       await expect(
-        program.parseAsync(['node', 'test', 'write', 'Hello', '--format', 'xml']),
+        program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'Hello',
+          '--format',
+          'xml',
+        ])
       ).rejects.toThrow(/invalid.*Allowed choices are text, json/);
     });
 
     it('should accept json format', async () => {
       mockWriteCommand.improve.mockResolvedValue('{"result": "ok"}');
-      await program.parseAsync(['node', 'test', 'write', 'Hello', '--format', 'json']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello',
+        '--format',
+        'json',
+      ]);
       expect(handleError).not.toHaveBeenCalled();
       expect(mockWriteCommand.improve).toHaveBeenCalled();
     });
@@ -345,39 +569,80 @@ describe('registerWrite', () => {
       mockExistsSync.mockReturnValue(true);
       mockWriteCommand.improveFile.mockResolvedValue('Improved file text');
       await program.parseAsync(['node', 'test', 'write', 'file.txt']);
-      expect(mockWriteCommand.improveFile).toHaveBeenCalledWith('file.txt', expect.any(Object));
+      expect(mockWriteCommand.improveFile).toHaveBeenCalledWith(
+        'file.txt',
+        expect.any(Object)
+      );
       expect(Logger.output).toHaveBeenCalledWith('Improved file text');
     });
   });
 
   describe('--check mode', () => {
     it('should set exitCode 8 when text needs improvement', async () => {
-      mockWriteCommand.checkText.mockResolvedValue({ needsImprovement: true, changes: 3 });
-      await program.parseAsync(['node', 'test', 'write', 'bad text', '--check']);
-      expect(mockWriteCommand.checkText).toHaveBeenCalledWith('bad text', expect.any(Object));
+      mockWriteCommand.checkText.mockResolvedValue({
+        needsImprovement: true,
+        changes: 3,
+      });
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'bad text',
+        '--check',
+      ]);
+      expect(mockWriteCommand.checkText).toHaveBeenCalledWith(
+        'bad text',
+        expect.any(Object)
+      );
       expect(Logger.warn).toHaveBeenCalled();
       expect(process.exitCode).toBe(8);
     });
 
     it('should not set exitCode when text is clean', async () => {
-      mockWriteCommand.checkText.mockResolvedValue({ needsImprovement: false, changes: 0 });
-      await program.parseAsync(['node', 'test', 'write', 'good text', '--check']);
+      mockWriteCommand.checkText.mockResolvedValue({
+        needsImprovement: false,
+        changes: 0,
+      });
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'good text',
+        '--check',
+      ]);
       expect(Logger.success).toHaveBeenCalled();
       expect(process.exitCode).toBeUndefined();
     });
 
     it('should check file when path exists', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.checkFile.mockResolvedValue({ needsImprovement: true, changes: 2 });
-      await program.parseAsync(['node', 'test', 'write', 'file.txt', '--check']);
-      expect(mockWriteCommand.checkFile).toHaveBeenCalledWith('file.txt', expect.any(Object));
+      mockWriteCommand.checkFile.mockResolvedValue({
+        needsImprovement: true,
+        changes: 2,
+      });
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'file.txt',
+        '--check',
+      ]);
+      expect(mockWriteCommand.checkFile).toHaveBeenCalledWith(
+        'file.txt',
+        expect.any(Object)
+      );
       expect(Logger.info).toHaveBeenCalled();
       expect(process.exitCode).toBe(8);
     });
 
     it('should return normally without calling process.exit()', async () => {
-      const exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => {}) as never);
-      mockWriteCommand.checkText.mockResolvedValue({ needsImprovement: true, changes: 1 });
+      const exitSpy = jest
+        .spyOn(process, 'exit')
+        .mockImplementation((() => {}) as never);
+      mockWriteCommand.checkText.mockResolvedValue({
+        needsImprovement: true,
+        changes: 1,
+      });
       await program.parseAsync(['node', 'test', 'write', 'text', '--check']);
       expect(exitSpy).not.toHaveBeenCalled();
       exitSpy.mockRestore();
@@ -386,35 +651,69 @@ describe('registerWrite', () => {
 
   describe('--fix mode', () => {
     it('should error when input is not a file', async () => {
-      await program.parseAsync(['node', 'test', 'write', 'not-a-file', '--fix']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'not-a-file',
+        '--fix',
+      ]);
       expect(handleError).toHaveBeenCalledWith(
-        expect.objectContaining({ message: expect.stringContaining('--fix requires a file path') }),
+        expect.objectContaining({
+          message: expect.stringContaining('--fix requires a file path'),
+        })
       );
     });
 
     it('should fix file and report success', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.autoFixFile.mockResolvedValue({ fixed: true, changes: 5, backupPath: 'file.txt.bak' });
+      mockWriteCommand.autoFixFile.mockResolvedValue({
+        fixed: true,
+        changes: 5,
+        backupPath: 'file.txt.bak',
+      });
       await program.parseAsync(['node', 'test', 'write', 'file.txt', '--fix']);
-      expect(mockWriteCommand.autoFixFile).toHaveBeenCalledWith('file.txt', expect.any(Object));
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('File improved'));
-      expect(Logger.info).toHaveBeenCalledWith(expect.stringContaining('Backup'));
+      expect(mockWriteCommand.autoFixFile).toHaveBeenCalledWith(
+        'file.txt',
+        expect.any(Object)
+      );
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('File improved')
+      );
+      expect(Logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('Backup')
+      );
     });
 
     it('should report no improvements needed', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.autoFixFile.mockResolvedValue({ fixed: false, changes: 0 });
+      mockWriteCommand.autoFixFile.mockResolvedValue({
+        fixed: false,
+        changes: 0,
+      });
       await program.parseAsync(['node', 'test', 'write', 'file.txt', '--fix']);
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('No improvements needed'));
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('No improvements needed')
+      );
     });
 
     it('should pass backup option', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.autoFixFile.mockResolvedValue({ fixed: true, changes: 1 });
-      await program.parseAsync(['node', 'test', 'write', 'file.txt', '--fix', '--backup']);
+      mockWriteCommand.autoFixFile.mockResolvedValue({
+        fixed: true,
+        changes: 1,
+      });
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'file.txt',
+        '--fix',
+        '--backup',
+      ]);
       expect(mockWriteCommand.autoFixFile).toHaveBeenCalledWith(
         'file.txt',
-        expect.objectContaining({ createBackup: true }),
+        expect.objectContaining({ createBackup: true })
       );
     });
   });
@@ -426,9 +725,20 @@ describe('registerWrite', () => {
         improved: 'new',
         diff: '-old\n+new',
       });
-      await program.parseAsync(['node', 'test', 'write', 'some text', '--diff']);
-      expect(mockWriteCommand.improveWithDiff).toHaveBeenCalledWith('some text', expect.any(Object));
-      expect(Logger.output).toHaveBeenCalledWith(expect.stringContaining('Original'));
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'some text',
+        '--diff',
+      ]);
+      expect(mockWriteCommand.improveWithDiff).toHaveBeenCalledWith(
+        'some text',
+        expect.any(Object)
+      );
+      expect(Logger.output).toHaveBeenCalledWith(
+        expect.stringContaining('Original')
+      );
     });
 
     it('should show diff for file input', async () => {
@@ -439,7 +749,10 @@ describe('registerWrite', () => {
         diff: '-old\n+new',
       });
       await program.parseAsync(['node', 'test', 'write', 'file.txt', '--diff']);
-      expect(mockWriteCommand.improveFileWithDiff).toHaveBeenCalledWith('file.txt', expect.any(Object));
+      expect(mockWriteCommand.improveFileWithDiff).toHaveBeenCalledWith(
+        'file.txt',
+        expect.any(Object)
+      );
     });
   });
 
@@ -465,31 +778,68 @@ describe('registerWrite', () => {
     it('should run interactive mode for text', async () => {
       mockWriteCommand.improveInteractive.mockResolvedValue('selected text');
       await program.parseAsync(['node', 'test', 'write', 'some text', '-i']);
-      expect(mockWriteCommand.improveInteractive).toHaveBeenCalledWith('some text', expect.any(Object));
+      expect(mockWriteCommand.improveInteractive).toHaveBeenCalledWith(
+        'some text',
+        expect.any(Object)
+      );
       expect(Logger.output).toHaveBeenCalledWith('selected text');
     });
 
     it('should run interactive mode for file', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.improveFileInteractive.mockResolvedValue({ selected: 'improved' });
+      mockWriteCommand.improveFileInteractive.mockResolvedValue({
+        selected: 'improved',
+      });
       await program.parseAsync(['node', 'test', 'write', 'file.txt', '-i']);
-      expect(mockWriteCommand.improveFileInteractive).toHaveBeenCalledWith('file.txt', expect.any(Object));
+      expect(mockWriteCommand.improveFileInteractive).toHaveBeenCalledWith(
+        'file.txt',
+        expect.any(Object)
+      );
       expect(Logger.output).toHaveBeenCalledWith('improved');
     });
 
     it('should write to output file in interactive file mode', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.improveFileInteractive.mockResolvedValue({ selected: 'improved' });
-      await program.parseAsync(['node', 'test', 'write', 'file.txt', '-i', '-o', 'out.txt']);
-      expect(mockWriteFile).toHaveBeenCalledWith('out.txt', 'improved', 'utf-8');
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Saved to out.txt'));
+      mockWriteCommand.improveFileInteractive.mockResolvedValue({
+        selected: 'improved',
+      });
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'file.txt',
+        '-i',
+        '-o',
+        'out.txt',
+      ]);
+      expect(mockWriteFile).toHaveBeenCalledWith(
+        'out.txt',
+        'improved',
+        'utf-8'
+      );
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Saved to out.txt')
+      );
     });
 
     it('should write in-place in interactive file mode', async () => {
       mockExistsSync.mockReturnValue(true);
-      mockWriteCommand.improveFileInteractive.mockResolvedValue({ selected: 'improved' });
-      await program.parseAsync(['node', 'test', 'write', 'file.txt', '-i', '--in-place']);
-      expect(mockWriteFile).toHaveBeenCalledWith('file.txt', 'improved', 'utf-8');
+      mockWriteCommand.improveFileInteractive.mockResolvedValue({
+        selected: 'improved',
+      });
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'file.txt',
+        '-i',
+        '--in-place',
+      ]);
+      expect(mockWriteFile).toHaveBeenCalledWith(
+        'file.txt',
+        'improved',
+        'utf-8'
+      );
     });
 
     it('should reject --interactive when stdin is not a TTY', async () => {
@@ -501,8 +851,10 @@ describe('registerWrite', () => {
       await program.parseAsync(['node', 'test', 'write', 'some text', '-i']);
       expect(handleError).toHaveBeenCalledWith(
         expect.objectContaining({
-          message: expect.stringContaining('--interactive requires an interactive terminal'),
-        }),
+          message: expect.stringContaining(
+            '--interactive requires an interactive terminal'
+          ),
+        })
       );
       expect(mockWriteCommand.improveInteractive).not.toHaveBeenCalled();
     });
@@ -511,10 +863,26 @@ describe('registerWrite', () => {
   describe('--output with text input', () => {
     it('should write result to output file when --output is specified with text input', async () => {
       mockWriteCommand.improve.mockResolvedValue('Improved text');
-      await program.parseAsync(['node', 'test', 'write', 'Hello world', '-o', '/tmp/out.txt']);
-      expect(mockWriteCommand.improve).toHaveBeenCalledWith('Hello world', expect.any(Object));
-      expect(mockWriteFile).toHaveBeenCalledWith('/tmp/out.txt', 'Improved text', 'utf-8');
-      expect(Logger.success).toHaveBeenCalledWith(expect.stringContaining('Saved to /tmp/out.txt'));
+      await program.parseAsync([
+        'node',
+        'test',
+        'write',
+        'Hello world',
+        '-o',
+        '/tmp/out.txt',
+      ]);
+      expect(mockWriteCommand.improve).toHaveBeenCalledWith(
+        'Hello world',
+        expect.any(Object)
+      );
+      expect(mockWriteFile).toHaveBeenCalledWith(
+        '/tmp/out.txt',
+        'Improved text',
+        'utf-8'
+      );
+      expect(Logger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Saved to /tmp/out.txt')
+      );
     });
 
     it('should still output to stdout when --output is not specified with text input', async () => {
@@ -529,7 +897,9 @@ describe('registerWrite', () => {
     it('should call handleError on unexpected errors', async () => {
       mockWriteCommand.improve.mockRejectedValue(new Error('API error'));
       await program.parseAsync(['node', 'test', 'write', 'Hello']);
-      expect(handleError).toHaveBeenCalledWith(expect.objectContaining({ message: 'API error' }));
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'API error' })
+      );
     });
   });
 });
diff --git a/tests/unit/resolve-endpoint.test.ts b/tests/unit/resolve-endpoint.test.ts
index de9ed74a..6cc0abb1 100644
--- a/tests/unit/resolve-endpoint.test.ts
+++ b/tests/unit/resolve-endpoint.test.ts
@@ -24,7 +24,10 @@ describe('isStandardDeepLUrl', () => {
     ['pro with path', 'https://api.deepl.com/v2/translate'],
     ['free bare', 'https://api-free.deepl.com'],
     ['free with path', 'https://api-free.deepl.com/v3/voice'],
-    ['uppercase hostname (URL normalizes to lowercase)', 'https://API.DEEPL.COM/v2'],
+    [
+      'uppercase hostname (URL normalizes to lowercase)',
+      'https://API.DEEPL.COM/v2',
+    ],
     ['explicit port 443 (stripped by URL parser)', 'https://api.deepl.com:443'],
   ])('standard: %s → true', (_label, url) => {
     expect(isStandardDeepLUrl(url)).toBe(true);
@@ -47,7 +50,12 @@ describe('resolveEndpoint', () => {
   it.each<[string, Parameters<typeof resolveEndpoint>[0], string]>([
     [
       'P1: apiUrlOverride wins over everything',
-      { apiKey: 'k:fx', configBaseUrl: 'https://api-jp.deepl.com', usePro: true, apiUrlOverride: 'https://override.test' },
+      {
+        apiKey: 'k:fx',
+        configBaseUrl: 'https://api-jp.deepl.com',
+        usePro: true,
+        apiUrlOverride: 'https://override.test',
+      },
       'https://override.test',
     ],
     [
@@ -60,26 +68,14 @@ describe('resolveEndpoint', () => {
       { apiKey: 'k:fx', configBaseUrl: 'https://api.deepl.com', usePro: true },
       FREE,
     ],
-    [
-      'P3: :fx key → free when config is missing',
-      { apiKey: 'k:fx' },
-      FREE,
-    ],
-    [
-      'P3: :fx key beats usePro: true',
-      { apiKey: 'k:fx', usePro: true },
-      FREE,
-    ],
+    ['P3: :fx key → free when config is missing', { apiKey: 'k:fx' }, FREE],
+    ['P3: :fx key beats usePro: true', { apiKey: 'k:fx', usePro: true }, FREE],
     [
       'P4: non-:fx key + usePro false → free',
       { apiKey: 'k-pro', usePro: false },
       FREE,
     ],
-    [
-      'P5: non-:fx key defaults to pro',
-      { apiKey: 'k-pro' },
-      PRO,
-    ],
+    ['P5: non-:fx key defaults to pro', { apiKey: 'k-pro' }, PRO],
     [
       'P5: standard config URL is ignored (treated as default)',
       { apiKey: 'k-pro', configBaseUrl: 'https://api.deepl.com', usePro: true },
diff --git a/tests/unit/retry-after-blank.test.ts b/tests/unit/retry-after-blank.test.ts
index 378abb2f..5a0d3336 100644
--- a/tests/unit/retry-after-blank.test.ts
+++ b/tests/unit/retry-after-blank.test.ts
@@ -27,9 +27,12 @@ describe('parseRetryAfter', () => {
     ['empty string', ''],
     ['single space', ' '],
     ['whitespace only', '   \t '],
-  ])('should treat a %s header as absent so jitter backoff applies', (_label, headerValue) => {
-    expect(client.parse(headerValue)).toBeUndefined();
-  });
+  ])(
+    'should treat a %s header as absent so jitter backoff applies',
+    (_label, headerValue) => {
+      expect(client.parse(headerValue)).toBeUndefined();
+    }
+  );
 
   it('should treat a missing header as absent', () => {
     expect(client.parse(undefined)).toBeUndefined();
diff --git a/tests/unit/safe-read-file.test.ts b/tests/unit/safe-read-file.test.ts
index d52837c8..607de533 100644
--- a/tests/unit/safe-read-file.test.ts
+++ b/tests/unit/safe-read-file.test.ts
@@ -3,7 +3,11 @@
  * Verifies symlink detection across all file-reading paths
  */
 
-import { safeReadFileSync, safeReadFile, isSymlink } from '../../src/utils/safe-read-file.js';
+import {
+  safeReadFileSync,
+  safeReadFile,
+  isSymlink,
+} from '../../src/utils/safe-read-file.js';
 import * as fs from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
@@ -12,7 +16,10 @@ describe('safe-read-file', () => {
   let testDir: string;
 
   beforeEach(() => {
-    testDir = join(tmpdir(), `deepl-cli-safe-read-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    testDir = join(
+      tmpdir(),
+      `deepl-cli-safe-read-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
     fs.mkdirSync(testDir, { recursive: true });
   });
 
diff --git a/tests/unit/service-factory-voice.test.ts b/tests/unit/service-factory-voice.test.ts
index 2089aa6e..daf54a1b 100644
--- a/tests/unit/service-factory-voice.test.ts
+++ b/tests/unit/service-factory-voice.test.ts
@@ -4,7 +4,6 @@
  */
 
 jest.mock('ws', () => {
-   
   const { EventEmitter } = require('events');
   class MockWebSocket extends EventEmitter {
     static OPEN = 1;
@@ -18,10 +17,24 @@ jest.mock('ws', () => {
 
 jest.mock('chalk', () => {
   const passthrough = (s: string) => s;
-  return { __esModule: true, default: { red: passthrough, green: passthrough, blue: passthrough, yellow: passthrough, gray: passthrough, bold: passthrough, level: 3 } };
+  return {
+    __esModule: true,
+    default: {
+      red: passthrough,
+      green: passthrough,
+      blue: passthrough,
+      yellow: passthrough,
+      gray: passthrough,
+      bold: passthrough,
+      level: 3,
+    },
+  };
 });
 
-import { createVoiceCommand, type GetApiKeyAndOptions } from '../../src/cli/commands/service-factory.js';
+import {
+  createVoiceCommand,
+  type GetApiKeyAndOptions,
+} from '../../src/cli/commands/service-factory.js';
 
 describe('createVoiceCommand', () => {
   it('should reject insecure HTTP base URL', async () => {
@@ -31,7 +44,7 @@ describe('createVoiceCommand', () => {
     });
 
     await expect(createVoiceCommand(getApiKeyAndOptions)).rejects.toThrow(
-      /Insecure HTTP URL rejected/,
+      /Insecure HTTP URL rejected/
     );
   });
 
@@ -42,7 +55,7 @@ describe('createVoiceCommand', () => {
     });
 
     await expect(createVoiceCommand(getApiKeyAndOptions)).rejects.toThrow(
-      /Unsupported protocol/,
+      /Unsupported protocol/
     );
   });
 
@@ -93,7 +106,7 @@ describe('createVoiceCommand', () => {
     });
 
     await expect(createVoiceCommand(getApiKeyAndOptions)).rejects.toThrow(
-      /Invalid URL/,
+      /Invalid URL/
     );
   });
 });
diff --git a/tests/unit/services/batch-translation.test.ts b/tests/unit/services/batch-translation.test.ts
index 2e7cf0df..7f5b386f 100644
--- a/tests/unit/services/batch-translation.test.ts
+++ b/tests/unit/services/batch-translation.test.ts
@@ -7,10 +7,16 @@ import * as path from 'path';
 import * as os from 'os';
 import { BatchTranslationService } from '../../../src/services/batch-translation';
 import { FileTranslationService } from '../../../src/services/file-translation';
-import { TranslationService, MAX_TEXT_BYTES } from '../../../src/services/translation';
+import {
+  TranslationService,
+  MAX_TEXT_BYTES,
+} from '../../../src/services/translation';
 import pLimit from 'p-limit';
 import fg from 'fast-glob';
-import { createMockFileTranslationService, createMockTranslationService } from '../../helpers/mock-factories';
+import {
+  createMockFileTranslationService,
+  createMockTranslationService,
+} from '../../helpers/mock-factories';
 import { NetworkError, ValidationError } from '../../../src/utils/errors';
 import { isUnrecoverableRequestError } from '../../../src/utils/unrecoverable-request-error';
 
@@ -66,10 +72,9 @@ describe('BatchTranslationService', () => {
 
     it('should accept custom concurrency limit', async () => {
       mockPLimit.mockClear();
-      const service = new BatchTranslationService(
-        mockFileTranslationService,
-        { concurrency: 5 }
-      );
+      const service = new BatchTranslationService(mockFileTranslationService, {
+        concurrency: 5,
+      });
 
       const file = path.join(testDir, 'concurrency-test.txt');
       fs.writeFileSync(file, 'test content');
@@ -257,8 +262,8 @@ describe('BatchTranslationService', () => {
       fs.mkdirSync(inputDir);
 
       const files = ['file1.txt', 'file2.md', 'file3.txt'];
-      const absoluteFiles = files.map(f => path.join(inputDir, f));
-      files.forEach(file => {
+      const absoluteFiles = files.map((f) => path.join(inputDir, f));
+      files.forEach((file) => {
         fs.writeFileSync(path.join(inputDir, file), 'Content');
       });
 
@@ -288,7 +293,7 @@ describe('BatchTranslationService', () => {
         path.join(inputDir, 'sub1', 'file2.txt'),
         path.join(inputDir, 'sub2', 'file3.txt'),
       ];
-      absoluteFiles.forEach(file => fs.writeFileSync(file, 'Content'));
+      absoluteFiles.forEach((file) => fs.writeFileSync(file, 'Content'));
 
       mockFastGlob.mockResolvedValue(absoluteFiles);
       mockFileTranslationService.translateFile.mockResolvedValue(undefined);
@@ -349,7 +354,7 @@ describe('BatchTranslationService', () => {
         path.join(inputDir, 'file1.txt'),
         path.join(inputDir, 'sub', 'file2.txt'),
       ];
-      absoluteFiles.forEach(file => fs.writeFileSync(file, 'Content'));
+      absoluteFiles.forEach((file) => fs.writeFileSync(file, 'Content'));
 
       mockFastGlob.mockResolvedValue(absoluteFiles);
       mockFileTranslationService.translateFile.mockResolvedValue(undefined);
@@ -485,7 +490,7 @@ describe('BatchTranslationService', () => {
       }
 
       mockTranslationService.translateBatch.mockImplementation(async (texts) =>
-        texts.map(t => ({ text: `translated: ${t}` }))
+        texts.map((t) => ({ text: `translated: ${t}` }))
       );
 
       const result = await batchServiceWithTranslation.translateFiles(
@@ -498,8 +503,10 @@ describe('BatchTranslationService', () => {
       expect(mockTranslationService.translateBatch).toHaveBeenCalledTimes(2);
 
       // First batch should have 50, second should have 2
-      const firstCallTexts = mockTranslationService.translateBatch.mock.calls[0]![0];
-      const secondCallTexts = mockTranslationService.translateBatch.mock.calls[1]![0];
+      const firstCallTexts =
+        mockTranslationService.translateBatch.mock.calls[0]![0];
+      const secondCallTexts =
+        mockTranslationService.translateBatch.mock.calls[1]![0];
       expect(firstCallTexts).toHaveLength(50);
       expect(secondCallTexts).toHaveLength(2);
     });
@@ -513,13 +520,13 @@ describe('BatchTranslationService', () => {
       }
 
       mockTranslationService.translateBatch.mockRejectedValue(
-        new ValidationError("API error: Value for 'target_lang' not supported."),
+        new ValidationError("API error: Value for 'target_lang' not supported.")
       );
 
       const result = await batchServiceWithTranslation.translateFiles(
         files,
         { targetLang: 'ex' as never },
-        { outputDir: testDir },
+        { outputDir: testDir }
       );
 
       // The same rejection applies to every batch, so it is asked once rather
@@ -537,13 +544,15 @@ describe('BatchTranslationService', () => {
       // A gateway error interpolates the upstream body, so the message alone
       // cannot distinguish it from a genuine rejection.
       const transient = new NetworkError(
-        "Server error (502): upstream unavailable, value for 'target_lang' not supported by shard",
+        "Server error (502): upstream unavailable, value for 'target_lang' not supported by shard"
       );
       expect(isUnrecoverableRequestError(transient)).toBe(false);
       expect(
         isUnrecoverableRequestError(
-          new ValidationError("API error: Value for 'target_lang' not supported."),
-        ),
+          new ValidationError(
+            "API error: Value for 'target_lang' not supported."
+          )
+        )
       ).toBe(true);
     });
 
@@ -557,12 +566,14 @@ describe('BatchTranslationService', () => {
 
       mockTranslationService.translateBatch
         .mockRejectedValueOnce(new Error('Too many requests'))
-        .mockImplementation(async (texts) => texts.map(t => ({ text: `translated: ${t}` })));
+        .mockImplementation(async (texts) =>
+          texts.map((t) => ({ text: `translated: ${t}` }))
+        );
 
       const result = await batchServiceWithTranslation.translateFiles(
         files,
         { targetLang: 'es' },
-        { outputDir: testDir },
+        { outputDir: testDir }
       );
 
       expect(mockTranslationService.translateBatch).toHaveBeenCalledTimes(2);
@@ -621,14 +632,16 @@ describe('BatchTranslationService', () => {
       const file = path.join(testDir, 'code.txt');
       fs.writeFileSync(file, 'Use `console.log()` with {name}');
 
-      mockTranslationService.translateBatch.mockImplementation(async (texts) => {
-        // Verify placeholders were applied before reaching translateBatch
-        expect(texts[0]).toContain('__CODE_');
-        expect(texts[0]).toContain('__VAR_');
-        expect(texts[0]).not.toContain('`console.log()`');
-        expect(texts[0]).not.toContain('{name}');
-        return texts.map(t => ({ text: t.replace('Use', 'Usa') }));
-      });
+      mockTranslationService.translateBatch.mockImplementation(
+        async (texts) => {
+          // Verify placeholders were applied before reaching translateBatch
+          expect(texts[0]).toContain('__CODE_');
+          expect(texts[0]).toContain('__VAR_');
+          expect(texts[0]).not.toContain('`console.log()`');
+          expect(texts[0]).not.toContain('{name}');
+          return texts.map((t) => ({ text: t.replace('Use', 'Usa') }));
+        }
+      );
 
       const result = await batchServiceWithTranslation.translateFiles(
         [file],
@@ -637,7 +650,10 @@ describe('BatchTranslationService', () => {
       );
 
       expect(result.successful).toHaveLength(1);
-      const outputContent = fs.readFileSync(result.successful[0]!.outputPath, 'utf-8');
+      const outputContent = fs.readFileSync(
+        result.successful[0]!.outputPath,
+        'utf-8'
+      );
       // Restored placeholders
       expect(outputContent).toContain('`console.log()`');
       expect(outputContent).toContain('{name}');
@@ -679,13 +695,12 @@ describe('BatchTranslationService', () => {
     });
 
     it('should handle batch API failure by marking all files in batch as failed', async () => {
-      const files = [
-        path.join(testDir, 'x.txt'),
-        path.join(testDir, 'y.txt'),
-      ];
-      files.forEach(f => fs.writeFileSync(f, 'content'));
+      const files = [path.join(testDir, 'x.txt'), path.join(testDir, 'y.txt')];
+      files.forEach((f) => fs.writeFileSync(f, 'content'));
 
-      mockTranslationService.translateBatch.mockRejectedValue(new Error('API 503'));
+      mockTranslationService.translateBatch.mockRejectedValue(
+        new Error('API 503')
+      );
 
       const result = await batchServiceWithTranslation.translateFiles(
         files,
@@ -704,7 +719,7 @@ describe('BatchTranslationService', () => {
         path.join(testDir, 'p1.txt'),
         path.join(testDir, 'p2.txt'),
       ];
-      files.forEach(f => fs.writeFileSync(f, 'hello'));
+      files.forEach((f) => fs.writeFileSync(f, 'hello'));
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'hola' },
@@ -717,7 +732,8 @@ describe('BatchTranslationService', () => {
         { targetLang: 'es' },
         {
           outputDir: testDir,
-          onProgress: (p) => progressCalls.push({ completed: p.completed, total: p.total }),
+          onProgress: (p) =>
+            progressCalls.push({ completed: p.completed, total: p.total }),
         }
       );
 
@@ -745,10 +761,12 @@ describe('BatchTranslationService', () => {
     });
 
     it('should route structured files (.json) through per-file path', async () => {
-      mockFileTranslationService.isSupportedFile.mockImplementation((filePath: string) => {
-        const ext = path.extname(filePath).toLowerCase();
-        return ['.txt', '.md', '.json', '.yaml', '.yml'].includes(ext);
-      });
+      mockFileTranslationService.isSupportedFile.mockImplementation(
+        (filePath: string) => {
+          const ext = path.extname(filePath).toLowerCase();
+          return ['.txt', '.md', '.json', '.yaml', '.yml'].includes(ext);
+        }
+      );
 
       const txtFile = path.join(testDir, 'plain.txt');
       const jsonFile = path.join(testDir, 'data.json');
@@ -777,7 +795,7 @@ describe('BatchTranslationService', () => {
         path.join(testDir, 'm1.txt'),
         path.join(testDir, 'm2.txt'),
       ];
-      files.forEach(f => fs.writeFileSync(f, 'content'));
+      files.forEach((f) => fs.writeFileSync(f, 'content'));
 
       // Return wrong number of results
       mockTranslationService.translateBatch.mockResolvedValue([
@@ -804,14 +822,16 @@ describe('BatchTranslationService', () => {
       }
       const lastFile = files[51]!;
 
-      mockTranslationService.translateBatch.mockImplementation(async (texts) => {
-        // Removing a later file while the first batch translates proves it
-        // has not been read yet when this call happens.
-        if (fs.existsSync(lastFile)) {
-          fs.rmSync(lastFile);
+      mockTranslationService.translateBatch.mockImplementation(
+        async (texts) => {
+          // Removing a later file while the first batch translates proves it
+          // has not been read yet when this call happens.
+          if (fs.existsSync(lastFile)) {
+            fs.rmSync(lastFile);
+          }
+          return texts.map((t) => ({ text: `translated: ${t}` }));
         }
-        return texts.map((t) => ({ text: `translated: ${t}` }));
-      });
+      );
 
       const result = await batchServiceWithTranslation.translateFiles(
         files,
@@ -958,8 +978,10 @@ describe('BatchTranslationService', () => {
 
       // First file succeeds (abort happens during its translation),
       // remaining files should be skipped
-      expect(result.successful.length + result.skipped.length + result.failed.length).toBe(files.length);
-      expect(result.skipped.some(s => s.reason === 'Aborted')).toBe(true);
+      expect(
+        result.successful.length + result.skipped.length + result.failed.length
+      ).toBe(files.length);
+      expect(result.skipped.some((s) => s.reason === 'Aborted')).toBe(true);
     });
 
     it('should not skip files when abort signal is not triggered', async () => {
@@ -982,13 +1004,13 @@ describe('BatchTranslationService', () => {
       );
 
       expect(result.successful).toHaveLength(2);
-      expect(result.skipped.filter(s => s.reason === 'Aborted')).toHaveLength(0);
+      expect(result.skipped.filter((s) => s.reason === 'Aborted')).toHaveLength(
+        0
+      );
     });
 
     it('should respect pre-aborted signal', async () => {
-      const files = [
-        path.join(testDir, 'file1.txt'),
-      ];
+      const files = [path.join(testDir, 'file1.txt')];
 
       files.forEach((file, i) => {
         fs.writeFileSync(file, `Content ${i + 1}`);
@@ -1006,7 +1028,7 @@ describe('BatchTranslationService', () => {
       );
 
       // File should be skipped since signal was pre-aborted
-      expect(result.skipped.some(s => s.reason === 'Aborted')).toBe(true);
+      expect(result.skipped.some((s) => s.reason === 'Aborted')).toBe(true);
       expect(mockFileTranslationService.translateFile).not.toHaveBeenCalled();
     });
   });
diff --git a/tests/unit/services/git-hooks.test.ts b/tests/unit/services/git-hooks.test.ts
index 2f442d5b..c15660fb 100644
--- a/tests/unit/services/git-hooks.test.ts
+++ b/tests/unit/services/git-hooks.test.ts
@@ -33,11 +33,26 @@ describe('GitHooksService', () => {
   describe('invalid hook type', () => {
     it.each([
       { method: 'install', invoke: (svc: any) => svc.install('invalid-hook') },
-      { method: 'uninstall', invoke: (svc: any) => svc.uninstall('invalid-hook') },
-      { method: 'isInstalled', invoke: (svc: any) => svc.isInstalled('invalid-hook') },
-      { method: 'getHookPath', invoke: (svc: any) => svc.getHookPath('invalid-hook') },
-      { method: 'generateHookContent', invoke: (svc: any) => svc.generateHookContent('invalid') },
-      { method: 'verifyIntegrity', invoke: (svc: any) => svc.verifyIntegrity('invalid-hook') },
+      {
+        method: 'uninstall',
+        invoke: (svc: any) => svc.uninstall('invalid-hook'),
+      },
+      {
+        method: 'isInstalled',
+        invoke: (svc: any) => svc.isInstalled('invalid-hook'),
+      },
+      {
+        method: 'getHookPath',
+        invoke: (svc: any) => svc.getHookPath('invalid-hook'),
+      },
+      {
+        method: 'generateHookContent',
+        invoke: (svc: any) => svc.generateHookContent('invalid'),
+      },
+      {
+        method: 'verifyIntegrity',
+        invoke: (svc: any) => svc.verifyIntegrity('invalid-hook'),
+      },
     ])('$method should throw error for invalid hook type', ({ invoke }) => {
       expect(() => invoke(gitHooksService)).toThrow('Invalid hook type');
     });
@@ -51,7 +66,9 @@ describe('GitHooksService', () => {
     it('should throw error for non-existent git directory', () => {
       const nonExistentDir = path.join(os.tmpdir(), 'non-existent-git');
 
-      expect(() => new GitHooksService(nonExistentDir)).toThrow('Git directory not found');
+      expect(() => new GitHooksService(nonExistentDir)).toThrow(
+        'Git directory not found'
+      );
     });
   });
 
@@ -59,17 +76,28 @@ describe('GitHooksService', () => {
     // Generated hook content must only ever name the published package,
     // @deepl/cli — an unpublished name emits a broken install instruction
     // into every generated hook.
-    const hookTypes = ['pre-commit', 'pre-push', 'commit-msg', 'post-commit'] as const;
-
-    it.each(hookTypes)('%s output never references an unpublished package name', (hookType) => {
-      gitHooksService.install(hookType);
+    const hookTypes = [
+      'pre-commit',
+      'pre-push',
+      'commit-msg',
+      'post-commit',
+    ] as const;
+
+    it.each(hookTypes)(
+      '%s output never references an unpublished package name',
+      (hookType) => {
+        gitHooksService.install(hookType);
 
-      const content = fs.readFileSync(path.join(testHooksDir, hookType), 'utf-8');
-      expect(content).not.toMatch(/install\s+-g\s+deepl-cli\b/);
-      if (/npm install/.test(content)) {
-        expect(content).toContain('npm install -g @deepl/cli');
+        const content = fs.readFileSync(
+          path.join(testHooksDir, hookType),
+          'utf-8'
+        );
+        expect(content).not.toMatch(/install\s+-g\s+deepl-cli\b/);
+        if (/npm install/.test(content)) {
+          expect(content).toContain('npm install -g @deepl/cli');
+        }
       }
-    });
+    );
   });
 
   describe('install()', () => {
@@ -87,7 +115,10 @@ describe('GitHooksService', () => {
     it('pre-commit hook invokes the CLI to validate translations', () => {
       gitHooksService.install('pre-commit');
 
-      const content = fs.readFileSync(path.join(testHooksDir, 'pre-commit'), 'utf-8');
+      const content = fs.readFileSync(
+        path.join(testHooksDir, 'pre-commit'),
+        'utf-8'
+      );
       expect(content).toContain('command -v deepl');
       expect(content).toContain('deepl sync validate');
       expect(content).toContain('.deepl-sync.yaml');
@@ -99,7 +130,10 @@ describe('GitHooksService', () => {
     it('pre-commit hook blocks the commit when validation fails', () => {
       gitHooksService.install('pre-commit');
 
-      const content = fs.readFileSync(path.join(testHooksDir, 'pre-commit'), 'utf-8');
+      const content = fs.readFileSync(
+        path.join(testHooksDir, 'pre-commit'),
+        'utf-8'
+      );
       expect(content).toContain('exit 1');
     });
 
@@ -192,7 +226,6 @@ describe('GitHooksService', () => {
       const backupPath = hookPath + '.backup';
       expect(fs.existsSync(backupPath)).toBe(false);
     });
-
   });
 
   describe('uninstall()', () => {
@@ -246,7 +279,6 @@ describe('GitHooksService', () => {
         'Hook is not a DeepL CLI hook'
       );
     });
-
   });
 
   describe('isInstalled()', () => {
@@ -270,7 +302,6 @@ describe('GitHooksService', () => {
 
       expect(gitHooksService.isInstalled('pre-commit')).toBe(false);
     });
-
   });
 
   describe('list()', () => {
@@ -342,7 +373,6 @@ describe('GitHooksService', () => {
 
       expect(hookPath).toBe(path.join(testHooksDir, 'post-commit'));
     });
-
   });
 
   describe('findGitRoot()', () => {
@@ -397,10 +427,13 @@ describe('GitHooksService', () => {
   });
 
   describe('hook content generation', () => {
-    const MARKER_PATTERN = /^# DeepL CLI Hook v(\d+) \[sha256:([a-f0-9]{64})\]$/m;
+    const MARKER_PATTERN =
+      /^# DeepL CLI Hook v(\d+) \[sha256:([a-f0-9]{64})\]$/m;
 
     it('should generate valid pre-commit hook content', () => {
-      const content = (gitHooksService as any).generateHookContent('pre-commit');
+      const content = (gitHooksService as any).generateHookContent(
+        'pre-commit'
+      );
 
       expect(content).toContain('#!/bin/sh');
       expect(content).toMatch(MARKER_PATTERN);
@@ -418,7 +451,9 @@ describe('GitHooksService', () => {
     });
 
     it('should generate valid commit-msg hook content', () => {
-      const content = (gitHooksService as any).generateHookContent('commit-msg');
+      const content = (gitHooksService as any).generateHookContent(
+        'commit-msg'
+      );
 
       expect(content).toContain('#!/bin/sh');
       expect(content).toMatch(MARKER_PATTERN);
@@ -429,7 +464,9 @@ describe('GitHooksService', () => {
     });
 
     it('should generate valid post-commit hook content', () => {
-      const content = (gitHooksService as any).generateHookContent('post-commit');
+      const content = (gitHooksService as any).generateHookContent(
+        'post-commit'
+      );
 
       expect(content).toContain('#!/bin/sh');
       expect(content).toMatch(MARKER_PATTERN);
@@ -440,7 +477,9 @@ describe('GitHooksService', () => {
     });
 
     it('should embed correct SHA-256 hash of the hook body', () => {
-      const content = (gitHooksService as any).generateHookContent('pre-commit');
+      const content = (gitHooksService as any).generateHookContent(
+        'pre-commit'
+      );
       const match = content.match(MARKER_PATTERN);
       expect(match).not.toBeNull();
 
@@ -452,20 +491,28 @@ describe('GitHooksService', () => {
     });
 
     it('should use marker version 1', () => {
-      const content = (gitHooksService as any).generateHookContent('pre-commit');
+      const content = (gitHooksService as any).generateHookContent(
+        'pre-commit'
+      );
       const match = content.match(MARKER_PATTERN);
       expect(match).not.toBeNull();
       expect(match![1]).toBe('1');
     });
 
     it('should produce consistent hash for same hook type', () => {
-      const content1 = (gitHooksService as any).generateHookContent('pre-commit');
-      const content2 = (gitHooksService as any).generateHookContent('pre-commit');
+      const content1 = (gitHooksService as any).generateHookContent(
+        'pre-commit'
+      );
+      const content2 = (gitHooksService as any).generateHookContent(
+        'pre-commit'
+      );
       expect(content1).toBe(content2);
     });
 
     it('should produce different hashes for different hook types', () => {
-      const content1 = (gitHooksService as any).generateHookContent('pre-commit');
+      const content1 = (gitHooksService as any).generateHookContent(
+        'pre-commit'
+      );
       const content2 = (gitHooksService as any).generateHookContent('pre-push');
 
       const hash1 = content1.match(MARKER_PATTERN)![2];
@@ -473,7 +520,6 @@ describe('GitHooksService', () => {
 
       expect(hash1).not.toBe(hash2);
     });
-
   });
 
   describe('isDeepLHook()', () => {
@@ -510,7 +556,10 @@ describe('GitHooksService', () => {
     });
 
     it('should match known SHA-256 value', () => {
-      const expected = crypto.createHash('sha256').update('hello', 'utf-8').digest('hex');
+      const expected = crypto
+        .createHash('sha256')
+        .update('hello', 'utf-8')
+        .digest('hex');
       expect(GitHooksService.computeHash('hello')).toBe(expected);
     });
 
@@ -578,7 +627,10 @@ describe('GitHooksService', () => {
 
     it('should return legacy marker version for old-style hooks', () => {
       const hookPath = path.join(testHooksDir, 'pre-commit');
-      fs.writeFileSync(hookPath, '#!/bin/sh\n# DeepL CLI Hook\necho "old style"');
+      fs.writeFileSync(
+        hookPath,
+        '#!/bin/sh\n# DeepL CLI Hook\necho "old style"'
+      );
 
       const result = gitHooksService.verifyIntegrity('pre-commit');
       expect(result.installed).toBe(true);
@@ -627,9 +679,9 @@ describe('GitHooksService', () => {
     });
 
     it('should verify integrity for all hook types', () => {
-      const hookTypes: Array<'pre-commit' | 'pre-push' | 'commit-msg' | 'post-commit'> = [
-        'pre-commit', 'pre-push', 'commit-msg', 'post-commit'
-      ];
+      const hookTypes: Array<
+        'pre-commit' | 'pre-push' | 'commit-msg' | 'post-commit'
+      > = ['pre-commit', 'pre-push', 'commit-msg', 'post-commit'];
 
       for (const hookType of hookTypes) {
         gitHooksService.install(hookType);
@@ -639,7 +691,6 @@ describe('GitHooksService', () => {
         expect(result.hashMatch).toBe(true);
       }
     });
-
   });
 
   describe('backward compatibility', () => {
@@ -649,14 +700,20 @@ describe('GitHooksService', () => {
 
     it('should detect old-style marker as installed', () => {
       const hookPath = path.join(testHooksDir, 'pre-commit');
-      fs.writeFileSync(hookPath, '#!/bin/sh\n# DeepL CLI Hook\necho "old hook"');
+      fs.writeFileSync(
+        hookPath,
+        '#!/bin/sh\n# DeepL CLI Hook\necho "old hook"'
+      );
 
       expect(gitHooksService.isInstalled('pre-commit')).toBe(true);
     });
 
     it('should allow uninstalling old-style hook', () => {
       const hookPath = path.join(testHooksDir, 'pre-commit');
-      fs.writeFileSync(hookPath, '#!/bin/sh\n# DeepL CLI Hook\necho "old hook"');
+      fs.writeFileSync(
+        hookPath,
+        '#!/bin/sh\n# DeepL CLI Hook\necho "old hook"'
+      );
 
       gitHooksService.uninstall('pre-commit');
       expect(fs.existsSync(hookPath)).toBe(false);
@@ -664,7 +721,10 @@ describe('GitHooksService', () => {
 
     it('should not backup old-style hook when reinstalling', () => {
       const hookPath = path.join(testHooksDir, 'pre-commit');
-      fs.writeFileSync(hookPath, '#!/bin/sh\n# DeepL CLI Hook\necho "old hook"');
+      fs.writeFileSync(
+        hookPath,
+        '#!/bin/sh\n# DeepL CLI Hook\necho "old hook"'
+      );
 
       gitHooksService.install('pre-commit');
 
@@ -677,7 +737,10 @@ describe('GitHooksService', () => {
 
     it('should upgrade old-style hook to versioned format on reinstall', () => {
       const hookPath = path.join(testHooksDir, 'pre-commit');
-      fs.writeFileSync(hookPath, '#!/bin/sh\n# DeepL CLI Hook\necho "old hook"');
+      fs.writeFileSync(
+        hookPath,
+        '#!/bin/sh\n# DeepL CLI Hook\necho "old hook"'
+      );
 
       gitHooksService.install('pre-commit');
 
diff --git a/tests/unit/services/watch.test.ts b/tests/unit/services/watch.test.ts
index 63207ec6..c7714e61 100644
--- a/tests/unit/services/watch.test.ts
+++ b/tests/unit/services/watch.test.ts
@@ -29,9 +29,10 @@ const mockWatcher = {
 };
 
 const getWatcherHandler = (event: string): ((...args: unknown[]) => void) =>
-  mockWatcher.on.mock.calls.find(call => call[0] === event)?.[1];
+  mockWatcher.on.mock.calls.find((call) => call[0] === event)?.[1];
 
-const flushPromises = () => new Promise<void>(resolve => process.nextTick(resolve));
+const flushPromises = () =>
+  new Promise<void>((resolve) => process.nextTick(resolve));
 
 describe('WatchService', () => {
   let watchService: WatchService;
@@ -149,10 +150,13 @@ describe('WatchService', () => {
       await watchService.watch(testDir, options);
 
       expect(watchService.isWatching()).toBe(true);
-      expect(chokidar.watch).toHaveBeenCalledWith(testDir, expect.objectContaining({
-        persistent: true,
-        ignoreInitial: true,
-      }));
+      expect(chokidar.watch).toHaveBeenCalledWith(
+        testDir,
+        expect.objectContaining({
+          persistent: true,
+          ignoreInitial: true,
+        })
+      );
     });
 
     it('should watch a single file', async () => {
@@ -327,7 +331,9 @@ describe('WatchService', () => {
       jest.advanceTimersByTime(350);
       await flushPromises();
 
-      expect(mockFileTranslationService.translateFileToMultiple).toHaveBeenCalled();
+      expect(
+        mockFileTranslationService.translateFileToMultiple
+      ).toHaveBeenCalled();
     });
   });
 
@@ -414,7 +420,9 @@ describe('WatchService', () => {
       await watchService.watch(testDir, options);
       await watchService.handleFileChange(testFile);
 
-      expect(onChange).toHaveBeenCalledWith(expect.stringContaining('test.txt'));
+      expect(onChange).toHaveBeenCalledWith(
+        expect.stringContaining('test.txt')
+      );
     });
 
     it('should call onTranslate callback after translation', async () => {
@@ -674,8 +682,8 @@ describe('WatchService', () => {
 
       // Test the ignored function
       const ignored = watchCall[1].ignored;
-      expect(ignored('/path/to/file.txt')).toBe(true);  // Should ignore .txt
-      expect(ignored('/path/to/file.md')).toBe(false);   // Should not ignore .md
+      expect(ignored('/path/to/file.txt')).toBe(true); // Should ignore .txt
+      expect(ignored('/path/to/file.md')).toBe(false); // Should not ignore .md
     });
 
     it('should not filter when no pattern is specified', async () => {
@@ -724,9 +732,9 @@ describe('WatchService', () => {
       const ignored = watchCall[1].ignored;
 
       // Should only match readme.md
-      expect(ignored('/path/to/readme.md')).toBe(false);   // Should NOT ignore readme.md
-      expect(ignored('/path/to/README.md')).toBe(true);    // Should ignore README.md (case sensitive)
-      expect(ignored('/path/to/other.md')).toBe(true);     // Should ignore other.md
+      expect(ignored('/path/to/readme.md')).toBe(false); // Should NOT ignore readme.md
+      expect(ignored('/path/to/README.md')).toBe(true); // Should ignore README.md (case sensitive)
+      expect(ignored('/path/to/other.md')).toBe(true); // Should ignore other.md
     });
 
     it('should handle prefix wildcard pattern (Issue #6)', async () => {
@@ -742,10 +750,10 @@ describe('WatchService', () => {
       const ignored = watchCall[1].ignored;
 
       // Should match files starting with "test"
-      expect(ignored('/path/to/test.txt')).toBe(false);     // Should NOT ignore test.txt
+      expect(ignored('/path/to/test.txt')).toBe(false); // Should NOT ignore test.txt
       expect(ignored('/path/to/test-file.md')).toBe(false); // Should NOT ignore test-file.md
-      expect(ignored('/path/to/testing.js')).toBe(false);   // Should NOT ignore testing.js
-      expect(ignored('/path/to/mytest.txt')).toBe(true);    // Should ignore mytest.txt
+      expect(ignored('/path/to/testing.js')).toBe(false); // Should NOT ignore testing.js
+      expect(ignored('/path/to/mytest.txt')).toBe(true); // Should ignore mytest.txt
     });
 
     it('should handle complex glob patterns (Issue #6)', async () => {
@@ -761,9 +769,9 @@ describe('WatchService', () => {
       const ignored = watchCall[1].ignored;
 
       // Should match .md or .txt files
-      expect(ignored('/path/to/file.md')).toBe(false);  // Should NOT ignore .md
+      expect(ignored('/path/to/file.md')).toBe(false); // Should NOT ignore .md
       expect(ignored('/path/to/file.txt')).toBe(false); // Should NOT ignore .txt
-      expect(ignored('/path/to/file.js')).toBe(true);   // Should ignore .js
+      expect(ignored('/path/to/file.js')).toBe(true); // Should ignore .js
     });
 
     it('should handle case-insensitive patterns (Issue #6)', async () => {
@@ -779,8 +787,8 @@ describe('WatchService', () => {
       const ignored = watchCall[1].ignored;
 
       // Should match README.md exactly (case-sensitive by default)
-      expect(ignored('/path/to/README.md')).toBe(false);  // Should NOT ignore README.md
-      expect(ignored('/path/to/readme.md')).toBe(true);   // Should ignore readme.md
+      expect(ignored('/path/to/README.md')).toBe(false); // Should NOT ignore README.md
+      expect(ignored('/path/to/readme.md')).toBe(true); // Should ignore readme.md
     });
   });
 
@@ -895,7 +903,7 @@ describe('WatchService', () => {
 
       // Get the 'change' event handler
       const changeHandler = mockWatcher.on.mock.calls.find(
-        call => call[0] === 'change'
+        (call) => call[0] === 'change'
       )?.[1];
 
       expect(changeHandler).toBeDefined();
@@ -927,7 +935,7 @@ describe('WatchService', () => {
 
       // Get the 'add' event handler
       const addHandler = mockWatcher.on.mock.calls.find(
-        call => call[0] === 'add'
+        (call) => call[0] === 'add'
       )?.[1];
 
       expect(addHandler).toBeDefined();
@@ -949,7 +957,9 @@ describe('WatchService', () => {
       fs.writeFileSync(testFile, 'Hello');
 
       // Don't start watch, just call handleFileChange
-      expect(() => watchService.handleFileChange(testFile)).toThrow('Watch not started');
+      expect(() => watchService.handleFileChange(testFile)).toThrow(
+        'Watch not started'
+      );
     });
   });
 
@@ -1214,7 +1224,9 @@ describe('WatchService', () => {
 
       // Try to trigger file change after stop
       // Should not throw, but also should not schedule translation
-      expect(() => watchService.handleFileChange(testFile)).toThrow('Watch not started');
+      expect(() => watchService.handleFileChange(testFile)).toThrow(
+        'Watch not started'
+      );
     });
 
     it('should handle rapid start/stop cycles without orphaned timers', async () => {
@@ -1390,7 +1402,9 @@ describe('WatchService', () => {
       fs.writeFileSync(testFile, 'Hello');
 
       const translationError = new Error('Network timeout');
-      mockFileTranslationService.translateFile.mockRejectedValue(translationError);
+      mockFileTranslationService.translateFile.mockRejectedValue(
+        translationError
+      );
 
       const options = {
         targetLangs: ['es' as const],
diff --git a/tests/unit/signal-exit.test.ts b/tests/unit/signal-exit.test.ts
index e261b060..10ca26da 100644
--- a/tests/unit/signal-exit.test.ts
+++ b/tests/unit/signal-exit.test.ts
@@ -20,7 +20,9 @@ describe('signal exit ownership', () => {
 
   beforeEach(() => {
     resetSignalExitForTests();
-    exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => undefined) as never);
+    exitSpy = jest
+      .spyOn(process, 'exit')
+      .mockImplementation((() => undefined) as never);
   });
 
   afterEach(() => {
diff --git a/tests/unit/stdin-translation-handler.test.ts b/tests/unit/stdin-translation-handler.test.ts
index eecac75f..89fc2cf7 100644
--- a/tests/unit/stdin-translation-handler.test.ts
+++ b/tests/unit/stdin-translation-handler.test.ts
@@ -18,7 +18,9 @@ import { readStdin } from '../../src/utils/read-stdin';
 
 const mockedReadStdin = readStdin as jest.MockedFunction<typeof readStdin>;
 
-function defaultOptions(overrides: Partial<TranslateOptions> = {}): TranslateOptions {
+function defaultOptions(
+  overrides: Partial<TranslateOptions> = {}
+): TranslateOptions {
   return { to: 'de', cache: true, ...overrides };
 }
 
@@ -42,27 +44,38 @@ describe('StdinTranslationHandler', () => {
       const result = await handler.translateFromStdin(defaultOptions());
 
       expect(mockedReadStdin).toHaveBeenCalled();
-      expect(mockTextHandler.translateText).toHaveBeenCalledWith('Hello from stdin', defaultOptions());
+      expect(mockTextHandler.translateText).toHaveBeenCalledWith(
+        'Hello from stdin',
+        defaultOptions()
+      );
       expect(result).toBe('translated');
     });
 
     it('should throw ValidationError for empty stdin', async () => {
       mockedReadStdin.mockResolvedValue('');
 
-      await expect(handler.translateFromStdin(defaultOptions())).rejects.toThrow(ValidationError);
-      await expect(handler.translateFromStdin(defaultOptions())).rejects.toThrow('No input provided from stdin');
+      await expect(
+        handler.translateFromStdin(defaultOptions())
+      ).rejects.toThrow(ValidationError);
+      await expect(
+        handler.translateFromStdin(defaultOptions())
+      ).rejects.toThrow('No input provided from stdin');
     });
 
     it('should throw ValidationError for whitespace-only stdin', async () => {
       mockedReadStdin.mockResolvedValue('   \n  \t  ');
 
-      await expect(handler.translateFromStdin(defaultOptions())).rejects.toThrow(ValidationError);
+      await expect(
+        handler.translateFromStdin(defaultOptions())
+      ).rejects.toThrow(ValidationError);
     });
 
     it('should throw ValidationError for null stdin', async () => {
       mockedReadStdin.mockResolvedValue(null as unknown as string);
 
-      await expect(handler.translateFromStdin(defaultOptions())).rejects.toThrow(ValidationError);
+      await expect(
+        handler.translateFromStdin(defaultOptions())
+      ).rejects.toThrow(ValidationError);
     });
 
     it('should pass options through to textHandler', async () => {
diff --git a/tests/unit/structured-file-translation.test.ts b/tests/unit/structured-file-translation.test.ts
index cfa44421..6750215a 100644
--- a/tests/unit/structured-file-translation.test.ts
+++ b/tests/unit/structured-file-translation.test.ts
@@ -63,10 +63,17 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        greeting: 'Hello',
-        farewell: 'Goodbye',
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            greeting: 'Hello',
+            farewell: 'Goodbye',
+          },
+          null,
+          2
+        )
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Hola', detectedSourceLang: 'en' },
@@ -84,15 +91,22 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        nav: {
-          home: 'Home',
-          about: 'About',
-        },
-        footer: {
-          copyright: 'All rights reserved',
-        },
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            nav: {
+              home: 'Home',
+              about: 'About',
+            },
+            footer: {
+              copyright: 'All rights reserved',
+            },
+          },
+          null,
+          2
+        )
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Inicio', detectedSourceLang: 'en' },
@@ -112,12 +126,19 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        label: 'Hello',
-        count: 42,
-        active: true,
-        data: null,
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            label: 'Hello',
+            count: 42,
+            active: true,
+            data: null,
+          },
+          null,
+          2
+        )
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Hola', detectedSourceLang: 'en' },
@@ -136,10 +157,17 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        items: ['Apple', 'Banana'],
-        mixed: ['Text', 42, true],
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            items: ['Apple', 'Banana'],
+            mixed: ['Text', 42, true],
+          },
+          null,
+          2
+        )
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Manzana', detectedSourceLang: 'en' },
@@ -241,9 +269,16 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        a: { b: { c: { d: 'Deep value' } } },
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            a: { b: { c: { d: 'Deep value' } } },
+          },
+          null,
+          2
+        )
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Valor profundo', detectedSourceLang: 'en' },
@@ -259,11 +294,18 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        zebra: 'Zebra',
-        apple: 'Apple',
-        mango: 'Mango',
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            zebra: 'Zebra',
+            apple: 'Apple',
+            mango: 'Mango',
+          },
+          null,
+          2
+        )
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Cebra', detectedSourceLang: 'en' },
@@ -285,7 +327,10 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({ key: 'Hello' }, null, 2) + '\n');
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify({ key: 'Hello' }, null, 2) + '\n'
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Hola', detectedSourceLang: 'en' },
@@ -321,14 +366,17 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.yaml');
       const outputPath = path.join(testDir, 'es.yaml');
 
-      fs.writeFileSync(inputPath, [
-        'nav:',
-        '  home: Home',
-        '  about: About',
-        'footer:',
-        '  copyright: All rights reserved',
-        '',
-      ].join('\n'));
+      fs.writeFileSync(
+        inputPath,
+        [
+          'nav:',
+          '  home: Home',
+          '  about: About',
+          'footer:',
+          '  copyright: All rights reserved',
+          '',
+        ].join('\n')
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Inicio', detectedSourceLang: 'en' },
@@ -348,13 +396,16 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.yaml');
       const outputPath = path.join(testDir, 'es.yaml');
 
-      fs.writeFileSync(inputPath, [
-        '# This is the main config',
-        'greeting: Hello # inline comment',
-        '# Section break',
-        'farewell: Goodbye',
-        '',
-      ].join('\n'));
+      fs.writeFileSync(
+        inputPath,
+        [
+          '# This is the main config',
+          'greeting: Hello # inline comment',
+          '# Section break',
+          'farewell: Goodbye',
+          '',
+        ].join('\n')
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Hola', detectedSourceLang: 'en' },
@@ -373,13 +424,12 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.yaml');
       const outputPath = path.join(testDir, 'es.yaml');
 
-      fs.writeFileSync(inputPath, [
-        'label: Hello',
-        'count: 42',
-        'active: true',
-        'data: null',
-        '',
-      ].join('\n'));
+      fs.writeFileSync(
+        inputPath,
+        ['label: Hello', 'count: 42', 'active: true', 'data: null', ''].join(
+          '\n'
+        )
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Hola', detectedSourceLang: 'en' },
@@ -414,12 +464,10 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.yaml');
       const outputPath = path.join(testDir, 'es.yaml');
 
-      fs.writeFileSync(inputPath, [
-        'items:',
-        '  - Apple',
-        '  - Banana',
-        '',
-      ].join('\n'));
+      fs.writeFileSync(
+        inputPath,
+        ['items:', '  - Apple', '  - Banana', ''].join('\n')
+      );
 
       mockTranslationService.translateBatch.mockResolvedValue([
         { text: 'Manzana', detectedSourceLang: 'en' },
@@ -467,7 +515,7 @@ describe('StructuredFileTranslationService', () => {
       }
       fs.writeFileSync(inputPath, JSON.stringify(data, null, 2));
 
-      const batchResults = Object.values(data).map(v => ({
+      const batchResults = Object.values(data).map((v) => ({
         text: `Translated ${v}`,
         detectedSourceLang: 'en' as const,
       }));
@@ -501,9 +549,7 @@ describe('StructuredFileTranslationService', () => {
           { text: 'T1', detectedSourceLang: 'en' },
           { text: 'T2', detectedSourceLang: 'en' },
         ])
-        .mockResolvedValueOnce([
-          { text: 'T3', detectedSourceLang: 'en' },
-        ]);
+        .mockResolvedValueOnce([{ text: 'T3', detectedSourceLang: 'en' }]);
 
       await service.translateFile(inputPath, outputPath, { targetLang: 'es' });
 
@@ -515,19 +561,26 @@ describe('StructuredFileTranslationService', () => {
     it('should translate to multiple target languages', async () => {
       const inputPath = path.join(testDir, 'en.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({ greeting: 'Hello' }, null, 2));
-
-      mockTranslationService.translateBatch.mockImplementation(async (_texts, opts) => {
-        if (opts.targetLang === 'es') return [{ text: 'Hola', detectedSourceLang: 'en' }];
-        if (opts.targetLang === 'fr') return [{ text: 'Bonjour', detectedSourceLang: 'en' }];
-        return [];
-      });
-
-      const results = await service.translateFileToMultiple(
+      fs.writeFileSync(
         inputPath,
-        ['es', 'fr'],
+        JSON.stringify({ greeting: 'Hello' }, null, 2)
+      );
+
+      mockTranslationService.translateBatch.mockImplementation(
+        async (_texts, opts) => {
+          if (opts.targetLang === 'es')
+            return [{ text: 'Hola', detectedSourceLang: 'en' }];
+          if (opts.targetLang === 'fr')
+            return [{ text: 'Bonjour', detectedSourceLang: 'en' }];
+          return [];
+        }
       );
 
+      const results = await service.translateFileToMultiple(inputPath, [
+        'es',
+        'fr',
+      ]);
+
       expect(results).toHaveLength(2);
       expect(results[0]?.targetLang).toBe('es');
       expect(results[1]?.targetLang).toBe('fr');
@@ -536,13 +589,20 @@ describe('StructuredFileTranslationService', () => {
     it('should write output files with language suffix', async () => {
       const inputPath = path.join(testDir, 'en.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({ greeting: 'Hello' }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify({ greeting: 'Hello' }, null, 2)
+      );
 
-      mockTranslationService.translateBatch.mockImplementation(async (_texts, opts) => {
-        if (opts.targetLang === 'es') return [{ text: 'Hola', detectedSourceLang: 'en' }];
-        if (opts.targetLang === 'fr') return [{ text: 'Bonjour', detectedSourceLang: 'en' }];
-        return [];
-      });
+      mockTranslationService.translateBatch.mockImplementation(
+        async (_texts, opts) => {
+          if (opts.targetLang === 'es')
+            return [{ text: 'Hola', detectedSourceLang: 'en' }];
+          if (opts.targetLang === 'fr')
+            return [{ text: 'Bonjour', detectedSourceLang: 'en' }];
+          return [];
+        }
+      );
 
       const results = await service.translateFileToMultiple(
         inputPath,
@@ -553,26 +613,35 @@ describe('StructuredFileTranslationService', () => {
       expect(results[0]?.outputPath).toContain('en.es.json');
       expect(results[1]?.outputPath).toContain('en.fr.json');
 
-      const esContent = JSON.parse(fs.readFileSync(results[0]!.outputPath!, 'utf-8'));
+      const esContent = JSON.parse(
+        fs.readFileSync(results[0]!.outputPath!, 'utf-8')
+      );
       expect(esContent.greeting).toBe('Hola');
     });
 
     it('should run translations concurrently', async () => {
       const inputPath = path.join(testDir, 'en.json');
-      fs.writeFileSync(inputPath, JSON.stringify({ greeting: 'Hello' }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify({ greeting: 'Hello' }, null, 2)
+      );
 
       let inflight = 0;
       let maxInflight = 0;
 
-      mockTranslationService.translateBatch.mockImplementation(async (_texts, opts) => {
-        inflight++;
-        maxInflight = Math.max(maxInflight, inflight);
-        await new Promise(r => setTimeout(r, 10));
-        inflight--;
-        if (opts.targetLang === 'es') return [{ text: 'Hola', detectedSourceLang: 'en' }];
-        if (opts.targetLang === 'fr') return [{ text: 'Bonjour', detectedSourceLang: 'en' }];
-        return [];
-      });
+      mockTranslationService.translateBatch.mockImplementation(
+        async (_texts, opts) => {
+          inflight++;
+          maxInflight = Math.max(maxInflight, inflight);
+          await new Promise((r) => setTimeout(r, 10));
+          inflight--;
+          if (opts.targetLang === 'es')
+            return [{ text: 'Hola', detectedSourceLang: 'en' }];
+          if (opts.targetLang === 'fr')
+            return [{ text: 'Bonjour', detectedSourceLang: 'en' }];
+          return [];
+        }
+      );
 
       await service.translateFileToMultiple(inputPath, ['es', 'fr']);
 
@@ -638,11 +707,18 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        a: 'Hello',
-        b: 'World',
-        c: 'Goodbye',
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            a: 'Hello',
+            b: 'World',
+            c: 'Goodbye',
+          },
+          null,
+          2
+        )
+      );
 
       // Return only 2 results for 3 strings → triggers mismatch
       mockTranslationService.translateBatch.mockResolvedValue([
@@ -664,9 +740,16 @@ describe('StructuredFileTranslationService', () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
-      fs.writeFileSync(inputPath, JSON.stringify({
-        a: 'Hello',
-      }, null, 2));
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            a: 'Hello',
+          },
+          null,
+          2
+        )
+      );
 
       // Return 2 results for 1 string → triggers mismatch
       mockTranslationService.translateBatch.mockResolvedValue([
@@ -698,9 +781,7 @@ describe('StructuredFileTranslationService', () => {
 
       // First batch succeeds
       mockTranslationService.translateBatch
-        .mockResolvedValueOnce([
-          { text: 'T1', detectedSourceLang: 'en' },
-        ])
+        .mockResolvedValueOnce([{ text: 'T1', detectedSourceLang: 'en' }])
         // Second batch returns mismatch (0 results for 1 string)
         .mockResolvedValueOnce([]);
 
diff --git a/tests/unit/style-rules-client.test.ts b/tests/unit/style-rules-client.test.ts
index 781ac011..af86bd5a 100644
--- a/tests/unit/style-rules-client.test.ts
+++ b/tests/unit/style-rules-client.test.ts
@@ -44,7 +44,7 @@ describe('StyleRulesClient', () => {
       expect(mockedAxios.create).toHaveBeenCalledWith(
         expect.objectContaining({
           baseURL: 'https://api-free.deepl.com',
-        }),
+        })
       );
     });
   });
@@ -98,7 +98,11 @@ describe('StyleRulesClient', () => {
               },
               custom_instructions: [
                 { label: 'Instruction 1', prompt: 'Use formal tone' },
-                { label: 'Instruction 2', prompt: 'Short sentences', source_language: 'en' },
+                {
+                  label: 'Instruction 2',
+                  prompt: 'Short sentences',
+                  source_language: 'en',
+                },
               ],
             },
           ],
@@ -160,7 +164,11 @@ describe('StyleRulesClient', () => {
     it('should handle 429 rate limit error', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 429, data: { message: 'Rate limited' }, headers: {} },
+        response: {
+          status: 429,
+          data: { message: 'Rate limited' },
+          headers: {},
+        },
         message: 'Rate limited',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -185,7 +193,10 @@ describe('StyleRulesClient', () => {
         headers: {},
       });
 
-      const result = await client.createStyleRule({ name: 'Corporate', language: 'en' });
+      const result = await client.createStyleRule({
+        name: 'Corporate',
+        language: 'en',
+      });
 
       expect(result).toEqual({
         styleId: 'sr-new',
@@ -200,17 +211,22 @@ describe('StyleRulesClient', () => {
           method: 'POST',
           url: '/v3/style_rules',
           data: expect.objectContaining({ name: 'Corporate', language: 'en' }),
-        }),
+        })
       );
     });
 
     it('should serialize customInstructions with snake_case sourceLanguage', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          style_id: 'sr-new', name: 'X', language: 'de', version: 1,
-          creation_time: 't', updated_time: 't',
+          style_id: 'sr-new',
+          name: 'X',
+          language: 'de',
+          version: 1,
+          creation_time: 't',
+          updated_time: 't',
         },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
 
       await client.createStyleRule({
@@ -228,7 +244,11 @@ describe('StyleRulesClient', () => {
     it('should propagate 400 error', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 400, data: { message: 'Invalid language' }, headers: {} },
+        response: {
+          status: 400,
+          data: { message: 'Invalid language' },
+          headers: {},
+        },
         message: 'Bad request',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -244,49 +264,75 @@ describe('StyleRulesClient', () => {
     it('should GET /v3/style_rules/:id and return basic rule', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          style_id: 'sr-1', name: 'One', language: 'en', version: 1,
-          creation_time: 'c', updated_time: 'u',
+          style_id: 'sr-1',
+          name: 'One',
+          language: 'en',
+          version: 1,
+          creation_time: 'c',
+          updated_time: 'u',
         },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
 
       const result = await client.getStyleRule('sr-1');
 
       expect(result).toEqual({
-        styleId: 'sr-1', name: 'One', language: 'en', version: 1,
-        creationTime: 'c', updatedTime: 'u',
+        styleId: 'sr-1',
+        name: 'One',
+        language: 'en',
+        version: 1,
+        creationTime: 'c',
+        updatedTime: 'u',
       });
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
-        expect.objectContaining({ method: 'GET', url: '/v3/style_rules/sr-1' }),
+        expect.objectContaining({ method: 'GET', url: '/v3/style_rules/sr-1' })
       );
     });
 
     it('should return StyleRuleDetailed when detailed=true', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          style_id: 'sr-2', name: 'Two', language: 'de', version: 3,
-          creation_time: 'c', updated_time: 'u',
-          configured_rules: { punctuation: { quotation_mark: 'use_guillemets' } },
+          style_id: 'sr-2',
+          name: 'Two',
+          language: 'de',
+          version: 3,
+          creation_time: 'c',
+          updated_time: 'u',
+          configured_rules: {
+            punctuation: { quotation_mark: 'use_guillemets' },
+          },
           custom_instructions: [{ label: 'L', prompt: 'P' }],
         },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
 
       const result = await client.getStyleRule('sr-2', true);
       expect((result as StyleRuleDetailed).configuredRules).toEqual({
         punctuation: { quotation_mark: 'use_guillemets' },
       });
-      expect((result as StyleRuleDetailed).customInstructions).toEqual([{ label: 'L', prompt: 'P' }]);
+      expect((result as StyleRuleDetailed).customInstructions).toEqual([
+        { label: 'L', prompt: 'P' },
+      ]);
     });
 
     it('should URL-encode the styleId path component', async () => {
       mockAxiosInstance.request.mockResolvedValue({
-        data: { style_id: 'has space', name: '', language: '', version: 0, creation_time: '', updated_time: '' },
-        status: 200, headers: {},
+        data: {
+          style_id: 'has space',
+          name: '',
+          language: '',
+          version: 0,
+          creation_time: '',
+          updated_time: '',
+        },
+        status: 200,
+        headers: {},
       });
       await client.getStyleRule('has space');
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
-        expect.objectContaining({ url: '/v3/style_rules/has%20space' }),
+        expect.objectContaining({ url: '/v3/style_rules/has%20space' })
       );
     });
 
@@ -307,10 +353,15 @@ describe('StyleRulesClient', () => {
     it('should PATCH /v3/style_rules/:id with partial body', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          style_id: 'sr-1', name: 'Renamed', language: 'en', version: 2,
-          creation_time: 'c', updated_time: 'u2',
+          style_id: 'sr-1',
+          name: 'Renamed',
+          language: 'en',
+          version: 2,
+          creation_time: 'c',
+          updated_time: 'u2',
         },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
 
       const result = await client.updateStyleRule('sr-1', { name: 'Renamed' });
@@ -321,14 +372,22 @@ describe('StyleRulesClient', () => {
           method: 'PATCH',
           url: '/v3/style_rules/sr-1',
           data: { name: 'Renamed' },
-        }),
+        })
       );
     });
 
     it('should omit fields not passed', async () => {
       mockAxiosInstance.request.mockResolvedValue({
-        data: { style_id: 'sr-1', name: 'X', language: 'en', version: 1, creation_time: 'c', updated_time: 'u' },
-        status: 200, headers: {},
+        data: {
+          style_id: 'sr-1',
+          name: 'X',
+          language: 'en',
+          version: 1,
+          creation_time: 'c',
+          updated_time: 'u',
+        },
+        status: 200,
+        headers: {},
       });
 
       await client.updateStyleRule('sr-1', {});
@@ -345,19 +404,28 @@ describe('StyleRulesClient', () => {
       mockAxiosInstance.request.mockRejectedValue(axiosError);
       jest.spyOn(axios, 'isAxiosError').mockReturnValue(true);
 
-      await expect(client.updateStyleRule('missing', { name: 'X' })).rejects.toThrow();
+      await expect(
+        client.updateStyleRule('missing', { name: 'X' })
+      ).rejects.toThrow();
     });
   });
 
   describe('deleteStyleRule()', () => {
     it('should DELETE /v3/style_rules/:id and resolve void', async () => {
-      mockAxiosInstance.request.mockResolvedValue({ data: undefined, status: 204, headers: {} });
+      mockAxiosInstance.request.mockResolvedValue({
+        data: undefined,
+        status: 204,
+        headers: {},
+      });
 
       const result = await client.deleteStyleRule('sr-1');
 
       expect(result).toBeUndefined();
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
-        expect.objectContaining({ method: 'DELETE', url: '/v3/style_rules/sr-1' }),
+        expect.objectContaining({
+          method: 'DELETE',
+          url: '/v3/style_rules/sr-1',
+        })
       );
     });
 
@@ -378,10 +446,14 @@ describe('StyleRulesClient', () => {
     it('should POST to /v3/style_rules/:id/custom_instructions with label+prompt and return mapped instruction', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: { label: 'tone', prompt: 'Be formal' },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
 
-      const result = await client.createCustomInstruction('sr-1', { label: 'tone', prompt: 'Be formal' });
+      const result = await client.createCustomInstruction('sr-1', {
+        label: 'tone',
+        prompt: 'Be formal',
+      });
 
       expect(result).toEqual({ label: 'tone', prompt: 'Be formal' });
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
@@ -389,29 +461,40 @@ describe('StyleRulesClient', () => {
           method: 'POST',
           url: '/v3/style_rules/sr-1/custom_instructions',
           data: { label: 'tone', prompt: 'Be formal' },
-        }),
+        })
       );
     });
 
     it('should serialize sourceLanguage as source_language on the wire', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: { label: 'L', prompt: 'P', source_language: 'en' },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
 
       const result = await client.createCustomInstruction('sr-1', {
-        label: 'L', prompt: 'P', sourceLanguage: 'en',
+        label: 'L',
+        prompt: 'P',
+        sourceLanguage: 'en',
       });
 
       expect(result.sourceLanguage).toBe('en');
       const call = mockAxiosInstance.request.mock.calls[0][0];
-      expect(call.data).toEqual({ label: 'L', prompt: 'P', source_language: 'en' });
+      expect(call.data).toEqual({
+        label: 'L',
+        prompt: 'P',
+        source_language: 'en',
+      });
     });
 
     it('should propagate 400 error', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 400, data: { message: 'Duplicate label' }, headers: {} },
+        response: {
+          status: 400,
+          data: { message: 'Duplicate label' },
+          headers: {},
+        },
         message: 'Bad request',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -429,12 +512,17 @@ describe('StyleRulesClient', () => {
   function queueInstructionLookup(label: string, instructionId: string): void {
     mockAxiosInstance.request.mockResolvedValueOnce({
       data: {
-        style_id: 'sr-1', name: 'X', language: 'en', version: 1,
-        creation_time: 'c', updated_time: 'u',
+        style_id: 'sr-1',
+        name: 'X',
+        language: 'en',
+        version: 1,
+        creation_time: 'c',
+        updated_time: 'u',
         configured_rules: {},
         custom_instructions: [{ id: instructionId, label, prompt: 'P' }],
       },
-      status: 200, headers: {},
+      status: 200,
+      headers: {},
     });
   }
 
@@ -442,26 +530,40 @@ describe('StyleRulesClient', () => {
     it('should look up instruction id by label and GET /v3/style_rules/:id/custom_instructions/:instructionId', async () => {
       queueInstructionLookup('tone', 'inst-uuid-1');
       mockAxiosInstance.request.mockResolvedValueOnce({
-        data: { id: 'inst-uuid-1', label: 'tone', prompt: 'Be formal', source_language: 'en' },
-        status: 200, headers: {},
+        data: {
+          id: 'inst-uuid-1',
+          label: 'tone',
+          prompt: 'Be formal',
+          source_language: 'en',
+        },
+        status: 200,
+        headers: {},
       });
 
       const result = await client.getCustomInstruction('sr-1', 'tone');
 
-      expect(result).toEqual({ id: 'inst-uuid-1', label: 'tone', prompt: 'Be formal', sourceLanguage: 'en' });
+      expect(result).toEqual({
+        id: 'inst-uuid-1',
+        label: 'tone',
+        prompt: 'Be formal',
+        sourceLanguage: 'en',
+      });
       const calls = mockAxiosInstance.request.mock.calls;
       // Second call is the actual GET on the instruction by id.
-      expect(calls[1][0]).toEqual(expect.objectContaining({
-        method: 'GET',
-        url: '/v3/style_rules/sr-1/custom_instructions/inst-uuid-1',
-      }));
+      expect(calls[1][0]).toEqual(
+        expect.objectContaining({
+          method: 'GET',
+          url: '/v3/style_rules/sr-1/custom_instructions/inst-uuid-1',
+        })
+      );
     });
 
     it('should URL-encode both path components', async () => {
       queueInstructionLookup('has space', 'inst id with space');
       mockAxiosInstance.request.mockResolvedValueOnce({
         data: { id: 'inst id with space', label: 'has space', prompt: 'P' },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
       // The styleId is also a constructed URL — we need it to test encoding,
       // but resolveInstructionId does its own GET which uses the raw styleId via
@@ -471,21 +573,31 @@ describe('StyleRulesClient', () => {
       const calls = mockAxiosInstance.request.mock.calls;
       await client.getCustomInstruction('sr-1', 'has space');
       const lastCall = calls[calls.length - 1][0];
-      expect(lastCall.url).toBe('/v3/style_rules/sr-1/custom_instructions/inst%20id%20with%20space');
+      expect(lastCall.url).toBe(
+        '/v3/style_rules/sr-1/custom_instructions/inst%20id%20with%20space'
+      );
     });
 
     it('should throw ValidationError when label not found', async () => {
       mockAxiosInstance.request.mockResolvedValueOnce({
         data: {
-          style_id: 'sr-1', name: 'X', language: 'en', version: 1,
-          creation_time: 'c', updated_time: 'u',
+          style_id: 'sr-1',
+          name: 'X',
+          language: 'en',
+          version: 1,
+          creation_time: 'c',
+          updated_time: 'u',
           configured_rules: {},
-          custom_instructions: [{ id: 'other-uuid', label: 'register', prompt: 'P' }],
+          custom_instructions: [
+            { id: 'other-uuid', label: 'register', prompt: 'P' },
+          ],
         },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
-      await expect(client.getCustomInstruction('sr-1', 'missing'))
-        .rejects.toThrow(/No custom instruction with label "missing"/);
+      await expect(
+        client.getCustomInstruction('sr-1', 'missing')
+      ).rejects.toThrow(/No custom instruction with label "missing"/);
     });
   });
 
@@ -494,26 +606,33 @@ describe('StyleRulesClient', () => {
       queueInstructionLookup('tone', 'inst-uuid-1');
       mockAxiosInstance.request.mockResolvedValueOnce({
         data: { id: 'inst-uuid-1', label: 'tone', prompt: 'Be friendlier' },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
 
-      const result = await client.updateCustomInstruction('sr-1', 'tone', { prompt: 'Be friendlier' });
+      const result = await client.updateCustomInstruction('sr-1', 'tone', {
+        prompt: 'Be friendlier',
+      });
 
       expect(result.prompt).toBe('Be friendlier');
       // The PUT call is the second axios request.
       // Body must include `label` (server requires it even though `instruction_id` is in the URL).
       const putCall = mockAxiosInstance.request.mock.calls[1][0];
-      expect(putCall).toEqual(expect.objectContaining({
-        method: 'PUT',
-        url: '/v3/style_rules/sr-1/custom_instructions/inst-uuid-1',
-        data: { label: 'tone', prompt: 'Be friendlier' },
-      }));
+      expect(putCall).toEqual(
+        expect.objectContaining({
+          method: 'PUT',
+          url: '/v3/style_rules/sr-1/custom_instructions/inst-uuid-1',
+          data: { label: 'tone', prompt: 'Be friendlier' },
+        })
+      );
     });
 
     it('should always include label and omit unset optional fields', async () => {
       queueInstructionLookup('tone', 'inst-uuid-1');
       mockAxiosInstance.request.mockResolvedValueOnce({
-        data: { id: 'inst-uuid-1', label: 'tone', prompt: 'x' }, status: 200, headers: {},
+        data: { id: 'inst-uuid-1', label: 'tone', prompt: 'x' },
+        status: 200,
+        headers: {},
       });
       await client.updateCustomInstruction('sr-1', 'tone', {});
       const putCall = mockAxiosInstance.request.mock.calls[1][0];
@@ -523,12 +642,17 @@ describe('StyleRulesClient', () => {
     it('should throw ValidationError when label not found', async () => {
       mockAxiosInstance.request.mockResolvedValueOnce({
         data: {
-          style_id: 'sr-1', name: 'X', language: 'en', version: 1,
-          creation_time: 'c', updated_time: 'u',
+          style_id: 'sr-1',
+          name: 'X',
+          language: 'en',
+          version: 1,
+          creation_time: 'c',
+          updated_time: 'u',
           configured_rules: {},
           custom_instructions: [],
         },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
       await expect(
         client.updateCustomInstruction('sr-1', 'missing', { prompt: 'X' })
@@ -539,30 +663,42 @@ describe('StyleRulesClient', () => {
   describe('deleteCustomInstruction()', () => {
     it('should look up id then DELETE /v3/style_rules/:id/custom_instructions/:instructionId and resolve void', async () => {
       queueInstructionLookup('tone', 'inst-uuid-1');
-      mockAxiosInstance.request.mockResolvedValueOnce({ data: undefined, status: 204, headers: {} });
+      mockAxiosInstance.request.mockResolvedValueOnce({
+        data: undefined,
+        status: 204,
+        headers: {},
+      });
 
       const result = await client.deleteCustomInstruction('sr-1', 'tone');
 
       expect(result).toBeUndefined();
       const deleteCall = mockAxiosInstance.request.mock.calls[1][0];
-      expect(deleteCall).toEqual(expect.objectContaining({
-        method: 'DELETE',
-        url: '/v3/style_rules/sr-1/custom_instructions/inst-uuid-1',
-      }));
+      expect(deleteCall).toEqual(
+        expect.objectContaining({
+          method: 'DELETE',
+          url: '/v3/style_rules/sr-1/custom_instructions/inst-uuid-1',
+        })
+      );
     });
 
     it('should propagate 404 error', async () => {
       mockAxiosInstance.request.mockResolvedValueOnce({
         data: {
-          style_id: 'sr-1', name: 'X', language: 'en', version: 1,
-          creation_time: 'c', updated_time: 'u',
+          style_id: 'sr-1',
+          name: 'X',
+          language: 'en',
+          version: 1,
+          creation_time: 'c',
+          updated_time: 'u',
           configured_rules: {},
           custom_instructions: [],
         },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
-      await expect(client.deleteCustomInstruction('sr-1', 'missing'))
-        .rejects.toThrow(/No custom instruction with label "missing"/);
+      await expect(
+        client.deleteCustomInstruction('sr-1', 'missing')
+      ).rejects.toThrow(/No custom instruction with label "missing"/);
     });
   });
 
@@ -574,12 +710,17 @@ describe('StyleRulesClient', () => {
       };
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          style_id: 'sr-1', name: 'X', language: 'en', version: 3,
-          creation_time: 'c', updated_time: 'u3',
+          style_id: 'sr-1',
+          name: 'X',
+          language: 'en',
+          version: 3,
+          creation_time: 'c',
+          updated_time: 'u3',
           configured_rules: rules,
           custom_instructions: [],
         },
-        status: 200, headers: {},
+        status: 200,
+        headers: {},
       });
 
       const result = await client.replaceConfiguredRules('sr-1', rules);
@@ -592,21 +733,25 @@ describe('StyleRulesClient', () => {
           method: 'PUT',
           url: '/v3/style_rules/sr-1/configured_rules',
           data: rules,
-        }),
+        })
       );
     });
 
     it('should propagate 400 error for invalid rules', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 400, data: { message: 'Invalid rule' }, headers: {} },
+        response: {
+          status: 400,
+          data: { message: 'Invalid rule' },
+          headers: {},
+        },
         message: 'Bad request',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
       jest.spyOn(axios, 'isAxiosError').mockReturnValue(true);
 
       await expect(
-        client.replaceConfiguredRules('sr-1', { bogus: { x: 'y' } }),
+        client.replaceConfiguredRules('sr-1', { bogus: { x: 'y' } })
       ).rejects.toThrow();
     });
   });
diff --git a/tests/unit/style-rules-command.test.ts b/tests/unit/style-rules-command.test.ts
index c294f0a2..d4c98185 100644
--- a/tests/unit/style-rules-command.test.ts
+++ b/tests/unit/style-rules-command.test.ts
@@ -26,12 +26,17 @@ describe('StyleRulesCommand', () => {
 
     it('should pass detailed option', async () => {
       await command.list({ detailed: true });
-      expect(mockService.getStyleRules).toHaveBeenCalledWith({ detailed: true });
+      expect(mockService.getStyleRules).toHaveBeenCalledWith({
+        detailed: true,
+      });
     });
 
     it('should pass pagination options', async () => {
       await command.list({ page: 2, pageSize: 10 });
-      expect(mockService.getStyleRules).toHaveBeenCalledWith({ page: 2, pageSize: 10 });
+      expect(mockService.getStyleRules).toHaveBeenCalledWith({
+        page: 2,
+        pageSize: 10,
+      });
     });
 
     it('should return rules from service', async () => {
@@ -92,7 +97,11 @@ describe('StyleRulesCommand', () => {
           },
           customInstructions: [
             { label: 'Formality', prompt: 'Keep it formal' },
-            { label: 'Tone', prompt: 'Use friendly tone', sourceLanguage: 'en' },
+            {
+              label: 'Tone',
+              prompt: 'Use friendly tone',
+              sourceLanguage: 'en',
+            },
           ],
         },
       ];
@@ -178,14 +187,16 @@ describe('StyleRulesCommand', () => {
     });
 
     it('should sanitize ANSI escapes in rule name when formatting list text', () => {
-      const evil: StyleRule[] = [{
-        styleId: 'sr-1',
-        name: 'Evil\u001b[31mred',
-        language: 'en',
-        version: 1,
-        creationTime: 'c',
-        updatedTime: 'u',
-      }];
+      const evil: StyleRule[] = [
+        {
+          styleId: 'sr-1',
+          name: 'Evil\u001b[31mred',
+          language: 'en',
+          version: 1,
+          creationTime: 'c',
+          updatedTime: 'u',
+        },
+      ];
       const result = command.formatStyleRulesList(evil);
       expect(result).not.toContain('\u001b[31m');
     });
@@ -194,7 +205,10 @@ describe('StyleRulesCommand', () => {
   describe('create', () => {
     it('should proxy to service.createStyleRule', async () => {
       await command.create({ name: 'X', language: 'en' });
-      expect(mockService.createStyleRule).toHaveBeenCalledWith({ name: 'X', language: 'en' });
+      expect(mockService.createStyleRule).toHaveBeenCalledWith({
+        name: 'X',
+        language: 'en',
+      });
     });
   });
 
@@ -213,7 +227,9 @@ describe('StyleRulesCommand', () => {
   describe('update', () => {
     it('should proxy to service.updateStyleRule', async () => {
       await command.update('sr-1', { name: 'Renamed' });
-      expect(mockService.updateStyleRule).toHaveBeenCalledWith('sr-1', { name: 'Renamed' });
+      expect(mockService.updateStyleRule).toHaveBeenCalledWith('sr-1', {
+        name: 'Renamed',
+      });
     });
   });
 
@@ -228,7 +244,10 @@ describe('StyleRulesCommand', () => {
     it('should proxy to service.replaceConfiguredRules', async () => {
       const rules = { punctuation: { quotation_mark: 'use_guillemets' } };
       await command.replaceRules('sr-1', rules);
-      expect(mockService.replaceConfiguredRules).toHaveBeenCalledWith('sr-1', rules);
+      expect(mockService.replaceConfiguredRules).toHaveBeenCalledWith(
+        'sr-1',
+        rules
+      );
     });
   });
 
@@ -290,7 +309,9 @@ describe('StyleRulesCommand', () => {
     it('should sanitize ANSI escapes in configured-rules keys and values', () => {
       const evil: StyleRuleDetailed = {
         ...baseRule,
-        configuredRules: { 'cat\u001b[31m': { 'key\u001b[32m': 'val\u001b[0m' } },
+        configuredRules: {
+          'cat\u001b[31m': { 'key\u001b[32m': 'val\u001b[0m' },
+        },
         customInstructions: [],
       };
       const result = command.formatStyleRule(evil);
@@ -303,8 +324,12 @@ describe('StyleRulesCommand', () => {
   describe('listInstructions', () => {
     it('should call service.getStyleRule with detailed=true and return the nested array', async () => {
       mockService.getStyleRule.mockResolvedValue({
-        styleId: 'sr-1', name: 'X', language: 'en', version: 1,
-        creationTime: 'c', updatedTime: 'u',
+        styleId: 'sr-1',
+        name: 'X',
+        language: 'en',
+        version: 1,
+        creationTime: 'c',
+        updatedTime: 'u',
         configuredRules: {},
         customInstructions: [
           { label: 'tone', prompt: 'Be formal' },
@@ -320,8 +345,12 @@ describe('StyleRulesCommand', () => {
 
     it('should return empty array when rule has no customInstructions field', async () => {
       mockService.getStyleRule.mockResolvedValue({
-        styleId: 'sr-1', name: 'X', language: 'en', version: 1,
-        creationTime: 'c', updatedTime: 'u',
+        styleId: 'sr-1',
+        name: 'X',
+        language: 'en',
+        version: 1,
+        creationTime: 'c',
+        updatedTime: 'u',
       });
 
       const result = await command.listInstructions('sr-1');
@@ -332,40 +361,57 @@ describe('StyleRulesCommand', () => {
   describe('addInstruction', () => {
     it('should proxy to service.createCustomInstruction', async () => {
       await command.addInstruction('sr-1', { label: 'L', prompt: 'P' });
-      expect(mockService.createCustomInstruction).toHaveBeenCalledWith('sr-1', { label: 'L', prompt: 'P' });
+      expect(mockService.createCustomInstruction).toHaveBeenCalledWith('sr-1', {
+        label: 'L',
+        prompt: 'P',
+      });
     });
   });
 
   describe('updateInstruction', () => {
     it('should proxy to service.updateCustomInstruction', async () => {
       await command.updateInstruction('sr-1', 'tone', { prompt: 'New text' });
-      expect(mockService.updateCustomInstruction).toHaveBeenCalledWith('sr-1', 'tone', { prompt: 'New text' });
+      expect(mockService.updateCustomInstruction).toHaveBeenCalledWith(
+        'sr-1',
+        'tone',
+        { prompt: 'New text' }
+      );
     });
   });
 
   describe('removeInstruction', () => {
     it('should proxy to service.deleteCustomInstruction', async () => {
       await command.removeInstruction('sr-1', 'tone');
-      expect(mockService.deleteCustomInstruction).toHaveBeenCalledWith('sr-1', 'tone');
+      expect(mockService.deleteCustomInstruction).toHaveBeenCalledWith(
+        'sr-1',
+        'tone'
+      );
     });
   });
 
   describe('formatCustomInstruction / formatCustomInstructionsList / formatCustomInstructionJson', () => {
     it('should render a single instruction in text', () => {
-      const result = command.formatCustomInstruction({ label: 'tone', prompt: 'Be formal' });
+      const result = command.formatCustomInstruction({
+        label: 'tone',
+        prompt: 'Be formal',
+      });
       expect(result).toContain('tone');
       expect(result).toContain('Be formal');
     });
 
     it('should append source-language suffix when present', () => {
       const result = command.formatCustomInstruction({
-        label: 'tone', prompt: 'Be formal', sourceLanguage: 'en',
+        label: 'tone',
+        prompt: 'Be formal',
+        sourceLanguage: 'en',
       });
       expect(result).toContain('[en]');
     });
 
     it('should render empty list as a friendly message', () => {
-      expect(command.formatCustomInstructionsList([])).toBe('No custom instructions found.');
+      expect(command.formatCustomInstructionsList([])).toBe(
+        'No custom instructions found.'
+      );
     });
 
     it('should render a list of instructions', () => {
@@ -387,7 +433,9 @@ describe('StyleRulesCommand', () => {
     });
 
     it('should emit valid JSON preserving raw strings', () => {
-      const json = command.formatCustomInstructionJson([{ label: 'L', prompt: 'P' }]);
+      const json = command.formatCustomInstructionJson([
+        { label: 'L', prompt: 'P' },
+      ]);
       expect(JSON.parse(json)).toEqual([{ label: 'L', prompt: 'P' }]);
     });
   });
@@ -439,7 +487,9 @@ describe('StyleRulesCommand', () => {
       const detailed: StyleRuleDetailed = {
         ...baseRule,
         // 2 leaf settings across 1 category — Rules count = 2
-        configuredRules: { punctuation: { quotation_mark: 'use_guillemets', spacing: 'tight' } },
+        configuredRules: {
+          punctuation: { quotation_mark: 'use_guillemets', spacing: 'tight' },
+        },
         customInstructions: [{ label: 'tone', prompt: 'formal' }],
       };
       const result = command.formatStyleRulesTable([detailed]);
@@ -463,7 +513,9 @@ describe('StyleRulesCommand', () => {
 
   describe('formatCustomInstructionsTable', () => {
     it('should return empty-state message when no instructions', () => {
-      expect(command.formatCustomInstructionsTable([])).toBe('No custom instructions found.');
+      expect(command.formatCustomInstructionsTable([])).toBe(
+        'No custom instructions found.'
+      );
     });
 
     it('should include label, prompt, and source columns', () => {
diff --git a/tests/unit/style-rules-service.test.ts b/tests/unit/style-rules-service.test.ts
index dc265341..93f5cafe 100644
--- a/tests/unit/style-rules-service.test.ts
+++ b/tests/unit/style-rules-service.test.ts
@@ -18,7 +18,11 @@ describe('StyleRulesService', () => {
     const service = new StyleRulesService(mockClient);
 
     await service.getStyleRules({ detailed: true, page: 2, pageSize: 10 });
-    expect(mockClient.getStyleRules).toHaveBeenCalledWith({ detailed: true, page: 2, pageSize: 10 });
+    expect(mockClient.getStyleRules).toHaveBeenCalledWith({
+      detailed: true,
+      page: 2,
+      pageSize: 10,
+    });
   });
 
   it('should return rules from client', async () => {
@@ -54,7 +58,10 @@ describe('StyleRulesService', () => {
     const mockClient = createMockDeepLClient();
     const service = new StyleRulesService(mockClient);
     await service.createStyleRule({ name: 'X', language: 'en' });
-    expect(mockClient.createStyleRule).toHaveBeenCalledWith({ name: 'X', language: 'en' });
+    expect(mockClient.createStyleRule).toHaveBeenCalledWith({
+      name: 'X',
+      language: 'en',
+    });
   });
 
   it('should delegate getStyleRule with detailed flag', async () => {
@@ -75,7 +82,9 @@ describe('StyleRulesService', () => {
     const mockClient = createMockDeepLClient();
     const service = new StyleRulesService(mockClient);
     await service.updateStyleRule('sr-1', { name: 'Renamed' });
-    expect(mockClient.updateStyleRule).toHaveBeenCalledWith('sr-1', { name: 'Renamed' });
+    expect(mockClient.updateStyleRule).toHaveBeenCalledWith('sr-1', {
+      name: 'Renamed',
+    });
   });
 
   it('should delegate deleteStyleRule to client', async () => {
@@ -90,34 +99,50 @@ describe('StyleRulesService', () => {
     const service = new StyleRulesService(mockClient);
     const rules = { punctuation: { quotation_mark: 'use_guillemets' } };
     await service.replaceConfiguredRules('sr-1', rules);
-    expect(mockClient.replaceConfiguredRules).toHaveBeenCalledWith('sr-1', rules);
+    expect(mockClient.replaceConfiguredRules).toHaveBeenCalledWith(
+      'sr-1',
+      rules
+    );
   });
 
   it('should delegate createCustomInstruction to client', async () => {
     const mockClient = createMockDeepLClient();
     const service = new StyleRulesService(mockClient);
     await service.createCustomInstruction('sr-1', { label: 'L', prompt: 'P' });
-    expect(mockClient.createCustomInstruction).toHaveBeenCalledWith('sr-1', { label: 'L', prompt: 'P' });
+    expect(mockClient.createCustomInstruction).toHaveBeenCalledWith('sr-1', {
+      label: 'L',
+      prompt: 'P',
+    });
   });
 
   it('should delegate getCustomInstruction to client', async () => {
     const mockClient = createMockDeepLClient();
     const service = new StyleRulesService(mockClient);
     await service.getCustomInstruction('sr-1', 'tone');
-    expect(mockClient.getCustomInstruction).toHaveBeenCalledWith('sr-1', 'tone');
+    expect(mockClient.getCustomInstruction).toHaveBeenCalledWith(
+      'sr-1',
+      'tone'
+    );
   });
 
   it('should delegate updateCustomInstruction to client', async () => {
     const mockClient = createMockDeepLClient();
     const service = new StyleRulesService(mockClient);
     await service.updateCustomInstruction('sr-1', 'tone', { prompt: 'New' });
-    expect(mockClient.updateCustomInstruction).toHaveBeenCalledWith('sr-1', 'tone', { prompt: 'New' });
+    expect(mockClient.updateCustomInstruction).toHaveBeenCalledWith(
+      'sr-1',
+      'tone',
+      { prompt: 'New' }
+    );
   });
 
   it('should delegate deleteCustomInstruction to client', async () => {
     const mockClient = createMockDeepLClient();
     const service = new StyleRulesService(mockClient);
     await service.deleteCustomInstruction('sr-1', 'tone');
-    expect(mockClient.deleteCustomInstruction).toHaveBeenCalledWith('sr-1', 'tone');
+    expect(mockClient.deleteCustomInstruction).toHaveBeenCalledWith(
+      'sr-1',
+      'tone'
+    );
   });
 });
diff --git a/tests/unit/sync/icu-structure-validation.test.ts b/tests/unit/sync/icu-structure-validation.test.ts
index 83f1eed4..1983247e 100644
--- a/tests/unit/sync/icu-structure-validation.test.ts
+++ b/tests/unit/sync/icu-structure-validation.test.ts
@@ -18,41 +18,48 @@ function severityOf(source: string, translation: string): string {
 
 describe('ICU structure validation', () => {
   it('should pass an intact translation', () => {
-    expect(severityOf(SOURCE, '{count, plural, one {# Artikel} other {# Artikel}}')).toBe('pass');
+    expect(
+      severityOf(SOURCE, '{count, plural, one {# Artikel} other {# Artikel}}')
+    ).toBe('pass');
   });
 
   it('should flag a translated format keyword', () => {
-    expect(severityOf(SOURCE, '{count, Plural, one {# Artikel} other {# Artikel}}')).not.toBe(
-      'pass',
-    );
+    expect(
+      severityOf(SOURCE, '{count, Plural, one {# Artikel} other {# Artikel}}')
+    ).not.toBe('pass');
   });
 
   it('should flag translated plural selectors', () => {
-    expect(severityOf(SOURCE, '{count, plural, eins {# Artikel} andere {# Artikel}}')).not.toBe(
-      'pass',
-    );
+    expect(
+      severityOf(SOURCE, '{count, plural, eins {# Artikel} andere {# Artikel}}')
+    ).not.toBe('pass');
   });
 
   it('should flag a translated argument name', () => {
     // The app passes `count`; renaming it breaks variable binding entirely.
-    expect(severityOf(SOURCE, '{Anzahl, plural, one {# Artikel} other {# Artikel}}')).not.toBe(
-      'pass',
-    );
+    expect(
+      severityOf(SOURCE, '{Anzahl, plural, one {# Artikel} other {# Artikel}}')
+    ).not.toBe('pass');
   });
 
   it('should flag the full live-API corruption', () => {
-    const asReturnedByEngine = '{count, Plural, ein {# item} weiteres {# items}}';
+    const asReturnedByEngine =
+      '{count, Plural, ein {# item} weiteres {# items}}';
 
     expect(severityOf(SOURCE, asReturnedByEngine)).not.toBe('pass');
   });
 
   it('should flag a dropped selector branch', () => {
-    expect(severityOf(SOURCE, '{count, plural, one {# Artikel}}')).not.toBe('pass');
+    expect(severityOf(SOURCE, '{count, plural, one {# Artikel}}')).not.toBe(
+      'pass'
+    );
   });
 
   it('should tolerate reordered selectors', () => {
     // Order is not semantically meaningful in ICU.
-    expect(severityOf(SOURCE, '{count, plural, other {# Artikel} one {# Artikel}}')).toBe('pass');
+    expect(
+      severityOf(SOURCE, '{count, plural, other {# Artikel} one {# Artikel}}')
+    ).toBe('pass');
   });
 
   it('should not flag an ordinary non-ICU translation', () => {
@@ -60,9 +67,12 @@ describe('ICU structure validation', () => {
   });
 
   it('should handle a message with surrounding prose', () => {
-    const source = 'You have {count, plural, one {# item} other {# items}} in your cart.';
-    const good = 'Sie haben {count, plural, one {# Artikel} other {# Artikel}} im Warenkorb.';
-    const bad = 'Sie haben {count, Plural, ein {# Artikel} weiteres {# Artikel}} im Warenkorb.';
+    const source =
+      'You have {count, plural, one {# item} other {# items}} in your cart.';
+    const good =
+      'Sie haben {count, plural, one {# Artikel} other {# Artikel}} im Warenkorb.';
+    const bad =
+      'Sie haben {count, Plural, ein {# Artikel} weiteres {# Artikel}} im Warenkorb.';
 
     expect(severityOf(source, good)).toBe('pass');
     expect(severityOf(source, bad)).not.toBe('pass');
diff --git a/tests/unit/sync/sync-bak-cleanup.test.ts b/tests/unit/sync/sync-bak-cleanup.test.ts
index c3bb6ea5..6a333fd6 100644
--- a/tests/unit/sync/sync-bak-cleanup.test.ts
+++ b/tests/unit/sync/sync-bak-cleanup.test.ts
@@ -1,7 +1,11 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { sweepStaleBackups, bucketSweepRoots, DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS } from '../../../src/sync/sync-bak-cleanup';
+import {
+  sweepStaleBackups,
+  bucketSweepRoots,
+  DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS,
+} from '../../../src/sync/sync-bak-cleanup';
 
 // ──────────────────────────────────────────────────────────────────────────────
 // bucketSweepRoots()
@@ -11,7 +15,9 @@ describe('bucketSweepRoots()', () => {
   const root = '/project';
 
   it('returns the literal directory prefix for a simple glob', () => {
-    const result = bucketSweepRoots(root, { json: { include: ['locales/**/*.json'] } });
+    const result = bucketSweepRoots(root, {
+      json: { include: ['locales/**/*.json'] },
+    });
     expect(result).toEqual([path.resolve(root, 'locales')]);
   });
 
@@ -21,7 +27,9 @@ describe('bucketSweepRoots()', () => {
   });
 
   it('handles a trailing-slash prefix (directory glob)', () => {
-    const result = bucketSweepRoots(root, { json: { include: ['src/locales/'] } });
+    const result = bucketSweepRoots(root, {
+      json: { include: ['src/locales/'] },
+    });
     expect(result).toContain(path.resolve(root, 'src/locales'));
   });
 
@@ -44,12 +52,16 @@ describe('bucketSweepRoots()', () => {
   });
 
   it('handles a glob with a {brace} wildcard', () => {
-    const result = bucketSweepRoots(root, { json: { include: ['src/{en,de}/**/*.json'] } });
+    const result = bucketSweepRoots(root, {
+      json: { include: ['src/{en,de}/**/*.json'] },
+    });
     expect(result).toEqual([path.resolve(root, 'src')]);
   });
 
   it('handles a glob with a ? wildcard', () => {
-    const result = bucketSweepRoots(root, { json: { include: ['loc?les/**/*.json'] } });
+    const result = bucketSweepRoots(root, {
+      json: { include: ['loc?les/**/*.json'] },
+    });
     expect(result).toEqual([root]);
   });
 });
@@ -96,7 +108,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     expect(fs.existsSync(staleBak)).toBe(false);
 
     // No readdir call should have touched outsideDir
-    const readdirCalls: string[] = readdirSpy.mock.calls.map((c: unknown[]) => c[0] as string);
+    const readdirCalls: string[] = readdirSpy.mock.calls.map(
+      (c: unknown[]) => c[0] as string
+    );
     expect(readdirCalls.some((p) => p.startsWith(outsideDir))).toBe(false);
   });
 
@@ -109,7 +123,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     const tenMinAgo = new Date(Date.now() - 10 * 60_000);
     fs.utimesSync(staleBak, tenMinAgo, tenMinAgo);
 
-    await sweepStaleBackups(tmpDir, 5 * 60_000, { json: { include: ['locales/**/*.json'] } });
+    await sweepStaleBackups(tmpDir, 5 * 60_000, {
+      json: { include: ['locales/**/*.json'] },
+    });
     expect(fs.existsSync(staleBak)).toBe(false);
   });
 
@@ -120,7 +136,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     const freshBak = path.join(localesDir, 'en.json.deepl.bak');
     fs.writeFileSync(freshBak, 'fresh', 'utf-8');
 
-    await sweepStaleBackups(tmpDir, 5 * 60_000, { json: { include: ['locales/**/*.json'] } });
+    await sweepStaleBackups(tmpDir, 5 * 60_000, {
+      json: { include: ['locales/**/*.json'] },
+    });
     expect(fs.existsSync(freshBak)).toBe(true);
   });
 
@@ -134,7 +152,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     fs.utimesSync(userBak, tenMinAgo, tenMinAgo);
     const sibling = path.join(localesDir, 'my-important-notes');
 
-    await sweepStaleBackups(tmpDir, 5 * 60_000, { json: { include: ['locales/**/*.json'] } });
+    await sweepStaleBackups(tmpDir, 5 * 60_000, {
+      json: { include: ['locales/**/*.json'] },
+    });
 
     expect(fs.existsSync(userBak)).toBe(true);
     expect(fs.readFileSync(userBak, 'utf-8')).toBe('user data');
@@ -152,7 +172,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     fs.utimesSync(bakFile, tenMinAgo, tenMinAgo);
     // sibling does not exist
 
-    await sweepStaleBackups(tmpDir, 5 * 60_000, { json: { include: ['locales/**/*.json'] } });
+    await sweepStaleBackups(tmpDir, 5 * 60_000, {
+      json: { include: ['locales/**/*.json'] },
+    });
 
     expect(fs.existsSync(sibling)).toBe(false);
     expect(fs.existsSync(bakFile)).toBe(false);
@@ -169,7 +191,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     const tenMinAgo = new Date(Date.now() - 10 * 60_000);
     fs.utimesSync(bakFile, tenMinAgo, tenMinAgo);
 
-    await sweepStaleBackups(tmpDir, 5 * 60_000, { json: { include: ['locales/**/*.json'] } });
+    await sweepStaleBackups(tmpDir, 5 * 60_000, {
+      json: { include: ['locales/**/*.json'] },
+    });
 
     expect(fs.readFileSync(sibling, 'utf-8')).toBe('{"key":"value"}');
     expect(fs.existsSync(bakFile)).toBe(false);
@@ -186,7 +210,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     const tenMinAgo = new Date(Date.now() - 10 * 60_000);
     fs.utimesSync(bakFile, tenMinAgo, tenMinAgo);
 
-    await sweepStaleBackups(tmpDir, 5 * 60_000, { json: { include: ['locales/**/*.json'] } });
+    await sweepStaleBackups(tmpDir, 5 * 60_000, {
+      json: { include: ['locales/**/*.json'] },
+    });
 
     expect(fs.readFileSync(sibling, 'utf-8')).toBe('{"current":"content"}');
     expect(fs.existsSync(bakFile)).toBe(false);
@@ -203,7 +229,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     const buckets = { json: { include: ['locales/**/*.json'] } };
     await sweepStaleBackups(tmpDir, 5 * 60_000, buckets);
 
-    const readdirCalls: string[] = readdirSpy.mock.calls.map((c: unknown[]) => c[0] as string);
+    const readdirCalls: string[] = readdirSpy.mock.calls.map(
+      (c: unknown[]) => c[0] as string
+    );
     // Only locales (and any of its subdirs) should be visited — not the 5 other* dirs
     for (let i = 0; i < 5; i++) {
       expect(readdirCalls.some((p) => p.includes(`other${i}`))).toBe(false);
diff --git a/tests/unit/sync/sync-bucket-walker.test.ts b/tests/unit/sync/sync-bucket-walker.test.ts
index 1ac8fb35..7636ca11 100644
--- a/tests/unit/sync/sync-bucket-walker.test.ts
+++ b/tests/unit/sync/sync-bucket-walker.test.ts
@@ -1,4 +1,7 @@
-import { extractTranslatable, walkBuckets } from '../../../src/sync/sync-bucket-walker';
+import {
+  extractTranslatable,
+  walkBuckets,
+} from '../../../src/sync/sync-bucket-walker';
 import type { ExtractedEntry, FormatParser } from '../../../src/formats/index';
 import { FormatRegistry } from '../../../src/formats/index';
 import { JsonFormatParser } from '../../../src/formats/json';
@@ -25,7 +28,9 @@ const mockFg = fg as jest.MockedFunction<typeof fg>;
 const mockReadFile = fs.promises.readFile as jest.Mock;
 const mockStat = fs.promises.stat as jest.Mock;
 
-function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+function makeConfig(
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -83,7 +88,11 @@ describe('walkBuckets', () => {
       extensions: ['.json'],
       extract: () => [
         { key: 'a', value: 'Hello' },
-        { key: 'b', value: '{0}none|{1}one|[2,*]many', metadata: { skipped: { reason: 'pipe_pluralization' } } },
+        {
+          key: 'b',
+          value: '{0}none|{1}one|[2,*]many',
+          metadata: { skipped: { reason: 'pipe_pluralization' } },
+        },
         { key: 'c', value: 'Goodbye' },
       ],
       reconstruct: (content: string) => content,
@@ -101,7 +110,7 @@ describe('walkBuckets', () => {
 
     expect(mockFg).toHaveBeenCalledWith(
       ['locales/en.json'],
-      expect.objectContaining({ followSymbolicLinks: false }),
+      expect.objectContaining({ followSymbolicLinks: false })
     );
   });
 
@@ -120,7 +129,7 @@ describe('walkBuckets', () => {
     const emptyRegistry = new FormatRegistry();
 
     await expect(
-      collect(walkBuckets(config, emptyRegistry, { strictParser: true })),
+      collect(walkBuckets(config, emptyRegistry, { strictParser: true }))
     ).rejects.toBeInstanceOf(ValidationError);
   });
 
@@ -179,7 +188,9 @@ describe('walkBuckets', () => {
     });
 
     it('skips entire bucket when glob returns more files than sync.limits.max_source_files', async () => {
-      mockFg.mockResolvedValue(Array.from({ length: 10 }, (_, i) => `/test/locales/en/${i}.json`));
+      mockFg.mockResolvedValue(
+        Array.from({ length: 10 }, (_, i) => `/test/locales/en/${i}.json`)
+      );
 
       const config = makeConfig({
         sync: {
@@ -216,10 +227,11 @@ describe('walkBuckets', () => {
       mockFg.mockResolvedValue(['/test/lang/en.php'] as never);
       mockStat.mockResolvedValue({ size: 200 });
       mockReadFile.mockResolvedValue(
-        `<?php return ['a' => ['b' => ['c' => ['d' => 'too deep']]]];`,
+        `<?php return ['a' => ['b' => ['c' => ['d' => 'too deep']]]];`
       );
 
-      const { PhpArraysFormatParser } = await import('../../../src/formats/php-arrays');
+      const { PhpArraysFormatParser } =
+        await import('../../../src/formats/php-arrays');
       const registry = new FormatRegistry();
       registry.register(new PhpArraysFormatParser());
 
@@ -241,7 +253,7 @@ describe('walkBuckets', () => {
 describe('extractTranslatable', () => {
   function makeParser(
     entries: ExtractedEntry[],
-    opts: { multiLocale?: boolean } = {},
+    opts: { multiLocale?: boolean } = {}
   ): FormatParser {
     return {
       multiLocale: opts.multiLocale,
@@ -254,7 +266,11 @@ describe('extractTranslatable', () => {
   it('drops entries tagged with metadata.skipped from the returned list', () => {
     const parser = makeParser([
       { key: 'greeting', value: 'Hello' },
-      { key: 'plural', value: '|{n} item', metadata: { skipped: 'pipe_pluralization' } },
+      {
+        key: 'plural',
+        value: '|{n} item',
+        metadata: { skipped: 'pipe_pluralization' },
+      },
       { key: 'farewell', value: 'Goodbye' },
     ]);
     const result = extractTranslatable(parser, '<content>');
diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index 60f7d3a5..bb097e4e 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -1,5 +1,9 @@
 import { SyncCommand } from '../../../src/cli/commands/sync-command';
-import type { SyncService, SyncResult, SyncFileResult } from '../../../src/sync/sync-service';
+import type {
+  SyncService,
+  SyncResult,
+  SyncFileResult,
+} from '../../../src/sync/sync-service';
 import { Logger } from '../../../src/utils/logger';
 
 const mockExecFile = jest.fn(
@@ -7,13 +11,20 @@ const mockExecFile = jest.fn(
     _cmd: string,
     _args: string[],
     _optsOrCb?: unknown,
-    cbArg?: (err: Error | null, result: { stdout: string; stderr: string }) => void,
+    cbArg?: (
+      err: Error | null,
+      result: { stdout: string; stderr: string }
+    ) => void
   ) => {
-    const cb = typeof _optsOrCb === 'function'
-      ? (_optsOrCb as (err: Error | null, result: { stdout: string; stderr: string }) => void)
-      : cbArg;
+    const cb =
+      typeof _optsOrCb === 'function'
+        ? (_optsOrCb as (
+            err: Error | null,
+            result: { stdout: string; stderr: string }
+          ) => void)
+        : cbArg;
     if (cb) cb(null, { stdout: '', stderr: '' });
-  },
+  }
 );
 
 jest.mock('child_process', () => ({
@@ -49,7 +60,8 @@ jest.mock('../../../src/sync/sync-config', () => ({
   loadSyncConfig: jest.fn(),
 }));
 
-const { loadSyncConfig: mockLoadSyncConfig } = require('../../../src/sync/sync-config') as { loadSyncConfig: jest.Mock };
+const { loadSyncConfig: mockLoadSyncConfig } =
+  require('../../../src/sync/sync-config') as { loadSyncConfig: jest.Mock };
 
 const defaultSyncConfig = {
   version: 1,
@@ -98,7 +110,9 @@ describe('SyncCommand', () => {
     mockLoadSyncConfig.mockResolvedValue({ ...defaultSyncConfig });
     logInfoSpy = jest.spyOn(Logger, 'info').mockImplementation(() => {});
     logWarnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
-    stdoutWriteSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    stdoutWriteSpy = jest
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
   });
 
   afterEach(() => {
@@ -115,7 +129,9 @@ describe('SyncCommand', () => {
 
       await command.run({ dryRun: true });
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(infoOutput.toLowerCase()).toContain('dry-run');
     });
 
@@ -126,7 +142,9 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(infoOutput.toLowerCase()).toContain('drift');
     });
 
@@ -143,8 +161,12 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
-      expect(infoOutput).toContain('Sync drift detected: 5 new, 2 deleted keys.');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
+      expect(infoOutput).toContain(
+        'Sync drift detected: 5 new, 2 deleted keys.'
+      );
     });
 
     it('should only mention nonzero categories in drift message', async () => {
@@ -160,14 +182,16 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('Sync drift detected: 3 deleted keys.');
       expect(infoOutput).not.toMatch(/\bnew\b/);
       expect(infoOutput).not.toMatch(/\bstale\b/);
     });
 
     it('should output valid JSON to stdout when format is json', async () => {
-        expect.assertions(4);
+      expect.assertions(4);
       const result = makeResult();
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
@@ -183,7 +207,10 @@ describe('SyncCommand', () => {
         }
       });
       expect(jsonCall).toBeDefined();
-      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<string, unknown>;
+      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<
+        string,
+        unknown
+      >;
       expect(parsed).toHaveProperty('ok');
       expect(parsed).toHaveProperty('totalKeys');
       expect(parsed).not.toHaveProperty('success');
@@ -196,7 +223,9 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('500,000 chars');
       expect(infoOutput).toMatch(/~?\$\d+\.\d+/);
     });
@@ -208,18 +237,26 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('Pro tier estimate');
     });
 
     it('should append Pro tier disclaimer to dry-run estimated cost in text mode', async () => {
-      const result = makeResult({ dryRun: true, estimatedCharacters: 300_000, totalCharactersBilled: 0 });
+      const result = makeResult({
+        dryRun: true,
+        estimatedCharacters: 300_000,
+        totalCharactersBilled: 0,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ dryRun: true });
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('Pro tier estimate');
     });
 
@@ -231,9 +268,17 @@ describe('SyncCommand', () => {
       await command.run({ format: 'json' });
 
       const jsonCall = stdoutWriteSpy.mock.calls.find((c: unknown[]) => {
-        try { JSON.parse(String(c[0]).trim()); return true; } catch { return false; }
+        try {
+          JSON.parse(String(c[0]).trim());
+          return true;
+        } catch {
+          return false;
+        }
       });
-      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<string, unknown>;
+      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<
+        string,
+        unknown
+      >;
       expect(parsed['estimatedCost']).toBe('~$25.00');
     });
 
@@ -245,9 +290,17 @@ describe('SyncCommand', () => {
       await command.run({ format: 'json' });
 
       const jsonCall = stdoutWriteSpy.mock.calls.find((c: unknown[]) => {
-        try { JSON.parse(String(c[0]).trim()); return true; } catch { return false; }
+        try {
+          JSON.parse(String(c[0]).trim());
+          return true;
+        } catch {
+          return false;
+        }
       });
-      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<string, unknown>;
+      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<
+        string,
+        unknown
+      >;
       expect(parsed['rateAssumption']).toBe('pro');
     });
 
@@ -259,10 +312,20 @@ describe('SyncCommand', () => {
       await command.run({ format: 'json' });
 
       const jsonCall = stdoutWriteSpy.mock.calls.find((c: unknown[]) => {
-        try { JSON.parse(String(c[0]).trim()); return true; } catch { return false; }
+        try {
+          JSON.parse(String(c[0]).trim());
+          return true;
+        } catch {
+          return false;
+        }
       });
-      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<string, unknown>;
-      expect(String(parsed['estimatedCost'])).not.toContain('Pro tier estimate');
+      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<
+        string,
+        unknown
+      >;
+      expect(String(parsed['estimatedCost'])).not.toContain(
+        'Pro tier estimate'
+      );
     });
 
     it('should display validation warnings when present', async () => {
@@ -272,7 +335,9 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const warnOutput = logWarnSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const warnOutput = logWarnSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(warnOutput).toContain('3');
       expect(warnOutput.toLowerCase()).toContain('warning');
     });
@@ -284,7 +349,9 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const warnOutput = logWarnSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const warnOutput = logWarnSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(warnOutput).toContain('5');
       expect(warnOutput.toLowerCase()).toContain('error');
     });
@@ -304,8 +371,16 @@ describe('SyncCommand', () => {
     });
 
     it('should behave identically to --frozen', async () => {
-      const resultFrozen = makeResult({ frozen: true, driftDetected: true, success: false });
-      const resultCi = makeResult({ frozen: true, driftDetected: true, success: false });
+      const resultFrozen = makeResult({
+        frozen: true,
+        driftDetected: true,
+        success: false,
+      });
+      const resultCi = makeResult({
+        frozen: true,
+        driftDetected: true,
+        success: false,
+      });
 
       const mockServiceFrozen = createMockSyncService(resultFrozen);
       const mockServiceCi = createMockSyncService(resultCi);
@@ -330,19 +405,28 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(infoOutput).not.toContain('$');
       expect(infoOutput).not.toContain('chars');
     });
 
     it('should show all key categories in summary', async () => {
-      const result = makeResult({ newKeys: 3, staleKeys: 2, currentKeys: 10, deletedKeys: 1 });
+      const result = makeResult({
+        newKeys: 3,
+        staleKeys: 2,
+        currentKeys: 10,
+        deletedKeys: 1,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map(c => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('3 new');
       expect(infoOutput).toContain('2 updated');
       expect(infoOutput).toContain('10 current');
@@ -364,62 +448,102 @@ describe('SyncCommand', () => {
 
   describe('dry-run estimation display', () => {
     it('should display estimated characters and cost in dry-run', async () => {
-      const result = makeResult({ dryRun: true, totalCharactersBilled: 0, estimatedCharacters: 4500, targetLocaleCount: 5 });
+      const result = makeResult({
+        dryRun: true,
+        totalCharactersBilled: 0,
+        estimatedCharacters: 4500,
+        targetLocaleCount: 5,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ dryRun: true });
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('~4,500 chars');
       expect(infoOutput).toMatch(/~?\$\d+\.\d+/);
     });
 
     it('should not display estimation line when estimatedCharacters is 0', async () => {
-      const result = makeResult({ dryRun: true, totalCharactersBilled: 0, estimatedCharacters: 0 });
+      const result = makeResult({
+        dryRun: true,
+        totalCharactersBilled: 0,
+        estimatedCharacters: 0,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ dryRun: true });
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).not.toContain('This sync');
     });
 
     it('should show locale count in dry-run summary', async () => {
-      const result = makeResult({ dryRun: true, totalCharactersBilled: 0, estimatedCharacters: 1000, targetLocaleCount: 3 });
+      const result = makeResult({
+        dryRun: true,
+        totalCharactersBilled: 0,
+        estimatedCharacters: 1000,
+        targetLocaleCount: 3,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ dryRun: true });
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('across 3 languages');
     });
 
     it('should use singular "language" when targetLocaleCount is 1', async () => {
-      const result = makeResult({ dryRun: true, totalCharactersBilled: 0, estimatedCharacters: 100, targetLocaleCount: 1 });
+      const result = makeResult({
+        dryRun: true,
+        totalCharactersBilled: 0,
+        estimatedCharacters: 100,
+        targetLocaleCount: 1,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ dryRun: true });
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('across 1 language');
       expect(infoOutput).not.toContain('languages');
     });
 
     it('should include estimatedCharacters in JSON dry-run output', async () => {
-      const result = makeResult({ dryRun: true, totalCharactersBilled: 0, estimatedCharacters: 4500, targetLocaleCount: 5 });
+      const result = makeResult({
+        dryRun: true,
+        totalCharactersBilled: 0,
+        estimatedCharacters: 4500,
+        targetLocaleCount: 5,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ dryRun: true, format: 'json' });
 
       const jsonCall = stdoutWriteSpy.mock.calls.find((c: unknown[]) => {
-        try { JSON.parse(String(c[0]).trim()); return true; } catch { return false; }
+        try {
+          JSON.parse(String(c[0]).trim());
+          return true;
+        } catch {
+          return false;
+        }
       });
-      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<string, unknown>;
+      const parsed = JSON.parse(String(jsonCall![0]).trim()) as Record<
+        string,
+        unknown
+      >;
       expect(parsed['estimatedCharacters']).toBe(4500);
       expect(parsed['estimatedCost']).toBe('~$0.11');
     });
@@ -430,8 +554,13 @@ describe('SyncCommand', () => {
     // `locale-complete` events; there is no aggregated post-sync summary.
     // These tests exercise onProgress directly to verify the live tick format.
     function mockServiceWithProgress(
-      events: Array<{ locale: string; file: string; translated: number; failed: number }>,
-      result: SyncResult,
+      events: Array<{
+        locale: string;
+        file: string;
+        translated: number;
+        failed: number;
+      }>,
+      result: SyncResult
     ): jest.Mocked<SyncService> {
       return {
         sync: jest.fn().mockImplementation(async (_config, options) => {
@@ -445,59 +574,100 @@ describe('SyncCommand', () => {
 
     it('emits per-locale tick for each completed file', async () => {
       const fileResults: SyncFileResult[] = [
-        { file: 'locales/de.json', locale: 'de', translated: 10, skipped: 0, failed: 0, written: true },
-        { file: 'locales/fr.json', locale: 'fr', translated: 10, skipped: 0, failed: 0, written: true },
+        {
+          file: 'locales/de.json',
+          locale: 'de',
+          translated: 10,
+          skipped: 0,
+          failed: 0,
+          written: true,
+        },
+        {
+          file: 'locales/fr.json',
+          locale: 'fr',
+          translated: 10,
+          skipped: 0,
+          failed: 0,
+          written: true,
+        },
       ];
       const mockService = mockServiceWithProgress(
         [
           { locale: 'de', file: 'locales/de.json', translated: 10, failed: 0 },
           { locale: 'fr', file: 'locales/fr.json', translated: 10, failed: 0 },
         ],
-        makeResult({ fileResults }),
+        makeResult({ fileResults })
       );
       const command = new SyncCommand(mockService);
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('\u2713 de: 10/10');
       expect(infoOutput).toContain('\u2713 fr: 10/10');
     });
 
     it('emits a tick per file for multiple files in the same locale', async () => {
       const fileResults: SyncFileResult[] = [
-        { file: 'locales/de.json', locale: 'de', translated: 5, skipped: 0, failed: 0, written: true },
-        { file: 'messages/de.json', locale: 'de', translated: 3, skipped: 0, failed: 0, written: true },
+        {
+          file: 'locales/de.json',
+          locale: 'de',
+          translated: 5,
+          skipped: 0,
+          failed: 0,
+          written: true,
+        },
+        {
+          file: 'messages/de.json',
+          locale: 'de',
+          translated: 3,
+          skipped: 0,
+          failed: 0,
+          written: true,
+        },
       ];
       const mockService = mockServiceWithProgress(
         [
           { locale: 'de', file: 'locales/de.json', translated: 5, failed: 0 },
           { locale: 'de', file: 'messages/de.json', translated: 3, failed: 0 },
         ],
-        makeResult({ fileResults }),
+        makeResult({ fileResults })
       );
       const command = new SyncCommand(mockService);
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('\u2713 de: 5/5 keys (locales/de.json)');
       expect(infoOutput).toContain('\u2713 de: 3/3 keys (messages/de.json)');
     });
 
     it('shows failure indicator when a locale has failures', async () => {
       const fileResults: SyncFileResult[] = [
-        { file: 'locales/de.json', locale: 'de', translated: 8, skipped: 0, failed: 2, written: true },
+        {
+          file: 'locales/de.json',
+          locale: 'de',
+          translated: 8,
+          skipped: 0,
+          failed: 2,
+          written: true,
+        },
       ];
       const mockService = mockServiceWithProgress(
         [{ locale: 'de', file: 'locales/de.json', translated: 8, failed: 2 }],
-        makeResult({ fileResults }),
+        makeResult({ fileResults })
       );
       const command = new SyncCommand(mockService);
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('\u2717 de: 8/10');
     });
 
@@ -508,7 +678,9 @@ describe('SyncCommand', () => {
 
       await command.run({ dryRun: true });
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).not.toMatch(/[✓✗]/);
       expect(infoOutput).not.toMatch(/\d+\/\d+/);
     });
@@ -520,7 +692,9 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).not.toMatch(/\d+\/\d+/);
     });
 
@@ -552,7 +726,9 @@ describe('SyncCommand', () => {
 
       await command.run({});
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       const tickMatches = infoOutput.match(/\u2713 de:/g) ?? [];
       expect(tickMatches).toHaveLength(1);
     });
@@ -597,13 +773,24 @@ describe('SyncCommand', () => {
           _cmd: string,
           args: string[],
           optsOrCb?: unknown,
-          cbArg?: (err: Error | null, result: { stdout: string; stderr: string }) => void,
+          cbArg?: (
+            err: Error | null,
+            result: { stdout: string; stderr: string }
+          ) => void
         ) => {
-          const cb = typeof optsOrCb === 'function'
-            ? (optsOrCb as (err: Error | null, result: { stdout: string; stderr: string }) => void)
-            : cbArg;
+          const cb =
+            typeof optsOrCb === 'function'
+              ? (optsOrCb as (
+                  err: Error | null,
+                  result: { stdout: string; stderr: string }
+                ) => void)
+              : cbArg;
           let stdout = '';
-          if (Array.isArray(args) && args[0] === 'rev-parse' && args[1] === '--git-dir') {
+          if (
+            Array.isArray(args) &&
+            args[0] === 'rev-parse' &&
+            args[1] === '--git-dir'
+          ) {
             stdout = '.git';
           }
           // Staging follows the dirty set, so a scenario that writes files must
@@ -612,7 +799,7 @@ describe('SyncCommand', () => {
             stdout = mockPorcelain;
           }
           if (cb) cb(null, { stdout, stderr: '' });
-        },
+        }
       );
       // Clean by default; tests expecting a commit declare their own dirt.
       mockPorcelain = '';
@@ -643,8 +830,12 @@ describe('SyncCommand', () => {
       expect(gitCalls).toContainEqual(
         expect.arrayContaining([
           'git',
-          expect.arrayContaining(['commit', '-m', expect.stringContaining('de')]),
-        ]),
+          expect.arrayContaining([
+            'commit',
+            '-m',
+            expect.stringContaining('de'),
+          ]),
+        ])
       );
     });
 
@@ -669,14 +860,17 @@ describe('SyncCommand', () => {
 
     it('should pass cwd=config.projectRoot to every git invocation', async () => {
       mockPorcelain = ' M locales/de.json\0 M .deepl-sync.lock\0';
-      const result = makeResult({ fileResults: [writtenFile], lockUpdated: true });
+      const result = makeResult({
+        fileResults: [writtenFile],
+        lockUpdated: true,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ autoCommit: true });
 
       const gitInvocations = mockExecFile.mock.calls.filter(
-        (c: unknown[]) => c[0] === 'git',
+        (c: unknown[]) => c[0] === 'git'
       );
       expect(gitInvocations.length).toBeGreaterThan(0);
       for (const call of gitInvocations) {
@@ -687,7 +881,8 @@ describe('SyncCommand', () => {
     });
 
     it('should stage multiple written files and include all locales in commit message', async () => {
-      mockPorcelain = ' M locales/de.json\0 M locales/fr.json\0 M .deepl-sync.lock\0';
+      mockPorcelain =
+        ' M locales/de.json\0 M locales/fr.json\0 M .deepl-sync.lock\0';
       const writtenFileFr: SyncFileResult = {
         file: 'locales/fr.json',
         locale: 'fr',
@@ -713,10 +908,11 @@ describe('SyncCommand', () => {
       expect(gitCalls).toContainEqual(['git', ['add', '.deepl-sync.lock']]);
 
       const commitCall = calls.find(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('commit'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
       );
       expect(commitCall).toBeDefined();
-      const commitMsg = (commitCall![1])[2];
+      const commitMsg = commitCall![1][2];
       expect(commitMsg).toContain('de');
       expect(commitMsg).toContain('fr');
     });
@@ -727,17 +923,25 @@ describe('SyncCommand', () => {
           _cmd: string,
           args: string[],
           optsOrCb?: unknown,
-          cbArg?: (err: Error | null, result: { stdout: string; stderr: string }) => void,
+          cbArg?: (
+            err: Error | null,
+            result: { stdout: string; stderr: string }
+          ) => void
         ) => {
-          const cb = typeof optsOrCb === 'function'
-            ? (optsOrCb as (err: Error | null, result: { stdout: string; stderr: string }) => void)
-            : cbArg;
+          const cb =
+            typeof optsOrCb === 'function'
+              ? (optsOrCb as (
+                  err: Error | null,
+                  result: { stdout: string; stderr: string }
+                ) => void)
+              : cbArg;
           if (Array.isArray(args) && args.includes('rev-parse')) {
-            if (cb) cb(new Error('not a git repository'), { stdout: '', stderr: '' });
+            if (cb)
+              cb(new Error('not a git repository'), { stdout: '', stderr: '' });
           } else {
             if (cb) cb(null, { stdout: '', stderr: '' });
           }
-        },
+        }
       );
 
       const result = makeResult({ fileResults: [writtenFile] });
@@ -746,11 +950,14 @@ describe('SyncCommand', () => {
 
       await command.run({ autoCommit: true });
 
-      const warnOutput = logWarnSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const warnOutput = logWarnSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(warnOutput).toContain('Not a git repository');
 
       const addCalls = mockExecFile.mock.calls.filter(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('add'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('add')
       );
       expect(addCalls).toHaveLength(0);
     });
@@ -764,10 +971,12 @@ describe('SyncCommand', () => {
 
       const calls = mockExecFile.mock.calls;
       const addCalls = calls.filter(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('add'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('add')
       );
       const commitCalls = calls.filter(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('commit'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
       );
       expect(addCalls).toHaveLength(0);
       expect(commitCalls).toHaveLength(0);
@@ -799,33 +1008,43 @@ describe('SyncCommand', () => {
       await command.run({ autoCommit: true, dryRun: true });
 
       const addCalls = mockExecFile.mock.calls.filter(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('add'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('add')
       );
       expect(addCalls).toHaveLength(0);
     });
 
     it('should not call git when driftDetected is true', async () => {
-      const result = makeResult({ driftDetected: true, fileResults: [writtenFile] });
+      const result = makeResult({
+        driftDetected: true,
+        fileResults: [writtenFile],
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ autoCommit: true });
 
       const addCalls = mockExecFile.mock.calls.filter(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('add'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('add')
       );
       expect(addCalls).toHaveLength(0);
     });
 
     it('should log success message after committing', async () => {
       mockPorcelain = ' M locales/de.json\0 M .deepl-sync.lock\0';
-      const result = makeResult({ fileResults: [writtenFile], lockUpdated: true });
+      const result = makeResult({
+        fileResults: [writtenFile],
+        lockUpdated: true,
+      });
       const mockService = createMockSyncService(result);
       const command = new SyncCommand(mockService);
 
       await command.run({ autoCommit: true });
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('Auto-committed');
       expect(infoOutput).toContain('2 file(s)');
     });
@@ -893,7 +1112,7 @@ describe('SyncCommand', () => {
             `watchAndSync setup did not attach watcher listeners within ${SETUP_READY_MAX_ROUNDS} ` +
               `flush rounds (chokidar.watch calls: ${mockWatch.mock.calls.length}). Either setup ` +
               `is genuinely hung, or this test exercises the early-return path where no watcher ` +
-              `is created and should not call flushWatchSetup.`,
+              `is created and should not call flushWatchSetup.`
           );
         }
         await flushRound();
@@ -911,7 +1130,10 @@ describe('SyncCommand', () => {
       const command = new SyncCommand(mockService);
 
       const sigintListeners: Array<() => void> = [];
-      const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((event: string, listener: () => void) => {
+      const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((
+        event: string,
+        listener: () => void
+      ) => {
         if (event === 'SIGINT') {
           sigintListeners.push(listener);
         }
@@ -948,7 +1170,9 @@ describe('SyncCommand', () => {
 
       await command.run({ watch: true });
 
-      const warnOutput = logWarnSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const warnOutput = logWarnSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(warnOutput).toContain('No source files to watch');
       expect(mockWatch).not.toHaveBeenCalled();
     });
@@ -960,13 +1184,24 @@ describe('SyncCommand', () => {
           _cmd: string,
           args: string[],
           optsOrCb?: unknown,
-          cbArg?: (err: Error | null, result: { stdout: string; stderr: string }) => void,
+          cbArg?: (
+            err: Error | null,
+            result: { stdout: string; stderr: string }
+          ) => void
         ) => {
-          const cb = typeof optsOrCb === 'function'
-            ? (optsOrCb as (err: Error | null, result: { stdout: string; stderr: string }) => void)
-            : cbArg;
+          const cb =
+            typeof optsOrCb === 'function'
+              ? (optsOrCb as (
+                  err: Error | null,
+                  result: { stdout: string; stderr: string }
+                ) => void)
+              : cbArg;
           let stdout = '';
-          if (Array.isArray(args) && args[0] === 'rev-parse' && args[1] === '--git-dir') {
+          if (
+            Array.isArray(args) &&
+            args[0] === 'rev-parse' &&
+            args[1] === '--git-dir'
+          ) {
             stdout = '.git';
           }
           // Staging follows the dirty set, so a scenario that writes files must
@@ -975,7 +1210,7 @@ describe('SyncCommand', () => {
             stdout = mockPorcelain;
           }
           if (cb) cb(null, { stdout, stderr: '' });
-        },
+        }
       );
       mockExistsSync.mockReset();
       mockExistsSync.mockImplementation((p: string | URL) => {
@@ -985,17 +1220,26 @@ describe('SyncCommand', () => {
       // Capture the debounced 'change'/'add' handlers installed by
       // attachDebouncedWatchLoop so we can drive watch cycles deterministically.
       const registeredHandlers: Array<(p?: string) => void> = [];
-      mockWatcherOn.mockImplementation((event: string, handler: (p?: string) => void) => {
-        if (event === 'change' || event === 'add') {
-          registeredHandlers.push(handler);
+      mockWatcherOn.mockImplementation(
+        (event: string, handler: (p?: string) => void) => {
+          if (event === 'change' || event === 'add') {
+            registeredHandlers.push(handler);
+          }
+          return mockWatcher;
         }
-        return mockWatcher;
-      });
+      );
 
       mockPorcelain = ' M locales/de.json\0 M .deepl-sync.lock\0';
       const result = makeResult({
         fileResults: [
-          { file: 'locales/de.json', locale: 'de', translated: 5, skipped: 0, failed: 0, written: true },
+          {
+            file: 'locales/de.json',
+            locale: 'de',
+            translated: 5,
+            skipped: 0,
+            failed: 0,
+            written: true,
+          },
         ],
         lockUpdated: true,
       });
@@ -1003,18 +1247,26 @@ describe('SyncCommand', () => {
       const command = new SyncCommand(mockService);
 
       const sigintListeners: Array<() => void> = [];
-      const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((event: string, listener: () => void) => {
+      const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((
+        event: string,
+        listener: () => void
+      ) => {
         if (event === 'SIGINT') sigintListeners.push(listener);
         return process;
       }) as unknown as ProcessOn);
 
-      const runPromise = command.run({ watch: true, debounce: 50, autoCommit: true });
+      const runPromise = command.run({
+        watch: true,
+        debounce: 50,
+        autoCommit: true,
+      });
 
       await flushWatchSetup();
 
       // Baseline: the pre-watch initial sync should already have committed once.
       const commitsBefore = mockExecFile.mock.calls.filter(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('commit'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
       ).length;
       expect(commitsBefore).toBeGreaterThanOrEqual(1);
 
@@ -1027,7 +1279,8 @@ describe('SyncCommand', () => {
       await flushWatchSetup();
 
       const commitsAfterFirstCycle = mockExecFile.mock.calls.filter(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('commit'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
       ).length;
       expect(commitsAfterFirstCycle).toBe(commitsBefore + 1);
 
@@ -1037,7 +1290,8 @@ describe('SyncCommand', () => {
       await flushWatchSetup();
 
       const commitsAfterSecondCycle = mockExecFile.mock.calls.filter(
-        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[]).includes('commit'),
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
       ).length;
       expect(commitsAfterSecondCycle).toBe(commitsBefore + 2);
 
@@ -1064,7 +1318,11 @@ describe('SyncCommand', () => {
       // can precede the process.on('SIGINT', ...) call. Retry with a hard
       // ceiling so a missing listener fails loudly rather than as
       // "Expected: 1, Received: 0".
-      for (let i = 0; i < 10 && process.listenerCount('SIGINT') === sigintBaseline; i++) {
+      for (
+        let i = 0;
+        i < 10 && process.listenerCount('SIGINT') === sigintBaseline;
+        i++
+      ) {
         await flushWatchSetup();
       }
       expect(process.listenerCount('SIGINT')).toBe(sigintBaseline + 1);
@@ -1079,7 +1337,11 @@ describe('SyncCommand', () => {
       // Second invocation should also add exactly one listener, then remove it.
       const secondRun = command.run({ watch: true, debounce: 50 });
       await flushWatchSetup();
-      for (let i = 0; i < 10 && process.listenerCount('SIGINT') === sigintBaseline; i++) {
+      for (
+        let i = 0;
+        i < 10 && process.listenerCount('SIGINT') === sigintBaseline;
+        i++
+      ) {
         await flushWatchSetup();
       }
       expect(process.listenerCount('SIGINT')).toBe(sigintBaseline + 1);
@@ -1098,7 +1360,10 @@ describe('SyncCommand', () => {
       const command = new SyncCommand(mockService);
 
       const sigintListeners: Array<() => void> = [];
-      const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((event: string, listener: () => void) => {
+      const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((
+        event: string,
+        listener: () => void
+      ) => {
         if (event === 'SIGINT') {
           sigintListeners.push(listener);
         }
@@ -1117,7 +1382,9 @@ describe('SyncCommand', () => {
 
       processOnSpy.mockRestore();
 
-      const infoOutput = logInfoSpy.mock.calls.map((c: unknown[]) => String(c[0])).join('\n');
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c: unknown[]) => String(c[0]))
+        .join('\n');
       expect(infoOutput).toContain('Watching');
       expect(infoOutput).toContain('pattern(s)');
     });
@@ -1129,10 +1396,12 @@ describe('SyncCommand', () => {
     describe('config cache across watch ticks', () => {
       function captureChangeHandlers(): Array<(p?: string) => void> {
         const handlers: Array<(p?: string) => void> = [];
-        mockWatcherOn.mockImplementation((event: string, handler: (p?: string) => void) => {
-          if (event === 'change' || event === 'add') handlers.push(handler);
-          return mockWatcher;
-        });
+        mockWatcherOn.mockImplementation(
+          (event: string, handler: (p?: string) => void) => {
+            if (event === 'change' || event === 'add') handlers.push(handler);
+            return mockWatcher;
+          }
+        );
         return handlers;
       }
 
@@ -1144,7 +1413,10 @@ describe('SyncCommand', () => {
         const handlers = captureChangeHandlers();
 
         const sigintListeners: Array<() => void> = [];
-        const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((event: string, listener: () => void) => {
+        const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((
+          event: string,
+          listener: () => void
+        ) => {
           if (event === 'SIGINT') sigintListeners.push(listener);
           return process;
         }) as unknown as ProcessOn);
@@ -1186,7 +1458,10 @@ describe('SyncCommand', () => {
         const handlers = captureChangeHandlers();
 
         const signalListeners: Record<string, Array<() => void>> = {};
-        const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((event: string, listener: () => void) => {
+        const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((
+          event: string,
+          listener: () => void
+        ) => {
           (signalListeners[event] ??= []).push(listener);
           return process;
         }) as unknown as ProcessOn);
@@ -1232,7 +1507,10 @@ describe('SyncCommand', () => {
         const handlers = captureChangeHandlers();
 
         const sigintListeners: Array<() => void> = [];
-        const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((event: string, listener: () => void) => {
+        const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((
+          event: string,
+          listener: () => void
+        ) => {
           if (event === 'SIGINT') sigintListeners.push(listener);
           return process;
         }) as unknown as ProcessOn);
@@ -1268,7 +1546,10 @@ describe('SyncCommand', () => {
         captureChangeHandlers();
 
         const sigintListeners: Array<() => void> = [];
-        const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((event: string, listener: () => void) => {
+        const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((
+          event: string,
+          listener: () => void
+        ) => {
           if (event === 'SIGINT') sigintListeners.push(listener);
           return process;
         }) as unknown as ProcessOn);
diff --git a/tests/unit/sync/sync-config-include-containment.test.ts b/tests/unit/sync/sync-config-include-containment.test.ts
index cacc536c..3143b17d 100644
--- a/tests/unit/sync/sync-config-include-containment.test.ts
+++ b/tests/unit/sync/sync-config-include-containment.test.ts
@@ -16,7 +16,9 @@ function configWithInclude(include: string[]): Record<string, unknown> {
     version: 1,
     source_locale: 'en',
     target_locales: ['de'],
-    buckets: { json: { include, target_path_pattern: 'locales/{locale}.json' } },
+    buckets: {
+      json: { include, target_path_pattern: 'locales/{locale}.json' },
+    },
   };
 }
 
@@ -32,14 +34,16 @@ describe('bucket include containment', () => {
 
   it('should reject a traversing entry even when other entries are fine', () => {
     expect(() =>
-      validateSyncConfig(configWithInclude(['locales/en.json', '../../etc/*.json'])),
+      validateSyncConfig(
+        configWithInclude(['locales/en.json', '../../etc/*.json'])
+      )
     ).toThrow();
   });
 
   it('should name the offending bucket and glob in the error', () => {
-    expect(() => validateSyncConfig(configWithInclude(['../evil/*.json']))).toThrow(
-      /include/i,
-    );
+    expect(() =>
+      validateSyncConfig(configWithInclude(['../evil/*.json']))
+    ).toThrow(/include/i);
   });
 
   it.each([
@@ -55,7 +59,7 @@ describe('bucket include containment', () => {
 
   it('should still reject a non-string include entry', () => {
     expect(() =>
-      validateSyncConfig(configWithInclude([42 as unknown as string])),
+      validateSyncConfig(configWithInclude([42 as unknown as string]))
     ).toThrow();
   });
 
diff --git a/tests/unit/sync/sync-config.test.ts b/tests/unit/sync/sync-config.test.ts
index b1b8cf23..462acc78 100644
--- a/tests/unit/sync/sync-config.test.ts
+++ b/tests/unit/sync/sync-config.test.ts
@@ -117,7 +117,9 @@ describe('sync-config', () => {
 
     it('should throw when raw is not an object', () => {
       expect(() => validateSyncConfig('not-an-object')).toThrow(ConfigError);
-      expect(() => validateSyncConfig('not-an-object')).toThrow('must be a YAML object');
+      expect(() => validateSyncConfig('not-an-object')).toThrow(
+        'must be a YAML object'
+      );
     });
 
     it('should throw when raw is null', () => {
@@ -129,138 +131,178 @@ describe('sync-config', () => {
     });
 
     it('should throw when version is missing', () => {
-      expect(() => validateSyncConfig({
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('missing required field: version');
+      expect(() =>
+        validateSyncConfig({
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('missing required field: version');
     });
 
     it('should throw when version is not 1', () => {
-      expect(() => validateSyncConfig({
-        version: 2,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('Unsupported sync config version: 2');
+      expect(() =>
+        validateSyncConfig({
+          version: 2,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('Unsupported sync config version: 2');
     });
 
     it('should throw when source_locale is missing', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('missing required field: source_locale');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('missing required field: source_locale');
     });
 
     it('should throw when source_locale is empty string', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: '  ',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('missing required field: source_locale');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: '  ',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('missing required field: source_locale');
     });
 
     it('should reject source_locale containing path traversal', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: '../evil',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('Invalid source locale "../evil"');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: '../evil',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('Invalid source locale "../evil"');
     });
 
     it('should reject source_locale containing forward slash', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en/US',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('Invalid source locale "en/US"');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en/US',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('Invalid source locale "en/US"');
     });
 
     it('should reject source_locale containing backslash', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en\\US',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('Invalid source locale "en\\US"');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en\\US',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('Invalid source locale "en\\US"');
     });
 
     it('should reject target_locales containing path traversal', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['../../tmp/evil'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('Invalid target locale "../../tmp/evil"');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['../../tmp/evil'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('Invalid target locale "../../tmp/evil"');
     });
 
     it('should reject target_locales with ../../etc/passwd traversal', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['../../etc/passwd'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow(ConfigError);
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['../../etc/passwd'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow(/path separators/);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['../../etc/passwd'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['../../etc/passwd'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow(/path separators/);
     });
 
     it('should reject target_locales with en/../../tmp traversal', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['en/../../tmp'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow(ConfigError);
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['en/../../tmp'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow(/path separators/);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['en/../../tmp'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['en/../../tmp'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow(/path separators/);
     });
 
     it('should reject source_locale with ../evil traversal', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: '../evil',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow(ConfigError);
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: '../evil',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow(/path separators/);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: '../evil',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: '../evil',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow(/path separators/);
     });
 
     it('should reject target locales that are not BCP-47 style codes', () => {
-      for (const bad of ['de_DE', 'de.json', 'de de', 'x', '.git', 'de!', 'verylonglocale-code-way-too-long']) {
-        expect(() => validateSyncConfig({
-          version: 1,
-          source_locale: 'en',
-          target_locales: [bad],
-          buckets: { json: { include: ['a.json'] } },
-        })).toThrow(ConfigError);
+      for (const bad of [
+        'de_DE',
+        'de.json',
+        'de de',
+        'x',
+        '.git',
+        'de!',
+        'verylonglocale-code-way-too-long',
+      ]) {
+        expect(() =>
+          validateSyncConfig({
+            version: 1,
+            source_locale: 'en',
+            target_locales: [bad],
+            buckets: { json: { include: ['a.json'] } },
+          })
+        ).toThrow(ConfigError);
       }
     });
 
     it('should reject a source_locale that is not a BCP-47 style code', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en_US.utf8',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en_US.utf8',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow(ConfigError);
     });
 
     it('should accept BCP-47 style locales with script and region subtags', () => {
@@ -270,34 +312,57 @@ describe('sync-config', () => {
         target_locales: ['de', 'pt-BR', 'zh-Hans', 'sr-Latn-RS'],
         buckets: { json: { include: ['a.json'] } },
       });
-      expect(result.target_locales).toEqual(['de', 'pt-BR', 'zh-Hans', 'sr-Latn-RS']);
+      expect(result.target_locales).toEqual([
+        'de',
+        'pt-BR',
+        'zh-Hans',
+        'sr-Latn-RS',
+      ]);
     });
 
     it('should reject a target_path_pattern that resolves into .git/', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['config'],
-        buckets: { json: { include: ['a.json'], target_path_pattern: '.git/{locale}' } },
-      })).toThrow(/\.git/);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['config'],
+          buckets: {
+            json: { include: ['a.json'], target_path_pattern: '.git/{locale}' },
+          },
+        })
+      ).toThrow(/\.git/);
     });
 
     it('should reject a target_path_pattern that resolves into .github/', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'], target_path_pattern: '.github/workflows/{locale}.yml' } },
-      })).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: {
+            json: {
+              include: ['a.json'],
+              target_path_pattern: '.github/workflows/{locale}.yml',
+            },
+          },
+        })
+      ).toThrow(ConfigError);
     });
 
     it('should reject a target_path_pattern with a nested .git segment', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'], target_path_pattern: 'vendor/.git/{locale}.json' } },
-      })).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: {
+            json: {
+              include: ['a.json'],
+              target_path_pattern: 'vendor/.git/{locale}.json',
+            },
+          },
+        })
+      ).toThrow(ConfigError);
     });
 
     it('should accept a target_path_pattern with a harmless dotted directory', () => {
@@ -305,62 +370,81 @@ describe('sync-config', () => {
         version: 1,
         source_locale: 'en',
         target_locales: ['de'],
-        buckets: { json: { include: ['a.json'], target_path_pattern: 'locales/{locale}/app.json' } },
+        buckets: {
+          json: {
+            include: ['a.json'],
+            target_path_pattern: 'locales/{locale}/app.json',
+          },
+        },
       });
-      expect(result.buckets['json']?.target_path_pattern).toBe('locales/{locale}/app.json');
+      expect(result.buckets['json']?.target_path_pattern).toBe(
+        'locales/{locale}/app.json'
+      );
     });
 
     it('should throw when target_locales is empty', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: [],
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('target_locales must be a non-empty array');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: [],
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('target_locales must be a non-empty array');
     });
 
     it('should throw when target_locales is not an array', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: 'de',
-        buckets: { json: { include: ['a.json'] } },
-      })).toThrow('target_locales must be a non-empty array');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: 'de',
+          buckets: { json: { include: ['a.json'] } },
+        })
+      ).toThrow('target_locales must be a non-empty array');
     });
 
     it('should throw when buckets is empty', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: {},
-      })).toThrow('buckets must be a non-empty object');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: {},
+        })
+      ).toThrow('buckets must be a non-empty object');
     });
 
     it('should throw when buckets is missing', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-      })).toThrow('buckets must be a non-empty object');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+        })
+      ).toThrow('buckets must be a non-empty object');
     });
 
     it('should throw when bucket is missing include', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: {} },
-      })).toThrow('bucket "json" must have a non-empty include array');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: {} },
+        })
+      ).toThrow('bucket "json" must have a non-empty include array');
     });
 
     it('should throw when bucket include is empty', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: [] } },
-      })).toThrow('bucket "json" must have a non-empty include array');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: [] } },
+        })
+      ).toThrow('bucket "json" must have a non-empty include array');
     });
 
     it('should preserve translation block through validation', () => {
@@ -373,7 +457,10 @@ describe('sync-config', () => {
       };
 
       const result = validateSyncConfig(raw);
-      expect(result.translation).toEqual({ formality: 'more', glossary: 'auto' });
+      expect(result.translation).toEqual({
+        formality: 'more',
+        glossary: 'auto',
+      });
     });
 
     it('should preserve tms block through validation', () => {
@@ -382,11 +469,19 @@ describe('sync-config', () => {
         source_locale: 'en',
         target_locales: ['de'],
         buckets: { json: { include: ['locales/en.json'] } },
-        tms: { enabled: true, server: 'https://example.com', project_id: 'test' },
+        tms: {
+          enabled: true,
+          server: 'https://example.com',
+          project_id: 'test',
+        },
       };
 
       const result = validateSyncConfig(raw);
-      expect(result.tms).toEqual({ enabled: true, server: 'https://example.com', project_id: 'test' });
+      expect(result.tms).toEqual({
+        enabled: true,
+        server: 'https://example.com',
+        project_id: 'test',
+      });
     });
 
     it('should preserve validation, sync, and ignore blocks', () => {
@@ -401,7 +496,10 @@ describe('sync-config', () => {
       };
 
       const result = validateSyncConfig(raw);
-      expect(result.validation).toEqual({ check_placeholders: true, fail_on_error: false });
+      expect(result.validation).toEqual({
+        check_placeholders: true,
+        fail_on_error: false,
+      });
       expect(result.sync).toEqual({ concurrency: 10, batch_size: 25 });
       expect(result.ignore).toEqual(['*.bak', 'tmp/**']);
     });
@@ -439,13 +537,13 @@ describe('sync-config', () => {
           validateSyncConfig({
             ...baseConfig,
             sync: { concurrency: 5, batch_size: 50 },
-          }),
+          })
         ).not.toThrow();
         expect(() =>
           validateSyncConfig({
             ...baseConfig,
             sync: { concurrency: 5, batch_size: 50, limits: { max_depth: 16 } },
-          }),
+          })
         ).not.toThrow();
       });
 
@@ -458,7 +556,7 @@ describe('sync-config', () => {
               batch_size: 50,
               limits: { max_entries_per_file: 150_000 },
             },
-          }),
+          })
         ).toThrow(ConfigError);
       });
 
@@ -471,7 +569,7 @@ describe('sync-config', () => {
               batch_size: 50,
               limits: { max_file_bytes: 20 * 1024 * 1024 },
             },
-          }),
+          })
         ).toThrow(ConfigError);
       });
 
@@ -484,7 +582,7 @@ describe('sync-config', () => {
               batch_size: 50,
               limits: { max_depth: 128 },
             },
-          }),
+          })
         ).toThrow(ConfigError);
       });
 
@@ -497,7 +595,7 @@ describe('sync-config', () => {
               batch_size: 50,
               limits: { max_depth: 16.5 },
             },
-          }),
+          })
         ).toThrow(ConfigError);
       });
 
@@ -510,7 +608,7 @@ describe('sync-config', () => {
               batch_size: 50,
               limits: { max_depth: 0 },
             },
-          }),
+          })
         ).toThrow(ConfigError);
       });
 
@@ -523,7 +621,7 @@ describe('sync-config', () => {
               batch_size: 50,
               limits: { max_unknown: 10 },
             },
-          }),
+          })
         ).toThrow(ConfigError);
       });
 
@@ -532,77 +630,93 @@ describe('sync-config', () => {
           validateSyncConfig({
             ...baseConfig,
             sync: { concurrency: 5, batch_size: 50, limits: 'not an object' },
-          }),
+          })
         ).toThrow(ConfigError);
       });
     });
 
     it('should throw when translation is a boolean instead of object', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-        translation: true,
-      })).toThrow(ConfigError);
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-        translation: true,
-      })).toThrow('translation must be an object');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+          translation: true,
+        })
+      ).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+          translation: true,
+        })
+      ).toThrow('translation must be an object');
     });
 
     it('should throw when translation is an array', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-        translation: [1, 2],
-      })).toThrow(ConfigError);
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-        translation: [1, 2],
-      })).toThrow('translation must be an object');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+          translation: [1, 2],
+        })
+      ).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+          translation: [1, 2],
+        })
+      ).toThrow('translation must be an object');
     });
 
     it('should throw when translation is null', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-        translation: null,
-      })).toThrow(ConfigError);
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-        translation: null,
-      })).toThrow('translation must be an object');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+          translation: null,
+        })
+      ).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+          translation: null,
+        })
+      ).toThrow('translation must be an object');
     });
 
     it('should throw when validation is a string instead of object', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-        validation: 'invalid',
-      })).toThrow(ConfigError);
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'] } },
-        validation: 'invalid',
-      })).toThrow('validation must be an object');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+          validation: 'invalid',
+        })
+      ).toThrow(ConfigError);
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'] } },
+          validation: 'invalid',
+        })
+      ).toThrow('validation must be an object');
     });
 
     it('should accept valid target_path_pattern with {locale}', () => {
@@ -610,36 +724,59 @@ describe('sync-config', () => {
         version: 1,
         source_locale: 'en',
         target_locales: ['de'],
-        buckets: { android_xml: { include: ['res/values/strings.xml'], target_path_pattern: 'res/values-{locale}/strings.xml' } },
+        buckets: {
+          android_xml: {
+            include: ['res/values/strings.xml'],
+            target_path_pattern: 'res/values-{locale}/strings.xml',
+          },
+        },
       });
-      expect(result.buckets['android_xml']!.target_path_pattern).toBe('res/values-{locale}/strings.xml');
+      expect(result.buckets['android_xml']!.target_path_pattern).toBe(
+        'res/values-{locale}/strings.xml'
+      );
     });
 
     it('should throw when target_path_pattern is not a string', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'], target_path_pattern: 42 } },
-      })).toThrow('target_path_pattern must be a string');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['a.json'], target_path_pattern: 42 } },
+        })
+      ).toThrow('target_path_pattern must be a string');
     });
 
     it('should throw when target_path_pattern lacks {locale}', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'], target_path_pattern: 'res/values/strings.xml' } },
-      })).toThrow('target_path_pattern must contain {locale} placeholder');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: {
+            json: {
+              include: ['a.json'],
+              target_path_pattern: 'res/values/strings.xml',
+            },
+          },
+        })
+      ).toThrow('target_path_pattern must contain {locale} placeholder');
     });
 
     it('should throw when target_path_pattern contains ".."', () => {
-      expect(() => validateSyncConfig({
-        version: 1,
-        source_locale: 'en',
-        target_locales: ['de'],
-        buckets: { json: { include: ['a.json'], target_path_pattern: '../{locale}/strings.xml' } },
-      })).toThrow('target_path_pattern must not contain ".."');
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: {
+            json: {
+              include: ['a.json'],
+              target_path_pattern: '../{locale}/strings.xml',
+            },
+          },
+        })
+      ).toThrow('target_path_pattern must not contain ".."');
     });
 
     describe('translation_memory_threshold validation', () => {
@@ -651,35 +788,53 @@ describe('sync-config', () => {
       };
 
       it('should reject top-level translation_memory_threshold above 100', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: { translation_memory_threshold: 9999 },
-        })).toThrow(ConfigError);
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: { translation_memory_threshold: 9999 },
-        })).toThrow('translation.translation_memory_threshold must be an integer between 0 and 100, got: 9999');
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: { translation_memory_threshold: 9999 },
+          })
+        ).toThrow(ConfigError);
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: { translation_memory_threshold: 9999 },
+          })
+        ).toThrow(
+          'translation.translation_memory_threshold must be an integer between 0 and 100, got: 9999'
+        );
       });
 
       it('should reject negative top-level translation_memory_threshold', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: { translation_memory_threshold: -1 },
-        })).toThrow('translation.translation_memory_threshold must be an integer between 0 and 100, got: -1');
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: { translation_memory_threshold: -1 },
+          })
+        ).toThrow(
+          'translation.translation_memory_threshold must be an integer between 0 and 100, got: -1'
+        );
       });
 
       it('should reject non-integer top-level translation_memory_threshold', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: { translation_memory_threshold: 50.5 },
-        })).toThrow('translation.translation_memory_threshold must be an integer between 0 and 100, got: 50.5');
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: { translation_memory_threshold: 50.5 },
+          })
+        ).toThrow(
+          'translation.translation_memory_threshold must be an integer between 0 and 100, got: 50.5'
+        );
       });
 
       it('should reject non-numeric top-level translation_memory_threshold', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: { translation_memory_threshold: 'abc' },
-        })).toThrow('translation.translation_memory_threshold must be an integer between 0 and 100, got: abc');
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: { translation_memory_threshold: 'abc' },
+          })
+        ).toThrow(
+          'translation.translation_memory_threshold must be an integer between 0 and 100, got: abc'
+        );
       });
 
       it('should accept top-level translation_memory_threshold within range', () => {
@@ -699,14 +854,18 @@ describe('sync-config', () => {
       });
 
       it('should reject per-locale translation_memory_threshold above 100 with locale key path', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: {
-            locale_overrides: {
-              de: { translation_memory_threshold: 200 },
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: {
+              locale_overrides: {
+                de: { translation_memory_threshold: 200 },
+              },
             },
-          },
-        })).toThrow('translation.locale_overrides.de.translation_memory_threshold must be an integer between 0 and 100, got: 200');
+          })
+        ).toThrow(
+          'translation.locale_overrides.de.translation_memory_threshold must be an integer between 0 and 100, got: 200'
+        );
       });
 
       it('should accept per-locale translation_memory_threshold within range', () => {
@@ -718,7 +877,10 @@ describe('sync-config', () => {
             },
           },
         });
-        expect(result.translation?.locale_overrides?.['de']?.translation_memory_threshold).toBe(90);
+        expect(
+          result.translation?.locale_overrides?.['de']
+            ?.translation_memory_threshold
+        ).toBe(90);
       });
 
       it('should accept missing (undefined) translation_memory_threshold', () => {
@@ -726,7 +888,9 @@ describe('sync-config', () => {
           ...baseConfig,
           translation: { glossary: 'my-glossary' },
         });
-        expect(result.translation?.translation_memory_threshold).toBeUndefined();
+        expect(
+          result.translation?.translation_memory_threshold
+        ).toBeUndefined();
       });
     });
 
@@ -749,59 +913,84 @@ describe('sync-config', () => {
       it('should accept translation_memory with model_type: quality_optimized', () => {
         const result = validateSyncConfig({
           ...baseConfig,
-          translation: { translation_memory: 'my-tm', model_type: 'quality_optimized' },
+          translation: {
+            translation_memory: 'my-tm',
+            model_type: 'quality_optimized',
+          },
         });
         expect(result.translation?.model_type).toBe('quality_optimized');
       });
 
       it('should reject translation_memory with model_type: latency_optimized', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: { translation_memory: 'my-tm', model_type: 'latency_optimized' },
-        })).toThrow(ConfigError);
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: { translation_memory: 'my-tm', model_type: 'latency_optimized' },
-        })).toThrow(
-          "translation.model_type must be 'quality_optimized' when translation_memory is set, got: latency_optimized",
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: {
+              translation_memory: 'my-tm',
+              model_type: 'latency_optimized',
+            },
+          })
+        ).toThrow(ConfigError);
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: {
+              translation_memory: 'my-tm',
+              model_type: 'latency_optimized',
+            },
+          })
+        ).toThrow(
+          "translation.model_type must be 'quality_optimized' when translation_memory is set, got: latency_optimized"
         );
       });
 
       it('should reject translation_memory with model_type: prefer_quality_optimized', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: { translation_memory: 'my-tm', model_type: 'prefer_quality_optimized' },
-        })).toThrow(
-          "translation.model_type must be 'quality_optimized' when translation_memory is set, got: prefer_quality_optimized",
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: {
+              translation_memory: 'my-tm',
+              model_type: 'prefer_quality_optimized',
+            },
+          })
+        ).toThrow(
+          "translation.model_type must be 'quality_optimized' when translation_memory is set, got: prefer_quality_optimized"
         );
       });
 
       it('should reject per-locale override with latency_optimized when TM set at top level', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: {
-            translation_memory: 'my-tm',
-            model_type: 'quality_optimized',
-            locale_overrides: {
-              de: { model_type: 'latency_optimized' },
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: {
+              translation_memory: 'my-tm',
+              model_type: 'quality_optimized',
+              locale_overrides: {
+                de: { model_type: 'latency_optimized' },
+              },
             },
-          },
-        })).toThrow(
-          "translation.locale_overrides.de.model_type must be 'quality_optimized' when translation_memory is set, got: latency_optimized",
+          })
+        ).toThrow(
+          "translation.locale_overrides.de.model_type must be 'quality_optimized' when translation_memory is set, got: latency_optimized"
         );
       });
 
       it('should reject per-locale override with latency_optimized when TM set in the same override', () => {
-        expect(() => validateSyncConfig({
-          ...baseConfig,
-          translation: {
-            model_type: 'quality_optimized',
-            locale_overrides: {
-              de: { translation_memory: 'de-tm', model_type: 'latency_optimized' },
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: {
+              model_type: 'quality_optimized',
+              locale_overrides: {
+                de: {
+                  translation_memory: 'de-tm',
+                  model_type: 'latency_optimized',
+                },
+              },
             },
-          },
-        })).toThrow(
-          "translation.locale_overrides.de.model_type must be 'quality_optimized' when translation_memory is set, got: latency_optimized",
+          })
+        ).toThrow(
+          "translation.locale_overrides.de.model_type must be 'quality_optimized' when translation_memory is set, got: latency_optimized"
         );
       });
 
@@ -825,7 +1014,9 @@ describe('sync-config', () => {
       it('should reject unknown top-level field and name it in the error', () => {
         const raw = { ...baseConfig, target_locale: 'en' };
         expect(() => validateSyncConfig(raw)).toThrow(ConfigError);
-        expect(() => validateSyncConfig(raw)).toThrow(/Unknown field "target_locale"/);
+        expect(() => validateSyncConfig(raw)).toThrow(
+          /Unknown field "target_locale"/
+        );
       });
 
       it('should suggest target_locales when user typed target_locale', () => {
@@ -851,7 +1042,9 @@ describe('sync-config', () => {
           fail('expected throw');
         } catch (err) {
           expect(err).toBeInstanceOf(ConfigError);
-          expect((err as ConfigError).message).toMatch(/Unknown field "bucket"/);
+          expect((err as ConfigError).message).toMatch(
+            /Unknown field "bucket"/
+          );
           expect((err as ConfigError).suggestion).toMatch(/buckets/);
         }
       });
@@ -863,7 +1056,9 @@ describe('sync-config', () => {
           fail('expected throw');
         } catch (err) {
           expect(err).toBeInstanceOf(ConfigError);
-          expect((err as ConfigError).message).toMatch(/Unknown field "translate"/);
+          expect((err as ConfigError).message).toMatch(
+            /Unknown field "translate"/
+          );
           expect((err as ConfigError).suggestion).toMatch(/translation/);
         }
       });
@@ -874,7 +1069,9 @@ describe('sync-config', () => {
           buckets: { json: { includes: ['a.json'] } },
         };
         expect(() => validateSyncConfig(raw)).toThrow(ConfigError);
-        expect(() => validateSyncConfig(raw)).toThrow(/Unknown field "includes"/);
+        expect(() => validateSyncConfig(raw)).toThrow(
+          /Unknown field "includes"/
+        );
         expect(() => validateSyncConfig(raw)).toThrow(/buckets\.json/);
       });
 
@@ -898,7 +1095,9 @@ describe('sync-config', () => {
           translation: { formalness: 'more' },
         };
         expect(() => validateSyncConfig(raw)).toThrow(ConfigError);
-        expect(() => validateSyncConfig(raw)).toThrow(/Unknown field "formalness"/);
+        expect(() => validateSyncConfig(raw)).toThrow(
+          /Unknown field "formalness"/
+        );
         expect(() => validateSyncConfig(raw)).toThrow(/translation/);
       });
 
@@ -917,7 +1116,9 @@ describe('sync-config', () => {
           fail('expected throw');
         } catch (err) {
           expect(err).toBeInstanceOf(ConfigError);
-          expect((err as ConfigError).message).toMatch(/Unknown field "apikey"/);
+          expect((err as ConfigError).message).toMatch(
+            /Unknown field "apikey"/
+          );
           expect((err as ConfigError).message).toMatch(/tms/);
           expect((err as ConfigError).suggestion).toMatch(/api_key/);
         }
@@ -933,7 +1134,9 @@ describe('sync-config', () => {
           },
         };
         expect(() => validateSyncConfig(raw)).toThrow(ConfigError);
-        expect(() => validateSyncConfig(raw)).toThrow(/Unknown field "formalness"/);
+        expect(() => validateSyncConfig(raw)).toThrow(
+          /Unknown field "formalness"/
+        );
         expect(() => validateSyncConfig(raw)).toThrow(/locale_overrides\.de/);
       });
 
@@ -943,7 +1146,9 @@ describe('sync-config', () => {
           validation: { fail_on_missings: true },
         };
         expect(() => validateSyncConfig(raw)).toThrow(ConfigError);
-        expect(() => validateSyncConfig(raw)).toThrow(/Unknown field "fail_on_missings"/);
+        expect(() => validateSyncConfig(raw)).toThrow(
+          /Unknown field "fail_on_missings"/
+        );
       });
 
       it('should reject unknown sync-behavior field', () => {
@@ -952,7 +1157,9 @@ describe('sync-config', () => {
           sync: { concurrency: 5, batch_size: 50, maxchars: 1000 },
         };
         expect(() => validateSyncConfig(raw)).toThrow(ConfigError);
-        expect(() => validateSyncConfig(raw)).toThrow(/Unknown field "maxchars"/);
+        expect(() => validateSyncConfig(raw)).toThrow(
+          /Unknown field "maxchars"/
+        );
       });
 
       it('should reject unknown context field', () => {
@@ -961,7 +1168,9 @@ describe('sync-config', () => {
           context: { enabled: true, scanpaths: ['src/**/*.ts'] },
         };
         expect(() => validateSyncConfig(raw)).toThrow(ConfigError);
-        expect(() => validateSyncConfig(raw)).toThrow(/Unknown field "scanpaths"/);
+        expect(() => validateSyncConfig(raw)).toThrow(
+          /Unknown field "scanpaths"/
+        );
       });
 
       it('should accept a fully-populated valid config with all known keys', () => {
@@ -1044,35 +1253,73 @@ describe('sync-config', () => {
         { label: 'array root', raw: [] },
         {
           label: 'missing version',
-          raw: { source_locale: 'en', target_locales: ['de'], buckets: { json: { include: ['a.json'] } } },
+          raw: {
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: { json: { include: ['a.json'] } },
+          },
         },
         {
           label: 'wrong version',
-          raw: { version: 2, source_locale: 'en', target_locales: ['de'], buckets: { json: { include: ['a.json'] } } },
+          raw: {
+            version: 2,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: { json: { include: ['a.json'] } },
+          },
         },
         {
           label: 'missing source_locale',
-          raw: { version: 1, target_locales: ['de'], buckets: { json: { include: ['a.json'] } } },
+          raw: {
+            version: 1,
+            target_locales: ['de'],
+            buckets: { json: { include: ['a.json'] } },
+          },
         },
         {
           label: 'source_locale with path separator',
-          raw: { version: 1, source_locale: 'en/US', target_locales: ['de'], buckets: { json: { include: ['a.json'] } } },
+          raw: {
+            version: 1,
+            source_locale: 'en/US',
+            target_locales: ['de'],
+            buckets: { json: { include: ['a.json'] } },
+          },
         },
         {
           label: 'target_locales not array',
-          raw: { version: 1, source_locale: 'en', target_locales: 'de', buckets: { json: { include: ['a.json'] } } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: 'de',
+            buckets: { json: { include: ['a.json'] } },
+          },
         },
         {
           label: 'target_locales contains non-string',
-          raw: { version: 1, source_locale: 'en', target_locales: [42], buckets: { json: { include: ['a.json'] } } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: [42],
+            buckets: { json: { include: ['a.json'] } },
+          },
         },
         {
           label: 'target locale with path traversal',
-          raw: { version: 1, source_locale: 'en', target_locales: ['../evil'], buckets: { json: { include: ['a.json'] } } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['../evil'],
+            buckets: { json: { include: ['a.json'] } },
+          },
         },
         {
           label: 'target_locales contains source_locale',
-          raw: { version: 1, source_locale: 'en', target_locales: ['en'], buckets: { json: { include: ['a.json'] } } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['en'],
+            buckets: { json: { include: ['a.json'] } },
+          },
         },
         {
           label: 'missing buckets',
@@ -1080,35 +1327,86 @@ describe('sync-config', () => {
         },
         {
           label: 'empty buckets object',
-          raw: { version: 1, source_locale: 'en', target_locales: ['de'], buckets: {} },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: {},
+          },
         },
         {
           label: 'bucket not an object',
-          raw: { version: 1, source_locale: 'en', target_locales: ['de'], buckets: { json: 'oops' } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: { json: 'oops' },
+          },
         },
         {
           label: 'bucket missing include',
-          raw: { version: 1, source_locale: 'en', target_locales: ['de'], buckets: { json: {} } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: { json: {} },
+          },
         },
         {
           label: 'bucket include contains non-string',
-          raw: { version: 1, source_locale: 'en', target_locales: ['de'], buckets: { json: { include: [42] } } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: { json: { include: [42] } },
+          },
         },
         {
           label: 'target_path_pattern wrong type',
-          raw: { version: 1, source_locale: 'en', target_locales: ['de'], buckets: { json: { include: ['a.json'], target_path_pattern: 42 } } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: { json: { include: ['a.json'], target_path_pattern: 42 } },
+          },
         },
         {
           label: 'target_path_pattern missing {locale}',
-          raw: { version: 1, source_locale: 'en', target_locales: ['de'], buckets: { json: { include: ['a.json'], target_path_pattern: 'res/strings.xml' } } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: {
+              json: {
+                include: ['a.json'],
+                target_path_pattern: 'res/strings.xml',
+              },
+            },
+          },
         },
         {
           label: 'target_path_pattern with ..',
-          raw: { version: 1, source_locale: 'en', target_locales: ['de'], buckets: { json: { include: ['a.json'], target_path_pattern: '../{locale}/strings.xml' } } },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: {
+              json: {
+                include: ['a.json'],
+                target_path_pattern: '../{locale}/strings.xml',
+              },
+            },
+          },
         },
         {
           label: 'translation block not an object',
-          raw: { version: 1, source_locale: 'en', target_locales: ['de'], buckets: { json: { include: ['a.json'] } }, translation: true },
+          raw: {
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: { json: { include: ['a.json'] } },
+            translation: true,
+          },
         },
         {
           label: 'translation_memory_threshold out of range',
@@ -1127,27 +1425,37 @@ describe('sync-config', () => {
             source_locale: 'en',
             target_locales: ['de'],
             buckets: { json: { include: ['a.json'] } },
-            translation: { translation_memory: 'tm', model_type: 'latency_optimized' },
+            translation: {
+              translation_memory: 'tm',
+              model_type: 'latency_optimized',
+            },
           },
         },
       ];
 
-      it.each(malformedConfigs)('every ConfigError from $label includes a suggestion', ({ raw }) => {
-        let caught: unknown;
-        try {
-          validateSyncConfig(raw);
-        } catch (err) {
-          caught = err;
+      it.each(malformedConfigs)(
+        'every ConfigError from $label includes a suggestion',
+        ({ raw }) => {
+          let caught: unknown;
+          try {
+            validateSyncConfig(raw);
+          } catch (err) {
+            caught = err;
+          }
+          expect(caught).toBeInstanceOf(ConfigError);
+          const err = caught as ConfigError;
+          expect(typeof err.suggestion).toBe('string');
+          expect((err.suggestion ?? '').length).toBeGreaterThan(0);
         }
-        expect(caught).toBeInstanceOf(ConfigError);
-        const err = caught as ConfigError;
-        expect(typeof err.suggestion).toBe('string');
-        expect((err.suggestion ?? '').length).toBeGreaterThan(0);
-      });
+      );
 
       it('suggestion for missing source_locale mentions source_locale', () => {
         try {
-          validateSyncConfig({ version: 1, target_locales: ['de'], buckets: { json: { include: ['a.json'] } } });
+          validateSyncConfig({
+            version: 1,
+            target_locales: ['de'],
+            buckets: { json: { include: ['a.json'] } },
+          });
           fail('expected throw');
         } catch (err) {
           expect(err).toBeInstanceOf(ConfigError);
@@ -1157,7 +1465,12 @@ describe('sync-config', () => {
 
       it('suggestion for bucket missing include mentions include', () => {
         try {
-          validateSyncConfig({ version: 1, source_locale: 'en', target_locales: ['de'], buckets: { json: {} } });
+          validateSyncConfig({
+            version: 1,
+            source_locale: 'en',
+            target_locales: ['de'],
+            buckets: { json: {} },
+          });
           fail('expected throw');
         } catch (err) {
           expect(err).toBeInstanceOf(ConfigError);
@@ -1171,7 +1484,12 @@ describe('sync-config', () => {
             version: 1,
             source_locale: 'en',
             target_locales: ['de'],
-            buckets: { json: { include: ['a.json'], target_path_pattern: 'res/strings.xml' } },
+            buckets: {
+              json: {
+                include: ['a.json'],
+                target_path_pattern: 'res/strings.xml',
+              },
+            },
           });
           fail('expected throw');
         } catch (err) {
@@ -1206,14 +1524,14 @@ describe('sync-config', () => {
     });
 
     it('should throw ConfigError when file is not found', async () => {
-      await expect(
-        loadSyncConfig(tmpDir),
-      ).rejects.toThrow(ConfigError);
+      await expect(loadSyncConfig(tmpDir)).rejects.toThrow(ConfigError);
     });
 
     it('should throw ConfigError when configPath override points to missing file', async () => {
       await expect(
-        loadSyncConfig(undefined, { configPath: '/nonexistent/path/.deepl-sync.yaml' }),
+        loadSyncConfig(undefined, {
+          configPath: '/nonexistent/path/.deepl-sync.yaml',
+        })
       ).rejects.toThrow(ConfigError);
     });
 
@@ -1221,9 +1539,7 @@ describe('sync-config', () => {
       const badYaml = path.join(tmpDir, SYNC_CONFIG_FILENAME);
       fs.writeFileSync(badYaml, '{{{{invalid yaml');
 
-      await expect(
-        loadSyncConfig(tmpDir),
-      ).rejects.toThrow(ConfigError);
+      await expect(loadSyncConfig(tmpDir)).rejects.toThrow(ConfigError);
 
       try {
         await loadSyncConfig(tmpDir);
@@ -1258,7 +1574,10 @@ describe('sync-config', () => {
       const result = await loadSyncConfig(undefined, { configPath });
 
       expect(Object.keys(result.buckets)).toEqual(['json', 'yaml']);
-      expect(result.buckets['yaml']?.include).toEqual(['config/*.yaml', 'i18n/*.yml']);
+      expect(result.buckets['yaml']?.include).toEqual([
+        'config/*.yaml',
+        'i18n/*.yml',
+      ]);
     });
 
     it('should merge formality CLI override into existing translation block', async () => {
@@ -1281,25 +1600,37 @@ translation:
 
     it('should create translation block when CLI override needs it', async () => {
       const configPath = path.join(FIXTURES_DIR, 'valid.yaml');
-      const result = await loadSyncConfig(undefined, { configPath, formality: 'less' });
+      const result = await loadSyncConfig(undefined, {
+        configPath,
+        formality: 'less',
+      });
       expect(result.translation?.formality).toBe('less');
     });
 
     it('should merge glossary CLI override into translation block', async () => {
       const configPath = path.join(FIXTURES_DIR, 'valid.yaml');
-      const result = await loadSyncConfig(undefined, { configPath, glossary: 'my-glossary' });
+      const result = await loadSyncConfig(undefined, {
+        configPath,
+        glossary: 'my-glossary',
+      });
       expect(result.translation?.glossary).toBe('my-glossary');
     });
 
     it('should merge modelType CLI override into translation block', async () => {
       const configPath = path.join(FIXTURES_DIR, 'valid.yaml');
-      const result = await loadSyncConfig(undefined, { configPath, modelType: 'quality_optimized' });
+      const result = await loadSyncConfig(undefined, {
+        configPath,
+        modelType: 'quality_optimized',
+      });
       expect(result.translation?.model_type).toBe('quality_optimized');
     });
 
     it('should merge context CLI override into context block', async () => {
       const configPath = path.join(FIXTURES_DIR, 'valid.yaml');
-      const result = await loadSyncConfig(undefined, { configPath, context: true });
+      const result = await loadSyncConfig(undefined, {
+        configPath,
+        context: true,
+      });
       expect(result.context?.enabled).toBe(true);
     });
   });
@@ -1315,23 +1646,31 @@ translation:
     it('should accept a localeFilter whose entries are all in target_locales', () => {
       const config = baseConfig();
       config.target_locales = ['de', 'fr'];
-      expect(() => applyCliOverrides(config, { localeFilter: ['de', 'fr'] })).not.toThrow();
+      expect(() =>
+        applyCliOverrides(config, { localeFilter: ['de', 'fr'] })
+      ).not.toThrow();
     });
 
     it('should throw ConfigError naming the offending and configured locales', () => {
       const config = baseConfig();
       config.target_locales = ['de', 'fr'];
-      expect(() => applyCliOverrides(config, { localeFilter: ['es'] })).toThrow(ConfigError);
-      expect(() => applyCliOverrides(config, { localeFilter: ['es'] })).toThrow(/es/);
-      expect(() => applyCliOverrides(config, { localeFilter: ['es'] })).toThrow(/de, fr/);
+      expect(() => applyCliOverrides(config, { localeFilter: ['es'] })).toThrow(
+        ConfigError
+      );
+      expect(() => applyCliOverrides(config, { localeFilter: ['es'] })).toThrow(
+        /es/
+      );
+      expect(() => applyCliOverrides(config, { localeFilter: ['es'] })).toThrow(
+        /de, fr/
+      );
     });
 
     it('should report every unconfigured locale in a mixed filter', () => {
       const config = baseConfig();
       config.target_locales = ['de', 'fr'];
-      expect(() => applyCliOverrides(config, { localeFilter: ['de', 'es', 'zz'] })).toThrow(
-        /es, zz/,
-      );
+      expect(() =>
+        applyCliOverrides(config, { localeFilter: ['de', 'es', 'zz'] })
+      ).toThrow(/es, zz/);
     });
 
     it('should merge formality into existing translation block', () => {
@@ -1353,7 +1692,9 @@ translation:
     });
 
     it('should merge modelType into translation block', () => {
-      const result = applyCliOverrides(baseConfig(), { modelType: 'quality_optimized' });
+      const result = applyCliOverrides(baseConfig(), {
+        modelType: 'quality_optimized',
+      });
       expect(result.translation?.model_type).toBe('quality_optimized');
     });
 
@@ -1395,14 +1736,19 @@ translation:
 
     it('should reject model_type override that breaks translation_memory compatibility', () => {
       const config = baseConfig();
-      config.translation = { translation_memory: 'tm-1', model_type: 'quality_optimized' };
+      config.translation = {
+        translation_memory: 'tm-1',
+        model_type: 'quality_optimized',
+      };
       expect(() =>
-        applyCliOverrides(config, { modelType: 'latency_optimized' }),
+        applyCliOverrides(config, { modelType: 'latency_optimized' })
       ).toThrow(ConfigError);
     });
 
     it('should accept model_type override when translation_memory is not set', () => {
-      const result = applyCliOverrides(baseConfig(), { modelType: 'latency_optimized' });
+      const result = applyCliOverrides(baseConfig(), {
+        modelType: 'latency_optimized',
+      });
       expect(result.translation?.model_type).toBe('latency_optimized');
     });
   });
@@ -1421,13 +1767,19 @@ translation:
       originalToken = process.env['TMS_TOKEN'];
       delete process.env['TMS_API_KEY'];
       delete process.env['TMS_TOKEN'];
-      stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+      stderrSpy = jest
+        .spyOn(process.stderr, 'write')
+        .mockImplementation(() => true);
     });
 
     afterEach(() => {
       fs.rmSync(tmpDir, { recursive: true, force: true });
-      Object.defineProperty(process.stderr, 'isTTY', { value: originalIsTTY, configurable: true });
-      if (originalApiKey !== undefined) process.env['TMS_API_KEY'] = originalApiKey;
+      Object.defineProperty(process.stderr, 'isTTY', {
+        value: originalIsTTY,
+        configurable: true,
+      });
+      if (originalApiKey !== undefined)
+        process.env['TMS_API_KEY'] = originalApiKey;
       if (originalToken !== undefined) process.env['TMS_TOKEN'] = originalToken;
       stderrSpy.mockRestore();
     });
@@ -1450,7 +1802,10 @@ ${extra}
     };
 
     it('emits a stderr warning when tms.api_key is inlined and stderr is not a TTY', async () => {
-      Object.defineProperty(process.stderr, 'isTTY', { value: false, configurable: true });
+      Object.defineProperty(process.stderr, 'isTTY', {
+        value: false,
+        configurable: true,
+      });
       writeConfig('  api_key: secret-key');
 
       await loadSyncConfig(tmpDir);
@@ -1461,7 +1816,10 @@ ${extra}
     });
 
     it('emits a stderr warning when tms.token is inlined and stderr is not a TTY', async () => {
-      Object.defineProperty(process.stderr, 'isTTY', { value: false, configurable: true });
+      Object.defineProperty(process.stderr, 'isTTY', {
+        value: false,
+        configurable: true,
+      });
       writeConfig('  token: secret-token');
 
       await loadSyncConfig(tmpDir);
@@ -1471,7 +1829,10 @@ ${extra}
     });
 
     it('still emits the warning when stderr is a TTY', async () => {
-      Object.defineProperty(process.stderr, 'isTTY', { value: true, configurable: true });
+      Object.defineProperty(process.stderr, 'isTTY', {
+        value: true,
+        configurable: true,
+      });
       writeConfig('  api_key: secret-key');
 
       await loadSyncConfig(tmpDir);
@@ -1481,7 +1842,10 @@ ${extra}
     });
 
     it('does not emit the warning when tms.api_key is absent', async () => {
-      Object.defineProperty(process.stderr, 'isTTY', { value: false, configurable: true });
+      Object.defineProperty(process.stderr, 'isTTY', {
+        value: false,
+        configurable: true,
+      });
       writeConfig('  enabled: false');
 
       await loadSyncConfig(tmpDir);
@@ -1492,7 +1856,10 @@ ${extra}
     });
 
     it('does not emit the warning when TMS_API_KEY env var is already set', async () => {
-      Object.defineProperty(process.stderr, 'isTTY', { value: false, configurable: true });
+      Object.defineProperty(process.stderr, 'isTTY', {
+        value: false,
+        configurable: true,
+      });
       process.env['TMS_API_KEY'] = 'env-key';
       writeConfig('  api_key: secret-key');
 
diff --git a/tests/unit/sync/sync-context.test.ts b/tests/unit/sync/sync-context.test.ts
index 0ed401d6..a38c32db 100644
--- a/tests/unit/sync/sync-context.test.ts
+++ b/tests/unit/sync/sync-context.test.ts
@@ -32,7 +32,9 @@ jest.mock('fs', () => {
 import * as fs from 'fs';
 
 const mockFastGlob = fg as jest.MockedFunction<typeof fg>;
-const mockReadFile = fs.promises.readFile as jest.MockedFunction<typeof fs.promises.readFile>;
+const mockReadFile = fs.promises.readFile as jest.MockedFunction<
+  typeof fs.promises.readFile
+>;
 
 describe('sync-context', () => {
   describe('buildKeyPatterns', () => {
@@ -76,7 +78,12 @@ describe('sync-context', () => {
 
     it('should match intl.formatMessage() calls', () => {
       const source = `intl.formatMessage({ id: 'items_count' })`;
-      const matches = extractContextFromSource(source, 'app.tsx', ['intl.formatMessage'], 0);
+      const matches = extractContextFromSource(
+        source,
+        'app.tsx',
+        ['intl.formatMessage'],
+        0
+      );
       expect(matches).toHaveLength(1);
       expect(matches[0]!.key).toBe('items_count');
       expect(matches[0]!.matchedFunction).toBe('intl.formatMessage');
@@ -91,7 +98,12 @@ describe('sync-context', () => {
 
     it('should return empty array when no matches found', () => {
       const source = `const x = 42;\nconsole.log(x);`;
-      const matches = extractContextFromSource(source, 'math.ts', DEFAULT_FUNCTION_NAMES, 0);
+      const matches = extractContextFromSource(
+        source,
+        'math.ts',
+        DEFAULT_FUNCTION_NAMES,
+        0
+      );
       expect(matches).toHaveLength(0);
     });
 
@@ -161,7 +173,12 @@ describe('sync-context', () => {
 
     it('should use correct file path in matches', () => {
       const source = `t('test')`;
-      const matches = extractContextFromSource(source, 'src/components/Header.tsx', ['t'], 0);
+      const matches = extractContextFromSource(
+        source,
+        'src/components/Header.tsx',
+        ['t'],
+        0
+      );
       expect(matches[0]!.filePath).toBe('src/components/Header.tsx');
     });
   });
@@ -235,11 +252,16 @@ describe('sync-context', () => {
 
   describe('extractAllKeyContexts', () => {
     it('should aggregate keys from multiple files', async () => {
-      mockFastGlob.mockResolvedValue(['/project/src/a.ts', '/project/src/b.ts']);
+      mockFastGlob.mockResolvedValue([
+        '/project/src/a.ts',
+        '/project/src/b.ts',
+      ]);
 
       mockReadFile.mockImplementation((filePath: unknown) => {
-        if (String(filePath).includes('a.ts')) return Promise.resolve(`t('shared_key')`);
-        if (String(filePath).includes('b.ts')) return Promise.resolve(`t('shared_key')\nt('unique_key')`);
+        if (String(filePath).includes('a.ts'))
+          return Promise.resolve(`t('shared_key')`);
+        if (String(filePath).includes('b.ts'))
+          return Promise.resolve(`t('shared_key')\nt('unique_key')`);
         return Promise.resolve('');
       });
 
@@ -254,10 +276,14 @@ describe('sync-context', () => {
     });
 
     it('should skip unreadable files gracefully', async () => {
-      mockFastGlob.mockResolvedValue(['/project/src/good.ts', '/project/src/bad.ts']);
+      mockFastGlob.mockResolvedValue([
+        '/project/src/good.ts',
+        '/project/src/bad.ts',
+      ]);
 
       mockReadFile.mockImplementation((filePath: unknown) => {
-        if (String(filePath).includes('bad.ts')) return Promise.reject(new Error('EACCES'));
+        if (String(filePath).includes('bad.ts'))
+          return Promise.reject(new Error('EACCES'));
         return Promise.resolve(`t('found')`);
       });
 
@@ -323,7 +349,7 @@ describe('sync-context', () => {
           cwd: '/project',
           absolute: true,
           onlyFiles: true,
-        }),
+        })
       );
     });
 
@@ -422,14 +448,21 @@ describe('sync-context', () => {
           rootDir: '/project',
         });
 
-        expect(mockFastGlob).toHaveBeenCalledWith(['/project/src/**/*.ts'], expect.any(Object));
+        expect(mockFastGlob).toHaveBeenCalledWith(
+          ['/project/src/**/*.ts'],
+          expect.any(Object)
+        );
       });
     });
   });
 
   describe('buildTemplateLiteralPatterns', () => {
     it('should return a regex for each non-intl function name', () => {
-      const patterns = buildTemplateLiteralPatterns(['t', 'i18n.t', 'intl.formatMessage']);
+      const patterns = buildTemplateLiteralPatterns([
+        't',
+        'i18n.t',
+        'intl.formatMessage',
+      ]);
       expect(patterns).toHaveLength(2);
       patterns.forEach((p) => expect(p).toBeInstanceOf(RegExp));
     });
@@ -451,11 +484,15 @@ describe('sync-context', () => {
     });
 
     it('should replace interpolation in middle', () => {
-      expect(templateToGlobPattern('features.${key}.title')).toBe('features.*.title');
+      expect(templateToGlobPattern('features.${key}.title')).toBe(
+        'features.*.title'
+      );
     });
 
     it('should replace multiple interpolations', () => {
-      expect(templateToGlobPattern('pricing.${tier}.features.${fi}')).toBe('pricing.*.features.*');
+      expect(templateToGlobPattern('pricing.${tier}.features.${fi}')).toBe(
+        'pricing.*.features.*'
+      );
     });
 
     it('should pass through strings with no interpolations', () => {
@@ -463,14 +500,21 @@ describe('sync-context', () => {
     });
 
     it('should handle complex interpolation expressions', () => {
-      expect(templateToGlobPattern('items.${i + 1}.label')).toBe('items.*.label');
+      expect(templateToGlobPattern('items.${i + 1}.label')).toBe(
+        'items.*.label'
+      );
     });
   });
 
   describe('extractTemplateLiteralMatches', () => {
     it('should match t() calls with template literals', () => {
       const source = 'const x = t(`nav.${key}`);';
-      const matches = extractTemplateLiteralMatches(source, 'app.tsx', ['t'], 0);
+      const matches = extractTemplateLiteralMatches(
+        source,
+        'app.tsx',
+        ['t'],
+        0
+      );
       expect(matches).toHaveLength(1);
       expect(matches[0]!.pattern).toBe('nav.${key}');
       expect(matches[0]!.matchedFunction).toBe('t');
@@ -479,40 +523,70 @@ describe('sync-context', () => {
 
     it('should match i18n.t() with template literals', () => {
       const source = 'i18n.t(`section.${name}`)';
-      const matches = extractTemplateLiteralMatches(source, 'app.tsx', ['i18n.t'], 0);
+      const matches = extractTemplateLiteralMatches(
+        source,
+        'app.tsx',
+        ['i18n.t'],
+        0
+      );
       expect(matches).toHaveLength(1);
       expect(matches[0]!.pattern).toBe('section.${name}');
     });
 
     it('should match $t() with template literals', () => {
       const source = '{{ $t(`items.${idx}`) }}';
-      const matches = extractTemplateLiteralMatches(source, 'comp.vue', ['$t'], 0);
+      const matches = extractTemplateLiteralMatches(
+        source,
+        'comp.vue',
+        ['$t'],
+        0
+      );
       expect(matches).toHaveLength(1);
       expect(matches[0]!.pattern).toBe('items.${idx}');
     });
 
     it('should not match when preceded by a dot', () => {
       const source = 'obj.t(`nav.${key}`)';
-      const matches = extractTemplateLiteralMatches(source, 'app.tsx', ['t'], 0);
+      const matches = extractTemplateLiteralMatches(
+        source,
+        'app.tsx',
+        ['t'],
+        0
+      );
       expect(matches).toHaveLength(0);
     });
 
     it('should ignore template literals without interpolation', () => {
       const source = 't(`static.key`)';
-      const matches = extractTemplateLiteralMatches(source, 'app.tsx', ['t'], 0);
+      const matches = extractTemplateLiteralMatches(
+        source,
+        'app.tsx',
+        ['t'],
+        0
+      );
       expect(matches).toHaveLength(0);
     });
 
     it('should include surrounding code context', () => {
       const source = 'line1\nline2\nt(`nav.${key}`)\nline4\nline5';
-      const matches = extractTemplateLiteralMatches(source, 'app.tsx', ['t'], 1);
+      const matches = extractTemplateLiteralMatches(
+        source,
+        'app.tsx',
+        ['t'],
+        1
+      );
       expect(matches).toHaveLength(1);
       expect(matches[0]!.surroundingCode).toBe('line2\nt(`nav.${key}`)\nline4');
     });
 
     it('should find multiple matches', () => {
       const source = 't(`a.${x}`)\nt(`b.${y}`)';
-      const matches = extractTemplateLiteralMatches(source, 'app.tsx', ['t'], 0);
+      const matches = extractTemplateLiteralMatches(
+        source,
+        'app.tsx',
+        ['t'],
+        0
+      );
       expect(matches).toHaveLength(2);
       expect(matches[0]!.pattern).toBe('a.${x}');
       expect(matches[1]!.pattern).toBe('b.${y}');
@@ -520,13 +594,21 @@ describe('sync-context', () => {
 
     it('should return empty array when no template literals found', () => {
       const source = "t('static_key')";
-      const matches = extractTemplateLiteralMatches(source, 'app.tsx', ['t'], 0);
+      const matches = extractTemplateLiteralMatches(
+        source,
+        'app.tsx',
+        ['t'],
+        0
+      );
       expect(matches).toHaveLength(0);
     });
   });
 
   describe('resolveTemplatePatterns', () => {
-    function makeTemplateMatch(pattern: string, overrides: Partial<TemplatePatternMatch> = {}): TemplatePatternMatch {
+    function makeTemplateMatch(
+      pattern: string,
+      overrides: Partial<TemplatePatternMatch> = {}
+    ): TemplatePatternMatch {
       return {
         pattern,
         filePath: 'app.tsx',
@@ -549,7 +631,11 @@ describe('sync-context', () => {
 
     it('should match known keys against a multi-wildcard pattern', () => {
       const patterns = [makeTemplateMatch('pricing.${tier}.features.${fi}')];
-      const knownKeys = ['pricing.free.features.0', 'pricing.pro.features.1', 'pricing.heading'];
+      const knownKeys = [
+        'pricing.free.features.0',
+        'pricing.pro.features.1',
+        'pricing.heading',
+      ];
       const result = resolveTemplatePatterns(patterns, knownKeys);
       expect(result.size).toBe(2);
       expect(result.has('pricing.free.features.0')).toBe(true);
@@ -585,7 +671,9 @@ describe('sync-context', () => {
     });
 
     it('should produce ContextMatch objects with correct fields', () => {
-      const patterns = [makeTemplateMatch('nav.${key}', { filePath: 'Navbar.tsx', line: 15 })];
+      const patterns = [
+        makeTemplateMatch('nav.${key}', { filePath: 'Navbar.tsx', line: 15 }),
+      ];
       const result = resolveTemplatePatterns(patterns, ['nav.home']);
       const matches = result.get('nav.home')!;
       expect(matches[0]!.key).toBe('nav.home');
@@ -598,12 +686,21 @@ describe('sync-context', () => {
       const DUPS = 1_000;
       const knownKeys = ['features.a.title', 'features.b.title', 'other.key'];
 
-      const canonical = makeTemplateMatch('features.${k}.title', { filePath: 'comp.tsx', line: 1 });
-      const dupPatterns = Array.from({ length: DUPS }, () => ({ ...canonical }));
-      dupPatterns.push(makeTemplateMatch('other.${x}', { filePath: 'other.tsx', line: 1 }));
+      const canonical = makeTemplateMatch('features.${k}.title', {
+        filePath: 'comp.tsx',
+        line: 1,
+      });
+      const dupPatterns = Array.from({ length: DUPS }, () => ({
+        ...canonical,
+      }));
+      dupPatterns.push(
+        makeTemplateMatch('other.${x}', { filePath: 'other.tsx', line: 1 })
+      );
 
       const singlePattern = [canonical];
-      singlePattern.push(makeTemplateMatch('other.${x}', { filePath: 'other.tsx', line: 1 }));
+      singlePattern.push(
+        makeTemplateMatch('other.${x}', { filePath: 'other.tsx', line: 1 })
+      );
 
       const resultSingle = resolveTemplatePatterns(singlePattern, knownKeys);
       const resultDup = resolveTemplatePatterns(dupPatterns, knownKeys);
@@ -612,19 +709,28 @@ describe('sync-context', () => {
       expect(resultDup.has('features.b.title')).toBe(true);
       expect(resultDup.has('other.key')).toBe(true);
 
-      const singleCtx = synthesizeContext(resultSingle.get('features.a.title')!, { key: 'features.a.title' });
-      const dupCtx = synthesizeContext(resultDup.get('features.a.title')!, { key: 'features.a.title' });
+      const singleCtx = synthesizeContext(
+        resultSingle.get('features.a.title')!,
+        { key: 'features.a.title' }
+      );
+      const dupCtx = synthesizeContext(resultDup.get('features.a.title')!, {
+        key: 'features.a.title',
+      });
       expect(dupCtx).toBe(singleCtx);
     });
 
     it('should not throw on a pattern containing an unbalanced group metacharacter', () => {
       const patterns = [makeTemplateMatch('item(${i}')];
-      expect(() => resolveTemplatePatterns(patterns, ['item(1', 'item.a'])).not.toThrow();
+      expect(() =>
+        resolveTemplatePatterns(patterns, ['item(1', 'item.a'])
+      ).not.toThrow();
     });
 
     it('should not throw on a pattern containing an unbalanced character class', () => {
       const patterns = [makeTemplateMatch('a[${i}')];
-      expect(() => resolveTemplatePatterns(patterns, ['a[0', 'ab'])).not.toThrow();
+      expect(() =>
+        resolveTemplatePatterns(patterns, ['a[0', 'ab'])
+      ).not.toThrow();
     });
 
     it('should match regex metacharacters in patterns literally', () => {
@@ -637,7 +743,11 @@ describe('sync-context', () => {
 
     it('should treat + and ? in patterns as literal characters', () => {
       const patterns = [makeTemplateMatch('count+?.${x}')];
-      const result = resolveTemplatePatterns(patterns, ['count+?.a', 'count.a', 'coun.a']);
+      const result = resolveTemplatePatterns(patterns, [
+        'count+?.a',
+        'count.a',
+        'coun.a',
+      ]);
       expect(result.has('count+?.a')).toBe(true);
       expect(result.has('count.a')).toBe(false);
       expect(result.has('coun.a')).toBe(false);
@@ -655,41 +765,57 @@ describe('sync-context', () => {
 
   describe('keyPathToContext', () => {
     it('should produce context for cta role', () => {
-      expect(keyPathToContext('pricing.free.cta')).toBe('Call-to-action in the pricing > free section.');
+      expect(keyPathToContext('pricing.free.cta')).toBe(
+        'Call-to-action in the pricing > free section.'
+      );
     });
 
     it('should produce context for title role', () => {
-      expect(keyPathToContext('nav.features.title')).toBe('Title in the nav > features section.');
+      expect(keyPathToContext('nav.features.title')).toBe(
+        'Title in the nav > features section.'
+      );
     });
 
     it('should produce context for heading role', () => {
-      expect(keyPathToContext('page.heading')).toBe('Heading in the page section.');
+      expect(keyPathToContext('page.heading')).toBe(
+        'Heading in the page section.'
+      );
     });
 
     it('should produce context for description role', () => {
       expect(keyPathToContext('settings.notifications.email.description')).toBe(
-        'Description in the settings > notifications > email section.',
+        'Description in the settings > notifications > email section.'
       );
     });
 
     it('should produce context for placeholder role', () => {
-      expect(keyPathToContext('form.name.placeholder')).toBe('Placeholder in the form > name section.');
+      expect(keyPathToContext('form.name.placeholder')).toBe(
+        'Placeholder in the form > name section.'
+      );
     });
 
     it('should produce context for tooltip role', () => {
-      expect(keyPathToContext('dashboard.tooltip')).toBe('Tooltip in the dashboard section.');
+      expect(keyPathToContext('dashboard.tooltip')).toBe(
+        'Tooltip in the dashboard section.'
+      );
     });
 
     it('should produce context for save role', () => {
-      expect(keyPathToContext('buttons.save')).toBe('Save action in the buttons section.');
+      expect(keyPathToContext('buttons.save')).toBe(
+        'Save action in the buttons section.'
+      );
     });
 
     it('should produce context for quote role', () => {
-      expect(keyPathToContext('testimonials.items.0.quote')).toBe('Quote in the testimonials > items section.');
+      expect(keyPathToContext('testimonials.items.0.quote')).toBe(
+        'Quote in the testimonials > items section.'
+      );
     });
 
     it('should handle compound segments with modifier suffix', () => {
-      expect(keyPathToContext('hero.cta_primary')).toBe('Primary call-to-action in the hero section.');
+      expect(keyPathToContext('hero.cta_primary')).toBe(
+        'Primary call-to-action in the hero section.'
+      );
     });
 
     it('should return empty string for single-segment key', () => {
@@ -701,19 +827,27 @@ describe('sync-context', () => {
     });
 
     it('should skip numeric segments in the section path', () => {
-      expect(keyPathToContext('items.0.label')).toBe('Label in the items section.');
+      expect(keyPathToContext('items.0.label')).toBe(
+        'Label in the items section.'
+      );
     });
 
     it('should handle deeply nested keys (4+ levels)', () => {
-      expect(keyPathToContext('a.b.c.d.title')).toBe('Title in the a > b > c > d section.');
+      expect(keyPathToContext('a.b.c.d.title')).toBe(
+        'Title in the a > b > c > d section.'
+      );
     });
 
     it('should capitalize unknown role segments', () => {
-      expect(keyPathToContext('errors.generic')).toBe('Generic in the errors section.');
+      expect(keyPathToContext('errors.generic')).toBe(
+        'Generic in the errors section.'
+      );
     });
 
     it('should handle underscored unknown segments', () => {
-      expect(keyPathToContext('settings.dark_mode')).toBe('Dark mode in the settings section.');
+      expect(keyPathToContext('settings.dark_mode')).toBe(
+        'Dark mode in the settings section.'
+      );
     });
 
     it('should return empty string for empty input', () => {
@@ -725,15 +859,21 @@ describe('sync-context', () => {
     });
 
     it('should produce context for two-segment key with known role', () => {
-      expect(keyPathToContext('nav.features')).toBe('Features in the nav section.');
+      expect(keyPathToContext('nav.features')).toBe(
+        'Features in the nav section.'
+      );
     });
 
     it('should honor NUL separator for YAML-style flattened keys', () => {
-      expect(keyPathToContext('nav\0features\0title')).toBe('Title in the nav > features section.');
+      expect(keyPathToContext('nav\0features\0title')).toBe(
+        'Title in the nav > features section.'
+      );
     });
 
     it('should treat a literal dot as part of a single NUL-separated segment', () => {
-      expect(keyPathToContext('app\0version.major')).toBe('Version.major in the app section.');
+      expect(keyPathToContext('app\0version.major')).toBe(
+        'Version.major in the app section.'
+      );
     });
   });
 
@@ -772,11 +912,15 @@ describe('sync-context', () => {
 
   describe('sectionToContext', () => {
     it('should format dot-separated section keys', () => {
-      expect(sectionToContext('nav.features')).toBe('Used in the nav > features section.');
+      expect(sectionToContext('nav.features')).toBe(
+        'Used in the nav > features section.'
+      );
     });
 
     it('should format NUL-separated section keys', () => {
-      expect(sectionToContext('nav\0features')).toBe('Used in the nav > features section.');
+      expect(sectionToContext('nav\0features')).toBe(
+        'Used in the nav > features section.'
+      );
     });
 
     it('should return empty string for empty section key', () => {
@@ -790,7 +934,9 @@ describe('sync-context', () => {
     });
 
     it('should extract h2 element with className', () => {
-      expect(extractElementType('<h2 className="heading">Title</h2>')).toBe('h2');
+      expect(extractElementType('<h2 className="heading">Title</h2>')).toBe(
+        'h2'
+      );
     });
 
     it('should extract th element', () => {
@@ -798,7 +944,9 @@ describe('sync-context', () => {
     });
 
     it('should extract self-closing input', () => {
-      expect(extractElementType('<input placeholder="search" />')).toBe('input');
+      expect(extractElementType('<input placeholder="search" />')).toBe(
+        'input'
+      );
     });
 
     it('should extract self-closing textarea', () => {
@@ -806,7 +954,11 @@ describe('sync-context', () => {
     });
 
     it('should extract button with complex JSX attributes', () => {
-      expect(extractElementType('<button onClick={handleClick} disabled={true}>Save</button>')).toBe('button');
+      expect(
+        extractElementType(
+          '<button onClick={handleClick} disabled={true}>Save</button>'
+        )
+      ).toBe('button');
     });
 
     it('should return null when no recognized element found', () => {
@@ -818,7 +970,9 @@ describe('sync-context', () => {
     });
 
     it('should return last match when multiple elements present', () => {
-      expect(extractElementType('<div><span>text</span><button>click</button></div>')).toBe('button');
+      expect(
+        extractElementType('<div><span>text</span><button>click</button></div>')
+      ).toBe('button');
     });
 
     it('should handle multiline JSX', () => {
@@ -827,7 +981,9 @@ describe('sync-context', () => {
     });
 
     it('should not match elements inside HTML comments', () => {
-      expect(extractElementType('<!-- <button>old</button> -->\n<div>content</div>')).toBeNull();
+      expect(
+        extractElementType('<!-- <button>old</button> -->\n<div>content</div>')
+      ).toBeNull();
     });
 
     it('should extract anchor element', () => {
diff --git a/tests/unit/sync/sync-differ-per-locale.test.ts b/tests/unit/sync/sync-differ-per-locale.test.ts
index e807a722..fc94f4d8 100644
--- a/tests/unit/sync/sync-differ-per-locale.test.ts
+++ b/tests/unit/sync/sync-differ-per-locale.test.ts
@@ -21,13 +21,18 @@ function entries(): ExtractedEntry[] {
   return [{ key: 'greeting', value: SOURCE }];
 }
 
-function lockEntry(translations: SyncLockEntry['translations']): Record<string, SyncLockEntry> {
+function lockEntry(
+  translations: SyncLockEntry['translations']
+): Record<string, SyncLockEntry> {
   return {
     greeting: { source_hash: CURRENT_HASH, source_text: SOURCE, translations },
   };
 }
 
-function translation(hash: string, status = 'translated'): SyncLockEntry['translations'][string] {
+function translation(
+  hash: string,
+  status = 'translated'
+): SyncLockEntry['translations'][string] {
   return {
     hash,
     status,
@@ -39,9 +44,12 @@ function translation(hash: string, status = 'translated'): SyncLockEntry['transl
 describe('computeDiff per-locale staleness', () => {
   it('should report a key as current when every locale is up to date', () => {
     const diffs = computeDiff(
-      lockEntry({ de: translation(CURRENT_HASH), fr: translation(CURRENT_HASH) }),
+      lockEntry({
+        de: translation(CURRENT_HASH),
+        fr: translation(CURRENT_HASH),
+      }),
       entries(),
-      ['de', 'fr'],
+      ['de', 'fr']
     );
 
     expect(diffs[0]?.status).toBe('current');
@@ -52,7 +60,7 @@ describe('computeDiff per-locale staleness', () => {
     const diffs = computeDiff(
       lockEntry({ de: translation(CURRENT_HASH), fr: translation(STALE_HASH) }),
       entries(),
-      ['de', 'fr'],
+      ['de', 'fr']
     );
 
     expect(diffs[0]?.status).toBe('stale');
@@ -62,19 +70,23 @@ describe('computeDiff per-locale staleness', () => {
     // A locale with no lockfile entry is a new target, promoted to `new` by
     // sync-process-bucket's hasNewLocale path so backfill is counted as new
     // keys rather than as drift. Marking it stale here would misreport it.
-    const diffs = computeDiff(lockEntry({ de: translation(CURRENT_HASH) }), entries(), [
-      'de',
-      'fr',
-    ]);
+    const diffs = computeDiff(
+      lockEntry({ de: translation(CURRENT_HASH) }),
+      entries(),
+      ['de', 'fr']
+    );
 
     expect(diffs[0]?.status).toBe('current');
   });
 
   it('should report a key as stale when a locale previously failed', () => {
     const diffs = computeDiff(
-      lockEntry({ de: translation(CURRENT_HASH), fr: translation(CURRENT_HASH, 'failed') }),
+      lockEntry({
+        de: translation(CURRENT_HASH),
+        fr: translation(CURRENT_HASH, 'failed'),
+      }),
       entries(),
-      ['de', 'fr'],
+      ['de', 'fr']
     );
 
     expect(diffs[0]?.status).toBe('stale');
@@ -86,7 +98,7 @@ describe('computeDiff per-locale staleness', () => {
     const diffs = computeDiff(
       lockEntry({ de: translation(CURRENT_HASH), es: translation(STALE_HASH) }),
       entries(),
-      ['de'],
+      ['de']
     );
 
     expect(diffs[0]?.status).toBe('current');
@@ -110,7 +122,7 @@ describe('computeDiff per-locale staleness', () => {
     // sync-status and other callers may omit the locale list.
     const diffs = computeDiff(
       lockEntry({ de: translation(CURRENT_HASH), fr: translation(STALE_HASH) }),
-      entries(),
+      entries()
     );
 
     expect(diffs[0]?.status).toBe('current');
diff --git a/tests/unit/sync/sync-differ.test.ts b/tests/unit/sync/sync-differ.test.ts
index 6a5dd0b8..d1434fbf 100644
--- a/tests/unit/sync/sync-differ.test.ts
+++ b/tests/unit/sync/sync-differ.test.ts
@@ -3,12 +3,16 @@ import { computeSourceHash } from '../../../src/sync/sync-lock';
 import type { SyncLockEntry } from '../../../src/sync/types';
 import type { ExtractedEntry } from '../../../src/formats/format';
 
-function makeLockEntry(value: string, translations: Record<string, string> = {}): SyncLockEntry {
+function makeLockEntry(
+  value: string,
+  translations: Record<string, string> = {}
+): SyncLockEntry {
   const translationEntries: SyncLockEntry['translations'] = {};
   for (const [locale, hash] of Object.entries(translations)) {
     translationEntries[locale] = {
       hash,
-      translated_at: '2026-01-01T00:00:00.000Z', status: 'translated',
+      translated_at: '2026-01-01T00:00:00.000Z',
+      status: 'translated',
     };
   }
   return {
@@ -48,7 +52,9 @@ describe('computeDiff()', () => {
     const lock: Record<string, SyncLockEntry> = {
       greeting: makeLockEntry('Hello'),
     };
-    const current: ExtractedEntry[] = [{ key: 'greeting', value: 'Hello World' }];
+    const current: ExtractedEntry[] = [
+      { key: 'greeting', value: 'Hello World' },
+    ];
     const result = computeDiff(lock, current);
     expect(result).toHaveLength(1);
     expect(result[0]!.status).toBe('stale');
@@ -136,7 +142,7 @@ describe('computeDiff()', () => {
 
   it('should handle unicode keys and values', () => {
     const lock: Record<string, SyncLockEntry> = {
-      'こんにちは': makeLockEntry('日本語'),
+      こんにちは: makeLockEntry('日本語'),
     };
     const current: ExtractedEntry[] = [{ key: 'こんにちは', value: '日本語' }];
     const result = computeDiff(lock, current);
@@ -158,14 +164,20 @@ describe('computeDiff()', () => {
       stale_key: makeLockEntry('old value'),
     };
     const current: ExtractedEntry[] = [
-      { key: 'new_key', value: 'Hello', metadata: { description: 'A greeting' } },
+      {
+        key: 'new_key',
+        value: 'Hello',
+        metadata: { description: 'A greeting' },
+      },
       { key: 'stale_key', value: 'changed', metadata: { maxLength: 100 } },
       { key: 'no_meta', value: 'plain' },
     ];
     const result = computeDiff(lock, current);
-    const byKey = new Map(result.map(d => [d.key, d]));
+    const byKey = new Map(result.map((d) => [d.key, d]));
 
-    expect(byKey.get('new_key')!.metadata).toEqual({ description: 'A greeting' });
+    expect(byKey.get('new_key')!.metadata).toEqual({
+      description: 'A greeting',
+    });
     expect(byKey.get('stale_key')!.metadata).toEqual({ maxLength: 100 });
     expect(byKey.get('no_meta')!.metadata).toBeUndefined();
   });
@@ -176,8 +188,16 @@ describe('computeDiff()', () => {
         source_hash: computeSourceHash('Hello'),
         source_text: 'Hello',
         translations: {
-          de: { hash: computeSourceHash('Hello'), translated_at: '2026-01-01T00:00:00.000Z', status: 'translated' },
-          fr: { hash: computeSourceHash('Hello'), translated_at: '2026-01-01T00:00:00.000Z', status: 'failed' },
+          de: {
+            hash: computeSourceHash('Hello'),
+            translated_at: '2026-01-01T00:00:00.000Z',
+            status: 'translated',
+          },
+          fr: {
+            hash: computeSourceHash('Hello'),
+            translated_at: '2026-01-01T00:00:00.000Z',
+            status: 'failed',
+          },
         },
       },
     };
@@ -192,21 +212,33 @@ describe('computeDiff()', () => {
     const lock: Record<string, SyncLockEntry> = {
       item_count: {
         source_hash: computeSourceHash('%d items', {
-          plurals: [{ quantity: 'one', value: '1 item' }, { quantity: 'other', value: '%d items' }],
+          plurals: [
+            { quantity: 'one', value: '1 item' },
+            { quantity: 'other', value: '%d items' },
+          ],
         }),
         source_text: '%d items',
         translations: {
-          de: { hash: 'abc', translated_at: '2026-01-01T00:00:00.000Z', status: 'translated' },
+          de: {
+            hash: 'abc',
+            translated_at: '2026-01-01T00:00:00.000Z',
+            status: 'translated',
+          },
         },
       },
     };
-    const current: ExtractedEntry[] = [{
-      key: 'item_count',
-      value: '%d items',
-      metadata: {
-        plurals: [{ quantity: 'one', value: '1 thing' }, { quantity: 'other', value: '%d items' }],
+    const current: ExtractedEntry[] = [
+      {
+        key: 'item_count',
+        value: '%d items',
+        metadata: {
+          plurals: [
+            { quantity: 'one', value: '1 thing' },
+            { quantity: 'other', value: '%d items' },
+          ],
+        },
       },
-    }];
+    ];
     const result = computeDiff(lock, current);
     expect(result).toHaveLength(1);
     expect(result[0]!.status).toBe('stale');
@@ -214,24 +246,36 @@ describe('computeDiff()', () => {
 
   it('should mark entry as current when primary and plural metadata are unchanged', () => {
     const metadata = {
-      plurals: [{ quantity: 'one', value: '1 item' }, { quantity: 'other', value: '%d items' }],
+      plurals: [
+        { quantity: 'one', value: '1 item' },
+        { quantity: 'other', value: '%d items' },
+      ],
     };
     const lock: Record<string, SyncLockEntry> = {
       item_count: {
         source_hash: computeSourceHash('%d items', metadata),
         source_text: '%d items',
         translations: {
-          de: { hash: 'abc', translated_at: '2026-01-01T00:00:00.000Z', status: 'translated' },
+          de: {
+            hash: 'abc',
+            translated_at: '2026-01-01T00:00:00.000Z',
+            status: 'translated',
+          },
         },
       },
     };
-    const current: ExtractedEntry[] = [{
-      key: 'item_count',
-      value: '%d items',
-      metadata: {
-        plurals: [{ quantity: 'one', value: '1 item' }, { quantity: 'other', value: '%d items' }],
+    const current: ExtractedEntry[] = [
+      {
+        key: 'item_count',
+        value: '%d items',
+        metadata: {
+          plurals: [
+            { quantity: 'one', value: '1 item' },
+            { quantity: 'other', value: '%d items' },
+          ],
+        },
       },
-    }];
+    ];
     const result = computeDiff(lock, current);
     expect(result).toHaveLength(1);
     expect(result[0]!.status).toBe('current');
diff --git a/tests/unit/sync/sync-export.test.ts b/tests/unit/sync/sync-export.test.ts
index 58b37d7e..1597e99e 100644
--- a/tests/unit/sync/sync-export.test.ts
+++ b/tests/unit/sync/sync-export.test.ts
@@ -18,9 +18,13 @@ jest.mock('fs', () => {
 });
 
 const mockedFg = fg as jest.MockedFunction<typeof fg>;
-const mockedReadFile = fs.promises.readFile as jest.MockedFunction<typeof fs.promises.readFile>;
+const mockedReadFile = fs.promises.readFile as jest.MockedFunction<
+  typeof fs.promises.readFile
+>;
 
-function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+function makeConfig(
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -50,7 +54,9 @@ describe('exportTranslations()', () => {
 
   it('should produce valid XLIFF with trans-unit elements containing source text', async () => {
     mockedFg.mockResolvedValue(['/project/locales/en/common.json'] as never);
-    mockedReadFile.mockResolvedValue(JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }));
+    mockedReadFile.mockResolvedValue(
+      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' })
+    );
 
     const result = await exportTranslations(makeConfig(), makeRegistry());
 
@@ -68,7 +74,9 @@ describe('exportTranslations()', () => {
 
     const result = await exportTranslations(makeConfig(), makeRegistry());
 
-    expect(result.content).toContain('<note from="location">locales/en/common.json</note>');
+    expect(result.content).toContain(
+      '<note from="location">locales/en/common.json</note>'
+    );
   });
 
   it('should respect locale filter (only generates <file> for filtered locales)', async () => {
diff --git a/tests/unit/sync/sync-finalize-failure.test.ts b/tests/unit/sync/sync-finalize-failure.test.ts
index 4585a035..81173604 100644
--- a/tests/unit/sync/sync-finalize-failure.test.ts
+++ b/tests/unit/sync/sync-finalize-failure.test.ts
@@ -74,7 +74,13 @@ describe('finalizeSyncResult failure reporting', () => {
   it('should report success when a locale had nothing to do', () => {
     // translated 0 with no failures is an up-to-date locale, not a failure.
     const result = finalize([
-      fileResult({ locale: 'de', translated: 0, failed: 0, skipped: 2, written: false }),
+      fileResult({
+        locale: 'de',
+        translated: 0,
+        failed: 0,
+        skipped: 2,
+        written: false,
+      }),
       fileResult({ locale: 'fr', translated: 2, written: true }),
     ]);
 
diff --git a/tests/unit/sync/sync-glossary-report.test.ts b/tests/unit/sync/sync-glossary-report.test.ts
index a6b0765d..12218e35 100644
--- a/tests/unit/sync/sync-glossary-report.test.ts
+++ b/tests/unit/sync/sync-glossary-report.test.ts
@@ -9,16 +9,24 @@ function makeLockFile(entries: SyncLockFile['entries'] = {}): SyncLockFile {
     generated_at: '2026-01-01T00:00:00Z',
     source_locale: 'en',
     entries,
-    stats: { total_keys: 0, total_translations: 0, last_sync: '2026-01-01T00:00:00Z' },
+    stats: {
+      total_keys: 0,
+      total_translations: 0,
+      last_sync: '2026-01-01T00:00:00Z',
+    },
   };
 }
 
 function translated(hash: string) {
-  return { hash, translated_at: '2026-01-01T00:00:00Z', status: 'translated' as const };
+  return {
+    hash,
+    translated_at: '2026-01-01T00:00:00Z',
+    status: 'translated' as const,
+  };
 }
 
 function index(
-  spec: Record<string, Record<string, Record<string, string>>>,
+  spec: Record<string, Record<string, Record<string, string>>>
 ): TargetTranslationIndex {
   const result: TargetTranslationIndex = new Map();
   for (const [file, locales] of Object.entries(spec)) {
@@ -35,10 +43,18 @@ describe('generateGlossaryReport()', () => {
   it('should report no inconsistencies when the same source text is translated identically', () => {
     const lock = makeLockFile({
       'en/common.json': {
-        greeting: { source_hash: 'abc123', source_text: 'Hello', translations: { de: translated('h1') } },
+        greeting: {
+          source_hash: 'abc123',
+          source_text: 'Hello',
+          translations: { de: translated('h1') },
+        },
       },
       'en/other.json': {
-        greeting2: { source_hash: 'abc123', source_text: 'Hello', translations: { de: translated('h1') } },
+        greeting2: {
+          source_hash: 'abc123',
+          source_text: 'Hello',
+          translations: { de: translated('h1') },
+        },
       },
     });
 
@@ -47,7 +63,7 @@ describe('generateGlossaryReport()', () => {
       index({
         'en/common.json': { de: { greeting: 'Hallo' } },
         'en/other.json': { de: { greeting2: 'Hallo' } },
-      }),
+      })
     );
 
     expect(report.totalTerms).toBe(1);
@@ -58,10 +74,18 @@ describe('generateGlossaryReport()', () => {
   it('should detect an inconsistency when the same source text has different translations', () => {
     const lock = makeLockFile({
       'en/common.json': {
-        greeting: { source_hash: 'abc123', source_text: 'Hello', translations: { de: translated('h1') } },
+        greeting: {
+          source_hash: 'abc123',
+          source_text: 'Hello',
+          translations: { de: translated('h1') },
+        },
       },
       'en/other.json': {
-        welcome: { source_hash: 'abc123', source_text: 'Hello', translations: { de: translated('h1') } },
+        welcome: {
+          source_hash: 'abc123',
+          source_text: 'Hello',
+          translations: { de: translated('h1') },
+        },
       },
     });
 
@@ -70,7 +94,7 @@ describe('generateGlossaryReport()', () => {
       index({
         'en/common.json': { de: { greeting: 'Hallo' } },
         'en/other.json': { de: { welcome: 'Guten Tag' } },
-      }),
+      })
     );
 
     expect(report.inconsistencies).toHaveLength(1);
@@ -93,13 +117,25 @@ describe('generateGlossaryReport()', () => {
   it('should populate files array correctly for multiple files with same source text', () => {
     const lock = makeLockFile({
       'file-a.json': {
-        key1: { source_hash: 'h1', source_text: 'Save', translations: { de: translated('h') } },
+        key1: {
+          source_hash: 'h1',
+          source_text: 'Save',
+          translations: { de: translated('h') },
+        },
       },
       'file-b.json': {
-        key2: { source_hash: 'h1', source_text: 'Save', translations: { de: translated('h') } },
+        key2: {
+          source_hash: 'h1',
+          source_text: 'Save',
+          translations: { de: translated('h') },
+        },
       },
       'file-c.json': {
-        key3: { source_hash: 'h1', source_text: 'Save', translations: { de: translated('h') } },
+        key3: {
+          source_hash: 'h1',
+          source_text: 'Save',
+          translations: { de: translated('h') },
+        },
       },
     });
 
@@ -109,13 +145,13 @@ describe('generateGlossaryReport()', () => {
         'file-a.json': { de: { key1: 'Speichern' } },
         'file-b.json': { de: { key2: 'Speichern' } },
         'file-c.json': { de: { key3: 'Sichern' } },
-      }),
+      })
     );
 
     expect(report.totalTerms).toBe(1);
     expect(report.inconsistencies).toHaveLength(1);
     expect(report.inconsistencies[0]!.files).toEqual(
-      expect.arrayContaining(['file-a.json', 'file-b.json', 'file-c.json']),
+      expect.arrayContaining(['file-a.json', 'file-b.json', 'file-c.json'])
     );
     expect(report.inconsistencies[0]!.files).toHaveLength(3);
   });
@@ -123,10 +159,18 @@ describe('generateGlossaryReport()', () => {
   it('surfaces actual translated text (not hashes) when a target-translation index is provided', () => {
     const lock = makeLockFile({
       'en/common.json': {
-        greeting: { source_hash: 'h', source_text: 'Dashboard', translations: { de: translated('de-v1') } },
+        greeting: {
+          source_hash: 'h',
+          source_text: 'Dashboard',
+          translations: { de: translated('de-v1') },
+        },
       },
       'en/admin.json': {
-        header: { source_hash: 'h', source_text: 'Dashboard', translations: { de: translated('de-v2') } },
+        header: {
+          source_hash: 'h',
+          source_text: 'Dashboard',
+          translations: { de: translated('de-v2') },
+        },
       },
     });
 
@@ -135,14 +179,16 @@ describe('generateGlossaryReport()', () => {
       index({
         'en/common.json': { de: { greeting: 'Armaturenbrett' } },
         'en/admin.json': { de: { header: 'Dashboard' } },
-      }),
+      })
     );
 
     expect(report.inconsistencies).toHaveLength(1);
     const inc = report.inconsistencies[0]!;
     expect(inc.sourceText).toBe('Dashboard');
     expect(inc.locale).toBe('de');
-    expect(inc.translations).toEqual(expect.arrayContaining(['Armaturenbrett', 'Dashboard']));
+    expect(inc.translations).toEqual(
+      expect.arrayContaining(['Armaturenbrett', 'Dashboard'])
+    );
     expect(inc.translations).not.toContain('de-v1');
     expect(inc.translations).not.toContain('de-v2');
   });
@@ -151,48 +197,86 @@ describe('generateGlossaryReport()', () => {
     it('reports a missing locale file instead of inventing an inconsistency', () => {
       const lock = makeLockFile({
         'en/common.json': {
-          greeting: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('de-hashA') } },
+          greeting: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('de-hashA') },
+          },
         },
         'en/other.json': {
-          greeting2: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('de-hashB') } },
+          greeting2: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('de-hashB') },
+          },
         },
       });
 
       // en/other.json has no de file yet.
       const report = generateGlossaryReport(
         lock,
-        index({ 'en/common.json': { de: { greeting: 'Hallo' } } }),
+        index({ 'en/common.json': { de: { greeting: 'Hallo' } } })
       );
 
       expect(report.inconsistencies).toHaveLength(0);
-      expect(report.missingTargets).toEqual([{ filePath: 'en/other.json', locale: 'de' }]);
+      expect(report.missingTargets).toEqual([
+        { filePath: 'en/other.json', locale: 'de' },
+      ]);
     });
 
     it('never emits a lock hash as a translation string', () => {
       const lock = makeLockFile({
         'en/common.json': {
-          greeting: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('de-hashA') } },
+          greeting: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('de-hashA') },
+          },
         },
         'en/other.json': {
-          greeting2: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('de-hashB') } },
+          greeting2: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('de-hashB') },
+          },
         },
       });
 
       const report = generateGlossaryReport(
         lock,
-        index({ 'en/common.json': { de: { greeting: 'Hallo' } } }),
+        index({ 'en/common.json': { de: { greeting: 'Hallo' } } })
       );
 
-      const allTranslations = report.inconsistencies.flatMap(inc => inc.translations);
+      const allTranslations = report.inconsistencies.flatMap(
+        (inc) => inc.translations
+      );
       expect(allTranslations).not.toContain('de-hashA');
       expect(allTranslations).not.toContain('de-hashB');
     });
 
     it('still detects divergence among the readable targets of a group', () => {
       const lock = makeLockFile({
-        'a.json': { k1: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('x') } } },
-        'b.json': { k2: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('x') } } },
-        'c.json': { k3: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('x') } } },
+        'a.json': {
+          k1: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('x') },
+          },
+        },
+        'b.json': {
+          k2: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('x') },
+          },
+        },
+        'c.json': {
+          k3: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('x') },
+          },
+        },
       });
 
       const report = generateGlossaryReport(
@@ -200,22 +284,32 @@ describe('generateGlossaryReport()', () => {
         index({
           'a.json': { de: { k1: 'Hallo' } },
           'b.json': { de: { k2: 'Servus' } },
-        }),
+        })
       );
 
       expect(report.inconsistencies).toHaveLength(1);
       expect(report.inconsistencies[0]!.translations).toEqual(
-        expect.arrayContaining(['Hallo', 'Servus']),
+        expect.arrayContaining(['Hallo', 'Servus'])
       );
       expect(report.inconsistencies[0]!.files).toEqual(['a.json', 'b.json']);
-      expect(report.missingTargets).toEqual([{ filePath: 'c.json', locale: 'de' }]);
+      expect(report.missingTargets).toEqual([
+        { filePath: 'c.json', locale: 'de' },
+      ]);
     });
 
     it('reports every unreadable target once per file and locale', () => {
       const lock = makeLockFile({
         'a.json': {
-          k1: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('x'), fr: translated('x') } },
-          k2: { source_hash: 'h2', source_text: 'Bye', translations: { de: translated('y') } },
+          k1: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('x'), fr: translated('x') },
+          },
+          k2: {
+            source_hash: 'h2',
+            source_text: 'Bye',
+            translations: { de: translated('y') },
+          },
         },
       });
 
@@ -229,8 +323,20 @@ describe('generateGlossaryReport()', () => {
 
     it('treats an omitted index as every target being unreadable', () => {
       const lock = makeLockFile({
-        'a.json': { k1: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('x') } } },
-        'b.json': { k2: { source_hash: 'h', source_text: 'Hi', translations: { de: translated('y') } } },
+        'a.json': {
+          k1: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('x') },
+          },
+        },
+        'b.json': {
+          k2: {
+            source_hash: 'h',
+            source_text: 'Hi',
+            translations: { de: translated('y') },
+          },
+        },
       });
 
       const report = generateGlossaryReport(lock);
@@ -243,17 +349,35 @@ describe('generateGlossaryReport()', () => {
   it('should count different source texts separately in totalTerms', () => {
     const lock = makeLockFile({
       'en/common.json': {
-        greeting: { source_hash: 'h1', source_text: 'Hello', translations: { de: translated('hash1') } },
-        farewell: { source_hash: 'h2', source_text: 'Goodbye', translations: { de: translated('hash2') } },
-        save: { source_hash: 'h3', source_text: 'Save', translations: { de: translated('hash3') } },
+        greeting: {
+          source_hash: 'h1',
+          source_text: 'Hello',
+          translations: { de: translated('hash1') },
+        },
+        farewell: {
+          source_hash: 'h2',
+          source_text: 'Goodbye',
+          translations: { de: translated('hash2') },
+        },
+        save: {
+          source_hash: 'h3',
+          source_text: 'Save',
+          translations: { de: translated('hash3') },
+        },
       },
     });
 
     const report = generateGlossaryReport(
       lock,
       index({
-        'en/common.json': { de: { greeting: 'Hallo', farewell: 'Auf Wiedersehen', save: 'Speichern' } },
-      }),
+        'en/common.json': {
+          de: {
+            greeting: 'Hallo',
+            farewell: 'Auf Wiedersehen',
+            save: 'Speichern',
+          },
+        },
+      })
     );
 
     expect(report.totalTerms).toBe(3);
@@ -266,7 +390,13 @@ describe('generateGlossaryReport()', () => {
         k1: {
           source_hash: 'h',
           source_text: 'Hi',
-          translations: { de: { hash: 'x', translated_at: '2026-01-01T00:00:00Z', status: 'pending' } },
+          translations: {
+            de: {
+              hash: 'x',
+              translated_at: '2026-01-01T00:00:00Z',
+              status: 'pending',
+            },
+          },
         },
       },
     });
diff --git a/tests/unit/sync/sync-glossary.test.ts b/tests/unit/sync/sync-glossary.test.ts
index b0bf1bee..ce03fc54 100644
--- a/tests/unit/sync/sync-glossary.test.ts
+++ b/tests/unit/sync/sync-glossary.test.ts
@@ -10,7 +10,11 @@ function roundTrip(entries: Record<string, string>): Record<string, string> {
   return GlossaryService.tsvToEntries(GlossaryService.entriesToTSV(entries));
 }
 
-function repeated(source: string, target: string, prefix: string): {
+function repeated(
+  source: string,
+  target: string,
+  prefix: string
+): {
   sourceEntries: Map<string, string>;
   localeEntries: Map<string, string>;
 } {
@@ -24,9 +28,10 @@ function repeated(source: string, target: string, prefix: string): {
 }
 
 describe('SyncGlossaryManager', () => {
-  function createManager(
-    overrides: Partial<SyncGlossaryManagerOptions> = {},
-  ): { manager: SyncGlossaryManager; glossaryService: ReturnType<typeof createMockGlossaryService> } {
+  function createManager(overrides: Partial<SyncGlossaryManagerOptions> = {}): {
+    manager: SyncGlossaryManager;
+    glossaryService: ReturnType<typeof createMockGlossaryService>;
+  } {
     const glossaryService = createMockGlossaryService();
     const manager = new SyncGlossaryManager({
       sourceLocale: 'en',
@@ -48,11 +53,14 @@ describe('SyncGlossaryManager', () => {
       ]);
 
       const targetEntries = new Map([
-        ['de', new Map([
-          ['page.title', 'Speichern'],
-          ['dialog.ok', 'Speichern'],
-          ['menu.save', 'Speichern'],
-        ])],
+        [
+          'de',
+          new Map([
+            ['page.title', 'Speichern'],
+            ['dialog.ok', 'Speichern'],
+            ['menu.save', 'Speichern'],
+          ]),
+        ],
       ]);
 
       const result = manager.extractTerms(sourceEntries, targetEntries);
@@ -70,11 +78,14 @@ describe('SyncGlossaryManager', () => {
       ]);
 
       const targetEntries = new Map([
-        ['de', new Map([
-          ['key1', 'Öffnen'],
-          ['key2', 'Offen'],
-          ['key3', 'Öffnen'],
-        ])],
+        [
+          'de',
+          new Map([
+            ['key1', 'Öffnen'],
+            ['key2', 'Offen'],
+            ['key3', 'Öffnen'],
+          ]),
+        ],
       ]);
 
       const result = manager.extractTerms(sourceEntries, targetEntries);
@@ -93,11 +104,14 @@ describe('SyncGlossaryManager', () => {
       ]);
 
       const targetEntries = new Map([
-        ['de', new Map([
-          ['key1', 'Lang'],
-          ['key2', 'Lang'],
-          ['key3', 'Lang'],
-        ])],
+        [
+          'de',
+          new Map([
+            ['key1', 'Lang'],
+            ['key2', 'Lang'],
+            ['key3', 'Lang'],
+          ]),
+        ],
       ]);
 
       const result = manager.extractTerms(sourceEntries, targetEntries);
@@ -123,16 +137,22 @@ describe('SyncGlossaryManager', () => {
       ]);
 
       const targetEntries = new Map([
-        ['de', new Map([
-          ['a', 'Ja'],
-          ['b', 'Ja'],
-          ['c', 'Ja'],
-        ])],
-        ['fr', new Map([
-          ['a', 'Oui'],
-          ['b', 'Oui'],
-          ['c', 'Oui'],
-        ])],
+        [
+          'de',
+          new Map([
+            ['a', 'Ja'],
+            ['b', 'Ja'],
+            ['c', 'Ja'],
+          ]),
+        ],
+        [
+          'fr',
+          new Map([
+            ['a', 'Oui'],
+            ['b', 'Oui'],
+            ['c', 'Oui'],
+          ]),
+        ],
       ]);
 
       const result = manager.extractTerms(sourceEntries, targetEntries);
@@ -157,7 +177,10 @@ describe('SyncGlossaryManager', () => {
       const { manager } = createManager();
       const { sourceEntries, localeEntries } = repeated('OK', '', 'k');
 
-      const result = manager.extractTerms(sourceEntries, new Map([['de', localeEntries]]));
+      const result = manager.extractTerms(
+        sourceEntries,
+        new Map([['de', localeEntries]])
+      );
 
       expect(result.has('de')).toBe(false);
       expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('k0'));
@@ -167,7 +190,10 @@ describe('SyncGlossaryManager', () => {
       const { manager } = createManager();
       const { sourceEntries, localeEntries } = repeated('OK', '   ', 'k');
 
-      const result = manager.extractTerms(sourceEntries, new Map([['de', localeEntries]]));
+      const result = manager.extractTerms(
+        sourceEntries,
+        new Map([['de', localeEntries]])
+      );
 
       expect(result.has('de')).toBe(false);
     });
@@ -176,16 +202,26 @@ describe('SyncGlossaryManager', () => {
       const { manager } = createManager();
       const { sourceEntries, localeEntries } = repeated('', 'Leer', 'k');
 
-      const result = manager.extractTerms(sourceEntries, new Map([['de', localeEntries]]));
+      const result = manager.extractTerms(
+        sourceEntries,
+        new Map([['de', localeEntries]])
+      );
 
       expect(result.has('de')).toBe(false);
     });
 
     it('should skip a term whose source contains a tab', () => {
       const { manager } = createManager();
-      const { sourceEntries, localeEntries } = repeated('Col\tumn', 'Spalte', 'k');
+      const { sourceEntries, localeEntries } = repeated(
+        'Col\tumn',
+        'Spalte',
+        'k'
+      );
 
-      const result = manager.extractTerms(sourceEntries, new Map([['de', localeEntries]]));
+      const result = manager.extractTerms(
+        sourceEntries,
+        new Map([['de', localeEntries]])
+      );
 
       expect(result.has('de')).toBe(false);
       expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('k0'));
@@ -196,10 +232,13 @@ describe('SyncGlossaryManager', () => {
       const { sourceEntries, localeEntries } = repeated(
         'Are you sure?\nThis cannot be undone.',
         'Sicher?',
-        'k',
+        'k'
       );
 
-      const result = manager.extractTerms(sourceEntries, new Map([['de', localeEntries]]));
+      const result = manager.extractTerms(
+        sourceEntries,
+        new Map([['de', localeEntries]])
+      );
 
       expect(result.has('de')).toBe(false);
     });
@@ -209,10 +248,19 @@ describe('SyncGlossaryManager', () => {
       const withNewline = repeated('Save', 'Spei\nchern', 'a');
       const withCr = repeated('Open', 'Öff\rnen', 'b');
 
-      const sourceEntries = new Map([...withNewline.sourceEntries, ...withCr.sourceEntries]);
-      const localeEntries = new Map([...withNewline.localeEntries, ...withCr.localeEntries]);
+      const sourceEntries = new Map([
+        ...withNewline.sourceEntries,
+        ...withCr.sourceEntries,
+      ]);
+      const localeEntries = new Map([
+        ...withNewline.localeEntries,
+        ...withCr.localeEntries,
+      ]);
 
-      const result = manager.extractTerms(sourceEntries, new Map([['de', localeEntries]]));
+      const result = manager.extractTerms(
+        sourceEntries,
+        new Map([['de', localeEntries]])
+      );
 
       expect(result.has('de')).toBe(false);
     });
@@ -222,10 +270,19 @@ describe('SyncGlossaryManager', () => {
       const clean = repeated('Save', 'Speichern', 'a');
       const dirty = repeated('Bad\tterm', 'Schlecht', 'b');
 
-      const sourceEntries = new Map([...clean.sourceEntries, ...dirty.sourceEntries]);
-      const localeEntries = new Map([...clean.localeEntries, ...dirty.localeEntries]);
+      const sourceEntries = new Map([
+        ...clean.sourceEntries,
+        ...dirty.sourceEntries,
+      ]);
+      const localeEntries = new Map([
+        ...clean.localeEntries,
+        ...dirty.localeEntries,
+      ]);
 
-      const result = manager.extractTerms(sourceEntries, new Map([['de', localeEntries]]));
+      const result = manager.extractTerms(
+        sourceEntries,
+        new Map([['de', localeEntries]])
+      );
 
       expect(result.get('de')).toEqual({ Save: 'Speichern' });
     });
@@ -233,7 +290,9 @@ describe('SyncGlossaryManager', () => {
 
   describe('syncGlossaries', () => {
     it('should create new glossary when none exists', async () => {
-      const { manager, glossaryService } = createManager({ targetLocales: ['de'] });
+      const { manager, glossaryService } = createManager({
+        targetLocales: ['de'],
+      });
 
       glossaryService.getGlossaryByName.mockResolvedValue(null);
       glossaryService.createGlossary.mockResolvedValue({
@@ -241,7 +300,9 @@ describe('SyncGlossaryManager', () => {
         name: 'deepl-sync-en-de',
         source_lang: 'en',
         target_langs: ['de'],
-        dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 1 }],
+        dictionaries: [
+          { source_lang: 'en', target_lang: 'de', entry_count: 1 },
+        ],
         creation_time: '2026-01-01T00:00:00Z',
       });
 
@@ -251,7 +312,14 @@ describe('SyncGlossaryManager', () => {
         ['k3', 'OK'],
       ]);
       const targetEntries = new Map([
-        ['de', new Map([['k1', 'OK'], ['k2', 'OK'], ['k3', 'OK']])],
+        [
+          'de',
+          new Map([
+            ['k1', 'OK'],
+            ['k2', 'OK'],
+            ['k3', 'OK'],
+          ]),
+        ],
       ]);
 
       const result = await manager.syncGlossaries(sourceEntries, targetEntries);
@@ -260,20 +328,24 @@ describe('SyncGlossaryManager', () => {
         'deepl-sync-en-de',
         'en',
         ['de'],
-        { OK: 'OK' },
+        { OK: 'OK' }
       );
       expect(result).toEqual({ 'en-de': 'new-id-1' });
     });
 
     it('should update existing glossary with new terms', async () => {
-      const { manager, glossaryService } = createManager({ targetLocales: ['de'] });
+      const { manager, glossaryService } = createManager({
+        targetLocales: ['de'],
+      });
 
       glossaryService.getGlossaryByName.mockResolvedValue({
         glossary_id: 'existing-id',
         name: 'deepl-sync-en-de',
         source_lang: 'en',
         target_langs: ['de'],
-        dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 1 }],
+        dictionaries: [
+          { source_lang: 'en', target_lang: 'de', entry_count: 1 },
+        ],
         creation_time: '2026-01-01T00:00:00Z',
       });
       glossaryService.getGlossaryEntries.mockResolvedValue({ Hello: 'Hallo' });
@@ -287,14 +359,17 @@ describe('SyncGlossaryManager', () => {
         ['k6', 'Save'],
       ]);
       const targetEntries = new Map([
-        ['de', new Map([
-          ['k1', 'Hallo'],
-          ['k2', 'Hallo'],
-          ['k3', 'Hallo'],
-          ['k4', 'Speichern'],
-          ['k5', 'Speichern'],
-          ['k6', 'Speichern'],
-        ])],
+        [
+          'de',
+          new Map([
+            ['k1', 'Hallo'],
+            ['k2', 'Hallo'],
+            ['k3', 'Hallo'],
+            ['k4', 'Speichern'],
+            ['k5', 'Speichern'],
+            ['k6', 'Speichern'],
+          ]),
+        ],
       ]);
 
       const result = await manager.syncGlossaries(sourceEntries, targetEntries);
@@ -303,12 +378,14 @@ describe('SyncGlossaryManager', () => {
       expect(glossaryService.updateGlossary).toHaveBeenCalledWith(
         'existing-id',
         {
-          dictionaries: [{
-            sourceLang: 'en',
-            targetLang: 'de',
-            entries: { Hello: 'Hallo', Save: 'Speichern' },
-          }],
-        },
+          dictionaries: [
+            {
+              sourceLang: 'en',
+              targetLang: 'de',
+              entries: { Hello: 'Hallo', Save: 'Speichern' },
+            },
+          ],
+        }
       );
       expect(glossaryService.addEntry).not.toHaveBeenCalled();
       expect(glossaryService.removeEntry).not.toHaveBeenCalled();
@@ -316,14 +393,18 @@ describe('SyncGlossaryManager', () => {
     });
 
     it('issues a single batched dictionary update per locale regardless of add/remove count', async () => {
-      const { manager, glossaryService } = createManager({ targetLocales: ['de'] });
+      const { manager, glossaryService } = createManager({
+        targetLocales: ['de'],
+      });
 
       glossaryService.getGlossaryByName.mockResolvedValue({
         glossary_id: 'existing-id',
         name: 'deepl-sync-en-de',
         source_lang: 'en',
         target_langs: ['de'],
-        dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 5 }],
+        dictionaries: [
+          { source_lang: 'en', target_lang: 'de', entry_count: 5 },
+        ],
         creation_time: '2026-01-01T00:00:00Z',
       });
 
@@ -336,10 +417,10 @@ describe('SyncGlossaryManager', () => {
       };
       glossaryService.getGlossaryEntries.mockResolvedValue(obsolete);
 
-      const newTerms: Array<[string, string]> = Array.from({ length: 10 }, (_, i) => [
-        `Term${i}`,
-        `Term${i}DE`,
-      ]);
+      const newTerms: Array<[string, string]> = Array.from(
+        { length: 10 },
+        (_, i) => [`Term${i}`, `Term${i}DE`]
+      );
 
       const sourceEntries = new Map<string, string>();
       const deLocale = new Map<string, string>();
@@ -358,25 +439,38 @@ describe('SyncGlossaryManager', () => {
       expect(glossaryService.addEntry).not.toHaveBeenCalled();
       expect(glossaryService.removeEntry).not.toHaveBeenCalled();
       expect(glossaryService.updateGlossary).toHaveBeenCalledTimes(1);
-      const [, payload] = glossaryService.updateGlossary.mock.calls[0] as [string, {
-        dictionaries: Array<{ sourceLang: string; targetLang: string; entries: Record<string, string> }>;
-      }];
+      const [, payload] = glossaryService.updateGlossary.mock.calls[0] as [
+        string,
+        {
+          dictionaries: Array<{
+            sourceLang: string;
+            targetLang: string;
+            entries: Record<string, string>;
+          }>;
+        },
+      ];
       expect(payload.dictionaries).toHaveLength(1);
-      expect(payload.dictionaries[0]?.entries).toEqual(Object.fromEntries(newTerms));
+      expect(payload.dictionaries[0]?.entries).toEqual(
+        Object.fromEntries(newTerms)
+      );
       for (const stale of Object.keys(obsolete)) {
         expect(payload.dictionaries[0]?.entries[stale]).toBeUndefined();
       }
     });
 
     it('skips the dictionary update call when the target terms are identical to current entries', async () => {
-      const { manager, glossaryService } = createManager({ targetLocales: ['de'] });
+      const { manager, glossaryService } = createManager({
+        targetLocales: ['de'],
+      });
 
       glossaryService.getGlossaryByName.mockResolvedValue({
         glossary_id: 'existing-id',
         name: 'deepl-sync-en-de',
         source_lang: 'en',
         target_langs: ['de'],
-        dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 1 }],
+        dictionaries: [
+          { source_lang: 'en', target_lang: 'de', entry_count: 1 },
+        ],
         creation_time: '2026-01-01T00:00:00Z',
       });
       glossaryService.getGlossaryEntries.mockResolvedValue({ Hello: 'Hallo' });
@@ -387,11 +481,14 @@ describe('SyncGlossaryManager', () => {
         ['k3', 'Hello'],
       ]);
       const targetEntries = new Map([
-        ['de', new Map([
-          ['k1', 'Hallo'],
-          ['k2', 'Hallo'],
-          ['k3', 'Hallo'],
-        ])],
+        [
+          'de',
+          new Map([
+            ['k1', 'Hallo'],
+            ['k2', 'Hallo'],
+            ['k3', 'Hallo'],
+          ]),
+        ],
       ]);
 
       await manager.syncGlossaries(sourceEntries, targetEntries);
@@ -402,12 +499,12 @@ describe('SyncGlossaryManager', () => {
     });
 
     it('should skip locale with no terms', async () => {
-      const { manager, glossaryService } = createManager({ targetLocales: ['de'] });
+      const { manager, glossaryService } = createManager({
+        targetLocales: ['de'],
+      });
 
       const sourceEntries = new Map([['k1', 'Unique']]);
-      const targetEntries = new Map([
-        ['de', new Map([['k1', 'Einzigartig']])],
-      ]);
+      const targetEntries = new Map([['de', new Map([['k1', 'Einzigartig']])]]);
 
       const result = await manager.syncGlossaries(sourceEntries, targetEntries);
 
@@ -423,25 +520,37 @@ describe('SyncGlossaryManager', () => {
        */
       async function syncTwice(
         sourceEntries: Map<string, string>,
-        localeEntries: Map<string, string>,
-      ): Promise<{ glossaryService: ReturnType<typeof createMockGlossaryService> }> {
-        const { manager, glossaryService } = createManager({ targetLocales: ['de'] });
+        localeEntries: Map<string, string>
+      ): Promise<{
+        glossaryService: ReturnType<typeof createMockGlossaryService>;
+      }> {
+        const { manager, glossaryService } = createManager({
+          targetLocales: ['de'],
+        });
         const info: GlossaryInfo = {
           glossary_id: 'gid-1',
           name: 'deepl-sync-en-de',
           source_lang: 'en',
           target_langs: ['de'],
-          dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 1 }],
+          dictionaries: [
+            { source_lang: 'en', target_lang: 'de', entry_count: 1 },
+          ],
           creation_time: '2026-01-01T00:00:00Z',
         };
 
         let stored: Record<string, string> | null = null;
-        glossaryService.getGlossaryByName.mockImplementation(async () => (stored ? info : null));
-        glossaryService.createGlossary.mockImplementation(async (_n, _s, _t, entries) => {
-          stored = roundTrip(entries);
-          return info;
-        });
-        glossaryService.getGlossaryEntries.mockImplementation(async () => stored ?? {});
+        glossaryService.getGlossaryByName.mockImplementation(async () =>
+          stored ? info : null
+        );
+        glossaryService.createGlossary.mockImplementation(
+          async (_n, _s, _t, entries) => {
+            stored = roundTrip(entries);
+            return info;
+          }
+        );
+        glossaryService.getGlossaryEntries.mockImplementation(
+          async () => stored ?? {}
+        );
         glossaryService.updateGlossary.mockResolvedValue(undefined);
 
         const targetEntries = new Map([['de', localeEntries]]);
@@ -452,18 +561,32 @@ describe('SyncGlossaryManager', () => {
       }
 
       it('should create once and never update when the source terms are unchanged', async () => {
-        const { sourceEntries, localeEntries } = repeated('Save', 'Speichern', 'k');
+        const { sourceEntries, localeEntries } = repeated(
+          'Save',
+          'Speichern',
+          'k'
+        );
 
-        const { glossaryService } = await syncTwice(sourceEntries, localeEntries);
+        const { glossaryService } = await syncTwice(
+          sourceEntries,
+          localeEntries
+        );
 
         expect(glossaryService.createGlossary).toHaveBeenCalledTimes(1);
         expect(glossaryService.updateGlossary).toHaveBeenCalledTimes(0);
       });
 
       it('should not re-upload when a term differs only by surrounding whitespace', async () => {
-        const { sourceEntries, localeEntries } = repeated('Save ', 'Speichern', 'k');
+        const { sourceEntries, localeEntries } = repeated(
+          'Save ',
+          'Speichern',
+          'k'
+        );
 
-        const { glossaryService } = await syncTwice(sourceEntries, localeEntries);
+        const { glossaryService } = await syncTwice(
+          sourceEntries,
+          localeEntries
+        );
 
         expect(glossaryService.createGlossary).toHaveBeenCalledTimes(1);
         expect(glossaryService.updateGlossary).toHaveBeenCalledTimes(0);
@@ -472,9 +595,13 @@ describe('SyncGlossaryManager', () => {
 
     describe('per-locale failure isolation', () => {
       it('should keep syncing other locales and name the failing locale in the warning', async () => {
-        const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+        const warnSpy = jest
+          .spyOn(Logger, 'warn')
+          .mockImplementation(() => undefined);
         try {
-          const { manager, glossaryService } = createManager({ targetLocales: ['de', 'fr'] });
+          const { manager, glossaryService } = createManager({
+            targetLocales: ['de', 'fr'],
+          });
 
           glossaryService.getGlossaryByName.mockResolvedValue(null);
           glossaryService.createGlossary.mockImplementation(async (name) => {
@@ -486,7 +613,9 @@ describe('SyncGlossaryManager', () => {
               name,
               source_lang: 'en',
               target_langs: ['fr'],
-              dictionaries: [{ source_lang: 'en', target_lang: 'fr', entry_count: 1 }],
+              dictionaries: [
+                { source_lang: 'en', target_lang: 'fr', entry_count: 1 },
+              ],
               creation_time: '2026-01-01T00:00:00Z',
             };
             return info;
@@ -495,14 +624,24 @@ describe('SyncGlossaryManager', () => {
           const { sourceEntries, localeEntries } = repeated('Yes', 'Ja', 'k');
           const targetEntries = new Map([
             ['de', localeEntries],
-            ['fr', new Map([...localeEntries].map(([k]) => [k, 'Oui'] as [string, string]))],
+            [
+              'fr',
+              new Map(
+                [...localeEntries].map(([k]) => [k, 'Oui'] as [string, string])
+              ),
+            ],
           ]);
 
-          const result = await manager.syncGlossaries(sourceEntries, targetEntries);
+          const result = await manager.syncGlossaries(
+            sourceEntries,
+            targetEntries
+          );
 
           expect(result).toEqual({ 'en-fr': 'fr-id' });
           expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('de'));
-          expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('glossary rejected by API'));
+          expect(warnSpy).toHaveBeenCalledWith(
+            expect.stringContaining('glossary rejected by API')
+          );
         } finally {
           warnSpy.mockRestore();
         }
@@ -519,13 +658,17 @@ describe('SyncGlossaryManager', () => {
         name: 'deepl-sync-en-de',
         source_lang: 'en',
         target_langs: ['de'],
-        dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 5 }],
+        dictionaries: [
+          { source_lang: 'en', target_lang: 'de', entry_count: 5 },
+        ],
         creation_time: '2026-01-01T00:00:00Z',
       });
 
       const result = await manager.getProjectGlossary('de');
 
-      expect(glossaryService.getGlossaryByName).toHaveBeenCalledWith('deepl-sync-en-de');
+      expect(glossaryService.getGlossaryByName).toHaveBeenCalledWith(
+        'deepl-sync-en-de'
+      );
       expect(result).toBe('found-id');
     });
 
diff --git a/tests/unit/sync/sync-init-detector-table.test.ts b/tests/unit/sync/sync-init-detector-table.test.ts
index 34cce2ec..47527681 100644
--- a/tests/unit/sync/sync-init-detector-table.test.ts
+++ b/tests/unit/sync/sync-init-detector-table.test.ts
@@ -28,7 +28,7 @@ import { resolveTargetPath } from '../../../src/sync/sync-utils';
 const TARGET_LOCALES = ['de', 'fr'] as const;
 
 function findEntry(
-  predicate: (p: DetectionPattern) => boolean,
+  predicate: (p: DetectionPattern) => boolean
 ): DetectionPattern {
   const entry = DETECTION_PATTERNS.find(predicate);
   if (!entry) throw new Error('No DETECTION_PATTERNS entry matched predicate');
@@ -37,7 +37,7 @@ function findEntry(
 
 function resolveBucketPattern(
   entry: DetectionPattern,
-  sourceFile: string,
+  sourceFile: string
 ): { pattern: string; targetPathPattern?: string } {
   const dir = sourceFile.includes('/')
     ? sourceFile.substring(0, sourceFile.lastIndexOf('/'))
@@ -47,7 +47,9 @@ function resolveBucketPattern(
     return { pattern: sourceFile };
   }
   if (entry.localeInPath) {
-    return { pattern: resolvedTemplate.replace('{locale}', entry.sourceLocale) };
+    return {
+      pattern: resolvedTemplate.replace('{locale}', entry.sourceLocale),
+    };
   }
   return { pattern: sourceFile, targetPathPattern: resolvedTemplate };
 }
@@ -56,7 +58,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
   describe('JSON', () => {
     it('flat layout: locales/en.json → bucket pattern matches source and target', () => {
       const entry = findEntry(
-        (p) => p.format === 'json' && p.globs.includes('locales/en.json'),
+        (p) => p.format === 'json' && p.globs.includes('locales/en.json')
       );
       const source = 'locales/en.json';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
@@ -64,26 +66,30 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(pattern).toBe('locales/en.json');
       expect(micromatch.isMatch(source, pattern)).toBe(true);
       for (const target of TARGET_LOCALES) {
-        expect(resolveTargetPath(source, 'en', target)).toBe(`locales/${target}.json`);
+        expect(resolveTargetPath(source, 'en', target)).toBe(
+          `locales/${target}.json`
+        );
       }
     });
 
     it('i18n/en.json flat variant', () => {
       const entry = findEntry(
-        (p) => p.format === 'json' && p.globs.includes('i18n/en.json'),
+        (p) => p.format === 'json' && p.globs.includes('i18n/en.json')
       );
       const source = 'i18n/en.json';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
       const { pattern } = resolveBucketPattern(entry, source);
       expect(pattern).toBe('i18n/en.json');
       for (const target of TARGET_LOCALES) {
-        expect(resolveTargetPath(source, 'en', target)).toBe(`i18n/${target}.json`);
+        expect(resolveTargetPath(source, 'en', target)).toBe(
+          `i18n/${target}.json`
+        );
       }
     });
 
     it('dir-per-locale layout: locales/en/*.json → glob bucket pattern', () => {
       const entry = findEntry(
-        (p) => p.format === 'json' && p.globs.includes('locales/en/*.json'),
+        (p) => p.format === 'json' && p.globs.includes('locales/en/*.json')
       );
       const source = 'locales/en/common.json';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
@@ -96,7 +102,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(micromatch.isMatch('locales/en/errors.json', pattern)).toBe(true);
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target)).toBe(
-          `locales/${target}/common.json`,
+          `locales/${target}/common.json`
         );
       }
     });
@@ -116,20 +122,23 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
   describe('YAML .yaml extension', () => {
     it('locales/en.yaml → .yaml bucket pattern preserves extension', () => {
       const entry = findEntry(
-        (p) => p.format === 'yaml' && p.globs.includes('locales/en.yaml'),
+        (p) => p.format === 'yaml' && p.globs.includes('locales/en.yaml')
       );
       const source = 'locales/en.yaml';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
       const { pattern } = resolveBucketPattern(entry, source);
       expect(pattern).toBe('locales/en.yaml');
       for (const target of TARGET_LOCALES) {
-        expect(resolveTargetPath(source, 'en', target)).toBe(`locales/${target}.yaml`);
+        expect(resolveTargetPath(source, 'en', target)).toBe(
+          `locales/${target}.yaml`
+        );
       }
     });
 
     it('Rails namespaced layout: config/locales/admin/en.yaml', () => {
       const entry = findEntry(
-        (p) => p.format === 'yaml' && p.globs.includes('config/locales/**/en.yaml'),
+        (p) =>
+          p.format === 'yaml' && p.globs.includes('config/locales/**/en.yaml')
       );
       const source = 'config/locales/admin/en.yaml';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
@@ -137,7 +146,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(pattern).toBe('config/locales/admin/en.yaml');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target)).toBe(
-          `config/locales/admin/${target}.yaml`,
+          `config/locales/admin/${target}.yaml`
         );
       }
     });
@@ -146,33 +155,38 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
   describe('YAML .yml extension', () => {
     it('locales/en.yml → .yml bucket pattern preserves extension', () => {
       const entry = findEntry(
-        (p) => p.format === 'yaml' && p.globs.includes('locales/en.yml'),
+        (p) => p.format === 'yaml' && p.globs.includes('locales/en.yml')
       );
       const source = 'locales/en.yml';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
       const { pattern } = resolveBucketPattern(entry, source);
       expect(pattern).toBe('locales/en.yml');
       for (const target of TARGET_LOCALES) {
-        expect(resolveTargetPath(source, 'en', target)).toBe(`locales/${target}.yml`);
+        expect(resolveTargetPath(source, 'en', target)).toBe(
+          `locales/${target}.yml`
+        );
       }
     });
 
     it('Rails canonical layout: config/locales/en.yml', () => {
       const entry = findEntry(
-        (p) => p.format === 'yaml' && p.globs.includes('config/locales/en.yml'),
+        (p) => p.format === 'yaml' && p.globs.includes('config/locales/en.yml')
       );
       const source = 'config/locales/en.yml';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
       const { pattern } = resolveBucketPattern(entry, source);
       expect(pattern).toBe('config/locales/en.yml');
       for (const target of TARGET_LOCALES) {
-        expect(resolveTargetPath(source, 'en', target)).toBe(`config/locales/${target}.yml`);
+        expect(resolveTargetPath(source, 'en', target)).toBe(
+          `config/locales/${target}.yml`
+        );
       }
     });
 
     it('Rails namespaced layout: config/locales/admin/en.yml', () => {
       const entry = findEntry(
-        (p) => p.format === 'yaml' && p.globs.includes('config/locales/**/en.yml'),
+        (p) =>
+          p.format === 'yaml' && p.globs.includes('config/locales/**/en.yml')
       );
       const source = 'config/locales/admin/en.yml';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
@@ -180,7 +194,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(pattern).toBe('config/locales/admin/en.yml');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target)).toBe(
-          `config/locales/admin/${target}.yml`,
+          `config/locales/admin/${target}.yml`
         );
       }
     });
@@ -192,7 +206,9 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
     it('does NOT match config/locales/de.yml (target-locale file)', () => {
       const yamlEntries = DETECTION_PATTERNS.filter((p) => p.format === 'yaml');
       for (const entry of yamlEntries) {
-        expect(micromatch.isMatch('config/locales/de.yml', entry.globs)).toBe(false);
+        expect(micromatch.isMatch('config/locales/de.yml', entry.globs)).toBe(
+          false
+        );
       }
     });
   });
@@ -206,7 +222,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(pattern).toBe('locale/en/LC_MESSAGES/*.po');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target)).toBe(
-          `locale/${target}/LC_MESSAGES/messages.po`,
+          `locale/${target}/LC_MESSAGES/messages.po`
         );
       }
     });
@@ -217,12 +233,15 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       const entry = findEntry((p) => p.format === 'android_xml');
       const source = 'res/values/strings.xml';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
-      const { pattern, targetPathPattern } = resolveBucketPattern(entry, source);
+      const { pattern, targetPathPattern } = resolveBucketPattern(
+        entry,
+        source
+      );
       expect(pattern).toBe('res/values/strings.xml');
       expect(targetPathPattern).toBe('res/values-{locale}/strings.xml');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target, targetPathPattern)).toBe(
-          `res/values-${target}/strings.xml`,
+          `res/values-${target}/strings.xml`
         );
       }
     });
@@ -237,7 +256,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(pattern).toBe('en.lproj/Localizable.strings');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target)).toBe(
-          `${target}.lproj/Localizable.strings`,
+          `${target}.lproj/Localizable.strings`
         );
       }
     });
@@ -248,8 +267,12 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
     // to the four-flag non-interactive init path.
     it('does NOT match bare-root Localizable.strings', () => {
       const entry = findEntry((p) => p.format === 'ios_strings');
-      expect(micromatch.isMatch('Localizable.strings', entry.globs)).toBe(false);
-      expect(micromatch.isMatch('build/Localizable.strings', entry.globs)).toBe(false);
+      expect(micromatch.isMatch('Localizable.strings', entry.globs)).toBe(
+        false
+      );
+      expect(micromatch.isMatch('build/Localizable.strings', entry.globs)).toBe(
+        false
+      );
     });
   });
 
@@ -261,7 +284,9 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       const { pattern } = resolveBucketPattern(entry, source);
       expect(pattern).toBe('l10n/app_en.arb');
       for (const target of TARGET_LOCALES) {
-        expect(resolveTargetPath(source, 'en', target)).toBe(`l10n/app_${target}.arb`);
+        expect(resolveTargetPath(source, 'en', target)).toBe(
+          `l10n/app_${target}.arb`
+        );
       }
     });
 
@@ -274,32 +299,41 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
   describe('XLIFF (canonical src/locale + Symfony translations)', () => {
     it('Angular canonical src/locale/messages.xlf', () => {
       const entry = findEntry(
-        (p) => p.format === 'xliff' && p.globs.includes('src/locale/messages.xlf'),
+        (p) =>
+          p.format === 'xliff' && p.globs.includes('src/locale/messages.xlf')
       );
       const source = 'src/locale/messages.xlf';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
-      const { pattern, targetPathPattern } = resolveBucketPattern(entry, source);
+      const { pattern, targetPathPattern } = resolveBucketPattern(
+        entry,
+        source
+      );
       expect(pattern).toBe('src/locale/messages.xlf');
       expect(targetPathPattern).toBe('src/locale/messages.{locale}.xlf');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target, targetPathPattern)).toBe(
-          `src/locale/messages.${target}.xlf`,
+          `src/locale/messages.${target}.xlf`
         );
       }
     });
 
     it('Symfony translations/messages.en.xlf', () => {
       const entry = findEntry(
-        (p) => p.format === 'xliff' && p.globs.includes('translations/messages.en.xlf'),
+        (p) =>
+          p.format === 'xliff' &&
+          p.globs.includes('translations/messages.en.xlf')
       );
       const source = 'translations/messages.en.xlf';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
-      const { pattern, targetPathPattern } = resolveBucketPattern(entry, source);
+      const { pattern, targetPathPattern } = resolveBucketPattern(
+        entry,
+        source
+      );
       expect(pattern).toBe('translations/messages.en.xlf');
       expect(targetPathPattern).toBe('translations/messages.{locale}.xlf');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target, targetPathPattern)).toBe(
-          `translations/messages.${target}.xlf`,
+          `translations/messages.${target}.xlf`
         );
       }
     });
@@ -307,11 +341,15 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
     // Negative: bare-root `*.xlf` / `*.xliff` match no XLIFF entry — CAT-tool
     // dumps (Trados/memoQ/Xcode `.xcloc` extracts) are false-positive magnets.
     it('does NOT match bare-root *.xlf or *.xliff (any XLIFF entry)', () => {
-      const xliffEntries = DETECTION_PATTERNS.filter((p) => p.format === 'xliff');
+      const xliffEntries = DETECTION_PATTERNS.filter(
+        (p) => p.format === 'xliff'
+      );
       for (const entry of xliffEntries) {
         expect(micromatch.isMatch('messages.xlf', entry.globs)).toBe(false);
         expect(micromatch.isMatch('export.xliff', entry.globs)).toBe(false);
-        expect(micromatch.isMatch('trados-export/file.xlf', entry.globs)).toBe(false);
+        expect(micromatch.isMatch('trados-export/file.xlf', entry.globs)).toBe(
+          false
+        );
       }
     });
   });
@@ -325,7 +363,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(pattern).toBe('lang/en/*.php');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target)).toBe(
-          `lang/${target}/messages.php`,
+          `lang/${target}/messages.php`
         );
       }
     });
@@ -336,7 +374,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target)).toBe(
-          `resources/lang/${target}/messages.php`,
+          `resources/lang/${target}/messages.php`
         );
       }
     });
@@ -352,7 +390,10 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       const entry = findEntry((p) => p.format === 'xcstrings');
       const source = 'Localizable.xcstrings';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
-      const { pattern, targetPathPattern } = resolveBucketPattern(entry, source);
+      const { pattern, targetPathPattern } = resolveBucketPattern(
+        entry,
+        source
+      );
       expect(pattern).toBe('Localizable.xcstrings');
       expect(targetPathPattern).toBeUndefined();
       expect(entry.multiLocale).toBe(true);
@@ -368,27 +409,31 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
   describe('go-i18n TOML', () => {
     it('locales/en.toml directory layout', () => {
       const entry = findEntry(
-        (p) => p.format === 'toml' && p.globs.includes('locales/en.toml'),
+        (p) => p.format === 'toml' && p.globs.includes('locales/en.toml')
       );
       const source = 'locales/en.toml';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
       const { pattern } = resolveBucketPattern(entry, source);
       expect(pattern).toBe('locales/en.toml');
       for (const target of TARGET_LOCALES) {
-        expect(resolveTargetPath(source, 'en', target)).toBe(`locales/${target}.toml`);
+        expect(resolveTargetPath(source, 'en', target)).toBe(
+          `locales/${target}.toml`
+        );
       }
     });
 
     it('active.en.toml root-level layout', () => {
       const entry = findEntry(
-        (p) => p.format === 'toml' && p.globs.includes('active.en.toml'),
+        (p) => p.format === 'toml' && p.globs.includes('active.en.toml')
       );
       const source = 'active.en.toml';
       expect(micromatch.isMatch(source, entry.globs)).toBe(true);
       const { pattern } = resolveBucketPattern(entry, source);
       expect(pattern).toBe('active.en.toml');
       for (const target of TARGET_LOCALES) {
-        expect(resolveTargetPath(source, 'en', target)).toBe(`active.${target}.toml`);
+        expect(resolveTargetPath(source, 'en', target)).toBe(
+          `active.${target}.toml`
+        );
       }
     });
 
@@ -397,7 +442,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
     // derived from the template at sync time, not re-detected.
     it('does NOT match active.fr.toml when active.en.toml is the source signal', () => {
       const entry = findEntry(
-        (p) => p.format === 'toml' && p.globs.includes('active.en.toml'),
+        (p) => p.format === 'toml' && p.globs.includes('active.en.toml')
       );
       expect(micromatch.isMatch('active.fr.toml', entry.globs)).toBe(false);
     });
@@ -412,7 +457,7 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
       expect(pattern).toBe('src/main/resources/messages_en.properties');
       for (const target of TARGET_LOCALES) {
         expect(resolveTargetPath(source, 'en', target)).toBe(
-          `src/main/resources/messages_${target}.properties`,
+          `src/main/resources/messages_${target}.properties`
         );
       }
     });
@@ -426,27 +471,57 @@ describe('DETECTION_PATTERNS table-driven harness', () => {
     // `locales/en/en.json`, which no bucket glob in the entry matches.
     const cases: Array<{ desc: string; format: string; source: string }> = [
       { desc: 'JSON flat', format: 'json', source: 'locales/en.json' },
-      { desc: 'JSON dir-per-locale', format: 'json', source: 'locales/en/common.json' },
+      {
+        desc: 'JSON dir-per-locale',
+        format: 'json',
+        source: 'locales/en/common.json',
+      },
       { desc: 'YAML .yaml', format: 'yaml', source: 'locales/en.yaml' },
       { desc: 'YAML .yml', format: 'yaml', source: 'locales/en.yml' },
-      { desc: 'Rails namespaced yml', format: 'yaml', source: 'config/locales/admin/en.yml' },
+      {
+        desc: 'Rails namespaced yml',
+        format: 'yaml',
+        source: 'config/locales/admin/en.yml',
+      },
       { desc: 'PO', format: 'po', source: 'locale/en/LC_MESSAGES/messages.po' },
-      { desc: 'iOS', format: 'ios_strings', source: 'en.lproj/Localizable.strings' },
+      {
+        desc: 'iOS',
+        format: 'ios_strings',
+        source: 'en.lproj/Localizable.strings',
+      },
       { desc: 'ARB', format: 'arb', source: 'l10n/app_en.arb' },
-      { desc: 'Laravel', format: 'laravel_php', source: 'lang/en/messages.php' },
+      {
+        desc: 'Laravel',
+        format: 'laravel_php',
+        source: 'lang/en/messages.php',
+      },
       { desc: 'go-i18n dir', format: 'toml', source: 'locales/en.toml' },
-      { desc: 'go-i18n active.en.toml', format: 'toml', source: 'active.en.toml' },
-      { desc: 'Spring', format: 'properties', source: 'src/main/resources/messages_en.properties' },
+      {
+        desc: 'go-i18n active.en.toml',
+        format: 'toml',
+        source: 'active.en.toml',
+      },
+      {
+        desc: 'Spring',
+        format: 'properties',
+        source: 'src/main/resources/messages_en.properties',
+      },
     ];
 
-    it.each(cases)('$desc: resolved bucket pattern matches source under entry globs', ({ format, source }) => {
-      const entry = DETECTION_PATTERNS.find(
-        (p) => p.format === format && !p.multiLocale && micromatch.isMatch(source, p.globs),
-      );
-      expect(entry).toBeDefined();
-      if (!entry) return;
-      const { pattern } = resolveBucketPattern(entry, source);
-      expect(micromatch.isMatch(source, pattern)).toBe(true);
-    });
+    it.each(cases)(
+      '$desc: resolved bucket pattern matches source under entry globs',
+      ({ format, source }) => {
+        const entry = DETECTION_PATTERNS.find(
+          (p) =>
+            p.format === format &&
+            !p.multiLocale &&
+            micromatch.isMatch(source, p.globs)
+        );
+        expect(entry).toBeDefined();
+        if (!entry) return;
+        const { pattern } = resolveBucketPattern(entry, source);
+        expect(micromatch.isMatch(source, pattern)).toBe(true);
+      }
+    );
   });
 });
diff --git a/tests/unit/sync/sync-init-validate.test.ts b/tests/unit/sync/sync-init-validate.test.ts
index 970480ea..9ea56133 100644
--- a/tests/unit/sync/sync-init-validate.test.ts
+++ b/tests/unit/sync/sync-init-validate.test.ts
@@ -18,8 +18,9 @@ describe('sync-init-validate', () => {
 
     it('rejects source locale appearing in target-locales (case-insensitive)', () => {
       expect.assertions(4);
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: 'de,EN,fr' }))
-        .toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({ ...base, targetLocales: 'de,EN,fr' })
+      ).toThrow(ValidationError);
       try {
         validateSyncInitFlags({ ...base, targetLocales: 'de,EN,fr' });
       } catch (e) {
@@ -32,8 +33,9 @@ describe('sync-init-validate', () => {
 
     it('rejects duplicate target-locales (case-insensitive)', () => {
       expect.assertions(3);
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: 'de,fr,DE' }))
-        .toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({ ...base, targetLocales: 'de,fr,DE' })
+      ).toThrow(ValidationError);
       try {
         validateSyncInitFlags({ ...base, targetLocales: 'de,fr,DE' });
       } catch (e) {
@@ -44,33 +46,45 @@ describe('sync-init-validate', () => {
     });
 
     it('rejects empty target-locales after splitting', () => {
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: ' , , ' }))
-        .toThrow(ValidationError);
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: '' }))
-        .toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({ ...base, targetLocales: ' , , ' })
+      ).toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({ ...base, targetLocales: '' })
+      ).toThrow(ValidationError);
     });
 
     it('rejects malformed locale codes', () => {
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: 'de,xx_YY' }))
-        .toThrow(ValidationError);
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: 'de,123' }))
-        .toThrow(ValidationError);
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: 'de,' + 'x'.repeat(30) }))
-        .toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({ ...base, targetLocales: 'de,xx_YY' })
+      ).toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({ ...base, targetLocales: 'de,123' })
+      ).toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({
+          ...base,
+          targetLocales: 'de,' + 'x'.repeat(30),
+        })
+      ).toThrow(ValidationError);
     });
 
     it('accepts BCP-47 style codes including script subtags', () => {
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: 'zh-Hans,pt-BR' }))
-        .not.toThrow();
-      expect(() => validateSyncInitFlags({ ...base, targetLocales: 'en-US-POSIX' }))
-        .not.toThrow();
+      expect(() =>
+        validateSyncInitFlags({ ...base, targetLocales: 'zh-Hans,pt-BR' })
+      ).not.toThrow();
+      expect(() =>
+        validateSyncInitFlags({ ...base, targetLocales: 'en-US-POSIX' })
+      ).not.toThrow();
     });
 
     it('rejects path traversal in --path', () => {
-      expect(() => validateSyncInitFlags({ ...base, filePath: '../etc/passwd' }))
-        .toThrow(ValidationError);
-      expect(() => validateSyncInitFlags({ ...base, filePath: 'locales/../../../etc' }))
-        .toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({ ...base, filePath: '../etc/passwd' })
+      ).toThrow(ValidationError);
+      expect(() =>
+        validateSyncInitFlags({ ...base, filePath: 'locales/../../../etc' })
+      ).toThrow(ValidationError);
     });
 
     it('allows missing source-path file but returns a warning', () => {
@@ -81,7 +95,9 @@ describe('sync-init-validate', () => {
         cwd: '/tmp/nonexistent-' + Date.now(),
       });
       expect(result.warnings.length).toBeGreaterThan(0);
-      expect(result.warnings.some(w => w.toLowerCase().includes('not'))).toBe(true);
+      expect(result.warnings.some((w) => w.toLowerCase().includes('not'))).toBe(
+        true
+      );
     });
 
     it('does not warn when --path exists', () => {
@@ -122,7 +138,7 @@ describe('sync-init-validate', () => {
 
     it('includes common locales that were missing from the old 5-language set', () => {
       const choices = buildTargetLocaleChoices();
-      const values = choices.map(c => c.value);
+      const values = choices.map((c) => c.value);
       expect(values).toContain('it');
       expect(values).toContain('ko');
       expect(values).toContain('nl');
@@ -133,7 +149,7 @@ describe('sync-init-validate', () => {
 
     it('pre-checks top common locales (de, es, fr, it, ja, ko, pt-br, zh)', () => {
       const choices = buildTargetLocaleChoices();
-      const checked = choices.filter(c => c.checked).map(c => c.value);
+      const checked = choices.filter((c) => c.checked).map((c) => c.value);
       for (const code of ['de', 'es', 'fr', 'it', 'ja', 'ko', 'pt-br', 'zh']) {
         expect(checked).toContain(code);
       }
@@ -141,7 +157,7 @@ describe('sync-init-validate', () => {
 
     it('uses display names that include the language and code', () => {
       const choices = buildTargetLocaleChoices();
-      const de = choices.find(c => c.value === 'de');
+      const de = choices.find((c) => c.value === 'de');
       expect(de).toBeDefined();
       expect(de!.name).toContain('German');
       expect(de!.name).toContain('de');
diff --git a/tests/unit/sync/sync-init.test.ts b/tests/unit/sync/sync-init.test.ts
index e179b29c..40a49b4b 100644
--- a/tests/unit/sync/sync-init.test.ts
+++ b/tests/unit/sync/sync-init.test.ts
@@ -26,7 +26,10 @@ describe('sync-init', () => {
   let testDir: string;
 
   beforeEach(() => {
-    testDir = path.join(os.tmpdir(), `deepl-sync-init-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    testDir = path.join(
+      os.tmpdir(),
+      `deepl-sync-init-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
     fs.mkdirSync(testDir, { recursive: true });
     mockFg.mockReset();
     mockFg.mockResolvedValue([]);
@@ -44,7 +47,7 @@ describe('sync-init', () => {
       fs.mkdirSync(localesDir, { recursive: true });
       fs.writeFileSync(
         path.join(localesDir, 'en.json'),
-        JSON.stringify({ hello: 'Hello', world: 'World' }),
+        JSON.stringify({ hello: 'Hello', world: 'World' })
       );
 
       mockFg.mockImplementation(async (patterns, _options) => {
@@ -69,7 +72,11 @@ describe('sync-init', () => {
       fs.mkdirSync(localesDir, { recursive: true });
       fs.writeFileSync(
         path.join(localesDir, 'en.yaml'),
-        YAML.stringify({ greeting: 'Hello', farewell: 'Goodbye', thanks: 'Thank you' }),
+        YAML.stringify({
+          greeting: 'Hello',
+          farewell: 'Goodbye',
+          thanks: 'Thank you',
+        })
       );
 
       mockFg.mockImplementation(async (patterns, _options) => {
@@ -91,7 +98,10 @@ describe('sync-init', () => {
     it('should detect Android XML using the documented bucket key', async () => {
       const resDir = path.join(testDir, 'res', 'values');
       fs.mkdirSync(resDir, { recursive: true });
-      fs.writeFileSync(path.join(resDir, 'strings.xml'), '<resources><string name="app_name">App</string></resources>');
+      fs.writeFileSync(
+        path.join(resDir, 'strings.xml'),
+        '<resources><string name="app_name">App</string></resources>'
+      );
 
       mockFg.mockImplementation(async (patterns, _options) => {
         const patternArray = Array.isArray(patterns) ? patterns : [patterns];
@@ -106,13 +116,18 @@ describe('sync-init', () => {
       const androidProject = result.find((p) => p.format === 'android_xml');
       expect(androidProject).toBeDefined();
       expect(androidProject!.pattern).toBe('res/values/strings.xml');
-      expect(androidProject!.targetPathPattern).toBe('res/values-{locale}/strings.xml');
+      expect(androidProject!.targetPathPattern).toBe(
+        'res/values-{locale}/strings.xml'
+      );
     });
 
     it('should detect iOS strings using the documented bucket key', async () => {
       const iosDir = path.join(testDir, 'en.lproj');
       fs.mkdirSync(iosDir, { recursive: true });
-      fs.writeFileSync(path.join(iosDir, 'Localizable.strings'), '"greeting" = "Hello";');
+      fs.writeFileSync(
+        path.join(iosDir, 'Localizable.strings'),
+        '"greeting" = "Hello";'
+      );
 
       mockFg.mockImplementation(async (patterns, _options) => {
         const patternArray = Array.isArray(patterns) ? patterns : [patterns];
@@ -133,7 +148,10 @@ describe('sync-init', () => {
     it('should detect XLIFF projects', async () => {
       const localeDir = path.join(testDir, 'src', 'locale');
       fs.mkdirSync(localeDir, { recursive: true });
-      fs.writeFileSync(path.join(localeDir, 'messages.xlf'), '<xliff version="1.2"></xliff>');
+      fs.writeFileSync(
+        path.join(localeDir, 'messages.xlf'),
+        '<xliff version="1.2"></xliff>'
+      );
 
       mockFg.mockImplementation(async (patterns, _options) => {
         const patternArray = Array.isArray(patterns) ? patterns : [patterns];
@@ -148,7 +166,9 @@ describe('sync-init', () => {
       const xliffProject = result.find((p) => p.format === 'xliff');
       expect(xliffProject).toBeDefined();
       expect(xliffProject!.pattern).toBe('src/locale/messages.xlf');
-      expect(xliffProject!.targetPathPattern).toBe('src/locale/messages.{locale}.xlf');
+      expect(xliffProject!.targetPathPattern).toBe(
+        'src/locale/messages.{locale}.xlf'
+      );
     });
 
     it('should return empty array when no i18n files found', async () => {
@@ -165,12 +185,14 @@ describe('sync-init', () => {
         fs.mkdirSync(railsDir, { recursive: true });
         fs.writeFileSync(
           path.join(railsDir, 'en.yml'),
-          'en:\n  greeting: "Hello"\n  farewell: "Goodbye"\n',
+          'en:\n  greeting: "Hello"\n  farewell: "Goodbye"\n'
         );
 
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
-          return arr.includes('config/locales/en.yml') ? ['config/locales/en.yml'] : [];
+          return arr.includes('config/locales/en.yml')
+            ? ['config/locales/en.yml']
+            : [];
         });
 
         const result = await detectI18nFiles(testDir);
@@ -184,7 +206,10 @@ describe('sync-init', () => {
         // A `locales/en.yml` match must generate a `.yml` bucket pattern; a
         // `.yaml` pattern would not match the file at sync time.
         fs.mkdirSync(path.join(testDir, 'locales'), { recursive: true });
-        fs.writeFileSync(path.join(testDir, 'locales', 'en.yml'), 'greeting: Hello\n');
+        fs.writeFileSync(
+          path.join(testDir, 'locales', 'en.yml'),
+          'greeting: Hello\n'
+        );
 
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
@@ -205,8 +230,14 @@ describe('sync-init', () => {
           path.join(resDir, 'Localizable.xcstrings'),
           JSON.stringify({
             sourceLanguage: 'en',
-            strings: { hi: { localizations: { en: { stringUnit: { state: 'translated', value: 'Hi' } } } } },
-          }),
+            strings: {
+              hi: {
+                localizations: {
+                  en: { stringUnit: { state: 'translated', value: 'Hi' } },
+                },
+              },
+            },
+          })
         );
 
         mockFg.mockImplementation(async (patterns) => {
@@ -227,17 +258,19 @@ describe('sync-init', () => {
       it('detects root-level `Localizable.xcstrings`', async () => {
         fs.writeFileSync(
           path.join(testDir, 'Localizable.xcstrings'),
-          JSON.stringify({ sourceLanguage: 'en', strings: {} }),
+          JSON.stringify({ sourceLanguage: 'en', strings: {} })
         );
 
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
-          return arr.includes('Localizable.xcstrings') ? ['Localizable.xcstrings'] : [];
+          return arr.includes('Localizable.xcstrings')
+            ? ['Localizable.xcstrings']
+            : [];
         });
 
         const result = await detectI18nFiles(testDir);
         expect(result.find((p) => p.format === 'xcstrings')?.pattern).toBe(
-          'Localizable.xcstrings',
+          'Localizable.xcstrings'
         );
       });
     });
@@ -247,7 +280,7 @@ describe('sync-init', () => {
         fs.mkdirSync(path.join(testDir, 'locales'), { recursive: true });
         fs.writeFileSync(
           path.join(testDir, 'locales', 'en.toml'),
-          '[greeting]\nother = "Hello"\n',
+          '[greeting]\nother = "Hello"\n'
         );
 
         mockFg.mockImplementation(async (patterns) => {
@@ -268,7 +301,7 @@ describe('sync-init', () => {
         fs.mkdirSync(springDir, { recursive: true });
         fs.writeFileSync(
           path.join(springDir, 'messages_en.properties'),
-          'welcome=Welcome\ngreeting=Hello\n',
+          'welcome=Welcome\ngreeting=Hello\n'
         );
 
         mockFg.mockImplementation(async (patterns) => {
@@ -281,7 +314,9 @@ describe('sync-init', () => {
         const result = await detectI18nFiles(testDir);
         const props = result.find((p) => p.format === 'properties');
         expect(props).toBeDefined();
-        expect(props!.pattern).toBe('src/main/resources/messages_en.properties');
+        expect(props!.pattern).toBe(
+          'src/main/resources/messages_en.properties'
+        );
         expect(props!.keyCount).toBe(2);
       });
     });
@@ -293,7 +328,7 @@ describe('sync-init', () => {
         fs.mkdirSync(langEn, { recursive: true });
         fs.writeFileSync(
           path.join(langEn, 'messages.php'),
-          `<?php return ['greeting' => 'Hello'];`,
+          `<?php return ['greeting' => 'Hello'];`
         );
 
         mockFg.mockImplementation(async (patterns) => {
@@ -316,7 +351,7 @@ describe('sync-init', () => {
         fs.mkdirSync(langEn, { recursive: true });
         fs.writeFileSync(
           path.join(langEn, 'messages.php'),
-          `<?php return ['greeting' => 'Hello', 'farewell' => 'Goodbye'];`,
+          `<?php return ['greeting' => 'Hello', 'farewell' => 'Goodbye'];`
         );
 
         mockFg.mockImplementation(async (patterns) => {
@@ -339,7 +374,7 @@ describe('sync-init', () => {
         fs.mkdirSync(langEn, { recursive: true });
         fs.writeFileSync(
           path.join(langEn, 'messages.php'),
-          `<?php return ['greeting' => 'Hello'];`,
+          `<?php return ['greeting' => 'Hello'];`
         );
 
         // Even if fg WOULD match, the requires-gate should skip the glob entirely.
@@ -370,7 +405,7 @@ describe('sync-init', () => {
         fs.mkdirSync(langEn, { recursive: true });
         fs.writeFileSync(
           path.join(langEn, 'messages.php'),
-          `<?php return ['greeting' => 'Hello'];`,
+          `<?php return ['greeting' => 'Hello'];`
         );
 
         mockFg.mockImplementation(async (patterns) => {
@@ -388,14 +423,21 @@ describe('sync-init', () => {
       it('prefers dir-per-locale when both layouts coexist', async () => {
         const flatDir = path.join(testDir, 'locales');
         fs.mkdirSync(flatDir, { recursive: true });
-        fs.writeFileSync(path.join(flatDir, 'en.json'), JSON.stringify({ legacy: 'Legacy' }));
+        fs.writeFileSync(
+          path.join(flatDir, 'en.json'),
+          JSON.stringify({ legacy: 'Legacy' })
+        );
         const nestedDir = path.join(flatDir, 'en');
         fs.mkdirSync(nestedDir, { recursive: true });
-        fs.writeFileSync(path.join(nestedDir, 'common.json'), JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }));
+        fs.writeFileSync(
+          path.join(nestedDir, 'common.json'),
+          JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' })
+        );
 
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
-          if (arr.includes('locales/en/*.json')) return ['locales/en/common.json'];
+          if (arr.includes('locales/en/*.json'))
+            return ['locales/en/common.json'];
           if (arr.includes('locales/en.json')) return ['locales/en.json'];
           return [];
         });
@@ -411,7 +453,10 @@ describe('sync-init', () => {
       it('falls back to flat when only flat is present', async () => {
         const flatDir = path.join(testDir, 'locales');
         fs.mkdirSync(flatDir, { recursive: true });
-        fs.writeFileSync(path.join(flatDir, 'en.json'), JSON.stringify({ greeting: 'Hello' }));
+        fs.writeFileSync(
+          path.join(flatDir, 'en.json'),
+          JSON.stringify({ greeting: 'Hello' })
+        );
 
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
@@ -432,21 +477,25 @@ describe('sync-init', () => {
         fs.mkdirSync(translationsDir, { recursive: true });
         fs.writeFileSync(
           path.join(translationsDir, 'messages.en.xlf'),
-          '<?xml version="1.0"?><xliff version="1.2"><file source-language="en"><body></body></file></xliff>',
+          '<?xml version="1.0"?><xliff version="1.2"><file source-language="en"><body></body></file></xliff>'
         );
 
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
-          if (arr.includes('translations/messages.en.xlf')) return ['translations/messages.en.xlf'];
+          if (arr.includes('translations/messages.en.xlf'))
+            return ['translations/messages.en.xlf'];
           return [];
         });
 
         const result = await detectI18nFiles(testDir);
         const symfony = result.find(
-          (p) => p.format === 'xliff' && p.pattern === 'translations/messages.en.xlf',
+          (p) =>
+            p.format === 'xliff' && p.pattern === 'translations/messages.en.xlf'
         );
         expect(symfony).toBeDefined();
-        expect(symfony!.targetPathPattern).toBe('translations/messages.{locale}.xlf');
+        expect(symfony!.targetPathPattern).toBe(
+          'translations/messages.{locale}.xlf'
+        );
       });
     });
 
@@ -463,11 +512,13 @@ describe('sync-init', () => {
             '<string name="app_name">App</string>' +
             '<string name="hello">Hello</string>' +
             '<string name="bye">Bye</string>' +
-            '</resources>',
+            '</resources>'
         );
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
-          return arr.includes('res/values/strings.xml') ? ['res/values/strings.xml'] : [];
+          return arr.includes('res/values/strings.xml')
+            ? ['res/values/strings.xml']
+            : [];
         });
 
         const result = await detectI18nFiles(testDir);
@@ -480,7 +531,7 @@ describe('sync-init', () => {
         fs.mkdirSync(iosDir, { recursive: true });
         fs.writeFileSync(
           path.join(iosDir, 'Localizable.strings'),
-          '"greeting" = "Hello";\n"farewell" = "Bye";\n',
+          '"greeting" = "Hello";\n"farewell" = "Bye";\n'
         );
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
@@ -507,7 +558,7 @@ describe('sync-init', () => {
             hello: 'Hello',
             bye: 'Bye',
             thanks: 'Thanks',
-          }),
+          })
         );
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
@@ -526,7 +577,7 @@ describe('sync-init', () => {
         fs.mkdirSync(l10nDir, { recursive: true });
         fs.writeFileSync(
           path.join(l10nDir, 'app_en.arb'),
-          JSON.stringify({ hello: 'Hello' }),
+          JSON.stringify({ hello: 'Hello' })
         );
 
         // Even if fg WOULD match, the requires-gate should skip the glob.
@@ -546,7 +597,7 @@ describe('sync-init', () => {
           path.join(poDir, 'messages.po'),
           'msgid ""\nmsgstr ""\n\n' +
             'msgid "hello"\nmsgstr "Hello"\n\n' +
-            'msgid "bye"\nmsgstr "Bye"\n',
+            'msgid "bye"\nmsgstr "Bye"\n'
         );
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
@@ -576,11 +627,13 @@ describe('sync-init', () => {
             '      <trans-unit id="bye"><source>Bye</source></trans-unit>\n' +
             '    </body>\n' +
             '  </file>\n' +
-            '</xliff>',
+            '</xliff>'
         );
         mockFg.mockImplementation(async (patterns) => {
           const arr = Array.isArray(patterns) ? patterns : [patterns];
-          return arr.includes('src/locale/messages.xlf') ? ['src/locale/messages.xlf'] : [];
+          return arr.includes('src/locale/messages.xlf')
+            ? ['src/locale/messages.xlf']
+            : [];
         });
 
         const result = await detectI18nFiles(testDir);
@@ -603,7 +656,10 @@ describe('sync-init', () => {
         version: number;
         source_locale: string;
         target_locales: string[];
-        buckets: Record<string, { include: string[]; target_path_pattern?: string }>;
+        buckets: Record<
+          string,
+          { include: string[]; target_path_pattern?: string }
+        >;
       };
 
       expect(parsed.version).toBe(1);
@@ -625,12 +681,19 @@ describe('sync-init', () => {
       });
 
       const parsed = YAML.parse(content) as {
-        buckets: Record<string, { include: string[]; target_path_pattern?: string }>;
+        buckets: Record<
+          string,
+          { include: string[]; target_path_pattern?: string }
+        >;
       };
 
       expect(parsed.buckets['android_xml']).toBeDefined();
-      expect(parsed.buckets['android_xml']!.include).toContain('res/values/strings.xml');
-      expect(parsed.buckets['android_xml']!.target_path_pattern).toBe('res/values-{locale}/strings.xml');
+      expect(parsed.buckets['android_xml']!.include).toContain(
+        'res/values/strings.xml'
+      );
+      expect(parsed.buckets['android_xml']!.target_path_pattern).toBe(
+        'res/values-{locale}/strings.xml'
+      );
     });
 
     it('should write concrete include pattern for yaml format', () => {
@@ -664,12 +727,14 @@ describe('sync-init', () => {
 
   describe('resolveInitConfigPath', () => {
     it('should default to .deepl-sync.yaml in the cwd', () => {
-      expect(resolveInitConfigPath(testDir)).toBe(path.join(testDir, '.deepl-sync.yaml'));
+      expect(resolveInitConfigPath(testDir)).toBe(
+        path.join(testDir, '.deepl-sync.yaml')
+      );
     });
 
     it('should honor an explicit path with a custom basename', () => {
       expect(resolveInitConfigPath(testDir, 'nested/custom.yaml')).toBe(
-        path.join(testDir, 'nested', 'custom.yaml'),
+        path.join(testDir, 'nested', 'custom.yaml')
       );
     });
 
@@ -684,7 +749,7 @@ describe('sync-init', () => {
       const content = 'version: 1\nsource_locale: en\n';
       const configPath = await writeSyncConfig(
         path.join(testDir, '.deepl-sync.yaml'),
-        content,
+        content
       );
 
       expect(configPath).toBe(path.join(testDir, '.deepl-sync.yaml'));
@@ -700,14 +765,18 @@ describe('sync-init', () => {
         .mockRejectedValue(new Error('rename failed'));
       try {
         await expect(
-          writeSyncConfig(configPath, 'version: 1\nsource_locale: de\n'),
+          writeSyncConfig(configPath, 'version: 1\nsource_locale: de\n')
         ).rejects.toThrow('rename failed');
       } finally {
         renameSpy.mockRestore();
       }
 
-      expect(fs.readFileSync(configPath, 'utf-8')).toBe('version: 1\nsource_locale: en\n');
-      expect(fs.readdirSync(testDir).filter(name => name.includes('.tmp.'))).toEqual([]);
+      expect(fs.readFileSync(configPath, 'utf-8')).toBe(
+        'version: 1\nsource_locale: en\n'
+      );
+      expect(
+        fs.readdirSync(testDir).filter((name) => name.includes('.tmp.'))
+      ).toEqual([]);
     });
 
     it('should create missing parent directories', async () => {
@@ -738,7 +807,9 @@ describe('sync-init', () => {
       expect(parsed.version).toBe(1);
       expect(parsed.source_locale).toBe('en');
       expect(parsed.target_locales).toEqual(['de', 'fr', 'ja']);
-      expect((parsed.buckets as unknown as Record<string, unknown>)['json']).toBeDefined();
+      expect(
+        (parsed.buckets as unknown as Record<string, unknown>)['json']
+      ).toBeDefined();
     });
   });
 });
diff --git a/tests/unit/sync/sync-instructions.test.ts b/tests/unit/sync/sync-instructions.test.ts
index 79b2553f..940bc680 100644
--- a/tests/unit/sync/sync-instructions.test.ts
+++ b/tests/unit/sync/sync-instructions.test.ts
@@ -21,7 +21,7 @@ describe('sync-instructions', () => {
       'should return true for supported base locale %s',
       (locale) => {
         expect(supportsCustomInstructions(locale)).toBe(true);
-      },
+      }
     );
 
     it.each(['DE', 'EN'])('should handle uppercase locale %s', (locale) => {
@@ -32,14 +32,14 @@ describe('sync-instructions', () => {
       'should handle regional variant %s',
       (locale) => {
         expect(supportsCustomInstructions(locale)).toBe(true);
-      },
+      }
     );
 
     it.each(['ar', 'he', 'pt-BR', 'nl', 'ru', 'tr', 'pl'])(
       'should return false for unsupported locale %s',
       (locale) => {
         expect(supportsCustomInstructions(locale)).toBe(false);
-      },
+      }
     );
 
     it('should return false for empty string', () => {
@@ -72,7 +72,7 @@ describe('sync-instructions', () => {
 
     it('should include button template', () => {
       expect(DEFAULT_INSTRUCTION_TEMPLATES['button']).toBe(
-        'Keep translation concise, maximum 3 words.',
+        'Keep translation concise, maximum 3 words.'
       );
     });
   });
@@ -83,12 +83,14 @@ describe('sync-instructions', () => {
   describe('generateElementInstruction', () => {
     it('should return the default instruction for a known element type', () => {
       expect(generateElementInstruction('button')).toBe(
-        'Keep translation concise, maximum 3 words.',
+        'Keep translation concise, maximum 3 words.'
       );
     });
 
     it('should return the correct instruction for each default template', () => {
-      for (const [element, expected] of Object.entries(DEFAULT_INSTRUCTION_TEMPLATES)) {
+      for (const [element, expected] of Object.entries(
+        DEFAULT_INSTRUCTION_TEMPLATES
+      )) {
         expect(generateElementInstruction(element)).toBe(expected);
       }
     });
@@ -108,18 +110,22 @@ describe('sync-instructions', () => {
 
     it('should use user templates to override defaults', () => {
       const userTemplates = { button: 'Max 2 words.' };
-      expect(generateElementInstruction('button', userTemplates)).toBe('Max 2 words.');
+      expect(generateElementInstruction('button', userTemplates)).toBe(
+        'Max 2 words.'
+      );
     });
 
     it('should allow user templates for types not in defaults', () => {
       const userTemplates = { div: 'Keep it short.' };
-      expect(generateElementInstruction('div', userTemplates)).toBe('Keep it short.');
+      expect(generateElementInstruction('div', userTemplates)).toBe(
+        'Keep it short.'
+      );
     });
 
     it('should not affect other types when user overrides one', () => {
       const userTemplates = { button: 'Max 2 words.' };
       expect(generateElementInstruction('a', userTemplates)).toBe(
-        DEFAULT_INSTRUCTION_TEMPLATES['a'],
+        DEFAULT_INSTRUCTION_TEMPLATES['a']
       );
     });
   });
@@ -129,15 +135,23 @@ describe('sync-instructions', () => {
   // -------------------------------------------------------------------
   describe('mergeInstructions', () => {
     it('should return user instructions only when no auto instruction', () => {
-      expect(mergeInstructions(['instruction1'], undefined)).toEqual(['instruction1']);
+      expect(mergeInstructions(['instruction1'], undefined)).toEqual([
+        'instruction1',
+      ]);
     });
 
     it('should return auto instruction only when no user instructions', () => {
-      expect(mergeInstructions(undefined, 'auto instruction')).toEqual(['auto instruction']);
+      expect(mergeInstructions(undefined, 'auto instruction')).toEqual([
+        'auto instruction',
+      ]);
     });
 
     it('should append auto instruction after user instructions', () => {
-      expect(mergeInstructions(['user1', 'user2'], 'auto')).toEqual(['user1', 'user2', 'auto']);
+      expect(mergeInstructions(['user1', 'user2'], 'auto')).toEqual([
+        'user1',
+        'user2',
+        'auto',
+      ]);
     });
 
     it('should return undefined when both inputs are undefined', () => {
@@ -149,7 +163,10 @@ describe('sync-instructions', () => {
     });
 
     it('should preserve empty strings in user instructions', () => {
-      expect(mergeInstructions(['', 'valid'], undefined)).toEqual(['', 'valid']);
+      expect(mergeInstructions(['', 'valid'], undefined)).toEqual([
+        '',
+        'valid',
+      ]);
     });
 
     it('should return empty array contents when user passes empty array and no auto', () => {
@@ -157,7 +174,12 @@ describe('sync-instructions', () => {
     });
 
     it('should handle multiple user instructions with auto', () => {
-      expect(mergeInstructions(['a', 'b', 'c'], 'auto')).toEqual(['a', 'b', 'c', 'auto']);
+      expect(mergeInstructions(['a', 'b', 'c'], 'auto')).toEqual([
+        'a',
+        'b',
+        'c',
+        'auto',
+      ]);
     });
 
     it('should cap at MAX_INSTRUCTIONS when more than 5 instructions provided', () => {
@@ -166,7 +188,9 @@ describe('sync-instructions', () => {
       const result = mergeInstructions(instructions, undefined);
       expect(result).toHaveLength(MAX_INSTRUCTIONS);
       expect(result).toEqual(['a', 'b', 'c', 'd', 'e']);
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('exceeds maximum'));
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('exceeds maximum')
+      );
       warnSpy.mockRestore();
     });
 
@@ -176,16 +200,22 @@ describe('sync-instructions', () => {
       const result = mergeInstructions([longInstruction], undefined);
       expect(result).toHaveLength(1);
       expect(result![0]).toHaveLength(MAX_INSTRUCTION_LENGTH);
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('truncated'));
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('truncated')
+      );
       warnSpy.mockRestore();
     });
 
     it('should both truncate and cap when needed', () => {
       const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
-      const instructions = Array.from({ length: 7 }, (_, i) => 'y'.repeat(MAX_INSTRUCTION_LENGTH + i + 1));
+      const instructions = Array.from({ length: 7 }, (_, i) =>
+        'y'.repeat(MAX_INSTRUCTION_LENGTH + i + 1)
+      );
       const result = mergeInstructions(instructions, undefined);
       expect(result).toHaveLength(MAX_INSTRUCTIONS);
-      expect(result!.every(i => i.length === MAX_INSTRUCTION_LENGTH)).toBe(true);
+      expect(result!.every((i) => i.length === MAX_INSTRUCTION_LENGTH)).toBe(
+        true
+      );
       expect(warnSpy).toHaveBeenCalledTimes(2);
       warnSpy.mockRestore();
     });
@@ -219,14 +249,14 @@ describe('sync-instructions', () => {
       'should include %s',
       (element) => {
         expect(LENGTH_CONSTRAINED_ELEMENTS.has(element)).toBe(true);
-      },
+      }
     );
 
     it.each(['a', 'h1', 'h2', 'p', 'div'])(
       'should not include %s',
       (element) => {
         expect(LENGTH_CONSTRAINED_ELEMENTS.has(element)).toBe(false);
-      },
+      }
     );
   });
 
@@ -244,7 +274,9 @@ describe('sync-instructions', () => {
     });
 
     it('should return undefined for non-length-constrained element', () => {
-      expect(generateLengthInstruction('Click here', 'p', 'de')).toBeUndefined();
+      expect(
+        generateLengthInstruction('Click here', 'p', 'de')
+      ).toBeUndefined();
       expect(generateLengthInstruction('Heading', 'div', 'de')).toBeUndefined();
     });
 
@@ -253,7 +285,9 @@ describe('sync-instructions', () => {
     });
 
     it('should return undefined for undefined elementType', () => {
-      expect(generateLengthInstruction('text', undefined, 'de')).toBeUndefined();
+      expect(
+        generateLengthInstruction('text', undefined, 'de')
+      ).toBeUndefined();
     });
 
     it('should return undefined for locale without expansion factor', () => {
diff --git a/tests/unit/sync/sync-locale-translator.test.ts b/tests/unit/sync/sync-locale-translator.test.ts
index 22564240..6e2344b9 100644
--- a/tests/unit/sync/sync-locale-translator.test.ts
+++ b/tests/unit/sync/sync-locale-translator.test.ts
@@ -41,18 +41,35 @@ jest.mock('../../../src/sync/translation-validator', () => ({
 
 import * as fs from 'fs';
 import { atomicWriteFile } from '../../../src/utils/atomic-write';
-import { resolveTargetPath, assertPathWithinRoot } from '../../../src/sync/sync-utils';
+import {
+  resolveTargetPath,
+  assertPathWithinRoot,
+} from '../../../src/sync/sync-utils';
 import { validateBatch } from '../../../src/sync/translation-validator';
 
-const mockReadFile = fs.promises.readFile as jest.MockedFunction<typeof fs.promises.readFile>;
-const mockMkdir = fs.promises.mkdir as jest.MockedFunction<typeof fs.promises.mkdir>;
-const mockAtomicWriteFile = atomicWriteFile as jest.MockedFunction<typeof atomicWriteFile>;
-const mockResolveTargetPath = resolveTargetPath as jest.MockedFunction<typeof resolveTargetPath>;
-const mockAssertPathWithinRoot = assertPathWithinRoot as jest.MockedFunction<typeof assertPathWithinRoot>;
-const mockValidateBatch = validateBatch as jest.MockedFunction<typeof validateBatch>;
+const mockReadFile = fs.promises.readFile as jest.MockedFunction<
+  typeof fs.promises.readFile
+>;
+const mockMkdir = fs.promises.mkdir as jest.MockedFunction<
+  typeof fs.promises.mkdir
+>;
+const mockAtomicWriteFile = atomicWriteFile as jest.MockedFunction<
+  typeof atomicWriteFile
+>;
+const mockResolveTargetPath = resolveTargetPath as jest.MockedFunction<
+  typeof resolveTargetPath
+>;
+const mockAssertPathWithinRoot = assertPathWithinRoot as jest.MockedFunction<
+  typeof assertPathWithinRoot
+>;
+const mockValidateBatch = validateBatch as jest.MockedFunction<
+  typeof validateBatch
+>;
 
 beforeEach(() => {
-  mockReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+  mockReadFile.mockRejectedValue(
+    Object.assign(new Error('ENOENT'), { code: 'ENOENT' })
+  );
   mockMkdir.mockResolvedValue(undefined);
   mockAtomicWriteFile.mockResolvedValue(undefined);
   mockResolveTargetPath.mockReturnValue('locales/de.json');
@@ -68,11 +85,17 @@ function makeTranslationResult(text: string, billedCharacters = text.length) {
   return { text, billedCharacters, detectedSourceLanguage: 'en' as const };
 }
 
-function makeDiff(key: string, value: string, metadata?: Record<string, unknown>): SyncDiff {
+function makeDiff(
+  key: string,
+  value: string,
+  metadata?: Record<string, unknown>
+): SyncDiff {
   return { key, value, status: 'new' as const, metadata };
 }
 
-function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+function makeConfig(
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -100,7 +123,7 @@ function makeParser(): FormatParser {
 function makeCtx(
   diffs: SyncDiff[],
   keyContexts: Map<string, KeyContext>,
-  locale = 'de',
+  locale = 'de'
 ): LocaleTranslatorContext {
   return {
     locale,
@@ -108,7 +131,7 @@ function makeCtx(
     content: '{}',
     parser: makeParser(),
     diffs,
-    toTranslate: diffs.filter(d => d.status === 'new'),
+    toTranslate: diffs.filter((d) => d.status === 'new'),
     fileLockEntries: {},
     existingTargetEntries: new Map(),
     keyContexts,
@@ -131,12 +154,20 @@ function captureTranslateBatch(returnTexts: string[]): {
   const calls: CapturedCall[] = [];
   let callIndex = 0;
   const mock = createMockTranslationService({
-    translateBatch: jest.fn().mockImplementation((texts: string[], opts: TranslationOptions) => {
-      calls.push({ texts: [...texts], opts: { ...opts } });
-      const start = callIndex;
-      callIndex += texts.length;
-      return Promise.resolve(texts.map((_, i) => makeTranslationResult(returnTexts[start + i] ?? `translated-${start + i}`)));
-    }),
+    translateBatch: jest
+      .fn()
+      .mockImplementation((texts: string[], opts: TranslationOptions) => {
+        calls.push({ texts: [...texts], opts: { ...opts } });
+        const start = callIndex;
+        callIndex += texts.length;
+        return Promise.resolve(
+          texts.map((_, i) =>
+            makeTranslationResult(
+              returnTexts[start + i] ?? `translated-${start + i}`
+            )
+          )
+        );
+      }),
   });
   return { mock, calls };
 }
@@ -144,7 +175,7 @@ function captureTranslateBatch(returnTexts: string[]): {
 function makeTranslator(
   svc: ReturnType<typeof createMockTranslationService>,
   config: ResolvedSyncConfig,
-  forceBatch?: boolean,
+  forceBatch?: boolean
 ): LocaleTranslator {
   return new LocaleTranslator(
     svc,
@@ -153,7 +184,7 @@ function makeTranslator(
     undefined,
     undefined,
     forceBatch,
-    undefined,
+    undefined
   );
 }
 
@@ -164,7 +195,10 @@ describe('LocaleTranslator', () => {
   describe('Path A — plain batch', () => {
     it('should call translateBatch without context or custom_instructions', async () => {
       const config = makeConfig();
-      const diffs = [makeDiff('greeting', 'Hello'), makeDiff('farewell', 'Goodbye')];
+      const diffs = [
+        makeDiff('greeting', 'Hello'),
+        makeDiff('farewell', 'Goodbye'),
+      ];
       const { mock, calls } = captureTranslateBatch(['Hallo', 'Tschüss']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
@@ -203,20 +237,42 @@ describe('LocaleTranslator', () => {
         makeDiff('other.key', 'Other'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['nav.home', { key: 'nav.home', context: 'Navigation link', occurrences: 1, elementType: null }],
-        ['nav.about', { key: 'nav.about', context: 'Navigation link', occurrences: 1, elementType: null }],
+        [
+          'nav.home',
+          {
+            key: 'nav.home',
+            context: 'Navigation link',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
+        [
+          'nav.about',
+          {
+            key: 'nav.about',
+            context: 'Navigation link',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
+      ]);
+      const { mock, calls } = captureTranslateBatch([
+        'Startseite',
+        'Über uns',
+        'Andere',
       ]);
-      const { mock, calls } = captureTranslateBatch(['Startseite', 'Über uns', 'Andere']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
 
       // Path A call (other.key)
-      const plainCall = calls.find(c => c.opts.context === undefined);
+      const plainCall = calls.find((c) => c.opts.context === undefined);
       expect(plainCall).toBeDefined();
       expect(plainCall!.opts.customInstructions).toBeUndefined();
 
       // Path B1 call (nav.*)
-      const contextCall = calls.find(c => c.opts.context !== undefined && c.opts.context !== '');
+      const contextCall = calls.find(
+        (c) => c.opts.context !== undefined && c.opts.context !== ''
+      );
       expect(contextCall).toBeDefined();
       expect(contextCall!.opts.context).toMatch(/nav/i);
       expect(contextCall!.opts.customInstructions).toBeUndefined();
@@ -234,15 +290,35 @@ describe('LocaleTranslator', () => {
         makeDiff('btn.cancel', 'Cancel'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['btn.save', { key: 'btn.save', context: 'Save button label', occurrences: 1, elementType: null }],
-        ['btn.cancel', { key: 'btn.cancel', context: 'Cancel button label', occurrences: 1, elementType: null }],
+        [
+          'btn.save',
+          {
+            key: 'btn.save',
+            context: 'Save button label',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
+        [
+          'btn.cancel',
+          {
+            key: 'btn.cancel',
+            context: 'Cancel button label',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
       ]);
       const { mock, calls } = captureTranslateBatch(['Speichern', 'Abbrechen']);
       // forceBatch=false → per-key (--no-batch mode)
-      await makeTranslator(mock, config, false).translate(makeCtx(diffs, keyContexts));
+      await makeTranslator(mock, config, false).translate(
+        makeCtx(diffs, keyContexts)
+      );
 
       // Each context key gets its own call
-      const contextCalls = calls.filter(c => c.opts.context && c.opts.context !== '');
+      const contextCalls = calls.filter(
+        (c) => c.opts.context && c.opts.context !== ''
+      );
       expect(contextCalls).toHaveLength(2);
       for (const call of contextCalls) {
         expect(call.opts.context).toBeTruthy();
@@ -257,20 +333,35 @@ describe('LocaleTranslator', () => {
   describe('Path C — element instruction batch', () => {
     it('should send custom_instructions containing element-specific text for button keys', async () => {
       const config = makeConfig();
-      const diffs = [makeDiff('cta.submit', 'Submit'), makeDiff('nav.home', 'Home')];
+      const diffs = [
+        makeDiff('cta.submit', 'Submit'),
+        makeDiff('nav.home', 'Home'),
+      ];
       const keyContexts = new Map<string, KeyContext>([
-        ['cta.submit', { key: 'cta.submit', context: '', occurrences: 1, elementType: 'button' }],
+        [
+          'cta.submit',
+          {
+            key: 'cta.submit',
+            context: '',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
       ]);
       const { mock, calls } = captureTranslateBatch(['Absenden', 'Startseite']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
 
-      const instructionCall = calls.find(c =>
-        Array.isArray(c.opts.customInstructions) && c.opts.customInstructions.length > 0,
+      const instructionCall = calls.find(
+        (c) =>
+          Array.isArray(c.opts.customInstructions) &&
+          c.opts.customInstructions.length > 0
       );
       expect(instructionCall).toBeDefined();
       expect(instructionCall!.opts.customInstructions).toEqual(
-        expect.arrayContaining([expect.stringMatching(/concise|maximum 3 words/i)]),
+        expect.arrayContaining([
+          expect.stringMatching(/concise|maximum 3 words/i),
+        ])
       );
       expect(instructionCall!.opts.context).toBeUndefined();
     });
@@ -278,20 +369,33 @@ describe('LocaleTranslator', () => {
     it('should send element-type-specific instructions for anchor (a) elements', async () => {
       const config = makeConfig();
       // Need 2+ keys to trigger the three-way partition (single key uses fast path)
-      const diffs = [makeDiff('link.read_more', 'Read more'), makeDiff('plain.key', 'Plain')];
+      const diffs = [
+        makeDiff('link.read_more', 'Read more'),
+        makeDiff('plain.key', 'Plain'),
+      ];
       const keyContexts = new Map<string, KeyContext>([
-        ['link.read_more', { key: 'link.read_more', context: '', occurrences: 1, elementType: 'a' }],
+        [
+          'link.read_more',
+          {
+            key: 'link.read_more',
+            context: '',
+            occurrences: 1,
+            elementType: 'a',
+          },
+        ],
       ]);
       const { mock, calls } = captureTranslateBatch(['Mehr lesen', 'Schlicht']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
 
-      const instructionCall = calls.find(c =>
-        Array.isArray(c.opts.customInstructions) && c.opts.customInstructions.length > 0,
+      const instructionCall = calls.find(
+        (c) =>
+          Array.isArray(c.opts.customInstructions) &&
+          c.opts.customInstructions.length > 0
       );
       expect(instructionCall).toBeDefined();
       expect(instructionCall!.opts.customInstructions).toEqual(
-        expect.arrayContaining([expect.stringMatching(/link text|concise/i)]),
+        expect.arrayContaining([expect.stringMatching(/link text|concise/i)])
       );
     });
   });
@@ -308,16 +412,46 @@ describe('LocaleTranslator', () => {
         makeDiff('cta.submit', 'Submit'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['cta.save', { key: 'cta.save', context: '', occurrences: 1, elementType: 'button' }],
-        ['cta.delete', { key: 'cta.delete', context: '', occurrences: 1, elementType: 'button' }],
-        ['cta.submit', { key: 'cta.submit', context: '', occurrences: 1, elementType: 'button' }],
+        [
+          'cta.save',
+          {
+            key: 'cta.save',
+            context: '',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+        [
+          'cta.delete',
+          {
+            key: 'cta.delete',
+            context: '',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+        [
+          'cta.submit',
+          {
+            key: 'cta.submit',
+            context: '',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+      ]);
+      const { mock, calls } = captureTranslateBatch([
+        'Speichern',
+        'Löschen',
+        'Absenden',
       ]);
-      const { mock, calls } = captureTranslateBatch(['Speichern', 'Löschen', 'Absenden']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
 
-      const instructionCalls = calls.filter(c =>
-        Array.isArray(c.opts.customInstructions) && c.opts.customInstructions.length > 0,
+      const instructionCalls = calls.filter(
+        (c) =>
+          Array.isArray(c.opts.customInstructions) &&
+          c.opts.customInstructions.length > 0
       );
       expect(instructionCalls).toHaveLength(1);
       expect(instructionCalls[0]!.texts).toHaveLength(3);
@@ -330,20 +464,43 @@ describe('LocaleTranslator', () => {
         makeDiff('heading.title', 'Welcome'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['cta.save', { key: 'cta.save', context: '', occurrences: 1, elementType: 'button' }],
-        ['heading.title', { key: 'heading.title', context: '', occurrences: 1, elementType: 'h1' }],
+        [
+          'cta.save',
+          {
+            key: 'cta.save',
+            context: '',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+        [
+          'heading.title',
+          {
+            key: 'heading.title',
+            context: '',
+            occurrences: 1,
+            elementType: 'h1',
+          },
+        ],
+      ]);
+      const { mock, calls } = captureTranslateBatch([
+        'Speichern',
+        'Willkommen',
       ]);
-      const { mock, calls } = captureTranslateBatch(['Speichern', 'Willkommen']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
 
-      const instructionCalls = calls.filter(c =>
-        Array.isArray(c.opts.customInstructions) && c.opts.customInstructions.length > 0,
+      const instructionCalls = calls.filter(
+        (c) =>
+          Array.isArray(c.opts.customInstructions) &&
+          c.opts.customInstructions.length > 0
       );
       expect(instructionCalls).toHaveLength(2);
-      const instructions = instructionCalls.map(c => c.opts.customInstructions!.join(' '));
-      expect(instructions.some(i => /3 words/i.test(i))).toBe(true); // button
-      expect(instructions.some(i => /heading|impactful/i.test(i))).toBe(true); // h1
+      const instructions = instructionCalls.map((c) =>
+        c.opts.customInstructions!.join(' ')
+      );
+      expect(instructions.some((i) => /3 words/i.test(i))).toBe(true); // button
+      expect(instructions.some((i) => /heading|impactful/i.test(i))).toBe(true); // h1
     });
   });
 
@@ -358,14 +515,17 @@ describe('LocaleTranslator', () => {
           msgid_plural: '%d items',
         }),
       ];
-      const { mock, calls } = captureTranslateBatch(['1 Element', '%d Elemente']);
+      const { mock, calls } = captureTranslateBatch([
+        '1 Element',
+        '%d Elemente',
+      ]);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
 
       // The plain batch call should contain both the singular and plural text.
       // %d is preserved as a placeholder token by preserveVariables, so we
       // only assert on length and a substring that survives preservation.
-      const batchCall = calls.find(c => c.opts.context === undefined);
+      const batchCall = calls.find((c) => c.opts.context === undefined);
       expect(batchCall).toBeDefined();
       expect(batchCall!.texts).toHaveLength(2);
       expect(batchCall!.texts[0]).toContain('item');
@@ -380,14 +540,28 @@ describe('LocaleTranslator', () => {
         makeDiff('plain.other', 'Other text'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['btn.count', { key: 'btn.count', context: '', occurrences: 1, elementType: 'button' }],
+        [
+          'btn.count',
+          {
+            key: 'btn.count',
+            context: '',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+      ]);
+      const { mock, calls } = captureTranslateBatch([
+        '1 Klick',
+        '%d Klicks',
+        'Anderer Text',
       ]);
-      const { mock, calls } = captureTranslateBatch(['1 Klick', '%d Klicks', 'Anderer Text']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
 
-      const instructionCall = calls.find(c =>
-        Array.isArray(c.opts.customInstructions) && c.opts.customInstructions.length > 0,
+      const instructionCall = calls.find(
+        (c) =>
+          Array.isArray(c.opts.customInstructions) &&
+          c.opts.customInstructions.length > 0
       );
       expect(instructionCall).toBeDefined();
       // Both plural forms (singular + plural slot) should be in the instruction batch
@@ -412,7 +586,10 @@ describe('LocaleTranslator', () => {
         makeDiff('plain.text', 'Some text'), // ensures three-way partition activates
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['cta.ok', { key: 'cta.ok', context: '', occurrences: 1, elementType: 'button' }],
+        [
+          'cta.ok',
+          { key: 'cta.ok', context: '', occurrences: 1, elementType: 'button' },
+        ],
       ]);
       const { mock, calls } = captureTranslateBatch(['OK', 'Irgendein Text']);
 
@@ -421,12 +598,14 @@ describe('LocaleTranslator', () => {
       // The button key must have been translated with custom_instructions (Path C).
       // If generateElementInstruction returns undefined the key falls to Path A and
       // both keys are batched together WITHOUT custom_instructions — canary fires.
-      const instructionCall = calls.find(c =>
-        Array.isArray(c.opts.customInstructions) && c.opts.customInstructions.length > 0,
+      const instructionCall = calls.find(
+        (c) =>
+          Array.isArray(c.opts.customInstructions) &&
+          c.opts.customInstructions.length > 0
       );
       expect(instructionCall).toBeDefined();
       expect(instructionCall!.opts.customInstructions).toEqual(
-        expect.arrayContaining([expect.stringMatching(/concise|3 words/i)]),
+        expect.arrayContaining([expect.stringMatching(/concise|3 words/i)])
       );
     });
   });
@@ -438,7 +617,10 @@ describe('LocaleTranslator', () => {
     it('should propagate translationMemoryId to every translateBatch call', async () => {
       const TM_ID = 'tm-abc-123';
       const config = makeConfig();
-      const diffs = [makeDiff('greeting', 'Hello'), makeDiff('farewell', 'Goodbye')];
+      const diffs = [
+        makeDiff('greeting', 'Hello'),
+        makeDiff('farewell', 'Goodbye'),
+      ];
       const { mock, calls } = captureTranslateBatch(['Hallo', 'Tschüss']);
       const translator = new LocaleTranslator(
         mock,
@@ -447,7 +629,7 @@ describe('LocaleTranslator', () => {
         undefined,
         TM_ID,
         undefined,
-        undefined,
+        undefined
       );
 
       await translator.translate(makeCtx(diffs, new Map()));
@@ -470,7 +652,7 @@ describe('LocaleTranslator', () => {
         GLOSSARY_ID,
         undefined,
         undefined,
-        undefined,
+        undefined
       );
 
       await translator.translate(makeCtx(diffs, new Map()));
@@ -490,11 +672,21 @@ describe('LocaleTranslator', () => {
       const config = makeConfig();
       const diffs = [makeDiff('greeting', 'Hello')];
       const keyContexts = new Map<string, KeyContext>([
-        ['greeting', { key: 'greeting', context: 'Homepage hero line', occurrences: 1, elementType: null }],
+        [
+          'greeting',
+          {
+            key: 'greeting',
+            context: 'Homepage hero line',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
       ]);
       const { mock, calls } = captureTranslateBatch(['Hallo']);
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, keyContexts)
+      );
 
       expect(calls).toHaveLength(1);
       expect(calls[0]!.opts.context).toBe('Homepage hero line');
@@ -505,11 +697,21 @@ describe('LocaleTranslator', () => {
       const config = makeConfig();
       const diffs = [makeDiff('greeting', 'Hello')];
       const keyContexts = new Map<string, KeyContext>([
-        ['greeting', { key: 'greeting', context: 'Irrelevant in force-batch mode', occurrences: 1, elementType: null }],
+        [
+          'greeting',
+          {
+            key: 'greeting',
+            context: 'Irrelevant in force-batch mode',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
       ]);
       const { mock } = captureTranslateBatch(['Hallo']);
 
-      const result = await makeTranslator(mock, config, true).translate(makeCtx(diffs, keyContexts));
+      const result = await makeTranslator(mock, config, true).translate(
+        makeCtx(diffs, keyContexts)
+      );
 
       expect(result.contextSentKeys.has('greeting')).toBe(false);
     });
@@ -522,11 +724,19 @@ describe('LocaleTranslator', () => {
     it('should tally warnings and errors from validateBatch when validation is enabled', async () => {
       mockValidateBatch.mockReturnValueOnce([
         {
-          key: 'a', source: 'Alpha', translation: 'A', severity: 'warn',
-          issues: [{ check: 'placeholder', severity: 'warn', message: 'warning' }],
+          key: 'a',
+          source: 'Alpha',
+          translation: 'A',
+          severity: 'warn',
+          issues: [
+            { check: 'placeholder', severity: 'warn', message: 'warning' },
+          ],
         },
         {
-          key: 'b', source: 'Beta', translation: 'B', severity: 'error',
+          key: 'b',
+          source: 'Beta',
+          translation: 'B',
+          severity: 'error',
           issues: [
             { check: 'placeholder', severity: 'error', message: 'error1' },
             { check: 'placeholder', severity: 'error', message: 'error2' },
@@ -540,7 +750,9 @@ describe('LocaleTranslator', () => {
       const diffs = [makeDiff('a', 'Alpha'), makeDiff('b', 'Beta')];
       const { mock } = captureTranslateBatch(['A', 'B']);
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, new Map())
+      );
 
       expect(result.validationWarnings).toBe(1);
       expect(result.validationErrors).toBe(2);
@@ -553,7 +765,9 @@ describe('LocaleTranslator', () => {
       const diffs = [makeDiff('a', 'Alpha')];
       const { mock } = captureTranslateBatch(['A']);
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, new Map())
+      );
 
       expect(mockValidateBatch).not.toHaveBeenCalled();
       expect(result.validationWarnings).toBe(0);
@@ -570,13 +784,14 @@ describe('LocaleTranslator', () => {
       const diffs = [makeDiff('a', 'Alpha'), makeDiff('b', 'Beta')];
       // translateBatch returns null for the second entry
       const mock = createMockTranslationService({
-        translateBatch: jest.fn().mockResolvedValue([
-          makeTranslationResult('A'),
-          null,
-        ]),
+        translateBatch: jest
+          .fn()
+          .mockResolvedValue([makeTranslationResult('A'), null]),
       });
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, new Map())
+      );
 
       expect(result.fileResult.translated).toBe(1);
       expect(result.fileResult.failed).toBe(1);
@@ -604,7 +819,9 @@ describe('LocaleTranslator', () => {
 
       const result = await makeTranslator(mock, config).translate(ctx);
 
-      expect(result.targetEntries.get('existing_key')).toBe('Alter Wert (prior translation)');
+      expect(result.targetEntries.get('existing_key')).toBe(
+        'Alter Wert (prior translation)'
+      );
       expect(result.targetEntries.get('new_key')).toBe('Neuer Wert');
     });
 
@@ -626,7 +843,13 @@ describe('LocaleTranslator', () => {
           b: {
             source_hash: 'h',
             source_text: 'Beta',
-            translations: { de: { hash: 'th', translated_at: '2026-04-23T00:00:00Z', status: 'translated' } },
+            translations: {
+              de: {
+                hash: 'th',
+                translated_at: '2026-04-23T00:00:00Z',
+                status: 'translated',
+              },
+            },
           },
         },
       };
@@ -659,9 +882,13 @@ describe('LocaleTranslator', () => {
       const result = await makeTranslator(mock, config).translate(ctx);
 
       // New-locale branch translates the untranslatedCurrentKeys set.
-      const newLocaleCall = calls.find(c => c.texts.includes('Existing value'));
+      const newLocaleCall = calls.find((c) =>
+        c.texts.includes('Existing value')
+      );
       expect(newLocaleCall).toBeDefined();
-      expect(result.targetEntries.get('existing_key')).toBe('Existierender Wert');
+      expect(result.targetEntries.get('existing_key')).toBe(
+        'Existierender Wert'
+      );
       expect(result.successfulKeys).toContain('existing_key');
       expect(result.fileResult.translated).toBe(1);
     });
@@ -680,7 +907,9 @@ describe('LocaleTranslator', () => {
           callIdx++;
           if (callIdx === 1) return Promise.resolve([]);
           return Promise.resolve(
-            texts.map((t) => makeTranslationResult(t.replace(/Hello/i, 'Hallo'))),
+            texts.map((t) =>
+              makeTranslationResult(t.replace(/Hello/i, 'Hallo'))
+            )
           );
         }),
       });
@@ -744,12 +973,17 @@ describe('LocaleTranslator', () => {
       await makeTranslator(mock, config).translate(ctx);
 
       // reconstruct should have been called with the existing target content as the template
-      expect(parser.reconstruct).toHaveBeenCalledWith(existingTarget, expect.any(Array));
+      expect(parser.reconstruct).toHaveBeenCalledWith(
+        existingTarget,
+        expect.any(Array)
+      );
     });
 
     it('should create a .deepl.bak copy of the existing target when the target exists and backup is not disabled', async () => {
       mockReadFile.mockResolvedValueOnce('{"prior":"X"}');
-      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<typeof fs.promises.copyFile>;
+      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<
+        typeof fs.promises.copyFile
+      >;
       copyFileSpy.mockResolvedValueOnce(undefined);
 
       const config = makeConfig();
@@ -765,7 +999,9 @@ describe('LocaleTranslator', () => {
 
     it('should skip the backup when sync.backup is explicitly false', async () => {
       mockReadFile.mockResolvedValueOnce('{"prior":"X"}');
-      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<typeof fs.promises.copyFile>;
+      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<
+        typeof fs.promises.copyFile
+      >;
       copyFileSpy.mockResolvedValueOnce(undefined);
 
       const config = makeConfig({
@@ -790,13 +1026,17 @@ describe('LocaleTranslator', () => {
         makeDiff('item_count', '1 item', { msgid_plural: '%d items' }),
         makeDiff('greeting', 'Hello'),
       ];
-      const { mock, calls } = captureTranslateBatch(['1 Element', '%d Elemente', 'Hallo']);
+      const { mock, calls } = captureTranslateBatch([
+        '1 Element',
+        '%d Elemente',
+        'Hallo',
+      ]);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
 
       // The three-way-partition batch should contain the singular text, the plural
       // text (slot), and the second plain key. Single plain batch call.
-      const batchCall = calls.find(c => c.opts.context === undefined);
+      const batchCall = calls.find((c) => c.opts.context === undefined);
       expect(batchCall).toBeDefined();
       expect(batchCall!.texts.length).toBeGreaterThanOrEqual(3);
     });
@@ -809,14 +1049,36 @@ describe('LocaleTranslator', () => {
         makeDiff('nav.home', 'Home'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['nav.count', { key: 'nav.count', context: 'Navigation count', occurrences: 1, elementType: null }],
-        ['nav.home', { key: 'nav.home', context: 'Navigation link', occurrences: 1, elementType: null }],
+        [
+          'nav.count',
+          {
+            key: 'nav.count',
+            context: 'Navigation count',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
+        [
+          'nav.home',
+          {
+            key: 'nav.home',
+            context: 'Navigation link',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
+      ]);
+      const { mock, calls } = captureTranslateBatch([
+        '1 Link',
+        '%d Links',
+        'Startseite',
       ]);
-      const { mock, calls } = captureTranslateBatch(['1 Link', '%d Links', 'Startseite']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
 
-      const sectionCall = calls.find(c => c.opts.context !== undefined && c.opts.context !== '');
+      const sectionCall = calls.find(
+        (c) => c.opts.context !== undefined && c.opts.context !== ''
+      );
       expect(sectionCall).toBeDefined();
       expect(sectionCall!.texts.length).toBeGreaterThanOrEqual(3);
     });
@@ -830,12 +1092,30 @@ describe('LocaleTranslator', () => {
       // Context AND elementType on the same keys — both get section-batched AND
       // contribute to instructionGroupCounts.
       const keyContexts = new Map<string, KeyContext>([
-        ['cta.save', { key: 'cta.save', context: 'Call-to-action row', occurrences: 1, elementType: 'button' }],
-        ['cta.cancel', { key: 'cta.cancel', context: 'Call-to-action row', occurrences: 1, elementType: 'button' }],
+        [
+          'cta.save',
+          {
+            key: 'cta.save',
+            context: 'Call-to-action row',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+        [
+          'cta.cancel',
+          {
+            key: 'cta.cancel',
+            context: 'Call-to-action row',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
       ]);
       const { mock } = captureTranslateBatch(['Speichern', 'Abbrechen']);
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, keyContexts)
+      );
 
       expect(result.instructionSentKeys.has('cta.save')).toBe(true);
       expect(result.instructionSentKeys.has('cta.cancel')).toBe(true);
@@ -849,13 +1129,31 @@ describe('LocaleTranslator', () => {
         makeDiff('btn.cancel', 'Cancel'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['btn.save', { key: 'btn.save', context: 'Save button label', occurrences: 1, elementType: 'button' }],
-        ['btn.cancel', { key: 'btn.cancel', context: 'Cancel button label', occurrences: 1, elementType: 'button' }],
+        [
+          'btn.save',
+          {
+            key: 'btn.save',
+            context: 'Save button label',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+        [
+          'btn.cancel',
+          {
+            key: 'btn.cancel',
+            context: 'Cancel button label',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
       ]);
       const { mock } = captureTranslateBatch(['Speichern', 'Abbrechen']);
 
       // forceBatch=false → Path B2
-      const result = await makeTranslator(mock, config, false).translate(makeCtx(diffs, keyContexts));
+      const result = await makeTranslator(mock, config, false).translate(
+        makeCtx(diffs, keyContexts)
+      );
 
       expect(result.instructionSentKeys.has('btn.save')).toBe(true);
       expect(result.instructionSentKeys.has('btn.cancel')).toBe(true);
@@ -869,16 +1167,38 @@ describe('LocaleTranslator', () => {
         makeDiff('btn.cancel', 'Cancel'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['btn.count', { key: 'btn.count', context: 'Click counter label', occurrences: 1, elementType: null }],
-        ['btn.cancel', { key: 'btn.cancel', context: 'Cancel button label', occurrences: 1, elementType: null }],
+        [
+          'btn.count',
+          {
+            key: 'btn.count',
+            context: 'Click counter label',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
+        [
+          'btn.cancel',
+          {
+            key: 'btn.cancel',
+            context: 'Cancel button label',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
+      ]);
+      const { mock, calls } = captureTranslateBatch([
+        '1 Klick',
+        '%d Klicks',
+        'Abbrechen',
       ]);
-      const { mock, calls } = captureTranslateBatch(['1 Klick', '%d Klicks', 'Abbrechen']);
 
-      await makeTranslator(mock, config, false).translate(makeCtx(diffs, keyContexts));
+      await makeTranslator(mock, config, false).translate(
+        makeCtx(diffs, keyContexts)
+      );
 
       // The per-key call for btn.count should include both singular and plural.
-      const pluralKeyCall = calls.find(c =>
-        c.opts.context === 'Click counter label' && c.texts.length === 2,
+      const pluralKeyCall = calls.find(
+        (c) => c.opts.context === 'Click counter label' && c.texts.length === 2
       );
       expect(pluralKeyCall).toBeDefined();
     });
@@ -895,7 +1215,15 @@ describe('LocaleTranslator', () => {
       const diffs = [makeDiff('greeting', 'Hello')];
       // keyContexts has a different context — the override should win.
       const keyContexts = new Map<string, KeyContext>([
-        ['greeting', { key: 'greeting', context: 'Auto-extracted context', occurrences: 1, elementType: null }],
+        [
+          'greeting',
+          {
+            key: 'greeting',
+            context: 'Auto-extracted context',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
       ]);
       const { mock, calls } = captureTranslateBatch(['Hallo']);
 
@@ -913,15 +1241,33 @@ describe('LocaleTranslator', () => {
         makeDiff('nav.about', 'About'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['nav.home', { key: 'nav.home', context: 'Auto context', occurrences: 1, elementType: null }],
-        ['nav.about', { key: 'nav.about', context: 'Auto context', occurrences: 1, elementType: null }],
+        [
+          'nav.home',
+          {
+            key: 'nav.home',
+            context: 'Auto context',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
+        [
+          'nav.about',
+          {
+            key: 'nav.about',
+            context: 'Auto context',
+            occurrences: 1,
+            elementType: null,
+          },
+        ],
       ]);
       const { mock, calls } = captureTranslateBatch(['Startseite', 'Über uns']);
 
       await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts));
 
       // Override key goes through per-key batch with its specific context.
-      const overrideCall = calls.find(c => c.opts.context === 'Override for home link');
+      const overrideCall = calls.find(
+        (c) => c.opts.context === 'Override for home link'
+      );
       expect(overrideCall).toBeDefined();
       expect(overrideCall!.texts).toHaveLength(1);
     });
@@ -948,7 +1294,9 @@ describe('LocaleTranslator', () => {
       ];
       const { mock } = captureTranslateBatch(['Original-DE', 'A-DE', 'B-DE']);
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, new Map())
+      );
 
       // Sync proceeds — primary entry translated, no crash on the missing-primary branch.
       expect(result.targetEntries.get('items')).toBe('Original-DE');
@@ -966,12 +1314,30 @@ describe('LocaleTranslator', () => {
         makeDiff('cta.cancel', 'Cancel'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['cta.save', { key: 'cta.save', context: 'Call-to-action row', occurrences: 1, elementType: 'button' }],
-        ['cta.cancel', { key: 'cta.cancel', context: 'Call-to-action row', occurrences: 1, elementType: 'button' }],
+        [
+          'cta.save',
+          {
+            key: 'cta.save',
+            context: 'Call-to-action row',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+        [
+          'cta.cancel',
+          {
+            key: 'cta.cancel',
+            context: 'Call-to-action row',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
       ]);
       const { mock } = captureTranslateBatch(['Opslaan', 'Annuleren']);
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts, 'nl'));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, keyContexts, 'nl')
+      );
 
       // 'nl' does not support custom instructions, so even though elementType is
       // present, instructionSentKeys stays empty in Path B1.
@@ -986,12 +1352,30 @@ describe('LocaleTranslator', () => {
         makeDiff('btn.cancel', 'Cancel'),
       ];
       const keyContexts = new Map<string, KeyContext>([
-        ['btn.save', { key: 'btn.save', context: 'Save button label', occurrences: 1, elementType: 'button' }],
-        ['btn.cancel', { key: 'btn.cancel', context: 'Cancel button label', occurrences: 1, elementType: 'button' }],
+        [
+          'btn.save',
+          {
+            key: 'btn.save',
+            context: 'Save button label',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
+        [
+          'btn.cancel',
+          {
+            key: 'btn.cancel',
+            context: 'Cancel button label',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
       ]);
       const { mock } = captureTranslateBatch(['Opslaan', 'Annuleren']);
 
-      const result = await makeTranslator(mock, config, false).translate(makeCtx(diffs, keyContexts, 'nl'));
+      const result = await makeTranslator(mock, config, false).translate(
+        makeCtx(diffs, keyContexts, 'nl')
+      );
 
       expect(result.instructionSentKeys.size).toBe(0);
       expect(result.instructionGroupCounts.size).toBe(0);
@@ -1012,7 +1396,9 @@ describe('LocaleTranslator', () => {
         ]),
       });
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, new Map())
+      );
 
       expect(result.charactersBilled).toBe(0);
       expect(result.billedPerKey.size).toBe(0);
@@ -1052,10 +1438,20 @@ describe('LocaleTranslator', () => {
   describe('target-file handling — containment ordering', () => {
     it('should assert containment before reading the target or writing the backup', async () => {
       const order: string[] = [];
-      mockAssertPathWithinRoot.mockImplementation(() => { order.push('assert'); });
-      mockReadFile.mockImplementation(() => { order.push('read'); return Promise.resolve('{"prior":"X"}'); });
-      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<typeof fs.promises.copyFile>;
-      copyFileSpy.mockImplementation(() => { order.push('copy'); return Promise.resolve(); });
+      mockAssertPathWithinRoot.mockImplementation(() => {
+        order.push('assert');
+      });
+      mockReadFile.mockImplementation(() => {
+        order.push('read');
+        return Promise.resolve('{"prior":"X"}');
+      });
+      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<
+        typeof fs.promises.copyFile
+      >;
+      copyFileSpy.mockImplementation(() => {
+        order.push('copy');
+        return Promise.resolve();
+      });
 
       const config = makeConfig();
       const diffs = [makeDiff('greeting', 'Hello')];
@@ -1074,14 +1470,16 @@ describe('LocaleTranslator', () => {
       mockAssertPathWithinRoot.mockImplementation(() => {
         throw new Error('Target path escapes project root: /evil/de.json');
       });
-      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<typeof fs.promises.copyFile>;
+      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<
+        typeof fs.promises.copyFile
+      >;
 
       const config = makeConfig();
       const diffs = [makeDiff('greeting', 'Hello')];
       const { mock } = captureTranslateBatch(['Hallo']);
 
       await expect(
-        makeTranslator(mock, config).translate(makeCtx(diffs, new Map())),
+        makeTranslator(mock, config).translate(makeCtx(diffs, new Map()))
       ).rejects.toThrow(/escapes project root/);
       expect(mockReadFile).not.toHaveBeenCalled();
       expect(copyFileSpy).not.toHaveBeenCalled();
@@ -1095,7 +1493,9 @@ describe('LocaleTranslator', () => {
   describe('target-file handling — backup failure', () => {
     it('should warn and continue when .bak copyFile rejects', async () => {
       mockReadFile.mockResolvedValueOnce('{"prior":"X"}');
-      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<typeof fs.promises.copyFile>;
+      const copyFileSpy = fs.promises.copyFile as jest.MockedFunction<
+        typeof fs.promises.copyFile
+      >;
       copyFileSpy.mockRejectedValueOnce(new Error('EACCES: permission denied'));
 
       const config = makeConfig();
@@ -1104,7 +1504,7 @@ describe('LocaleTranslator', () => {
 
       // Should not throw; backup failure is logged, sync proceeds.
       await expect(
-        makeTranslator(mock, config).translate(makeCtx(diffs, new Map())),
+        makeTranslator(mock, config).translate(makeCtx(diffs, new Map()))
       ).resolves.toBeDefined();
       expect(copyFileSpy).toHaveBeenCalled();
     });
@@ -1122,15 +1522,27 @@ describe('LocaleTranslator', () => {
       ];
       const keyContexts = new Map<string, KeyContext>([
         // cta.save has elementType but 'nl' does not support instructions
-        ['cta.save', { key: 'cta.save', context: '', occurrences: 1, elementType: 'button' }],
+        [
+          'cta.save',
+          {
+            key: 'cta.save',
+            context: '',
+            occurrences: 1,
+            elementType: 'button',
+          },
+        ],
       ]);
       const { mock, calls } = captureTranslateBatch(['Opslaan', 'Eenvoudig']);
 
-      await makeTranslator(mock, config).translate(makeCtx(diffs, keyContexts, 'nl'));
+      await makeTranslator(mock, config).translate(
+        makeCtx(diffs, keyContexts, 'nl')
+      );
 
       // No call should carry customInstructions because 'nl' is unsupported.
-      const instructionCall = calls.find(c =>
-        Array.isArray(c.opts.customInstructions) && c.opts.customInstructions.length > 0,
+      const instructionCall = calls.find(
+        (c) =>
+          Array.isArray(c.opts.customInstructions) &&
+          c.opts.customInstructions.length > 0
       );
       expect(instructionCall).toBeUndefined();
       // Both keys land in a single plain batch.
@@ -1160,7 +1572,9 @@ describe('LocaleTranslator', () => {
       ];
       const { mock } = captureTranslateBatch(['1 Element']);
 
-      const result = await makeTranslator(mock, config).translate(makeCtx(diffs, new Map()));
+      const result = await makeTranslator(mock, config).translate(
+        makeCtx(diffs, new Map())
+      );
 
       // targetEntries reflects the translation for the primary key
       expect(result.targetEntries.get('items')).toBe('1 Element');
@@ -1185,7 +1599,11 @@ describe('LocaleTranslator', () => {
 
       await makeTranslator(mock, config).translate(ctx);
 
-      expect(parser.reconstruct).toHaveBeenCalledWith(expect.any(String), expect.any(Array), 'de');
+      expect(parser.reconstruct).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.any(Array),
+        'de'
+      );
     });
   });
 });
diff --git a/tests/unit/sync/sync-lock.test.ts b/tests/unit/sync/sync-lock.test.ts
index 08b5bee2..97345a7b 100644
--- a/tests/unit/sync/sync-lock.test.ts
+++ b/tests/unit/sync/sync-lock.test.ts
@@ -1,7 +1,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { computeSourceHash, createEmptyLockFile, SyncLockManager } from '../../../src/sync/sync-lock';
+import {
+  computeSourceHash,
+  createEmptyLockFile,
+  SyncLockManager,
+} from '../../../src/sync/sync-lock';
 import { Logger } from '../../../src/utils/logger';
 import { LOCK_FILE_VERSION, LOCK_FILE_COMMENT } from '../../../src/sync/types';
 import type { SyncLockFile, SyncLockEntry } from '../../../src/sync/types';
@@ -40,7 +44,10 @@ describe('computeSourceHash()', () => {
   it('should produce different hash when plural metadata is provided', () => {
     const hashWithout = computeSourceHash('text');
     const hashWith = computeSourceHash('text', {
-      plurals: [{ quantity: 'one', value: '1 item' }, { quantity: 'other', value: '%d items' }],
+      plurals: [
+        { quantity: 'one', value: '1 item' },
+        { quantity: 'other', value: '%d items' },
+      ],
     });
     expect(hashWith).toHaveLength(12);
     expect(hashWith).not.toBe(hashWithout);
@@ -70,7 +77,9 @@ describe('computeSourceHash()', () => {
 
   it('should include plural_forms in hash', () => {
     const hashWithout = computeSourceHash('item');
-    const hashWith = computeSourceHash('item', { plural_forms: { 'msgstr[0]': '', 'msgstr[1]': '' } });
+    const hashWith = computeSourceHash('item', {
+      plural_forms: { 'msgstr[0]': '', 'msgstr[1]': '' },
+    });
     expect(hashWith).not.toBe(hashWithout);
   });
 });
@@ -127,7 +136,11 @@ describe('SyncLockManager', () => {
         generated_at: '2026-01-01T00:00:00.000Z',
         source_locale: 'en',
         entries: {},
-        stats: { total_keys: 0, total_translations: 0, last_sync: '2026-01-01T00:00:00.000Z' },
+        stats: {
+          total_keys: 0,
+          total_translations: 0,
+          last_sync: '2026-01-01T00:00:00.000Z',
+        },
       };
       fs.writeFileSync(lockFilePath, JSON.stringify(lockFile, null, 2));
       const result = await manager.read();
@@ -139,7 +152,9 @@ describe('SyncLockManager', () => {
       const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
       fs.writeFileSync(lockFilePath, '{not valid json!!!');
       const result = await manager.read();
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Lock file corrupted'));
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Lock file corrupted')
+      );
       expect(result.entries).toEqual({});
     });
 
@@ -149,7 +164,9 @@ describe('SyncLockManager', () => {
       fs.writeFileSync(lockFilePath, JSON.stringify(lockFile));
       const result = await manager.read();
       expect(warnSpy).toHaveBeenCalledWith(
-        expect.stringContaining(`Unsupported lock file version 999 (expected ${LOCK_FILE_VERSION})`),
+        expect.stringContaining(
+          `Unsupported lock file version 999 (expected ${LOCK_FILE_VERSION})`
+        )
       );
       expect(result.entries).toEqual({});
     });
@@ -159,15 +176,20 @@ describe('SyncLockManager', () => {
       const lockFile = { entries: {} };
       fs.writeFileSync(lockFilePath, JSON.stringify(lockFile));
       const result = await manager.read();
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Lock file corrupted (missing version)'));
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Lock file corrupted (missing version)')
+      );
       expect(result.entries).toEqual({});
     });
 
     describe('backup before reset', () => {
-      const backupPattern = /^\.deepl-sync\.lock\.bak-(?:corrupt|v\d+)-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(?:-\d{3})?Z$/;
+      const backupPattern =
+        /^\.deepl-sync\.lock\.bak-(?:corrupt|v\d+)-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(?:-\d{3})?Z$/;
 
       const listBackups = (): string[] =>
-        fs.readdirSync(tmpDir).filter((name) => name.startsWith('.deepl-sync.lock.bak-'));
+        fs
+          .readdirSync(tmpDir)
+          .filter((name) => name.startsWith('.deepl-sync.lock.bak-'));
 
       it('should back up corrupt JSON lockfile before resetting', async () => {
         jest.spyOn(Logger, 'warn').mockImplementation(() => {});
@@ -181,7 +203,9 @@ describe('SyncLockManager', () => {
         const backupName = backups[0]!;
         expect(backupName).toMatch(backupPattern);
         expect(backupName).toContain('.bak-corrupt-');
-        expect(fs.readFileSync(path.join(tmpDir, backupName), 'utf-8')).toBe(original);
+        expect(fs.readFileSync(path.join(tmpDir, backupName), 'utf-8')).toBe(
+          original
+        );
       });
 
       it('should back up wrong-version lockfile before resetting and tag version in filename', async () => {
@@ -196,7 +220,9 @@ describe('SyncLockManager', () => {
         const backupName = backups[0]!;
         expect(backupName).toMatch(backupPattern);
         expect(backupName).toContain('.bak-v0-');
-        expect(fs.readFileSync(path.join(tmpDir, backupName), 'utf-8')).toBe(original);
+        expect(fs.readFileSync(path.join(tmpDir, backupName), 'utf-8')).toBe(
+          original
+        );
       });
 
       it('should back up missing-version lockfile as v-unknown and preserve contents', async () => {
@@ -210,12 +236,17 @@ describe('SyncLockManager', () => {
         expect(backups).toHaveLength(1);
         const backupName = backups[0]!;
         expect(backupName).toContain('.bak-v-unknown-');
-        expect(fs.readFileSync(path.join(tmpDir, backupName), 'utf-8')).toBe(original);
+        expect(fs.readFileSync(path.join(tmpDir, backupName), 'utf-8')).toBe(
+          original
+        );
       });
 
       it('should log the backup path at WARN level', async () => {
         const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
-        fs.writeFileSync(lockFilePath, JSON.stringify({ version: 99, entries: {} }));
+        fs.writeFileSync(
+          lockFilePath,
+          JSON.stringify({ version: 99, entries: {} })
+        );
 
         await manager.read();
 
@@ -232,7 +263,11 @@ describe('SyncLockManager', () => {
           generated_at: '2026-01-01T00:00:00.000Z',
           source_locale: 'en',
           entries: {},
-          stats: { total_keys: 0, total_translations: 0, last_sync: '2026-01-01T00:00:00.000Z' },
+          stats: {
+            total_keys: 0,
+            total_translations: 0,
+            last_sync: '2026-01-01T00:00:00.000Z',
+          },
         };
         fs.writeFileSync(lockFilePath, JSON.stringify(lockFile, null, 2));
 
@@ -252,7 +287,9 @@ describe('SyncLockManager', () => {
       const lockFile = { version: LOCK_FILE_VERSION };
       fs.writeFileSync(lockFilePath, JSON.stringify(lockFile));
       const result = await manager.read();
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Lock file missing entries'));
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Lock file missing entries')
+      );
       expect(result.entries).toEqual({});
     });
 
@@ -268,7 +305,11 @@ describe('SyncLockManager', () => {
               source_hash: '185f8db32271',
               source_text: 'Hello',
               translations: {
-                es: { hash: 'abc', translated_at: '2026-01-01T00:00:00.000Z', status: 'translated' },
+                es: {
+                  hash: 'abc',
+                  translated_at: '2026-01-01T00:00:00.000Z',
+                  status: 'translated',
+                },
               },
             },
             farewell: {
@@ -278,7 +319,11 @@ describe('SyncLockManager', () => {
             },
           },
         },
-        stats: { total_keys: 2, total_translations: 1, last_sync: '2026-01-01T00:00:00.000Z' },
+        stats: {
+          total_keys: 2,
+          total_translations: 1,
+          last_sync: '2026-01-01T00:00:00.000Z',
+        },
       };
       fs.writeFileSync(lockFilePath, JSON.stringify(lockFile, null, 2));
       const result = await manager.read();
@@ -328,8 +373,16 @@ describe('SyncLockManager', () => {
           source_hash: 'aaa',
           source_text: 'Hello',
           translations: {
-            fr: { hash: 'h1', translated_at: '2026-01-01T00:00:00.000Z', status: 'translated' },
-            de: { hash: 'h2', translated_at: '2026-01-01T00:00:00.000Z', status: 'translated' },
+            fr: {
+              hash: 'h1',
+              translated_at: '2026-01-01T00:00:00.000Z',
+              status: 'translated',
+            },
+            de: {
+              hash: 'h2',
+              translated_at: '2026-01-01T00:00:00.000Z',
+              status: 'translated',
+            },
           },
         },
         alpha: {
@@ -402,7 +455,10 @@ describe('SyncLockManager', () => {
         translations: {},
       };
       await manager.updateEntry('file.json', 'greeting', entry);
-      await manager.updateEntry('file.json', 'farewell', { ...entry, source_hash: 'bbb' });
+      await manager.updateEntry('file.json', 'farewell', {
+        ...entry,
+        source_hash: 'bbb',
+      });
 
       await manager.removeEntry('file.json', 'greeting');
       const result = await manager.read();
@@ -424,7 +480,9 @@ describe('SyncLockManager', () => {
     });
 
     it('should handle removing non-existent entry gracefully', async () => {
-      await expect(manager.removeEntry('missing.json', 'no-key')).resolves.not.toThrow();
+      await expect(
+        manager.removeEntry('missing.json', 'no-key')
+      ).resolves.not.toThrow();
     });
   });
 
diff --git a/tests/unit/sync/sync-message-preprocess.test.ts b/tests/unit/sync/sync-message-preprocess.test.ts
index aedce20c..39751192 100644
--- a/tests/unit/sync/sync-message-preprocess.test.ts
+++ b/tests/unit/sync/sync-message-preprocess.test.ts
@@ -1,4 +1,8 @@
-import { expandPlurals, detectIcu, writebackPlurals } from '../../../src/sync/sync-message-preprocess';
+import {
+  expandPlurals,
+  detectIcu,
+  writebackPlurals,
+} from '../../../src/sync/sync-message-preprocess';
 import type { SyncDiff } from '../../../src/sync/types';
 import type { TranslationResult } from '../../../src/api/translation-client';
 
@@ -26,7 +30,7 @@ describe('expandPlurals', () => {
 
     const { extendedTexts, pluralSlots } = expandPlurals(
       ['{count, plural, other {# apples}}'],
-      [diff],
+      [diff]
     );
 
     expect(extendedTexts).toHaveLength(2);
@@ -98,14 +102,22 @@ describe('writebackPlurals', () => {
       { text: '1 Artikel', billedCharacters: 9 },
     ];
     const slots = [
-      { diffIndex: 0, format: 'android' as const, slotKey: 'one', textIndex: 1 },
+      {
+        diffIndex: 0,
+        format: 'android' as const,
+        slotKey: 'one',
+        textIndex: 1,
+      },
     ];
 
     writebackPlurals(results, slots, [diff]);
 
-    const plurals = diff.metadata!['plurals'] as Array<{ quantity: string; value: string }>;
-    expect(plurals.find(p => p.quantity === 'one')!.value).toBe('1 Artikel');
-    expect(plurals.find(p => p.quantity === 'other')!.value).toBe('%d items'); // untouched
+    const plurals = diff.metadata!['plurals'] as Array<{
+      quantity: string;
+      value: string;
+    }>;
+    expect(plurals.find((p) => p.quantity === 'one')!.value).toBe('1 Artikel');
+    expect(plurals.find((p) => p.quantity === 'other')!.value).toBe('%d items'); // untouched
   });
 
   it('writes msgstr[1] for PO msgid_plural slots and propagates to higher msgstr[N]', () => {
@@ -121,7 +133,12 @@ describe('writebackPlurals', () => {
       { text: 'Artikel (pl)', billedCharacters: 12 },
     ];
     const slots = [
-      { diffIndex: 0, format: 'po' as const, slotKey: 'msgid_plural', textIndex: 1 },
+      {
+        diffIndex: 0,
+        format: 'po' as const,
+        slotKey: 'msgid_plural',
+        textIndex: 1,
+      },
     ];
 
     writebackPlurals(results, slots, [diff]);
@@ -138,12 +155,20 @@ describe('writebackPlurals', () => {
     });
     const results: (TranslationResult | null)[] = [null, null];
     const slots = [
-      { diffIndex: 0, format: 'android' as const, slotKey: 'one', textIndex: 1 },
+      {
+        diffIndex: 0,
+        format: 'android' as const,
+        slotKey: 'one',
+        textIndex: 1,
+      },
     ];
 
     writebackPlurals(results, slots, [diff]);
 
-    const plurals = diff.metadata!['plurals'] as Array<{ quantity: string; value: string }>;
+    const plurals = diff.metadata!['plurals'] as Array<{
+      quantity: string;
+      value: string;
+    }>;
     expect(plurals[0]!.value).toBe('original');
   });
 });
diff --git a/tests/unit/sync/sync-process-bucket.test.ts b/tests/unit/sync/sync-process-bucket.test.ts
index 07e78844..51b09ee9 100644
--- a/tests/unit/sync/sync-process-bucket.test.ts
+++ b/tests/unit/sync/sync-process-bucket.test.ts
@@ -6,7 +6,10 @@ import type { ProcessBucketDeps } from '../../../src/sync/sync-process-bucket';
 import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
 import type { SyncLockFile } from '../../../src/sync/types';
 import type { WalkedBucketFile } from '../../../src/sync/sync-bucket-walker';
-import type { LocaleTranslator, TranslateLocaleResult } from '../../../src/sync/sync-locale-translator';
+import type {
+  LocaleTranslator,
+  TranslateLocaleResult,
+} from '../../../src/sync/sync-locale-translator';
 import { ValidationError } from '../../../src/utils/errors';
 
 jest.mock('../../../src/utils/logger', () => ({
@@ -31,13 +34,19 @@ function makeLockFile(): SyncLockFile {
   };
 }
 
-function makeConfig(projectRoot: string, targetPathPattern: string): ResolvedSyncConfig {
+function makeConfig(
+  projectRoot: string,
+  targetPathPattern: string
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
     target_locales: ['de'],
     buckets: {
-      json: { include: ['locales/en.json'], target_path_pattern: targetPathPattern },
+      json: {
+        include: ['locales/en.json'],
+        target_path_pattern: targetPathPattern,
+      },
     },
     projectRoot,
     configPath: path.join(projectRoot, '.deepl-sync.yaml'),
@@ -47,7 +56,14 @@ function makeConfig(projectRoot: string, targetPathPattern: string): ResolvedSyn
 
 function makeTranslateResult(): TranslateLocaleResult {
   return {
-    fileResult: { file: 'locales/de.json', locale: 'de', translated: 1, skipped: 0, failed: 0, written: true },
+    fileResult: {
+      file: 'locales/de.json',
+      locale: 'de',
+      translated: 1,
+      skipped: 0,
+      failed: 0,
+      written: true,
+    },
     successfulKeys: ['greeting'],
     charactersBilled: 5,
     billedPerKey: new Map(),
@@ -62,7 +78,7 @@ function makeTranslateResult(): TranslateLocaleResult {
 
 function makeDeps(
   config: ResolvedSyncConfig,
-  translate: jest.Mock,
+  translate: jest.Mock
 ): ProcessBucketDeps {
   return {
     config,
@@ -118,25 +134,32 @@ describe('processBucket', () => {
       const translate = jest.fn().mockResolvedValue(makeTranslateResult());
 
       await expect(
-        processBucket(makeWalked(config), makeDeps(config, translate)),
+        processBucket(makeWalked(config), makeDeps(config, translate))
       ).rejects.toThrow(/escapes project root/);
       expect(translate).not.toHaveBeenCalled();
     });
 
     it('should not read target files outside the project root during the pre-read', async () => {
-      const outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-outside-'));
+      const outsideDir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-outside-')
+      );
       try {
         const secret = path.join(outsideDir, 'de.json');
         fs.writeFileSync(secret, '{"secret":"value"}', 'utf-8');
         const relOutside = path.relative(tmpDir, outsideDir);
-        const config = makeConfig(tmpDir, path.posix.join(...relOutside.split(path.sep), '{locale}.json'));
+        const config = makeConfig(
+          tmpDir,
+          path.posix.join(...relOutside.split(path.sep), '{locale}.json')
+        );
         const translate = jest.fn().mockResolvedValue(makeTranslateResult());
         const readSpy = jest.spyOn(fs.promises, 'readFile');
 
         await expect(
-          processBucket(makeWalked(config), makeDeps(config, translate)),
+          processBucket(makeWalked(config), makeDeps(config, translate))
         ).rejects.toThrow(ValidationError);
-        expect(readSpy.mock.calls.map((c) => String(c[0]))).not.toContain(secret);
+        expect(readSpy.mock.calls.map((c) => String(c[0]))).not.toContain(
+          secret
+        );
         readSpy.mockRestore();
       } finally {
         fs.rmSync(outsideDir, { recursive: true, force: true });
@@ -145,20 +168,27 @@ describe('processBucket', () => {
 
     it('should rethrow a containment ValidationError raised inside the locale translator', async () => {
       const config = makeConfig(tmpDir, 'locales/{locale}.json');
-      const translate = jest.fn().mockRejectedValue(
-        new ValidationError('Target path escapes project root: /evil/de.json'),
-      );
+      const translate = jest
+        .fn()
+        .mockRejectedValue(
+          new ValidationError('Target path escapes project root: /evil/de.json')
+        );
 
       await expect(
-        processBucket(makeWalked(config), makeDeps(config, translate)),
+        processBucket(makeWalked(config), makeDeps(config, translate))
       ).rejects.toThrow(/escapes project root/);
     });
 
     it('should still absorb generic per-locale translation failures', async () => {
       const config = makeConfig(tmpDir, 'locales/{locale}.json');
-      const translate = jest.fn().mockRejectedValue(new Error('network hiccup'));
+      const translate = jest
+        .fn()
+        .mockRejectedValue(new Error('network hiccup'));
 
-      const result = await processBucket(makeWalked(config), makeDeps(config, translate));
+      const result = await processBucket(
+        makeWalked(config),
+        makeDeps(config, translate)
+      );
 
       expect(result.fileResults).toHaveLength(1);
       expect(result.fileResults[0]!.written).toBe(false);
@@ -171,7 +201,10 @@ describe('processBucket', () => {
       const config = makeConfig(tmpDir, 'locales/{locale}.json');
       const translate = jest.fn().mockResolvedValue(makeTranslateResult());
 
-      const result = await processBucket(makeWalked(config), makeDeps(config, translate));
+      const result = await processBucket(
+        makeWalked(config),
+        makeDeps(config, translate)
+      );
 
       expect(translate).toHaveBeenCalledTimes(1);
       expect(result.fileResults).toHaveLength(1);
diff --git a/tests/unit/sync/sync-push-pull.test.ts b/tests/unit/sync/sync-push-pull.test.ts
index 5b8f0ed8..2874baad 100644
--- a/tests/unit/sync/sync-push-pull.test.ts
+++ b/tests/unit/sync/sync-push-pull.test.ts
@@ -33,8 +33,12 @@ jest.mock('../../../src/sync/sync-lock', () => {
     ...actual,
     SyncLockManager: jest.fn().mockImplementation(() => ({
       read: jest.fn().mockResolvedValue({
-        _comment: '', version: 1, generated_at: '', source_locale: 'en',
-        entries: {}, stats: { total_keys: 0, total_translations: 0, last_sync: '' },
+        _comment: '',
+        version: 1,
+        generated_at: '',
+        source_locale: 'en',
+        entries: {},
+        stats: { total_keys: 0, total_translations: 0, last_sync: '' },
       }),
       write: jest.fn().mockResolvedValue(undefined),
     })),
@@ -73,7 +77,7 @@ describe('sync push/pull (TMS integration)', () => {
         expect.objectContaining({
           method: 'PUT',
           body: JSON.stringify({ locale: 'de', value: 'Hallo' }),
-        }),
+        })
       );
     });
 
@@ -83,7 +87,7 @@ describe('sync push/pull (TMS integration)', () => {
       await client.pushKey('nav/home', 'de', 'Startseite');
       expect(mockFetch).toHaveBeenCalledWith(
         expect.stringContaining('nav%2Fhome'),
-        expect.anything(),
+        expect.anything()
       );
     });
   });
@@ -105,7 +109,7 @@ describe('sync push/pull (TMS integration)', () => {
       await client.pullKeys('fr');
       expect(mockFetch).toHaveBeenCalledWith(
         expect.stringContaining('locale=fr'),
-        expect.anything(),
+        expect.anything()
       );
     });
   });
@@ -119,7 +123,10 @@ describe('sync push/pull (TMS integration)', () => {
         apiKey: 'my-key',
       });
       await client.pushKey('k', 'de', 'v');
-      const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<string, string>;
+      const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<
+        string,
+        string
+      >;
       expect(headers?.['Authorization']).toBe('ApiKey my-key');
     });
 
@@ -131,19 +138,28 @@ describe('sync push/pull (TMS integration)', () => {
         token: 'my-token',
       });
       await client.pushKey('k', 'de', 'v');
-      const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<string, string>;
+      const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<
+        string,
+        string
+      >;
       expect(headers?.['Authorization']).toBe('Bearer my-token');
     });
 
     it('should throw on API error responses', async () => {
-      mockFetch.mockResolvedValue({ ok: false, status: 401, statusText: 'Unauthorized' });
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 401,
+        statusText: 'Unauthorized',
+      });
       const client = makeClient();
       await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow('401');
     });
   });
 });
 
-function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+function makeConfig(
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -169,7 +185,9 @@ describe('pushTranslations()', () => {
     // Jest resetMocks:true wipes the module-level fs.promises.readFile default,
     // so re-establish it. walkBuckets reads the source file up front; push then
     // decides whether to use that content (isMultiLocale) or re-read a target.
-    (fs.promises.readFile as jest.Mock).mockResolvedValue('{"greeting":"Hello"}');
+    (fs.promises.readFile as jest.Mock).mockResolvedValue(
+      '{"greeting":"Hello"}'
+    );
   });
 
   it('should push entries from target files to TmsClient', async () => {
@@ -186,7 +204,9 @@ describe('pushTranslations()', () => {
     expect(mockFetch).toHaveBeenCalledTimes(1);
 
     const [url, init] = mockFetch.mock.calls[0] as [string, RequestInit];
-    expect(url).toBe('https://tms.example.com/api/projects/proj-123/keys/greeting');
+    expect(url).toBe(
+      'https://tms.example.com/api/projects/proj-123/keys/greeting'
+    );
     expect(url).toContain('/keys/greeting');
     expect(init.method).toBe('PUT');
     expect(init.body).toBe(JSON.stringify({ locale: 'de', value: 'Hallo' }));
@@ -199,7 +219,9 @@ describe('pushTranslations()', () => {
 
     const client = makeClient();
     const config = makeConfig({ target_locales: ['de', 'fr'] });
-    const result = await pushTranslations(config, client, makeRegistry(), { localeFilter: ['fr'] });
+    const result = await pushTranslations(config, client, makeRegistry(), {
+      localeFilter: ['fr'],
+    });
 
     // One source file (en.json) x one key (greeting) x one included locale (fr)
     // = 1 push. The excluded locale (de) must contribute 0 pushes.
@@ -210,15 +232,23 @@ describe('pushTranslations()', () => {
       const init = call[1] as { body?: string } | undefined;
       return init?.body ?? '';
     });
-    expect(fetchBodies).toEqual([JSON.stringify({ locale: 'fr', value: 'Hallo' })]);
-    expect(fetchBodies.some((body) => body.includes('"locale":"fr"'))).toBe(true);
-    expect(fetchBodies.some((body) => body.includes('"locale":"de"'))).toBe(false);
+    expect(fetchBodies).toEqual([
+      JSON.stringify({ locale: 'fr', value: 'Hallo' }),
+    ]);
+    expect(fetchBodies.some((body) => body.includes('"locale":"fr"'))).toBe(
+      true
+    );
+    expect(fetchBodies.some((body) => body.includes('"locale":"de"'))).toBe(
+      false
+    );
   });
 
   it('should skip when target file does not exist', async () => {
     mockFg.mockResolvedValue(['/test/locales/en.json']);
     (fs.readFileSync as jest.Mock).mockImplementation(() => {
-      const err = new Error('ENOENT: no such file or directory') as NodeJS.ErrnoException;
+      const err = new Error(
+        'ENOENT: no such file or directory'
+      ) as NodeJS.ErrnoException;
       err.code = 'ENOENT';
       throw err;
     });
@@ -235,10 +265,16 @@ describe('pushTranslations()', () => {
   it('should propagate non-ENOENT errors (e.g. auth failures) instead of swallowing them', async () => {
     mockFg.mockResolvedValue(['/test/locales/en.json']);
     (fs.readFileSync as jest.Mock).mockReturnValue('{"greeting":"Hallo"}');
-    mockFetch.mockResolvedValue({ ok: false, status: 401, statusText: 'Unauthorized' });
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 401,
+      statusText: 'Unauthorized',
+    });
 
     const client = makeClient();
-    await expect(pushTranslations(makeConfig(), client, makeRegistry())).rejects.toThrow(/401/);
+    await expect(
+      pushTranslations(makeConfig(), client, makeRegistry())
+    ).rejects.toThrow(/401/);
   });
 
   describe('bounded concurrency', () => {
@@ -265,7 +301,11 @@ describe('pushTranslations()', () => {
       });
 
       const client = makeClient();
-      const result = await pushTranslations(makeConfig(), client, makeRegistry());
+      const result = await pushTranslations(
+        makeConfig(),
+        client,
+        makeRegistry()
+      );
 
       expect(result.pushed).toBe(30);
       expect(mockFetch).toHaveBeenCalledTimes(30);
@@ -313,13 +353,20 @@ describe('pushTranslations()', () => {
         const thisCall = callCount;
         await new Promise((resolve) => setTimeout(resolve, 5));
         if (thisCall === 2) {
-          return { ok: false, status: 500, statusText: 'Internal Server Error', text: async () => '' };
+          return {
+            ok: false,
+            status: 500,
+            statusText: 'Internal Server Error',
+            text: async () => '',
+          };
         }
         return { ok: true, json: async () => ({}) };
       });
 
       const client = makeClient();
-      await expect(pushTranslations(makeConfig(), client, makeRegistry())).rejects.toThrow(/500/);
+      await expect(
+        pushTranslations(makeConfig(), client, makeRegistry())
+      ).rejects.toThrow(/500/);
       expect(callCount).toBeLessThan(30);
     });
 
@@ -339,7 +386,11 @@ describe('pushTranslations()', () => {
 
       const client = makeClient();
       // No tms block at all on the resolved config -> default concurrency path.
-      const result = await pushTranslations(makeConfig(), client, makeRegistry());
+      const result = await pushTranslations(
+        makeConfig(),
+        client,
+        makeRegistry()
+      );
 
       expect(result.pushed).toBe(30);
       expect(peak).toBeLessThanOrEqual(10);
@@ -349,15 +400,21 @@ describe('pushTranslations()', () => {
 });
 
 describe('pullTranslations()', () => {
-  const { SyncLockManager: MockLockManager } = jest.requireMock('../../../src/sync/sync-lock');
+  const { SyncLockManager: MockLockManager } = jest.requireMock(
+    '../../../src/sync/sync-lock'
+  );
 
   beforeEach(() => {
     mockFetch.mockReset();
     mockFg.mockReset();
     MockLockManager.mockImplementation(() => ({
       read: jest.fn().mockResolvedValue({
-        _comment: '', version: 1, generated_at: '', source_locale: 'en',
-        entries: {}, stats: { total_keys: 0, total_translations: 0, last_sync: '' },
+        _comment: '',
+        version: 1,
+        generated_at: '',
+        source_locale: 'en',
+        entries: {},
+        stats: { total_keys: 0, total_translations: 0, last_sync: '' },
       }),
       write: jest.fn().mockResolvedValue(undefined),
     }));
@@ -365,7 +422,9 @@ describe('pullTranslations()', () => {
 
   it('should pull keys and write target files', async () => {
     mockFg.mockResolvedValue(['/test/locales/en.json']);
-    (fs.promises.readFile as jest.Mock).mockResolvedValue('{"greeting":"Hello"}');
+    (fs.promises.readFile as jest.Mock).mockResolvedValue(
+      '{"greeting":"Hello"}'
+    );
     mockFetch.mockResolvedValue({
       ok: true,
       json: async () => ({ greeting: 'Hallo' }),
@@ -380,7 +439,9 @@ describe('pullTranslations()', () => {
 
   it('should return 0 when no keys are pulled', async () => {
     mockFg.mockResolvedValue(['/test/locales/en.json']);
-    (fs.promises.readFile as jest.Mock).mockResolvedValue('{"greeting":"Hello"}');
+    (fs.promises.readFile as jest.Mock).mockResolvedValue(
+      '{"greeting":"Hello"}'
+    );
     mockFetch.mockResolvedValue({
       ok: true,
       json: async () => ({}),
@@ -405,15 +466,19 @@ describe('pullTranslations()', () => {
       '/test/locales/en/marketing.json',
     ];
     mockFg.mockResolvedValue(sourceFiles);
-    (fs.promises.readFile as jest.Mock).mockResolvedValue('{"greeting":"Hello"}');
+    (fs.promises.readFile as jest.Mock).mockResolvedValue(
+      '{"greeting":"Hello"}'
+    );
 
     const pullKeysSpy = jest
       .spyOn(TmsClient.prototype, 'pullKeys')
-      .mockImplementation(async (locale: string): Promise<Record<string, string>> => {
-        if (locale === 'de') return { greeting: 'Hallo' };
-        if (locale === 'fr') return { greeting: 'Bonjour' };
-        return {};
-      });
+      .mockImplementation(
+        async (locale: string): Promise<Record<string, string>> => {
+          if (locale === 'de') return { greeting: 'Hallo' };
+          if (locale === 'fr') return { greeting: 'Bonjour' };
+          return {};
+        }
+      );
 
     try {
       const client = makeClient();
diff --git a/tests/unit/sync/sync-resolve.test.ts b/tests/unit/sync/sync-resolve.test.ts
index 9a384dd7..c438966d 100644
--- a/tests/unit/sync/sync-resolve.test.ts
+++ b/tests/unit/sync/sync-resolve.test.ts
@@ -1,5 +1,9 @@
 import * as fs from 'fs';
-import { hasConflictMarkers, resolveConflicts, resolveLockFile } from '../../../src/sync/sync-resolve';
+import {
+  hasConflictMarkers,
+  resolveConflicts,
+  resolveLockFile,
+} from '../../../src/sync/sync-resolve';
 import type { ResolveDecision } from '../../../src/sync/sync-resolve';
 
 jest.mock('fs', () => {
@@ -14,8 +18,12 @@ jest.mock('fs', () => {
   };
 });
 
-const mockReadFile = fs.promises.readFile as jest.MockedFunction<typeof fs.promises.readFile>;
-const mockWriteFile = fs.promises.writeFile as jest.MockedFunction<typeof fs.promises.writeFile>;
+const mockReadFile = fs.promises.readFile as jest.MockedFunction<
+  typeof fs.promises.readFile
+>;
+const mockWriteFile = fs.promises.writeFile as jest.MockedFunction<
+  typeof fs.promises.writeFile
+>;
 
 beforeEach(() => {
   jest.clearAllMocks();
@@ -23,7 +31,8 @@ beforeEach(() => {
 
 describe('hasConflictMarkers()', () => {
   it('should return true when content starts with <<<<<<< marker', () => {
-    const content = '<<<<<<< HEAD\nsome content\n=======\nother content\n>>>>>>> branch';
+    const content =
+      '<<<<<<< HEAD\nsome content\n=======\nother content\n>>>>>>> branch';
     expect(hasConflictMarkers(content)).toBe(true);
   });
 
@@ -250,7 +259,11 @@ describe('resolveLockFile()', () => {
     expect(result.entriesMerged).toBe(1);
 
     expect(mockReadFile).toHaveBeenCalledWith(lockPath, 'utf-8');
-    expect(mockWriteFile).toHaveBeenCalledWith(lockPath, expect.any(String), 'utf-8');
+    expect(mockWriteFile).toHaveBeenCalledWith(
+      lockPath,
+      expect.any(String),
+      'utf-8'
+    );
 
     const writtenContent = mockWriteFile.mock.calls[0]![1] as string;
     const parsed = JSON.parse(writtenContent);
@@ -346,7 +359,9 @@ describe('per-entry decision report', () => {
     const { decisions } = resolveConflicts(content);
     expect(Array.isArray(decisions)).toBe(true);
 
-    const byKey = new Map<string, ResolveDecision>(decisions.map((d) => [d.key, d]));
+    const byKey = new Map<string, ResolveDecision>(
+      decisions.map((d) => [d.key, d])
+    );
 
     const ours = byKey.get('kept_ours');
     expect(ours).toBeDefined();
@@ -362,7 +377,9 @@ describe('per-entry decision report', () => {
   it('tags a decision as length-heuristic when JSON.parse fails without logging itself', () => {
     // The command layer prints the warning once from the decision; the
     // library must stay silent so it is not printed twice.
-    const warnSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    const warnSpy = jest
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
     try {
       const content = [
         'prefix line',
@@ -374,7 +391,9 @@ describe('per-entry decision report', () => {
         'suffix line',
       ].join('\n');
 
-      const { decisions } = resolveConflicts(content, { file: 'locales/de/app.json' });
+      const { decisions } = resolveConflicts(content, {
+        file: 'locales/de/app.json',
+      });
 
       const fallback = decisions.find((d) => d.source === 'length-heuristic');
       expect(fallback).toBeDefined();
@@ -383,7 +402,9 @@ describe('per-entry decision report', () => {
       expect(fallback!.reason.length).toBeGreaterThan(0);
 
       const warned = warnSpy.mock.calls.some((args) => {
-        const joined = args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ');
+        const joined = args
+          .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
+          .join(' ');
         return /parse-error fallback/i.test(joined);
       });
       expect(warned).toBe(false);
@@ -426,7 +447,9 @@ describe('per-entry decision report', () => {
     mockReadFile.mockResolvedValue(content);
     mockWriteFile.mockResolvedValue(undefined);
 
-    const result = await resolveLockFile('/tmp/test-sync/.deepl-sync.lock', { dryRun: true });
+    const result = await resolveLockFile('/tmp/test-sync/.deepl-sync.lock', {
+      dryRun: true,
+    });
     expect(result.hadConflicts).toBe(true);
     expect(result.resolved).toBe(true);
     expect(mockWriteFile).not.toHaveBeenCalled();
@@ -440,10 +463,12 @@ describe('prototype pollution hardening', () => {
     // Canary: trip loud on any future cross-talk that leaks through the merge helpers.
     /* eslint-disable jest/no-standalone-expect */
     expect(({} as Record<string, unknown>)['polluted']).toBeUndefined();
-    expect(((Object.prototype as unknown) as Record<string, unknown>)['polluted']).toBeUndefined();
+    expect(
+      (Object.prototype as unknown as Record<string, unknown>)['polluted']
+    ).toBeUndefined();
     /* eslint-enable jest/no-standalone-expect */
     // Remove the key so a leak in one test cannot poison later ones.
-    delete ((Object.prototype as unknown) as Record<string, unknown>)['polluted'];
+    delete (Object.prototype as unknown as Record<string, unknown>)['polluted'];
   });
 
   it('should not pollute Object.prototype via __proto__ key in conflict fragment', () => {
@@ -460,7 +485,9 @@ describe('prototype pollution hardening', () => {
     resolveConflicts(content);
 
     expect(({} as Record<string, unknown>)['polluted']).toBeUndefined();
-    expect(((Object.prototype as unknown) as Record<string, unknown>)['polluted']).toBeUndefined();
+    expect(
+      (Object.prototype as unknown as Record<string, unknown>)['polluted']
+    ).toBeUndefined();
   });
 
   it('should not pollute Object.prototype via constructor.prototype in conflict fragment', () => {
@@ -477,7 +504,9 @@ describe('prototype pollution hardening', () => {
     resolveConflicts(content);
 
     expect(({} as Record<string, unknown>)['polluted']).toBeUndefined();
-    expect(((Object.prototype as unknown) as Record<string, unknown>)['polluted']).toBeUndefined();
+    expect(
+      (Object.prototype as unknown as Record<string, unknown>)['polluted']
+    ).toBeUndefined();
   });
 
   it('should not pollute Object.prototype when __proto__ appears on the ours side', () => {
@@ -494,7 +523,9 @@ describe('prototype pollution hardening', () => {
     resolveConflicts(content);
 
     expect(({} as Record<string, unknown>)['polluted']).toBeUndefined();
-    expect(((Object.prototype as unknown) as Record<string, unknown>)['polluted']).toBeUndefined();
+    expect(
+      (Object.prototype as unknown as Record<string, unknown>)['polluted']
+    ).toBeUndefined();
   });
 
   it('should not pollute Object.prototype via prototype key in conflict fragment', () => {
@@ -510,7 +541,9 @@ describe('prototype pollution hardening', () => {
 
     resolveConflicts(content);
 
-    expect(((Object.prototype as unknown) as Record<string, unknown>)['polluted']).toBeUndefined();
+    expect(
+      (Object.prototype as unknown as Record<string, unknown>)['polluted']
+    ).toBeUndefined();
   });
 
   it('should drop __proto__/constructor/prototype keys entirely from merged output', () => {
@@ -530,9 +563,15 @@ describe('prototype pollution hardening', () => {
     const { resolved } = resolveConflicts(content);
     const parsed = JSON.parse(resolved);
 
-    expect(Object.prototype.hasOwnProperty.call(parsed, '__proto__')).toBe(false);
-    expect(Object.prototype.hasOwnProperty.call(parsed, 'constructor')).toBe(false);
-    expect(Object.prototype.hasOwnProperty.call(parsed, 'prototype')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(parsed, '__proto__')).toBe(
+      false
+    );
+    expect(Object.prototype.hasOwnProperty.call(parsed, 'constructor')).toBe(
+      false
+    );
+    expect(Object.prototype.hasOwnProperty.call(parsed, 'prototype')).toBe(
+      false
+    );
     expect(parsed.legit).toBeDefined();
     expect(parsed.safe).toBeDefined();
   });
diff --git a/tests/unit/sync/sync-service.test.ts b/tests/unit/sync/sync-service.test.ts
index 309b17b2..24beac34 100644
--- a/tests/unit/sync/sync-service.test.ts
+++ b/tests/unit/sync/sync-service.test.ts
@@ -2,18 +2,24 @@ import { SyncService, resolveTargetPath } from '../../../src/sync/sync-service';
 import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
 import type { SyncLockFile, SyncLockEntry } from '../../../src/sync/types';
 import { computeSourceHash } from '../../../src/sync/sync-lock';
-import { createMockTranslationService, createMockGlossaryService } from '../../helpers/mock-factories';
+import {
+  createMockTranslationService,
+  createMockGlossaryService,
+} from '../../helpers/mock-factories';
 import { FormatRegistry } from '../../../src/formats/index';
-import type { FormatParser, ExtractedEntry, TranslatedEntry } from '../../../src/formats/format';
+import type {
+  FormatParser,
+  ExtractedEntry,
+  TranslatedEntry,
+} from '../../../src/formats/format';
 import { JsonFormatParser } from '../../../src/formats/json';
 import { YamlFormatParser } from '../../../src/formats/yaml';
 import { ValidationError, ConfigError } from '../../../src/utils/errors';
 
 jest.mock('fast-glob', () => {
-  const mockFn = Object.assign(
-    jest.fn().mockResolvedValue([]),
-    { escapePath: (s: string) => s.replace(/[\\^$.|?*+()[\]{}]/g, '\\$&') },
-  );
+  const mockFn = Object.assign(jest.fn().mockResolvedValue([]), {
+    escapePath: (s: string) => s.replace(/[\\^$.|?*+()[\]{}]/g, '\\$&'),
+  });
   return { __esModule: true, default: mockFn };
 });
 
@@ -42,13 +48,18 @@ jest.mock('../../../src/utils/atomic-write', () => ({
 }));
 
 jest.mock('../../../src/sync/sync-context', () => ({
-  extractAllKeyContexts: jest.fn().mockResolvedValue({ keyContexts: new Map(), templatePatterns: [] }),
+  extractAllKeyContexts: jest
+    .fn()
+    .mockResolvedValue({ keyContexts: new Map(), templatePatterns: [] }),
   resolveTemplatePatterns: jest.fn().mockReturnValue(new Map()),
   synthesizeContext: jest.fn().mockReturnValue(''),
   sectionContextKey: jest.fn().mockImplementation((key: string) => {
     const segments = key.split('.');
     if (segments.length < 2) return '';
-    return segments.slice(0, -1).filter((s: string) => !/^\d+$/.test(s)).join('.');
+    return segments
+      .slice(0, -1)
+      .filter((s: string) => !/^\d+$/.test(s))
+      .join('.');
   }),
   sectionToContext: jest.fn().mockImplementation((section: string) => {
     if (!section) return '';
@@ -92,16 +103,32 @@ import { SyncLockManager } from '../../../src/sync/sync-lock';
 import { extractAllKeyContexts } from '../../../src/sync/sync-context';
 import { Logger } from '../../../src/utils/logger';
 
-const mockExtractAllKeyContexts = extractAllKeyContexts as jest.MockedFunction<typeof extractAllKeyContexts>;
+const mockExtractAllKeyContexts = extractAllKeyContexts as jest.MockedFunction<
+  typeof extractAllKeyContexts
+>;
 const mockFg = fg as jest.MockedFunction<typeof fg>;
-const mockReadFile = fs.promises.readFile as jest.MockedFunction<typeof fs.promises.readFile>;
-const mockMkdir = fs.promises.mkdir as jest.MockedFunction<typeof fs.promises.mkdir>;
-const mockAtomicWriteFile = atomicWriteFile as jest.MockedFunction<typeof atomicWriteFile>;
-const mockCopyFile = fs.promises.copyFile as jest.MockedFunction<typeof fs.promises.copyFile>;
-const mockUnlink = fs.promises.unlink as jest.MockedFunction<typeof fs.promises.unlink>;
-const MockSyncLockManager = SyncLockManager as jest.MockedClass<typeof SyncLockManager>;
-
-function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+const mockReadFile = fs.promises.readFile as jest.MockedFunction<
+  typeof fs.promises.readFile
+>;
+const mockMkdir = fs.promises.mkdir as jest.MockedFunction<
+  typeof fs.promises.mkdir
+>;
+const mockAtomicWriteFile = atomicWriteFile as jest.MockedFunction<
+  typeof atomicWriteFile
+>;
+const mockCopyFile = fs.promises.copyFile as jest.MockedFunction<
+  typeof fs.promises.copyFile
+>;
+const mockUnlink = fs.promises.unlink as jest.MockedFunction<
+  typeof fs.promises.unlink
+>;
+const MockSyncLockManager = SyncLockManager as jest.MockedClass<
+  typeof SyncLockManager
+>;
+
+function makeConfig(
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -127,7 +154,7 @@ function makeEmptyLockFile(sourceLocale = ''): SyncLockFile {
 
 function makeLockFileWithEntries(
   entries: Record<string, Record<string, SyncLockEntry>>,
-  sourceLocale = 'en',
+  sourceLocale = 'en'
 ): SyncLockFile {
   return {
     ...makeEmptyLockFile(sourceLocale),
@@ -142,7 +169,10 @@ function makeLockFileWithEntries(
  * `translations[locale].hash`. Pass an explicit hash only to model a locale
  * that has genuinely fallen behind the source.
  */
-function makeLockEntry(value: string, translations: Record<string, { hash?: string; status: string }> = {}): SyncLockEntry {
+function makeLockEntry(
+  value: string,
+  translations: Record<string, { hash?: string; status: string }> = {}
+): SyncLockEntry {
   const translationEntries: SyncLockEntry['translations'] = {};
   for (const [locale, info] of Object.entries(translations)) {
     translationEntries[locale] = {
@@ -165,9 +195,11 @@ function createRegistry(): FormatRegistry {
   return registry;
 }
 
-function createService(overrides: {
-  translateBatch?: jest.Mock;
-} = {}) {
+function createService(
+  overrides: {
+    translateBatch?: jest.Mock;
+  } = {}
+) {
   const mockTranslation = createMockTranslationService({
     translateBatch: overrides.translateBatch ?? jest.fn().mockResolvedValue([]),
   });
@@ -189,15 +221,22 @@ const mockMultiLocaleParser: FormatParser = {
     if (!locale) return [];
     const entries: ExtractedEntry[] = [];
     for (const [key, val] of Object.entries(data.strings ?? {})) {
-      const loc = (val as Record<string, unknown>)['localizations'] as Record<string, unknown> | undefined;
-      const unit = (loc?.[locale] as Record<string, unknown>)?.['stringUnit'] as Record<string, string> | undefined;
+      const loc = (val as Record<string, unknown>)['localizations'] as
+        Record<string, unknown> | undefined;
+      const unit = (loc?.[locale] as Record<string, unknown>)?.[
+        'stringUnit'
+      ] as Record<string, string> | undefined;
       if (unit?.['value']) {
         entries.push({ key, value: unit['value'] });
       }
     }
     return entries.sort((a, b) => a.key.localeCompare(b.key));
   },
-  reconstruct(content: string, entries: TranslatedEntry[], locale?: string): string {
+  reconstruct(
+    content: string,
+    entries: TranslatedEntry[],
+    locale?: string
+  ): string {
     const data = JSON.parse(content);
     data.strings ??= {};
     for (const entry of entries) {
@@ -216,7 +255,9 @@ function createMultiLocaleRegistry(): FormatRegistry {
   return registry;
 }
 
-function createMultiLocaleService(overrides: { translateBatch?: jest.Mock } = {}) {
+function createMultiLocaleService(
+  overrides: { translateBatch?: jest.Mock } = {}
+) {
   const mockTranslation = createMockTranslationService({
     translateBatch: overrides.translateBatch ?? jest.fn().mockResolvedValue([]),
   });
@@ -229,17 +270,21 @@ function createMultiLocaleService(overrides: { translateBatch?: jest.Mock } = {}
 function setupLockManager(lockFile: SyncLockFile) {
   const mockRead = jest.fn().mockResolvedValue(lockFile);
   const mockWrite = jest.fn().mockResolvedValue(undefined);
-  MockSyncLockManager.mockImplementation(() => ({
-    read: mockRead,
-    write: mockWrite,
-    updateEntry: jest.fn(),
-    removeEntry: jest.fn(),
-    exists: jest.fn(),
-  }) as unknown as SyncLockManager);
+  MockSyncLockManager.mockImplementation(
+    () =>
+      ({
+        read: mockRead,
+        write: mockWrite,
+        updateEntry: jest.fn(),
+        removeEntry: jest.fn(),
+        exists: jest.fn(),
+      }) as unknown as SyncLockManager
+  );
   return { mockRead, mockWrite };
 }
 
-const SOURCE_JSON = JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n';
+const SOURCE_JSON =
+  JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n';
 
 describe('SyncService', () => {
   describe('sync() — happy path', () => {
@@ -267,7 +312,7 @@ describe('SyncService', () => {
       expect(translateBatch).toHaveBeenCalledTimes(1);
       expect(translateBatch).toHaveBeenCalledWith(
         ['Goodbye', 'Hello'],
-        expect.objectContaining({ targetLang: 'de' }),
+        expect.objectContaining({ targetLang: 'de' })
       );
       expect(mockAtomicWriteFile).toHaveBeenCalledTimes(1);
       expect(mockWrite).toHaveBeenCalledTimes(1);
@@ -347,7 +392,10 @@ describe('SyncService', () => {
 
       // 12 chars × 1 filtered locale = 12
       const config = makeConfig({ target_locales: ['de', 'fr'] });
-      const result = await service.sync(config, { dryRun: true, localeFilter: ['de'] });
+      const result = await service.sync(config, {
+        dryRun: true,
+        localeFilter: ['de'],
+      });
       expect(result.estimatedCharacters).toBe(12);
     });
   });
@@ -378,9 +426,11 @@ describe('SyncService', () => {
 
       expect(mockCopyFile).toHaveBeenCalledWith(
         '/test/locales/de.json',
-        '/test/locales/de.json.deepl.bak',
+        '/test/locales/de.json.deepl.bak'
+      );
+      expect(mockUnlink).toHaveBeenCalledWith(
+        '/test/locales/de.json.deepl.bak'
       );
-      expect(mockUnlink).toHaveBeenCalledWith('/test/locales/de.json.deepl.bak');
     });
 
     it('should NOT create .bak in dry-run mode', async () => {
@@ -442,29 +492,38 @@ describe('SyncService', () => {
       const result = await service.sync(makeConfig());
       expect(result.success).toBe(true);
       // Backup was created, then unlinked (normal post-success path).
-      expect(mockUnlink).toHaveBeenCalledWith('/test/locales/de.json.deepl.bak');
+      expect(mockUnlink).toHaveBeenCalledWith(
+        '/test/locales/de.json.deepl.bak'
+      );
     });
   });
 
   describe('sync() — multi-locale format', () => {
-    const XCSTRINGS_SOURCE = JSON.stringify({
-      sourceLanguage: 'en',
-      version: '1.0',
-      strings: {
-        greeting: {
-          localizations: {
-            en: { stringUnit: { state: 'translated', value: 'Hello' } },
-          },
-        },
-        farewell: {
-          localizations: {
-            en: { stringUnit: { state: 'translated', value: 'Goodbye' } },
+    const XCSTRINGS_SOURCE =
+      JSON.stringify(
+        {
+          sourceLanguage: 'en',
+          version: '1.0',
+          strings: {
+            greeting: {
+              localizations: {
+                en: { stringUnit: { state: 'translated', value: 'Hello' } },
+              },
+            },
+            farewell: {
+              localizations: {
+                en: { stringUnit: { state: 'translated', value: 'Goodbye' } },
+              },
+            },
           },
         },
-      },
-    }, null, 2) + '\n';
+        null,
+        2
+      ) + '\n';
 
-    function makeMultiLocaleConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+    function makeMultiLocaleConfig(
+      overrides: Partial<ResolvedSyncConfig> = {}
+    ): ResolvedSyncConfig {
       return {
         version: 1,
         source_locale: 'en',
@@ -479,7 +538,8 @@ describe('SyncService', () => {
 
     it('should use source path as target for all locales', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn()
+      const translateBatch = jest
+        .fn()
         .mockResolvedValueOnce([
           { text: 'Auf Wiedersehen', billedCharacters: 15 },
           { text: 'Hallo', billedCharacters: 5 },
@@ -506,7 +566,10 @@ describe('SyncService', () => {
         expect(fr.file).toBe('Localizable.xcstrings');
       }
       expect(result.fileResults).toHaveLength(2);
-      expect(result.fileResults.map(f => f.locale).sort()).toEqual(['de', 'fr']);
+      expect(result.fileResults.map((f) => f.locale).sort()).toEqual([
+        'de',
+        'fr',
+      ]);
     });
 
     it('should pass locale to parser.extract() for source entries', async () => {
@@ -535,14 +598,15 @@ describe('SyncService', () => {
 
       mockFg.mockResolvedValue(['/test/Localizable.xcstrings'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
-        if (String(p) === '/test/Localizable.xcstrings') return XCSTRINGS_SOURCE;
+        if (String(p) === '/test/Localizable.xcstrings')
+          return XCSTRINGS_SOURCE;
         throw new Error('ENOENT');
       });
 
       await service.sync(makeMultiLocaleConfig());
 
       // reconstruct should be called with locale for each target
-      const localeArgs = reconstructSpy.mock.calls.map(c => c[2]);
+      const localeArgs = reconstructSpy.mock.calls.map((c) => c[2]);
       expect(localeArgs).toContain('de');
       expect(localeArgs).toContain('fr');
       reconstructSpy.mockRestore();
@@ -551,18 +615,23 @@ describe('SyncService', () => {
     it('should force concurrency=1 for multi-locale formats', async () => {
       setupLockManager(makeEmptyLockFile());
       const callOrder: string[] = [];
-      const translateBatch = jest.fn().mockImplementation(async (_texts: string[], opts: { targetLang: string }) => {
-        callOrder.push(opts.targetLang);
-        return [
-          { text: 'T1', billedCharacters: 2 },
-          { text: 'T2', billedCharacters: 2 },
-        ];
-      });
+      const translateBatch = jest
+        .fn()
+        .mockImplementation(
+          async (_texts: string[], opts: { targetLang: string }) => {
+            callOrder.push(opts.targetLang);
+            return [
+              { text: 'T1', billedCharacters: 2 },
+              { text: 'T2', billedCharacters: 2 },
+            ];
+          }
+        );
       const { service } = createMultiLocaleService({ translateBatch });
 
       mockFg.mockResolvedValue(['/test/Localizable.xcstrings'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
-        if (String(p) === '/test/Localizable.xcstrings') return XCSTRINGS_SOURCE;
+        if (String(p) === '/test/Localizable.xcstrings')
+          return XCSTRINGS_SOURCE;
         throw new Error('ENOENT');
       });
 
@@ -591,7 +660,7 @@ describe('SyncService', () => {
       expect(mockCopyFile).toHaveBeenCalledTimes(1);
       expect(mockCopyFile).toHaveBeenCalledWith(
         '/test/Localizable.xcstrings',
-        '/test/Localizable.xcstrings.deepl.bak',
+        '/test/Localizable.xcstrings.deepl.bak'
       );
     });
 
@@ -603,7 +672,9 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/Localizable.xcstrings'] as never);
       mockReadFile.mockResolvedValue(XCSTRINGS_SOURCE);
 
-      const result = await service.sync(makeMultiLocaleConfig(), { dryRun: true });
+      const result = await service.sync(makeMultiLocaleConfig(), {
+        dryRun: true,
+      });
 
       expect(result.dryRun).toBe(true);
       expect(result.newKeys).toBe(2);
@@ -635,7 +706,9 @@ describe('SyncService', () => {
         'locales/en.json': {
           farewell: makeLockEntry('Goodbye', { de: { status: 'translated' } }),
           greeting: makeLockEntry('Hello', { de: { status: 'translated' } }),
-          removed_key: makeLockEntry('Old text', { de: { status: 'translated' } }),
+          removed_key: makeLockEntry('Old text', {
+            de: { status: 'translated' },
+          }),
         },
       });
       const { mockWrite } = setupLockManager(lockFile);
@@ -685,10 +758,12 @@ describe('SyncService', () => {
 
       mockFg.mockResolvedValue([] as never);
 
-      await expect(service.sync(makeConfig(), { force: true, frozen: true })).rejects.toThrow(ValidationError);
-      await expect(service.sync(makeConfig(), { force: true, frozen: true })).rejects.toThrow(
-        'Cannot use --force and --frozen together',
-      );
+      await expect(
+        service.sync(makeConfig(), { force: true, frozen: true })
+      ).rejects.toThrow(ValidationError);
+      await expect(
+        service.sync(makeConfig(), { force: true, frozen: true })
+      ).rejects.toThrow('Cannot use --force and --frozen together');
     });
   });
 
@@ -720,7 +795,7 @@ describe('SyncService', () => {
       expect(result.currentKeys).toBe(0);
       expect(translateBatch).toHaveBeenCalledWith(
         ['Goodbye', 'Hello'],
-        expect.objectContaining({ targetLang: 'de' }),
+        expect.objectContaining({ targetLang: 'de' })
       );
     });
   });
@@ -731,7 +806,9 @@ describe('SyncService', () => {
         'locales/en.json': {
           farewell: makeLockEntry('Goodbye', { de: { status: 'translated' } }),
           greeting: makeLockEntry('Hello', { de: { status: 'translated' } }),
-          removed_key: makeLockEntry('Old text', { de: { status: 'translated' } }),
+          removed_key: makeLockEntry('Old text', {
+            de: { status: 'translated' },
+          }),
         },
       });
       setupLockManager(lockFile);
@@ -754,7 +831,7 @@ describe('SyncService', () => {
       expect(result.newKeys).toBe(2);
       expect(translateBatch).toHaveBeenCalledWith(
         ['Goodbye', 'Hello'],
-        expect.objectContaining({ targetLang: 'de' }),
+        expect.objectContaining({ targetLang: 'de' })
       );
     });
   });
@@ -780,9 +857,9 @@ describe('SyncService', () => {
       expect(translateBatch).toHaveBeenCalledTimes(1);
       expect(translateBatch).toHaveBeenCalledWith(
         expect.anything(),
-        expect.objectContaining({ targetLang: 'de' }),
+        expect.objectContaining({ targetLang: 'de' })
       );
-      expect(result.fileResults.every(fr => fr.locale === 'de')).toBe(true);
+      expect(result.fileResults.every((fr) => fr.locale === 'de')).toBe(true);
     });
   });
 
@@ -832,9 +909,9 @@ describe('SyncService', () => {
 
     it('should reconstruct YAML targets from source when the existing target file is empty', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
       mockFg.mockResolvedValue(['/test/locales/en.yaml'] as never);
@@ -852,7 +929,9 @@ describe('SyncService', () => {
       await service.sync(config);
 
       expect(mockAtomicWriteFile).toHaveBeenCalledTimes(1);
-      expect(String(mockAtomicWriteFile.mock.calls[0]![1])).toBe('greeting: Hallo\n');
+      expect(String(mockAtomicWriteFile.mock.calls[0]![1])).toBe(
+        'greeting: Hallo\n'
+      );
     });
   });
 
@@ -866,19 +945,24 @@ describe('SyncService', () => {
       });
 
       await expect(service.sync(config)).rejects.toThrow(ValidationError);
-      await expect(service.sync(config)).rejects.toThrow('No parser for format "xml"');
+      await expect(service.sync(config)).rejects.toThrow(
+        'No parser for format "xml"'
+      );
     });
   });
 
   describe('sync() — multiple files', () => {
     it('should process each file separately', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Translated', billedCharacters: 10 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Translated', billedCharacters: 10 }]);
       const { service } = createService({ translateBatch });
 
-      mockFg.mockResolvedValue(['/test/locales/en/a.json', '/test/locales/en/b.json'] as never);
+      mockFg.mockResolvedValue([
+        '/test/locales/en/a.json',
+        '/test/locales/en/b.json',
+      ] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         const filePath = String(p);
         if (filePath.endsWith('a.json') || filePath.endsWith('b.json')) {
@@ -987,7 +1071,7 @@ describe('SyncService', () => {
 
       expect(mockMkdir).toHaveBeenCalledWith(
         expect.stringContaining('locales'),
-        { recursive: true },
+        { recursive: true }
       );
     });
   });
@@ -1035,14 +1119,16 @@ describe('SyncService', () => {
       const lockFile = makeLockFileWithEntries({
         'locales/en.json': {
           farewell: makeLockEntry('Goodbye', { de: { status: 'translated' } }),
-          greeting: makeLockEntry('Old Hello', { de: { status: 'translated' } }),
+          greeting: makeLockEntry('Old Hello', {
+            de: { status: 'translated' },
+          }),
         },
       });
       setupLockManager(lockFile);
 
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
@@ -1059,7 +1145,9 @@ describe('SyncService', () => {
       // because this fixture has no de.json on disk: a lockfile entry with no
       // target content means the file was deleted, so the key must be
       // translated again rather than recorded as already done.
-      const sentTexts = translateBatch.mock.calls.flatMap((call) => call[0] as string[]);
+      const sentTexts = translateBatch.mock.calls.flatMap(
+        (call) => call[0] as string[]
+      );
       expect(sentTexts).toContain('Hello');
       expect(sentTexts).toContain('Goodbye');
     });
@@ -1110,7 +1198,7 @@ describe('SyncService', () => {
       expect(translateBatch).toHaveBeenCalledTimes(2);
       expect(result.fileResults).toHaveLength(2);
 
-      const locales = result.fileResults.map(fr => fr.locale);
+      const locales = result.fileResults.map((fr) => fr.locale);
       expect(locales).toContain('de');
       expect(locales).toContain('fr');
     });
@@ -1156,7 +1244,12 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue([] as never);
 
       const config = makeConfig({
-        buckets: { json: { include: ['locales/**/*.json'], exclude: ['locales/generated/**'] } },
+        buckets: {
+          json: {
+            include: ['locales/**/*.json'],
+            exclude: ['locales/generated/**'],
+          },
+        },
       });
       await service.sync(config);
 
@@ -1164,7 +1257,7 @@ describe('SyncService', () => {
         ['locales/**/*.json'],
         expect.objectContaining({
           ignore: ['locales/generated/**'],
-        }),
+        })
       );
     });
   });
@@ -1179,13 +1272,23 @@ describe('SyncService', () => {
       });
       setupLockManager(lockFile);
 
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo NEU', billedCharacters: 9 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo NEU', billedCharacters: 9 }]);
       const { service } = createService({ translateBatch });
 
-      const sourceJson = JSON.stringify({ greeting: 'Hello CHANGED', farewell: 'Goodbye' }, null, 2) + '\n';
-      const targetDeJson = JSON.stringify({ greeting: 'Hallo', farewell: 'Auf Wiedersehen' }, null, 2) + '\n';
+      const sourceJson =
+        JSON.stringify(
+          { greeting: 'Hello CHANGED', farewell: 'Goodbye' },
+          null,
+          2
+        ) + '\n';
+      const targetDeJson =
+        JSON.stringify(
+          { greeting: 'Hallo', farewell: 'Auf Wiedersehen' },
+          null,
+          2
+        ) + '\n';
 
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
@@ -1200,7 +1303,10 @@ describe('SyncService', () => {
       const writeCall = mockAtomicWriteFile.mock.calls[0];
       expect(writeCall).toBeDefined();
       // writeCall args: [filePath, content, encoding]
-      const writtenJson = JSON.parse(String(writeCall![1])) as Record<string, string>;
+      const writtenJson = JSON.parse(String(writeCall![1])) as Record<
+        string,
+        string
+      >;
       // The target file should use 'Auf Wiedersehen' (from existing target), not 'Goodbye' (source text)
       expect(writtenJson['farewell']).toBe('Auf Wiedersehen');
       expect(writtenJson['greeting']).toBe('Hallo NEU');
@@ -1213,7 +1319,9 @@ describe('SyncService', () => {
         'locales/en.json': {
           farewell: makeLockEntry('Goodbye', { de: { status: 'translated' } }),
           greeting: makeLockEntry('Hello', { de: { status: 'translated' } }),
-          removed_key: makeLockEntry('Old text', { de: { status: 'translated' } }),
+          removed_key: makeLockEntry('Old text', {
+            de: { status: 'translated' },
+          }),
         },
       });
       const { mockWrite } = setupLockManager(lockFile);
@@ -1282,14 +1390,16 @@ describe('SyncService', () => {
       // fast-glob returns `locales/en.json` for the bucket pattern (matching
       // the new path only) and returns both `en.json` occurrences for the
       // broader base-name scan used by the GC guard.
-      mockFg.mockImplementation((async (patterns: string | string[]): Promise<string[]> => {
-        const arr = Array.isArray(patterns) ? patterns : [patterns];
-        const first = arr[0] ?? '';
-        if (first.startsWith('**/')) {
-          return ['locales/en.json', 'locales/old-path/en.json'];
+      mockFg.mockImplementation(
+        async (patterns: string | string[]): Promise<string[]> => {
+          const arr = Array.isArray(patterns) ? patterns : [patterns];
+          const first = arr[0] ?? '';
+          if (first.startsWith('**/')) {
+            return ['locales/en.json', 'locales/old-path/en.json'];
+          }
+          return ['/test/locales/en.json'];
         }
-        return ['/test/locales/en.json'];
-      }));
+      );
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
         throw new Error('ENOENT');
@@ -1300,11 +1410,17 @@ describe('SyncService', () => {
       const writtenLockFile = mockWrite.mock.calls[0]![0] as SyncLockFile;
       // Entry for the old path survives because its base name is findable.
       expect(writtenLockFile.entries['locales/old-path/en.json']).toBeDefined();
-      expect(writtenLockFile.entries['locales/old-path/en.json']!['greeting']).toBeDefined();
+      expect(
+        writtenLockFile.entries['locales/old-path/en.json']!['greeting']
+      ).toBeDefined();
       // The warning names the lock path and hints at a glob change.
       const messages = warnSpy.mock.calls.map((c) => c.join(' '));
-      expect(messages.some((m: string) => m.includes('locales/old-path/en.json'))).toBe(true);
-      expect(messages.some((m: string) => m.toLowerCase().includes('glob change'))).toBe(true);
+      expect(
+        messages.some((m: string) => m.includes('locales/old-path/en.json'))
+      ).toBe(true);
+      expect(
+        messages.some((m: string) => m.toLowerCase().includes('glob change'))
+      ).toBe(true);
     });
 
     it('still deletes entries whose base name is absent from projectRoot', async () => {
@@ -1320,15 +1436,17 @@ describe('SyncService', () => {
       const translateBatch = jest.fn().mockResolvedValue([]);
       const { service } = createService({ translateBatch });
 
-      mockFg.mockImplementation((async (patterns: string | string[]): Promise<string[]> => {
-        const arr = Array.isArray(patterns) ? patterns : [patterns];
-        const first = arr[0] ?? '';
-        if (first.startsWith('**/')) {
-          // Base-name scan for `truly-deleted.json` returns nothing.
-          return [];
+      mockFg.mockImplementation(
+        async (patterns: string | string[]): Promise<string[]> => {
+          const arr = Array.isArray(patterns) ? patterns : [patterns];
+          const first = arr[0] ?? '';
+          if (first.startsWith('**/')) {
+            // Base-name scan for `truly-deleted.json` returns nothing.
+            return [];
+          }
+          return ['/test/locales/en.json'];
         }
-        return ['/test/locales/en.json'];
-      }));
+      );
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
         throw new Error('ENOENT');
@@ -1337,7 +1455,9 @@ describe('SyncService', () => {
       await service.sync(makeConfig());
 
       const writtenLockFile = mockWrite.mock.calls[0]![0] as SyncLockFile;
-      expect(writtenLockFile.entries['locales/truly-deleted.json']).toBeUndefined();
+      expect(
+        writtenLockFile.entries['locales/truly-deleted.json']
+      ).toBeUndefined();
       expect(writtenLockFile.entries['locales/en.json']).toBeDefined();
     });
   });
@@ -1345,10 +1465,12 @@ describe('SyncService', () => {
   describe('sync() — per-locale translation success tracking', () => {
     it('should set lock status to failed for keys where translation returned undefined', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        undefined,
-        { text: 'Auf Wiedersehen', billedCharacters: 15 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([
+          undefined,
+          { text: 'Auf Wiedersehen', billedCharacters: 15 },
+        ]);
       const { service } = createService({ translateBatch });
 
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
@@ -1365,8 +1487,10 @@ describe('SyncService', () => {
       const fileEntries = writtenLockFile.entries['locales/en.json'];
       expect(fileEntries).toBeDefined();
 
-      const farewellStatus = fileEntries!['farewell']?.translations['de']?.status;
-      const greetingStatus = fileEntries!['greeting']?.translations['de']?.status;
+      const farewellStatus =
+        fileEntries!['farewell']?.translations['de']?.status;
+      const greetingStatus =
+        fileEntries!['greeting']?.translations['de']?.status;
       // One should be 'translated', one should be 'failed'
       const statuses = [farewellStatus, greetingStatus].sort();
       expect(statuses).toEqual(['failed', 'translated']);
@@ -1376,16 +1500,19 @@ describe('SyncService', () => {
   describe('sync() — partial batch failure', () => {
     it('should complete sync when some batch results are undefined', async () => {
       setupLockManager(makeEmptyLockFile());
-      const sourceJson = JSON.stringify(
-        { alpha: 'Alpha', beta: 'Beta', gamma: 'Gamma' },
-        null,
-        2,
-      ) + '\n';
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Alpha-DE', billedCharacters: 5 },
-        undefined,
-        { text: 'Gamma-DE', billedCharacters: 10 },
-      ]);
+      const sourceJson =
+        JSON.stringify(
+          { alpha: 'Alpha', beta: 'Beta', gamma: 'Gamma' },
+          null,
+          2
+        ) + '\n';
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([
+          { text: 'Alpha-DE', billedCharacters: 5 },
+          undefined,
+          { text: 'Gamma-DE', billedCharacters: 10 },
+        ]);
       const { service } = createService({ translateBatch });
 
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
@@ -1406,16 +1533,19 @@ describe('SyncService', () => {
 
     it('should write successful translations to target file despite partial failure', async () => {
       setupLockManager(makeEmptyLockFile());
-      const sourceJson = JSON.stringify(
-        { alpha: 'Alpha', beta: 'Beta', gamma: 'Gamma' },
-        null,
-        2,
-      ) + '\n';
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Alpha-DE', billedCharacters: 5 },
-        undefined,
-        { text: 'Gamma-DE', billedCharacters: 10 },
-      ]);
+      const sourceJson =
+        JSON.stringify(
+          { alpha: 'Alpha', beta: 'Beta', gamma: 'Gamma' },
+          null,
+          2
+        ) + '\n';
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([
+          { text: 'Alpha-DE', billedCharacters: 5 },
+          undefined,
+          { text: 'Gamma-DE', billedCharacters: 10 },
+        ]);
       const { service } = createService({ translateBatch });
 
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
@@ -1435,16 +1565,19 @@ describe('SyncService', () => {
 
     it('should record failed status in lock file for undefined batch results', async () => {
       const { mockWrite } = setupLockManager(makeEmptyLockFile());
-      const sourceJson = JSON.stringify(
-        { alpha: 'Alpha', beta: 'Beta', gamma: 'Gamma' },
-        null,
-        2,
-      ) + '\n';
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Alpha-DE', billedCharacters: 5 },
-        undefined,
-        { text: 'Gamma-DE', billedCharacters: 10 },
-      ]);
+      const sourceJson =
+        JSON.stringify(
+          { alpha: 'Alpha', beta: 'Beta', gamma: 'Gamma' },
+          null,
+          2
+        ) + '\n';
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([
+          { text: 'Alpha-DE', billedCharacters: 5 },
+          undefined,
+          { text: 'Gamma-DE', billedCharacters: 10 },
+        ]);
       const { service } = createService({ translateBatch });
 
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
@@ -1459,21 +1592,26 @@ describe('SyncService', () => {
       const fileEntries = writtenLockFile.entries['locales/en.json'];
       expect(fileEntries).toBeDefined();
 
-      expect(fileEntries!['alpha']?.translations['de']?.status).toBe('translated');
+      expect(fileEntries!['alpha']?.translations['de']?.status).toBe(
+        'translated'
+      );
       expect(fileEntries!['beta']?.translations['de']?.status).toBe('failed');
-      expect(fileEntries!['gamma']?.translations['de']?.status).toBe('translated');
+      expect(fileEntries!['gamma']?.translations['de']?.status).toBe(
+        'translated'
+      );
     });
   });
 
   describe('sync() — context omitted for multi-key batches', () => {
     it('should set context for single-key batch', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
-      const singleKeyJson = JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n';
+      const singleKeyJson =
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n';
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return singleKeyJson;
@@ -1481,7 +1619,16 @@ describe('SyncService', () => {
       });
 
       mockExtractAllKeyContexts.mockResolvedValue({
-        keyContexts: new Map([['greeting', { key: 'greeting', context: 'Used in navbar header', occurrences: 1 }]]),
+        keyContexts: new Map([
+          [
+            'greeting',
+            {
+              key: 'greeting',
+              context: 'Used in navbar header',
+              occurrences: 1,
+            },
+          ],
+        ]),
         templatePatterns: [],
       });
 
@@ -1490,15 +1637,15 @@ describe('SyncService', () => {
 
       expect(translateBatch).toHaveBeenCalledWith(
         ['Hello'],
-        expect.objectContaining({ context: 'Used in navbar header' }),
+        expect.objectContaining({ context: 'Used in navbar header' })
       );
     });
 
     it('should send per-key requests with context for multi-key batch', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'translated', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'translated', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
@@ -1509,8 +1656,14 @@ describe('SyncService', () => {
 
       mockExtractAllKeyContexts.mockResolvedValue({
         keyContexts: new Map([
-          ['greeting', { key: 'greeting', context: 'Header context', occurrences: 1 }],
-          ['farewell', { key: 'farewell', context: 'Footer context', occurrences: 1 }],
+          [
+            'greeting',
+            { key: 'greeting', context: 'Header context', occurrences: 1 },
+          ],
+          [
+            'farewell',
+            { key: 'farewell', context: 'Footer context', occurrences: 1 },
+          ],
         ]),
         templatePatterns: [],
       });
@@ -1522,11 +1675,11 @@ describe('SyncService', () => {
       expect(translateBatch).toHaveBeenCalledTimes(2);
       expect(translateBatch).toHaveBeenCalledWith(
         expect.anything(),
-        expect.objectContaining({ context: 'Footer context' }),
+        expect.objectContaining({ context: 'Footer context' })
       );
       expect(translateBatch).toHaveBeenCalledWith(
         expect.anything(),
-        expect.objectContaining({ context: 'Header context' }),
+        expect.objectContaining({ context: 'Header context' })
       );
     });
 
@@ -1546,8 +1699,14 @@ describe('SyncService', () => {
 
       mockExtractAllKeyContexts.mockResolvedValue({
         keyContexts: new Map([
-          ['greeting', { key: 'greeting', context: 'Header context', occurrences: 1 }],
-          ['farewell', { key: 'farewell', context: 'Footer context', occurrences: 1 }],
+          [
+            'greeting',
+            { key: 'greeting', context: 'Header context', occurrences: 1 },
+          ],
+          [
+            'farewell',
+            { key: 'farewell', context: 'Footer context', occurrences: 1 },
+          ],
         ]),
         templatePatterns: [],
       });
@@ -1559,18 +1718,23 @@ describe('SyncService', () => {
       expect(translateBatch).toHaveBeenCalledTimes(1);
       expect(translateBatch).toHaveBeenCalledWith(
         expect.anything(),
-        expect.objectContaining({ context: undefined }),
+        expect.objectContaining({ context: undefined })
       );
     });
 
     it('should batch keys without context and send per-key for keys with context', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'translated', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'translated', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
-      const threeKeyJson = JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye', other: 'Other' }, null, 2) + '\n';
+      const threeKeyJson =
+        JSON.stringify(
+          { greeting: 'Hello', farewell: 'Goodbye', other: 'Other' },
+          null,
+          2
+        ) + '\n';
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return threeKeyJson;
@@ -1580,7 +1744,10 @@ describe('SyncService', () => {
       // Only 'greeting' has context; 'farewell' and 'other' do not
       mockExtractAllKeyContexts.mockResolvedValue({
         keyContexts: new Map([
-          ['greeting', { key: 'greeting', context: 'Navbar header', occurrences: 1 }],
+          [
+            'greeting',
+            { key: 'greeting', context: 'Navbar header', occurrences: 1 },
+          ],
         ]),
         templatePatterns: [],
       });
@@ -1592,11 +1759,11 @@ describe('SyncService', () => {
       expect(translateBatch).toHaveBeenCalledTimes(2);
       expect(translateBatch).toHaveBeenCalledWith(
         expect.anything(),
-        expect.objectContaining({ context: 'Navbar header' }),
+        expect.objectContaining({ context: 'Navbar header' })
       );
       expect(translateBatch).toHaveBeenCalledWith(
         expect.anything(),
-        expect.objectContaining({ context: undefined }),
+        expect.objectContaining({ context: undefined })
       );
     });
   });
@@ -1616,24 +1783,28 @@ describe('SyncService', () => {
         throw new Error('ENOENT');
       });
 
-      const events: Array<{ type: string; key?: string; translated: number }> = [];
+      const events: Array<{ type: string; key?: string; translated: number }> =
+        [];
       await service.sync(makeConfig(), {
-        onProgress: (event) => events.push({
-          type: event.type,
-          key: event.type === 'key-translated' ? event.key : undefined,
-          translated: event.translated,
-        }),
+        onProgress: (event) =>
+          events.push({
+            type: event.type,
+            key: event.type === 'key-translated' ? event.key : undefined,
+            translated: event.translated,
+          }),
       });
 
-      const keyEvents = events.filter(e => e.type === 'key-translated');
-      const localeEvents = events.filter(e => e.type === 'locale-complete');
+      const keyEvents = events.filter((e) => e.type === 'key-translated');
+      const localeEvents = events.filter((e) => e.type === 'locale-complete');
       expect(keyEvents.length).toBe(2);
       expect(keyEvents[0]!.translated).toBe(1);
       expect(keyEvents[1]!.translated).toBe(2);
       expect(localeEvents.length).toBe(1);
       expect(localeEvents[0]!.translated).toBe(2);
-      const lastKeyIdx = events.findIndex(e => e === keyEvents[keyEvents.length - 1]);
-      const localeIdx = events.findIndex(e => e === localeEvents[0]);
+      const lastKeyIdx = events.findIndex(
+        (e) => e === keyEvents[keyEvents.length - 1]
+      );
+      const localeIdx = events.findIndex((e) => e === localeEvents[0]);
       expect(lastKeyIdx).toBeLessThan(localeIdx);
     });
 
@@ -1660,12 +1831,13 @@ describe('SyncService', () => {
   describe('sync() — context_sent in lock entries', () => {
     it('should set context_sent: true for keys translated with context', async () => {
       const { mockWrite } = setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
-      const singleKeyJson = JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n';
+      const singleKeyJson =
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n';
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return singleKeyJson;
@@ -1673,7 +1845,12 @@ describe('SyncService', () => {
       });
 
       mockExtractAllKeyContexts.mockResolvedValue({
-        keyContexts: new Map([['greeting', { key: 'greeting', context: 'Navbar header', occurrences: 1 }]]),
+        keyContexts: new Map([
+          [
+            'greeting',
+            { key: 'greeting', context: 'Navbar header', occurrences: 1 },
+          ],
+        ]),
         templatePatterns: [],
       });
 
@@ -1714,7 +1891,7 @@ describe('SyncService', () => {
         expect.objectContaining({
           customInstructions: ['Keep formal tone'],
           styleId: 'style-123',
-        }),
+        })
       );
     });
 
@@ -1751,7 +1928,7 @@ describe('SyncService', () => {
         expect.objectContaining({
           customInstructions: ['Use du instead of Sie'],
           styleId: 'style-de',
-        }),
+        })
       );
     });
   });
@@ -1764,7 +1941,9 @@ describe('SyncService', () => {
         { text: 'Auf Wiedersehen', billedCharacters: 15 },
       ]);
       const { service, mockGlossary } = createService({ translateBatch });
-      mockGlossary.resolveGlossaryId.mockResolvedValue('resolved-glossary-id-123');
+      mockGlossary.resolveGlossaryId.mockResolvedValue(
+        'resolved-glossary-id-123'
+      );
 
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
@@ -1785,13 +1964,16 @@ describe('SyncService', () => {
 
       // With the override's own locale as the pair, so a glossary that does not
       // cover it fails at startup rather than reaching the API.
-      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
-        from: 'en',
-        targets: ['de'],
-      });
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        {
+          from: 'en',
+          targets: ['de'],
+        }
+      );
       expect(translateBatch).toHaveBeenCalledWith(
         expect.anything(),
-        expect.objectContaining({ glossaryId: 'resolved-glossary-id-123' }),
+        expect.objectContaining({ glossaryId: 'resolved-glossary-id-123' })
       );
     });
   });
@@ -1815,7 +1997,7 @@ describe('SyncService', () => {
       expect(result.totalCharactersBilled).toBe(0);
       expect(translateBatch).not.toHaveBeenCalled();
       expect(Logger.warn).toHaveBeenCalledWith(
-        expect.stringContaining('No matching locales for filter [zz]'),
+        expect.stringContaining('No matching locales for filter [zz]')
       );
     });
   });
@@ -1824,7 +2006,8 @@ describe('SyncService', () => {
     it('should translate non-primary plural forms in metadata', async () => {
       setupLockManager(makeEmptyLockFile());
 
-      const sourceJson = JSON.stringify({ item_count: '%d items' }, null, 2) + '\n';
+      const sourceJson =
+        JSON.stringify({ item_count: '%d items' }, null, 2) + '\n';
       const translateBatch = jest.fn().mockResolvedValue([
         { text: '%d Artikel', billedCharacters: 10 },
         { text: '1 Artikel', billedCharacters: 9 },
@@ -1866,12 +2049,22 @@ describe('SyncService', () => {
       expect(calledTexts[1]).toBe('1 item');
 
       const reconstructCall = mockParser.reconstruct.mock.calls[0];
-      const entries = reconstructCall[1] as Array<{ key: string; metadata?: Record<string, unknown> }>;
-      const itemEntry = entries.find(e => e.key === 'item_count');
+      const entries = reconstructCall[1] as Array<{
+        key: string;
+        metadata?: Record<string, unknown>;
+      }>;
+      const itemEntry = entries.find((e) => e.key === 'item_count');
       expect(itemEntry).toBeDefined();
-      const plurals = itemEntry!.metadata!['plurals'] as Array<{ quantity: string; value: string }>;
-      expect(plurals.find(p => p.quantity === 'one')!.value).toBe('1 Artikel');
-      expect(plurals.find(p => p.quantity === 'other')!.value).toBe('%d Artikel');
+      const plurals = itemEntry!.metadata!['plurals'] as Array<{
+        quantity: string;
+        value: string;
+      }>;
+      expect(plurals.find((p) => p.quantity === 'one')!.value).toBe(
+        '1 Artikel'
+      );
+      expect(plurals.find((p) => p.quantity === 'other')!.value).toBe(
+        '%d Artikel'
+      );
     });
   });
 
@@ -1920,10 +2113,16 @@ describe('SyncService', () => {
       expect(calledTexts[1]).toBe('items');
 
       const reconstructCall = mockParser.reconstruct.mock.calls[0];
-      const entries = reconstructCall[1] as Array<{ key: string; metadata?: Record<string, unknown> }>;
-      const itemEntry = entries.find(e => e.key === 'item');
+      const entries = reconstructCall[1] as Array<{
+        key: string;
+        metadata?: Record<string, unknown>;
+      }>;
+      const itemEntry = entries.find((e) => e.key === 'item');
       expect(itemEntry).toBeDefined();
-      const forms = itemEntry!.metadata!['plural_forms'] as Record<string, string>;
+      const forms = itemEntry!.metadata!['plural_forms'] as Record<
+        string,
+        string
+      >;
       expect(forms['msgstr[0]']).toBe('Artikel');
       expect(forms['msgstr[1]']).toBe('Artikel (pl)');
     });
@@ -1989,12 +2188,13 @@ describe('SyncService', () => {
   describe('sync() — config.validation.fail_on_error', () => {
     it('should throw ValidationError when fail_on_error is true and validation errors exist', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
-      const sourceJson = JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n';
+      const sourceJson =
+        JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n';
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
@@ -2009,18 +2209,19 @@ describe('SyncService', () => {
       });
 
       await expect(service.sync(config)).rejects.toThrow(
-        'Sync completed but validation failed',
+        'Sync completed but validation failed'
       );
     });
 
     it('should not throw when fail_on_error is false even with validation errors', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
-      const sourceJson = JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n';
+      const sourceJson =
+        JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n';
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
@@ -2043,12 +2244,13 @@ describe('SyncService', () => {
   describe('sync() — config.validation.check_placeholders: false', () => {
     it('should skip validation when check_placeholders is false', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
-      const sourceJson = JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n';
+      const sourceJson =
+        JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n';
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
@@ -2072,12 +2274,13 @@ describe('SyncService', () => {
   describe('sync() — config.validation.validate_after_sync: false', () => {
     it('should skip validation entirely when validate_after_sync is false', async () => {
       setupLockManager(makeEmptyLockFile());
-      const translateBatch = jest.fn().mockResolvedValue([
-        { text: 'Hallo', billedCharacters: 5 },
-      ]);
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5 }]);
       const { service } = createService({ translateBatch });
 
-      const sourceJson = JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n';
+      const sourceJson =
+        JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n';
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
@@ -2103,7 +2306,8 @@ describe('SyncService', () => {
     it('should include characters billed for plural translations', async () => {
       setupLockManager(makeEmptyLockFile());
 
-      const sourceJson = JSON.stringify({ item_count: '%d items' }, null, 2) + '\n';
+      const sourceJson =
+        JSON.stringify({ item_count: '%d items' }, null, 2) + '\n';
       const translateBatch = jest.fn().mockResolvedValue([
         { text: '%d Artikel', billedCharacters: 10 },
         { text: '1 Artikel', billedCharacters: 9 },
@@ -2148,7 +2352,9 @@ describe('SyncService', () => {
       setupLockManager(makeEmptyLockFile());
 
       mockFg.mockResolvedValue(['/test/locales/en.json']);
-      mockReadFile.mockResolvedValue('{"greeting":"Hello World test string that is long"}');
+      mockReadFile.mockResolvedValue(
+        '{"greeting":"Hello World test string that is long"}'
+      );
 
       const config = makeConfig({
         sync: { concurrency: 1, batch_size: 50, max_characters: 10 },
@@ -2198,15 +2404,23 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json']);
       mockReadFile.mockResolvedValue('{"greeting":"Hello Changed"}');
 
-      setupLockManager(makeLockFileWithEntries({
-        'locales/en.json': {
-          greeting: {
-            source_hash: computeSourceHash('Hello Original'),
-            source_text: 'Hello Original',
-            translations: { de: { hash: 'x', translated_at: '', status: 'translated' as const } },
+      setupLockManager(
+        makeLockFileWithEntries({
+          'locales/en.json': {
+            greeting: {
+              source_hash: computeSourceHash('Hello Original'),
+              source_text: 'Hello Original',
+              translations: {
+                de: {
+                  hash: 'x',
+                  translated_at: '',
+                  status: 'translated' as const,
+                },
+              },
+            },
           },
-        },
-      }));
+        })
+      );
 
       const config = makeConfig({
         validation: { fail_on_missing: false },
@@ -2222,15 +2436,23 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json']);
       mockReadFile.mockResolvedValue('{"greeting":"Hello Changed"}');
 
-      setupLockManager(makeLockFileWithEntries({
-        'locales/en.json': {
-          greeting: {
-            source_hash: computeSourceHash('Hello Original'),
-            source_text: 'Hello Original',
-            translations: { de: { hash: 'x', translated_at: '', status: 'translated' as const } },
+      setupLockManager(
+        makeLockFileWithEntries({
+          'locales/en.json': {
+            greeting: {
+              source_hash: computeSourceHash('Hello Original'),
+              source_text: 'Hello Original',
+              translations: {
+                de: {
+                  hash: 'x',
+                  translated_at: '',
+                  status: 'translated' as const,
+                },
+              },
+            },
           },
-        },
-      }));
+        })
+      );
 
       const config = makeConfig({
         validation: { fail_on_stale: false },
@@ -2250,7 +2472,9 @@ describe('SyncService', () => {
 
       await service.sync(makeConfig(), { dryRun: true, force: true });
 
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('--dry-run with --force'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('--dry-run with --force')
+      );
     });
   });
 
@@ -2266,14 +2490,21 @@ describe('SyncService', () => {
       ]);
       const { service, mockTranslation } = createService({ translateBatch });
       mockTranslation.listTranslationMemories.mockResolvedValue([
-        { translation_memory_id: TM_UUID_A, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: TM_UUID_A,
+          name: 'my-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ]);
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await service.sync(makeConfig({
-        translation: { translation_memory: 'my-tm' },
-      }));
+      await service.sync(
+        makeConfig({
+          translation: { translation_memory: 'my-tm' },
+        })
+      );
 
       expect(translateBatch).toHaveBeenCalled();
       const opts = translateBatch.mock.calls[0]![1] as Record<string, unknown>;
@@ -2288,22 +2519,37 @@ describe('SyncService', () => {
       ]);
       const { service, mockTranslation } = createService({ translateBatch });
       mockTranslation.listTranslationMemories.mockResolvedValue([
-        { translation_memory_id: TM_UUID_A, name: 'de-tm', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: TM_UUID_A,
+          name: 'de-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ]);
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await service.sync(makeConfig({
-        target_locales: ['de', 'fr'],
-        translation: {
-          locale_overrides: { de: { translation_memory: 'de-tm' } },
-        },
-      }));
+      await service.sync(
+        makeConfig({
+          target_locales: ['de', 'fr'],
+          translation: {
+            locale_overrides: { de: { translation_memory: 'de-tm' } },
+          },
+        })
+      );
 
-      const deCall = translateBatch.mock.calls.find(c => (c[1] as Record<string, unknown>)['targetLang'] === 'de');
-      const frCall = translateBatch.mock.calls.find(c => (c[1] as Record<string, unknown>)['targetLang'] === 'fr');
-      expect((deCall![1] as Record<string, unknown>)['translationMemoryId']).toBe(TM_UUID_A);
-      expect((frCall![1] as Record<string, unknown>)['translationMemoryId']).toBeUndefined();
+      const deCall = translateBatch.mock.calls.find(
+        (c) => (c[1] as Record<string, unknown>)['targetLang'] === 'de'
+      );
+      const frCall = translateBatch.mock.calls.find(
+        (c) => (c[1] as Record<string, unknown>)['targetLang'] === 'fr'
+      );
+      expect(
+        (deCall![1] as Record<string, unknown>)['translationMemoryId']
+      ).toBe(TM_UUID_A);
+      expect(
+        (frCall![1] as Record<string, unknown>)['translationMemoryId']
+      ).toBeUndefined();
     });
 
     it('should prefer per-locale override TM id over top-level for override locale', async () => {
@@ -2314,22 +2560,38 @@ describe('SyncService', () => {
       ]);
       const { service, mockTranslation } = createService({ translateBatch });
       mockTranslation.listTranslationMemories.mockResolvedValue([
-        { translation_memory_id: TM_UUID_A, name: 'top-tm', source_language: 'en', target_languages: ['de'] },
-        { translation_memory_id: TM_UUID_B, name: 'de-tm', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: TM_UUID_A,
+          name: 'top-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
+        {
+          translation_memory_id: TM_UUID_B,
+          name: 'de-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ]);
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await service.sync(makeConfig({
-        target_locales: ['de'],
-        translation: {
-          translation_memory: 'top-tm',
-          locale_overrides: { de: { translation_memory: 'de-tm' } },
-        },
-      }));
+      await service.sync(
+        makeConfig({
+          target_locales: ['de'],
+          translation: {
+            translation_memory: 'top-tm',
+            locale_overrides: { de: { translation_memory: 'de-tm' } },
+          },
+        })
+      );
 
-      const deCall = translateBatch.mock.calls.find(c => (c[1] as Record<string, unknown>)['targetLang'] === 'de');
-      expect((deCall![1] as Record<string, unknown>)['translationMemoryId']).toBe(TM_UUID_B);
+      const deCall = translateBatch.mock.calls.find(
+        (c) => (c[1] as Record<string, unknown>)['targetLang'] === 'de'
+      );
+      expect(
+        (deCall![1] as Record<string, unknown>)['translationMemoryId']
+      ).toBe(TM_UUID_B);
     });
 
     it('should prefer per-locale threshold over top-level threshold', async () => {
@@ -2340,36 +2602,55 @@ describe('SyncService', () => {
       ]);
       const { service, mockTranslation } = createService({ translateBatch });
       mockTranslation.listTranslationMemories.mockResolvedValue([
-        { translation_memory_id: TM_UUID_A, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: TM_UUID_A,
+          name: 'my-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ]);
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await service.sync(makeConfig({
-        target_locales: ['de'],
-        translation: {
-          translation_memory: 'my-tm',
-          translation_memory_threshold: 60,
-          locale_overrides: { de: { translation_memory_threshold: 90 } },
-        },
-      }));
+      await service.sync(
+        makeConfig({
+          target_locales: ['de'],
+          translation: {
+            translation_memory: 'my-tm',
+            translation_memory_threshold: 60,
+            locale_overrides: { de: { translation_memory_threshold: 90 } },
+          },
+        })
+      );
 
-      const deCall = translateBatch.mock.calls.find(c => (c[1] as Record<string, unknown>)['targetLang'] === 'de');
-      expect((deCall![1] as Record<string, unknown>)['translationMemoryThreshold']).toBe(90);
+      const deCall = translateBatch.mock.calls.find(
+        (c) => (c[1] as Record<string, unknown>)['targetLang'] === 'de'
+      );
+      expect(
+        (deCall![1] as Record<string, unknown>)['translationMemoryThreshold']
+      ).toBe(90);
     });
 
     it('should resolve the top-level TM during dryRun so the preview validates it', async () => {
       setupLockManager(makeEmptyLockFile());
       const { service, mockTranslation } = createService();
       mockTranslation.listTranslationMemories.mockResolvedValue([
-        { translation_memory_id: TM_UUID_A, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: TM_UUID_A,
+          name: 'my-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ]);
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await service.sync(makeConfig({
-        translation: { translation_memory: 'my-tm' },
-      }), { dryRun: true });
+      await service.sync(
+        makeConfig({
+          translation: { translation_memory: 'my-tm' },
+        }),
+        { dryRun: true }
+      );
 
       expect(mockTranslation.listTranslationMemories).toHaveBeenCalled();
     });
@@ -2378,18 +2659,27 @@ describe('SyncService', () => {
       setupLockManager(makeEmptyLockFile());
       const { service, mockTranslation } = createService();
       mockTranslation.listTranslationMemories.mockResolvedValue([
-        { translation_memory_id: TM_UUID_A, name: 'shared-tm', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: TM_UUID_A,
+          name: 'shared-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ]);
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await expect(service.sync(makeConfig({
-        target_locales: ['de', 'fr'],
-        translation: {
-          translation_memory: 'shared-tm',
-          locale_overrides: { de: { translation_memory: 'shared-tm' } },
-        },
-      }))).rejects.toThrow(/does not support the requested language pair/);
+      await expect(
+        service.sync(
+          makeConfig({
+            target_locales: ['de', 'fr'],
+            translation: {
+              translation_memory: 'shared-tm',
+              locale_overrides: { de: { translation_memory: 'shared-tm' } },
+            },
+          })
+        )
+      ).rejects.toThrow(/does not support the requested language pair/);
     });
 
     it('should reuse tmCache across top-level and per-locale override with same name', async () => {
@@ -2400,18 +2690,25 @@ describe('SyncService', () => {
       ]);
       const { service, mockTranslation } = createService({ translateBatch });
       mockTranslation.listTranslationMemories.mockResolvedValue([
-        { translation_memory_id: TM_UUID_A, name: 'shared-tm', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: TM_UUID_A,
+          name: 'shared-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ]);
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await service.sync(makeConfig({
-        target_locales: ['de'],
-        translation: {
-          translation_memory: 'shared-tm',
-          locale_overrides: { de: { translation_memory: 'shared-tm' } },
-        },
-      }));
+      await service.sync(
+        makeConfig({
+          target_locales: ['de'],
+          translation: {
+            translation_memory: 'shared-tm',
+            locale_overrides: { de: { translation_memory: 'shared-tm' } },
+          },
+        })
+      );
 
       expect(mockTranslation.listTranslationMemories).toHaveBeenCalledTimes(1);
     });
@@ -2425,16 +2722,21 @@ describe('SyncService', () => {
       mockReadFile.mockResolvedValue(SOURCE_JSON);
       mockGlossary.resolveGlossaryId.mockResolvedValue('glos-123');
 
-      await service.sync(makeConfig({
-        translation: { glossary: 'my-glossary' },
-      }));
+      await service.sync(
+        makeConfig({
+          translation: { glossary: 'my-glossary' },
+        })
+      );
 
       // With the configured pair, so a glossary that does not cover it fails here
       // rather than once per file.
-      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
-        from: 'en',
-        targets: ['de'],
-      });
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        {
+          from: 'en',
+          targets: ['de'],
+        }
+      );
     });
 
     it('should resolve glossary during dryRun so the preview validates the config', async () => {
@@ -2447,14 +2749,20 @@ describe('SyncService', () => {
       mockReadFile.mockResolvedValue(SOURCE_JSON);
       mockGlossary.resolveGlossaryId.mockResolvedValue('glos-123');
 
-      await service.sync(makeConfig({
-        translation: { glossary: 'my-glossary' },
-      }), { dryRun: true });
+      await service.sync(
+        makeConfig({
+          translation: { glossary: 'my-glossary' },
+        }),
+        { dryRun: true }
+      );
 
-      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
-        from: 'en',
-        targets: ['de'],
-      });
+      expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        {
+          from: 'en',
+          targets: ['de'],
+        }
+      );
     });
 
     it('should surface a top-level glossary that does not cover the pair during dryRun', async () => {
@@ -2463,11 +2771,15 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json']);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
       mockGlossary.resolveGlossaryId.mockRejectedValue(
-        new ConfigError('Glossary "my-glossary" does not support the requested language pair'),
+        new ConfigError(
+          'Glossary "my-glossary" does not support the requested language pair'
+        )
       );
 
       await expect(
-        service.sync(makeConfig({ translation: { glossary: 'my-glossary' } }), { dryRun: true }),
+        service.sync(makeConfig({ translation: { glossary: 'my-glossary' } }), {
+          dryRun: true,
+        })
       ).rejects.toThrow(/does not support the requested language pair/);
     });
 
@@ -2478,12 +2790,14 @@ describe('SyncService', () => {
       mockReadFile.mockResolvedValue(SOURCE_JSON);
       mockGlossary.resolveGlossaryId.mockResolvedValue('glos-fr');
 
-      await service.sync(makeConfig({
-        target_locales: ['de', 'fr'],
-        translation: {
-          locale_overrides: { fr: { glossary: 'fr-terms' } },
-        },
-      }));
+      await service.sync(
+        makeConfig({
+          target_locales: ['de', 'fr'],
+          translation: {
+            locale_overrides: { fr: { glossary: 'fr-terms' } },
+          },
+        })
+      );
 
       expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('fr-terms', {
         from: 'en',
@@ -2499,15 +2813,21 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json']);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
       mockGlossary.resolveGlossaryId.mockRejectedValue(
-        new ConfigError('Glossary "fr-terms" does not support the requested language pair'),
+        new ConfigError(
+          'Glossary "fr-terms" does not support the requested language pair'
+        )
       );
 
-      await expect(service.sync(makeConfig({
-        target_locales: ['de', 'fr'],
-        translation: {
-          locale_overrides: { fr: { glossary: 'fr-terms' } },
-        },
-      }))).rejects.toThrow(/does not support the requested language pair/);
+      await expect(
+        service.sync(
+          makeConfig({
+            target_locales: ['de', 'fr'],
+            translation: {
+              locale_overrides: { fr: { glossary: 'fr-terms' } },
+            },
+          })
+        )
+      ).rejects.toThrow(/does not support the requested language pair/);
 
       expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledTimes(1);
     });
@@ -2519,12 +2839,15 @@ describe('SyncService', () => {
       mockReadFile.mockResolvedValue(SOURCE_JSON);
       mockGlossary.resolveGlossaryId.mockResolvedValue('glos-fr');
 
-      await service.sync(makeConfig({
-        target_locales: ['de', 'fr'],
-        translation: {
-          locale_overrides: { fr: { glossary: 'fr-terms' } },
-        },
-      }), { dryRun: true });
+      await service.sync(
+        makeConfig({
+          target_locales: ['de', 'fr'],
+          translation: {
+            locale_overrides: { fr: { glossary: 'fr-terms' } },
+          },
+        }),
+        { dryRun: true }
+      );
 
       expect(mockGlossary.resolveGlossaryId).toHaveBeenCalledWith('fr-terms', {
         from: 'en',
@@ -2538,12 +2861,14 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json']);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await service.sync(makeConfig({
-        target_locales: ['de'],
-        translation: {
-          locale_overrides: { de: { glossary: 'auto' } },
-        },
-      }));
+      await service.sync(
+        makeConfig({
+          target_locales: ['de'],
+          translation: {
+            locale_overrides: { de: { glossary: 'auto' } },
+          },
+        })
+      );
 
       expect(mockGlossary.resolveGlossaryId).not.toHaveBeenCalled();
     });
@@ -2554,12 +2879,15 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json']);
       mockReadFile.mockResolvedValue(SOURCE_JSON);
 
-      await service.sync(makeConfig({
-        target_locales: ['de', 'fr'],
-        translation: {
-          locale_overrides: { fr: { glossary: 'fr-terms' } },
-        },
-      }), { localeFilter: ['de'] });
+      await service.sync(
+        makeConfig({
+          target_locales: ['de', 'fr'],
+          translation: {
+            locale_overrides: { fr: { glossary: 'fr-terms' } },
+          },
+        }),
+        { localeFilter: ['de'] }
+      );
 
       expect(mockGlossary.resolveGlossaryId).not.toHaveBeenCalled();
     });
@@ -2573,7 +2901,10 @@ describe('SyncService', () => {
         { text: 'Hallo', billedCharacters: 5 },
       ]);
 
-      mockExtractAllKeyContexts.mockResolvedValue({ keyContexts: new Map(), templatePatterns: [] });
+      mockExtractAllKeyContexts.mockResolvedValue({
+        keyContexts: new Map(),
+        templatePatterns: [],
+      });
       mockFg.mockResolvedValue(['/test/locales/en.json']);
       mockReadFile.mockResolvedValue('{"greeting":"Hello"}');
 
@@ -2601,7 +2932,8 @@ describe('SyncService', () => {
       ]);
       const { service } = createService({ translateBatch });
 
-      const sourceJson = JSON.stringify({ empty_key: '', greeting: 'Hello' }, null, 2) + '\n';
+      const sourceJson =
+        JSON.stringify({ empty_key: '', greeting: 'Hello' }, null, 2) + '\n';
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
@@ -2615,10 +2947,12 @@ describe('SyncService', () => {
       expect(result.newKeys).toBe(2);
       expect(translateBatch).toHaveBeenCalledWith(
         expect.arrayContaining(['']),
-        expect.anything(),
+        expect.anything()
       );
       expect(mockAtomicWriteFile).toHaveBeenCalledTimes(1);
-      const writtenContent = JSON.parse(String(mockAtomicWriteFile.mock.calls[0]![1]));
+      const writtenContent = JSON.parse(
+        String(mockAtomicWriteFile.mock.calls[0]![1])
+      );
       expect(writtenContent).toHaveProperty('empty_key');
     });
   });
@@ -2640,39 +2974,54 @@ describe('SyncService', () => {
 
       expect(result.success).toBe(false);
       expect(result.fileResults.length).toBeGreaterThan(0);
-      expect(result.fileResults.every(fr => fr.translated === 0)).toBe(true);
+      expect(result.fileResults.every((fr) => fr.translated === 0)).toBe(true);
     });
   });
 });
 
 describe('resolveTargetPath()', () => {
   it('should replace locale in filename', () => {
-    expect(resolveTargetPath('locales/en.json', 'en', 'de')).toBe('locales/de.json');
+    expect(resolveTargetPath('locales/en.json', 'en', 'de')).toBe(
+      'locales/de.json'
+    );
   });
 
   it('should replace locale in directory path', () => {
-    expect(resolveTargetPath('locales/en/common.json', 'en', 'de')).toBe('locales/de/common.json');
+    expect(resolveTargetPath('locales/en/common.json', 'en', 'de')).toBe(
+      'locales/de/common.json'
+    );
   });
 
   it('should not partially match within longer words', () => {
-    expect(resolveTargetPath('locales/en.json', 'en', 'de')).toBe('locales/de.json');
-    expect(resolveTargetPath('content/en.json', 'en', 'de')).toBe('content/de.json');
+    expect(resolveTargetPath('locales/en.json', 'en', 'de')).toBe(
+      'locales/de.json'
+    );
+    expect(resolveTargetPath('content/en.json', 'en', 'de')).toBe(
+      'content/de.json'
+    );
   });
 
   it('should handle path with dots in directory name', () => {
-    expect(resolveTargetPath('my.app/locales/en/messages.json', 'en', 'fr'))
-      .toBe('my.app/locales/fr/messages.json');
+    expect(
+      resolveTargetPath('my.app/locales/en/messages.json', 'en', 'fr')
+    ).toBe('my.app/locales/fr/messages.json');
   });
 
   it('should replace at start of path', () => {
-    expect(resolveTargetPath('en/messages.json', 'en', 'de')).toBe('de/messages.json');
+    expect(resolveTargetPath('en/messages.json', 'en', 'de')).toBe(
+      'de/messages.json'
+    );
   });
 
   it('should handle regional locale codes', () => {
-    expect(resolveTargetPath('locales/en-US.json', 'en-US', 'de-DE')).toBe('locales/de-DE.json');
+    expect(resolveTargetPath('locales/en-US.json', 'en-US', 'de-DE')).toBe(
+      'locales/de-DE.json'
+    );
   });
 
   it('should handle multiple occurrences', () => {
-    expect(resolveTargetPath('en/data/en.json', 'en', 'de')).toBe('de/data/de.json');
+    expect(resolveTargetPath('en/data/en.json', 'en', 'de')).toBe(
+      'de/data/de.json'
+    );
   });
 });
diff --git a/tests/unit/sync/sync-source-as-translation.test.ts b/tests/unit/sync/sync-source-as-translation.test.ts
index f86f0c05..d80354a0 100644
--- a/tests/unit/sync/sync-source-as-translation.test.ts
+++ b/tests/unit/sync/sync-source-as-translation.test.ts
@@ -14,7 +14,10 @@ import type { LocaleTranslatorContext } from '../../../src/sync/sync-locale-tran
 import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
 import type { SyncDiff } from '../../../src/sync/types';
 import type { KeyContext } from '../../../src/sync/sync-context';
-import type { FormatParser, TranslatedEntry } from '../../../src/formats/format';
+import type {
+  FormatParser,
+  TranslatedEntry,
+} from '../../../src/formats/format';
 import { createMockTranslationService } from '../../helpers/mock-factories';
 
 jest.mock('fs', () => ({
@@ -51,17 +54,30 @@ jest.mock('../../../src/sync/translation-validator', () => ({
 
 import * as fs from 'fs';
 import { atomicWriteFile } from '../../../src/utils/atomic-write';
-import { resolveTargetPath, assertPathWithinRoot } from '../../../src/sync/sync-utils';
+import {
+  resolveTargetPath,
+  assertPathWithinRoot,
+} from '../../../src/sync/sync-utils';
 import { validateBatch } from '../../../src/sync/translation-validator';
 
-const mockReadFile = fs.promises.readFile as jest.MockedFunction<typeof fs.promises.readFile>;
-const mockMkdir = fs.promises.mkdir as jest.MockedFunction<typeof fs.promises.mkdir>;
-const mockAtomicWriteFile = atomicWriteFile as jest.MockedFunction<typeof atomicWriteFile>;
-const mockResolveTargetPath = resolveTargetPath as jest.MockedFunction<typeof resolveTargetPath>;
+const mockReadFile = fs.promises.readFile as jest.MockedFunction<
+  typeof fs.promises.readFile
+>;
+const mockMkdir = fs.promises.mkdir as jest.MockedFunction<
+  typeof fs.promises.mkdir
+>;
+const mockAtomicWriteFile = atomicWriteFile as jest.MockedFunction<
+  typeof atomicWriteFile
+>;
+const mockResolveTargetPath = resolveTargetPath as jest.MockedFunction<
+  typeof resolveTargetPath
+>;
 const mockAssertPathWithinRoot = assertPathWithinRoot as jest.MockedFunction<
   typeof assertPathWithinRoot
 >;
-const mockValidateBatch = validateBatch as jest.MockedFunction<typeof validateBatch>;
+const mockValidateBatch = validateBatch as jest.MockedFunction<
+  typeof validateBatch
+>;
 
 /** Captures what reconstruct() was asked to write. */
 let reconstructedEntries: TranslatedEntry[] = [];
@@ -98,8 +114,12 @@ function makeConfig(): ResolvedSyncConfig {
  * lockfile says this locale has a translation, but the target file supplies
  * none — the file was deleted, or held an empty value.
  */
-function makeCtx(existingForLocale: Map<string, string>): LocaleTranslatorContext {
-  const diffs: SyncDiff[] = [{ key: 'greeting', value: 'Hello', status: 'current' }];
+function makeCtx(
+  existingForLocale: Map<string, string>
+): LocaleTranslatorContext {
+  const diffs: SyncDiff[] = [
+    { key: 'greeting', value: 'Hello', status: 'current' },
+  ];
   return {
     locale: 'de',
     relPath: 'locales/en.json',
@@ -112,7 +132,12 @@ function makeCtx(existingForLocale: Map<string, string>): LocaleTranslatorContex
         source_hash: 'abc',
         source_text: 'Hello',
         translations: {
-          de: { character_count: 5, hash: 'abc', status: 'translated', translated_at: '2026-01-01' },
+          de: {
+            character_count: 5,
+            hash: 'abc',
+            status: 'translated',
+            translated_at: '2026-01-01',
+          },
         },
       },
     } as unknown as LocaleTranslatorContext['fileLockEntries'],
@@ -128,7 +153,9 @@ function makeCtx(existingForLocale: Map<string, string>): LocaleTranslatorContex
 describe('source text as translation', () => {
   beforeEach(() => {
     reconstructedEntries = [];
-    mockReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+    mockReadFile.mockRejectedValue(
+      Object.assign(new Error('ENOENT'), { code: 'ENOENT' })
+    );
     mockMkdir.mockResolvedValue(undefined);
     mockAtomicWriteFile.mockResolvedValue(undefined);
     mockResolveTargetPath.mockReturnValue('locales/de.json');
@@ -140,8 +167,18 @@ describe('source text as translation', () => {
     const service = createMockTranslationService();
     service.translateBatch = jest
       .fn()
-      .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5, detectedSourceLanguage: 'en' }]);
-    const translator = new LocaleTranslator(service, new Set<string>(), makeConfig(), undefined, undefined, undefined, undefined);
+      .mockResolvedValue([
+        { text: 'Hallo', billedCharacters: 5, detectedSourceLanguage: 'en' },
+      ]);
+    const translator = new LocaleTranslator(
+      service,
+      new Set<string>(),
+      makeConfig(),
+      undefined,
+      undefined,
+      undefined,
+      undefined
+    );
 
     await translator.translate(makeCtx(new Map()));
 
@@ -154,16 +191,26 @@ describe('source text as translation', () => {
     const service = createMockTranslationService();
     const translateBatch = jest
       .fn()
-      .mockResolvedValue([{ text: 'Hallo', billedCharacters: 5, detectedSourceLanguage: 'en' }]);
+      .mockResolvedValue([
+        { text: 'Hallo', billedCharacters: 5, detectedSourceLanguage: 'en' },
+      ]);
     service.translateBatch = translateBatch;
-    const translator = new LocaleTranslator(service, new Set<string>(), makeConfig(), undefined, undefined, undefined, undefined);
+    const translator = new LocaleTranslator(
+      service,
+      new Set<string>(),
+      makeConfig(),
+      undefined,
+      undefined,
+      undefined,
+      undefined
+    );
 
     await translator.translate(makeCtx(new Map()));
 
     // The source text may be sent in any batch, so look across all calls
     // rather than assuming which one carries it.
     const sentTexts = translateBatch.mock.calls.flatMap(
-      (call) => (call as unknown[])[0] as string[],
+      (call) => (call as unknown[])[0] as string[]
     );
     expect(sentTexts).toContain('Hello');
   });
@@ -171,15 +218,25 @@ describe('source text as translation', () => {
   it('should keep an existing translation when the target file has one', async () => {
     const service = createMockTranslationService();
     service.translateBatch = jest.fn().mockResolvedValue([]);
-    const translator = new LocaleTranslator(service, new Set<string>(), makeConfig(), undefined, undefined, undefined, undefined);
+    const translator = new LocaleTranslator(
+      service,
+      new Set<string>(),
+      makeConfig(),
+      undefined,
+      undefined,
+      undefined,
+      undefined
+    );
 
     await translator.translate(makeCtx(new Map([['greeting', 'Guten Tag']])));
 
-    expect(reconstructedEntries.find((e) => e.key === 'greeting')?.translation).toBe('Guten Tag');
+    expect(
+      reconstructedEntries.find((e) => e.key === 'greeting')?.translation
+    ).toBe('Guten Tag');
     // translateBatch is still invoked, but with nothing to do — the point is
     // that the already-translated key is not re-sent.
     const sentTexts = (service.translateBatch as jest.Mock).mock.calls.flatMap(
-      (call) => (call as unknown[])[0] as string[],
+      (call) => (call as unknown[])[0] as string[]
     );
     expect(sentTexts).not.toContain('Hello');
   });
diff --git a/tests/unit/sync/sync-status.test.ts b/tests/unit/sync/sync-status.test.ts
index 3f32df62..2ccc7705 100644
--- a/tests/unit/sync/sync-status.test.ts
+++ b/tests/unit/sync/sync-status.test.ts
@@ -1,6 +1,10 @@
 import { computeSyncStatus } from '../../../src/sync/sync-status';
 import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
-import type { FormatRegistry, FormatParser, ExtractedEntry } from '../../../src/formats/index';
+import type {
+  FormatRegistry,
+  FormatParser,
+  ExtractedEntry,
+} from '../../../src/formats/index';
 
 jest.mock('fs', () => ({
   promises: {
@@ -18,10 +22,14 @@ import { SyncLockManager } from '../../../src/sync/sync-lock';
 import { computeDiff } from '../../../src/sync/sync-differ';
 
 const mockFg = fg as jest.MockedFunction<typeof fg>;
-const mockReadFile = fs.promises.readFile as jest.MockedFunction<typeof fs.promises.readFile>;
+const mockReadFile = fs.promises.readFile as jest.MockedFunction<
+  typeof fs.promises.readFile
+>;
 const mockComputeDiff = computeDiff as jest.MockedFunction<typeof computeDiff>;
 
-function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+function makeConfig(
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -60,7 +68,14 @@ function makeRegistry(parser: FormatParser): FormatRegistry {
 describe('computeSyncStatus', () => {
   beforeEach(() => {
     (SyncLockManager as jest.Mock).mockImplementation(() => ({
-      read: jest.fn().mockResolvedValue({ entries: {}, source_locale: 'en', version: 1, _comment: '', generated_at: '', stats: { total_keys: 0, total_translations: 0, last_sync: '' } }),
+      read: jest.fn().mockResolvedValue({
+        entries: {},
+        source_locale: 'en',
+        version: 1,
+        _comment: '',
+        generated_at: '',
+        stats: { total_keys: 0, total_translations: 0, last_sync: '' },
+      }),
     }));
     mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
     mockReadFile.mockResolvedValue('{}');
@@ -92,11 +107,27 @@ describe('computeSyncStatus', () => {
       read: jest.fn().mockResolvedValue({
         entries: {
           'locales/en.json': {
-            greeting: { source_hash: 'a', source_text: 'Hello', translations: { de: { hash: 'a', translated_at: '', status: 'translated' } } },
-            farewell: { source_hash: 'c', source_text: 'Goodbye', translations: { de: { hash: 'c', translated_at: '', status: 'translated' } } },
+            greeting: {
+              source_hash: 'a',
+              source_text: 'Hello',
+              translations: {
+                de: { hash: 'a', translated_at: '', status: 'translated' },
+              },
+            },
+            farewell: {
+              source_hash: 'c',
+              source_text: 'Goodbye',
+              translations: {
+                de: { hash: 'c', translated_at: '', status: 'translated' },
+              },
+            },
           },
         },
-        source_locale: 'en', version: 1, _comment: '', generated_at: '', stats: { total_keys: 2, total_translations: 2, last_sync: '' },
+        source_locale: 'en',
+        version: 1,
+        _comment: '',
+        generated_at: '',
+        stats: { total_keys: 2, total_translations: 2, last_sync: '' },
       }),
     }));
     const parser = makeParser();
@@ -130,11 +161,27 @@ describe('computeSyncStatus', () => {
       read: jest.fn().mockResolvedValue({
         entries: {
           'locales/en.json': {
-            greeting: { source_hash: 'a', source_text: 'Hello', translations: { de: { hash: 'a', translated_at: '', status: 'translated' } } },
-            removed_key: { source_hash: 'abc123', source_text: 'Old text', translations: { de: { hash: 'abc123', translated_at: '', status: 'translated' } } },
+            greeting: {
+              source_hash: 'a',
+              source_text: 'Hello',
+              translations: {
+                de: { hash: 'a', translated_at: '', status: 'translated' },
+              },
+            },
+            removed_key: {
+              source_hash: 'abc123',
+              source_text: 'Old text',
+              translations: {
+                de: { hash: 'abc123', translated_at: '', status: 'translated' },
+              },
+            },
           },
         },
-        source_locale: 'en', version: 1, _comment: '', generated_at: '', stats: { total_keys: 2, total_translations: 2, last_sync: '' },
+        source_locale: 'en',
+        version: 1,
+        _comment: '',
+        generated_at: '',
+        stats: { total_keys: 2, total_translations: 2, last_sync: '' },
       }),
     }));
     const parser = makeParser();
@@ -154,7 +201,7 @@ describe('computeSyncStatus', () => {
       makeConfig({
         buckets: { android_xml: { include: ['res/values/strings.xml'] } },
       }),
-      registry,
+      registry
     );
 
     expect(registry.getParserByFormatKey).toHaveBeenCalledWith('android_xml');
diff --git a/tests/unit/sync/sync-tms.test.ts b/tests/unit/sync/sync-tms.test.ts
index eeb5c95b..93cbfec9 100644
--- a/tests/unit/sync/sync-tms.test.ts
+++ b/tests/unit/sync/sync-tms.test.ts
@@ -52,8 +52,12 @@ jest.mock('../../../src/sync/sync-lock', () => {
     ...actual,
     SyncLockManager: jest.fn().mockImplementation(() => ({
       read: jest.fn().mockResolvedValue({
-        _comment: '', version: 1, generated_at: '', source_locale: 'en',
-        entries: {}, stats: { total_keys: 0, total_translations: 0, last_sync: '' },
+        _comment: '',
+        version: 1,
+        generated_at: '',
+        source_locale: 'en',
+        entries: {},
+        stats: { total_keys: 0, total_translations: 0, last_sync: '' },
       }),
       write: jest.fn().mockResolvedValue(undefined),
     })),
@@ -67,7 +71,9 @@ const mockFg = fg as jest.MockedFunction<typeof fg>;
 const mockReadFileSync = fs.readFileSync as jest.Mock;
 const mockReadFile = fs.promises.readFile as jest.Mock;
 
-function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+function makeConfig(
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -82,11 +88,12 @@ function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncCo
 
 function makeStubParser(
   extractResults: ExtractedEntry[][] | ExtractedEntry[],
-  opts: { multiLocale?: boolean; configKey?: string } = {},
+  opts: { multiLocale?: boolean; configKey?: string } = {}
 ): FormatParser {
-  const queue = Array.isArray(extractResults[0]) && typeof extractResults[0] !== 'string'
-    ? (extractResults as ExtractedEntry[][]).slice()
-    : null;
+  const queue =
+    Array.isArray(extractResults[0]) && typeof extractResults[0] !== 'string'
+      ? (extractResults as ExtractedEntry[][]).slice()
+      : null;
   const single = !queue ? (extractResults as ExtractedEntry[]) : null;
 
   return {
@@ -198,7 +205,9 @@ describe('TmsClient.pushEntry — runtime skip-partition guard', () => {
       projectId: 'p',
       apiKey: 'k',
     });
-    const pushKeySpy = jest.spyOn(client, 'pushKey').mockResolvedValue(undefined);
+    const pushKeySpy = jest
+      .spyOn(client, 'pushKey')
+      .mockResolvedValue(undefined);
     const skipped: ExtractedEntry = {
       key: 'msgs.apples',
       value: '{0} none|{1} one|[2,*] many',
@@ -216,7 +225,9 @@ describe('TmsClient.pushEntry — runtime skip-partition guard', () => {
       projectId: 'p',
       apiKey: 'k',
     });
-    const pushKeySpy = jest.spyOn(client, 'pushKey').mockResolvedValue(undefined);
+    const pushKeySpy = jest
+      .spyOn(client, 'pushKey')
+      .mockResolvedValue(undefined);
     await client.pushEntry({ key: 'greeting', value: 'Hallo' }, 'de');
     expect(pushKeySpy).toHaveBeenCalledWith('greeting', 'de', 'Hallo');
   });
@@ -253,12 +264,14 @@ describe('pushTranslations — skip-partition invariant at inline extract sites'
     const result = await pushTranslations(
       makeConfig(),
       client,
-      makeRegistryWithParser(parser),
+      makeRegistryWithParser(parser)
     );
 
     const pushKeyMock = client.pushKey as jest.Mock;
     const pushedKeys = pushKeyMock.mock.calls.map((args) => args[0]);
-    expect(pushedKeys).toEqual(expect.arrayContaining(['greeting', 'farewell']));
+    expect(pushedKeys).toEqual(
+      expect.arrayContaining(['greeting', 'farewell'])
+    );
     expect(pushedKeys).not.toContain('plural.apples');
     expect(result.pushed).toBe(2);
     expect(result.skipped).toContainEqual({
@@ -290,7 +303,11 @@ describe('pushTranslations — skip-partition invariant at inline extract sites'
     const config = makeConfig({
       buckets: { xcstrings: { include: ['Localizable.xcstrings'] } },
     });
-    const result = await pushTranslations(config, client, makeRegistryWithParser(parser));
+    const result = await pushTranslations(
+      config,
+      client,
+      makeRegistryWithParser(parser)
+    );
 
     const pushKeyMock = client.pushKey as jest.Mock;
     expect(pushKeyMock.mock.calls.map((a) => a[0])).toEqual(['greeting']);
@@ -314,7 +331,11 @@ describe('pushTranslations — skip-partition invariant at inline extract sites'
     const client = makeTmsClient();
 
     const config = makeConfig({ target_locales: ['de', 'fr'] });
-    const result = await pushTranslations(config, client, makeRegistryWithParser(parser));
+    const result = await pushTranslations(
+      config,
+      client,
+      makeRegistryWithParser(parser)
+    );
 
     const pushKeyMock = client.pushKey as jest.Mock;
     for (const args of pushKeyMock.mock.calls) {
@@ -329,15 +350,21 @@ describe('pushTranslations — skip-partition invariant at inline extract sites'
 });
 
 describe('pullTranslations — skip-partition invariant at pull-merge extract (lines 144-145)', () => {
-  const { SyncLockManager: MockLockManager } = jest.requireMock('../../../src/sync/sync-lock');
+  const { SyncLockManager: MockLockManager } = jest.requireMock(
+    '../../../src/sync/sync-lock'
+  );
 
   beforeEach(() => {
     mockFg.mockReset();
     mockReadFile.mockReset();
     MockLockManager.mockImplementation(() => ({
       read: jest.fn().mockResolvedValue({
-        _comment: '', version: 1, generated_at: '', source_locale: 'en',
-        entries: {}, stats: { total_keys: 0, total_translations: 0, last_sync: '' },
+        _comment: '',
+        version: 1,
+        generated_at: '',
+        source_locale: 'en',
+        entries: {},
+        stats: { total_keys: 0, total_translations: 0, last_sync: '' },
       }),
       write: jest.fn().mockResolvedValue(undefined),
     }));
@@ -349,7 +376,9 @@ describe('pullTranslations — skip-partition invariant at pull-merge extract (l
     // Walker reads the source file; pull then also reads the target file.
     mockReadFile.mockImplementation(async (p: fs.PathLike) => {
       const name = path.basename(String(p));
-      return name.includes('en') ? '<?php return ["a"=>"Hi"];' : '<?php return ["a"=>"Old"];';
+      return name.includes('en')
+        ? '<?php return ["a"=>"Hi"];'
+        : '<?php return ["a"=>"Old"];';
     });
 
     const sourceEntries: ExtractedEntry[] = [
@@ -377,7 +406,7 @@ describe('pullTranslations — skip-partition invariant at pull-merge extract (l
     const result = await pullTranslations(
       makeConfig(),
       client,
-      makeRegistryWithParser(parser),
+      makeRegistryWithParser(parser)
     );
 
     expect(result.pulled).toBe(1);
@@ -415,7 +444,11 @@ describe('pullTranslations — skip-partition invariant at pull-merge extract (l
     const config = makeConfig({
       buckets: { xcstrings: { include: ['Localizable.xcstrings'] } },
     });
-    const result = await pullTranslations(config, client, makeRegistryWithParser(parser));
+    const result = await pullTranslations(
+      config,
+      client,
+      makeRegistryWithParser(parser)
+    );
 
     expect(result.pulled).toBe(1);
     const reconstructMock = parser.reconstruct as jest.Mock;
@@ -437,9 +470,9 @@ describe('formatSkippedSummary', () => {
   });
 
   it('renders a single-reason summary', () => {
-    expect(formatSkippedSummary([rec('target_missing'), rec('target_missing')])).toBe(
-      ' (2 skipped: 2 target file not yet present)',
-    );
+    expect(
+      formatSkippedSummary([rec('target_missing'), rec('target_missing')])
+    ).toBe(' (2 skipped: 2 target file not yet present)');
   });
 
   it('renders a mixed-reason summary with per-reason counts', () => {
diff --git a/tests/unit/sync/sync-utils.test.ts b/tests/unit/sync/sync-utils.test.ts
index 36fb6e5f..11a01a69 100644
--- a/tests/unit/sync/sync-utils.test.ts
+++ b/tests/unit/sync/sync-utils.test.ts
@@ -12,30 +12,44 @@ import { ValidationError } from '../../../src/utils/errors';
 
 describe('resolveTargetPath()', () => {
   it('should replace locale in filename', () => {
-    expect(resolveTargetPath('locales/en.json', 'en', 'de')).toBe('locales/de.json');
+    expect(resolveTargetPath('locales/en.json', 'en', 'de')).toBe(
+      'locales/de.json'
+    );
   });
 
   it('should replace locale in directory path', () => {
-    expect(resolveTargetPath('locales/en/common.json', 'en', 'de')).toBe('locales/de/common.json');
+    expect(resolveTargetPath('locales/en/common.json', 'en', 'de')).toBe(
+      'locales/de/common.json'
+    );
   });
 
   it('should not partially match within longer words', () => {
-    expect(resolveTargetPath('content/en.json', 'en', 'de')).toBe('content/de.json');
+    expect(resolveTargetPath('content/en.json', 'en', 'de')).toBe(
+      'content/de.json'
+    );
     // "content" contains "en" but only as a substring, not as a path segment
     // A path with no locale at a word boundary throws ValidationError
-    expect(() => resolveTargetPath('contents/messages.json', 'en', 'de')).toThrow(ValidationError);
+    expect(() =>
+      resolveTargetPath('contents/messages.json', 'en', 'de')
+    ).toThrow(ValidationError);
   });
 
   it('should handle regional locale codes', () => {
-    expect(resolveTargetPath('locales/en-US.json', 'en-US', 'de')).toBe('locales/de.json');
+    expect(resolveTargetPath('locales/en-US.json', 'en-US', 'de')).toBe(
+      'locales/de.json'
+    );
   });
 
   it('should replace at start of path', () => {
-    expect(resolveTargetPath('en/messages.json', 'en', 'de')).toBe('de/messages.json');
+    expect(resolveTargetPath('en/messages.json', 'en', 'de')).toBe(
+      'de/messages.json'
+    );
   });
 
   it('should handle multiple occurrences', () => {
-    expect(resolveTargetPath('en/data/en.json', 'en', 'de')).toBe('de/data/de.json');
+    expect(resolveTargetPath('en/data/en.json', 'en', 'de')).toBe(
+      'de/data/de.json'
+    );
   });
 
   it('should handle underscore boundary (ARB format)', () => {
@@ -43,18 +57,26 @@ describe('resolveTargetPath()', () => {
   });
 
   it('should handle dot boundary (iOS .lproj)', () => {
-    expect(resolveTargetPath('en.lproj/Localizable.strings', 'en', 'de')).toBe('de.lproj/Localizable.strings');
+    expect(resolveTargetPath('en.lproj/Localizable.strings', 'en', 'de')).toBe(
+      'de.lproj/Localizable.strings'
+    );
   });
 
   it('should throw ValidationError when locale not found in path', () => {
-    expect(() => resolveTargetPath('res/values/strings.xml', 'en', 'de')).toThrow(ValidationError);
-    expect(() => resolveTargetPath('res/values/strings.xml', 'en', 'de')).toThrow(
-      'Cannot resolve target path: locale "en" not found in path "res/values/strings.xml"',
+    expect(() =>
+      resolveTargetPath('res/values/strings.xml', 'en', 'de')
+    ).toThrow(ValidationError);
+    expect(() =>
+      resolveTargetPath('res/values/strings.xml', 'en', 'de')
+    ).toThrow(
+      'Cannot resolve target path: locale "en" not found in path "res/values/strings.xml"'
     );
   });
 
   it('should throw ValidationError when path is unchanged after substitution', () => {
-    expect(() => resolveTargetPath('messages.json', 'fr', 'de')).toThrow(ValidationError);
+    expect(() => resolveTargetPath('messages.json', 'fr', 'de')).toThrow(
+      ValidationError
+    );
   });
 
   it('should treat $1 in targetLocale literally, not as a backreference', () => {
@@ -71,40 +93,50 @@ describe('resolveTargetPath()', () => {
 describe('resolveTargetPath() with targetPathPattern', () => {
   it('should resolve Android XML target path via {locale} template', () => {
     const result = resolveTargetPath(
-      'res/values/strings.xml', 'en', 'de',
-      'res/values-{locale}/strings.xml',
+      'res/values/strings.xml',
+      'en',
+      'de',
+      'res/values-{locale}/strings.xml'
     );
     expect(result).toBe('res/values-de/strings.xml');
   });
 
   it('should resolve XLIFF target path via {locale} template', () => {
     const result = resolveTargetPath(
-      'src/locale/messages.xlf', 'en', 'de',
-      'src/locale/messages.{locale}.xlf',
+      'src/locale/messages.xlf',
+      'en',
+      'de',
+      'src/locale/messages.{locale}.xlf'
     );
     expect(result).toBe('src/locale/messages.de.xlf');
   });
 
   it('should replace {basename} with source file basename', () => {
     const result = resolveTargetPath(
-      'res/values/arrays.xml', 'en', 'de',
-      'res/values-{locale}/{basename}',
+      'res/values/arrays.xml',
+      'en',
+      'de',
+      'res/values-{locale}/{basename}'
     );
     expect(result).toBe('res/values-de/arrays.xml');
   });
 
   it('should handle multiple {locale} occurrences', () => {
     const result = resolveTargetPath(
-      'src/file.txt', 'en', 'fr',
-      '{locale}/output/{locale}.json',
+      'src/file.txt',
+      'en',
+      'fr',
+      '{locale}/output/{locale}.json'
     );
     expect(result).toBe('fr/output/fr.json');
   });
 
   it('should ignore sourceLocale when pattern is provided', () => {
     const result = resolveTargetPath(
-      'res/values/strings.xml', 'en', 'ja',
-      'res/values-{locale}/strings.xml',
+      'res/values/strings.xml',
+      'en',
+      'ja',
+      'res/values-{locale}/strings.xml'
     );
     expect(result).toBe('res/values-ja/strings.xml');
   });
@@ -112,12 +144,18 @@ describe('resolveTargetPath() with targetPathPattern', () => {
 
 describe('assertPathWithinRoot()', () => {
   it('should pass for a valid path within root', () => {
-    expect(() => assertPathWithinRoot('/project/locales/de.json', '/project')).not.toThrow();
+    expect(() =>
+      assertPathWithinRoot('/project/locales/de.json', '/project')
+    ).not.toThrow();
   });
 
   it('should throw ValidationError for path escaping with ../', () => {
-    expect(() => assertPathWithinRoot('/project/../etc/passwd', '/project')).toThrow(ValidationError);
-    expect(() => assertPathWithinRoot('/project/../etc/passwd', '/project')).toThrow('Target path escapes project root');
+    expect(() =>
+      assertPathWithinRoot('/project/../etc/passwd', '/project')
+    ).toThrow(ValidationError);
+    expect(() =>
+      assertPathWithinRoot('/project/../etc/passwd', '/project')
+    ).toThrow('Target path escapes project root');
   });
 
   it('should pass for path exactly at root', () => {
@@ -125,7 +163,9 @@ describe('assertPathWithinRoot()', () => {
   });
 
   it('should throw for sibling directory', () => {
-    expect(() => assertPathWithinRoot('/other-project/file.json', '/project')).toThrow(ValidationError);
+    expect(() =>
+      assertPathWithinRoot('/other-project/file.json', '/project')
+    ).toThrow(ValidationError);
   });
 
   it('sanitizes control chars in absPath echo', () => {
@@ -149,20 +189,33 @@ describe('assertPathWithinRoot()', () => {
       // → /private/tmp case is the canonical example; this test reproduces
       // that shape portably under os.tmpdir().
       realRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'kxri-real-'));
-      symlinkedRoot = path.join(os.tmpdir(), `kxri-link-${process.pid}-${Date.now()}`);
+      symlinkedRoot = path.join(
+        os.tmpdir(),
+        `kxri-link-${process.pid}-${Date.now()}`
+      );
       fs.symlinkSync(realRoot, symlinkedRoot);
     });
 
     afterAll(() => {
-      try { fs.unlinkSync(symlinkedRoot); } catch { /* may not exist */ }
-      try { fs.rmSync(realRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+      try {
+        fs.unlinkSync(symlinkedRoot);
+      } catch {
+        /* may not exist */
+      }
+      try {
+        fs.rmSync(realRoot, { recursive: true, force: true });
+      } catch {
+        /* best effort */
+      }
     });
 
     it('accepts a path under the realpath when projectRoot is the symlink', () => {
       // projectRoot typed as the symlink, output path under the real form
       // → must pass: both resolve through realpath to the same inode.
       const outputViaReal = path.join(realRoot, 'out.xlf');
-      expect(() => assertPathWithinRoot(outputViaReal, symlinkedRoot)).not.toThrow();
+      expect(() =>
+        assertPathWithinRoot(outputViaReal, symlinkedRoot)
+      ).not.toThrow();
     });
 
     it('accepts a path under the symlink when projectRoot is the realpath', () => {
@@ -170,19 +223,23 @@ describe('assertPathWithinRoot()', () => {
       // (/private/tmp/foo) but the user types --output via the symlink form
       // (/tmp/foo/out.xlf). Both forms must resolve identically.
       const outputViaSymlink = path.join(symlinkedRoot, 'out.xlf');
-      expect(() => assertPathWithinRoot(outputViaSymlink, realRoot)).not.toThrow();
+      expect(() =>
+        assertPathWithinRoot(outputViaSymlink, realRoot)
+      ).not.toThrow();
     });
 
     it('rejects a symlink inside the project that points outside', () => {
       // Defense-in-depth: realpath resolution catches symlink-based escapes.
       // A symlink inside the project pointing at a sibling path must be
       // rejected.
-      const escapeTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'kxri-escape-'));
+      const escapeTarget = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'kxri-escape-')
+      );
       const escapeLink = path.join(realRoot, 'escape');
       fs.symlinkSync(escapeTarget, escapeLink);
       try {
         expect(() =>
-          assertPathWithinRoot(path.join(escapeLink, 'leak.xlf'), realRoot),
+          assertPathWithinRoot(path.join(escapeLink, 'leak.xlf'), realRoot)
         ).toThrow(ValidationError);
       } finally {
         fs.unlinkSync(escapeLink);
@@ -217,8 +274,12 @@ describe('resolveTargetPath() error message sanitization', () => {
 describe('getParserForBucket()', () => {
   it('resolves config-key bucket names via the registry', async () => {
     const registry = await createDefaultRegistry();
-    expect(getParserForBucket(registry, 'android_xml')?.name).toBe('Android XML');
-    expect(getParserForBucket(registry, 'ios_strings')?.name).toBe('iOS Strings');
+    expect(getParserForBucket(registry, 'android_xml')?.name).toBe(
+      'Android XML'
+    );
+    expect(getParserForBucket(registry, 'ios_strings')?.name).toBe(
+      'iOS Strings'
+    );
     expect(getParserForBucket(registry, 'json')?.name).toBe('JSON i18n');
   });
 
@@ -236,12 +297,24 @@ describe('mergePulledTranslations()', () => {
         { key: 'farewell', value: 'Goodbye' },
       ],
       { greeting: 'Hallo' },
-      new Map([['farewell', 'Tschuess']]),
+      new Map([['farewell', 'Tschuess']])
     );
 
     expect(merged).toEqual([
-      { key: 'greeting', value: 'Hello', translation: 'Hallo', context: undefined, metadata: undefined },
-      { key: 'farewell', value: 'Goodbye', translation: 'Tschuess', context: undefined, metadata: undefined },
+      {
+        key: 'greeting',
+        value: 'Hello',
+        translation: 'Hallo',
+        context: undefined,
+        metadata: undefined,
+      },
+      {
+        key: 'farewell',
+        value: 'Goodbye',
+        translation: 'Tschuess',
+        context: undefined,
+        metadata: undefined,
+      },
     ]);
   });
 
@@ -251,12 +324,24 @@ describe('mergePulledTranslations()', () => {
         { key: 'greeting', value: 'Hello' },
         { key: 'farewell', value: 'Goodbye' },
       ],
-      { greeting: 'Hallo' },
+      { greeting: 'Hallo' }
     );
 
     expect(merged).toEqual([
-      { key: 'greeting', value: 'Hello', translation: 'Hallo', context: undefined, metadata: undefined },
-      { key: 'farewell', value: 'Goodbye', translation: 'Goodbye', context: undefined, metadata: undefined },
+      {
+        key: 'greeting',
+        value: 'Hello',
+        translation: 'Hallo',
+        context: undefined,
+        metadata: undefined,
+      },
+      {
+        key: 'farewell',
+        value: 'Goodbye',
+        translation: 'Goodbye',
+        context: undefined,
+        metadata: undefined,
+      },
     ]);
   });
 });
diff --git a/tests/unit/sync/sync-validate.test.ts b/tests/unit/sync/sync-validate.test.ts
index 53a1a343..41602ae4 100644
--- a/tests/unit/sync/sync-validate.test.ts
+++ b/tests/unit/sync/sync-validate.test.ts
@@ -1,6 +1,10 @@
 import { validateTranslations } from '../../../src/sync/sync-validate';
 import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
-import type { FormatParser, FormatRegistry, ExtractedEntry } from '../../../src/formats/index';
+import type {
+  FormatParser,
+  FormatRegistry,
+  ExtractedEntry,
+} from '../../../src/formats/index';
 
 jest.mock('fs', () => ({
   promises: {
@@ -14,10 +18,16 @@ import * as fs from 'fs';
 import fg from 'fast-glob';
 
 const mockFg = fg as jest.MockedFunction<typeof fg>;
-const mockReadFile = fs.promises.readFile as jest.MockedFunction<typeof fs.promises.readFile>;
-const mockAccess = fs.promises.access as jest.MockedFunction<typeof fs.promises.access>;
+const mockReadFile = fs.promises.readFile as jest.MockedFunction<
+  typeof fs.promises.readFile
+>;
+const mockAccess = fs.promises.access as jest.MockedFunction<
+  typeof fs.promises.access
+>;
 
-function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncConfig {
+function makeConfig(
+  overrides: Partial<ResolvedSyncConfig> = {}
+): ResolvedSyncConfig {
   return {
     version: 1,
     source_locale: 'en',
@@ -30,11 +40,21 @@ function makeConfig(overrides: Partial<ResolvedSyncConfig> = {}): ResolvedSyncCo
   };
 }
 
-function makeParser(sourceEntries: ExtractedEntry[], targetEntries: ExtractedEntry[]): FormatParser {
-  const extract = jest.fn()
+function makeParser(
+  sourceEntries: ExtractedEntry[],
+  targetEntries: ExtractedEntry[]
+): FormatParser {
+  const extract = jest
+    .fn()
     .mockReturnValueOnce(sourceEntries)
     .mockReturnValueOnce(targetEntries);
-  return { name: 'JSON', configKey: 'json', extensions: ['.json'], extract, reconstruct: jest.fn() };
+  return {
+    name: 'JSON',
+    configKey: 'json',
+    extensions: ['.json'],
+    extract,
+    reconstruct: jest.fn(),
+  };
 }
 
 function makeRegistry(parser: FormatParser): FormatRegistry {
@@ -54,22 +74,38 @@ describe('validateTranslations', () => {
   });
 
   it('should pass when all translations preserve placeholders', async () => {
-    const source = [{ key: 'greeting', value: 'Hello {name}' }] as ExtractedEntry[];
-    const target = [{ key: 'greeting', value: 'Hallo {name}' }] as ExtractedEntry[];
-    mockReadFile.mockResolvedValueOnce('source').mockResolvedValueOnce('target');
+    const source = [
+      { key: 'greeting', value: 'Hello {name}' },
+    ] as ExtractedEntry[];
+    const target = [
+      { key: 'greeting', value: 'Hallo {name}' },
+    ] as ExtractedEntry[];
+    mockReadFile
+      .mockResolvedValueOnce('source')
+      .mockResolvedValueOnce('target');
     const parser = makeParser(source, target);
-    const result = await validateTranslations(makeConfig(), makeRegistry(parser));
+    const result = await validateTranslations(
+      makeConfig(),
+      makeRegistry(parser)
+    );
     expect(result.errors).toBe(0);
     expect(result.warnings).toBe(0);
     expect(result.passed).toBe(1);
   });
 
   it('should detect missing placeholder as error', async () => {
-    const source = [{ key: 'greeting', value: 'Hello {name}' }] as ExtractedEntry[];
+    const source = [
+      { key: 'greeting', value: 'Hello {name}' },
+    ] as ExtractedEntry[];
     const target = [{ key: 'greeting', value: 'Hallo' }] as ExtractedEntry[];
-    mockReadFile.mockResolvedValueOnce('source').mockResolvedValueOnce('target');
+    mockReadFile
+      .mockResolvedValueOnce('source')
+      .mockResolvedValueOnce('target');
     const parser = makeParser(source, target);
-    const result = await validateTranslations(makeConfig(), makeRegistry(parser));
+    const result = await validateTranslations(
+      makeConfig(),
+      makeRegistry(parser)
+    );
     expect(result.errors).toBeGreaterThan(0);
   });
 
@@ -82,9 +118,14 @@ describe('validateTranslations', () => {
       { key: 'a', value: 'Hallo' },
       { key: 'b', value: 'OK' },
     ] as ExtractedEntry[];
-    mockReadFile.mockResolvedValueOnce('source').mockResolvedValueOnce('target');
+    mockReadFile
+      .mockResolvedValueOnce('source')
+      .mockResolvedValueOnce('target');
     const parser = makeParser(source, target);
-    const result = await validateTranslations(makeConfig(), makeRegistry(parser));
+    const result = await validateTranslations(
+      makeConfig(),
+      makeRegistry(parser)
+    );
     expect(result.totalChecked).toBe(2);
     expect(result.errors).toBe(1);
     expect(result.warnings).toBe(1);
@@ -95,26 +136,40 @@ describe('validateTranslations', () => {
     mockReadFile.mockResolvedValueOnce('source');
     mockAccess.mockRejectedValueOnce(new Error('ENOENT'));
     const parser: FormatParser = {
-      name: 'JSON', configKey: 'json', extensions: ['.json'],
+      name: 'JSON',
+      configKey: 'json',
+      extensions: ['.json'],
       extract: jest.fn().mockReturnValue(source),
       reconstruct: jest.fn(),
     };
-    const result = await validateTranslations(makeConfig(), makeRegistry(parser));
+    const result = await validateTranslations(
+      makeConfig(),
+      makeRegistry(parser)
+    );
     expect(result.totalChecked).toBe(0);
   });
 
   it('should return empty result for empty source', async () => {
     mockReadFile.mockResolvedValueOnce('source');
     const parser = makeParser([], []);
-    const result = await validateTranslations(makeConfig(), makeRegistry(parser));
+    const result = await validateTranslations(
+      makeConfig(),
+      makeRegistry(parser)
+    );
     expect(result.totalChecked).toBe(0);
     expect(result.issues).toEqual([]);
   });
 
   it('should resolve documented ios_strings bucket keys via the registry config-key lookup', async () => {
-    const source = [{ key: 'greeting', value: 'Hello {name}' }] as ExtractedEntry[];
-    const target = [{ key: 'greeting', value: 'Hallo {name}' }] as ExtractedEntry[];
-    mockReadFile.mockResolvedValueOnce('source').mockResolvedValueOnce('target');
+    const source = [
+      { key: 'greeting', value: 'Hello {name}' },
+    ] as ExtractedEntry[];
+    const target = [
+      { key: 'greeting', value: 'Hallo {name}' },
+    ] as ExtractedEntry[];
+    mockReadFile
+      .mockResolvedValueOnce('source')
+      .mockResolvedValueOnce('target');
     const parser = makeParser(source, target);
     const registry = makeRegistry(parser);
 
@@ -122,7 +177,7 @@ describe('validateTranslations', () => {
       makeConfig({
         buckets: { ios_strings: { include: ['en.lproj/Localizable.strings'] } },
       }),
-      registry,
+      registry
     );
 
     expect(registry.getParserByFormatKey).toHaveBeenCalledWith('ios_strings');
diff --git a/tests/unit/sync/tms-client.test.ts b/tests/unit/sync/tms-client.test.ts
index ef10b97c..a0eb551b 100644
--- a/tests/unit/sync/tms-client.test.ts
+++ b/tests/unit/sync/tms-client.test.ts
@@ -26,12 +26,18 @@ describe('TmsClient', () => {
     await client.pushKey('greeting', 'de', 'Hallo');
     expect(mockFetch).toHaveBeenCalledWith(
       'https://tms.example.com/api/projects/proj-123/keys/greeting',
-      expect.objectContaining({ method: 'PUT', body: JSON.stringify({ locale: 'de', value: 'Hallo' }) }),
+      expect.objectContaining({
+        method: 'PUT',
+        body: JSON.stringify({ locale: 'de', value: 'Hallo' }),
+      })
     );
   });
 
   it('should send GET and parse JSON for pullKeys', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: 'Hallo' }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: 'Hallo' }),
+    });
     const result = await client.pullKeys('de');
     expect(result).toEqual({ greeting: 'Hallo' });
   });
@@ -39,40 +45,73 @@ describe('TmsClient', () => {
   it('should use ApiKey auth header', async () => {
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('k', 'de', 'v');
-    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<string, string>;
+    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<
+      string,
+      string
+    >;
     expect(headers?.['Authorization']).toBe('ApiKey test-key');
   });
 
   it('should use Bearer auth when token configured', async () => {
-    const tokenClient = new TmsClient({ serverUrl: 'https://s.com', projectId: 'p', token: 'tok' });
+    const tokenClient = new TmsClient({
+      serverUrl: 'https://s.com',
+      projectId: 'p',
+      token: 'tok',
+    });
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await tokenClient.pushKey('k', 'de', 'v');
-    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<string, string>;
+    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<
+      string,
+      string
+    >;
     expect(headers?.['Authorization']).toBe('Bearer tok');
   });
 
   it('should throw ConfigError with remediation hint on 401', async () => {
-    mockFetch.mockResolvedValue({ ok: false, status: 401, statusText: 'Unauthorized' });
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 401,
+      statusText: 'Unauthorized',
+    });
     await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(ConfigError);
-    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(/TMS authentication failed \(401/);
+    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(
+      /TMS authentication failed \(401/
+    );
   });
 
   it('should throw ConfigError with remediation hint on 403', async () => {
-    mockFetch.mockResolvedValue({ ok: false, status: 403, statusText: 'Forbidden' });
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 403,
+      statusText: 'Forbidden',
+    });
     await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(ConfigError);
-    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(/TMS authentication failed \(403/);
+    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(
+      /TMS authentication failed \(403/
+    );
   });
 
   it('should throw generic Error on non-auth HTTP failures (e.g. 500)', async () => {
-    mockFetch.mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error' });
-    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(/TMS API error: 500/);
-    await expect(client.pushKey('k', 'de', 'v')).rejects.not.toThrow(ConfigError);
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 500,
+      statusText: 'Internal Server Error',
+    });
+    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(
+      /TMS API error: 500/
+    );
+    await expect(client.pushKey('k', 'de', 'v')).rejects.not.toThrow(
+      ConfigError
+    );
   });
 
   it('should encode key paths', async () => {
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('nav/home', 'de', 'v');
-    expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('nav%2Fhome'), expect.anything());
+    expect(mockFetch).toHaveBeenCalledWith(
+      expect.stringContaining('nav%2Fhome'),
+      expect.anything()
+    );
   });
 });
 
@@ -86,7 +125,9 @@ describe('TmsClient HTTPS validation', () => {
       apiKey: 'key',
     });
     await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(ConfigError);
-    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow('TMS server URL must use HTTPS');
+    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(
+      'TMS server URL must use HTTPS'
+    );
   });
 
   it('should accept https:// URLs', async () => {
@@ -124,40 +165,53 @@ describe('TmsClient URL construction', () => {
   beforeEach(() => mockFetch.mockReset());
 
   function clientFor(serverUrl: string): TmsClient {
-    return new TmsClient({ serverUrl, projectId: 'proj-1', apiKey: 'key', fetch: mockFetch });
+    return new TmsClient({
+      serverUrl,
+      projectId: 'proj-1',
+      apiKey: 'key',
+      fetch: mockFetch,
+    });
   }
 
   it('should not double the separator when the server URL has a trailing slash', async () => {
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
-    await clientFor('https://tms.example.com/').pushKey('greeting', 'de', 'Hallo');
+    await clientFor('https://tms.example.com/').pushKey(
+      'greeting',
+      'de',
+      'Hallo'
+    );
 
     expect(mockFetch).toHaveBeenCalledWith(
       'https://tms.example.com/api/projects/proj-1/keys/greeting',
-      expect.anything(),
+      expect.anything()
     );
   });
 
   it('should preserve a base path on the server URL', async () => {
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
-    await clientFor('https://tms.example.com/tms/').pushKey('greeting', 'de', 'Hallo');
+    await clientFor('https://tms.example.com/tms/').pushKey(
+      'greeting',
+      'de',
+      'Hallo'
+    );
 
     expect(mockFetch).toHaveBeenCalledWith(
       'https://tms.example.com/tms/api/projects/proj-1/keys/greeting',
-      expect.anything(),
+      expect.anything()
     );
   });
 
   it('should reject a server URL carrying a query string instead of truncating the path', async () => {
-    await expect(clientFor('https://tms.example.com/?token=abc').pushKey('k', 'de', 'v')).rejects.toThrow(
-      ConfigError,
-    );
+    await expect(
+      clientFor('https://tms.example.com/?token=abc').pushKey('k', 'de', 'v')
+    ).rejects.toThrow(ConfigError);
     expect(mockFetch).not.toHaveBeenCalled();
   });
 
   it('should reject a server URL carrying a fragment', async () => {
-    await expect(clientFor('https://tms.example.com/#frag').pushKey('k', 'de', 'v')).rejects.toThrow(
-      ConfigError,
-    );
+    await expect(
+      clientFor('https://tms.example.com/#frag').pushKey('k', 'de', 'v')
+    ).rejects.toThrow(ConfigError);
     expect(mockFetch).not.toHaveBeenCalled();
   });
 
@@ -167,7 +221,7 @@ describe('TmsClient URL construction', () => {
 
     expect(mockFetch).toHaveBeenCalledWith(
       'https://tms.example.com/api/projects/proj-1/keys/export?format=json&locale=de',
-      expect.anything(),
+      expect.anything()
     );
   });
 });
@@ -178,15 +232,17 @@ describe('TmsClient error message redaction', () => {
   it('should redact credentials embedded in the server URL from timeout messages', async () => {
     jest.useFakeTimers();
     try {
-      const stubFetch = jest.fn().mockImplementation((_url: string, init?: RequestInit) => {
-        return new Promise((_resolve, reject) => {
-          init?.signal?.addEventListener('abort', () => {
-            const err = new Error('aborted');
-            err.name = 'AbortError';
-            reject(err);
+      const stubFetch = jest
+        .fn()
+        .mockImplementation((_url: string, init?: RequestInit) => {
+          return new Promise((_resolve, reject) => {
+            init?.signal?.addEventListener('abort', () => {
+              const err = new Error('aborted');
+              err.name = 'AbortError';
+              reject(err);
+            });
           });
         });
-      });
       const client = new TmsClient({
         serverUrl: 'https://alice:s3cret@tms.example.com',
         projectId: 'p',
@@ -201,7 +257,9 @@ describe('TmsClient error message redaction', () => {
       await jest.advanceTimersByTimeAsync(1001);
 
       await expect(promise).rejects.toThrow(
-        expect.objectContaining({ message: expect.not.stringContaining('s3cret') }),
+        expect.objectContaining({
+          message: expect.not.stringContaining('s3cret'),
+        })
       );
     } finally {
       jest.useRealTimers();
@@ -217,15 +275,21 @@ describe('TmsClient error message redaction', () => {
     });
 
     await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(
-      expect.objectContaining({ message: expect.not.stringContaining('s3cret') }),
+      expect.objectContaining({
+        message: expect.not.stringContaining('s3cret'),
+      })
     );
   });
 });
 
 describe('TmsTimeoutError classification', () => {
   it('should exit with the network error code', () => {
-    expect(exitCodeForError(new TmsTimeoutError('TMS request timed out'))).toBe(ExitCode.NetworkError);
-    expect(exitCodeForError(new TmsTimeoutError('TMS request timed out'))).toBe(5);
+    expect(exitCodeForError(new TmsTimeoutError('TMS request timed out'))).toBe(
+      ExitCode.NetworkError
+    );
+    expect(exitCodeForError(new TmsTimeoutError('TMS request timed out'))).toBe(
+      5
+    );
   });
 });
 
@@ -241,7 +305,9 @@ describe('TmsClient.pullKeys response size cap', () => {
   it('should reject a response whose declared content-length exceeds the cap', async () => {
     mockFetch.mockResolvedValue({
       ok: true,
-      headers: new Headers({ 'content-length': String(MAX_PULL_BODY_BYTES + 1) }),
+      headers: new Headers({
+        'content-length': String(MAX_PULL_BODY_BYTES + 1),
+      }),
       json: async () => ({}),
     });
 
@@ -291,7 +357,9 @@ describe('TmsClient fetch injection', () => {
   beforeEach(() => mockFetch.mockReset());
 
   it('should call the injected fetch instead of global fetch', async () => {
-    const stubFetch = jest.fn().mockResolvedValue({ ok: true, json: async () => ({}) });
+    const stubFetch = jest
+      .fn()
+      .mockResolvedValue({ ok: true, json: async () => ({}) });
     const client = new TmsClient({
       serverUrl: 'https://tms.example.com',
       projectId: 'proj-1',
@@ -323,15 +391,17 @@ describe('TmsClient timeout', () => {
 
   it('should reject with a timeout error after the configured duration when fetch never resolves', async () => {
     jest.useFakeTimers();
-    const stubFetch = jest.fn().mockImplementation((_url: string, init?: RequestInit) => {
-      return new Promise((_resolve, reject) => {
-        init?.signal?.addEventListener('abort', () => {
-          const err = new Error('aborted');
-          err.name = 'AbortError';
-          reject(err);
+    const stubFetch = jest
+      .fn()
+      .mockImplementation((_url: string, init?: RequestInit) => {
+        return new Promise((_resolve, reject) => {
+          init?.signal?.addEventListener('abort', () => {
+            const err = new Error('aborted');
+            err.name = 'AbortError';
+            reject(err);
+          });
         });
       });
-    });
     const client = new TmsClient({
       serverUrl: 'https://tms.example.com',
       projectId: 'p',
@@ -353,9 +423,20 @@ describe('TmsClient retry', () => {
   beforeEach(() => mockFetch.mockReset());
 
   it('should retry once on 429 and succeed on the second attempt', async () => {
-    const stubFetch = jest.fn()
-      .mockResolvedValueOnce({ ok: false, status: 429, statusText: 'Too Many Requests', text: async () => '' })
-      .mockResolvedValueOnce({ ok: true, status: 200, statusText: 'OK', json: async () => ({}) });
+    const stubFetch = jest
+      .fn()
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        text: async () => '',
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        json: async () => ({}),
+      });
     const client = new TmsClient({
       serverUrl: 'https://tms.example.com',
       projectId: 'p',
@@ -440,7 +521,7 @@ describe('TmsClient error body', () => {
       retry: { maxAttempts: 1 },
     });
     await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(
-      expect.objectContaining({ message: expect.not.stringContaining('\x1b') }),
+      expect.objectContaining({ message: expect.not.stringContaining('\x1b') })
     );
   });
 
@@ -460,7 +541,9 @@ describe('TmsClient error body', () => {
       retry: { maxAttempts: 1 },
     });
     await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(
-      expect.objectContaining({ message: expect.not.stringContaining('\u202E') }),
+      expect.objectContaining({
+        message: expect.not.stringContaining('\u202E'),
+      })
     );
   });
 });
@@ -474,7 +557,9 @@ describe('resolveTmsCredentials', () => {
     delete process.env['TMS_TOKEN'];
   });
 
-  afterEach(() => { process.env = envSnapshot; });
+  afterEach(() => {
+    process.env = envSnapshot;
+  });
 
   it('should prefer env var over config api_key', () => {
     process.env['TMS_API_KEY'] = 'env-key';
@@ -504,7 +589,9 @@ describe('createTmsClient', () => {
     mockFetch.mockReset();
   });
 
-  afterEach(() => { process.env = envSnapshot; });
+  afterEach(() => {
+    process.env = envSnapshot;
+  });
 
   const baseConfig: SyncTmsConfig = {
     enabled: true,
@@ -518,7 +605,10 @@ describe('createTmsClient', () => {
 
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('k', 'de', 'v');
-    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<string, string>;
+    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<
+      string,
+      string
+    >;
     expect(headers?.['Authorization']).toBe('ApiKey env-key');
   });
 
@@ -528,7 +618,10 @@ describe('createTmsClient', () => {
 
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('k', 'de', 'v');
-    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<string, string>;
+    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<
+      string,
+      string
+    >;
     expect(headers?.['Authorization']).toBe('Bearer env-token');
   });
 
@@ -537,19 +630,26 @@ describe('createTmsClient', () => {
 
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('k', 'de', 'v');
-    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<string, string>;
+    const headers = mockFetch.mock.calls[0]?.[1]?.headers as Record<
+      string,
+      string
+    >;
     expect(headers?.['Authorization']).toBe('ApiKey config-key');
   });
 
   it('should pass server URL and project_id to the constructed client', async () => {
     process.env['TMS_API_KEY'] = 'env-key';
-    const client = createTmsClient({ ...baseConfig, server: 'https://custom.example.com', project_id: 'custom-proj' });
+    const client = createTmsClient({
+      ...baseConfig,
+      server: 'https://custom.example.com',
+      project_id: 'custom-proj',
+    });
 
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('greeting', 'de', 'Hallo');
     expect(mockFetch).toHaveBeenCalledWith(
       'https://custom.example.com/api/projects/custom-proj/keys/greeting',
-      expect.anything(),
+      expect.anything()
     );
   });
 });
@@ -564,63 +664,100 @@ describe('TmsClient.pullKeys response validation', () => {
   beforeEach(() => mockFetch.mockReset());
 
   it('should reject response with non-string value', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: 42 }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: 42 }),
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
-    await expect(client.pullKeys('de')).rejects.toThrow(/non-string|not a string|must be a string/i);
+    await expect(client.pullKeys('de')).rejects.toThrow(
+      /non-string|not a string|must be a string/i
+    );
   });
 
   it('should reject response with nested-object value', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: { nested: 'x' } }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: { nested: 'x' } }),
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
   });
 
   it('should reject response with null value', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: null }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: null }),
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
   });
 
   it('should reject response when the payload itself is not an object', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => 'not-an-object' });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => 'not-an-object',
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
   });
 
   it('should reject key containing forward-slash path separator', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ 'nav/home': 'Home' }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ 'nav/home': 'Home' }),
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
     await expect(client.pullKeys('de')).rejects.toThrow(/key|separator/i);
   });
 
   it('should reject key containing backslash path separator', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ 'nav\\home': 'Home' }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ 'nav\\home': 'Home' }),
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
   });
 
   it('should reject key containing NUL byte', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ 'bad\x00key': 'value' }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ 'bad\x00key': 'value' }),
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
   });
 
   it('should reject key containing ASCII control chars', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ 'bad\x1bkey': 'value' }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ 'bad\x1bkey': 'value' }),
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
   });
 
   it('should reject per-value length over 64KiB', async () => {
     const oversized = 'a'.repeat(64 * 1024 + 1);
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: oversized }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: oversized }),
+    });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
-    await expect(client.pullKeys('de')).rejects.toThrow(/64|size|length|large/i);
+    await expect(client.pullKeys('de')).rejects.toThrow(
+      /64|size|length|large/i
+    );
   });
 
   it('should accept per-value length exactly at 64KiB', async () => {
     const atLimit = 'a'.repeat(64 * 1024);
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: atLimit }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: atLimit }),
+    });
     const result = await client.pullKeys('de');
     expect(result['greeting']).toBe(atLimit);
   });
 
   it('should strip ASCII control chars from accepted values', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: 'Hal\x00lo\x1bWorld\x7f' }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: 'Hal\x00lo\x1bWorld\x7f' }),
+    });
     const result = await client.pullKeys('de');
     expect(result['greeting']).toBe('HalloWorld');
   });
@@ -629,21 +766,30 @@ describe('TmsClient.pullKeys response validation', () => {
     // Tabs (\x09), line feeds (\x0a), carriage returns (\x0d) are control chars
     // per the spec but common in translation values; stripping them is the
     // documented behavior (fail-closed on format-breaking bytes).
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: 'line1\nline2\tend' }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: 'line1\nline2\tend' }),
+    });
     const result = await client.pullKeys('de');
     // The regex [\x00-\x1f\x7f] matches \n and \t. Expect both stripped.
     expect(result['greeting']).toBe('line1line2end');
   });
 
   it('should pass through normal payloads unchanged', async () => {
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: 'Hallo', farewell: 'Tschüss' }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: 'Hallo', farewell: 'Tschüss' }),
+    });
     const result = await client.pullKeys('de');
     expect(result).toEqual({ greeting: 'Hallo', farewell: 'Tschüss' });
   });
 
   it('should include an actionable suggestion string on the ValidationError', async () => {
     expect.assertions(2);
-    mockFetch.mockResolvedValue({ ok: true, json: async () => ({ greeting: 42 }) });
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ greeting: 42 }),
+    });
     try {
       await client.pullKeys('de');
     } catch (err) {
@@ -657,7 +803,9 @@ describe('TmsClient.pullKeys response validation', () => {
     for (let i = 0; i < 50001; i++) oversized[`key${i}`] = 'value';
     mockFetch.mockResolvedValue({ ok: true, json: async () => oversized });
     await expect(client.pullKeys('de')).rejects.toThrow(ValidationError);
-    await expect(client.pullKeys('de')).rejects.toThrow(/MAX_PULL_KEY_COUNT \(50000\)/);
+    await expect(client.pullKeys('de')).rejects.toThrow(
+      /MAX_PULL_KEY_COUNT \(50000\)/
+    );
   });
 
   it('should succeed when response has exactly 50,000 keys', async () => {
diff --git a/tests/unit/sync/translation-validator.test.ts b/tests/unit/sync/translation-validator.test.ts
index f7bca94b..6a59d32b 100644
--- a/tests/unit/sync/translation-validator.test.ts
+++ b/tests/unit/sync/translation-validator.test.ts
@@ -7,7 +7,11 @@ describe('translation-validator', () => {
   describe('validateTranslation', () => {
     describe('placeholders', () => {
       it('should pass when {name} is preserved', () => {
-        const result = validateTranslation('key', 'Hello {name}', 'Hallo {name}');
+        const result = validateTranslation(
+          'key',
+          'Hello {name}',
+          'Hallo {name}'
+        );
         expect(result.severity).toBe('pass');
         expect(result.issues).toHaveLength(0);
       });
@@ -22,26 +26,42 @@ describe('translation-validator', () => {
       });
 
       it('should pass when {{count}} is preserved', () => {
-        const result = validateTranslation('key', 'You have {{count}} items', 'Sie haben {{count}} Artikel');
+        const result = validateTranslation(
+          'key',
+          'You have {{count}} items',
+          'Sie haben {{count}} Artikel'
+        );
         expect(result.severity).toBe('pass');
         expect(result.issues).toHaveLength(0);
       });
 
       it('should error when ${var} is missing in translation', () => {
-        const result = validateTranslation('key', 'Value is ${var}', 'Wert ist');
+        const result = validateTranslation(
+          'key',
+          'Value is ${var}',
+          'Wert ist'
+        );
         expect(result.severity).toBe('error');
         const issue = result.issues.find((i) => i.severity === 'error');
         expect(issue?.message).toContain('${var}');
       });
 
       it('should pass when %s and %d are preserved', () => {
-        const result = validateTranslation('key', 'Hello %s, you have %d items', 'Hallo %s, Sie haben %d Artikel');
+        const result = validateTranslation(
+          'key',
+          'Hello %s, you have %d items',
+          'Hallo %s, Sie haben %d Artikel'
+        );
         expect(result.severity).toBe('pass');
         expect(result.issues).toHaveLength(0);
       });
 
       it('should error when %1$s is missing in translation', () => {
-        const result = validateTranslation('key', 'Hello %1$s from %2$s', 'Hallo');
+        const result = validateTranslation(
+          'key',
+          'Hello %1$s from %2$s',
+          'Hallo'
+        );
         expect(result.severity).toBe('error');
         const issue = result.issues.find((i) => i.severity === 'error');
         expect(issue?.message).toContain('%1$s');
@@ -56,7 +76,11 @@ describe('translation-validator', () => {
       });
 
       it('should detect one missing {count} when source has two and translation has one', () => {
-        const result = validateTranslation('key', '{count} of {count}', '{count}');
+        const result = validateTranslation(
+          'key',
+          '{count} of {count}',
+          '{count}'
+        );
         expect(result.severity).toBe('error');
         const issue = result.issues.find((i) => i.severity === 'error');
         expect(issue?.message).toContain('{count}');
@@ -65,13 +89,21 @@ describe('translation-validator', () => {
       });
 
       it('should extract {{name}} as a single placeholder, not also {name}', () => {
-        const result = validateTranslation('key', '{{name}} hello', '{{name}} hallo');
+        const result = validateTranslation(
+          'key',
+          '{{name}} hello',
+          '{{name}} hallo'
+        );
         expect(result.severity).toBe('pass');
         expect(result.issues).toHaveLength(0);
       });
 
       it('should extract both %1$s and %2$d as separate placeholders', () => {
-        const result = validateTranslation('key', '%1$s costs %2$d', '%1$s kostet %2$d');
+        const result = validateTranslation(
+          'key',
+          '%1$s costs %2$d',
+          '%1$s kostet %2$d'
+        );
         expect(result.severity).toBe('pass');
         expect(result.issues).toHaveLength(0);
       });
@@ -89,38 +121,52 @@ describe('translation-validator', () => {
         const source = '{count, plural, one {# item} other {# items}}';
         const translation = '{count, plural, one {Artikel} other {Artikel}}';
         const result = validateTranslation('key', source, translation);
-        const phIssues = result.issues.filter((i) => i.check === 'placeholders');
+        const phIssues = result.issues.filter(
+          (i) => i.check === 'placeholders'
+        );
         expect(phIssues).toHaveLength(0);
       });
 
       it('should not report select branch bodies as placeholders', () => {
         const source = '{gender, select, male {He} female {She} other {They}}';
-        const translation = '{gender, select, male {Er} female {Sie} other {Sie}}';
+        const translation =
+          '{gender, select, male {Er} female {Sie} other {Sie}}';
         const result = validateTranslation('key', source, translation);
-        const phIssues = result.issues.filter((i) => i.check === 'placeholders');
+        const phIssues = result.issues.filter(
+          (i) => i.check === 'placeholders'
+        );
         expect(phIssues).toHaveLength(0);
       });
 
       it('should still error when a placeholder inside a branch is dropped', () => {
-        const source = '{count, plural, one {{name} has # item} other {{name} has # items}}';
-        const translation = '{count, plural, one {hat # Artikel} other {hat # Artikel}}';
+        const source =
+          '{count, plural, one {{name} has # item} other {{name} has # items}}';
+        const translation =
+          '{count, plural, one {hat # Artikel} other {hat # Artikel}}';
         const result = validateTranslation('key', source, translation);
-        const issue = result.issues.find((i) => i.check === 'placeholders' && i.severity === 'error');
+        const issue = result.issues.find(
+          (i) => i.check === 'placeholders' && i.severity === 'error'
+        );
         expect(issue).toBeDefined();
         expect(issue!.message).toContain('{name}');
       });
 
       it('should pass when placeholders inside branches are preserved', () => {
-        const source = '{count, plural, one {{name} has # item} other {{name} has # items}}';
-        const translation = '{count, plural, one {{name} hat # Artikel} other {{name} hat # Artikel}}';
+        const source =
+          '{count, plural, one {{name} has # item} other {{name} has # items}}';
+        const translation =
+          '{count, plural, one {{name} hat # Artikel} other {{name} hat # Artikel}}';
         const result = validateTranslation('key', source, translation);
-        const phIssues = result.issues.filter((i) => i.check === 'placeholders');
+        const phIssues = result.issues.filter(
+          (i) => i.check === 'placeholders'
+        );
         expect(phIssues).toHaveLength(0);
       });
 
       it('should warn when a branch gains an extra placeholder', () => {
         const source = '{count, plural, one {# item} other {# items}}';
-        const translation = '{count, plural, one {{extra} Artikel} other {Artikel}}';
+        const translation =
+          '{count, plural, one {{extra} Artikel} other {Artikel}}';
         const result = validateTranslation('key', source, translation);
         const issue = result.issues.find((i) => i.check === 'placeholders');
         expect(issue).toBeDefined();
@@ -132,44 +178,67 @@ describe('translation-validator', () => {
     describe('ICU brackets', () => {
       it('should pass when ICU brackets are balanced', () => {
         const source = '{count, plural, one {# item} other {# items}}';
-        const translation = '{count, plural, one {# Artikel} other {# Artikel}}';
+        const translation =
+          '{count, plural, one {# Artikel} other {# Artikel}}';
         const result = validateTranslation('key', source, translation);
-        expect(result.issues.filter((i) => i.check === 'icu-brackets')).toHaveLength(0);
+        expect(
+          result.issues.filter((i) => i.check === 'icu-brackets')
+        ).toHaveLength(0);
       });
 
       it('should error when ICU closing bracket is missing', () => {
         const source = '{count, plural, one {# item} other {# items}}';
         const translation = '{count, plural, one {# Artikel} other {# Artikel}';
         const result = validateTranslation('key', source, translation);
-        const icuIssues = result.issues.filter((i) => i.check === 'icu-brackets');
+        const icuIssues = result.issues.filter(
+          (i) => i.check === 'icu-brackets'
+        );
         expect(icuIssues).toHaveLength(1);
         expect(icuIssues[0]?.severity).toBe('error');
       });
 
       it('should handle nested ICU select/plural correctly', () => {
-        const source = '{gender, select, male {{count, plural, one {He has # item} other {He has # items}}} female {{count, plural, one {She has # item} other {She has # items}}} other {They have # items}}';
-        const translation = '{gender, select, male {{count, plural, one {Er hat # Artikel} other {Er hat # Artikel}}} female {{count, plural, one {Sie hat # Artikel} other {Sie hat # Artikel}}} other {Sie haben # Artikel}}';
+        const source =
+          '{gender, select, male {{count, plural, one {He has # item} other {He has # items}}} female {{count, plural, one {She has # item} other {She has # items}}} other {They have # items}}';
+        const translation =
+          '{gender, select, male {{count, plural, one {Er hat # Artikel} other {Er hat # Artikel}}} female {{count, plural, one {Sie hat # Artikel} other {Sie hat # Artikel}}} other {Sie haben # Artikel}}';
         const result = validateTranslation('key', source, translation);
-        const icuIssues = result.issues.filter((i) => i.check === 'icu-brackets');
+        const icuIssues = result.issues.filter(
+          (i) => i.check === 'icu-brackets'
+        );
         expect(icuIssues).toHaveLength(0);
       });
 
       it('should not flag non-ICU text with braces', () => {
-        const result = validateTranslation('key', 'Hello {name}', 'Hallo {name}');
-        const icuIssues = result.issues.filter((i) => i.check === 'icu-brackets');
+        const result = validateTranslation(
+          'key',
+          'Hello {name}',
+          'Hallo {name}'
+        );
+        const icuIssues = result.issues.filter(
+          (i) => i.check === 'icu-brackets'
+        );
         expect(icuIssues).toHaveLength(0);
       });
     });
 
     describe('HTML tags', () => {
       it('should pass when <b>text</b> tags are matched', () => {
-        const result = validateTranslation('key', '<b>Hello</b> world', '<b>Hallo</b> Welt');
+        const result = validateTranslation(
+          'key',
+          '<b>Hello</b> world',
+          '<b>Hallo</b> Welt'
+        );
         expect(result.severity).toBe('pass');
         expect(result.issues).toHaveLength(0);
       });
 
       it('should warn when </b> is missing in translation', () => {
-        const result = validateTranslation('key', '<b>Hello</b> world', '<b>Hallo Welt');
+        const result = validateTranslation(
+          'key',
+          '<b>Hello</b> world',
+          '<b>Hallo Welt'
+        );
         expect(result.severity).toBe('warn');
         const htmlIssues = result.issues.filter((i) => i.check === 'html-tags');
         expect(htmlIssues).toHaveLength(1);
@@ -178,7 +247,11 @@ describe('translation-validator', () => {
       });
 
       it('should pass when self-closing <br/> is preserved', () => {
-        const result = validateTranslation('key', 'Line 1<br/>Line 2', 'Zeile 1<br/>Zeile 2');
+        const result = validateTranslation(
+          'key',
+          'Line 1<br/>Line 2',
+          'Zeile 1<br/>Zeile 2'
+        );
         expect(result.severity).toBe('pass');
         expect(result.issues).toHaveLength(0);
       });
@@ -201,7 +274,7 @@ describe('translation-validator', () => {
         const result = validateTranslation(
           'key',
           'Hello {name} <b>bold</b>',
-          'Hallo <b>fett',
+          'Hallo <b>fett'
         );
         expect(result.severity).toBe('error');
       });
@@ -239,20 +312,20 @@ describe('translation-validator', () => {
   describe('untranslated detection', () => {
     it('should warn when translation is identical to source', () => {
       const result = validateTranslation('key', 'Hello world', 'Hello world');
-      const issue = result.issues.find(i => i.check === 'untranslated');
+      const issue = result.issues.find((i) => i.check === 'untranslated');
       expect(issue).toBeDefined();
       expect(issue!.severity).toBe('warn');
     });
 
     it('should not warn when translation differs from source', () => {
       const result = validateTranslation('key', 'Hello world', 'Hallo Welt');
-      const issue = result.issues.find(i => i.check === 'untranslated');
+      const issue = result.issues.find((i) => i.check === 'untranslated');
       expect(issue).toBeUndefined();
     });
 
     it('should not warn for single-character strings', () => {
       const result = validateTranslation('key', '!', '!');
-      const issue = result.issues.find(i => i.check === 'untranslated');
+      const issue = result.issues.find((i) => i.check === 'untranslated');
       expect(issue).toBeUndefined();
     });
   });
@@ -260,9 +333,10 @@ describe('translation-validator', () => {
   describe('length ratio', () => {
     it('should warn when translation exceeds 150% of source length', () => {
       const source = 'Short text here';
-      const translation = 'This is a very much longer translation that far exceeds the original';
+      const translation =
+        'This is a very much longer translation that far exceeds the original';
       const result = validateTranslation('key', source, translation);
-      const issue = result.issues.find(i => i.check === 'length-ratio');
+      const issue = result.issues.find((i) => i.check === 'length-ratio');
       expect(issue).toBeDefined();
       expect(issue!.severity).toBe('warn');
       expect(issue!.message).toMatch(/\d+%/);
@@ -270,13 +344,13 @@ describe('translation-validator', () => {
 
     it('should not warn when translation is within 150% of source', () => {
       const result = validateTranslation('key', 'Hello world', 'Hallo Welt!');
-      const issue = result.issues.find(i => i.check === 'length-ratio');
+      const issue = result.issues.find((i) => i.check === 'length-ratio');
       expect(issue).toBeUndefined();
     });
 
     it('should not warn for short source strings', () => {
       const result = validateTranslation('key', 'OK', 'Einverstanden');
-      const issue = result.issues.find(i => i.check === 'length-ratio');
+      const issue = result.issues.find((i) => i.check === 'length-ratio');
       expect(issue).toBeUndefined();
     });
   });
diff --git a/tests/unit/tag-handling-version.test.ts b/tests/unit/tag-handling-version.test.ts
index fe5a79b3..316de21b 100644
--- a/tests/unit/tag-handling-version.test.ts
+++ b/tests/unit/tag-handling-version.test.ts
@@ -22,11 +22,21 @@ describe('resolveTagHandlingVersion', () => {
   });
 
   it('should honour an explicit v1 over the pinned default', () => {
-    expect(resolveTagHandlingVersion({ tagHandling: 'xml', tagHandlingVersion: 'v1' })).toBe('v1');
+    expect(
+      resolveTagHandlingVersion({
+        tagHandling: 'xml',
+        tagHandlingVersion: 'v1',
+      })
+    ).toBe('v1');
   });
 
   it('should honour an explicit v2', () => {
-    expect(resolveTagHandlingVersion({ tagHandling: 'html', tagHandlingVersion: 'v2' })).toBe('v2');
+    expect(
+      resolveTagHandlingVersion({
+        tagHandling: 'html',
+        tagHandlingVersion: 'v2',
+      })
+    ).toBe('v2');
   });
 
   it('should keep an explicit version that arrived without tag handling', () => {
diff --git a/tests/unit/text-preservation-loop.test.ts b/tests/unit/text-preservation-loop.test.ts
index b7796437..457172a9 100644
--- a/tests/unit/text-preservation-loop.test.ts
+++ b/tests/unit/text-preservation-loop.test.ts
@@ -13,7 +13,11 @@
  * results, it hangs with no API call at all.
  */
 
-import { preserveVariables, preserveCodeBlocks, restorePlaceholders } from '../../src/utils/text-preservation';
+import {
+  preserveVariables,
+  preserveCodeBlocks,
+  restorePlaceholders,
+} from '../../src/utils/text-preservation';
 
 describe('restorePlaceholders termination', () => {
   it('should terminate when the original contains its own placeholder token', () => {
@@ -47,7 +51,10 @@ describe('restorePlaceholders termination', () => {
 
   it('should restore ordinary placeholders correctly', () => {
     const map = new Map<string, string>();
-    const preserved = preserveVariables('Hello {name}, you have {count} items', map);
+    const preserved = preserveVariables(
+      'Hello {name}, you have {count} items',
+      map
+    );
 
     const restored = restorePlaceholders(preserved, map);
 
diff --git a/tests/unit/text-preservation.test.ts b/tests/unit/text-preservation.test.ts
index 4799a4bf..b1d3a33b 100644
--- a/tests/unit/text-preservation.test.ts
+++ b/tests/unit/text-preservation.test.ts
@@ -1,4 +1,8 @@
-import { preserveCodeBlocks, preserveVariables, restorePlaceholders } from '../../src/utils/text-preservation.js';
+import {
+  preserveCodeBlocks,
+  preserveVariables,
+  restorePlaceholders,
+} from '../../src/utils/text-preservation.js';
 
 describe('text-preservation', () => {
   describe('preserveCodeBlocks', () => {
@@ -179,7 +183,8 @@ describe('text-preservation', () => {
 
   describe('round-trip', () => {
     it('should restore original text after preserve → restore cycle', () => {
-      const original = 'Run `npm install` to install ${packageName} (version %s)';
+      const original =
+        'Run `npm install` to install ${packageName} (version %s)';
       const map = new Map<string, string>();
 
       let processed = preserveCodeBlocks(original, map);
diff --git a/tests/unit/text-translation-handler.test.ts b/tests/unit/text-translation-handler.test.ts
index a6de8a28..026f2aa4 100644
--- a/tests/unit/text-translation-handler.test.ts
+++ b/tests/unit/text-translation-handler.test.ts
@@ -1,5 +1,8 @@
 import { TextTranslationHandler } from '../../src/cli/commands/translate/text-translation-handler';
-import type { HandlerContext, TranslateOptions } from '../../src/cli/commands/translate/types';
+import type {
+  HandlerContext,
+  TranslateOptions,
+} from '../../src/cli/commands/translate/types';
 import { ValidationError, AuthError } from '../../src/utils/errors';
 import {
   createMockTranslationService,
@@ -25,33 +28,48 @@ jest.mock('../../src/utils/logger', () => ({
   },
 }));
 
-function createMockContext(overrides: {
-  translationService?: jest.Mocked<TranslationService>;
-  fileTranslationService?: jest.Mocked<FileTranslationService>;
-  documentTranslationService?: jest.Mocked<DocumentTranslationService>;
-  glossaryService?: jest.Mocked<GlossaryService>;
-  config?: jest.Mocked<ConfigService>;
-} = {}): { ctx: HandlerContext; mocks: {
-  translationService: jest.Mocked<TranslationService>;
-  fileTranslationService: jest.Mocked<FileTranslationService>;
-  batchTranslationService: jest.Mocked<BatchTranslationService>;
-  documentTranslationService: jest.Mocked<DocumentTranslationService>;
-  glossaryService: jest.Mocked<GlossaryService>;
-  config: jest.Mocked<ConfigService>;
-}} {
-  const translationService = overrides.translationService ?? createMockTranslationService({
-    translate: jest.fn().mockResolvedValue({ text: 'translated', detectedSourceLang: 'en' }),
-  });
-  const fileTranslationService = overrides.fileTranslationService ?? createMockFileTranslationService();
+function createMockContext(
+  overrides: {
+    translationService?: jest.Mocked<TranslationService>;
+    fileTranslationService?: jest.Mocked<FileTranslationService>;
+    documentTranslationService?: jest.Mocked<DocumentTranslationService>;
+    glossaryService?: jest.Mocked<GlossaryService>;
+    config?: jest.Mocked<ConfigService>;
+  } = {}
+): {
+  ctx: HandlerContext;
+  mocks: {
+    translationService: jest.Mocked<TranslationService>;
+    fileTranslationService: jest.Mocked<FileTranslationService>;
+    batchTranslationService: jest.Mocked<BatchTranslationService>;
+    documentTranslationService: jest.Mocked<DocumentTranslationService>;
+    glossaryService: jest.Mocked<GlossaryService>;
+    config: jest.Mocked<ConfigService>;
+  };
+} {
+  const translationService =
+    overrides.translationService ??
+    createMockTranslationService({
+      translate: jest
+        .fn()
+        .mockResolvedValue({ text: 'translated', detectedSourceLang: 'en' }),
+    });
+  const fileTranslationService =
+    overrides.fileTranslationService ?? createMockFileTranslationService();
   const batchTranslationService = {} as jest.Mocked<BatchTranslationService>;
-  const documentTranslationService = overrides.documentTranslationService ?? createMockDocumentTranslationService();
-  const glossaryService = overrides.glossaryService ?? createMockGlossaryService();
-  const config = overrides.config ?? createMockConfigService({
-    getValue: jest.fn((key: string) => {
-      if (key === 'auth.apiKey') return 'test-api-key';
-      return undefined;
-    }),
-  });
+  const documentTranslationService =
+    overrides.documentTranslationService ??
+    createMockDocumentTranslationService();
+  const glossaryService =
+    overrides.glossaryService ?? createMockGlossaryService();
+  const config =
+    overrides.config ??
+    createMockConfigService({
+      getValue: jest.fn((key: string) => {
+        if (key === 'auth.apiKey') return 'test-api-key';
+        return undefined;
+      }),
+    });
 
   const ctx: HandlerContext = {
     translationService,
@@ -62,10 +80,22 @@ function createMockContext(overrides: {
     config,
   };
 
-  return { ctx, mocks: { translationService, fileTranslationService, batchTranslationService, documentTranslationService, glossaryService, config } };
+  return {
+    ctx,
+    mocks: {
+      translationService,
+      fileTranslationService,
+      batchTranslationService,
+      documentTranslationService,
+      glossaryService,
+      config,
+    },
+  };
 }
 
-function defaultOptions(overrides: Partial<TranslateOptions> = {}): TranslateOptions {
+function defaultOptions(
+  overrides: Partial<TranslateOptions> = {}
+): TranslateOptions {
   return { to: 'de', cache: true, ...overrides };
 }
 
@@ -97,12 +127,18 @@ describe('TextTranslationHandler', () => {
 
   describe('translateText()', () => {
     it('should throw ValidationError for empty text', async () => {
-      await expect(handler.translateText('', defaultOptions())).rejects.toThrow(ValidationError);
-      await expect(handler.translateText('', defaultOptions())).rejects.toThrow('Text cannot be empty');
+      await expect(handler.translateText('', defaultOptions())).rejects.toThrow(
+        ValidationError
+      );
+      await expect(handler.translateText('', defaultOptions())).rejects.toThrow(
+        'Text cannot be empty'
+      );
     });
 
     it('should throw ValidationError for whitespace-only text', async () => {
-      await expect(handler.translateText('   ', defaultOptions())).rejects.toThrow(ValidationError);
+      await expect(
+        handler.translateText('   ', defaultOptions())
+      ).rejects.toThrow(ValidationError);
     });
 
     it('should throw AuthError when no API key is configured', async () => {
@@ -112,7 +148,9 @@ describe('TextTranslationHandler', () => {
         }),
       });
       const h = new TextTranslationHandler(ctx);
-      await expect(h.translateText('Hello', defaultOptions())).rejects.toThrow(AuthError);
+      await expect(h.translateText('Hello', defaultOptions())).rejects.toThrow(
+        AuthError
+      );
     });
 
     it('should not throw AuthError when DEEPL_API_KEY env var is set', async () => {
@@ -143,7 +181,10 @@ describe('TextTranslationHandler', () => {
         { targetLang: 'fr', text: 'Bonjour' },
       ]);
 
-      const result = await handler.translateText('Hello', defaultOptions({ to: 'de,fr' }));
+      const result = await handler.translateText(
+        'Hello',
+        defaultOptions({ to: 'de,fr' })
+      );
       expect(mocks.translationService.translateToMultiple).toHaveBeenCalled();
       expect(result).toContain('[de]');
       expect(result).toContain('[fr]');
@@ -151,63 +192,114 @@ describe('TextTranslationHandler', () => {
 
     describe('custom instructions validation', () => {
       it('should throw ValidationError when >10 custom instructions', async () => {
-        const instructions = Array.from({ length: 11 }, (_, i) => `instruction ${i}`);
+        const instructions = Array.from(
+          { length: 11 },
+          (_, i) => `instruction ${i}`
+        );
         await expect(
-          handler.translateText('Hello', defaultOptions({ customInstruction: instructions }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ customInstruction: instructions })
+          )
         ).rejects.toThrow(ValidationError);
         await expect(
-          handler.translateText('Hello', defaultOptions({ customInstruction: instructions }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ customInstruction: instructions })
+          )
         ).rejects.toThrow('Maximum 10 custom instructions allowed');
       });
 
       it('should throw ValidationError when instruction exceeds 300 chars', async () => {
         const longInstruction = 'x'.repeat(301);
         await expect(
-          handler.translateText('Hello', defaultOptions({ customInstruction: [longInstruction] }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ customInstruction: [longInstruction] })
+          )
         ).rejects.toThrow(ValidationError);
         await expect(
-          handler.translateText('Hello', defaultOptions({ customInstruction: [longInstruction] }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ customInstruction: [longInstruction] })
+          )
         ).rejects.toThrow('character limit');
       });
 
       it('should throw ValidationError when custom instructions used with latency_optimized', async () => {
         await expect(
-          handler.translateText('Hello', defaultOptions({ customInstruction: ['Be formal'], modelType: 'latency_optimized' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({
+              customInstruction: ['Be formal'],
+              modelType: 'latency_optimized',
+            })
+          )
         ).rejects.toThrow(ValidationError);
         await expect(
-          handler.translateText('Hello', defaultOptions({ customInstruction: ['Be formal'], modelType: 'latency_optimized' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({
+              customInstruction: ['Be formal'],
+              modelType: 'latency_optimized',
+            })
+          )
         ).rejects.toThrow('cannot be used with latency_optimized');
       });
     });
 
     it('should throw ValidationError when styleId used with latency_optimized', async () => {
       await expect(
-        handler.translateText('Hello', defaultOptions({ styleId: 'some-style', modelType: 'latency_optimized' }))
+        handler.translateText(
+          'Hello',
+          defaultOptions({
+            styleId: 'some-style',
+            modelType: 'latency_optimized',
+          })
+        )
       ).rejects.toThrow(ValidationError);
       await expect(
-        handler.translateText('Hello', defaultOptions({ styleId: 'some-style', modelType: 'latency_optimized' }))
+        handler.translateText(
+          'Hello',
+          defaultOptions({
+            styleId: 'some-style',
+            modelType: 'latency_optimized',
+          })
+        )
       ).rejects.toThrow('Style ID cannot be used with latency_optimized');
     });
 
     describe('XML parameters without --tag-handling xml', () => {
       it('should throw ValidationError for --outline-detection without --tag-handling xml', async () => {
         await expect(
-          handler.translateText('Hello', defaultOptions({ outlineDetection: 'true' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ outlineDetection: 'true' })
+          )
         ).rejects.toThrow(ValidationError);
         await expect(
-          handler.translateText('Hello', defaultOptions({ outlineDetection: 'true' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ outlineDetection: 'true' })
+          )
         ).rejects.toThrow('require --tag-handling xml');
       });
 
       it('should throw ValidationError for --splitting-tags without --tag-handling xml', async () => {
         await expect(
-          handler.translateText('Hello', defaultOptions({ splittingTags: 'p,div' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ splittingTags: 'p,div' })
+          )
         ).rejects.toThrow(ValidationError);
       });
 
       it('should throw ValidationError for --non-splitting-tags without --tag-handling xml', async () => {
         await expect(
-          handler.translateText('Hello', defaultOptions({ nonSplittingTags: 'span' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ nonSplittingTags: 'span' })
+          )
         ).rejects.toThrow(ValidationError);
       });
 
@@ -220,29 +312,47 @@ describe('TextTranslationHandler', () => {
 
     it('should throw ValidationError for invalid outlineDetection value', async () => {
       await expect(
-        handler.translateText('Hello', defaultOptions({ outlineDetection: 'yes', tagHandling: 'xml' }))
+        handler.translateText(
+          'Hello',
+          defaultOptions({ outlineDetection: 'yes', tagHandling: 'xml' })
+        )
       ).rejects.toThrow(ValidationError);
       await expect(
-        handler.translateText('Hello', defaultOptions({ outlineDetection: 'yes', tagHandling: 'xml' }))
+        handler.translateText(
+          'Hello',
+          defaultOptions({ outlineDetection: 'yes', tagHandling: 'xml' })
+        )
       ).rejects.toThrow('must be "true" or "false"');
     });
 
     describe('tagHandlingVersion validation', () => {
       it('should throw ValidationError without --tag-handling', async () => {
         await expect(
-          handler.translateText('Hello', defaultOptions({ tagHandlingVersion: 'v1' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ tagHandlingVersion: 'v1' })
+          )
         ).rejects.toThrow(ValidationError);
         await expect(
-          handler.translateText('Hello', defaultOptions({ tagHandlingVersion: 'v1' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ tagHandlingVersion: 'v1' })
+          )
         ).rejects.toThrow('requires --tag-handling to be set');
       });
 
       it('should throw ValidationError for invalid version value', async () => {
         await expect(
-          handler.translateText('Hello', defaultOptions({ tagHandlingVersion: 'v3', tagHandling: 'xml' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ tagHandlingVersion: 'v3', tagHandling: 'xml' })
+          )
         ).rejects.toThrow(ValidationError);
         await expect(
-          handler.translateText('Hello', defaultOptions({ tagHandlingVersion: 'v3', tagHandling: 'xml' }))
+          handler.translateText(
+            'Hello',
+            defaultOptions({ tagHandlingVersion: 'v3', tagHandling: 'xml' })
+          )
         ).rejects.toThrow('must be "v1" or "v2"');
       });
     });
@@ -250,10 +360,16 @@ describe('TextTranslationHandler', () => {
     it('should throw ValidationError for glossary without --from', async () => {
       mocks.glossaryService.resolveGlossaryId.mockResolvedValue('glossary-123');
       await expect(
-        handler.translateText('Hello', defaultOptions({ glossary: ['my-glossary'] }))
+        handler.translateText(
+          'Hello',
+          defaultOptions({ glossary: ['my-glossary'] })
+        )
       ).rejects.toThrow(ValidationError);
       await expect(
-        handler.translateText('Hello', defaultOptions({ glossary: ['my-glossary'] }))
+        handler.translateText(
+          'Hello',
+          defaultOptions({ glossary: ['my-glossary'] })
+        )
       ).rejects.toThrow('Source language (--from) is required');
     });
 
@@ -262,34 +378,57 @@ describe('TextTranslationHandler', () => {
 
       it('throws ValidationError (exit 6) when --translation-memory used without --from', async () => {
         const err = await handler
-          .translateText('Hello', defaultOptions({ translationMemory: 'my-tm' }))
-          .catch(e => e);
+          .translateText(
+            'Hello',
+            defaultOptions({ translationMemory: 'my-tm' })
+          )
+          .catch((e) => e);
         expect(err).toBeInstanceOf(ValidationError);
         expect((err as ValidationError).exitCode).toBe(6);
-        expect((err as Error).message).toContain('--from is required when using --translation-memory');
+        expect((err as Error).message).toContain(
+          '--from is required when using --translation-memory'
+        );
       });
 
       it('throws ValidationError (exit 6) when combined with latency_optimized', async () => {
         const err = await handler
-          .translateText('Hello', defaultOptions({
-            from: 'en', translationMemory: 'my-tm', modelType: 'latency_optimized',
-          }))
-          .catch(e => e);
+          .translateText(
+            'Hello',
+            defaultOptions({
+              from: 'en',
+              translationMemory: 'my-tm',
+              modelType: 'latency_optimized',
+            })
+          )
+          .catch((e) => e);
         expect(err).toBeInstanceOf(ValidationError);
         expect((err as ValidationError).exitCode).toBe(6);
-        expect((err as Error).message).toContain('requires quality_optimized model type');
+        expect((err as Error).message).toContain(
+          'requires quality_optimized model type'
+        );
       });
 
       it('resolves TM name via listTranslationMemories and passes resolved UUID to translate()', async () => {
         mocks.translationService.listTranslationMemories.mockResolvedValue([
-          { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+          {
+            translation_memory_id: TM_UUID,
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+          },
         ]);
 
-        await handler.translateText('Hello', defaultOptions({
-          from: 'en', translationMemory: 'my-tm',
-        }));
+        await handler.translateText(
+          'Hello',
+          defaultOptions({
+            from: 'en',
+            translationMemory: 'my-tm',
+          })
+        );
 
-        expect(mocks.translationService.listTranslationMemories).toHaveBeenCalledTimes(1);
+        expect(
+          mocks.translationService.listTranslationMemories
+        ).toHaveBeenCalledTimes(1);
         expect(mocks.translationService.translate).toHaveBeenCalledWith(
           'Hello',
           expect.objectContaining({
@@ -303,12 +442,22 @@ describe('TextTranslationHandler', () => {
 
       it('passes --tm-threshold through as translationMemoryThreshold', async () => {
         mocks.translationService.listTranslationMemories.mockResolvedValue([
-          { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+          {
+            translation_memory_id: TM_UUID,
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+          },
         ]);
 
-        await handler.translateText('Hello', defaultOptions({
-          from: 'en', translationMemory: 'my-tm', tmThreshold: 85,
-        }));
+        await handler.translateText(
+          'Hello',
+          defaultOptions({
+            from: 'en',
+            translationMemory: 'my-tm',
+            tmThreshold: 85,
+          })
+        );
 
         expect(mocks.translationService.translate).toHaveBeenCalledWith(
           'Hello',
@@ -318,11 +467,17 @@ describe('TextTranslationHandler', () => {
       });
 
       it('UUID fast-path: does NOT call listTranslationMemories when a UUID is passed', async () => {
-        await handler.translateText('Hello', defaultOptions({
-          from: 'en', translationMemory: TM_UUID,
-        }));
+        await handler.translateText(
+          'Hello',
+          defaultOptions({
+            from: 'en',
+            translationMemory: TM_UUID,
+          })
+        );
 
-        expect(mocks.translationService.listTranslationMemories).not.toHaveBeenCalled();
+        expect(
+          mocks.translationService.listTranslationMemories
+        ).not.toHaveBeenCalled();
         expect(mocks.translationService.translate).toHaveBeenCalledWith(
           'Hello',
           expect.objectContaining({ translationMemoryId: TM_UUID }),
@@ -332,12 +487,21 @@ describe('TextTranslationHandler', () => {
 
       it('forces modelType=quality_optimized when --translation-memory set and no --model-type given', async () => {
         mocks.translationService.listTranslationMemories.mockResolvedValue([
-          { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+          {
+            translation_memory_id: TM_UUID,
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+          },
         ]);
 
-        await handler.translateText('Hello', defaultOptions({
-          from: 'en', translationMemory: 'my-tm',
-        }));
+        await handler.translateText(
+          'Hello',
+          defaultOptions({
+            from: 'en',
+            translationMemory: 'my-tm',
+          })
+        );
 
         expect(mocks.translationService.translate).toHaveBeenCalledWith(
           'Hello',
@@ -349,7 +513,12 @@ describe('TextTranslationHandler', () => {
       describe('multi-target', () => {
         it('lists translation memories exactly once regardless of target count', async () => {
           mocks.translationService.listTranslationMemories.mockResolvedValue([
-            { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+            {
+              translation_memory_id: TM_UUID,
+              name: 'my-tm',
+              source_language: 'en',
+              target_languages: ['de'],
+            },
           ]);
           mocks.translationService.translateToMultiple.mockResolvedValue([
             { targetLang: 'de', text: 'Hallo' },
@@ -357,12 +526,21 @@ describe('TextTranslationHandler', () => {
             { targetLang: 'de', text: 'Hallo' },
           ]);
 
-          await handler.translateText('Hello', defaultOptions({
-            from: 'en', to: 'de,de,de', translationMemory: 'my-tm',
-          }));
+          await handler.translateText(
+            'Hello',
+            defaultOptions({
+              from: 'en',
+              to: 'de,de,de',
+              translationMemory: 'my-tm',
+            })
+          );
 
-          expect(mocks.translationService.listTranslationMemories).toHaveBeenCalledTimes(1);
-          expect(mocks.translationService.translateToMultiple).toHaveBeenCalledWith(
+          expect(
+            mocks.translationService.listTranslationMemories
+          ).toHaveBeenCalledTimes(1);
+          expect(
+            mocks.translationService.translateToMultiple
+          ).toHaveBeenCalledWith(
             'Hello',
             ['de', 'de', 'de'],
             expect.objectContaining({
@@ -375,35 +553,60 @@ describe('TextTranslationHandler', () => {
         it('does NOT warn about --translation-memory or --tm-threshold as ignored options', async () => {
           const { Logger } = jest.requireMock('../../src/utils/logger');
           mocks.translationService.listTranslationMemories.mockResolvedValue([
-            { translation_memory_id: TM_UUID, name: 'my-tm', source_language: 'en', target_languages: ['de'] },
+            {
+              translation_memory_id: TM_UUID,
+              name: 'my-tm',
+              source_language: 'en',
+              target_languages: ['de'],
+            },
           ]);
           mocks.translationService.translateToMultiple.mockResolvedValue([
             { targetLang: 'de', text: 'Hallo' },
           ]);
 
-          await handler.translateText('Hello', defaultOptions({
-            from: 'en', to: 'de,de', translationMemory: 'my-tm', tmThreshold: 80,
-          }));
+          await handler.translateText(
+            'Hello',
+            defaultOptions({
+              from: 'en',
+              to: 'de,de',
+              translationMemory: 'my-tm',
+              tmThreshold: 80,
+            })
+          );
 
-          const warnCalls = (Logger.warn as jest.Mock).mock.calls.map(c => c[0] as string);
-          expect(warnCalls.some(m => m.includes('--translation-memory'))).toBe(false);
-          expect(warnCalls.some(m => m.includes('--tm-threshold'))).toBe(false);
+          const warnCalls = (Logger.warn as jest.Mock).mock.calls.map(
+            (c) => c[0] as string
+          );
+          expect(
+            warnCalls.some((m) => m.includes('--translation-memory'))
+          ).toBe(false);
+          expect(warnCalls.some((m) => m.includes('--tm-threshold'))).toBe(
+            false
+          );
         });
 
         it('throws ValidationError when --translation-memory used without --from in multi-target', async () => {
           const err = await handler
-            .translateText('Hello', defaultOptions({ to: 'de,fr', translationMemory: 'my-tm' }))
-            .catch(e => e);
+            .translateText(
+              'Hello',
+              defaultOptions({ to: 'de,fr', translationMemory: 'my-tm' })
+            )
+            .catch((e) => e);
           expect(err).toBeInstanceOf(ValidationError);
           expect((err as ValidationError).exitCode).toBe(6);
-          expect((err as Error).message).toContain('--from is required when using --translation-memory');
+          expect((err as Error).message).toContain(
+            '--from is required when using --translation-memory'
+          );
         });
       });
     });
 
     describe('format output', () => {
       it('should return JSON string for format=json', async () => {
-        const result = await handler.translateText('Hello', defaultOptions({ format: 'json' }));
+        const result = await handler.translateText(
+          'Hello',
+          defaultOptions({ format: 'json' })
+        );
         const parsed = JSON.parse(result);
         expect(parsed).toHaveProperty('text', 'translated');
       });
@@ -415,7 +618,10 @@ describe('TextTranslationHandler', () => {
           cached: false,
         });
 
-        const result = await handler.translateText('Hello', defaultOptions({ format: 'json' }));
+        const result = await handler.translateText(
+          'Hello',
+          defaultOptions({ format: 'json' })
+        );
 
         expect(JSON.parse(result).cached).toBe(false);
       });
@@ -427,13 +633,19 @@ describe('TextTranslationHandler', () => {
           cached: true,
         });
 
-        const result = await handler.translateText('Hello', defaultOptions({ format: 'json' }));
+        const result = await handler.translateText(
+          'Hello',
+          defaultOptions({ format: 'json' })
+        );
 
         expect(JSON.parse(result).cached).toBe(true);
       });
 
       it('should default cached to false when the service omits the flag', async () => {
-        const result = await handler.translateText('Hello', defaultOptions({ format: 'json' }));
+        const result = await handler.translateText(
+          'Hello',
+          defaultOptions({ format: 'json' })
+        );
 
         expect(JSON.parse(result).cached).toBe(false);
       });
@@ -451,7 +663,10 @@ describe('TextTranslationHandler', () => {
             { targetLang: 'fr', text: 'Bonjour' },
           ]);
 
-          const result = await handler.translateText('Hello', defaultOptions({ to: 'de,fr', format: 'table' }));
+          const result = await handler.translateText(
+            'Hello',
+            defaultOptions({ to: 'de,fr', format: 'table' })
+          );
           expect(result).toContain('de');
           expect(result).toContain('fr');
         } finally {
@@ -476,7 +691,10 @@ describe('TextTranslationHandler', () => {
             { targetLang: 'fr', text: 'Bonjour' },
           ]);
 
-          const result = await handler.translateText('Hello', defaultOptions({ to: 'de,fr', format: 'table' }));
+          const result = await handler.translateText(
+            'Hello',
+            defaultOptions({ to: 'de,fr', format: 'table' })
+          );
           expect(result).toBe('[de] Hallo\n[fr] Bonjour');
         } finally {
           Object.defineProperty(process.stdout, 'isTTY', {
@@ -516,16 +734,24 @@ describe('TextTranslationHandler', () => {
         { targetLang: 'de', text: 'Hallo' },
       ]);
 
-      await handler.translateText('Hello', defaultOptions({
-        to: 'de,fr',
-        splitSentences: 'on',
-      }));
+      await handler.translateText(
+        'Hello',
+        defaultOptions({
+          to: 'de,fr',
+          splitSentences: 'on',
+        })
+      );
 
-      expect(Logger.warn).toHaveBeenCalledWith(expect.stringContaining('multi-target'));
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('multi-target')
+      );
     });
 
     it('should lowercase target and source language codes', async () => {
-      await handler.translateText('Hello', defaultOptions({ to: 'DE', from: 'EN' }));
+      await handler.translateText(
+        'Hello',
+        defaultOptions({ to: 'DE', from: 'EN' })
+      );
       expect(mocks.translationService.translate).toHaveBeenCalledWith(
         'Hello',
         expect.objectContaining({ targetLang: 'de', sourceLang: 'en' }),
diff --git a/tests/unit/tm-command.test.ts b/tests/unit/tm-command.test.ts
index 4207e3c6..e36a1f63 100644
--- a/tests/unit/tm-command.test.ts
+++ b/tests/unit/tm-command.test.ts
@@ -45,8 +45,18 @@ describe('TmCommand', () => {
 
     it('renders name and language pair per TM', () => {
       const tms: TranslationMemory[] = [
-        { translation_memory_id: 'a', name: 'brand-terms', source_language: 'en', target_languages: ['de', 'fr'] },
-        { translation_memory_id: 'b', name: 'legal-phrases', source_language: 'en', target_languages: ['fr'] },
+        {
+          translation_memory_id: 'a',
+          name: 'brand-terms',
+          source_language: 'en',
+          target_languages: ['de', 'fr'],
+        },
+        {
+          translation_memory_id: 'b',
+          name: 'legal-phrases',
+          source_language: 'en',
+          target_languages: ['fr'],
+        },
       ];
       const out = tmCommand.formatList(tms);
       expect(out).toContain('brand-terms');
@@ -57,7 +67,12 @@ describe('TmCommand', () => {
 
     it('strips ASCII control chars from the name column so a malicious TM cannot corrupt the terminal', () => {
       const tms: TranslationMemory[] = [
-        { translation_memory_id: 'a', name: 'evil\x1b[2Jname\x07', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: 'a',
+          name: 'evil\x1b[2Jname\x07',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ];
       const out = tmCommand.formatList(tms);
       expect(out).not.toContain('\x1b[');
@@ -68,7 +83,12 @@ describe('TmCommand', () => {
 
     it('strips zero-width codepoints from the name column', () => {
       const tms: TranslationMemory[] = [
-        { translation_memory_id: 'a', name: 'prod\u200Btm', source_language: 'en', target_languages: ['de'] },
+        {
+          translation_memory_id: 'a',
+          name: 'prod\u200Btm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
       ];
       const out = tmCommand.formatList(tms);
       expect(out).not.toContain('\u200B');
diff --git a/tests/unit/translate-command.test.ts b/tests/unit/translate-command.test.ts
index b37d37d6..0254d651 100644
--- a/tests/unit/translate-command.test.ts
+++ b/tests/unit/translate-command.test.ts
@@ -2,8 +2,6 @@
  * Tests for Translate Command
  */
 
- 
-
 import { TranslateCommand } from '../../src/cli/commands/translate';
 import { TranslationService } from '../../src/services/translation';
 import { DocumentTranslationService } from '../../src/services/document-translation';
@@ -17,15 +15,24 @@ import {
   createMockGlossaryService,
   createMockConfigService,
 } from '../helpers/mock-factories';
-import { buildTranslationOptions, getFileSize } from '../../src/cli/commands/translate/translate-utils';
+import {
+  buildTranslationOptions,
+  getFileSize,
+} from '../../src/cli/commands/translate/translate-utils';
 import { atomicWriteFileSync } from '../../src/utils/atomic-write';
 
 // Mock ESM dependencies
 jest.mock('ora', () => {
   const mockSpinner = {
-    start: jest.fn(function(this: any) { return this; }),
-    succeed: jest.fn(function(this: any) { return this; }),
-    fail: jest.fn(function(this: any) { return this; }),
+    start: jest.fn(function (this: any) {
+      return this;
+    }),
+    succeed: jest.fn(function (this: any) {
+      return this;
+    }),
+    fail: jest.fn(function (this: any) {
+      return this;
+    }),
     text: '',
   };
   return jest.fn(() => mockSpinner);
@@ -65,7 +72,9 @@ describe('TranslateCommand', () => {
 
     mockConfigService = createMockConfigService({
       getValue: jest.fn((key: string) => {
-        if (key === 'auth.apiKey') {return 'mock-api-key';}
+        if (key === 'auth.apiKey') {
+          return 'mock-api-key';
+        }
         return undefined;
       }),
     });
@@ -161,7 +170,9 @@ describe('TranslateCommand', () => {
 
     it('should throw error when API key is not set', async () => {
       // Override mock to return no API key for this specific test
-      (mockConfigService.getValue as jest.Mock).mockImplementation(() => undefined);
+      (mockConfigService.getValue as jest.Mock).mockImplementation(
+        () => undefined
+      );
       const originalEnv = process.env['DEEPL_API_KEY'];
       delete process.env['DEEPL_API_KEY'];
 
@@ -170,11 +181,15 @@ describe('TranslateCommand', () => {
       ).rejects.toThrow('API key not set');
 
       // Restore environment
-      if (originalEnv) {process.env['DEEPL_API_KEY'] = originalEnv;}
+      if (originalEnv) {
+        process.env['DEEPL_API_KEY'] = originalEnv;
+      }
     });
 
     it('should support multiple target languages', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'es', text: 'Hola' },
         { targetLang: 'fr', text: 'Bonjour' },
         { targetLang: 'de', text: 'Hallo' },
@@ -513,7 +528,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should pass context for multiple target languages', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'es', text: 'Hola' },
         { targetLang: 'fr', text: 'Bonjour' },
       ]);
@@ -537,7 +554,8 @@ describe('TranslateCommand', () => {
         text: 'El banco está cerrado',
       });
 
-      const longContext = 'This document is about financial services. The previous paragraph discussed banking hours and the next paragraph will cover online banking options.';
+      const longContext =
+        'This document is about financial services. The previous paragraph discussed banking hours and the next paragraph will cover online banking options.';
 
       await translateCommand.translateText('The bank is closed', {
         to: 'es',
@@ -699,7 +717,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should pass formality to translateToMultiple', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'es', text: 'Hola' },
         { targetLang: 'de', text: 'Hallo' },
       ]);
@@ -719,7 +739,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should pass sourceLang to translateToMultiple', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'es', text: 'Hola' },
         { targetLang: 'fr', text: 'Bonjour' },
       ]);
@@ -809,7 +831,10 @@ describe('TranslateCommand', () => {
     });
 
     it('should reject more than 10 custom instructions', async () => {
-      const instructions = Array.from({ length: 11 }, (_, i) => `Instruction ${i + 1}`);
+      const instructions = Array.from(
+        { length: 11 },
+        (_, i) => `Instruction ${i + 1}`
+      );
 
       await expect(
         translateCommand.translateText('Hello', {
@@ -837,11 +862,15 @@ describe('TranslateCommand', () => {
           customInstruction: ['Use informal tone'],
           modelType: 'latency_optimized',
         })
-      ).rejects.toThrow('Custom instructions cannot be used with latency_optimized model type');
+      ).rejects.toThrow(
+        'Custom instructions cannot be used with latency_optimized model type'
+      );
     });
 
     it('should pass custom instructions to translateToMultiple', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'es', text: 'Hola' },
         { targetLang: 'fr', text: 'Bonjour' },
       ]);
@@ -865,7 +894,10 @@ describe('TranslateCommand', () => {
         text: 'Hola',
       });
 
-      const instructions = Array.from({ length: 10 }, (_, i) => `Instruction ${i + 1}`);
+      const instructions = Array.from(
+        { length: 10 },
+        (_, i) => `Instruction ${i + 1}`
+      );
 
       await translateCommand.translateText('Hello', {
         to: 'es',
@@ -907,12 +939,18 @@ describe('TranslateCommand', () => {
     it('should detect and route to translateDirectory() for directory paths', async () => {
       // Mock fs to indicate a directory; routing must consult lstatSync so symlinks are not followed.
       const fs = jest.requireActual('fs');
-      jest.spyOn(fs, 'lstatSync').mockReturnValue({ isSymbolicLink: () => false, isDirectory: () => true } as any);
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({
+        isSymbolicLink: () => false,
+        isDirectory: () => true,
+      } as any);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
-      jest.spyOn(fs, 'statSync').mockReturnValue({ isDirectory: () => true } as any);
+      jest
+        .spyOn(fs, 'statSync')
+        .mockReturnValue({ isDirectory: () => true } as any);
 
       // Create a spy on translateDirectory
-      const spy = jest.spyOn((translateCommand as any).directoryHandler, 'translateDirectory')
+      const spy = jest
+        .spyOn((translateCommand as any).directoryHandler, 'translateDirectory')
         .mockResolvedValue('Directory translation result');
 
       const result = await translateCommand.translate('/path/to/dir', {
@@ -921,7 +959,10 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('Directory translation result');
-      expect(spy).toHaveBeenCalledWith('/path/to/dir', { to: 'es', output: '/out' });
+      expect(spy).toHaveBeenCalledWith('/path/to/dir', {
+        to: 'es',
+        output: '/out',
+      });
 
       spy.mockRestore();
     });
@@ -930,12 +971,16 @@ describe('TranslateCommand', () => {
       // Mock fs to indicate a file; routing must consult lstatSync so symlinks are not followed.
       const fs = jest.requireActual('fs');
       const mockStats = { isDirectory: () => false, isFile: () => true };
-      jest.spyOn(fs, 'lstatSync').mockReturnValue({ isSymbolicLink: () => false, isFile: () => true } as any);
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({
+        isSymbolicLink: () => false,
+        isFile: () => true,
+      } as any);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
       jest.spyOn(fs, 'statSync').mockReturnValue(mockStats as any);
 
       // Create a spy on translateFile
-      const spy = jest.spyOn((translateCommand as any).fileHandler, 'translateFile')
+      const spy = jest
+        .spyOn((translateCommand as any).fileHandler, 'translateFile')
         .mockResolvedValue('File translation result');
 
       const result = await translateCommand.translate('/path/to/file.txt', {
@@ -944,7 +989,11 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('File translation result');
-      expect(spy).toHaveBeenCalledWith('/path/to/file.txt', { to: 'es', output: '/out.txt' }, mockStats);
+      expect(spy).toHaveBeenCalledWith(
+        '/path/to/file.txt',
+        { to: 'es', output: '/out.txt' },
+        mockStats
+      );
 
       spy.mockRestore();
     });
@@ -958,7 +1007,9 @@ describe('TranslateCommand', () => {
         text: 'Hola mundo',
       });
 
-      const result = await translateCommand.translate('Hello world', { to: 'es' });
+      const result = await translateCommand.translate('Hello world', {
+        to: 'es',
+      });
 
       expect(result).toBe('Hola mundo');
       expect(mockTranslationService.translate).toHaveBeenCalled();
@@ -968,7 +1019,10 @@ describe('TranslateCommand', () => {
   describe('translateFile()', () => {
     it('should throw error if output is not specified', async () => {
       await expect(
-        (translateCommand as any).fileHandler.translateFile('/path/to/file.txt', { to: 'es' })
+        (translateCommand as any).fileHandler.translateFile(
+          '/path/to/file.txt',
+          { to: 'es' }
+        )
       ).rejects.toThrow('Output file path is required');
     });
 
@@ -977,21 +1031,26 @@ describe('TranslateCommand', () => {
       const fs = jest.requireActual('fs');
       jest.spyOn(fs, 'statSync').mockReturnValue({
         size: 1024, // 1KB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
       jest.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Hola mundo',
       });
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/input.txt', {
-        to: 'es',
-        output: '/output.txt',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/input.txt',
+        {
+          to: 'es',
+          output: '/output.txt',
+        }
+      );
 
       expect(result).toContain('Translated /input.txt');
       expect(result).toContain('/output.txt');
@@ -1003,7 +1062,7 @@ describe('TranslateCommand', () => {
       const fs = jest.requireActual('fs');
       jest.spyOn(fs, 'statSync').mockReturnValue({
         size: 1024, // 1KB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
 
@@ -1016,10 +1075,13 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.fileTranslationService = mockFileService;
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/input.txt', {
-        to: 'es,fr,de',
-        output: '/output',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/input.txt',
+        {
+          to: 'es,fr,de',
+          output: '/output',
+        }
+      );
 
       expect(result).toContain('Translated /input.txt to 3 languages');
       expect(result).toContain('[es]');
@@ -1030,13 +1092,17 @@ describe('TranslateCommand', () => {
 
     it('should pass source language when specified', async () => {
       const fs = jest.requireActual('fs');
-      jest.spyOn(fs, 'statSync').mockReturnValue({ size: 1024, isDirectory: () => false } as any);
+      jest
+        .spyOn(fs, 'statSync')
+        .mockReturnValue({ size: 1024, isDirectory: () => false } as any);
       jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
       jest.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
       (safeReadFileSync as jest.Mock).mockReturnValue('Hello world');
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Hola mundo',
       });
@@ -1056,13 +1122,17 @@ describe('TranslateCommand', () => {
 
     it('should pass formality when specified', async () => {
       const fs = jest.requireActual('fs');
-      jest.spyOn(fs, 'statSync').mockReturnValue({ size: 1024, isDirectory: () => false } as any);
+      jest
+        .spyOn(fs, 'statSync')
+        .mockReturnValue({ size: 1024, isDirectory: () => false } as any);
       jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
       jest.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
       (safeReadFileSync as jest.Mock).mockReturnValue('Hello world');
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Hola mundo',
       });
@@ -1082,13 +1152,17 @@ describe('TranslateCommand', () => {
 
     it('should pass preserveCode option', async () => {
       const fs = jest.requireActual('fs');
-      jest.spyOn(fs, 'statSync').mockReturnValue({ size: 1024, isDirectory: () => false } as any);
+      jest
+        .spyOn(fs, 'statSync')
+        .mockReturnValue({ size: 1024, isDirectory: () => false } as any);
       jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
       jest.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
       (safeReadFileSync as jest.Mock).mockReturnValue('Hello world');
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Hola mundo',
       });
@@ -1108,7 +1182,9 @@ describe('TranslateCommand', () => {
 
     it('should pass source language to multi-file translation', async () => {
       const fs = jest.requireActual('fs');
-      jest.spyOn(fs, 'statSync').mockReturnValue({ size: 1024, isDirectory: () => false } as any);
+      jest
+        .spyOn(fs, 'statSync')
+        .mockReturnValue({ size: 1024, isDirectory: () => false } as any);
       jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
 
       const mockFileService = {
@@ -1134,7 +1210,9 @@ describe('TranslateCommand', () => {
 
     it('should pass formality to multi-file translation', async () => {
       const fs = jest.requireActual('fs');
-      jest.spyOn(fs, 'statSync').mockReturnValue({ size: 1024, isDirectory: () => false } as any);
+      jest
+        .spyOn(fs, 'statSync')
+        .mockReturnValue({ size: 1024, isDirectory: () => false } as any);
       jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
 
       const mockFileService = {
@@ -1162,7 +1240,10 @@ describe('TranslateCommand', () => {
   describe('translateDirectory()', () => {
     it('should throw error if output directory is not specified', async () => {
       await expect(
-        (translateCommand as any).directoryHandler.translateDirectory('/path/to/dir', { to: 'es' })
+        (translateCommand as any).directoryHandler.translateDirectory(
+          '/path/to/dir',
+          { to: 'es' }
+        )
       ).rejects.toThrow('Output directory is required');
     });
 
@@ -1179,7 +1260,9 @@ describe('TranslateCommand', () => {
 
   describe('glossary integration', () => {
     it('should translate text with glossary by name', async () => {
-      (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValueOnce('glossary-123');
+      (
+        mockGlossaryService.resolveGlossaryId as jest.Mock
+      ).mockResolvedValueOnce('glossary-123');
 
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Hallo Welt',
@@ -1193,7 +1276,10 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('Hallo Welt');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', { from: 'en', targets: ['de'] });
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        { from: 'en', targets: ['de'] }
+      );
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello world',
         { targetLang: 'de', sourceLang: 'en', glossaryId: 'glossary-123' },
@@ -1202,7 +1288,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should translate text with glossary by ID', async () => {
-      (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValueOnce('01234567-89ab-cdef-0123-456789abcdef');
+      (
+        mockGlossaryService.resolveGlossaryId as jest.Mock
+      ).mockResolvedValueOnce('01234567-89ab-cdef-0123-456789abcdef');
 
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Bonjour le monde',
@@ -1216,10 +1304,17 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('Bonjour le monde');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('01234567-89ab-cdef-0123-456789abcdef', { from: 'en', targets: ['fr'] });
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+        '01234567-89ab-cdef-0123-456789abcdef',
+        { from: 'en', targets: ['fr'] }
+      );
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello world',
-        { targetLang: 'fr', sourceLang: 'en', glossaryId: '01234567-89ab-cdef-0123-456789abcdef' },
+        {
+          targetLang: 'fr',
+          sourceLang: 'en',
+          glossaryId: '01234567-89ab-cdef-0123-456789abcdef',
+        },
         { preserveCode: undefined, skipCache: true }
       );
     });
@@ -1230,7 +1325,9 @@ describe('TranslateCommand', () => {
           to: 'de',
           glossary: ['my-glossary'],
         })
-      ).rejects.toThrow('Source language (--from) is required when using a glossary');
+      ).rejects.toThrow(
+        'Source language (--from) is required when using a glossary'
+      );
     });
 
     it('should require --from when using --glossary with multi-target', async () => {
@@ -1239,13 +1336,15 @@ describe('TranslateCommand', () => {
           to: 'de,fr',
           glossary: ['my-glossary'],
         })
-      ).rejects.toThrow('Source language (--from) is required when using a glossary');
+      ).rejects.toThrow(
+        'Source language (--from) is required when using a glossary'
+      );
     });
 
     it('should throw error when glossary not found by name', async () => {
-      (mockGlossaryService.resolveGlossaryId as jest.Mock).mockRejectedValueOnce(
-        new Error('Glossary "non-existent" not found')
-      );
+      (
+        mockGlossaryService.resolveGlossaryId as jest.Mock
+      ).mockRejectedValueOnce(new Error('Glossary "non-existent" not found'));
 
       await expect(
         translateCommand.translateText('Hello world', {
@@ -1255,13 +1354,20 @@ describe('TranslateCommand', () => {
         })
       ).rejects.toThrow('Glossary "non-existent" not found');
 
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('non-existent', { from: 'en', targets: ['de'] });
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+        'non-existent',
+        { from: 'en', targets: ['de'] }
+      );
     });
 
     it('should translate to multiple languages with glossary', async () => {
-      (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValueOnce('glossary-789');
+      (
+        mockGlossaryService.resolveGlossaryId as jest.Mock
+      ).mockResolvedValueOnce('glossary-789');
 
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'de', text: 'Hallo' },
         { targetLang: 'fr', text: 'Bonjour' },
       ]);
@@ -1273,7 +1379,10 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('[de] Hallo\n[fr] Bonjour');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('tech-terms', { from: 'en', targets: ['de', 'fr'] });
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+        'tech-terms',
+        { from: 'en', targets: ['de', 'fr'] }
+      );
       expect(mockTranslationService.translateToMultiple).toHaveBeenCalledWith(
         'Hello',
         ['de', 'fr'],
@@ -1282,7 +1391,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should combine glossary with other options (formality, context)', async () => {
-      (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValueOnce('glossary-abc');
+      (
+        mockGlossaryService.resolveGlossaryId as jest.Mock
+      ).mockResolvedValueOnce('glossary-abc');
 
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Sehr geehrte Damen und Herren',
@@ -1298,7 +1409,10 @@ describe('TranslateCommand', () => {
       });
 
       expect(result).toBe('Sehr geehrte Damen und Herren');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('business-glossary', { from: 'en', targets: ['de'] });
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+        'business-glossary',
+        { from: 'en', targets: ['de'] }
+      );
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Dear Sir or Madam',
         {
@@ -1337,45 +1451,61 @@ describe('TranslateCommand', () => {
 
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 50 * 1024, // 50 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       jest.spyOn(mockFs, 'readFileSync').mockReturnValue(smallContent);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Translated content',
       });
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/path/to/small.txt', {
-        to: 'es',
-        output: '/out.txt',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/small.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        }
+      );
 
       // Should use text translation API (cached)
       expect(mockTranslationService.translate).toHaveBeenCalled();
-      expect(mockDocumentTranslationService.translateDocument).not.toHaveBeenCalled();
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).not.toHaveBeenCalled();
       expect(result).toContain('Translated /path/to/small.txt');
     });
 
     it('should fall back to document API for large .txt files (over 100 KiB)', async () => {
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 150 * 1024, // 150 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValueOnce({
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValueOnce({
         success: true,
         outputPath: '/out.txt',
       });
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/path/to/large.txt', {
-        to: 'es',
-        output: '/out.txt',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/large.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        }
+      );
 
       // Should use document API (not cached)
-      expect(mockDocumentTranslationService.translateDocument).toHaveBeenCalled();
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).toHaveBeenCalled();
       expect(mockTranslationService.translate).not.toHaveBeenCalled();
       expect(result).toContain('File exceeds');
       expect(result).toContain('using document API');
@@ -1386,19 +1516,24 @@ describe('TranslateCommand', () => {
 
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 10 * 1024, // 10 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       jest.spyOn(mockFs, 'readFileSync').mockReturnValue(smallContent);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(false);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Translated markdown',
       });
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/path/to/doc.md', {
-        to: 'es',
-        output: '/out.md',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/doc.md',
+        {
+          to: 'es',
+          output: '/out.md',
+        }
+      );
 
       // Should use text translation API (cached)
       expect(mockTranslationService.translate).toHaveBeenCalled();
@@ -1410,23 +1545,30 @@ describe('TranslateCommand', () => {
 
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 5 * 1024, // 5 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       jest.spyOn(mockFs, 'readFileSync').mockReturnValue(smallContent);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: '<html><body>Hola</body></html>',
       });
 
-      await (translateCommand as any).fileHandler.translateFile('/path/to/page.html', {
-        to: 'es',
-        output: '/out.html',
-      });
+      await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/page.html',
+        {
+          to: 'es',
+          output: '/out.html',
+        }
+      );
 
       // Should use text translation API (cached)
       expect(mockTranslationService.translate).toHaveBeenCalled();
-      expect(mockDocumentTranslationService.translateDocument).not.toHaveBeenCalled();
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).not.toHaveBeenCalled();
     });
 
     it('should use cached text API for .srt subtitle files', async () => {
@@ -1434,87 +1576,118 @@ describe('TranslateCommand', () => {
 
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 5 * 1024, // 5 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       jest.spyOn(mockFs, 'readFileSync').mockReturnValue(srtContent);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Translated subtitles',
       });
 
-      await (translateCommand as any).fileHandler.translateFile('/path/to/movie.srt', {
-        to: 'es',
-        output: '/out.srt',
-      });
+      await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/movie.srt',
+        {
+          to: 'es',
+          output: '/out.srt',
+        }
+      );
 
       // Should use text translation API (cached)
       expect(mockTranslationService.translate).toHaveBeenCalled();
-      expect(mockDocumentTranslationService.translateDocument).not.toHaveBeenCalled();
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).not.toHaveBeenCalled();
     });
 
     it('should use cached text API for .xlf translation files', async () => {
-      const xlfContent = '<?xml version="1.0"?><xliff><file><trans-unit><source>Hello</source></trans-unit></file></xliff>';
+      const xlfContent =
+        '<?xml version="1.0"?><xliff><file><trans-unit><source>Hello</source></trans-unit></file></xliff>';
 
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 10 * 1024, // 10 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       jest.spyOn(mockFs, 'readFileSync').mockReturnValue(xlfContent);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Translated XML',
       });
 
-      await (translateCommand as any).fileHandler.translateFile('/path/to/strings.xlf', {
-        to: 'es',
-        output: '/out.xlf',
-      });
+      await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/strings.xlf',
+        {
+          to: 'es',
+          output: '/out.xlf',
+        }
+      );
 
       // Should use text translation API (cached)
       expect(mockTranslationService.translate).toHaveBeenCalled();
-      expect(mockDocumentTranslationService.translateDocument).not.toHaveBeenCalled();
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).not.toHaveBeenCalled();
     });
 
     it('should always use document API for binary files (.pdf, .docx)', async () => {
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 10 * 1024, // 10 KiB (small, but still binary)
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValueOnce({
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValueOnce({
         success: true,
         outputPath: '/out.pdf',
       });
 
-      await (translateCommand as any).fileHandler.translateFile('/path/to/document.pdf', {
-        to: 'es',
-        output: '/out.pdf',
-      });
+      await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/document.pdf',
+        {
+          to: 'es',
+          output: '/out.pdf',
+        }
+      );
 
       // Should use document API (even though small)
-      expect(mockDocumentTranslationService.translateDocument).toHaveBeenCalled();
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).toHaveBeenCalled();
       expect(mockTranslationService.translate).not.toHaveBeenCalled();
     });
 
     it('should show warning when falling back to document API', async () => {
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 150 * 1024, // 150 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValueOnce({
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValueOnce({
         success: true,
         outputPath: '/out.txt',
       });
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/path/to/large.txt', {
-        to: 'es',
-        output: '/out.txt',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/large.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        }
+      );
 
       // Should include warning message
       expect(result).toContain('File exceeds');
@@ -1528,24 +1701,33 @@ describe('TranslateCommand', () => {
 
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 1 * 1024, // 1 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       jest.spyOn(mockFs, 'readFileSync').mockReturnValue(smallContent);
       jest.spyOn(mockFs, 'writeFileSync').mockImplementation(() => undefined);
       jest.spyOn(mockFs, 'mkdirSync').mockImplementation(() => undefined);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: translatedContent,
       });
 
-      await (translateCommand as any).fileHandler.translateFile('/path/to/small.txt', {
-        to: 'es',
-        output: '/out.txt',
-      });
+      await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/small.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        }
+      );
 
       // Should write translated content to file via atomic write
-      expect(atomicWriteFileSync).toHaveBeenCalledWith('/out.txt', translatedContent, 'utf-8');
+      expect(atomicWriteFileSync).toHaveBeenCalledWith(
+        '/out.txt',
+        translatedContent,
+        'utf-8'
+      );
     });
 
     it('should handle UTF-8 encoding correctly', async () => {
@@ -1553,22 +1735,30 @@ describe('TranslateCommand', () => {
 
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 5 * 1024, // 5 KiB
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       (safeReadFileSync as jest.Mock).mockReturnValue(unicodeContent);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Hola 世界 🌍',
       });
 
-      await (translateCommand as any).fileHandler.translateFile('/path/to/unicode.txt', {
-        to: 'es',
-        output: '/out.txt',
-      });
+      await (translateCommand as any).fileHandler.translateFile(
+        '/path/to/unicode.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        }
+      );
 
       // Should read with UTF-8 encoding via safeReadFileSync
-      expect(safeReadFileSync).toHaveBeenCalledWith('/path/to/unicode.txt', 'utf-8');
+      expect(safeReadFileSync).toHaveBeenCalledWith(
+        '/path/to/unicode.txt',
+        'utf-8'
+      );
     });
   });
 
@@ -1579,11 +1769,13 @@ describe('TranslateCommand', () => {
 
       // Access the private isFilePath method via translate()
       // Windows path should be detected as file path
-      const spy = jest.spyOn((translateCommand as any).fileHandler, 'translateFile')
+      const spy = jest
+        .spyOn((translateCommand as any).fileHandler, 'translateFile')
         .mockResolvedValue('File translation result');
 
       // Mock fileTranslationService.isSupportedFile to return true for .txt
-      const mockFileService = (translateCommand as any).ctx.fileTranslationService;
+      const mockFileService = (translateCommand as any).ctx
+        .fileTranslationService;
       jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
 
       await translateCommand.translate('C:\\Users\\Documents\\file.txt', {
@@ -1591,7 +1783,11 @@ describe('TranslateCommand', () => {
         output: '/out.txt',
       });
 
-      expect(spy).toHaveBeenCalledWith('C:\\Users\\Documents\\file.txt', { to: 'es', output: '/out.txt' }, null);
+      expect(spy).toHaveBeenCalledWith(
+        'C:\\Users\\Documents\\file.txt',
+        { to: 'es', output: '/out.txt' },
+        null
+      );
       spy.mockRestore();
     });
 
@@ -1599,10 +1795,12 @@ describe('TranslateCommand', () => {
       const fs = jest.requireActual('fs');
       jest.spyOn(fs, 'existsSync').mockReturnValue(false);
 
-      const spy = jest.spyOn((translateCommand as any).fileHandler, 'translateFile')
+      const spy = jest
+        .spyOn((translateCommand as any).fileHandler, 'translateFile')
         .mockResolvedValue('File translation result');
 
-      const mockFileService = (translateCommand as any).ctx.fileTranslationService;
+      const mockFileService = (translateCommand as any).ctx
+        .fileTranslationService;
       jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
 
       await translateCommand.translate('/home/user/documents/file.txt', {
@@ -1610,7 +1808,11 @@ describe('TranslateCommand', () => {
         output: '/out.txt',
       });
 
-      expect(spy).toHaveBeenCalledWith('/home/user/documents/file.txt', { to: 'es', output: '/out.txt' }, null);
+      expect(spy).toHaveBeenCalledWith(
+        '/home/user/documents/file.txt',
+        { to: 'es', output: '/out.txt' },
+        null
+      );
       spy.mockRestore();
     });
 
@@ -1618,7 +1820,8 @@ describe('TranslateCommand', () => {
       const fs = jest.requireActual('fs');
       jest.spyOn(fs, 'existsSync').mockReturnValue(false);
 
-      const mockFileService = (translateCommand as any).ctx.fileTranslationService;
+      const mockFileService = (translateCommand as any).ctx
+        .fileTranslationService;
       jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
 
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
@@ -1642,7 +1845,8 @@ describe('TranslateCommand', () => {
       const fs = jest.requireActual('fs');
       jest.spyOn(fs, 'existsSync').mockReturnValue(false);
 
-      const mockFileService = (translateCommand as any).ctx.fileTranslationService;
+      const mockFileService = (translateCommand as any).ctx
+        .fileTranslationService;
       jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(false);
 
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
@@ -1650,9 +1854,12 @@ describe('TranslateCommand', () => {
       });
 
       // Text with / should be treated as text, not file path
-      await translateCommand.translate('Check https://example.com for details', {
-        to: 'es',
-      });
+      await translateCommand.translate(
+        'Check https://example.com for details',
+        {
+          to: 'es',
+        }
+      );
 
       // Should call translateText, NOT translateFile
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
@@ -1666,10 +1873,12 @@ describe('TranslateCommand', () => {
       const fs = jest.requireActual('fs');
       jest.spyOn(fs, 'existsSync').mockReturnValue(false);
 
-      const spy = jest.spyOn((translateCommand as any).fileHandler, 'translateFile')
+      const spy = jest
+        .spyOn((translateCommand as any).fileHandler, 'translateFile')
         .mockResolvedValue('File translation result');
 
-      const mockFileService = (translateCommand as any).ctx.fileTranslationService;
+      const mockFileService = (translateCommand as any).ctx
+        .fileTranslationService;
       jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
 
       await translateCommand.translate('folder\\subfolder\\file.txt', {
@@ -1677,7 +1886,11 @@ describe('TranslateCommand', () => {
         output: '/out.txt',
       });
 
-      expect(spy).toHaveBeenCalledWith('folder\\subfolder\\file.txt', { to: 'es', output: '/out.txt' }, null);
+      expect(spy).toHaveBeenCalledWith(
+        'folder\\subfolder\\file.txt',
+        { to: 'es', output: '/out.txt' },
+        null
+      );
       spy.mockRestore();
     });
 
@@ -1685,10 +1898,12 @@ describe('TranslateCommand', () => {
       const fs = jest.requireActual('fs');
       jest.spyOn(fs, 'existsSync').mockReturnValue(false);
 
-      const spy = jest.spyOn((translateCommand as any).fileHandler, 'translateFile')
+      const spy = jest
+        .spyOn((translateCommand as any).fileHandler, 'translateFile')
         .mockResolvedValue('File translation result');
 
-      const mockFileService = (translateCommand as any).ctx.fileTranslationService;
+      const mockFileService = (translateCommand as any).ctx
+        .fileTranslationService;
       jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
 
       await translateCommand.translate('folder/subfolder/file.txt', {
@@ -1696,15 +1911,20 @@ describe('TranslateCommand', () => {
         output: '/out.txt',
       });
 
-      expect(spy).toHaveBeenCalledWith('folder/subfolder/file.txt', { to: 'es', output: '/out.txt' }, null);
+      expect(spy).toHaveBeenCalledWith(
+        'folder/subfolder/file.txt',
+        { to: 'es', output: '/out.txt' },
+        null
+      );
       spy.mockRestore();
     });
 
-    it('should handle files with no path separator (file.txt) as text when file doesn\'t exist', async () => {
+    it("should handle files with no path separator (file.txt) as text when file doesn't exist", async () => {
       const fs = jest.requireActual('fs');
       jest.spyOn(fs, 'existsSync').mockReturnValue(false);
 
-      const mockFileService = (translateCommand as any).ctx.fileTranslationService;
+      const mockFileService = (translateCommand as any).ctx
+        .fileTranslationService;
       jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
 
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
@@ -1735,7 +1955,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should accept all valid language codes', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'es', text: 'Hola' },
         { targetLang: 'fr', text: 'Bonjour' },
         { targetLang: 'de', text: 'Hallo' },
@@ -1764,7 +1986,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should trim whitespace in language codes', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'es', text: 'Hola' },
         { targetLang: 'fr', text: 'Bonjour' },
       ]);
@@ -1782,7 +2006,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should accept mixed-case language codes by normalizing to lowercase', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'de', text: 'Hallo' },
         { targetLang: 'pt-br', text: 'Olá' },
       ]);
@@ -1822,7 +2048,9 @@ describe('TranslateCommand', () => {
 
     it('should validate language codes for file translation', async () => {
       const fs = jest.requireActual('fs');
-      jest.spyOn(fs, 'statSync').mockReturnValue({ size: 1024, isDirectory: () => false } as any);
+      jest
+        .spyOn(fs, 'statSync')
+        .mockReturnValue({ size: 1024, isDirectory: () => false } as any);
       jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
 
       await expect(
@@ -1887,15 +2115,20 @@ describe('TranslateCommand', () => {
       jest.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Hola mundo',
       });
 
-      const result = await translateCommand.translate('/path/to/regular-file.txt', {
-        to: 'es',
-        output: '/out.txt',
-      });
+      const result = await translateCommand.translate(
+        '/path/to/regular-file.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        }
+      );
 
       expect(result).toContain('Translated');
       expect(result).toContain('/out.txt');
@@ -1915,7 +2148,8 @@ describe('TranslateCommand', () => {
       } as any);
 
       // Mock translateDirectory to return success
-      const spy = jest.spyOn((translateCommand as any).directoryHandler, 'translateDirectory')
+      const spy = jest
+        .spyOn((translateCommand as any).directoryHandler, 'translateDirectory')
         .mockResolvedValue('Directory translation complete');
 
       const result = await translateCommand.translate('/path/to/regular-dir', {
@@ -1941,7 +2175,9 @@ describe('TranslateCommand', () => {
           to: 'es',
           output: '/out.txt',
         })
-      ).rejects.toThrow('Symlinks are not supported for security reasons: /path/to/symlink.txt');
+      ).rejects.toThrow(
+        'Symlinks are not supported for security reasons: /path/to/symlink.txt'
+      );
     });
   });
 
@@ -1986,7 +2222,9 @@ describe('TranslateCommand', () => {
           styleId: 'abc-123-uuid',
           modelType: 'latency_optimized',
         })
-      ).rejects.toThrow('Style ID cannot be used with latency_optimized model type');
+      ).rejects.toThrow(
+        'Style ID cannot be used with latency_optimized model type'
+      );
     });
 
     it('should pass styleId in translateToMultiple', async () => {
@@ -2230,7 +2468,9 @@ describe('TranslateCommand', () => {
       });
 
       it('should reject formality for an extended target among several', async () => {
-        (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+        (
+          mockDocumentTranslationService.isDocumentSupported as jest.Mock
+        ).mockReturnValue(false);
 
         await expect(
           fileHandler().translateFile('/doc.txt', {
@@ -2242,7 +2482,9 @@ describe('TranslateCommand', () => {
       });
 
       it('should reject formality for a format routed through fileTranslationService', async () => {
-        (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+        (
+          mockDocumentTranslationService.isDocumentSupported as jest.Mock
+        ).mockReturnValue(false);
         (translateCommand as any).ctx.fileTranslationService = {
           translateFile: jest.fn().mockResolvedValue(undefined),
           isSupportedFile: jest.fn().mockReturnValue(true),
@@ -2261,7 +2503,9 @@ describe('TranslateCommand', () => {
       it('should not reject a glossary on a path that resolves none', async () => {
         // The csv path carries no glossary to the request, so refusing the run
         // over one would refuse a command that works.
-        (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+        (
+          mockDocumentTranslationService.isDocumentSupported as jest.Mock
+        ).mockReturnValue(false);
         const mockFileService = {
           translateFile: jest.fn().mockResolvedValue(undefined),
           isSupportedFile: jest.fn().mockReturnValue(true),
@@ -2282,7 +2526,10 @@ describe('TranslateCommand', () => {
 
     describe('directory mode', () => {
       function directory(options: Record<string, unknown>) {
-        return (translateCommand as any).directoryHandler.translateDirectory('/src', options);
+        return (translateCommand as any).directoryHandler.translateDirectory(
+          '/src',
+          options
+        );
       }
 
       beforeEach(() => {
@@ -2292,9 +2539,12 @@ describe('TranslateCommand', () => {
             failed: [],
             skipped: [],
           }),
-          getStatistics: jest
-            .fn()
-            .mockReturnValue({ total: 1, successful: 1, failed: 0, skipped: 0 }),
+          getStatistics: jest.fn().mockReturnValue({
+            total: 1,
+            successful: 1,
+            failed: 0,
+            skipped: 0,
+          }),
         };
       });
 
@@ -2306,7 +2556,11 @@ describe('TranslateCommand', () => {
 
       it('should reject latency_optimized for an extended target', async () => {
         await expect(
-          directory({ to: 'sw', modelType: 'latency_optimized', output: '/out' })
+          directory({
+            to: 'sw',
+            modelType: 'latency_optimized',
+            output: '/out',
+          })
         ).rejects.toThrow('only support quality_optimized');
       });
 
@@ -2330,23 +2584,33 @@ describe('TranslateCommand', () => {
 
     describe('document mode', () => {
       function document(options: Record<string, unknown>) {
-        return fileHandler().documentHandler.translateDocument('/doc.pdf', options);
+        return fileHandler().documentHandler.translateDocument(
+          '/doc.pdf',
+          options
+        );
       }
 
       it('should reject formality for an extended target', async () => {
-        await expect(document({ to: 'sw', formality: 'more', output: '/out.pdf' })).rejects.toThrow(
-          'do not support formality'
-        );
+        await expect(
+          document({ to: 'sw', formality: 'more', output: '/out.pdf' })
+        ).rejects.toThrow('do not support formality');
       });
 
       it('should reject a glossary for an extended target', async () => {
         await expect(
-          document({ to: 'sw', from: 'en', glossary: ['my-glossary'], output: '/out.pdf' })
+          document({
+            to: 'sw',
+            from: 'en',
+            glossary: ['my-glossary'],
+            output: '/out.pdf',
+          })
         ).rejects.toThrow('do not support glossaries');
       });
 
       it('should not reject a model type it strips after warning', async () => {
-        (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+        (
+          mockDocumentTranslationService.translateDocument as jest.Mock
+        ).mockResolvedValue({
           success: true,
           outputPath: '/out.pdf',
         });
@@ -2364,7 +2628,10 @@ describe('TranslateCommand', () => {
     describe('source language', () => {
       it('should reject a malformed --from in text mode', async () => {
         await expect(
-          translateCommand.translateText('Hello', { to: 'es', from: 'not!!a!!lang' })
+          translateCommand.translateText('Hello', {
+            to: 'es',
+            from: 'not!!a!!lang',
+          })
         ).rejects.toThrow('Invalid source language code');
       });
 
@@ -2380,11 +2647,14 @@ describe('TranslateCommand', () => {
 
       it('should reject a malformed --from in directory mode', async () => {
         await expect(
-          (translateCommand as any).directoryHandler.translateDirectory('/src', {
-            to: 'es',
-            from: 'not!!a!!lang',
-            output: '/out',
-          })
+          (translateCommand as any).directoryHandler.translateDirectory(
+            '/src',
+            {
+              to: 'es',
+              from: 'not!!a!!lang',
+              output: '/out',
+            }
+          )
         ).rejects.toThrow('Invalid source language code');
       });
 
@@ -2685,7 +2955,9 @@ describe('TranslateCommand', () => {
 
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         '<p>Hello</p>',
-        expect.objectContaining({ splittingTags: ['_tag', 'my-tag', 'my.tag'] }),
+        expect.objectContaining({
+          splittingTags: ['_tag', 'my-tag', 'my.tag'],
+        }),
         expect.any(Object)
       );
     });
@@ -2963,7 +3235,9 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
 
-      const result = await (translateCommand as any).directoryHandler.translateDirectory('/src', {
+      const result = await (
+        translateCommand as any
+      ).directoryHandler.translateDirectory('/src', {
         to: 'es',
         output: '/out',
       });
@@ -2990,7 +3264,9 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
 
-      const result = await (translateCommand as any).directoryHandler.translateDirectory('/src', {
+      const result = await (
+        translateCommand as any
+      ).directoryHandler.translateDirectory('/src', {
         to: 'es',
         output: '/out',
       });
@@ -3016,7 +3292,9 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
 
-      const result = await (translateCommand as any).directoryHandler.translateDirectory('/src', {
+      const result = await (
+        translateCommand as any
+      ).directoryHandler.translateDirectory('/src', {
         to: 'es',
         output: '/out',
       });
@@ -3040,16 +3318,23 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
 
-      await (translateCommand as any).directoryHandler.translateDirectory('/src', {
-        to: 'es',
-        from: 'en',
-        formality: 'more',
-        output: '/out',
-      });
+      await (translateCommand as any).directoryHandler.translateDirectory(
+        '/src',
+        {
+          to: 'es',
+          from: 'en',
+          formality: 'more',
+          output: '/out',
+        }
+      );
 
       expect(mockBatchService.translateDirectory).toHaveBeenCalledWith(
         '/src',
-        expect.objectContaining({ targetLang: 'es', sourceLang: 'en', formality: 'more' }),
+        expect.objectContaining({
+          targetLang: 'es',
+          sourceLang: 'en',
+          formality: 'more',
+        }),
         expect.any(Object)
       );
     });
@@ -3057,7 +3342,9 @@ describe('TranslateCommand', () => {
     it('should override concurrency when specified', async () => {
       // When concurrency is specified, a new BatchTranslationService is created
       // which replaces the existing one. We need to mock the constructor.
-      const { BatchTranslationService } = jest.requireMock('../../src/services/batch-translation');
+      const { BatchTranslationService } = jest.requireMock(
+        '../../src/services/batch-translation'
+      );
       const mockInstance = {
         translateDirectory: jest.fn().mockResolvedValue({
           successful: [],
@@ -3073,11 +3360,14 @@ describe('TranslateCommand', () => {
       };
       BatchTranslationService.mockImplementation(() => mockInstance);
 
-      await (translateCommand as any).directoryHandler.translateDirectory('/src', {
-        to: 'es',
-        output: '/out',
-        concurrency: 10,
-      });
+      await (translateCommand as any).directoryHandler.translateDirectory(
+        '/src',
+        {
+          to: 'es',
+          output: '/out',
+          concurrency: 10,
+        }
+      );
 
       expect(BatchTranslationService).toHaveBeenCalledWith(
         expect.anything(),
@@ -3088,7 +3378,9 @@ describe('TranslateCommand', () => {
 
     it('should propagate errors from batch service', async () => {
       const mockBatchService = {
-        translateDirectory: jest.fn().mockRejectedValue(new Error('Batch failed')),
+        translateDirectory: jest
+          .fn()
+          .mockRejectedValue(new Error('Batch failed')),
         getStatistics: jest.fn(),
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
@@ -3107,9 +3399,15 @@ describe('TranslateCommand', () => {
       // Re-setup ora mock since clearAllMocks resets it
       const ora = jest.requireMock('ora');
       const mockSpinner = {
-        start: jest.fn(function(this: any) { return this; }),
-        succeed: jest.fn(function(this: any) { return this; }),
-        fail: jest.fn(function(this: any) { return this; }),
+        start: jest.fn(function (this: any) {
+          return this;
+        }),
+        succeed: jest.fn(function (this: any) {
+          return this;
+        }),
+        fail: jest.fn(function (this: any) {
+          return this;
+        }),
         text: '',
       };
       ora.mockReturnValue(mockSpinner);
@@ -3129,7 +3427,9 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
 
-      const result = await (translateCommand as any).directoryHandler.translateDirectory('/src', {
+      const result = await (
+        translateCommand as any
+      ).directoryHandler.translateDirectory('/src', {
         to: 'es',
         output: '/out',
       });
@@ -3155,12 +3455,15 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
 
-      await (translateCommand as any).directoryHandler.translateDirectory('/src', {
-        to: 'es',
-        output: '/out',
-        recursive: false,
-        pattern: '*.md',
-      });
+      await (translateCommand as any).directoryHandler.translateDirectory(
+        '/src',
+        {
+          to: 'es',
+          output: '/out',
+          recursive: false,
+          pattern: '*.md',
+        }
+      );
 
       expect(mockBatchService.translateDirectory).toHaveBeenCalledWith(
         '/src',
@@ -3189,11 +3492,14 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
 
-      await (translateCommand as any).directoryHandler.translateDirectory('/src', {
-        to: 'es',
-        output: '/out',
-        recursive: false,
-      });
+      await (translateCommand as any).directoryHandler.translateDirectory(
+        '/src',
+        {
+          to: 'es',
+          output: '/out',
+          recursive: false,
+        }
+      );
 
       expect(mockBatchService.translateDirectory).toHaveBeenCalledWith(
         '/src',
@@ -3220,7 +3526,9 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.batchTranslationService = mockBatchService;
 
-      const result = await (translateCommand as any).directoryHandler.translateDirectory('/src', {
+      const result = await (
+        translateCommand as any
+      ).directoryHandler.translateDirectory('/src', {
         to: 'es,fr',
         output: '/out',
       });
@@ -3241,18 +3549,24 @@ describe('TranslateCommand', () => {
     });
 
     it('should translate a document successfully', async () => {
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValue({
         success: true,
         outputPath: '/out.pdf',
       });
 
-      const result = await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+      const result = await (
+        translateCommand as any
+      ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
         to: 'es',
         output: '/out.pdf',
       });
 
       expect(result).toContain('Translated /doc.pdf -> /out.pdf');
-      expect(mockDocumentTranslationService.translateDocument).toHaveBeenCalledWith(
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).toHaveBeenCalledWith(
         '/doc.pdf',
         '/out.pdf',
         expect.objectContaining({ targetLang: 'es' }),
@@ -3261,18 +3575,24 @@ describe('TranslateCommand', () => {
     });
 
     it('should pass sourceLang to document translation', async () => {
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValue({
         success: true,
         outputPath: '/out.pdf',
       });
 
-      await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+      await (
+        translateCommand as any
+      ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
         to: 'es',
         from: 'en',
         output: '/out.pdf',
       });
 
-      expect(mockDocumentTranslationService.translateDocument).toHaveBeenCalledWith(
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).toHaveBeenCalledWith(
         '/doc.pdf',
         '/out.pdf',
         expect.objectContaining({ targetLang: 'es', sourceLang: 'en' }),
@@ -3281,18 +3601,24 @@ describe('TranslateCommand', () => {
     });
 
     it('should pass formality to document translation', async () => {
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValue({
         success: true,
         outputPath: '/out.pdf',
       });
 
-      await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+      await (
+        translateCommand as any
+      ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
         to: 'es',
         formality: 'more',
         output: '/out.pdf',
       });
 
-      expect(mockDocumentTranslationService.translateDocument).toHaveBeenCalledWith(
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).toHaveBeenCalledWith(
         '/doc.pdf',
         '/out.pdf',
         expect.objectContaining({ formality: 'more' }),
@@ -3301,18 +3627,24 @@ describe('TranslateCommand', () => {
     });
 
     it('should pass outputFormat to document translation', async () => {
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValue({
         success: true,
         outputPath: '/out.docx',
       });
 
-      await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+      await (
+        translateCommand as any
+      ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
         to: 'es',
         output: '/out.docx',
         outputFormat: 'docx',
       });
 
-      expect(mockDocumentTranslationService.translateDocument).toHaveBeenCalledWith(
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).toHaveBeenCalledWith(
         '/doc.pdf',
         '/out.docx',
         expect.objectContaining({ outputFormat: 'docx' }),
@@ -3321,18 +3653,24 @@ describe('TranslateCommand', () => {
     });
 
     it('should pass enableDocumentMinification option', async () => {
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValue({
         success: true,
         outputPath: '/out.pdf',
       });
 
-      await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+      await (
+        translateCommand as any
+      ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
         to: 'es',
         output: '/out.pdf',
         enableMinification: true,
       });
 
-      expect(mockDocumentTranslationService.translateDocument).toHaveBeenCalledWith(
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).toHaveBeenCalledWith(
         '/doc.pdf',
         '/out.pdf',
         expect.objectContaining({ enableDocumentMinification: true }),
@@ -3341,13 +3679,17 @@ describe('TranslateCommand', () => {
     });
 
     it('should display billed characters when returned', async () => {
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockResolvedValue({
         success: true,
         outputPath: '/out.pdf',
         billedCharacters: 1500,
       });
 
-      const result = await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+      const result = await (
+        translateCommand as any
+      ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
         to: 'es',
         output: '/out.pdf',
       });
@@ -3356,15 +3698,18 @@ describe('TranslateCommand', () => {
     });
 
     it('should propagate errors from document service', async () => {
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockRejectedValue(
-        new Error('Document upload failed')
-      );
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockRejectedValue(new Error('Document upload failed'));
 
       await expect(
-        (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
-          to: 'es',
-          output: '/out.pdf',
-        })
+        (translateCommand as any).fileHandler.documentHandler.translateDocument(
+          '/doc.pdf',
+          {
+            to: 'es',
+            output: '/out.pdf',
+          }
+        )
       ).rejects.toThrow('Document upload failed');
     });
 
@@ -3374,14 +3719,22 @@ describe('TranslateCommand', () => {
       // Re-setup ora mock since clearAllMocks resets it
       const ora = jest.requireMock('ora');
       const mockSpinner = {
-        start: jest.fn(function(this: any) { return this; }),
-        succeed: jest.fn(function(this: any) { return this; }),
-        fail: jest.fn(function(this: any) { return this; }),
+        start: jest.fn(function (this: any) {
+          return this;
+        }),
+        succeed: jest.fn(function (this: any) {
+          return this;
+        }),
+        fail: jest.fn(function (this: any) {
+          return this;
+        }),
         text: '',
       };
       ora.mockReturnValue(mockSpinner);
 
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockImplementation(
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockImplementation(
         (_input: string, _output: string, _opts: any, onProgress: Function) => {
           onProgress({ status: 'queued' });
           onProgress({ status: 'translating', secondsRemaining: 10 });
@@ -3391,7 +3744,9 @@ describe('TranslateCommand', () => {
         }
       );
 
-      const result = await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+      const result = await (
+        translateCommand as any
+      ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
         to: 'es',
         output: '/out.pdf',
       });
@@ -3407,25 +3762,36 @@ describe('TranslateCommand', () => {
       // Re-setup ora mock since clearAllMocks resets it
       const ora = jest.requireMock('ora');
       const mockSpinner = {
-        start: jest.fn(function(this: any) { return this; }),
-        succeed: jest.fn(function(this: any) { return this; }),
-        fail: jest.fn(function(this: any) { return this; }),
+        start: jest.fn(function (this: any) {
+          return this;
+        }),
+        succeed: jest.fn(function (this: any) {
+          return this;
+        }),
+        fail: jest.fn(function (this: any) {
+          return this;
+        }),
         text: '',
       };
       ora.mockReturnValue(mockSpinner);
 
-      (mockDocumentTranslationService.translateDocument as jest.Mock).mockRejectedValue(
-        new Error('Network error')
-      );
+      (
+        mockDocumentTranslationService.translateDocument as jest.Mock
+      ).mockRejectedValue(new Error('Network error'));
 
       await expect(
-        (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
-          to: 'es',
-          output: '/out.pdf',
-        })
+        (translateCommand as any).fileHandler.documentHandler.translateDocument(
+          '/doc.pdf',
+          {
+            to: 'es',
+            output: '/out.pdf',
+          }
+        )
       ).rejects.toThrow('Network error');
 
-      expect(mockSpinner.fail).toHaveBeenCalledWith('Document translation failed');
+      expect(mockSpinner.fail).toHaveBeenCalledWith(
+        'Document translation failed'
+      );
     });
   });
 
@@ -3447,7 +3813,9 @@ describe('TranslateCommand', () => {
         isDirectory: () => false,
       } as any);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(false);
 
       const mockFileService = {
         translateFile: jest.fn().mockResolvedValue(undefined),
@@ -3456,10 +3824,13 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.fileTranslationService = mockFileService;
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/input.csv', {
-        to: 'es',
-        output: '/output.csv',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/input.csv',
+        {
+          to: 'es',
+          output: '/output.csv',
+        }
+      );
 
       expect(result).toBe('Translated /input.csv -> /output.csv');
       expect(mockFileService.translateFile).toHaveBeenCalledWith(
@@ -3476,7 +3847,9 @@ describe('TranslateCommand', () => {
         isDirectory: () => false,
       } as any);
 
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(false);
 
       const mockFileService = {
         translateFile: jest.fn().mockResolvedValue(undefined),
@@ -3495,7 +3868,11 @@ describe('TranslateCommand', () => {
       expect(mockFileService.translateFile).toHaveBeenCalledWith(
         '/input.csv',
         '/output.csv',
-        expect.objectContaining({ targetLang: 'es', sourceLang: 'en', formality: 'less' }),
+        expect.objectContaining({
+          targetLang: 'es',
+          sourceLang: 'en',
+          formality: 'less',
+        }),
         { preserveCode: undefined }
       );
     });
@@ -3507,10 +3884,14 @@ describe('TranslateCommand', () => {
       });
 
       await expect(
-        (translateCommand as any).fileHandler.translateFile('/nonexistent.txt', {
-          to: 'es',
-          output: '/out.txt',
-        }, null)
+        (translateCommand as any).fileHandler.translateFile(
+          '/nonexistent.txt',
+          {
+            to: 'es',
+            output: '/out.txt',
+          },
+          null
+        )
       ).rejects.toThrow('File not found or cannot be accessed');
     });
   });
@@ -3537,20 +3918,28 @@ describe('TranslateCommand', () => {
     });
 
     it('should pass glossaryId to text translation for file', async () => {
-      (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValue('glossary-file-123');
+      (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValue(
+        'glossary-file-123'
+      );
       mockTranslationService.translate.mockResolvedValue({
         text: 'Hola',
         detectedSourceLang: undefined,
       });
 
-      await (translateCommand as any).fileHandler.translateTextFile('/doc.txt', {
-        to: 'es',
-        from: 'en',
-        output: '/out.txt',
-        glossary: ['my-glossary'],
-      });
+      await (translateCommand as any).fileHandler.translateTextFile(
+        '/doc.txt',
+        {
+          to: 'es',
+          from: 'en',
+          output: '/out.txt',
+          glossary: ['my-glossary'],
+        }
+      );
 
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', { from: 'en', targets: ['es'] });
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        { from: 'en', targets: ['es'] }
+      );
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello',
         expect.objectContaining({ glossaryId: 'glossary-file-123' }),
@@ -3564,11 +3953,14 @@ describe('TranslateCommand', () => {
         detectedSourceLang: undefined,
       });
 
-      await (translateCommand as any).fileHandler.translateTextFile('/doc.txt', {
-        to: 'es',
-        output: '/out.txt',
-        preserveFormatting: true,
-      });
+      await (translateCommand as any).fileHandler.translateTextFile(
+        '/doc.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+          preserveFormatting: true,
+        }
+      );
 
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello',
@@ -3583,11 +3975,14 @@ describe('TranslateCommand', () => {
         detectedSourceLang: undefined,
       });
 
-      await (translateCommand as any).fileHandler.translateTextFile('/doc.txt', {
-        to: 'es',
-        output: '/out.txt',
-        context: 'Technical documentation',
-      });
+      await (translateCommand as any).fileHandler.translateTextFile(
+        '/doc.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+          context: 'Technical documentation',
+        }
+      );
 
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello',
@@ -3597,24 +3992,31 @@ describe('TranslateCommand', () => {
     });
 
     it('should create output directory if it does not exist', async () => {
-      jest.spyOn(mockFs, 'existsSync').mockImplementation((...args: unknown[]) => {
-        if (args[0] === '/nested/dir') {
-          return false;
-        }
-        return true;
-      });
+      jest
+        .spyOn(mockFs, 'existsSync')
+        .mockImplementation((...args: unknown[]) => {
+          if (args[0] === '/nested/dir') {
+            return false;
+          }
+          return true;
+        });
 
       mockTranslationService.translate.mockResolvedValue({
         text: 'Hola',
         detectedSourceLang: undefined,
       });
 
-      await (translateCommand as any).fileHandler.translateTextFile('/doc.txt', {
-        to: 'es',
-        output: '/nested/dir/out.txt',
-      });
+      await (translateCommand as any).fileHandler.translateTextFile(
+        '/doc.txt',
+        {
+          to: 'es',
+          output: '/nested/dir/out.txt',
+        }
+      );
 
-      expect(mockFs.mkdirSync).toHaveBeenCalledWith('/nested/dir', { recursive: true });
+      expect(mockFs.mkdirSync).toHaveBeenCalledWith('/nested/dir', {
+        recursive: true,
+      });
     });
 
     it('should pass formality and sourceLang to text file translation', async () => {
@@ -3623,16 +4025,23 @@ describe('TranslateCommand', () => {
         detectedSourceLang: undefined,
       });
 
-      await (translateCommand as any).fileHandler.translateTextFile('/doc.txt', {
-        to: 'es',
-        from: 'en',
-        formality: 'more',
-        output: '/out.txt',
-      });
+      await (translateCommand as any).fileHandler.translateTextFile(
+        '/doc.txt',
+        {
+          to: 'es',
+          from: 'en',
+          formality: 'more',
+          output: '/out.txt',
+        }
+      );
 
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ targetLang: 'es', sourceLang: 'en', formality: 'more' }),
+        expect.objectContaining({
+          targetLang: 'es',
+          sourceLang: 'en',
+          formality: 'more',
+        }),
         expect.any(Object)
       );
     });
@@ -3644,10 +4053,13 @@ describe('TranslateCommand', () => {
         detectedSourceLang: undefined,
       });
 
-      await (translateCommand as any).fileHandler.translateTextFile('/doc.txt', {
-        to: 'es',
-        output: '/out.txt',
-      });
+      await (translateCommand as any).fileHandler.translateTextFile(
+        '/doc.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        }
+      );
 
       expect(safeReadFileSync).toHaveBeenCalledWith('/doc.txt', 'utf-8');
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
@@ -3659,7 +4071,9 @@ describe('TranslateCommand', () => {
 
     it('should reject symlinks when reading translation files', async () => {
       (safeReadFileSync as jest.Mock).mockImplementation(() => {
-        throw new Error('Symlinks are not supported for security reasons: /doc.txt');
+        throw new Error(
+          'Symlinks are not supported for security reasons: /doc.txt'
+        );
       });
 
       await expect(
@@ -3667,7 +4081,9 @@ describe('TranslateCommand', () => {
           to: 'es',
           output: '/out.txt',
         })
-      ).rejects.toThrow('Symlinks are not supported for security reasons: /doc.txt');
+      ).rejects.toThrow(
+        'Symlinks are not supported for security reasons: /doc.txt'
+      );
 
       expect(safeReadFileSync).toHaveBeenCalledWith('/doc.txt', 'utf-8');
       expect(mockTranslationService.translate).not.toHaveBeenCalled();
@@ -3693,7 +4109,9 @@ describe('TranslateCommand', () => {
       } as any);
 
       // Large .txt, but document API does NOT support it
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(false);
 
       const mockFileService = {
         translateFile: jest.fn().mockResolvedValue(undefined),
@@ -3702,15 +4120,20 @@ describe('TranslateCommand', () => {
       };
       (translateCommand as any).ctx.fileTranslationService = mockFileService;
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/large.txt', {
-        to: 'es',
-        output: '/out.txt',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/large.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        }
+      );
 
       // Falls through to the fileTranslationService path
       expect(result).toBe('Translated /large.txt -> /out.txt');
       expect(mockFileService.translateFile).toHaveBeenCalled();
-      expect(mockDocumentTranslationService.translateDocument).not.toHaveBeenCalled();
+      expect(
+        mockDocumentTranslationService.translateDocument
+      ).not.toHaveBeenCalled();
     });
   });
 
@@ -3766,10 +4189,14 @@ describe('TranslateCommand', () => {
         detectedSourceLang: undefined,
       });
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/doc.txt', {
-        to: 'es',
-        output: '/out.txt',
-      }, cachedStats);
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/doc.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        },
+        cachedStats
+      );
 
       expect(result).toContain('Translated /doc.txt');
       expect(mockTranslationService.translate).toHaveBeenCalled();
@@ -3786,10 +4213,14 @@ describe('TranslateCommand', () => {
         detectedSourceLang: undefined,
       });
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/doc.txt', {
-        to: 'es',
-        output: '/out.txt',
-      }, null);
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/doc.txt',
+        {
+          to: 'es',
+          output: '/out.txt',
+        },
+        null
+      );
 
       expect(result).toContain('Translated /doc.txt');
     });
@@ -3808,7 +4239,9 @@ describe('TranslateCommand', () => {
 
     describe('multi-target mode', () => {
       beforeEach(() => {
-        (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValue([
+        (
+          mockTranslationService.translateToMultiple as jest.Mock
+        ).mockResolvedValue([
           { targetLang: 'es', text: 'Hola' },
           { targetLang: 'fr', text: 'Bonjour' },
         ]);
@@ -3824,7 +4257,9 @@ describe('TranslateCommand', () => {
         });
 
         expect(warnSpy).toHaveBeenCalledWith(
-          expect.stringMatching(/multi-target mode does not support.*--split-sentences/)
+          expect.stringMatching(
+            /multi-target mode does not support.*--split-sentences/
+          )
         );
         expect(warnSpy).toHaveBeenCalledWith(
           expect.stringMatching(/--tag-handling/)
@@ -3869,15 +4304,18 @@ describe('TranslateCommand', () => {
     describe('directory mode', () => {
       it('should warn when unsupported options are passed to directory mode', async () => {
         await expect(
-          (translateCommand as any).directoryHandler.translateDirectory('/path/to/dir', {
-            to: 'es',
-            output: '/output',
-            splitSentences: 'on',
-            glossary: ['my-glossary'],
-            customInstruction: ['Be formal'],
-            modelType: 'quality_optimized',
-            context: 'technical docs',
-          })
+          (translateCommand as any).directoryHandler.translateDirectory(
+            '/path/to/dir',
+            {
+              to: 'es',
+              output: '/output',
+              splitSentences: 'on',
+              glossary: ['my-glossary'],
+              customInstruction: ['Be formal'],
+              modelType: 'quality_optimized',
+              context: 'technical docs',
+            }
+          )
         ).rejects.toThrow(); // will fail due to batch service mock, but warning comes first
 
         expect(warnSpy).toHaveBeenCalledWith(
@@ -3896,12 +4334,15 @@ describe('TranslateCommand', () => {
 
       it('should not warn when only supported options are used in directory mode', async () => {
         await expect(
-          (translateCommand as any).directoryHandler.translateDirectory('/path/to/dir', {
-            to: 'es',
-            output: '/output',
-            from: 'en',
-            formality: 'more',
-          })
+          (translateCommand as any).directoryHandler.translateDirectory(
+            '/path/to/dir',
+            {
+              to: 'es',
+              output: '/output',
+              from: 'en',
+              formality: 'more',
+            }
+          )
         ).rejects.toThrow(); // batch service mock will cause this to fail
 
         expect(warnSpy).not.toHaveBeenCalled();
@@ -3911,14 +4352,18 @@ describe('TranslateCommand', () => {
     describe('document mode', () => {
       beforeEach(() => {
         jest.spyOn(Logger, 'shouldShowSpinner').mockReturnValue(false);
-        (mockDocumentTranslationService.translateDocument as jest.Mock).mockResolvedValue({
+        (
+          mockDocumentTranslationService.translateDocument as jest.Mock
+        ).mockResolvedValue({
           success: true,
           outputPath: '/output.pdf',
         });
       });
 
       it('should warn when unsupported options are passed to document mode', async () => {
-        await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+        await (
+          translateCommand as any
+        ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
           to: 'es',
           output: '/output.pdf',
           splitSentences: 'on',
@@ -3940,11 +4385,13 @@ describe('TranslateCommand', () => {
       });
 
       it('should not warn when only supported options are used in document mode', async () => {
-        (mockGlossaryService.resolveGlossaryId as jest.Mock).mockResolvedValueOnce(
-          'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
-        );
+        (
+          mockGlossaryService.resolveGlossaryId as jest.Mock
+        ).mockResolvedValueOnce('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa');
 
-        await (translateCommand as any).fileHandler.documentHandler.translateDocument('/doc.pdf', {
+        await (
+          translateCommand as any
+        ).fileHandler.documentHandler.translateDocument('/doc.pdf', {
           to: 'es',
           output: '/output.pdf',
           from: 'en',
@@ -3959,7 +4406,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should not warn for undefined or false boolean options', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValue([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValue([
         { targetLang: 'es', text: 'Hola' },
         { targetLang: 'fr', text: 'Bonjour' },
       ]);
@@ -4151,9 +4600,12 @@ describe('TranslateCommand', () => {
         text: `${familyEmoji} familia`,
       });
 
-      const result = await translateCommand.translateText(`${familyEmoji} family`, {
-        to: 'es',
-      });
+      const result = await translateCommand.translateText(
+        `${familyEmoji} family`,
+        {
+          to: 'es',
+        }
+      );
 
       expect(result).toBe(`${familyEmoji} familia`);
       expect(mockTranslationService.translate).toHaveBeenCalledWith(
@@ -4235,7 +4687,9 @@ describe('TranslateCommand', () => {
     });
 
     it('should translate CJK text to multiple targets', async () => {
-      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+      (
+        mockTranslationService.translateToMultiple as jest.Mock
+      ).mockResolvedValueOnce([
         { targetLang: 'en', text: 'Hello world' },
         { targetLang: 'fr', text: 'Bonjour le monde' },
       ]);
@@ -4261,7 +4715,9 @@ describe('TranslateCommand', () => {
       jest.spyOn(mockFs, 'mkdirSync').mockImplementation(() => undefined);
 
       jest.spyOn(Logger, 'shouldShowSpinner').mockReturnValue(false);
-      stdoutWriteSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+      stdoutWriteSpy = jest
+        .spyOn(process.stdout, 'write')
+        .mockImplementation(() => true);
     });
 
     afterEach(() => {
@@ -4271,18 +4727,23 @@ describe('TranslateCommand', () => {
     it('should write translated text to stdout when output is -', async () => {
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 1024,
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       (safeReadFileSync as jest.Mock).mockReturnValue('Hello world');
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
       (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
         text: 'Hola mundo',
       });
 
-      const result = await (translateCommand as any).fileHandler.translateFile('/input.txt', {
-        to: 'es',
-        output: '-',
-      });
+      const result = await (translateCommand as any).fileHandler.translateFile(
+        '/input.txt',
+        {
+          to: 'es',
+          output: '-',
+        }
+      );
 
       expect(stdoutWriteSpy).toHaveBeenCalledWith('Hola mundo');
       expect(result).toBe('');
@@ -4301,25 +4762,32 @@ describe('TranslateCommand', () => {
     it('should reject --output - for document translation', async () => {
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 200 * 1024,
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(true);
 
       await expect(
-        (translateCommand as any).fileHandler.documentHandler.translateDocument('/input.pdf', {
-          to: 'es',
-          output: '-',
-        })
+        (translateCommand as any).fileHandler.documentHandler.translateDocument(
+          '/input.pdf',
+          {
+            to: 'es',
+            output: '-',
+          }
+        )
       ).rejects.toThrow('Cannot stream binary document translation to stdout');
     });
 
     it('should reject --output - for structured file (JSON/YAML) translation', async () => {
       jest.spyOn(mockFs, 'statSync').mockReturnValue({
         size: 1024,
-        isDirectory: () => false
+        isDirectory: () => false,
       } as any);
       (safeReadFileSync as jest.Mock).mockReturnValue('{"key": "value"}');
-      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(false);
+      (
+        mockDocumentTranslationService.isDocumentSupported as jest.Mock
+      ).mockReturnValue(false);
 
       await expect(
         (translateCommand as any).fileHandler.translateFile('/input.json', {
diff --git a/tests/unit/translate-default-target.test.ts b/tests/unit/translate-default-target.test.ts
index f08c9dd4..ac0c288c 100644
--- a/tests/unit/translate-default-target.test.ts
+++ b/tests/unit/translate-default-target.test.ts
@@ -19,9 +19,15 @@ jest.mock('chalk', () => {
 
 jest.mock('ora', () => {
   const mockSpinner = {
-    start: jest.fn(function(this: any) { return this; }),
-    succeed: jest.fn(function(this: any) { return this; }),
-    fail: jest.fn(function(this: any) { return this; }),
+    start: jest.fn(function (this: any) {
+      return this;
+    }),
+    succeed: jest.fn(function (this: any) {
+      return this;
+    }),
+    fail: jest.fn(function (this: any) {
+      return this;
+    }),
     text: '',
   };
   return jest.fn(() => mockSpinner);
@@ -37,7 +43,8 @@ jest.mock('../../src/cli/commands/service-factory', () => ({
 
 import { createTranslateCommand } from '../../src/cli/commands/service-factory';
 
-const mockCreateTranslateCommand = createTranslateCommand as jest.MockedFunction<typeof createTranslateCommand>;
+const mockCreateTranslateCommand =
+  createTranslateCommand as jest.MockedFunction<typeof createTranslateCommand>;
 
 describe('translate command default target language', () => {
   let program: Command;
@@ -73,7 +80,9 @@ describe('translate command default target language', () => {
 
     mockDeps = {
       createDeepLClient: jest.fn(),
-      getApiKeyAndOptions: jest.fn().mockReturnValue({ apiKey: 'test-key', options: {} }),
+      getApiKeyAndOptions: jest
+        .fn()
+        .mockReturnValue({ apiKey: 'test-key', options: {} }),
       getConfigService: jest.fn().mockReturnValue(mockConfigService),
       getCacheService: jest.fn(),
       handleError: handleErrorSpy as unknown as (error: unknown) => never,
@@ -92,12 +101,19 @@ describe('translate command default target language', () => {
         translateFromStdin: jest.fn(),
       } as any);
 
-      await program.parseAsync(['node', 'test', 'translate', 'Hello', '--to', 'es']);
+      await program.parseAsync([
+        'node',
+        'test',
+        'translate',
+        'Hello',
+        '--to',
+        'es',
+      ]);
 
       expect(mockDeps.getConfigService).not.toHaveBeenCalled();
       expect(mockTranslate).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ to: 'es' }),
+        expect.objectContaining({ to: 'es' })
       );
     });
   });
@@ -120,10 +136,12 @@ describe('translate command default target language', () => {
       await program.parseAsync(['node', 'test', 'translate', 'Hello']);
 
       expect(mockDeps.getConfigService).toHaveBeenCalled();
-      expect(mockConfigService.getValue).toHaveBeenCalledWith('defaults.targetLangs');
+      expect(mockConfigService.getValue).toHaveBeenCalledWith(
+        'defaults.targetLangs'
+      );
       expect(mockTranslate).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ to: 'fr' }),
+        expect.objectContaining({ to: 'fr' })
       );
     });
 
@@ -145,7 +163,7 @@ describe('translate command default target language', () => {
 
       expect(mockTranslate).toHaveBeenCalledWith(
         'Hello',
-        expect.objectContaining({ to: 'ja' }),
+        expect.objectContaining({ to: 'ja' })
       );
     });
 
@@ -158,7 +176,7 @@ describe('translate command default target language', () => {
       });
 
       await expect(
-        program.parseAsync(['node', 'test', 'translate', 'Hello']),
+        program.parseAsync(['node', 'test', 'translate', 'Hello'])
       ).rejects.toThrow();
 
       expect(handleErrorSpy).toHaveBeenCalled();
@@ -170,7 +188,7 @@ describe('translate command default target language', () => {
       mockConfigService.getValue.mockReturnValue(undefined);
 
       await expect(
-        program.parseAsync(['node', 'test', 'translate', 'Hello']),
+        program.parseAsync(['node', 'test', 'translate', 'Hello'])
       ).rejects.toThrow();
 
       expect(handleErrorSpy).toHaveBeenCalled();
@@ -195,7 +213,7 @@ describe('translate command default target language', () => {
       await program.parseAsync(['node', 'test', 'translate']);
 
       expect(mockTranslateFromStdin).toHaveBeenCalledWith(
-        expect.objectContaining({ to: 'de' }),
+        expect.objectContaining({ to: 'de' })
       );
     });
   });
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index a317f013..4bb609c2 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -43,7 +43,9 @@ jest.mock('fs', () => ({
   statSync: jest.fn(),
 }));
 
-const mockedExistsSync = fs.existsSync as jest.MockedFunction<typeof fs.existsSync>;
+const mockedExistsSync = fs.existsSync as jest.MockedFunction<
+  typeof fs.existsSync
+>;
 const mockedStatSync = fs.statSync as jest.MockedFunction<typeof fs.statSync>;
 const mockedLoggerWarn = Logger.warn as jest.MockedFunction<typeof Logger.warn>;
 
@@ -73,7 +75,18 @@ describe('translate-utils', () => {
     });
 
     it('TEXT_BASED_EXTENSIONS should include expected extensions', () => {
-      expect(TEXT_BASED_EXTENSIONS).toEqual(['.txt', '.md', '.html', '.htm', '.srt', '.xlf', '.xliff', '.json', '.yaml', '.yml']);
+      expect(TEXT_BASED_EXTENSIONS).toEqual([
+        '.txt',
+        '.md',
+        '.html',
+        '.htm',
+        '.srt',
+        '.xlf',
+        '.xliff',
+        '.json',
+        '.yaml',
+        '.yml',
+      ]);
     });
 
     it('STRUCTURED_EXTENSIONS should include expected extensions', () => {
@@ -111,11 +124,15 @@ describe('translate-utils', () => {
     });
 
     it('should throw ValidationError for a malformed language code', () => {
-      expect(() => validateLanguageCodes(['not-a-language'])).toThrow(ValidationError);
+      expect(() => validateLanguageCodes(['not-a-language'])).toThrow(
+        ValidationError
+      );
     });
 
     it('should include the invalid code in the error message', () => {
-      expect(() => validateLanguageCodes(['zzzz'])).toThrow(/Invalid target language code: "zzzz"/);
+      expect(() => validateLanguageCodes(['zzzz'])).toThrow(
+        /Invalid target language code: "zzzz"/
+      );
     });
 
     it('should pass through a well-formed code the snapshot does not know', () => {
@@ -132,7 +149,9 @@ describe('translate-utils', () => {
 
       // Said before anything is sent, since the API answers an unknown code with
       // a bare "target_lang not supported" that points nowhere.
-      const warning = mockedLoggerWarn.mock.calls.map(call => String(call[0])).join('\n');
+      const warning = mockedLoggerWarn.mock.calls
+        .map((call) => String(call[0]))
+        .join('\n');
       expect(warning).toContain('"ex" is not in the bundled language list');
       expect(warning).toContain('deepl languages');
     });
@@ -145,7 +164,14 @@ describe('translate-utils', () => {
     });
 
     it('should still reject input that is not shaped like a language tag', () => {
-      for (const code of ['g', 'grman', 'de_ch', 'de-', '../etc/passwd', 'de ch']) {
+      for (const code of [
+        'g',
+        'grman',
+        'de_ch',
+        'de-',
+        '../etc/passwd',
+        'de ch',
+      ]) {
         expect(() => validateLanguageCodes([code])).toThrow(ValidationError);
       }
     });
@@ -166,7 +192,9 @@ describe('translate-utils', () => {
     });
 
     it('should throw on first invalid code in array', () => {
-      expect(() => validateLanguageCodes(['en', 'invalid', 'de'])).toThrow(/Invalid target language code: "invalid"/);
+      expect(() => validateLanguageCodes(['en', 'invalid', 'de'])).toThrow(
+        /Invalid target language code: "invalid"/
+      );
     });
 
     it('should warn once per unknown code however many times it is validated', () => {
@@ -182,7 +210,9 @@ describe('translate-utils', () => {
       validateLanguageCodes(['ex', 'zz']);
       validateLanguageCodes(['ex', 'zz']);
 
-      const warnings = mockedLoggerWarn.mock.calls.map(call => String(call[0]));
+      const warnings = mockedLoggerWarn.mock.calls.map((call) =>
+        String(call[0])
+      );
       expect(warnings).toHaveLength(2);
       expect(warnings[0]).toContain('"ex"');
       expect(warnings[1]).toContain('"zz"');
@@ -209,16 +239,20 @@ describe('translate-utils', () => {
     });
 
     it('should reject a malformed code as a source, not a target', () => {
-      expect(() => validateSourceLanguage('not!!a!!lang')).toThrow(ValidationError);
       expect(() => validateSourceLanguage('not!!a!!lang')).toThrow(
-        /Invalid source language code: "not!!a!!lang"/,
+        ValidationError
+      );
+      expect(() => validateSourceLanguage('not!!a!!lang')).toThrow(
+        /Invalid source language code: "not!!a!!lang"/
       );
     });
 
     it('should defer a well-formed unknown code to the API with a warning', () => {
       expect(() => validateSourceLanguage('zz')).not.toThrow();
 
-      const warning = mockedLoggerWarn.mock.calls.map(call => String(call[0])).join('\n');
+      const warning = mockedLoggerWarn.mock.calls
+        .map((call) => String(call[0]))
+        .join('\n');
       expect(warning).toContain('"zz" is not in the bundled language list');
     });
 
@@ -233,36 +267,40 @@ describe('translate-utils', () => {
   describe('validateTranslationLanguages()', () => {
     it('should reject a malformed target code', () => {
       expect(() => validateTranslationLanguages(['not!!a!!lang'], {})).toThrow(
-        /Invalid target language code/,
+        /Invalid target language code/
       );
     });
 
     it('should reject a malformed source code', () => {
-      expect(() => validateTranslationLanguages(['de'], { from: 'not!!a!!lang' })).toThrow(
-        /Invalid source language code/,
-      );
+      expect(() =>
+        validateTranslationLanguages(['de'], { from: 'not!!a!!lang' })
+      ).toThrow(/Invalid source language code/);
     });
 
     it('should enforce the extended-tier constraint over the whole target list', () => {
-      expect(() => validateTranslationLanguages(['de', 'hi'], { formality: 'more' })).toThrow(
-        /Language\(s\) hi do not support formality/,
-      );
+      expect(() =>
+        validateTranslationLanguages(['de', 'hi'], { formality: 'more' })
+      ).toThrow(/Language\(s\) hi do not support formality/);
     });
 
     it('should enforce the extended-tier constraint for a single target', () => {
       expect(() =>
-        validateTranslationLanguages(['hi'], { modelType: 'latency_optimized' }),
+        validateTranslationLanguages(['hi'], { modelType: 'latency_optimized' })
       ).toThrow(/only support quality_optimized/);
     });
 
     it('should accept a valid pair with no constrained options', () => {
-      expect(() => validateTranslationLanguages(['de', 'fr'], { from: 'en' })).not.toThrow();
+      expect(() =>
+        validateTranslationLanguages(['de', 'fr'], { from: 'en' })
+      ).not.toThrow();
     });
 
     it('should not enforce an arm the caller left out', () => {
       // The input modes disagree about which flags they honour; a mode that
       // discards a flag passes it here as absent.
-      expect(() => validateTranslationLanguages(['hi'], { formality: 'more' })).toThrow();
+      expect(() =>
+        validateTranslationLanguages(['hi'], { formality: 'more' })
+      ).toThrow();
       expect(() => validateTranslationLanguages(['hi'], {})).not.toThrow();
     });
   });
@@ -272,40 +310,64 @@ describe('translate-utils', () => {
 
     it('should throw for extended language with latency_optimized model', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, modelType: 'latency_optimized' })
+        validateExtendedLanguageConstraints('hi', {
+          ...baseOptions,
+          modelType: 'latency_optimized',
+        })
       ).toThrow(ValidationError);
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, modelType: 'latency_optimized' })
+        validateExtendedLanguageConstraints('hi', {
+          ...baseOptions,
+          modelType: 'latency_optimized',
+        })
       ).toThrow(/only support quality_optimized/);
     });
 
     it('should throw for extended language with formality setting', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, formality: 'more' })
+        validateExtendedLanguageConstraints('hi', {
+          ...baseOptions,
+          formality: 'more',
+        })
       ).toThrow(ValidationError);
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, formality: 'more' })
+        validateExtendedLanguageConstraints('hi', {
+          ...baseOptions,
+          formality: 'more',
+        })
       ).toThrow(/do not support formality/);
     });
 
     it('should not throw for extended language with formality=default', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, formality: 'default' })
+        validateExtendedLanguageConstraints('hi', {
+          ...baseOptions,
+          formality: 'default',
+        })
       ).not.toThrow();
     });
 
     it('should throw for extended language with glossary', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, glossary: ['my-glossary'] })
+        validateExtendedLanguageConstraints('hi', {
+          ...baseOptions,
+          glossary: ['my-glossary'],
+        })
       ).toThrow(ValidationError);
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, glossary: ['my-glossary'] })
+        validateExtendedLanguageConstraints('hi', {
+          ...baseOptions,
+          glossary: ['my-glossary'],
+        })
       ).toThrow(/do not support glossaries/);
     });
 
     it('should not throw for an empty glossary list, which selects nothing', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('hi', { ...baseOptions, glossary: [] })
+        validateExtendedLanguageConstraints('hi', {
+          ...baseOptions,
+          glossary: [],
+        })
       ).not.toThrow();
     });
 
@@ -321,13 +383,18 @@ describe('translate-utils', () => {
 
     it('should handle comma-separated target languages', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('hi, sw', { ...baseOptions, modelType: 'latency_optimized' })
+        validateExtendedLanguageConstraints('hi, sw', {
+          ...baseOptions,
+          modelType: 'latency_optimized',
+        })
       ).toThrow(/hi, sw/);
     });
 
     it('should not throw when only non-extended langs in comma-separated list', () => {
       expect(() =>
-        validateExtendedLanguageConstraints('en, de', { modelType: 'latency_optimized' })
+        validateExtendedLanguageConstraints('en, de', {
+          modelType: 'latency_optimized',
+        })
       ).not.toThrow();
     });
 
@@ -340,52 +407,81 @@ describe('translate-utils', () => {
 
   describe('validateXmlTags()', () => {
     it('should accept valid tag names', () => {
-      expect(() => validateXmlTags(['div', 'span', 'myTag'], '--splitting-tags')).not.toThrow();
+      expect(() =>
+        validateXmlTags(['div', 'span', 'myTag'], '--splitting-tags')
+      ).not.toThrow();
     });
 
     it('should accept tags starting with underscore', () => {
-      expect(() => validateXmlTags(['_tag', '_my-tag'], '--splitting-tags')).not.toThrow();
+      expect(() =>
+        validateXmlTags(['_tag', '_my-tag'], '--splitting-tags')
+      ).not.toThrow();
     });
 
     it('should accept tags with hyphens, underscores, and periods', () => {
-      expect(() => validateXmlTags(['my-tag', 'my_tag', 'my.tag'], '--splitting-tags')).not.toThrow();
+      expect(() =>
+        validateXmlTags(['my-tag', 'my_tag', 'my.tag'], '--splitting-tags')
+      ).not.toThrow();
     });
 
     it('should throw for empty tag', () => {
-      expect(() => validateXmlTags([''], '--splitting-tags')).toThrow(ValidationError);
-      expect(() => validateXmlTags([''], '--splitting-tags')).toThrow(/Tag name cannot be empty/);
+      expect(() => validateXmlTags([''], '--splitting-tags')).toThrow(
+        ValidationError
+      );
+      expect(() => validateXmlTags([''], '--splitting-tags')).toThrow(
+        /Tag name cannot be empty/
+      );
     });
 
     it('should throw for whitespace-only tag', () => {
-      expect(() => validateXmlTags(['  '], '--splitting-tags')).toThrow(/Tag name cannot be empty/);
+      expect(() => validateXmlTags(['  '], '--splitting-tags')).toThrow(
+        /Tag name cannot be empty/
+      );
     });
 
     it('should throw for tag starting with "xml" (lowercase)', () => {
-      expect(() => validateXmlTags(['xmltag'], '--splitting-tags')).toThrow(/cannot start with "xml"/);
+      expect(() => validateXmlTags(['xmltag'], '--splitting-tags')).toThrow(
+        /cannot start with "xml"/
+      );
     });
 
     it('should throw for tag starting with "XML" (uppercase)', () => {
-      expect(() => validateXmlTags(['XMLtag'], '--splitting-tags')).toThrow(/cannot start with "xml"/);
+      expect(() => validateXmlTags(['XMLtag'], '--splitting-tags')).toThrow(
+        /cannot start with "xml"/
+      );
     });
 
     it('should throw for tag starting with "Xml" (mixed case)', () => {
-      expect(() => validateXmlTags(['Xmltag'], '--splitting-tags')).toThrow(/cannot start with "xml"/);
+      expect(() => validateXmlTags(['Xmltag'], '--splitting-tags')).toThrow(
+        /cannot start with "xml"/
+      );
     });
 
     it('should throw for tag with invalid characters', () => {
-      expect(() => validateXmlTags(['tag!name'], '--splitting-tags')).toThrow(/Invalid XML tag name/);
+      expect(() => validateXmlTags(['tag!name'], '--splitting-tags')).toThrow(
+        /Invalid XML tag name/
+      );
     });
 
     it('should throw for tag starting with digit', () => {
-      expect(() => validateXmlTags(['1tag'], '--splitting-tags')).toThrow(/Invalid XML tag name/);
+      expect(() => validateXmlTags(['1tag'], '--splitting-tags')).toThrow(
+        /Invalid XML tag name/
+      );
     });
 
     it('should include param name in error message', () => {
-      expect(() => validateXmlTags([''], '--ignore-tags')).toThrow(/--ignore-tags/);
+      expect(() => validateXmlTags([''], '--ignore-tags')).toThrow(
+        /--ignore-tags/
+      );
     });
 
     it('should accept multiple valid tags', () => {
-      expect(() => validateXmlTags(['header', 'footer', 'nav', 'aside'], '--splitting-tags')).not.toThrow();
+      expect(() =>
+        validateXmlTags(
+          ['header', 'footer', 'nav', 'aside'],
+          '--splitting-tags'
+        )
+      ).not.toThrow();
     });
 
     it('should accept empty array', () => {
@@ -536,12 +632,18 @@ describe('translate-utils', () => {
     });
 
     it('should map context', () => {
-      const result = buildTranslationOptions({ to: 'de', context: 'technical document' });
+      const result = buildTranslationOptions({
+        to: 'de',
+        context: 'technical document',
+      });
       expect(result.context).toBe('technical document');
     });
 
     it('should map splitSentences', () => {
-      const result = buildTranslationOptions({ to: 'de', splitSentences: 'nonewlines' });
+      const result = buildTranslationOptions({
+        to: 'de',
+        splitSentences: 'nonewlines',
+      });
       expect(result.splitSentences).toBe('nonewlines');
     });
 
@@ -551,7 +653,10 @@ describe('translate-utils', () => {
     });
 
     it('should map modelType', () => {
-      const result = buildTranslationOptions({ to: 'de', modelType: 'quality_optimized' });
+      const result = buildTranslationOptions({
+        to: 'de',
+        modelType: 'quality_optimized',
+      });
       expect(result.modelType).toBe('quality_optimized');
     });
 
@@ -565,29 +670,42 @@ describe('translate-utils', () => {
     });
 
     it('should reject tagHandlingVersion without tagHandling', () => {
-      expect(() => buildTranslationOptions({ to: 'de', tagHandlingVersion: 'v2' })).toThrow(
-        '--tag-handling-version requires --tag-handling',
-      );
+      expect(() =>
+        buildTranslationOptions({ to: 'de', tagHandlingVersion: 'v2' })
+      ).toThrow('--tag-handling-version requires --tag-handling');
     });
 
     it('should reject a tagHandlingVersion that is neither v1 nor v2', () => {
       expect(() =>
-        buildTranslationOptions({ to: 'de', tagHandling: 'xml', tagHandlingVersion: 'v3' }),
+        buildTranslationOptions({
+          to: 'de',
+          tagHandling: 'xml',
+          tagHandlingVersion: 'v3',
+        })
       ).toThrow('--tag-handling-version must be "v1" or "v2"');
     });
 
     it('should map preserveFormatting when explicitly set', () => {
-      const result = buildTranslationOptions({ to: 'de', preserveFormatting: true });
+      const result = buildTranslationOptions({
+        to: 'de',
+        preserveFormatting: true,
+      });
       expect(result.preserveFormatting).toBe(true);
     });
 
     it('should map preserveFormatting=false when explicitly set', () => {
-      const result = buildTranslationOptions({ to: 'de', preserveFormatting: false });
+      const result = buildTranslationOptions({
+        to: 'de',
+        preserveFormatting: false,
+      });
       expect(result.preserveFormatting).toBe(false);
     });
 
     it('should map showBilledCharacters', () => {
-      const result = buildTranslationOptions({ to: 'de', showBilledCharacters: true });
+      const result = buildTranslationOptions({
+        to: 'de',
+        showBilledCharacters: true,
+      });
       expect(result.showBilledCharacters).toBe(true);
     });
 
@@ -619,40 +737,66 @@ describe('translate-utils', () => {
 
     it('should return true when cachedStats.isFile() returns true', () => {
       const stats = { isFile: () => true } as fs.Stats;
-      expect(isFilePath('anything', stats, mockFileTranslationService)).toBe(true);
+      expect(isFilePath('anything', stats, mockFileTranslationService)).toBe(
+        true
+      );
     });
 
     it('should return true when cachedStats is null and file exists', () => {
       mockedExistsSync.mockReturnValue(true);
-      expect(isFilePath('/some/file.txt', null, mockFileTranslationService)).toBe(true);
+      expect(
+        isFilePath('/some/file.txt', null, mockFileTranslationService)
+      ).toBe(true);
     });
 
     it('should return true when cachedStats is undefined and file exists', () => {
       mockedExistsSync.mockReturnValue(true);
-      expect(isFilePath('/some/file.txt', undefined, mockFileTranslationService)).toBe(true);
+      expect(
+        isFilePath('/some/file.txt', undefined, mockFileTranslationService)
+      ).toBe(true);
     });
 
     it('should return false for URL inputs', () => {
-      expect(isFilePath('http://example.com', null, mockFileTranslationService)).toBe(false);
-      expect(isFilePath('https://example.com/file.txt', null, mockFileTranslationService)).toBe(false);
-      expect(isFilePath('ftp://files.example.com', null, mockFileTranslationService)).toBe(false);
+      expect(
+        isFilePath('http://example.com', null, mockFileTranslationService)
+      ).toBe(false);
+      expect(
+        isFilePath(
+          'https://example.com/file.txt',
+          null,
+          mockFileTranslationService
+        )
+      ).toBe(false);
+      expect(
+        isFilePath('ftp://files.example.com', null, mockFileTranslationService)
+      ).toBe(false);
     });
 
     it('should return true for paths with separators when isSupportedFile returns true', () => {
       mockedExistsSync.mockReturnValue(false);
-      (mockFileTranslationService.isSupportedFile as jest.Mock).mockReturnValue(true);
-      expect(isFilePath('dir/file.txt', null, mockFileTranslationService)).toBe(true);
+      (mockFileTranslationService.isSupportedFile as jest.Mock).mockReturnValue(
+        true
+      );
+      expect(isFilePath('dir/file.txt', null, mockFileTranslationService)).toBe(
+        true
+      );
     });
 
     it('should return false for paths with separators when isSupportedFile returns false', () => {
       mockedExistsSync.mockReturnValue(false);
-      (mockFileTranslationService.isSupportedFile as jest.Mock).mockReturnValue(false);
-      expect(isFilePath('dir/file.xyz', null, mockFileTranslationService)).toBe(false);
+      (mockFileTranslationService.isSupportedFile as jest.Mock).mockReturnValue(
+        false
+      );
+      expect(isFilePath('dir/file.xyz', null, mockFileTranslationService)).toBe(
+        false
+      );
     });
 
     it('should return false for plain text without path separators', () => {
       mockedExistsSync.mockReturnValue(false);
-      expect(isFilePath('Hello world', null, mockFileTranslationService)).toBe(false);
+      expect(isFilePath('Hello world', null, mockFileTranslationService)).toBe(
+        false
+      );
     });
 
     it('should not call existsSync when cachedStats is provided', () => {
@@ -663,9 +807,12 @@ describe('translate-utils', () => {
   });
 
   describe('isTextBasedFile()', () => {
-    it.each(TEXT_BASED_EXTENSIONS)('should return true for %s extension', (ext) => {
-      expect(isTextBasedFile(`file${ext}`)).toBe(true);
-    });
+    it.each(TEXT_BASED_EXTENSIONS)(
+      'should return true for %s extension',
+      (ext) => {
+        expect(isTextBasedFile(`file${ext}`)).toBe(true);
+      }
+    );
 
     it('should be case-insensitive', () => {
       expect(isTextBasedFile('file.TXT')).toBe(true);
@@ -686,9 +833,12 @@ describe('translate-utils', () => {
   });
 
   describe('isStructuredFile()', () => {
-    it.each(STRUCTURED_EXTENSIONS)('should return true for %s extension', (ext) => {
-      expect(isStructuredFile(`file${ext}`)).toBe(true);
-    });
+    it.each(STRUCTURED_EXTENSIONS)(
+      'should return true for %s extension',
+      (ext) => {
+        expect(isStructuredFile(`file${ext}`)).toBe(true);
+      }
+    );
 
     it('should be case-insensitive', () => {
       expect(isStructuredFile('file.JSON')).toBe(true);
@@ -732,10 +882,16 @@ describe('translate-utils', () => {
         resolveGlossaryId: jest.fn().mockResolvedValue('glossary-123'),
       } as unknown as GlossaryService;
 
-      const result = await resolveGlossaryId(mockGlossaryService, 'my-glossary');
+      const result = await resolveGlossaryId(
+        mockGlossaryService,
+        'my-glossary'
+      );
 
       expect(result).toBe('glossary-123');
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', undefined);
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        undefined
+      );
     });
 
     it('should forward the expected language pair for the preflight check', async () => {
@@ -748,10 +904,13 @@ describe('translate-utils', () => {
         targets: ['de'],
       });
 
-      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
-        from: 'en',
-        targets: ['de'],
-      });
+      expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        {
+          from: 'en',
+          targets: ['de'],
+        }
+      );
     });
 
     it('should pass through errors from glossaryService', async () => {
@@ -759,7 +918,9 @@ describe('translate-utils', () => {
         resolveGlossaryId: jest.fn().mockRejectedValue(new Error('Not found')),
       } as unknown as GlossaryService;
 
-      await expect(resolveGlossaryId(mockGlossaryService, 'missing')).rejects.toThrow('Not found');
+      await expect(
+        resolveGlossaryId(mockGlossaryService, 'missing')
+      ).rejects.toThrow('Not found');
     });
   });
 });
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index 8264a54a..5f4f0432 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -3,7 +3,12 @@
  * Covers translate, translateBatch, getUsage, getSupportedLanguages
  */
 
-import { TranslationClient, isTranslationResult, MAX_TRANSLATION_MEMORY_LIST_PAGES, TRANSLATION_MEMORY_LIST_PAGE_SIZE } from '../../src/api/translation-client.js';
+import {
+  TranslationClient,
+  isTranslationResult,
+  MAX_TRANSLATION_MEMORY_LIST_PAGES,
+  TRANSLATION_MEMORY_LIST_PAGE_SIZE,
+} from '../../src/api/translation-client.js';
 import { Logger } from '../../src/utils/logger.js';
 import axios from 'axios';
 
@@ -44,7 +49,7 @@ describe('TranslationClient', () => {
       expect(mockedAxios.create).toHaveBeenCalledWith(
         expect.objectContaining({
           baseURL: 'https://api-free.deepl.com',
-        }),
+        })
       );
     });
   });
@@ -97,7 +102,9 @@ describe('TranslationClient', () => {
     it('should include model_type_used when present', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          translations: [{ text: 'Hola', model_type_used: 'quality_optimized' }],
+          translations: [
+            { text: 'Hola', model_type_used: 'quality_optimized' },
+          ],
         },
         status: 200,
         headers: {},
@@ -148,7 +155,9 @@ describe('TranslationClient', () => {
         headers: {},
       });
 
-      const result = await client.translateBatch(['Hello', 'World'], { targetLang: 'es' });
+      const result = await client.translateBatch(['Hello', 'World'], {
+        targetLang: 'es',
+      });
 
       expect(result).toHaveLength(2);
       expect(result[0]!.text).toBe('Hola');
@@ -206,12 +215,18 @@ describe('TranslationClient', () => {
     };
 
     it('should emit translation_memory_id when translationMemoryId is set', async () => {
-      await client.translate('Hello', { targetLang: 'es', translationMemoryId: TM_UUID });
+      await client.translate('Hello', {
+        targetLang: 'es',
+        translationMemoryId: TM_UUID,
+      });
       expect(getRequestBody()).toContain(`translation_memory_id=${TM_UUID}`);
     });
 
     it('should default translation_memory_threshold to 75 when only translationMemoryId is set', async () => {
-      await client.translate('Hello', { targetLang: 'es', translationMemoryId: TM_UUID });
+      await client.translate('Hello', {
+        targetLang: 'es',
+        translationMemoryId: TM_UUID,
+      });
       expect(getRequestBody()).toContain('translation_memory_threshold=75');
     });
 
@@ -225,7 +240,10 @@ describe('TranslationClient', () => {
     });
 
     it('should omit both keys when translationMemoryId is not set', async () => {
-      await client.translate('Hello', { targetLang: 'es', translationMemoryThreshold: 80 });
+      await client.translate('Hello', {
+        targetLang: 'es',
+        translationMemoryThreshold: 80,
+      });
       const body = getRequestBody();
       expect(body).not.toContain('translation_memory_id');
       expect(body).not.toContain('translation_memory_threshold');
@@ -277,7 +295,10 @@ describe('TranslationClient', () => {
     });
 
     it('should send repeated glossary_ids fields for several glossaries', async () => {
-      await client.translate('Hello', { targetLang: 'es', glossaryIds: [A, B, C] });
+      await client.translate('Hello', {
+        targetLang: 'es',
+        glossaryIds: [A, B, C],
+      });
       const body = getRequestBody();
       expect(body).toContain(`glossary_ids=${A}`);
       expect(body).toContain(`glossary_ids=${B}`);
@@ -286,7 +307,10 @@ describe('TranslationClient', () => {
     });
 
     it('should keep the caller order on the wire rather than sorting it', async () => {
-      await client.translate('Hello', { targetLang: 'es', glossaryIds: [C, A] });
+      await client.translate('Hello', {
+        targetLang: 'es',
+        glossaryIds: [C, A],
+      });
       expect(getRequestBody()).toContain(`glossary_ids=${C}&glossary_ids=${A}`);
     });
 
@@ -297,14 +321,21 @@ describe('TranslationClient', () => {
 
     it('should reject more than five glossaries before sending a request', async () => {
       await expect(
-        client.translate('Hello', { targetLang: 'es', glossaryIds: [A, B, C, A, B, C] }),
+        client.translate('Hello', {
+          targetLang: 'es',
+          glossaryIds: [A, B, C, A, B, C],
+        })
       ).rejects.toThrow(/maximum of 5 glossaries/);
       expect(mockAxiosInstance.request).not.toHaveBeenCalled();
     });
 
     it('should reject glossaryId combined with glossaryIds', async () => {
       await expect(
-        client.translate('Hello', { targetLang: 'es', glossaryId: A, glossaryIds: [B] }),
+        client.translate('Hello', {
+          targetLang: 'es',
+          glossaryId: A,
+          glossaryIds: [B],
+        })
       ).rejects.toThrow(/Cannot combine/);
       expect(mockAxiosInstance.request).not.toHaveBeenCalled();
     });
@@ -315,7 +346,10 @@ describe('TranslationClient', () => {
         status: 200,
         headers: {},
       });
-      await client.translateBatch(['Hello', 'Bye'], { targetLang: 'es', glossaryIds: [A, B] });
+      await client.translateBatch(['Hello', 'Bye'], {
+        targetLang: 'es',
+        glossaryIds: [A, B],
+      });
       const body = getRequestBody();
       expect(body).toContain(`glossary_ids=${A}`);
       expect(body).toContain(`glossary_ids=${B}`);
@@ -409,12 +443,16 @@ describe('TranslationClient', () => {
         headers: {},
       });
 
-      await expect(client.getSupportedLanguages('source')).resolves.toHaveLength(1);
+      await expect(
+        client.getSupportedLanguages('source')
+      ).resolves.toHaveLength(1);
     });
 
     it('should still drop a language whose role flag is explicitly false', async () => {
       mockAxiosInstance.request.mockResolvedValue({
-        data: [{ lang: 'en-gb', name: 'English (British)', usable_as_source: false }],
+        data: [
+          { lang: 'en-gb', name: 'English (British)', usable_as_source: false },
+        ],
         status: 200,
         headers: {},
       });
@@ -425,9 +463,24 @@ describe('TranslationClient', () => {
     it('should return source languages', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [
-          { lang: 'en', name: 'English', usable_as_source: true, usable_as_target: true },
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
-          { lang: 'en-gb', name: 'English (British)', usable_as_source: false, usable_as_target: true },
+          {
+            lang: 'en',
+            name: 'English',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+          {
+            lang: 'en-gb',
+            name: 'English (British)',
+            usable_as_source: false,
+            usable_as_target: true,
+          },
         ],
         status: 200,
         headers: {},
@@ -443,7 +496,7 @@ describe('TranslationClient', () => {
           method: 'GET',
           url: '/v3/languages',
           params: { resource: 'translate_text' },
-        }),
+        })
       );
     });
 
@@ -455,7 +508,10 @@ describe('TranslationClient', () => {
             name: 'Spanish',
             usable_as_source: true,
             usable_as_target: true,
-            features: { formality: { status: 'stable' }, glossary: { status: 'stable' } },
+            features: {
+              formality: { status: 'stable' },
+              glossary: { status: 'stable' },
+            },
           },
           {
             lang: 'ko',
@@ -502,7 +558,13 @@ describe('TranslationClient', () => {
       };
       mockAxiosInstance.request.mockResolvedValue({
         data: [
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true, features },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+            features,
+          },
         ],
         status: 200,
         headers: {},
@@ -518,7 +580,12 @@ describe('TranslationClient', () => {
     it('should omit features when the response carries none', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: [
-          { lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true },
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
         ],
         status: 200,
         headers: {},
@@ -535,7 +602,14 @@ describe('TranslationClient', () => {
 
     it('should fetch the language list once for both roles', async () => {
       mockAxiosInstance.request.mockResolvedValue({
-        data: [{ lang: 'de', name: 'German', usable_as_source: true, usable_as_target: true }],
+        data: [
+          {
+            lang: 'de',
+            name: 'German',
+            usable_as_source: true,
+            usable_as_target: true,
+          },
+        ],
         status: 200,
         headers: {},
       });
@@ -553,7 +627,11 @@ describe('TranslationClient', () => {
       expect.assertions(2);
       const axiosError = Object.assign(new Error('Request failed'), {
         isAxiosError: true,
-        response: { status: 403, data: { message: 'Invalid API key' }, headers: {} },
+        response: {
+          status: 403,
+          data: { message: 'Invalid API key' },
+          headers: {},
+        },
         config: {},
       });
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -587,7 +665,10 @@ describe('TranslationClient', () => {
 
       expect(result).toEqual([tm]);
       expect(mockAxiosInstance.request).toHaveBeenCalledWith(
-        expect.objectContaining({ method: 'GET', url: '/v3/translation_memories' }),
+        expect.objectContaining({
+          method: 'GET',
+          url: '/v3/translation_memories',
+        })
       );
     });
 
@@ -649,7 +730,9 @@ describe('TranslationClient', () => {
         target_lang: 'DE',
       });
       const firstPage = Array.from({ length: pageSize }, (_, i) => buildTm(i));
-      const secondPage = Array.from({ length: pageSize }, (_, i) => buildTm(pageSize + i));
+      const secondPage = Array.from({ length: pageSize }, (_, i) =>
+        buildTm(pageSize + i)
+      );
       const thirdPage = [buildTm(pageSize * 2)];
       const total = pageSize * 2 + 1;
 
@@ -678,8 +761,14 @@ describe('TranslationClient', () => {
       expect(result[pageSize * 2]).toEqual(thirdPage[0]);
       expect(mockAxiosInstance.request).toHaveBeenCalledTimes(3);
       expect(mockAxiosInstance.request.mock.calls[0][0].params).toBeUndefined();
-      expect(mockAxiosInstance.request.mock.calls[1][0].params).toEqual({ page: 1, page_size: pageSize });
-      expect(mockAxiosInstance.request.mock.calls[2][0].params).toEqual({ page: 2, page_size: pageSize });
+      expect(mockAxiosInstance.request.mock.calls[1][0].params).toEqual({
+        page: 1,
+        page_size: pageSize,
+      });
+      expect(mockAxiosInstance.request.mock.calls[2][0].params).toEqual({
+        page: 2,
+        page_size: pageSize,
+      });
     });
 
     it('should stop once accumulated results reach total_count', async () => {
@@ -743,17 +832,26 @@ describe('TranslationClient', () => {
       const fullPage = Array.from({ length: pageSize }, (_, i) => buildTm(i));
 
       mockAxiosInstance.request.mockResolvedValue({
-        data: { translation_memories: fullPage, total_count: Number.MAX_SAFE_INTEGER },
+        data: {
+          translation_memories: fullPage,
+          total_count: Number.MAX_SAFE_INTEGER,
+        },
         status: 200,
         headers: {},
       });
-      const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+      const warnSpy = jest
+        .spyOn(Logger, 'warn')
+        .mockImplementation(() => undefined);
 
       try {
         const result = await client.listTranslationMemories();
 
-        expect(mockAxiosInstance.request).toHaveBeenCalledTimes(MAX_TRANSLATION_MEMORY_LIST_PAGES);
-        expect(result).toHaveLength(MAX_TRANSLATION_MEMORY_LIST_PAGES * pageSize);
+        expect(mockAxiosInstance.request).toHaveBeenCalledTimes(
+          MAX_TRANSLATION_MEMORY_LIST_PAGES
+        );
+        expect(result).toHaveLength(
+          MAX_TRANSLATION_MEMORY_LIST_PAGES * pageSize
+        );
         expect(warnSpy).toHaveBeenCalled();
         const warned = warnSpy.mock.calls.flat().join(' ');
         expect(warned).toMatch(/translation memor/i);
@@ -785,5 +883,4 @@ describe('TranslationClient', () => {
       expect(isTranslationResult({ text: 123 })).toBe(false);
     });
   });
-
 });
diff --git a/tests/unit/translation-memory.test.ts b/tests/unit/translation-memory.test.ts
index 19ed5f41..ea861f1c 100644
--- a/tests/unit/translation-memory.test.ts
+++ b/tests/unit/translation-memory.test.ts
@@ -12,7 +12,9 @@ import type { TranslationMemory } from '../../src/types/index';
 
 const UUID = '11111111-2222-3333-4444-555555555555';
 
-const makeTm = (overrides: Partial<TranslationMemory> = {}): TranslationMemory => ({
+const makeTm = (
+  overrides: Partial<TranslationMemory> = {}
+): TranslationMemory => ({
   translation_memory_id: UUID,
   name: 'my-tm',
   source_language: 'en',
@@ -20,7 +22,9 @@ const makeTm = (overrides: Partial<TranslationMemory> = {}): TranslationMemory =
   ...overrides,
 });
 
-const makeClient = (tms: TranslationMemory[] = []): jest.Mocked<TranslationMemoryLister> => ({
+const makeClient = (
+  tms: TranslationMemory[] = []
+): jest.Mocked<TranslationMemoryLister> => ({
   listTranslationMemories: jest.fn().mockResolvedValue(tms),
 });
 
@@ -104,30 +108,38 @@ describe('resolveTranslationMemoryId', () => {
     });
 
     it('re-runs pair-check when same TM name is requested with a different expected pair (cache does not bypass validation)', async () => {
-      const client = makeClient([makeTm({ source_language: 'en', target_languages: ['de'] })]);
+      const client = makeClient([
+        makeTm({ source_language: 'en', target_languages: ['de'] }),
+      ]);
       const cache = new Map<string, string>();
 
       const first = await resolveTranslationMemoryId(client, 'my-tm', cache, {
-        from: 'en', targets: ['de'],
+        from: 'en',
+        targets: ['de'],
       });
       expect(first).toBe(UUID);
 
       await expect(
         resolveTranslationMemoryId(client, 'my-tm', cache, {
-          from: 'en', targets: ['fr'],
+          from: 'en',
+          targets: ['fr'],
         })
       ).rejects.toThrow('does not support the requested language pair');
     });
 
     it('reuses cached UUID when the same name + same pair is requested twice (no extra list call)', async () => {
-      const client = makeClient([makeTm({ source_language: 'en', target_languages: ['de'] })]);
+      const client = makeClient([
+        makeTm({ source_language: 'en', target_languages: ['de'] }),
+      ]);
       const cache = new Map<string, string>();
 
       const first = await resolveTranslationMemoryId(client, 'my-tm', cache, {
-        from: 'en', targets: ['de'],
+        from: 'en',
+        targets: ['de'],
       });
       const second = await resolveTranslationMemoryId(client, 'my-tm', cache, {
-        from: 'en', targets: ['de'],
+        from: 'en',
+        targets: ['de'],
       });
 
       expect(first).toBe(UUID);
@@ -146,7 +158,10 @@ describe('resolveTranslationMemoryId', () => {
       const cache = new Map<string, string>();
 
       await expect(
-        resolveTranslationMemoryId(client, 'prod-tm\x00', cache, { from: 'en', targets: ['de'] }),
+        resolveTranslationMemoryId(client, 'prod-tm\x00', cache, {
+          from: 'en',
+          targets: ['de'],
+        })
       ).rejects.toThrow(/not found/);
     });
 
@@ -159,28 +174,45 @@ describe('resolveTranslationMemoryId', () => {
       const cache = new Map<string, string>();
 
       await expect(
-        resolveTranslationMemoryId(client, 'prod-tm\u200B', cache, { from: 'en', targets: ['de'] }),
+        resolveTranslationMemoryId(client, 'prod-tm\u200B', cache, {
+          from: 'en',
+          targets: ['de'],
+        })
       ).rejects.toThrow(/not found/);
     });
 
     it('throws ConfigError when two TMs share the same exact name (no first-create-wins)', async () => {
       const first = makeTm({ translation_memory_id: UUID, name: 'shared' });
-      const second = makeTm({ translation_memory_id: '22222222-2222-3333-4444-555555555555', name: 'shared' });
+      const second = makeTm({
+        translation_memory_id: '22222222-2222-3333-4444-555555555555',
+        name: 'shared',
+      });
       const client = makeClient([first, second]);
       const cache = new Map<string, string>();
 
       await expect(
-        resolveTranslationMemoryId(client, 'shared', cache, { from: 'en', targets: ['de'] }),
+        resolveTranslationMemoryId(client, 'shared', cache, {
+          from: 'en',
+          targets: ['de'],
+        })
       ).rejects.toThrow(/Multiple translation memories share the name/);
     });
 
     it('legit unambiguous name still resolves cleanly (no false positive)', async () => {
-      const client = makeClient([makeTm({ translation_memory_id: UUID, name: 'my-tm' })]);
+      const client = makeClient([
+        makeTm({ translation_memory_id: UUID, name: 'my-tm' }),
+      ]);
       const cache = new Map<string, string>();
 
-      const resolved = await resolveTranslationMemoryId(client, 'my-tm', cache, {
-        from: 'en', targets: ['de'],
-      });
+      const resolved = await resolveTranslationMemoryId(
+        client,
+        'my-tm',
+        cache,
+        {
+          from: 'en',
+          targets: ['de'],
+        }
+      );
 
       expect(resolved).toBe(UUID);
     });
@@ -194,9 +226,15 @@ describe('resolveTranslationMemoryId', () => {
       const client = makeClient([legit, filteredSibling]);
       const cache = new Map<string, string>();
 
-      const resolved = await resolveTranslationMemoryId(client, 'prod-tm', cache, {
-        from: 'en', targets: ['de'],
-      });
+      const resolved = await resolveTranslationMemoryId(
+        client,
+        'prod-tm',
+        cache,
+        {
+          from: 'en',
+          targets: ['de'],
+        }
+      );
 
       expect(resolved).toBe(UUID);
     });
@@ -212,7 +250,9 @@ describe('resolveTranslationMemoryId', () => {
       await resolveTranslationMemoryId(client, 'my-tm', cache);
 
       expect(spy).toHaveBeenCalledWith(
-        expect.stringContaining(`Resolved translation memory "my-tm" -> ${UUID}`)
+        expect.stringContaining(
+          `Resolved translation memory "my-tm" -> ${UUID}`
+        )
       );
       spy.mockRestore();
     });
@@ -228,7 +268,9 @@ describe('resolveTranslationMemoryId', () => {
       await resolveTranslationMemoryId(client, 'my-tm', cache);
 
       expect(spy).toHaveBeenCalledWith(
-        expect.stringContaining(`Translation memory cache hit: "my-tm" -> ${UUID}`)
+        expect.stringContaining(
+          `Translation memory cache hit: "my-tm" -> ${UUID}`
+        )
       );
       spy.mockRestore();
     });
@@ -251,7 +293,7 @@ describe('resolveTranslationMemoryId', () => {
       const err = thrown as ConfigError;
       expect(err.message).toBe('Translation memory "missing-tm" not found');
       expect(err.suggestion).toBe(
-        'Pass the UUID directly, or check your translation memories on the DeepL dashboard.',
+        'Pass the UUID directly, or check your translation memories on the DeepL dashboard.'
       );
       expect(err.exitCode).toBe(7);
     });
@@ -272,7 +314,7 @@ describe('resolveTranslationMemoryId', () => {
 
       expect(thrown).toBeInstanceOf(ConfigError);
       expect((thrown as ConfigError).message).toBe(
-        `Translation memory "${expectedName}" not found`,
+        `Translation memory "${expectedName}" not found`
       );
     });
   });
@@ -298,7 +340,7 @@ describe('resolveTranslationMemoryId', () => {
         resolveTranslationMemoryId(client, 'my-tm', cache, {
           from: 'fr',
           targets: ['de'],
-        }),
+        })
       ).rejects.toBeInstanceOf(ConfigError);
     });
 
@@ -310,7 +352,7 @@ describe('resolveTranslationMemoryId', () => {
         resolveTranslationMemoryId(client, 'my-tm', cache, {
           from: 'en',
           targets: ['fr'],
-        }),
+        })
       ).rejects.toBeInstanceOf(ConfigError);
     });
 
@@ -322,7 +364,7 @@ describe('resolveTranslationMemoryId', () => {
         resolveTranslationMemoryId(client, 'my-tm', cache, {
           from: 'en',
           targets: ['de', 'fr'],
-        }),
+        })
       ).rejects.toBeInstanceOf(ConfigError);
     });
 
@@ -334,7 +376,7 @@ describe('resolveTranslationMemoryId', () => {
         resolveTranslationMemoryId(client, 'my-tm', cache, {
           from: 'fr',
           targets: ['de'],
-        }),
+        })
       ).rejects.toBeInstanceOf(ConfigError);
 
       expect(cache.has('my-tm')).toBe(false);
diff --git a/tests/unit/translation-options-factory.test.ts b/tests/unit/translation-options-factory.test.ts
index c8bd1f5c..7f0ed0ed 100644
--- a/tests/unit/translation-options-factory.test.ts
+++ b/tests/unit/translation-options-factory.test.ts
@@ -1,4 +1,7 @@
-import { buildBaseTranslationOptions, applySharedTmAndGlossary } from '../../src/cli/commands/translate/translation-options-factory';
+import {
+  buildBaseTranslationOptions,
+  applySharedTmAndGlossary,
+} from '../../src/cli/commands/translate/translation-options-factory';
 import type { TranslateOptions } from '../../src/cli/commands/translate/types';
 import type { GlossaryService } from '../../src/services/glossary';
 import type { TranslationService } from '../../src/services/translation';
@@ -17,37 +20,58 @@ describe('translation-options-factory', () => {
     });
 
     it('maps formality', () => {
-      const result = buildBaseTranslationOptions({ to: 'de', formality: 'more' });
+      const result = buildBaseTranslationOptions({
+        to: 'de',
+        formality: 'more',
+      });
       expect(result.formality).toBe('more');
     });
 
     it('maps glossary into options.glossary but does NOT set glossaryId (resolution is async)', () => {
-      const result = buildBaseTranslationOptions({ to: 'de', glossary: ['my-glossary'] });
+      const result = buildBaseTranslationOptions({
+        to: 'de',
+        glossary: ['my-glossary'],
+      });
       expect(result.glossaryId).toBeUndefined();
     });
 
     it('maps modelType', () => {
-      const result = buildBaseTranslationOptions({ to: 'de', modelType: 'quality_optimized' });
+      const result = buildBaseTranslationOptions({
+        to: 'de',
+        modelType: 'quality_optimized',
+      });
       expect(result.modelType).toBe('quality_optimized');
     });
 
     it('maps preserveFormatting=true', () => {
-      const result = buildBaseTranslationOptions({ to: 'de', preserveFormatting: true });
+      const result = buildBaseTranslationOptions({
+        to: 'de',
+        preserveFormatting: true,
+      });
       expect(result.preserveFormatting).toBe(true);
     });
 
     it('maps preserveFormatting=false', () => {
-      const result = buildBaseTranslationOptions({ to: 'de', preserveFormatting: false });
+      const result = buildBaseTranslationOptions({
+        to: 'de',
+        preserveFormatting: false,
+      });
       expect(result.preserveFormatting).toBe(false);
     });
 
     it('maps context string', () => {
-      const result = buildBaseTranslationOptions({ to: 'de', context: 'product ui' });
+      const result = buildBaseTranslationOptions({
+        to: 'de',
+        context: 'product ui',
+      });
       expect(result.context).toBe('product ui');
     });
 
     it('maps showBilledCharacters', () => {
-      const result = buildBaseTranslationOptions({ to: 'de', showBilledCharacters: true });
+      const result = buildBaseTranslationOptions({
+        to: 'de',
+        showBilledCharacters: true,
+      });
       expect(result.showBilledCharacters).toBe(true);
     });
 
@@ -57,7 +81,13 @@ describe('translation-options-factory', () => {
     });
 
     it('produces identical output for the same inputs across invocations (stability)', () => {
-      const opts: TranslateOptions = { to: 'de', from: 'en', formality: 'more', modelType: 'quality_optimized', preserveFormatting: true };
+      const opts: TranslateOptions = {
+        to: 'de',
+        from: 'en',
+        formality: 'more',
+        modelType: 'quality_optimized',
+        preserveFormatting: true,
+      };
       const a = buildBaseTranslationOptions(opts);
       const b = buildBaseTranslationOptions(opts);
       expect(a).toEqual(b);
@@ -74,7 +104,13 @@ describe('translation-options-factory', () => {
       } as unknown as jest.Mocked<GlossaryService>;
       translationSvc = {
         listTranslationMemories: jest.fn().mockResolvedValue([
-          { translation_memory_id: 'tm-uuid-1', name: 'my-tm', source_language: 'en', target_languages: ['de'], ready: true },
+          {
+            translation_memory_id: 'tm-uuid-1',
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+            ready: true,
+          },
         ]),
       } as unknown as jest.Mocked<TranslationService>;
     });
@@ -82,102 +118,158 @@ describe('translation-options-factory', () => {
     it('resolves glossaryId when options.glossary is set', async () => {
       glossarySvc.resolveGlossaryId.mockResolvedValue('glos-123');
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de', glossary: ['my-glossary'] }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de'],
-      });
+      await applySharedTmAndGlossary(
+        base,
+        { to: 'de', glossary: ['my-glossary'] },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de'],
+        }
+      );
       expect(base['glossaryId']).toBe('glos-123');
       // No `from` in these options, so there is no pair to preflight against.
-      expect(glossarySvc.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', undefined);
+      expect(glossarySvc.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        undefined
+      );
     });
 
     it('passes the requested language pair when from and targets are known', async () => {
       glossarySvc.resolveGlossaryId.mockResolvedValue('glos-123');
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de,fr', from: 'en', glossary: ['my-glossary'] }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de', 'fr'],
-      });
-      expect(glossarySvc.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
-        from: 'en',
-        targets: ['de', 'fr'],
-      });
+      await applySharedTmAndGlossary(
+        base,
+        { to: 'de,fr', from: 'en', glossary: ['my-glossary'] },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de', 'fr'],
+        }
+      );
+      expect(glossarySvc.resolveGlossaryId).toHaveBeenCalledWith(
+        'my-glossary',
+        {
+          from: 'en',
+          targets: ['de', 'fr'],
+        }
+      );
     });
 
     it('skips glossary resolution when options.glossary is absent', async () => {
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de' }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de'],
-      });
+      await applySharedTmAndGlossary(
+        base,
+        { to: 'de' },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de'],
+        }
+      );
       expect(base['glossaryId']).toBeUndefined();
       expect(glossarySvc.resolveGlossaryId).not.toHaveBeenCalled();
     });
 
     it('resolves TM id and sets threshold when options.translationMemory is set', async () => {
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de', from: 'en', translationMemory: 'my-tm', tmThreshold: 80 }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de'],
-      });
+      await applySharedTmAndGlossary(
+        base,
+        { to: 'de', from: 'en', translationMemory: 'my-tm', tmThreshold: 80 },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de'],
+        }
+      );
       expect(base['translationMemoryId']).toBe('tm-uuid-1');
       expect(base['translationMemoryThreshold']).toBe(80);
     });
 
     it('defaults modelType to quality_optimized when TM is set and modelType was absent', async () => {
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de', from: 'en', translationMemory: 'my-tm' }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de'],
-      });
+      await applySharedTmAndGlossary(
+        base,
+        { to: 'de', from: 'en', translationMemory: 'my-tm' },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de'],
+        }
+      );
       expect(base['modelType']).toBe('quality_optimized');
     });
 
     it('preserves an already-set modelType when TM is also set', async () => {
-      const base: Record<string, unknown> = { targetLang: 'de', modelType: 'quality_optimized' };
-      await applySharedTmAndGlossary(base, { to: 'de', from: 'en', translationMemory: 'my-tm', modelType: 'quality_optimized' }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de'],
-      });
+      const base: Record<string, unknown> = {
+        targetLang: 'de',
+        modelType: 'quality_optimized',
+      };
+      await applySharedTmAndGlossary(
+        base,
+        {
+          to: 'de',
+          from: 'en',
+          translationMemory: 'my-tm',
+          modelType: 'quality_optimized',
+        },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de'],
+        }
+      );
       expect(base['modelType']).toBe('quality_optimized');
     });
 
     it('omits translationMemoryThreshold when tmThreshold is undefined', async () => {
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de', from: 'en', translationMemory: 'my-tm' }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de'],
-      });
+      await applySharedTmAndGlossary(
+        base,
+        { to: 'de', from: 'en', translationMemory: 'my-tm' },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de'],
+        }
+      );
       expect(base['translationMemoryThreshold']).toBeUndefined();
     });
 
     it('resolves TM for a multi-target list of languages', async () => {
       translationSvc.listTranslationMemories = jest.fn().mockResolvedValue([
-        { translation_memory_id: 'tm-multi', name: 'multi-tm', source_language: 'en', target_languages: ['de'], ready: true },
+        {
+          translation_memory_id: 'tm-multi',
+          name: 'multi-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+          ready: true,
+        },
       ]) as never;
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de', from: 'en', translationMemory: 'multi-tm' }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de'], // single-pair TMs for each target — here one target matches
-      });
+      await applySharedTmAndGlossary(
+        base,
+        { to: 'de', from: 'en', translationMemory: 'multi-tm' },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de'], // single-pair TMs for each target — here one target matches
+        }
+      );
       expect(base['translationMemoryId']).toBe('tm-multi');
     });
 
     it('skips TM block when options.translationMemory is absent', async () => {
       const base: Record<string, unknown> = { targetLang: 'de' };
-      await applySharedTmAndGlossary(base, { to: 'de' }, {
-        glossaryService: glossarySvc,
-        translationService: translationSvc,
-        targets: ['de'],
-      });
+      await applySharedTmAndGlossary(
+        base,
+        { to: 'de' },
+        {
+          glossaryService: glossarySvc,
+          translationService: translationSvc,
+          targets: ['de'],
+        }
+      );
       expect(base['translationMemoryId']).toBeUndefined();
       expect(base['translationMemoryThreshold']).toBeUndefined();
     });
@@ -236,7 +328,13 @@ describe('translation-options-factory', () => {
       } as unknown as jest.Mocked<GlossaryService>;
       const translationSvc = {
         listTranslationMemories: jest.fn().mockResolvedValue([
-          { translation_memory_id: 'tm-1', name: 'my-tm', source_language: 'en', target_languages: ['de'], ready: true },
+          {
+            translation_memory_id: 'tm-1',
+            name: 'my-tm',
+            source_language: 'en',
+            target_languages: ['de'],
+            ready: true,
+          },
         ]),
       } as unknown as jest.Mocked<TranslationService>;
 
diff --git a/tests/unit/translation-service.test.ts b/tests/unit/translation-service.test.ts
index e203e6c0..5fb11b14 100644
--- a/tests/unit/translation-service.test.ts
+++ b/tests/unit/translation-service.test.ts
@@ -2,14 +2,20 @@
  * Tests for TranslationService
  */
 
- 
-
-import { TranslationService, MAX_TEXT_BYTES, MULTI_TARGET_CONCURRENCY } from '../../src/services/translation';
+import {
+  TranslationService,
+  MAX_TEXT_BYTES,
+  MULTI_TARGET_CONCURRENCY,
+} from '../../src/services/translation';
 import { DeepLClient, TranslationResult } from '../../src/api/deepl-client';
 import { ConfigService } from '../../src/storage/config';
 import { CacheService } from '../../src/storage/cache';
 import { Language } from '../../src/types';
-import { createMockDeepLClient, createMockConfigService, createMockCacheService } from '../helpers/mock-factories';
+import {
+  createMockDeepLClient,
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
 
 // Mock dependencies
 jest.mock('../../src/api/deepl-client');
@@ -48,14 +54,17 @@ describe('TranslationService', () => {
 
     mockCacheService = createMockCacheService();
 
-    translationService = new TranslationService(mockDeepLClient, mockConfigService, mockCacheService);
+    translationService = new TranslationService(
+      mockDeepLClient,
+      mockConfigService,
+      mockCacheService
+    );
   });
 
   describe('initialization', () => {
     it('should create a TranslationService instance', () => {
       expect(translationService).toBeInstanceOf(TranslationService);
     });
-
   });
 
   describe('translate()', () => {
@@ -96,7 +105,6 @@ describe('TranslationService', () => {
         auth: {},
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
-
       });
 
       mockDeepLClient.translate.mockResolvedValue({
@@ -123,12 +131,15 @@ describe('TranslationService', () => {
           formality: 'more',
           preserveFormatting: true,
         },
-        cache: { enabled: true, maxSize: 1024 * 1024 * 1024, ttl: 30 * 24 * 60 * 60 },
+        cache: {
+          enabled: true,
+          maxSize: 1024 * 1024 * 1024,
+          ttl: 30 * 24 * 60 * 60,
+        },
         api: { baseUrl: 'https://api.deepl.com/v2', usePro: true },
         auth: {},
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
-
       });
 
       mockDeepLClient.translate.mockResolvedValue({
@@ -157,7 +168,6 @@ describe('TranslationService', () => {
 
     it('should throw error when no target language specified', async () => {
       await expect(
-         
         translationService.translate('Hello', {} as any)
       ).rejects.toThrow('Target language is required');
     });
@@ -289,10 +299,20 @@ describe('TranslationService', () => {
 
     it('should handle batch size limits (50 texts per batch)', async () => {
       // Create 100 UNIQUE texts to avoid deduplication
-      const largeTextArray = Array(100).fill(0).map((_, i) => `test${i}`);
+      const largeTextArray = Array(100)
+        .fill(0)
+        .map((_, i) => `test${i}`);
       mockDeepLClient.translateBatch
-        .mockResolvedValueOnce(Array(50).fill(0).map((_, i) => ({ text: `traducido${i}` })))
-        .mockResolvedValueOnce(Array(50).fill(0).map((_, i) => ({ text: `traducido${i + 50}` })));
+        .mockResolvedValueOnce(
+          Array(50)
+            .fill(0)
+            .map((_, i) => ({ text: `traducido${i}` }))
+        )
+        .mockResolvedValueOnce(
+          Array(50)
+            .fill(0)
+            .map((_, i) => ({ text: `traducido${i + 50}` }))
+        );
 
       await translationService.translateBatch(largeTextArray, {
         targetLang: 'es',
@@ -305,14 +325,20 @@ describe('TranslationService', () => {
     it('should correctly map results when first batch fails (CRITICAL BUG #3)', async () => {
       // This test demonstrates the critical index mismatch bug
       // Scenario: 100 texts, first batch (50 texts) fails, second batch (50 texts) succeeds
-      const batch1Texts = Array(50).fill(0).map((_, i) => `Text${i}`);
-      const batch2Texts = Array(50).fill(0).map((_, i) => `Text${i + 50}`);
+      const batch1Texts = Array(50)
+        .fill(0)
+        .map((_, i) => `Text${i}`);
+      const batch2Texts = Array(50)
+        .fill(0)
+        .map((_, i) => `Text${i + 50}`);
       const allTexts = [...batch1Texts, ...batch2Texts];
 
       // First batch fails, second batch succeeds
       mockDeepLClient.translateBatch
         .mockRejectedValueOnce(new Error('API error for first batch'))
-        .mockResolvedValueOnce(batch2Texts.map(t => ({ text: `${t}_translated` })));
+        .mockResolvedValueOnce(
+          batch2Texts.map((t) => ({ text: `${t}_translated` }))
+        );
 
       const results = await translationService.translateBatch(allTexts, {
         targetLang: 'es',
@@ -336,7 +362,7 @@ describe('TranslationService', () => {
       expect(cacheSetCalls.length).toBe(50); // 50 successful translations cached
 
       // Verify a specific text was cached correctly
-      const text55CacheCall = cacheSetCalls.find(call => {
+      const text55CacheCall = cacheSetCalls.find((call) => {
         const result = call[1] as TranslationResult;
         return result.text === 'Text55_translated';
       });
@@ -346,12 +372,18 @@ describe('TranslationService', () => {
     it('should handle partial batch failures correctly', async () => {
       // Test with 100 texts split into 2 batches (50 each)
       // Batch 1 succeeds, Batch 2 fails
-      const batch1Texts = Array(50).fill(0).map((_, i) => `Text${i}`);
-      const batch2Texts = Array(50).fill(0).map((_, i) => `Text${i + 50}`);
+      const batch1Texts = Array(50)
+        .fill(0)
+        .map((_, i) => `Text${i}`);
+      const batch2Texts = Array(50)
+        .fill(0)
+        .map((_, i) => `Text${i + 50}`);
       const allTexts = [...batch1Texts, ...batch2Texts];
 
       mockDeepLClient.translateBatch
-        .mockResolvedValueOnce(batch1Texts.map(t => ({ text: `${t}_translated` }))) // Batch 1 succeeds
+        .mockResolvedValueOnce(
+          batch1Texts.map((t) => ({ text: `${t}_translated` }))
+        ) // Batch 1 succeeds
         .mockRejectedValueOnce(new Error('API error for second batch')); // Batch 2 fails
 
       const results = await translationService.translateBatch(allTexts, {
@@ -376,13 +408,13 @@ describe('TranslationService', () => {
       // This test demonstrates the duplicate text bug
       // When the same text appears multiple times, all occurrences should get translations
       mockDeepLClient.translateBatch.mockResolvedValue([
-        { text: 'Hola' },     // Translation for "Hello"
-        { text: 'Mundo' },    // Translation for "World"
+        { text: 'Hola' }, // Translation for "Hello"
+        { text: 'Mundo' }, // Translation for "World"
       ]);
 
       // Input has "Hello" twice - both should be translated
       const results = await translationService.translateBatch(
-        ['Hello', 'Hello', 'World'],  // "Hello" appears twice
+        ['Hello', 'Hello', 'World'], // "Hello" appears twice
         { targetLang: 'es' }
       );
 
@@ -391,12 +423,12 @@ describe('TranslationService', () => {
 
       // Both "Hello" instances should have translations
       expect(results[0]?.text).toBe('Hola');
-      expect(results[1]?.text).toBe('Hola');  // Second "Hello" should also be translated
+      expect(results[1]?.text).toBe('Hola'); // Second "Hello" should also be translated
       expect(results[2]?.text).toBe('Mundo');
 
       // Verify API was called with deduplicated texts (only unique texts sent)
       expect(mockDeepLClient.translateBatch).toHaveBeenCalledWith(
-        ['Hello', 'World'],  // Deduplicated!
+        ['Hello', 'World'], // Deduplicated!
         expect.any(Object)
       );
     });
@@ -429,43 +461,49 @@ describe('TranslationService', () => {
       const resolvers: Array<(value: { text: string }) => void> = [];
 
       mockDeepLClient.translate.mockImplementation(
-        () => new Promise<{ text: string }>((resolve) => {
-          resolvers.push(resolve);
-        })
+        () =>
+          new Promise<{ text: string }>((resolve) => {
+            resolvers.push(resolve);
+          })
       );
 
-      const resultPromise = translationService.translateToMultiple('Hello', langs);
+      const resultPromise = translationService.translateToMultiple(
+        'Hello',
+        langs
+      );
 
       // With 3 languages and concurrency limit of 5, all 3 should start immediately
-      await new Promise(r => setTimeout(r, 10));
+      await new Promise((r) => setTimeout(r, 10));
       expect(resolvers).toHaveLength(3);
 
-      resolvers.forEach(r => r({ text: 'Translated' }));
+      resolvers.forEach((r) => r({ text: 'Translated' }));
       const results = await resultPromise;
       expect(results).toHaveLength(3);
     });
 
     it('should enforce concurrency limit when target languages exceed it', async () => {
       const langs = Array.from(
-        { length: MULTI_TARGET_CONCURRENCY + 3 }, (_, i) => `lang${i}`
+        { length: MULTI_TARGET_CONCURRENCY + 3 },
+        (_, i) => `lang${i}`
       ) as Language[];
       let inflight = 0;
       let maxInflight = 0;
 
-      mockDeepLClient.translate.mockImplementation(
-        () => {
-          inflight++;
-          maxInflight = Math.max(maxInflight, inflight);
-          return new Promise<{ text: string }>((resolve) => {
-            setTimeout(() => {
-              inflight--;
-              resolve({ text: 'Translated' });
-            }, 5);
-          });
-        }
-      );
+      mockDeepLClient.translate.mockImplementation(() => {
+        inflight++;
+        maxInflight = Math.max(maxInflight, inflight);
+        return new Promise<{ text: string }>((resolve) => {
+          setTimeout(() => {
+            inflight--;
+            resolve({ text: 'Translated' });
+          }, 5);
+        });
+      });
 
-      const results = await translationService.translateToMultiple('Hello', langs);
+      const results = await translationService.translateToMultiple(
+        'Hello',
+        langs
+      );
 
       expect(results).toHaveLength(langs.length);
       expect(maxInflight).toBeLessThanOrEqual(MULTI_TARGET_CONCURRENCY);
@@ -475,7 +513,8 @@ describe('TranslationService', () => {
     it('should process all items even when concurrency is limited', async () => {
       const count = MULTI_TARGET_CONCURRENCY * 3;
       const langs = Array.from(
-        { length: count }, (_, i) => `lang${i}`
+        { length: count },
+        (_, i) => `lang${i}`
       ) as Language[];
 
       mockDeepLClient.translate.mockImplementation(
@@ -483,7 +522,10 @@ describe('TranslationService', () => {
           Promise.resolve({ text: `translated-${opts.targetLang}` })
       );
 
-      const results = await translationService.translateToMultiple('Hello', langs);
+      const results = await translationService.translateToMultiple(
+        'Hello',
+        langs
+      );
 
       expect(results).toHaveLength(count);
       for (let i = 0; i < count; i++) {
@@ -589,9 +631,11 @@ describe('TranslationService', () => {
   describe('preserveVariables()', () => {
     it('should preserve curly brace variables', async () => {
       // Mock to echo back the translated text with placeholders intact
-      mockDeepLClient.translate.mockImplementation((text) => Promise.resolve({
-        text: text.replace('Hello', 'Hola'),
-      }));
+      mockDeepLClient.translate.mockImplementation((text) =>
+        Promise.resolve({
+          text: text.replace('Hello', 'Hola'),
+        })
+      );
 
       const result = await translationService.translate('Hello {name}', {
         targetLang: 'es',
@@ -601,9 +645,11 @@ describe('TranslationService', () => {
     });
 
     it('should preserve dollar sign variables', async () => {
-      mockDeepLClient.translate.mockImplementation((text) => Promise.resolve({
-        text: text.replace('Hello', 'Hola'),
-      }));
+      mockDeepLClient.translate.mockImplementation((text) =>
+        Promise.resolve({
+          text: text.replace('Hello', 'Hola'),
+        })
+      );
 
       const result = await translationService.translate('Hello ${name}', {
         targetLang: 'es',
@@ -613,37 +659,58 @@ describe('TranslationService', () => {
     });
 
     it('should preserve printf-style variables', async () => {
-      mockDeepLClient.translate.mockImplementation((text) => Promise.resolve({
-        text: text.replace('Hello', 'Hola').replace('you are', 'tienes').replace('years old', 'años'),
-      }));
+      mockDeepLClient.translate.mockImplementation((text) =>
+        Promise.resolve({
+          text: text
+            .replace('Hello', 'Hola')
+            .replace('you are', 'tienes')
+            .replace('years old', 'años'),
+        })
+      );
 
-      const result = await translationService.translate('Hello %s, you are %d years old', {
-        targetLang: 'es',
-      });
+      const result = await translationService.translate(
+        'Hello %s, you are %d years old',
+        {
+          targetLang: 'es',
+        }
+      );
 
       expect(result.text).toBe('Hola %s, tienes %d años');
     });
 
     it('should preserve numbered placeholders', async () => {
-      mockDeepLClient.translate.mockImplementation((text) => Promise.resolve({
-        text: text.replace('Hello', 'Hola').replace('you are', 'tienes').replace('years old', 'años'),
-      }));
+      mockDeepLClient.translate.mockImplementation((text) =>
+        Promise.resolve({
+          text: text
+            .replace('Hello', 'Hola')
+            .replace('you are', 'tienes')
+            .replace('years old', 'años'),
+        })
+      );
 
-      const result = await translationService.translate('Hello {0}, you are {1} years old', {
-        targetLang: 'es',
-      });
+      const result = await translationService.translate(
+        'Hello {0}, you are {1} years old',
+        {
+          targetLang: 'es',
+        }
+      );
 
       expect(result.text).toBe('Hola {0}, tienes {1} años');
     });
 
     it('should preserve multiple variable types', async () => {
-      mockDeepLClient.translate.mockImplementation((text) => Promise.resolve({
-        text: text.replace('has', 'tiene').replace('and', 'y'),
-      }));
+      mockDeepLClient.translate.mockImplementation((text) =>
+        Promise.resolve({
+          text: text.replace('has', 'tiene').replace('and', 'y'),
+        })
+      );
 
-      const result = await translationService.translate('{name} has ${count} and %s', {
-        targetLang: 'es',
-      });
+      const result = await translationService.translate(
+        '{name} has ${count} and %s',
+        {
+          targetLang: 'es',
+        }
+      );
 
       // Variables are preserved, though order may change based on translation
       expect(result.text).toContain('{name}');
@@ -653,11 +720,16 @@ describe('TranslationService', () => {
 
     it('should preserve many variables efficiently (Issue #7)', async () => {
       // Test with many variables to ensure efficient placeholder generation
-      const text = Array(100).fill(0).map((_, i) => `{var${i}}`).join(' ');
-
-      mockDeepLClient.translate.mockImplementation((translatedText) => Promise.resolve({
-        text: translatedText, // Echo back with placeholders
-      }));
+      const text = Array(100)
+        .fill(0)
+        .map((_, i) => `{var${i}}`)
+        .join(' ');
+
+      mockDeepLClient.translate.mockImplementation((translatedText) =>
+        Promise.resolve({
+          text: translatedText, // Echo back with placeholders
+        })
+      );
 
       const result = await translationService.translate(text, {
         targetLang: 'es',
@@ -670,13 +742,18 @@ describe('TranslationService', () => {
     });
 
     it('should handle duplicate variable names correctly', async () => {
-      mockDeepLClient.translate.mockImplementation((text) => Promise.resolve({
-        text: text.replace('and', 'y'),
-      }));
+      mockDeepLClient.translate.mockImplementation((text) =>
+        Promise.resolve({
+          text: text.replace('and', 'y'),
+        })
+      );
 
-      const result = await translationService.translate('{name} and {name} and {name}', {
-        targetLang: 'es',
-      });
+      const result = await translationService.translate(
+        '{name} and {name} and {name}',
+        {
+          targetLang: 'es',
+        }
+      );
 
       // Should preserve all three {name} instances
       const nameCount = (result.text.match(/\{name\}/g) ?? []).length;
@@ -760,7 +837,8 @@ describe('TranslationService', () => {
         { language: 'es', name: 'Spanish' },
       ]);
 
-      const languages = await translationService.getSupportedLanguages('source');
+      const languages =
+        await translationService.getSupportedLanguages('source');
 
       expect(languages).toHaveLength(2);
       expect(languages[0]?.language).toBe('en');
@@ -773,7 +851,8 @@ describe('TranslationService', () => {
         { language: 'fr', name: 'French' },
       ]);
 
-      const languages = await translationService.getSupportedLanguages('target');
+      const languages =
+        await translationService.getSupportedLanguages('target');
 
       expect(languages).toHaveLength(2);
       expect(languages[0]?.language).toBe('es');
@@ -797,7 +876,9 @@ describe('TranslationService', () => {
       const text = 'a'.repeat(50000);
       mockDeepLClient.translate.mockResolvedValue({ text: 'a'.repeat(50000) });
 
-      const result = await translationService.translate(text, { targetLang: 'es' });
+      const result = await translationService.translate(text, {
+        targetLang: 'es',
+      });
 
       expect(result.text.length).toBe(50000);
       expect(mockDeepLClient.translate).toHaveBeenCalled();
@@ -807,7 +888,9 @@ describe('TranslationService', () => {
       const text = 'a'.repeat(MAX_TEXT_BYTES);
       mockDeepLClient.translate.mockResolvedValue({ text });
 
-      const result = await translationService.translate(text, { targetLang: 'es' });
+      const result = await translationService.translate(text, {
+        targetLang: 'es',
+      });
 
       expect(result.text).toBe(text);
     });
@@ -826,7 +909,9 @@ describe('TranslationService', () => {
 
       await expect(
         translationService.translate(text, { targetLang: 'es' })
-      ).rejects.toThrow(`${expectedBytes} bytes exceeds the ${MAX_TEXT_BYTES} byte limit`);
+      ).rejects.toThrow(
+        `${expectedBytes} bytes exceeds the ${MAX_TEXT_BYTES} byte limit`
+      );
     });
 
     it('should suggest splitting text in the error message', async () => {
@@ -834,7 +919,9 @@ describe('TranslationService', () => {
 
       await expect(
         translationService.translate(text, { targetLang: 'es' })
-      ).rejects.toThrow('Split the text into smaller chunks or use file translation');
+      ).rejects.toThrow(
+        'Split the text into smaller chunks or use file translation'
+      );
     });
 
     it('should measure multi-byte characters correctly', async () => {
@@ -844,7 +931,9 @@ describe('TranslationService', () => {
       const textAtLimit = cjkChar.repeat(charCount);
       mockDeepLClient.translate.mockResolvedValue({ text: textAtLimit });
 
-      const result = await translationService.translate(textAtLimit, { targetLang: 'en' });
+      const result = await translationService.translate(textAtLimit, {
+        targetLang: 'en',
+      });
       expect(result.text).toBe(textAtLimit);
 
       // One more character pushes it over
@@ -868,10 +957,9 @@ describe('TranslationService', () => {
       const oversizedText = 'a'.repeat(MAX_TEXT_BYTES + 1);
 
       await expect(
-        translationService.translateBatch(
-          ['Hello', oversizedText, 'World'],
-          { targetLang: 'es' }
-        )
+        translationService.translateBatch(['Hello', oversizedText, 'World'], {
+          targetLang: 'es',
+        })
       ).rejects.toThrow('Text at index 1 too large');
     });
 
@@ -888,10 +976,9 @@ describe('TranslationService', () => {
         { text: 'B-translated' },
       ]);
 
-      const results = await translationService.translateBatch(
-        [text1, text2],
-        { targetLang: 'es' },
-      );
+      const results = await translationService.translateBatch([text1, text2], {
+        targetLang: 'es',
+      });
 
       expect(results).toHaveLength(2);
       expect(results[0]?.text).toBe('A-translated');
@@ -986,7 +1073,9 @@ describe('TranslationService', () => {
         text: 'Hola (cached)',
       });
 
-      const result = await translationService.translate('Hello', { targetLang: 'es' });
+      const result = await translationService.translate('Hello', {
+        targetLang: 'es',
+      });
 
       expect(result.text).toBe('Hola (cached)');
       expect(mockDeepLClient.translate).not.toHaveBeenCalled();
@@ -998,7 +1087,9 @@ describe('TranslationService', () => {
         text: 'Hola (cached)',
       });
 
-      const result = await translationService.translate('Hello', { targetLang: 'es' });
+      const result = await translationService.translate('Hello', {
+        targetLang: 'es',
+      });
 
       expect(result.cached).toBe(true);
     });
@@ -1008,7 +1099,9 @@ describe('TranslationService', () => {
         text: 'Hola',
       });
 
-      const result = await translationService.translate('Hello', { targetLang: 'es' });
+      const result = await translationService.translate('Hello', {
+        targetLang: 'es',
+      });
 
       expect(result.cached).toBe(false);
     });
@@ -1053,7 +1146,9 @@ describe('TranslationService', () => {
       expect(mockDeepLClient.translate).toHaveBeenCalledTimes(1);
 
       // Second call with same params
-      const result2 = await translationService.translate('Hello', { targetLang: 'es' });
+      const result2 = await translationService.translate('Hello', {
+        targetLang: 'es',
+      });
       expect(result2.text).toBe('Hola (cached)');
       expect(mockDeepLClient.translate).toHaveBeenCalledTimes(1); // Still only 1 API call
     });
@@ -1161,14 +1256,17 @@ describe('TranslationService', () => {
       const B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
 
       const keysFor = async (
-        optionSets: Array<Record<string, unknown>>,
+        optionSets: Array<Record<string, unknown>>
       ): Promise<string[]> => {
         mockCacheService.get.mockReturnValue(null);
         mockDeepLClient.translate.mockResolvedValue({ text: 'Hola' });
         mockCacheService.set.mockClear();
 
         for (const options of optionSets) {
-          await translationService.translate('Hello', { targetLang: 'es', ...options } as any);
+          await translationService.translate('Hello', {
+            targetLang: 'es',
+            ...options,
+          } as any);
         }
 
         return mockCacheService.set.mock.calls.map((call) => call[0]);
@@ -1183,13 +1281,19 @@ describe('TranslationService', () => {
       });
 
       it('should separate one glossary from two', async () => {
-        const [one, two] = await keysFor([{ glossaryIds: [A] }, { glossaryIds: [A, B] }]);
+        const [one, two] = await keysFor([
+          { glossaryIds: [A] },
+          { glossaryIds: [A, B] },
+        ]);
         expect(one).not.toBe(two);
       });
 
       /** A reordered list is a different request to the API, so the keys must differ. */
       it('should separate the two orderings of the same glossaries', async () => {
-        const [ab, ba] = await keysFor([{ glossaryIds: [A, B] }, { glossaryIds: [B, A] }]);
+        const [ab, ba] = await keysFor([
+          { glossaryIds: [A, B] },
+          { glossaryIds: [B, A] },
+        ]);
         expect(ab).not.toBe(ba);
       });
 
@@ -1209,14 +1313,17 @@ describe('TranslationService', () => {
 
     describe('tag handling version cache keys', () => {
       const keysFor = async (
-        optionSets: Array<Record<string, unknown>>,
+        optionSets: Array<Record<string, unknown>>
       ): Promise<string[]> => {
         mockCacheService.get.mockReturnValue(null);
         mockDeepLClient.translate.mockResolvedValue({ text: 'Hola' });
         mockCacheService.set.mockClear();
 
         for (const options of optionSets) {
-          await translationService.translate('Hello', { targetLang: 'es', ...options } as any);
+          await translationService.translate('Hello', {
+            targetLang: 'es',
+            ...options,
+          } as any);
         }
 
         return mockCacheService.set.mock.calls.map((call) => call[0]);
@@ -1242,21 +1349,27 @@ describe('TranslationService', () => {
 
     describe('cache keys for parameters that change the translation', () => {
       const keysFor = async (
-        optionSets: Array<Record<string, unknown>>,
+        optionSets: Array<Record<string, unknown>>
       ): Promise<string[]> => {
         mockCacheService.get.mockReturnValue(null);
         mockDeepLClient.translate.mockResolvedValue({ text: 'Hola' });
         mockCacheService.set.mockClear();
 
         for (const options of optionSets) {
-          await translationService.translate('Hello', { targetLang: 'es', ...options } as any);
+          await translationService.translate('Hello', {
+            targetLang: 'es',
+            ...options,
+          } as any);
         }
 
         return mockCacheService.set.mock.calls.map((call) => call[0]);
       };
 
       it('should separate a translation-memory request from one without', async () => {
-        const [none, withTm] = await keysFor([{}, { translationMemoryId: 'tm-1' }]);
+        const [none, withTm] = await keysFor([
+          {},
+          { translationMemoryId: 'tm-1' },
+        ]);
         expect(none).not.toBe(withTm);
       });
 
@@ -1359,9 +1472,12 @@ describe('TranslationService', () => {
 
       expect(result.text).toBe('Hello world');
       expect(result.detectedSourceLang).toBe('zh');
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith('你好世界', expect.objectContaining({
-        targetLang: 'en',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        '你好世界',
+        expect.objectContaining({
+          targetLang: 'en',
+        })
+      );
     });
 
     it('should translate CJK Japanese characters', async () => {
@@ -1375,9 +1491,12 @@ describe('TranslationService', () => {
       });
 
       expect(result.text).toBe('Hello');
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith('こんにちは', expect.objectContaining({
-        targetLang: 'en',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        'こんにちは',
+        expect.objectContaining({
+          targetLang: 'en',
+        })
+      );
     });
 
     it('should translate CJK Korean characters', async () => {
@@ -1391,9 +1510,12 @@ describe('TranslationService', () => {
       });
 
       expect(result.text).toBe('Hello');
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith('안녕하세요', expect.objectContaining({
-        targetLang: 'en',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        '안녕하세요',
+        expect.objectContaining({
+          targetLang: 'en',
+        })
+      );
     });
 
     it('should translate Arabic/RTL text', async () => {
@@ -1407,9 +1529,12 @@ describe('TranslationService', () => {
       });
 
       expect(result.text).toBe('Hello world');
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith('مرحبا بالعالم', expect.objectContaining({
-        targetLang: 'en',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        'مرحبا بالعالم',
+        expect.objectContaining({
+          targetLang: 'en',
+        })
+      );
     });
 
     it('should handle text with emoji', async () => {
@@ -1422,9 +1547,12 @@ describe('TranslationService', () => {
       });
 
       expect(result.text).toBe('Hola 🌍🎉');
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith('Hello 🌍🎉', expect.objectContaining({
-        targetLang: 'es',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        'Hello 🌍🎉',
+        expect.objectContaining({
+          targetLang: 'es',
+        })
+      );
     });
 
     it('should handle multi-codepoint emoji (family ZWJ sequence)', async () => {
@@ -1433,14 +1561,20 @@ describe('TranslationService', () => {
         text: `${familyEmoji} familia`,
       });
 
-      const result = await translationService.translate(`${familyEmoji} family`, {
-        targetLang: 'es',
-      });
+      const result = await translationService.translate(
+        `${familyEmoji} family`,
+        {
+          targetLang: 'es',
+        }
+      );
 
       expect(result.text).toBe(`${familyEmoji} familia`);
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith(`${familyEmoji} family`, expect.objectContaining({
-        targetLang: 'es',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        `${familyEmoji} family`,
+        expect.objectContaining({
+          targetLang: 'es',
+        })
+      );
     });
 
     it('should handle combining characters (precomposed)', async () => {
@@ -1454,9 +1588,12 @@ describe('TranslationService', () => {
       });
 
       expect(result.text).toBe(precomposed);
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith(precomposed, expect.objectContaining({
-        targetLang: 'es',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        precomposed,
+        expect.objectContaining({
+          targetLang: 'es',
+        })
+      );
     });
 
     it('should handle combining characters (decomposed)', async () => {
@@ -1470,9 +1607,12 @@ describe('TranslationService', () => {
       });
 
       expect(result.text).toBe(decomposed);
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith(decomposed, expect.objectContaining({
-        targetLang: 'es',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        decomposed,
+        expect.objectContaining({
+          targetLang: 'es',
+        })
+      );
     });
 
     it('should handle mixed scripts in a single string', async () => {
@@ -1486,9 +1626,12 @@ describe('TranslationService', () => {
       });
 
       expect(result.text).toBe('Translated mixed text');
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith(mixedText, expect.objectContaining({
-        targetLang: 'es',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        mixedText,
+        expect.objectContaining({
+          targetLang: 'es',
+        })
+      );
     });
 
     it('should handle surrogate pair characters (astral plane)', async () => {
@@ -1502,9 +1645,12 @@ describe('TranslationService', () => {
       });
 
       expect(result.text).toBe(astralChar);
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith(astralChar, expect.objectContaining({
-        targetLang: 'es',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        astralChar,
+        expect.objectContaining({
+          targetLang: 'es',
+        })
+      );
     });
 
     it('should handle zero-width joiners in text', async () => {
@@ -1573,9 +1719,11 @@ describe('TranslationService', () => {
     });
 
     it('should preserve variables in CJK text', async () => {
-      mockDeepLClient.translate.mockImplementation((text) => Promise.resolve({
-        text: text.replace('こんにちは', 'Hola'),
-      }));
+      mockDeepLClient.translate.mockImplementation((text) =>
+        Promise.resolve({
+          text: text.replace('こんにちは', 'Hola'),
+        })
+      );
 
       const result = await translationService.translate('こんにちは {name}', {
         targetLang: 'es',
@@ -1608,9 +1756,12 @@ describe('TranslationService', () => {
       await translationService.translate('你好', { targetLang: 'en' });
 
       expect(mockCacheService.set).toHaveBeenCalledTimes(1);
-      expect(mockDeepLClient.translate).toHaveBeenCalledWith('你好', expect.objectContaining({
-        targetLang: 'en',
-      }));
+      expect(mockDeepLClient.translate).toHaveBeenCalledWith(
+        '你好',
+        expect.objectContaining({
+          targetLang: 'en',
+        })
+      );
     });
   });
 
@@ -1618,7 +1769,10 @@ describe('TranslationService', () => {
     let cachelessService: TranslationService;
 
     beforeEach(() => {
-      cachelessService = new TranslationService(mockDeepLClient, mockConfigService);
+      cachelessService = new TranslationService(
+        mockDeepLClient,
+        mockConfigService
+      );
     });
 
     it('should translate even though cache.enabled is true in config', async () => {
@@ -1627,7 +1781,9 @@ describe('TranslationService', () => {
         detectedSourceLang: 'en',
       });
 
-      const result = await cachelessService.translate('Hello', { targetLang: 'es' });
+      const result = await cachelessService.translate('Hello', {
+        targetLang: 'es',
+      });
 
       expect(result.text).toBe('Hola');
       expect(mockDeepLClient.translate).toHaveBeenCalledTimes(1);
@@ -1639,11 +1795,13 @@ describe('TranslationService', () => {
         { text: 'Mundo' },
       ]);
 
-      const results = await cachelessService.translateBatch(['Hello', 'World'], { targetLang: 'es' });
+      const results = await cachelessService.translateBatch(
+        ['Hello', 'World'],
+        { targetLang: 'es' }
+      );
 
       expect(results).toHaveLength(2);
       expect(results[0]?.text).toBe('Hola');
     });
   });
-
 });
diff --git a/tests/unit/type-guards.test.ts b/tests/unit/type-guards.test.ts
index 1116f7a7..0f760854 100644
--- a/tests/unit/type-guards.test.ts
+++ b/tests/unit/type-guards.test.ts
@@ -7,12 +7,14 @@ describe('isTranslationResult', () => {
   });
 
   it('should return true with optional fields', () => {
-    expect(isTranslationResult({
-      text: 'Hola',
-      detectedSourceLang: 'EN',
-      billedCharacters: 5,
-      modelTypeUsed: 'quality_optimized',
-    })).toBe(true);
+    expect(
+      isTranslationResult({
+        text: 'Hola',
+        detectedSourceLang: 'EN',
+        billedCharacters: 5,
+        modelTypeUsed: 'quality_optimized',
+      })
+    ).toBe(true);
   });
 
   it('should return false for missing text', () => {
@@ -42,9 +44,9 @@ describe('isTranslationResult', () => {
 
 describe('isWriteImprovementArray', () => {
   it('should return true for valid array', () => {
-    expect(isWriteImprovementArray([
-      { text: 'Improved text', targetLanguage: 'en' },
-    ])).toBe(true);
+    expect(
+      isWriteImprovementArray([{ text: 'Improved text', targetLanguage: 'en' }])
+    ).toBe(true);
   });
 
   it('should return true for empty array', () => {
@@ -52,10 +54,12 @@ describe('isWriteImprovementArray', () => {
   });
 
   it('should return true for multiple items', () => {
-    expect(isWriteImprovementArray([
-      { text: 'First', targetLanguage: 'en' },
-      { text: 'Second', targetLanguage: 'de' },
-    ])).toBe(true);
+    expect(
+      isWriteImprovementArray([
+        { text: 'First', targetLanguage: 'en' },
+        { text: 'Second', targetLanguage: 'de' },
+      ])
+    ).toBe(true);
   });
 
   it('should return false for non-array', () => {
@@ -71,9 +75,7 @@ describe('isWriteImprovementArray', () => {
   });
 
   it('should return false for array with invalid item (missing text)', () => {
-    expect(isWriteImprovementArray([
-      { targetLanguage: 'en' },
-    ])).toBe(false);
+    expect(isWriteImprovementArray([{ targetLanguage: 'en' }])).toBe(false);
   });
 
   it('should return false for array with null item', () => {
diff --git a/tests/unit/types/glossary-types.test.ts b/tests/unit/types/glossary-types.test.ts
index 41c7c13d..96efd61f 100644
--- a/tests/unit/types/glossary-types.test.ts
+++ b/tests/unit/types/glossary-types.test.ts
@@ -62,11 +62,13 @@ describe('normalizeGlossaryInfo', () => {
     const response: GlossaryApiResponse = {
       glossary_id: 'test-123',
       name: 'Valid Glossary',
-      dictionaries: [{
-        source_lang: 'en',
-        target_lang: 'es',
-        entry_count: 5,
-      }],
+      dictionaries: [
+        {
+          source_lang: 'en',
+          target_lang: 'es',
+          entry_count: 5,
+        },
+      ],
       creation_time: '2025-10-13T10:00:00Z',
     };
 
diff --git a/tests/unit/unrecoverable-request-error.test.ts b/tests/unit/unrecoverable-request-error.test.ts
index 20e1a6a9..227e9418 100644
--- a/tests/unit/unrecoverable-request-error.test.ts
+++ b/tests/unit/unrecoverable-request-error.test.ts
@@ -22,19 +22,27 @@ describe('isUnrecoverableRequestError', () => {
       "API error: Value for 'source_lang' not supported.",
       'API error: target_lang not supported',
       'API error: source_lang not supported',
-    ])('should match %s', message => {
-      expect(isUnrecoverableRequestError(new ValidationError(message))).toBe(true);
+    ])('should match %s', (message) => {
+      expect(isUnrecoverableRequestError(new ValidationError(message))).toBe(
+        true
+      );
     });
 
     it('should match regardless of case', () => {
       expect(
-        isUnrecoverableRequestError(new ValidationError("VALUE FOR 'TARGET_LANG' NOT SUPPORTED.")),
+        isUnrecoverableRequestError(
+          new ValidationError("VALUE FOR 'TARGET_LANG' NOT SUPPORTED.")
+        )
       ).toBe(true);
     });
 
     it('should treat a refused key and an exhausted quota as request-wide', () => {
-      expect(isUnrecoverableRequestError(new AuthError('Authentication failed'))).toBe(true);
-      expect(isUnrecoverableRequestError(new QuotaError('Quota exceeded'))).toBe(true);
+      expect(
+        isUnrecoverableRequestError(new AuthError('Authentication failed'))
+      ).toBe(true);
+      expect(
+        isUnrecoverableRequestError(new QuotaError('Quota exceeded'))
+      ).toBe(true);
     });
   });
 
@@ -45,23 +53,29 @@ describe('isUnrecoverableRequestError', () => {
       expect(
         isUnrecoverableRequestError(
           new NetworkError(
-            "Server error (502): upstream unavailable, value for 'target_lang' not supported by shard",
-          ),
-        ),
+            "Server error (502): upstream unavailable, value for 'target_lang' not supported by shard"
+          )
+        )
       ).toBe(false);
     });
 
     it('should not match a rate limit', () => {
-      expect(isUnrecoverableRequestError(new RateLimitError('Rate limit exceeded'))).toBe(false);
+      expect(
+        isUnrecoverableRequestError(new RateLimitError('Rate limit exceeded'))
+      ).toBe(false);
     });
 
     it('should not match an unrelated validation error', () => {
-      expect(isUnrecoverableRequestError(new ValidationError('Text cannot be empty'))).toBe(false);
+      expect(
+        isUnrecoverableRequestError(new ValidationError('Text cannot be empty'))
+      ).toBe(false);
     });
 
     it('should not match a plain Error, whatever it says', () => {
       expect(
-        isUnrecoverableRequestError(new Error("Value for 'target_lang' not supported.")),
+        isUnrecoverableRequestError(
+          new Error("Value for 'target_lang' not supported.")
+        )
       ).toBe(false);
     });
 
diff --git a/tests/unit/usage-command.test.ts b/tests/unit/usage-command.test.ts
index 9220a0a0..ed44c522 100644
--- a/tests/unit/usage-command.test.ts
+++ b/tests/unit/usage-command.test.ts
@@ -2,8 +2,6 @@
  * Tests for Usage Command
  */
 
- 
-
 import { UsageCommand } from '../../src/cli/commands/usage';
 import { createMockUsageService } from '../helpers/mock-factories';
 
@@ -71,25 +69,33 @@ describe('UsageCommand', () => {
     });
 
     it('should handle API errors', async () => {
-      mockService.getUsage = jest.fn().mockRejectedValue(new Error('API error'));
+      mockService.getUsage = jest
+        .fn()
+        .mockRejectedValue(new Error('API error'));
 
       await expect(usageCommand.getUsage()).rejects.toThrow('API error');
     });
 
     it('should handle authentication errors', async () => {
-      mockService.getUsage = jest.fn().mockRejectedValue(
-        new Error('Authentication failed: Invalid API key')
-      );
+      mockService.getUsage = jest
+        .fn()
+        .mockRejectedValue(new Error('Authentication failed: Invalid API key'));
 
-      await expect(usageCommand.getUsage()).rejects.toThrow('Authentication failed: Invalid API key');
+      await expect(usageCommand.getUsage()).rejects.toThrow(
+        'Authentication failed: Invalid API key'
+      );
     });
 
     it('should handle quota exceeded errors', async () => {
-      mockService.getUsage = jest.fn().mockRejectedValue(
-        new Error('Quota exceeded: Character limit reached')
+      mockService.getUsage = jest
+        .fn()
+        .mockRejectedValue(
+          new Error('Quota exceeded: Character limit reached')
+        );
+
+      await expect(usageCommand.getUsage()).rejects.toThrow(
+        'Quota exceeded: Character limit reached'
       );
-
-      await expect(usageCommand.getUsage()).rejects.toThrow('Quota exceeded: Character limit reached');
     });
   });
 
@@ -152,8 +158,16 @@ describe('UsageCommand', () => {
         characterCount: 2150000,
         characterLimit: 20000000,
         products: [
-          { productType: 'translate', characterCount: 900000, apiKeyCharacterCount: 880000 },
-          { productType: 'write', characterCount: 1250000, apiKeyCharacterCount: 1000000 },
+          {
+            productType: 'translate',
+            characterCount: 900000,
+            apiKeyCharacterCount: 880000,
+          },
+          {
+            productType: 'write',
+            characterCount: 1250000,
+            apiKeyCharacterCount: 1000000,
+          },
         ],
       });
 
@@ -185,8 +199,16 @@ describe('UsageCommand', () => {
         startTime: '2025-04-24T14:58:02Z',
         endTime: '2025-05-24T14:58:02Z',
         products: [
-          { productType: 'translate', characterCount: 900000, apiKeyCharacterCount: 880000 },
-          { productType: 'write', characterCount: 1250000, apiKeyCharacterCount: 1000000 },
+          {
+            productType: 'translate',
+            characterCount: 900000,
+            apiKeyCharacterCount: 880000,
+          },
+          {
+            productType: 'write',
+            characterCount: 1250000,
+            apiKeyCharacterCount: 1000000,
+          },
         ],
       });
 
@@ -275,7 +297,9 @@ describe('UsageCommand', () => {
       });
 
       expect(formatted).toContain('Product Breakdown:');
-      expect(formatted).toContain('translate: 5,000 units (API key: 4,500 units)');
+      expect(formatted).toContain(
+        'translate: 5,000 units (API key: 4,500 units)'
+      );
     });
 
     it('should show unlimited for zero API key character limit', () => {
@@ -294,7 +318,11 @@ describe('UsageCommand', () => {
         characterCount: 2150000,
         characterLimit: 20000000,
         products: [
-          { productType: 'translate', characterCount: 900000, apiKeyCharacterCount: 880000 },
+          {
+            productType: 'translate',
+            characterCount: 900000,
+            apiKeyCharacterCount: 880000,
+          },
         ],
       });
 
@@ -315,8 +343,17 @@ describe('UsageCommand', () => {
         characterCount: 2150000,
         characterLimit: 20000000,
         products: [
-          { productType: 'translate', characterCount: 900000, apiKeyCharacterCount: 880000 },
-          { productType: 'speech_to_text', characterCount: 3661000, apiKeyCharacterCount: 3661000, billingUnit: 'milliseconds' },
+          {
+            productType: 'translate',
+            characterCount: 900000,
+            apiKeyCharacterCount: 880000,
+          },
+          {
+            productType: 'speech_to_text',
+            characterCount: 3661000,
+            apiKeyCharacterCount: 3661000,
+            billingUnit: 'milliseconds',
+          },
         ],
       });
 
@@ -401,7 +438,9 @@ describe('UsageCommand', () => {
         ],
       });
 
-      expect(formatted).toContain('speech_to_text: 100h 0m 0s (API key: 24h 23m 0s)');
+      expect(formatted).toContain(
+        'speech_to_text: 100h 0m 0s (API key: 24h 23m 0s)'
+      );
     });
 
     it('should prefer unitCount over apiKeyUnitCount for minutes-billed totals', () => {
@@ -420,7 +459,9 @@ describe('UsageCommand', () => {
         ],
       });
 
-      expect(formatted).toContain('speech_to_text: 2h 0m 0s (API key: 1h 0m 0s)');
+      expect(formatted).toContain(
+        'speech_to_text: 2h 0m 0s (API key: 1h 0m 0s)'
+      );
     });
 
     it('should render camelCase product types with the documented snake_case names', () => {
@@ -428,7 +469,11 @@ describe('UsageCommand', () => {
         characterCount: 0,
         characterLimit: 20000000,
         products: [
-          { productType: 'textTranslation', characterCount: 900000, apiKeyCharacterCount: 880000 },
+          {
+            productType: 'textTranslation',
+            characterCount: 900000,
+            apiKeyCharacterCount: 880000,
+          },
         ],
       });
 
@@ -445,8 +490,17 @@ describe('UsageCommand', () => {
         startTime: '2025-04-24T14:58:02Z',
         endTime: '2025-05-24T14:58:02Z',
         products: [
-          { productType: 'translate', characterCount: 900000, apiKeyCharacterCount: 880000 },
-          { productType: 'speech_to_text', characterCount: 120000, apiKeyCharacterCount: 120000, billingUnit: 'milliseconds' },
+          {
+            productType: 'translate',
+            characterCount: 900000,
+            apiKeyCharacterCount: 880000,
+          },
+          {
+            productType: 'speech_to_text',
+            characterCount: 120000,
+            apiKeyCharacterCount: 120000,
+            billingUnit: 'milliseconds',
+          },
         ],
       });
 
@@ -503,7 +557,11 @@ describe('UsageCommand', () => {
         characterCount: 1000,
         characterLimit: 10000,
         products: [
-          { productType: 'translate', characterCount: 900, apiKeyCharacterCount: 800 },
+          {
+            productType: 'translate',
+            characterCount: 900,
+            apiKeyCharacterCount: 800,
+          },
           {
             productType: 'speech_to_text',
             characterCount: 120000,
diff --git a/tests/unit/utils/glob-prefix.test.ts b/tests/unit/utils/glob-prefix.test.ts
index c3e15555..9aa7cbe1 100644
--- a/tests/unit/utils/glob-prefix.test.ts
+++ b/tests/unit/utils/glob-prefix.test.ts
@@ -4,7 +4,9 @@ import { ConfigError } from '../../../src/utils/errors';
 describe('extractGlobLiteralPrefix', () => {
   describe('clean patterns', () => {
     it('extracts prefix up to the first wildcard segment', () => {
-      expect(extractGlobLiteralPrefix('src/locales/**/*.json')).toBe('src/locales');
+      expect(extractGlobLiteralPrefix('src/locales/**/*.json')).toBe(
+        'src/locales'
+      );
     });
 
     it('returns empty prefix for top-level wildcard pattern', () => {
@@ -12,11 +14,15 @@ describe('extractGlobLiteralPrefix', () => {
     });
 
     it('handles nested literal segments with brace at the end', () => {
-      expect(extractGlobLiteralPrefix('src/app/{foo,bar}/*.json')).toBe('src/app');
+      expect(extractGlobLiteralPrefix('src/app/{foo,bar}/*.json')).toBe(
+        'src/app'
+      );
     });
 
     it('returns the whole pattern when no wildcards are present', () => {
-      expect(extractGlobLiteralPrefix('src/app/routes.ts')).toBe('src/app/routes.ts');
+      expect(extractGlobLiteralPrefix('src/app/routes.ts')).toBe(
+        'src/app/routes.ts'
+      );
     });
 
     it('preserves a leading dot-segment literal', () => {
@@ -36,29 +42,41 @@ describe('extractGlobLiteralPrefix', () => {
     });
 
     it('treats a segment with escaped wildcard as literal', () => {
-      expect(extractGlobLiteralPrefix('src/\\*literal/**/*.ts')).toBe('src/\\*literal');
+      expect(extractGlobLiteralPrefix('src/\\*literal/**/*.ts')).toBe(
+        'src/\\*literal'
+      );
     });
 
     it('preserves an absolute-style prefix within the project root when all literal', () => {
-      expect(extractGlobLiteralPrefix('src/locales/en/**.json')).toBe('src/locales/en');
+      expect(extractGlobLiteralPrefix('src/locales/en/**.json')).toBe(
+        'src/locales/en'
+      );
     });
   });
 
   describe('path-traversal rejection', () => {
     it('rejects a leading parent-directory segment', () => {
-      expect(() => extractGlobLiteralPrefix('../sensitive/**')).toThrow(ConfigError);
+      expect(() => extractGlobLiteralPrefix('../sensitive/**')).toThrow(
+        ConfigError
+      );
     });
 
     it('rejects a mid-pattern parent-directory segment', () => {
-      expect(() => extractGlobLiteralPrefix('src/../etc/**')).toThrow(ConfigError);
+      expect(() => extractGlobLiteralPrefix('src/../etc/**')).toThrow(
+        ConfigError
+      );
     });
 
     it('rejects brace-expansion containing parent-directory', () => {
-      expect(() => extractGlobLiteralPrefix('{..,src}/**/*.json')).toThrow(ConfigError);
+      expect(() => extractGlobLiteralPrefix('{..,src}/**/*.json')).toThrow(
+        ConfigError
+      );
     });
 
     it('rejects nested brace-expansion containing parent-directory', () => {
-      expect(() => extractGlobLiteralPrefix('src/{app,..}/**')).toThrow(ConfigError);
+      expect(() => extractGlobLiteralPrefix('src/{app,..}/**')).toThrow(
+        ConfigError
+      );
     });
 
     it('rejects extglob containing parent-directory', () => {
@@ -66,7 +84,9 @@ describe('extractGlobLiteralPrefix', () => {
     });
 
     it('rejects extglob alternation containing parent-directory', () => {
-      expect(() => extractGlobLiteralPrefix('src/+(foo|..)/**')).toThrow(ConfigError);
+      expect(() => extractGlobLiteralPrefix('src/+(foo|..)/**')).toThrow(
+        ConfigError
+      );
     });
 
     it('rejects bare ".." pattern', () => {
diff --git a/tests/unit/utils/icu-preservation.test.ts b/tests/unit/utils/icu-preservation.test.ts
index 608465a3..4919890a 100644
--- a/tests/unit/utils/icu-preservation.test.ts
+++ b/tests/unit/utils/icu-preservation.test.ts
@@ -4,17 +4,23 @@ describe('icu-preservation', () => {
   describe('parseIcu', () => {
     describe('detection', () => {
       it('should detect plural pattern', () => {
-        const result = parseIcu('{count, plural, one {# item} other {# items}}');
+        const result = parseIcu(
+          '{count, plural, one {# item} other {# items}}'
+        );
         expect(result.isIcu).toBe(true);
       });
 
       it('should detect select pattern', () => {
-        const result = parseIcu('{gender, select, male {He} female {She} other {They}}');
+        const result = parseIcu(
+          '{gender, select, male {He} female {She} other {They}}'
+        );
         expect(result.isIcu).toBe(true);
       });
 
       it('should detect selectordinal pattern', () => {
-        const result = parseIcu('{count, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}');
+        const result = parseIcu(
+          '{count, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}'
+        );
         expect(result.isIcu).toBe(true);
       });
 
@@ -41,7 +47,9 @@ describe('icu-preservation', () => {
 
     describe('plural extraction', () => {
       it('should extract leaf text from plural branches', () => {
-        const result = parseIcu('{count, plural, one {# item} other {# items}}');
+        const result = parseIcu(
+          '{count, plural, one {# item} other {# items}}'
+        );
         expect(result.isIcu).toBe(true);
         expect(result.segments).toHaveLength(2);
         expect(result.segments[0]!.text).toBe('# item');
@@ -49,13 +57,17 @@ describe('icu-preservation', () => {
       });
 
       it('should mark segments as plural branches', () => {
-        const result = parseIcu('{count, plural, one {# item} other {# items}}');
+        const result = parseIcu(
+          '{count, plural, one {# item} other {# items}}'
+        );
         expect(result.segments[0]!.isPluralBranch).toBe(true);
         expect(result.segments[1]!.isPluralBranch).toBe(true);
       });
 
       it('should handle =0 selector', () => {
-        const result = parseIcu('{count, plural, =0 {No items} one {# item} other {# items}}');
+        const result = parseIcu(
+          '{count, plural, =0 {No items} one {# item} other {# items}}'
+        );
         expect(result.segments).toHaveLength(3);
         expect(result.segments[0]!.text).toBe('No items');
         expect(result.segments[1]!.text).toBe('# item');
@@ -63,14 +75,18 @@ describe('icu-preservation', () => {
       });
 
       it('should handle many plural categories', () => {
-        const result = parseIcu('{count, plural, zero {none} one {single} two {pair} few {several} many {lots} other {some}}');
+        const result = parseIcu(
+          '{count, plural, zero {none} one {single} two {pair} few {several} many {lots} other {some}}'
+        );
         expect(result.segments).toHaveLength(6);
       });
     });
 
     describe('select extraction', () => {
       it('should extract leaf text from select branches', () => {
-        const result = parseIcu('{gender, select, male {He liked your post} female {She liked your post} other {They liked your post}}');
+        const result = parseIcu(
+          '{gender, select, male {He liked your post} female {She liked your post} other {They liked your post}}'
+        );
         expect(result.isIcu).toBe(true);
         expect(result.segments).toHaveLength(3);
         expect(result.segments[0]!.text).toBe('He liked your post');
@@ -87,7 +103,9 @@ describe('icu-preservation', () => {
 
     describe('selectordinal extraction', () => {
       it('should extract ordinal branches', () => {
-        const result = parseIcu('{count, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}');
+        const result = parseIcu(
+          '{count, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}'
+        );
         expect(result.segments).toHaveLength(4);
         expect(result.segments[0]!.text).toBe('#st');
         expect(result.segments[3]!.text).toBe('#th');
@@ -97,19 +115,29 @@ describe('icu-preservation', () => {
 
     describe('reassembly', () => {
       it('should reassemble plural with translated text', () => {
-        const result = parseIcu('{count, plural, one {# item} other {# items}}');
+        const result = parseIcu(
+          '{count, plural, one {# item} other {# items}}'
+        );
         const translated = result.reassemble(['# Artikel', '# Artikel']);
-        expect(translated).toBe('{count, plural, one {# Artikel} other {# Artikel}}');
+        expect(translated).toBe(
+          '{count, plural, one {# Artikel} other {# Artikel}}'
+        );
       });
 
       it('should reassemble select with translated text', () => {
-        const result = parseIcu('{gender, select, male {He} female {She} other {They}}');
+        const result = parseIcu(
+          '{gender, select, male {He} female {She} other {They}}'
+        );
         const translated = result.reassemble(['Er', 'Sie', 'Sie']);
-        expect(translated).toBe('{gender, select, male {Er} female {Sie} other {Sie}}');
+        expect(translated).toBe(
+          '{gender, select, male {Er} female {Sie} other {Sie}}'
+        );
       });
 
       it('should preserve variable name and keyword exactly', () => {
-        const result = parseIcu('{myCount, plural, one {one thing} other {many things}}');
+        const result = parseIcu(
+          '{myCount, plural, one {one thing} other {many things}}'
+        );
         const translated = result.reassemble(['eine Sache', 'viele Sachen']);
         expect(translated).toContain('myCount');
         expect(translated).toContain('plural');
@@ -126,7 +154,9 @@ describe('icu-preservation', () => {
 
     describe('offset', () => {
       it('should parse plural with offset:1', () => {
-        const result = parseIcu('{count, plural, offset:1 one {you and # other} other {you and # others}}');
+        const result = parseIcu(
+          '{count, plural, offset:1 one {you and # other} other {you and # others}}'
+        );
         expect(result.isIcu).toBe(true);
         expect(result.segments).toHaveLength(2);
         expect(result.segments[0]!.text).toBe('you and # other');
@@ -134,39 +164,49 @@ describe('icu-preservation', () => {
       });
 
       it('should preserve offset:1 verbatim on reassembly', () => {
-        const input = '{count, plural, offset:1 one {you and # other} other {you and # others}}';
+        const input =
+          '{count, plural, offset:1 one {you and # other} other {you and # others}}';
         const result = parseIcu(input);
         const roundTrip = result.reassemble(result.segments.map((s) => s.text));
         expect(roundTrip).toBe(input);
       });
 
       it('should parse offset:0', () => {
-        const result = parseIcu('{count, plural, offset:0 one {# item} other {# items}}');
+        const result = parseIcu(
+          '{count, plural, offset:0 one {# item} other {# items}}'
+        );
         expect(result.isIcu).toBe(true);
         expect(result.reassemble(['# item', '# items'])).toBe(
-          '{count, plural, offset:0 one {# item} other {# items}}',
+          '{count, plural, offset:0 one {# item} other {# items}}'
         );
       });
 
       it('should parse selectordinal with offset', () => {
-        const result = parseIcu('{count, selectordinal, offset:2 one {#st} other {#th}}');
+        const result = parseIcu(
+          '{count, selectordinal, offset:2 one {#st} other {#th}}'
+        );
         expect(result.isIcu).toBe(true);
         expect(result.segments).toHaveLength(2);
         expect(result.reassemble(['#st', '#th'])).toBe(
-          '{count, selectordinal, offset:2 one {#st} other {#th}}',
+          '{count, selectordinal, offset:2 one {#st} other {#th}}'
         );
       });
 
       it('should parse nested plural with offset', () => {
-        const input = '{count, plural, offset:1 one {{gender, select, male {He} other {They}}} other {# guests}}';
+        const input =
+          '{count, plural, offset:1 one {{gender, select, male {He} other {They}}} other {# guests}}';
         const result = parseIcu(input);
         expect(result.isIcu).toBe(true);
         expect(result.segments).toHaveLength(3);
-        expect(result.reassemble(result.segments.map((s) => s.text))).toBe(input);
+        expect(result.reassemble(result.segments.map((s) => s.text))).toBe(
+          input
+        );
       });
 
       it('should NOT treat offset as valid for select', () => {
-        const result = parseIcu('{gender, select, offset:1 male {He} other {They}}');
+        const result = parseIcu(
+          '{gender, select, offset:1 male {He} other {They}}'
+        );
         expect(result.isIcu).toBe(false);
       });
     });
@@ -255,7 +295,9 @@ describe('icu-preservation', () => {
 
     describe('edge cases', () => {
       it('should handle whitespace variations', () => {
-        const result = parseIcu('{ count , plural , one { # item } other { # items } }');
+        const result = parseIcu(
+          '{ count , plural , one { # item } other { # items } }'
+        );
         expect(result.isIcu).toBe(true);
         expect(result.segments).toHaveLength(2);
         expect(result.segments[0]!.text).toBe(' # item ');
@@ -270,7 +312,9 @@ describe('icu-preservation', () => {
       });
 
       it('should handle branches with simple variables inside', () => {
-        const result = parseIcu('{count, plural, one {{name} has # item} other {{name} has # items}}');
+        const result = parseIcu(
+          '{count, plural, one {{name} has # item} other {{name} has # items}}'
+        );
         expect(result.isIcu).toBe(true);
         expect(result.segments).toHaveLength(2);
         expect(result.segments[0]!.text).toContain('{name}');
@@ -289,7 +333,8 @@ describe('icu-preservation', () => {
       });
 
       it('should handle nested ICU (select inside plural)', () => {
-        const input = '{count, plural, one {{gender, select, male {He has # item} female {She has # item} other {They have # item}}} other {{gender, select, male {He has # items} female {She has # items} other {They have # items}}}}';
+        const input =
+          '{count, plural, one {{gender, select, male {He has # item} female {She has # item} other {They have # item}}} other {{gender, select, male {He has # items} female {She has # items} other {They have # items}}}}';
         const result = parseIcu(input);
         expect(result.isIcu).toBe(true);
         // Nested: 2 plural branches × 3 select branches = 6 leaf segments
@@ -298,7 +343,9 @@ describe('icu-preservation', () => {
 
       it('should handle long branch text', () => {
         const longText = 'A'.repeat(500);
-        const result = parseIcu(`{n, plural, one {${longText}} other {${longText}s}}`);
+        const result = parseIcu(
+          `{n, plural, one {${longText}} other {${longText}s}}`
+        );
         expect(result.isIcu).toBe(true);
         expect(result.segments[0]!.text).toBe(longText);
       });
diff --git a/tests/unit/uuid.test.ts b/tests/unit/uuid.test.ts
index 2eac1b2e..321e33de 100644
--- a/tests/unit/uuid.test.ts
+++ b/tests/unit/uuid.test.ts
@@ -1,4 +1,8 @@
-import { UUID_RE, validateUuid, validateTranslationMemoryId } from '../../src/utils/uuid';
+import {
+  UUID_RE,
+  validateUuid,
+  validateTranslationMemoryId,
+} from '../../src/utils/uuid';
 import { ValidationError } from '../../src/utils/errors';
 
 describe('UUID_RE', () => {
@@ -11,11 +15,15 @@ describe('UUID_RE', () => {
   });
 
   it('is anchored — rejects embedded UUID with leading text', () => {
-    expect(UUID_RE.test('prefix-11111111-2222-3333-4444-555555555555')).toBe(false);
+    expect(UUID_RE.test('prefix-11111111-2222-3333-4444-555555555555')).toBe(
+      false
+    );
   });
 
   it('is anchored — rejects embedded UUID with trailing text', () => {
-    expect(UUID_RE.test('11111111-2222-3333-4444-555555555555-suffix')).toBe(false);
+    expect(UUID_RE.test('11111111-2222-3333-4444-555555555555-suffix')).toBe(
+      false
+    );
   });
 
   it('rejects empty string', () => {
@@ -32,13 +40,17 @@ describe('UUID_RE', () => {
 
   it('rejects a uuid with path-traversal chars', () => {
     expect(UUID_RE.test('../11111111-2222-3333-4444-555555555555')).toBe(false);
-    expect(UUID_RE.test('11111111-2222-3333-4444-555555555555/../')).toBe(false);
+    expect(UUID_RE.test('11111111-2222-3333-4444-555555555555/../')).toBe(
+      false
+    );
   });
 });
 
 describe('validateUuid', () => {
   it('accepts a canonical UUID without throwing', () => {
-    expect(() => validateUuid('11111111-2222-3333-4444-555555555555')).not.toThrow();
+    expect(() =>
+      validateUuid('11111111-2222-3333-4444-555555555555')
+    ).not.toThrow();
   });
 
   it('throws ValidationError on malformed input', () => {
@@ -63,11 +75,15 @@ describe('validateUuid', () => {
 
 describe('validateTranslationMemoryId', () => {
   it('accepts a canonical UUID without throwing', () => {
-    expect(() => validateTranslationMemoryId('11111111-2222-3333-4444-555555555555')).not.toThrow();
+    expect(() =>
+      validateTranslationMemoryId('11111111-2222-3333-4444-555555555555')
+    ).not.toThrow();
   });
 
   it('throws ValidationError on non-UUID strings (loose glossary pattern rejected)', () => {
-    expect(() => validateTranslationMemoryId('my-tm-name')).toThrow('Invalid translation memory ID format');
+    expect(() => validateTranslationMemoryId('my-tm-name')).toThrow(
+      'Invalid translation memory ID format'
+    );
   });
 
   it('throws ValidationError on path-traversal input without echoing raw bytes', () => {
diff --git a/tests/unit/validate-url.test.ts b/tests/unit/validate-url.test.ts
index d33a5244..dfac1ac0 100644
--- a/tests/unit/validate-url.test.ts
+++ b/tests/unit/validate-url.test.ts
@@ -3,7 +3,9 @@ import { validateApiUrl } from '../../src/utils/validate-url';
 describe('validateApiUrl', () => {
   describe('HTTPS URLs (accepted)', () => {
     it('should accept https://api-free.deepl.com/v2', () => {
-      expect(() => validateApiUrl('https://api-free.deepl.com/v2')).not.toThrow();
+      expect(() =>
+        validateApiUrl('https://api-free.deepl.com/v2')
+      ).not.toThrow();
     });
 
     it('should accept https://api.deepl.com/v2', () => {
@@ -11,7 +13,9 @@ describe('validateApiUrl', () => {
     });
 
     it('should accept any HTTPS URL', () => {
-      expect(() => validateApiUrl('https://custom-proxy.example.com/deepl')).not.toThrow();
+      expect(() =>
+        validateApiUrl('https://custom-proxy.example.com/deepl')
+      ).not.toThrow();
     });
 
     it('should accept HTTPS URL with port', () => {
@@ -41,25 +45,35 @@ describe('validateApiUrl', () => {
     });
 
     it('should accept http://127.0.0.1 with path', () => {
-      expect(() => validateApiUrl('http://127.0.0.1:9090/api/v2')).not.toThrow();
+      expect(() =>
+        validateApiUrl('http://127.0.0.1:9090/api/v2')
+      ).not.toThrow();
     });
   });
 
   describe('HTTP remote URLs (rejected)', () => {
     it('should reject http://api-free.deepl.com', () => {
-      expect(() => validateApiUrl('http://api-free.deepl.com')).toThrow(/Insecure HTTP URL rejected/);
+      expect(() => validateApiUrl('http://api-free.deepl.com')).toThrow(
+        /Insecure HTTP URL rejected/
+      );
     });
 
     it('should reject http://api.deepl.com/v2', () => {
-      expect(() => validateApiUrl('http://api.deepl.com/v2')).toThrow(/Insecure HTTP URL rejected/);
+      expect(() => validateApiUrl('http://api.deepl.com/v2')).toThrow(
+        /Insecure HTTP URL rejected/
+      );
     });
 
     it('should reject http://example.com', () => {
-      expect(() => validateApiUrl('http://example.com')).toThrow(/Insecure HTTP URL rejected/);
+      expect(() => validateApiUrl('http://example.com')).toThrow(
+        /Insecure HTTP URL rejected/
+      );
     });
 
     it('should reject http://evil-server.com/steal-keys', () => {
-      expect(() => validateApiUrl('http://evil-server.com/steal-keys')).toThrow(/Insecure HTTP URL rejected/);
+      expect(() => validateApiUrl('http://evil-server.com/steal-keys')).toThrow(
+        /Insecure HTTP URL rejected/
+      );
     });
 
     it('should include guidance about HTTPS in error message', () => {
@@ -67,7 +81,9 @@ describe('validateApiUrl', () => {
     });
 
     it('should mention credential exposure in error message', () => {
-      expect(() => validateApiUrl('http://example.com')).toThrow(/credential exposure/);
+      expect(() => validateApiUrl('http://example.com')).toThrow(
+        /credential exposure/
+      );
     });
 
     it('should mention localhost exception in error message', () => {
@@ -87,11 +103,15 @@ describe('validateApiUrl', () => {
 
   describe('unsupported protocols (rejected)', () => {
     it('should reject ftp:// URLs', () => {
-      expect(() => validateApiUrl('ftp://example.com')).toThrow(/Unsupported protocol/);
+      expect(() => validateApiUrl('ftp://example.com')).toThrow(
+        /Unsupported protocol/
+      );
     });
 
     it('should reject file:// URLs', () => {
-      expect(() => validateApiUrl('file:///etc/passwd')).toThrow(/Unsupported protocol/);
+      expect(() => validateApiUrl('file:///etc/passwd')).toThrow(
+        /Unsupported protocol/
+      );
     });
   });
 });
diff --git a/tests/unit/voice-command-endpoint-resolution.test.ts b/tests/unit/voice-command-endpoint-resolution.test.ts
index a9f5091d..a2e4176e 100644
--- a/tests/unit/voice-command-endpoint-resolution.test.ts
+++ b/tests/unit/voice-command-endpoint-resolution.test.ts
@@ -21,8 +21,13 @@ jest.mock('chalk', () => {
   return {
     __esModule: true,
     default: {
-      red: passthrough, green: passthrough, blue: passthrough,
-      yellow: passthrough, gray: passthrough, bold: passthrough, level: 3,
+      red: passthrough,
+      green: passthrough,
+      blue: passthrough,
+      yellow: passthrough,
+      gray: passthrough,
+      bold: passthrough,
+      level: 3,
     },
   };
 });
diff --git a/tests/unit/voice-command.test.ts b/tests/unit/voice-command.test.ts
index d56b6d72..52be5ca9 100644
--- a/tests/unit/voice-command.test.ts
+++ b/tests/unit/voice-command.test.ts
@@ -79,11 +79,17 @@ describe('VoiceCommand', () => {
     command = new VoiceCommand(mockService);
 
     // Force non-TTY for most tests (no live display)
-    Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true });
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: false,
+      configurable: true,
+    });
   });
 
   afterEach(() => {
-    Object.defineProperty(process.stdout, 'isTTY', { value: undefined, configurable: true });
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: undefined,
+      configurable: true,
+    });
   });
 
   describe('translate()', () => {
@@ -99,7 +105,7 @@ describe('VoiceCommand', () => {
         expect.objectContaining({
           targetLangs: ['de'],
         }),
-        undefined,
+        undefined
       );
     });
 
@@ -115,7 +121,10 @@ describe('VoiceCommand', () => {
     it('should format as JSON when --format json', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
 
-      const result = await command.translate('test.mp3', { to: 'de', format: 'json' });
+      const result = await command.translate('test.mp3', {
+        to: 'de',
+        format: 'json',
+      });
       const parsed = JSON.parse(result);
 
       expect(parsed.sessionId).toBe('session-123');
@@ -129,7 +138,10 @@ describe('VoiceCommand', () => {
     it('should include segment timing in JSON output', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
 
-      const result = await command.translate('test.mp3', { to: 'de', format: 'json' });
+      const result = await command.translate('test.mp3', {
+        to: 'de',
+        format: 'json',
+      });
       const parsed = JSON.parse(result);
 
       expect(parsed.source.segments[0].startTime).toBe(0);
@@ -146,7 +158,7 @@ describe('VoiceCommand', () => {
         expect.objectContaining({
           sourceLang: 'en',
         }),
-        undefined,
+        undefined
       );
     });
 
@@ -160,42 +172,52 @@ describe('VoiceCommand', () => {
         expect.objectContaining({
           formality: 'more',
         }),
-        undefined,
+        undefined
       );
     });
 
     it('should pass glossary option', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
 
-      await command.translate('test.mp3', { to: 'de', glossary: 'glossary-123' });
+      await command.translate('test.mp3', {
+        to: 'de',
+        glossary: 'glossary-123',
+      });
 
       expect(mockService.translateFile).toHaveBeenCalledWith(
         'test.mp3',
         expect.objectContaining({
           glossaryId: 'glossary-123',
         }),
-        undefined,
+        undefined
       );
     });
 
     it('should pass content-type option', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
 
-      await command.translate('test.pcm', { to: 'de', contentType: 'audio/pcm;encoding=s16le;rate=16000' });
+      await command.translate('test.pcm', {
+        to: 'de',
+        contentType: 'audio/pcm;encoding=s16le;rate=16000',
+      });
 
       expect(mockService.translateFile).toHaveBeenCalledWith(
         'test.pcm',
         expect.objectContaining({
           contentType: 'audio/pcm;encoding=s16le;rate=16000',
         }),
-        undefined,
+        undefined
       );
     });
 
     it('should pass chunk size and interval options', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
 
-      await command.translate('test.mp3', { to: 'de', chunkSize: 3200, chunkInterval: 100 });
+      await command.translate('test.mp3', {
+        to: 'de',
+        chunkSize: 3200,
+        chunkInterval: 100,
+      });
 
       expect(mockService.translateFile).toHaveBeenCalledWith(
         'test.mp3',
@@ -203,7 +225,7 @@ describe('VoiceCommand', () => {
           chunkSize: 3200,
           chunkInterval: 100,
         }),
-        undefined,
+        undefined
       );
     });
 
@@ -217,21 +239,24 @@ describe('VoiceCommand', () => {
         expect.objectContaining({
           reconnect: false,
         }),
-        undefined,
+        undefined
       );
     });
 
     it('should pass maxReconnectAttempts option', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
 
-      await command.translate('test.mp3', { to: 'de', maxReconnectAttempts: 5 });
+      await command.translate('test.mp3', {
+        to: 'de',
+        maxReconnectAttempts: 5,
+      });
 
       expect(mockService.translateFile).toHaveBeenCalledWith(
         'test.mp3',
         expect.objectContaining({
           maxReconnectAttempts: 5,
         }),
-        undefined,
+        undefined
       );
     });
 
@@ -243,12 +268,15 @@ describe('VoiceCommand', () => {
       expect(mockService.translateFile).toHaveBeenCalledWith(
         'test.mp3',
         expect.anything(),
-        undefined,
+        undefined
       );
     });
 
     it('should not pass TTY callbacks when --no-stream is set', async () => {
-      Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+      Object.defineProperty(process.stdout, 'isTTY', {
+        value: true,
+        configurable: true,
+      });
       mockService.translateFile.mockResolvedValue(mockResult);
 
       await command.translate('test.mp3', { to: 'de', stream: false });
@@ -256,14 +284,16 @@ describe('VoiceCommand', () => {
       expect(mockService.translateFile).toHaveBeenCalledWith(
         'test.mp3',
         expect.anything(),
-        undefined,
+        undefined
       );
     });
 
     it('should propagate errors from service', async () => {
       mockService.translateFile.mockRejectedValue(new Error('API error'));
 
-      await expect(command.translate('test.mp3', { to: 'de' })).rejects.toThrow('API error');
+      await expect(command.translate('test.mp3', { to: 'de' })).rejects.toThrow(
+        'API error'
+      );
     });
 
     it('should split comma-separated target languages', async () => {
@@ -276,7 +306,7 @@ describe('VoiceCommand', () => {
         expect.objectContaining({
           targetLangs: ['de', 'fr'],
         }),
-        undefined,
+        undefined
       );
     });
 
@@ -290,7 +320,7 @@ describe('VoiceCommand', () => {
         expect.objectContaining({
           targetLangs: ['de', 'fr'],
         }),
-        undefined,
+        undefined
       );
     });
   });
@@ -340,7 +370,9 @@ describe('VoiceCommand', () => {
       const listenerCountBefore = process.listenerCount('SIGINT');
       mockService.translateFile.mockRejectedValue(new Error('API error'));
 
-      await expect(command.translate('test.mp3', { to: 'de' })).rejects.toThrow('API error');
+      await expect(command.translate('test.mp3', { to: 'de' })).rejects.toThrow(
+        'API error'
+      );
 
       expect(process.listenerCount('SIGINT')).toBe(listenerCountBefore);
     });
@@ -370,14 +402,17 @@ describe('VoiceCommand', () => {
           targetLangs: ['de'],
           contentType: 'audio/mpeg',
         }),
-        undefined,
+        undefined
       );
     });
 
     it('should format as JSON when requested', async () => {
       mockService.translateStdin.mockResolvedValue(mockResult);
 
-      const result = await command.translateFromStdin({ to: 'de', format: 'json' });
+      const result = await command.translateFromStdin({
+        to: 'de',
+        format: 'json',
+      });
       const parsed = JSON.parse(result);
 
       expect(parsed.sessionId).toBe('session-123');
@@ -388,8 +423,13 @@ describe('VoiceCommand', () => {
     let writeSpy: jest.SpyInstance;
 
     beforeEach(() => {
-      Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
-      writeSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+      Object.defineProperty(process.stdout, 'isTTY', {
+        value: true,
+        configurable: true,
+      });
+      writeSpy = jest
+        .spyOn(process.stdout, 'write')
+        .mockImplementation(() => true);
       mockMoveCursor.mockReset();
       mockClearLine.mockReset();
       mockCursorTo.mockReset();
@@ -405,7 +445,9 @@ describe('VoiceCommand', () => {
       await command.translate('test.mp3', { to: 'de' });
 
       const callArgs = mockService.translateFile.mock.calls[0]!;
-      expect(callArgs[2]).toEqual(expect.objectContaining({ onSourceTranscript: expect.any(Function) }));
+      expect(callArgs[2]).toEqual(
+        expect.objectContaining({ onSourceTranscript: expect.any(Function) })
+      );
       expect(callArgs[2]).toHaveProperty('onSourceTranscript');
       expect(callArgs[2]).toHaveProperty('onTargetTranscript');
     });
@@ -433,148 +475,167 @@ describe('VoiceCommand', () => {
     });
 
     it('should render source transcript when onSourceTranscript is invoked', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onSourceTranscript!({
-
-
-          concluded: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
-          tentative: [],
-        });
-        return Promise.resolve(mockResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onSourceTranscript!({
+            concluded: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
+            tentative: [],
+          });
+          return Promise.resolve(mockResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
       const sourceWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[source]') && call[0].includes('Hello')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' &&
+          call[0].includes('[source]') &&
+          call[0].includes('Hello')
       );
       expect(sourceWrites.length).toBeGreaterThanOrEqual(1);
     });
 
     it('should render target transcript when onTargetTranscript is invoked', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onTargetTranscript!({
-          language: 'de',
-          concluded: [{ text: 'Hallo', start_time: 0, end_time: 0.5 }],
-          tentative: [],
-        });
-        return Promise.resolve(mockResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onTargetTranscript!({
+            language: 'de',
+            concluded: [{ text: 'Hallo', start_time: 0, end_time: 0.5 }],
+            tentative: [],
+          });
+          return Promise.resolve(mockResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
       const targetWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[de]') && call[0].includes('Hallo')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' &&
+          call[0].includes('[de]') &&
+          call[0].includes('Hallo')
       );
       expect(targetWrites.length).toBeGreaterThanOrEqual(1);
     });
 
     it('should accumulate concluded text across multiple source updates', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onSourceTranscript!({
-
-
-          concluded: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
-          tentative: [],
-        });
-        callbacks!.onSourceTranscript!({
-
-
-          concluded: [{ text: 'world', start_time: 0.5, end_time: 1.0 }],
-          tentative: [],
-        });
-        return Promise.resolve(mockResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onSourceTranscript!({
+            concluded: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
+            tentative: [],
+          });
+          callbacks!.onSourceTranscript!({
+            concluded: [{ text: 'world', start_time: 0.5, end_time: 1.0 }],
+            tentative: [],
+          });
+          return Promise.resolve(mockResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
       const accumulatedWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('Hello world')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('Hello world')
       );
       expect(accumulatedWrites.length).toBeGreaterThanOrEqual(1);
     });
 
     it('should display tentative text in source transcript', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onSourceTranscript!({
-
-
-          concluded: [],
-          tentative: [{ text: 'Hel', start_time: 0, end_time: 0.3 }],
-        });
-        return Promise.resolve(mockResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onSourceTranscript!({
+            concluded: [],
+            tentative: [{ text: 'Hel', start_time: 0, end_time: 0.3 }],
+          });
+          return Promise.resolve(mockResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
       const tentativeWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('Hel')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('Hel')
       );
       expect(tentativeWrites.length).toBeGreaterThanOrEqual(1);
     });
 
     it('should display tentative text in target transcript', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onTargetTranscript!({
-          language: 'de',
-          concluded: [],
-          tentative: [{ text: 'Hal', start_time: 0, end_time: 0.3 }],
-        });
-        return Promise.resolve(mockResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onTargetTranscript!({
+            language: 'de',
+            concluded: [],
+            tentative: [{ text: 'Hal', start_time: 0, end_time: 0.3 }],
+          });
+          return Promise.resolve(mockResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
       const tentativeWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[de]') && call[0].includes('Hal')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' &&
+          call[0].includes('[de]') &&
+          call[0].includes('Hal')
       );
       expect(tentativeWrites.length).toBeGreaterThanOrEqual(1);
     });
 
     it('should ignore target transcript for unknown language', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onTargetTranscript!({
-          language: 'es',
-          concluded: [{ text: 'Hola', start_time: 0, end_time: 0.5 }],
-          tentative: [],
-        });
-        return Promise.resolve(mockResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onTargetTranscript!({
+            language: 'es',
+            concluded: [{ text: 'Hola', start_time: 0, end_time: 0.5 }],
+            tentative: [],
+          });
+          return Promise.resolve(mockResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
       const esWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('Hola')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('Hola')
       );
       expect(esWrites).toHaveLength(0);
     });
 
     it('should include onReconnecting callback in TTY mode', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        expect(callbacks).toHaveProperty('onReconnecting');
-        expect(typeof callbacks!.onReconnecting).toBe('function');
-        callbacks!.onReconnecting!(1);
-        return Promise.resolve(mockResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          expect(callbacks).toHaveProperty('onReconnecting');
+          expect(typeof callbacks!.onReconnecting).toBe('function');
+          callbacks!.onReconnecting!(1);
+          return Promise.resolve(mockResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
       const reconnectWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('reconnecting'),
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('reconnecting')
       );
       expect(reconnectWrites.length).toBeGreaterThanOrEqual(1);
     });
 
     it('should use readline functions during render', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onSourceTranscript!({
-
-
-          concluded: [{ text: 'Hi', start_time: 0, end_time: 0.2 }],
-          tentative: [],
-        });
-        return Promise.resolve(mockResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onSourceTranscript!({
+            concluded: [{ text: 'Hi', start_time: 0, end_time: 0.2 }],
+            tentative: [],
+          });
+          return Promise.resolve(mockResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
@@ -614,8 +675,13 @@ describe('VoiceCommand', () => {
     let writeSpy: jest.SpyInstance;
 
     beforeEach(() => {
-      Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
-      writeSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+      Object.defineProperty(process.stdout, 'isTTY', {
+        value: true,
+        configurable: true,
+      });
+      writeSpy = jest
+        .spyOn(process.stdout, 'write')
+        .mockImplementation(() => true);
       mockMoveCursor.mockReset();
       mockClearLine.mockReset();
       mockCursorTo.mockReset();
@@ -628,35 +694,53 @@ describe('VoiceCommand', () => {
     it('should coalesce multiple synchronous transcript updates into a single render', async () => {
       const multiResult: VoiceSessionResult = {
         sessionId: 'session-debounce',
-        source: { lang: 'en', text: 'Hello', segments: [{ text: 'Hello', start_time: 0, end_time: 0.5 }] },
+        source: {
+          lang: 'en',
+          text: 'Hello',
+          segments: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
+        },
         targets: [
-          { lang: 'de', text: 'Hallo', segments: [{ text: 'Hallo', start_time: 0, end_time: 0.5 }] },
-          { lang: 'fr', text: 'Bonjour', segments: [{ text: 'Bonjour', start_time: 0, end_time: 0.5 }] },
-          { lang: 'es', text: 'Hola', segments: [{ text: 'Hola', start_time: 0, end_time: 0.5 }] },
+          {
+            lang: 'de',
+            text: 'Hallo',
+            segments: [{ text: 'Hallo', start_time: 0, end_time: 0.5 }],
+          },
+          {
+            lang: 'fr',
+            text: 'Bonjour',
+            segments: [{ text: 'Bonjour', start_time: 0, end_time: 0.5 }],
+          },
+          {
+            lang: 'es',
+            text: 'Hola',
+            segments: [{ text: 'Hola', start_time: 0, end_time: 0.5 }],
+          },
         ],
       };
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onSourceTranscript!({
-          concluded: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
-          tentative: [],
-        });
-        callbacks!.onTargetTranscript!({
-          language: 'de',
-          concluded: [{ text: 'Hallo', start_time: 0, end_time: 0.5 }],
-          tentative: [],
-        });
-        callbacks!.onTargetTranscript!({
-          language: 'fr',
-          concluded: [{ text: 'Bonjour', start_time: 0, end_time: 0.5 }],
-          tentative: [],
-        });
-        callbacks!.onTargetTranscript!({
-          language: 'es',
-          concluded: [{ text: 'Hola', start_time: 0, end_time: 0.5 }],
-          tentative: [],
-        });
-        return Promise.resolve(multiResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onSourceTranscript!({
+            concluded: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
+            tentative: [],
+          });
+          callbacks!.onTargetTranscript!({
+            language: 'de',
+            concluded: [{ text: 'Hallo', start_time: 0, end_time: 0.5 }],
+            tentative: [],
+          });
+          callbacks!.onTargetTranscript!({
+            language: 'fr',
+            concluded: [{ text: 'Bonjour', start_time: 0, end_time: 0.5 }],
+            tentative: [],
+          });
+          callbacks!.onTargetTranscript!({
+            language: 'es',
+            concluded: [{ text: 'Hola', start_time: 0, end_time: 0.5 }],
+            tentative: [],
+          });
+          return Promise.resolve(multiResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de,fr,es' });
 
@@ -664,7 +748,7 @@ describe('VoiceCommand', () => {
       // Without debouncing: 4 callbacks = 4 renders = 4 upward moves of -4
       // With debouncing: 1 coalesced render = 1 upward move of -4 (plus clearTTYDisplay's -4)
       const renderUpMoves = mockMoveCursor.mock.calls.filter(
-        (call: unknown[]) => (call as number[])[2] === -4,
+        (call: unknown[]) => (call as number[])[2] === -4
       );
       expect(renderUpMoves.length).toBeLessThanOrEqual(2);
     });
@@ -672,40 +756,63 @@ describe('VoiceCommand', () => {
     it('should still render all accumulated state in the coalesced render', async () => {
       const multiResult: VoiceSessionResult = {
         sessionId: 'session-debounce-2',
-        source: { lang: 'en', text: 'Hi', segments: [{ text: 'Hi', start_time: 0, end_time: 0.3 }] },
+        source: {
+          lang: 'en',
+          text: 'Hi',
+          segments: [{ text: 'Hi', start_time: 0, end_time: 0.3 }],
+        },
         targets: [
-          { lang: 'de', text: 'Hallo', segments: [{ text: 'Hallo', start_time: 0, end_time: 0.3 }] },
-          { lang: 'fr', text: 'Salut', segments: [{ text: 'Salut', start_time: 0, end_time: 0.3 }] },
+          {
+            lang: 'de',
+            text: 'Hallo',
+            segments: [{ text: 'Hallo', start_time: 0, end_time: 0.3 }],
+          },
+          {
+            lang: 'fr',
+            text: 'Salut',
+            segments: [{ text: 'Salut', start_time: 0, end_time: 0.3 }],
+          },
         ],
       };
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        callbacks!.onSourceTranscript!({
-          concluded: [{ text: 'Hi', start_time: 0, end_time: 0.3 }],
-          tentative: [],
-        });
-        callbacks!.onTargetTranscript!({
-          language: 'de',
-          concluded: [{ text: 'Hallo', start_time: 0, end_time: 0.3 }],
-          tentative: [],
-        });
-        callbacks!.onTargetTranscript!({
-          language: 'fr',
-          concluded: [{ text: 'Salut', start_time: 0, end_time: 0.3 }],
-          tentative: [],
-        });
-        return Promise.resolve(multiResult);
-      });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          callbacks!.onSourceTranscript!({
+            concluded: [{ text: 'Hi', start_time: 0, end_time: 0.3 }],
+            tentative: [],
+          });
+          callbacks!.onTargetTranscript!({
+            language: 'de',
+            concluded: [{ text: 'Hallo', start_time: 0, end_time: 0.3 }],
+            tentative: [],
+          });
+          callbacks!.onTargetTranscript!({
+            language: 'fr',
+            concluded: [{ text: 'Salut', start_time: 0, end_time: 0.3 }],
+            tentative: [],
+          });
+          return Promise.resolve(multiResult);
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de,fr' });
 
       const sourceWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[source]') && call[0].includes('Hi'),
+        (call: unknown[]) =>
+          typeof call[0] === 'string' &&
+          call[0].includes('[source]') &&
+          call[0].includes('Hi')
       );
       const deWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[de]') && call[0].includes('Hallo'),
+        (call: unknown[]) =>
+          typeof call[0] === 'string' &&
+          call[0].includes('[de]') &&
+          call[0].includes('Hallo')
       );
       const frWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[fr]') && call[0].includes('Salut'),
+        (call: unknown[]) =>
+          typeof call[0] === 'string' &&
+          call[0].includes('[fr]') &&
+          call[0].includes('Salut')
       );
       expect(sourceWrites.length).toBeGreaterThanOrEqual(1);
       expect(deWrites.length).toBeGreaterThanOrEqual(1);
@@ -713,37 +820,42 @@ describe('VoiceCommand', () => {
     });
 
     it('should allow a new render after the debounced render fires', async () => {
-      mockService.translateFile.mockImplementation((_file, _opts, callbacks) => {
-        return new Promise((resolve) => {
-          callbacks!.onSourceTranscript!({
-            concluded: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
-            tentative: [],
-          });
-          callbacks!.onTargetTranscript!({
-            language: 'de',
-            concluded: [{ text: 'Hallo', start_time: 0, end_time: 0.5 }],
-            tentative: [],
-          });
+      mockService.translateFile.mockImplementation(
+        (_file, _opts, callbacks) => {
+          return new Promise((resolve) => {
+            callbacks!.onSourceTranscript!({
+              concluded: [{ text: 'Hello', start_time: 0, end_time: 0.5 }],
+              tentative: [],
+            });
+            callbacks!.onTargetTranscript!({
+              language: 'de',
+              concluded: [{ text: 'Hallo', start_time: 0, end_time: 0.5 }],
+              tentative: [],
+            });
 
-          // Let the first debounced render fire, then send more updates
-          queueMicrotask(() => {
+            // Let the first debounced render fire, then send more updates
             queueMicrotask(() => {
-              callbacks!.onSourceTranscript!({
-                concluded: [{ text: 'world', start_time: 0.5, end_time: 1.0 }],
-                tentative: [],
-              });
               queueMicrotask(() => {
-                resolve(mockResult);
+                callbacks!.onSourceTranscript!({
+                  concluded: [
+                    { text: 'world', start_time: 0.5, end_time: 1.0 },
+                  ],
+                  tentative: [],
+                });
+                queueMicrotask(() => {
+                  resolve(mockResult);
+                });
               });
             });
           });
-        });
-      });
+        }
+      );
 
       await command.translate('test.mp3', { to: 'de' });
 
       const accumulatedWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('Hello world'),
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('Hello world')
       );
       expect(accumulatedWrites.length).toBeGreaterThanOrEqual(1);
     });
@@ -753,8 +865,13 @@ describe('VoiceCommand', () => {
     let writeSpy: jest.SpyInstance;
 
     beforeEach(() => {
-      Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
-      writeSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+      Object.defineProperty(process.stdout, 'isTTY', {
+        value: true,
+        configurable: true,
+      });
+      writeSpy = jest
+        .spyOn(process.stdout, 'write')
+        .mockImplementation(() => true);
       mockMoveCursor.mockReset();
       mockClearLine.mockReset();
       mockCursorTo.mockReset();
@@ -770,7 +887,9 @@ describe('VoiceCommand', () => {
       await command.translateFromStdin({ to: 'de' });
 
       const callArgs = mockService.translateStdin.mock.calls[0]!;
-      expect(callArgs[1]).toEqual(expect.objectContaining({ onSourceTranscript: expect.any(Function) }));
+      expect(callArgs[1]).toEqual(
+        expect.objectContaining({ onSourceTranscript: expect.any(Function) })
+      );
       expect(callArgs[1]).toHaveProperty('onSourceTranscript');
       expect(callArgs[1]).toHaveProperty('onTargetTranscript');
     });
@@ -797,8 +916,6 @@ describe('VoiceCommand', () => {
     it('should render source and target when callbacks are invoked via stdin', async () => {
       mockService.translateStdin.mockImplementation((_opts, callbacks) => {
         callbacks!.onSourceTranscript!({
-
-
           concluded: [{ text: 'Test', start_time: 0, end_time: 0.3 }],
           tentative: [],
         });
@@ -813,10 +930,16 @@ describe('VoiceCommand', () => {
       await command.translateFromStdin({ to: 'de' });
 
       const sourceWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[source]') && call[0].includes('Test')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' &&
+          call[0].includes('[source]') &&
+          call[0].includes('Test')
       );
       const targetWrites = writeSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('[de]') && call[0].includes('Prüfung')
+        (call: unknown[]) =>
+          typeof call[0] === 'string' &&
+          call[0].includes('[de]') &&
+          call[0].includes('Prüfung')
       );
       expect(sourceWrites.length).toBeGreaterThanOrEqual(1);
       expect(targetWrites.length).toBeGreaterThanOrEqual(1);
@@ -827,7 +950,9 @@ describe('VoiceCommand', () => {
     let stderrSpy: jest.SpyInstance;
 
     beforeEach(() => {
-      stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+      stderrSpy = jest
+        .spyOn(process.stderr, 'write')
+        .mockImplementation(() => true);
     });
 
     afterEach(() => {
@@ -837,42 +962,62 @@ describe('VoiceCommand', () => {
     it('should warn on stderr when --glossary is used with multiple target languages', async () => {
       mockService.translateFile.mockResolvedValue(multiTargetResult);
 
-      await command.translate('test.mp3', { to: 'de,fr', glossary: 'glossary-123' });
+      await command.translate('test.mp3', {
+        to: 'de,fr',
+        glossary: 'glossary-123',
+      });
 
       expect(stderrSpy).toHaveBeenCalledWith(
-        expect.stringContaining('Warning: --glossary applies a single glossary ID to all target languages'),
+        expect.stringContaining(
+          'Warning: --glossary applies a single glossary ID to all target languages'
+        )
       );
     });
 
     it('should mention the target languages in the warning', async () => {
       mockService.translateFile.mockResolvedValue(multiTargetResult);
 
-      await command.translate('test.mp3', { to: 'de,fr', glossary: 'glossary-123' });
+      await command.translate('test.mp3', {
+        to: 'de,fr',
+        glossary: 'glossary-123',
+      });
 
       const warningCall = stderrSpy.mock.calls.find(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('Warning'),
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('Warning')
+      );
+      expect(warningCall).toEqual(
+        expect.arrayContaining([expect.stringContaining('Warning')])
       );
-      expect(warningCall).toEqual(expect.arrayContaining([expect.stringContaining('Warning')]));
       expect(warningCall![0]).toContain('de, fr');
     });
 
     it('should suggest translating each target separately', async () => {
       mockService.translateFile.mockResolvedValue(multiTargetResult);
 
-      await command.translate('test.mp3', { to: 'de,fr', glossary: 'glossary-123' });
+      await command.translate('test.mp3', {
+        to: 'de,fr',
+        glossary: 'glossary-123',
+      });
 
       expect(stderrSpy).toHaveBeenCalledWith(
-        expect.stringContaining('Consider translating each target language separately'),
+        expect.stringContaining(
+          'Consider translating each target language separately'
+        )
       );
     });
 
     it('should not warn when --glossary is used with a single target language', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
 
-      await command.translate('test.mp3', { to: 'de', glossary: 'glossary-123' });
+      await command.translate('test.mp3', {
+        to: 'de',
+        glossary: 'glossary-123',
+      });
 
       const warningCalls = stderrSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('Warning'),
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('Warning')
       );
       expect(warningCalls).toHaveLength(0);
     });
@@ -883,7 +1028,8 @@ describe('VoiceCommand', () => {
       await command.translate('test.mp3', { to: 'de,fr' });
 
       const warningCalls = stderrSpy.mock.calls.filter(
-        (call: unknown[]) => typeof call[0] === 'string' && call[0].includes('Warning'),
+        (call: unknown[]) =>
+          typeof call[0] === 'string' && call[0].includes('Warning')
       );
       expect(warningCalls).toHaveLength(0);
     });
@@ -891,24 +1037,32 @@ describe('VoiceCommand', () => {
     it('should warn for translateFromStdin too when glossary + multiple targets', async () => {
       mockService.translateStdin.mockResolvedValue(multiTargetResult);
 
-      await command.translateFromStdin({ to: 'de,fr', glossary: 'glossary-123' });
+      await command.translateFromStdin({
+        to: 'de,fr',
+        glossary: 'glossary-123',
+      });
 
       expect(stderrSpy).toHaveBeenCalledWith(
-        expect.stringContaining('Warning: --glossary applies a single glossary ID to all target languages'),
+        expect.stringContaining(
+          'Warning: --glossary applies a single glossary ID to all target languages'
+        )
       );
     });
 
     it('should still pass glossaryId through to the service despite the warning', async () => {
       mockService.translateFile.mockResolvedValue(multiTargetResult);
 
-      await command.translate('test.mp3', { to: 'de,fr', glossary: 'glossary-123' });
+      await command.translate('test.mp3', {
+        to: 'de,fr',
+        glossary: 'glossary-123',
+      });
 
       expect(mockService.translateFile).toHaveBeenCalledWith(
         'test.mp3',
         expect.objectContaining({
           glossaryId: 'glossary-123',
         }),
-        undefined,
+        undefined
       );
     });
   });
@@ -916,19 +1070,19 @@ describe('VoiceCommand', () => {
   describe('language code validation', () => {
     it('should reject invalid target language code', async () => {
       await expect(command.translate('test.mp3', { to: 'zz' })).rejects.toThrow(
-        /Invalid voice target language.*"zz"/,
+        /Invalid voice target language.*"zz"/
       );
     });
 
     it('should reject when one of multiple target languages is invalid', async () => {
-      await expect(command.translate('test.mp3', { to: 'de,xyz' })).rejects.toThrow(
-        /Invalid voice target language.*"xyz"/,
-      );
+      await expect(
+        command.translate('test.mp3', { to: 'de,xyz' })
+      ).rejects.toThrow(/Invalid voice target language.*"xyz"/);
     });
 
     it('should list valid target languages in error message', async () => {
       await expect(command.translate('test.mp3', { to: 'zz' })).rejects.toThrow(
-        /Valid codes:/,
+        /Valid codes:/
       );
     });
 
@@ -948,32 +1102,38 @@ describe('VoiceCommand', () => {
 
     it('should reject invalid source language code', async () => {
       await expect(
-        command.translate('test.mp3', { to: 'de', from: 'zz' }),
+        command.translate('test.mp3', { to: 'de', from: 'zz' })
       ).rejects.toThrow(/Invalid voice source language.*"zz"/);
     });
 
     it('should accept valid source language code', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
-      const result = await command.translate('test.mp3', { to: 'de', from: 'en' });
+      const result = await command.translate('test.mp3', {
+        to: 'de',
+        from: 'en',
+      });
       expect(result).toContain('[de] Hallo Welt');
     });
 
     it('should reject invalid content type', async () => {
       await expect(
-        command.translate('test.mp3', { to: 'de', contentType: 'audio/wav' }),
+        command.translate('test.mp3', { to: 'de', contentType: 'audio/wav' })
       ).rejects.toThrow(/Invalid voice content type.*"audio\/wav"/);
     });
 
     it('should accept valid content type', async () => {
       mockService.translateFile.mockResolvedValue(mockResult);
-      const result = await command.translate('test.mp3', { to: 'de', contentType: 'audio/mpeg' });
+      const result = await command.translate('test.mp3', {
+        to: 'de',
+        contentType: 'audio/mpeg',
+      });
       expect(result).toContain('[de] Hallo Welt');
     });
 
     it('should validate language codes for translateFromStdin too', async () => {
-      await expect(command.translateFromStdin({ to: 'invalid' })).rejects.toThrow(
-        /Invalid voice target language/,
-      );
+      await expect(
+        command.translateFromStdin({ to: 'invalid' })
+      ).rejects.toThrow(/Invalid voice target language/);
     });
 
     it('should reject target language codes that are only valid as source', async () => {
@@ -981,7 +1141,7 @@ describe('VoiceCommand', () => {
       // All source codes are a subset of target codes in current data,
       // but en-GB/en-US/pt-BR/pt-PT are target-only
       await expect(
-        command.translate('test.mp3', { to: 'de', from: 'en-GB' }),
+        command.translate('test.mp3', { to: 'de', from: 'en-GB' })
       ).rejects.toThrow(/Invalid voice source language.*"en-GB"/);
     });
   });
@@ -1070,7 +1230,10 @@ describe('VoiceCommand', () => {
       };
       mockService.translateFile.mockResolvedValue(hostileResult);
 
-      const result = await command.translate('test.mp3', { to: 'de', format: 'json' });
+      const result = await command.translate('test.mp3', {
+        to: 'de',
+        format: 'json',
+      });
 
       // JSON.stringify escapes the control character, so it cannot act on a
       // terminal, and a consumer still gets the text the API returned.
@@ -1086,7 +1249,9 @@ describe('VoiceCommand', () => {
       mockService.translateFile.mockResolvedValue(mockResult);
 
       for (const code of ['en-gb', 'zh-hans', 'PT-br']) {
-        await expect(command.translate('test.mp3', { to: code })).resolves.toContain('[source]');
+        await expect(
+          command.translate('test.mp3', { to: code })
+        ).resolves.toContain('[source]');
       }
     });
 
@@ -1097,19 +1262,21 @@ describe('VoiceCommand', () => {
 
       expect(mockService.translateFile).toHaveBeenLastCalledWith(
         'test.mp3',
-        expect.objectContaining({ targetLangs: ['zh-HANS', 'en-GB'], sourceLang: 'en' }),
-        undefined,
+        expect.objectContaining({
+          targetLangs: ['zh-HANS', 'en-GB'],
+          sourceLang: 'en',
+        }),
+        undefined
       );
     });
 
     it('should still reject a code that is not a voice language', async () => {
       await expect(command.translate('test.mp3', { to: 'xx' })).rejects.toThrow(
-        /Invalid voice target language/,
-      );
-      await expect(command.translate('test.mp3', { to: 'de', from: 'xx' })).rejects.toThrow(
-        /Invalid voice source language/,
+        /Invalid voice target language/
       );
+      await expect(
+        command.translate('test.mp3', { to: 'de', from: 'xx' })
+      ).rejects.toThrow(/Invalid voice source language/);
     });
   });
-
 });
diff --git a/tests/unit/voice-glossary-resolution.test.ts b/tests/unit/voice-glossary-resolution.test.ts
index fda7cd1f..7443f961 100644
--- a/tests/unit/voice-glossary-resolution.test.ts
+++ b/tests/unit/voice-glossary-resolution.test.ts
@@ -45,7 +45,9 @@ function resetAllMockImplementations() {
   mockTranslate.mockResolvedValue('Translated audio text');
   mockTranslateFromStdin.mockResolvedValue('Translated stdin text');
 
-  const { createVoiceCommand } = require('../../src/cli/commands/service-factory');
+  const {
+    createVoiceCommand,
+  } = require('../../src/cli/commands/service-factory');
   createVoiceCommand.mockResolvedValue(mockVoiceCmdObj);
 }
 
@@ -78,8 +80,13 @@ describe('Voice Glossary Resolution', () => {
   });
 
   async function loadAndRegister() {
-    const { registerVoice } = await import('../../src/cli/commands/register-voice');
-    registerVoice(program, { getApiKeyAndOptions, createDeepLClient, handleError } as any);
+    const { registerVoice } =
+      await import('../../src/cli/commands/register-voice');
+    registerVoice(program, {
+      getApiKeyAndOptions,
+      createDeepLClient,
+      handleError,
+    } as any);
   }
 
   it('should pass UUID glossary through resolveGlossaryId', async () => {
@@ -87,13 +94,22 @@ describe('Voice Glossary Resolution', () => {
     mockResolveGlossaryId.mockResolvedValue(uuid);
 
     await loadAndRegister();
-    await program.parseAsync(['node', 'test', 'voice', 'test.ogg', '--to', 'de', '--glossary', uuid]);
+    await program.parseAsync([
+      'node',
+      'test',
+      'voice',
+      'test.ogg',
+      '--to',
+      'de',
+      '--glossary',
+      uuid,
+    ]);
 
     expect(createDeepLClient).toHaveBeenCalled();
     expect(mockResolveGlossaryId).toHaveBeenCalledWith(uuid, undefined);
     expect(mockTranslate).toHaveBeenCalledWith(
       'test.ogg',
-      expect.objectContaining({ glossary: uuid }),
+      expect.objectContaining({ glossary: uuid })
     );
   });
 
@@ -102,23 +118,45 @@ describe('Voice Glossary Resolution', () => {
     mockResolveGlossaryId.mockResolvedValue(resolvedId);
 
     await loadAndRegister();
-    await program.parseAsync(['node', 'test', 'voice', 'test.ogg', '--to', 'de', '--glossary', 'my-glossary']);
+    await program.parseAsync([
+      'node',
+      'test',
+      'voice',
+      'test.ogg',
+      '--to',
+      'de',
+      '--glossary',
+      'my-glossary',
+    ]);
 
     expect(createDeepLClient).toHaveBeenCalled();
-    expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary', undefined);
+    expect(mockResolveGlossaryId).toHaveBeenCalledWith(
+      'my-glossary',
+      undefined
+    );
     expect(mockTranslate).toHaveBeenCalledWith(
       'test.ogg',
-      expect.objectContaining({ glossary: resolvedId }),
+      expect.objectContaining({ glossary: resolvedId })
     );
   });
 
   it('should resolve with the requested pair so coverage is checked locally', async () => {
-    mockResolveGlossaryId.mockResolvedValue('aaaabbbb-cccc-dddd-eeee-ffffffffffff');
+    mockResolveGlossaryId.mockResolvedValue(
+      'aaaabbbb-cccc-dddd-eeee-ffffffffffff'
+    );
 
     await loadAndRegister();
     await program.parseAsync([
-      'node', 'test', 'voice', 'test.ogg',
-      '--from', 'en', '--to', 'de,fr', '--glossary', 'my-glossary',
+      'node',
+      'test',
+      'voice',
+      'test.ogg',
+      '--from',
+      'en',
+      '--to',
+      'de,fr',
+      '--glossary',
+      'my-glossary',
     ]);
 
     expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
@@ -128,12 +166,22 @@ describe('Voice Glossary Resolution', () => {
   });
 
   it('should pass the canonical spellings of the pair, not what was typed', async () => {
-    mockResolveGlossaryId.mockResolvedValue('aaaabbbb-cccc-dddd-eeee-ffffffffffff');
+    mockResolveGlossaryId.mockResolvedValue(
+      'aaaabbbb-cccc-dddd-eeee-ffffffffffff'
+    );
 
     await loadAndRegister();
     await program.parseAsync([
-      'node', 'test', 'voice', 'test.ogg',
-      '--from', 'EN', '--to', 'zh-hans', '--glossary', 'my-glossary',
+      'node',
+      'test',
+      'voice',
+      'test.ogg',
+      '--from',
+      'EN',
+      '--to',
+      'zh-hans',
+      '--glossary',
+      'my-glossary',
     ]);
 
     expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
@@ -143,22 +191,41 @@ describe('Voice Glossary Resolution', () => {
   });
 
   it('should resolve without a pair when --from is absent, since coverage needs both', async () => {
-    mockResolveGlossaryId.mockResolvedValue('aaaabbbb-cccc-dddd-eeee-ffffffffffff');
+    mockResolveGlossaryId.mockResolvedValue(
+      'aaaabbbb-cccc-dddd-eeee-ffffffffffff'
+    );
 
     await loadAndRegister();
     await program.parseAsync([
-      'node', 'test', 'voice', 'test.ogg', '--to', 'de', '--glossary', 'my-glossary',
+      'node',
+      'test',
+      'voice',
+      'test.ogg',
+      '--to',
+      'de',
+      '--glossary',
+      'my-glossary',
     ]);
 
-    expect(mockResolveGlossaryId).toHaveBeenCalledWith('my-glossary', undefined);
+    expect(mockResolveGlossaryId).toHaveBeenCalledWith(
+      'my-glossary',
+      undefined
+    );
   });
 
   it('should reject an invalid target language before spending the resolution call', async () => {
     await loadAndRegister();
     await expect(
       program.parseAsync([
-        'node', 'test', 'voice', 'test.ogg', '--to', 'bogus', '--glossary', 'my-glossary',
-      ]),
+        'node',
+        'test',
+        'voice',
+        'test.ogg',
+        '--to',
+        'bogus',
+        '--glossary',
+        'my-glossary',
+      ])
     ).rejects.toThrow('Invalid voice target language');
 
     expect(createDeepLClient).not.toHaveBeenCalled();
@@ -169,9 +236,17 @@ describe('Voice Glossary Resolution', () => {
     await loadAndRegister();
     await expect(
       program.parseAsync([
-        'node', 'test', 'voice', 'test.ogg',
-        '--to', 'de', '--from', 'bogus', '--glossary', 'my-glossary',
-      ]),
+        'node',
+        'test',
+        'voice',
+        'test.ogg',
+        '--to',
+        'de',
+        '--from',
+        'bogus',
+        '--glossary',
+        'my-glossary',
+      ])
     ).rejects.toThrow('Invalid voice source language');
 
     expect(mockResolveGlossaryId).not.toHaveBeenCalled();
@@ -181,9 +256,17 @@ describe('Voice Glossary Resolution', () => {
     await loadAndRegister();
     await expect(
       program.parseAsync([
-        'node', 'test', 'voice', 'test.ogg',
-        '--to', 'de', '--content-type', 'audio/wav', '--glossary', 'my-glossary',
-      ]),
+        'node',
+        'test',
+        'voice',
+        'test.ogg',
+        '--to',
+        'de',
+        '--content-type',
+        'audio/wav',
+        '--glossary',
+        'my-glossary',
+      ])
     ).rejects.toThrow('Invalid voice content type');
 
     expect(mockResolveGlossaryId).not.toHaveBeenCalled();
@@ -191,18 +274,36 @@ describe('Voice Glossary Resolution', () => {
 
   it('should not create DeepLClient or call resolveGlossaryId when no glossary is specified', async () => {
     await loadAndRegister();
-    await program.parseAsync(['node', 'test', 'voice', 'test.ogg', '--to', 'de']);
+    await program.parseAsync([
+      'node',
+      'test',
+      'voice',
+      'test.ogg',
+      '--to',
+      'de',
+    ]);
 
     expect(createDeepLClient).not.toHaveBeenCalled();
     expect(mockResolveGlossaryId).not.toHaveBeenCalled();
   });
 
   it('should propagate errors from glossary resolution via handleError', async () => {
-    mockResolveGlossaryId.mockRejectedValue(new Error('Glossary "unknown" not found'));
+    mockResolveGlossaryId.mockRejectedValue(
+      new Error('Glossary "unknown" not found')
+    );
 
     await loadAndRegister();
     await expect(
-      program.parseAsync(['node', 'test', 'voice', 'test.ogg', '--to', 'de', '--glossary', 'unknown']),
+      program.parseAsync([
+        'node',
+        'test',
+        'voice',
+        'test.ogg',
+        '--to',
+        'de',
+        '--glossary',
+        'unknown',
+      ])
     ).rejects.toThrow('Glossary "unknown" not found');
 
     expect(handleError).toHaveBeenCalled();
diff --git a/tests/unit/voice-service.test.ts b/tests/unit/voice-service.test.ts
index 4af71fdf..1bf2ef7f 100644
--- a/tests/unit/voice-service.test.ts
+++ b/tests/unit/voice-service.test.ts
@@ -16,7 +16,6 @@ import * as os from 'os';
 import { createMockVoiceClient } from '../helpers/mock-factories';
 
 jest.mock('ws', () => {
-   
   const { EventEmitter: EE } = require('events');
   class MockWebSocket extends EE {
     static OPEN = 1;
@@ -44,20 +43,22 @@ function setupSessionMock(
   mockClient: jest.Mocked<VoiceClient>,
   sessionId: string,
   mockWs: ReturnType<typeof createMockWebSocket>,
-  onOpen: (callbacks: any) => void,
+  onOpen: (callbacks: any) => void
 ) {
   mockClient.createSession.mockResolvedValue({
     streaming_url: 'wss://test',
     token: 'token',
     session_id: sessionId,
   });
-  mockClient.createWebSocket.mockImplementation((_url: string, _token: string, callbacks: any) => {
-    process.nextTick(() => {
-      mockWs.emit('open');
-      process.nextTick(() => onOpen(callbacks));
-    });
-    return mockWs as any;
-  });
+  mockClient.createWebSocket.mockImplementation(
+    (_url: string, _token: string, callbacks: any) => {
+      process.nextTick(() => {
+        mockWs.emit('open');
+        process.nextTick(() => onOpen(callbacks));
+      });
+      return mockWs as any;
+    }
+  );
 }
 
 describe('VoiceService', () => {
@@ -65,7 +66,9 @@ describe('VoiceService', () => {
   let mockClient: jest.Mocked<VoiceClient>;
 
   beforeEach(() => {
-    jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'] });
+    jest.useFakeTimers({
+      doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'],
+    });
     jest.clearAllMocks();
     mockClient = createMockVoiceClient();
 
@@ -82,7 +85,9 @@ describe('VoiceService', () => {
     });
 
     it('should throw error if client is not provided', () => {
-      expect(() => new VoiceService(null as unknown as VoiceClient)).toThrow(ValidationError);
+      expect(() => new VoiceService(null as unknown as VoiceClient)).toThrow(
+        ValidationError
+      );
     });
   });
 
@@ -94,19 +99,27 @@ describe('VoiceService', () => {
 
   describe('detectContentType()', () => {
     it('should detect .ogg as opus/ogg', () => {
-      expect(service.detectContentType('audio.ogg')).toBe('audio/opus;container=ogg');
+      expect(service.detectContentType('audio.ogg')).toBe(
+        'audio/opus;container=ogg'
+      );
     });
 
     it('should detect .opus as opus/ogg', () => {
-      expect(service.detectContentType('audio.opus')).toBe('audio/opus;container=ogg');
+      expect(service.detectContentType('audio.opus')).toBe(
+        'audio/opus;container=ogg'
+      );
     });
 
     it('should detect .webm as opus/webm', () => {
-      expect(service.detectContentType('audio.webm')).toBe('audio/opus;container=webm');
+      expect(service.detectContentType('audio.webm')).toBe(
+        'audio/opus;container=webm'
+      );
     });
 
     it('should detect .mka as opus/matroska', () => {
-      expect(service.detectContentType('audio.mka')).toBe('audio/opus;container=matroska');
+      expect(service.detectContentType('audio.mka')).toBe(
+        'audio/opus;container=matroska'
+      );
     });
 
     it('should detect .flac as audio/flac', () => {
@@ -118,11 +131,15 @@ describe('VoiceService', () => {
     });
 
     it('should detect .pcm as PCM 16kHz', () => {
-      expect(service.detectContentType('raw.pcm')).toBe('audio/pcm;encoding=s16le;rate=16000');
+      expect(service.detectContentType('raw.pcm')).toBe(
+        'audio/pcm;encoding=s16le;rate=16000'
+      );
     });
 
     it('should detect .raw as PCM 16kHz', () => {
-      expect(service.detectContentType('raw.raw')).toBe('audio/pcm;encoding=s16le;rate=16000');
+      expect(service.detectContentType('raw.raw')).toBe(
+        'audio/pcm;encoding=s16le;rate=16000'
+      );
     });
 
     it('should return undefined for unknown extensions', () => {
@@ -135,19 +152,27 @@ describe('VoiceService', () => {
 
     it('should handle uppercase extensions via extname', () => {
       // extname('audio.OGG') returns '.OGG', and toLowerCase() handles it
-      expect(service.detectContentType('audio.OGG')).toBe('audio/opus;container=ogg');
-      expect(service.detectContentType('audio.ogg')).toBe('audio/opus;container=ogg');
+      expect(service.detectContentType('audio.OGG')).toBe(
+        'audio/opus;container=ogg'
+      );
+      expect(service.detectContentType('audio.ogg')).toBe(
+        'audio/opus;container=ogg'
+      );
     });
 
     it('should handle paths with directories', () => {
-      expect(service.detectContentType('/path/to/audio.mp3')).toBe('audio/mpeg');
+      expect(service.detectContentType('/path/to/audio.mp3')).toBe(
+        'audio/mpeg'
+      );
     });
   });
 
   describe('validateOptions()', () => {
     it('should accept valid options with one target language', () => {
       expect(() =>
-        service.validateOptions({ targetLangs: ['de'] } as VoiceTranslateOptions),
+        service.validateOptions({
+          targetLangs: ['de'],
+        } as VoiceTranslateOptions)
       ).not.toThrow();
     });
 
@@ -155,22 +180,22 @@ describe('VoiceService', () => {
       expect(() =>
         service.validateOptions({
           targetLangs: ['de', 'fr', 'es', 'it', 'pt'],
-        } as VoiceTranslateOptions),
+        } as VoiceTranslateOptions)
       ).not.toThrow();
     });
 
     it('should reject empty target languages', () => {
       expect(() =>
-        service.validateOptions({ targetLangs: [] } as VoiceTranslateOptions),
+        service.validateOptions({ targetLangs: [] } as VoiceTranslateOptions)
       ).toThrow(ValidationError);
       expect(() =>
-        service.validateOptions({ targetLangs: [] } as VoiceTranslateOptions),
+        service.validateOptions({ targetLangs: [] } as VoiceTranslateOptions)
       ).toThrow(/at least one target language/i);
     });
 
     it('should reject undefined target languages', () => {
       expect(() =>
-        service.validateOptions({} as VoiceTranslateOptions),
+        service.validateOptions({} as VoiceTranslateOptions)
       ).toThrow(ValidationError);
     });
 
@@ -178,12 +203,12 @@ describe('VoiceService', () => {
       expect(() =>
         service.validateOptions({
           targetLangs: ['de', 'fr', 'es', 'it', 'pt', 'ja'],
-        } as VoiceTranslateOptions),
+        } as VoiceTranslateOptions)
       ).toThrow(ValidationError);
       expect(() =>
         service.validateOptions({
           targetLangs: ['de', 'fr', 'es', 'it', 'pt', 'ja'],
-        } as VoiceTranslateOptions),
+        } as VoiceTranslateOptions)
       ).toThrow(/maximum 5/i);
     });
   });
@@ -197,7 +222,9 @@ describe('VoiceService', () => {
       tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'voice-test-'));
       testFile = path.join(tmpDir, 'test.mp3');
       await fs.writeFile(testFile, Buffer.alloc(1024));
-      jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'] });
+      jest.useFakeTimers({
+        doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'],
+      });
     });
 
     afterEach(async () => {
@@ -209,12 +236,14 @@ describe('VoiceService', () => {
       jest.useRealTimers();
       const unknownFile = path.join(tmpDir, 'test.wav');
       await fs.writeFile(unknownFile, Buffer.alloc(100));
-      jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'] });
+      jest.useFakeTimers({
+        doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'],
+      });
 
       await expect(
         service.translateFile(unknownFile, {
           targetLangs: ['de'],
-        }),
+        })
       ).rejects.toThrow(ValidationError);
     });
 
@@ -227,7 +256,9 @@ describe('VoiceService', () => {
       jest.useRealTimers();
       const wavFile = path.join(tmpDir, 'test.wav');
       await fs.writeFile(wavFile, Buffer.alloc(100));
-      jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'] });
+      jest.useFakeTimers({
+        doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'],
+      });
 
       const result = await service.translateFile(wavFile, {
         targetLangs: ['de'],
@@ -241,7 +272,7 @@ describe('VoiceService', () => {
       await expect(
         service.translateFile('/nonexistent/file.mp3', {
           targetLangs: ['de'],
-        }),
+        })
       ).rejects.toThrow();
     });
 
@@ -251,17 +282,19 @@ describe('VoiceService', () => {
       const symlinkFile = path.join(tmpDir, 'link.mp3');
       await fs.writeFile(targetFile, Buffer.alloc(100));
       await fs.symlink(targetFile, symlinkFile);
-      jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'] });
+      jest.useFakeTimers({
+        doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'],
+      });
 
       await expect(
         service.translateFile(symlinkFile, {
           targetLangs: ['de'],
-        }),
+        })
       ).rejects.toThrow(ValidationError);
       await expect(
         service.translateFile(symlinkFile, {
           targetLangs: ['de'],
-        }),
+        })
       ).rejects.toThrow(/symlinks are not supported/i);
     });
 
@@ -295,7 +328,7 @@ describe('VoiceService', () => {
       expect(mockClient.createSession).toHaveBeenCalledWith(
         expect.objectContaining({
           source_media_content_type: 'audio/mpeg',
-        }),
+        })
       );
       expect(result.sessionId).toBe('session-mp3');
     });
@@ -304,7 +337,14 @@ describe('VoiceService', () => {
       const mockWs = createMockWebSocket();
       setupSessionMock(mockClient, 'session-transcript', mockWs, (cb) => {
         cb.onSourceTranscript?.({
-          concluded: [{ text: 'Hello world', language: 'en', start_time: 0, end_time: 1.5 }],
+          concluded: [
+            {
+              text: 'Hello world',
+              language: 'en',
+              start_time: 0,
+              end_time: 1.5,
+            },
+          ],
           tentative: [],
         });
         cb.onTargetTranscript?.({
@@ -331,11 +371,17 @@ describe('VoiceService', () => {
       const mockWs = createMockWebSocket();
       setupSessionMock(mockClient, 'session-multi', mockWs, (cb) => {
         cb.onSourceTranscript?.({
-          concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 0.5 }],
-          tentative: [{ text: 'world', language: 'en', start_time: 0.5, end_time: 1 }],
+          concluded: [
+            { text: 'Hello', language: 'en', start_time: 0, end_time: 0.5 },
+          ],
+          tentative: [
+            { text: 'world', language: 'en', start_time: 0.5, end_time: 1 },
+          ],
         });
         cb.onSourceTranscript?.({
-          concluded: [{ text: 'world', language: 'en', start_time: 0.5, end_time: 1 }],
+          concluded: [
+            { text: 'world', language: 'en', start_time: 0.5, end_time: 1 },
+          ],
           tentative: [],
         });
         cb.onTargetTranscript?.({
@@ -459,7 +505,7 @@ describe('VoiceService', () => {
         service.translateFile(testFile, {
           targetLangs: ['de'],
           chunkInterval: 0,
-        }),
+        })
       ).rejects.toThrow(VoiceError);
     });
 
@@ -481,7 +527,7 @@ describe('VoiceService', () => {
           target_languages: ['de'],
           formality: 'more',
           glossary_id: 'glossary-123',
-        }),
+        })
       );
     });
 
@@ -493,29 +539,31 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-ws-error',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          // ws always emits close after an error; the session reports the
-          // transport failure from there.
-          mockWs.emit('error', new Error('Connection refused'));
-          mockWs.emit('close');
-        });
-        return mockWs as any;
-      });
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
+          process.nextTick(() => {
+            // ws always emits close after an error; the session reports the
+            // transport failure from there.
+            mockWs.emit('error', new Error('Connection refused'));
+            mockWs.emit('close');
+          });
+          return mockWs as any;
+        }
+      );
 
       await expect(
         service.translateFile(testFile, {
           targetLangs: ['de'],
           chunkInterval: 0,
           reconnect: false,
-        }),
+        })
       ).rejects.toThrow(VoiceError);
       await expect(
         service.translateFile(testFile, {
           targetLangs: ['de'],
           chunkInterval: 0,
           reconnect: false,
-        }),
+        })
       ).rejects.toThrow(/WebSocket connection failed: Connection refused/);
     });
 
@@ -528,16 +576,18 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-close',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, callbacks: any) => {
           process.nextTick(() => {
-            callbacks.onEndOfStream?.();
-            mockWs.emit('close');
+            mockWs.emit('open');
+            process.nextTick(() => {
+              callbacks.onEndOfStream?.();
+              mockWs.emit('close');
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       await service.translateFile(testFile, {
         targetLangs: ['de'],
@@ -560,16 +610,20 @@ describe('VoiceService', () => {
       // (indicating chunk streaming completed), ensuring SIGINT fires mid-stream
       let endStreamCb: (() => void) | null = null;
       mockClient.sendEndOfSource.mockImplementation(() => {
-        if (endStreamCb) { process.nextTick(endStreamCb); }
+        if (endStreamCb) {
+          process.nextTick(endStreamCb);
+        }
       });
 
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, callbacks: any) => {
-        endStreamCb = () => callbacks.onEndOfStream?.();
-        process.nextTick(() => {
-          mockWs.emit('open');
-        });
-        return mockWs as any;
-      });
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, callbacks: any) => {
+          endStreamCb = () => callbacks.onEndOfStream?.();
+          process.nextTick(() => {
+            mockWs.emit('open');
+          });
+          return mockWs as any;
+        }
+      );
 
       await service.translateFile(testFile, {
         targetLangs: ['de'],
@@ -585,25 +639,29 @@ describe('VoiceService', () => {
       jest.useRealTimers();
       const largeFile = path.join(tmpDir, 'large.mp3');
       await fs.writeFile(largeFile, Buffer.alloc(10000));
-      jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'] });
+      jest.useFakeTimers({
+        doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'],
+      });
 
       mockClient.createSession.mockResolvedValue({
         streaming_url: 'wss://test',
         token: 'token',
         session_id: 'session-readystate',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, callbacks: any) => {
           process.nextTick(() => {
-            mockWs.readyState = 3; // CLOSED
+            mockWs.emit('open');
             process.nextTick(() => {
-              callbacks.onEndOfStream?.();
+              mockWs.readyState = 3; // CLOSED
+              process.nextTick(() => {
+                callbacks.onEndOfStream?.();
+              });
             });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const promise = service.translateFile(largeFile, {
         targetLangs: ['de'],
@@ -629,19 +687,23 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-chunk-error',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
-        });
-        return mockWs as any;
-      });
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
+          process.nextTick(() => {
+            mockWs.emit('open');
+          });
+          return mockWs as any;
+        }
+      );
 
       // Mock the chunk reader to throw deterministically
       // (avoids a filesystem race between createReadStream and unlink)
-      // eslint-disable-next-line require-yield
-      jest.spyOn(service as any, 'readFileInChunks').mockImplementation(async function*() {
-        throw new Error('ENOENT: no such file or directory');
-      });
+      jest
+        .spyOn(service as any, 'readFileInChunks')
+        // eslint-disable-next-line require-yield
+        .mockImplementation(async function* () {
+          throw new Error('ENOENT: no such file or directory');
+        });
 
       const promise = service.translateFile(testFile, {
         targetLangs: ['de'],
@@ -661,12 +723,16 @@ describe('VoiceService', () => {
         cb.onEndOfStream?.();
       });
 
-      await service.translateFile(testFile, {
-        targetLangs: ['de'],
-        chunkInterval: 0,
-      }, {
-        onEndOfSourceTranscript,
-      });
+      await service.translateFile(
+        testFile,
+        {
+          targetLangs: ['de'],
+          chunkInterval: 0,
+        },
+        {
+          onEndOfSourceTranscript,
+        }
+      );
 
       expect(onEndOfSourceTranscript).toHaveBeenCalledTimes(1);
     });
@@ -680,12 +746,16 @@ describe('VoiceService', () => {
         cb.onEndOfStream?.();
       });
 
-      await service.translateFile(testFile, {
-        targetLangs: ['de'],
-        chunkInterval: 0,
-      }, {
-        onEndOfTargetTranscript,
-      });
+      await service.translateFile(
+        testFile,
+        {
+          targetLangs: ['de'],
+          chunkInterval: 0,
+        },
+        {
+          onEndOfTargetTranscript,
+        }
+      );
 
       expect(onEndOfTargetTranscript).toHaveBeenCalledTimes(1);
       expect(onEndOfTargetTranscript).toHaveBeenCalledWith('de');
@@ -704,7 +774,9 @@ describe('VoiceService', () => {
       largeFile = path.join(tmpDir, 'large.mp3');
       await fs.writeFile(testFile, Buffer.alloc(1024));
       await fs.writeFile(largeFile, Buffer.alloc(5000));
-      jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'] });
+      jest.useFakeTimers({
+        doNotFake: ['nextTick', 'setImmediate', 'clearImmediate'],
+      });
     });
 
     afterEach(async () => {
@@ -732,37 +804,45 @@ describe('VoiceService', () => {
       });
 
       let wsCallCount = 0;
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, callbacks: any) => {
-        wsCallCount++;
-        if (wsCallCount === 1) {
-          process.nextTick(() => {
-            mockWs1.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, callbacks: any) => {
+          wsCallCount++;
+          if (wsCallCount === 1) {
             process.nextTick(() => {
-              // Simulate unexpected close (no end_of_stream)
-              mockWs1.readyState = 3;
-              mockWs1.emit('close');
+              mockWs1.emit('open');
+              process.nextTick(() => {
+                // Simulate unexpected close (no end_of_stream)
+                mockWs1.readyState = 3;
+                mockWs1.emit('close');
+              });
             });
-          });
-          return mockWs1 as any;
-        } else {
-          process.nextTick(() => {
-            mockWs2.emit('open');
+            return mockWs1 as any;
+          } else {
             process.nextTick(() => {
-              callbacks.onEndOfStream?.();
+              mockWs2.emit('open');
+              process.nextTick(() => {
+                callbacks.onEndOfStream?.();
+              });
             });
-          });
-          return mockWs2 as any;
+            return mockWs2 as any;
+          }
         }
-      });
+      );
 
-      const result = await service.translateFile(testFile, {
-        targetLangs: ['de'],
-        chunkInterval: 0,
-      }, { onReconnecting });
+      const result = await service.translateFile(
+        testFile,
+        {
+          targetLangs: ['de'],
+          chunkInterval: 0,
+        },
+        { onReconnecting }
+      );
 
       expect(result.sessionId).toBe('session-reconnect');
       expect(onReconnecting).toHaveBeenCalledWith(1);
-      expect((mockClient as any).reconnectSession).toHaveBeenCalledWith('token-1');
+      expect((mockClient as any).reconnectSession).toHaveBeenCalledWith(
+        'token-1'
+      );
     });
 
     it('should reject after max reconnect attempts exhausted', async () => {
@@ -773,40 +853,44 @@ describe('VoiceService', () => {
       });
 
       let tokenCounter = 1;
-      (mockClient as any).reconnectSession = jest.fn().mockImplementation(() => {
-        tokenCounter++;
-        return Promise.resolve({
-          streaming_url: `wss://test-${tokenCounter}`,
-          token: `token-${tokenCounter}`,
+      (mockClient as any).reconnectSession = jest
+        .fn()
+        .mockImplementation(() => {
+          tokenCounter++;
+          return Promise.resolve({
+            streaming_url: `wss://test-${tokenCounter}`,
+            token: `token-${tokenCounter}`,
+          });
         });
-      });
 
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        const mockWs = createMockWebSocket();
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
+          const mockWs = createMockWebSocket();
 
-        process.nextTick(() => {
-          mockWs.emit('open');
           process.nextTick(() => {
-            mockWs.readyState = 3;
-            mockWs.emit('close');
+            mockWs.emit('open');
+            process.nextTick(() => {
+              mockWs.readyState = 3;
+              mockWs.emit('close');
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       await expect(
         service.translateFile(testFile, {
           targetLangs: ['de'],
           chunkInterval: 0,
           maxReconnectAttempts: 2,
-        }),
+        })
       ).rejects.toThrow(VoiceError);
       await expect(
         service.translateFile(testFile, {
           targetLangs: ['de'],
           chunkInterval: 0,
           maxReconnectAttempts: 2,
-        }),
+        })
       ).rejects.toThrow(/WebSocket closed unexpectedly/);
     });
 
@@ -820,23 +904,25 @@ describe('VoiceService', () => {
       });
       (mockClient as any).reconnectSession = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            mockWs.readyState = 3;
-            mockWs.emit('close');
+            mockWs.emit('open');
+            process.nextTick(() => {
+              mockWs.readyState = 3;
+              mockWs.emit('close');
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       await expect(
         service.translateFile(testFile, {
           targetLangs: ['de'],
           chunkInterval: 0,
           reconnect: false,
-        }),
+        })
       ).rejects.toThrow(VoiceError);
 
       expect((mockClient as any).reconnectSession).not.toHaveBeenCalled();
@@ -852,17 +938,19 @@ describe('VoiceService', () => {
       });
       (mockClient as any).reconnectSession = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, callbacks: any) => {
           process.nextTick(() => {
-            callbacks.onEndOfStream?.();
-            // Simulate ws.close() triggering 'close' event
-            mockWs.emit('close');
+            mockWs.emit('open');
+            process.nextTick(() => {
+              callbacks.onEndOfStream?.();
+              // Simulate ws.close() triggering 'close' event
+              mockWs.emit('close');
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const result = await service.translateFile(testFile, {
         targetLangs: ['de'],
@@ -881,26 +969,28 @@ describe('VoiceService', () => {
         token: 'token-1',
         session_id: 'session-reconnect-fail',
       });
-      (mockClient as any).reconnectSession = jest.fn().mockRejectedValue(
-        new VoiceError('Voice API access denied.'),
-      );
+      (mockClient as any).reconnectSession = jest
+        .fn()
+        .mockRejectedValue(new VoiceError('Voice API access denied.'));
 
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            mockWs.readyState = 3;
-            mockWs.emit('close');
+            mockWs.emit('open');
+            process.nextTick(() => {
+              mockWs.readyState = 3;
+              mockWs.emit('close');
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       await expect(
         service.translateFile(testFile, {
           targetLangs: ['de'],
           chunkInterval: 0,
-        }),
+        })
       ).rejects.toThrow(VoiceError);
     });
 
@@ -927,21 +1017,23 @@ describe('VoiceService', () => {
 
       let ws2Callbacks: any = null;
 
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, callbacks: any) => {
-        wsCallCount++;
-        if (wsCallCount === 1) {
-          process.nextTick(() => {
-            mockWs1.emit('open');
-          });
-          return mockWs1 as any;
-        } else {
-          ws2Callbacks = callbacks;
-          process.nextTick(() => {
-            mockWs2.emit('open');
-          });
-          return mockWs2 as any;
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, callbacks: any) => {
+          wsCallCount++;
+          if (wsCallCount === 1) {
+            process.nextTick(() => {
+              mockWs1.emit('open');
+            });
+            return mockWs1 as any;
+          } else {
+            ws2Callbacks = callbacks;
+            process.nextTick(() => {
+              mockWs2.emit('open');
+            });
+            return mockWs2 as any;
+          }
         }
-      });
+      );
 
       // Signal end-of-stream when sendEndOfSource is called, after all chunks
       // have been sent. Driving it off the call rather than polling keeps this
@@ -989,12 +1081,12 @@ describe('VoiceService', () => {
       await expect(
         service.translateStdin({
           targetLangs: ['de'],
-        }),
+        })
       ).rejects.toThrow(ValidationError);
       await expect(
         service.translateStdin({
           targetLangs: ['de'],
-        }),
+        })
       ).rejects.toThrow(/content type is required/i);
     });
 
@@ -1003,7 +1095,7 @@ describe('VoiceService', () => {
         service.translateStdin({
           targetLangs: [],
           contentType: 'audio/mpeg',
-        }),
+        })
       ).rejects.toThrow(ValidationError);
     });
 
@@ -1017,16 +1109,18 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-stdin',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            mockStdin.write(Buffer.alloc(100));
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              mockStdin.write(Buffer.alloc(100));
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const promise = service.translateStdin({
         targetLangs: ['de'],
@@ -1045,7 +1139,7 @@ describe('VoiceService', () => {
       expect(mockClient.createSession).toHaveBeenCalledWith(
         expect.objectContaining({
           source_media_content_type: 'audio/mpeg',
-        }),
+        })
       );
       expect(mockClient.sendAudioChunk).toHaveBeenCalled();
     });
@@ -1060,17 +1154,19 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-stdin-defaults',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            // Write more than default chunkSize (6400) to verify chunking
-            mockStdin.write(Buffer.alloc(7000));
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              // Write more than default chunkSize (6400) to verify chunking
+              mockStdin.write(Buffer.alloc(7000));
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const promise = service.translateStdin({
         targetLangs: ['de'],
@@ -1101,21 +1197,23 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-large-stream',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            const totalSize = 65536;
-            const pushSize = 256;
-            for (let i = 0; i < totalSize / pushSize; i++) {
-              const buf = Buffer.alloc(pushSize, i & 0xff);
-              mockStdin.write(buf);
-            }
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              const totalSize = 65536;
+              const pushSize = 256;
+              for (let i = 0; i < totalSize / pushSize; i++) {
+                const buf = Buffer.alloc(pushSize, i & 0xff);
+                mockStdin.write(buf);
+              }
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const chunkSize = 6400;
       const promise = service.translateStdin({
@@ -1158,16 +1256,18 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-exact-multiple',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            mockStdin.write(Buffer.alloc(12800));
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              mockStdin.write(Buffer.alloc(12800));
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const chunkSize = 6400;
       const promise = service.translateStdin({
@@ -1209,19 +1309,21 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-single-byte',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            const totalBytes = 25;
-            for (let i = 0; i < totalBytes; i++) {
-              mockStdin.write(Buffer.from([i]));
-            }
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              const totalBytes = 25;
+              for (let i = 0; i < totalBytes; i++) {
+                mockStdin.write(Buffer.from([i]));
+              }
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const chunkSize = 10;
       const promise = service.translateStdin({
@@ -1263,17 +1365,19 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-stdin-remainder',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            // Write less than one chunk to test remainder yielding (line 242-243)
-            mockStdin.write(Buffer.alloc(50));
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              // Write less than one chunk to test remainder yielding (line 242-243)
+              mockStdin.write(Buffer.alloc(50));
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const promise = service.translateStdin({
         targetLangs: ['de'],
@@ -1304,15 +1408,17 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-empty-stdin',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const promise = service.translateStdin({
         targetLangs: ['de'],
@@ -1342,21 +1448,23 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-large-stdin',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            // Write 256KB of data -- double the translate command's 128KB limit
-            const totalSize = 256 * 1024;
-            const pushSize = 4096;
-            for (let i = 0; i < totalSize / pushSize; i++) {
-              mockStdin.write(Buffer.alloc(pushSize, i & 0xff));
-            }
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              // Write 256KB of data -- double the translate command's 128KB limit
+              const totalSize = 256 * 1024;
+              const pushSize = 4096;
+              for (let i = 0; i < totalSize / pushSize; i++) {
+                mockStdin.write(Buffer.alloc(pushSize, i & 0xff));
+              }
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const chunkSize = 6400;
       const promise = service.translateStdin({
@@ -1397,20 +1505,22 @@ describe('VoiceService', () => {
         token: 'token',
         session_id: 'session-accumulate',
       });
-      mockClient.createWebSocket.mockImplementation((_url: string, _token: string, _callbacks: any) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url: string, _token: string, _callbacks: any) => {
           process.nextTick(() => {
-            // Push 3 chunks of 40 bytes each (120 total) with chunkSize=100
-            // Should yield one 100-byte chunk + one 20-byte remainder
-            mockStdin.write(Buffer.alloc(40, 0xaa));
-            mockStdin.write(Buffer.alloc(40, 0xbb));
-            mockStdin.write(Buffer.alloc(40, 0xcc));
-            mockStdin.end();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              // Push 3 chunks of 40 bytes each (120 total) with chunkSize=100
+              // Should yield one 100-byte chunk + one 20-byte remainder
+              mockStdin.write(Buffer.alloc(40, 0xaa));
+              mockStdin.write(Buffer.alloc(40, 0xbb));
+              mockStdin.write(Buffer.alloc(40, 0xcc));
+              mockStdin.end();
+            });
           });
-        });
-        return mockWs as any;
-      });
+          return mockWs as any;
+        }
+      );
 
       const chunkSize = 100;
       const promise = service.translateStdin({
diff --git a/tests/unit/voice-stream-session.test.ts b/tests/unit/voice-stream-session.test.ts
index a3bb4f61..84f0e84e 100644
--- a/tests/unit/voice-stream-session.test.ts
+++ b/tests/unit/voice-stream-session.test.ts
@@ -1,4 +1,3 @@
- 
 /**
  * Tests for VoiceStreamSession
  * Covers WebSocket lifecycle, reconnection, SIGINT handling, chunk streaming,
@@ -73,15 +72,21 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
-          process.nextTick(() => callbacks.onEndOfStream?.());
-        });
-        return mockWs;
-      });
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
+          process.nextTick(() => {
+            mockWs.emit('open');
+            process.nextTick(() => callbacks.onEndOfStream?.());
+          });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
       const result = await streamSession.run(emptyChunks());
       expect(result.source.lang).toBe('auto');
     });
@@ -93,13 +98,15 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
-          process.nextTick(() => callbacks.onEndOfStream?.());
-        });
-        return mockWs;
-      });
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
+          process.nextTick(() => {
+            mockWs.emit('open');
+            process.nextTick(() => callbacks.onEndOfStream?.());
+          });
+          return mockWs;
+        }
+      );
 
       const streamSession = new VoiceStreamSession(mockClient, session, {
         ...options,
@@ -126,20 +133,28 @@ describe('VoiceStreamSession', () => {
         });
       });
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, _callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
-        });
-        return mockWs;
-      });
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, _callbacks) => {
+          process.nextTick(() => {
+            mockWs.emit('open');
+          });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
-      const result = await streamSession.run(singleChunk(Buffer.from('audio-data')));
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
+      const result = await streamSession.run(
+        singleChunk(Buffer.from('audio-data'))
+      );
 
       expect(mockClient.createWebSocket).toHaveBeenCalledWith(
         'wss://test.deepl.com/stream',
         'token-1',
-        expect.any(Object),
+        expect.any(Object)
       );
       expect(mockClient.sendAudioChunk).toHaveBeenCalled();
       expect(mockClient.sendEndOfSource).toHaveBeenCalled();
@@ -153,26 +168,34 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
           process.nextTick(() => {
-            callbacks.onSourceTranscript?.({
-              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
-              tentative: [],
-            });
-            callbacks.onTargetTranscript?.({
-              language: 'de',
-              concluded: [{ text: 'Hallo', start_time: 0, end_time: 1 }],
-              tentative: [],
+            mockWs.emit('open');
+            process.nextTick(() => {
+              callbacks.onSourceTranscript?.({
+                concluded: [
+                  { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+                ],
+                tentative: [],
+              });
+              callbacks.onTargetTranscript?.({
+                language: 'de',
+                concluded: [{ text: 'Hallo', start_time: 0, end_time: 1 }],
+                tentative: [],
+              });
+              callbacks.onEndOfStream?.();
             });
-            callbacks.onEndOfStream?.();
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
       const result = await streamSession.run(emptyChunks());
 
       expect(result.source.text).toBe('Hello');
@@ -191,18 +214,24 @@ describe('VoiceStreamSession', () => {
 
       const listenerCountBefore = process.listenerCount('SIGINT');
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
           process.nextTick(() => {
-            expect(process.listenerCount('SIGINT')).toBe(listenerCountBefore);
-            callbacks.onEndOfStream?.();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              expect(process.listenerCount('SIGINT')).toBe(listenerCountBefore);
+              callbacks.onEndOfStream?.();
+            });
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
       await streamSession.run(emptyChunks());
     });
   });
@@ -215,18 +244,24 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
           process.nextTick(() => {
-            streamSession.cancel();
-            process.nextTick(() => callbacks.onEndOfStream?.());
+            mockWs.emit('open');
+            process.nextTick(() => {
+              streamSession.cancel();
+              process.nextTick(() => callbacks.onEndOfStream?.());
+            });
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
       await streamSession.run(emptyChunks());
 
       expect(mockClient.sendEndOfSource).toHaveBeenCalledWith(mockWs);
@@ -239,15 +274,21 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
-          process.nextTick(() => callbacks.onEndOfStream?.());
-        });
-        return mockWs;
-      });
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
+          process.nextTick(() => {
+            mockWs.emit('open');
+            process.nextTick(() => callbacks.onEndOfStream?.());
+          });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
       await streamSession.run(emptyChunks());
 
       mockClient.sendEndOfSource.mockClear();
@@ -278,10 +319,14 @@ describe('VoiceStreamSession', () => {
 
       const noReconnect = { ...options, reconnect: false };
       await expect(
-        new VoiceStreamSession(mockClient, session, noReconnect).run(emptyChunks()),
+        new VoiceStreamSession(mockClient, session, noReconnect).run(
+          emptyChunks()
+        )
       ).rejects.toThrow(VoiceError);
       await expect(
-        new VoiceStreamSession(mockClient, session, noReconnect).run(emptyChunks()),
+        new VoiceStreamSession(mockClient, session, noReconnect).run(
+          emptyChunks()
+        )
       ).rejects.toThrow(/WebSocket connection failed: Connection refused/);
     });
 
@@ -292,23 +337,31 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
           process.nextTick(() => {
-            callbacks.onError?.({
-              request_type: 'unknown',
-              error_code: 400,
-              reason_code: 9040000,
-              error_message: 'Invalid audio format',
+            mockWs.emit('open');
+            process.nextTick(() => {
+              callbacks.onError?.({
+                request_type: 'unknown',
+                error_code: 400,
+                reason_code: 9040000,
+                error_message: 'Invalid audio format',
+              });
             });
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
-      await expect(streamSession.run(emptyChunks())).rejects.toThrow(VoiceError);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
+      await expect(streamSession.run(emptyChunks())).rejects.toThrow(
+        VoiceError
+      );
     });
 
     it('should reject when chunk streaming throws', async () => {
@@ -323,8 +376,14 @@ describe('VoiceStreamSession', () => {
         return mockWs;
       });
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
-      await expect(streamSession.run(throwingChunks())).rejects.toThrow('chunk error');
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
+      await expect(streamSession.run(throwingChunks())).rejects.toThrow(
+        'chunk error'
+      );
       expect(mockWs.close).toHaveBeenCalled();
     });
   });
@@ -340,33 +399,38 @@ describe('VoiceStreamSession', () => {
       });
 
       let wsCallCount = 0;
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        wsCallCount++;
-        const mockWs = new EventEmitter();
-        mockWs.readyState = 1;
-        mockWs.send = jest.fn();
-        mockWs.close = jest.fn();
-
-        if (wsCallCount === 1) {
-          process.nextTick(() => {
-            mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
+          wsCallCount++;
+          const mockWs = new EventEmitter();
+          mockWs.readyState = 1;
+          mockWs.send = jest.fn();
+          mockWs.close = jest.fn();
+
+          if (wsCallCount === 1) {
             process.nextTick(() => {
-              mockWs.emit('error', new Error('read ECONNRESET'));
-              mockWs.readyState = 3;
-              mockWs.emit('close');
+              mockWs.emit('open');
+              process.nextTick(() => {
+                mockWs.emit('error', new Error('read ECONNRESET'));
+                mockWs.readyState = 3;
+                mockWs.emit('close');
+              });
             });
-          });
-        } else {
-          process.nextTick(() => {
-            mockWs.emit('open');
-            process.nextTick(() => callbacks.onEndOfStream?.());
-          });
+          } else {
+            process.nextTick(() => {
+              mockWs.emit('open');
+              process.nextTick(() => callbacks.onEndOfStream?.());
+            });
+          }
+          return mockWs;
         }
-        return mockWs;
-      });
+      );
 
       const streamSession = new VoiceStreamSession(
-        mockClient, session, options, { onReconnecting },
+        mockClient,
+        session,
+        options,
+        { onReconnecting }
       );
       const result = await streamSession.run(emptyChunks());
 
@@ -405,7 +469,7 @@ describe('VoiceStreamSession', () => {
         new VoiceStreamSession(mockClient, session, {
           ...options,
           maxReconnectAttempts: 1,
-        }).run(emptyChunks()),
+        }).run(emptyChunks())
       ).rejects.toThrow(/WebSocket connection failed: read ECONNRESET/);
       expect(mockClient.reconnectSession).toHaveBeenCalledTimes(1);
     });
@@ -415,7 +479,7 @@ describe('VoiceStreamSession', () => {
       const input = trackedChunks();
 
       mockClient.reconnectSession.mockRejectedValue(
-        new VoiceError('Voice API access denied.'),
+        new VoiceError('Voice API access denied.')
       );
 
       mockClient.createWebSocket.mockImplementation(() => {
@@ -435,7 +499,11 @@ describe('VoiceStreamSession', () => {
         return mockWs;
       });
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
       await expect(streamSession.run(input.chunks)).rejects.toThrow(VoiceError);
 
       expect(input.closed()).toBe(true);
@@ -461,28 +529,33 @@ describe('VoiceStreamSession', () => {
       });
 
       let wsCallCount = 0;
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        wsCallCount++;
-        if (wsCallCount === 1) {
-          process.nextTick(() => {
-            mockWs1.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
+          wsCallCount++;
+          if (wsCallCount === 1) {
             process.nextTick(() => {
-              mockWs1.readyState = 3;
-              mockWs1.emit('close');
+              mockWs1.emit('open');
+              process.nextTick(() => {
+                mockWs1.readyState = 3;
+                mockWs1.emit('close');
+              });
             });
-          });
-          return mockWs1;
-        } else {
-          process.nextTick(() => {
-            mockWs2.emit('open');
-            process.nextTick(() => callbacks.onEndOfStream?.());
-          });
-          return mockWs2;
+            return mockWs1;
+          } else {
+            process.nextTick(() => {
+              mockWs2.emit('open');
+              process.nextTick(() => callbacks.onEndOfStream?.());
+            });
+            return mockWs2;
+          }
         }
-      });
+      );
 
       const streamSession = new VoiceStreamSession(
-        mockClient, session, options, { onReconnecting },
+        mockClient,
+        session,
+        options,
+        { onReconnecting }
       );
       const result = await streamSession.run(emptyChunks());
 
@@ -524,12 +597,14 @@ describe('VoiceStreamSession', () => {
         maxReconnectAttempts: 2,
       });
 
-      await expect(streamSession.run(emptyChunks())).rejects.toThrow(VoiceError);
+      await expect(streamSession.run(emptyChunks())).rejects.toThrow(
+        VoiceError
+      );
       await expect(
         new VoiceStreamSession(mockClient, session, {
           ...options,
           maxReconnectAttempts: 2,
-        }).run(emptyChunks()),
+        }).run(emptyChunks())
       ).rejects.toThrow(/WebSocket closed unexpectedly/);
     });
 
@@ -556,7 +631,9 @@ describe('VoiceStreamSession', () => {
         reconnect: false,
       });
 
-      await expect(streamSession.run(emptyChunks())).rejects.toThrow(VoiceError);
+      await expect(streamSession.run(emptyChunks())).rejects.toThrow(
+        VoiceError
+      );
       expect(mockClient.reconnectSession).not.toHaveBeenCalled();
     });
 
@@ -568,7 +645,7 @@ describe('VoiceStreamSession', () => {
       mockWs.close = jest.fn();
 
       mockClient.reconnectSession.mockRejectedValue(
-        new VoiceError('Voice API access denied.'),
+        new VoiceError('Voice API access denied.')
       );
 
       mockClient.createWebSocket.mockImplementation(() => {
@@ -582,8 +659,14 @@ describe('VoiceStreamSession', () => {
         return mockWs;
       });
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
-      await expect(streamSession.run(emptyChunks())).rejects.toThrow(VoiceError);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
+      await expect(streamSession.run(emptyChunks())).rejects.toThrow(
+        VoiceError
+      );
     });
   });
 
@@ -595,30 +678,50 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
           process.nextTick(() => {
-            callbacks.onSourceTranscript?.({
-              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 0.5 }],
-              tentative: [],
-            });
-            callbacks.onSourceTranscript?.({
-              concluded: [{ text: 'world', language: 'en', start_time: 0.5, end_time: 1 }],
-              tentative: [],
-            });
-            callbacks.onTargetTranscript?.({
-              language: 'de',
-              concluded: [{ text: 'Hallo Welt', start_time: 0, end_time: 1 }],
-              tentative: [],
+            mockWs.emit('open');
+            process.nextTick(() => {
+              callbacks.onSourceTranscript?.({
+                concluded: [
+                  {
+                    text: 'Hello',
+                    language: 'en',
+                    start_time: 0,
+                    end_time: 0.5,
+                  },
+                ],
+                tentative: [],
+              });
+              callbacks.onSourceTranscript?.({
+                concluded: [
+                  {
+                    text: 'world',
+                    language: 'en',
+                    start_time: 0.5,
+                    end_time: 1,
+                  },
+                ],
+                tentative: [],
+              });
+              callbacks.onTargetTranscript?.({
+                language: 'de',
+                concluded: [{ text: 'Hallo Welt', start_time: 0, end_time: 1 }],
+                tentative: [],
+              });
+              callbacks.onEndOfStream?.();
             });
-            callbacks.onEndOfStream?.();
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
       const result = await streamSession.run(emptyChunks());
 
       expect(result.source.text).toBe('Hello world');
@@ -632,25 +735,27 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
           process.nextTick(() => {
-            callbacks.onTargetTranscript?.({
-              language: 'de',
-              concluded: [{ text: 'Hallo', start_time: 0, end_time: 1 }],
-              tentative: [],
-            });
-            callbacks.onTargetTranscript?.({
-              language: 'fr',
-              concluded: [{ text: 'Bonjour', start_time: 0, end_time: 1 }],
-              tentative: [],
+            mockWs.emit('open');
+            process.nextTick(() => {
+              callbacks.onTargetTranscript?.({
+                language: 'de',
+                concluded: [{ text: 'Hallo', start_time: 0, end_time: 1 }],
+                tentative: [],
+              });
+              callbacks.onTargetTranscript?.({
+                language: 'fr',
+                concluded: [{ text: 'Bonjour', start_time: 0, end_time: 1 }],
+                tentative: [],
+              });
+              callbacks.onEndOfStream?.();
             });
-            callbacks.onEndOfStream?.();
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
       const streamSession = new VoiceStreamSession(mockClient, session, {
         targetLangs: ['de', 'fr'],
@@ -669,26 +774,39 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
           process.nextTick(() => {
-            callbacks.onSourceTranscript?.({
-              concluded: [{ text: 'Bonjour', language: 'fr', start_time: 0, end_time: 1 }],
-              tentative: [],
-            });
-            callbacks.onTargetTranscript?.({
-              language: 'de',
-              concluded: [{ text: 'Guten Tag', start_time: 0, end_time: 1 }],
-              tentative: [],
+            mockWs.emit('open');
+            process.nextTick(() => {
+              callbacks.onSourceTranscript?.({
+                concluded: [
+                  {
+                    text: 'Bonjour',
+                    language: 'fr',
+                    start_time: 0,
+                    end_time: 1,
+                  },
+                ],
+                tentative: [],
+              });
+              callbacks.onTargetTranscript?.({
+                language: 'de',
+                concluded: [{ text: 'Guten Tag', start_time: 0, end_time: 1 }],
+                tentative: [],
+              });
+              callbacks.onEndOfStream?.();
             });
-            callbacks.onEndOfStream?.();
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options
+      );
       const result = await streamSession.run(emptyChunks());
 
       expect(result.source.lang).toBe('fr');
@@ -700,7 +818,7 @@ describe('VoiceStreamSession', () => {
     function runWithFrames(
       frames: (callbacks: VoiceStreamCallbacks) => void,
       sessionOptions: VoiceTranslateOptions = options,
-      chunks: AsyncGenerator<Buffer> = emptyChunks(),
+      chunks: AsyncGenerator<Buffer> = emptyChunks()
     ): Promise<VoiceSessionResult> {
       const EventEmitter = require('events');
       const mockWs = new EventEmitter();
@@ -708,18 +826,24 @@ describe('VoiceStreamSession', () => {
       mockWs.send = jest.fn();
       mockWs.close = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, callbacks) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, callbacks) => {
           process.nextTick(() => {
-            frames(callbacks);
-            callbacks.onEndOfStream?.();
+            mockWs.emit('open');
+            process.nextTick(() => {
+              frames(callbacks);
+              callbacks.onEndOfStream?.();
+            });
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, sessionOptions);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        sessionOptions
+      );
       return streamSession.run(chunks);
     }
 
@@ -727,10 +851,12 @@ describe('VoiceStreamSession', () => {
       await expect(
         runWithFrames((callbacks) => {
           callbacks.onSourceTranscript?.({
-            concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+            concluded: [
+              { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+            ],
             tentative: [],
           });
-        }),
+        })
       ).rejects.toThrow(VoiceError);
     });
 
@@ -740,7 +866,9 @@ describe('VoiceStreamSession', () => {
         await runWithFrames(
           (callbacks) => {
             callbacks.onSourceTranscript?.({
-              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+              concluded: [
+                { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+              ],
               tentative: [],
             });
             callbacks.onTargetTranscript?.({
@@ -749,7 +877,7 @@ describe('VoiceStreamSession', () => {
               tentative: [],
             });
           },
-          { targetLangs: ['de', 'fr', 'es'], chunkInterval: 0 },
+          { targetLangs: ['de', 'fr', 'es'], chunkInterval: 0 }
         );
       } catch (error) {
         expect((error as Error).message).toContain('de');
@@ -762,7 +890,9 @@ describe('VoiceStreamSession', () => {
       await expect(
         runWithFrames((callbacks) => {
           callbacks.onSourceTranscript?.({
-            concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+            concluded: [
+              { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+            ],
             tentative: [],
           });
           callbacks.onTargetTranscript?.({
@@ -770,7 +900,7 @@ describe('VoiceStreamSession', () => {
             concluded: [{ text: '  ', start_time: 0, end_time: 1 }],
             tentative: [],
           });
-        }),
+        })
       ).rejects.toThrow(VoiceError);
     });
 
@@ -778,7 +908,9 @@ describe('VoiceStreamSession', () => {
       await expect(
         runWithFrames((callbacks) => {
           callbacks.onSourceTranscript?.({
-            concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+            concluded: [
+              { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+            ],
             tentative: [],
           });
           callbacks.onTargetTranscript?.({
@@ -786,7 +918,7 @@ describe('VoiceStreamSession', () => {
             concluded: [],
             tentative: [{ text: 'Hallo', start_time: 0, end_time: 1 }],
           });
-        }),
+        })
       ).rejects.toThrow(VoiceError);
     });
 
@@ -803,7 +935,9 @@ describe('VoiceStreamSession', () => {
       const result = await runWithFrames(
         (callbacks) => {
           callbacks.onSourceTranscript?.({
-            concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+            concluded: [
+              { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+            ],
             tentative: [],
           });
           callbacks.onTargetTranscript?.({
@@ -814,7 +948,7 @@ describe('VoiceStreamSession', () => {
             tentative: [],
           });
         },
-        { targetLangs: ['zh-HANS'], chunkInterval: 0 },
+        { targetLangs: ['zh-HANS'], chunkInterval: 0 }
       );
 
       expect(result.targets[0]!.text).toBe('你好');
@@ -827,7 +961,9 @@ describe('VoiceStreamSession', () => {
         await runWithFrames(
           (callbacks) => {
             callbacks.onSourceTranscript?.({
-              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+              concluded: [
+                { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+              ],
               tentative: [],
             });
             callbacks.onTargetTranscript?.({
@@ -836,15 +972,17 @@ describe('VoiceStreamSession', () => {
               tentative: [],
             });
           },
-          { targetLangs: ['fr', 'de'], chunkInterval: 0 },
+          { targetLangs: ['fr', 'de'], chunkInterval: 0 }
         );
       } catch (error) {
         // The audio is billed either way, so what did arrive must not be thrown
         // away with the failure.
         const partial = (error as VoicePartialResultError).result;
         expect(partial.source.text).toBe('Hello');
-        expect(partial.targets.find(t => t.lang === 'fr')?.text).toBe('Bonjour');
-        expect(partial.targets.find(t => t.lang === 'de')?.text).toBe('');
+        expect(partial.targets.find((t) => t.lang === 'fr')?.text).toBe(
+          'Bonjour'
+        );
+        expect(partial.targets.find((t) => t.lang === 'de')?.text).toBe('');
       }
     });
 
@@ -855,13 +993,15 @@ describe('VoiceStreamSession', () => {
         runWithFrames(
           (callbacks) => {
             callbacks.onSourceTranscript?.({
-              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
+              concluded: [
+                { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+              ],
               tentative: [],
             });
           },
           options,
-          tracked.chunks,
-        ),
+          tracked.chunks
+        )
       ).rejects.toThrow(VoiceError);
 
       expect(tracked.closed()).toBe(true);
@@ -884,28 +1024,37 @@ describe('VoiceStreamSession', () => {
         onEndOfStream: jest.fn(),
       };
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, internalCbs) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, internalCbs) => {
           process.nextTick(() => {
-            internalCbs.onSourceTranscript?.({
-              concluded: [{ text: 'Hello', language: 'en', start_time: 0, end_time: 1 }],
-              tentative: [],
-            });
-            internalCbs.onTargetTranscript?.({
-              language: 'de',
-              concluded: [{ text: 'Hallo', start_time: 0, end_time: 1 }],
-              tentative: [],
+            mockWs.emit('open');
+            process.nextTick(() => {
+              internalCbs.onSourceTranscript?.({
+                concluded: [
+                  { text: 'Hello', language: 'en', start_time: 0, end_time: 1 },
+                ],
+                tentative: [],
+              });
+              internalCbs.onTargetTranscript?.({
+                language: 'de',
+                concluded: [{ text: 'Hallo', start_time: 0, end_time: 1 }],
+                tentative: [],
+              });
+              internalCbs.onEndOfSourceTranscript?.();
+              internalCbs.onEndOfTargetTranscript?.('de');
+              internalCbs.onEndOfStream?.();
             });
-            internalCbs.onEndOfSourceTranscript?.();
-            internalCbs.onEndOfTargetTranscript?.('de');
-            internalCbs.onEndOfStream?.();
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
-      const streamSession = new VoiceStreamSession(mockClient, session, options, callbacks);
+      const streamSession = new VoiceStreamSession(
+        mockClient,
+        session,
+        options,
+        callbacks
+      );
       await streamSession.run(emptyChunks());
 
       expect(callbacks.onSourceTranscript).toHaveBeenCalledTimes(1);
@@ -924,28 +1073,35 @@ describe('VoiceStreamSession', () => {
 
       const onError = jest.fn();
 
-      mockClient.createWebSocket.mockImplementation((_url, _token, internalCbs) => {
-        process.nextTick(() => {
-          mockWs.emit('open');
+      mockClient.createWebSocket.mockImplementation(
+        (_url, _token, internalCbs) => {
           process.nextTick(() => {
-            internalCbs.onError?.({
-              request_type: 'unknown',
-              error_code: 400,
-              reason_code: 0,
-              error_message: 'Bad request',
+            mockWs.emit('open');
+            process.nextTick(() => {
+              internalCbs.onError?.({
+                request_type: 'unknown',
+                error_code: 400,
+                reason_code: 0,
+                error_message: 'Bad request',
+              });
             });
           });
-        });
-        return mockWs;
-      });
+          return mockWs;
+        }
+      );
 
       const streamSession = new VoiceStreamSession(
-        mockClient, session, options, { onError },
+        mockClient,
+        session,
+        options,
+        { onError }
       );
 
-      await expect(streamSession.run(emptyChunks())).rejects.toThrow(VoiceError);
+      await expect(streamSession.run(emptyChunks())).rejects.toThrow(
+        VoiceError
+      );
       expect(onError).toHaveBeenCalledWith(
-        expect.objectContaining({ error_code: 400 }),
+        expect.objectContaining({ error_code: 400 })
       );
     });
   });
@@ -955,7 +1111,6 @@ async function* emptyChunks(): AsyncGenerator<Buffer> {
   // yields nothing
 }
 
- 
 async function* singleChunk(data: Buffer): AsyncGenerator<Buffer> {
   yield data;
 }
@@ -966,7 +1121,10 @@ async function* throwingChunks(): AsyncGenerator<Buffer> {
 }
 
 /** A chunk source that reports whether the session closed it. */
-function trackedChunks(): { chunks: AsyncGenerator<Buffer>; closed: () => boolean } {
+function trackedChunks(): {
+  chunks: AsyncGenerator<Buffer>;
+  closed: () => boolean;
+} {
   let closed = false;
   async function* generate(): AsyncGenerator<Buffer> {
     try {
diff --git a/tests/unit/voice-types-errors.test.ts b/tests/unit/voice-types-errors.test.ts
index bdf354ae..46d73ff2 100644
--- a/tests/unit/voice-types-errors.test.ts
+++ b/tests/unit/voice-types-errors.test.ts
@@ -67,17 +67,13 @@ describe('formatVoiceJson()', () => {
     source: {
       lang: 'en',
       text: 'Hello world',
-      segments: [
-        { text: 'Hello world', start_time: 0, end_time: 1.5 },
-      ],
+      segments: [{ text: 'Hello world', start_time: 0, end_time: 1.5 }],
     },
     targets: [
       {
         lang: 'de',
         text: 'Hallo Welt',
-        segments: [
-          { text: 'Hallo Welt', start_time: 0, end_time: 1.5 },
-        ],
+        segments: [{ text: 'Hallo Welt', start_time: 0, end_time: 1.5 }],
       },
     ],
   };
diff --git a/tests/unit/watch-command.test.ts b/tests/unit/watch-command.test.ts
index 344331fb..6d80b8bb 100644
--- a/tests/unit/watch-command.test.ts
+++ b/tests/unit/watch-command.test.ts
@@ -78,9 +78,9 @@ describe('WatchCommand', () => {
 
     mockFileTranslationService = createMockFileTranslationService();
 
-    (FileTranslationService as jest.MockedClass<typeof FileTranslationService>).mockImplementation(
-      () => mockFileTranslationService
-    );
+    (
+      FileTranslationService as jest.MockedClass<typeof FileTranslationService>
+    ).mockImplementation(() => mockFileTranslationService);
 
     mockWatchService = createMockWatchService({
       getStats: jest.fn().mockReturnValue({
@@ -97,7 +97,10 @@ describe('WatchCommand', () => {
     jest.spyOn(console, 'log').mockImplementation();
     jest.spyOn(console, 'error').mockImplementation();
 
-    watchCommand = new WatchCommand(mockTranslationService, mockGlossaryService);
+    watchCommand = new WatchCommand(
+      mockTranslationService,
+      mockGlossaryService
+    );
   });
 
   afterEach(() => {
@@ -107,7 +110,9 @@ describe('WatchCommand', () => {
   describe('constructor', () => {
     it('should create WatchCommand with TranslationService and GlossaryService', () => {
       expect(watchCommand).toBeInstanceOf(WatchCommand);
-      expect(FileTranslationService).toHaveBeenCalledWith(mockTranslationService);
+      expect(FileTranslationService).toHaveBeenCalledWith(
+        mockTranslationService
+      );
     });
   });
 
@@ -138,7 +143,9 @@ describe('WatchCommand', () => {
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
 
       // Create a Promise that rejects immediately to avoid hanging
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -160,7 +167,9 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -181,9 +190,13 @@ describe('WatchCommand', () => {
 
     it('should create translations subdirectory for directory input', async () => {
       expect.assertions(1);
-      (fs.existsSync as jest.Mock).mockReturnValueOnce(true).mockReturnValueOnce(false);
+      (fs.existsSync as jest.Mock)
+        .mockReturnValueOnce(true)
+        .mockReturnValueOnce(false);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => true });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/dir', {
@@ -202,7 +215,9 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/dir/file.md', {
@@ -224,7 +239,9 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -247,7 +264,9 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', { to: 'es' });
@@ -267,14 +286,18 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       const configured = new WatchCommand(
         mockTranslationService,
         mockGlossaryService,
         createMockConfigService({
-          getValue: jest.fn((key: string) => (key === 'watch.debounceMs' ? 1200 : undefined)),
-        }),
+          getValue: jest.fn((key: string) =>
+            key === 'watch.debounceMs' ? 1200 : undefined
+          ),
+        })
       );
 
       try {
@@ -295,14 +318,18 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       const configured = new WatchCommand(
         mockTranslationService,
         mockGlossaryService,
         createMockConfigService({
-          getValue: jest.fn((key: string) => (key === 'watch.debounceMs' ? 1200 : undefined)),
-        }),
+          getValue: jest.fn((key: string) =>
+            key === 'watch.debounceMs' ? 1200 : undefined
+          ),
+        })
       );
 
       try {
@@ -323,7 +350,9 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/dir', {
@@ -346,7 +375,9 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -374,7 +405,9 @@ describe('WatchCommand', () => {
       expect.assertions(2);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -399,7 +432,9 @@ describe('WatchCommand', () => {
       expect.assertions(2);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -414,8 +449,16 @@ describe('WatchCommand', () => {
 
       // Test the callback with array result
       await watchOptions.onTranslate!('/test/file.md', [
-        { targetLang: 'es', text: 'translated text', outputPath: '/test/file.es.md' },
-        { targetLang: 'fr', text: 'translated text', outputPath: '/test/file.fr.md' },
+        {
+          targetLang: 'es',
+          text: 'translated text',
+          outputPath: '/test/file.es.md',
+        },
+        {
+          targetLang: 'fr',
+          text: 'translated text',
+          outputPath: '/test/file.fr.md',
+        },
       ]);
 
       expect(mockLogger.success).toHaveBeenCalled();
@@ -425,7 +468,9 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -451,7 +496,9 @@ describe('WatchCommand', () => {
       expect.assertions(2);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -482,14 +529,18 @@ describe('WatchCommand', () => {
     describe('--glossary without --from', () => {
       it('should reject before starting a watcher', async () => {
         (fs.existsSync as jest.Mock).mockReturnValue(true);
-        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+        (fs.statSync as jest.Mock).mockReturnValue({
+          isDirectory: () => false,
+        });
 
         await expect(
           watchCommand.watch('/some/file.md', {
             to: 'es',
             glossary: 'my-glossary',
           })
-        ).rejects.toThrow('Source language (--from) is required when using a glossary');
+        ).rejects.toThrow(
+          'Source language (--from) is required when using a glossary'
+        );
 
         expect(mockWatchService.watch).not.toHaveBeenCalled();
       });
@@ -497,7 +548,9 @@ describe('WatchCommand', () => {
       it('should reject with a ValidationError carrying a watch example', async () => {
         expect.assertions(3);
         (fs.existsSync as jest.Mock).mockReturnValue(true);
-        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+        (fs.statSync as jest.Mock).mockReturnValue({
+          isDirectory: () => false,
+        });
 
         try {
           await watchCommand.watch('/some/file.md', {
@@ -507,13 +560,17 @@ describe('WatchCommand', () => {
         } catch (error) {
           expect(error).toBeInstanceOf(ValidationError);
           expect((error as ValidationError).exitCode).toBe(6);
-          expect((error as ValidationError).suggestion).toContain('deepl watch');
+          expect((error as ValidationError).suggestion).toContain(
+            'deepl watch'
+          );
         }
       });
 
       it('should not resolve the glossary name, which would call the API', async () => {
         (fs.existsSync as jest.Mock).mockReturnValue(true);
-        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+        (fs.statSync as jest.Mock).mockReturnValue({
+          isDirectory: () => false,
+        });
 
         await expect(
           watchCommand.watch('/some/file.md', {
@@ -530,56 +587,80 @@ describe('WatchCommand', () => {
         // WatchCommand call has to read the configured default the same way the
         // CLI path does, or the two disagree about what is runnable.
         (fs.existsSync as jest.Mock).mockReturnValue(true);
-        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+        (fs.statSync as jest.Mock).mockReturnValue({
+          isDirectory: () => false,
+        });
         mockGlossaryService.resolveGlossaryId.mockResolvedValue('glossary-123');
         // Thrown so the watcher does not keep the test open, as elsewhere here.
-        mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+        mockWatchService.watch.mockImplementation(() => {
+          throw new Error('Test complete');
+        });
 
         const configured = new WatchCommand(
           mockTranslationService,
           mockGlossaryService,
           createMockConfigService({
             getValue: jest.fn((key: string) =>
-              key === 'defaults.sourceLang' ? 'en' : undefined,
+              key === 'defaults.sourceLang' ? 'en' : undefined
             ),
-          }),
+          })
         );
 
         await expect(
-          configured.watch('/some/file.md', { to: 'es', glossary: 'my-glossary' }),
+          configured.watch('/some/file.md', {
+            to: 'es',
+            glossary: 'my-glossary',
+          })
         ).rejects.toThrow('Test complete');
 
-        expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
-          from: 'en',
-          targets: ['es'],
-        });
+        expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+          'my-glossary',
+          {
+            from: 'en',
+            targets: ['es'],
+          }
+        );
         expect(mockWatchService.watch).toHaveBeenCalledWith(
           '/some/file.md',
-          expect.objectContaining({ glossaryId: 'glossary-123', sourceLang: 'en' }),
+          expect.objectContaining({
+            glossaryId: 'glossary-123',
+            sourceLang: 'en',
+          })
         );
       });
 
       it('should still reject when the configured default is absent too', async () => {
         (fs.existsSync as jest.Mock).mockReturnValue(true);
-        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+        (fs.statSync as jest.Mock).mockReturnValue({
+          isDirectory: () => false,
+        });
 
         const configured = new WatchCommand(
           mockTranslationService,
           mockGlossaryService,
-          createMockConfigService({ getValue: jest.fn(() => undefined) }),
+          createMockConfigService({ getValue: jest.fn(() => undefined) })
         );
 
         await expect(
-          configured.watch('/some/file.md', { to: 'es', glossary: 'my-glossary' }),
-        ).rejects.toThrow('Source language (--from) is required when using a glossary');
+          configured.watch('/some/file.md', {
+            to: 'es',
+            glossary: 'my-glossary',
+          })
+        ).rejects.toThrow(
+          'Source language (--from) is required when using a glossary'
+        );
       });
 
       it('should accept --glossary when --from is provided', async () => {
         expect.assertions(1);
         (fs.existsSync as jest.Mock).mockReturnValue(true);
-        (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+        (fs.statSync as jest.Mock).mockReturnValue({
+          isDirectory: () => false,
+        });
         mockGlossaryService.resolveGlossaryId.mockResolvedValue('resolved-id');
-        mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+        mockWatchService.watch.mockImplementation(() => {
+          throw new Error('Test complete');
+        });
 
         try {
           await watchCommand.watch('/some/file.md', {
@@ -593,10 +674,13 @@ describe('WatchCommand', () => {
 
         // The pair goes with it so coverage is checked at launch, not once per
         // file change.
-        expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith('my-glossary', {
-          from: 'en',
-          targets: ['es'],
-        });
+        expect(mockGlossaryService.resolveGlossaryId).toHaveBeenCalledWith(
+          'my-glossary',
+          {
+            from: 'en',
+            targets: ['es'],
+          }
+        );
       });
     });
 
@@ -616,13 +700,23 @@ describe('WatchCommand', () => {
       });
 
       // Wait a bit for Logger statements to execute
-      await new Promise(resolve => setTimeout(resolve, 100));
+      await new Promise((resolve) => setTimeout(resolve, 100));
 
-      expect(mockLogger.success).toHaveBeenCalledWith(expect.stringContaining('Watching for changes'));
-      expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('Path: /some/file.md'));
-      expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('Targets: es, fr'));
-      expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('Pattern: *.md'));
-      expect(mockLogger.warn).toHaveBeenCalledWith(expect.stringContaining('Auto-commit enabled'));
+      expect(mockLogger.success).toHaveBeenCalledWith(
+        expect.stringContaining('Watching for changes')
+      );
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('Path: /some/file.md')
+      );
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('Targets: es, fr')
+      );
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('Pattern: *.md')
+      );
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Auto-commit enabled')
+      );
 
       // Don't wait for the promise to resolve (it won't due to infinite Promise)
     }, 1000);
@@ -631,7 +725,9 @@ describe('WatchCommand', () => {
       expect.assertions(1);
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('file.md', {
@@ -669,10 +765,13 @@ describe('WatchCommand', () => {
 
     it('should auto-commit translations when autoCommit is enabled for multiple languages', async () => {
       expect.assertions(1);
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       // Mock exec to simulate git commands
-      const mockExecAsync = jest.fn()
+      const mockExecAsync = jest
+        .fn()
         .mockResolvedValueOnce({ stdout: '.git', stderr: '' }) // git rev-parse check
         .mockResolvedValue({ stdout: '', stderr: '' }); // git add and commit
 
@@ -706,7 +805,9 @@ describe('WatchCommand', () => {
 
     it('should auto-commit translations when autoCommit is enabled for single language', async () => {
       expect.assertions(1);
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -731,7 +832,9 @@ describe('WatchCommand', () => {
 
     it('should handle auto-commit when not in git repository', async () => {
       expect.assertions(1);
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -757,7 +860,9 @@ describe('WatchCommand', () => {
 
     it('should handle auto-commit with no output files', async () => {
       expect.assertions(1);
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -782,7 +887,9 @@ describe('WatchCommand', () => {
 
     it('should handle auto-commit errors gracefully', async () => {
       expect.assertions(1);
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -819,7 +926,9 @@ describe('WatchCommand', () => {
       expect.assertions(2);
       const stagedSet = new Set(['/abs/file1.txt']);
       jest.spyOn(watchCommand, 'getStagedFiles').mockResolvedValue(stagedSet);
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/dir', {
@@ -847,7 +956,9 @@ describe('WatchCommand', () => {
         gitStaged: true,
       });
 
-      expect(mockLogger.warn).toHaveBeenCalledWith(expect.stringContaining('No git-staged files found'));
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('No git-staged files found')
+      );
       expect(WatchService).not.toHaveBeenCalledWith(
         expect.anything(),
         expect.objectContaining({ stagedFiles: expect.anything() })
@@ -855,9 +966,9 @@ describe('WatchCommand', () => {
     });
 
     it('should propagate error when not in a git repo', async () => {
-      jest.spyOn(watchCommand, 'getStagedFiles').mockRejectedValue(
-        new Error('--git-staged requires a git repository')
-      );
+      jest
+        .spyOn(watchCommand, 'getStagedFiles')
+        .mockRejectedValue(new Error('--git-staged requires a git repository'));
 
       await expect(
         watchCommand.watch('/some/dir', {
@@ -870,7 +981,9 @@ describe('WatchCommand', () => {
     it('should not call getStagedFiles when gitStaged is not set', async () => {
       expect.assertions(1);
       jest.spyOn(watchCommand, 'getStagedFiles');
-      mockWatchService.watch.mockImplementation(() => { throw new Error('Test complete'); });
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
 
       try {
         await watchCommand.watch('/some/file.md', {
diff --git a/tests/unit/write-client.test.ts b/tests/unit/write-client.test.ts
index 6782958d..8b6577a0 100644
--- a/tests/unit/write-client.test.ts
+++ b/tests/unit/write-client.test.ts
@@ -25,7 +25,9 @@ describe('WriteClient', () => {
     jest.spyOn(axios, 'isAxiosError').mockReturnValue(false);
 
     client = new WriteClient('test-api-key');
-    jest.spyOn(HttpClient.prototype, 'sleep' as any).mockResolvedValue(undefined);
+    jest
+      .spyOn(HttpClient.prototype, 'sleep' as any)
+      .mockResolvedValue(undefined);
   });
 
   afterAll(() => {
@@ -45,7 +47,7 @@ describe('WriteClient', () => {
       expect(mockedAxios.create).toHaveBeenCalledWith(
         expect.objectContaining({
           baseURL: 'https://api-free.deepl.com',
-        }),
+        })
       );
     });
 
@@ -54,7 +56,7 @@ describe('WriteClient', () => {
       expect(mockedAxios.create).toHaveBeenCalledWith(
         expect.objectContaining({
           baseURL: 'https://custom.example.com',
-        }),
+        })
       );
     });
   });
@@ -86,9 +88,7 @@ describe('WriteClient', () => {
     it('should pass targetLang option', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          improvements: [
-            { text: 'Improved', target_language: 'en-GB' },
-          ],
+          improvements: [{ text: 'Improved', target_language: 'en-GB' }],
         },
         status: 200,
         headers: {},
@@ -100,16 +100,14 @@ describe('WriteClient', () => {
         expect.objectContaining({
           method: 'POST',
           url: '/v2/write/rephrase',
-        }),
+        })
       );
     });
 
     it('should pass writingStyle option', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          improvements: [
-            { text: 'Formal text', target_language: 'en-US' },
-          ],
+          improvements: [{ text: 'Formal text', target_language: 'en-US' }],
         },
         status: 200,
         headers: {},
@@ -125,9 +123,7 @@ describe('WriteClient', () => {
     it('should pass tone option', async () => {
       mockAxiosInstance.request.mockResolvedValue({
         data: {
-          improvements: [
-            { text: 'Friendly text', target_language: 'en-US' },
-          ],
+          improvements: [{ text: 'Friendly text', target_language: 'en-US' }],
         },
         status: 200,
         headers: {},
@@ -147,9 +143,9 @@ describe('WriteClient', () => {
         headers: {},
       });
 
-      await expect(
-        client.improveText('Test', {})
-      ).rejects.toThrow('No improvements returned');
+      await expect(client.improveText('Test', {})).rejects.toThrow(
+        'No improvements returned'
+      );
     });
 
     it('should throw NetworkError when improvements field is missing', async () => {
@@ -159,9 +155,9 @@ describe('WriteClient', () => {
         headers: {},
       });
 
-      await expect(
-        client.improveText('Test', {})
-      ).rejects.toThrow('No improvements returned');
+      await expect(client.improveText('Test', {})).rejects.toThrow(
+        'No improvements returned'
+      );
     });
 
     it('should handle 403 auth error', async () => {
@@ -173,57 +169,72 @@ describe('WriteClient', () => {
       mockAxiosInstance.request.mockRejectedValue(axiosError);
       jest.spyOn(axios, 'isAxiosError').mockReturnValue(true);
 
-      await expect(
-        client.improveText('Test', {})
-      ).rejects.toThrow();
+      await expect(client.improveText('Test', {})).rejects.toThrow();
     });
 
     it('should handle 429 rate limit error', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 429, data: { message: 'Too many requests' }, headers: {} },
+        response: {
+          status: 429,
+          data: { message: 'Too many requests' },
+          headers: {},
+        },
         message: 'Rate limited',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
       jest.spyOn(axios, 'isAxiosError').mockReturnValue(true);
 
-      await expect(
-        client.improveText('Test', {})
-      ).rejects.toThrow();
+      await expect(client.improveText('Test', {})).rejects.toThrow();
     });
 
     it('should handle 503 service unavailable', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 503, data: { message: 'Unavailable' }, headers: {} },
+        response: {
+          status: 503,
+          data: { message: 'Unavailable' },
+          headers: {},
+        },
         message: 'Service unavailable',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
       jest.spyOn(axios, 'isAxiosError').mockReturnValue(true);
 
-      await expect(
-        client.improveText('Test', {})
-      ).rejects.toThrow();
+      await expect(client.improveText('Test', {})).rejects.toThrow();
     });
 
     it('should append docs hint on 400 when writingStyle was sent', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 400, data: { message: "Style 'business' is not supported for 'ja'" }, headers: {} },
+        response: {
+          status: 400,
+          data: { message: "Style 'business' is not supported for 'ja'" },
+          headers: {},
+        },
         message: 'Bad request',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
       jest.spyOn(axios, 'isAxiosError').mockReturnValue(true);
 
       await expect(
-        client.improveText('Test', { targetLang: 'ja', writingStyle: 'business' })
-      ).rejects.toThrow(/See https:\/\/github\.com\/DeepL\/deepl-cli\/blob\/main\/docs\/API\.md#write for supported target language \/ style \/ tone combinations/);
+        client.improveText('Test', {
+          targetLang: 'ja',
+          writingStyle: 'business',
+        })
+      ).rejects.toThrow(
+        /See https:\/\/github\.com\/DeepL\/deepl-cli\/blob\/main\/docs\/API\.md#write for supported target language \/ style \/ tone combinations/
+      );
     });
 
     it('should append docs hint on 400 when tone was sent', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 400, data: { message: "Tone 'friendly' is not supported for 'ko'" }, headers: {} },
+        response: {
+          status: 400,
+          data: { message: "Tone 'friendly' is not supported for 'ko'" },
+          headers: {},
+        },
         message: 'Bad request',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -231,13 +242,19 @@ describe('WriteClient', () => {
 
       await expect(
         client.improveText('Test', { targetLang: 'ko', tone: 'friendly' })
-      ).rejects.toThrow(/See https:\/\/github\.com\/DeepL\/deepl-cli\/blob\/main\/docs\/API\.md#write for supported target language \/ style \/ tone combinations/);
+      ).rejects.toThrow(
+        /See https:\/\/github\.com\/DeepL\/deepl-cli\/blob\/main\/docs\/API\.md#write for supported target language \/ style \/ tone combinations/
+      );
     });
 
     it('should NOT append docs hint on 400 when neither style nor tone was sent', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 400, data: { message: 'Generic bad request' }, headers: {} },
+        response: {
+          status: 400,
+          data: { message: 'Generic bad request' },
+          headers: {},
+        },
         message: 'Bad request',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
@@ -288,7 +305,7 @@ describe('WriteClient', () => {
         expect.objectContaining({
           method: 'POST',
           url: '/v2/write/correct',
-        }),
+        })
       );
     });
 
@@ -331,9 +348,9 @@ describe('WriteClient', () => {
         headers: {},
       });
 
-      await expect(
-        client.correctText('Test', {})
-      ).rejects.toThrow('No improvements returned');
+      await expect(client.correctText('Test', {})).rejects.toThrow(
+        'No improvements returned'
+      );
     });
 
     it('should handle 403 auth error', async () => {
@@ -345,15 +362,17 @@ describe('WriteClient', () => {
       mockAxiosInstance.request.mockRejectedValue(axiosError);
       jest.spyOn(axios, 'isAxiosError').mockReturnValue(true);
 
-      await expect(
-        client.correctText('Test', {})
-      ).rejects.toThrow();
+      await expect(client.correctText('Test', {})).rejects.toThrow();
     });
 
     it('should NOT append the style/tone docs hint on 400', async () => {
       const axiosError = {
         isAxiosError: true,
-        response: { status: 400, data: { message: 'Generic bad request' }, headers: {} },
+        response: {
+          status: 400,
+          data: { message: 'Generic bad request' },
+          headers: {},
+        },
         message: 'Bad request',
       };
       mockAxiosInstance.request.mockRejectedValue(axiosError);
diff --git a/tests/unit/write-command.test.ts b/tests/unit/write-command.test.ts
index 85d5734a..8980ec54 100644
--- a/tests/unit/write-command.test.ts
+++ b/tests/unit/write-command.test.ts
@@ -63,7 +63,10 @@ describe('WriteCommand', () => {
     writeCommand = new WriteCommand(mockWriteService);
 
     // Create temporary directory for file tests with more entropy to avoid collisions
-    testDir = join(tmpdir(), `deepl-cli-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    testDir = join(
+      tmpdir(),
+      `deepl-cli-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
     await fs.mkdir(testDir, { recursive: true });
   });
 
@@ -94,7 +97,9 @@ describe('WriteCommand', () => {
           },
         ];
 
-        mockWriteService.getBestImprovement.mockResolvedValue(mockImprovements[0]!);
+        mockWriteService.getBestImprovement.mockResolvedValue(
+          mockImprovements[0]!
+        );
 
         const result = await writeCommand.improve('This is a sentence.', {
           lang: 'en-us',
@@ -335,7 +340,9 @@ describe('WriteCommand', () => {
     describe('parameter constraints', () => {
       it('should propagate service error when both style and tone are specified', async () => {
         mockWriteService.getBestImprovement.mockRejectedValueOnce(
-          new Error('Cannot specify both --style and --tone in a single request')
+          new Error(
+            'Cannot specify both --style and --tone in a single request'
+          )
         );
 
         await expect(
@@ -382,7 +389,18 @@ describe('WriteCommand', () => {
 
     describe('supported languages', () => {
       it('should work with all supported Write languages', async () => {
-        const languages: Array<'de' | 'en' | 'en-gb' | 'en-us' | 'es' | 'fr' | 'it' | 'pt' | 'pt-br' | 'pt-pt'> = [
+        const languages: Array<
+          | 'de'
+          | 'en'
+          | 'en-gb'
+          | 'en-us'
+          | 'es'
+          | 'fr'
+          | 'it'
+          | 'pt'
+          | 'pt-br'
+          | 'pt-pt'
+        > = [
           'de',
           'en',
           'en-gb',
@@ -401,7 +419,9 @@ describe('WriteCommand', () => {
             targetLanguage: lang,
           };
 
-          mockWriteService.getBestImprovement.mockResolvedValue(mockImprovement);
+          mockWriteService.getBestImprovement.mockResolvedValue(
+            mockImprovement
+          );
 
           const result = await writeCommand.improve('Test', { lang });
 
@@ -440,7 +460,9 @@ describe('WriteCommand', () => {
 
       it('should throw error for non-existent file', async () => {
         await expect(
-          writeCommand.improveFile(join(testDir, 'nonexistent.txt'), { lang: 'en-us' })
+          writeCommand.improveFile(join(testDir, 'nonexistent.txt'), {
+            lang: 'en-us',
+          })
         ).rejects.toThrow('File not found');
       });
 
@@ -823,10 +845,18 @@ describe('WriteCommand', () => {
     it('should generate alternatives with different styles', async () => {
       // Mock different responses for different styles
       mockWriteService.improve
-        .mockResolvedValueOnce([{ text: 'Simple improvement.', targetLanguage: 'en-US' }])
-        .mockResolvedValueOnce([{ text: 'Business improvement.', targetLanguage: 'en-US' }])
-        .mockResolvedValueOnce([{ text: 'Academic improvement.', targetLanguage: 'en-US' }])
-        .mockResolvedValueOnce([{ text: 'Casual improvement.', targetLanguage: 'en-US' }]);
+        .mockResolvedValueOnce([
+          { text: 'Simple improvement.', targetLanguage: 'en-US' },
+        ])
+        .mockResolvedValueOnce([
+          { text: 'Business improvement.', targetLanguage: 'en-US' },
+        ])
+        .mockResolvedValueOnce([
+          { text: 'Academic improvement.', targetLanguage: 'en-US' },
+        ])
+        .mockResolvedValueOnce([
+          { text: 'Casual improvement.', targetLanguage: 'en-US' },
+        ]);
 
       mockSelect.mockResolvedValue(1);
 
@@ -877,10 +907,18 @@ describe('WriteCommand', () => {
     it('should remove duplicate improvements', async () => {
       // Mock where some styles return the same text
       mockWriteService.improve
-        .mockResolvedValueOnce([{ text: 'Same improvement.', targetLanguage: 'en-US' }])
-        .mockResolvedValueOnce([{ text: 'Same improvement.', targetLanguage: 'en-US' }])
-        .mockResolvedValueOnce([{ text: 'Different improvement.', targetLanguage: 'en-US' }])
-        .mockResolvedValueOnce([{ text: 'Same improvement.', targetLanguage: 'en-US' }]);
+        .mockResolvedValueOnce([
+          { text: 'Same improvement.', targetLanguage: 'en-US' },
+        ])
+        .mockResolvedValueOnce([
+          { text: 'Same improvement.', targetLanguage: 'en-US' },
+        ])
+        .mockResolvedValueOnce([
+          { text: 'Different improvement.', targetLanguage: 'en-US' },
+        ])
+        .mockResolvedValueOnce([
+          { text: 'Same improvement.', targetLanguage: 'en-US' },
+        ]);
 
       mockSelect.mockResolvedValue(0);
 
@@ -927,9 +965,13 @@ describe('WriteCommand', () => {
       // Mock where some styles fail but others succeed
       mockWriteService.improve
         .mockRejectedValueOnce(new Error('API error'))
-        .mockResolvedValueOnce([{ text: 'Business improvement.', targetLanguage: 'en-US' }])
+        .mockResolvedValueOnce([
+          { text: 'Business improvement.', targetLanguage: 'en-US' },
+        ])
         .mockRejectedValueOnce(new Error('API error'))
-        .mockResolvedValueOnce([{ text: 'Casual improvement.', targetLanguage: 'en-US' }]);
+        .mockResolvedValueOnce([
+          { text: 'Casual improvement.', targetLanguage: 'en-US' },
+        ]);
 
       mockSelect.mockResolvedValue(0);
 
@@ -944,9 +986,13 @@ describe('WriteCommand', () => {
     it('should log verbose diagnostics when a write style fails', async () => {
       mockWriteService.improve
         .mockRejectedValueOnce(new Error('Rate limit exceeded'))
-        .mockResolvedValueOnce([{ text: 'Business improvement.', targetLanguage: 'en-US' }])
+        .mockResolvedValueOnce([
+          { text: 'Business improvement.', targetLanguage: 'en-US' },
+        ])
         .mockRejectedValueOnce(new Error('Server error'))
-        .mockResolvedValueOnce([{ text: 'Casual improvement.', targetLanguage: 'en-US' }]);
+        .mockResolvedValueOnce([
+          { text: 'Casual improvement.', targetLanguage: 'en-US' },
+        ]);
 
       mockSelect.mockResolvedValue(0);
 
@@ -968,9 +1014,15 @@ describe('WriteCommand', () => {
     it('should log verbose diagnostics with stringified non-Error objects', async () => {
       mockWriteService.improve
         .mockRejectedValueOnce('string error')
-        .mockResolvedValueOnce([{ text: 'Business improvement.', targetLanguage: 'en-US' }])
-        .mockResolvedValueOnce([{ text: 'Academic improvement.', targetLanguage: 'en-US' }])
-        .mockResolvedValueOnce([{ text: 'Casual improvement.', targetLanguage: 'en-US' }]);
+        .mockResolvedValueOnce([
+          { text: 'Business improvement.', targetLanguage: 'en-US' },
+        ])
+        .mockResolvedValueOnce([
+          { text: 'Academic improvement.', targetLanguage: 'en-US' },
+        ])
+        .mockResolvedValueOnce([
+          { text: 'Casual improvement.', targetLanguage: 'en-US' },
+        ]);
 
       mockSelect.mockResolvedValue(0);
 
diff --git a/tests/unit/write-service.test.ts b/tests/unit/write-service.test.ts
index 34761b93..a587156f 100644
--- a/tests/unit/write-service.test.ts
+++ b/tests/unit/write-service.test.ts
@@ -7,7 +7,11 @@ import { DeepLClient } from '../../src/api/deepl-client.js';
 import { ConfigService } from '../../src/storage/config.js';
 import { CacheService } from '../../src/storage/cache.js';
 import { WriteImprovement } from '../../src/types/index.js';
-import { createMockDeepLClient, createMockConfigService, createMockCacheService } from '../helpers/mock-factories';
+import {
+  createMockDeepLClient,
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
 
 describe('WriteService', () => {
   let writeService: WriteService;
@@ -25,7 +29,11 @@ describe('WriteService', () => {
 
     mockCacheService = createMockCacheService();
 
-    writeService = new WriteService(mockClient, mockConfigService, mockCacheService);
+    writeService = new WriteService(
+      mockClient,
+      mockConfigService,
+      mockCacheService
+    );
   });
 
   describe('initialization', () => {
@@ -35,13 +43,21 @@ describe('WriteService', () => {
 
     it('should throw error if client is not provided', () => {
       expect(() => {
-        new WriteService(null as unknown as DeepLClient, mockConfigService, mockCacheService);
+        new WriteService(
+          null as unknown as DeepLClient,
+          mockConfigService,
+          mockCacheService
+        );
       }).toThrow('DeepL client is required');
     });
 
     it('should throw error if config service is not provided', () => {
       expect(() => {
-        new WriteService(mockClient, null as unknown as ConfigService, mockCacheService);
+        new WriteService(
+          mockClient,
+          null as unknown as ConfigService,
+          mockCacheService
+        );
       }).toThrow('Config service is required');
     });
   });
@@ -65,9 +81,12 @@ describe('WriteService', () => {
 
         expect(result).toHaveLength(1);
         expect(result[0]?.text).toBe('This is a well-written sentence.');
-        expect(mockClient.improveText).toHaveBeenCalledWith('This is a sentence.', {
-          targetLang: 'en-us',
-        });
+        expect(mockClient.improveText).toHaveBeenCalledWith(
+          'This is a sentence.',
+          {
+            targetLang: 'en-us',
+          }
+        );
       });
 
       it('should throw error for empty text', async () => {
@@ -116,10 +135,13 @@ describe('WriteService', () => {
         });
 
         expect(result[0]?.text).toBe('This is easy to read.');
-        expect(mockClient.improveText).toHaveBeenCalledWith('This is a sentence.', {
-          targetLang: 'en-us',
-          writingStyle: 'simple',
-        });
+        expect(mockClient.improveText).toHaveBeenCalledWith(
+          'This is a sentence.',
+          {
+            targetLang: 'en-us',
+            writingStyle: 'simple',
+          }
+        );
       });
 
       it('should apply business writing style', async () => {
@@ -453,7 +475,9 @@ describe('WriteService', () => {
     it('should return cached result on hit without calling API', async () => {
       mockCacheService.get.mockReturnValue(mockImprovements);
 
-      const result = await writeService.improve('Test', { targetLang: 'en-us' });
+      const result = await writeService.improve('Test', {
+        targetLang: 'en-us',
+      });
 
       expect(result).toEqual(mockImprovements);
       expect(mockClient.improveText).not.toHaveBeenCalled();
@@ -474,7 +498,11 @@ describe('WriteService', () => {
     it('should skip cache when skipCache is true', async () => {
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      await writeService.improve('Test', { targetLang: 'en-us' }, { skipCache: true });
+      await writeService.improve(
+        'Test',
+        { targetLang: 'en-us' },
+        { skipCache: true }
+      );
 
       expect(mockCacheService.get).not.toHaveBeenCalled();
       expect(mockCacheService.set).not.toHaveBeenCalled();
@@ -484,8 +512,14 @@ describe('WriteService', () => {
     it('should produce different cache keys for different options', async () => {
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'business' });
-      await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'casual' });
+      await writeService.improve('Test', {
+        targetLang: 'en-us',
+        writingStyle: 'business',
+      });
+      await writeService.improve('Test', {
+        targetLang: 'en-us',
+        writingStyle: 'casual',
+      });
 
       const key1 = mockCacheService.set.mock.calls[0]![0];
       const key2 = mockCacheService.set.mock.calls[1]![0];
@@ -495,8 +529,14 @@ describe('WriteService', () => {
     it('should produce same cache key for same options (deterministic)', async () => {
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'business' });
-      await writeService.improve('Test', { targetLang: 'en-us', writingStyle: 'business' });
+      await writeService.improve('Test', {
+        targetLang: 'en-us',
+        writingStyle: 'business',
+      });
+      await writeService.improve('Test', {
+        targetLang: 'en-us',
+        writingStyle: 'business',
+      });
 
       const key1 = mockCacheService.set.mock.calls[0]![0];
       const key2 = mockCacheService.set.mock.calls[1]![0];
@@ -506,7 +546,9 @@ describe('WriteService', () => {
     it('should benefit getBestImprovement from cache', async () => {
       mockCacheService.get.mockReturnValue(mockImprovements);
 
-      const result = await writeService.getBestImprovement('Test', { targetLang: 'en-us' });
+      const result = await writeService.getBestImprovement('Test', {
+        targetLang: 'en-us',
+      });
 
       expect(result.text).toBe('Improved text.');
       expect(mockClient.improveText).not.toHaveBeenCalled();
@@ -525,16 +567,24 @@ describe('WriteService', () => {
     it('should correct text via client.correctText', async () => {
       mockClient.correctText.mockResolvedValue(mockCorrections);
 
-      const result = await writeService.correct('This is an test.', { targetLang: 'en-us' });
+      const result = await writeService.correct('This is an test.', {
+        targetLang: 'en-us',
+      });
 
       expect(result).toEqual(mockCorrections);
-      expect(mockClient.correctText).toHaveBeenCalledWith('This is an test.', { targetLang: 'en-us' });
+      expect(mockClient.correctText).toHaveBeenCalledWith('This is an test.', {
+        targetLang: 'en-us',
+      });
       expect(mockClient.improveText).not.toHaveBeenCalled();
     });
 
     it('should throw ValidationError for empty text', async () => {
-      await expect(writeService.correct('', {})).rejects.toThrow('Text cannot be empty');
-      await expect(writeService.correct('   ', {})).rejects.toThrow('Text cannot be empty');
+      await expect(writeService.correct('', {})).rejects.toThrow(
+        'Text cannot be empty'
+      );
+      await expect(writeService.correct('   ', {})).rejects.toThrow(
+        'Text cannot be empty'
+      );
       expect(mockClient.correctText).not.toHaveBeenCalled();
     });
 
@@ -553,7 +603,9 @@ describe('WriteService', () => {
     it('should return cached result on hit without calling API', async () => {
       mockCacheService.get.mockReturnValue(mockCorrections);
 
-      const result = await writeService.correct('Test', { targetLang: 'en-us' });
+      const result = await writeService.correct('Test', {
+        targetLang: 'en-us',
+      });
 
       expect(result).toEqual(mockCorrections);
       expect(mockClient.correctText).not.toHaveBeenCalled();
@@ -563,7 +615,11 @@ describe('WriteService', () => {
     it('should skip cache when skipCache is true', async () => {
       mockClient.correctText.mockResolvedValue(mockCorrections);
 
-      await writeService.correct('Test', { targetLang: 'en-us' }, { skipCache: true });
+      await writeService.correct(
+        'Test',
+        { targetLang: 'en-us' },
+        { skipCache: true }
+      );
 
       expect(mockCacheService.get).not.toHaveBeenCalled();
       expect(mockCacheService.set).not.toHaveBeenCalled();
@@ -601,7 +657,9 @@ describe('WriteService', () => {
         { text: 'Second.', targetLanguage: 'en-US' },
       ]);
 
-      const result = await writeService.getBestCorrection('Test', { targetLang: 'en-us' });
+      const result = await writeService.getBestCorrection('Test', {
+        targetLang: 'en-us',
+      });
 
       expect(result.text).toBe('First.');
     });
@@ -618,7 +676,18 @@ describe('WriteService', () => {
 
   describe('supported languages', () => {
     it('should work with all supported Write languages', async () => {
-      const languages: Array<'de' | 'en' | 'en-gb' | 'en-us' | 'es' | 'fr' | 'it' | 'pt' | 'pt-br' | 'pt-pt'> = [
+      const languages: Array<
+        | 'de'
+        | 'en'
+        | 'en-gb'
+        | 'en-us'
+        | 'es'
+        | 'fr'
+        | 'it'
+        | 'pt'
+        | 'pt-br'
+        | 'pt-pt'
+      > = [
         'de',
         'en',
         'en-gb',
@@ -658,7 +727,9 @@ describe('WriteService', () => {
       ];
       mockClient.improveText.mockResolvedValue(mockImprovements);
 
-      const result = await cachelessService.improve('Test', { targetLang: 'en-us' });
+      const result = await cachelessService.improve('Test', {
+        targetLang: 'en-us',
+      });
 
       expect(result).toHaveLength(1);
       expect(mockClient.improveText).toHaveBeenCalledTimes(1);

From 186870a7a536436a7424d860705dde982949342f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 22:48:56 -0400
Subject: [PATCH 074/256] chore: prune dead .gitignore entries and un-ignore db
 fixtures
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Remove patterns nothing in the repo produces: build/ and lib/ (output only
goes to dist/), .nyc_output/ (coverage is Jest), .npm, the yarn/pnpm/npm
debug logs and logs/ (redundant with *.log), *.pid/*.seed/*.pid.lock,
cert and credential files, Windows-only OS files, the .cache/.temp/.tmp
family, and .deepl-cli/ (the legacy config dir only resolves under $HOME).

Add !tests/fixtures/*.db so committed fixture databases are not silently
ignored by *.db; the transient sqlite sidecars stay ignored.

Local per-clone tooling (.beads/, issues.jsonl, qa/, .playwright-mcp/)
moves to .git/info/exclude. The set of ignored files is unchanged.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .gitignore | 44 ++++----------------------------------------
 1 file changed, 4 insertions(+), 40 deletions(-)

diff --git a/.gitignore b/.gitignore
index af0927de..f2f12138 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,16 +1,12 @@
 # Dependencies
 node_modules/
-.npm
 
 # Build outputs
 dist/
-build/
-lib/
 *.tsbuildinfo
 
 # Testing
 coverage/
-.nyc_output/
 
 # Environment variables
 .env
@@ -19,11 +15,6 @@ coverage/
 # Secrets and credentials
 *.pem
 *.key
-*.p12
-*.pfx
-*.cert
-*.crt
-credentials.json
 
 # IDEs and editors
 .vscode/
@@ -34,47 +25,20 @@ credentials.json
 
 # OS files
 .DS_Store
-Thumbs.db
-Desktop.ini
-
-# Debug logs
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-
-# Runtime data
-*.pid
-*.seed
-*.pid.lock
 
 # Logs
-logs/
 *.log
 
-# Cache and temporary files
-.cache/
-.temp/
-.tmp/
-*.tmp
+# Caches
 .eslintcache
 
-# DeepL CLI specific
-.deepl-cli/
+# SQLite databases; the cache lives outside the repo, but a stray
+# DEEPL_CONFIG_DIR could land one here. Fixture databases are committed.
 *.db
+!tests/fixtures/*.db
 *.db-journal
 *.db-wal
 *.db-shm
 
 # Claude Code local tooling (settings, hooks, agent worktrees, session state)
 .claude/
-
-# Playwright MCP local state
-.playwright-mcp/
-
-# Beads issue tracking (local)
-.beads/
-issues.jsonl
-
-# QA harness
-qa/

From 4c1c9164b1cf65cbb367dc918e88ccc64ac81d60 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 22:50:54 -0400
Subject: [PATCH 075/256] chore: prune redundant .prettierignore entries
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

node_modules is ignored by prettier natively, and *.log and .DS_Store are
skipped during directory traversal because no parser can be inferred, so
none of the three changed what prettier touched. dist and coverage stay:
prettier does descend into them when pointed at the repo root.

Verified src/data/language-entries.ts is still ignored, and that prettier
would rewrite it without that entry.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .prettierignore | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/.prettierignore b/.prettierignore
index f1d49a79..e4be2aff 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -1,8 +1,7 @@
-node_modules
+# Build and coverage output. The format scripts only cover src/ and tests/,
+# but prettier reaches these when pointed at the repo root.
 dist
 coverage
-*.log
-.DS_Store
 
 # Generated from GET /v3/languages; check:languages compares the raw text, so
 # reformatting it would report permanent drift.

From 4a6820ea81ad96821bfdf1154ae13cf61ed25103 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 22:51:09 -0400
Subject: [PATCH 076/256] ci: gate formatting and fail lint on warnings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`format:check` and `lint` both existed but neither was enforced as written:
nothing ran `format:check`, and `lint` exited 0 on warnings. The prettier
adoption in 01ec9a3 showed why both matter — rewrapping moved four
`eslint-disable-next-line` directives off the lines they suppressed, and the 15
resulting warnings would have gone green.

- `lint` now runs with `--max-warnings 0`, matching the zero-warning baseline
  the repo already held.
- CI runs `format:check` before `lint`, so formatting drift is reported as
  formatting rather than as the lint failures it goes on to cause.
- `format:staged` formats staged `src/` and `tests/` TypeScript and re-stages
  it, for use from a pre-commit hook, so formatting is applied rather than
  remembered. `.git/hooks` is not version-controlled, so CONTRIBUTING.md
  documents enabling it per clone.

Prettier runs twice over the staged set. It preserves whether an object literal
was written multi-line, which interacts with member-chain breaking: an
over-long single-line object ending a chain formats to "chain broken, object
expanded", then to "chain collapsed, object hugged", which is the fixed point.
A single pass would leave content that `format:check` then rejects.

A partially staged file is reported and skipped, since reformatting and
re-adding it would stage hunks the author left out.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/ci.yml  |  4 +++
 CLAUDE.md                 |  4 ++-
 CONTRIBUTING.md           | 18 +++++++++++
 package.json              |  3 +-
 scripts/format-staged.mjs | 63 +++++++++++++++++++++++++++++++++++++++
 5 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 scripts/format-staged.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 29da1801..70d25d03 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -27,6 +27,10 @@ jobs:
           cache: npm
 
       - run: npm ci
+      # Ahead of lint: reformatting can move an eslint-disable directive off the
+      # line it suppresses, so drift should be reported as formatting rather
+      # than as the lint failures it goes on to cause.
+      - run: npm run format:check
       - run: npm run lint
       - run: npm run type-check
       - run: npm run check-deps
diff --git a/CLAUDE.md b/CLAUDE.md
index 122bfc0a..c5cfc8c9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -179,6 +179,7 @@ Use conventional commits:
 - Make separate commits per logical change
 - Group tests with the logic they test
 - **Run `npm run lint` and `npm run type-check` before every commit**
+- **Never silence a lint warning to get past the gate** — `lint` runs with `--max-warnings 0`, so a warning fails CI. Fix the cause; if a rule genuinely does not apply, scope a disable directive to the code it covers and say why
 
 ## Pull Request Guidelines
 
@@ -192,7 +193,8 @@ PR descriptions should include:
 ## Pre-Commit Checklist
 
 - [ ] All tests pass (`npm test`)
-- [ ] Linter passes (`npm run lint`)
+- [ ] Formatting is clean (`npm run format:check`) — the format-on-commit hook handles this if enabled; see CONTRIBUTING.md
+- [ ] Linter passes (`npm run lint`) — warnings fail the build (`--max-warnings 0`)
 - [ ] TypeScript compiles (`npm run type-check`)
 - [ ] Unit, integration, and E2E tests written for new features
 - [ ] HTTP mocking with nock for API interactions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 547317a5..3ba23509 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -36,6 +36,24 @@ npm link
 deepl --version
 ```
 
+### Enable the formatting hook
+
+CI runs `npm run format:check`, and `.git/hooks` is not version-controlled, so
+enable the format-on-commit hook once per clone. It formats only the staged
+`src/` and `tests/` TypeScript and re-stages it, so formatting is applied rather
+than something you have to remember:
+
+```bash
+cat >> .git/hooks/pre-commit <<'HOOK'
+npm run --silent format:staged || exit $?
+HOOK
+chmod +x .git/hooks/pre-commit
+```
+
+A partially staged file is reported and skipped rather than reformatted, because
+re-adding it would stage the hunks you deliberately left out. Run
+`npm run format` yourself in that case.
+
 ## Development Workflow
 
 This project follows **Test-Driven Development (TDD)**. Every change goes through the Red-Green-Refactor cycle:
diff --git a/package.json b/package.json
index 61ab9780..a7fc770c 100644
--- a/package.json
+++ b/package.json
@@ -39,12 +39,13 @@
     "test:debug": "jest --runInBand --detectOpenHandles --forceExit=false",
     "examples": "bash examples/run-all.sh",
     "examples:fast": "bash examples/run-all.sh --fast",
-    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts' --max-warnings 0",
     "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
     "type-check": "tsc --noEmit",
     "check-deps": "node scripts/check-dependencies.mjs",
     "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:staged": "node scripts/format-staged.mjs",
     "prepublishOnly": "npm run build",
     "generate:languages": "node scripts/generate-language-registry.mjs",
     "check:languages": "node scripts/generate-language-registry.mjs --check"
diff --git a/scripts/format-staged.mjs b/scripts/format-staged.mjs
new file mode 100644
index 00000000..02408239
--- /dev/null
+++ b/scripts/format-staged.mjs
@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Formats staged TypeScript files with Prettier and re-stages them, so
+ * formatting is applied rather than asked of the author and `format:check`
+ * cannot fail in CI for a commit made through this hook.
+ *
+ * Prettier is run twice. It preserves whether an object literal was written
+ * multi-line, and that interacts with member-chain breaking: an over-long
+ * single-line object at the end of a chain formats to "chain broken, object
+ * expanded" on the first pass, then to "chain collapsed, object hugged" on the
+ * second, which is the fixed point. One pass would leave content a later
+ * `format:check` rejects.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PREFIXES = ['src/', 'tests/'];
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf-8' });
+}
+
+function paths(args) {
+  return new Set(
+    git(args)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+  );
+}
+
+const staged = [...paths(['diff', '--cached', '--name-only', '--diff-filter=ACM'])]
+  .filter((file) => file.endsWith('.ts'))
+  .filter((file) => PREFIXES.some((prefix) => file.startsWith(prefix)));
+
+// Rewriting a file that is only partially staged and then re-adding it would
+// stage the hunks the author deliberately left out, so those are reported and
+// left alone rather than quietly widened.
+const unstaged = paths(['diff', '--name-only', '--diff-filter=ACM']);
+const partial = staged.filter((file) => unstaged.has(file));
+const safe = staged.filter((file) => !unstaged.has(file));
+
+if (partial.length > 0) {
+  console.warn(
+    `prettier: skipping ${partial.length} partially staged file(s); run "npm run format" before committing:\n` +
+      partial.map((file) => `  ${file}`).join('\n')
+  );
+}
+
+if (safe.length === 0) {
+  process.exit(0);
+}
+
+// Respects .prettierignore, so an ignored file — the generated language
+// snapshot — is skipped rather than rewritten into permanent check:languages
+// drift.
+for (let pass = 0; pass < 2; pass++) {
+  execFileSync('npx', ['prettier', '--write', '--ignore-unknown', ...safe], {
+    stdio: 'inherit',
+  });
+}
+
+git(['add', '--', ...safe]);

From 1365d369df685fd9ed7000813ab178cd3081ca1c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Tue, 4 Aug 2026 22:54:26 -0400
Subject: [PATCH 077/256] chore: guard test fixtures in .prettierignore
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A root-level prettier run reached test fixtures, which are byte-exact
inputs. en-reserved-words.yaml quotes "yes"/"no" so YAML 1.1 cannot read
them as booleans, and prettier rewrites those to single quotes; the sync
context fixtures are parsed for surrounding source, so rewriting them
changes what the extractor sees.

No change to the format scripts' scope, which stays src/ and tests/;
format:check still passes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .prettierignore | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/.prettierignore b/.prettierignore
index e4be2aff..03e611fe 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -1,8 +1,15 @@
-# Build and coverage output. The format scripts only cover src/ and tests/,
-# but prettier reaches these when pointed at the repo root.
+# The format scripts only cover src/ and tests/, but prettier reaches
+# everything below when pointed at the repo root.
+
+# Build and coverage output
 dist
 coverage
 
 # Generated from GET /v3/languages; check:languages compares the raw text, so
 # reformatting it would report permanent drift.
 src/data/language-entries.ts
+
+# Fixtures are byte-exact test inputs. Some encode the very thing under test:
+# en-reserved-words.yaml quotes "yes"/"no" so YAML 1.1 cannot read them as
+# booleans, and prettier rewrites those quotes.
+tests/fixtures/

From 9d494fa5df8d31c86397b84967234d7689d77652 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 07:00:20 -0400
Subject: [PATCH 078/256] fix(test): restore coverage source maps in ts-jest
 transform
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Coverage was measured against the emitted JavaScript without source maps,
so istanbul attributed statements and functions to arbitrary positions --
import lines and JSDoc blocks were reported as uncovered, and downlevel
helpers appeared as never-executed anonymous functions. Reported totals
sat 4-8 points below the real ones and every configured threshold failed
while all tests passed.

tsconfig.json sets sourceMap:false so maps stay out of the published
tarball, and ts-jest merges the transform's inline options over that file
rather than replacing it, so the setting has to be re-enabled here.

Measured against the same 6536 tests, no test changes:

  statements  90.47% -> 94.84%  (threshold 93)
  branches    82.36% -> 88.64%  (threshold 86)
  lines       92.15% -> 95.30%  (threshold 93)
  functions   86.50% -> 94.71%  (threshold 94)

npm run test:coverage now exits 0.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 jest.config.js | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/jest.config.js b/jest.config.js
index 290b6b46..158dff48 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -56,6 +56,11 @@ export default {
   transform: {
     '^.+\\.tsx?$': ['ts-jest', {
       tsconfig: {
+        // tsconfig.json disables source maps to keep them out of the published
+        // package. ts-jest merges the options below over that file rather than
+        // replacing it, and istanbul needs the maps to attribute coverage to
+        // TypeScript lines instead of to positions in the emitted JavaScript.
+        sourceMap: true,
         // Relaxed settings for tests
         strict: true,
         esModuleInterop: true,

From cf5e4b833ed4a350f389dd4fdee23c5c831b20e5 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 07:53:31 -0400
Subject: [PATCH 079/256] test: cover parsePositiveIntOption bounds and lenient
 parsing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bounded-integer option parser behind --concurrency and --debounce had
no test of its own, so the rejection branch it exists for was unexercised:
0%, with the whole guard resting on code no test called.

Covers both sides of the boundary (1, max inclusive, max+1, zero, negative,
non-numeric, empty, whitespace, hex, Infinity) and the error message's
option name, bounds and offending value.

Also pins Number.parseInt's leniency, which the guard inherits and which is
easy to mistake for a rejection: '4.7' yields 4, '4abc' yields 4, and '1e3'
yields 1 rather than 1000. Those reach the option value as-is.

parse-int-option.ts: 33.33% -> 100% statements, 0% -> 100% branches.
Suite totals: statements 94.88, branches 88.72, lines 95.34, functions 94.78.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/cli/parse-int-option.test.ts | 84 +++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 tests/unit/cli/parse-int-option.test.ts

diff --git a/tests/unit/cli/parse-int-option.test.ts b/tests/unit/cli/parse-int-option.test.ts
new file mode 100644
index 00000000..a7185130
--- /dev/null
+++ b/tests/unit/cli/parse-int-option.test.ts
@@ -0,0 +1,84 @@
+/**
+ * Unit tests for the bounded positive-integer option parser.
+ *
+ * Number.parseInt is lenient — it truncates decimals and stops at the first
+ * non-digit — so some inputs that look invalid still yield a usable integer.
+ * Those are pinned here alongside the rejections, since the difference is what
+ * reaches the option value downstream.
+ */
+
+import { InvalidArgumentError } from 'commander';
+import { parsePositiveIntOption } from '../../../src/cli/commands/parse-int-option';
+
+describe('parsePositiveIntOption', () => {
+  describe('accepted values', () => {
+    it('returns the parsed integer', () => {
+      expect(parsePositiveIntOption('7', 'concurrency', 100)).toBe(7);
+    });
+
+    it('accepts the lower bound of 1', () => {
+      expect(parsePositiveIntOption('1', 'concurrency', 100)).toBe(1);
+    });
+
+    it('accepts the maximum inclusively', () => {
+      expect(parsePositiveIntOption('100', 'concurrency', 100)).toBe(100);
+    });
+
+    it('tolerates surrounding whitespace', () => {
+      expect(parsePositiveIntOption(' 5 ', 'concurrency', 100)).toBe(5);
+      expect(parsePositiveIntOption('\t7', 'concurrency', 100)).toBe(7);
+    });
+
+    it('accepts an explicit plus sign', () => {
+      expect(parsePositiveIntOption('+5', 'concurrency', 100)).toBe(5);
+    });
+  });
+
+  describe('rejected values', () => {
+    it.each([
+      '0',
+      '-1',
+      '-0',
+      '101',
+      '99999',
+      'abc',
+      '',
+      '  ',
+      '0x10',
+      'Infinity',
+    ])('rejects %p with an InvalidArgumentError', (value) => {
+      expect(() => parsePositiveIntOption(value, 'concurrency', 100)).toThrow(
+        InvalidArgumentError
+      );
+    });
+  });
+
+  describe('error message', () => {
+    it('names the option, the bounds, and the offending value', () => {
+      expect(() => parsePositiveIntOption('0', 'concurrency', 100)).toThrow(
+        "--concurrency must be an integer between 1 and 100, got '0'"
+      );
+    });
+
+    it('uses the caller-supplied name and maximum', () => {
+      expect(() => parsePositiveIntOption('0', 'debounce', 600_000)).toThrow(
+        "--debounce must be an integer between 1 and 600000, got '0'"
+      );
+    });
+  });
+
+  describe('lenient integer parsing', () => {
+    it('truncates a decimal rather than rejecting it', () => {
+      expect(parsePositiveIntOption('4.7', 'concurrency', 100)).toBe(4);
+      expect(parsePositiveIntOption('1.9', 'concurrency', 100)).toBe(1);
+    });
+
+    it('stops at the first non-digit rather than rejecting', () => {
+      expect(parsePositiveIntOption('4abc', 'concurrency', 100)).toBe(4);
+    });
+
+    it('reads scientific notation as its leading digits', () => {
+      expect(parsePositiveIntOption('1e3', 'concurrency', 100)).toBe(1);
+    });
+  });
+});

From 52cae803a8731e333b672df5a026bf54cc4d1da3 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 08:19:10 -0400
Subject: [PATCH 080/256] test: cover _describe and tm command registration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both files reported 0% coverage because only E2E reached them, and E2E
spawns a subprocess so it contributes none. Excluding them as CLI glue was
the cheaper option, but neither turned out to be glue:

register-describe.ts normalises --format with toLowerCase().trim() before
validating it, and no test covered the normalisation -- the E2E suite only
passes a valid 'json' and an invalid 'yaml'. Uppercase and padded values are
now pinned as accepted.

register-tm.ts chooses between the formatted table and raw JSON on --format,
and that dispatch was covered by nothing at all: cli-tm.e2e.test.ts exercises
only --help, a missing API key, and registration. So the exclusion would have
hidden an untested branch rather than classified a tested one.

jest.config.js is therefore unchanged; no new coverage exclusions.

register-describe.ts  0% -> 100% statements (branches 66.66%; the two
  remaining are `opts.format ?? …` fallbacks that commander's 'json'
  default makes unreachable)
register-tm.ts        0% -> 100% statements, branches, functions
Suite totals: statements 95.14, branches 88.83, lines 95.61, functions 95.05

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/cli/register-describe.test.ts | 110 +++++++++++++++++++++++
 tests/unit/cli/register-tm.test.ts       | 107 ++++++++++++++++++++++
 2 files changed, 217 insertions(+)
 create mode 100644 tests/unit/cli/register-describe.test.ts
 create mode 100644 tests/unit/cli/register-tm.test.ts

diff --git a/tests/unit/cli/register-describe.test.ts b/tests/unit/cli/register-describe.test.ts
new file mode 100644
index 00000000..1b58c34a
--- /dev/null
+++ b/tests/unit/cli/register-describe.test.ts
@@ -0,0 +1,110 @@
+/**
+ * Unit tests for the hidden `_describe` command registration.
+ *
+ * The action normalises --format before validating it, so a value differing
+ * only in case or surrounding whitespace is accepted rather than rejected.
+ */
+
+import { Command } from 'commander';
+
+jest.mock('../../../src/utils/logger', () => ({
+  Logger: {
+    info: jest.fn(),
+    warn: jest.fn(),
+    success: jest.fn(),
+    output: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+import { registerDescribe } from '../../../src/cli/commands/register-describe';
+import { Logger } from '../../../src/utils/logger';
+import { ValidationError } from '../../../src/utils/errors';
+
+describe('registerDescribe', () => {
+  let program: Command;
+  let handleError: jest.Mock;
+
+  beforeEach(() => {
+    program = new Command();
+    program.name('deepl').description('DeepL CLI');
+    program.exitOverride();
+    handleError = jest.fn();
+    registerDescribe(program, {
+      handleError: handleError as unknown as (error: unknown) => never,
+    });
+  });
+
+  async function runDescribe(argv: string[] = []): Promise<void> {
+    await program.parseAsync(['node', 'deepl', '_describe', ...argv]);
+  }
+
+  function emittedTree(): { name: string; commands: { name: string }[] } {
+    const [payload] = (Logger.output as jest.Mock).mock.calls[0] as [string];
+    return JSON.parse(payload);
+  }
+
+  describe('emitting the surface', () => {
+    it('writes the program tree as JSON when no format is given', async () => {
+      await runDescribe();
+
+      expect(handleError).not.toHaveBeenCalled();
+      expect(Logger.output).toHaveBeenCalledTimes(1);
+      expect(emittedTree().name).toBe('deepl');
+    });
+
+    it('includes the registered command in the tree', async () => {
+      await runDescribe();
+
+      expect(emittedTree().commands.map((c) => c.name)).toContain('_describe');
+    });
+
+    it('pretty-prints with two-space indentation', async () => {
+      await runDescribe();
+
+      const [payload] = (Logger.output as jest.Mock).mock.calls[0] as [string];
+      expect(payload).toContain('\n  "name": "deepl"');
+    });
+
+    it('accepts --format json explicitly', async () => {
+      await runDescribe(['--format', 'json']);
+
+      expect(handleError).not.toHaveBeenCalled();
+      expect(Logger.output).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('format normalisation', () => {
+    it('accepts an uppercase format', async () => {
+      await runDescribe(['--format', 'JSON']);
+
+      expect(handleError).not.toHaveBeenCalled();
+      expect(Logger.output).toHaveBeenCalledTimes(1);
+    });
+
+    it('accepts a format padded with whitespace', async () => {
+      await runDescribe(['--format', '  json  ']);
+
+      expect(handleError).not.toHaveBeenCalled();
+      expect(Logger.output).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('rejecting an unsupported format', () => {
+    it('routes a ValidationError to handleError', async () => {
+      await runDescribe(['--format', 'yaml']);
+
+      expect(Logger.output).not.toHaveBeenCalled();
+      expect(handleError).toHaveBeenCalledTimes(1);
+      expect(handleError.mock.calls[0]![0]).toBeInstanceOf(ValidationError);
+    });
+
+    it('names the offending value and the supported formats', async () => {
+      await runDescribe(['--format', 'yaml']);
+
+      const error = handleError.mock.calls[0]![0] as ValidationError;
+      expect(error.message).toContain('yaml');
+      expect(error.message).toContain('json');
+    });
+  });
+});
diff --git a/tests/unit/cli/register-tm.test.ts b/tests/unit/cli/register-tm.test.ts
new file mode 100644
index 00000000..34ed0b60
--- /dev/null
+++ b/tests/unit/cli/register-tm.test.ts
@@ -0,0 +1,107 @@
+/**
+ * Unit tests for the `deepl tm` command registration.
+ *
+ * `tm list` chooses between the formatted table and raw JSON on --format, and
+ * that dispatch is the only behaviour the registration itself carries.
+ */
+
+import { Command } from 'commander';
+
+jest.mock('../../../src/utils/logger', () => ({
+  Logger: {
+    info: jest.fn(),
+    warn: jest.fn(),
+    success: jest.fn(),
+    output: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+jest.mock('../../../src/cli/commands/service-factory', () => ({
+  createTmCommand: jest.fn(),
+}));
+
+import { registerTm } from '../../../src/cli/commands/register-tm';
+import { createTmCommand } from '../../../src/cli/commands/service-factory';
+import { Logger } from '../../../src/utils/logger';
+
+const mockCreateTmCommand = createTmCommand as jest.MockedFunction<
+  typeof createTmCommand
+>;
+
+const TMS = [{ translationMemoryId: 'tm-1', name: 'legal' }];
+
+describe('registerTm', () => {
+  let program: Command;
+  let handleError: jest.Mock;
+  let list: jest.Mock;
+  let formatList: jest.Mock;
+
+  beforeEach(() => {
+    list = jest.fn().mockResolvedValue(TMS);
+    formatList = jest.fn().mockReturnValue('tm-table');
+    mockCreateTmCommand.mockResolvedValue({
+      list,
+      formatList,
+    } as unknown as Awaited<ReturnType<typeof createTmCommand>>);
+
+    program = new Command();
+    program.exitOverride();
+    handleError = jest.fn();
+    registerTm(program, {
+      createDeepLClient: jest.fn(),
+      handleError: handleError as unknown as (error: unknown) => never,
+    });
+  });
+
+  async function runTmList(argv: string[] = []): Promise<void> {
+    await program.parseAsync(['node', 'deepl', 'tm', 'list', ...argv]);
+  }
+
+  describe('output format', () => {
+    it('prints the formatted table by default', async () => {
+      await runTmList();
+
+      expect(formatList).toHaveBeenCalledWith(TMS);
+      expect(Logger.output).toHaveBeenCalledWith('tm-table');
+      expect(handleError).not.toHaveBeenCalled();
+    });
+
+    it('prints raw JSON when --format json', async () => {
+      await runTmList(['--format', 'json']);
+
+      expect(Logger.output).toHaveBeenCalledWith(JSON.stringify(TMS, null, 2));
+      expect(formatList).not.toHaveBeenCalled();
+    });
+
+    it('prints the formatted table when --format text is explicit', async () => {
+      await runTmList(['--format', 'text']);
+
+      expect(formatList).toHaveBeenCalledWith(TMS);
+      expect(Logger.output).toHaveBeenCalledWith('tm-table');
+    });
+  });
+
+  describe('error handling', () => {
+    it('routes a listing failure to handleError', async () => {
+      list.mockRejectedValue(new Error('boom'));
+
+      await runTmList();
+
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'boom' })
+      );
+      expect(Logger.output).not.toHaveBeenCalled();
+    });
+
+    it('routes a client construction failure to handleError', async () => {
+      mockCreateTmCommand.mockRejectedValue(new Error('no api key'));
+
+      await runTmList();
+
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'no api key' })
+      );
+    });
+  });
+});

From 5c829b2ef2057f47679c126d934d95215efd6b95 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 08:29:13 -0400
Subject: [PATCH 081/256] test(sync): wait on the outcome in the auto-commit
 watch-cycle test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The test fired a change event, advanced past the debounce window, then
drained a fixed 25 rounds and asserted the commit count. That budget races
loop iterations against the real filesystem I/O in sweepStaleBackups, and it
failed once under coverage instrumentation with "Expected 3, Received 2".

The mechanism is the controller's deliberate coalescing: runOnce() sets
pendingRun and returns when a sync is already in flight, so an overlapping
second cycle commits only after the first reaches its `finally` and
re-dispatches -- several hops beyond where the fixed drain stopped.

Each cycle now waits until its own commit has landed before the next event is
fired. That is sound rather than lenient: coalescing defers a cycle, it never
drops one, so the expected count is always reached eventually, and a real
regression still fails via the round ceiling instead of an off-by-one on a
half-settled pipeline. The assertions stay exact (toBe, not toBeGreaterThan).

Proof the drain is no longer load-bearing: with SETTLE_ROUNDS forced to 0
this test passes, where previously it depended on the drain. Two other tests
in the block do fail at 0 -- "returns SIGINT/SIGTERM listener counts to their
baseline" and "should log the number of watched patterns" -- so they carry the
same latent fragility, but neither has been observed flaking and both are left
alone here.

The original intermittent failure could not be reproduced deterministically
(it survives SETTLE_ROUNDS=0/1/2, removal of the inter-cycle drain, and eight
CPU spinners), so the fix rests on the convergence argument above rather than
on a red-to-green demonstration. Suite unchanged at 6569 passing; coverage
unchanged.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/sync/sync-command.test.ts | 67 +++++++++++++++++++---------
 1 file changed, 47 insertions(+), 20 deletions(-)

diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index bb097e4e..1f33ac3c 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -1124,6 +1124,34 @@ describe('SyncCommand', () => {
       }
     }
 
+    // A watch cycle's observable effect lands several async hops after the
+    // debounce timer fires, and a cycle overlapping an in-flight sync is
+    // coalesced into `pendingRun` — its effect then arrives only once the
+    // running sync reaches its `finally` and re-dispatches. The number of hops
+    // therefore depends on real filesystem I/O timing, so a fixed drain races
+    // microsecond-scale loop iterations against millisecond-scale syscalls,
+    // exactly as phase 1 of flushWatchSetup avoids doing.
+    //
+    // Waiting on the outcome is sound rather than merely lenient: coalescing
+    // defers a cycle, it never drops one, so the expected count is always
+    // reached eventually. A genuine regression still fails, via the ceiling
+    // below rather than an off-by-one on a half-settled pipeline.
+    async function flushUntil(
+      isSettled: () => boolean,
+      what: string
+    ): Promise<void> {
+      let rounds = 0;
+      while (!isSettled()) {
+        if (rounds >= SETUP_READY_MAX_ROUNDS) {
+          throw new Error(
+            `${what} did not settle within ${SETUP_READY_MAX_ROUNDS} flush rounds`
+          );
+        }
+        await flushRound();
+        rounds++;
+      }
+    }
+
     it('should create a chokidar watcher with bucket include patterns', async () => {
       const result = makeResult();
       const mockService = createMockSyncService(result);
@@ -1263,37 +1291,36 @@ describe('SyncCommand', () => {
 
       await flushWatchSetup();
 
+      const commitCount = (): number =>
+        mockExecFile.mock.calls.filter(
+          (c: unknown[]) =>
+            Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
+        ).length;
+
       // Baseline: the pre-watch initial sync should already have committed once.
-      const commitsBefore = mockExecFile.mock.calls.filter(
-        (c: unknown[]) =>
-          Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
-      ).length;
+      const commitsBefore = commitCount();
       expect(commitsBefore).toBeGreaterThanOrEqual(1);
 
       // Trigger a watch cycle by firing one of the registered change handlers,
-      // then advance timers past the debounce window and flush microtasks so
-      // the queued sync + autoCommit pipeline runs to completion.
+      // then advance timers past the debounce window and wait for that cycle's
+      // commit before starting the next, so the two cycles cannot coalesce.
       expect(registeredHandlers.length).toBeGreaterThan(0);
       registeredHandlers[0]!();
       await jest.advanceTimersByTimeAsync(60);
-      await flushWatchSetup();
-
-      const commitsAfterFirstCycle = mockExecFile.mock.calls.filter(
-        (c: unknown[]) =>
-          Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
-      ).length;
-      expect(commitsAfterFirstCycle).toBe(commitsBefore + 1);
+      await flushUntil(
+        () => commitCount() >= commitsBefore + 1,
+        'first watch cycle commit'
+      );
+      expect(commitCount()).toBe(commitsBefore + 1);
 
       // Second cycle — an independent edit should produce another commit.
       registeredHandlers[0]!();
       await jest.advanceTimersByTimeAsync(60);
-      await flushWatchSetup();
-
-      const commitsAfterSecondCycle = mockExecFile.mock.calls.filter(
-        (c: unknown[]) =>
-          Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
-      ).length;
-      expect(commitsAfterSecondCycle).toBe(commitsBefore + 2);
+      await flushUntil(
+        () => commitCount() >= commitsBefore + 2,
+        'second watch cycle commit'
+      );
+      expect(commitCount()).toBe(commitsBefore + 2);
 
       for (const listener of sigintListeners) listener();
       await runPromise;

From a89f10bd03e47952594487892ac11b7ee7908bf4 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 08:46:50 -0400
Subject: [PATCH 082/256] test(sync): assert the bounded-integer parser is
 wired to --concurrency/--debounce
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

parsePositiveIntOption is now fully covered, but nothing asserted it was
attached to the options that use it. Dropping the parser, or widening a bound,
would have restored the original defect -- an out-of-range --concurrency
reaching worker-pool sizing -- with every test still green.

Each option now has its rejections driven through commander, which converts
the parser's InvalidArgumentError into a CommanderError before any action
runs, so the rejection is observed out of parseAsync and the sync is proven
not to start. The in-range cases assert the value arrives at run() as a
number rather than the raw string, which is the parser's other job.

Verified discriminating by mutation: widening the --concurrency bound from
100 to 100000 fails exactly one test (rejects "101") and leaves the other 13
passing. A rebuild is required between mutating src/ and running, or the
build guard in tests/setup.ts fails every test in the file instead.

Also hoists the shared empty sync result to a module constant, since the new
block needs the same stub.

No coverage change: register-sync-*.ts is excluded from collectCoverageFrom.
Suite 6569 -> 6578 passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/cli/register-sync-root.test.ts | 115 ++++++++++++++++++----
 1 file changed, 97 insertions(+), 18 deletions(-)

diff --git a/tests/unit/cli/register-sync-root.test.ts b/tests/unit/cli/register-sync-root.test.ts
index 4adc6673..c41dc2fe 100644
--- a/tests/unit/cli/register-sync-root.test.ts
+++ b/tests/unit/cli/register-sync-root.test.ts
@@ -35,6 +35,25 @@ function makeDeps(handleError: jest.Mock): ServiceDeps {
   };
 }
 
+const EMPTY_SYNC_RESULT = {
+  success: true,
+  totalKeys: 0,
+  newKeys: 0,
+  staleKeys: 0,
+  deletedKeys: 0,
+  currentKeys: 0,
+  totalCharactersBilled: 0,
+  fileResults: [],
+  validationWarnings: 0,
+  validationErrors: 0,
+  estimatedCharacters: 0,
+  targetLocaleCount: 0,
+  dryRun: false,
+  frozen: false,
+  driftDetected: false,
+  lockUpdated: false,
+};
+
 async function runSync(argv: string[], deps: ServiceDeps): Promise<void> {
   const program = new Command();
   program.exitOverride();
@@ -54,24 +73,7 @@ describe('deepl sync --context hard-error', () => {
       Promise.resolve({
         run: jest.fn((opts: Record<string, unknown>) => {
           capturedSyncOptions = opts;
-          return Promise.resolve({
-            success: true,
-            totalKeys: 0,
-            newKeys: 0,
-            staleKeys: 0,
-            deletedKeys: 0,
-            currentKeys: 0,
-            totalCharactersBilled: 0,
-            fileResults: [],
-            validationWarnings: 0,
-            validationErrors: 0,
-            estimatedCharacters: 0,
-            targetLocaleCount: 0,
-            dryRun: false,
-            frozen: false,
-            driftDetected: false,
-            lockUpdated: false,
-          });
+          return Promise.resolve(EMPTY_SYNC_RESULT);
         }),
       })
     );
@@ -131,3 +133,80 @@ describe('deepl sync --context hard-error', () => {
     expect(capturedSyncOptions?.['context']).toBeUndefined();
   });
 });
+
+describe('deepl sync bounded integer options', () => {
+  let handleError: jest.Mock;
+  let capturedSyncOptions: Record<string, unknown> | undefined;
+
+  beforeEach(() => {
+    handleError = jest.fn();
+    capturedSyncOptions = undefined;
+    mockCreateSyncCommand.mockReset();
+    mockCreateSyncCommand.mockImplementation(() =>
+      Promise.resolve({
+        run: jest.fn((opts: Record<string, unknown>) => {
+          capturedSyncOptions = opts;
+          return Promise.resolve(EMPTY_SYNC_RESULT);
+        }),
+      })
+    );
+  });
+
+  // Commander converts an InvalidArgumentError thrown by an option parser into
+  // a CommanderError before any action runs, so the rejection surfaces out of
+  // parseAsync rather than through handleError.
+  async function parseExpectingRejection(argv: string[]): Promise<Error> {
+    const program = new Command();
+    program.exitOverride();
+    program.configureOutput({ writeErr: () => {} });
+    registerSync(program, makeDeps(handleError));
+    try {
+      await program.parseAsync(['node', 'deepl', 'sync', ...argv]);
+    } catch (error) {
+      return error as Error;
+    }
+    throw new Error(`expected 'sync ${argv.join(' ')}' to be rejected`);
+  }
+
+  describe('--concurrency', () => {
+    it.each(['0', '-1', '101', 'abc'])(
+      'rejects %p without starting a sync',
+      async (value) => {
+        const error = await parseExpectingRejection(['--concurrency', value]);
+
+        expect(error.message).toContain(
+          '--concurrency must be an integer between 1 and 100'
+        );
+        expect(mockCreateSyncCommand).not.toHaveBeenCalled();
+      }
+    );
+
+    it('passes an in-range value through as a number', async () => {
+      await runSync(['--concurrency', '7'], makeDeps(handleError));
+
+      expect(handleError).not.toHaveBeenCalled();
+      expect(capturedSyncOptions?.['concurrency']).toBe(7);
+    });
+  });
+
+  describe('--debounce', () => {
+    it.each(['0', '600001', 'abc'])(
+      'rejects %p without starting a sync',
+      async (value) => {
+        const error = await parseExpectingRejection(['--debounce', value]);
+
+        expect(error.message).toContain(
+          '--debounce must be an integer between 1 and 600000'
+        );
+        expect(mockCreateSyncCommand).not.toHaveBeenCalled();
+      }
+    );
+
+    it('passes an in-range value through as a number', async () => {
+      await runSync(['--debounce', '250'], makeDeps(handleError));
+
+      expect(handleError).not.toHaveBeenCalled();
+      expect(capturedSyncOptions?.['debounce']).toBe(250);
+    });
+  });
+});

From fa1387b216bdb8672a9befdcff7db9d9301dda33 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 08:56:58 -0400
Subject: [PATCH 083/256] style(test): trim comment justification from the
 watch-cycle flush helper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The comment argued for the helper over the fixed-drain approach it replaced
rather than describing what the code does. Keeps the coalescing mechanism and
the defer-never-drop invariant, which are what a reader needs to see why
awaiting the count terminates; drops the comparison.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/sync/sync-command.test.ts | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index 1f33ac3c..c8cd30fb 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -1126,16 +1126,9 @@ describe('SyncCommand', () => {
 
     // A watch cycle's observable effect lands several async hops after the
     // debounce timer fires, and a cycle overlapping an in-flight sync is
-    // coalesced into `pendingRun` — its effect then arrives only once the
-    // running sync reaches its `finally` and re-dispatches. The number of hops
-    // therefore depends on real filesystem I/O timing, so a fixed drain races
-    // microsecond-scale loop iterations against millisecond-scale syscalls,
-    // exactly as phase 1 of flushWatchSetup avoids doing.
-    //
-    // Waiting on the outcome is sound rather than merely lenient: coalescing
-    // defers a cycle, it never drops one, so the expected count is always
-    // reached eventually. A genuine regression still fails, via the ceiling
-    // below rather than an off-by-one on a half-settled pipeline.
+    // coalesced into `pendingRun` — its effect arrives only once the running
+    // sync reaches its `finally` and re-dispatches. Coalescing defers a cycle
+    // and never drops one, so the awaited count is always reached eventually.
     async function flushUntil(
       isSettled: () => boolean,
       what: string

From a7c78c2939763ec1a62c45a9a539934151e6084f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 08:57:00 -0400
Subject: [PATCH 084/256] ci: gate on coverage thresholds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI ran `npm test`, which ignores the coverageThreshold block in
jest.config.js, so the thresholds set at the 1.0.0 release had never once
been enforced. They are now, via test:coverage -- the same suite plus the
gate.

Kept at 93/86/93/94 rather than raised to the measured 95.14/88.83/95.61/
95.05. Functions is the binding metric either way: it clears 94 by 0.71,
leaving room for roughly 16 more uncovered functions, where the other three
have room for 90+. Raising the floors would tighten only the metrics that
were not going to fail first, at the cost of four numbers to hand-maintain.

Contributor docs said `npm test` was sufficient, which would now pass
locally and fail the build, so the pre-commit checklist in CLAUDE.md and the
pre-push command and PR checklist in CONTRIBUTING.md name test:coverage
instead.

No CHANGELOG entry, matching 4a6820e, the comparable CI-gate change.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 2 +-
 CLAUDE.md                | 1 +
 CONTRIBUTING.md          | 6 ++++--
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 70d25d03..09f6861d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -35,4 +35,4 @@ jobs:
       - run: npm run type-check
       - run: npm run check-deps
       - run: npm run build
-      - run: npm test
+      - run: npm run test:coverage
diff --git a/CLAUDE.md b/CLAUDE.md
index c5cfc8c9..32207b01 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -193,6 +193,7 @@ PR descriptions should include:
 ## Pre-Commit Checklist
 
 - [ ] All tests pass (`npm test`)
+- [ ] Coverage thresholds hold (`npm run test:coverage`) — this is what CI runs, so a change that passes `npm test` can still fail the build
 - [ ] Formatting is clean (`npm run format:check`) — the format-on-commit hook handles this if enabled; see CONTRIBUTING.md
 - [ ] Linter passes (`npm run lint`) — warnings fail the build (`--max-warnings 0`)
 - [ ] TypeScript compiles (`npm run type-check`)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3ba23509..2978ad3e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -196,8 +196,10 @@ Contributions must be licensed under the same license as the project:
 2. **Write tests first**, then implement the feature (TDD).
 3. **Run the full check suite** before pushing:
    ```bash
-   npm test && npm run lint && npm run type-check && npm run build
+   npm run test:coverage && npm run lint && npm run type-check && npm run build
    ```
+   `test:coverage` runs the same suite as `npm test` and additionally enforces
+   the coverage thresholds, which is what CI gates on.
 4. **Open a PR** with a clear description covering:
    - Summary of the change and motivation
    - List of specific changes
@@ -207,7 +209,7 @@ Contributions must be licensed under the same license as the project:
 
 ### PR Checklist
 
-- [ ] All tests pass (`npm test`)
+- [ ] All tests pass and coverage thresholds hold (`npm run test:coverage`)
 - [ ] Linter passes (`npm run lint`)
 - [ ] TypeScript compiles (`npm run type-check`)
 - [ ] New code includes unit, integration, and e2e tests

From 460695b73c745f41440d9113bd013c49d5d7ee20 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 10:09:23 -0400
Subject: [PATCH 085/256] test(sync): cover the process lock's failure and
 hand-off branches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The lock arbitrates concurrent syncs in one directory, but only its three
main paths were exercised, by sync-concurrent.integration.test.ts: release
and reacquire, stale reclaim, and refusal on a live PID. That left the error
branches -- the ones that decide whether a lock is stolen or a stranger's
pidfile is deleted -- at 56% branch coverage with no unit test of their own.

Now covered:

- liveness probe: a genuinely running PID and an EPERM probe both count as
  alive and refuse the lock; ESRCH and any unrecognised errno count as dead
  and reclaim it
- pidfile contents no sync wrote (not JSON, a bare string, absent/fractional/
  zero/negative pid, absent startedAt) are treated as stale and reclaimed,
  reported as "unknown PID" rather than a guess, and never probed for liveness
- a read failure other than ENOENT propagates instead of being read as stale,
  so an unreadable lock is not silently stolen
- the stale pidfile vanishing before the unlink is tolerated; any other
  unlink errno propagates
- release() leaves the pidfile alone once another process owns it, stays quiet
  when it is already gone, warns rather than throws when it cannot be removed,
  and unlinks only once across repeated calls
- a write failure other than EEXIST propagates

jest.spyOn cannot patch the namespace object ts-jest builds for
`import * as fs`, whose properties are non-configurable getters; the spies
target the module object those getters read through.

sync-process-lock.ts: 75.4% -> 100% statements, 56.25% -> 96.87% branches.
The one uncovered branch is the String(err) fallback for a thrown non-Error,
which fs does not produce. Suite totals: statements 95.30, branches 89.09,
lines 95.73, functions 95.05.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/sync/sync-process-lock.test.ts | 278 ++++++++++++++++++++++
 1 file changed, 278 insertions(+)
 create mode 100644 tests/unit/sync/sync-process-lock.test.ts

diff --git a/tests/unit/sync/sync-process-lock.test.ts b/tests/unit/sync/sync-process-lock.test.ts
new file mode 100644
index 00000000..f5625d12
--- /dev/null
+++ b/tests/unit/sync/sync-process-lock.test.ts
@@ -0,0 +1,278 @@
+/**
+ * Unit tests for the `deepl sync` process lock.
+ *
+ * The lock arbitrates between concurrent syncs in one directory, so its error
+ * paths are the interesting ones: a liveness probe that cannot see the process
+ * it is asking about, a pidfile holding content no sync wrote, and a pidfile
+ * that changes owner or disappears between the check and the unlink.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+jest.mock('../../../src/utils/logger', () => ({
+  Logger: {
+    info: jest.fn(),
+    warn: jest.fn(),
+    success: jest.fn(),
+    output: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+import {
+  acquireSyncProcessLock,
+  PROCESS_LOCK_FILE_NAME,
+} from '../../../src/sync/sync-process-lock';
+import { Logger } from '../../../src/utils/logger';
+import { ConfigError } from '../../../src/utils/errors';
+
+// `import * as fs` compiles to a namespace object whose properties are
+// non-configurable getters, so jest.spyOn cannot replace them. Those getters
+// read through to the module object below, which is what the code under test
+// resolves its own `fs.*` calls against.
+const fsModule = require('fs') as typeof fs;
+
+function errnoError(code: string): NodeJS.ErrnoException {
+  const error = new Error(code) as NodeJS.ErrnoException;
+  error.code = code;
+  return error;
+}
+
+describe('acquireSyncProcessLock', () => {
+  let projectRoot: string;
+  let pidFilePath: string;
+
+  beforeEach(() => {
+    projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-lock-'));
+    pidFilePath = path.join(projectRoot, PROCESS_LOCK_FILE_NAME);
+  });
+
+  afterEach(() => {
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  /** Plant a pidfile as some other process would have left it. */
+  function plantPidFile(contents: unknown): void {
+    fs.writeFileSync(
+      pidFilePath,
+      typeof contents === 'string' ? contents : JSON.stringify(contents)
+    );
+  }
+
+  function ownerPid(): number {
+    const parsed: unknown = JSON.parse(fs.readFileSync(pidFilePath, 'utf-8'));
+    return (parsed as { pid: number }).pid;
+  }
+
+  describe('acquiring a free lock', () => {
+    it('writes a pidfile naming this process', () => {
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(handle.pidFilePath).toBe(pidFilePath);
+      expect(ownerPid()).toBe(process.pid);
+      handle.release();
+      expect(fs.existsSync(pidFilePath)).toBe(false);
+    });
+
+    it('propagates a pidfile write failure that is not EEXIST', () => {
+      let caught: unknown;
+      try {
+        acquireSyncProcessLock(path.join(projectRoot, 'no-such-directory'));
+      } catch (error) {
+        caught = error;
+      }
+
+      expect((caught as NodeJS.ErrnoException | undefined)?.code).toBe(
+        'ENOENT'
+      );
+      expect(caught).not.toBeInstanceOf(ConfigError);
+    });
+  });
+
+  describe('liveness probe', () => {
+    it('refuses the lock when the pidfile names a process that is genuinely running', () => {
+      plantPidFile({ pid: process.pid, startedAt: '2026-01-01T00:00:00.000Z' });
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+      expect(fs.existsSync(pidFilePath)).toBe(true);
+    });
+
+    it('refuses the lock when the probe reports EPERM, which means a process this user does not own', () => {
+      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      jest.spyOn(process, 'kill').mockImplementation(() => {
+        throw errnoError('EPERM');
+      });
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+    });
+
+    it('names the holding PID and its start time when refusing', () => {
+      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      jest.spyOn(process, 'kill').mockImplementation(() => {
+        throw errnoError('EPERM');
+      });
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(
+        /PID=4242, started 2026-01-01T00:00:00\.000Z/
+      );
+    });
+
+    it('reclaims the lock when the probe reports ESRCH', () => {
+      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      jest.spyOn(process, 'kill').mockImplementation(() => {
+        throw errnoError('ESRCH');
+      });
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(ownerPid()).toBe(process.pid);
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('PID=4242')
+      );
+      handle.release();
+    });
+
+    it('treats an unrecognised probe error as not alive rather than propagating it', () => {
+      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      jest.spyOn(process, 'kill').mockImplementation(() => {
+        throw errnoError('EINVAL');
+      });
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(ownerPid()).toBe(process.pid);
+      handle.release();
+    });
+  });
+
+  describe('unreadable pidfile contents', () => {
+    it.each([
+      ['content that is not JSON', 'not json at all'],
+      ['JSON that is not an object', '"a bare string"'],
+      ['an object with no pid', '{"startedAt":"2026-01-01T00:00:00.000Z"}'],
+      [
+        'a fractional pid',
+        '{"pid":1.5,"startedAt":"2026-01-01T00:00:00.000Z"}',
+      ],
+      ['a zero pid', '{"pid":0,"startedAt":"2026-01-01T00:00:00.000Z"}'],
+      ['a negative pid', '{"pid":-1,"startedAt":"2026-01-01T00:00:00.000Z"}'],
+      ['no startedAt', '{"pid":4242}'],
+    ])('reclaims the lock when the pidfile holds %s', (_label, contents) => {
+      plantPidFile(contents);
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(ownerPid()).toBe(process.pid);
+      handle.release();
+    });
+
+    it('reports an unknown PID rather than guessing when the pidfile is unreadable', () => {
+      plantPidFile('not json at all');
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('unknown PID')
+      );
+      handle.release();
+    });
+
+    it('never probes liveness for an unreadable pidfile', () => {
+      plantPidFile('not json at all');
+      const killSpy = jest.spyOn(process, 'kill');
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(killSpy).not.toHaveBeenCalled();
+      handle.release();
+    });
+
+    it('propagates a pidfile read failure that is not ENOENT', () => {
+      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      jest.spyOn(fsModule, 'readFileSync').mockImplementation(() => {
+        throw errnoError('EACCES');
+      });
+
+      let caught: unknown;
+      try {
+        acquireSyncProcessLock(projectRoot);
+      } catch (error) {
+        caught = error;
+      }
+
+      expect((caught as NodeJS.ErrnoException | undefined)?.code).toBe(
+        'EACCES'
+      );
+      expect(caught).not.toBeInstanceOf(ConfigError);
+    });
+  });
+
+  describe('reclaiming a stale pidfile', () => {
+    it('proceeds when another process unlinks the stale pidfile first', () => {
+      plantPidFile('not json at all');
+      jest.spyOn(fsModule, 'unlinkSync').mockImplementation((target) => {
+        fs.rmSync(target, { force: true });
+        throw errnoError('ENOENT');
+      });
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(ownerPid()).toBe(process.pid);
+      handle.release();
+    });
+
+    it('propagates an unlink failure that is not ENOENT', () => {
+      plantPidFile('not json at all');
+      jest.spyOn(fsModule, 'unlinkSync').mockImplementation(() => {
+        throw errnoError('EACCES');
+      });
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow('EACCES');
+    });
+  });
+
+  describe('release', () => {
+    it('leaves the pidfile alone once another process owns it', () => {
+      const handle = acquireSyncProcessLock(projectRoot);
+      const otherPid = process.pid + 1;
+      plantPidFile({ pid: otherPid, startedAt: '2026-01-01T00:00:00.000Z' });
+
+      handle.release();
+
+      expect(fs.existsSync(pidFilePath)).toBe(true);
+      expect(ownerPid()).toBe(otherPid);
+    });
+
+    it('stays quiet when the pidfile is already gone', () => {
+      const handle = acquireSyncProcessLock(projectRoot);
+      fs.rmSync(pidFilePath);
+
+      expect(() => handle.release()).not.toThrow();
+      expect(Logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('warns rather than throwing when the pidfile cannot be removed', () => {
+      const handle = acquireSyncProcessLock(projectRoot);
+      jest.spyOn(fsModule, 'unlinkSync').mockImplementation(() => {
+        throw errnoError('EACCES');
+      });
+
+      expect(() => handle.release()).not.toThrow();
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining(PROCESS_LOCK_FILE_NAME)
+      );
+    });
+
+    it('removes the pidfile only once across repeated calls', () => {
+      const handle = acquireSyncProcessLock(projectRoot);
+      handle.release();
+      const unlinkSpy = jest.spyOn(fsModule, 'unlinkSync');
+
+      handle.release();
+
+      expect(unlinkSpy).not.toHaveBeenCalled();
+    });
+  });
+});

From b513f4eb5f03105424da03cf06c760e5f953798f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 10:24:51 -0400
Subject: [PATCH 086/256] test: file format regression suites with their
 parsers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six format suites sat in tests/unit/ while every other format test lived in
tests/unit/formats/, so the directory did not show that the cross-parser
invariants -- CDATA breakout refusal, LF/CRLF equivalence, three-sync fixed
points, U+2028 in TOML, surrogate-pair escaping, XLIFF state attributes --
are format coverage. Moved, and the redundant formats- prefix dropped since
the directory carries it. Imports rebased one level deeper; no test bodies
touched.

tests/property/cache-key-normalization.test.ts gains the .property.test.ts
suffix its six siblings already use.

All 44 moved tests still pass and the suite total is unchanged at 6601.
Recorded as renames, so history follows the files.

Suite totals move by 0.04 branch points, which is expected from a rename:
jest orders suites by name, so a different set shares each worker, and a
module's already-loaded branches are reached only when a worker loads it
twice. Deterministic across runs and far inside the threshold headroom.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ...est.ts => cache-key-normalization.property.test.ts} |  0
 .../android-cdata.test.ts}                             |  4 ++--
 .../{formats-crlf.test.ts => formats/crlf.test.ts}     | 10 +++++-----
 .../roundtrip.test.ts}                                 |  6 +++---
 .../toml-sections.test.ts}                             |  2 +-
 .../xcstrings-arb.test.ts}                             |  4 ++--
 .../xliff-attributes.test.ts}                          |  2 +-
 7 files changed, 14 insertions(+), 14 deletions(-)
 rename tests/property/{cache-key-normalization.test.ts => cache-key-normalization.property.test.ts} (100%)
 rename tests/unit/{formats-android-cdata.test.ts => formats/android-cdata.test.ts} (97%)
 rename tests/unit/{formats-crlf.test.ts => formats/crlf.test.ts} (89%)
 rename tests/unit/{formats-roundtrip.test.ts => formats/roundtrip.test.ts} (96%)
 rename tests/unit/{formats-toml-sections.test.ts => formats/toml-sections.test.ts} (98%)
 rename tests/unit/{formats-xcstrings-arb.test.ts => formats/xcstrings-arb.test.ts} (97%)
 rename tests/unit/{formats-xliff-attributes.test.ts => formats/xliff-attributes.test.ts} (98%)

diff --git a/tests/property/cache-key-normalization.test.ts b/tests/property/cache-key-normalization.property.test.ts
similarity index 100%
rename from tests/property/cache-key-normalization.test.ts
rename to tests/property/cache-key-normalization.property.test.ts
diff --git a/tests/unit/formats-android-cdata.test.ts b/tests/unit/formats/android-cdata.test.ts
similarity index 97%
rename from tests/unit/formats-android-cdata.test.ts
rename to tests/unit/formats/android-cdata.test.ts
index 34238989..c5bc2ed5 100644
--- a/tests/unit/formats-android-cdata.test.ts
+++ b/tests/unit/formats/android-cdata.test.ts
@@ -7,8 +7,8 @@
  * parser's stance on CDATA in translatable content.
  */
 
-import { AndroidXmlFormatParser } from '../../src/formats/android-xml';
-import { ValidationError } from '../../src/utils/errors';
+import { AndroidXmlFormatParser } from '../../../src/formats/android-xml';
+import { ValidationError } from '../../../src/utils/errors';
 
 const WITH_CDATA = `<?xml version="1.0" encoding="utf-8"?>
 <resources>
diff --git a/tests/unit/formats-crlf.test.ts b/tests/unit/formats/crlf.test.ts
similarity index 89%
rename from tests/unit/formats-crlf.test.ts
rename to tests/unit/formats/crlf.test.ts
index fed6eb18..e44dbf56 100644
--- a/tests/unit/formats-crlf.test.ts
+++ b/tests/unit/formats/crlf.test.ts
@@ -7,11 +7,11 @@
  * the file from nothing.
  */
 
-import { PoFormatParser } from '../../src/formats/po';
-import { IosStringsFormatParser } from '../../src/formats/ios-strings';
-import { PropertiesFormatParser } from '../../src/formats/properties';
-import { TomlFormatParser } from '../../src/formats/toml';
-import type { FormatParser } from '../../src/formats/format';
+import { PoFormatParser } from '../../../src/formats/po';
+import { IosStringsFormatParser } from '../../../src/formats/ios-strings';
+import { PropertiesFormatParser } from '../../../src/formats/properties';
+import { TomlFormatParser } from '../../../src/formats/toml';
+import type { FormatParser } from '../../../src/formats/format';
 
 interface LineBasedCase {
   label: string;
diff --git a/tests/unit/formats-roundtrip.test.ts b/tests/unit/formats/roundtrip.test.ts
similarity index 96%
rename from tests/unit/formats-roundtrip.test.ts
rename to tests/unit/formats/roundtrip.test.ts
index ff7bc53e..3bfbde42 100644
--- a/tests/unit/formats-roundtrip.test.ts
+++ b/tests/unit/formats/roundtrip.test.ts
@@ -5,9 +5,9 @@
  * unnoticed — a single run looks almost right.
  */
 
-import { AndroidXmlFormatParser } from '../../src/formats/android-xml';
-import { PropertiesFormatParser } from '../../src/formats/properties';
-import { TomlFormatParser } from '../../src/formats/toml';
+import { AndroidXmlFormatParser } from '../../../src/formats/android-xml';
+import { PropertiesFormatParser } from '../../../src/formats/properties';
+import { TomlFormatParser } from '../../../src/formats/toml';
 
 describe('parser round-trip stability', () => {
   describe('Android XML entity escaping', () => {
diff --git a/tests/unit/formats-toml-sections.test.ts b/tests/unit/formats/toml-sections.test.ts
similarity index 98%
rename from tests/unit/formats-toml-sections.test.ts
rename to tests/unit/formats/toml-sections.test.ts
index 97011848..bc4968fb 100644
--- a/tests/unit/formats-toml-sections.test.ts
+++ b/tests/unit/formats/toml-sections.test.ts
@@ -7,7 +7,7 @@
  * then still missing, it was re-appended on every subsequent sync run.
  */
 
-import { TomlFormatParser } from '../../src/formats/toml';
+import { TomlFormatParser } from '../../../src/formats/toml';
 
 describe('TOML section handling for new keys', () => {
   const sectioned = '[messages]\ngreeting = "Hello"\n';
diff --git a/tests/unit/formats-xcstrings-arb.test.ts b/tests/unit/formats/xcstrings-arb.test.ts
similarity index 97%
rename from tests/unit/formats-xcstrings-arb.test.ts
rename to tests/unit/formats/xcstrings-arb.test.ts
index aff39517..732ba198 100644
--- a/tests/unit/formats-xcstrings-arb.test.ts
+++ b/tests/unit/formats/xcstrings-arb.test.ts
@@ -6,8 +6,8 @@
  *    resource file could not be read at all.
  */
 
-import { XcstringsFormatParser } from '../../src/formats/xcstrings';
-import { ArbFormatParser } from '../../src/formats/arb';
+import { XcstringsFormatParser } from '../../../src/formats/xcstrings';
+import { ArbFormatParser } from '../../../src/formats/arb';
 
 describe('Xcode String Catalog localizations', () => {
   const withVariations = JSON.stringify(
diff --git a/tests/unit/formats-xliff-attributes.test.ts b/tests/unit/formats/xliff-attributes.test.ts
similarity index 98%
rename from tests/unit/formats-xliff-attributes.test.ts
rename to tests/unit/formats/xliff-attributes.test.ts
index 4fe117d6..6ea2977f 100644
--- a/tests/unit/formats-xliff-attributes.test.ts
+++ b/tests/unit/formats/xliff-attributes.test.ts
@@ -10,7 +10,7 @@
  * the stale translation.
  */
 
-import { XliffFormatParser } from '../../src/formats/xliff';
+import { XliffFormatParser } from '../../../src/formats/xliff';
 
 const V12_WITH_STATE = `<?xml version="1.0" encoding="UTF-8"?>
 <xliff version="1.2">

From 61b1b2788e06b25de6eea138fc234a7d5a60d882 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 10:30:11 -0400
Subject: [PATCH 087/256] test(usage): merge duplicate integration coverage
 into the E2E suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cli-usage.integration.test.ts and cli-usage.e2e.test.ts both drove the built
binary as a subprocess, so they were one layer split across two directories.
Of its four tests, two asserted help text, one duplicated the E2E API-key
check more weakly, and one asserted the synopsis takes no arguments.

Deleting it would have lost two things the E2E suite only checked with a
loose /character|usage|statistics|limit/ regex, so those assertions are
tightened to the real description instead, and the synopsis check moves
across scoped to the usage line -- the whole help output contains '<' from
global options like --timeout <ms>.

Verified the tightened assertions bite: renaming the command description to
"Show API usage stats" fails two tests that previously passed.

Net 4 tests removed, 1 added. Coverage is unaffected by construction: both
files spawn dist/cli/index.js, so neither ever contributed to it -- which is
part of why the duplication went unnoticed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-usage.e2e.test.ts               | 14 +++-
 .../integration/cli-usage.integration.test.ts | 65 -------------------
 2 files changed, 12 insertions(+), 67 deletions(-)
 delete mode 100644 tests/integration/cli-usage.integration.test.ts

diff --git a/tests/e2e/cli-usage.e2e.test.ts b/tests/e2e/cli-usage.e2e.test.ts
index e7fcf111..b8eeafd7 100644
--- a/tests/e2e/cli-usage.e2e.test.ts
+++ b/tests/e2e/cli-usage.e2e.test.ts
@@ -28,7 +28,7 @@ describe('Usage Command E2E', () => {
     it('should describe the command', () => {
       const output = runCLI('usage --help');
 
-      expect(output).toMatch(/character|usage|statistics|limit/i);
+      expect(output).toContain('Show API usage statistics');
     });
 
     it('should show available options', () => {
@@ -36,6 +36,16 @@ describe('Usage Command E2E', () => {
 
       expect(output).toContain('help');
     });
+
+    it('should take no positional arguments', () => {
+      const output = runCLI('usage --help');
+      const synopsis = output
+        .split('\n')
+        .find((line) => line.includes('Usage: deepl usage'));
+
+      expect(synopsis).toBeDefined();
+      expect(synopsis).not.toContain('<');
+    });
   });
 
   describe('usage error handling', () => {
@@ -69,7 +79,7 @@ describe('Usage Command E2E', () => {
       const helpOutput = runCLI('--help');
 
       expect(helpOutput).toContain('usage');
-      expect(helpOutput).toMatch(/character|usage/i);
+      expect(helpOutput).toContain('Show API usage statistics');
     });
 
     it('should support --quiet flag', () => {
diff --git a/tests/integration/cli-usage.integration.test.ts b/tests/integration/cli-usage.integration.test.ts
deleted file mode 100644
index 110996b4..00000000
--- a/tests/integration/cli-usage.integration.test.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-/**
- * Integration Tests for Usage CLI Command
- * Tests the usage command CLI behavior and output formatting
- */
-
-import { createTestConfigDir, makeRunCLI } from '../helpers';
-
-describe('Usage CLI Integration', () => {
-  const testConfig = createTestConfigDir('usage');
-  const { runCLI } = makeRunCLI(testConfig.path);
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  describe('deepl usage --help', () => {
-    it('should display help for usage command', () => {
-      const output = runCLI('deepl usage --help');
-
-      expect(output).toContain('Usage:');
-      expect(output).toContain('deepl usage');
-      expect(output).toContain('Show API usage statistics');
-    });
-  });
-
-  describe('deepl usage without API key', () => {
-    it('should require API key to be configured', () => {
-      // Ensure no API key is set
-      try {
-        runCLI('deepl auth clear', { stdio: 'pipe' });
-      } catch {
-        // Ignore if already cleared
-      }
-
-      expect.assertions(1);
-      try {
-        runCLI('deepl usage', { stdio: 'pipe', excludeApiKey: true });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should indicate API key is required
-        expect(output).toMatch(/API key|auth|not set/i);
-      }
-    });
-  });
-
-  describe('deepl usage command structure', () => {
-    it('should be available as a command', () => {
-      const helpOutput = runCLI('deepl --help');
-
-      // Usage command should be listed in main help
-      expect(helpOutput).toContain('usage');
-      expect(helpOutput).toContain('Show API usage statistics');
-    });
-
-    it('should not require any arguments', () => {
-      // Help should show no required arguments
-      const output = runCLI('deepl usage --help');
-
-      // Should be simple command with no required parameters
-      expect(output).toContain('Usage: deepl usage');
-      expect(output).not.toContain('<required');
-      expect(output).not.toContain('[arguments]');
-    });
-  });
-});

From 0ad1bc2670195b9f46f8e4b70a5d9c863eda01d5 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 10:31:45 -0400
Subject: [PATCH 088/256] test(auth): merge duplicate integration coverage into
 the E2E suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both files drove the built binary as a subprocess. Of the integration file's
four tests one was an exact duplicate of the E2E "No API key set" test, two
asserted messages the E2E suite only matched with loose regexes, and one had
no E2E counterpart at all.

Ported: set-key refusing a well-formed key the API rejects. set-key validates
before persisting, so this exercises the service path rather than local format
checking, and nothing in the E2E suite covered it. Note it reaches the real
API -- nock.disableNetConnect() in tests/setup.ts does not reach a subprocess.

Tightened: /empty|required/ -> "API key cannot be empty", and
/removed|cleared/ -> "API key removed", which /cleared/ alone would not have
caught. The check symbol is left out of the expectation so a colour escape
between it and the text cannot break the match.

Net 4 tests removed, 1 added.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-auth.e2e.test.ts                | 13 +++-
 .../integration/cli-auth.integration.test.ts  | 73 -------------------
 2 files changed, 11 insertions(+), 75 deletions(-)
 delete mode 100644 tests/integration/cli-auth.integration.test.ts

diff --git a/tests/e2e/cli-auth.e2e.test.ts b/tests/e2e/cli-auth.e2e.test.ts
index 892f59e2..d5006a13 100644
--- a/tests/e2e/cli-auth.e2e.test.ts
+++ b/tests/e2e/cli-auth.e2e.test.ts
@@ -61,7 +61,7 @@ describe('Auth Command E2E', () => {
   describe('auth clear', () => {
     it('should clear API key successfully', () => {
       const output = runCLIAll('auth clear');
-      expect(output).toMatch(/removed|cleared/i);
+      expect(output).toContain('API key removed');
     });
   });
 
@@ -70,7 +70,16 @@ describe('Auth Command E2E', () => {
       const result = runCLIExpectError('auth set-key ""');
 
       expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toMatch(/empty|required/i);
+      expect(result.output).toContain('API key cannot be empty');
+    });
+
+    // set-key validates against the API before persisting, so a
+    // well-formed-but-wrong key is refused by the service rather than locally.
+    it('should reject a key the API does not accept', () => {
+      const result = runCLIExpectError('auth set-key invalid-key-123');
+
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toContain('Authentication failed');
     });
   });
 
diff --git a/tests/integration/cli-auth.integration.test.ts b/tests/integration/cli-auth.integration.test.ts
deleted file mode 100644
index 69ccb22b..00000000
--- a/tests/integration/cli-auth.integration.test.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-/**
- * Integration Tests for Auth CLI Commands
- * Tests the full auth command flow with real config persistence
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { createTestConfigDir, makeRunCLI } from '../helpers';
-
-describe('Auth CLI Integration', () => {
-  const testConfig = createTestConfigDir('auth');
-  const configPath = path.join(testConfig.path, 'config.json');
-  const { runCLI, runCLIAll } = makeRunCLI(testConfig.path, {
-    excludeApiKey: true,
-  });
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  beforeEach(() => {
-    // Remove config file before each test
-    if (fs.existsSync(configPath)) {
-      fs.unlinkSync(configPath);
-    }
-  });
-
-  describe('deepl auth set-key', () => {
-    it('should reject empty API key', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl auth set-key ""');
-      } catch (error: any) {
-        expect(error.stderr ?? error.stdout).toContain(
-          'API key cannot be empty'
-        );
-      }
-    });
-
-    it('should reject invalid API key via API validation', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl auth set-key invalid-key-123');
-      } catch (error: any) {
-        // Now expects API validation error (not format error)
-        expect(error.stderr ?? error.stdout).toContain('Authentication failed');
-      }
-    });
-  });
-
-  describe('deepl auth show', () => {
-    it('should show "No API key set" when no key configured', () => {
-      expect.assertions(1);
-      // Clear any existing key first
-      try {
-        runCLI('deepl auth clear');
-      } catch (_e) {
-        // Ignore if already cleared
-      }
-
-      const output = runCLI('deepl auth show');
-      expect(output).toContain('No API key set');
-    });
-  });
-
-  describe('deepl auth clear', () => {
-    it('should successfully clear API key', () => {
-      // Even without a key set, clear should succeed
-      const output = runCLIAll('deepl auth clear');
-      expect(output).toContain('✓ API key removed');
-    });
-  });
-});

From 791997e619a5e76a1b069531a14e112a992b8647 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 10:32:45 -0400
Subject: [PATCH 089/256] test(detect): merge duplicate integration coverage
 into the E2E suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both files drove the built binary as a subprocess. Four of the integration
file's eight tests duplicated E2E tests outright ([text] optional, main-help
registration, missing API key). Two were weak enough to be worth not carrying
over:

- "should be listed under Information commands" only asserted the word
  "detect" appears in help; it never checked the command group its title
  names, so it duplicated the test above it.
- "should show error when no text provided and stdin is empty" asserted only
  output.length > 0, which any output satisfies including an unrelated crash.
  The argument-empty path is covered by "should handle empty text gracefully",
  and stdin handling by cli-stdin-stdout / cli-no-input.

The remaining assertions were stronger than their E2E counterparts and are
folded in: the real command description in both `detect --help` and main help,
where E2E matched /detect|language/ and /detect.*language/; the --format
choices, where E2E checked only the flag name; and the presence of the
Examples block, added to the existing help test rather than as a new one.

Net 8 tests removed, 0 added.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-detect.e2e.test.ts              |   8 +-
 .../cli-detect.integration.test.ts            | 101 ------------------
 2 files changed, 5 insertions(+), 104 deletions(-)
 delete mode 100644 tests/integration/cli-detect.integration.test.ts

diff --git a/tests/e2e/cli-detect.e2e.test.ts b/tests/e2e/cli-detect.e2e.test.ts
index d89c858d..a097b7af 100644
--- a/tests/e2e/cli-detect.e2e.test.ts
+++ b/tests/e2e/cli-detect.e2e.test.ts
@@ -20,18 +20,20 @@ describe('Detect Command E2E', () => {
       expect(output).toContain('Usage:');
       expect(output).toContain('detect');
       expect(output).toContain('Options:');
+      expect(output).toContain('Examples:');
     });
 
     it('should describe the command', () => {
       const output = runCLI('detect --help');
 
-      expect(output).toMatch(/detect|language/i);
+      expect(output).toContain('Detect the language of text');
     });
 
-    it('should show --format option', () => {
+    it('should show --format option with its choices', () => {
       const output = runCLI('detect --help');
 
       expect(output).toContain('--format');
+      expect(output).toContain('json');
     });
 
     it('should show text argument as optional', () => {
@@ -73,7 +75,7 @@ describe('Detect Command E2E', () => {
     it('should show detect in main help with description', () => {
       const helpOutput = runCLI('--help');
 
-      expect(helpOutput).toMatch(/detect.*language/i);
+      expect(helpOutput).toContain('Detect the language of text');
     });
   });
 
diff --git a/tests/integration/cli-detect.integration.test.ts b/tests/integration/cli-detect.integration.test.ts
deleted file mode 100644
index f71fb2e8..00000000
--- a/tests/integration/cli-detect.integration.test.ts
+++ /dev/null
@@ -1,101 +0,0 @@
-/**
- * Integration Tests for Detect CLI Command
- * Tests the detect command CLI behavior, help output, and argument validation
- */
-
-import { execSync } from 'child_process';
-import { createTestConfigDir, makeRunCLI } from '../helpers';
-
-describe('Detect CLI Integration', () => {
-  const testConfig = createTestConfigDir('detect');
-  const { runCLI } = makeRunCLI(testConfig.path);
-
-  const runCLIExpectFail = (
-    command: string,
-    options: { env?: Record<string, string | undefined> } = {}
-  ): string => {
-    try {
-      execSync(command, {
-        encoding: 'utf-8',
-        env: {
-          ...process.env,
-          DEEPL_CONFIG_DIR: testConfig.path,
-          ...options.env,
-        },
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-      throw new Error('Expected command to fail');
-    } catch (error: any) {
-      return (error.stderr ?? '') + (error.stdout ?? '');
-    }
-  };
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  describe('deepl detect --help', () => {
-    it('should display help for detect command', () => {
-      const output = runCLI('deepl detect --help');
-
-      expect(output).toContain('Usage:');
-      expect(output).toContain('deepl detect');
-      expect(output).toContain('Detect the language of text');
-    });
-
-    it('should show --format option in help', () => {
-      const output = runCLI('deepl detect --help');
-
-      expect(output).toContain('--format');
-      expect(output).toContain('json');
-    });
-
-    it('should show examples in help', () => {
-      const output = runCLI('deepl detect --help');
-
-      expect(output).toContain('Examples:');
-      expect(output).toContain('deepl detect');
-    });
-
-    it('should accept optional text argument', () => {
-      const output = runCLI('deepl detect --help');
-
-      expect(output).toContain('[text]');
-    });
-  });
-
-  describe('deepl detect command registration', () => {
-    it('should be listed in main help', () => {
-      const output = runCLI('deepl --help');
-
-      expect(output).toContain('detect');
-      expect(output).toContain('Detect the language of text');
-    });
-
-    it('should be listed under Information commands', () => {
-      const output = runCLI('deepl --help');
-
-      expect(output).toContain('detect');
-    });
-  });
-
-  describe('deepl detect without API key', () => {
-    it('should fail with API key error when no key configured', () => {
-      const output = runCLIExpectFail('deepl detect "Bonjour le monde"', {
-        env: { DEEPL_API_KEY: '' },
-      });
-
-      expect(output).toMatch(/API key|not set/i);
-    });
-  });
-
-  describe('deepl detect argument validation', () => {
-    it('should show error when no text provided and stdin is empty', () => {
-      const output = runCLIExpectFail('echo "" | deepl detect', {
-        env: { DEEPL_API_KEY: 'fake-key-for-validation' },
-      });
-
-      expect(output.length).toBeGreaterThan(0);
-    });
-  });
-});

From 940bd3d9346275e351b8beff657520d179b73386 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 11:32:04 -0400
Subject: [PATCH 090/256] test(no-input): merge the --no-input suites and
 isolate the config dir
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two files overlapped on three of five scenarios. Each also held one the
other lacked: the integration file covered `cache clear --yes` proceeding and
init naming `deepl auth set-key`, while the E2E file covered --no-input
appearing in global help and init refusing when stdin is not a terminal.

The merged file uses makeNodeRunCLI rather than bare `execSync('deepl ...')`.
That matters beyond tidiness: the E2E file invoked whatever `deepl` was on
PATH with no DEEPL_CONFIG_DIR, so it ran against the real user config. Its
existing `cache clear` case aborts and so was harmless, but porting the --yes
case into it unchanged would have cleared the developer's actual cache.

The two init cases are one test now, since both drive the same invocation and
only differ in which line of output they assert.

Net 10 tests across two files becomes 6 in one.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-no-input.e2e.test.ts            | 87 +++++++++----------
 .../cli-no-input.integration.test.ts          | 55 ------------
 2 files changed, 41 insertions(+), 101 deletions(-)
 delete mode 100644 tests/integration/cli-no-input.integration.test.ts

diff --git a/tests/e2e/cli-no-input.e2e.test.ts b/tests/e2e/cli-no-input.e2e.test.ts
index 6181d3bf..e7ebcc7e 100644
--- a/tests/e2e/cli-no-input.e2e.test.ts
+++ b/tests/e2e/cli-no-input.e2e.test.ts
@@ -1,76 +1,71 @@
 /**
- * E2E Tests for --no-input Global Flag
- * Tests full CLI invocations verifying exit codes and error messages
+ * E2E Tests for the --no-input Global Flag
+ *
+ * Covers the commands that would otherwise prompt: the confirmation guard on
+ * `cache clear`, and the two commands that need a terminal and must refuse
+ * rather than block on one.
  */
 
-import { execSync } from 'child_process';
+import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
 describe('--no-input E2E', () => {
+  const testConfig = createTestConfigDir('e2e-no-input');
+  const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(
+    testConfig.path
+  );
+
+  afterAll(() => {
+    testConfig.cleanup();
+  });
+
   describe('help output', () => {
     it('should show --no-input in global help', () => {
-      const output = execSync('deepl --help', { encoding: 'utf-8' });
+      const output = runCLI('--help');
 
       expect(output).toContain('--no-input');
     });
   });
 
   describe('cache clear', () => {
-    it('should exit 0 and abort when --no-input is used without --yes', () => {
-      const output = execSync('deepl --no-input cache clear 2>&1', {
-        encoding: 'utf-8',
-        shell: '/bin/sh',
-      });
+    it('should abort rather than prompt when --yes is absent', () => {
+      const output = runCLIAll('--no-input cache clear');
 
       expect(output).toContain('Aborted.');
     });
+
+    it('should proceed when --yes supplies the confirmation', () => {
+      const output = runCLIAll('--no-input cache clear --yes');
+
+      expect(output).toContain('Cache cleared successfully');
+    });
   });
 
   describe('init', () => {
-    it('should exit with code 6 when --no-input is used', () => {
-      expect.assertions(2);
-      try {
-        execSync('deepl --no-input init', { encoding: 'utf-8', stdio: 'pipe' });
-      } catch (error: any) {
-        expect(error.status).toBe(6);
-        expect(error.stderr.toString()).toContain(
-          'not supported in non-interactive mode'
-        );
-      }
+    it('should exit 6 and point at auth set-key instead of prompting', () => {
+      const result = runCLIExpectError('--no-input init');
+
+      expect(result.status).toBe(6);
+      expect(result.output).toContain('not supported in non-interactive mode');
+      expect(result.output).toContain('deepl auth set-key');
     });
 
     // The path taken by `docker run` without -it, by CI, and by piped
     // invocations: the wizard must refuse rather than prompt into an EOF.
-    it('should exit with code 6 when stdin is not a terminal', () => {
-      expect.assertions(3);
-      try {
-        execSync('deepl init < /dev/null', {
-          encoding: 'utf-8',
-          stdio: 'pipe',
-          shell: '/bin/sh',
-        });
-      } catch (error: any) {
-        const stderr = error.stderr.toString();
-        expect(error.status).toBe(6);
-        expect(stderr).toContain('not supported in non-interactive mode');
-        expect(stderr).not.toContain('unsettled top-level await');
-      }
+    it('should exit 6 when stdin is not a terminal', () => {
+      const result = runCLIExpectError('init < /dev/null');
+
+      expect(result.status).toBe(6);
+      expect(result.output).toContain('not supported in non-interactive mode');
+      expect(result.output).not.toContain('unsettled top-level await');
     });
   });
 
   describe('write --interactive', () => {
-    it('should exit with code 6 when --no-input is used', () => {
-      expect.assertions(2);
-      try {
-        execSync('deepl --no-input write "test" --interactive', {
-          encoding: 'utf-8',
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        expect(error.status).toBe(6);
-        expect(error.stderr.toString()).toContain(
-          'requires an interactive terminal'
-        );
-      }
+    it('should exit 6 rather than opening an interactive session', () => {
+      const result = runCLIExpectError('--no-input write "test" --interactive');
+
+      expect(result.status).toBe(6);
+      expect(result.output).toContain('requires an interactive terminal');
     });
   });
 });
diff --git a/tests/integration/cli-no-input.integration.test.ts b/tests/integration/cli-no-input.integration.test.ts
deleted file mode 100644
index 9a000412..00000000
--- a/tests/integration/cli-no-input.integration.test.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-/**
- * Integration Tests for --no-input Global Flag
- * Tests that --no-input suppresses interactive prompts and guards interactive-only commands
- */
-
-import { createTestConfigDir, makeRunCLI } from '../helpers';
-
-describe('--no-input flag', () => {
-  const testConfig = createTestConfigDir('no-input');
-  const { runCLIAll, runCLIExpectError } = makeRunCLI(testConfig.path);
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  describe('cache clear --no-input', () => {
-    it('should abort without prompting', () => {
-      const output = runCLIAll('deepl --no-input cache clear');
-
-      expect(output).toContain('Aborted.');
-    });
-
-    it('should proceed when --yes is also provided', () => {
-      const output = runCLIAll('deepl --no-input cache clear --yes');
-
-      expect(output).toContain('Cache cleared successfully');
-    });
-  });
-
-  describe('write --interactive --no-input', () => {
-    it('should error with exit code 6', () => {
-      const result = runCLIExpectError(
-        'deepl --no-input write "test text" --interactive'
-      );
-
-      expect(result.status).toBe(6);
-      expect(result.output).toContain('requires an interactive terminal');
-    });
-  });
-
-  describe('init --no-input', () => {
-    it('should error with exit code 6', () => {
-      const result = runCLIExpectError('deepl --no-input init');
-
-      expect(result.status).toBe(6);
-      expect(result.output).toContain('not supported in non-interactive mode');
-    });
-
-    it('should suggest auth set-key alternative', () => {
-      const result = runCLIExpectError('deepl --no-input init');
-
-      expect(result.output).toContain('deepl auth set-key');
-    });
-  });
-});

From 75c21c6a4b29ad9c1108efafdfd1f9b45f9ef572 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 11:33:32 -0400
Subject: [PATCH 091/256] test(completion): keep the deeper suite and drop the
 shallow duplicate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This pair inverts the usual direction. The E2E file asserted only that output
contained "complete" and "deepl"; the integration file asserted the generated
scripts are actually loadable -- _deepl_completions and its `complete -F`
registration, compgen and COMPREPLY for bash, `#compdef deepl` with _deepl()
and `_arguments -C` for zsh, `complete -c deepl` with __fish_use_subcommand
and the -f that suppresses filename completion for fish, plus the per-command
dispatch functions and subcommand scoping.

Every E2E assertion was a weaker form of an integration one, so the E2E file
contributed nothing and the integration content survives, moved into the E2E
path and onto makeNodeRunCLI.

Verified the depth earns its place: renaming _deepl_completions in the source
fails a test here, and would have passed every assertion the old E2E file made.

One weakness carried over rather than fixed: "should include all registered
top-level commands" checks a hardcoded list that predates voice, sync, tm,
correct, detect and init, and matches them anywhere in the script rather than
as completion entries.

Net 18 tests across two files becomes 12 in one.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-completion.e2e.test.ts          | 117 +++++++++++++----
 .../cli-completion.integration.test.ts        | 118 ------------------
 2 files changed, 91 insertions(+), 144 deletions(-)
 delete mode 100644 tests/integration/cli-completion.integration.test.ts

diff --git a/tests/e2e/cli-completion.e2e.test.ts b/tests/e2e/cli-completion.e2e.test.ts
index f37f81e7..48f2f942 100644
--- a/tests/e2e/cli-completion.e2e.test.ts
+++ b/tests/e2e/cli-completion.e2e.test.ts
@@ -1,61 +1,126 @@
 /**
  * E2E Tests for Shell Completion Command
- * Tests `deepl completion` generation for bash, zsh, and fish shells
+ *
+ * Asserts the generated scripts are actually loadable by each shell -- the
+ * dispatch functions, the completion builtins they call, and the subcommand
+ * scoping -- rather than only that some output was produced.
  */
 
 import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
 describe('Completion Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-completion');
-  const { runCLI, runCLIAll } = makeNodeRunCLI(testConfig.path);
+  const { runCLI, runCLIAll } = makeNodeRunCLI(testConfig.path, {
+    excludeApiKey: true,
+  });
 
   afterAll(() => {
     testConfig.cleanup();
   });
 
-  describe('completion --help', () => {
-    it('should show help text with supported shells', () => {
-      const output = runCLI('completion --help');
-      expect(output).toContain('bash');
-      expect(output).toContain('zsh');
-      expect(output).toContain('fish');
-      expect(output).toContain('Generate shell completion scripts');
+  describe('completion bash', () => {
+    it('should output a valid bash completion script', () => {
+      const output = runCLI('completion bash');
+      expect(output).toContain('_deepl_completions');
+      expect(output).toContain('complete -F _deepl_completions deepl');
+      expect(output).toContain('compgen');
+      expect(output).toContain('COMPREPLY');
     });
-  });
 
-  describe('completion bash', () => {
-    it('should generate bash completion script', () => {
+    it('should include all registered top-level commands', () => {
+      const output = runCLI('completion bash');
+      const expectedCommands = [
+        'translate',
+        'auth',
+        'usage',
+        'languages',
+        'watch',
+        'write',
+        'config',
+        'cache',
+        'glossary',
+        'hooks',
+        'style-rules',
+        'admin',
+        'completion',
+      ];
+      for (const cmd of expectedCommands) {
+        expect(output).toContain(cmd);
+      }
+    });
+
+    it('should include subcommand completions', () => {
       const output = runCLI('completion bash');
-      expect(output).toContain('complete');
-      expect(output).toContain('deepl');
+      expect(output).toContain('auth)');
+      expect(output).toContain('set-key');
+      expect(output).toContain('cache)');
+      expect(output).toContain('stats');
     });
   });
 
   describe('completion zsh', () => {
-    it('should generate zsh completion script', () => {
+    it('should output a valid zsh completion script', () => {
+      const output = runCLI('completion zsh');
+      expect(output).toContain('#compdef deepl');
+      expect(output).toContain('_deepl()');
+      expect(output).toContain('_arguments -C');
+    });
+
+    it('should include command descriptions', () => {
       const output = runCLI('completion zsh');
-      expect(output).toContain('deepl');
-      expect(output).toContain('compdef');
+      expect(output).toContain('translate:');
+      expect(output).toContain('auth:');
+      expect(output).toContain('cache:');
+    });
+
+    it('should include subcommand dispatch functions', () => {
+      const output = runCLI('completion zsh');
+      expect(output).toContain('_deepl_auth()');
+      expect(output).toContain('_deepl_cache()');
+      expect(output).toContain('_deepl_glossary()');
     });
   });
 
   describe('completion fish', () => {
-    it('should generate fish completion script', () => {
+    it('should output a valid fish completion script', () => {
+      const output = runCLI('completion fish');
+      expect(output).toContain('complete -c deepl');
+      expect(output).toContain('__fish_use_subcommand');
+    });
+
+    it('should include subcommand scoping', () => {
       const output = runCLI('completion fish');
-      expect(output).toContain('deepl');
-      expect(output).toContain('complete');
+      expect(output).toContain('__fish_seen_subcommand_from auth');
+      expect(output).toContain('__fish_seen_subcommand_from cache');
+    });
+
+    it('should disable default file completions', () => {
+      const output = runCLI('completion fish');
+      expect(output).toContain('complete -c deepl -f');
     });
   });
 
-  describe('completion with unsupported shell', () => {
-    it('should exit with non-zero code for unknown shell', () => {
-      expect(() => runCLIAll('completion powershell')).toThrow();
+  describe('error handling', () => {
+    it('should fail with unsupported shell type', () => {
+      expect(() => {
+        runCLI('completion powershell');
+      }).toThrow();
+    });
+
+    it('should fail with no shell argument', () => {
+      expect(() => {
+        runCLIAll('completion');
+      }).toThrow();
     });
   });
 
-  describe('completion without argument', () => {
-    it('should exit with error when no shell is specified', () => {
-      expect(() => runCLIAll('completion')).toThrow();
+  describe('help text', () => {
+    it('should show help with --help flag', () => {
+      const output = runCLIAll('completion --help');
+      expect(output).toContain('Generate shell completion scripts');
+      expect(output).toContain('bash');
+      expect(output).toContain('zsh');
+      expect(output).toContain('fish');
     });
   });
 });
diff --git a/tests/integration/cli-completion.integration.test.ts b/tests/integration/cli-completion.integration.test.ts
deleted file mode 100644
index 2ccfabcc..00000000
--- a/tests/integration/cli-completion.integration.test.ts
+++ /dev/null
@@ -1,118 +0,0 @@
-import { createTestConfigDir, makeRunCLI } from '../helpers';
-
-describe('Completion CLI Integration', () => {
-  const testConfig = createTestConfigDir('completion');
-  const { runCLI, runCLIAll } = makeRunCLI(testConfig.path, {
-    excludeApiKey: true,
-  });
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  describe('deepl completion bash', () => {
-    it('should output a valid bash completion script', () => {
-      const output = runCLI('deepl completion bash');
-      expect(output).toContain('_deepl_completions');
-      expect(output).toContain('complete -F _deepl_completions deepl');
-      expect(output).toContain('compgen');
-      expect(output).toContain('COMPREPLY');
-    });
-
-    it('should include all registered top-level commands', () => {
-      const output = runCLI('deepl completion bash');
-      const expectedCommands = [
-        'translate',
-        'auth',
-        'usage',
-        'languages',
-        'watch',
-        'write',
-        'config',
-        'cache',
-        'glossary',
-        'hooks',
-        'style-rules',
-        'admin',
-        'completion',
-      ];
-      for (const cmd of expectedCommands) {
-        expect(output).toContain(cmd);
-      }
-    });
-
-    it('should include subcommand completions', () => {
-      const output = runCLI('deepl completion bash');
-      expect(output).toContain('auth)');
-      expect(output).toContain('set-key');
-      expect(output).toContain('cache)');
-      expect(output).toContain('stats');
-    });
-  });
-
-  describe('deepl completion zsh', () => {
-    it('should output a valid zsh completion script', () => {
-      const output = runCLI('deepl completion zsh');
-      expect(output).toContain('#compdef deepl');
-      expect(output).toContain('_deepl()');
-      expect(output).toContain('_arguments -C');
-    });
-
-    it('should include command descriptions', () => {
-      const output = runCLI('deepl completion zsh');
-      expect(output).toContain('translate:');
-      expect(output).toContain('auth:');
-      expect(output).toContain('cache:');
-    });
-
-    it('should include subcommand dispatch functions', () => {
-      const output = runCLI('deepl completion zsh');
-      expect(output).toContain('_deepl_auth()');
-      expect(output).toContain('_deepl_cache()');
-      expect(output).toContain('_deepl_glossary()');
-    });
-  });
-
-  describe('deepl completion fish', () => {
-    it('should output a valid fish completion script', () => {
-      const output = runCLI('deepl completion fish');
-      expect(output).toContain('complete -c deepl');
-      expect(output).toContain('__fish_use_subcommand');
-    });
-
-    it('should include subcommand scoping', () => {
-      const output = runCLI('deepl completion fish');
-      expect(output).toContain('__fish_seen_subcommand_from auth');
-      expect(output).toContain('__fish_seen_subcommand_from cache');
-    });
-
-    it('should disable default file completions', () => {
-      const output = runCLI('deepl completion fish');
-      expect(output).toContain('complete -c deepl -f');
-    });
-  });
-
-  describe('error handling', () => {
-    it('should fail with unsupported shell type', () => {
-      expect(() => {
-        runCLI('deepl completion powershell');
-      }).toThrow();
-    });
-
-    it('should fail with no shell argument', () => {
-      expect(() => {
-        runCLIAll('deepl completion');
-      }).toThrow();
-    });
-  });
-
-  describe('help text', () => {
-    it('should show help with --help flag', () => {
-      const output = runCLIAll('deepl completion --help');
-      expect(output).toContain('Generate shell completion scripts');
-      expect(output).toContain('bash');
-      expect(output).toContain('zsh');
-      expect(output).toContain('fish');
-    });
-  });
-});

From da498eb53d44cf0cee46d7a3d2cc08d8de1911e0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 11:34:49 -0400
Subject: [PATCH 092/256] test(cache): merge duplicate integration coverage
 into the E2E suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The E2E file was already the richer of the two: it verifies enable/disable
survive across processes, cross-checks the persisted flag via `config get`,
and asserts the WARN prefix on the non-TTY table fallback. Ten of the
integration file's twelve tests restated things it already covered, in some
cases more loosely -- /Cache Status: (enabled|disabled)/ against E2E tests
that pin the specific state.

Two were not covered and are ported:

- cache stats reporting size as "N MB" with the share of the limit used,
  where the E2E suite only checked that "Size:" appears at all
- repeating an already-satisfied operation still reporting success, which the
  integration file spent three tests on (enable, disable, clear) and which
  folds into one

Net 12 tests removed, 2 added.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-cache.e2e.test.ts               |  20 +++
 .../integration/cli-cache.integration.test.ts | 121 ------------------
 2 files changed, 20 insertions(+), 121 deletions(-)
 delete mode 100644 tests/integration/cli-cache.integration.test.ts

diff --git a/tests/e2e/cli-cache.e2e.test.ts b/tests/e2e/cli-cache.e2e.test.ts
index 6c9e20a9..f8b630de 100644
--- a/tests/e2e/cli-cache.e2e.test.ts
+++ b/tests/e2e/cli-cache.e2e.test.ts
@@ -97,6 +97,13 @@ describe('Cache Command E2E', () => {
       expect(output).toContain('Size:');
     });
 
+    it('should report size in MB alongside the share of the limit used', () => {
+      const output = runCLI('cache stats');
+
+      expect(output).toMatch(/Size: [\d.]+ MB/);
+      expect(output).toMatch(/[\d.]+% used/);
+    });
+
     it('should exit successfully', () => {
       const result = runCLIExpectError('cache stats');
       expect(result.status).toBe(0);
@@ -135,6 +142,19 @@ describe('Cache Command E2E', () => {
 
       expect(output).toContain('Cache disabled');
     });
+
+    it('should report success when an operation is already satisfied', () => {
+      runCLIAll('cache enable');
+      expect(runCLIAll('cache enable')).toContain('Cache enabled');
+
+      runCLIAll('cache disable');
+      expect(runCLIAll('cache disable')).toContain('Cache disabled');
+
+      runCLIAll('cache clear --yes');
+      expect(runCLIAll('cache clear --yes')).toContain(
+        'Cache cleared successfully'
+      );
+    });
   });
 
   describe('cache workflow', () => {
diff --git a/tests/integration/cli-cache.integration.test.ts b/tests/integration/cli-cache.integration.test.ts
deleted file mode 100644
index 8b128911..00000000
--- a/tests/integration/cli-cache.integration.test.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-/**
- * Integration Tests for Cache CLI Commands
- * Tests cache management with real database operations
- */
-
-import { createTestConfigDir, makeRunCLI } from '../helpers';
-
-describe('Cache CLI Integration', () => {
-  const testConfig = createTestConfigDir('cache');
-  const { runCLI, runCLIAll } = makeRunCLI(testConfig.path);
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  describe('deepl cache stats', () => {
-    it('should show cache statistics', () => {
-      const output = runCLI('deepl cache stats');
-
-      // Should contain key metrics
-      expect(output).toContain('Cache Status:');
-      expect(output).toContain('Entries:');
-      expect(output).toContain('Size:');
-    });
-
-    it('should show if cache is enabled or disabled', () => {
-      const output = runCLI('deepl cache stats');
-
-      // Should show status
-      expect(output).toMatch(/Cache Status: (enabled|disabled)/);
-    });
-
-    it('should show size in MB and percentage', () => {
-      const output = runCLI('deepl cache stats');
-
-      // Should show size format
-      expect(output).toMatch(/Size: [\d.]+ MB/);
-      expect(output).toMatch(/[\d.]+% used/);
-    });
-  });
-
-  describe('deepl cache enable', () => {
-    it('should enable cache successfully', () => {
-      const output = runCLIAll('deepl cache enable');
-
-      expect(output).toContain('Cache enabled');
-    });
-
-    it('should not error if cache already enabled', () => {
-      // Enable twice
-      runCLI('deepl cache enable');
-      const output = runCLIAll('deepl cache enable');
-
-      expect(output).toContain('Cache enabled');
-    });
-  });
-
-  describe('deepl cache disable', () => {
-    it('should disable cache successfully', () => {
-      const output = runCLIAll('deepl cache disable');
-
-      expect(output).toContain('Cache disabled');
-    });
-
-    it('should not error if cache already disabled', () => {
-      // Disable twice
-      runCLI('deepl cache disable');
-      const output = runCLIAll('deepl cache disable');
-
-      expect(output).toContain('Cache disabled');
-    });
-  });
-
-  describe('deepl cache clear', () => {
-    it('should clear cache successfully with --yes flag', () => {
-      const output = runCLIAll('deepl cache clear --yes');
-
-      expect(output).toContain('Cache cleared successfully');
-    });
-
-    it('should not error when cache is empty', () => {
-      // Clear twice
-      runCLI('deepl cache clear --yes');
-      const output = runCLIAll('deepl cache clear --yes');
-
-      expect(output).toContain('Cache cleared successfully');
-    });
-
-    it('should abort without --yes in non-TTY mode', () => {
-      const output = runCLIAll('deepl cache clear');
-
-      expect(output).toContain('Aborted');
-    });
-
-    it('should accept -y short flag', () => {
-      const output = runCLIAll('deepl cache clear -y');
-
-      expect(output).toContain('Cache cleared successfully');
-    });
-  });
-
-  describe('cache workflow', () => {
-    it('should handle enable -> clear -> disable workflow', () => {
-      // Enable
-      const enableOutput = runCLIAll('deepl cache enable');
-      expect(enableOutput).toContain('Cache enabled');
-
-      // Clear
-      const clearOutput = runCLIAll('deepl cache clear --yes');
-      expect(clearOutput).toContain('Cache cleared successfully');
-
-      // Stats should show 0 entries
-      const statsOutput = runCLI('deepl cache stats');
-      expect(statsOutput).toContain('Entries: 0');
-
-      // Disable
-      const disableOutput = runCLIAll('deepl cache disable');
-      expect(disableOutput).toContain('Cache disabled');
-    });
-  });
-});

From 162b9b30a04b5ce608e619cfda46c47a8166ff0f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 11:41:19 -0400
Subject: [PATCH 093/256] test(config): merge the config suites, keeping the
 integration file's substance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Another pair where the integration file was the deeper one. It covered value
coercion beyond booleans and strings (a number stored as a number, a
comma-separated list split into an array), that a write reaches config.json on
disk rather than only surviving a read-back through the same CLI,
pretty-printed list output, reset via -y, and that aborting a reset leaves
values untouched -- where the E2E file only checked for the word "Aborted".

Its output.color pair is carried over strengthened. The original asserted no
ANSI when output.color was false but did not set FORCE_COLOR, so a non-TTY
subprocess satisfied it whatever the setting did. Both directions now set
FORCE_COLOR=1, making the setting the only variable; confirmed against the
built CLI that false suppresses colour and true emits it under FORCE_COLOR.

Dropped rather than ported: "should remove config file on reset", whose only
assertion was that the command did not throw -- it never looked at the file
its title names.

Each test now starts from `config reset --yes` instead of a hand-written
config.json, so the expected values are the CLI's own defaults and the
existing "restore default" lines are no longer needed.

Net 29 tests across two files becomes 21 in one.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-config.e2e.test.ts              | 151 ++++++++---
 .../cli-config.integration.test.ts            | 236 ------------------
 2 files changed, 115 insertions(+), 272 deletions(-)
 delete mode 100644 tests/integration/cli-config.integration.test.ts

diff --git a/tests/e2e/cli-config.e2e.test.ts b/tests/e2e/cli-config.e2e.test.ts
index d340b61d..2e095c23 100644
--- a/tests/e2e/cli-config.e2e.test.ts
+++ b/tests/e2e/cli-config.e2e.test.ts
@@ -1,12 +1,22 @@
 /**
  * E2E Tests for Config Command
- * Tests the `deepl config` command end-to-end
+ *
+ * Covers the value coercion `config set` applies, that writes reach the
+ * config file on disk, and that `output.color` decides colouring even when
+ * the environment asks for it.
  */
 
+import * as fs from 'fs';
+import * as path from 'path';
 import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
+// ANSI escape introducer: ESC followed by '['.
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /\x1b\[/;
+
 describe('Config Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-config');
+  const configPath = path.join(testConfig.path, 'config.json');
   const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(
     testConfig.path
   );
@@ -15,6 +25,12 @@ describe('Config Command E2E', () => {
     testConfig.cleanup();
   });
 
+  // Every test starts from the shipped defaults rather than from whatever the
+  // previous one left behind, so the expected values below are the CLI's own.
+  beforeEach(() => {
+    runCLI('config reset --yes');
+  });
+
   describe('config --help', () => {
     it('should display help text', () => {
       const output = runCLI('config --help');
@@ -27,7 +43,7 @@ describe('Config Command E2E', () => {
     it('should describe the command', () => {
       const output = runCLI('config --help');
 
-      expect(output).toMatch(/config|settings|manage/i);
+      expect(output).toContain('Manage configuration');
     });
 
     it('should list subcommands', () => {
@@ -38,74 +54,137 @@ describe('Config Command E2E', () => {
   });
 
   describe('config list', () => {
-    it('should display configuration as JSON', () => {
+    it('should display every configuration section as JSON', () => {
       const output = runCLI('config list');
+      const config = JSON.parse(output) as Record<string, unknown>;
 
-      const config = JSON.parse(output);
+      expect(config).toHaveProperty('auth');
+      expect(config).toHaveProperty('api');
+      expect(config).toHaveProperty('defaults');
       expect(config).toHaveProperty('cache');
       expect(config).toHaveProperty('output');
+      expect(config).toHaveProperty('watch');
+    });
+
+    it('should pretty-print rather than emit one line', () => {
+      const output = runCLI('config list');
+
+      expect(output).toContain('{\n');
+      expect(output).toContain('  "auth"');
     });
 
     it('should exit successfully', () => {
       const result = runCLIExpectError('config list');
+
       expect(result.status).toBe(0);
     });
   });
 
   describe('config get', () => {
-    it('should get a config value', () => {
-      const output = runCLI('config get cache.enabled');
-      const value = JSON.parse(output);
-      expect(typeof value).toBe('boolean');
+    it('should get a nested value', () => {
+      expect(JSON.parse(runCLI('config get cache.enabled'))).toBe(true);
+    });
+
+    it('should get a whole section', () => {
+      const cache = JSON.parse(runCLI('config get cache')) as Record<
+        string,
+        unknown
+      >;
+
+      expect(cache).toHaveProperty('enabled');
+      expect(cache).toHaveProperty('maxSize');
+      expect(cache).toHaveProperty('ttl');
     });
 
-    it('should return null for non-existent key', () => {
-      const output = runCLI('config get nonexistent.key');
-      const value = JSON.parse(output);
-      expect(value).toBeNull();
+    it('should return null for an unknown key', () => {
+      expect(JSON.parse(runCLI('config get nonexistent.key'))).toBeNull();
     });
   });
 
-  describe('config set and get workflow', () => {
-    it('should set and retrieve a boolean value', () => {
+  describe('config set value coercion', () => {
+    it('should store a boolean as a boolean', () => {
       runCLI('config set cache.enabled false');
 
-      const output = runCLI('config get cache.enabled');
-      const value = JSON.parse(output);
-      expect(value).toBe(false);
+      expect(JSON.parse(runCLI('config get cache.enabled'))).toBe(false);
+    });
 
-      // Restore default
-      runCLI('config set cache.enabled true');
+    it('should store a number as a number', () => {
+      runCLI('config set cache.maxSize 2048');
+
+      expect(JSON.parse(runCLI('config get cache.maxSize'))).toBe(2048);
     });
 
-    it('should set and retrieve a string value', () => {
+    it('should store a string as a string', () => {
       runCLI('config set output.format json');
 
-      const output = runCLI('config get output.format');
-      const value = JSON.parse(output);
-      expect(value).toBe('json');
+      expect(JSON.parse(runCLI('config get output.format'))).toBe('json');
+    });
+
+    it('should split a comma-separated list into an array', () => {
+      runCLI('config set defaults.targetLangs es,fr,de');
+
+      expect(JSON.parse(runCLI('config get defaults.targetLangs'))).toEqual([
+        'es',
+        'fr',
+        'de',
+      ]);
+    });
+
+    it('should persist the change to the config file on disk', () => {
+      runCLI('config set cache.enabled false');
+
+      const onDisk = JSON.parse(fs.readFileSync(configPath, 'utf-8')) as {
+        cache: { enabled: boolean };
+      };
 
-      // Restore default
-      runCLI('config set output.format text');
+      expect(onDisk.cache.enabled).toBe(false);
     });
   });
 
   describe('config reset', () => {
-    it('should abort without --yes in non-TTY mode', () => {
-      const output = runCLIAll('config reset');
-      expect(output).toContain('Aborted');
+    it('should restore defaults with --yes', () => {
+      runCLI('config set cache.enabled false');
+      runCLI('config reset --yes');
+
+      expect(JSON.parse(runCLI('config get cache.enabled'))).toBe(true);
     });
 
-    it('should reset with --yes flag', () => {
-      // Change a value
+    it('should accept the -y short flag', () => {
       runCLI('config set cache.enabled false');
+      runCLI('config reset -y');
 
-      // Reset
-      runCLI('config reset --yes');
+      expect(JSON.parse(runCLI('config get cache.enabled'))).toBe(true);
+    });
+
+    it('should abort without --yes and leave values untouched', () => {
+      runCLI('config set cache.enabled false');
+
+      expect(runCLIAll('config reset')).toContain('Aborted');
+      expect(JSON.parse(runCLI('config get cache.enabled'))).toBe(false);
+    });
+  });
+
+  describe('output.color', () => {
+    // FORCE_COLOR is set in both directions so the setting, not the absence of
+    // a TTY, is what the assertion turns on.
+    it('should suppress colour when output.color is false', () => {
+      runCLI('config set output.color false');
+
+      const output = runCLIAll('config set cache.enabled true', {
+        env: { FORCE_COLOR: '1' },
+      });
+
+      expect(output).not.toMatch(ANSI_REGEX);
+    });
+
+    it('should emit colour when output.color is true', () => {
+      runCLI('config set output.color true');
+
+      const output = runCLIAll('config set cache.enabled true', {
+        env: { FORCE_COLOR: '1' },
+      });
 
-      // Verify defaults restored
-      const output = runCLI('config get cache.enabled');
-      expect(JSON.parse(output)).toBe(true);
+      expect(output).toMatch(ANSI_REGEX);
     });
   });
 
@@ -119,7 +198,7 @@ describe('Config Command E2E', () => {
     it('should show config in main help with description', () => {
       const helpOutput = runCLI('--help');
 
-      expect(helpOutput).toMatch(/config/i);
+      expect(helpOutput).toContain('Manage configuration');
     });
   });
 });
diff --git a/tests/integration/cli-config.integration.test.ts b/tests/integration/cli-config.integration.test.ts
deleted file mode 100644
index 4d612829..00000000
--- a/tests/integration/cli-config.integration.test.ts
+++ /dev/null
@@ -1,236 +0,0 @@
-/**
- * Integration Tests for Config CLI Commands
- * Tests the full config command flow with real file persistence
- */
-
-import { execSync } from 'child_process';
-import * as fs from 'fs';
-import * as path from 'path';
-import { createTestConfigDir, makeRunCLI } from '../helpers';
-
-describe('Config CLI Integration', () => {
-  const testConfig = createTestConfigDir('test-config');
-  const testConfigDir = testConfig.path;
-  const configPath = path.join(testConfigDir, 'config.json');
-  const { runCLI } = makeRunCLI(testConfig.path);
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  beforeEach(() => {
-    // Create default config for each test
-    const defaultConfig = {
-      auth: { apiKey: undefined },
-      api: {
-        baseUrl: 'https://api-free.deepl.com/v2',
-        usePro: false,
-      },
-      defaults: {
-        sourceLang: undefined,
-        targetLangs: [],
-        formality: 'default',
-        preserveFormatting: true,
-      },
-      cache: {
-        enabled: true,
-        maxSize: 1073741824,
-        ttl: 2592000,
-      },
-      output: {
-        format: 'text',
-        color: true,
-        verbose: false,
-      },
-      watch: {
-        debounceMs: 500,
-        autoCommit: false,
-        pattern: '**/*',
-      },
-    };
-
-    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
-  });
-
-  describe('deepl config list', () => {
-    it('should list all configuration values as JSON', () => {
-      const output = runCLI('deepl config list');
-
-      // Parse JSON output
-      const config = JSON.parse(output);
-
-      // Verify structure
-      expect(config).toHaveProperty('auth');
-      expect(config).toHaveProperty('api');
-      expect(config).toHaveProperty('defaults');
-      expect(config).toHaveProperty('cache');
-      expect(config).toHaveProperty('output');
-      expect(config).toHaveProperty('watch');
-    });
-
-    it('should show formatted JSON', () => {
-      const output = runCLI('deepl config list');
-
-      // Should be pretty-printed JSON
-      expect(output).toContain('{\n');
-      expect(output).toContain('  "auth"');
-    });
-  });
-
-  describe('deepl config get', () => {
-    it('should get specific nested config value', () => {
-      const output = runCLI('deepl config get cache.enabled');
-
-      const value = JSON.parse(output);
-      expect(value).toBe(true);
-    });
-
-    it('should get top-level config section', () => {
-      const output = runCLI('deepl config get cache');
-
-      const cache = JSON.parse(output);
-      expect(cache).toHaveProperty('enabled');
-      expect(cache).toHaveProperty('maxSize');
-      expect(cache).toHaveProperty('ttl');
-    });
-
-    it('should return null for non-existent key', () => {
-      const output = runCLI('deepl config get nonexistent.key');
-
-      const value = JSON.parse(output);
-      expect(value).toBeNull();
-    });
-  });
-
-  describe('deepl config set', () => {
-    it('should set a boolean value', () => {
-      runCLI('deepl config set cache.enabled false');
-
-      // Verify it was set
-      const output = runCLI('deepl config get cache.enabled');
-      const value = JSON.parse(output);
-      expect(value).toBe(false);
-    });
-
-    it('should set a number value', () => {
-      runCLI('deepl config set cache.maxSize 2048');
-
-      // Verify it was set
-      const output = runCLI('deepl config get cache.maxSize');
-      const value = JSON.parse(output);
-      expect(value).toBe(2048);
-    });
-
-    it('should set a string value', () => {
-      runCLI('deepl config set output.format json');
-
-      // Verify it was set
-      const output = runCLI('deepl config get output.format');
-      const value = JSON.parse(output);
-      expect(value).toBe('json');
-    });
-
-    it('should set array values from comma-separated string', () => {
-      runCLI('deepl config set defaults.targetLangs es,fr,de');
-
-      // Verify it was set
-      const output = runCLI('deepl config get defaults.targetLangs');
-      const value = JSON.parse(output);
-      expect(value).toEqual(['es', 'fr', 'de']);
-    });
-
-    it('should persist changes to config file', () => {
-      runCLI('deepl config set cache.enabled false');
-
-      // Read config file directly
-      const configContent = fs.readFileSync(configPath, 'utf-8');
-      const config = JSON.parse(configContent);
-
-      expect(config.cache.enabled).toBe(false);
-    });
-  });
-
-  describe('deepl config reset', () => {
-    it('should reset configuration to defaults with --yes flag', () => {
-      // Change a value
-      runCLI('deepl config set cache.enabled false');
-
-      // Reset (success message goes to stderr via Logger.success, so just verify it runs)
-      runCLI('deepl config reset --yes');
-
-      // Verify defaults restored
-      const cacheEnabled = runCLI('deepl config get cache.enabled');
-      expect(JSON.parse(cacheEnabled)).toBe(true);
-    });
-
-    it('should remove config file on reset', () => {
-      expect(() => runCLI('deepl config reset --yes')).not.toThrow();
-    });
-
-    it('should abort without --yes in non-TTY mode', () => {
-      // Change a value
-      runCLI('deepl config set cache.enabled false');
-
-      // Reset without --yes (non-TTY should abort)
-      const output = execSync('deepl config reset 2>&1', {
-        encoding: 'utf-8',
-        env: { ...process.env, DEEPL_CONFIG_DIR: testConfigDir },
-        shell: '/bin/sh',
-      });
-      expect(output).toContain('Aborted');
-
-      // Value should still be changed
-      const cacheEnabled = runCLI('deepl config get cache.enabled');
-      expect(JSON.parse(cacheEnabled)).toBe(false);
-    });
-
-    it('should accept -y short flag', () => {
-      runCLI('deepl config set cache.enabled false');
-      runCLI('deepl config reset -y');
-
-      const cacheEnabled = runCLI('deepl config get cache.enabled');
-      expect(JSON.parse(cacheEnabled)).toBe(true);
-    });
-  });
-
-  describe('output.color disables chalk colors', () => {
-    // ANSI escape code pattern: ESC[ followed by color/style codes
-    // eslint-disable-next-line no-control-regex
-    const ANSI_REGEX = /\x1b\[/;
-
-    // Success messages go to stderr via Logger.success, so redirect stderr to stdout
-    const runCLIWithStderr = (
-      command: string,
-      extraEnv?: Record<string, string>
-    ): string => {
-      return execSync(`${command} 2>&1`, {
-        encoding: 'utf-8',
-        env: { ...process.env, DEEPL_CONFIG_DIR: testConfigDir, ...extraEnv },
-        shell: '/bin/sh',
-      });
-    };
-
-    it('should produce no ANSI codes in output when output.color is false', () => {
-      runCLI('deepl config set output.color false');
-
-      // Run a command that normally produces colored output (config set emits chalk.green via Logger.success on stderr)
-      const output = runCLIWithStderr('deepl config set cache.enabled true');
-
-      expect(output).not.toMatch(ANSI_REGEX);
-    });
-
-    it('should produce ANSI codes when output.color is true (default)', () => {
-      // Ensure color is enabled (default)
-      runCLI('deepl config set output.color true');
-
-      // Run a command that produces colored output
-      // Force color output by setting FORCE_COLOR=1 (chalk respects this)
-      // Capture stderr where Logger.success writes
-      const output = runCLIWithStderr('deepl config set cache.enabled true', {
-        FORCE_COLOR: '1',
-      });
-
-      expect(output).toMatch(ANSI_REGEX);
-    });
-  });
-});

From 7468caa27780e7343b808f83c2801ce534135135 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 11:43:02 -0400
Subject: [PATCH 094/256] test(languages): merge duplicate integration coverage
 into the E2E suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The E2E file was already the richer side, covering --format json, the
--features matrix against a mock server, and flag combinations. Four of the
integration file's nine tests restated registry-degradation cases it covers
more strongly, and two were vacuous:

- "should not require any arguments" asserted the help does not contain the
  literal "<required", which commander never emits -- it writes <name>.
- "should accept optional flags" asserted the help contains "[options]",
  true of every commander command.

Ported: regional variants matched as anchored rows rather than substrings, so
a variant relabelled or dropped from the bundled snapshot fails. The E2E
suite only checked that "English (British)" appeared somewhere. Carried over
with its excludeApiKey and noColor options intact -- the codes are chalk.cyan'd,
so an anchored row breaks wherever colour is forced on.

Tightened: the real command description in both `languages --help` and main
help, where E2E matched /list.*languages/i; and the --source/--target option
descriptions, where E2E matched the looser "source languages".

Net 31 tests across two files becomes 23 in one.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-languages.e2e.test.ts           |  24 +++-
 .../cli-languages.integration.test.ts         | 109 ------------------
 2 files changed, 21 insertions(+), 112 deletions(-)
 delete mode 100644 tests/integration/cli-languages.integration.test.ts

diff --git a/tests/e2e/cli-languages.e2e.test.ts b/tests/e2e/cli-languages.e2e.test.ts
index deb310aa..556a2696 100644
--- a/tests/e2e/cli-languages.e2e.test.ts
+++ b/tests/e2e/cli-languages.e2e.test.ts
@@ -46,6 +46,7 @@ describe('Languages Command E2E', () => {
       expect(output).toContain('Usage:');
       expect(output).toContain('languages');
       expect(output).toContain('Options:');
+      expect(output).toContain('List supported source and target languages');
     });
 
     it('should show source and target options', () => {
@@ -53,8 +54,8 @@ describe('Languages Command E2E', () => {
 
       expect(output).toContain('--source');
       expect(output).toContain('--target');
-      expect(output).toContain('source languages');
-      expect(output).toContain('target languages');
+      expect(output).toContain('Show only source languages');
+      expect(output).toContain('Show only target languages');
     });
 
     it('should display short flags', () => {
@@ -99,6 +100,21 @@ describe('Languages Command E2E', () => {
       expect(result.stdout).toContain('English (American)');
     });
 
+    // Anchored rows rather than substrings, so a variant listed under the wrong
+    // label or dropped from the bundled snapshot fails here. noColor because the
+    // code is chalk.cyan'd; excludeApiKey to read the snapshot, not the API.
+    it('should list regional variants against their own labels', () => {
+      const output = runCLI('languages --target', {
+        excludeApiKey: true,
+        noColor: true,
+      });
+
+      expect(output).toMatch(/^\s+de-ch\s+German \(Swiss\)$/m);
+      expect(output).toMatch(/^\s+fr-ca\s+French \(Canadian\)$/m);
+      expect(output).toMatch(/^\s+de-de\s+German$/m);
+      expect(output).toMatch(/^\s+fr-fr\s+French$/m);
+    });
+
     it('should warn about missing API key', () => {
       const result = runCLIWithEnv('languages', { DEEPL_API_KEY: '' });
 
@@ -271,7 +287,9 @@ describe('Languages Command E2E', () => {
       const helpOutput = runCLI('--help');
 
       expect(helpOutput).toContain('languages');
-      expect(helpOutput).toMatch(/list.*languages/i);
+      expect(helpOutput).toContain(
+        'List supported source and target languages'
+      );
     });
 
     it('should support --quiet flag', () => {
diff --git a/tests/integration/cli-languages.integration.test.ts b/tests/integration/cli-languages.integration.test.ts
deleted file mode 100644
index 1edfacf8..00000000
--- a/tests/integration/cli-languages.integration.test.ts
+++ /dev/null
@@ -1,109 +0,0 @@
-/**
- * Integration Tests for Languages CLI Command
- * Tests the languages command CLI behavior and output formatting
- */
-
-import { createTestConfigDir, makeRunCLI } from '../helpers';
-
-describe('Languages CLI Integration', () => {
-  const testConfig = createTestConfigDir('languages');
-  const { runCLI } = makeRunCLI(testConfig.path);
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  describe('deepl languages --help', () => {
-    it('should display help for languages command', () => {
-      const output = runCLI('deepl languages --help');
-
-      expect(output).toContain('Usage:');
-      expect(output).toContain('deepl languages');
-      expect(output).toContain('List supported source and target languages');
-      expect(output).toContain('--source');
-      expect(output).toContain('--target');
-    });
-  });
-
-  describe('deepl languages without API key (graceful degradation)', () => {
-    it('should show registry-only output with warning when no API key', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl auth clear');
-      } catch {
-        // Ignore if already cleared
-      }
-
-      const output = runCLI('deepl languages', { apiKey: '' });
-
-      expect(output).toContain('Source Languages:');
-      expect(output).toContain('Target Languages:');
-    });
-
-    it('should show extended languages without API key', () => {
-      const output = runCLI('deepl languages --source', { apiKey: '' });
-
-      expect(output).toContain('Source Languages:');
-      expect(output).toContain('Extended Languages');
-    });
-
-    it('should list the regional variants the snapshot previously omitted', () => {
-      // noColor because the code is chalk.cyan'd, so anchoring on the row would
-      // otherwise trip over the escape sequence wherever colour is forced on;
-      // excludeApiKey to read the snapshot rather than the live API.
-      const output = runCLI('deepl languages --target', {
-        excludeApiKey: true,
-        noColor: true,
-      });
-
-      expect(output).toMatch(/^\s+de-ch\s+German \(Swiss\)$/m);
-      expect(output).toMatch(/^\s+fr-ca\s+French \(Canadian\)$/m);
-      expect(output).toMatch(/^\s+de-de\s+German$/m);
-      expect(output).toMatch(/^\s+fr-fr\s+French$/m);
-    });
-  });
-
-  describe('deepl languages command structure', () => {
-    it('should be available as a command', () => {
-      const helpOutput = runCLI('deepl --help');
-
-      // Languages command should be listed in main help
-      expect(helpOutput).toContain('languages');
-      expect(helpOutput).toContain(
-        'List supported source and target languages'
-      );
-    });
-
-    it('should support --source flag', () => {
-      const output = runCLI('deepl languages --help');
-
-      // Should have --source flag
-      expect(output).toContain('--source');
-      expect(output).toContain('-s');
-      expect(output).toContain('Show only source languages');
-    });
-
-    it('should support --target flag', () => {
-      const output = runCLI('deepl languages --help');
-
-      // Should have --target flag (no -t short flag to avoid conflict with --to)
-      expect(output).toContain('--target');
-      expect(output).toContain('Show only target languages');
-    });
-
-    it('should not require any arguments', () => {
-      const output = runCLI('deepl languages --help');
-
-      // Should be simple command with no required parameters
-      expect(output).toContain('Usage: deepl languages');
-      expect(output).not.toContain('<required');
-    });
-
-    it('should accept optional flags', () => {
-      const output = runCLI('deepl languages --help');
-
-      // Flags should be marked as optional
-      expect(output).toContain('[options]');
-    });
-  });
-});

From 86ee9e9cfed04d2feb2421836bb051b5f10b1afb Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 11:44:29 -0400
Subject: [PATCH 095/256] test(voice): merge duplicate integration coverage
 into the E2E suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Eight of the integration file's ten tests restated E2E coverage: the same
help-flag list (E2E also asserts <file>), examples, missing file, missing
--to, missing API key, and main-help registration. "should show format
choices" only checked that the words "text" and "json" appear anywhere in
help, which the E2E --format tests cover by actually passing them.

Two are ported:

- --no-reconnect and --max-reconnect-attempts, which the E2E help test's
  otherwise-complete flag list omitted
- an http:// baseUrl in config being rejected rather than used, which nothing
  in the E2E suite covered. It gets its own config dir, since the test works
  by poisoning config.json and the rest of the file shares one

Net 10 tests removed, 1 added.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-voice.e2e.test.ts               |  31 ++++
 .../integration/cli-voice.integration.test.ts | 155 ------------------
 2 files changed, 31 insertions(+), 155 deletions(-)
 delete mode 100644 tests/integration/cli-voice.integration.test.ts

diff --git a/tests/e2e/cli-voice.e2e.test.ts b/tests/e2e/cli-voice.e2e.test.ts
index 5ddee6f2..d8650c62 100644
--- a/tests/e2e/cli-voice.e2e.test.ts
+++ b/tests/e2e/cli-voice.e2e.test.ts
@@ -34,6 +34,8 @@ describe('Voice CLI E2E', () => {
       expect(output).toContain('--chunk-interval');
       expect(output).toContain('--no-stream');
       expect(output).toContain('--format');
+      expect(output).toContain('--no-reconnect');
+      expect(output).toContain('--max-reconnect-attempts');
     });
 
     it('should show voice in main help', () => {
@@ -49,6 +51,35 @@ describe('Voice CLI E2E', () => {
     });
   });
 
+  describe('Insecure API URL in config', () => {
+    // Its own config dir: the point of the test is a poisoned config.json, and
+    // the rest of this file shares one.
+    it('should reject an http:// base URL rather than sending audio to it', () => {
+      const insecureConfig = createTestConfigDir('voice-e2e-insecure');
+      const audioFile = path.join(testDir, 'insecure-url.mp3');
+      fs.writeFileSync(audioFile, Buffer.alloc(100));
+      fs.writeFileSync(
+        path.join(insecureConfig.path, 'config.json'),
+        JSON.stringify({
+          auth: { apiKey: 'test-key-for-url-validation' },
+          api: { baseUrl: 'http://evil-server.example.com/v2', usePro: false },
+        })
+      );
+      const { runCLIAll: runInsecure } = makeRunCLI(insecureConfig.path);
+
+      let output: string;
+      try {
+        output = runInsecure(`deepl voice ${audioFile} --to de`);
+      } catch (error) {
+        const failure = error as { stdout?: unknown; stderr?: unknown };
+        output = String(failure.stdout ?? '') + String(failure.stderr ?? '');
+      }
+      insecureConfig.cleanup();
+
+      expect(output).toMatch(/Insecure HTTP URL rejected/i);
+    });
+  });
+
   describe('Exit codes', () => {
     it('should exit with non-zero when no file argument provided', () => {
       expect.assertions(1);
diff --git a/tests/integration/cli-voice.integration.test.ts b/tests/integration/cli-voice.integration.test.ts
deleted file mode 100644
index 94912048..00000000
--- a/tests/integration/cli-voice.integration.test.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-/**
- * Integration Tests for Voice CLI Command
- * Tests the voice command CLI behavior, argument validation, and error handling.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { createTestConfigDir, createTestDir, makeRunCLI } from '../helpers';
-
-describe('Voice CLI Integration', () => {
-  const testConfig = createTestConfigDir('voice');
-  const testFiles = createTestDir('voice-files');
-  const testDir = testFiles.path;
-  const { runCLI } = makeRunCLI(testConfig.path);
-
-  afterAll(() => {
-    testConfig.cleanup();
-    testFiles.cleanup();
-  });
-
-  describe('deepl voice --help', () => {
-    it('should display help for voice command', () => {
-      const output = runCLI('deepl voice --help');
-
-      expect(output).toContain('Usage:');
-      expect(output).toContain('deepl voice');
-      expect(output).toContain('Translate audio');
-      expect(output).toContain('--to');
-      expect(output).toContain('--from');
-      expect(output).toContain('--formality');
-      expect(output).toContain('--glossary');
-      expect(output).toContain('--content-type');
-      expect(output).toContain('--chunk-size');
-      expect(output).toContain('--chunk-interval');
-      expect(output).toContain('--no-stream');
-      expect(output).toContain('--format');
-    });
-
-    it('should show usage examples in help text', () => {
-      const output = runCLI('deepl voice --help');
-
-      expect(output).toContain('Examples:');
-      expect(output).toContain('recording.ogg');
-      expect(output).toContain('--to de');
-    });
-
-    it('should show format choices', () => {
-      const output = runCLI('deepl voice --help');
-
-      expect(output).toContain('text');
-      expect(output).toContain('json');
-    });
-
-    it('should show reconnection options in help', () => {
-      const output = runCLI('deepl voice --help');
-
-      expect(output).toContain('--no-reconnect');
-      expect(output).toContain('--max-reconnect-attempts');
-    });
-
-    it('should show formality choices', () => {
-      const output = runCLI('deepl voice --help');
-
-      expect(output).toContain('formal');
-      expect(output).toContain('more');
-      expect(output).toContain('informal');
-      expect(output).toContain('less');
-    });
-  });
-
-  describe('argument validation', () => {
-    it('should require a file argument', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl voice --to de', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|required|argument/i);
-      }
-    });
-
-    it('should require --to flag', () => {
-      const testFile = path.join(testDir, 'test.mp3');
-      fs.writeFileSync(testFile, Buffer.alloc(100));
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl voice ${testFile}`, { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/target language|--to/i);
-      }
-    });
-  });
-
-  describe('deepl voice without API key', () => {
-    it('should fail when no API key is available', () => {
-      const testFile = path.join(testDir, 'test-noauth.mp3');
-      fs.writeFileSync(testFile, Buffer.alloc(100));
-
-      try {
-        runCLI('deepl auth clear', { excludeApiKey: true });
-      } catch {
-        // Ignore
-      }
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl voice ${testFile} --to de`, { excludeApiKey: true });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth|not set/i);
-      }
-    });
-  });
-
-  describe('URL validation in getApiKeyAndOptions', () => {
-    it('should warn about insecure HTTP base URL', () => {
-      const testFile = path.join(testDir, 'test-url.mp3');
-      fs.writeFileSync(testFile, Buffer.alloc(100));
-
-      const configPath = path.join(testConfig.path, 'config.json');
-      fs.writeFileSync(
-        configPath,
-        JSON.stringify({
-          auth: { apiKey: 'test-key-for-url-validation' },
-          api: { baseUrl: 'http://evil-server.example.com/v2', usePro: false },
-        })
-      );
-
-      // CLI falls back to defaults when config contains an insecure URL
-      try {
-        const output = runCLI(`deepl voice ${testFile} --to de`, {
-          stdio: 'pipe',
-        });
-        // Should show the rejection warning but continue with defaults
-        expect(output).toMatch(/Insecure HTTP URL rejected/i);
-      } catch (error: any) {
-        const output =
-          error.stderr?.toString() ??
-          error.stdout?.toString() ??
-          error.message ??
-          '';
-        expect(output).toMatch(/Insecure HTTP URL rejected/i);
-      }
-    });
-  });
-
-  describe('voice appears in main help', () => {
-    it('should list voice command in main help', () => {
-      const output = runCLI('deepl --help');
-      expect(output).toContain('voice');
-    });
-  });
-});

From 5324d6ace2b08ceb54cc4bdd08411fb5bae3c5f4 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 14:58:42 -0400
Subject: [PATCH 096/256] test(glossary): assert the subcommand surface from a
 table
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cli-glossary.integration.test.ts held 63 tests, most of them one template
repeated per subcommand: has-subcommand, synopsis arity, two or three
too-few-argument cases, accepts-all-arguments, --help. Roughly 26 tests
exercised commander's argument arity that way, alongside 6 "should have X
subcommand", 5 "should accept --help flag" and 2 "should not require any
arguments".

Despite the volume it was incomplete: the template covered 10 subcommands and
never reached update, replace-dictionary or delete-dictionary. Driving the same
assertions from one table covers all 13, and a new subcommand is covered by
adding a row rather than copying a describe block.

Dropped as vacuous rather than merged. The create-file tests ("should accept
TSV file", "should accept CSV file", the language-pair case) assert
not.toMatch(/invalid.*format/) on a run with no API key, so the command dies
at auth long before reading the file and the assertion cannot fail. TSV and
CSV parsing is genuinely covered by glossary-service's tsvToEntries tests.
Likewise "glossary languages should not accept extraneous arguments", whose
/argument|API key|auth/i matches the auth failure it actually got.

Kept as behaviour: delete aborting without --yes, both confirmation flags
being documented, --format json on the three reading subcommands, and the
API-key requirement. Arity failures now also assert the output does *not*
mention an API key, proving commander refused on arity rather than the command
reaching the API -- which the originals' /missing|argument|required/i did not
establish.

Verified the table bites: making add-entry's <target> optional fails two tests.

Net 75 tests across two files becomes 18 in one.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-glossary.e2e.test.ts            | 208 ++++--
 .../cli-glossary.integration.test.ts          | 669 ------------------
 2 files changed, 145 insertions(+), 732 deletions(-)
 delete mode 100644 tests/integration/cli-glossary.integration.test.ts

diff --git a/tests/e2e/cli-glossary.e2e.test.ts b/tests/e2e/cli-glossary.e2e.test.ts
index 19c3e7f7..4f0cb8ba 100644
--- a/tests/e2e/cli-glossary.e2e.test.ts
+++ b/tests/e2e/cli-glossary.e2e.test.ts
@@ -1,109 +1,191 @@
 /**
  * E2E Tests for Glossary Command
- * Tests the `deepl glossary` command end-to-end
+ *
+ * The subcommand surface is asserted from one table rather than once per
+ * subcommand, so a new subcommand is covered by adding a row. Glossary
+ * behaviour that needs an account -- creating, listing, entry edits -- belongs
+ * to the glossary service and client unit suites; what matters here is that
+ * every subcommand declares its required arguments and refuses to run without
+ * them.
  */
 
 import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
+/** Every `glossary` subcommand, with the synopsis its help must show. */
+const SUBCOMMANDS: Array<{
+  name: string;
+  synopsis: string;
+  description: string;
+}> = [
+  {
+    name: 'create',
+    synopsis: 'create <name> <source-lang> <target-lang> <file>',
+    description: 'Create a glossary from TSV/CSV file',
+  },
+  {
+    name: 'list',
+    synopsis: 'list [options]',
+    description: 'List all glossaries',
+  },
+  {
+    name: 'show',
+    synopsis: 'show [options] <name-or-id>',
+    description: 'Show glossary details',
+  },
+  {
+    name: 'entries',
+    synopsis: 'entries [options] <name-or-id>',
+    description: 'Show glossary entries',
+  },
+  {
+    name: 'delete',
+    synopsis: 'delete [options] <name-or-id>',
+    description: 'Delete a glossary',
+  },
+  {
+    name: 'languages',
+    synopsis: 'languages',
+    description: 'List supported glossary language pairs',
+  },
+  {
+    name: 'add-entry',
+    synopsis: 'add-entry [options] <name-or-id> <source> <target>',
+    description: 'Add a new entry to a glossary',
+  },
+  {
+    name: 'update-entry',
+    synopsis: 'update-entry [options] <name-or-id> <source> <new-target>',
+    description: 'Update an existing entry in a glossary',
+  },
+  {
+    name: 'remove-entry',
+    synopsis: 'remove-entry [options] <name-or-id> <source>',
+    description: 'Remove an entry from a glossary',
+  },
+  {
+    name: 'rename',
+    synopsis: 'rename <name-or-id> <new-name>',
+    description: 'Rename a glossary',
+  },
+  {
+    name: 'update',
+    synopsis: 'update [options] <name-or-id>',
+    description: 'Update glossary name and/or dictionary entries',
+  },
+  {
+    name: 'replace-dictionary',
+    synopsis: 'replace-dictionary <name-or-id> <target-lang> <file>',
+    description: 'Replace all entries in a glossary dictionary',
+  },
+  {
+    name: 'delete-dictionary',
+    synopsis: 'delete-dictionary [options] <name-or-id> <target-lang>',
+    description: 'Delete a dictionary from a multilingual glossary',
+  },
+];
+
+/** Invocations one argument short of what the subcommand requires. */
+const TOO_FEW_ARGUMENTS: Array<[string, string]> = [
+  ['create', 'glossary create "Test" en de'],
+  ['show', 'glossary show'],
+  ['entries', 'glossary entries'],
+  ['delete', 'glossary delete'],
+  ['add-entry', 'glossary add-entry "Test" "Hello"'],
+  ['update-entry', 'glossary update-entry "Test" "Hello"'],
+  ['remove-entry', 'glossary remove-entry "Test"'],
+  ['rename', 'glossary rename "Test"'],
+  ['update', 'glossary update'],
+  ['replace-dictionary', 'glossary replace-dictionary "Test" de'],
+  ['delete-dictionary', 'glossary delete-dictionary "Test"'],
+];
+
 describe('Glossary Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-glossary');
-  const { runCLI, runCLIExpectError } = makeNodeRunCLI(testConfig.path);
+  const { runCLI, runCLIAll, runCLIExpectError } = makeNodeRunCLI(
+    testConfig.path,
+    { noColor: true }
+  );
 
   afterAll(() => {
     testConfig.cleanup();
   });
 
   describe('glossary --help', () => {
-    it('should display help text', () => {
+    it('should list every subcommand with its description', () => {
       const output = runCLI('glossary --help');
 
-      expect(output).toContain('Usage:');
-      expect(output).toContain('glossary');
-      expect(output).toContain('Options:');
+      expect(output).toContain('Manage translation glossaries');
+      for (const { name, description } of SUBCOMMANDS) {
+        expect(output).toContain(name);
+        expect(output).toContain(description);
+      }
     });
 
-    it('should describe the command', () => {
+    it('should declare the required arguments of every subcommand', () => {
       const output = runCLI('glossary --help');
 
-      expect(output).toMatch(/glossar|manage/i);
+      for (const { synopsis } of SUBCOMMANDS) {
+        expect(output).toContain(synopsis);
+      }
     });
 
-    it('should list subcommands', () => {
-      const output = runCLI('glossary --help');
+    it('should offer --format json on the reading subcommands', () => {
+      for (const subcommand of ['list', 'show', 'entries']) {
+        const output = runCLI(`glossary ${subcommand} --help`);
 
-      expect(output).toContain('Commands:');
-      expect(output).toContain('create');
-      expect(output).toContain('list');
-      expect(output).toContain('show');
-      expect(output).toContain('delete');
+        expect(output).toContain('--format');
+        expect(output).toContain('json');
+      }
     });
   });
 
-  describe('glossary list without API key', () => {
-    it('should require API key', () => {
-      const result = runCLIExpectError('glossary list', { apiKey: '' });
-
-      expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toMatch(/api key/i);
-    });
+  describe('required arguments', () => {
+    // Asserting the failure is *not* about credentials is the point: it shows
+    // commander refused on arity before the command could reach the API.
+    it.each(TOO_FEW_ARGUMENTS)(
+      'should refuse %s when an argument is missing',
+      (_name, invocation) => {
+        const result = runCLIExpectError(invocation, { excludeApiKey: true });
+
+        expect(result.status).toBeGreaterThan(0);
+        expect(result.output).toMatch(/missing required argument/i);
+        expect(result.output).not.toMatch(/API key/i);
+      }
+    );
   });
 
-  describe('glossary subcommand help', () => {
-    it('should show help for glossary list', () => {
-      const output = runCLI('glossary list --help');
+  describe('glossary delete confirmation', () => {
+    it('should abort rather than delete when --yes is absent', () => {
+      const output = runCLIAll('glossary delete "My Glossary"');
 
-      expect(output).toContain('list');
-      expect(output).toContain('--format');
+      expect(output).toContain('Aborted');
     });
 
-    it('should show help for glossary create', () => {
-      const output = runCLI('glossary create --help');
-
-      expect(output).toContain('create');
-    });
-
-    it('should show help for glossary delete', () => {
+    it('should document both confirmation flags', () => {
       const output = runCLI('glossary delete --help');
 
-      expect(output).toContain('delete');
       expect(output).toContain('--yes');
+      expect(output).toContain('-y');
     });
   });
 
-  describe('glossary error handling', () => {
-    it('should require arguments for show subcommand', () => {
-      const result = runCLIExpectError('glossary show');
+  describe('credentials', () => {
+    it('should require an API key to reach the glossary API', () => {
+      const result = runCLIExpectError('glossary list', {
+        excludeApiKey: true,
+      });
 
       expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toMatch(/missing|argument|required/i);
-    });
-
-    it('should require arguments for delete subcommand', () => {
-      const result = runCLIExpectError('glossary delete');
-
-      expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toMatch(/missing|argument|required/i);
-    });
-
-    it('should require arguments for entries subcommand', () => {
-      const result = runCLIExpectError('glossary entries');
-
-      expect(result.status).toBeGreaterThan(0);
-      expect(result.output).toMatch(/missing|argument|required/i);
+      expect(result.output).toMatch(/API key|auth|not set/i);
     });
   });
 
-  describe('glossary command structure', () => {
-    it('should be registered as a command', () => {
-      const helpOutput = runCLI('--help');
-
-      expect(helpOutput).toContain('glossary');
-    });
+  describe('command structure', () => {
+    it('should show glossary in main help with its description', () => {
+      const output = runCLI('--help');
 
-    it('should show glossary in main help with description', () => {
-      const helpOutput = runCLI('--help');
-
-      expect(helpOutput).toMatch(/glossar/i);
+      expect(output).toContain('glossary');
+      expect(output).toContain('Manage translation glossaries');
     });
   });
 });
diff --git a/tests/integration/cli-glossary.integration.test.ts b/tests/integration/cli-glossary.integration.test.ts
deleted file mode 100644
index 0b23df5e..00000000
--- a/tests/integration/cli-glossary.integration.test.ts
+++ /dev/null
@@ -1,669 +0,0 @@
-/**
- * Integration Tests for Glossary CLI Command
- * Tests the glossary command CLI behavior, subcommands, and validation
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { createTestConfigDir, createTestDir, makeRunCLI } from '../helpers';
-
-describe('Glossary CLI Integration', () => {
-  const testConfig = createTestConfigDir('glossary');
-  const testFiles = createTestDir('glossary-files');
-  const { runCLI } = makeRunCLI(testConfig.path);
-  const testDir = testFiles.path;
-
-  afterAll(() => {
-    testConfig.cleanup();
-    testFiles.cleanup();
-  });
-
-  describe('deepl glossary --help', () => {
-    it('should display help for glossary command', () => {
-      const output = runCLI('deepl glossary --help');
-
-      expect(output).toContain('Usage:');
-      expect(output).toContain('deepl glossary');
-      expect(output).toContain('Manage translation glossaries');
-      expect(output).toContain('create');
-      expect(output).toContain('list');
-      expect(output).toContain('show');
-      expect(output).toContain('entries');
-      expect(output).toContain('delete');
-    });
-  });
-
-  describe('deepl glossary without API key', () => {
-    it('should require API key for glossary operations', () => {
-      // Ensure no API key is set
-      try {
-        runCLI('deepl auth clear', { stdio: 'pipe' });
-      } catch {
-        // Ignore if already cleared
-      }
-
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary list', { stdio: 'pipe', excludeApiKey: true });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should indicate API key is required
-        expect(output).toMatch(/API key|auth|not set/i);
-      }
-    });
-  });
-
-  describe('glossary create', () => {
-    it('should require name, source-lang, target-lang, and file arguments', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain(
-        'create <name> <source-lang> <target-lang> <file>'
-      );
-      expect(helpOutput).toContain('Create a glossary from TSV/CSV file');
-    });
-
-    it('should validate missing file argument', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary create "Test" en de', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|file|API key|auth/i);
-      }
-    });
-
-    it('should validate non-existent file', () => {
-      const nonExistentFile = path.join(testDir, 'does-not-exist.tsv');
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl glossary create "Test" en de "${nonExistentFile}"`, {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/not found|does not exist|API key|auth/i);
-      }
-    });
-
-    it('should accept TSV file', () => {
-      const tsvFile = path.join(testDir, 'glossary.tsv');
-      fs.writeFileSync(tsvFile, 'Hello\tHola\nWorld\tMundo\n', 'utf-8');
-
-      expect.assertions(2);
-      try {
-        // Will fail without API key but should recognize file type
-        runCLI(`deepl glossary create "Test" en es "${tsvFile}"`, {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth, not file format
-        expect(output).toMatch(/API key|auth/i);
-        expect(output).not.toMatch(/invalid.*format|unsupported/i);
-      }
-    });
-
-    it('should accept CSV file', () => {
-      const csvFile = path.join(testDir, 'glossary.csv');
-      fs.writeFileSync(csvFile, 'Hello,Hola\nWorld,Mundo\n', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should recognize file type
-        runCLI(`deepl glossary create "Test" en es "${csvFile}"`, {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should not fail on file format
-        expect(output).not.toMatch(/invalid.*format|unsupported/i);
-      }
-    });
-
-    it('should accept comma-separated target languages', () => {
-      const tsvFile = path.join(testDir, 'glossary-multi.tsv');
-      fs.writeFileSync(tsvFile, 'Hello\tHola\nWorld\tMundo\n', 'utf-8');
-
-      expect.assertions(2);
-      try {
-        runCLI(`deepl glossary create "MultiTest" en de,fr,es "${tsvFile}"`, {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth/i);
-        expect(output).not.toMatch(/unsupported|invalid.*format/i);
-      }
-    });
-  });
-
-  describe('glossary list', () => {
-    it('should have list subcommand', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('list');
-      expect(helpOutput).toContain('List all glossaries');
-    });
-
-    it('should not require any arguments', () => {
-      expect.assertions(2);
-      try {
-        // Will fail without API key
-        runCLI('deepl glossary list', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth, not missing arguments
-        expect(output).toMatch(/API key|auth/i);
-        expect(output).not.toMatch(/required|missing.*argument/i);
-      }
-    });
-
-    it('should accept --format json option', () => {
-      const helpOutput = runCLI('deepl glossary list --help');
-      expect(helpOutput).toContain('--format');
-      expect(helpOutput).toContain('json');
-    });
-  });
-
-  describe('glossary show', () => {
-    it('should accept --format json option', () => {
-      const helpOutput = runCLI('deepl glossary show --help');
-      expect(helpOutput).toContain('--format');
-      expect(helpOutput).toContain('json');
-    });
-
-    it('should require name-or-id argument', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('show');
-      expect(helpOutput).toContain('<name-or-id>');
-      expect(helpOutput).toContain('Show glossary details');
-    });
-
-    it('should validate missing argument', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary show', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should accept glossary name or ID', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should accept argument
-        runCLI('deepl glossary show "My Glossary"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth or not found, not argument validation
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-  });
-
-  describe('glossary entries', () => {
-    it('should accept --format json option', () => {
-      const helpOutput = runCLI('deepl glossary entries --help');
-      expect(helpOutput).toContain('--format');
-      expect(helpOutput).toContain('json');
-    });
-
-    it('should require name-or-id argument', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toMatch(/entries.*<name-or-id>/);
-      expect(helpOutput).toContain('Show glossary entries');
-    });
-
-    it('should validate missing argument', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary entries', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should accept glossary name or ID', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should accept argument
-        runCLI('deepl glossary entries "My Glossary"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth or not found, not argument validation
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-  });
-
-  describe('glossary delete', () => {
-    it('should require name-or-id argument', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toMatch(/delete.*<name-or-id>/);
-      expect(helpOutput).toContain('Delete a glossary');
-    });
-
-    it('should validate missing argument', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary delete', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should accept glossary name or ID with --yes flag', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should accept argument
-        runCLI('deepl glossary delete "My Glossary" --yes', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth or not found, not argument validation
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-
-    it('should abort without --yes in non-TTY mode', () => {
-      const { runCLIAll } = makeRunCLI(testConfig.path);
-      const output = runCLIAll('deepl glossary delete "My Glossary"');
-      expect(output).toContain('Aborted');
-    });
-
-    it('should accept -y short flag', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary delete "My Glossary" -y', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-
-    it('should show --yes option in help', () => {
-      const helpOutput = runCLI('deepl glossary delete --help');
-      expect(helpOutput).toContain('--yes');
-      expect(helpOutput).toContain('-y');
-    });
-  });
-
-  describe('command structure', () => {
-    it('should be available as a command', () => {
-      const helpOutput = runCLI('deepl --help');
-
-      // Glossary command should be listed in main help
-      expect(helpOutput).toContain('glossary');
-      expect(helpOutput).toContain('Manage translation glossaries');
-    });
-
-    it('should have subcommands', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      // Should show subcommands structure
-      expect(helpOutput).toContain('Commands:');
-      expect(helpOutput).toMatch(/create.*list.*show.*entries.*delete/s);
-    });
-
-    it('should support help for subcommands', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      // Should mention help command
-      expect(helpOutput).toContain('help [command]');
-    });
-  });
-
-  describe('file format support', () => {
-    it('should mention TSV format', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('TSV');
-    });
-
-    it('should mention CSV format', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('CSV');
-    });
-  });
-
-  describe('language validation', () => {
-    it('should accept valid language pairs', () => {
-      const tsvFile = path.join(testDir, 'valid-lang.tsv');
-      fs.writeFileSync(tsvFile, 'test\tprueba\n', 'utf-8');
-
-      expect.assertions(2);
-      try {
-        // Common language pairs
-        runCLI(`deepl glossary create "Test" en es "${tsvFile}"`, {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth, not language validation
-        expect(output).toMatch(/API key|auth/i);
-        expect(output).not.toMatch(/invalid.*language|unsupported.*language/i);
-      }
-    });
-  });
-
-  describe('glossary languages', () => {
-    it('should have languages subcommand', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('languages');
-      expect(helpOutput).toContain('List supported glossary language pairs');
-    });
-
-    it('should not require any arguments', () => {
-      expect.assertions(2);
-      try {
-        // Will fail without API key
-        runCLI('deepl glossary languages', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth, not missing arguments
-        expect(output).toMatch(/API key|auth/i);
-        expect(output).not.toMatch(/required|missing.*argument/i);
-      }
-    });
-
-    it('should not accept extraneous arguments', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key, but should not accept extra args
-        runCLI('deepl glossary languages extra-arg', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail (either too many args or auth)
-        expect(output).toMatch(/argument|API key|auth/i);
-      }
-    });
-
-    it('should accept --help flag', () => {
-      const helpOutput = runCLI('deepl glossary languages --help');
-
-      expect(helpOutput).toContain('languages');
-      expect(helpOutput).toContain('List supported glossary language pairs');
-    });
-  });
-
-  describe('glossary add-entry', () => {
-    it('should have add-entry subcommand', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('add-entry');
-      expect(helpOutput).toContain('Add a new entry to a glossary');
-    });
-
-    it('should require name-or-id, source, and target arguments', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toMatch(/add-entry.*<name-or-id>.*<source>.*<target>/);
-    });
-
-    it('should validate missing arguments', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary add-entry', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should validate missing source and target', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary add-entry "My Glossary"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should validate missing target', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary add-entry "My Glossary" "Hello"', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should accept all required arguments', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should accept arguments
-        runCLI('deepl glossary add-entry "My Glossary" "Hello" "Hola"', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth or not found, not argument validation
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-
-    it('should accept --help flag', () => {
-      const helpOutput = runCLI('deepl glossary add-entry --help');
-
-      expect(helpOutput).toContain('add-entry');
-      expect(helpOutput).toContain('Add a new entry to a glossary');
-    });
-  });
-
-  describe('glossary update-entry', () => {
-    it('should have update-entry subcommand', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('update-entry');
-      expect(helpOutput).toContain('Update an existing entry in a glossary');
-    });
-
-    it('should require name-or-id, source, and new-target arguments', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toMatch(
-        /update-entry.*<name-or-id>.*<source>.*<new-target>/
-      );
-    });
-
-    it('should validate missing arguments', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary update-entry', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should validate missing source and new-target', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary update-entry "My Glossary"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should validate missing new-target', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary update-entry "My Glossary" "Hello"', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should accept all required arguments', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should accept arguments
-        runCLI(
-          'deepl glossary update-entry "My Glossary" "Hello" "Hola Updated"',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth or not found, not argument validation
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-
-    it('should accept --help flag', () => {
-      const helpOutput = runCLI('deepl glossary update-entry --help');
-
-      expect(helpOutput).toContain('update-entry');
-      expect(helpOutput).toContain('Update an existing entry in a glossary');
-    });
-  });
-
-  describe('glossary remove-entry', () => {
-    it('should have remove-entry subcommand', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('remove-entry');
-      expect(helpOutput).toContain('Remove an entry from a glossary');
-    });
-
-    it('should require name-or-id and source arguments', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toMatch(/remove-entry.*<name-or-id>.*<source>/);
-    });
-
-    it('should validate missing arguments', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary remove-entry', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should validate missing source', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary remove-entry "My Glossary"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should accept all required arguments', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should accept arguments
-        runCLI('deepl glossary remove-entry "My Glossary" "Hello"', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth or not found, not argument validation
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-
-    it('should accept --help flag', () => {
-      const helpOutput = runCLI('deepl glossary remove-entry --help');
-
-      expect(helpOutput).toContain('remove-entry');
-      expect(helpOutput).toContain('Remove an entry from a glossary');
-    });
-  });
-
-  describe('glossary rename', () => {
-    it('should have rename subcommand', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('rename');
-      expect(helpOutput).toContain('Rename a glossary');
-    });
-
-    it('should require name-or-id and new-name arguments', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('rename <name-or-id> <new-name>');
-    });
-
-    it('should validate missing arguments', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary rename', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should validate missing new-name', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl glossary rename "My Glossary"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing|argument|required/i);
-      }
-    });
-
-    it('should accept all required arguments', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should accept arguments
-        runCLI('deepl glossary rename "My Glossary" "New Name"', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth or not found, not argument validation
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-
-    it('should accept glossary ID as identifier', () => {
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should accept ID format
-        runCLI('deepl glossary rename "abc123-def456" "New Name"', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on auth or not found, not argument validation
-        expect(output).toMatch(/API key|auth|not found/i);
-      }
-    });
-
-    it('should accept --help flag', () => {
-      const helpOutput = runCLI('deepl glossary rename --help');
-
-      expect(helpOutput).toContain('rename');
-      expect(helpOutput).toContain('Rename a glossary');
-    });
-
-    it('should show rename in glossary help', () => {
-      const helpOutput = runCLI('deepl glossary --help');
-
-      expect(helpOutput).toContain('rename');
-      expect(helpOutput).toMatch(/rename.*<name-or-id>.*<new-name>/);
-    });
-  });
-});

From a9894f9b7b18daa960c1fbcc3b2090e4bc233024 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 15:00:59 -0400
Subject: [PATCH 097/256] test(document): drop the CLI-surface half of the
 document integration file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cli-document-translation.integration.test.ts held two unrelated top-level
describes: a nock-driven upload/poll/download suite that exercises the service
in-process, and a "Document Translation CLI Integration" block that spawned the
built binary. Only the second overlapped the E2E suite, so the file is split
rather than merged -- the nock half stays.

The removed block was a strict subset of cli-document-translation.e2e.test.ts,
which already covers the same six file types, both --output-format and
--enable-minification, the API-key requirement and the missing --to error.
Several of its assertions could not have failed anyway: "should require API
key for document translation" asserted not.toMatch(/unknown option|unsupported
file type/), which says nothing about API keys, and the file-type cases assert
the absence of an unsupported-type error on a run that dies at auth first.

The helper import narrows to DEEPL_FREE_API_URL; createTestConfigDir,
createTestDir and makeRunCLI were used only by the removed block.

Net 11 tests removed at runtime, 0 added.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ...i-document-translation.integration.test.ts | 132 +-----------------
 1 file changed, 1 insertion(+), 131 deletions(-)

diff --git a/tests/integration/cli-document-translation.integration.test.ts b/tests/integration/cli-document-translation.integration.test.ts
index 41417bcc..fd63f8c8 100644
--- a/tests/integration/cli-document-translation.integration.test.ts
+++ b/tests/integration/cli-document-translation.integration.test.ts
@@ -10,12 +10,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { DeepLClient } from '../../src/api/deepl-client.js';
 import { DocumentTranslationService } from '../../src/services/document-translation.js';
-import {
-  DEEPL_FREE_API_URL,
-  createTestConfigDir,
-  createTestDir,
-  makeRunCLI,
-} from '../helpers';
+import { DEEPL_FREE_API_URL } from '../helpers';
 
 const FREE_API_URL = DEEPL_FREE_API_URL;
 const API_KEY = 'test-api-key-integration:fx';
@@ -916,128 +911,3 @@ describe('Document Translation Integration', () => {
     });
   });
 });
-
-describe('Document Translation CLI Integration', () => {
-  const cliTestConfig = createTestConfigDir('doc-cli');
-  const cliTestFiles = createTestDir('doc-cli-files');
-  const testDir = cliTestFiles.path;
-  const { runCLI } = makeRunCLI(cliTestConfig.path);
-
-  afterAll(() => {
-    cliTestConfig.cleanup();
-    cliTestFiles.cleanup();
-  });
-
-  describe('CLI argument validation for document translation', () => {
-    it('should require --to flag for document files', () => {
-      const testFile = path.join(testDir, 'cli-doc.pdf');
-      fs.writeFileSync(testFile, Buffer.from([0x25, 0x50, 0x44, 0x46]));
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl translate "${testFile}"`, { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/required.*--to|target.*language/i);
-      }
-    });
-
-    it('should require --output flag for file translation', () => {
-      const testFile = path.join(testDir, 'cli-doc2.txt');
-      fs.writeFileSync(testFile, 'Hello world test content');
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl translate "${testFile}" --to es`, { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth|output/i);
-      }
-    });
-
-    it('should require API key for document translation', () => {
-      const testFile = path.join(testDir, 'cli-doc3.pdf');
-      fs.writeFileSync(testFile, Buffer.from([0x25, 0x50, 0x44, 0x46]));
-
-      expect.assertions(1);
-      try {
-        runCLI(
-          `deepl translate "${testFile}" --to es --output "${testDir}/out.pdf"`,
-          {
-            stdio: 'pipe',
-          }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option|unsupported.*file.*type/i);
-      }
-    });
-
-    it('should accept --output-format flag without unknown option error', () => {
-      const testFile = path.join(testDir, 'cli-doc4.pdf');
-      fs.writeFileSync(testFile, Buffer.from([0x25, 0x50, 0x44, 0x46]));
-
-      expect.assertions(1);
-      try {
-        runCLI(
-          `deepl translate "${testFile}" --to es --output "${testDir}/out.docx" --output-format docx`,
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*output-format/i);
-      }
-    });
-
-    it('should accept --enable-minification flag without unknown option error', () => {
-      const testFile = path.join(testDir, 'cli-doc5.pptx');
-      fs.writeFileSync(testFile, Buffer.from([0x50, 0x4b, 0x03, 0x04]));
-
-      expect.assertions(1);
-      try {
-        runCLI(
-          `deepl translate "${testFile}" --to es --output "${testDir}/out.pptx" --enable-minification`,
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*enable-minification/i);
-      }
-    });
-  });
-
-  describe('supported document file types via CLI', () => {
-    const documentTypes = [
-      { ext: 'pdf', header: [0x25, 0x50, 0x44, 0x46] },
-      { ext: 'docx', header: [0x50, 0x4b, 0x03, 0x04] },
-      { ext: 'pptx', header: [0x50, 0x4b, 0x03, 0x04] },
-      { ext: 'xlsx', header: [0x50, 0x4b, 0x03, 0x04] },
-      { ext: 'html', header: null, content: '<html><body>Test</body></html>' },
-      { ext: 'htm', header: null, content: '<html><body>Test</body></html>' },
-    ];
-
-    for (const docType of documentTypes) {
-      it(`should accept .${docType.ext} files`, () => {
-        const testFile = path.join(testDir, `cli-type-test.${docType.ext}`);
-        const outputFile = path.join(testDir, `cli-type-out.${docType.ext}`);
-
-        if (docType.header) {
-          fs.writeFileSync(testFile, Buffer.from(docType.header));
-        } else {
-          fs.writeFileSync(testFile, docType.content ?? '');
-        }
-
-        expect.assertions(1);
-        try {
-          runCLI(
-            `deepl translate "${testFile}" --to es --output "${outputFile}"`,
-            { stdio: 'pipe' }
-          );
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout;
-          expect(output).not.toMatch(/unsupported.*file.*type/i);
-        }
-      });
-    }
-  });
-});

From 349a89bbb4563cbf89d603e6904922e7bf17e82f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 15:05:23 -0400
Subject: [PATCH 098/256] test(style-rules): split the CLI surface out and
 assert it from a table
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cli-style-rules.integration.test.ts held two unrelated top-level describes: a
"Style Rules CLI Integration" block that spawned the binary, and a nock-driven
"Style Rules API Integration" block driving StyleRulesCommand in-process. The
first is removed; the second stays and the file is renamed in its docblock to
say what it now is.

Both sides of this pair had real content. The E2E file was nine describes each
asserting one subcommand's options; the integration block held the validation
worth keeping. Merged, the surface -- synopsis, description and options for all
nine subcommands -- comes from one table, so a new subcommand is a new row
rather than a new describe.

Kept as behaviour: --dry-run reporting a deletion and an instruction removal
without performing either, which run to completion without credentials and so
assert real output rather than a failure message; update refusing with exit 6
when given neither --name nor --rules; create requiring --name and --language;
and per-subcommand arity, now including delete and remove-instruction, which
the integration block never checked.

Dropped: eleven tests whose assertion pair was not.toMatch(/unknown option/)
plus toMatch(/API key|auth/) -- they establish only that flags parsed before
the run died at auth, which the arity table and documented-surface already
cover. Arity failures now additionally assert the output does not mention an
API key, so an arity refusal cannot be confused with a credentials failure.

Net 70 tests across the pair becomes 48, of which 32 are the untouched nock
suite.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-style-rules.e2e.test.ts         | 230 ++++++++----
 .../cli-style-rules.integration.test.ts       | 332 +-----------------
 2 files changed, 166 insertions(+), 396 deletions(-)

diff --git a/tests/e2e/cli-style-rules.e2e.test.ts b/tests/e2e/cli-style-rules.e2e.test.ts
index fd2b341b..04a1e318 100644
--- a/tests/e2e/cli-style-rules.e2e.test.ts
+++ b/tests/e2e/cli-style-rules.e2e.test.ts
@@ -1,112 +1,204 @@
 /**
  * E2E Tests for Style Rules Command
- * Tests `deepl style-rules` help text and argument validation
+ *
+ * The subcommand surface -- synopsis, description and options -- is asserted
+ * from one table, so a new subcommand is covered by adding a row. Style-rule
+ * behaviour that needs a Pro account is covered by the nock suite in
+ * cli-style-rules.integration.test.ts; what belongs here is argument
+ * validation and the --dry-run paths, which run without credentials.
  */
 
 import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
+const SUBCOMMANDS: Array<{
+  name: string;
+  synopsis: string;
+  description: string;
+  options: string[];
+}> = [
+  {
+    name: 'list',
+    synopsis: 'list [options]',
+    description: 'List all style rules',
+    options: ['--detailed', '--page', '--page-size', '--format'],
+  },
+  {
+    name: 'create',
+    synopsis: 'create [options]',
+    description: 'Create a new style rule list',
+    options: ['--name', '--language', '--rules', '--format'],
+  },
+  {
+    name: 'show',
+    synopsis: 'show [options] <id>',
+    description: 'Show a single style rule list',
+    options: ['--detailed', '--format'],
+  },
+  {
+    name: 'update',
+    synopsis: 'update [options] <id>',
+    description: 'Update a style rule list',
+    options: ['--name', '--rules'],
+  },
+  {
+    name: 'delete',
+    synopsis: 'delete [options] <id>',
+    description: 'Delete a style rule list',
+    options: ['--yes', '--dry-run'],
+  },
+  {
+    name: 'instructions',
+    synopsis: 'instructions [options] <style-id>',
+    description: 'List custom instructions for a style rule',
+    options: ['--format'],
+  },
+  {
+    name: 'add-instruction',
+    synopsis: 'add-instruction [options] <style-id> <label> <prompt>',
+    description: 'Add a custom instruction to a style rule',
+    options: ['--source-language'],
+  },
+  {
+    name: 'update-instruction',
+    synopsis: 'update-instruction [options] <style-id> <label> <prompt>',
+    description: 'Update a custom instruction on a style rule',
+    options: ['--source-language'],
+  },
+  {
+    name: 'remove-instruction',
+    synopsis: 'remove-instruction [options] <style-id> <label>',
+    description: 'Remove a custom instruction from a style rule',
+    options: ['--yes', '--dry-run'],
+  },
+];
+
+/** Invocations one positional argument short of what the subcommand requires. */
+const TOO_FEW_ARGUMENTS: Array<[string, string]> = [
+  ['show', 'style-rules show'],
+  ['update', 'style-rules update'],
+  ['delete', 'style-rules delete'],
+  ['instructions', 'style-rules instructions'],
+  ['add-instruction', 'style-rules add-instruction sr-1 tone'],
+  ['update-instruction', 'style-rules update-instruction sr-1 tone'],
+  ['remove-instruction', 'style-rules remove-instruction sr-1'],
+];
+
 describe('Style Rules Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-style-rules');
-  const { runCLI } = makeNodeRunCLI(testConfig.path);
+  const { runCLI, runCLIExpectError } = makeNodeRunCLI(testConfig.path, {
+    noColor: true,
+  });
 
   afterAll(() => {
     testConfig.cleanup();
   });
 
   describe('style-rules --help', () => {
-    it('should show help with available subcommands', () => {
+    it('should list every subcommand with its description', () => {
       const output = runCLI('style-rules --help');
+
       expect(output).toContain('Manage DeepL style rules');
-      expect(output).toContain('list');
       expect(output).toContain('Pro API only');
+      expect(output).toContain('Examples:');
+      for (const { name, description } of SUBCOMMANDS) {
+        expect(output).toContain(name);
+        expect(output).toContain(description);
+      }
     });
 
-    it('should show examples in help text', () => {
+    it('should declare the required arguments of every subcommand', () => {
       const output = runCLI('style-rules --help');
-      expect(output).toContain('deepl style-rules list');
-      expect(output).toContain('--detailed');
-      expect(output).toContain('--format json');
-    });
-  });
 
-  describe('style-rules list --help', () => {
-    it('should show list subcommand options', () => {
-      const output = runCLI('style-rules list --help');
-      expect(output).toContain('--detailed');
-      expect(output).toContain('--page');
-      expect(output).toContain('--page-size');
-      expect(output).toContain('--format');
+      for (const { synopsis } of SUBCOMMANDS) {
+        expect(output).toContain(synopsis);
+      }
     });
-  });
 
-  describe('style-rules create --help', () => {
-    it('should show create subcommand options', () => {
-      const output = runCLI('style-rules create --help');
-      expect(output).toContain('--name');
-      expect(output).toContain('--language');
-      expect(output).toContain('--rules');
-      expect(output).toContain('--format');
-    });
-  });
+    it('should offer each subcommand its own options', () => {
+      for (const { name, options } of SUBCOMMANDS) {
+        const output = runCLI(`style-rules ${name} --help`);
 
-  describe('style-rules show --help', () => {
-    it('should show show subcommand options', () => {
-      const output = runCLI('style-rules show --help');
-      expect(output).toContain('--detailed');
-      expect(output).toContain('--format');
-      expect(output).toMatch(/<id>|id/);
+        for (const option of options) {
+          expect(output).toContain(option);
+        }
+      }
     });
   });
 
-  describe('style-rules update --help', () => {
-    it('should show update subcommand options', () => {
-      const output = runCLI('style-rules update --help');
-      expect(output).toContain('--name');
-      expect(output).toContain('--rules');
+  describe('required arguments', () => {
+    // Asserting the failure is *not* about credentials shows commander refused
+    // on arity before the command could reach the API.
+    it.each(TOO_FEW_ARGUMENTS)(
+      'should refuse %s when a positional argument is missing',
+      (_name, invocation) => {
+        const result = runCLIExpectError(invocation, { excludeApiKey: true });
+
+        expect(result.status).toBeGreaterThan(0);
+        expect(result.output).toMatch(/missing required argument/i);
+        expect(result.output).not.toMatch(/API key/i);
+      }
+    );
+
+    it('should require --name and --language on create', () => {
+      const result = runCLIExpectError('style-rules create', {
+        excludeApiKey: true,
+      });
+
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toMatch(/required.*(--name|--language)/i);
     });
-  });
 
-  describe('style-rules delete --help', () => {
-    it('should show delete subcommand options', () => {
-      const output = runCLI('style-rules delete --help');
-      expect(output).toContain('--yes');
-      expect(output).toContain('--dry-run');
+    it('should exit 6 when update is given neither --name nor --rules', () => {
+      const result = runCLIExpectError('style-rules update sr-1', {
+        excludeApiKey: true,
+      });
+
+      expect(result.status).toBe(6);
     });
   });
 
-  describe('style-rules instructions --help', () => {
-    it('should show instructions subcommand', () => {
-      const output = runCLI('style-rules instructions --help');
-      expect(output).toContain('--format');
-      expect(output).toMatch(/<style-id>|style-id/);
+  describe('--dry-run', () => {
+    // Runs to completion without credentials, which is what makes it safe to
+    // assert on real output here rather than on a failure message.
+    it('should report the deletion it would perform without performing it', () => {
+      const output = runCLI('style-rules delete sr-1 --dry-run', {
+        excludeApiKey: true,
+      });
+
+      expect(output).toContain('[dry-run]');
+      expect(output).toContain('sr-1');
     });
-  });
 
-  describe('style-rules add-instruction --help', () => {
-    it('should show add-instruction subcommand', () => {
-      const output = runCLI('style-rules add-instruction --help');
-      expect(output).toMatch(/<style-id>|style-id/);
-      expect(output).toMatch(/<label>|label/);
-      expect(output).toMatch(/<prompt>|prompt/);
-      expect(output).toContain('--source-language');
+    it('should report the instruction removal it would perform', () => {
+      const output = runCLI(
+        'style-rules remove-instruction sr-1 tone --dry-run',
+        {
+          excludeApiKey: true,
+        }
+      );
+
+      expect(output).toContain('[dry-run]');
+      expect(output).toContain('sr-1');
+      expect(output).toContain('tone');
     });
   });
 
-  describe('style-rules update-instruction --help', () => {
-    it('should show update-instruction subcommand', () => {
-      const output = runCLI('style-rules update-instruction --help');
-      expect(output).toMatch(/<style-id>|style-id/);
-      expect(output).toMatch(/<label>|label/);
-      expect(output).toMatch(/<prompt>|prompt/);
-      expect(output).toContain('--source-language');
+  describe('credentials', () => {
+    it('should require an API key to reach the style-rules API', () => {
+      const result = runCLIExpectError('style-rules list', {
+        excludeApiKey: true,
+      });
+
+      expect(result.status).toBeGreaterThan(0);
+      expect(result.output).toMatch(/API key|auth/i);
     });
   });
 
-  describe('style-rules remove-instruction --help', () => {
-    it('should show remove-instruction subcommand', () => {
-      const output = runCLI('style-rules remove-instruction --help');
-      expect(output).toContain('--yes');
-      expect(output).toContain('--dry-run');
+  describe('command structure', () => {
+    it('should show style-rules in main help', () => {
+      const output = runCLI('--help');
+
+      expect(output).toContain('style-rules');
     });
   });
 });
diff --git a/tests/integration/cli-style-rules.integration.test.ts b/tests/integration/cli-style-rules.integration.test.ts
index 28114588..21ccac96 100644
--- a/tests/integration/cli-style-rules.integration.test.ts
+++ b/tests/integration/cli-style-rules.integration.test.ts
@@ -1,337 +1,15 @@
 /**
- * Integration Tests for Style Rules CLI Command
- * Tests CLI argument parsing, HTTP request structure with nock, and error handling
+ * Integration Tests for the Style Rules API client
+ * Drives StyleRulesCommand in-process against nock, asserting request structure,
+ * response field mapping and error handling. CLI argument parsing lives in
+ * tests/e2e/cli-style-rules.e2e.test.ts.
  */
 
 import nock from 'nock';
 import { DeepLClient } from '../../src/api/deepl-client.js';
 import { StyleRulesService } from '../../src/services/style-rules.js';
 import { StyleRulesCommand } from '../../src/cli/commands/style-rules.js';
-import {
-  createTestConfigDir,
-  makeRunCLI,
-  DEEPL_FREE_API_URL,
-} from '../helpers';
-
-describe('Style Rules CLI Integration', () => {
-  const testConfig = createTestConfigDir('style-rules');
-  const { runCLI } = makeRunCLI(testConfig.path);
-
-  afterAll(() => {
-    testConfig.cleanup();
-  });
-
-  describe('deepl style-rules --help', () => {
-    it('should display help for style-rules command', () => {
-      const output = runCLI('deepl style-rules --help');
-
-      expect(output).toContain('Usage:');
-      expect(output).toContain('style-rules');
-      expect(output).toContain('Manage DeepL style rules');
-      expect(output).toContain('list');
-    });
-
-    it('should display help for style-rules list subcommand', () => {
-      const output = runCLI('deepl style-rules list --help');
-
-      expect(output).toContain('List all style rules');
-      expect(output).toContain('--detailed');
-      expect(output).toContain('--page');
-      expect(output).toContain('--page-size');
-      expect(output).toContain('--format');
-    });
-  });
-
-  describe('deepl style-rules without API key', () => {
-    beforeEach(() => {
-      try {
-        runCLI('deepl auth clear', { stdio: 'pipe' });
-      } catch {
-        // Ignore if already cleared
-      }
-    });
-
-    it('should require API key for style-rules list', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules list', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth|not set/i);
-      }
-    });
-
-    it('should require API key for style-rules list --detailed', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules list --detailed', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth|not set/i);
-      }
-    });
-
-    it('should require API key for style-rules list with pagination', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules list --page 1 --page-size 10', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth|not set/i);
-      }
-    });
-  });
-
-  describe('option flags validation', () => {
-    it('should accept --detailed flag without error', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules list --detailed', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*detailed/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should accept --page flag without error', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules list --page 2', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*page/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should accept --page-size flag without error', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules list --page-size 10', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*page-size/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should accept --format json flag without error', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules list --format json', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*format/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should accept all flags combined', () => {
-      expect.assertions(2);
-      try {
-        runCLI(
-          'deepl style-rules list --detailed --page 1 --page-size 5 --format json',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should accept create subcommand with required flags', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules create --name Foo --language en', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should require --name and --language on create', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules create', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/required.*(--name|--language)/i);
-      }
-    });
-
-    it('should accept show subcommand with positional id', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules show sr-1', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should require id argument on show', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules show', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing.*argument|id.*required/i);
-      }
-    });
-
-    it('should accept update subcommand with --name', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules update sr-1 --name "New"', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should require --name or --rules on update (exit 6)', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules update sr-1', { stdio: 'pipe' });
-      } catch (error: any) {
-        expect(error.status).toBe(6);
-      }
-    });
-
-    it('should accept delete --dry-run without running the deletion', () => {
-      const output = runCLI('deepl style-rules delete sr-1 --dry-run');
-      expect(output).toContain('[dry-run]');
-      expect(output).toContain('sr-1');
-    });
-
-    it('should accept instructions subcommand with positional style-id', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules instructions sr-1', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should require style-id argument on instructions', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules instructions', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing.*argument|style-id.*required/i);
-      }
-    });
-
-    it('should accept add-instruction with three positional args', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl style-rules add-instruction sr-1 tone "Be formal"', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should require all three args on add-instruction', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules add-instruction sr-1 tone', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/missing.*argument|prompt.*required/i);
-      }
-    });
-
-    it('should accept update-instruction with three positional args', () => {
-      expect.assertions(2);
-      try {
-        runCLI(
-          'deepl style-rules update-instruction sr-1 tone "Be friendlier"',
-          { stdio: 'pipe', excludeApiKey: true }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-
-    it('should accept remove-instruction --dry-run without running', () => {
-      const output = runCLI(
-        'deepl style-rules remove-instruction sr-1 tone --dry-run'
-      );
-      expect(output).toContain('[dry-run]');
-      expect(output).toContain('tone');
-      expect(output).toContain('sr-1');
-    });
-
-    it('should accept --source-language on add-instruction', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl style-rules add-instruction sr-1 tone "Be formal" --source-language en',
-          { stdio: 'pipe', excludeApiKey: true }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*source-language/i);
-      }
-    });
-  });
-
-  describe('command structure', () => {
-    it('should be listed in main help', () => {
-      const output = runCLI('deepl --help');
-      expect(output).toContain('style-rules');
-    });
-
-    it('should describe as Pro API only', () => {
-      const output = runCLI('deepl style-rules --help');
-      expect(output).toContain('Pro API only');
-    });
-
-    it('should have list as a subcommand', () => {
-      const output = runCLI('deepl style-rules --help');
-      expect(output).toContain('list');
-      expect(output).toContain('List all style rules');
-    });
-  });
-});
+import { DEEPL_FREE_API_URL } from '../helpers';
 
 describe('Style Rules API Integration', () => {
   const API_KEY = 'test-api-key-123:fx';

From 6e3c97aa532eb520886f41afa9a14750ca434560 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 15:11:43 -0400
Subject: [PATCH 099/256] test: move subprocess-only CLI suites from
 integration to e2e
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five files under tests/integration/ drove the built binary as a subprocess and
had no e2e counterpart, so unlike the pairs merged earlier there was nothing
duplicated -- only a file in the wrong directory. cli-admin, cli-config-file,
cli-dry-run, cli-help-hint and cli-lazy-cache move across unchanged apart from
their titles, which said "Integration" and would have read wrong under
tests/e2e/.

No imports needed rebasing: tests/integration/ and tests/e2e/ sit at the same
depth, so ../helpers and ../../src resolve identically. cli-dry-run keeps its
one src import, the ExitCode enum, which it uses to assert exit codes rather
than magic numbers.

Recorded as renames. All 72 tests still pass and suite totals are unchanged at
278 suites and 6452 tests, since nothing was deleted.

Integration suites that invoke the CLI drop from 22 to 3: cli-translate (54
call sites) and cli-structured-file-translate (10) are hybrids still needing
the split treatment, and cli-watch has 3 call sites inside what is otherwise an
in-process WatchService suite. watch-auto-commit and sync-tms only shell out to
git, so they were never layer violations.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../cli-admin.e2e.test.ts}                                    | 4 ++--
 .../cli-config-file.e2e.test.ts}                              | 4 ++--
 .../cli-dry-run.e2e.test.ts}                                  | 4 ++--
 .../cli-help-hint.e2e.test.ts}                                | 0
 .../cli-lazy-cache.e2e.test.ts}                               | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)
 rename tests/{integration/cli-admin.integration.test.ts => e2e/cli-admin.e2e.test.ts} (98%)
 rename tests/{integration/cli-config-file.integration.test.ts => e2e/cli-config-file.e2e.test.ts} (99%)
 rename tests/{integration/cli-dry-run.integration.test.ts => e2e/cli-dry-run.e2e.test.ts} (99%)
 rename tests/{integration/cli-help-hint.integration.test.ts => e2e/cli-help-hint.e2e.test.ts} (100%)
 rename tests/{integration/cli-lazy-cache.integration.test.ts => e2e/cli-lazy-cache.e2e.test.ts} (98%)

diff --git a/tests/integration/cli-admin.integration.test.ts b/tests/e2e/cli-admin.e2e.test.ts
similarity index 98%
rename from tests/integration/cli-admin.integration.test.ts
rename to tests/e2e/cli-admin.e2e.test.ts
index d66083d4..48d65adf 100644
--- a/tests/integration/cli-admin.integration.test.ts
+++ b/tests/e2e/cli-admin.e2e.test.ts
@@ -1,11 +1,11 @@
 /**
- * Integration Tests for Admin CLI Command
+ * E2E Tests for Admin CLI Command
  * Tests the admin command CLI behavior, argument validation, and error handling
  */
 
 import { createTestConfigDir, makeRunCLI } from '../helpers';
 
-describe('Admin CLI Integration', () => {
+describe('Admin CLI E2E', () => {
   const testConfig = createTestConfigDir('admin');
   const { runCLI, runCLIAll } = makeRunCLI(testConfig.path);
 
diff --git a/tests/integration/cli-config-file.integration.test.ts b/tests/e2e/cli-config-file.e2e.test.ts
similarity index 99%
rename from tests/integration/cli-config-file.integration.test.ts
rename to tests/e2e/cli-config-file.e2e.test.ts
index d38d3396..ec0bbc41 100644
--- a/tests/integration/cli-config-file.integration.test.ts
+++ b/tests/e2e/cli-config-file.e2e.test.ts
@@ -1,5 +1,5 @@
 /**
- * Integration tests for --config flag
+ * E2E tests for the --config flag
  * Tests using custom configuration files
  */
 
@@ -8,7 +8,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { makeRunCLI } from '../helpers';
 
-describe('CLI --config flag integration', () => {
+describe('CLI --config flag E2E', () => {
   const testDir = path.join(
     os.tmpdir(),
     `.deepl-cli-config-test-${Date.now()}`
diff --git a/tests/integration/cli-dry-run.integration.test.ts b/tests/e2e/cli-dry-run.e2e.test.ts
similarity index 99%
rename from tests/integration/cli-dry-run.integration.test.ts
rename to tests/e2e/cli-dry-run.e2e.test.ts
index 4694ae45..9cb32200 100644
--- a/tests/integration/cli-dry-run.integration.test.ts
+++ b/tests/e2e/cli-dry-run.e2e.test.ts
@@ -1,5 +1,5 @@
 /**
- * Integration Tests for --dry-run flag across CLI commands
+ * E2E Tests for the --dry-run flag across CLI commands
  * Tests that --dry-run prevents actual operations and shows descriptive messages
  */
 
@@ -8,7 +8,7 @@ import * as path from 'path';
 import { createTestConfigDir, createTestDir, makeRunCLI } from '../helpers';
 import { ExitCode } from '../../src/utils/exit-codes';
 
-describe('--dry-run CLI Integration', () => {
+describe('--dry-run CLI E2E', () => {
   const testConfig = createTestConfigDir('dryrun');
   const testFiles = createTestDir('dryrun-files');
   const { runCLI, runCLIAll, runCLIExpectError } = makeRunCLI(testConfig.path);
diff --git a/tests/integration/cli-help-hint.integration.test.ts b/tests/e2e/cli-help-hint.e2e.test.ts
similarity index 100%
rename from tests/integration/cli-help-hint.integration.test.ts
rename to tests/e2e/cli-help-hint.e2e.test.ts
diff --git a/tests/integration/cli-lazy-cache.integration.test.ts b/tests/e2e/cli-lazy-cache.e2e.test.ts
similarity index 98%
rename from tests/integration/cli-lazy-cache.integration.test.ts
rename to tests/e2e/cli-lazy-cache.e2e.test.ts
index d92b39ef..5c58c67b 100644
--- a/tests/integration/cli-lazy-cache.integration.test.ts
+++ b/tests/e2e/cli-lazy-cache.e2e.test.ts
@@ -1,5 +1,5 @@
 /**
- * Integration Tests for Lazy CacheService Instantiation
+ * E2E Tests for Lazy CacheService Instantiation
  * Verifies that commands not needing cache (help, version, auth, config)
  * do not trigger SQLite database creation.
  */

From 543ed8473448cc5049e854788d6bd69a32fd1233 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 15:22:27 -0400
Subject: [PATCH 100/256] test(cli): cover the auth stdin path and the watch
 registration branches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

register-auth.ts sat at 71% statements and 50% branches with the entire stdin
path untested: the terminal guard, reading the key, and the 128KB limit. The
existing suite only ever passed the key as an argument. Now covered are
--from-stdin reading and trimming the key, an omitted key falling through to
stdin when it is not a terminal, refusing rather than blocking when it is a
terminal, refusing input over 128KB across chunk boundaries, and --no-verify
reporting that the key was stored without validation.

register-watch.ts sat at 69% statements and 54% branches; dry-run.test.ts
reached the basic --dry-run path and nothing else. Now covered are --to
falling back to defaults.targetLangs and failing when that is absent or empty,
a glossary taking its source language from config and failing when none is
available, the glossary being resolved before --dry-run so a doomed run is not
reported as viable, all three output-directory branches (directory, single
file, bare filename), each optional --dry-run line reporting only when its
flag is present, and the watcher path itself including a failure reaching
handleError.

register-auth.ts  71.11% -> 97.77% statements, 50% -> 100% branches. The one
  uncovered line is the `return` after handleError, which never runs because
  handleError is typed as never-returning.
register-watch.ts 68.75% -> 100% on all four metrics.
Suite totals: statements 95.55, branches 89.43, lines 95.99.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/cli/register-watch.test.ts       | 258 ++++++++++++++++++++
 tests/unit/register-commands-group1.test.ts | 107 ++++++++
 2 files changed, 365 insertions(+)
 create mode 100644 tests/unit/cli/register-watch.test.ts

diff --git a/tests/unit/cli/register-watch.test.ts b/tests/unit/cli/register-watch.test.ts
new file mode 100644
index 00000000..f0b83130
--- /dev/null
+++ b/tests/unit/cli/register-watch.test.ts
@@ -0,0 +1,258 @@
+/**
+ * Unit tests for the `deepl watch` command registration.
+ *
+ * Covers what the registration decides before the watcher exists: resolving
+ * --to from config, applying a glossary's source language, the output directory
+ * --dry-run reports, and the optional lines that report only when their flag
+ * is present.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { Command } from 'commander';
+
+jest.mock('chalk', () => {
+  const passthrough = (s: string): string => s;
+  return {
+    __esModule: true,
+    default: { level: 0, yellow: passthrough, green: passthrough },
+  };
+});
+
+jest.mock('../../../src/utils/logger', () => ({
+  Logger: {
+    info: jest.fn(),
+    warn: jest.fn(),
+    success: jest.fn(),
+    output: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+jest.mock('../../../src/cli/commands/service-factory', () => ({
+  createWatchCommand: jest.fn(),
+}));
+
+import { registerWatch } from '../../../src/cli/commands/register-watch';
+import { createWatchCommand } from '../../../src/cli/commands/service-factory';
+import { Logger } from '../../../src/utils/logger';
+import { ValidationError } from '../../../src/utils/errors';
+import type { ServiceDeps } from '../../../src/cli/commands/service-factory';
+
+const mockCreateWatchCommand = createWatchCommand as jest.MockedFunction<
+  typeof createWatchCommand
+>;
+
+describe('registerWatch', () => {
+  let program: Command;
+  let handleError: jest.Mock;
+  let watch: jest.Mock;
+  let configValues: Record<string, unknown>;
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-'));
+    configValues = {};
+    watch = jest.fn().mockResolvedValue(undefined);
+    mockCreateWatchCommand.mockResolvedValue({ watch } as unknown as Awaited<
+      ReturnType<typeof createWatchCommand>
+    >);
+
+    handleError = jest.fn((error: unknown) => {
+      throw error;
+    });
+    program = new Command();
+    program.exitOverride();
+    registerWatch(program, {
+      createDeepLClient: jest.fn(),
+      getApiKeyAndOptions: jest.fn(),
+      getConfigService: () =>
+        ({
+          getValue: (key: string) => configValues[key],
+        }) as unknown as ReturnType<ServiceDeps['getConfigService']>,
+      getCacheService: jest.fn(),
+      handleError: handleError as unknown as ServiceDeps['handleError'],
+    });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  async function runWatch(argv: string[]): Promise<void> {
+    await program.parseAsync(['node', 'deepl', 'watch', ...argv]);
+  }
+
+  /** The single string --dry-run writes through Logger.output. */
+  function dryRunReport(): string {
+    const [report] = (Logger.output as jest.Mock).mock.calls[0] as [string];
+    return report;
+  }
+
+  describe('resolving the target language', () => {
+    it('falls back to defaults.targetLangs when --to is omitted', async () => {
+      configValues['defaults.targetLangs'] = ['de', 'fr'];
+
+      await runWatch([tmpDir]);
+
+      expect(watch).toHaveBeenCalledWith(
+        tmpDir,
+        expect.objectContaining({ to: 'de,fr' })
+      );
+    });
+
+    it('rejects when --to is omitted and no default is configured', async () => {
+      await expect(runWatch([tmpDir])).rejects.toThrow(
+        'No target language specified.'
+      );
+
+      expect(handleError.mock.calls[0]![0]).toBeInstanceOf(ValidationError);
+      expect(watch).not.toHaveBeenCalled();
+    });
+
+    it('rejects when defaults.targetLangs is configured but empty', async () => {
+      configValues['defaults.targetLangs'] = [];
+
+      await expect(runWatch([tmpDir])).rejects.toThrow(
+        'No target language specified.'
+      );
+    });
+  });
+
+  describe('glossary source language', () => {
+    it('takes the source language from config when --glossary needs one', async () => {
+      configValues['defaults.sourceLang'] = 'EN';
+
+      await runWatch([tmpDir, '--to', 'de', '--glossary', 'my-terms']);
+
+      expect(watch).toHaveBeenCalledWith(
+        tmpDir,
+        expect.objectContaining({ from: 'en', glossary: 'my-terms' })
+      );
+    });
+
+    it('rejects a glossary with no source language available', async () => {
+      await expect(
+        runWatch([tmpDir, '--to', 'de', '--glossary', 'my-terms'])
+      ).rejects.toThrow('Source language (--from) is required');
+
+      expect(watch).not.toHaveBeenCalled();
+    });
+
+    it('resolves the glossary before --dry-run reports the run as viable', async () => {
+      await expect(
+        runWatch([tmpDir, '--to', 'de', '--glossary', 'my-terms', '--dry-run'])
+      ).rejects.toThrow('Source language (--from) is required');
+
+      expect(Logger.output).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('--dry-run output directory', () => {
+    it('reports <path>/translations for a directory', async () => {
+      await runWatch([tmpDir, '--to', 'de', '--dry-run']);
+
+      expect(dryRunReport()).toContain(
+        `Output directory: ${tmpDir}/translations`
+      );
+      expect(watch).not.toHaveBeenCalled();
+    });
+
+    it('reports the containing directory for a single file', async () => {
+      const file = path.join(tmpDir, 'notes.md');
+      fs.writeFileSync(file, '# notes');
+
+      await runWatch([file, '--to', 'de', '--dry-run']);
+
+      expect(dryRunReport()).toContain(`Output directory: ${tmpDir}`);
+    });
+
+    it('falls back to the current directory for a bare filename', async () => {
+      // No '/' to strip, so the derived parent is empty and defaults to '.'
+      await runWatch(['notes.md', '--to', 'de', '--dry-run']);
+
+      expect(dryRunReport()).toContain('Output directory: .');
+    });
+
+    it('prefers an explicit --output over either default', async () => {
+      await runWatch([
+        tmpDir,
+        '--to',
+        'de',
+        '--output',
+        '/tmp/elsewhere',
+        '--dry-run',
+      ]);
+
+      expect(dryRunReport()).toContain('Output directory: /tmp/elsewhere');
+    });
+  });
+
+  describe('--dry-run optional lines', () => {
+    it('omits the optional lines when their flags are absent', async () => {
+      await runWatch([tmpDir, '--to', 'de', '--dry-run']);
+      const report = dryRunReport();
+
+      expect(report).not.toContain('Source language:');
+      expect(report).not.toContain('Git-staged:');
+      expect(report).not.toContain('Debounce:');
+      expect(report).not.toContain('Auto-commit:');
+      expect(report).not.toContain('File pattern:');
+    });
+
+    it('reports each optional line when its flag is given', async () => {
+      await runWatch([
+        tmpDir,
+        '--to',
+        'de',
+        '--from',
+        'en',
+        '--git-staged',
+        '--debounce',
+        '750',
+        '--auto-commit',
+        '--pattern',
+        '**/*.md',
+        '--dry-run',
+      ]);
+      const report = dryRunReport();
+
+      expect(report).toContain('Source language: en');
+      expect(report).toContain('Git-staged: only watching staged files');
+      expect(report).toContain('Debounce: 750ms');
+      expect(report).toContain('Auto-commit: enabled');
+      expect(report).toContain('File pattern: **/*.md');
+    });
+
+    it('lists every requested target language', async () => {
+      await runWatch([tmpDir, '--to', 'de, fr ,es', '--dry-run']);
+
+      expect(dryRunReport()).toContain('Target language(s): de, fr, es');
+    });
+  });
+
+  describe('starting the watcher', () => {
+    it('passes the resolved options through to WatchCommand.watch', async () => {
+      await runWatch([tmpDir, '--to', 'de', '--from', 'en']);
+
+      expect(mockCreateWatchCommand).toHaveBeenCalledTimes(1);
+      expect(watch).toHaveBeenCalledWith(
+        tmpDir,
+        expect.objectContaining({ to: 'de', from: 'en' })
+      );
+    });
+
+    it('routes a watcher failure to handleError', async () => {
+      watch.mockRejectedValue(new Error('watcher exploded'));
+
+      await expect(runWatch([tmpDir, '--to', 'de'])).rejects.toThrow(
+        'watcher exploded'
+      );
+
+      expect(handleError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'watcher exploded' })
+      );
+    });
+  });
+});
diff --git a/tests/unit/register-commands-group1.test.ts b/tests/unit/register-commands-group1.test.ts
index a6489816..dc0fe8b1 100644
--- a/tests/unit/register-commands-group1.test.ts
+++ b/tests/unit/register-commands-group1.test.ts
@@ -4,6 +4,7 @@
  */
 
 import { Command } from 'commander';
+import { Readable } from 'stream';
 
 // ── Mock chalk ──────────────────────────────────────────────────────────────
 jest.mock('chalk', () => {
@@ -527,6 +528,112 @@ describe('registerAuth', () => {
     expect(handleError).toHaveBeenCalledWith(setKeyError);
   });
 
+  it('auth set-key --no-verify should save without contacting the API', async () => {
+    await loadAndRegister();
+    await program.parseAsync([
+      'node',
+      'test',
+      'auth',
+      'set-key',
+      'my-api-key-12345',
+      '--no-verify',
+    ]);
+
+    expect(mockSetKey).toHaveBeenCalledWith('my-api-key-12345', {
+      verify: false,
+    });
+    expect(mockLogger.success).toHaveBeenCalledWith(
+      expect.stringContaining('saved without validation')
+    );
+  });
+
+  describe('auth set-key reading from stdin', () => {
+    /** Swap process.stdin for a readable carrying `chunks`. */
+    async function withStdin(
+      chunks: Buffer[],
+      isTTY: boolean,
+      run: () => Promise<void>
+    ): Promise<void> {
+      const original = Object.getOwnPropertyDescriptor(process, 'stdin')!;
+      const replacement = Readable.from(chunks);
+      Object.defineProperty(replacement, 'isTTY', {
+        value: isTTY,
+        configurable: true,
+      });
+      Object.defineProperty(process, 'stdin', {
+        value: replacement,
+        configurable: true,
+      });
+      try {
+        await run();
+      } finally {
+        Object.defineProperty(process, 'stdin', original);
+      }
+    }
+
+    it('should read the key from stdin and trim it', async () => {
+      await loadAndRegister();
+
+      await withStdin([Buffer.from('  piped-api-key\n')], false, async () => {
+        await program.parseAsync([
+          'node',
+          'test',
+          'auth',
+          'set-key',
+          '--from-stdin',
+        ]);
+      });
+
+      expect(mockSetKey).toHaveBeenCalledWith('piped-api-key', {
+        verify: true,
+      });
+    });
+
+    it('should read from stdin when no key is given and stdin is not a terminal', async () => {
+      await loadAndRegister();
+
+      await withStdin([Buffer.from('implicit-key')], false, async () => {
+        await program.parseAsync(['node', 'test', 'auth', 'set-key']);
+      });
+
+      expect(mockSetKey).toHaveBeenCalledWith('implicit-key', { verify: true });
+    });
+
+    it('should refuse rather than block when no key is given on a terminal', async () => {
+      await loadAndRegister();
+
+      await withStdin([], true, async () => {
+        await expect(
+          program.parseAsync(['node', 'test', 'auth', 'set-key'])
+        ).rejects.toThrow('API key required');
+      });
+
+      expect(mockSetKey).not.toHaveBeenCalled();
+    });
+
+    it('should refuse input larger than 128KB', async () => {
+      await loadAndRegister();
+
+      await withStdin(
+        [Buffer.alloc(64 * 1024, 'a'), Buffer.alloc(65 * 1024, 'b')],
+        false,
+        async () => {
+          await expect(
+            program.parseAsync([
+              'node',
+              'test',
+              'auth',
+              'set-key',
+              '--from-stdin',
+            ])
+          ).rejects.toThrow('Input exceeds maximum size of 128KB');
+        }
+      );
+
+      expect(mockSetKey).not.toHaveBeenCalled();
+    });
+  });
+
   it('auth clear should remove key and report success', async () => {
     await loadAndRegister();
     await program.parseAsync(['node', 'test', 'auth', 'clear']);

From fb0a09cf7b8d69c459bcc59350647b5c17c37319 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 15:35:09 -0400
Subject: [PATCH 101/256] docs(examples): renumber examples into their
 functional groups
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Examples 29 and 33 to 37 were appended as they were written rather than
inserted into the group they belong to, so the numbering no longer matched the
grouping that run-all.sh and examples/README.md already used. write-extended
-languages and correct sat twelve files away from write, style-rules-crud from
style-rules, and tm-list bisected the sync block.

Numbering now follows the existing section order -- Translate, Write, Voice,
Resources, Workflow, Configuration, Information, Administration, Getting
Started, Advanced -- so the run order and the filenames agree. 01 to 13 are
unchanged; 24 files move. 26 and 27 are left free for the sync resolve and
audit examples.

The number is also dropped from each script's header comment and banner echo,
where it duplicated the filename. Those banners were the reason renumbering
previously meant a stale "Example 36" printing from a file named 14; with the
number in one place only, a future reorder is renames alone. The internal
sub-example comments in 03-batch-processing.sh are its own section numbering
and are left alone, as is the fast-mode skip message, which now names the
examples it skips instead of their numbers.

Recorded as renames. Every file named in run-all.sh exists and every example
is named in run-all.sh, both checked; all 38 scripts pass bash -n and keep
their executable bit. CHANGELOG references are left pointing at the old paths,
being a record of what the files were called at the time.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                                     |  8 +-
 docs/SYNC.md                                  |  4 +-
 examples/01-basic-translation.sh              |  4 +-
 examples/02-file-translation.sh               |  4 +-
 examples/03-batch-processing.sh               |  4 +-
 examples/04-context-aware-translation.sh      |  4 +-
 examples/05-document-translation.sh           |  4 +-
 examples/06-document-format-conversion.sh     |  4 +-
 examples/07-structured-file-translation.sh    |  4 +-
 examples/08-model-type-selection.sh           |  4 +-
 examples/09-xml-tag-handling.sh               |  4 +-
 examples/10-custom-instructions.sh            |  4 +-
 examples/11-table-output.sh                   |  4 +-
 examples/12-cost-transparency.sh              |  4 +-
 examples/13-write.sh                          |  4 +-
 ...ages.sh => 14-write-extended-languages.sh} |  4 +-
 examples/{37-correct.sh => 15-correct.sh}     |  4 +-
 examples/{14-voice.sh => 16-voice.sh}         |  4 +-
 .../{15-glossaries.sh => 17-glossaries.sh}    |  4 +-
 examples/{33-tm-list.sh => 18-tm-list.sh}     |  4 +-
 .../{16-watch-mode.sh => 19-watch-mode.sh}    |  4 +-
 examples/{17-git-hooks.sh => 20-git-hooks.sh} |  4 +-
 ...-integration.sh => 21-cicd-integration.sh} |  4 +-
 .../{30-sync-basic.sh => 22-sync-basic.sh}    |  4 +-
 examples/{31-sync-ci.sh => 23-sync-ci.sh}     |  4 +-
 ...lidation.sh => 24-sync-live-validation.sh} |  4 +-
 ...-laravel-php.sh => 25-sync-laravel-php.sh} |  4 +-
 ...9-configuration.sh => 28-configuration.sh} |  4 +-
 ...fig-files.sh => 29-custom-config-files.sh} |  4 +-
 examples/{21-cache.sh => 30-cache.sh}         |  4 +-
 .../{22-style-rules.sh => 31-style-rules.sh}  |  4 +-
 ...e-rules-crud.sh => 32-style-rules-crud.sh} |  4 +-
 ...e-monitoring.sh => 33-usage-monitoring.sh} |  4 +-
 examples/{24-languages.sh => 34-languages.sh} |  4 +-
 examples/{25-detect.sh => 35-detect.sh}       |  4 +-
 .../{26-completion.sh => 36-completion.sh}    |  4 +-
 examples/{27-admin.sh => 37-admin.sh}         |  4 +-
 examples/{28-init.sh => 38-init.sh}           |  4 +-
 ...-translate.sh => 39-advanced-translate.sh} |  4 +-
 examples/README.md                            | 48 +++++-----
 examples/run-all.sh                           | 92 +++++++++----------
 41 files changed, 150 insertions(+), 150 deletions(-)
 rename examples/{36-write-extended-languages.sh => 14-write-extended-languages.sh} (92%)
 rename examples/{37-correct.sh => 15-correct.sh} (90%)
 rename examples/{14-voice.sh => 16-voice.sh} (97%)
 rename examples/{15-glossaries.sh => 17-glossaries.sh} (99%)
 rename examples/{33-tm-list.sh => 18-tm-list.sh} (89%)
 rename examples/{16-watch-mode.sh => 19-watch-mode.sh} (98%)
 rename examples/{17-git-hooks.sh => 20-git-hooks.sh} (98%)
 rename examples/{18-cicd-integration.sh => 21-cicd-integration.sh} (98%)
 rename examples/{30-sync-basic.sh => 22-sync-basic.sh} (98%)
 rename examples/{31-sync-ci.sh => 23-sync-ci.sh} (97%)
 rename examples/{32-sync-live-validation.sh => 24-sync-live-validation.sh} (99%)
 rename examples/{34-sync-laravel-php.sh => 25-sync-laravel-php.sh} (97%)
 rename examples/{19-configuration.sh => 28-configuration.sh} (97%)
 rename examples/{20-custom-config-files.sh => 29-custom-config-files.sh} (97%)
 rename examples/{21-cache.sh => 30-cache.sh} (97%)
 rename examples/{22-style-rules.sh => 31-style-rules.sh} (96%)
 rename examples/{35-style-rules-crud.sh => 32-style-rules-crud.sh} (96%)
 rename examples/{23-usage-monitoring.sh => 33-usage-monitoring.sh} (95%)
 rename examples/{24-languages.sh => 34-languages.sh} (97%)
 rename examples/{25-detect.sh => 35-detect.sh} (94%)
 rename examples/{26-completion.sh => 36-completion.sh} (93%)
 rename examples/{27-admin.sh => 37-admin.sh} (97%)
 rename examples/{28-init.sh => 38-init.sh} (96%)
 rename examples/{29-advanced-translate.sh => 39-advanced-translate.sh} (98%)

diff --git a/README.md b/README.md
index 60edc71d..3b39fce0 100644
--- a/README.md
+++ b/README.md
@@ -874,7 +874,7 @@ Pattern: *.md
 Press Ctrl+C to stop
 ```
 
-See [examples/16-watch-mode.sh](./examples/16-watch-mode.sh) for a complete watch mode example with multiple scenarios.
+See [examples/19-watch-mode.sh](./examples/19-watch-mode.sh) for a complete watch mode example with multiple scenarios.
 
 ### Git Hooks
 
@@ -927,7 +927,7 @@ Git Hooks Status:
 
 **Note:** The hooks are generated with placeholder validation logic. You can customize them based on your project's translation workflow by editing the hook files directly at `.git/hooks/pre-commit` or `.git/hooks/pre-push`.
 
-See [examples/17-git-hooks.sh](./examples/17-git-hooks.sh) for a complete git hooks example demonstrating installation, usage, and management.
+See [examples/20-git-hooks.sh](./examples/20-git-hooks.sh) for a complete git hooks example demonstrating installation, usage, and management.
 
 ### Configuration
 
@@ -983,7 +983,7 @@ deepl usage
 
 **Note:** Usage statistics help you track your DeepL API character quota and avoid exceeding limits.
 
-See [examples/23-usage-monitoring.sh](./examples/23-usage-monitoring.sh) for a complete usage monitoring example.
+See [examples/33-usage-monitoring.sh](./examples/33-usage-monitoring.sh) for a complete usage monitoring example.
 
 **Cost Transparency:**
 
@@ -1073,7 +1073,7 @@ deepl languages
 
 **The API decides what exists.** `GET /v3/languages` is authoritative; the bundled list is a generated snapshot of it (`npm run generate:languages`) so that listing and validating languages works offline. Because a snapshot can lag the API, a well-formed language code it does not list is passed to the API rather than rejected locally — that is why `deepl translate --to de-CH` works even if your copy of the list predates Swiss German. Input that is not shaped like a language tag is still rejected immediately.
 
-See [examples/24-languages.sh](./examples/24-languages.sh) for a complete example.
+See [examples/34-languages.sh](./examples/34-languages.sh) for a complete example.
 
 #### Configure Defaults
 
diff --git a/docs/SYNC.md b/docs/SYNC.md
index d9b91adf..9d4b6886 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -977,6 +977,6 @@ See [API.md Exit Codes appendix](API.md#exit-codes) for detailed per-code descri
 ## Further Reading
 
 - [API Reference](./API.md#sync) -- complete command and flag reference
-- [Example: Basic Sync](../examples/30-sync-basic.sh) -- walkthrough of a typical sync workflow
-- [Example: CI/CD Sync](../examples/31-sync-ci.sh) -- using sync in automated pipelines
+- [Example: Basic Sync](../examples/22-sync-basic.sh) -- walkthrough of a typical sync workflow
+- [Example: CI/CD Sync](../examples/23-sync-ci.sh) -- using sync in automated pipelines
 - [CHANGELOG](../CHANGELOG.md) -- release history
diff --git a/examples/01-basic-translation.sh b/examples/01-basic-translation.sh
index c1507e98..5eeddc46 100755
--- a/examples/01-basic-translation.sh
+++ b/examples/01-basic-translation.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 1: Basic Translation
+# Basic Translation
 # Demonstrates simple text translation with various options
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 1: Basic Translation ==="
+echo "=== DeepL CLI: Basic Translation ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/02-file-translation.sh b/examples/02-file-translation.sh
index b4552d14..75180fae 100755
--- a/examples/02-file-translation.sh
+++ b/examples/02-file-translation.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 2: File Translation & Caching
+# File Translation & Caching
 # Demonstrates translating files with format preservation and smart caching
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 2: File Translation ==="
+echo "=== DeepL CLI: File Translation ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/03-batch-processing.sh b/examples/03-batch-processing.sh
index 71e54ddc..cfedc39f 100755
--- a/examples/03-batch-processing.sh
+++ b/examples/03-batch-processing.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 3: Batch Processing
+# Batch Processing
 # Demonstrates processing multiple files efficiently
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 3: Batch Processing ==="
+echo "=== DeepL CLI: Batch Processing ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/04-context-aware-translation.sh b/examples/04-context-aware-translation.sh
index 8cf02ee3..292b258c 100755
--- a/examples/04-context-aware-translation.sh
+++ b/examples/04-context-aware-translation.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 4: Context-Aware Translation
+# Context-Aware Translation
 # Demonstrates using context to improve translation quality
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 4: Context-Aware Translation ==="
+echo "=== DeepL CLI: Context-Aware Translation ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/05-document-translation.sh b/examples/05-document-translation.sh
index 7239d22c..6d56a5c7 100755
--- a/examples/05-document-translation.sh
+++ b/examples/05-document-translation.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 5: Document Translation
+# Document Translation
 # Demonstrates translating complete documents while preserving formatting
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 5: Document Translation ==="
+echo "=== DeepL CLI: Document Translation ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/06-document-format-conversion.sh b/examples/06-document-format-conversion.sh
index 53b47ccc..5ced25e5 100755
--- a/examples/06-document-format-conversion.sh
+++ b/examples/06-document-format-conversion.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 6: Document Format Conversion
+# Document Format Conversion
 # Demonstrates the --output-format flag for document translation
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 6: Document Format Conversion ==="
+echo "=== DeepL CLI: Document Format Conversion ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/07-structured-file-translation.sh b/examples/07-structured-file-translation.sh
index ed0aa295..812e1aa5 100755
--- a/examples/07-structured-file-translation.sh
+++ b/examples/07-structured-file-translation.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 7: Structured File Translation (JSON/YAML)
+# Structured File Translation (JSON/YAML)
 # Demonstrates translating i18n locale files while preserving structure
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 7: Structured File Translation ==="
+echo "=== DeepL CLI: Structured File Translation ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/08-model-type-selection.sh b/examples/08-model-type-selection.sh
index 90f2230e..aa8431a0 100755
--- a/examples/08-model-type-selection.sh
+++ b/examples/08-model-type-selection.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 8: Model Type Selection
+# Model Type Selection
 # Demonstrates using different model types for quality vs. speed trade-offs
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 8: Model Type Selection ==="
+echo "=== DeepL CLI: Model Type Selection ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/09-xml-tag-handling.sh b/examples/09-xml-tag-handling.sh
index 546a6e69..f4aba09b 100755
--- a/examples/09-xml-tag-handling.sh
+++ b/examples/09-xml-tag-handling.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 9: Advanced XML Tag Handling
+# Advanced XML Tag Handling
 # Demonstrates fine-tuned control over XML/HTML translation with tag handling parameters
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 9: Advanced XML Tag Handling ==="
+echo "=== DeepL CLI: Advanced XML Tag Handling ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/10-custom-instructions.sh b/examples/10-custom-instructions.sh
index 4d179c79..dd7bfabc 100755
--- a/examples/10-custom-instructions.sh
+++ b/examples/10-custom-instructions.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 10: Custom Instructions
+# Custom Instructions
 # Use custom instructions to guide DeepL translations with specific rules
 
 set -e
 
-echo "=== DeepL CLI Example 10: Custom Instructions ==="
+echo "=== DeepL CLI: Custom Instructions ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/11-table-output.sh b/examples/11-table-output.sh
index e6189281..0fcda2a4 100755
--- a/examples/11-table-output.sh
+++ b/examples/11-table-output.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 11: Table Output Format
+# Table Output Format
 # Demonstrates structured table output for comparing translations across multiple languages
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 11: Table Output Format ==="
+echo "=== DeepL CLI: Table Output Format ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/12-cost-transparency.sh b/examples/12-cost-transparency.sh
index 3e1955ed..bd406f93 100755
--- a/examples/12-cost-transparency.sh
+++ b/examples/12-cost-transparency.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 12: Cost Transparency with Billed Characters
+# Cost Transparency with Billed Characters
 # Demonstrates tracking actual billed characters for translation cost analysis
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 12: Cost Transparency ==="
+echo "=== DeepL CLI: Cost Transparency ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/13-write.sh b/examples/13-write.sh
index 16f627a9..ca873cad 100755
--- a/examples/13-write.sh
+++ b/examples/13-write.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 13: DeepL Write API
+# DeepL Write API
 # Demonstrates grammar, style, and tone enhancement
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 13: DeepL Write API ==="
+echo "=== DeepL CLI: DeepL Write API ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/36-write-extended-languages.sh b/examples/14-write-extended-languages.sh
similarity index 92%
rename from examples/36-write-extended-languages.sh
rename to examples/14-write-extended-languages.sh
index a8a1b58c..41ec73dc 100755
--- a/examples/36-write-extended-languages.sh
+++ b/examples/14-write-extended-languages.sh
@@ -1,11 +1,11 @@
 #!/bin/bash
-# Example 36: Write — extended language coverage
+# Write — extended language coverage
 # Demonstrates ja/ko/zh/zh-hans target languages and
 # tone / style applied to ES/IT/FR/PT variants.
 
 set -e
 
-echo "=== DeepL CLI Example 36: Write — Extended Language Coverage ==="
+echo "=== DeepL CLI: Write — Extended Language Coverage ==="
 echo
 
 if ! deepl auth show &>/dev/null; then
diff --git a/examples/37-correct.sh b/examples/15-correct.sh
similarity index 90%
rename from examples/37-correct.sh
rename to examples/15-correct.sh
index 93fb8acb..048ffa38 100755
--- a/examples/37-correct.sh
+++ b/examples/15-correct.sh
@@ -1,11 +1,11 @@
 #!/bin/bash
-# Example 37: Correct — spelling and grammar correction without rewording
+# Correct — spelling and grammar correction without rewording
 # Demonstrates the correct command: basic use, alias, check mode,
 # fix with backup, diff view, and JSON output.
 
 set -e
 
-echo "=== DeepL CLI Example 37: Correct — Spelling and Grammar ==="
+echo "=== DeepL CLI: Correct — Spelling and Grammar ==="
 echo
 
 if ! deepl auth show &>/dev/null; then
diff --git a/examples/14-voice.sh b/examples/16-voice.sh
similarity index 97%
rename from examples/14-voice.sh
rename to examples/16-voice.sh
index fafbb856..29b88932 100755
--- a/examples/14-voice.sh
+++ b/examples/16-voice.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 14: Voice (Real-Time Speech Translation)
+# Voice (Real-Time Speech Translation)
 # Translate audio files using the DeepL Voice API with WebSocket streaming
 
 set -e
 
-echo "=== DeepL CLI Example 14: Voice ==="
+echo "=== DeepL CLI: Voice ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/15-glossaries.sh b/examples/17-glossaries.sh
similarity index 99%
rename from examples/15-glossaries.sh
rename to examples/17-glossaries.sh
index 94f9600d..2f6659e7 100755
--- a/examples/15-glossaries.sh
+++ b/examples/17-glossaries.sh
@@ -1,11 +1,11 @@
 #!/bin/bash
-# Example 15: Glossaries (v3 API)
+# Glossaries (v3 API)
 # Demonstrates managing glossaries for consistent terminology
 # v3 API supports both single-target and multilingual glossaries
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 15: Glossaries (v3 API) ==="
+echo "=== DeepL CLI: Glossaries (v3 API) ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/33-tm-list.sh b/examples/18-tm-list.sh
similarity index 89%
rename from examples/33-tm-list.sh
rename to examples/18-tm-list.sh
index 67079587..a864b929 100755
--- a/examples/33-tm-list.sh
+++ b/examples/18-tm-list.sh
@@ -1,5 +1,5 @@
 #!/bin/bash
-# Example 33: Translation Memory listing
+# Translation Memory listing
 # Lists all translation memories on the current DeepL account.
 # TM files are authored and uploaded via the DeepL web UI; this CLI
 # surfaces them so you can copy a UUID or name into a translate or
@@ -7,7 +7,7 @@
 
 set -e
 
-echo "=== DeepL CLI Example 33: deepl tm list ==="
+echo "=== DeepL CLI: deepl tm list ==="
 echo
 
 if ! deepl auth show &>/dev/null; then
diff --git a/examples/16-watch-mode.sh b/examples/19-watch-mode.sh
similarity index 98%
rename from examples/16-watch-mode.sh
rename to examples/19-watch-mode.sh
index 069d65f9..10f98086 100755
--- a/examples/16-watch-mode.sh
+++ b/examples/19-watch-mode.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 16: Watch Mode
+# Watch Mode
 # Demonstrates real-time file monitoring and auto-translation
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 16: Watch Mode ==="
+echo "=== DeepL CLI: Watch Mode ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/17-git-hooks.sh b/examples/20-git-hooks.sh
similarity index 98%
rename from examples/17-git-hooks.sh
rename to examples/20-git-hooks.sh
index e9f6e9be..f776eebb 100755
--- a/examples/17-git-hooks.sh
+++ b/examples/20-git-hooks.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 17: Git Hooks Integration
+# Git Hooks Integration
 # Demonstrates automating translation validation in git workflow
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 17: Git Hooks Integration ==="
+echo "=== DeepL CLI: Git Hooks Integration ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/18-cicd-integration.sh b/examples/21-cicd-integration.sh
similarity index 98%
rename from examples/18-cicd-integration.sh
rename to examples/21-cicd-integration.sh
index 17c7b61f..5865ec4d 100755
--- a/examples/18-cicd-integration.sh
+++ b/examples/21-cicd-integration.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 18: CI/CD Integration
+# CI/CD Integration
 # Demonstrates using DeepL CLI in automated workflows
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 18: CI/CD Integration ==="
+echo "=== DeepL CLI: CI/CD Integration ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/30-sync-basic.sh b/examples/22-sync-basic.sh
similarity index 98%
rename from examples/30-sync-basic.sh
rename to examples/22-sync-basic.sh
index a23316e1..f90a0452 100755
--- a/examples/30-sync-basic.sh
+++ b/examples/22-sync-basic.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 30: Sync — Basic Usage
+# Sync — Basic Usage
 # Demonstrates scanning, diffing, and syncing i18n locale files
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 30: Sync — Basic Usage ==="
+echo "=== DeepL CLI: Sync — Basic Usage ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/31-sync-ci.sh b/examples/23-sync-ci.sh
similarity index 97%
rename from examples/31-sync-ci.sh
rename to examples/23-sync-ci.sh
index 746a672b..1025292f 100755
--- a/examples/31-sync-ci.sh
+++ b/examples/23-sync-ci.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 31: Sync — CI/CD Integration
+# Sync — CI/CD Integration
 # Demonstrates using deepl sync in automated pipelines
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 31: Sync — CI/CD Integration ==="
+echo "=== DeepL CLI: Sync — CI/CD Integration ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/32-sync-live-validation.sh b/examples/24-sync-live-validation.sh
similarity index 99%
rename from examples/32-sync-live-validation.sh
rename to examples/24-sync-live-validation.sh
index c020f878..9c0aa498 100755
--- a/examples/32-sync-live-validation.sh
+++ b/examples/24-sync-live-validation.sh
@@ -1,12 +1,12 @@
 #!/bin/bash
-# Example 32: Sync — Live API Validation
+# Sync — Live API Validation
 # Comprehensive end-to-end validation of all sync features against the real DeepL API.
 # Exercises: multi-format, placeholders, plurals, incremental sync, new locales,
 # frozen mode, status, validate, force, and context extraction.
 
 set -euo pipefail
 
-echo "=== DeepL CLI Example 32: Sync — Live API Validation ==="
+echo "=== DeepL CLI: Sync — Live API Validation ==="
 echo
 
 # Check API key
diff --git a/examples/34-sync-laravel-php.sh b/examples/25-sync-laravel-php.sh
similarity index 97%
rename from examples/34-sync-laravel-php.sh
rename to examples/25-sync-laravel-php.sh
index b9507e67..ac1fd4fc 100755
--- a/examples/34-sync-laravel-php.sh
+++ b/examples/25-sync-laravel-php.sh
@@ -1,11 +1,11 @@
 #!/bin/bash
-# Example 34: Sync — Laravel PHP arrays
+# Sync — Laravel PHP arrays
 # Demonstrates the laravel_php format parser: AST allowlist, span-surgical
 # reconstruct, pipe-pluralization warning gate, and sync.limits caps.
 
 set -e
 
-echo "=== DeepL CLI Example 34: Sync — Laravel PHP arrays ==="
+echo "=== DeepL CLI: Sync — Laravel PHP arrays ==="
 echo
 
 if ! deepl auth show &>/dev/null; then
diff --git a/examples/19-configuration.sh b/examples/28-configuration.sh
similarity index 97%
rename from examples/19-configuration.sh
rename to examples/28-configuration.sh
index 65bb8086..21ab9060 100755
--- a/examples/19-configuration.sh
+++ b/examples/28-configuration.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 19: Configuration
+# Configuration
 # Demonstrates configuration management
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 19: Configuration ==="
+echo "=== DeepL CLI: Configuration ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/20-custom-config-files.sh b/examples/29-custom-config-files.sh
similarity index 97%
rename from examples/20-custom-config-files.sh
rename to examples/29-custom-config-files.sh
index bf5c618d..677dce99 100755
--- a/examples/20-custom-config-files.sh
+++ b/examples/29-custom-config-files.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 20: Custom Configuration Files
+# Custom Configuration Files
 # Demonstrates using --config flag for multiple configurations
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 20: Custom Configuration Files ==="
+echo "=== DeepL CLI: Custom Configuration Files ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/21-cache.sh b/examples/30-cache.sh
similarity index 97%
rename from examples/21-cache.sh
rename to examples/30-cache.sh
index 4156ecd9..ee107359 100755
--- a/examples/21-cache.sh
+++ b/examples/30-cache.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 21: Cache Management
+# Cache Management
 # Demonstrates working with the translation cache
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 21: Cache Management ==="
+echo "=== DeepL CLI: Cache Management ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/22-style-rules.sh b/examples/31-style-rules.sh
similarity index 96%
rename from examples/22-style-rules.sh
rename to examples/31-style-rules.sh
index e4416200..c080d12b 100755
--- a/examples/22-style-rules.sh
+++ b/examples/31-style-rules.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 22: Style Rules
+# Style Rules
 # List and use DeepL style rules for consistent translation styles (Pro API only)
 
 set -e
 
-echo "=== DeepL CLI Example 22: Style Rules ==="
+echo "=== DeepL CLI: Style Rules ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/35-style-rules-crud.sh b/examples/32-style-rules-crud.sh
similarity index 96%
rename from examples/35-style-rules-crud.sh
rename to examples/32-style-rules-crud.sh
index fc4d6e07..7c4f7179 100755
--- a/examples/35-style-rules-crud.sh
+++ b/examples/32-style-rules-crud.sh
@@ -1,11 +1,11 @@
 #!/bin/bash
-# Example 35: Style Rules CRUD
+# Style Rules CRUD
 # End-to-end walkthrough of creating, updating, and deleting a style rule,
 # including custom instruction management. Pro API only.
 
 set -e
 
-echo "=== DeepL CLI Example 35: Style Rules CRUD ==="
+echo "=== DeepL CLI: Style Rules CRUD ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/23-usage-monitoring.sh b/examples/33-usage-monitoring.sh
similarity index 95%
rename from examples/23-usage-monitoring.sh
rename to examples/33-usage-monitoring.sh
index 47504221..6d00085d 100755
--- a/examples/23-usage-monitoring.sh
+++ b/examples/33-usage-monitoring.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 23: API Usage Monitoring
+# API Usage Monitoring
 # Demonstrates checking API character usage and quota
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 23: API Usage Monitoring ==="
+echo "=== DeepL CLI: API Usage Monitoring ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/24-languages.sh b/examples/34-languages.sh
similarity index 97%
rename from examples/24-languages.sh
rename to examples/34-languages.sh
index 3446d608..8c72214a 100755
--- a/examples/24-languages.sh
+++ b/examples/34-languages.sh
@@ -1,11 +1,11 @@
 #!/bin/bash
-# Example 24: List Supported Languages
+# List Supported Languages
 # Demonstrates listing source and target languages supported by DeepL,
 # including extended languages and graceful degradation without an API key
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 24: Supported Languages ==="
+echo "=== DeepL CLI: Supported Languages ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/25-detect.sh b/examples/35-detect.sh
similarity index 94%
rename from examples/25-detect.sh
rename to examples/35-detect.sh
index e15e2e49..d4790a81 100755
--- a/examples/25-detect.sh
+++ b/examples/35-detect.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 25: Language Detection
+# Language Detection
 # Demonstrates detecting the language of text using the DeepL API
 
 set -e
 
-echo "=== DeepL CLI Example 25: Language Detection ==="
+echo "=== DeepL CLI: Language Detection ==="
 echo
 
 if ! deepl auth show &>/dev/null; then
diff --git a/examples/26-completion.sh b/examples/36-completion.sh
similarity index 93%
rename from examples/26-completion.sh
rename to examples/36-completion.sh
index daabe505..577e2aa1 100755
--- a/examples/26-completion.sh
+++ b/examples/36-completion.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 26: Shell Completions
+# Shell Completions
 # Demonstrates generating shell completion scripts for bash, zsh, and fish
 
 set -e
 
-echo "=== DeepL CLI Example 26: Shell Completions ==="
+echo "=== DeepL CLI: Shell Completions ==="
 echo
 
 echo "1. Generate bash completion (preview):"
diff --git a/examples/27-admin.sh b/examples/37-admin.sh
similarity index 97%
rename from examples/27-admin.sh
rename to examples/37-admin.sh
index 6b21a3d1..9fa894b0 100755
--- a/examples/27-admin.sh
+++ b/examples/37-admin.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 27: Admin API
+# Admin API
 # Manage API keys and view organization usage analytics (requires admin API key)
 
 set -e
 
-echo "=== DeepL CLI Example 27: Admin API ==="
+echo "=== DeepL CLI: Admin API ==="
 echo
 echo "Note: Admin API requires an admin-level API key."
 echo "These commands manage developer keys and usage analytics for your organization."
diff --git a/examples/28-init.sh b/examples/38-init.sh
similarity index 96%
rename from examples/28-init.sh
rename to examples/38-init.sh
index 05097707..7ef4b26b 100755
--- a/examples/28-init.sh
+++ b/examples/38-init.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 28: Setup Wizard (deepl init)
+# Setup Wizard (deepl init)
 # Demonstrates first-time interactive setup
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 28: Setup Wizard ==="
+echo "=== DeepL CLI: Setup Wizard ==="
 echo
 
 # Note: deepl init is an interactive wizard that requires terminal input.
diff --git a/examples/29-advanced-translate.sh b/examples/39-advanced-translate.sh
similarity index 98%
rename from examples/29-advanced-translate.sh
rename to examples/39-advanced-translate.sh
index 4054c948..8c2d0402 100755
--- a/examples/29-advanced-translate.sh
+++ b/examples/39-advanced-translate.sh
@@ -1,10 +1,10 @@
 #!/bin/bash
-# Example 29: Advanced Translation Options
+# Advanced Translation Options
 # Demonstrates tag handling versions, beta languages, custom API URLs, and minification
 
 set -e  # Exit on error
 
-echo "=== DeepL CLI Example 29: Advanced Translation Options ==="
+echo "=== DeepL CLI: Advanced Translation Options ==="
 echo
 
 # Check if API key is configured
diff --git a/examples/README.md b/examples/README.md
index 3840266c..7291e1a7 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -22,53 +22,53 @@ This directory contains practical, real-world examples of using the DeepL CLI.
 
 **Write:**
 - [Writing Enhancement](./13-write.sh) - Using DeepL Write API for grammar, style, and tone improvement
-- [Write — Extended Languages](./36-write-extended-languages.sh) - JA/KO/ZH targets and tone/style on ES/IT/FR/PT variants
-- [Correct](./37-correct.sh) - Spelling and grammar correction without rewording (`deepl correct`, alias `c`)
+- [Write — Extended Languages](./14-write-extended-languages.sh) - JA/KO/ZH targets and tone/style on ES/IT/FR/PT variants
+- [Correct](./15-correct.sh) - Spelling and grammar correction without rewording (`deepl correct`, alias `c`)
 
 **Voice:**
-- [Voice Translation](./14-voice.sh) - Real-time speech translation via the Voice API
+- [Voice Translation](./16-voice.sh) - Real-time speech translation via the Voice API
 
 ### Resources
 
-- [Glossaries](./15-glossaries.sh) - Managing glossaries for consistent terminology
-- [Translation Memory Listing](./33-tm-list.sh) — List translation memories on your account
+- [Glossaries](./17-glossaries.sh) - Managing glossaries for consistent terminology
+- [Translation Memory Listing](./18-tm-list.sh) — List translation memories on your account
 
 ### Workflow
 
-- [Watch Mode](./16-watch-mode.sh) - Real-time file monitoring and auto-translation
-- [Git Hooks Integration](./17-git-hooks.sh) - Automating translation validation in git workflow
-- [CI/CD Integration](./18-cicd-integration.sh) - Using DeepL CLI in automated workflows
-- [Sync — Basic Usage](./30-sync-basic.sh) - Scanning, diffing, and syncing i18n locale files
-- [Sync — CI/CD Integration](./31-sync-ci.sh) - Using deepl sync in automated pipelines
-- [Sync — Live Validation](./32-sync-live-validation.sh) - Comprehensive end-to-end validation of all sync features
-- [Sync — Laravel PHP arrays](./34-sync-laravel-php.sh) - `laravel_php` format parser: AST allowlist, span-surgical reconstruct, pipe-pluralization warning gate, `sync.limits` caps
+- [Watch Mode](./19-watch-mode.sh) - Real-time file monitoring and auto-translation
+- [Git Hooks Integration](./20-git-hooks.sh) - Automating translation validation in git workflow
+- [CI/CD Integration](./21-cicd-integration.sh) - Using DeepL CLI in automated workflows
+- [Sync — Basic Usage](./22-sync-basic.sh) - Scanning, diffing, and syncing i18n locale files
+- [Sync — CI/CD Integration](./23-sync-ci.sh) - Using deepl sync in automated pipelines
+- [Sync — Live Validation](./24-sync-live-validation.sh) - Comprehensive end-to-end validation of all sync features
+- [Sync — Laravel PHP arrays](./25-sync-laravel-php.sh) - `laravel_php` format parser: AST allowlist, span-surgical reconstruct, pipe-pluralization warning gate, `sync.limits` caps
 
 ### Configuration
 
-- [Configuration](./19-configuration.sh) - Setting up and managing configuration
-- [Custom Config Files](./20-custom-config-files.sh) - Using multiple configuration files for different projects
-- [Cache Management](./21-cache.sh) - Working with the translation cache
-- [Style Rules](./22-style-rules.sh) - Listing and using pre-configured style rules for consistent translations
-- [Style Rules — CRUD](./35-style-rules-crud.sh) - End-to-end style-rules lifecycle: create, update rules, manage custom instructions, delete
+- [Configuration](./28-configuration.sh) - Setting up and managing configuration
+- [Custom Config Files](./29-custom-config-files.sh) - Using multiple configuration files for different projects
+- [Cache Management](./30-cache.sh) - Working with the translation cache
+- [Style Rules](./31-style-rules.sh) - Listing and using pre-configured style rules for consistent translations
+- [Style Rules — CRUD](./32-style-rules-crud.sh) - End-to-end style-rules lifecycle: create, update rules, manage custom instructions, delete
 
 ### Information
 
-- [Usage Monitoring](./23-usage-monitoring.sh) - Monitoring API character usage and quota
-- [Supported Languages](./24-languages.sh) - Listing source and target languages supported by DeepL
-- [Language Detection](./25-detect.sh) - Detecting the language of text input
-- [Shell Completions](./26-completion.sh) - Setting up bash, zsh, and fish shell completions
+- [Usage Monitoring](./33-usage-monitoring.sh) - Monitoring API character usage and quota
+- [Supported Languages](./34-languages.sh) - Listing source and target languages supported by DeepL
+- [Language Detection](./35-detect.sh) - Detecting the language of text input
+- [Shell Completions](./36-completion.sh) - Setting up bash, zsh, and fish shell completions
 
 ### Administration
 
-- [Admin API](./27-admin.sh) - Managing API keys and viewing organization usage analytics
+- [Admin API](./37-admin.sh) - Managing API keys and viewing organization usage analytics
 
 ### Getting Started
 
-- [Setup Wizard](./28-init.sh) - Interactive first-time setup with `deepl init`
+- [Setup Wizard](./38-init.sh) - Interactive first-time setup with `deepl init`
 
 ### Advanced
 
-- [Advanced Translation](./29-advanced-translate.sh) - Tag handling versions, beta languages, custom API URLs, and document minification
+- [Advanced Translation](./39-advanced-translate.sh) - Tag handling versions, beta languages, custom API URLs, and document minification
 
 ## Prerequisites
 
diff --git a/examples/run-all.sh b/examples/run-all.sh
index 61f706c5..11e4b477 100755
--- a/examples/run-all.sh
+++ b/examples/run-all.sh
@@ -62,43 +62,43 @@ EXAMPLES=(
   "12-cost-transparency.sh"
   # Core Commands - Write
   "13-write.sh"
-  "36-write-extended-languages.sh"
-  "37-correct.sh"
+  "14-write-extended-languages.sh"
+  "15-correct.sh"
   # Core Commands - Voice
-  "14-voice.sh"
+  "16-voice.sh"
   # Resources
-  "15-glossaries.sh"
-  "33-tm-list.sh"
+  "17-glossaries.sh"
+  "18-tm-list.sh"
   # Workflow
-  "16-watch-mode.sh"
-  "17-git-hooks.sh"
-  "18-cicd-integration.sh"
-  "30-sync-basic.sh"
-  "31-sync-ci.sh"
-  "32-sync-live-validation.sh"
-  "34-sync-laravel-php.sh"
+  "19-watch-mode.sh"
+  "20-git-hooks.sh"
+  "21-cicd-integration.sh"
+  "22-sync-basic.sh"
+  "23-sync-ci.sh"
+  "24-sync-live-validation.sh"
+  "25-sync-laravel-php.sh"
   # Configuration
-  "19-configuration.sh"
-  "20-custom-config-files.sh"
-  "21-cache.sh"
-  "22-style-rules.sh"
-  "35-style-rules-crud.sh"
+  "28-configuration.sh"
+  "29-custom-config-files.sh"
+  "30-cache.sh"
+  "31-style-rules.sh"
+  "32-style-rules-crud.sh"
   # Information
-  "23-usage-monitoring.sh"
-  "24-languages.sh"
-  "25-detect.sh"
-  "26-completion.sh"
+  "33-usage-monitoring.sh"
+  "34-languages.sh"
+  "35-detect.sh"
+  "36-completion.sh"
   # Administration
-  "27-admin.sh"
+  "37-admin.sh"
   # Getting Started
-  "28-init.sh"
+  "38-init.sh"
   # Advanced
-  "29-advanced-translate.sh"
+  "39-advanced-translate.sh"
 )
 
 # Skip slow examples in fast mode
 if [ "$FAST_MODE" = true ]; then
-  echo "ℹ️  Fast mode enabled - skipping slow examples (16, 17)"
+  echo "ℹ️  Fast mode enabled - skipping slow examples (watch mode, git hooks)"
   echo
   EXAMPLES=(
     # Core Commands - Translate
@@ -116,35 +116,35 @@ if [ "$FAST_MODE" = true ]; then
     "12-cost-transparency.sh"
     # Core Commands - Write
     "13-write.sh"
-    "36-write-extended-languages.sh"
-    "37-correct.sh"
+    "14-write-extended-languages.sh"
+    "15-correct.sh"
     # Core Commands - Voice
-    "14-voice.sh"
+    "16-voice.sh"
     # Resources
-    "15-glossaries.sh"
+    "17-glossaries.sh"
     # Workflow (watch/hooks skipped)
-    "18-cicd-integration.sh"
-    "30-sync-basic.sh"
-    "31-sync-ci.sh"
-    "32-sync-live-validation.sh"
-    "34-sync-laravel-php.sh"
+    "21-cicd-integration.sh"
+    "22-sync-basic.sh"
+    "23-sync-ci.sh"
+    "24-sync-live-validation.sh"
+    "25-sync-laravel-php.sh"
     # Configuration
-    "19-configuration.sh"
-    "20-custom-config-files.sh"
-    "21-cache.sh"
-    "22-style-rules.sh"
-    "35-style-rules-crud.sh"
+    "28-configuration.sh"
+    "29-custom-config-files.sh"
+    "30-cache.sh"
+    "31-style-rules.sh"
+    "32-style-rules-crud.sh"
     # Information
-    "23-usage-monitoring.sh"
-    "24-languages.sh"
-    "25-detect.sh"
-    "26-completion.sh"
+    "33-usage-monitoring.sh"
+    "34-languages.sh"
+    "35-detect.sh"
+    "36-completion.sh"
     # Administration
-    "27-admin.sh"
+    "37-admin.sh"
     # Getting Started
-    "28-init.sh"
+    "38-init.sh"
     # Advanced
-    "29-advanced-translate.sh"
+    "39-advanced-translate.sh"
   )
 fi
 

From 848eeb216e257a5eabea29f9a5fcedc0a9a4fdb9 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 15:49:04 -0400
Subject: [PATCH 102/256] fix(sync): resolve merge conflicts at the locale, not
 the entry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`deepl sync resolve` kept ours for every conflict in a real .deepl-sync.lock,
discarding the incoming side's newer translations at exit code 0.

isTranslationEntry() treated any object with `source_hash` as a leaf to
compare. Every lockfile entry has one, so the entry-level branch ran and read
`entry.translated_at`, which is never present there -- the timestamp belongs to
each locale inside the entry's `translations` map. That fell through to "kept
ours: neither side had translated_at" and continued, so the recursion just
below, which would have descended to the locale and found the timestamp, was
unreachable. The decision was not tagged `length-heuristic`, so the per-entry
report that exists to make auto-resolve auditable showed nothing amiss.

An object carrying a `translations` map is now a container rather than a leaf,
so the merge descends to the locale where the timestamps are. Decisions are
reported against that path (`greeting.translations.de`) instead of the entry.
Fields both sides agree on no longer produce a decision, which the descent
would otherwise report as scalar conflicts on `source_hash`, `source_locale`
and `updated_at`.

The existing tests could not catch this: their fixtures put `translated_at`
directly on the entry, which SyncLockManager does not write. Added a describe
driving the shape it does write, covering theirs-newer, ours-newer, the absence
of the "neither side" verdict, the absence of agreement-as-conflict, and the
reported key path. Verified red before the change and green after, and
end-to-end against the built binary: ours 2026-02-01 vs theirs 2026-03-01 now
resolves to theirs where it previously resolved to ours.

The permissive `source_hash` test is retained for entries with no
`translations` map, so an entry where only theirs carries a timestamp still
takes theirs wholesale rather than being merged field by field.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                         |  2 +
 src/sync/sync-resolve.ts             | 13 +++-
 tests/unit/sync/sync-resolve.test.ts | 94 ++++++++++++++++++++++++++++
 3 files changed, 108 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a27a461e..56f333f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`deepl sync resolve` kept the local side of every merge conflict, silently discarding a teammate's newer translations.** The documented rule — take the newer translation by `translated_at` — never fired on a real `.deepl-sync.lock`. The leaf test treated any object carrying `source_hash` as a translation to compare, and every lockfile entry carries one, so the resolver read `translated_at` on the entry, where it does not exist; the real timestamp lives on each locale inside that entry's `translations` map, and the recursion that would have reached it was never taken. Each conflict was therefore reported as `kept ours: neither side had translated_at` and resolved to ours, at exit code 0 and without the `length-heuristic` tag that exists to mark exactly this kind of unreliable decision — so the per-entry report gave no sign that anything had been dropped. An entry holding a `translations` map is now treated as a container and merged one locale at a time, which is where the timestamps are, and the report names the locale it decided (`greeting.translations.de`) rather than the entry. Fields the two sides agree on are no longer listed as conflicts. The existing tests passed throughout because their fixtures put `translated_at` directly on the entry, a shape `SyncLockManager` does not write; the suite now also drives the shape it does.
+
 - **docs**: Five documentation inaccuracies found in the pre-2.0 audit. `docs/API.md` and `README.md` still said the **last** `--glossary` wins a conflicting term, contradicting the same files, the flag's own help text, and the verified behaviour — which mapping wins is the API's choice and does not follow flag order. `docs/API.md`'s command-group table omitted `correct` while claiming to match `deepl --help`, and the README's table of contents omitted its Spelling and Grammar Correction section. `docs/API.md`'s environment-variable reference omitted `NO_PROXY`, which the HTTP client honours and the README already documented. `docs/TROUBLESHOOTING.md` attributed "Translation cache backend failed to load" to running Node.js < 24, which the startup version check now rejects earlier with its own message, so the stated cause was unreachable; that entry now describes the reachable case (a v24+ runtime with no usable `node:sqlite`) and the version error is documented under exit code 6, where it previously appeared nowhere.
 
 - **watch**: **`deepl watch` debounced at 300 ms while `--help` and every doc said 500, and `watch.debounceMs` did nothing.** The command forwarded a debounce only when `--debounce` was passed, so an omitted flag fell through to `WatchService`'s own 300 ms fallback — a third copy of a value the config schema and the flag's help text both put at 500. The configured key was accepted by `deepl config set` and listed in the documented schema, but nothing ever read it for `watch`. Resolution is now flag, then `watch.debounceMs`, then the documented 500 ms default, and that default is a single exported constant shared with the config schema so the two cannot drift again. `deepl sync --watch` was already correct at 500 and is unchanged.
diff --git a/src/sync/sync-resolve.ts b/src/sync/sync-resolve.ts
index 759cce7b..c3300e82 100644
--- a/src/sync/sync-resolve.ts
+++ b/src/sync/sync-resolve.ts
@@ -175,6 +175,12 @@ function deepMergeWithDecisions(
       continue;
     }
 
+    // Both sides carry the same value, so there is nothing to resolve and
+    // nothing worth a line in the report.
+    if (ourValue === theirValue) {
+      continue;
+    }
+
     if (isTranslationEntry(ourValue) && isTranslationEntry(theirValue)) {
       const ourDate = (ourValue as Record<string, unknown>)['translated_at'] as
         string | undefined;
@@ -252,7 +258,12 @@ function deepMergeWithDecisions(
 function isTranslationEntry(obj: unknown): boolean {
   if (typeof obj !== 'object' || obj === null) return false;
   const record = obj as Record<string, unknown>;
-  return 'translated_at' in record || 'source_hash' in record;
+  if ('translated_at' in record) return true;
+  // An object holding a `translations` map is a container, not a leaf: its
+  // timestamps belong to the locales inside it, so it has to be merged one
+  // locale at a time rather than compared at this level.
+  if ('translations' in record) return false;
+  return 'source_hash' in record;
 }
 
 export async function resolveLockFile(
diff --git a/tests/unit/sync/sync-resolve.test.ts b/tests/unit/sync/sync-resolve.test.ts
index c438966d..08385d22 100644
--- a/tests/unit/sync/sync-resolve.test.ts
+++ b/tests/unit/sync/sync-resolve.test.ts
@@ -132,6 +132,100 @@ describe('resolveConflicts()', () => {
     });
   });
 
+  // The fixtures above put translated_at directly on the entry. SyncLockManager
+  // does not write that shape: the entry carries source_hash and a translations
+  // map, and translated_at sits on each locale inside it. These drive the shape
+  // that reaches the resolver after a real `git merge`.
+  describe('the lockfile shape SyncLockManager writes', () => {
+    function conflictedLock(ourStamp: string, theirStamp: string): string {
+      const entry = (hash: string, stamp: string): string =>
+        `      "greeting": { "source_hash": "185f8db32271", "source_locale": "en", "updated_at": "2026-01-01T00:00:00.000Z", "translations": { "de": { "locale": "de", "hash": "${hash}", "translated_at": "${stamp}" } } }`;
+      return [
+        '{',
+        '  "version": 1,',
+        '  "entries": {',
+        '    "locales/en.json": {',
+        '<<<<<<< HEAD',
+        entry('ours_hash', ourStamp),
+        '=======',
+        entry('theirs_hash', theirStamp),
+        '>>>>>>> feature/de-updates',
+        '    }',
+        '  }',
+        '}',
+      ].join('\n');
+    }
+
+    function survivingHash(resolved: string): string {
+      const parsed = JSON.parse(resolved) as {
+        entries: Record<
+          string,
+          Record<string, { translations: Record<string, { hash: string }> }>
+        >;
+      };
+      return parsed.entries['locales/en.json']!['greeting']!.translations['de']!
+        .hash;
+    }
+
+    it('should take theirs when their nested translation is newer', () => {
+      const { resolved, decisions } = resolveConflicts(
+        conflictedLock('2026-02-01T00:00:00.000Z', '2026-03-01T00:00:00.000Z')
+      );
+
+      expect(survivingHash(resolved)).toBe('theirs_hash');
+      expect(
+        decisions.some(
+          (d) => d.source === 'theirs' && /newer translated_at/.test(d.reason)
+        )
+      ).toBe(true);
+    });
+
+    it('should keep ours when our nested translation is newer', () => {
+      const { resolved, decisions } = resolveConflicts(
+        conflictedLock('2026-03-01T00:00:00.000Z', '2026-02-01T00:00:00.000Z')
+      );
+
+      expect(survivingHash(resolved)).toBe('ours_hash');
+      expect(
+        decisions.some(
+          (d) => d.source === 'ours' && /newer translated_at/.test(d.reason)
+        )
+      ).toBe(true);
+    });
+
+    it('should never report that neither side had a timestamp', () => {
+      const { decisions } = resolveConflicts(
+        conflictedLock('2026-02-01T00:00:00.000Z', '2026-03-01T00:00:00.000Z')
+      );
+
+      expect(
+        decisions.filter((d) => /neither side had translated_at/.test(d.reason))
+      ).toHaveLength(0);
+    });
+
+    it('should not report fields the two sides agree on as conflicts', () => {
+      const { decisions } = resolveConflicts(
+        conflictedLock('2026-02-01T00:00:00.000Z', '2026-03-01T00:00:00.000Z')
+      );
+
+      // source_hash, source_locale and updated_at are identical on both sides.
+      expect(
+        decisions.filter((d) => /scalar conflict/.test(d.reason))
+      ).toHaveLength(0);
+    });
+
+    it('should report one decision, against the nested locale key', () => {
+      const { decisions } = resolveConflicts(
+        conflictedLock('2026-02-01T00:00:00.000Z', '2026-03-01T00:00:00.000Z')
+      );
+
+      // The merge runs on the conflict fragment, so the path is relative to it
+      // rather than to the whole lockfile. One entry, because the fields the
+      // sides agree on are not reported.
+      expect(decisions.map((d) => d.key)).toEqual(['greeting.translations.de']);
+    });
+  });
+
   describe('fallback to longer side when JSON does not parse', () => {
     it('should pick the longer side when neither side is valid JSON', () => {
       const content = [

From 44def11dcfb77aca5641ec64c62d7138eb132b24 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 15:58:43 -0400
Subject: [PATCH 103/256] docs(examples): add sync resolve and sync audit
 examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

These were the two subcommands with no example script. Both work on the
lockfile and never call the API, so unlike the rest of the sync examples they
run without a key or a network, and each says so rather than gating on
`deepl auth show`.

26-sync-resolve.sh builds a .deepl-sync.lock in the state git leaves after two
branches re-translate the same key, previews the decision with --dry-run and
shows the file is untouched, resolves for real, confirms the later translation
survived, and shows the --format json decision list a merge driver would read.

27-sync-audit.sh gives one English term to two keys, translates them
differently in German, and audits: one inconsistency reported with both
renderings. Aligning the two makes it clean again, while a term with a single
translation is never flagged. Both text and JSON output are shown.

Slots 26 and 27 were reserved for these by the renumbering, so the sync block
stays contiguous and no file moves again. Both arrays in run-all.sh include
them -- they are fast and hermetic, so the --fast subset keeps them too. Ran
both end to end.

`sync push` and `sync pull` remain without examples: they need a reachable TMS
endpoint and a TMS_API_KEY, so an example could not run unattended. The reason
is now stated in examples/README.md, where it previously looked like an
oversight.

No CHANGELOG entry: examples/ is excluded from the published package by the
files field, so nothing here reaches a consumer.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 examples/26-sync-resolve.sh | 127 ++++++++++++++++++++++++++++++++++++
 examples/27-sync-audit.sh   | 123 ++++++++++++++++++++++++++++++++++
 examples/README.md          |   7 ++
 examples/run-all.sh         |   4 ++
 4 files changed, 261 insertions(+)
 create mode 100755 examples/26-sync-resolve.sh
 create mode 100755 examples/27-sync-audit.sh

diff --git a/examples/26-sync-resolve.sh b/examples/26-sync-resolve.sh
new file mode 100755
index 00000000..84f8237d
--- /dev/null
+++ b/examples/26-sync-resolve.sh
@@ -0,0 +1,127 @@
+#!/bin/bash
+# Sync — Resolving lockfile merge conflicts
+# Demonstrates `deepl sync resolve` on a .deepl-sync.lock left conflicted by git
+
+set -e  # Exit on error
+
+echo "=== DeepL CLI: Sync — Resolve Lockfile Conflicts ==="
+echo
+
+# resolve reads and rewrites .deepl-sync.lock and never calls the API, so this
+# example runs without a key or a network.
+echo "No API key needed: resolve works on the lockfile alone."
+echo
+
+PROJECT_DIR="/tmp/deepl-sync-resolve-demo"
+rm -rf "$PROJECT_DIR"
+mkdir -p "$PROJECT_DIR/locales"
+
+cleanup() {
+  rm -rf "$PROJECT_DIR"
+}
+trap cleanup EXIT
+
+cd "$PROJECT_DIR"
+
+cat > .deepl-sync.yaml << 'EOF'
+version: 1
+source_locale: en
+target_locales:
+  - de
+buckets:
+  json:
+    include:
+      - "locales/en.json"
+EOF
+
+echo '{ "greeting": "Hello" }' > locales/en.json
+echo '{ "greeting": "Hallo" }' > locales/de.json
+
+echo "Created test project: $PROJECT_DIR"
+echo
+
+# 1. A lockfile in the state git leaves behind when two branches both
+#    re-translated the same key. Both sides are valid JSON; they differ only in
+#    the German translation and its timestamp.
+echo "1. A .deepl-sync.lock left conflicted by git merge"
+cat > .deepl-sync.lock << 'EOF'
+{
+  "version": 1,
+  "generated_at": "2026-01-01T00:00:00.000Z",
+  "source_locale": "en",
+  "entries": {
+    "locales/en.json": {
+<<<<<<< HEAD
+      "greeting": { "source_hash": "185f8db32271", "source_text": "Hello", "source_locale": "en", "updated_at": "2026-01-01T00:00:00.000Z", "translations": { "de": { "locale": "de", "hash": "185f8db32271", "status": "translated", "translated_at": "2026-02-01T00:00:00.000Z" } } }
+=======
+      "greeting": { "source_hash": "185f8db32271", "source_text": "Hello", "source_locale": "en", "updated_at": "2026-01-01T00:00:00.000Z", "translations": { "de": { "locale": "de", "hash": "185f8db32271", "status": "translated", "translated_at": "2026-03-01T00:00:00.000Z" } } }
+>>>>>>> feature/de-updates
+    }
+  },
+  "stats": { "total_keys": 1, "total_translations": 1, "last_sync": "2026-01-01T00:00:00.000Z" }
+}
+EOF
+grep -c '<<<<<<<\|=======\|>>>>>>>' .deepl-sync.lock | xargs echo "   conflict marker lines:"
+echo "   ours was translated 2026-02-01, theirs 2026-03-01"
+echo
+
+# 2. --dry-run prints the decision it would make and leaves the file alone.
+echo "2. Preview the decisions without writing (--dry-run)"
+deepl sync resolve --dry-run
+echo
+echo "   lockfile still conflicted after the dry run:"
+grep -c '<<<<<<<' .deepl-sync.lock | xargs echo "   remaining <<<<<<< markers:"
+echo
+
+# 3. Apply. For each conflicting locale the newer translated_at wins, so the
+#    branch that translated later is the one kept.
+echo "3. Resolve for real"
+deepl sync resolve
+echo
+
+echo "4. The newer side survived"
+node -e '
+const fs = require("fs");
+const lock = JSON.parse(fs.readFileSync(".deepl-sync.lock", "utf8"));
+const de = lock.entries["locales/en.json"].greeting.translations.de;
+console.log("   kept translated_at:", de.translated_at);
+console.log("   conflict markers remaining:", /<<<<<<</.test(fs.readFileSync(".deepl-sync.lock", "utf8")) ? "yes" : "none");
+'
+echo
+
+# 4. JSON output, for a merge driver or CI step that needs to inspect decisions.
+echo "5. Machine-readable decisions (--format json)"
+cat > .deepl-sync.lock << 'EOF'
+{
+  "version": 1,
+  "generated_at": "2026-01-01T00:00:00.000Z",
+  "source_locale": "en",
+  "entries": {
+    "locales/en.json": {
+<<<<<<< HEAD
+      "greeting": { "source_hash": "185f8db32271", "source_text": "Hello", "source_locale": "en", "updated_at": "2026-01-01T00:00:00.000Z", "translations": { "de": { "locale": "de", "hash": "185f8db32271", "status": "translated", "translated_at": "2026-02-01T00:00:00.000Z" } } }
+=======
+      "greeting": { "source_hash": "185f8db32271", "source_text": "Hello", "source_locale": "en", "updated_at": "2026-01-01T00:00:00.000Z", "translations": { "de": { "locale": "de", "hash": "185f8db32271", "status": "translated", "translated_at": "2026-03-01T00:00:00.000Z" } } }
+>>>>>>> feature/de-updates
+    }
+  },
+  "stats": { "total_keys": 1, "total_translations": 1, "last_sync": "2026-01-01T00:00:00.000Z" }
+}
+EOF
+deepl sync resolve --format json
+echo
+
+cat << 'EOF'
+
+Notes:
+  - Each conflicting locale is decided on its own translated_at; the later
+    translation wins and the decision names the locale it applied to.
+  - A conflict region whose sides do not parse as JSON falls back to keeping the
+    longer side. That decision is tagged length-heuristic and logged as a WARN;
+    review those by hand rather than trusting them.
+  - resolve only settles the lockfile. Run `deepl sync` afterwards to fill any
+    translation gaps the merge left behind.
+
+EOF
+
+echo "=== Resolve example complete ==="
diff --git a/examples/27-sync-audit.sh b/examples/27-sync-audit.sh
new file mode 100755
index 00000000..f8cf96dc
--- /dev/null
+++ b/examples/27-sync-audit.sh
@@ -0,0 +1,123 @@
+#!/bin/bash
+# Sync — Auditing translation consistency
+# Demonstrates `deepl sync audit` finding one source term translated two ways
+
+set -e  # Exit on error
+
+echo "=== DeepL CLI: Sync — Audit Translation Consistency ==="
+echo
+
+# audit compares the lockfile against the translations already on disk and never
+# calls the API, so this example runs without a key or a network.
+echo "No API key needed: audit compares the lockfile against your target files."
+echo
+
+PROJECT_DIR="/tmp/deepl-sync-audit-demo"
+rm -rf "$PROJECT_DIR"
+mkdir -p "$PROJECT_DIR/locales"
+
+cleanup() {
+  rm -rf "$PROJECT_DIR"
+}
+trap cleanup EXIT
+
+cd "$PROJECT_DIR"
+
+cat > .deepl-sync.yaml << 'EOF'
+version: 1
+source_locale: en
+target_locales:
+  - de
+buckets:
+  json:
+    include:
+      - "locales/en.json"
+EOF
+
+echo "Created test project: $PROJECT_DIR"
+echo
+
+# 1. Two keys carrying the same English source text. This is the ordinary
+#    shape of a UI string reused in a button and a menu item.
+echo "1. Source file with one term used twice"
+cat > locales/en.json << 'EOF'
+{
+  "save_button": "Save",
+  "save_menu": "Save",
+  "cancel_button": "Cancel"
+}
+EOF
+cat locales/en.json
+echo
+
+# 2. German translated the two "Save" keys differently. Both are valid German;
+#    the point is that one product should not use both.
+echo "2. German where the same term was translated two ways"
+cat > locales/de.json << 'EOF'
+{
+  "save_button": "Speichern",
+  "save_menu": "Sichern",
+  "cancel_button": "Abbrechen"
+}
+EOF
+cat locales/de.json
+echo
+
+# 3. audit reads source_text and the per-locale status from the lockfile, then
+#    compares the actual translated strings in the target files.
+cat > .deepl-sync.lock << 'EOF'
+{
+  "version": 1,
+  "generated_at": "2026-01-01T00:00:00.000Z",
+  "source_locale": "en",
+  "entries": {
+    "locales/en.json": {
+      "save_button": { "source_hash": "s1", "source_text": "Save", "source_locale": "en", "updated_at": "2026-01-01T00:00:00.000Z", "translations": { "de": { "locale": "de", "hash": "s1", "status": "translated", "translated_at": "2026-01-01T00:00:00.000Z" } } },
+      "save_menu": { "source_hash": "s1", "source_text": "Save", "source_locale": "en", "updated_at": "2026-01-01T00:00:00.000Z", "translations": { "de": { "locale": "de", "hash": "s1", "status": "translated", "translated_at": "2026-01-01T00:00:00.000Z" } } },
+      "cancel_button": { "source_hash": "c1", "source_text": "Cancel", "source_locale": "en", "updated_at": "2026-01-01T00:00:00.000Z", "translations": { "de": { "locale": "de", "hash": "c1", "status": "translated", "translated_at": "2026-01-01T00:00:00.000Z" } } }
+    }
+  },
+  "stats": { "total_keys": 3, "total_translations": 3, "last_sync": "2026-01-01T00:00:00.000Z" }
+}
+EOF
+
+echo "3. Audit the project"
+deepl sync audit
+echo
+
+# 4. JSON for a CI step. inconsistencies[] is empty on a consistent project, so
+#    a pipeline can gate on its length.
+echo "4. Machine-readable report (--format json)"
+deepl sync audit --format json
+echo
+
+# 5. Align the two translations and the inconsistency goes away. "Cancel" was
+#    never flagged: one source term with one translation is consistent.
+echo "5. Align the two translations, then audit again"
+cat > locales/de.json << 'EOF'
+{
+  "save_button": "Speichern",
+  "save_menu": "Speichern",
+  "cancel_button": "Abbrechen"
+}
+EOF
+deepl sync audit
+echo
+
+cat << 'EOF'
+
+Notes:
+  - "Audit" here means translation consistency — one source term rendered
+    differently across a project — not security auditing in the npm audit sense.
+  - Comparison uses the text in your target files, not the lockfile hashes: the
+    per-locale hash is a hash of the SOURCE text, so it is identical across a
+    term group by construction and cannot identify a translation.
+  - A target file that cannot be read or parsed is left out of the comparison
+    and listed under missingTargets rather than silently counted as consistent.
+  - Inconsistencies are reported, not corrected. Fix them by editing the target
+    file, or keep terminology aligned up front with a glossary
+    (see 17-glossaries.sh).
+
+EOF
+
+echo "=== Audit example complete ==="
diff --git a/examples/README.md b/examples/README.md
index 7291e1a7..124c7ef8 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -42,6 +42,13 @@ This directory contains practical, real-world examples of using the DeepL CLI.
 - [Sync — CI/CD Integration](./23-sync-ci.sh) - Using deepl sync in automated pipelines
 - [Sync — Live Validation](./24-sync-live-validation.sh) - Comprehensive end-to-end validation of all sync features
 - [Sync — Laravel PHP arrays](./25-sync-laravel-php.sh) - `laravel_php` format parser: AST allowlist, span-surgical reconstruct, pipe-pluralization warning gate, `sync.limits` caps
+- [Sync — Resolve Lockfile Conflicts](./26-sync-resolve.sh) - Auto-resolving a `.deepl-sync.lock` left conflicted by `git merge`, and previewing the decisions first
+- [Sync — Audit Translation Consistency](./27-sync-audit.sh) - Finding one source term translated two different ways across a project
+
+`deepl sync push` and `deepl sync pull` have no example script here. They need a
+reachable TMS endpoint and a `TMS_API_KEY`, so an example could not run
+unattended as part of `run-all.sh`; see [docs/SYNC.md](../docs/SYNC.md) for their
+reference documentation.
 
 ### Configuration
 
diff --git a/examples/run-all.sh b/examples/run-all.sh
index 11e4b477..d74f330a 100755
--- a/examples/run-all.sh
+++ b/examples/run-all.sh
@@ -77,6 +77,8 @@ EXAMPLES=(
   "23-sync-ci.sh"
   "24-sync-live-validation.sh"
   "25-sync-laravel-php.sh"
+  "26-sync-resolve.sh"
+  "27-sync-audit.sh"
   # Configuration
   "28-configuration.sh"
   "29-custom-config-files.sh"
@@ -128,6 +130,8 @@ if [ "$FAST_MODE" = true ]; then
     "23-sync-ci.sh"
     "24-sync-live-validation.sh"
     "25-sync-laravel-php.sh"
+    "26-sync-resolve.sh"
+    "27-sync-audit.sh"
     # Configuration
     "28-configuration.sh"
     "29-custom-config-files.sh"

From 4a7dda361fc184607eafb9955b84031d3c779e5c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 16:06:14 -0400
Subject: [PATCH 104/256] test(docs): assert the argument surface and
 subcommand docs coverage centrally
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_describe reported names, aliases, options and subcommands, but not positional
arguments or whether a command is hidden. Both are now emitted, which lets one
check cover what was previously spread across per-command E2E tables, or not
covered at all.

Added to documented-surface:

- the full required-argument surface as one table: 28 commands across voice,
  watch, completion, config, hooks, glossary, style-rules and admin. Relaxing a
  required argument to optional, or adding a new one, fails here. Verified by
  making `glossary add-entry <target>` optional, which the table rejects.
- optional arguments must follow required ones. Commander cannot parse a
  required argument after an optional one, so the order is a correctness
  constraint rather than a convention.
- every non-hidden subcommand has a documented invocation. The table check in
  docs/API.md already covered top-level commands; a new `glossary` or `sync`
  verb could previously ship undocumented. All 53 pass today, so this is a
  guard rather than a fix.

Hidden commands are skipped via the reported flag rather than an allowlist, so
`sync glossary-report` -- a rejector for a name that never shipped -- needs no
special-casing, and the existing top-level check no longer has to infer
visibility from a leading underscore.

The per-subcommand synopsis assertions in the glossary and style-rules E2E
files are removed as redundant: commander renders the synopsis from the same
registered arguments the table now checks, so the two cannot disagree, and the
table covers 28 commands where those two covered 22 between them. Their
runtime rejection tests stay -- those prove commander enforces the arity, which
inspecting the surface does not.

describe.ts stays at 100% coverage. Suite 6477 -> 6484.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/cli/commands/describe.ts               |  44 +++++++-
 tests/e2e/cli-glossary.e2e.test.ts         |  29 +-----
 tests/e2e/cli-style-rules.e2e.test.ts      |  24 +----
 tests/unit/cli/describe.test.ts            |  74 ++++++++++++++
 tests/unit/docs/documented-surface.test.ts | 112 +++++++++++++++++++++
 5 files changed, 234 insertions(+), 49 deletions(-)

diff --git a/src/cli/commands/describe.ts b/src/cli/commands/describe.ts
index 680ad990..8eb15612 100644
--- a/src/cli/commands/describe.ts
+++ b/src/cli/commands/describe.ts
@@ -1,4 +1,4 @@
-import type { Command, Option } from 'commander';
+import type { Argument, Command, Option } from 'commander';
 
 export interface DescribeOption {
   flags: string;
@@ -6,12 +6,25 @@ export interface DescribeOption {
   defaultValue?: unknown;
 }
 
+export interface DescribeArgument {
+  name: string;
+  required: boolean;
+}
+
 export interface DescribeCommand {
   name: string;
   description: string;
   aliases: string[];
+  /** Positional arguments, in declaration order. */
+  arguments: DescribeArgument[];
   options: DescribeOption[];
   commands: DescribeCommand[];
+  /**
+   * Omitted from `--help`. Hidden commands are part of the parsed surface but
+   * not the documented one, so a consumer can skip them without knowing their
+   * names.
+   */
+  hidden: boolean;
 }
 
 function describeOption(opt: Option): DescribeOption {
@@ -25,16 +38,39 @@ function describeOption(opt: Option): DescribeOption {
   return out;
 }
 
-function describeCommand(cmd: Command): DescribeCommand {
+function describeArgument(arg: Argument): DescribeArgument {
+  return { name: arg.name(), required: arg.required };
+}
+
+/**
+ * Names the parent lists in `--help`. Commander adds an implicit `help` entry
+ * that is not among the parent's registered commands, so membership is compared
+ * by name rather than by identity.
+ */
+function visibleChildNames(cmd: Command): Set<string> {
+  return new Set(
+    cmd
+      .createHelp()
+      .visibleCommands(cmd)
+      .map((child) => child.name())
+  );
+}
+
+function describeCommand(cmd: Command, hidden: boolean): DescribeCommand {
+  const visible = visibleChildNames(cmd);
   return {
     name: cmd.name(),
     description: cmd.description(),
     aliases: cmd.aliases(),
+    arguments: cmd.registeredArguments.map(describeArgument),
     options: cmd.options.map(describeOption),
-    commands: cmd.commands.map(describeCommand),
+    commands: cmd.commands.map((child) =>
+      describeCommand(child, !visible.has(child.name()))
+    ),
+    hidden,
   };
 }
 
 export function describeProgram(program: Command): DescribeCommand {
-  return describeCommand(program);
+  return describeCommand(program, false);
 }
diff --git a/tests/e2e/cli-glossary.e2e.test.ts b/tests/e2e/cli-glossary.e2e.test.ts
index 4f0cb8ba..158a7838 100644
--- a/tests/e2e/cli-glossary.e2e.test.ts
+++ b/tests/e2e/cli-glossary.e2e.test.ts
@@ -5,81 +5,68 @@
  * subcommand, so a new subcommand is covered by adding a row. Glossary
  * behaviour that needs an account -- creating, listing, entry edits -- belongs
  * to the glossary service and client unit suites; what matters here is that
- * every subcommand declares its required arguments and refuses to run without
- * them.
+ * every subcommand refuses to run when a required argument is missing. The
+ * declared arity itself is asserted centrally in
+ * tests/unit/docs/documented-surface.test.ts.
  */
 
 import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
-/** Every `glossary` subcommand, with the synopsis its help must show. */
+/** Every `glossary` subcommand, with the description its help must show. */
 const SUBCOMMANDS: Array<{
   name: string;
-  synopsis: string;
   description: string;
 }> = [
   {
     name: 'create',
-    synopsis: 'create <name> <source-lang> <target-lang> <file>',
     description: 'Create a glossary from TSV/CSV file',
   },
   {
     name: 'list',
-    synopsis: 'list [options]',
     description: 'List all glossaries',
   },
   {
     name: 'show',
-    synopsis: 'show [options] <name-or-id>',
     description: 'Show glossary details',
   },
   {
     name: 'entries',
-    synopsis: 'entries [options] <name-or-id>',
     description: 'Show glossary entries',
   },
   {
     name: 'delete',
-    synopsis: 'delete [options] <name-or-id>',
     description: 'Delete a glossary',
   },
   {
     name: 'languages',
-    synopsis: 'languages',
     description: 'List supported glossary language pairs',
   },
   {
     name: 'add-entry',
-    synopsis: 'add-entry [options] <name-or-id> <source> <target>',
     description: 'Add a new entry to a glossary',
   },
   {
     name: 'update-entry',
-    synopsis: 'update-entry [options] <name-or-id> <source> <new-target>',
     description: 'Update an existing entry in a glossary',
   },
   {
     name: 'remove-entry',
-    synopsis: 'remove-entry [options] <name-or-id> <source>',
     description: 'Remove an entry from a glossary',
   },
   {
     name: 'rename',
-    synopsis: 'rename <name-or-id> <new-name>',
     description: 'Rename a glossary',
   },
   {
     name: 'update',
-    synopsis: 'update [options] <name-or-id>',
     description: 'Update glossary name and/or dictionary entries',
   },
   {
     name: 'replace-dictionary',
-    synopsis: 'replace-dictionary <name-or-id> <target-lang> <file>',
     description: 'Replace all entries in a glossary dictionary',
   },
   {
     name: 'delete-dictionary',
-    synopsis: 'delete-dictionary [options] <name-or-id> <target-lang>',
     description: 'Delete a dictionary from a multilingual glossary',
   },
 ];
@@ -121,14 +108,6 @@ describe('Glossary Command E2E', () => {
       }
     });
 
-    it('should declare the required arguments of every subcommand', () => {
-      const output = runCLI('glossary --help');
-
-      for (const { synopsis } of SUBCOMMANDS) {
-        expect(output).toContain(synopsis);
-      }
-    });
-
     it('should offer --format json on the reading subcommands', () => {
       for (const subcommand of ['list', 'show', 'entries']) {
         const output = runCLI(`glossary ${subcommand} --help`);
diff --git a/tests/e2e/cli-style-rules.e2e.test.ts b/tests/e2e/cli-style-rules.e2e.test.ts
index 04a1e318..138b8e26 100644
--- a/tests/e2e/cli-style-rules.e2e.test.ts
+++ b/tests/e2e/cli-style-rules.e2e.test.ts
@@ -1,8 +1,10 @@
 /**
  * E2E Tests for Style Rules Command
  *
- * The subcommand surface -- synopsis, description and options -- is asserted
- * from one table, so a new subcommand is covered by adding a row. Style-rule
+ * The subcommand surface -- description and options -- is asserted from one
+ * table, so a new subcommand is covered by adding a row. The declared arity
+ * itself is asserted centrally in tests/unit/docs/documented-surface.test.ts.
+ * Style-rule
  * behaviour that needs a Pro account is covered by the nock suite in
  * cli-style-rules.integration.test.ts; what belongs here is argument
  * validation and the --dry-run paths, which run without credentials.
@@ -12,61 +14,51 @@ import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
 const SUBCOMMANDS: Array<{
   name: string;
-  synopsis: string;
   description: string;
   options: string[];
 }> = [
   {
     name: 'list',
-    synopsis: 'list [options]',
     description: 'List all style rules',
     options: ['--detailed', '--page', '--page-size', '--format'],
   },
   {
     name: 'create',
-    synopsis: 'create [options]',
     description: 'Create a new style rule list',
     options: ['--name', '--language', '--rules', '--format'],
   },
   {
     name: 'show',
-    synopsis: 'show [options] <id>',
     description: 'Show a single style rule list',
     options: ['--detailed', '--format'],
   },
   {
     name: 'update',
-    synopsis: 'update [options] <id>',
     description: 'Update a style rule list',
     options: ['--name', '--rules'],
   },
   {
     name: 'delete',
-    synopsis: 'delete [options] <id>',
     description: 'Delete a style rule list',
     options: ['--yes', '--dry-run'],
   },
   {
     name: 'instructions',
-    synopsis: 'instructions [options] <style-id>',
     description: 'List custom instructions for a style rule',
     options: ['--format'],
   },
   {
     name: 'add-instruction',
-    synopsis: 'add-instruction [options] <style-id> <label> <prompt>',
     description: 'Add a custom instruction to a style rule',
     options: ['--source-language'],
   },
   {
     name: 'update-instruction',
-    synopsis: 'update-instruction [options] <style-id> <label> <prompt>',
     description: 'Update a custom instruction on a style rule',
     options: ['--source-language'],
   },
   {
     name: 'remove-instruction',
-    synopsis: 'remove-instruction [options] <style-id> <label>',
     description: 'Remove a custom instruction from a style rule',
     options: ['--yes', '--dry-run'],
   },
@@ -106,14 +98,6 @@ describe('Style Rules Command E2E', () => {
       }
     });
 
-    it('should declare the required arguments of every subcommand', () => {
-      const output = runCLI('style-rules --help');
-
-      for (const { synopsis } of SUBCOMMANDS) {
-        expect(output).toContain(synopsis);
-      }
-    });
-
     it('should offer each subcommand its own options', () => {
       for (const { name, options } of SUBCOMMANDS) {
         const output = runCLI(`style-rules ${name} --help`);
diff --git a/tests/unit/cli/describe.test.ts b/tests/unit/cli/describe.test.ts
index 07e11aeb..5ff973db 100644
--- a/tests/unit/cli/describe.test.ts
+++ b/tests/unit/cli/describe.test.ts
@@ -19,12 +19,21 @@ describe('describeProgram', () => {
       .option('-t, --to <lang>', 'Target language')
       .option('-f, --from <lang>', 'Source language');
 
+    program
+      .command('show')
+      .description('Show a glossary')
+      .argument('<name-or-id>', 'Glossary name or ID')
+      .argument('[target-lang]', 'Restrict to one target language');
+
     const sync = program
       .command('sync')
       .alias('sy')
       .description('Sync translations with TMS');
     sync.command('push').description('Push translations');
     sync.command('pull').description('Pull translations');
+    sync
+      .command('legacy-name', { hidden: true })
+      .description('Renamed; kept to point callers at the new name');
   });
 
   describe('shape', () => {
@@ -83,6 +92,71 @@ describe('describeProgram', () => {
     });
   });
 
+  describe('positional arguments', () => {
+    it('reports each argument in declaration order', () => {
+      const show = describeProgram(program).commands.find(
+        (c) => c.name === 'show'
+      );
+
+      expect(show?.arguments.map((a) => a.name)).toEqual([
+        'name-or-id',
+        'target-lang',
+      ]);
+    });
+
+    it('distinguishes required from optional arguments', () => {
+      const show = describeProgram(program).commands.find(
+        (c) => c.name === 'show'
+      );
+
+      expect(show?.arguments).toEqual([
+        { name: 'name-or-id', required: true },
+        { name: 'target-lang', required: false },
+      ]);
+    });
+
+    it('reports an empty list for a command taking no arguments', () => {
+      const translate = describeProgram(program).commands.find(
+        (c) => c.name === 'translate'
+      );
+
+      expect(translate?.arguments).toEqual([]);
+    });
+  });
+
+  describe('hidden commands', () => {
+    // Hidden subcommands are usually renamed-command rejectors. They are part of
+    // the parsed surface but not of the documented one, so a consumer of
+    // _describe needs to tell them apart without hard-coding their names.
+    it('marks a hidden subcommand as hidden', () => {
+      const sync = describeProgram(program).commands.find(
+        (c) => c.name === 'sync'
+      );
+      const legacy = sync?.commands.find((c) => c.name === 'legacy-name');
+
+      expect(legacy?.hidden).toBe(true);
+    });
+
+    it('marks a visible subcommand as not hidden', () => {
+      const sync = describeProgram(program).commands.find(
+        (c) => c.name === 'sync'
+      );
+
+      expect(sync?.commands.find((c) => c.name === 'push')?.hidden).toBe(false);
+      expect(sync?.hidden).toBe(false);
+    });
+
+    it('still reports the hidden command so the surface stays complete', () => {
+      const sync = describeProgram(program).commands.find(
+        (c) => c.name === 'sync'
+      );
+
+      expect(sync?.commands.map((c) => c.name)).toEqual(
+        expect.arrayContaining(['push', 'pull', 'legacy-name'])
+      );
+    });
+  });
+
   describe('serialization', () => {
     it('produces JSON-serializable output', () => {
       const result = describeProgram(program);
diff --git a/tests/unit/docs/documented-surface.test.ts b/tests/unit/docs/documented-surface.test.ts
index a5a35a1f..b75f515e 100644
--- a/tests/unit/docs/documented-surface.test.ts
+++ b/tests/unit/docs/documented-surface.test.ts
@@ -12,10 +12,48 @@ import { getAllLanguageCodes } from '../../../src/data/language-registry';
 interface DescribedCommand {
   name: string;
   aliases: string[];
+  arguments: { name: string; required: boolean }[];
   options: { flags: string }[];
   commands: DescribedCommand[];
+  hidden: boolean;
 }
 
+/**
+ * Every command taking a required positional argument, and which arguments it
+ * requires. Relaxing one to optional, or adding a new required one, changes the
+ * CLI's calling convention for anyone already scripting against it.
+ */
+const REQUIRED_ARGUMENTS: Record<string, string[]> = {
+  voice: ['file'],
+  watch: ['path'],
+  completion: ['shell'],
+  'config set': ['key', 'value'],
+  'hooks install': ['hook-type'],
+  'hooks uninstall': ['hook-type'],
+  'hooks path': ['hook-type'],
+  'glossary create': ['name', 'source-lang', 'target-lang', 'file'],
+  'glossary show': ['name-or-id'],
+  'glossary entries': ['name-or-id'],
+  'glossary delete': ['name-or-id'],
+  'glossary update': ['name-or-id'],
+  'glossary rename': ['name-or-id', 'new-name'],
+  'glossary add-entry': ['name-or-id', 'source', 'target'],
+  'glossary update-entry': ['name-or-id', 'source', 'new-target'],
+  'glossary remove-entry': ['name-or-id', 'source'],
+  'glossary replace-dictionary': ['name-or-id', 'target-lang', 'file'],
+  'glossary delete-dictionary': ['name-or-id', 'target-lang'],
+  'style-rules show': ['id'],
+  'style-rules update': ['id'],
+  'style-rules delete': ['id'],
+  'style-rules instructions': ['style-id'],
+  'style-rules add-instruction': ['style-id', 'label', 'prompt'],
+  'style-rules update-instruction': ['style-id', 'label', 'prompt'],
+  'style-rules remove-instruction': ['style-id', 'label'],
+  'admin keys deactivate': ['key-id'],
+  'admin keys rename': ['key-id', 'label'],
+  'admin keys set-limit': ['key-id', 'characters'],
+};
+
 const ROOT = path.join(__dirname, '..', '..', '..');
 const CLI_ENTRY = path.join(ROOT, 'dist', 'cli', 'index.js');
 const DOCS = [
@@ -223,6 +261,80 @@ describe('documented CLI surface', () => {
     });
   });
 
+  // Walks the whole tree. Hidden commands are renamed-command rejectors: part of
+  // the parsed surface but not the documented one, and _describe reports the
+  // flag so neither check below needs to know their names.
+  function eachCommand(
+    visit: (command: DescribedCommand, commandPath: string[]) => void
+  ): void {
+    const walk = (cmd: DescribedCommand, prefix: string[]): void => {
+      for (const child of cmd.commands) {
+        if (child.name === 'help' || child.hidden) continue;
+        const next = [...prefix, child.name];
+        visit(child, next);
+        walk(child, next);
+      }
+    };
+    walk(surface, []);
+  }
+
+  describe('subcommand coverage', () => {
+    it('documents an invocation of every subcommand', () => {
+      // A top-level command missing from docs/API.md's table is caught above.
+      // This catches the subcommand case, where a new `glossary` or `sync` verb
+      // can ship with no documented invocation at all.
+      const documentedPaths = new Set<string>();
+      for (const docPath of DOCS) {
+        const contents = fs.readFileSync(path.join(ROOT, docPath), 'utf-8');
+        for (const invocation of invocations(contents)) {
+          const tokens = commandTokens(invocation);
+          for (let depth = 1; depth <= tokens.length; depth++) {
+            documentedPaths.add(tokens.slice(0, depth).join(' '));
+          }
+        }
+      }
+
+      const undocumented: string[] = [];
+      eachCommand((_command, commandPath) => {
+        if (commandPath.length < 2) return;
+        const joined = commandPath.join(' ');
+        if (!documentedPaths.has(joined)) undocumented.push(joined);
+      });
+
+      expect(undocumented).toEqual([]);
+    });
+  });
+
+  describe('positional argument surface', () => {
+    it('requires exactly the arguments recorded above', () => {
+      const actual: Record<string, string[]> = {};
+      eachCommand((command, commandPath) => {
+        const required = command.arguments
+          .filter((argument) => argument.required)
+          .map((argument) => argument.name);
+        if (required.length > 0) actual[commandPath.join(' ')] = required;
+      });
+
+      expect(actual).toEqual(REQUIRED_ARGUMENTS);
+    });
+
+    it('declares optional arguments after required ones', () => {
+      // Commander cannot parse a required argument that follows an optional one,
+      // so the declaration order is a correctness constraint, not a style rule.
+      const offenders: string[] = [];
+      eachCommand((command, commandPath) => {
+        const firstOptional = command.arguments.findIndex((a) => !a.required);
+        if (firstOptional === -1) return;
+        const requiredAfter = command.arguments
+          .slice(firstOptional)
+          .some((a) => a.required);
+        if (requiredAfter) offenders.push(commandPath.join(' '));
+      });
+
+      expect(offenders).toEqual([]);
+    });
+  });
+
   describe('retired endpoints', () => {
     // Language listings moved to GET /v3/languages; the v2 endpoints are
     // formally deprecated, so no doc should teach a reader to call them.

From 3625e7179635a3fa33d06786cf04ed47c666ddfc Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 16:09:18 -0400
Subject: [PATCH 105/256] test(structured-file): drop the CLI-surface half of
 the integration file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cli-structured-file-translate.integration.test.ts held two nested describes: a
"CLI argument validation" block driving the built binary, and a service-level
block driving TranslationService and FileTranslationService in-process against
nock. Only the first overlapped the E2E suite, so the file is split rather than
merged and renamed in its describe to say what it now is.

cli-structured-file.e2e.test.ts is a strict superset of the removed block. It
covers the same JSON/YAML/.yml acceptance, the --output requirement, invalid and
empty JSON, and the invalid language code -- and asserts the error message and
exit code where the integration tests only checked that something threw. It also
covers indentation preservation, empty YAML, extension recognition, nested
directories and output-directory creation, none of which the removed block had.

Three of the removed tests asserted not.toMatch(/Unsupported file type/) on a
run with a fake key, so they passed on the auth failure regardless of how the
file was handled. Five carried a duplicated expect.assertions(1) from a
copy-paste.

The integration file now has no CLI call sites; the runCLI factory and its
import go with the block. Net 8 tests removed at runtime, 0 added.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ...uctured-file-translate.integration.test.ts | 104 +-----------------
 1 file changed, 1 insertion(+), 103 deletions(-)

diff --git a/tests/integration/cli-structured-file-translate.integration.test.ts b/tests/integration/cli-structured-file-translate.integration.test.ts
index 3f5e9b4c..268286f7 100644
--- a/tests/integration/cli-structured-file-translate.integration.test.ts
+++ b/tests/integration/cli-structured-file-translate.integration.test.ts
@@ -14,18 +14,13 @@ import { CacheService } from '../../src/storage/cache';
 import {
   createTestConfigDir,
   createTestDir,
-  makeRunCLI,
   DEEPL_FREE_API_URL,
 } from '../helpers';
 
-describe('Structured File Translation CLI Integration', () => {
+describe('Structured File Translation service integration', () => {
   const testConfig = createTestConfigDir('test-structured');
   const testFiles = createTestDir('structured-files');
   const testDir = testFiles.path;
-  const { runCLI } = makeRunCLI(testConfig.path, {
-    apiKey: 'test-api-key-123',
-  });
-
   beforeAll(() => {
     fs.writeFileSync(
       path.join(testConfig.path, 'config.json'),
@@ -53,103 +48,6 @@ describe('Structured File Translation CLI Integration', () => {
     nock.cleanAll();
   });
 
-  describe('CLI argument validation', () => {
-    it('should accept JSON file with --to and --output flags', () => {
-      const testFile = path.join(testDir, 'validation.json');
-      fs.writeFileSync(testFile, JSON.stringify({ key: 'test' }, null, 2));
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl translate "${testFile}" --to es --output /tmp/out.json`);
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on API auth, not argument validation or file type
-        expect(output).not.toMatch(/Unsupported file type/i);
-      }
-    });
-
-    it('should accept YAML file with --to and --output flags', () => {
-      expect.assertions(1);
-      const testFile = path.join(testDir, 'validation.yaml');
-      fs.writeFileSync(testFile, 'key: test\n');
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl translate "${testFile}" --to es --output /tmp/out.yaml`);
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Unsupported file type/i);
-      }
-    });
-
-    it('should accept .yml file with --to and --output flags', () => {
-      expect.assertions(1);
-      const testFile = path.join(testDir, 'validation.yml');
-      fs.writeFileSync(testFile, 'key: test\n');
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl translate "${testFile}" --to es --output /tmp/out.yml`);
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Unsupported file type/i);
-      }
-    });
-
-    it('should validate target language for structured files', () => {
-      const testFile = path.join(testDir, 'lang-val.json');
-      fs.writeFileSync(testFile, JSON.stringify({ key: 'test' }, null, 2));
-
-      expect(() => {
-        runCLI(
-          `deepl translate "${testFile}" --to INVALID --output /tmp/out.json`
-        );
-      }).toThrow();
-    });
-
-    it('should require --output flag for structured file translation', () => {
-      const testFile = path.join(testDir, 'no-output.json');
-      fs.writeFileSync(testFile, JSON.stringify({ key: 'test' }, null, 2));
-
-      expect(() => {
-        runCLI(`deepl translate "${testFile}" --to es`);
-      }).toThrow();
-    });
-
-    it('should handle empty JSON object without API call', () => {
-      const inputPath = path.join(testDir, 'empty.json');
-      const outputPath = path.join(testDir, 'empty-es.json');
-
-      fs.writeFileSync(inputPath, '{}');
-
-      const output = runCLI(
-        `deepl translate "${inputPath}" --to es --output "${outputPath}"`
-      );
-      expect(output).toContain('Translated');
-
-      const result = JSON.parse(fs.readFileSync(outputPath, 'utf-8'));
-      expect(result).toEqual({});
-    });
-
-    it('should reject invalid JSON files', () => {
-      const testFile = path.join(testDir, 'invalid.json');
-      fs.writeFileSync(testFile, '{ not valid json }');
-
-      expect(() => {
-        runCLI(`deepl translate "${testFile}" --to es --output /tmp/out.json`);
-      }).toThrow();
-    });
-
-    it('should reject empty JSON files', () => {
-      const testFile = path.join(testDir, 'empty-file.json');
-      fs.writeFileSync(testFile, '');
-
-      expect(() => {
-        runCLI(`deepl translate "${testFile}" --to es --output /tmp/out.json`);
-      }).toThrow();
-    });
-  });
-
   describe('service-level integration (in-process with nock)', () => {
     const API_KEY = 'test-api-key-123:fx';
     const FREE_API_URL = DEEPL_FREE_API_URL;

From 1e2b91a5b82096e4c2d6d014f12f52ff862b0964 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Wed, 5 Aug 2026 16:14:32 -0400
Subject: [PATCH 106/256] test(translate): split CLI flag coverage out of the
 integration file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cli-translate.integration.test.ts was the largest hybrid: a 1000-line block
spawning the built binary across 24 describes, followed by a nock block driving
handler -> resolver -> service -> HTTP in-process for translation-memory wiring.
The file now holds only the second, and says so.

Seventeen of the 24 describes were already covered elsewhere and are dropped:
help text, missing API key, --to and --output requirements, option-flag
acceptance, command structure, error messages, file types, JSON output, billed
characters, minification, --custom-instruction, --style-id, extended languages
and --tag-handling-version are all in cli-workflow, cli-success-paths,
cli-file-translation or cli-document-translation, mostly with stronger
assertions -- cli-success-paths translates a real file where these only checked
that nothing threw. Four style-rules tests were misfiled here entirely. The
"default target language from config" block goes because
tests/unit/translate-default-target.test.ts covers all six of its cases,
including the empty-targetLangs and stdin paths it did not reach.

The seven describes with no equivalent move to tests/e2e/cli-translate-flags
.e2e.test.ts: directory --output requirements, comma-separated targets, XML
tag-handling flags in combination, table output, the removed
--enable-beta-languages flag still being rejected and absent from help,
--api-url refusing http:// for remote hosts while allowing localhost and
127.0.0.1, and the choice lists on --formality, --tag-handling, --model-type and
--split-sentences. cli-parse-errors covers only "invalid option choice exits 6"
generically, so the per-option lists would otherwise have gone unguarded.

Integration suites invoking the CLI are now one file, cli-watch, with three call
sites inside an otherwise in-process WatchService suite. Suite 6484 -> 6426.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-translate-flags.e2e.test.ts     |  477 ++++++++
 .../cli-translate.integration.test.ts         | 1029 +----------------
 2 files changed, 480 insertions(+), 1026 deletions(-)
 create mode 100644 tests/e2e/cli-translate-flags.e2e.test.ts

diff --git a/tests/e2e/cli-translate-flags.e2e.test.ts b/tests/e2e/cli-translate-flags.e2e.test.ts
new file mode 100644
index 00000000..b04ed8ab
--- /dev/null
+++ b/tests/e2e/cli-translate-flags.e2e.test.ts
@@ -0,0 +1,477 @@
+/**
+ * E2E Tests for translate flag handling
+ *
+ * Flag-level behaviour of `deepl translate` that the workflow and success-path
+ * suites do not reach: directory output requirements, comma-separated targets,
+ * XML tag-handling combinations, table output, the removed
+ * --enable-beta-languages flag, --api-url scheme enforcement, and the choice
+ * lists on the constrained options.
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir, makeRunCLI } from '../helpers';
+
+describe('Translate CLI flags E2E', () => {
+  const testConfig = createTestConfigDir('e2e-translate-flags');
+  const testFiles = createTestDir('translate-flag-files');
+  const testConfigDir = testConfig.path;
+  const testDir = testFiles.path;
+  const { runCLI } = makeRunCLI(testConfig.path);
+
+  // Cached to avoid respawning the CLI for every help assertion.
+  let translateHelp: string;
+
+  beforeAll(() => {
+    translateHelp = runCLI('deepl translate --help');
+  });
+
+  afterAll(() => {
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  describe('directory translation validation', () => {
+    it('should require --output flag for directory translation', () => {
+      // Create a test directory with files
+      const testSubDir = path.join(testDir, 'subdir');
+      fs.mkdirSync(testSubDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(testSubDir, 'file1.txt'),
+        'Content 1',
+        'utf-8'
+      );
+
+      expect.assertions(1);
+      try {
+        runCLI(`deepl translate "${testSubDir}" --to es`, { stdio: 'pipe' });
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        // Will fail on API key or output requirement
+        expect(output).toMatch(/API key|auth|output/i);
+      }
+    });
+
+    it('should accept directory path with --to and --output flags', () => {
+      const testSubDir2 = path.join(testDir, 'subdir2');
+      const outputDir = path.join(testDir, 'output-dir');
+      fs.mkdirSync(testSubDir2, { recursive: true });
+      fs.writeFileSync(path.join(testSubDir2, 'file1.txt'), 'Content', 'utf-8');
+
+      expect.assertions(1);
+      try {
+        // This will fail without API key, but should recognize valid arguments
+        runCLI(
+          `deepl translate "${testSubDir2}" --to es --output "${outputDir}"`,
+          { stdio: 'pipe' }
+        );
+        // CLI accepted the arguments without error
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        // Should fail on API key, not argument validation
+        expect(output).toMatch(/API key|auth/i);
+      }
+    });
+  });
+
+  describe('multiple target languages', () => {
+    it('should accept comma-separated target languages', () => {
+      const helpOutput = translateHelp;
+      expect(helpOutput).toContain('--to <language>');
+      expect(helpOutput).toContain('comma-separated');
+    });
+
+    it('should validate comma-separated format', () => {
+      // Help should indicate comma-separated format is supported
+      const helpOutput = translateHelp;
+      expect(helpOutput).toContain('comma-separated');
+    });
+  });
+
+  describe('XML tag handling parameters', () => {
+    it.each([
+      {
+        flag: '--outline-detection',
+        patterns: [/xml.*structure.*detection/i, /tag-handling.*xml/i],
+      },
+      {
+        flag: '--splitting-tags',
+        patterns: [/xml.*tags.*split/i],
+      },
+      {
+        flag: '--non-splitting-tags',
+        patterns: [/should not be used to split sentences/i],
+        normalizeWhitespace: true,
+      },
+      {
+        flag: '--ignore-tags',
+        patterns: [/ignore/i],
+      },
+    ])(
+      'should show $flag flag in help',
+      ({ flag, patterns, normalizeWhitespace }) => {
+        const helpOutput = translateHelp;
+        expect(helpOutput).toContain(flag);
+        for (const pattern of patterns) {
+          const text = normalizeWhitespace
+            ? helpOutput.replace(/\s+/g, ' ')
+            : helpOutput;
+          expect(text).toMatch(pattern);
+        }
+      }
+    );
+
+    it.each([
+      {
+        flag: '--outline-detection',
+        args: '--outline-detection true',
+      },
+      {
+        flag: '--splitting-tags',
+        args: '--splitting-tags "br,hr,div"',
+      },
+      {
+        flag: '--non-splitting-tags',
+        args: '--non-splitting-tags "code,pre"',
+      },
+      {
+        flag: '--ignore-tags',
+        args: '--ignore-tags "script,style"',
+      },
+    ])('should accept $flag flag without error', ({ flag, args }) => {
+      expect.assertions(1);
+      try {
+        runCLI(
+          `deepl translate "<p>Hello</p>" --to es --tag-handling xml ${args}`,
+          { stdio: 'pipe' }
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(
+          new RegExp(`unknown.*option.*${flag.replace('--', '')}`, 'i')
+        );
+      }
+    });
+
+    it('should accept all XML tag handling flags together', () => {
+      expect.assertions(1);
+      try {
+        runCLI(
+          'deepl translate "<p>Hello</p>" --to es --tag-handling xml --outline-detection false --splitting-tags "br,hr" --non-splitting-tags "code" --ignore-tags "script"',
+          { stdio: 'pipe' }
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(/unknown.*option/i);
+      }
+    });
+  });
+
+  describe('table output format', () => {
+    it('should show table format option in help', () => {
+      const helpOutput = translateHelp;
+      expect(helpOutput).toContain('--format <format>');
+      expect(helpOutput).toMatch(/json/i);
+    });
+
+    it('should accept --format table flag without error', () => {
+      expect.assertions(2);
+      try {
+        runCLI('deepl translate "Hello" --to es,fr,de --format table', {
+          stdio: 'pipe',
+        });
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(/unknown.*format.*table/i);
+        expect(output).not.toMatch(/invalid.*format/i);
+      }
+    });
+
+    it('should recognize table format as valid option', () => {
+      expect.assertions(2);
+      try {
+        runCLI('deepl translate "Test" --to es,fr --format table', {
+          stdio: 'pipe',
+        });
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout ?? error.message;
+        expect(output).not.toMatch(/invalid.*format/i);
+        expect(output).not.toMatch(/unknown.*option/i);
+      }
+    });
+
+    it('should work with multiple target languages', () => {
+      expect.assertions(2);
+      try {
+        runCLI(
+          'deepl translate "Hello world" --to es,fr,de,ja --format table',
+          { stdio: 'pipe' }
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(/invalid.*format/i);
+        expect(output).not.toMatch(/unknown.*option/i);
+      }
+    });
+
+    it('should accept table format with other options', () => {
+      expect.assertions(1);
+      try {
+        runCLI(
+          'deepl translate "Test" --to es,fr --format table --formality more --context "Business email"',
+          { stdio: 'pipe' }
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(/invalid.*format/i);
+      }
+    });
+
+    it('should accept table format with --show-billed-characters', () => {
+      expect.assertions(2);
+      try {
+        runCLI(
+          'deepl translate "Test" --to es,fr,de --format table --show-billed-characters --no-cache',
+          { stdio: 'pipe' }
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(/invalid.*format/i);
+        expect(output).not.toMatch(/unknown.*option/i);
+      }
+    });
+  });
+
+  describe('--enable-beta-languages flag (removed)', () => {
+    it('should not appear in help text', () => {
+      const result = translateHelp;
+      expect(result).not.toContain('--enable-beta-languages');
+    });
+
+    it('should be rejected as an unknown option', () => {
+      expect.assertions(1);
+      try {
+        runCLI('deepl translate "Hello" --to es --enable-beta-languages', {
+          stdio: 'pipe',
+        });
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).toMatch(/unknown.*option/i);
+      }
+    });
+  });
+
+  describe('--api-url HTTPS enforcement', () => {
+    const runCLIWithKey = (command: string): string => {
+      return execSync(command, {
+        encoding: 'utf-8',
+        timeout: 3000,
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: testConfigDir,
+          DEEPL_API_KEY: 'fake-key-for-url-validation',
+        },
+      });
+    };
+
+    it('should reject http:// URLs for remote hosts', () => {
+      expect.assertions(2);
+      try {
+        runCLIWithKey(
+          'deepl translate "Hello" --to es --api-url http://evil-server.com/v2'
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).toMatch(/Insecure HTTP URL rejected/i);
+        expect(output).toMatch(/credential exposure/i);
+      }
+    });
+
+    it('should accept https:// URLs', () => {
+      expect.assertions(1);
+      try {
+        runCLIWithKey(
+          'deepl translate "Hello" --to es --api-url https://api-free.deepl.com/v2'
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(/Insecure HTTP URL rejected/i);
+      }
+    });
+
+    it('should allow http://localhost for local testing', () => {
+      expect.assertions(1);
+      try {
+        runCLIWithKey(
+          'deepl translate "Hello" --to es --api-url http://localhost:3000/v2'
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(/Insecure HTTP URL rejected/i);
+      }
+    });
+
+    it('should allow http://127.0.0.1 for local testing', () => {
+      expect.assertions(1);
+      try {
+        runCLIWithKey(
+          'deepl translate "Hello" --to es --api-url http://127.0.0.1:5000/v2'
+        );
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).not.toMatch(/Insecure HTTP URL rejected/i);
+      }
+    });
+  });
+
+  describe('choices validation for enum options', () => {
+    it('should reject invalid --formality value', () => {
+      expect.assertions(8);
+      try {
+        runCLI('deepl translate "Hello" --to es --formality super_formal', {
+          stdio: 'pipe',
+        });
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).toMatch(/--formality/);
+        expect(output).toMatch(/invalid/i);
+        expect(output).toMatch(/Allowed choices/i);
+        expect(output).toContain('default');
+        expect(output).toContain('more');
+        expect(output).toContain('less');
+        expect(output).toContain('prefer_more');
+        expect(output).toContain('prefer_less');
+      }
+    });
+
+    it('should accept all valid --formality values', () => {
+      const validValues = [
+        'default',
+        'more',
+        'less',
+        'prefer_more',
+        'prefer_less',
+      ];
+      expect.assertions(validValues.length);
+      for (const value of validValues) {
+        try {
+          runCLI(`deepl translate "Hello" --to es --formality ${value}`, {
+            stdio: 'pipe',
+          });
+        } catch (error: any) {
+          const output = error.stderr ?? error.stdout ?? '';
+          expect(output).not.toMatch(/invalid.*Allowed choices/i);
+        }
+      }
+    });
+
+    it('should reject invalid --tag-handling value', () => {
+      expect.assertions(5);
+      try {
+        runCLI('deepl translate "Hello" --to es --tag-handling json', {
+          stdio: 'pipe',
+        });
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).toMatch(/--tag-handling/);
+        expect(output).toMatch(/invalid/i);
+        expect(output).toMatch(/Allowed choices/i);
+        expect(output).toContain('xml');
+        expect(output).toContain('html');
+      }
+    });
+
+    it('should accept valid --tag-handling values', () => {
+      const validValues = ['xml', 'html'];
+      expect.assertions(validValues.length);
+      for (const value of validValues) {
+        try {
+          runCLI(
+            `deepl translate "<p>Hello</p>" --to es --tag-handling ${value}`,
+            { stdio: 'pipe' }
+          );
+        } catch (error: any) {
+          const output = error.stderr ?? error.stdout ?? '';
+          expect(output).not.toMatch(/invalid.*Allowed choices/i);
+        }
+      }
+    });
+
+    it('should reject invalid --model-type value', () => {
+      expect.assertions(6);
+      try {
+        runCLI('deepl translate "Hello" --to es --model-type fast', {
+          stdio: 'pipe',
+        });
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).toMatch(/--model-type/);
+        expect(output).toMatch(/invalid/i);
+        expect(output).toMatch(/Allowed choices/i);
+        expect(output).toContain('quality_optimized');
+        expect(output).toContain('prefer_quality_optimized');
+        expect(output).toContain('latency_optimized');
+      }
+    });
+
+    it('should accept valid --model-type values', () => {
+      const validValues = [
+        'quality_optimized',
+        'prefer_quality_optimized',
+        'latency_optimized',
+      ];
+      expect.assertions(validValues.length);
+      for (const value of validValues) {
+        try {
+          runCLI(`deepl translate "Hello" --to es --model-type ${value}`, {
+            stdio: 'pipe',
+          });
+        } catch (error: any) {
+          const output = error.stderr ?? error.stdout ?? '';
+          expect(output).not.toMatch(/invalid.*Allowed choices/i);
+        }
+      }
+    });
+
+    it('should reject invalid --split-sentences value', () => {
+      expect.assertions(6);
+      try {
+        runCLI('deepl translate "Hello" --to es --split-sentences always', {
+          stdio: 'pipe',
+        });
+      } catch (error: any) {
+        const output = error.stderr ?? error.stdout;
+        expect(output).toMatch(/--split-sentences/);
+        expect(output).toMatch(/invalid/i);
+        expect(output).toMatch(/Allowed choices/i);
+        expect(output).toContain('on');
+        expect(output).toContain('off');
+        expect(output).toContain('nonewlines');
+      }
+    });
+
+    it('should accept valid --split-sentences values', () => {
+      const validValues = ['on', 'off', 'nonewlines'];
+      expect.assertions(validValues.length);
+      for (const value of validValues) {
+        try {
+          runCLI(`deepl translate "Hello" --to es --split-sentences ${value}`, {
+            stdio: 'pipe',
+          });
+        } catch (error: any) {
+          const output = error.stderr ?? error.stdout ?? '';
+          expect(output).not.toMatch(/invalid.*Allowed choices/i);
+        }
+      }
+    });
+
+    it('should show choices in help text for constrained options', () => {
+      const helpOutput = translateHelp;
+      expect(helpOutput).toMatch(/--formality.*choices/is);
+      expect(helpOutput).toMatch(/--tag-handling.*choices/is);
+      expect(helpOutput).toMatch(/--model-type.*choices/is);
+      expect(helpOutput).toMatch(/--split-sentences.*choices/is);
+    });
+  });
+});
diff --git a/tests/integration/cli-translate.integration.test.ts b/tests/integration/cli-translate.integration.test.ts
index 68ec9db7..89fe7751 100644
--- a/tests/integration/cli-translate.integration.test.ts
+++ b/tests/integration/cli-translate.integration.test.ts
@@ -1,17 +1,14 @@
 /**
- * Integration Tests for Translate CLI Command
- * Tests the translate command CLI behavior, argument validation, and error handling
+ * Integration Tests for Translation Memory wiring on `deepl translate`
+ * Drives handler -> resolver -> service -> HTTP in-process against nock.
+ * CLI flag handling lives in tests/e2e/cli-translate-flags.e2e.test.ts.
  */
 
-import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import nock from 'nock';
 import {
-  createTestConfigDir,
-  createTestDir,
-  makeRunCLI,
   DEEPL_FREE_API_URL,
   TEST_API_KEY,
   createMockConfigService,
@@ -29,1026 +26,6 @@ import type {
 } from '../../src/cli/commands/translate/types';
 import type { BatchTranslationService } from '../../src/services/batch-translation';
 
-describe('Translate CLI Integration', () => {
-  const testConfig = createTestConfigDir('test-translate');
-  const testFiles = createTestDir('translate-files');
-  const testConfigDir = testConfig.path;
-  const testDir = testFiles.path;
-  const { runCLI } = makeRunCLI(testConfig.path);
-
-  // Cache help outputs to avoid redundant process spawns (~25 duplicate calls eliminated)
-  let translateHelp: string;
-  let mainHelp: string;
-  let styleRulesHelp: string;
-  let styleRulesListHelp: string;
-
-  beforeAll(() => {
-    translateHelp = runCLI('deepl translate --help');
-    mainHelp = runCLI('deepl --help');
-    styleRulesHelp = runCLI('deepl style-rules --help');
-    styleRulesListHelp = runCLI('deepl style-rules list --help');
-  });
-
-  afterAll(() => {
-    testConfig.cleanup();
-    testFiles.cleanup();
-  });
-
-  describe('deepl translate --help', () => {
-    it('should display help for translate command', () => {
-      const output = translateHelp;
-
-      expect(output).toContain('Usage:');
-      expect(output).toContain('deepl translate');
-      expect(output).toContain('Translate text, files, or directories');
-      expect(output).toContain('--to');
-      expect(output).toContain('--from');
-      expect(output).toContain('--output');
-      expect(output).toContain('--formality');
-      expect(output).toContain('--preserve-code');
-      expect(output).toContain('--context');
-      expect(output).toContain('--split-sentences');
-      expect(output).toContain('--tag-handling');
-      expect(output).toContain('--model-type');
-    });
-  });
-
-  describe('deepl translate without API key', () => {
-    it('should require API key to be configured', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello" --to es', { excludeApiKey: true });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should indicate API key is required
-        expect(output).toMatch(/API key|auth|not set/i);
-      }
-    });
-  });
-
-  describe('required arguments validation', () => {
-    it('should require --to flag or config default for translation', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/target language|--to/i);
-      }
-    });
-
-    it('should accept text argument with --to flag', () => {
-      const helpOutput = translateHelp;
-      // Verify command structure accepts text argument
-      expect(helpOutput).toContain('[text]');
-      expect(helpOutput).toContain('--to <language>');
-    });
-  });
-
-  describe('default target language from config', () => {
-    const runCLINoApiKey = (
-      command: string,
-      options: { stdio?: any } = {}
-    ): string => {
-      const env: Record<string, string | undefined> = {
-        ...process.env,
-        DEEPL_CONFIG_DIR: testConfigDir,
-      };
-      delete env['DEEPL_API_KEY'];
-      return execSync(command, {
-        encoding: 'utf-8',
-        env,
-        ...options,
-      });
-    };
-
-    it('should show error mentioning both --to and config when neither is set', () => {
-      // Clear any config that might have targetLangs set
-      const configPath = path.join(testConfigDir, 'config.json');
-      if (fs.existsSync(configPath)) {
-        fs.unlinkSync(configPath);
-      }
-
-      expect.assertions(2);
-      try {
-        runCLINoApiKey('deepl translate "Hello"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/--to/);
-        expect(output).toMatch(/deepl init/);
-      }
-    });
-
-    it('should use config default target language when --to is omitted', () => {
-      const configPath = path.join(testConfigDir, 'config.json');
-      const config = {
-        auth: {},
-        api: { baseUrl: 'https://api.deepl.com', usePro: true },
-        defaults: {
-          targetLangs: ['es'],
-          formality: 'default',
-          preserveFormatting: true,
-        },
-        cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
-        output: { format: 'text', verbose: false, color: true },
-        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
-      };
-      fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
-
-      expect.assertions(1);
-      try {
-        // Without --to, should fall back to config default 'es'
-        // Will still fail because no API key, but should NOT fail on missing --to
-        runCLINoApiKey('deepl translate "Hello"', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on API key, not on missing target language
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-  });
-
-  describe('file translation validation', () => {
-    it('should require --output flag for file translation', () => {
-      // Create a test file
-      const testFile = path.join(testDir, 'test.txt');
-      fs.writeFileSync(testFile, 'Hello world', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl translate "${testFile}" --to es`, { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Will fail on API key or output requirement
-        expect(output).toMatch(/API key|auth|output/i);
-      }
-    });
-
-    it('should accept file path with --to and --output flags', () => {
-      const testFile = path.join(testDir, 'test2.txt');
-      const outputFile = path.join(testDir, 'output.txt');
-      fs.writeFileSync(testFile, 'Hello', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        // This will fail without API key, but should recognize valid arguments
-        runCLI(
-          `deepl translate "${testFile}" --to es --output "${outputFile}"`,
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/output.*required/i);
-      }
-    });
-
-    it('should handle non-existent file gracefully', () => {
-      const nonExistentFile = path.join(testDir, 'does-not-exist.txt');
-
-      expect.assertions(1);
-      try {
-        runCLI(
-          `deepl translate "${nonExistentFile}" --to es --output output.txt`,
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should indicate file not found or API key missing
-        expect(output).toMatch(/not found|does not exist|API key|auth/i);
-      }
-    });
-  });
-
-  describe('directory translation validation', () => {
-    it('should require --output flag for directory translation', () => {
-      // Create a test directory with files
-      const testSubDir = path.join(testDir, 'subdir');
-      fs.mkdirSync(testSubDir, { recursive: true });
-      fs.writeFileSync(
-        path.join(testSubDir, 'file1.txt'),
-        'Content 1',
-        'utf-8'
-      );
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl translate "${testSubDir}" --to es`, { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Will fail on API key or output requirement
-        expect(output).toMatch(/API key|auth|output/i);
-      }
-    });
-
-    it('should accept directory path with --to and --output flags', () => {
-      const testSubDir2 = path.join(testDir, 'subdir2');
-      const outputDir = path.join(testDir, 'output-dir');
-      fs.mkdirSync(testSubDir2, { recursive: true });
-      fs.writeFileSync(path.join(testSubDir2, 'file1.txt'), 'Content', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        // This will fail without API key, but should recognize valid arguments
-        runCLI(
-          `deepl translate "${testSubDir2}" --to es --output "${outputDir}"`,
-          { stdio: 'pipe' }
-        );
-        // CLI accepted the arguments without error
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        // Should fail on API key, not argument validation
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-  });
-
-  describe('option flags validation', () => {
-    it.each([
-      { flag: '--from <language>', description: 'Source language' },
-      { flag: '--formality <level>', descriptionPattern: /more.*less/i },
-      { flag: '--preserve-code', description: 'code blocks' },
-      { flag: '--context <text>', description: 'context' },
-      {
-        flag: '--split-sentences <mode>',
-        descriptionPattern: /on.*off.*nonewlines/i,
-      },
-      { flag: '--tag-handling <mode>', descriptionPattern: /xml.*html/i },
-      {
-        flag: '--model-type <type>',
-        descriptionPattern: /quality_optimized|latency_optimized/i,
-      },
-      { flag: '--no-recursive', description: 'subdirectories' },
-      { flag: '--pattern <pattern>', description: 'Glob pattern' },
-      { flag: '--concurrency <number>', description: 'parallel' },
-      { flag: '--api-url <url>', description: 'Custom API endpoint' },
-    ])(
-      'should accept $flag flag',
-      ({ flag, description, descriptionPattern }) => {
-        const helpOutput = translateHelp;
-        expect(helpOutput).toContain(flag);
-        if (description) {
-          expect(helpOutput).toContain(description);
-        }
-        if (descriptionPattern) {
-          expect(helpOutput).toMatch(descriptionPattern);
-        }
-      }
-    );
-  });
-
-  describe('multiple target languages', () => {
-    it('should accept comma-separated target languages', () => {
-      const helpOutput = translateHelp;
-      expect(helpOutput).toContain('--to <language>');
-      expect(helpOutput).toContain('comma-separated');
-    });
-
-    it('should validate comma-separated format', () => {
-      // Help should indicate comma-separated format is supported
-      const helpOutput = translateHelp;
-      expect(helpOutput).toContain('comma-separated');
-    });
-  });
-
-  describe('command structure', () => {
-    it('should be available as a command', () => {
-      const helpOutput = mainHelp;
-
-      // Translate command should be listed in main help
-      expect(helpOutput).toContain('translate');
-      expect(helpOutput).toContain('Translate text, files, or directories');
-    });
-
-    it('should accept text as optional argument', () => {
-      const output = translateHelp;
-
-      // Text should be optional (can use stdin)
-      // Shown in usage line as [text]
-      expect(output).toContain('translate|t [options] [text]');
-      expect(output).toContain('Arguments:');
-    });
-
-    it('should support stdin input', () => {
-      const output = translateHelp;
-
-      // Help should mention stdin
-      expect(output).toMatch(/stdin|read from stdin/i);
-    });
-  });
-
-  describe('error messages', () => {
-    it('should show clear error when --to omitted and no config default', () => {
-      // Clear config to ensure no default targetLangs
-      const configPath = path.join(testConfigDir, 'config.json');
-      if (fs.existsSync(configPath)) {
-        fs.unlinkSync(configPath);
-      }
-
-      const env = { ...process.env, DEEPL_CONFIG_DIR: testConfigDir };
-      (env as Record<string, string | undefined>)['DEEPL_API_KEY'] = undefined;
-
-      expect.assertions(1);
-      try {
-        execSync('deepl translate "Hello"', {
-          encoding: 'utf-8',
-          env,
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/--to|target/i);
-      }
-    });
-
-    it('should show clear error for file without output', () => {
-      const testFile = path.join(testDir, 'error-test.txt');
-      fs.writeFileSync(testFile, 'Test', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        runCLI(`deepl translate "${testFile}" --to es`, { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth|output/i);
-      }
-    });
-  });
-
-  describe('file type support', () => {
-    it('should support .txt files', () => {
-      const txtFile = path.join(testDir, 'test.txt');
-      const outputFile = path.join(testDir, 'output.txt');
-      fs.writeFileSync(txtFile, 'Test content', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should recognize file type
-        runCLI(
-          `deepl translate "${txtFile}" --to es --output "${outputFile}"`,
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unsupported.*file/i);
-      }
-    });
-
-    it('should support .md files', () => {
-      const mdFile = path.join(testDir, 'test.md');
-      const outputFile = path.join(testDir, 'output.md');
-      fs.writeFileSync(mdFile, '# Test\n\nContent', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        // Will fail without API key but should recognize file type
-        runCLI(`deepl translate "${mdFile}" --to es --output "${outputFile}"`, {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unsupported.*file/i);
-      }
-    });
-  });
-
-  describe('output format', () => {
-    it('should support --format option', () => {
-      // Help should show --format option
-      const output = translateHelp;
-      expect(output).toContain('--format <format>');
-      expect(output).toContain('json');
-      expect(output).toContain('text');
-    });
-  });
-
-  describe('billed characters', () => {
-    it('should show --show-billed-characters flag in help', () => {
-      const helpOutput = translateHelp;
-      expect(helpOutput).toContain('--show-billed-characters');
-      expect(helpOutput).toMatch(/billed.*character/i);
-      expect(helpOutput).toMatch(/cost.*transparency/i);
-    });
-
-    it('should accept --show-billed-characters flag without error', () => {
-      // Verify the flag is recognized (will fail on API key but shouldn't error on unknown flag)
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello" --to es --show-billed-characters', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*show-billed-characters/i);
-      }
-    });
-  });
-
-  describe('document minification', () => {
-    it('should show --enable-minification flag in help', () => {
-      const helpOutput = translateHelp;
-      expect(helpOutput).toContain('--enable-minification');
-      expect(helpOutput).toMatch(/minification/i);
-      expect(helpOutput).toMatch(/pptx|docx/i);
-    });
-
-    it('should accept --enable-minification flag without error', () => {
-      // Create a test PPTX file (mock)
-      const pptxFile = path.join(testDir, 'presentation.pptx');
-      const outputFile = path.join(testDir, 'output.pptx');
-      fs.writeFileSync(pptxFile, 'Mock PPTX content', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        runCLI(
-          `deepl translate "${pptxFile}" --to es --output "${outputFile}" --enable-minification`,
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option.*enable-minification/i);
-      }
-    });
-
-    it('should recognize --enable-minification flag in command', () => {
-      // Verify the flag doesn't cause "unknown option" error
-      const pptxFile = path.join(testDir, 'test.pptx');
-      const outputFile = path.join(testDir, 'out.pptx');
-      fs.writeFileSync(pptxFile, 'content', 'utf-8');
-
-      expect.assertions(1);
-      try {
-        runCLI(
-          `deepl translate "${pptxFile}" --to fr --output "${outputFile}" --enable-minification`,
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout ?? error.message;
-        // Should not contain unknown option error
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-  });
-
-  describe('XML tag handling parameters', () => {
-    it.each([
-      {
-        flag: '--outline-detection',
-        patterns: [/xml.*structure.*detection/i, /tag-handling.*xml/i],
-      },
-      {
-        flag: '--splitting-tags',
-        patterns: [/xml.*tags.*split/i],
-      },
-      {
-        flag: '--non-splitting-tags',
-        patterns: [/should not be used to split sentences/i],
-        normalizeWhitespace: true,
-      },
-      {
-        flag: '--ignore-tags',
-        patterns: [/ignore/i],
-      },
-    ])(
-      'should show $flag flag in help',
-      ({ flag, patterns, normalizeWhitespace }) => {
-        const helpOutput = translateHelp;
-        expect(helpOutput).toContain(flag);
-        for (const pattern of patterns) {
-          const text = normalizeWhitespace
-            ? helpOutput.replace(/\s+/g, ' ')
-            : helpOutput;
-          expect(text).toMatch(pattern);
-        }
-      }
-    );
-
-    it.each([
-      {
-        flag: '--outline-detection',
-        args: '--outline-detection true',
-      },
-      {
-        flag: '--splitting-tags',
-        args: '--splitting-tags "br,hr,div"',
-      },
-      {
-        flag: '--non-splitting-tags',
-        args: '--non-splitting-tags "code,pre"',
-      },
-      {
-        flag: '--ignore-tags',
-        args: '--ignore-tags "script,style"',
-      },
-    ])('should accept $flag flag without error', ({ flag, args }) => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          `deepl translate "<p>Hello</p>" --to es --tag-handling xml ${args}`,
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(
-          new RegExp(`unknown.*option.*${flag.replace('--', '')}`, 'i')
-        );
-      }
-    });
-
-    it('should accept all XML tag handling flags together', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl translate "<p>Hello</p>" --to es --tag-handling xml --outline-detection false --splitting-tags "br,hr" --non-splitting-tags "code" --ignore-tags "script"',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-  });
-
-  describe('table output format', () => {
-    it('should show table format option in help', () => {
-      const helpOutput = translateHelp;
-      expect(helpOutput).toContain('--format <format>');
-      expect(helpOutput).toMatch(/json/i);
-    });
-
-    it('should accept --format table flag without error', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl translate "Hello" --to es,fr,de --format table', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*format.*table/i);
-        expect(output).not.toMatch(/invalid.*format/i);
-      }
-    });
-
-    it('should recognize table format as valid option', () => {
-      expect.assertions(2);
-      try {
-        runCLI('deepl translate "Test" --to es,fr --format table', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout ?? error.message;
-        expect(output).not.toMatch(/invalid.*format/i);
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-
-    it('should work with multiple target languages', () => {
-      expect.assertions(2);
-      try {
-        runCLI(
-          'deepl translate "Hello world" --to es,fr,de,ja --format table',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/invalid.*format/i);
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-
-    it('should accept table format with other options', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl translate "Test" --to es,fr --format table --formality more --context "Business email"',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/invalid.*format/i);
-      }
-    });
-
-    it('should accept table format with --show-billed-characters', () => {
-      expect.assertions(2);
-      try {
-        runCLI(
-          'deepl translate "Test" --to es,fr,de --format table --show-billed-characters --no-cache',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/invalid.*format/i);
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-  });
-
-  describe('--custom-instruction flag', () => {
-    it('should display --custom-instruction in help text', () => {
-      const output = translateHelp;
-      expect(output).toContain('--custom-instruction');
-    });
-
-    it('should accept a single --custom-instruction flag', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl translate "Hello" --to es --custom-instruction "Use informal tone"',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-
-    it('should accept multiple --custom-instruction flags', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl translate "Hello" --to es --custom-instruction "Use informal tone" --custom-instruction "Preserve brand names"',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-
-    it('should accept --custom-instruction with other options', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl translate "Hello" --to es --formality more --custom-instruction "Keep it formal" --model-type quality_optimized',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-  });
-
-  describe('--style-id flag', () => {
-    it('should show --style-id in help text', () => {
-      const result = translateHelp;
-      expect(result).toContain('--style-id');
-    });
-
-    it('should accept --style-id flag', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello" --to es --style-id "abc-123-def"', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-
-    it('should accept --style-id with other options', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl translate "Hello" --to es --style-id "abc-123" --formality more',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-  });
-
-  describe('--enable-beta-languages flag (removed)', () => {
-    it('should not appear in help text', () => {
-      const result = translateHelp;
-      expect(result).not.toContain('--enable-beta-languages');
-    });
-
-    it('should be rejected as an unknown option', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello" --to es --enable-beta-languages', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/unknown.*option/i);
-      }
-    });
-  });
-
-  describe('style-rules command', () => {
-    it('should show style-rules in main help', () => {
-      const result = mainHelp;
-      expect(result).toContain('style-rules');
-    });
-
-    it('should show list subcommand in style-rules help', () => {
-      const result = styleRulesHelp;
-      expect(result).toContain('list');
-    });
-
-    it('should show --detailed flag in style-rules list help', () => {
-      const result = styleRulesListHelp;
-      expect(result).toContain('--detailed');
-      expect(result).toContain('--page');
-      expect(result).toContain('--page-size');
-      expect(result).toContain('--format');
-    });
-
-    it('should require API key for style-rules list', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl style-rules list', {
-          stdio: 'pipe',
-          excludeApiKey: true,
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/API key|auth/i);
-      }
-    });
-  });
-
-  describe('expanded language support', () => {
-    it('should accept extended language codes', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello" --to sw', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Invalid target language/i);
-      }
-    });
-
-    it('should accept ES-419 target variant', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello" --to es-419', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Invalid target language/i);
-      }
-    });
-
-    it('should accept zh-hans and zh-hant variants', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello" --to zh-hans', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Invalid target language/i);
-      }
-    });
-
-    it('should accept newly added core languages (he, vi)', () => {
-      expect.assertions(1);
-      try {
-        runCLI('deepl translate "Hello" --to he', { stdio: 'pipe' });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Invalid target language/i);
-      }
-    });
-  });
-
-  describe('--tag-handling-version flag', () => {
-    it('should show --tag-handling-version in help text', () => {
-      const result = translateHelp;
-      expect(result).toContain('--tag-handling-version');
-    });
-
-    it('should accept --tag-handling-version with --tag-handling', () => {
-      expect.assertions(1);
-      try {
-        runCLI(
-          'deepl translate "<p>Hello</p>" --to es --tag-handling html --tag-handling-version v2',
-          { stdio: 'pipe' }
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/unknown.*option/i);
-      }
-    });
-  });
-
-  describe('--api-url HTTPS enforcement', () => {
-    const runCLIWithKey = (command: string): string => {
-      return execSync(command, {
-        encoding: 'utf-8',
-        timeout: 3000,
-        env: {
-          ...process.env,
-          DEEPL_CONFIG_DIR: testConfigDir,
-          DEEPL_API_KEY: 'fake-key-for-url-validation',
-        },
-      });
-    };
-
-    it('should reject http:// URLs for remote hosts', () => {
-      expect.assertions(2);
-      try {
-        runCLIWithKey(
-          'deepl translate "Hello" --to es --api-url http://evil-server.com/v2'
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/Insecure HTTP URL rejected/i);
-        expect(output).toMatch(/credential exposure/i);
-      }
-    });
-
-    it('should accept https:// URLs', () => {
-      expect.assertions(1);
-      try {
-        runCLIWithKey(
-          'deepl translate "Hello" --to es --api-url https://api-free.deepl.com/v2'
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Insecure HTTP URL rejected/i);
-      }
-    });
-
-    it('should allow http://localhost for local testing', () => {
-      expect.assertions(1);
-      try {
-        runCLIWithKey(
-          'deepl translate "Hello" --to es --api-url http://localhost:3000/v2'
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Insecure HTTP URL rejected/i);
-      }
-    });
-
-    it('should allow http://127.0.0.1 for local testing', () => {
-      expect.assertions(1);
-      try {
-        runCLIWithKey(
-          'deepl translate "Hello" --to es --api-url http://127.0.0.1:5000/v2'
-        );
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).not.toMatch(/Insecure HTTP URL rejected/i);
-      }
-    });
-  });
-
-  describe('choices validation for enum options', () => {
-    it('should reject invalid --formality value', () => {
-      expect.assertions(8);
-      try {
-        runCLI('deepl translate "Hello" --to es --formality super_formal', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/--formality/);
-        expect(output).toMatch(/invalid/i);
-        expect(output).toMatch(/Allowed choices/i);
-        expect(output).toContain('default');
-        expect(output).toContain('more');
-        expect(output).toContain('less');
-        expect(output).toContain('prefer_more');
-        expect(output).toContain('prefer_less');
-      }
-    });
-
-    it('should accept all valid --formality values', () => {
-      const validValues = [
-        'default',
-        'more',
-        'less',
-        'prefer_more',
-        'prefer_less',
-      ];
-      expect.assertions(validValues.length);
-      for (const value of validValues) {
-        try {
-          runCLI(`deepl translate "Hello" --to es --formality ${value}`, {
-            stdio: 'pipe',
-          });
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout ?? '';
-          expect(output).not.toMatch(/invalid.*Allowed choices/i);
-        }
-      }
-    });
-
-    it('should reject invalid --tag-handling value', () => {
-      expect.assertions(5);
-      try {
-        runCLI('deepl translate "Hello" --to es --tag-handling json', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/--tag-handling/);
-        expect(output).toMatch(/invalid/i);
-        expect(output).toMatch(/Allowed choices/i);
-        expect(output).toContain('xml');
-        expect(output).toContain('html');
-      }
-    });
-
-    it('should accept valid --tag-handling values', () => {
-      const validValues = ['xml', 'html'];
-      expect.assertions(validValues.length);
-      for (const value of validValues) {
-        try {
-          runCLI(
-            `deepl translate "<p>Hello</p>" --to es --tag-handling ${value}`,
-            { stdio: 'pipe' }
-          );
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout ?? '';
-          expect(output).not.toMatch(/invalid.*Allowed choices/i);
-        }
-      }
-    });
-
-    it('should reject invalid --model-type value', () => {
-      expect.assertions(6);
-      try {
-        runCLI('deepl translate "Hello" --to es --model-type fast', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/--model-type/);
-        expect(output).toMatch(/invalid/i);
-        expect(output).toMatch(/Allowed choices/i);
-        expect(output).toContain('quality_optimized');
-        expect(output).toContain('prefer_quality_optimized');
-        expect(output).toContain('latency_optimized');
-      }
-    });
-
-    it('should accept valid --model-type values', () => {
-      const validValues = [
-        'quality_optimized',
-        'prefer_quality_optimized',
-        'latency_optimized',
-      ];
-      expect.assertions(validValues.length);
-      for (const value of validValues) {
-        try {
-          runCLI(`deepl translate "Hello" --to es --model-type ${value}`, {
-            stdio: 'pipe',
-          });
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout ?? '';
-          expect(output).not.toMatch(/invalid.*Allowed choices/i);
-        }
-      }
-    });
-
-    it('should reject invalid --split-sentences value', () => {
-      expect.assertions(6);
-      try {
-        runCLI('deepl translate "Hello" --to es --split-sentences always', {
-          stdio: 'pipe',
-        });
-      } catch (error: any) {
-        const output = error.stderr ?? error.stdout;
-        expect(output).toMatch(/--split-sentences/);
-        expect(output).toMatch(/invalid/i);
-        expect(output).toMatch(/Allowed choices/i);
-        expect(output).toContain('on');
-        expect(output).toContain('off');
-        expect(output).toContain('nonewlines');
-      }
-    });
-
-    it('should accept valid --split-sentences values', () => {
-      const validValues = ['on', 'off', 'nonewlines'];
-      expect.assertions(validValues.length);
-      for (const value of validValues) {
-        try {
-          runCLI(`deepl translate "Hello" --to es --split-sentences ${value}`, {
-            stdio: 'pipe',
-          });
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout ?? '';
-          expect(output).not.toMatch(/invalid.*Allowed choices/i);
-        }
-      }
-    });
-
-    it('should show choices in help text for constrained options', () => {
-      const helpOutput = translateHelp;
-      expect(helpOutput).toMatch(/--formality.*choices/is);
-      expect(helpOutput).toMatch(/--tag-handling.*choices/is);
-      expect(helpOutput).toMatch(/--model-type.*choices/is);
-      expect(helpOutput).toMatch(/--split-sentences.*choices/is);
-    });
-  });
-});
-
 /**
  * Translation Memory wiring — full-stack integration coverage.
  *

From 85c26fd8dfe6cdc9435fbfbc023919ed5d1f90a9 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 10:45:56 +0200
Subject: [PATCH 107/256] test: name the watch service suite for what it tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cli-watch.integration.test.ts drives WatchService in-process; its docblock and
its top-level describe both already said "Watch Service". Only the filename
suggested a CLI suite, which is why the earlier pass mistook it for a duplicate
of cli-watch.e2e.test.ts and why a grep for CLI call sites keeps surfacing it.

Pure rename: no content change, 32 tests unchanged, suite totals unchanged. The
three CLI call sites it does have are `watch --help` and the git-staged
scenarios, which belong with the service tests around them.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ...atch.integration.test.ts => watch-service.integration.test.ts} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename tests/integration/{cli-watch.integration.test.ts => watch-service.integration.test.ts} (100%)

diff --git a/tests/integration/cli-watch.integration.test.ts b/tests/integration/watch-service.integration.test.ts
similarity index 100%
rename from tests/integration/cli-watch.integration.test.ts
rename to tests/integration/watch-service.integration.test.ts

From 29aa376c0bc047e4300a8b99c9efc5cc54596c3c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 11:11:45 +0200
Subject: [PATCH 108/256] fix(translate): resolve a directory --output for a
 single target language
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`deepl translate t.md --to ko --output dir/` failed with EISDIR at exit 1,
while `--to ko,ja --output dir/` wrote dir/t.ko.md and dir/t.ja.md. --output is
documented as a file path or a directory, so the single-target branch -- the
common one -- was the half that contradicted the documentation.

The multi-target branch passed --output as `outputDir` and derived
<stem>.<lang>.<ext> inside it. Single-target used the destination verbatim, so
the atomic rename landed on the directory. The decision was made at each write
site -- the text write, the structured-file service call, the document upload,
the non-text fallback -- which is why the same defect existed four times over
and why a trailing slash made no difference.

resolveFileOutputPath() now makes that decision once, before any branch runs: a
directory takes the multi-target naming, so two locales into one directory
cannot collide. `dir` and `dir/` are the same thing, since the test is
statSync().isDirectory() rather than a trailing slash; a trailing slash also
creates the directory when it is missing, which is what multi-target already
did. A converted document is named by --output-format, because that flag
decides what the bytes are, and only the document path is passed the override --
the text path ignores the flag, so naming a text file .docx would have lied
about its contents. `--output -` returns before touching the filesystem, and a
path that does not exist still means "file to create".

Routing now resolves to two booleans before the branches, which also drops the
duplicated isDocumentSupported() call.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +
 README.md                                     |   4 +
 docs/API.md                                   |   2 +-
 .../translate/file-translation-handler.ts     |  60 ++++---
 src/cli/commands/translate/translate-utils.ts |  36 +++++
 tests/e2e/cli-success-paths.e2e.test.ts       |  67 ++++++++
 tests/unit/file-translation-handler.test.ts   | 151 ++++++++++++++++++
 tests/unit/translate-utils.test.ts            |  80 ++++++++++
 8 files changed, 382 insertions(+), 20 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 56f333f3..f6b99f08 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **translate**: **`--output <dir>` failed with `EISDIR` for a single target language, though it worked for two or more.** `--output` is documented as a file path *or* a directory, and the multi-target branch honoured that — `--to ko,ja --output dir/` wrote `dir/t.ko.md` and `dir/t.ja.md` — while the single-target branch used the destination verbatim and let the atomic rename land on the directory: `Error: EISDIR: illegal operation on a directory, rename 'dir/.tmp.59970.vmrlp5' -> 'dir/'`, exit 1. Two branches of the same command disagreed, and the one that contradicted the documentation was the common one. It affected text files, structured files (JSON/YAML) and documents alike, because each branch decided the destination at its own call site. The destination is now resolved once, ahead of every branch, and a directory names the file the way multi-target translation already does: `deepl translate t.md --to ko --output dir/` writes `dir/t.ko.md`, so two locales into one directory cannot collide. `dir` and `dir/` behave identically — the check is `statSync().isDirectory()`, not a trailing-slash test — and a trailing slash additionally creates the directory when it does not exist, matching multi-target. A converted document is named by `--output-format` (`report.pdf --to de --output-format docx --output dir/` writes `dir/report.de.docx`), since that flag decides what the bytes are. `--output -` and a non-existent path such as `--output out/new.md` are unaffected. Pre-existing, not a regression. `examples/03-batch-processing.sh` hit this in five places and hid four of them behind `2>/dev/null`, `|| true` and a `(cached or completed)` message that reported a cache hit for a call that had errored — so `npm run examples` reported 37/37 passed while this was broken; those guards are gone, and section 8's cache comparison now times calls that actually succeed.
+
 - **sync**: **`deepl sync resolve` kept the local side of every merge conflict, silently discarding a teammate's newer translations.** The documented rule — take the newer translation by `translated_at` — never fired on a real `.deepl-sync.lock`. The leaf test treated any object carrying `source_hash` as a translation to compare, and every lockfile entry carries one, so the resolver read `translated_at` on the entry, where it does not exist; the real timestamp lives on each locale inside that entry's `translations` map, and the recursion that would have reached it was never taken. Each conflict was therefore reported as `kept ours: neither side had translated_at` and resolved to ours, at exit code 0 and without the `length-heuristic` tag that exists to mark exactly this kind of unreliable decision — so the per-entry report gave no sign that anything had been dropped. An entry holding a `translations` map is now treated as a container and merged one locale at a time, which is where the timestamps are, and the report names the locale it decided (`greeting.translations.de`) rather than the entry. Fields the two sides agree on are no longer listed as conflicts. The existing tests passed throughout because their fixtures put `translated_at` directly on the entry, a shape `SyncLockManager` does not write; the suite now also drives the shape it does.
 
 - **docs**: Five documentation inaccuracies found in the pre-2.0 audit. `docs/API.md` and `README.md` still said the **last** `--glossary` wins a conflicting term, contradicting the same files, the flag's own help text, and the verified behaviour — which mapping wins is the API's choice and does not follow flag order. `docs/API.md`'s command-group table omitted `correct` while claiming to match `deepl --help`, and the README's table of contents omitted its Spelling and Grammar Correction section. `docs/API.md`'s environment-variable reference omitted `NO_PROXY`, which the HTTP client honours and the README already documented. `docs/TROUBLESHOOTING.md` attributed "Translation cache backend failed to load" to running Node.js < 24, which the startup version check now rejects earlier with its own message, so the stated cause was unreachable; that entry now describes the reachable case (a v24+ runtime with no usable `node:sqlite`) and the version error is documented under exit code 6, where it previously appeared nowhere.
diff --git a/README.md b/README.md
index 3b39fce0..16c58d0f 100644
--- a/README.md
+++ b/README.md
@@ -327,6 +327,10 @@ Small text-based files (under 100 KiB) automatically use the cached text transla
 deepl translate README.md --to es --output README.es.md
 # Translated README.md -> README.es.md
 
+# Output directory (names the file <name>.<lang>.<ext>)
+deepl translate README.md --to es --output ./translated/
+# Translated README.md -> translated/README.es.md
+
 # Multiple target languages (creates README.es.md, README.fr.md, etc.)
 deepl translate docs.md --to es,fr,de --output ./translated/
 # Translated docs.md to 3 languages:
diff --git a/docs/API.md b/docs/API.md
index a6c51983..b2ef06e1 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -232,7 +232,7 @@ Translate text directly, from stdin, from files, or entire directories. Supports
 
 **Output Options:**
 
-- `--output, -o PATH` - Output file or directory (required for file/directory translation, optional for text). Use `-` for stdout (text-based files only)
+- `--output, -o PATH` - Output file or directory (required for file/directory translation, optional for text). A directory receives `<name>.<lang>.<ext>` — `deepl translate README.md --to es --output docs/` writes `docs/README.es.md`, and a trailing slash creates the directory if it does not exist. Use `-` for stdout (text-based files only)
 - `--output-format FORMAT` - Convert PDF to DOCX during translation. Valid choices: `docx` (only supported conversion)
 - `--enable-minification` - Enable document minification for PPTX/DOCX files (reduces file size)
 - `--format FORMAT` - Output format: `text`, `json`, `table` (default: `text`)
diff --git a/src/cli/commands/translate/file-translation-handler.ts b/src/cli/commands/translate/file-translation-handler.ts
index 8b6a240a..53f7cf1f 100644
--- a/src/cli/commands/translate/file-translation-handler.ts
+++ b/src/cli/commands/translate/file-translation-handler.ts
@@ -11,6 +11,7 @@ import {
   isTextBasedFile,
   isStructuredFile,
   getFileSize,
+  resolveFileOutputPath,
   SAFE_TEXT_SIZE_LIMIT,
 } from './translate-utils.js';
 import {
@@ -31,13 +32,14 @@ export class FileTranslationHandler {
     options: TranslateOptions,
     cachedStats?: fs.Stats | null
   ): Promise<string> {
-    if (!options.output) {
+    const requestedOutput = options.output;
+    if (!requestedOutput) {
       throw new ValidationError(
         'Output file path is required for file translation. Use --output <path>'
       );
     }
 
-    const stdoutMode = options.output === '-';
+    const stdoutMode = requestedOutput === '-';
 
     if (options.to.includes(',') && stdoutMode) {
       throw new ValidationError(
@@ -96,13 +98,11 @@ export class FileTranslationHandler {
       );
     }
 
+    let useTextTranslation = false;
+    let oversizeWarning: string | null = null;
+
     if (isTextBasedFile(filePath)) {
-      let fileSize: number | null;
-      if (cachedStats) {
-        fileSize = cachedStats.size;
-      } else {
-        fileSize = getFileSize(filePath);
-      }
+      const fileSize = cachedStats ? cachedStats.size : getFileSize(filePath);
 
       if (fileSize === null) {
         throw new ValidationError(
@@ -111,22 +111,44 @@ export class FileTranslationHandler {
       }
 
       if (fileSize <= SAFE_TEXT_SIZE_LIMIT) {
-        return this.translateTextFile(filePath, options);
+        useTextTranslation = true;
       } else if (
         this.ctx.documentTranslationService.isDocumentSupported(filePath)
       ) {
         const fileSizeKiB = (fileSize / 1024).toFixed(1);
-        const warning = `⚠ File exceeds 100 KiB limit for cached translation (${fileSizeKiB} KiB), using document API instead`;
-        Logger.warn(warning);
-        const result = await this.documentHandler.translateDocument(
-          filePath,
-          options
-        );
-        return `${warning}\n${result}`;
+        oversizeWarning = `⚠ File exceeds 100 KiB limit for cached translation (${fileSizeKiB} KiB), using document API instead`;
       }
     }
 
-    if (this.ctx.documentTranslationService.isDocumentSupported(filePath)) {
+    const useDocumentApi =
+      !useTextTranslation &&
+      this.ctx.documentTranslationService.isDocumentSupported(filePath);
+
+    // Resolved once, ahead of every branch below: each of them writes to
+    // options.output, so deciding this per branch is what let a directory
+    // destination reach the write unnoticed.
+    const outputPath = resolveFileOutputPath(
+      filePath,
+      requestedOutput,
+      options.to,
+      useDocumentApi ? options.outputFormat : undefined
+    );
+    options = { ...options, output: outputPath };
+
+    if (useTextTranslation) {
+      return this.translateTextFile(filePath, options);
+    }
+
+    if (oversizeWarning) {
+      Logger.warn(oversizeWarning);
+      const result = await this.documentHandler.translateDocument(
+        filePath,
+        options
+      );
+      return `${oversizeWarning}\n${result}`;
+    }
+
+    if (useDocumentApi) {
       return this.documentHandler.translateDocument(filePath, options);
     }
 
@@ -142,12 +164,12 @@ export class FileTranslationHandler {
 
     await this.ctx.fileTranslationService.translateFile(
       filePath,
-      options.output,
+      outputPath,
       translationOptions,
       { preserveCode: options.preserveCode }
     );
 
-    return `Translated ${filePath} -> ${options.output}`;
+    return `Translated ${filePath} -> ${outputPath}`;
   }
 
   async translateTextFile(
diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index a6fa90a7..66b76ac0 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -317,6 +317,42 @@ export function isStructuredFile(filePath: string): boolean {
   return STRUCTURED_EXTENSIONS.includes(ext);
 }
 
+/**
+ * Resolves --output for a single target language. A directory names the file the
+ * way multi-target translation does (<stem>.<lang>.<ext>); anything else —
+ * stdout, an existing file, a path that does not exist yet — is the destination
+ * verbatim. outputFormat, when the mode honours it, decides the extension, since
+ * it decides what the bytes are.
+ */
+export function resolveFileOutputPath(
+  inputPath: string,
+  output: string,
+  targetLang: string,
+  outputFormat?: string
+): string {
+  if (output === '-') {
+    return output;
+  }
+
+  // A trailing separator says "directory" whether or not it exists yet, which is
+  // how multi-target translation already reads --output.
+  if (!output.endsWith('/') && !output.endsWith(path.sep)) {
+    try {
+      if (!fs.statSync(output).isDirectory()) {
+        return output;
+      }
+    } catch {
+      return output;
+    }
+  }
+
+  const sourceExt = path.extname(inputPath);
+  const stem = path.basename(inputPath, sourceExt);
+  const ext = outputFormat ? `.${outputFormat.toLowerCase()}` : sourceExt;
+
+  return path.join(output, `${stem}.${targetLang}${ext}`);
+}
+
 export function getFileSize(filePath: string): number | null {
   try {
     const stats = fs.statSync(filePath);
diff --git a/tests/e2e/cli-success-paths.e2e.test.ts b/tests/e2e/cli-success-paths.e2e.test.ts
index 8abc8914..f12024a3 100644
--- a/tests/e2e/cli-success-paths.e2e.test.ts
+++ b/tests/e2e/cli-success-paths.e2e.test.ts
@@ -169,6 +169,73 @@ describe('CLI Success Paths E2E', () => {
       expect(content).toContain('Hola');
     });
 
+    it('should write <stem>.<lang>.<ext> when --output is an existing directory', () => {
+      const inputFile = path.join(testDir, 'single-dir.md');
+      const outDir = path.join(testDir, 'single-dir-out');
+      fs.writeFileSync(inputFile, 'Hello', 'utf-8');
+      fs.mkdirSync(outDir, { recursive: true });
+
+      const output = runCLI(
+        `translate "${inputFile}" --to es --output "${outDir}"`
+      );
+
+      const expected = path.join(outDir, 'single-dir.es.md');
+      expect(output).toContain(expected);
+      expect(fs.readFileSync(expected, 'utf-8')).toContain('Hola');
+    });
+
+    it('should treat a trailing slash on the output directory identically', () => {
+      const inputFile = path.join(testDir, 'slash-dir.md');
+      const outDir = path.join(testDir, 'slash-dir-out');
+      fs.writeFileSync(inputFile, 'Hello', 'utf-8');
+      fs.mkdirSync(outDir, { recursive: true });
+
+      runCLI(
+        `translate "${inputFile}" --to es --output "${outDir}${path.sep}"`
+      );
+
+      expect(
+        fs.readFileSync(path.join(outDir, 'slash-dir.es.md'), 'utf-8')
+      ).toContain('Hola');
+    });
+
+    it('should write a structured file into an output directory under its own stem', () => {
+      const inputFile = path.join(testDir, 'messages.json');
+      const outDir = path.join(testDir, 'structured-dir-out');
+      fs.writeFileSync(inputFile, JSON.stringify({ greeting: 'Hello' }));
+      fs.mkdirSync(outDir, { recursive: true });
+
+      runCLI(`translate "${inputFile}" --to es --output "${outDir}"`);
+      runCLI(`translate "${inputFile}" --to fr --output "${outDir}"`);
+
+      expect(fs.existsSync(path.join(outDir, 'messages.es.json'))).toBe(true);
+      expect(fs.existsSync(path.join(outDir, 'messages.fr.json'))).toBe(true);
+    });
+
+    it('should create an output directory named with a trailing slash', () => {
+      const inputFile = path.join(testDir, 'missing-dir.md');
+      const outDir = path.join(testDir, 'missing-dir-out');
+      fs.writeFileSync(inputFile, 'Hello', 'utf-8');
+
+      runCLI(
+        `translate "${inputFile}" --to es --output "${outDir}${path.sep}"`
+      );
+
+      expect(
+        fs.readFileSync(path.join(outDir, 'missing-dir.es.md'), 'utf-8')
+      ).toContain('Hola');
+    });
+
+    it('should still create a non-existent --output path as a file', () => {
+      const inputFile = path.join(testDir, 'new-path.md');
+      const outputFile = path.join(testDir, 'new-path-out', 'new.md');
+      fs.writeFileSync(inputFile, 'Hello', 'utf-8');
+
+      runCLI(`translate "${inputFile}" --to es --output "${outputFile}"`);
+
+      expect(fs.readFileSync(outputFile, 'utf-8')).toContain('Hola');
+    });
+
     it('should exit with code 0 on successful translation', () => {
       const output = runCLI('translate "Hello" --to es');
       expect(output).toContain('Hola');
diff --git a/tests/unit/file-translation-handler.test.ts b/tests/unit/file-translation-handler.test.ts
index 14b32685..0a4706f5 100644
--- a/tests/unit/file-translation-handler.test.ts
+++ b/tests/unit/file-translation-handler.test.ts
@@ -20,6 +20,7 @@ jest.mock('fs', () => {
     ...actual,
     existsSync: jest.fn().mockReturnValue(true),
     mkdirSync: jest.fn(),
+    statSync: jest.fn(),
   };
 });
 jest.mock('../../src/utils/atomic-write', () => ({
@@ -53,6 +54,7 @@ jest.mock('../../src/cli/commands/translate/translate-utils', () => {
 });
 
 import * as fs from 'fs';
+import { atomicWriteFileSync } from '../../src/utils/atomic-write';
 import { safeReadFileSync } from '../../src/utils/safe-read-file';
 import {
   isTextBasedFile,
@@ -151,8 +153,16 @@ describe('FileTranslationHandler', () => {
     mockedGetFileSize.mockReturnValue(50);
     (fs.existsSync as jest.Mock).mockReturnValue(true);
     (fs.mkdirSync as jest.Mock).mockImplementation(() => undefined);
+    (fs.statSync as jest.Mock).mockImplementation(() => {
+      throw new Error('ENOENT');
+    });
   });
 
+  /** Makes every --output value look like an existing directory. */
+  function outputIsDirectory(): void {
+    (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => true });
+  }
+
   describe('translateFile()', () => {
     it('should throw ValidationError when no output is specified', async () => {
       await expect(
@@ -456,6 +466,147 @@ describe('FileTranslationHandler', () => {
       stdoutWrite.mockRestore();
     });
 
+    describe('--output pointing at an existing directory', () => {
+      it('derives <stem>.<lang>.<ext> for a text file', async () => {
+        mockedIsTextBasedFile.mockReturnValue(true);
+        outputIsDirectory();
+
+        const result = await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({ output: '/tmp/out' })
+        );
+
+        expect(atomicWriteFileSync).toHaveBeenCalledWith(
+          '/tmp/out/file.de.txt',
+          'translated',
+          'utf-8'
+        );
+        expect(result).toContain('/tmp/out/file.de.txt');
+      });
+
+      it('treats a trailing slash identically for a text file', async () => {
+        mockedIsTextBasedFile.mockReturnValue(true);
+        outputIsDirectory();
+
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({ output: '/tmp/out/' })
+        );
+
+        expect(atomicWriteFileSync).toHaveBeenCalledWith(
+          '/tmp/out/file.de.txt',
+          'translated',
+          'utf-8'
+        );
+      });
+
+      it('derives <stem>.<lang>.<ext> for a structured file', async () => {
+        mockedIsTextBasedFile.mockReturnValue(true);
+        mockedIsStructuredFile.mockReturnValue(true);
+        outputIsDirectory();
+
+        await handler.translateFile(
+          '/tmp/messages.json',
+          defaultOptions({ output: '/tmp/out' })
+        );
+
+        expect(mocks.fileTranslationService.translateFile).toHaveBeenCalledWith(
+          '/tmp/messages.json',
+          '/tmp/out/messages.de.json',
+          expect.any(Object),
+          expect.any(Object)
+        );
+      });
+
+      it('derives <stem>.<lang>.<ext> for a document', async () => {
+        mocks.documentTranslationService.isDocumentSupported.mockReturnValue(
+          true
+        );
+        outputIsDirectory();
+
+        await handler.translateFile(
+          '/tmp/doc.pdf',
+          defaultOptions({ output: '/tmp/out' })
+        );
+
+        expect(mockDocHandler.translateDocument).toHaveBeenCalledWith(
+          '/tmp/doc.pdf',
+          expect.objectContaining({ output: '/tmp/out/doc.de.pdf' })
+        );
+      });
+
+      it('names a converted document by its --output-format extension', async () => {
+        mocks.documentTranslationService.isDocumentSupported.mockReturnValue(
+          true
+        );
+        outputIsDirectory();
+
+        await handler.translateFile(
+          '/tmp/report.pdf',
+          defaultOptions({ output: '/tmp/out', outputFormat: 'docx' })
+        );
+
+        expect(mockDocHandler.translateDocument).toHaveBeenCalledWith(
+          '/tmp/report.pdf',
+          expect.objectContaining({ output: '/tmp/out/report.de.docx' })
+        );
+      });
+
+      it('ignores --output-format on the text path, where it is not honoured', async () => {
+        mockedIsTextBasedFile.mockReturnValue(true);
+        outputIsDirectory();
+
+        await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({ output: '/tmp/out', outputFormat: 'docx' })
+        );
+
+        expect(atomicWriteFileSync).toHaveBeenCalledWith(
+          '/tmp/out/file.de.txt',
+          'translated',
+          'utf-8'
+        );
+      });
+
+      it('derives <stem>.<lang>.<ext> on the non-text non-document fallback', async () => {
+        mocks.documentTranslationService.isDocumentSupported.mockReturnValue(
+          false
+        );
+        outputIsDirectory();
+
+        await handler.translateFile(
+          '/tmp/file.xyz',
+          defaultOptions({ output: '/tmp/out' })
+        );
+
+        expect(mocks.fileTranslationService.translateFile).toHaveBeenCalledWith(
+          '/tmp/file.xyz',
+          '/tmp/out/file.de.xyz',
+          expect.any(Object),
+          expect.any(Object)
+        );
+      });
+
+      it('still streams to stdout when --output is "-"', async () => {
+        mockedIsTextBasedFile.mockReturnValue(true);
+        outputIsDirectory();
+        const stdoutWrite = jest
+          .spyOn(process.stdout, 'write')
+          .mockImplementation(() => true);
+
+        const result = await handler.translateFile(
+          '/tmp/file.txt',
+          defaultOptions({ output: '-' })
+        );
+
+        expect(stdoutWrite).toHaveBeenCalledWith('translated');
+        expect(result).toBe('');
+        expect(atomicWriteFileSync).not.toHaveBeenCalled();
+
+        stdoutWrite.mockRestore();
+      });
+    });
+
     it('should throw ValidationError for glossary without --from in translateTextFile', async () => {
       mockedIsTextBasedFile.mockReturnValue(true);
       mockedGetFileSize.mockReturnValue(50);
diff --git a/tests/unit/translate-utils.test.ts b/tests/unit/translate-utils.test.ts
index 4bb609c2..bd352282 100644
--- a/tests/unit/translate-utils.test.ts
+++ b/tests/unit/translate-utils.test.ts
@@ -19,6 +19,7 @@ import {
   isTextBasedFile,
   isStructuredFile,
   getFileSize,
+  resolveFileOutputPath,
   resolveGlossaryId,
 } from '../../src/cli/commands/translate/translate-utils';
 import { ValidationError } from '../../src/utils/errors';
@@ -876,6 +877,85 @@ describe('translate-utils', () => {
     });
   });
 
+  describe('resolveFileOutputPath()', () => {
+    const asDirectory = () =>
+      mockedStatSync.mockReturnValue({
+        isDirectory: () => true,
+      } as fs.Stats);
+    const asFile = () =>
+      mockedStatSync.mockReturnValue({
+        isDirectory: () => false,
+      } as fs.Stats);
+    const asMissing = () =>
+      mockedStatSync.mockImplementation(() => {
+        throw new Error('ENOENT');
+      });
+
+    it('derives <stem>.<lang>.<ext> inside an existing directory', () => {
+      asDirectory();
+      expect(resolveFileOutputPath('/src/t.md', '/out', 'ko')).toBe(
+        '/out/t.ko.md'
+      );
+    });
+
+    it('treats a trailing slash the same as no trailing slash', () => {
+      asDirectory();
+      expect(resolveFileOutputPath('/src/t.md', '/out/', 'ko')).toBe(
+        '/out/t.ko.md'
+      );
+    });
+
+    it('names by the source stem, not the directory, so two locales cannot collide', () => {
+      asDirectory();
+      expect(resolveFileOutputPath('/src/messages.json', '/out', 'ko')).toBe(
+        '/out/messages.ko.json'
+      );
+      expect(resolveFileOutputPath('/src/messages.json', '/out', 'ja')).toBe(
+        '/out/messages.ja.json'
+      );
+    });
+
+    it('leaves an existing file path untouched', () => {
+      asFile();
+      expect(resolveFileOutputPath('/src/t.md', '/out/explicit.md', 'ko')).toBe(
+        '/out/explicit.md'
+      );
+    });
+
+    it('leaves a non-existent path untouched, so it still means "file to create"', () => {
+      asMissing();
+      expect(resolveFileOutputPath('/src/t.md', '/out/new.md', 'ko')).toBe(
+        '/out/new.md'
+      );
+    });
+
+    it('honours a trailing slash on a directory that does not exist yet', () => {
+      asMissing();
+      expect(resolveFileOutputPath('/src/t.md', '/out/new-dir/', 'ko')).toBe(
+        '/out/new-dir/t.ko.md'
+      );
+    });
+
+    it('leaves stdout alone without touching the filesystem', () => {
+      expect(resolveFileOutputPath('/src/t.md', '-', 'ko')).toBe('-');
+      expect(mockedStatSync).not.toHaveBeenCalled();
+    });
+
+    it('uses the converted extension when an output format is given', () => {
+      asDirectory();
+      expect(
+        resolveFileOutputPath('/src/report.pdf', '/out', 'de', 'docx')
+      ).toBe('/out/report.de.docx');
+    });
+
+    it('ignores the output format for an explicit file path', () => {
+      asFile();
+      expect(
+        resolveFileOutputPath('/src/report.pdf', '/out/r.de.pdf', 'de', 'docx')
+      ).toBe('/out/r.de.pdf');
+    });
+  });
+
   describe('resolveGlossaryId()', () => {
     it('should delegate to glossaryService.resolveGlossaryId', async () => {
       const mockGlossaryService = {

From 440f02c5a21fd3a31bc011f3990e635645f7b335 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 11:11:54 +0200
Subject: [PATCH 109/256] fix(examples): stop swallowing translate failures in
 batch processing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

03-batch-processing.sh reported 37/37 passed for `npm run examples` while
`translate --output <dir>` was broken for a single target language. Section 6
printed "(cached or completed)" for a call that had errored, and section 8's
cache comparison timed four failures per run against four more, so the
"speed improvement" it reported measured nothing.

The guards are gone: `2>/dev/null || echo "(cached or completed)"` in section 6,
and `2>&1 || true` in both timing loops. Section 8 keeps `>/dev/null`, which
hides successful output rather than errors. With set -e, a regression here now
fails the example.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 examples/03-batch-processing.sh | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/03-batch-processing.sh b/examples/03-batch-processing.sh
index cfedc39f..7c07b23f 100755
--- a/examples/03-batch-processing.sh
+++ b/examples/03-batch-processing.sh
@@ -172,7 +172,7 @@ for file in "$SAMPLE_DIR"/*.md; do
   echo "   [$CURRENT/$TOTAL - $PERCENT%] Processing $filename..."
 
   # Translate (use cache for speed)
-  deepl translate "$file" --to ja --output "$OUTPUT_DIR/ja/" 2>/dev/null || echo "     (cached or completed)"
+  deepl translate "$file" --to ja --output "$OUTPUT_DIR/ja/"
 done
 
 echo "   ✓ Batch processing complete"
@@ -210,7 +210,7 @@ deepl cache clear --yes >/dev/null 2>&1
 
 START=$(date +%s)
 for file in "$SAMPLE_DIR"/*.md; do
-  deepl translate "$file" --to zh --output "$OUTPUT_DIR/zh/" >/dev/null 2>&1 || true
+  deepl translate "$file" --to zh --output "$OUTPUT_DIR/zh/" >/dev/null
 done
 END=$(date +%s)
 DURATION=$((END - START))
@@ -222,7 +222,7 @@ echo "   Second run (cache hit):"
 
 START=$(date +%s)
 for file in "$SAMPLE_DIR"/*.md; do
-  deepl translate "$file" --to zh --output "$OUTPUT_DIR/zh/" >/dev/null 2>&1 || true
+  deepl translate "$file" --to zh --output "$OUTPUT_DIR/zh/" >/dev/null
 done
 END=$(date +%s)
 CACHED_DURATION=$((END - START))

From f660a07181d8cbbb1f9fd6939ecb8cae4fe04933 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 12:14:23 +0200
Subject: [PATCH 110/256] test(sync): wait on the outcome in the last two
 fixed-drain watch tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both tests synchronised on flushWatchSetup's fixed SETTLE_ROUNDS drain rather
than on the state they assert, the same pattern that produced a real flake in
the auto-commit test fixed by 5c829b2.

Forcing SETTLE_ROUNDS to 0 failed exactly these two and no others, so the
dependence on the drain budget was measurable:

- listener counts: the retry loop called flushWatchSetup again, but phase 1 is
  a no-op once mockWatcherOn has any call, so the second invocation's setup
  made no progress at all and the loop spun ten times doing nothing. It now
  waits until both stop listeners are above the captured baseline.
- watched patterns: it returned as soon as any watcher listener attached, which
  in a contaminated run can be another session's. It now waits for its own log
  line and its own stop listener -- the pattern count is logged before
  chokidar.watch, so the listener is the later of the two.

Both assertions stay exact; the round ceiling still fails loudly on a genuine
hang. Verified the same way as 5c829b2: with SETTLE_ROUNDS forced to 0 all 49
tests in the file pass across three runs. Restored to 25 for the callers that
still drain after emitting change events.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/sync/sync-command.test.ts | 39 +++++++++++++---------------
 1 file changed, 18 insertions(+), 21 deletions(-)

diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index c8cd30fb..f9c3d859 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -1332,19 +1332,12 @@ describe('SyncCommand', () => {
       // Don't mock process.on — the whole point is to observe real listener
       // churn across repeated invocations. Trigger shutdown by emitting the
       // signal to the real process emitter (listeners only react synchronously).
+      const listenersAttached = (): boolean =>
+        process.listenerCount('SIGINT') > sigintBaseline &&
+        process.listenerCount('SIGTERM') > sigtermBaseline;
+
       const firstRun = command.run({ watch: true, debounce: 50 });
-      await flushWatchSetup();
-      // flushWatchSetup returns as soon as the watcher listeners attach, which
-      // can precede the process.on('SIGINT', ...) call. Retry with a hard
-      // ceiling so a missing listener fails loudly rather than as
-      // "Expected: 1, Received: 0".
-      for (
-        let i = 0;
-        i < 10 && process.listenerCount('SIGINT') === sigintBaseline;
-        i++
-      ) {
-        await flushWatchSetup();
-      }
+      await flushUntil(listenersAttached, 'first watch session stop listeners');
       expect(process.listenerCount('SIGINT')).toBe(sigintBaseline + 1);
       expect(process.listenerCount('SIGTERM')).toBe(sigtermBaseline + 1);
 
@@ -1356,14 +1349,10 @@ describe('SyncCommand', () => {
 
       // Second invocation should also add exactly one listener, then remove it.
       const secondRun = command.run({ watch: true, debounce: 50 });
-      await flushWatchSetup();
-      for (
-        let i = 0;
-        i < 10 && process.listenerCount('SIGINT') === sigintBaseline;
-        i++
-      ) {
-        await flushWatchSetup();
-      }
+      await flushUntil(
+        listenersAttached,
+        'second watch session stop listeners'
+      );
       expect(process.listenerCount('SIGINT')).toBe(sigintBaseline + 1);
       expect(process.listenerCount('SIGTERM')).toBe(sigtermBaseline + 1);
 
@@ -1392,7 +1381,15 @@ describe('SyncCommand', () => {
 
       const runPromise = command.run({ watch: true, debounce: 100 });
 
-      await flushWatchSetup();
+      // The pattern count is logged before chokidar.watch, so the stop listener
+      // is the later of the two things this test needs; wait for both.
+      await flushUntil(
+        () =>
+          logInfoSpy.mock.calls.some((c: unknown[]) =>
+            String(c[0]).includes('pattern(s)')
+          ) && sigintListeners.length > 0,
+        'watched-pattern log line and stop listener'
+      );
 
       for (const listener of sigintListeners) {
         listener();

From 0f51bf5fc71fe13ca17e320d60c2bae8255e8991 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 12:18:09 +0200
Subject: [PATCH 111/256] test(docs): assert the option choice surface
 centrally
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_describe reported an option's flags, description and default value but not its
choice list, so nothing could check the enum surface in one place. It now
reports choices from commander's argChoices, and documented-surface asserts the
whole map with toEqual alongside REQUIRED_ARGUMENTS.

That covers all 45 constrained options across translate, write, correct, voice,
glossary, tm, watch, sync, hooks, config, cache, style-rules, usage, languages,
detect and admin. Previously four of them were covered, by hand, in
cli-translate-flags; every --format, --source-language-mode and
--tag-handling-version had no assertion on its accepted values at all. Removing
a value or adding one now fails, in either direction. Verified by dropping
'nonewlines' from --split-sentences, which the table rejects.

The vocabularies shared by several options -- formality, model type, and the
two --format shapes -- are named constants, so a change to one enum is a single
edit rather than fifteen.

The four 'should accept all valid X values' tests in cli-translate-flags are
removed: they spawned the CLI once per enum value to assert only that the value
was not rejected, which is what the table now states directly. Their sibling
'should reject invalid X value' tests stay -- a table cannot show that
commander enforces the list -- as does the help-text choices assertion.

describe.ts stays at 100% coverage.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/cli/commands/describe.ts               |  5 ++
 tests/e2e/cli-translate-flags.e2e.test.ts  | 76 +----------------
 tests/unit/cli/describe.test.ts            | 35 +++++++-
 tests/unit/docs/documented-surface.test.ts | 98 +++++++++++++++++++++-
 4 files changed, 138 insertions(+), 76 deletions(-)

diff --git a/src/cli/commands/describe.ts b/src/cli/commands/describe.ts
index 8eb15612..8a74d371 100644
--- a/src/cli/commands/describe.ts
+++ b/src/cli/commands/describe.ts
@@ -4,6 +4,8 @@ export interface DescribeOption {
   flags: string;
   description: string;
   defaultValue?: unknown;
+  /** Accepted values, when the option constrains its argument to a fixed set. */
+  choices?: string[];
 }
 
 export interface DescribeArgument {
@@ -35,6 +37,9 @@ function describeOption(opt: Option): DescribeOption {
   if (opt.defaultValue !== undefined) {
     out.defaultValue = opt.defaultValue;
   }
+  if (opt.argChoices !== undefined) {
+    out.choices = [...opt.argChoices];
+  }
   return out;
 }
 
diff --git a/tests/e2e/cli-translate-flags.e2e.test.ts b/tests/e2e/cli-translate-flags.e2e.test.ts
index b04ed8ab..e4456a10 100644
--- a/tests/e2e/cli-translate-flags.e2e.test.ts
+++ b/tests/e2e/cli-translate-flags.e2e.test.ts
@@ -4,8 +4,9 @@
  * Flag-level behaviour of `deepl translate` that the workflow and success-path
  * suites do not reach: directory output requirements, comma-separated targets,
  * XML tag-handling combinations, table output, the removed
- * --enable-beta-languages flag, --api-url scheme enforcement, and the choice
- * lists on the constrained options.
+ * --enable-beta-languages flag, --api-url scheme enforcement, and rejection of
+ * out-of-list values on the constrained options. The choice lists themselves
+ * are asserted centrally in tests/unit/docs/documented-surface.test.ts.
  */
 
 import { execSync } from 'child_process';
@@ -345,27 +346,6 @@ describe('Translate CLI flags E2E', () => {
       }
     });
 
-    it('should accept all valid --formality values', () => {
-      const validValues = [
-        'default',
-        'more',
-        'less',
-        'prefer_more',
-        'prefer_less',
-      ];
-      expect.assertions(validValues.length);
-      for (const value of validValues) {
-        try {
-          runCLI(`deepl translate "Hello" --to es --formality ${value}`, {
-            stdio: 'pipe',
-          });
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout ?? '';
-          expect(output).not.toMatch(/invalid.*Allowed choices/i);
-        }
-      }
-    });
-
     it('should reject invalid --tag-handling value', () => {
       expect.assertions(5);
       try {
@@ -382,22 +362,6 @@ describe('Translate CLI flags E2E', () => {
       }
     });
 
-    it('should accept valid --tag-handling values', () => {
-      const validValues = ['xml', 'html'];
-      expect.assertions(validValues.length);
-      for (const value of validValues) {
-        try {
-          runCLI(
-            `deepl translate "<p>Hello</p>" --to es --tag-handling ${value}`,
-            { stdio: 'pipe' }
-          );
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout ?? '';
-          expect(output).not.toMatch(/invalid.*Allowed choices/i);
-        }
-      }
-    });
-
     it('should reject invalid --model-type value', () => {
       expect.assertions(6);
       try {
@@ -415,25 +379,6 @@ describe('Translate CLI flags E2E', () => {
       }
     });
 
-    it('should accept valid --model-type values', () => {
-      const validValues = [
-        'quality_optimized',
-        'prefer_quality_optimized',
-        'latency_optimized',
-      ];
-      expect.assertions(validValues.length);
-      for (const value of validValues) {
-        try {
-          runCLI(`deepl translate "Hello" --to es --model-type ${value}`, {
-            stdio: 'pipe',
-          });
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout ?? '';
-          expect(output).not.toMatch(/invalid.*Allowed choices/i);
-        }
-      }
-    });
-
     it('should reject invalid --split-sentences value', () => {
       expect.assertions(6);
       try {
@@ -451,21 +396,6 @@ describe('Translate CLI flags E2E', () => {
       }
     });
 
-    it('should accept valid --split-sentences values', () => {
-      const validValues = ['on', 'off', 'nonewlines'];
-      expect.assertions(validValues.length);
-      for (const value of validValues) {
-        try {
-          runCLI(`deepl translate "Hello" --to es --split-sentences ${value}`, {
-            stdio: 'pipe',
-          });
-        } catch (error: any) {
-          const output = error.stderr ?? error.stdout ?? '';
-          expect(output).not.toMatch(/invalid.*Allowed choices/i);
-        }
-      }
-    });
-
     it('should show choices in help text for constrained options', () => {
       const helpOutput = translateHelp;
       expect(helpOutput).toMatch(/--formality.*choices/is);
diff --git a/tests/unit/cli/describe.test.ts b/tests/unit/cli/describe.test.ts
index 5ff973db..d162a9af 100644
--- a/tests/unit/cli/describe.test.ts
+++ b/tests/unit/cli/describe.test.ts
@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { describeProgram } from '../../../src/cli/commands/describe';
 
 describe('describeProgram', () => {
@@ -17,7 +17,14 @@ describe('describeProgram', () => {
       .command('translate')
       .description('Translate text or files')
       .option('-t, --to <lang>', 'Target language')
-      .option('-f, --from <lang>', 'Source language');
+      .option('-f, --from <lang>', 'Source language')
+      .addOption(
+        new Option('--formality <level>', 'Formality').choices([
+          'default',
+          'more',
+          'less',
+        ])
+      );
 
     program
       .command('show')
@@ -92,6 +99,30 @@ describe('describeProgram', () => {
     });
   });
 
+  describe('option choices', () => {
+    // Commander rejects a value outside the list, so the list is part of the
+    // CLI's contract and a consumer of _describe has to be able to see it.
+    it('reports the accepted values of a constrained option', () => {
+      const translate = describeProgram(program).commands.find(
+        (c) => c.name === 'translate'
+      );
+      const formality = translate?.options.find((o) =>
+        o.flags.includes('--formality')
+      );
+
+      expect(formality?.choices).toEqual(['default', 'more', 'less']);
+    });
+
+    it('omits choices on an option that accepts any value', () => {
+      const translate = describeProgram(program).commands.find(
+        (c) => c.name === 'translate'
+      );
+      const to = translate?.options.find((o) => o.flags.includes('--to'));
+
+      expect(to).not.toHaveProperty('choices');
+    });
+  });
+
   describe('positional arguments', () => {
     it('reports each argument in declaration order', () => {
       const show = describeProgram(program).commands.find(
diff --git a/tests/unit/docs/documented-surface.test.ts b/tests/unit/docs/documented-surface.test.ts
index b75f515e..52d14455 100644
--- a/tests/unit/docs/documented-surface.test.ts
+++ b/tests/unit/docs/documented-surface.test.ts
@@ -9,11 +9,16 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getAllLanguageCodes } from '../../../src/data/language-registry';
 
+interface DescribedOption {
+  flags: string;
+  choices?: string[];
+}
+
 interface DescribedCommand {
   name: string;
   aliases: string[];
   arguments: { name: string; required: boolean }[];
-  options: { flags: string }[];
+  options: DescribedOption[];
   commands: DescribedCommand[];
   hidden: boolean;
 }
@@ -54,6 +59,81 @@ const REQUIRED_ARGUMENTS: Record<string, string[]> = {
   'admin keys set-limit': ['key-id', 'characters'],
 };
 
+/**
+ * Vocabularies shared by more than one option. Naming them keeps the table
+ * below scannable and makes a change to one enum a single edit.
+ */
+const FORMALITY = [
+  'default',
+  'more',
+  'less',
+  'prefer_more',
+  'prefer_less',
+  'formal',
+  'informal',
+];
+const MODEL_TYPE = [
+  'quality_optimized',
+  'prefer_quality_optimized',
+  'latency_optimized',
+];
+const TEXT_JSON = ['text', 'json'];
+const TEXT_JSON_TABLE = ['text', 'json', 'table'];
+
+/**
+ * Every option that constrains its argument to a fixed set, and the set it
+ * accepts. Commander rejects anything outside the list, so each entry is part
+ * of the CLI's contract: dropping a value breaks callers already passing it,
+ * and adding one is a surface change that belongs in the docs.
+ */
+const OPTION_CHOICES: Record<string, string[]> = {
+  'translate --formality': FORMALITY,
+  'translate --model-type': MODEL_TYPE,
+  'translate --split-sentences': ['on', 'off', 'nonewlines'],
+  'translate --output-format': ['docx'],
+  'translate --tag-handling': ['xml', 'html'],
+  'translate --tag-handling-version': ['v1', 'v2'],
+  'translate --format': TEXT_JSON_TABLE,
+  'write --format': TEXT_JSON,
+  'correct --format': TEXT_JSON,
+  'voice --formality': FORMALITY,
+  'voice --source-language-mode': ['auto', 'fixed'],
+  'voice --format': TEXT_JSON,
+  'glossary list --format': TEXT_JSON,
+  'glossary show --format': TEXT_JSON,
+  'glossary entries --format': TEXT_JSON,
+  'tm list --format': TEXT_JSON,
+  'watch --formality': FORMALITY,
+  'sync --formality': FORMALITY,
+  'sync --model-type': MODEL_TYPE,
+  'sync --format': TEXT_JSON,
+  'sync init --format': TEXT_JSON,
+  'sync status --format': TEXT_JSON,
+  'sync validate --format': TEXT_JSON,
+  'sync audit --format': TEXT_JSON,
+  'sync export --format': TEXT_JSON,
+  'sync resolve --format': TEXT_JSON,
+  'sync push --format': TEXT_JSON,
+  'sync pull --format': TEXT_JSON,
+  'hooks list --format': TEXT_JSON,
+  'config get --format': TEXT_JSON,
+  'config list --format': TEXT_JSON,
+  'cache stats --format': TEXT_JSON_TABLE,
+  'style-rules list --format': TEXT_JSON_TABLE,
+  'style-rules create --format': TEXT_JSON,
+  'style-rules show --format': TEXT_JSON,
+  'style-rules update --format': TEXT_JSON,
+  'style-rules instructions --format': TEXT_JSON_TABLE,
+  'style-rules add-instruction --format': TEXT_JSON,
+  'style-rules update-instruction --format': TEXT_JSON,
+  'usage --format': TEXT_JSON_TABLE,
+  'languages --format': TEXT_JSON_TABLE,
+  'detect --format': TEXT_JSON,
+  'admin keys list --format': TEXT_JSON,
+  'admin keys create --format': TEXT_JSON,
+  'admin usage --format': TEXT_JSON,
+};
+
 const ROOT = path.join(__dirname, '..', '..', '..');
 const CLI_ENTRY = path.join(ROOT, 'dist', 'cli', 'index.js');
 const DOCS = [
@@ -335,6 +415,22 @@ describe('documented CLI surface', () => {
     });
   });
 
+  describe('option choice surface', () => {
+    it('accepts exactly the choice lists recorded above', () => {
+      const actual: Record<string, string[]> = {};
+      eachCommand((command, commandPath) => {
+        for (const option of command.options) {
+          if (!option.choices) continue;
+          const long = option.flags.match(/--[a-z0-9-]+/)?.[0];
+          if (!long) continue;
+          actual[`${commandPath.join(' ')} ${long}`] = option.choices;
+        }
+      });
+
+      expect(actual).toEqual(OPTION_CHOICES);
+    });
+  });
+
   describe('retired endpoints', () => {
     // Language listings moved to GET /v3/languages; the v2 endpoints are
     // formally deprecated, so no doc should teach a reader to call them.

From 42d1eb3862dfa397f51eff4006a4824c380d96ef Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 12:21:50 +0200
Subject: [PATCH 112/256] test(completion): derive the expected completion
 vocabulary from _describe
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The top-level command check listed 13 names against a CLI that has 19 -- it
predates voice, sync, tm, correct, detect and init -- and asserted with
toContain, a substring match anywhere in the generated script rather than a
check that the name is a completion word. A command dropped from the script
would have failed nothing as long as it stayed in the 13 and appeared somewhere
in the file, in a dispatch function name, a description or a comment.

The scripts themselves were correct; this was a test gap. All three now derive
their expectation from _describe's non-hidden command tree and compare against
the words actually parsed out of the generated script:

- bash: the compgen -W list guarded by `cword -eq 1`, plus each parent's case
  branch, compared for set equality against the registered names -- so a
  dropped command and a stale leftover both fail
- zsh: the commands=() array inside _deepl(), plus a dispatch function for
  every parent rather than the hand-picked auth/cache/glossary
- fish: every `-n '__fish_use_subcommand' -a` entry, plus seen-subcommand
  scoping for every parent

Aliases (t, w, c) are included -- they are part of what users type. Commander's
implicit `help` command is filtered from both sides instead of predicted: it is
absent from _describe, and the script offers it only where the command has no
action handler of its own, so it appears under `glossary` but not under `sync`.

Verified by injecting three regressions into the generator at once -- dropping
`detect` from the top-level list, `stats` from cache's subcommands, and auth's
whole subcommand entry -- which fails all six derived assertions and no others.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/e2e/cli-completion.e2e.test.ts | 212 ++++++++++++++++++++-------
 1 file changed, 156 insertions(+), 56 deletions(-)

diff --git a/tests/e2e/cli-completion.e2e.test.ts b/tests/e2e/cli-completion.e2e.test.ts
index 48f2f942..01446fd2 100644
--- a/tests/e2e/cli-completion.e2e.test.ts
+++ b/tests/e2e/cli-completion.e2e.test.ts
@@ -4,99 +4,199 @@
  * Asserts the generated scripts are actually loadable by each shell -- the
  * dispatch functions, the completion builtins they call, and the subcommand
  * scoping -- rather than only that some output was produced.
+ *
+ * The command vocabulary each script must offer is derived from the hidden
+ * `_describe` command rather than listed here, so a newly registered command is
+ * covered the day it lands.
  */
 
 import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
 
+interface DescribedCommand {
+  name: string;
+  aliases: string[];
+  commands: DescribedCommand[];
+  hidden: boolean;
+}
+
+/**
+ * Commander's `help` command is created on demand, so `_describe` never reports
+ * it, and it is offered only where the command has no action handler of its own
+ * -- present under `glossary`, absent under `sync`. It is filtered out of both
+ * sides of every comparison below rather than predicted.
+ */
+const IMPLICIT_COMMAND = 'help';
+
 describe('Completion Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-completion');
   const { runCLI, runCLIAll } = makeNodeRunCLI(testConfig.path, {
     excludeApiKey: true,
   });
 
+  /** Commands a user can type at the first position, aliases included. */
+  let expectedTopLevel: string[];
+  /** Commands with subcommands of their own, which each script must scope. */
+  let expectedParents: string[];
+  let expectedSubcommands: Map<string, string[]>;
+
+  beforeAll(() => {
+    const surface = JSON.parse(
+      runCLI('_describe --format json')
+    ) as DescribedCommand;
+
+    const visible = (cmd: DescribedCommand): DescribedCommand[] =>
+      cmd.commands.filter((child) => !child.hidden);
+
+    expectedTopLevel = visible(surface).flatMap((cmd) => [
+      cmd.name,
+      ...cmd.aliases,
+    ]);
+
+    expectedSubcommands = new Map(
+      visible(surface)
+        .map((cmd): [string, string[]] => [
+          cmd.name,
+          visible(cmd).map((sub) => sub.name),
+        ])
+        .filter(([, subs]) => subs.length > 0)
+    );
+    expectedParents = [...expectedSubcommands.keys()];
+  });
+
   afterAll(() => {
     testConfig.cleanup();
   });
 
+  /** Word lists mix commands and flags; only the commands are derived. */
+  function commandWords(words: string[]): string[] {
+    return words
+      .filter((word) => !word.startsWith('-') && word !== IMPLICIT_COMMAND)
+      .sort();
+  }
+
   describe('completion bash', () => {
+    let script: string;
+
+    beforeAll(() => {
+      script = runCLI('completion bash');
+    });
+
+    /** The `compgen -W` list guarded by `cword -eq 1`, i.e. the top-level one. */
+    function topLevelWords(): string[] {
+      const match = script.match(
+        /cword\} -eq 1 \]\]; then\s*COMPREPLY=\(\$\(compgen -W "([^"]*)"/
+      );
+      expect(match).not.toBeNull();
+      return match![1]!.split(' ');
+    }
+
+    function branchWords(parent: string): string[] {
+      const match = script.match(
+        new RegExp(
+          `\\n\\s*${parent}\\)\\n\\s*COMPREPLY=\\(\\$\\(compgen -W "([^"]*)"`
+        )
+      );
+      expect(match).not.toBeNull();
+      return match![1]!.split(' ');
+    }
+
     it('should output a valid bash completion script', () => {
-      const output = runCLI('completion bash');
-      expect(output).toContain('_deepl_completions');
-      expect(output).toContain('complete -F _deepl_completions deepl');
-      expect(output).toContain('compgen');
-      expect(output).toContain('COMPREPLY');
-    });
-
-    it('should include all registered top-level commands', () => {
-      const output = runCLI('completion bash');
-      const expectedCommands = [
-        'translate',
-        'auth',
-        'usage',
-        'languages',
-        'watch',
-        'write',
-        'config',
-        'cache',
-        'glossary',
-        'hooks',
-        'style-rules',
-        'admin',
-        'completion',
-      ];
-      for (const cmd of expectedCommands) {
-        expect(output).toContain(cmd);
-      }
+      expect(script).toContain('_deepl_completions');
+      expect(script).toContain('complete -F _deepl_completions deepl');
+      expect(script).toContain('compgen');
+      expect(script).toContain('COMPREPLY');
+    });
+
+    it('should offer exactly the registered top-level commands', () => {
+      expect(commandWords(topLevelWords())).toEqual(
+        [...expectedTopLevel].sort()
+      );
     });
 
-    it('should include subcommand completions', () => {
-      const output = runCLI('completion bash');
-      expect(output).toContain('auth)');
-      expect(output).toContain('set-key');
-      expect(output).toContain('cache)');
-      expect(output).toContain('stats');
+    it('should offer exactly the registered subcommands under each parent', () => {
+      const actual: Record<string, string[]> = {};
+      const expected: Record<string, string[]> = {};
+      for (const parent of expectedParents) {
+        actual[parent] = commandWords(branchWords(parent));
+        expected[parent] = [...expectedSubcommands.get(parent)!].sort();
+      }
+
+      expect(actual).toEqual(expected);
     });
   });
 
   describe('completion zsh', () => {
+    let script: string;
+
+    beforeAll(() => {
+      script = runCLI('completion zsh');
+    });
+
+    /** The `commands=(...)` array inside `_deepl()`, one `'name:description'` per line. */
+    function topLevelEntries(): string[] {
+      const body = script.slice(script.indexOf('_deepl() {'));
+      const list = body.slice(
+        body.indexOf('commands=('),
+        body.indexOf('\n    )')
+      );
+      return [...list.matchAll(/'([^:']+):/g)].map((match) => match[1]!);
+    }
+
     it('should output a valid zsh completion script', () => {
-      const output = runCLI('completion zsh');
-      expect(output).toContain('#compdef deepl');
-      expect(output).toContain('_deepl()');
-      expect(output).toContain('_arguments -C');
+      expect(script).toContain('#compdef deepl');
+      expect(script).toContain('_deepl()');
+      expect(script).toContain('_arguments -C');
     });
 
-    it('should include command descriptions', () => {
-      const output = runCLI('completion zsh');
-      expect(output).toContain('translate:');
-      expect(output).toContain('auth:');
-      expect(output).toContain('cache:');
+    it('should describe exactly the registered top-level commands', () => {
+      expect(commandWords(topLevelEntries())).toEqual(
+        [...expectedTopLevel].sort()
+      );
     });
 
-    it('should include subcommand dispatch functions', () => {
-      const output = runCLI('completion zsh');
-      expect(output).toContain('_deepl_auth()');
-      expect(output).toContain('_deepl_cache()');
-      expect(output).toContain('_deepl_glossary()');
+    it('should include a dispatch function for every parent command', () => {
+      // Hyphens are not valid in a zsh function name, so `style-rules` is
+      // dispatched by `_deepl_style_rules`.
+      const missing = expectedParents.filter(
+        (parent) => !script.includes(`_deepl_${parent.replace(/-/g, '_')}()`)
+      );
+
+      expect(missing).toEqual([]);
     });
   });
 
   describe('completion fish', () => {
+    let script: string;
+
+    beforeAll(() => {
+      script = runCLI('completion fish');
+    });
+
     it('should output a valid fish completion script', () => {
-      const output = runCLI('completion fish');
-      expect(output).toContain('complete -c deepl');
-      expect(output).toContain('__fish_use_subcommand');
+      expect(script).toContain('complete -c deepl');
+      expect(script).toContain('__fish_use_subcommand');
     });
 
-    it('should include subcommand scoping', () => {
-      const output = runCLI('completion fish');
-      expect(output).toContain('__fish_seen_subcommand_from auth');
-      expect(output).toContain('__fish_seen_subcommand_from cache');
+    it('should offer exactly the registered top-level commands', () => {
+      const offered = [
+        ...script.matchAll(/-n '__fish_use_subcommand' -a '([^']+)'/g),
+      ].map((match) => match[1]!);
+
+      expect(commandWords(offered)).toEqual([...expectedTopLevel].sort());
+    });
+
+    it('should scope completions to every parent command', () => {
+      const missing = expectedParents.filter(
+        (parent) =>
+          !script.includes(`__fish_seen_subcommand_from ${parent}'`) &&
+          !script.includes(`__fish_seen_subcommand_from ${parent};`)
+      );
+
+      expect(missing).toEqual([]);
     });
 
     it('should disable default file completions', () => {
-      const output = runCLI('completion fish');
-      expect(output).toContain('complete -c deepl -f');
+      expect(script).toContain('complete -c deepl -f');
     });
   });
 

From 90efa10b9256a9e7a40ad9fbc67bdb506d374c44 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 16:14:33 +0200
Subject: [PATCH 113/256] fix(git): separate pathspecs with -- and scope
 auto-commit to its own files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`execFile` prevents shell injection but not git's own option parsing. A sync
`target_path_pattern` that renders a leading dash reached `git add` as a flag:
`--pathspec-from-file={locale}` satisfies every existing pattern check, since
none rejects a leading dash, so a repo-supplied pattern could name the file
list to stage and defeat the auto-commit preflight that bounds the staged set.

`git commit` then ran with no pathspec and committed the whole index, so a
separately staged `.env.local` or unfinished work landed in a `chore(i18n)`
commit whose message described only the translation.

Both auto-commit paths now pass staged paths after `--` and commit with
`--only`. `sync` was partly shielded by its unrelated-modifications preflight
and `watch` was not, but both are fixed so the two call sites cannot drift.
The `git add` loop is kept because `--only` requires a new output file to be
staged before it can be committed.

Tests assert the security properties rather than the argument shape: that `--`
precedes a dash-leading pathspec, and that the commit's pathspec is exactly the
staged translation set.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                         |  2 +
 src/cli/commands/sync-command.ts     | 12 +++-
 src/cli/commands/watch.ts            | 17 ++++--
 tests/unit/sync/sync-command.test.ts | 84 +++++++++++++++++++++++++---
 4 files changed, 101 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6b99f08..bd500e1f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -355,6 +355,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
+
 - **config**: `ConfigService.save()` writes through an unpredictably named temp file created with an exclusive flag, instead of a fixed `config.json.tmp`. A symlink planted at the predictable path redirected the config — which holds the API key in plaintext — to a path of the planter's choosing, and the subsequent rename left `config.json` as that symlink, so every later write followed it too. The mode is also applied with `chmod` after creation, which the umask cannot widen.
 
 - **tests**: The test suite no longer inherits real credentials or the real config directory. Suites that spawn the bare `deepl` command cannot be intercepted by nock, so they reached the live DeepL API with whatever key was exported and read and wrote the developer's cache database; cached responses matching this suite's fixtures were recovered from a real cache, confirming it had happened. `globalSetup` now clears `DEEPL_API_KEY`, `TMS_API_KEY` and `TMS_TOKEN` and points `DEEPL_CONFIG_DIR` at a temporary directory before workers fork.
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index e6b39559..4c9fcbea 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -650,8 +650,10 @@ export class SyncCommand {
     const filesToStage = dirtyOwned;
     if (filesToStage.length === 0) return;
 
+    // `--` stops git reading a target path that begins with a dash as an
+    // option: execFile prevents shell injection, not git's own option parsing.
     for (const file of filesToStage) {
-      await execFileAsync('git', ['add', file], { cwd });
+      await execFileAsync('git', ['add', '--', file], { cwd });
     }
 
     const localeOf = new Map<string, string>(ownedPaths);
@@ -666,7 +668,13 @@ export class SyncCommand {
     const msg = locales
       ? `chore(i18n): sync translations for ${locales}`
       : 'chore(i18n): sync translation lockfile';
-    await execFileAsync('git', ['commit', '-m', msg], { cwd });
+    // --only restricts the commit to the staged translation files, so anything
+    // else already in the index is not swept into an i18n commit.
+    await execFileAsync(
+      'git',
+      ['commit', '--only', '-m', msg, '--', ...filesToStage],
+      { cwd }
+    );
     Logger.info(`Auto-committed ${filesToStage.length} file(s): ${msg}`);
   }
 
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index 8893ee97..d5326ecb 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -331,9 +331,10 @@ export class WatchCommand {
         return;
       }
 
-      // Stage files - execFile passes arguments as array, preventing injection
+      // `--` stops git reading an output path that begins with a dash as an
+      // option: execFile prevents shell injection, not git's own option parsing.
       for (const file of outputFiles) {
-        await execFileAsync('git', ['add', file]);
+        await execFileAsync('git', ['add', '--', file]);
       }
 
       // Create commit message
@@ -343,8 +344,16 @@ export class WatchCommand {
 
       const commitMsg = `chore(i18n): auto-translate ${sourceFile} to ${langs}`;
 
-      // Commit - commit message is passed as array argument, preventing injection
-      await execFileAsync('git', ['commit', '-m', commitMsg]);
+      // --only restricts the commit to the translated outputs, so anything else
+      // already staged in the index is not swept into an i18n commit.
+      await execFileAsync('git', [
+        'commit',
+        '--only',
+        '-m',
+        commitMsg,
+        '--',
+        ...outputFiles,
+      ]);
 
       Logger.success(chalk.green('✓ Auto-committed translations'));
     } catch (error) {
diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index f9c3d859..e7c4c7f1 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -825,8 +825,14 @@ describe('SyncCommand', () => {
       const gitCalls = calls.map((c: unknown[]) => [c[0], c[1]]);
 
       expect(gitCalls).toContainEqual(['git', ['rev-parse', '--git-dir']]);
-      expect(gitCalls).toContainEqual(['git', ['add', 'locales/de.json']]);
-      expect(gitCalls).toContainEqual(['git', ['add', '.deepl-sync.lock']]);
+      expect(gitCalls).toContainEqual([
+        'git',
+        ['add', '--', 'locales/de.json'],
+      ]);
+      expect(gitCalls).toContainEqual([
+        'git',
+        ['add', '--', '.deepl-sync.lock'],
+      ]);
       expect(gitCalls).toContainEqual(
         expect.arrayContaining([
           'git',
@@ -854,8 +860,14 @@ describe('SyncCommand', () => {
       const calls = mockExecFile.mock.calls;
       const gitCalls = calls.map((c: unknown[]) => [c[0], c[1]]);
 
-      expect(gitCalls).toContainEqual(['git', ['add', 'locales/de.json']]);
-      expect(gitCalls).not.toContainEqual(['git', ['add', '.deepl-sync.lock']]);
+      expect(gitCalls).toContainEqual([
+        'git',
+        ['add', '--', 'locales/de.json'],
+      ]);
+      expect(gitCalls).not.toContainEqual([
+        'git',
+        ['add', '--', '.deepl-sync.lock'],
+      ]);
     });
 
     it('should pass cwd=config.projectRoot to every git invocation', async () => {
@@ -903,20 +915,76 @@ describe('SyncCommand', () => {
       const calls = mockExecFile.mock.calls;
       const gitCalls = calls.map((c: unknown[]) => [c[0], c[1]]);
 
-      expect(gitCalls).toContainEqual(['git', ['add', 'locales/de.json']]);
-      expect(gitCalls).toContainEqual(['git', ['add', 'locales/fr.json']]);
-      expect(gitCalls).toContainEqual(['git', ['add', '.deepl-sync.lock']]);
+      expect(gitCalls).toContainEqual([
+        'git',
+        ['add', '--', 'locales/de.json'],
+      ]);
+      expect(gitCalls).toContainEqual([
+        'git',
+        ['add', '--', 'locales/fr.json'],
+      ]);
+      expect(gitCalls).toContainEqual([
+        'git',
+        ['add', '--', '.deepl-sync.lock'],
+      ]);
 
       const commitCall = calls.find(
         (c: unknown[]) =>
           Array.isArray(c[1]) && (c[1] as string[]).includes('commit')
       );
       expect(commitCall).toBeDefined();
-      const commitMsg = commitCall![1][2];
+      const commitArgs = commitCall![1];
+      const commitMsg = commitArgs[commitArgs.indexOf('-m') + 1];
       expect(commitMsg).toContain('de');
       expect(commitMsg).toContain('fr');
     });
 
+    it('should pass a dash-leading target path after -- so git cannot read it as an option', async () => {
+      // A target_path_pattern rendering a leading dash reaches git as a pathspec;
+      // without `--`, git parses it as an option and stages unrelated files.
+      mockPorcelain = ' M --pathspec-from-file=de\0';
+      const result = makeResult({
+        fileResults: [{ ...writtenFile, file: '--pathspec-from-file=de' }],
+        lockUpdated: false,
+      });
+      const command = new SyncCommand(createMockSyncService(result));
+
+      await command.run({ autoCommit: true });
+
+      const addCall = mockExecFile.mock.calls.find(
+        (c: unknown[]) => Array.isArray(c[1]) && (c[1] as string[])[0] === 'add'
+      );
+      expect(addCall).toBeDefined();
+      const addArgs = addCall![1];
+      expect(addArgs.indexOf('--')).toBeLessThan(
+        addArgs.indexOf('--pathspec-from-file=de')
+      );
+    });
+
+    it('should restrict the commit to the staged translation files', async () => {
+      // Without --only plus an explicit pathspec, git commit takes the whole
+      // index, sweeping in anything the user staged separately.
+      mockPorcelain = ' M locales/de.json\0';
+      const result = makeResult({
+        fileResults: [writtenFile],
+        lockUpdated: false,
+      });
+      const command = new SyncCommand(createMockSyncService(result));
+
+      await command.run({ autoCommit: true });
+
+      const commitCall = mockExecFile.mock.calls.find(
+        (c: unknown[]) =>
+          Array.isArray(c[1]) && (c[1] as string[])[0] === 'commit'
+      );
+      expect(commitCall).toBeDefined();
+      const commitArgs = commitCall![1];
+      expect(commitArgs).toContain('--only');
+      expect(commitArgs.slice(commitArgs.indexOf('--') + 1)).toEqual([
+        'locales/de.json',
+      ]);
+    });
+
     it('should log warning and skip when not a git repository', async () => {
       mockExecFile.mockImplementation(
         (

From 72149d7796cc7bc5a448445fe7a02b0e1272a3ee Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 16:14:52 +0200
Subject: [PATCH 114/256] fix(deps): pin brace-expansion to >=5.0.9 via
 overrides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`npm audit --audit-level=moderate --omit=dev` — the gate security.yml runs on
every push and nightly — was failing on GHSA-rgw5-rvv9-x895, an unbounded
intermediate-array DoS in the `brace-expansion` copy reached through the
production dependency `minimatch`. 5.0.9 satisfies minimatch's own `^5.0.8`,
so no minimatch bump is needed.

Declared under `overrides` rather than `dependencies`: the CLI never imports
the package, and declaring it fails `npm run check-deps`, which rejects a
dependency that no file under `src/` references.

Not exploitable through this CLI — minimatch rejects a pattern long enough to
trigger the quadratic path with its own "pattern is too long" guard, and any
pattern under that cap expands in single-digit milliseconds. Fixed to clear the
advisory and unblock the gate.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md      |  2 ++
 package-lock.json | 48 +++--------------------------------------------
 package.json      |  3 +++
 3 files changed, 8 insertions(+), 45 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd500e1f..f84163fe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -357,6 +357,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
 
+- **deps**: `brace-expansion` is pinned to `>=5.0.9` through an `overrides` entry, resolving GHSA-rgw5-rvv9-x895 (unbounded intermediate arrays) in the copy reached via `minimatch`. `npm audit --audit-level=moderate --omit=dev` — the gate `security.yml` runs on every push and nightly — was failing. It is an `overrides` entry rather than a dependency because the CLI does not import the package, and declaring it would fail `check-deps`.
+
 - **config**: `ConfigService.save()` writes through an unpredictably named temp file created with an exclusive flag, instead of a fixed `config.json.tmp`. A symlink planted at the predictable path redirected the config — which holds the API key in plaintext — to a path of the planter's choosing, and the subsequent rename left `config.json` as that symlink, so every later write followed it too. The mode is also applied with `chmod` after creation, which the umask cannot widen.
 
 - **tests**: The test suite no longer inherits real credentials or the real config directory. Suites that spawn the bare `deepl` command cannot be intercepted by nock, so they reached the live DeepL API with whatever key was exported and read and wrote the developer's cache database; cached responses matching this suite's fixtures were recovered from a real cache, confirming it had happened. `globalSetup` now clears `DEEPL_API_KEY`, `TMS_API_KEY` and `TMS_TOKEN` and points `DEEPL_CONFIG_DIR` at a temporary directory before workers fork.
diff --git a/package-lock.json b/package-lock.json
index 5130390d..8fe6751d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -3952,9 +3952,9 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "5.0.8",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.8.tgz",
-      "integrity": "sha512-JZyDyq3D4AUifKTPOB7DELf6XsB3WdPuNxCtob1vFXPsSXhdAiHBWJ/tJ8HAc9aH84BK+5JFZLNkJKx3G9kzQg==",
+      "version": "5.0.9",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
+      "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
@@ -4341,13 +4341,6 @@
         "node": ">=22.12.0"
       }
     },
-    "node_modules/concat-map": {
-      "version": "0.0.1",
-      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
-      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/conventional-changelog-angular": {
       "version": "9.2.1",
       "resolved": "https://registry.npmjs.org/conventional-changelog-angular/-/conventional-changelog-angular-9.2.1.tgz",
@@ -5445,23 +5438,6 @@
         "tslib": "2"
       }
     },
-    "node_modules/glob/node_modules/balanced-match": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
-      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/glob/node_modules/brace-expansion": {
-      "version": "2.1.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.2.tgz",
-      "integrity": "sha512-w5JZcKgdhDOgOwm8H+KgbosopHMuGcl6qbulwjtz3SM7I7P3yW1eAjzMPLrIE+NQ9vjgANKHWeMHnrT0OXW1oA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "balanced-match": "^1.0.0"
-      }
-    },
     "node_modules/glob/node_modules/minimatch": {
       "version": "9.0.9",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
@@ -8550,24 +8526,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/test-exclude/node_modules/balanced-match": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
-      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/test-exclude/node_modules/brace-expansion": {
-      "version": "1.1.16",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
-      "integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "balanced-match": "^1.0.0",
-        "concat-map": "0.0.1"
-      }
-    },
     "node_modules/test-exclude/node_modules/glob": {
       "version": "7.2.3",
       "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
diff --git a/package.json b/package.json
index a7fc770c..94c2fc82 100644
--- a/package.json
+++ b/package.json
@@ -66,6 +66,9 @@
     "node": ">=24.0.0",
     "npm": ">=9.0.0"
   },
+  "overrides": {
+    "brace-expansion": "^5.0.9"
+  },
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
     "axios": "^1.7.9",

From 60af011684e7769badacd81e7d1284cc04afc9e6 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 16:34:08 +0200
Subject: [PATCH 115/256] fix(sync): bound glob brace expansion before it
 reaches fast-glob
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

fast-glob expands brace groups through `braces`, which caps only its
input length (10000) and places no bound on the expansion it produces —
unlike the similarly named `brace-expansion`. The expansion is a product,
so a 1007-byte `include` pattern of 200 `{a,b}` groups in a repo-supplied
`.deepl-sync.yaml` ended `deepl sync` and `deepl sync validate` with
`FATAL ERROR: Ineffective mark-compacts near heap limit` (SIGABRT, exit
134). An abort is not a catchable exception, so the per-bucket error
handling could not contain it, and the generated pre-commit hook and the
documented CI step died the same way. 20 groups is only 107 characters
and already wedges the run.

Bound every pattern-bearing config field at load: `buckets.*.include`,
`buckets.*.exclude`, top-level `ignore`, and `context.scan_paths`. The
bound is a conservative over-approximation computed without expanding
anything, counts numeric and alpha ranges by cardinality, and folds
unbalanced groups in as if closed so an unclosed `{` cannot smuggle a
bomb past it. It is iterative because a recursive walk would itself
stack-overflow on a deeply nested pattern. Neither cap is configurable —
the attacker supplies the config — and both sit below the point where
`braces` throws, making its RangeError and SyntaxError paths unreachable.

Verified end to end: exit 134 with the guard removed, exit 7 with an
actionable message naming the field with it in place.

Refs: cli-8kr2.1

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +
 docs/SYNC.md                                  |   2 +
 src/sync/sync-config.ts                       |  27 +++
 src/utils/glob-safety.ts                      | 166 ++++++++++++++++++
 tests/e2e/cli-sync-glob-bomb.e2e.test.ts      | 156 ++++++++++++++++
 .../sync/sync-config-glob-expansion.test.ts   | 100 +++++++++++
 tests/unit/utils/glob-safety.test.ts          | 136 ++++++++++++++
 7 files changed, 589 insertions(+)
 create mode 100644 src/utils/glob-safety.ts
 create mode 100644 tests/e2e/cli-sync-glob-bomb.e2e.test.ts
 create mode 100644 tests/unit/sync/sync-config-glob-expansion.test.ts
 create mode 100644 tests/unit/utils/glob-safety.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f84163fe..0fe2ebd3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -357,6 +357,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
 
+- **sync**: glob patterns from `.deepl-sync.yaml` are bounded before they reach fast-glob, so a hostile checkout can no longer end the process with an uncatchable out-of-memory abort. fast-glob expands brace groups through `braces`, a different package from `brace-expansion` despite the name, and `braces` caps only its input length — the expansion it produces is a product with no bound at all. A 1007-byte `include` pattern of 200 `{a,b}` groups therefore killed `deepl sync` and `deepl sync validate` with `FATAL ERROR: Ineffective mark-compacts near heap limit` (SIGABRT, exit 134). An abort is not a JavaScript exception, so the per-bucket error handling could not contain it, and the tool's own generated pre-commit hook and documented CI step were killed the same way. Brace expansion is a product rather than a sum, so this needs very little input: 20 groups is 107 characters and already wedges the run. Every pattern-bearing field is now checked at config load — `buckets.*.include`, `buckets.*.exclude`, top-level `ignore`, and `context.scan_paths` — rejecting anything that expands past 1000 paths or exceeds 4096 characters with a `ConfigError` (exit 7) naming the field. The bound is a conservative over-approximation computed without expanding anything, it counts numeric and alpha ranges (`{1..9}`, `{a..e}`) by cardinality, and it folds unbalanced groups in as if closed so an unclosed `{` cannot smuggle a bomb past it. Neither cap is configurable, since the attacker in this scenario supplies the config; both sit below the point where `braces` itself throws, so its `RangeError` and `SyntaxError` paths are unreachable too. Realistic patterns are nowhere near the cap — `{en,de,fr}/**/*.{json,yaml,yml}` expands to 9.
+
 - **deps**: `brace-expansion` is pinned to `>=5.0.9` through an `overrides` entry, resolving GHSA-rgw5-rvv9-x895 (unbounded intermediate arrays) in the copy reached via `minimatch`. `npm audit --audit-level=moderate --omit=dev` — the gate `security.yml` runs on every push and nightly — was failing. It is an `overrides` entry rather than a dependency because the CLI does not import the package, and declaring it would fail `check-deps`.
 
 - **config**: `ConfigService.save()` writes through an unpredictably named temp file created with an exclusive flag, instead of a fixed `config.json.tmp`. A symlink planted at the predictable path redirected the config — which holds the API key in plaintext — to a path of the planter's choosing, and the subsequent rename left `config.json` as that symlink, so every later write followed it too. The mode is also applied with `chmod` after creation, which the umask cannot widen.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 9d4b6886..427bb0c2 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -153,6 +153,8 @@ Each bucket maps a format name to a set of file patterns. The format name must b
 | `target_path_pattern` | `string` | No | Template for target file paths. Use `{locale}` for the target locale and `{basename}` for the source filename. Required for formats where the source locale is not in the source file path (e.g., Android XML, XLIFF). |
 | `key_style` | `string` | No | Key format: `nested` (dot-separated keys become nested objects) or `flat` (keys preserved as-is). |
 
+**Glob pattern bounds.** Every glob string in the config — `include`, `exclude`, top-level `ignore`, and `context.scan_paths` — must expand to at most 1000 paths through its brace groups and be at most 4096 characters long. Both bounds are fixed and cannot be raised in the config: brace expansion is a product, so `{a,b}` repeated 20 times is only 107 characters but expands to over a million paths and exhausts the heap before any file is read. A pattern past either bound fails at config load with `ConfigError` (exit 7), naming the field. Realistic patterns are far below the cap — `{en,de,fr}/**/*.{json,yaml,yml}` expands to 9.
+
 #### `translation`
 
 | Field | Type | Required | Default | Description |
diff --git a/src/sync/sync-config.ts b/src/sync/sync-config.ts
index 21208a24..3a3b0fdf 100644
--- a/src/sync/sync-config.ts
+++ b/src/sync/sync-config.ts
@@ -4,6 +4,7 @@ import * as YAML from 'yaml';
 import { ConfigError } from '../utils/errors.js';
 import { safeReadFileSync } from '../utils/safe-read-file.js';
 import { sanitizeForTerminal } from '../utils/control-chars.js';
+import { assertBoundedGlobExpansion } from '../utils/glob-safety.js';
 import type {
   SyncConfig,
   SyncBucketConfig,
@@ -398,6 +399,16 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
           `Replace the absolute path in buckets.${safeName}.include with a path relative to the project root.`
         );
       }
+      assertBoundedGlobExpansion(inc, `buckets.${safeName}.include`);
+    }
+    // exclude joins include on the way to fast-glob (as its `ignore` option),
+    // so it needs the same expansion bound.
+    if (Array.isArray(b['exclude'])) {
+      for (const exc of b['exclude']) {
+        if (typeof exc === 'string') {
+          assertBoundedGlobExpansion(exc, `buckets.${safeName}.exclude`);
+        }
+      }
     }
     if (b['target_path_pattern'] !== undefined) {
       if (typeof b['target_path_pattern'] !== 'string') {
@@ -575,6 +586,22 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
       KNOWN_CONTEXT_KEYS,
       'context'
     );
+    const scanPaths = (obj['context'] as Record<string, unknown>)['scan_paths'];
+    if (Array.isArray(scanPaths)) {
+      for (const scanPath of scanPaths) {
+        if (typeof scanPath === 'string') {
+          assertBoundedGlobExpansion(scanPath, 'context.scan_paths');
+        }
+      }
+    }
+  }
+
+  if (Array.isArray(obj['ignore'])) {
+    for (const ignored of obj['ignore']) {
+      if (typeof ignored === 'string') {
+        assertBoundedGlobExpansion(ignored, 'ignore');
+      }
+    }
   }
 
   const tmsBlock = obj['tms'] as Record<string, unknown> | undefined;
diff --git a/src/utils/glob-safety.ts b/src/utils/glob-safety.ts
new file mode 100644
index 00000000..e609b305
--- /dev/null
+++ b/src/utils/glob-safety.ts
@@ -0,0 +1,166 @@
+import { ConfigError } from './errors.js';
+import { sanitizeForTerminal } from './control-chars.js';
+
+/**
+ * fast-glob expands brace groups through `braces`, which bounds only its INPUT
+ * length (10000 characters) and places no bound on the expansion it produces —
+ * unlike `brace-expansion`, whose similar name hides a very different set of
+ * caps. The expansion is the product of every group's alternatives, so 20
+ * `{a,b}` groups fit in 107 characters and allocate ~600MB, and 22 groups end
+ * the process with a V8 out-of-memory abort. An abort is not a catchable
+ * exception, so patterns must be bounded before they reach fast-glob at all.
+ *
+ * The cap sits at or below the `braces` range limit (1000) so that a range
+ * wider than the limit is rejected here rather than surfacing as a raw
+ * RangeError from inside the glob walk.
+ */
+export const MAX_GLOB_EXPANSION = 1000;
+
+/**
+ * Length ceiling applied before `braces` sees the pattern, keeping its own
+ * 10000-character SyntaxError unreachable.
+ */
+export const MAX_GLOB_PATTERN_LENGTH = 4096;
+
+const PATTERN_IN_MESSAGE_MAX = 80;
+
+interface Frame {
+  /** Product of the expansion counts concatenated in the current alternative. */
+  current: number;
+  /** Summed expansion counts of the alternatives already closed by a comma. */
+  completed: number;
+  /** Index just past the `{` that opened this frame. */
+  bodyStart: number;
+  hasComma: boolean;
+}
+
+/**
+ * Cardinality of a `braces` range body (`1..9`, `1..9..2`, `a..e`), or null if
+ * the body is not a range.
+ */
+function rangeCardinality(body: string): number | null {
+  const parts = body.split('..');
+  if (parts.length < 2 || parts.length > 3) return null;
+
+  const [from, to, rawStep] = parts;
+  let step = 1;
+  if (rawStep !== undefined) {
+    if (!/^-?\d+$/.test(rawStep)) return null;
+    step = Math.abs(Number(rawStep)) || 1;
+  }
+
+  if (/^-?\d+$/.test(from!) && /^-?\d+$/.test(to!)) {
+    return Math.floor(Math.abs(Number(to) - Number(from)) / step) + 1;
+  }
+  if (/^[a-zA-Z]$/.test(from!) && /^[a-zA-Z]$/.test(to!)) {
+    const span = Math.abs(to!.charCodeAt(0) - from!.charCodeAt(0));
+    return Math.floor(span / step) + 1;
+  }
+  return null;
+}
+
+function closeFrame(frame: Frame, pattern: string, end: number): number {
+  if (frame.hasComma) {
+    return frame.completed + frame.current;
+  }
+  // A comma-less group is literal in `braces` (`{en}` stays `{en}`) unless it
+  // is a range, but it may still contain a group that does expand.
+  const body = pattern.slice(frame.bodyStart, end);
+  return (rangeCardinality(body) ?? 1) * frame.current;
+}
+
+/**
+ * Conservative upper bound on the number of paths a glob pattern's brace
+ * groups expand to. Saturates at `MAX_GLOB_EXPANSION + 1` rather than
+ * computing the full product, and over-approximates unbalanced groups so an
+ * unclosed `{` cannot be used to smuggle a bomb past the bound.
+ *
+ * Iterative by design: a recursive walk would itself stack-overflow on a
+ * deeply nested pattern.
+ */
+export function countGlobExpansion(pattern: string): number {
+  const saturated = MAX_GLOB_EXPANSION + 1;
+  const root: Frame = {
+    current: 1,
+    completed: 0,
+    bodyStart: 0,
+    hasComma: false,
+  };
+  const stack: Frame[] = [root];
+
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i];
+
+    if (ch === '\\') {
+      i += 1;
+      continue;
+    }
+
+    if (ch === '{') {
+      stack.push({
+        current: 1,
+        completed: 0,
+        bodyStart: i + 1,
+        hasComma: false,
+      });
+      continue;
+    }
+
+    if (stack.length === 1) continue;
+
+    const top = stack[stack.length - 1]!;
+
+    if (ch === ',') {
+      top.completed += top.current;
+      top.current = 1;
+      top.hasComma = true;
+      if (top.completed > MAX_GLOB_EXPANSION) return saturated;
+      continue;
+    }
+
+    if (ch === '}') {
+      stack.pop();
+      const parent = stack[stack.length - 1]!;
+      parent.current *= closeFrame(top, pattern, i);
+      if (parent.current > MAX_GLOB_EXPANSION) return saturated;
+    }
+  }
+
+  // Unbalanced `{` groups are literal to `braces`, but folding them in as if
+  // closed keeps the bound an over-approximation.
+  while (stack.length > 1) {
+    const frame = stack.pop()!;
+    const parent = stack[stack.length - 1]!;
+    parent.current *= closeFrame(frame, pattern, pattern.length);
+    if (parent.current > MAX_GLOB_EXPANSION) return saturated;
+  }
+
+  return root.current;
+}
+
+/**
+ * Reject a glob pattern whose brace expansion or raw length could wedge the
+ * process inside fast-glob. `field` names the config path for the error.
+ */
+export function assertBoundedGlobExpansion(
+  pattern: string,
+  field: string
+): void {
+  if (pattern.length > MAX_GLOB_PATTERN_LENGTH) {
+    throw new ConfigError(
+      `${field} entry is ${pattern.length} characters long, exceeding the ${MAX_GLOB_PATTERN_LENGTH}-character limit for a glob pattern`,
+      `Shorten the pattern in ${field}, or split it across several entries.`
+    );
+  }
+
+  if (countGlobExpansion(pattern) > MAX_GLOB_EXPANSION) {
+    const shown =
+      pattern.length > PATTERN_IN_MESSAGE_MAX
+        ? `${pattern.slice(0, PATTERN_IN_MESSAGE_MAX)}…`
+        : pattern;
+    throw new ConfigError(
+      `${field} entry "${sanitizeForTerminal(shown)}" expands to more than ${MAX_GLOB_EXPANSION} paths through its brace groups`,
+      `Reduce the number of {...} alternatives in ${field}, or list the paths as separate entries.`
+    );
+  }
+}
diff --git a/tests/e2e/cli-sync-glob-bomb.e2e.test.ts b/tests/e2e/cli-sync-glob-bomb.e2e.test.ts
new file mode 100644
index 00000000..10fee648
--- /dev/null
+++ b/tests/e2e/cli-sync-glob-bomb.e2e.test.ts
@@ -0,0 +1,156 @@
+/**
+ * E2E regression for the brace-expansion bomb in a repo-supplied
+ * `.deepl-sync.yaml`. fast-glob expands brace groups through `braces`, which
+ * bounds only its input length: a 1KB include pattern of 200 `{a,b}` groups
+ * used to end the process with a V8 out-of-memory abort (SIGABRT, exit 134).
+ * An abort is not a catchable exception, so no try/catch inside sync could
+ * contain it — the guard has to reject the pattern before fast-glob sees it.
+ * A 107-byte pattern of 20 groups wedged the run too, there as a stack
+ * overflow rather than an OOM.
+ *
+ * The child runs with a small heap so that a regression aborts quickly and
+ * deterministically instead of timing out the test.
+ */
+
+import { spawnSync, SpawnSyncReturns } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const CONFIG_EXIT_CODE = 7;
+
+describe('CLI sync glob bomb containment', () => {
+  const testConfig = createTestConfigDir('e2e-sync-glob-bomb');
+  const testFiles = createTestDir('e2e-sync-glob-bomb-files');
+
+  interface Run {
+    status: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+  }
+
+  function runCli(args: string[]): Run {
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        cwd: testFiles.path,
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: testConfig.path,
+          NO_COLOR: '1',
+          NODE_OPTIONS: '--max-old-space-size=512',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 30000,
+      }
+    );
+    return {
+      status: result.status,
+      signal: result.signal,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  function writeSyncConfig(includeGlob: string): void {
+    fs.writeFileSync(
+      path.join(testFiles.path, '.deepl-sync.yaml'),
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - de',
+        'buckets:',
+        '  json:',
+        '    include:',
+        `      - '${includeGlob}'`,
+        '    target_path_pattern: "locales/{locale}.json"',
+        '',
+      ].join('\n')
+    );
+  }
+
+  beforeAll(() => {
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify(
+        {
+          auth: { apiKey: 'mock-api-key-for-testing:fx' },
+          api: { baseUrl: 'http://127.0.0.1:1/', usePro: false },
+          defaults: {
+            targetLangs: [],
+            formality: 'default',
+            preserveFormatting: true,
+          },
+          cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+          output: { format: 'text', verbose: false, color: false },
+          watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+        },
+        null,
+        2
+      )
+    );
+    const localesDir = path.join(testFiles.path, 'locales');
+    fs.mkdirSync(localesDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(localesDir, 'en.json'),
+      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
+    );
+  });
+
+  afterEach(() => {
+    const configPath = path.join(testFiles.path, '.deepl-sync.yaml');
+    if (fs.existsSync(configPath)) fs.rmSync(configPath);
+  });
+
+  it('should reject the 1KB brace bomb instead of aborting the process', () => {
+    writeSyncConfig(`${'{a,b}'.repeat(200)}/*.json`);
+    const result = runCli(['sync', 'validate']);
+
+    expect(result.signal).toBeNull();
+    expect(result.status).toBe(CONFIG_EXIT_CODE);
+    expect(result.stderr).not.toMatch(/FATAL ERROR|heap out of memory/i);
+    expect(result.stderr).toMatch(/expands to more than/i);
+  });
+
+  it('should name the offending field in the error', () => {
+    writeSyncConfig(`${'{a,b}'.repeat(200)}/*.json`);
+    const result = runCli(['sync', 'validate']);
+
+    expect(result.stderr).toMatch(/buckets\.json\.include/);
+  });
+
+  it('should reject a 107-byte brace bomb', () => {
+    writeSyncConfig(`${'{a,b}'.repeat(20)}/*.json`);
+    const result = runCli(['sync', 'validate']);
+
+    expect(result.signal).toBeNull();
+    expect(result.status).toBe(CONFIG_EXIT_CODE);
+  });
+
+  it('should emit the JSON error envelope rather than aborting', () => {
+    writeSyncConfig(`${'{a,b}'.repeat(200)}/*.json`);
+    const result = runCli(['sync', 'validate', '--format', 'json']);
+
+    expect(result.signal).toBeNull();
+    expect(result.status).toBe(CONFIG_EXIT_CODE);
+    const envelope = JSON.parse(result.stderr) as {
+      ok: boolean;
+      error: { message: string };
+    };
+    expect(envelope.ok).toBe(false);
+    expect(envelope.error.message).toMatch(/expands to more than/i);
+  });
+
+  it('should still accept a realistic brace glob', () => {
+    writeSyncConfig('locales/{en,de}.json');
+    const result = runCli(['sync', 'validate']);
+
+    expect(result.signal).toBeNull();
+    expect(result.status).not.toBe(CONFIG_EXIT_CODE);
+  });
+});
diff --git a/tests/unit/sync/sync-config-glob-expansion.test.ts b/tests/unit/sync/sync-config-glob-expansion.test.ts
new file mode 100644
index 00000000..6a4207ed
--- /dev/null
+++ b/tests/unit/sync/sync-config-glob-expansion.test.ts
@@ -0,0 +1,100 @@
+/**
+ * A repo-supplied `.deepl-sync.yaml` must not be able to hand fast-glob a
+ * pattern whose brace expansion exhausts the heap. `braces` bounds only its
+ * input length, so a 107-byte pattern of 20 `{a,b}` groups allocates ~600MB
+ * and 22 groups aborts the process with a V8 OOM — an abort, not an exception,
+ * so no per-bucket try/catch can contain it.
+ *
+ * Every config field whose strings reach fast-glob is covered here: bucket
+ * `include` and `exclude`, top-level `ignore`, and `context.scan_paths`.
+ */
+
+import { validateSyncConfig } from '../../../src/sync/sync-config';
+import { ConfigError } from '../../../src/utils/errors';
+
+const BOMB = `${'{a,b}'.repeat(200)}/*.json`;
+const SMALL_BOMB = `${'{a,b}'.repeat(20)}/*.json`;
+
+function baseConfig(): Record<string, unknown> {
+  return {
+    version: 1,
+    source_locale: 'en',
+    target_locales: ['de'],
+    buckets: {
+      json: {
+        include: ['locales/*.json'],
+        target_path_pattern: 'locales/{locale}.json',
+      },
+    },
+  };
+}
+
+describe('sync config glob expansion bounds', () => {
+  it('should reject a brace bomb in bucket include', () => {
+    const config = baseConfig();
+    (config['buckets'] as Record<string, Record<string, unknown>>)['json']![
+      'include'
+    ] = [BOMB];
+    expect(() => validateSyncConfig(config)).toThrow(ConfigError);
+  });
+
+  it('should reject a brace bomb in bucket exclude', () => {
+    const config = baseConfig();
+    (config['buckets'] as Record<string, Record<string, unknown>>)['json']![
+      'exclude'
+    ] = [BOMB];
+    expect(() => validateSyncConfig(config)).toThrow(ConfigError);
+  });
+
+  it('should reject a brace bomb in top-level ignore', () => {
+    const config = baseConfig();
+    config['ignore'] = [BOMB];
+    expect(() => validateSyncConfig(config)).toThrow(ConfigError);
+  });
+
+  it('should reject a brace bomb in context.scan_paths', () => {
+    const config = baseConfig();
+    config['context'] = { enabled: true, scan_paths: [BOMB] };
+    expect(() => validateSyncConfig(config)).toThrow(ConfigError);
+  });
+
+  it('should reject the sub-1KB variant that already exhausts the heap', () => {
+    const config = baseConfig();
+    (config['buckets'] as Record<string, Record<string, unknown>>)['json']![
+      'include'
+    ] = [SMALL_BOMB];
+    expect(() => validateSyncConfig(config)).toThrow(ConfigError);
+  });
+
+  it('should reject a bomb hidden behind a benign first entry', () => {
+    const config = baseConfig();
+    (config['buckets'] as Record<string, Record<string, unknown>>)['json']![
+      'include'
+    ] = ['locales/*.json', BOMB];
+    expect(() => validateSyncConfig(config)).toThrow(ConfigError);
+  });
+
+  it('should name the offending bucket and field', () => {
+    const config = baseConfig();
+    (config['buckets'] as Record<string, Record<string, unknown>>)['json']![
+      'exclude'
+    ] = [BOMB];
+    expect(() => validateSyncConfig(config)).toThrow(/buckets\.json\.exclude/);
+  });
+
+  it('should still accept realistic brace usage in every field', () => {
+    const config = baseConfig();
+    (config['buckets'] as Record<string, Record<string, unknown>>)['json']![
+      'include'
+    ] = ['{en,de,fr}/**/*.{json,yaml,yml}'];
+    (config['buckets'] as Record<string, Record<string, unknown>>)['json']![
+      'exclude'
+    ] = ['**/{node_modules,dist,coverage}/**'];
+    config['ignore'] = ['**/*.{min,bundle}.json'];
+    config['context'] = {
+      enabled: true,
+      scan_paths: ['src/**/*.{ts,tsx,js,jsx}'],
+    };
+    expect(() => validateSyncConfig(config)).not.toThrow();
+  });
+});
diff --git a/tests/unit/utils/glob-safety.test.ts b/tests/unit/utils/glob-safety.test.ts
new file mode 100644
index 00000000..973db7b7
--- /dev/null
+++ b/tests/unit/utils/glob-safety.test.ts
@@ -0,0 +1,136 @@
+/**
+ * fast-glob expands brace groups through `braces`, which caps only its INPUT
+ * length and places no bound at all on the expansion it produces. The product
+ * of alternatives is therefore unbounded: 20 `{a,b}` groups fit in 107 bytes
+ * and allocate ~600MB, and 22 groups abort the process with a V8 OOM that no
+ * try/catch can contain. These tests pin the pre-flight bound that keeps such
+ * a pattern away from fast-glob.
+ */
+
+import {
+  MAX_GLOB_EXPANSION,
+  MAX_GLOB_PATTERN_LENGTH,
+  assertBoundedGlobExpansion,
+  countGlobExpansion,
+} from '../../../src/utils/glob-safety';
+import { ConfigError } from '../../../src/utils/errors';
+
+describe('countGlobExpansion', () => {
+  it.each([
+    ['a literal path', 'locales/en.json', 1],
+    ['a wildcard', 'src/**/*.json', 1],
+    ['a single brace group', 'locales/{en,de}.json', 2],
+    ['a three-way group', '**/*.{json,yaml,yml}', 3],
+    ['sibling groups multiplying', '{en,de}/**/*.{json,yaml}', 4],
+    ['a nested group', '{a,{b,c}}/*.json', 3],
+    ['an empty alternative', '{,foo}/*.json', 2],
+  ])('should count %s as %i', (_label, pattern, expected) => {
+    expect(countGlobExpansion(pattern)).toBe(expected);
+  });
+
+  it('should treat a comma-less brace group as literal', () => {
+    expect(countGlobExpansion('locales/{en}.json')).toBe(1);
+  });
+
+  it('should count a numeric range by its cardinality', () => {
+    expect(countGlobExpansion('page{1..9}/*.json')).toBe(9);
+  });
+
+  it('should count a stepped numeric range by its cardinality', () => {
+    expect(countGlobExpansion('page{1..9..2}/*.json')).toBe(5);
+  });
+
+  it('should count an alpha range by its cardinality', () => {
+    expect(countGlobExpansion('{a..e}/*.json')).toBe(5);
+  });
+
+  it('should ignore escaped braces', () => {
+    expect(countGlobExpansion('lit\\{a,b\\}/*.json')).toBe(1);
+  });
+
+  it('should saturate rather than compute the full product', () => {
+    expect(countGlobExpansion('{a,b}'.repeat(200))).toBeGreaterThan(
+      MAX_GLOB_EXPANSION
+    );
+  });
+
+  it('should over-approximate an unbalanced group rather than under-count it', () => {
+    expect(countGlobExpansion('{a,b}'.repeat(200) + '{c,d')).toBeGreaterThan(
+      MAX_GLOB_EXPANSION
+    );
+  });
+
+  it('should not recurse on deeply nested groups', () => {
+    let nested = 'a';
+    for (let i = 0; i < 5000; i += 1) nested = `{${nested},b}`;
+    expect(() => countGlobExpansion(nested)).not.toThrow(RangeError);
+  });
+});
+
+describe('assertBoundedGlobExpansion', () => {
+  it.each([
+    ['a literal path', 'locales/en.json'],
+    ['a recursive wildcard', 'src/**/*.json'],
+    ['a realistic multi-extension glob', '{en,de,fr}/**/*.{json,yaml,yml}'],
+    ['an extglob', 'src/@(foo|bar)/*.json'],
+  ])('should accept %s', (_label, pattern) => {
+    expect(() =>
+      assertBoundedGlobExpansion(pattern, 'buckets.json.include')
+    ).not.toThrow();
+  });
+
+  it('should reject the 1KB brace bomb from the red-team repro', () => {
+    const bomb = '{a,b}'.repeat(200) + '/*.json';
+    expect(() =>
+      assertBoundedGlobExpansion(bomb, 'buckets.json.include')
+    ).toThrow(ConfigError);
+  });
+
+  it('should reject a pattern only 107 bytes long', () => {
+    const bomb = '{a,b}'.repeat(20) + '/*.json';
+    expect(bomb.length).toBeLessThan(120);
+    expect(() =>
+      assertBoundedGlobExpansion(bomb, 'buckets.json.include')
+    ).toThrow(ConfigError);
+  });
+
+  it('should name the field and the cap in the error', () => {
+    expect(() =>
+      assertBoundedGlobExpansion('{a,b}'.repeat(30), 'context.scan_paths')
+    ).toThrow(new RegExp(`context\\.scan_paths.*${MAX_GLOB_EXPANSION}`, 's'));
+  });
+
+  it('should sanitize control characters in the reported pattern', () => {
+    expect.assertions(2);
+    try {
+      assertBoundedGlobExpansion(`\x1b]0;x\x07${'{a,b}'.repeat(30)}`, 'ignore');
+    } catch (err) {
+      expect((err as ConfigError).message).not.toContain('\x1b');
+      expect((err as ConfigError).message).not.toContain('\x07');
+    }
+  });
+
+  it('should reject a pattern longer than the length cap before braces sees it', () => {
+    const long = `${'a'.repeat(MAX_GLOB_PATTERN_LENGTH + 1)}/*.json`;
+    expect(() => assertBoundedGlobExpansion(long, 'ignore')).toThrow(
+      ConfigError
+    );
+  });
+
+  it('should keep the length cap below the point where braces itself throws', () => {
+    expect(MAX_GLOB_PATTERN_LENGTH).toBeLessThan(10000);
+  });
+
+  it('should keep the expansion cap at or below the braces range limit', () => {
+    // `braces` throws a RangeError once a single range expands past 1000
+    // entries. Keeping the cap at or below that makes the RangeError
+    // unreachable, so a hostile range is a ConfigError, not a raw throw.
+    expect(MAX_GLOB_EXPANSION).toBeLessThanOrEqual(1000);
+  });
+
+  it('should reject a range wider than the cap', () => {
+    expect(() =>
+      assertBoundedGlobExpansion('page{1..100000}/*.json', 'ignore')
+    ).toThrow(ConfigError);
+  });
+});

From 2f42bf3bb9d952d8b9a07d3ccc92ab4c58673f8c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 16:40:24 +0200
Subject: [PATCH 116/256] fix(sync): enforce .git/.github containment on
 resolved paths, not just the pattern
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FORBIDDEN_TARGET_SEGMENTS exists so a translated-locale name can never
become VCS metadata or CI workflow code, but it had exactly one
enforcement site: inside the `if (target_path_pattern !== undefined)`
branch of config validation. A bucket that omitted the pattern reached
the default locale-substitution path with no check at all, so

  buckets.yaml.include: ['.github/workflows/en.yml']

made `deepl sync` write `.github/workflows/de.yml` whose `run:` body was
whatever the translation endpoint returned, at exit 0. The root
containment check accepted it because the path never leaves the root.

Move the check onto the resolved path in assertPathWithinRoot — the one
boundary every read and write in the pipeline passes through. That covers
the substitution branch and the multi-locale branch, which writes back to
the source path and never calls resolveTargetPath, and it cannot be
bypassed by a future call site that forgets. Segments are compared
relative to the project root, so a checkout living under a `.github`
directory is unaffected. The pattern-level check stays, so a bad
target_path_pattern is still reported at config load.

Verified: `sync`, `sync status`, and `sync validate` on a bucket rooted in
.github now exit 6 naming the directory, before any translation request,
and no de.yml is created.

Refs: cli-8kr2.3

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +
 docs/SYNC.md                                  |   2 +
 src/sync/sync-config.ts                       |   9 +-
 src/sync/sync-utils.ts                        |  26 ++-
 .../e2e/cli-sync-vcs-containment.e2e.test.ts  | 149 ++++++++++++++++++
 .../sync-forbidden-target-segments.test.ts    |  88 +++++++++++
 6 files changed, 271 insertions(+), 5 deletions(-)
 create mode 100644 tests/e2e/cli-sync-vcs-containment.e2e.test.ts
 create mode 100644 tests/unit/sync/sync-forbidden-target-segments.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0fe2ebd3..cbd972d0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -357,6 +357,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
 
+- **sync**: no sync path may resolve into `.git/` or `.github/` any more, closing a gap where the guard that exists to prevent exactly that was enforced on one branch only. `FORBIDDEN_TARGET_SEGMENTS` was checked against a literal `target_path_pattern`, so a bucket that simply omitted the pattern reached the default locale-substitution path unguarded: `buckets.yaml.include: ['.github/workflows/en.yml']` made `deepl sync` write `.github/workflows/de.yml` whose `run:` body was whatever the translation endpoint returned — CI workflow code under the influence of a hostile checkout or a hostile endpoint, at exit 0. The containment check on the project root accepted it, because the path never leaves the root. The check now sits on the resolved path inside `assertPathWithinRoot`, the one boundary every read and write in the pipeline passes through, so both the substitution branch and the multi-locale branch — which writes back to the source path and never calls `resolveTargetPath` at all — inherit it, and a future call site cannot forget it. A bucket rooted in `.github/` now fails at the source-file walk with exit 6 and a message naming the directory, before any translation request is made; the pattern-level check is kept as well, so a bad `target_path_pattern` is still reported at config load. Segments are compared relative to the project root, so a checkout living under a `.github` directory is unaffected, and `.gitlab/`, `.gitignore`, and paths merely containing `github` as a substring are untouched.
+
 - **sync**: glob patterns from `.deepl-sync.yaml` are bounded before they reach fast-glob, so a hostile checkout can no longer end the process with an uncatchable out-of-memory abort. fast-glob expands brace groups through `braces`, a different package from `brace-expansion` despite the name, and `braces` caps only its input length — the expansion it produces is a product with no bound at all. A 1007-byte `include` pattern of 200 `{a,b}` groups therefore killed `deepl sync` and `deepl sync validate` with `FATAL ERROR: Ineffective mark-compacts near heap limit` (SIGABRT, exit 134). An abort is not a JavaScript exception, so the per-bucket error handling could not contain it, and the tool's own generated pre-commit hook and documented CI step were killed the same way. Brace expansion is a product rather than a sum, so this needs very little input: 20 groups is 107 characters and already wedges the run. Every pattern-bearing field is now checked at config load — `buckets.*.include`, `buckets.*.exclude`, top-level `ignore`, and `context.scan_paths` — rejecting anything that expands past 1000 paths or exceeds 4096 characters with a `ConfigError` (exit 7) naming the field. The bound is a conservative over-approximation computed without expanding anything, it counts numeric and alpha ranges (`{1..9}`, `{a..e}`) by cardinality, and it folds unbalanced groups in as if closed so an unclosed `{` cannot smuggle a bomb past it. Neither cap is configurable, since the attacker in this scenario supplies the config; both sit below the point where `braces` itself throws, so its `RangeError` and `SyntaxError` paths are unreachable too. Realistic patterns are nowhere near the cap — `{en,de,fr}/**/*.{json,yaml,yml}` expands to 9.
 
 - **deps**: `brace-expansion` is pinned to `>=5.0.9` through an `overrides` entry, resolving GHSA-rgw5-rvv9-x895 (unbounded intermediate arrays) in the copy reached via `minimatch`. `npm audit --audit-level=moderate --omit=dev` — the gate `security.yml` runs on every push and nightly — was failing. It is an `overrides` entry rather than a dependency because the CLI does not import the package, and declaring it would fail `check-deps`.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 427bb0c2..b91ed83a 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -52,6 +52,8 @@ The lockfile tracks content hashes for every source string. On subsequent runs,
 
 All sync commands (`sync`, `sync push`, `sync pull`, `sync export`, `sync validate`) refuse to follow symbolic links when scanning `include` globs. A symlink matching a bucket pattern is silently skipped, preventing a hostile symlink (e.g., `locales/en.json` -> `/etc/passwd`) from exfiltrating files outside the project root to the TMS server or into an exported XLIFF.
 
+Sync also refuses to read or write any path resolving into `.git/` or `.github/`, whether it arrives as an `include` match or as a resolved target path. Translating a file into `.github/workflows/` would turn a target-locale filename into CI workflow code whose body came from the translation endpoint, so a bucket rooted there fails with exit 6 rather than being silently skipped. The check compares segments relative to the project root, so a checkout that itself lives under a `.github` directory is unaffected.
+
 ### Concurrent sync
 
 Only one `deepl sync` run is supported at a time per project directory. At startup, sync writes a `.deepl-sync.lock.pidfile` containing its PID; a second invocation that sees an existing pidfile whose PID is still alive exits with `ConfigError` (exit code 7). If the PID is dead (e.g., a previous run crashed), sync removes the stale pidfile with a warning and proceeds. The pidfile is deleted automatically on normal completion and on SIGINT/SIGTERM.
diff --git a/src/sync/sync-config.ts b/src/sync/sync-config.ts
index 3a3b0fdf..b250e050 100644
--- a/src/sync/sync-config.ts
+++ b/src/sync/sync-config.ts
@@ -26,9 +26,12 @@ export const SYNC_CONFIG_FILENAME = '.deepl-sync.yaml';
 // rejected rather than merely denylisted.
 export const LOCALE_CODE_RE = /^[a-zA-Z]{2,8}(-[a-zA-Z0-9]{2,8})*$/;
 
-// Directories a target_path_pattern must never resolve into: writing there
-// lets a translated-locale name become VCS metadata or CI workflow code.
-const FORBIDDEN_TARGET_SEGMENTS: ReadonlySet<string> = new Set([
+// Directories no sync path may resolve into: writing there lets a
+// translated-locale name become VCS metadata or CI workflow code. Enforced
+// both here against a literal target_path_pattern and, for every path the
+// pipeline actually reads or writes, in assertPathWithinRoot — the default
+// locale-substitution path has no pattern to inspect.
+export const FORBIDDEN_TARGET_SEGMENTS: ReadonlySet<string> = new Set([
   '.git',
   '.github',
 ]);
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index d3ca13de..df57d071 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -8,6 +8,7 @@ import type {
 } from '../formats/index.js';
 import { ValidationError } from '../utils/errors.js';
 import { sanitizeForTerminal } from '../utils/control-chars.js';
+import { FORBIDDEN_TARGET_SEGMENTS } from './sync-config.js';
 
 export function getParserForBucket(
   formatRegistry: FormatRegistry,
@@ -111,8 +112,9 @@ function realpathOrAncestor(absPath: string): string {
 }
 
 /**
- * Verify that an absolute path stays within the project root.
- * Throws ValidationError if path escapes.
+ * Verify that an absolute path is one the sync pipeline may read or write:
+ * inside the project root, and outside the repository's own control
+ * directories (`FORBIDDEN_TARGET_SEGMENTS`). Throws ValidationError otherwise.
  *
  * Both sides are resolved through `realpathOrAncestor` so symlinks are
  * followed before the containment check. Without that, a project rooted
@@ -120,6 +122,15 @@ function realpathOrAncestor(absPath: string): string {
  * symlink to `/private/tmp`) would reject paths the user typed in their
  * unresolved form. Symlink-based escapes (a symlink inside the project
  * pointing outside) are now also caught.
+ *
+ * The forbidden-segment check belongs on the resolved path rather than on
+ * `target_path_pattern` alone: the default locale-substitution branch of
+ * `resolveTargetPath` has no pattern to inspect, and the multi-locale branch
+ * writes back to the source path without calling it at all. Every read and
+ * write in the pipeline passes through here, so this is the one place that
+ * cannot be bypassed by a caller that forgets. Segments are compared relative
+ * to the root, so a checkout that happens to live under a `.github`
+ * directory is unaffected.
  */
 export function assertPathWithinRoot(
   absPath: string,
@@ -135,4 +146,15 @@ export function assertPathWithinRoot(
       `Target path escapes project root: ${sanitizeForTerminal(absPath)}`
     );
   }
+
+  const forbidden = path
+    .relative(resolvedRoot, resolvedPath)
+    .split(/[/\\]/)
+    .find((segment) => FORBIDDEN_TARGET_SEGMENTS.has(segment.toLowerCase()));
+  if (forbidden) {
+    throw new ValidationError(
+      `Sync path resolves into "${forbidden}/", which sync must never read or write: ${sanitizeForTerminal(absPath)}`,
+      `Point buckets at a locale directory outside ${forbidden}/ in .deepl-sync.yaml.`
+    );
+  }
 }
diff --git a/tests/e2e/cli-sync-vcs-containment.e2e.test.ts b/tests/e2e/cli-sync-vcs-containment.e2e.test.ts
new file mode 100644
index 00000000..cd87cf88
--- /dev/null
+++ b/tests/e2e/cli-sync-vcs-containment.e2e.test.ts
@@ -0,0 +1,149 @@
+/**
+ * E2E regression for the `.github` / `.git` containment gap. A bucket that
+ * omitted `target_path_pattern` reached the default locale-substitution path
+ * with no forbidden-segment check, so
+ *
+ *   buckets.yaml.include: ['.github/workflows/en.yml']
+ *
+ * made `deepl sync` write `.github/workflows/de.yml` from whatever the
+ * translation endpoint returned — CI workflow code under the attacker's
+ * influence, at exit 0. The guard now sits on the resolved path, so the run
+ * refuses at the source-file walk, before any translation request.
+ */
+
+import { spawnSync, SpawnSyncReturns } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const VALIDATION_EXIT_CODE = 6;
+
+describe('CLI sync VCS directory containment', () => {
+  const testConfig = createTestConfigDir('e2e-sync-vcs');
+  const testFiles = createTestDir('e2e-sync-vcs-files');
+
+  interface Run {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+  }
+
+  function runCli(args: string[]): Run {
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        cwd: testFiles.path,
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: testConfig.path,
+          NO_COLOR: '1',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 30000,
+      }
+    );
+    return {
+      status: result.status,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  const workflowsDir = () => path.join(testFiles.path, '.github', 'workflows');
+
+  beforeAll(() => {
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify(
+        {
+          auth: { apiKey: 'mock-api-key-for-testing:fx' },
+          api: { baseUrl: 'http://127.0.0.1:1/', usePro: false },
+          defaults: {
+            targetLangs: [],
+            formality: 'default',
+            preserveFormatting: true,
+          },
+          cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+          output: { format: 'text', verbose: false, color: false },
+          watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+        },
+        null,
+        2
+      )
+    );
+  });
+
+  beforeEach(() => {
+    fs.mkdirSync(workflowsDir(), { recursive: true });
+    fs.writeFileSync(
+      path.join(workflowsDir(), 'en.yml'),
+      'name: ci\non: push\njobs:\n  build:\n    steps:\n      - run: echo hi\n'
+    );
+    fs.writeFileSync(
+      path.join(testFiles.path, '.deepl-sync.yaml'),
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - de',
+        'buckets:',
+        '  yaml:',
+        '    include:',
+        '      - ".github/workflows/en.yml"',
+        '',
+      ].join('\n')
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(path.join(testFiles.path, '.github'), {
+      recursive: true,
+      force: true,
+    });
+    fs.rmSync(path.join(testFiles.path, '.deepl-sync.yaml'), { force: true });
+  });
+
+  it.each([['sync'], ['sync status'], ['sync validate']])(
+    'should refuse `deepl %s` for a bucket rooted in .github',
+    (command) => {
+      const result = runCli(command.split(' '));
+
+      expect(result.status).toBe(VALIDATION_EXIT_CODE);
+      expect(result.stderr).toMatch(/\.github/);
+      expect(fs.existsSync(path.join(workflowsDir(), 'de.yml'))).toBe(false);
+    }
+  );
+
+  it('should leave the source workflow byte-identical', () => {
+    const before = fs.readFileSync(path.join(workflowsDir(), 'en.yml'));
+    runCli(['sync']);
+    const after = fs.readFileSync(path.join(workflowsDir(), 'en.yml'));
+
+    expect(after.equals(before)).toBe(true);
+  });
+
+  it('should still refuse when a target_path_pattern points out of .github', () => {
+    fs.writeFileSync(
+      path.join(testFiles.path, '.deepl-sync.yaml'),
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - de',
+        'buckets:',
+        '  yaml:',
+        '    include:',
+        '      - ".github/workflows/en.yml"',
+        '    target_path_pattern: "locales/{locale}.yml"',
+        '',
+      ].join('\n')
+    );
+    const result = runCli(['sync']);
+
+    expect(result.status).toBe(VALIDATION_EXIT_CODE);
+    expect(result.stderr).toMatch(/\.github/);
+  });
+});
diff --git a/tests/unit/sync/sync-forbidden-target-segments.test.ts b/tests/unit/sync/sync-forbidden-target-segments.test.ts
new file mode 100644
index 00000000..016d1d7c
--- /dev/null
+++ b/tests/unit/sync/sync-forbidden-target-segments.test.ts
@@ -0,0 +1,88 @@
+/**
+ * `FORBIDDEN_TARGET_SEGMENTS` exists so a translated-locale name can never
+ * become VCS metadata or CI workflow code. It had exactly one enforcement
+ * site — inside the `if (target_path_pattern !== undefined)` branch of config
+ * validation — so a bucket that simply omitted `target_path_pattern` reached
+ * the default locale-substitution path with no check at all:
+ *
+ *   buckets.yaml.include: ['.github/workflows/en.yml']
+ *   -> sync writes .github/workflows/de.yml from API-returned bytes
+ *
+ * `assertPathWithinRoot` accepted it, because the path never leaves the
+ * project root. The guard now lives on the resolved path at that shared
+ * boundary, so every read and write in the sync pipeline inherits it —
+ * including the multi-locale branch, which writes back to the source path and
+ * never calls `resolveTargetPath` at all.
+ */
+
+import * as path from 'path';
+import { assertPathWithinRoot } from '../../../src/sync/sync-utils';
+import { validateSyncConfig } from '../../../src/sync/sync-config';
+import { ValidationError } from '../../../src/utils/errors';
+
+const ROOT = path.resolve('/project');
+
+describe('forbidden target segments on resolved paths', () => {
+  it.each([
+    ['a CI workflow file', '.github/workflows/de.yml'],
+    ['the CI directory itself', '.github'],
+    ['a file directly in the CI directory', '.github/de.yml'],
+    ['git metadata', '.git/config'],
+    ['the git directory itself', '.git'],
+    ['a nested CI directory', 'packages/app/.github/workflows/de.yml'],
+    ['a nested git directory', 'vendor/dep/.git/hooks/pre-commit'],
+  ])('should reject %s', (_label, relPath) => {
+    expect(() => assertPathWithinRoot(path.join(ROOT, relPath), ROOT)).toThrow(
+      ValidationError
+    );
+  });
+
+  it('should reject case variants, since the filesystem may not care', () => {
+    expect(() =>
+      assertPathWithinRoot(path.join(ROOT, '.GitHub/workflows/de.yml'), ROOT)
+    ).toThrow(ValidationError);
+  });
+
+  it('should name the offending directory rather than claim a root escape', () => {
+    expect(() =>
+      assertPathWithinRoot(path.join(ROOT, '.github/workflows/de.yml'), ROOT)
+    ).toThrow(/\.github/);
+    expect(() =>
+      assertPathWithinRoot(path.join(ROOT, '.github/workflows/de.yml'), ROOT)
+    ).not.toThrow(/escapes project root/);
+  });
+
+  it.each([
+    ['a normal locale file', 'locales/de.json'],
+    ['a dotfile directory that is not VCS metadata', '.config/locales/de.json'],
+    ['a path whose segment merely starts with .git', '.gitlab/de.yml'],
+    ['a file named .gitignore', '.gitignore'],
+    ['a segment containing github as a substring', 'src/github-api/de.json'],
+  ])('should still accept %s', (_label, relPath) => {
+    expect(() =>
+      assertPathWithinRoot(path.join(ROOT, relPath), ROOT)
+    ).not.toThrow();
+  });
+
+  it('should keep reporting a root escape as a root escape', () => {
+    expect(() =>
+      assertPathWithinRoot(path.join(ROOT, '..', 'etc', 'passwd'), ROOT)
+    ).toThrow(/escapes project root/);
+  });
+
+  it('should still reject a forbidden segment in target_path_pattern at config load', () => {
+    expect(() =>
+      validateSyncConfig({
+        version: 1,
+        source_locale: 'en',
+        target_locales: ['de'],
+        buckets: {
+          yaml: {
+            include: ['locales/en.yml'],
+            target_path_pattern: '.github/workflows/{locale}.yml',
+          },
+        },
+      })
+    ).toThrow(/\.github/);
+  });
+});

From 85339610f4ff7ec30f3f33e64fede5d5b35e12d0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 16:46:08 +0200
Subject: [PATCH 117/256] fix(sync): stop the stale-backup sweep from writing,
 and scope it honestly
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The startup sweep restored ANY zero-length file from a `<file>.deepl.bak`
sibling, with no check that the sibling was a translation target, was
matched by a bucket glob, was tracked, or that the backup came from this
tool. A hostile checkout shipping an empty tracked file plus a
`.deepl.bak` alongside it — any clone older than five minutes qualifies,
since checkout stamps mtimes at clone time — got bytes of its choosing
written into that file during sync startup, before any translation, at
exit 0, with one Logger.warn as the only trace and the .bak unlinked
straight after.

Every target write goes through atomicWriteFile, which renames a
fully-written temp file into place, so a crash cannot leave a zero-length
target. Confirmed by reading the write paths: the only non-atomic writes
under src/sync are lockfile writes. The restore branch therefore had no
legitimate trigger and is removed; the sweep only unlinks now.

Separately, bucketSweepRoots took the literal prefix before the first
wildcard, so a glob starting with one yielded path.dirname('') === '.' —
the whole project root, walked recursively, defeating the scoping the
function exists to provide. Such a glob now contributes no root. The cost
is that a bucket globbing '**/en.json' gets no stale-backup cleanup, so
inert .deepl.bak files may accumulate; logged under --verbose rather than
skipped silently.

Refs: cli-8kr2.2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                             |  4 +-
 docs/SYNC.md                             |  2 +-
 src/sync/sync-bak-cleanup.ts             | 41 +++++++------
 tests/unit/sync/sync-bak-cleanup.test.ts | 76 ++++++++++++++++++++++--
 4 files changed, 96 insertions(+), 27 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cbd972d0..a9f7efe7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -85,7 +85,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **batch**: Plain-text batch translation now reads, translates, and writes one API batch at a time instead of loading every file into memory up front, so memory stays proportional to a single batch rather than the whole tree. Batch grouping also measures the form-encoded body size (what the API's 128 KiB limit actually applies to) instead of raw UTF-8 bytes, so CJK-heavy batches whose percent-encoding inflates ~3x are split correctly instead of being rejected server-side.
 
-- **sync**: Backups are written as `<file>.deepl.bak` instead of `<file>.bak`, and the stale-backup sweep considers only the `.deepl.bak` suffix — a user's own `*.bak` files are never touched again. The sweep also no longer re-creates a target file that was deleted; it restores a backup only over a sibling that exists but is empty. **Migration**: `.bak` files from earlier versions are no longer swept or restored — delete leftover `<target>.bak` files manually if desired.
+- **sync**: Backups are written as `<file>.deepl.bak` instead of `<file>.bak`, and the stale-backup sweep considers only the `.deepl.bak` suffix — a user's own `*.bak` files are never touched again. The sweep also no longer re-creates a target file that was deleted, nor restores one over an existing file: it only ever deletes (see the Security entry below). **Migration**: `.bak` files from earlier versions are no longer swept or restored — delete leftover `<target>.bak` files manually if desired.
 
 - **cli**: The primary human-readable reports of `sync status`, `sync validate`, `sync audit`, `sync init`, and `auth show` print to stdout, so `deepl sync status > report.txt` and `deepl auth show > key.txt` capture output instead of producing empty files. Diagnostics, warnings, and progress stay on stderr, and `--format json` stdout purity is unchanged.
 
@@ -357,6 +357,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
 
+- **sync**: the startup stale-backup sweep no longer writes anything, and no longer takes the whole project as its scope. It restored any **zero-length** file from a `<file>.deepl.bak` sibling, with no check that the sibling was a translation target, was matched by a bucket glob, was tracked, or that the backup came from this tool. A hostile checkout shipping an empty tracked file plus a `.deepl.bak` alongside it — any clone older than five minutes qualifies, since checkout stamps mtimes at clone time — therefore got bytes of its choosing written into that file during sync **startup**, before any translation, at exit 0, with a single `Logger.warn` as the only trace and the `.bak` unlinked immediately after. Because every target write goes through `atomicWriteFile`, which renames a fully-written temp file into place, a crash cannot leave a zero-length target: the restore branch had no legitimate trigger left and is removed, so the sweep only ever unlinks. Separately, a bucket glob beginning with a wildcard (`**/en.json`, `*.json`) has no literal prefix, and the old `path.dirname('')` fallback handed the sweep the entire project root to walk recursively — defeating the scoping the function exists to provide. Such a glob now contributes no sweep root, which means a bucket configured that way gets no stale-backup cleanup and may accumulate inert `.deepl.bak` files; run with `--verbose` to see when this is skipped.
+
 - **sync**: no sync path may resolve into `.git/` or `.github/` any more, closing a gap where the guard that exists to prevent exactly that was enforced on one branch only. `FORBIDDEN_TARGET_SEGMENTS` was checked against a literal `target_path_pattern`, so a bucket that simply omitted the pattern reached the default locale-substitution path unguarded: `buckets.yaml.include: ['.github/workflows/en.yml']` made `deepl sync` write `.github/workflows/de.yml` whose `run:` body was whatever the translation endpoint returned — CI workflow code under the influence of a hostile checkout or a hostile endpoint, at exit 0. The containment check on the project root accepted it, because the path never leaves the root. The check now sits on the resolved path inside `assertPathWithinRoot`, the one boundary every read and write in the pipeline passes through, so both the substitution branch and the multi-locale branch — which writes back to the source path and never calls `resolveTargetPath` at all — inherit it, and a future call site cannot forget it. A bucket rooted in `.github/` now fails at the source-file walk with exit 6 and a message naming the directory, before any translation request is made; the pattern-level check is kept as well, so a bad `target_path_pattern` is still reported at config load. Segments are compared relative to the project root, so a checkout living under a `.github` directory is unaffected, and `.gitlab/`, `.gitignore`, and paths merely containing `github` as a substring are untouched.
 
 - **sync**: glob patterns from `.deepl-sync.yaml` are bounded before they reach fast-glob, so a hostile checkout can no longer end the process with an uncatchable out-of-memory abort. fast-glob expands brace groups through `braces`, a different package from `brace-expansion` despite the name, and `braces` caps only its input length — the expansion it produces is a product with no bound at all. A 1007-byte `include` pattern of 200 `{a,b}` groups therefore killed `deepl sync` and `deepl sync validate` with `FATAL ERROR: Ineffective mark-compacts near heap limit` (SIGABRT, exit 134). An abort is not a JavaScript exception, so the per-bucket error handling could not contain it, and the tool's own generated pre-commit hook and documented CI step were killed the same way. Brace expansion is a product rather than a sum, so this needs very little input: 20 groups is 107 characters and already wedges the run. Every pattern-bearing field is now checked at config load — `buckets.*.include`, `buckets.*.exclude`, top-level `ignore`, and `context.scan_paths` — rejecting anything that expands past 1000 paths or exceeds 4096 characters with a `ConfigError` (exit 7) naming the field. The bound is a conservative over-approximation computed without expanding anything, it counts numeric and alpha ranges (`{1..9}`, `{a..e}`) by cardinality, and it folds unbalanced groups in as if closed so an unclosed `{` cannot smuggle a bomb past it. Neither cap is configurable, since the attacker in this scenario supplies the config; both sit below the point where `braces` itself throws, so its `RangeError` and `SyntaxError` paths are unreachable too. Realistic patterns are nowhere near the cap — `{en,de,fr}/**/*.{json,yaml,yml}` expands to 9.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index b91ed83a..2c9e849e 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -706,7 +706,7 @@ deepl sync --watch --dry-run
 
 **Event coalescing.** Only one sync runs at a time. If more file-change events arrive while a sync is in flight, they are coalesced into a **single** follow-up run that starts after the current sync completes — no matter how many bursts of edits fired in between. Earlier releases silently dropped these in-flight events, which could leave the final edit of a burst unsynced until the user triggered another change manually.
 
-**Stale `.deepl.bak` sweep.** On startup, the watcher sweeps for `.deepl.bak` siblings older than 5 minutes (files with any other suffix, including plain `.bak`, are never touched). A stale backup whose target file exists but is empty is auto-restored from the backup before the backup is removed; in every other case — including a missing target, which is never recreated — the stale backup is removed outright. This recovers cleanly from a previous watcher that was killed mid-translation without leaving residue for the user to manually clean up.
+**Stale `.deepl.bak` sweep.** On startup, the watcher sweeps for `.deepl.bak` siblings older than 5 minutes (files with any other suffix, including plain `.bak`, are never touched). The sweep only ever deletes: a stale backup is removed outright, and no target file is ever created or overwritten from one. Target writes go through an atomic write-then-rename, so a watcher killed mid-translation cannot leave a truncated or zero-length target that would need restoring. The sweep is scoped to the directories implied by each bucket's `include` globs; a glob that begins with a wildcard (`**/en.json`, `*.json`) has no literal directory prefix to scope to and is skipped, so a bucket configured that way may accumulate `.deepl.bak` files. Run with `--verbose` to see when a glob is skipped for this reason.
 
 **Scope.** Watched paths are the `buckets.*.include` globs from `.deepl-sync.yaml`, plus `.deepl-sync.yaml` itself. When `.deepl-sync.yaml` changes, the config is reloaded from disk before the next sync cycle runs — YAML values like bucket definitions, `formality`, `glossary`, and `model_type` are picked up without restarting the watcher. Sending `SIGHUP` (`kill -HUP <pid>`) also force-reloads the config immediately, without waiting for a file-change event. Watch mode does not cross-talk with the separate `deepl watch` command (which is for translating individual plain-text files).
 
diff --git a/src/sync/sync-bak-cleanup.ts b/src/sync/sync-bak-cleanup.ts
index d48b98fa..cee80955 100644
--- a/src/sync/sync-bak-cleanup.ts
+++ b/src/sync/sync-bak-cleanup.ts
@@ -23,7 +23,12 @@ let _warnedNoScope = false;
  * Derive the set of concrete directory roots to sweep from bucket `include`
  * globs. Returns unique absolute paths that are the longest literal prefixes
  * of each glob (i.e. everything before the first `*`, `?`, `{`, or `[`).
- * Falls back to `projectRoot` for globs with no literal prefix.
+ *
+ * A glob that starts with a wildcard has no literal prefix and contributes no
+ * root. Falling back to `projectRoot` there defeated the scoping this function
+ * exists to provide: `**\/en.json` handed the sweep the entire project tree,
+ * walked recursively. The cost is that such a bucket gets no stale-backup
+ * cleanup, which leaves inert `.deepl.bak` files on disk.
  */
 export function bucketSweepRoots(
   projectRoot: string,
@@ -35,6 +40,12 @@ export function bucketSweepRoots(
     for (const glob of bucket.include) {
       const specialIdx = glob.search(/[*?{[]/);
       const literal = specialIdx === -1 ? glob : glob.slice(0, specialIdx);
+      if (literal === '') {
+        Logger.verbose(
+          `Skipping stale-backup sweep for "${glob}": the pattern has no literal directory prefix to scope the sweep to.`
+        );
+        continue;
+      }
       const dir = literal.endsWith('/')
         ? literal.slice(0, -1)
         : path.dirname(literal);
@@ -59,10 +70,14 @@ export function bucketSweepRoots(
 
 /**
  * Walk `projectRoot` breadth-first and remove `.deepl.bak` files whose mtime
- * is older than `maxAgeMs`. When the sibling (the backup's target) exists but
- * is zero-length, restore it from the backup before unlinking. A missing
- * sibling is never recreated, and files with any other suffix (including
- * plain `.bak`) are left untouched.
+ * is older than `maxAgeMs`. Nothing is ever written: the sweep only unlinks,
+ * and files with any other suffix (including plain `.bak`) are left untouched.
+ *
+ * It used to restore a zero-length sibling from its backup first. Because
+ * every target write goes through `atomicWriteFile`, which renames a
+ * fully-written temp file into place, a crash cannot leave a zero-length
+ * target — so that branch had no legitimate trigger, and a hostile checkout
+ * could use it to write chosen bytes into any empty file within a sweep root.
  *
  * When `buckets` is provided the sweep is scoped to the directories implied by
  * each bucket's `include` globs instead of the entire project tree, keeping
@@ -126,22 +141,6 @@ async function sweepDir(
     try {
       const stat = await fs.promises.stat(full);
       if (stat.mtimeMs >= threshold) continue;
-      const sibling = full.slice(0, -BACKUP_SUFFIX.length);
-      let siblingEmpty = false;
-      try {
-        const sStat = await fs.promises.stat(sibling);
-        siblingEmpty = sStat.size === 0;
-      } catch {
-        siblingEmpty = false;
-      }
-      if (siblingEmpty) {
-        try {
-          await fs.promises.copyFile(full, sibling);
-          Logger.warn(`Restored ${sibling} from stale backup ${full}.`);
-        } catch {
-          /* fall through to unlink */
-        }
-      }
       try {
         await fs.promises.unlink(full);
       } catch {
diff --git a/tests/unit/sync/sync-bak-cleanup.test.ts b/tests/unit/sync/sync-bak-cleanup.test.ts
index 6a333fd6..294e508c 100644
--- a/tests/unit/sync/sync-bak-cleanup.test.ts
+++ b/tests/unit/sync/sync-bak-cleanup.test.ts
@@ -21,8 +21,29 @@ describe('bucketSweepRoots()', () => {
     expect(result).toEqual([path.resolve(root, 'locales')]);
   });
 
-  it('handles a glob with no directory prefix (project root)', () => {
-    const result = bucketSweepRoots(root, { json: { include: ['*.json'] } });
+  // A glob whose first character is a wildcard has no literal prefix at all,
+  // so the old `path.dirname('')` fallback yielded '.' — the entire project
+  // root, walked recursively. Scoping the sweep is the whole point of deriving
+  // roots from includes, so such a glob contributes no root rather than the
+  // widest possible one.
+  it.each([
+    ['a bare wildcard', '*.json'],
+    ['a globstar', '**/en.json'],
+    ['a leading brace group', '{en,de}/*.json'],
+    ['a leading character class', '[a-z]*/messages.json'],
+  ])('contributes no sweep root for %s', (_label, glob) => {
+    expect(bucketSweepRoots(root, { json: { include: [glob] } })).toEqual([]);
+  });
+
+  it('keeps the literal roots of sibling globs when one has no prefix', () => {
+    const result = bucketSweepRoots(root, {
+      json: { include: ['**/en.json', 'locales/**/*.json'] },
+    });
+    expect(result).toEqual([path.resolve(root, 'locales')]);
+  });
+
+  it('still returns the project root for a literal file at the root', () => {
+    const result = bucketSweepRoots(root, { json: { include: ['en.json'] } });
     expect(result).toEqual([root]);
   });
 
@@ -180,7 +201,13 @@ describe('sweepStaleBackups() with bucket config', () => {
     expect(fs.existsSync(bakFile)).toBe(false);
   });
 
-  it('restores a zero-length sibling from .deepl.bak before unlinking', async () => {
+  // The sweep used to overwrite any zero-length file from its `.deepl.bak`
+  // sibling, with no check that the sibling was a translation target or that
+  // the backup came from this tool. `atomicWriteFile` renames a fully-written
+  // temp file into place and so can never leave a zero-length target, which
+  // left the restore branch with no legitimate trigger and made it a way for a
+  // hostile checkout to write chosen bytes into an empty tracked file.
+  it('leaves a zero-length sibling alone while removing the stale .deepl.bak', async () => {
     const localesDir = path.join(tmpDir, 'locales');
     fs.mkdirSync(localesDir, { recursive: true });
 
@@ -195,10 +222,51 @@ describe('sweepStaleBackups() with bucket config', () => {
       json: { include: ['locales/**/*.json'] },
     });
 
-    expect(fs.readFileSync(sibling, 'utf-8')).toBe('{"key":"value"}');
+    expect(fs.readFileSync(sibling, 'utf-8')).toBe('');
     expect(fs.existsSync(bakFile)).toBe(false);
   });
 
+  it('does not write attacker bytes into an unrelated empty source file', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    fs.mkdirSync(pkgDir, { recursive: true });
+
+    const victim = path.join(pkgDir, '__init__.py');
+    const bakFile = `${victim}.deepl.bak`;
+    fs.writeFileSync(victim, '', 'utf-8');
+    fs.writeFileSync(bakFile, 'import os; os.system("id")\n', 'utf-8');
+    const tenMinAgo = new Date(Date.now() - 10 * 60_000);
+    fs.utimesSync(bakFile, tenMinAgo, tenMinAgo);
+
+    await sweepStaleBackups(tmpDir, 5 * 60_000, {
+      json: { include: ['pkg/**/*.json'] },
+    });
+
+    expect(fs.readFileSync(victim, 'utf-8')).toBe('');
+  });
+
+  it('does not sweep the whole project for a glob with no literal prefix', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    fs.mkdirSync(pkgDir, { recursive: true });
+
+    const victim = path.join(pkgDir, '__init__.py');
+    const bakFile = `${victim}.deepl.bak`;
+    fs.writeFileSync(victim, '', 'utf-8');
+    fs.writeFileSync(bakFile, 'attacker content\n', 'utf-8');
+    const tenMinAgo = new Date(Date.now() - 10 * 60_000);
+    fs.utimesSync(bakFile, tenMinAgo, tenMinAgo);
+
+    await sweepStaleBackups(tmpDir, 5 * 60_000, {
+      json: { include: ['**/en.json'] },
+    });
+
+    expect(fs.readFileSync(victim, 'utf-8')).toBe('');
+    expect(fs.existsSync(bakFile)).toBe(true);
+    const readdirCalls: string[] = readdirSpy.mock.calls.map(
+      (c: unknown[]) => c[0] as string
+    );
+    expect(readdirCalls).toHaveLength(0);
+  });
+
   it('leaves a non-empty sibling untouched while removing the stale .deepl.bak', async () => {
     const localesDir = path.join(tmpDir, 'locales');
     fs.mkdirSync(localesDir, { recursive: true });

From 1585a43fe303480b08e36dc4711fe45f9f633028 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 16:55:03 +0200
Subject: [PATCH 118/256] fix(cache): key translations and write results on the
 resolved API endpoint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One cache.db is shared by every endpoint a config directory has ever
talked to, and the translation key hashed 20 request parameters but not
who was going to answer them. So

  deepl translate "hello world" --to DE --api-url http://127.0.0.1:18111

served that endpoint's answer back for api.deepl.com for the full 30-day
TTL, with no network reachable at all. Custom endpoints are a supported
feature — proxies, regional endpoints — so this needed nothing the tool
discourages. WriteService.generateCacheKey had the same gap.

Append `endpoint` to both cacheData objects, derived from
resolveClientBaseUrl — extracted from HttpClient's own constructor so the
key and the transport read the same expression instead of two copies that
can drift. Appending keeps the existing field order stable, as the
generateCacheKey doc comment requires.

CACHE_SCHEMA_VERSION moves to 3, dropping `translation:`, `write:`, and
`correct:` rows on open: every one of those keys changed, and retiring
them also clears any entry a custom endpoint already poisoned. Other
namespaces are untouched.

Cache writes stay enabled for non-standard endpoints. With the endpoint in
the key there is nothing left to cross-contaminate, and disabling them
would cost proxy users their cache for no gain.

Verified end to end against two stub endpoints returning different text
for the same request: two distinct rows, neither answering for the other
nor for the real API.

Refs: cli-8kr2.9

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +
 README.md                                     |   2 +
 src/api/deepl-client.ts                       |  15 ++-
 src/api/http-client.ts                        |  15 ++-
 src/services/translation.ts                   |   8 ++
 src/services/write.ts                         |   6 +
 src/storage/cache.ts                          |  29 ++---
 .../cache-key-normalization.property.test.ts  |  10 +-
 tests/unit/cache-backcompat.test.ts           |  25 +++--
 tests/unit/cache-service.test.ts              |  22 ++--
 .../unit/services/cache-key-endpoint.test.ts  | 106 ++++++++++++++++++
 11 files changed, 204 insertions(+), 36 deletions(-)
 create mode 100644 tests/unit/services/cache-key-endpoint.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a9f7efe7..3ec05198 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -357,6 +357,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
 
+- **cache**: the resolved API base URL is now part of every translation, `write`, and `correct` cache key. One `cache.db` is shared by every endpoint a config directory has ever talked to, and the key hashed 20 request parameters but not who was going to answer them — so a single `deepl translate "hello" --to DE --api-url http://127.0.0.1:18111` served that endpoint's answer back for `api.deepl.com` for the full 30-day TTL, with no network reachable at all. Custom endpoints are a supported feature (proxies, regional endpoints), so this needed nothing the tool discourages: pointing the CLI at a local stub once was enough to make its output the cached truth everywhere. Verified end to end against two stub endpoints returning different text for the same request: each now gets its own row, and neither can answer for the other or for the real API. The endpoint is derived from the same expression the HTTP transport uses (`resolveClientBaseUrl`) rather than a second copy that could drift, and the free and Pro endpoints are keyed apart too. `CACHE_SCHEMA_VERSION` moves to 3, so opening an existing DB drops its `translation:`, `write:`, and `correct:` rows — every one of those keys changed, and retiring them is also what clears any entry a custom endpoint already poisoned. Other namespaces are untouched. Cache **writes** are deliberately still allowed for non-standard endpoints: with the endpoint in the key there is nothing left to cross-contaminate, and disabling them would cost proxy and regional-endpoint users their cache for no gain.
+
 - **sync**: the startup stale-backup sweep no longer writes anything, and no longer takes the whole project as its scope. It restored any **zero-length** file from a `<file>.deepl.bak` sibling, with no check that the sibling was a translation target, was matched by a bucket glob, was tracked, or that the backup came from this tool. A hostile checkout shipping an empty tracked file plus a `.deepl.bak` alongside it — any clone older than five minutes qualifies, since checkout stamps mtimes at clone time — therefore got bytes of its choosing written into that file during sync **startup**, before any translation, at exit 0, with a single `Logger.warn` as the only trace and the `.bak` unlinked immediately after. Because every target write goes through `atomicWriteFile`, which renames a fully-written temp file into place, a crash cannot leave a zero-length target: the restore branch had no legitimate trigger left and is removed, so the sweep only ever unlinks. Separately, a bucket glob beginning with a wildcard (`**/en.json`, `*.json`) has no literal prefix, and the old `path.dirname('')` fallback handed the sweep the entire project root to walk recursively — defeating the scoping the function exists to provide. Such a glob now contributes no sweep root, which means a bucket configured that way gets no stale-backup cleanup and may accumulate inert `.deepl.bak` files; run with `--verbose` to see when this is skipped.
 
 - **sync**: no sync path may resolve into `.git/` or `.github/` any more, closing a gap where the guard that exists to prevent exactly that was enforced on one branch only. `FORBIDDEN_TARGET_SEGMENTS` was checked against a literal `target_path_pattern`, so a bucket that simply omitted the pattern reached the default locale-substitution path unguarded: `buckets.yaml.include: ['.github/workflows/en.yml']` made `deepl sync` write `.github/workflows/de.yml` whose `run:` body was whatever the translation endpoint returned — CI workflow code under the influence of a hostile checkout or a hostile endpoint, at exit 0. The containment check on the project root accepted it, because the path never leaves the root. The check now sits on the resolved path inside `assertPathWithinRoot`, the one boundary every read and write in the pipeline passes through, so both the substitution branch and the multi-locale branch — which writes back to the source path and never calls `resolveTargetPath` at all — inherit it, and a future call site cannot forget it. A bucket rooted in `.github/` now fails at the source-file walk with exit 6 and a message naming the directory, before any translation request is made; the pattern-level check is kept as well, so a bad `target_path_pattern` is still reported at config load. Segments are compared relative to the project root, so a checkout living under a `.github` directory is unaffected, and `.gitlab/`, `.gitignore`, and paths merely containing `github` as a substring are untouched.
diff --git a/README.md b/README.md
index 16c58d0f..ce3e0887 100644
--- a/README.md
+++ b/README.md
@@ -1496,6 +1496,8 @@ deepl cache disable
 
 Cache location: `~/.cache/deepl-cli/cache.db` (or `~/.deepl-cli/cache.db` for legacy installations)
 
+One database is shared by every endpoint a config directory has ever talked to, so the resolved API base URL is part of every translation, `write`, and `correct` cache key. A run against `--api-url http://localhost:1234` gets its own entries and can never answer a later request aimed at `api.deepl.com`; the free and Pro endpoints are likewise keyed apart.
+
 ## 💻 Development
 
 ### Prerequisites
diff --git a/src/api/deepl-client.ts b/src/api/deepl-client.ts
index 3496317e..c1d640da 100644
--- a/src/api/deepl-client.ts
+++ b/src/api/deepl-client.ts
@@ -1,4 +1,8 @@
-import { HttpClient, DeepLClientOptions } from './http-client.js';
+import {
+  HttpClient,
+  DeepLClientOptions,
+  resolveClientBaseUrl,
+} from './http-client.js';
 import {
   TranslationClient,
   TranslationResult,
@@ -67,6 +71,15 @@ export class DeepLClient {
     this.options = options;
   }
 
+  /**
+   * The base URL requests from this client will actually go to. Cache keys
+   * must include it: the same request against a different endpoint is a
+   * different request, and every endpoint shares one cache DB.
+   */
+  get resolvedBaseUrl(): string {
+    return resolveClientBaseUrl(this.options);
+  }
+
   private get translationClient(): TranslationClient {
     this._translationClient ??= new TranslationClient(
       this.apiKey,
diff --git a/src/api/http-client.ts b/src/api/http-client.ts
index c4712128..d35ea0c1 100644
--- a/src/api/http-client.ts
+++ b/src/api/http-client.ts
@@ -45,6 +45,18 @@ export interface DeepLClientOptions {
 
 export { sanitizeUrl };
 
+/**
+ * The base URL a client built from these options will actually send to.
+ *
+ * Exported so that anything which must reflect the endpoint — notably the
+ * translation and write cache keys, since two endpoints return different text
+ * for the same request — derives it from the same expression the transport
+ * uses, rather than a copy that can drift out of step with it.
+ */
+export function resolveClientBaseUrl(options: DeepLClientOptions): string {
+  return options.baseUrl ?? (options.usePro ? PRO_API_URL : FREE_API_URL);
+}
+
 const DEFAULT_TIMEOUT = 30000;
 const DEFAULT_MAX_RETRIES = 3;
 const MAX_SOCKETS = 10;
@@ -218,8 +230,7 @@ export class HttpClient {
       throw new AuthError('API key is required');
     }
 
-    const baseURL =
-      options.baseUrl ?? (options.usePro ? PRO_API_URL : FREE_API_URL);
+    const baseURL = resolveClientBaseUrl(options);
 
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.requestTimeout = options.timeout ?? DEFAULT_TIMEOUT;
diff --git a/src/services/translation.ts b/src/services/translation.ts
index 5fc06141..7418406a 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -455,6 +455,13 @@ export class TranslationService {
    * different requests. `preserveFormatting` counts because preserve_formatting
    * suppresses the sentence-boundary punctuation and case correction, which
    * shows up in the text.
+   *
+   * `endpoint` is not a request parameter but decides who answers the request,
+   * and one cache DB is shared by every endpoint a config dir has ever talked
+   * to. Without it, a single run against `--api-url http://localhost:1234`
+   * served its answers back for api.deepl.com for the full 30-day TTL, with no
+   * network involved. Custom endpoints are a supported feature — proxies,
+   * regional endpoints — so this needs no misuse to reach.
    */
   private generateCacheKey(text: string, options: TranslationOptions): string {
     // Keyed on the parameter the request will actually carry, so the two ways of
@@ -490,6 +497,7 @@ export class TranslationService {
       nonSplittingTags: options.nonSplittingTags, // 18. Tags that do not
       outlineDetection: options.outlineDetection, // 19. XML structure inference
       preserveFormatting: options.preserveFormatting, // 20. Suppresses boundary correction
+      endpoint: this.client.resolvedBaseUrl, // 21. Who answered the request
     };
 
     // Generate SHA-256 hash of the stable representation
diff --git a/src/services/write.ts b/src/services/write.ts
index f3eda215..8c067acf 100644
--- a/src/services/write.ts
+++ b/src/services/write.ts
@@ -166,6 +166,11 @@ export class WriteService {
    * The prefix separates rephrase and correct results: the two endpoints
    * return different text for the same input, so their entries must never
    * satisfy each other's lookups.
+   *
+   * `endpoint` is not a request parameter but decides who answers the request,
+   * and one cache DB is shared by every endpoint a config dir has ever talked
+   * to. Without it, a run against a custom `--api-url` served its answers back
+   * for api.deepl.com for the full TTL.
    */
   private generateCacheKey(
     text: string,
@@ -177,6 +182,7 @@ export class WriteService {
       targetLang: options.targetLang,
       writingStyle: (options as WriteOptions).writingStyle,
       tone: (options as WriteOptions).tone,
+      endpoint: this.client.resolvedBaseUrl,
     };
 
     const hash = crypto
diff --git a/src/storage/cache.ts b/src/storage/cache.ts
index 80f3e7ab..4af0fc97 100644
--- a/src/storage/cache.ts
+++ b/src/storage/cache.ts
@@ -70,12 +70,13 @@ function isCorruptionError(error: unknown): boolean {
  * `PRAGMA user_version` on fresh DBs and checked on every open. Bumping
  * this number means "future callers will read a DB laid out differently."
  *
- * Version 2 marks a change in how translation cache keys are computed. Opening
- * an older DB drops the `translation:` rows -- no reader can reach them again --
- * and leaves every other namespace in place. The table layout is identical in all
- * versions, so nothing is migrated.
+ * Version 2 marks a change in how translation cache keys are computed. Version 3
+ * adds the resolved API endpoint to the translation, write, and correct keys, so
+ * all three namespaces changed. Opening an older DB drops the rows whose keys can
+ * no longer be reached and leaves every other namespace in place. The table layout
+ * is identical in all versions, so nothing is migrated.
  */
-const CACHE_SCHEMA_VERSION = 2;
+const CACHE_SCHEMA_VERSION = 3;
 
 export class CacheService {
   private static instance: CacheService | null = null;
@@ -253,14 +254,16 @@ export class CacheService {
     `);
 
     if (userVersion < CACHE_SCHEMA_VERSION) {
-      // Only the translation namespace. Its keys all changed, so every row is
-      // unreachable and would otherwise occupy the size budget and `cache stats`
-      // until its TTL expires. `write`/`correct` keys changed only for the five
-      // target codes whose casing moved, and a hash cannot say which rows those
-      // are -- dropping the namespace would discard far more reachable entries
-      // than it reclaimed, so those few expire on their own. A fresh DB has no
-      // rows, so this is a no-op on first open.
-      this.db.exec("DELETE FROM cache WHERE key LIKE 'translation:%'");
+      // Every key in these three namespaces changed when the endpoint joined the
+      // hashed data, so every row is unreachable and would otherwise occupy the
+      // size budget and `cache stats` until its TTL expires. Dropping them is
+      // also the point: a row poisoned by a run against a custom endpoint must
+      // not survive the upgrade that stops it happening again. Other namespaces
+      // (glossary listings, language lists) are unaffected and stay. A fresh DB
+      // has no rows, so this is a no-op on first open.
+      this.db.exec(
+        "DELETE FROM cache WHERE key LIKE 'translation:%' OR key LIKE 'write:%' OR key LIKE 'correct:%'"
+      );
       this.db.exec(`PRAGMA user_version = ${CACHE_SCHEMA_VERSION}`);
     }
   }
diff --git a/tests/property/cache-key-normalization.property.test.ts b/tests/property/cache-key-normalization.property.test.ts
index e707f6dd..799059fc 100644
--- a/tests/property/cache-key-normalization.property.test.ts
+++ b/tests/property/cache-key-normalization.property.test.ts
@@ -5,8 +5,8 @@
  * normalization, so NFC and NFD encodings of the same visible string produce
  * two cache entries — and therefore two billable API calls.
  *
- * generateCacheKey reads nothing from `this`, so it is invoked via the
- * prototype without constructing the service.
+ * generateCacheKey reads only `this.client.resolvedBaseUrl`, so it is invoked
+ * via the prototype against a stub receiver rather than a constructed service.
  */
 import { TranslationService } from '../../src/services/translation';
 
@@ -16,6 +16,8 @@ const generateCacheKey = (
   TranslationService.prototype as unknown as { generateCacheKey: KeyFn }
 ).generateCacheKey;
 
+const receiver = { client: { resolvedBaseUrl: 'https://api.deepl.com' } };
+
 describe('translation cache key normalization', () => {
   it('documents that NFC and NFD of the same visible string produce distinct keys', () => {
     const nfc = 'café'.normalize('NFC');
@@ -23,8 +25,8 @@ describe('translation cache key normalization', () => {
     expect(nfc).not.toBe(nfd); // different code points
     expect(nfc.normalize('NFC')).toBe(nfd.normalize('NFC')); // same visible string
 
-    const keyNfc = generateCacheKey.call(null, nfc, { targetLang: 'de' });
-    const keyNfd = generateCacheKey.call(null, nfd, { targetLang: 'de' });
+    const keyNfc = generateCacheKey.call(receiver, nfc, { targetLang: 'de' });
+    const keyNfd = generateCacheKey.call(receiver, nfd, { targetLang: 'de' });
 
     // Current behavior: two entries for one visible string. Whether this is
     // a bug or intentional exact-input keying is a policy decision.
diff --git a/tests/unit/cache-backcompat.test.ts b/tests/unit/cache-backcompat.test.ts
index 1ea11088..815045d9 100644
--- a/tests/unit/cache-backcompat.test.ts
+++ b/tests/unit/cache-backcompat.test.ts
@@ -7,6 +7,14 @@
  * better-sqlite3 12.11.1 (SQLite 3.53.2) mirroring CacheService's real
  * on-disk layout: WAL journal mode, user_version = 1, cache table with
  * timestamp index, three rows stamped 2026-07-01T00:00:00Z.
+ *
+ * Opening it runs the schema upgrade to the current version, which retires the
+ * namespaces whose keys changed. Of the three fixture rows, the two
+ * `translate:v1:*` rows survive (that prefix predates the `translation:`
+ * namespace and is not one the upgrade touches) and the `write:v1:*` row is
+ * dropped, because adding the resolved endpoint to the hashed data made every
+ * pre-existing write key unreachable. Reading the survivors is what proves
+ * node:sqlite opens a better-sqlite3 file.
  */
 
 import * as fs from 'fs';
@@ -55,7 +63,7 @@ describe('CacheService better-sqlite3 back-compat', () => {
     expect(corruptBackups).toEqual([]);
   });
 
-  it('reads all entries written by better-sqlite3', () => {
+  it('reads the entries written by better-sqlite3 that the upgrade keeps', () => {
     const service = openFixture();
 
     expect(service.get('translate:v1:hello')).toEqual({
@@ -66,16 +74,19 @@ describe('CacheService better-sqlite3 back-compat', () => {
       text: 'Welt',
       detectedSourceLang: 'en',
     });
-    expect(service.get('write:v1:improve')).toEqual({
-      text: 'An improved sentence.',
-    });
+  });
+
+  it('retires the write row the schema upgrade makes unreachable', () => {
+    const service = openFixture();
+
+    expect(service.get('write:v1:improve')).toBeNull();
   });
 
   it('reports accurate stats for the pre-existing entries', () => {
     const service = openFixture();
 
     const stats = service.stats();
-    expect(stats.entries).toBe(3);
+    expect(stats.entries).toBe(2);
     expect(stats.totalSize).toBeGreaterThan(0);
   });
 
@@ -89,7 +100,7 @@ describe('CacheService better-sqlite3 back-compat', () => {
       text: 'Hallo',
       detectedSourceLang: 'en',
     });
-    expect(service.stats().entries).toBe(4);
+    expect(service.stats().entries).toBe(3);
   });
 
   it('survives a close and reopen cycle', () => {
@@ -100,6 +111,6 @@ describe('CacheService better-sqlite3 back-compat', () => {
 
     const reopened = openFixture();
     expect(reopened.get('translate:v1:new')).toEqual({ text: 'Neu' });
-    expect(reopened.stats().entries).toBe(4);
+    expect(reopened.stats().entries).toBe(3);
   });
 });
diff --git a/tests/unit/cache-service.test.ts b/tests/unit/cache-service.test.ts
index 130895e6..6ba12b5a 100644
--- a/tests/unit/cache-service.test.ts
+++ b/tests/unit/cache-service.test.ts
@@ -84,7 +84,7 @@ describe('CacheService', () => {
       const result = db.prepare('PRAGMA user_version').get() as {
         user_version: number;
       };
-      expect(result.user_version).toBe(2);
+      expect(result.user_version).toBe(3);
     });
 
     it('should upgrade-stamp a pre-versioned (user_version=0) database in place', () => {
@@ -105,28 +105,32 @@ describe('CacheService', () => {
               user_version: number;
             }
           ).user_version
-        ).toBe(2);
+        ).toBe(3);
         expect(reopened.get('preexisting')).toEqual({ text: 'survives' });
       } finally {
         reopened.close();
       }
     });
 
-    it('should drop only translation rows when upgrading an older database', () => {
-      // Every translation key changed, so those rows are unreachable. write and
-      // correct keys changed only for the five recased target codes, which a hash
-      // cannot identify, so that namespace is left to its TTL rather than dropped
-      // wholesale.
+    it('should drop the request-keyed namespaces when upgrading an older database', () => {
+      // Adding the resolved endpoint to the hashed data changed every
+      // translation, write, and correct key, so those rows are unreachable —
+      // and dropping them is also what retires a row poisoned by a run against
+      // a custom endpoint. Namespaces whose keys did not change are kept.
       const db = (cacheService as any).db;
       db.exec('PRAGMA user_version = 1');
       cacheService.set('translation:oldhash', { text: 'unreachable' });
-      cacheService.set('write:samehash', { text: 'still reachable' });
+      cacheService.set('write:oldhash', { text: 'unreachable' });
+      cacheService.set('correct:oldhash', { text: 'unreachable' });
+      cacheService.set('languages:target', { text: 'still reachable' });
       cacheService.close();
 
       const reopened = new CacheService({ dbPath: testCachePath });
       try {
         expect(reopened.get('translation:oldhash')).toBeNull();
-        expect(reopened.get('write:samehash')).toEqual({
+        expect(reopened.get('write:oldhash')).toBeNull();
+        expect(reopened.get('correct:oldhash')).toBeNull();
+        expect(reopened.get('languages:target')).toEqual({
           text: 'still reachable',
         });
       } finally {
diff --git a/tests/unit/services/cache-key-endpoint.test.ts b/tests/unit/services/cache-key-endpoint.test.ts
new file mode 100644
index 00000000..6c0faf5e
--- /dev/null
+++ b/tests/unit/services/cache-key-endpoint.test.ts
@@ -0,0 +1,106 @@
+/**
+ * The translation and write cache keys hash the request parameters, but the
+ * resolved API endpoint is not a request parameter — and one cache DB is shared
+ * by every endpoint a config dir has ever talked to. A single run against
+ * `--api-url http://127.0.0.1:18111` therefore served its answers back for
+ * api.deepl.com for the full 30-day TTL, with no network reachable at all.
+ * Custom endpoints are a supported feature (proxies, regional endpoints), so
+ * this needed no misuse to reach.
+ */
+
+import { TranslationService } from '../../../src/services/translation';
+import { WriteService } from '../../../src/services/write';
+import { DeepLClient } from '../../../src/api/deepl-client';
+import type { ConfigService } from '../../../src/storage/config';
+
+interface KeyedService {
+  generateCacheKey: (...args: unknown[]) => string;
+}
+
+// generateCacheKey reads only `this.client`, so a bare config stub suffices.
+const configStub = {} as ConfigService;
+
+function clientFor(baseUrl: string | undefined, usePro = false): DeepLClient {
+  return new DeepLClient('test-key:fx', {
+    ...(baseUrl !== undefined && { baseUrl }),
+    usePro,
+  });
+}
+
+function translationKeyFor(
+  baseUrl: string | undefined,
+  usePro = false
+): string {
+  const service = new TranslationService(
+    clientFor(baseUrl, usePro),
+    configStub
+  );
+  return (service as unknown as KeyedService).generateCacheKey('hello world', {
+    targetLang: 'DE',
+  });
+}
+
+function writeKeyFor(baseUrl: string | undefined): string {
+  const service = new WriteService(clientFor(baseUrl), configStub);
+  return (service as unknown as KeyedService).generateCacheKey(
+    'hello world',
+    { targetLang: 'en-US' },
+    'write'
+  );
+}
+
+describe('translation cache key includes the resolved endpoint', () => {
+  it('should differ between two custom endpoints', () => {
+    expect(translationKeyFor('http://127.0.0.1:18111', false)).not.toBe(
+      translationKeyFor('http://127.0.0.1:18112', false)
+    );
+  });
+
+  it('should differ between a custom endpoint and the default', () => {
+    expect(translationKeyFor('http://127.0.0.1:18111', false)).not.toBe(
+      translationKeyFor(undefined, false)
+    );
+  });
+
+  it('should differ between the free and pro endpoints', () => {
+    expect(translationKeyFor(undefined, false)).not.toBe(
+      translationKeyFor(undefined, true)
+    );
+  });
+
+  it('should stay stable for the same endpoint', () => {
+    expect(translationKeyFor('http://127.0.0.1:18111', false)).toBe(
+      translationKeyFor('http://127.0.0.1:18111', false)
+    );
+  });
+
+  it('should keep the translation: namespace prefix', () => {
+    expect(translationKeyFor(undefined, false)).toMatch(
+      /^translation:[0-9a-f]{64}$/
+    );
+  });
+});
+
+describe('write cache key includes the resolved endpoint', () => {
+  it('should differ between two custom endpoints', () => {
+    expect(writeKeyFor('http://127.0.0.1:18111')).not.toBe(
+      writeKeyFor('http://127.0.0.1:18112')
+    );
+  });
+
+  it('should differ between a custom endpoint and the default', () => {
+    expect(writeKeyFor('http://127.0.0.1:18111')).not.toBe(
+      writeKeyFor(undefined)
+    );
+  });
+
+  it('should stay stable for the same endpoint', () => {
+    expect(writeKeyFor('http://127.0.0.1:18111')).toBe(
+      writeKeyFor('http://127.0.0.1:18111')
+    );
+  });
+
+  it('should keep the write: namespace prefix', () => {
+    expect(writeKeyFor(undefined)).toMatch(/^write:[0-9a-f]{64}$/);
+  });
+});

From 118499830769865bd136a7785ad25bef6a504ea7 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 17:04:41 +0200
Subject: [PATCH 119/256] fix(translate): make --no-cache reach the batch path
 used by structured files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In one function thirty lines apart, the plain-text branch of the translate
command passed `skipCache: !options.cache` and the structured branch
passed only `{ preserveCode }`. TranslationService.translateBatch() had no
service-options parameter at all and consulted persisted `cache.enabled`
alone, so `--no-cache` was accepted and ignored for all 11 structured i18n
formats. A wrong translation was therefore permanent: re-running the
identical command with --no-cache sent zero requests and reproduced the
previous output byte for byte, defeating the one remedy a user reaches for.

translateBatch now takes the same serviceOptions shape as translate() and
honours skipCache on both the cache read and the cache write. The flag is
threaded through translateFile, translateFileToMultiple, and
translateStringsInBatches: the multi-target file path dropped it too, for
plain text as well as structured files, so fixing only the branch the
finding named would have left the sibling bare — the exact shape of the
bug.

Verified end to end against a local stub endpoint: two identical runs
without the flag make one request (the second served from cache), and the
same pair with --no-cache makes two.

`sync` and `batch` do not expose --no-cache; the new parameter is optional,
so every other translateBatch caller keeps its current behaviour.

Refs: cli-8kr2.7

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +
 .../translate/file-translation-handler.ts     |   5 +-
 src/services/file-translation.ts              |  21 ++-
 src/services/structured-file-translation.ts   |  23 +++-
 src/services/translation.ts                   |  27 +++-
 .../translate-batch-skip-cache.test.ts        | 129 ++++++++++++++++++
 .../unit/structured-file-translation.test.ts  |   6 +-
 tests/unit/translate-command.test.ts          |   6 +-
 8 files changed, 196 insertions(+), 23 deletions(-)
 create mode 100644 tests/unit/services/translate-batch-skip-cache.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ec05198..c6248dae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **translate**: **`--no-cache` was accepted and silently ignored for every structured i18n format** — JSON, YAML, TOML, PO, XLIFF, Android XML, iOS `.strings`, `.xcstrings`, ARB, `.properties`, and Laravel PHP. In one function thirty lines apart, the plain-text branch passed `skipCache: !options.cache` and the structured branch passed only `{ preserveCode }`, because `TranslationService.translateBatch()` had no service-options parameter at all and consulted persisted `cache.enabled` alone. A wrong translation was therefore permanent: re-running the identical command with `--no-cache` sent **zero** requests and reproduced the previous output byte for byte, defeating the one remedy a user would reach for. `translateBatch` now takes the same `serviceOptions` shape as `translate()` and honours `skipCache` on both the cache read and the cache write, and the flag is threaded through `translateFile`, `translateFileToMultiple`, and `translateStringsInBatches` — the multi-target file path dropped it too, for plain text as well as structured files, so both single- and multi-target now behave alike rather than fixing one sibling and leaving the other bare. Verified end to end against a local stub: two identical runs without the flag make one request (second served from cache); the same pair with `--no-cache` makes two. The bypass message (`ℹ️ Cache bypassed for this request (--no-cache)`) is emitted on the batch path as well now. `sync` and `batch` do not expose `--no-cache` and are unchanged.
+
 - **translate**: **`--output <dir>` failed with `EISDIR` for a single target language, though it worked for two or more.** `--output` is documented as a file path *or* a directory, and the multi-target branch honoured that — `--to ko,ja --output dir/` wrote `dir/t.ko.md` and `dir/t.ja.md` — while the single-target branch used the destination verbatim and let the atomic rename land on the directory: `Error: EISDIR: illegal operation on a directory, rename 'dir/.tmp.59970.vmrlp5' -> 'dir/'`, exit 1. Two branches of the same command disagreed, and the one that contradicted the documentation was the common one. It affected text files, structured files (JSON/YAML) and documents alike, because each branch decided the destination at its own call site. The destination is now resolved once, ahead of every branch, and a directory names the file the way multi-target translation already does: `deepl translate t.md --to ko --output dir/` writes `dir/t.ko.md`, so two locales into one directory cannot collide. `dir` and `dir/` behave identically — the check is `statSync().isDirectory()`, not a trailing-slash test — and a trailing slash additionally creates the directory when it does not exist, matching multi-target. A converted document is named by `--output-format` (`report.pdf --to de --output-format docx --output dir/` writes `dir/report.de.docx`), since that flag decides what the bytes are. `--output -` and a non-existent path such as `--output out/new.md` are unaffected. Pre-existing, not a regression. `examples/03-batch-processing.sh` hit this in five places and hid four of them behind `2>/dev/null`, `|| true` and a `(cached or completed)` message that reported a cache hit for a call that had errored — so `npm run examples` reported 37/37 passed while this was broken; those guards are gone, and section 8's cache comparison now times calls that actually succeed.
 
 - **sync**: **`deepl sync resolve` kept the local side of every merge conflict, silently discarding a teammate's newer translations.** The documented rule — take the newer translation by `translated_at` — never fired on a real `.deepl-sync.lock`. The leaf test treated any object carrying `source_hash` as a translation to compare, and every lockfile entry carries one, so the resolver read `translated_at` on the entry, where it does not exist; the real timestamp lives on each locale inside that entry's `translations` map, and the recursion that would have reached it was never taken. Each conflict was therefore reported as `kept ours: neither side had translated_at` and resolved to ours, at exit code 0 and without the `length-heuristic` tag that exists to mark exactly this kind of unreliable decision — so the per-entry report gave no sign that anything had been dropped. An entry holding a `translations` map is now treated as a container and merged one locale at a time, which is where the timestamps are, and the report names the locale it decided (`greeting.translations.de`) rather than the entry. Fields the two sides agree on are no longer listed as conflicts. The existing tests passed throughout because their fixtures put `translated_at` directly on the entry, a shape `SyncLockManager` does not write; the suite now also drives the shape it does.
diff --git a/src/cli/commands/translate/file-translation-handler.ts b/src/cli/commands/translate/file-translation-handler.ts
index 53f7cf1f..d6445da2 100644
--- a/src/cli/commands/translate/file-translation-handler.ts
+++ b/src/cli/commands/translate/file-translation-handler.ts
@@ -89,7 +89,8 @@ export class FileTranslationHandler {
         await this.ctx.fileTranslationService.translateFileToMultiple(
           filePath,
           validTargetLangs,
-          translationOptions
+          translationOptions,
+          { skipCache: !options.cache }
         );
 
       return (
@@ -220,7 +221,7 @@ export class FileTranslationHandler {
         filePath,
         options.output!,
         translationOptions,
-        { preserveCode: options.preserveCode }
+        { preserveCode: options.preserveCode, skipCache: !options.cache }
       );
 
       return `Translated ${filePath} -> ${options.output}`;
diff --git a/src/services/file-translation.ts b/src/services/file-translation.ts
index 9810648e..f798b7c6 100644
--- a/src/services/file-translation.ts
+++ b/src/services/file-translation.ts
@@ -18,6 +18,8 @@ interface NodeErrno extends Error {
 
 interface FileTranslationOptions {
   preserveCode?: boolean;
+  /** Bypasses the cache read and write for every request the file produces. */
+  skipCache?: boolean;
 }
 
 interface MultipleFileOptions {
@@ -120,7 +122,8 @@ export class FileTranslationService {
   async translateFileToMultiple(
     inputPath: string,
     targetLangs: Language[],
-    options: Omit<TranslationOptions, 'targetLang'> & MultipleFileOptions = {}
+    options: Omit<TranslationOptions, 'targetLang'> & MultipleFileOptions = {},
+    fileOptions: FileTranslationOptions = {}
   ): Promise<FileMultiTargetResult[]> {
     if (!this.isSupportedFile(inputPath)) {
       throw new ValidationError(
@@ -132,7 +135,12 @@ export class FileTranslationService {
     // Delegate structured files (JSON/YAML) to StructuredFileTranslationService
     if (this.isStructuredExt(inputPath)) {
       const svc = await this.getStructuredService();
-      return svc.translateFileToMultiple(inputPath, targetLangs, options);
+      return svc.translateFileToMultiple(
+        inputPath,
+        targetLangs,
+        options,
+        fileOptions
+      );
     }
 
     // Read file content using safeReadFile (rejects symlinks for security)
@@ -153,11 +161,10 @@ export class FileTranslationService {
 
     // Translate to multiple languages
     const translationResults =
-      await this.translationService.translateToMultiple(
-        content,
-        targetLangs,
-        options
-      );
+      await this.translationService.translateToMultiple(content, targetLangs, {
+        ...options,
+        skipCache: fileOptions.skipCache,
+      });
 
     // Convert to FileMultiTargetResult
     const results: FileMultiTargetResult[] = translationResults.map((r) => ({
diff --git a/src/services/structured-file-translation.ts b/src/services/structured-file-translation.ts
index 632f4df5..ac2bf47b 100644
--- a/src/services/structured-file-translation.ts
+++ b/src/services/structured-file-translation.ts
@@ -19,6 +19,9 @@ import { ValidationError, NetworkError } from '../utils/errors.js';
 
 interface FileTranslationOptions {
   preserveCode?: boolean;
+  /** Bypasses the cache read and write, so `--no-cache` reaches the batch
+   *  path that every structured i18n format goes through. */
+  skipCache?: boolean;
 }
 
 interface FileMultiTargetResult {
@@ -59,7 +62,7 @@ export class StructuredFileTranslationService {
     inputPath: string,
     outputPath: string,
     options: TranslationOptions,
-    _fileOptions: FileTranslationOptions = {}
+    fileOptions: FileTranslationOptions = {}
   ): Promise<void> {
     const content = await this.readFile(inputPath);
 
@@ -74,7 +77,8 @@ export class StructuredFileTranslationService {
     if (strings.length > 0) {
       const translations = await this.translateStringsInBatches(
         strings.map((s) => s.value),
-        options
+        options,
+        fileOptions
       );
 
       if (parsed.format === 'yaml' && parsed.yamlDoc) {
@@ -96,7 +100,8 @@ export class StructuredFileTranslationService {
     targetLangs: Language[],
     options: Omit<TranslationOptions, 'targetLang'> & {
       outputDir?: string;
-    } = {}
+    } = {},
+    fileOptions: FileTranslationOptions = {}
   ): Promise<FileMultiTargetResult[]> {
     const content = await this.readFile(inputPath);
 
@@ -125,7 +130,8 @@ export class StructuredFileTranslationService {
         if (strings.length > 0) {
           const translations = await this.translateStringsInBatches(
             stringValues,
-            { ...options, targetLang }
+            { ...options, targetLang },
+            fileOptions
           );
 
           if (parsed.format === 'yaml' && parsed.yamlDoc) {
@@ -313,7 +319,8 @@ export class StructuredFileTranslationService {
 
   private async translateStringsInBatches(
     strings: string[],
-    options: TranslationOptions
+    options: TranslationOptions,
+    fileOptions: FileTranslationOptions = {}
   ): Promise<string[]> {
     const results: string[] = [];
     let batch: string[] = [];
@@ -325,7 +332,8 @@ export class StructuredFileTranslationService {
       if (batch.length > 0 && batchBytes + strBytes > MAX_TEXT_BYTES) {
         const batchResults = await this.translationService.translateBatch(
           batch,
-          options
+          options,
+          { skipCache: fileOptions.skipCache }
         );
         if (batchResults.length !== batch.length) {
           throw new NetworkError(
@@ -347,7 +355,8 @@ export class StructuredFileTranslationService {
     if (batch.length > 0) {
       const batchResults = await this.translationService.translateBatch(
         batch,
-        options
+        options,
+        { skipCache: fileOptions.skipCache }
       );
       if (batchResults.length !== batch.length) {
         throw new NetworkError(
diff --git a/src/services/translation.ts b/src/services/translation.ts
index 7418406a..3ccc7cb2 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -40,6 +40,15 @@ interface TranslateServiceOptions {
   skipCache?: boolean;
 }
 
+/**
+ * Service-level options for `translateBatch`. Separate from
+ * `TranslateServiceOptions` because code-block preservation is a single-text
+ * concern that the batch path does not apply.
+ */
+export interface TranslateBatchServiceOptions {
+  skipCache?: boolean;
+}
+
 interface MultiTargetResult {
   targetLang: Language;
   text: string;
@@ -181,10 +190,15 @@ export class TranslationService {
    *
    * @param texts - Array of texts to translate
    * @param options - Translation options
+   * @param serviceOptions - `skipCache` bypasses both the cache read and the
+   *   cache write, matching `translate()`. Without it, `--no-cache` was a
+   *   silent no-op for every structured i18n format, so a corrupt translation
+   *   could not be re-fetched and the natural remedy did nothing.
    */
   async translateBatch(
     texts: string[],
-    options: TranslationOptions
+    options: TranslationOptions,
+    serviceOptions: TranslateBatchServiceOptions = {}
   ): Promise<TranslationResult[]> {
     if (texts.length === 0) {
       return [];
@@ -208,6 +222,13 @@ export class TranslationService {
     const configData = this.config.get();
     const defaults = configData.defaults;
     const cacheEnabled = this.config.getValue<boolean>('cache.enabled') ?? true;
+    const shouldUseCache = cacheEnabled && !serviceOptions.skipCache;
+
+    if (!cacheEnabled) {
+      Logger.info('ℹ️  Cache is disabled');
+    } else if (serviceOptions.skipCache) {
+      Logger.info('ℹ️  Cache bypassed for this request (--no-cache)');
+    }
 
     // Merge options with defaults
     const translationOptions: TranslationOptions = {
@@ -233,7 +254,7 @@ export class TranslationService {
 
       const cacheKey = this.generateCacheKey(text, translationOptions);
 
-      if (cacheEnabled) {
+      if (shouldUseCache) {
         const cachedResult = this.cache?.get(cacheKey, isTranslationResult);
         if (cachedResult) {
           results[i] = cachedResult;
@@ -318,7 +339,7 @@ export class TranslationService {
         }
 
         // Cache the result (only once per unique text)
-        if (cacheEnabled) {
+        if (shouldUseCache) {
           const cacheKey = this.generateCacheKey(text, translationOptions);
           this.cache?.set(cacheKey, result);
         }
diff --git a/tests/unit/services/translate-batch-skip-cache.test.ts b/tests/unit/services/translate-batch-skip-cache.test.ts
new file mode 100644
index 00000000..fcbf46f7
--- /dev/null
+++ b/tests/unit/services/translate-batch-skip-cache.test.ts
@@ -0,0 +1,129 @@
+/**
+ * `--no-cache` was a silent no-op for all 11 structured i18n formats.
+ *
+ * In one function 30 lines apart, the plain-text branch of the translate
+ * command passed `skipCache: !options.cache` and the structured branch passed
+ * only `{ preserveCode }` — because `TranslationService.translateBatch()` had
+ * no service-options parameter at all and read `cache.enabled` from persisted
+ * config alone. So a corrupt translation was permanent: re-running the
+ * identical command with `--no-cache` against a different endpoint sent zero
+ * requests and reproduced the poisoned output byte for byte, defeating the one
+ * remedy a user would reach for.
+ */
+
+import { TranslationService } from '../../../src/services/translation';
+import type { DeepLClient } from '../../../src/api/deepl-client';
+import type { ConfigService } from '../../../src/storage/config';
+import type { CacheService } from '../../../src/storage/cache';
+
+function makeService(): {
+  service: TranslationService;
+  clientCalls: string[][];
+  cacheGets: string[];
+  cacheSets: string[];
+} {
+  const clientCalls: string[][] = [];
+  const cacheGets: string[] = [];
+  const cacheSets: string[] = [];
+
+  const client = {
+    resolvedBaseUrl: 'https://api-free.deepl.com',
+    translateBatch: (texts: string[]) => {
+      clientCalls.push(texts);
+      return Promise.resolve(
+        texts.map((t) => ({ text: `FRESH(${t})`, detectedSourceLang: 'en' }))
+      );
+    },
+  } as unknown as DeepLClient;
+
+  const config = {
+    get: () => ({ defaults: {} }),
+    getValue: (key: string) => (key === 'cache.enabled' ? true : undefined),
+  } as unknown as ConfigService;
+
+  const cache = {
+    get: (key: string) => {
+      cacheGets.push(key);
+      return { text: 'POISONED', detectedSourceLang: 'en' };
+    },
+    set: (key: string) => {
+      cacheSets.push(key);
+    },
+  } as unknown as CacheService;
+
+  return {
+    service: new TranslationService(client, config, cache),
+    clientCalls,
+    cacheGets,
+    cacheSets,
+  };
+}
+
+describe('translateBatch honours skipCache', () => {
+  it('serves the cached entry when skipCache is not set', async () => {
+    const { service, clientCalls, cacheGets } = makeService();
+
+    const results = await service.translateBatch(['hello'], {
+      targetLang: 'de',
+    });
+
+    expect(results[0]?.text).toBe('POISONED');
+    expect(cacheGets).toHaveLength(1);
+    expect(clientCalls).toHaveLength(0);
+  });
+
+  it('bypasses the cached entry and calls the API when skipCache is set', async () => {
+    const { service, clientCalls, cacheGets } = makeService();
+
+    const results = await service.translateBatch(
+      ['hello'],
+      { targetLang: 'de' },
+      { skipCache: true }
+    );
+
+    expect(results[0]?.text).toBe('FRESH(hello)');
+    expect(cacheGets).toHaveLength(0);
+    expect(clientCalls).toEqual([['hello']]);
+  });
+
+  it('does not write the fresh result back when skipCache is set', async () => {
+    const { service, cacheSets } = makeService();
+
+    await service.translateBatch(
+      ['hello'],
+      { targetLang: 'de' },
+      { skipCache: true }
+    );
+
+    expect(cacheSets).toHaveLength(0);
+  });
+
+  it('writes the fresh result back when skipCache is not set', async () => {
+    const { service, cacheSets } = makeService();
+    const cache = (service as unknown as { cache: { get: () => unknown } })
+      .cache;
+    cache.get = () => null;
+
+    await service.translateBatch(['hello'], { targetLang: 'de' });
+
+    expect(cacheSets).toHaveLength(1);
+  });
+
+  it('bypasses the cache for every text in a multi-text batch', async () => {
+    const { service, clientCalls, cacheGets } = makeService();
+
+    const results = await service.translateBatch(
+      ['one', 'two', 'three'],
+      { targetLang: 'de' },
+      { skipCache: true }
+    );
+
+    expect(results.map((r) => r.text)).toEqual([
+      'FRESH(one)',
+      'FRESH(two)',
+      'FRESH(three)',
+    ]);
+    expect(cacheGets).toHaveLength(0);
+    expect(clientCalls).toEqual([['one', 'two', 'three']]);
+  });
+});
diff --git a/tests/unit/structured-file-translation.test.ts b/tests/unit/structured-file-translation.test.ts
index 6750215a..7633079c 100644
--- a/tests/unit/structured-file-translation.test.ts
+++ b/tests/unit/structured-file-translation.test.ts
@@ -527,7 +527,8 @@ describe('StructuredFileTranslationService', () => {
       expect(mockTranslationService.translateBatch).toHaveBeenCalledTimes(1);
       expect(mockTranslationService.translateBatch).toHaveBeenCalledWith(
         expect.arrayContaining(['Value 0']),
-        expect.objectContaining({ targetLang: 'es' })
+        expect.objectContaining({ targetLang: 'es' }),
+        { skipCache: undefined }
       );
     });
 
@@ -697,7 +698,8 @@ describe('StructuredFileTranslationService', () => {
           targetLang: 'es',
           formality: 'more',
           glossaryId: 'g-123',
-        })
+        }),
+        { skipCache: undefined }
       );
     });
   });
diff --git a/tests/unit/translate-command.test.ts b/tests/unit/translate-command.test.ts
index 0254d651..7a59ebe4 100644
--- a/tests/unit/translate-command.test.ts
+++ b/tests/unit/translate-command.test.ts
@@ -1204,7 +1204,8 @@ describe('TranslateCommand', () => {
       expect(mockFileService.translateFileToMultiple).toHaveBeenCalledWith(
         '/input.txt',
         ['es', 'fr'],
-        expect.objectContaining({ sourceLang: 'en', outputDir: '/output' })
+        expect.objectContaining({ sourceLang: 'en', outputDir: '/output' }),
+        expect.objectContaining({ skipCache: expect.any(Boolean) })
       );
     });
 
@@ -1232,7 +1233,8 @@ describe('TranslateCommand', () => {
       expect(mockFileService.translateFileToMultiple).toHaveBeenCalledWith(
         '/input.txt',
         ['es', 'de'],
-        expect.objectContaining({ formality: 'more', outputDir: '/output' })
+        expect.objectContaining({ formality: 'more', outputDir: '/output' }),
+        expect.objectContaining({ skipCache: expect.any(Boolean) })
       );
     });
   });

From 631d4778429ae79d63055247030ae9869544b784 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 21:55:19 +0200
Subject: [PATCH 120/256] fix(api): refuse a batch response that returns the
 submitted texts reordered
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

POST /v2/translate correlates a translation to its request item by position
and by nothing else, and the only check on the response was that it carried
the same number of entries. An endpoint returning the request's own texts
rotated by one therefore wrote every translation under the wrong i18n key
at exit 0, reporting full success:

  {confirm_delete: 'Delete account permanently', cancel: 'Cancel',
   save: 'Save changes'}
    -> {confirm_delete: 'Cancel', cancel: 'Save changes',
        save: 'Delete account permanently'}

which hides a destructive action behind the cancel label. The placeholder
validator cannot see it, since plain UI strings carry no placeholders to
compare, and the result was then cached under the submitted text.

translateBatch now rejects a response that is the submitted texts
themselves rearranged. Both conditions are required — a multiset match on
the returned texts and at least one moved position — so it cannot fire on
an identity translation (source language equal to target, where nothing
moves) or on a single item whose translation happens to equal another
item's source text, which a partially translated file produces. Duplicates
are counted rather than deduped, so a repeated text out of place is read as
a bad translation and not as a reordering.

This is deliberately narrow. It catches the one reordering that is provable
from the response alone; an endpoint returning plausible translations in
the wrong order stays undetectable, because the protocol carries no
per-item identity to check against. The alternative the finding suggested —
carrying a sentinel through the placeholder mechanism — was rejected: it
perturbs the text sent to the engine, changes billed characters, and
degrades the primary function to defend against an endpoint the operator
configured.

The guard sits in the one client method every batch caller shares, so it
covers translate on all 11 structured formats, plain-text batches, and
sync. Verified end to end against a rotating stub endpoint: exit 5 and no
file written, where the same command previously exited 0 with the keys
transposed; an honest stub on the same fixture is unaffected.

Refs: cli-8kr2.6

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +
 src/api/translation-client.ts                 | 54 +++++++++++++
 ...uctured-file-translate.integration.test.ts | 39 ++++++++++
 tests/unit/translation-client.test.ts         | 75 +++++++++++++++++++
 4 files changed, 170 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c6248dae..42aeff4a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -357,6 +357,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **api**: a batch translation response that returns the submitted texts themselves, rearranged, is now refused instead of written out. `POST /v2/translate` correlates a translation to its request item by position and by nothing else, and the only check on the response was that it had the same number of entries — so an endpoint returning the request's own texts rotated by one wrote each translation under the wrong i18n key at exit 0, reporting full success. `{confirm_delete: 'Delete account permanently', cancel: 'Cancel', save: 'Save changes'}` came back as `{confirm_delete: 'Cancel', cancel: 'Save changes', save: 'Delete account permanently'}`, hiding a destructive action behind the cancel label; the placeholder validator cannot see it, because plain UI strings carry no placeholders to compare. Verified end to end against a rotating stub: exit 5 and no file written, where the same run previously exited 0 with the keys transposed, and an honest endpoint on the same fixture is unaffected. The check requires **both** that the returned texts are a multiset match for the submitted ones and that at least one has moved position, so it cannot fire on a legitimate identity translation (source language equal to target, where nothing moves) or on one item whose translation happens to equal another item's source text, which a partially translated file produces. It is deliberately narrow: this catches the one reordering that is provable from the response alone, and an endpoint returning plausible **translations** in the wrong order remains undetectable, because the protocol carries no per-item identity to verify. It applies to every batch caller — `translate` on all 11 structured i18n formats, plain-text batches, and `sync` — since it sits in the one client method they share.
+
 - **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
 
 - **cache**: the resolved API base URL is now part of every translation, `write`, and `correct` cache key. One `cache.db` is shared by every endpoint a config directory has ever talked to, and the key hashed 20 request parameters but not who was going to answer them — so a single `deepl translate "hello" --to DE --api-url http://127.0.0.1:18111` served that endpoint's answer back for `api.deepl.com` for the full 30-day TTL, with no network reachable at all. Custom endpoints are a supported feature (proxies, regional endpoints), so this needed nothing the tool discourages: pointing the CLI at a local stub once was enough to make its output the cached truth everywhere. Verified end to end against two stub endpoints returning different text for the same request: each now gets its own row, and neither can answer for the other or for the real API. The endpoint is derived from the same expression the HTTP transport uses (`resolveClientBaseUrl`) rather than a second copy that could drift, and the free and Pro endpoints are keyed apart too. `CACHE_SCHEMA_VERSION` moves to 3, so opening an existing DB drops its `translation:`, `write:`, and `correct:` rows — every one of those keys changed, and retiring them is also what clears any entry a custom endpoint already poisoned. Other namespaces are untouched. Cache **writes** are deliberately still allowed for non-standard endpoints: with the endpoint in the key there is nothing left to cross-contaminate, and disabling them would cost proxy and regional-endpoint users their cache for no gain.
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index c4150d93..44828527 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -66,6 +66,47 @@ export interface TranslationResult {
   cached?: boolean;
 }
 
+/**
+ * Whether `returned` is the submitted `texts` themselves, rearranged.
+ *
+ * /v2/translate correlates a translation to its request item by position and
+ * nothing else, so a same-length reordered response passes the length check and
+ * gets written under the wrong i18n key at exit 0. This catches the one
+ * reordering that is provable from the response alone; an endpoint that returns
+ * plausible translations in the wrong order stays undetectable, because the
+ * protocol carries no per-item identity to check against.
+ *
+ * Both conditions are required. Multiset equality alone fires on a legitimate
+ * identity translation (source language equal to target). A displaced position
+ * alone fires whenever one item's translation happens to equal another item's
+ * source text, which a partially translated file produces.
+ */
+function isReorderedEcho(texts: string[], returned: string[]): boolean {
+  const remaining = new Map<string, number>();
+  for (const text of texts) {
+    remaining.set(text, (remaining.get(text) ?? 0) + 1);
+  }
+
+  let displaced = false;
+  for (let i = 0; i < returned.length; i++) {
+    const text = returned[i]!;
+    const count = remaining.get(text);
+    if (count === undefined) {
+      return false;
+    }
+    if (count === 1) {
+      remaining.delete(text);
+    } else {
+      remaining.set(text, count - 1);
+    }
+    if (text !== texts[i]) {
+      displaced = true;
+    }
+  }
+
+  return displaced && remaining.size === 0;
+}
+
 export function isTranslationResult(data: unknown): data is TranslationResult {
   if (data === null || typeof data !== 'object') {
     return false;
@@ -196,6 +237,19 @@ export class TranslationClient extends HttpClient {
         );
       }
 
+      if (
+        isReorderedEcho(
+          texts,
+          response.translations.map((translation) => translation.text)
+        )
+      ) {
+        throw new NetworkError(
+          'The endpoint returned the submitted texts in a different order, so each translation ' +
+            'would be stored against the wrong entry. Nothing was written. Check which endpoint ' +
+            'this run used (--api-url, or api.baseUrl in your config).'
+        );
+      }
+
       return response.translations.map((translation) => ({
         text: translation.text,
         detectedSourceLang: translation.detected_source_language
diff --git a/tests/integration/cli-structured-file-translate.integration.test.ts b/tests/integration/cli-structured-file-translate.integration.test.ts
index 268286f7..26b72fb6 100644
--- a/tests/integration/cli-structured-file-translate.integration.test.ts
+++ b/tests/integration/cli-structured-file-translate.integration.test.ts
@@ -117,6 +117,45 @@ describe('Structured File Translation service integration', () => {
       expect(result.farewell).toBe('Adiós');
     });
 
+    it('should refuse to write a file when the endpoint reorders the batch', async () => {
+      const inputPath = path.join(testDir, 'svc-reorder-en.json');
+      const outputPath = path.join(testDir, 'svc-reorder-de.json');
+
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            confirm_delete: 'Delete account permanently',
+            cancel: 'Cancel',
+            save: 'Save changes',
+          },
+          null,
+          2
+        )
+      );
+
+      nock(FREE_API_URL)
+        .post('/v2/translate')
+        .reply(200, {
+          translations: [
+            { text: 'Cancel', detected_source_language: 'EN' },
+            { text: 'Save changes', detected_source_language: 'EN' },
+            {
+              text: 'Delete account permanently',
+              detected_source_language: 'EN',
+            },
+          ],
+        });
+
+      await expect(
+        fileTranslationService.translateFile(inputPath, outputPath, {
+          targetLang: 'de',
+        })
+      ).rejects.toThrow('returned the submitted texts in a different order');
+
+      expect(fs.existsSync(outputPath)).toBe(false);
+    });
+
     it('should translate nested JSON preserving structure', async () => {
       const inputPath = path.join(testDir, 'svc-nested.json');
       const outputPath = path.join(testDir, 'svc-nested-es.json');
diff --git a/tests/unit/translation-client.test.ts b/tests/unit/translation-client.test.ts
index 5f4f0432..228944a2 100644
--- a/tests/unit/translation-client.test.ts
+++ b/tests/unit/translation-client.test.ts
@@ -196,6 +196,81 @@ describe('TranslationClient', () => {
         client.translateBatch(['Hello'], { targetLang: 'es' })
       ).rejects.toThrow('Unexpected API response');
     });
+
+    describe('reordered-echo rejection', () => {
+      const replyWith = (texts: string[]): void => {
+        mockAxiosInstance.request.mockResolvedValue({
+          data: { translations: texts.map((text) => ({ text })) },
+          status: 200,
+          headers: {},
+        });
+      };
+
+      it('should reject a response that rotates the submitted texts', async () => {
+        const texts = ['Delete account permanently', 'Cancel', 'Save changes'];
+        replyWith(['Cancel', 'Save changes', 'Delete account permanently']);
+
+        await expect(
+          client.translateBatch(texts, { targetLang: 'de' })
+        ).rejects.toThrow('returned the submitted texts in a different order');
+      });
+
+      it('should reject a response that swaps two of the submitted texts', async () => {
+        replyWith(['Hola', 'Adiós', 'Sí']);
+        await expect(
+          client.translateBatch(['Hola', 'Sí', 'Adiós'], { targetLang: 'es' })
+        ).rejects.toThrow('returned the submitted texts in a different order');
+      });
+
+      it('should accept a response that echoes every text in place', async () => {
+        replyWith(['Hello', 'World']);
+
+        const result = await client.translateBatch(['Hello', 'World'], {
+          targetLang: 'en-us',
+        });
+
+        expect(result.map((r) => r.text)).toEqual(['Hello', 'World']);
+      });
+
+      it('should accept a translation that coincides with another item’s source text', async () => {
+        // 'Hello' translates to 'Hallo', which is also the second submitted
+        // text: one displaced position, but not a rearrangement of the batch.
+        replyWith(['Hallo', 'Hallo']);
+
+        const result = await client.translateBatch(['Hello', 'Hallo'], {
+          targetLang: 'de',
+        });
+
+        expect(result.map((r) => r.text)).toEqual(['Hallo', 'Hallo']);
+      });
+
+      it('should accept a single echoed text', async () => {
+        replyWith(['OK']);
+
+        const result = await client.translateBatch(['OK'], {
+          targetLang: 'de',
+        });
+
+        expect(result[0]!.text).toBe('OK');
+      });
+
+      it('should accept a response that repeats one submitted text out of place', async () => {
+        // Duplicate-aware: the returned multiset differs from the submitted
+        // one, so this is a bad translation, not a detectable reordering.
+        replyWith(['Cancel', 'Cancel', 'Guardar']);
+
+        const result = await client.translateBatch(
+          ['Delete', 'Cancel', 'Save'],
+          { targetLang: 'es' }
+        );
+
+        expect(result.map((r) => r.text)).toEqual([
+          'Cancel',
+          'Cancel',
+          'Guardar',
+        ]);
+      });
+    });
   });
 
   describe('translation memory params', () => {

From 4b3e895e8225187e3400bc53b60422957cb4f251 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 22:02:56 +0200
Subject: [PATCH 121/256] fix(sync): stop one shared result from carrying
 another key's placeholder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

preserveVariables replaces every variable with a positional token, so
'Hello {name}' and 'Hello {user}' both become 'Hello __VAR_0__' — one text
on the wire, which is what the deduplication in translateBatch exists to
exploit. It then assigned the same result OBJECT to every index that
duplicate covered, and the restore loop in sync-locale-translator edited
result.text in place. The first key's restore consumed the token, so the
second key found none left and was written with the first key's variable:

  {alpha: 'Hello {name}', beta: 'Hello {user}'}
    -> beta: 'XX Hello {name}'

  {delta: 'Deleted %s files', epsilon: 'Deleted %d files'}
    -> epsilon: 'XX Deleted %s files'

The second pair is the common one, and it produces a format specifier that
no longer matches its argument. No hostile input is involved — two strings
differing only in their variable is enough. The run reported 5/5 keys at
exit 0, the lockfile recorded the key as translated, and the next sync
reported it current, so the corruption was permanent.

Fixed at the producer: translateBatch gives each index its own copy, since
it returns an array typed as one result per index and six other callers are
one refactor away from the same bug. Both restore loops also replace their
entry rather than editing it, so the idiom that turned an alias into
corruption is gone from the call sites too.

Verified end to end against a local stub: every key now gets its own
placeholder back, and the two validation errors and two warnings the run
previously emitted — advisory, exit 0, details not printed — are gone,
since they were reporting exactly this.

deepl translate was never affected; its single-text path already returned a
new string rather than mutating.

Refs: cli-8kr2.12

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                               |  2 +
 src/services/translation.ts                |  9 ++++-
 src/sync/sync-locale-translator.ts         | 23 ++++++++----
 tests/integration/sync.integration.test.ts | 43 ++++++++++++++++++++++
 tests/unit/translation-service.test.ts     | 17 +++++++++
 5 files changed, 84 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 42aeff4a..92f22ca9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **two keys whose placeholders protect to the same text no longer receive each other's variables.** `preserveVariables` replaces every variable with a positional token, so `Hello {name}` and `Hello {user}` both become `Hello __VAR_0__` — one text on the wire, and `TranslationService.translateBatch` deduplicates them, which is the point. It then assigned the *same* result object to every index the duplicate covered, and the restore loop in `sync-locale-translator.ts` edited `result.text` **in place**: the first key's restore consumed the token, so the second key found none left and was written with the first key's variable. `{alpha: 'Hello {name}', beta: 'Hello {user}'}` produced `beta: 'XX Hello {name}'`, and the far more common `%s`/`%d` pair — `{delta: 'Deleted %s files', epsilon: 'Deleted %d files'}` — produced `epsilon: 'XX Deleted %s files'`, a format specifier that no longer matches its argument. This needed no hostile input, only two strings that differ solely in their variable. The run reported `5/5 keys` at exit 0, the lockfile recorded the affected key as `translated`, and the next sync reported it `current`, so the corruption was permanent. `translateBatch` now gives each index its own copy of the result — the array is typed as one result per index, and no caller can alias two logical results any more — and both restore loops replace their entry instead of editing it. Verified end to end: every key gets its own placeholder back, and the two validation errors and two warnings the run previously emitted (advisory, exit 0, details not printed) are gone, since they were reporting exactly this. `deepl translate` was never affected; its single-text path already returned a new string.
+
 - **translate**: **`--no-cache` was accepted and silently ignored for every structured i18n format** — JSON, YAML, TOML, PO, XLIFF, Android XML, iOS `.strings`, `.xcstrings`, ARB, `.properties`, and Laravel PHP. In one function thirty lines apart, the plain-text branch passed `skipCache: !options.cache` and the structured branch passed only `{ preserveCode }`, because `TranslationService.translateBatch()` had no service-options parameter at all and consulted persisted `cache.enabled` alone. A wrong translation was therefore permanent: re-running the identical command with `--no-cache` sent **zero** requests and reproduced the previous output byte for byte, defeating the one remedy a user would reach for. `translateBatch` now takes the same `serviceOptions` shape as `translate()` and honours `skipCache` on both the cache read and the cache write, and the flag is threaded through `translateFile`, `translateFileToMultiple`, and `translateStringsInBatches` — the multi-target file path dropped it too, for plain text as well as structured files, so both single- and multi-target now behave alike rather than fixing one sibling and leaving the other bare. Verified end to end against a local stub: two identical runs without the flag make one request (second served from cache); the same pair with `--no-cache` makes two. The bypass message (`ℹ️ Cache bypassed for this request (--no-cache)`) is emitted on the batch path as well now. `sync` and `batch` do not expose `--no-cache` and are unchanged.
 
 - **translate**: **`--output <dir>` failed with `EISDIR` for a single target language, though it worked for two or more.** `--output` is documented as a file path *or* a directory, and the multi-target branch honoured that — `--to ko,ja --output dir/` wrote `dir/t.ko.md` and `dir/t.ja.md` — while the single-target branch used the destination verbatim and let the atomic rename land on the directory: `Error: EISDIR: illegal operation on a directory, rename 'dir/.tmp.59970.vmrlp5' -> 'dir/'`, exit 1. Two branches of the same command disagreed, and the one that contradicted the documentation was the common one. It affected text files, structured files (JSON/YAML) and documents alike, because each branch decided the destination at its own call site. The destination is now resolved once, ahead of every branch, and a directory names the file the way multi-target translation already does: `deepl translate t.md --to ko --output dir/` writes `dir/t.ko.md`, so two locales into one directory cannot collide. `dir` and `dir/` behave identically — the check is `statSync().isDirectory()`, not a trailing-slash test — and a trailing slash additionally creates the directory when it does not exist, matching multi-target. A converted document is named by `--output-format` (`report.pdf --to de --output-format docx --output dir/` writes `dir/report.de.docx`), since that flag decides what the bytes are. `--output -` and a non-existent path such as `--output out/new.md` are unaffected. Pre-existing, not a regression. `examples/03-batch-processing.sh` hit this in five places and hid four of them behind `2>/dev/null`, `|| true` and a `(cached or completed)` message that reported a cache hit for a call that had errored — so `npm run examples` reported 37/37 passed while this was broken; those guards are gone, and section 8's cache comparison now times calls that actually succeed.
diff --git a/src/services/translation.ts b/src/services/translation.ts
index 3ccc7cb2..5bda7ec7 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -333,9 +333,14 @@ export class TranslationService {
 
       const originalIndices = textIndexMap.get(text);
       if (originalIndices) {
-        // Assign result to ALL indices where this text appeared (handles duplicates)
+        // Assign result to ALL indices where this text appeared (handles
+        // duplicates). Each index gets its own copy: the returned array is
+        // typed as one result per index, and a caller editing results[i] in
+        // place was silently editing every other index whose text deduplicated
+        // to the same request item — which wrote one key's placeholder into
+        // another key's translation.
         for (const index of originalIndices) {
-          results[index] = result;
+          results[index] = { ...result };
         }
 
         // Cache the result (only once per unique text)
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 418e6843..f6ab23ac 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -484,11 +484,17 @@ export class LocaleTranslator {
       }
     }
 
-    // Restore placeholders in all results
+    // Restore placeholders in all results, replacing each entry rather than
+    // editing it, so a result this batch shares with another index keeps its
+    // own placeholders.
     for (let ri = 0; ri < results.length; ri++) {
       const pMap = preservationMaps[ri];
-      if (results[ri] && pMap && pMap.size > 0) {
-        results[ri]!.text = restorePlaceholders(results[ri]!.text, pMap);
+      const result = results[ri];
+      if (result && pMap && pMap.size > 0) {
+        results[ri] = {
+          ...result,
+          text: restorePlaceholders(result.text, pMap),
+        };
       }
     }
 
@@ -637,11 +643,12 @@ export class LocaleTranslator {
 
         for (let ri = 0; ri < newLocaleResults.length; ri++) {
           const pMap = nlPreservationMaps[ri];
-          if (newLocaleResults[ri] && pMap && pMap.size > 0) {
-            newLocaleResults[ri]!.text = restorePlaceholders(
-              newLocaleResults[ri]!.text,
-              pMap
-            );
+          const nlResult = newLocaleResults[ri];
+          if (nlResult && pMap && pMap.size > 0) {
+            newLocaleResults[ri] = {
+              ...nlResult,
+              text: restorePlaceholders(nlResult.text, pMap),
+            };
           }
         }
 
diff --git a/tests/integration/sync.integration.test.ts b/tests/integration/sync.integration.test.ts
index ef3123c0..68ccbf9b 100644
--- a/tests/integration/sync.integration.test.ts
+++ b/tests/integration/sync.integration.test.ts
@@ -174,6 +174,49 @@ describe('Sync Integration', () => {
       expect(translated).toHaveProperty('welcome');
     });
 
+    it('should restore each key’s own placeholder when two keys protect alike', async () => {
+      writeYamlConfig(tmpDir, BASIC_CONFIG_YAML);
+      writeSourceFile(
+        tmpDir,
+        'locales/en.json',
+        JSON.stringify(
+          {
+            alpha: 'Hello {name}',
+            beta: 'Hello {user}',
+            delta: 'Deleted %s files',
+            epsilon: 'Deleted %d files',
+          },
+          null,
+          2
+        ) + '\n'
+      );
+
+      // Each pair protects to the same placeholder text, so only two texts are
+      // sent. Echoing them back with a prefix keeps which source produced which
+      // translation readable in the target file.
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .reply(200, (_uri, body) => ({
+          translations: new URLSearchParams(String(body))
+            .getAll('text')
+            .map((text) => ({
+              text: `XX ${text}`,
+              detected_source_language: 'EN',
+            })),
+        }));
+
+      const config = await loadSyncConfig(tmpDir);
+      await syncService.sync(config);
+
+      const translated = JSON.parse(
+        fs.readFileSync(path.join(tmpDir, 'locales', 'de.json'), 'utf-8')
+      );
+      expect(translated.alpha).toBe('XX Hello {name}');
+      expect(translated.beta).toBe('XX Hello {user}');
+      expect(translated.delta).toBe('XX Deleted %s files');
+      expect(translated.epsilon).toBe('XX Deleted %d files');
+    });
+
     it('should create lock file', async () => {
       writeYamlConfig(tmpDir, BASIC_CONFIG_YAML);
       writeSourceFile(tmpDir, 'locales/en.json', SOURCE_JSON);
diff --git a/tests/unit/translation-service.test.ts b/tests/unit/translation-service.test.ts
index 5fb11b14..60292bc5 100644
--- a/tests/unit/translation-service.test.ts
+++ b/tests/unit/translation-service.test.ts
@@ -249,6 +249,23 @@ describe('TranslationService', () => {
       expect(mockDeepLClient.translate).not.toHaveBeenCalled();
     });
 
+    it('should give each duplicate text its own result object', async () => {
+      mockDeepLClient.translateBatch.mockResolvedValue([{ text: 'Hola' }]);
+
+      const results = await translationService.translateBatch(
+        ['Hello', 'Hello'],
+        { targetLang: 'es' }
+      );
+
+      expect(mockDeepLClient.translateBatch).toHaveBeenCalledWith(
+        ['Hello'],
+        expect.objectContaining({ targetLang: 'es' })
+      );
+      expect(results[0]).toEqual(results[1]);
+      // A caller that mutates results[0] must not be editing results[1].
+      expect(results[0]).not.toBe(results[1]);
+    });
+
     it('should handle empty array', async () => {
       const results = await translationService.translateBatch([], {
         targetLang: 'es',

From b9ab98a94d13b596c01dd774ba2d58fcf7bf4b8d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 22:23:54 +0200
Subject: [PATCH 122/256] fix(sync): bound recursive parser walks and skip the
 one file, not the run
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The JSON and YAML walkers recurse once per nesting level with no depth
guard, so a 16KB file of 8,000 nested arrays killed deepl sync, sync
validate and translate <file> alike with 'Error: Maximum call stack size
exceeded'. It is far below the 4 MiB max_file_bytes default, so the
pre-read size check never sees it.

In a sync it was worse than a crash. A healthy file earlier in the bucket
had already been translated, billed and written, and the run died before
the lockfile was written, so that work was unrecorded and the next run paid
for it again.

sync.limits.max_depth existed for this and reached only the Laravel PHP
parser; sync-bucket-walker.ts documented the gap in a comment rather than
closing it. Now:

- JsonFormatParser takes a maxDepth and rejects past it with a catchable
  FormatDepthExceededError naming the key path, on extract and reconstruct
  alike (reconstruct blew up earlier than extract, at ~4,000 levels).
- The walker applies sync.limits.max_depth to any parser that accepts one,
  through a new optional withMaxDepth on FormatParser, so the next
  recursive parser opts in instead of needing another special case. It
  applies unconditionally rather than only when the user overrode the
  default, since a parser's own default is a stack-safety ceiling and
  sync's is a policy.
- One file over the cap is skipped with a warning and the run finishes and
  records what it did. PhpArraysCapExceededError now extends the shared
  error, so one catch covers every parser.

YAML is bounded differently, because bounding our own recursion could not
have helped it: the yaml library builds its tree recursively and reports the
blown stack as a parse diagnostic, so it fails inside the library before
collectStringSlots runs at all. Measured in both flow and block style. That
diagnostic is classified as a depth rejection so the same skip applies, and
a RangeError escaping any parser is caught at the same boundary as a
backstop. Adding a maxDepth to yaml's visit would have been dead code.

The direct translate <file> path has no .deepl-sync.yaml and so no
configured limit; it gets a fixed ceiling of 100 levels, which clears any
realistic i18n file and sits far below the ~2,000 at which the stack gives
out, so its only effect is to name the failure instead of exhausting the
stack.

Verified end to end: a bucket holding one healthy and one 8,000-deep file
completes at exit 0, writes the healthy target and the lockfile, and reports
the skip; the same holds for a deep YAML bucket and for sync validate.

Refs: cli-8kr2.18

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +
 docs/SYNC.md                                  |  2 +-
 src/formats/format.ts                         | 29 ++++++
 src/formats/index.ts                          |  1 +
 src/formats/json.ts                           | 89 ++++++++++++++++---
 src/formats/php-arrays.ts                     | 15 ++--
 src/formats/yaml.ts                           | 29 +++++-
 src/services/structured-file-translation.ts   | 35 ++++++--
 src/sync/sync-bucket-walker.ts                | 43 +++++----
 tests/integration/sync.integration.test.ts    | 57 ++++++++++++
 tests/unit/formats/json.test.ts               | 65 +++++++++++++-
 tests/unit/formats/yaml.test.ts               | 25 +++++-
 .../unit/structured-file-translation.test.ts  | 38 ++++++++
 13 files changed, 381 insertions(+), 49 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 92f22ca9..1d7d6931 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync, translate**: **a deeply nested JSON or YAML file no longer ends the whole run with `Error: Maximum call stack size exceeded`.** The JSON and YAML walkers recurse once per nesting level with no depth guard, so a 16KB file of 8,000 nested arrays — far below the 4 MiB `sync.limits.max_file_bytes` default, so the pre-read size check never sees it — killed `deepl sync`, `deepl sync validate` and `deepl translate <file>` alike. In a sync it was worse than a crash: a healthy file earlier in the bucket had already been translated, billed and written, and because the run died before the lockfile was written that work was unrecorded, so the next run paid for it again. `sync.limits.max_depth` (default 32, ceiling 64) existed for exactly this and was wired only to the Laravel PHP parser, which `sync-bucket-walker.ts` documented in a comment rather than fixing. Three changes: `JsonFormatParser` takes a `maxDepth` and rejects past it with a catchable error naming the key path; the walker now applies `sync.limits.max_depth` to **any** parser that accepts one — via a new optional `withMaxDepth` on `FormatParser`, so a future recursive parser opts in rather than needing a new special case — and always, rather than only when the user overrode the default; and one file exceeding the cap is skipped with a warning while the run finishes and records what it did. Verified end to end: a bucket holding one healthy and one 8,000-deep file now completes at exit 0, writes the healthy target, writes the lockfile, and prints `Skipping deep/en.json: JSON: max nesting depth 32 exceeded at 'a.0.0.0…'`. **YAML is bounded differently, because bounding our own recursion could not have helped it:** the `yaml` library builds its tree recursively and reports the blown stack as a parse diagnostic, so it fails inside the library before any walker of ours runs — measured in both flow and block style. That diagnostic is now recognised as a depth rejection and skipped like any other, and a `RangeError` escaping any parser is caught at the same boundary as a backstop. The direct `deepl translate <file>` path has no `.deepl-sync.yaml` and so no configured limit; it gets a fixed ceiling of 100 levels, which clears any realistic i18n file by a wide margin and sits far below the ~2,000 levels at which the stack actually gives out, so its only effect is to turn an opaque stack overflow into a named error.
+
 - **sync**: **two keys whose placeholders protect to the same text no longer receive each other's variables.** `preserveVariables` replaces every variable with a positional token, so `Hello {name}` and `Hello {user}` both become `Hello __VAR_0__` — one text on the wire, and `TranslationService.translateBatch` deduplicates them, which is the point. It then assigned the *same* result object to every index the duplicate covered, and the restore loop in `sync-locale-translator.ts` edited `result.text` **in place**: the first key's restore consumed the token, so the second key found none left and was written with the first key's variable. `{alpha: 'Hello {name}', beta: 'Hello {user}'}` produced `beta: 'XX Hello {name}'`, and the far more common `%s`/`%d` pair — `{delta: 'Deleted %s files', epsilon: 'Deleted %d files'}` — produced `epsilon: 'XX Deleted %s files'`, a format specifier that no longer matches its argument. This needed no hostile input, only two strings that differ solely in their variable. The run reported `5/5 keys` at exit 0, the lockfile recorded the affected key as `translated`, and the next sync reported it `current`, so the corruption was permanent. `translateBatch` now gives each index its own copy of the result — the array is typed as one result per index, and no caller can alias two logical results any more — and both restore loops replace their entry instead of editing it. Verified end to end: every key gets its own placeholder back, and the two validation errors and two warnings the run previously emitted (advisory, exit 0, details not printed) are gone, since they were reporting exactly this. `deepl translate` was never affected; its single-text path already returned a new string.
 
 - **translate**: **`--no-cache` was accepted and silently ignored for every structured i18n format** — JSON, YAML, TOML, PO, XLIFF, Android XML, iOS `.strings`, `.xcstrings`, ARB, `.properties`, and Laravel PHP. In one function thirty lines apart, the plain-text branch passed `skipCache: !options.cache` and the structured branch passed only `{ preserveCode }`, because `TranslationService.translateBatch()` had no service-options parameter at all and consulted persisted `cache.enabled` alone. A wrong translation was therefore permanent: re-running the identical command with `--no-cache` sent **zero** requests and reproduced the previous output byte for byte, defeating the one remedy a user would reach for. `translateBatch` now takes the same `serviceOptions` shape as `translate()` and honours `skipCache` on both the cache read and the cache write, and the flag is threaded through `translateFile`, `translateFileToMultiple`, and `translateStringsInBatches` — the multi-target file path dropped it too, for plain text as well as structured files, so both single- and multi-target now behave alike rather than fixing one sibling and leaving the other bare. Verified end to end against a local stub: two identical runs without the flag make one request (second served from cache); the same pair with `--no-cache` makes two. The bypass message (`ℹ️ Cache bypassed for this request (--no-cache)`) is emitted on the batch path as well now. `sync` and `batch` do not expose `--no-cache` and are unchanged.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 2c9e849e..a36acea1 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -276,7 +276,7 @@ In JSON output (`--format json`), the `strategy` field provides the breakdown:
 | `max_scan_files` | `number` | No | `50000` | Hard ceiling on the number of files matched by `context.scan_paths`. Prevents a misconfigured pattern from wedging the CLI on shared CI with huge source trees and slow disks. Exceeding the cap throws `ValidationError` with a suggestion to narrow the pattern. Positive integer. |
 | `limits.max_entries_per_file` | `number` | No | `25000` | Per-file parser cap on extracted entry count. Files exceeding this are skipped with a warning. Hard ceiling: `100000`. Values above the ceiling fail at config load with `ConfigError` (exit 7). |
 | `limits.max_file_bytes` | `number` | No | `4194304` (4 MiB) | Per-file parser cap on on-disk size, checked via `fs.stat` before read. Files exceeding this are skipped with a warning. Hard ceiling: `10485760` (10 MiB). Values above the ceiling fail at config load with `ConfigError` (exit 7). |
-| `limits.max_depth` | `number` | No | `32` | Per-file parser cap on associative-array nesting depth. Protects against stack-overflow on adversarial input. Currently consumed by the Laravel PHP parser. Files exceeding this are skipped with a warning. Hard ceiling: `64`. Values above the ceiling fail at config load with `ConfigError` (exit 7). |
+| `limits.max_depth` | `number` | No | `32` | Per-file parser cap on nesting depth. Protects against stack-overflow on adversarial input. Consumed by the Laravel PHP and JSON parsers (the ones that walk their tree recursively); other formats are bounded by their own parser instead. Files exceeding this are skipped with a warning, and the rest of the run continues. Hard ceiling: `64`. Values above the ceiling fail at config load with `ConfigError` (exit 7). |
 | `limits.max_source_files` | `number` | No | `10000` | Per-bucket cap on how many source files a single `include` glob may match. Buckets exceeding this are **skipped entirely with a warning** — the assumption is that a glob which returned 10k+ files is picking up an unintended vendored tree. Narrow the `include` pattern or raise the cap. Hard ceiling: `1000000`. Values above the ceiling fail at config load with `ConfigError` (exit 7). |
 
 #### `tms`
diff --git a/src/formats/format.ts b/src/formats/format.ts
index 57504317..9490554c 100644
--- a/src/formats/format.ts
+++ b/src/formats/format.ts
@@ -33,4 +33,33 @@ export interface FormatParser {
   ): string;
   /** Optional: extract context for a specific key from file content */
   extractContext?(content: string, key: string): string | undefined;
+  /**
+   * Optional: a copy of this parser bounded to `maxDepth` levels of nesting.
+   * Parsers that walk their tree recursively implement it so `sync` can apply
+   * `sync.limits.max_depth`; the walker skips the field for parsers without it.
+   */
+  withMaxDepth?(maxDepth: number): FormatParser;
+}
+
+/**
+ * Thrown when a parser refuses a file for exceeding its nesting cap. Walkers
+ * catch this to skip the one file with a warning, rather than propagating a
+ * ValidationError (a hard reject) or letting a recursive walk exhaust the stack
+ * and take the whole run down with a bare RangeError.
+ */
+export class FormatDepthExceededError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FormatDepthExceededError';
+  }
+}
+
+/**
+ * Renders a key path for a depth-limit message. At the depth these fire, the
+ * full path is dozens of segments of no diagnostic value beyond the first few,
+ * so it is clipped rather than printed in full.
+ */
+export function describeKeyPath(keyPath: string): string {
+  if (!keyPath) return '<root>';
+  return keyPath.length > 60 ? `${keyPath.slice(0, 60)}…` : keyPath;
 }
diff --git a/src/formats/index.ts b/src/formats/index.ts
index 04063ad0..8b28e33b 100644
--- a/src/formats/index.ts
+++ b/src/formats/index.ts
@@ -77,3 +77,4 @@ export type {
   ExtractedEntry,
   TranslatedEntry,
 } from './format.js';
+export { FormatDepthExceededError } from './format.js';
diff --git a/src/formats/json.ts b/src/formats/json.ts
index 12ee25af..4890487e 100644
--- a/src/formats/json.ts
+++ b/src/formats/json.ts
@@ -1,7 +1,9 @@
-import type {
-  ExtractedEntry,
-  FormatParser,
-  TranslatedEntry,
+import {
+  FormatDepthExceededError,
+  describeKeyPath,
+  type ExtractedEntry,
+  type FormatParser,
+  type TranslatedEntry,
 } from './format.js';
 import { detectIndent } from './util/detect-indent.js';
 import { Logger } from '../utils/logger.js';
@@ -11,11 +13,43 @@ interface FlatKeyInfo {
   scopes: Map<string, number>;
 }
 
+export interface JsonParserOptions {
+  maxDepth?: number;
+}
+
+/**
+ * Stack-safety ceiling for callers with no configured limit, such as
+ * `deepl translate file.json`. It sits far above any realistic i18n file and
+ * far below the depth at which the recursive walks exhaust the stack (~2,000
+ * levels measured), so its only effect is to turn an opaque
+ * `RangeError: Maximum call stack size exceeded` into a named error. `sync`
+ * narrows it to `sync.limits.max_depth` (32 by default).
+ */
+export const DEFAULT_JSON_MAX_DEPTH = 100;
+
 export class JsonFormatParser implements FormatParser {
   readonly name = 'JSON i18n';
   readonly configKey = 'json';
   readonly extensions = ['.json'];
 
+  private readonly maxDepth: number;
+
+  constructor(options: JsonParserOptions = {}) {
+    this.maxDepth = options.maxDepth ?? DEFAULT_JSON_MAX_DEPTH;
+  }
+
+  withMaxDepth(maxDepth: number): JsonFormatParser {
+    return new JsonFormatParser({ maxDepth });
+  }
+
+  private assertDepth(depth: number, prefix: string): void {
+    if (depth > this.maxDepth) {
+      throw new FormatDepthExceededError(
+        `JSON: max nesting depth ${this.maxDepth} exceeded at '${describeKeyPath(prefix)}'.`
+      );
+    }
+  }
+
   extract(content: string): ExtractedEntry[] {
     const clean = content.replace(/^\uFEFF/, '');
     if (!clean.trim()) return [];
@@ -72,8 +106,10 @@ export class JsonFormatParser implements FormatParser {
     obj: Record<string, unknown>,
     prefix: string,
     keys: Set<string>,
-    scopes: Map<string, number>
+    scopes: Map<string, number>,
+    depth = 1
   ): void {
+    this.assertDepth(depth, prefix);
     for (const prop of Object.keys(obj)) {
       const dotPath = prefix ? `${prefix}.${prop}` : prop;
       if (prop.includes('.')) {
@@ -87,7 +123,8 @@ export class JsonFormatParser implements FormatParser {
           val as Record<string, unknown>,
           dotPath,
           keys,
-          scopes
+          scopes,
+          depth + 1
         );
       }
     }
@@ -135,21 +172,28 @@ export class JsonFormatParser implements FormatParser {
     return standard;
   }
 
-  private walk(obj: unknown, prefix: string, entries: ExtractedEntry[]): void {
+  private walk(
+    obj: unknown,
+    prefix: string,
+    entries: ExtractedEntry[],
+    depth = 1
+  ): void {
     if (Array.isArray(obj)) {
+      this.assertDepth(depth, prefix);
       for (let i = 0; i < obj.length; i++) {
         const item: unknown = obj[i];
         const key = prefix ? `${prefix}.${i}` : String(i);
         if (typeof item === 'string') {
           entries.push({ key, value: item });
         } else if (typeof item === 'object' && item !== null) {
-          this.walk(item, key, entries);
+          this.walk(item, key, entries, depth + 1);
         }
       }
       return;
     }
 
     if (typeof obj === 'object' && obj !== null) {
+      this.assertDepth(depth, prefix);
       const record = obj as Record<string, unknown>;
       for (const prop of Object.keys(record)) {
         const val: unknown = record[prop];
@@ -157,7 +201,7 @@ export class JsonFormatParser implements FormatParser {
         if (typeof val === 'string') {
           entries.push({ key, value: val });
         } else if (typeof val === 'object' && val !== null) {
-          this.walk(val, key, entries);
+          this.walk(val, key, entries, depth + 1);
         }
       }
     }
@@ -167,9 +211,11 @@ export class JsonFormatParser implements FormatParser {
     obj: unknown,
     prefix: string,
     translations: Map<string, string>,
-    flatKeyInfo: FlatKeyInfo
+    flatKeyInfo: FlatKeyInfo,
+    depth = 1
   ): void {
     if (Array.isArray(obj)) {
+      this.assertDepth(depth, prefix);
       for (let i = 0; i < obj.length; i++) {
         const key = prefix ? `${prefix}.${i}` : String(i);
         const item: unknown = obj[i];
@@ -179,13 +225,20 @@ export class JsonFormatParser implements FormatParser {
             obj[i] = translation;
           }
         } else if (typeof item === 'object' && item !== null) {
-          this.applyTranslations(item, key, translations, flatKeyInfo);
+          this.applyTranslations(
+            item,
+            key,
+            translations,
+            flatKeyInfo,
+            depth + 1
+          );
         }
       }
       return;
     }
 
     if (typeof obj === 'object' && obj !== null) {
+      this.assertDepth(depth, prefix);
       const record = obj as Record<string, unknown>;
       for (const prop of Object.keys(record)) {
         const key = prefix ? `${prefix}.${prop}` : prop;
@@ -196,7 +249,13 @@ export class JsonFormatParser implements FormatParser {
             record[prop] = translation;
           }
         } else if (typeof val === 'object' && val !== null) {
-          this.applyTranslations(val, key, translations, flatKeyInfo);
+          this.applyTranslations(
+            val,
+            key,
+            translations,
+            flatKeyInfo,
+            depth + 1
+          );
         }
       }
     }
@@ -276,9 +335,11 @@ export class JsonFormatParser implements FormatParser {
     obj: unknown,
     prefix: string,
     translations: Map<string, string>,
-    flatKeyInfo: FlatKeyInfo
+    flatKeyInfo: FlatKeyInfo,
+    depth = 1
   ): void {
     if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) return;
+    this.assertDepth(depth, prefix);
     const record = obj as Record<string, unknown>;
     for (const prop of Object.keys(record)) {
       const key = prefix ? `${prefix}.${prop}` : prop;
@@ -292,7 +353,7 @@ export class JsonFormatParser implements FormatParser {
         val !== null &&
         !Array.isArray(val)
       ) {
-        this.removeDeletedKeys(val, key, translations, flatKeyInfo);
+        this.removeDeletedKeys(val, key, translations, flatKeyInfo, depth + 1);
         if (Object.keys(val).length === 0) {
           delete record[prop];
         }
diff --git a/src/formats/php-arrays.ts b/src/formats/php-arrays.ts
index 113e69a0..e2cf9a36 100644
--- a/src/formats/php-arrays.ts
+++ b/src/formats/php-arrays.ts
@@ -1,7 +1,8 @@
-import type {
-  ExtractedEntry,
-  FormatParser,
-  TranslatedEntry,
+import {
+  FormatDepthExceededError,
+  type ExtractedEntry,
+  type FormatParser,
+  type TranslatedEntry,
 } from './format.js';
 import { ValidationError } from '../utils/errors.js';
 import { Logger } from '../utils/logger.js';
@@ -27,7 +28,7 @@ export interface PhpArraysParserOptions {
  * this specifically to convert into a file-skip + warn (vs. propagating
  * an allowlist ValidationError, which is a hard reject).
  */
-export class PhpArraysCapExceededError extends Error {
+export class PhpArraysCapExceededError extends FormatDepthExceededError {
   constructor(message: string) {
     super(message);
     this.name = 'PhpArraysCapExceededError';
@@ -120,6 +121,10 @@ export class PhpArraysFormatParser implements FormatParser {
     this.maxDepth = options.maxDepth ?? DEFAULT_PHP_MAX_DEPTH;
   }
 
+  withMaxDepth(maxDepth: number): PhpArraysFormatParser {
+    return new PhpArraysFormatParser({ maxDepth });
+  }
+
   extract(content: string, _locale?: string): ExtractedEntry[] {
     const clean = content.replace(/^\uFEFF/, '');
     if (!clean.trim()) return [];
diff --git a/src/formats/yaml.ts b/src/formats/yaml.ts
index 64810b0a..21f5e46e 100644
--- a/src/formats/yaml.ts
+++ b/src/formats/yaml.ts
@@ -1,10 +1,30 @@
 import * as YAML from 'yaml';
-import type {
-  FormatParser,
-  ExtractedEntry,
-  TranslatedEntry,
+import {
+  FormatDepthExceededError,
+  type FormatParser,
+  type ExtractedEntry,
+  type TranslatedEntry,
 } from './format.js';
 
+/**
+ * The `yaml` library builds its document tree recursively and reports a blown
+ * stack as an ordinary parse diagnostic rather than letting the RangeError
+ * escape. A deeply nested document therefore fails inside the library, before
+ * any walker of ours runs, which is why bounding our own recursion cannot
+ * prevent it. Recognising it here lets the one file be skipped like any other
+ * depth rejection instead of ending the run.
+ */
+function assertNotStackExhaustion(messages: string): void {
+  if (/maximum call stack size exceeded/i.test(messages)) {
+    // Only the first line: the library follows it with a source excerpt and a
+    // caret, which points at nesting and says nothing a reader can act on.
+    const location = messages.split('\n')[0] ?? messages;
+    throw new FormatDepthExceededError(
+      `YAML: nesting depth exhausted the stack while parsing (${location.trim()})`
+    );
+  }
+}
+
 type StringSlot =
   | { path: string[]; value: string; parent: YAML.YAMLMap; pair: YAML.Pair }
   | { path: string[]; value: string; parent: YAML.YAMLSeq; index: number };
@@ -23,6 +43,7 @@ export class YamlFormatParser implements FormatParser {
 
     if (doc.errors.length > 0) {
       const messages = doc.errors.map((e) => e.message).join('; ');
+      assertNotStackExhaustion(messages);
       throw new Error(`YAML parse error: ${messages}`);
     }
 
diff --git a/src/services/structured-file-translation.ts b/src/services/structured-file-translation.ts
index ac2bf47b..57452ba5 100644
--- a/src/services/structured-file-translation.ts
+++ b/src/services/structured-file-translation.ts
@@ -16,6 +16,15 @@ import {
   MULTI_TARGET_CONCURRENCY,
 } from '../utils/concurrency.js';
 import { ValidationError, NetworkError } from '../utils/errors.js';
+import { describeKeyPath } from '../formats/format.js';
+
+/**
+ * Stack-safety ceiling for the direct `deepl translate <file>` path, which has
+ * no `.deepl-sync.yaml` and therefore no `sync.limits.max_depth` to consult.
+ * It matches `DEFAULT_JSON_MAX_DEPTH`: far above any realistic i18n file, far
+ * below the depth at which a recursive walk exhausts the stack.
+ */
+export const MAX_STRUCTURED_DEPTH = 100;
 
 interface FileTranslationOptions {
   preserveCode?: boolean;
@@ -224,21 +233,37 @@ export class StructuredFileTranslationService {
     const strings: ExtractedString[] = [];
     let index = 0;
 
-    const walk = (value: unknown, currentPath: (string | number)[]): void => {
+    const walk = (
+      value: unknown,
+      currentPath: (string | number)[],
+      depth: number
+    ): void => {
       if (typeof value === 'string') {
         strings.push({ path: [...currentPath], value, index: index++ });
-      } else if (Array.isArray(value)) {
+        return;
+      }
+      if (depth > MAX_STRUCTURED_DEPTH) {
+        throw new ValidationError(
+          `Max nesting depth ${MAX_STRUCTURED_DEPTH} exceeded at '${describeKeyPath(currentPath.join('.'))}'. ` +
+            'Structured translation walks the document recursively, so a more deeply nested file would exhaust the stack.'
+        );
+      }
+      if (Array.isArray(value)) {
         for (let i = 0; i < value.length; i++) {
-          walk(value[i], [...currentPath, i]);
+          walk(value[i], [...currentPath, i], depth + 1);
         }
       } else if (value !== null && typeof value === 'object') {
         for (const key of Object.keys(value)) {
-          walk((value as Record<string, unknown>)[key], [...currentPath, key]);
+          walk(
+            (value as Record<string, unknown>)[key],
+            [...currentPath, key],
+            depth + 1
+          );
         }
       }
     };
 
-    walk(data, []);
+    walk(data, [], 1);
     return strings;
   }
 
diff --git a/src/sync/sync-bucket-walker.ts b/src/sync/sync-bucket-walker.ts
index 2b4d0372..f0111c81 100644
--- a/src/sync/sync-bucket-walker.ts
+++ b/src/sync/sync-bucket-walker.ts
@@ -1,21 +1,18 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import fg from 'fast-glob';
-import type {
-  ExtractedEntry,
-  FormatParser,
-  FormatRegistry,
+import {
+  FormatDepthExceededError,
+  type ExtractedEntry,
+  type FormatParser,
+  type FormatRegistry,
 } from '../formats/index.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncBucketConfig } from './types.js';
-import { resolveSyncLimits, DEFAULT_SYNC_LIMITS } from './types.js';
+import { resolveSyncLimits } from './types.js';
 import { assertPathWithinRoot } from './sync-utils.js';
 import { Logger } from '../utils/logger.js';
 import { ValidationError } from '../utils/errors.js';
-import {
-  PhpArraysFormatParser,
-  PhpArraysCapExceededError,
-} from '../formats/php-arrays.js';
 
 export interface WalkedBucketFile {
   bucket: string;
@@ -111,14 +108,13 @@ export async function* walkBuckets(
       continue;
     }
 
-    // For laravel_php, use a config-aware parser instance when the user has
-    // overridden max_depth. Other formats (which don't consume max_depth)
-    // use the registered parser as-is.
+    // Any parser that walks its tree recursively gets a copy bounded to
+    // sync.limits.max_depth; the rest are used as registered. Applying it
+    // unconditionally, rather than only when the user overrode the default,
+    // keeps the configured limit meaningful for parsers whose own default is a
+    // looser stack-safety ceiling than sync's policy.
     const parser: FormatParser =
-      registeredParser.configKey === 'laravel_php' &&
-      limits.max_depth !== DEFAULT_SYNC_LIMITS.max_depth
-        ? new PhpArraysFormatParser({ maxDepth: limits.max_depth })
-        : registeredParser;
+      registeredParser.withMaxDepth?.(limits.max_depth) ?? registeredParser;
 
     const ignorePatterns = [
       ...(bucketConfig.exclude ?? []),
@@ -180,12 +176,25 @@ export async function* walkBuckets(
             ? parser.extract(content, config.source_locale)
             : parser.extract(content);
       } catch (err) {
-        if (err instanceof PhpArraysCapExceededError) {
+        if (err instanceof FormatDepthExceededError) {
           Logger.warn(
             `Skipping ${path.relative(config.projectRoot, sourceFile)}: ${err.message}`
           );
           continue;
         }
+        // A RangeError here is a parser that recursed past the stack rather than
+        // past a cap it enforces itself — the yaml library does this on a deeply
+        // nested document, before any of our own walkers run. One hostile file
+        // must not end the run, discarding the lockfile for work already
+        // translated, billed and written.
+        if (err instanceof RangeError) {
+          Logger.warn(
+            `Skipping ${path.relative(config.projectRoot, sourceFile)}: ` +
+              `nesting depth exhausted the stack while parsing (${err.message}).`
+          );
+          continue;
+        }
+
         throw err;
       }
 
diff --git a/tests/integration/sync.integration.test.ts b/tests/integration/sync.integration.test.ts
index 68ccbf9b..32033a81 100644
--- a/tests/integration/sync.integration.test.ts
+++ b/tests/integration/sync.integration.test.ts
@@ -21,6 +21,7 @@ import { PropertiesFormatParser } from '../../src/formats/properties';
 import { AndroidXmlFormatParser } from '../../src/formats/android-xml';
 import { loadSyncConfig } from '../../src/sync/sync-config';
 import { computeSourceHash } from '../../src/sync/sync-lock';
+import { Logger } from '../../src/utils/logger';
 import { LOCK_FILE_NAME } from '../../src/sync/types';
 import { ConfigError, ValidationError } from '../../src/utils/errors';
 import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
@@ -217,6 +218,62 @@ describe('Sync Integration', () => {
       expect(translated.epsilon).toBe('XX Deleted %d files');
     });
 
+    it('should skip a file nested past the depth cap and still finish the run', async () => {
+      writeYamlConfig(
+        tmpDir,
+        `version: 1
+source_locale: en
+target_locales:
+  - de
+buckets:
+  json:
+    include:
+      - "locales/en.json"
+      - "deep/en.json"
+`
+      );
+      writeSourceFile(tmpDir, 'locales/en.json', SOURCE_JSON);
+      // 8,000 nested arrays, ~16KB: far below max_file_bytes, deep enough to
+      // exhaust the stack in a recursive walk.
+      writeSourceFile(
+        tmpDir,
+        'deep/en.json',
+        `{"a":${'['.repeat(8000)}"x"${']'.repeat(8000)}}`
+      );
+
+      const warn = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .reply(200, (_uri, body) => ({
+          translations: new URLSearchParams(String(body))
+            .getAll('text')
+            .map((text) => ({
+              text: `XX ${text}`,
+              detected_source_language: 'EN',
+            })),
+        }));
+
+      const config = await loadSyncConfig(tmpDir);
+      const result = await syncService.sync(config);
+
+      expect(result.success).toBe(true);
+      expect(
+        warn.mock.calls.some(
+          (call) =>
+            String(call[0]).includes('deep/en.json') &&
+            /nesting depth/i.test(String(call[0]))
+        )
+      ).toBe(true);
+      warn.mockRestore();
+
+      // The healthy file is translated and its work is recorded, rather than
+      // being paid for and then discarded when the run aborts.
+      expect(fs.existsSync(path.join(tmpDir, 'locales', 'de.json'))).toBe(true);
+      expect(fs.existsSync(path.join(tmpDir, 'deep', 'de.json'))).toBe(false);
+      expect(fs.existsSync(path.join(tmpDir, '.deepl-sync.lock'))).toBe(true);
+    });
+
     it('should create lock file', async () => {
       writeYamlConfig(tmpDir, BASIC_CONFIG_YAML);
       writeSourceFile(tmpDir, 'locales/en.json', SOURCE_JSON);
diff --git a/tests/unit/formats/json.test.ts b/tests/unit/formats/json.test.ts
index a302308b..2cb40e0b 100644
--- a/tests/unit/formats/json.test.ts
+++ b/tests/unit/formats/json.test.ts
@@ -1,5 +1,11 @@
-import { JsonFormatParser } from '../../../src/formats/json';
-import type { TranslatedEntry } from '../../../src/formats/format';
+import {
+  JsonFormatParser,
+  DEFAULT_JSON_MAX_DEPTH,
+} from '../../../src/formats/json';
+import {
+  FormatDepthExceededError,
+  type TranslatedEntry,
+} from '../../../src/formats/format';
 
 const parser = new JsonFormatParser();
 
@@ -679,4 +685,59 @@ describe('JsonFormatParser', () => {
       expect(parsed['outer']).not.toHaveProperty('inner');
     });
   });
+
+  describe('max depth cap', () => {
+    const nestObjects = (depth: number): string => {
+      let inner = '"x"';
+      for (let i = 0; i < depth; i++) inner = `{"k${i}":${inner}}`;
+      return inner;
+    };
+
+    it('accepts nesting up to the configured maxDepth', () => {
+      const shallow = new JsonFormatParser({ maxDepth: 3 });
+      expect(() => shallow.extract(nestObjects(3))).not.toThrow();
+    });
+
+    it('throws FormatDepthExceededError when nesting exceeds maxDepth', () => {
+      const shallow = new JsonFormatParser({ maxDepth: 3 });
+      expect(() => shallow.extract(nestObjects(4))).toThrow(
+        FormatDepthExceededError
+      );
+    });
+
+    it('counts array nesting as well as object nesting', () => {
+      const shallow = new JsonFormatParser({ maxDepth: 3 });
+      const arrays = `{"a":${'['.repeat(4)}"x"${']'.repeat(4)}}`;
+      expect(() => shallow.extract(arrays)).toThrow(FormatDepthExceededError);
+    });
+
+    it('names the key path where the limit was hit', () => {
+      const shallow = new JsonFormatParser({ maxDepth: 2 });
+      expect(() => shallow.extract('{"outer":{"inner":{"leaf":"x"}}}')).toThrow(
+        /outer\.inner/
+      );
+    });
+
+    it('guards reconstruct as well as extract', () => {
+      const shallow = new JsonFormatParser({ maxDepth: 3 });
+      expect(() => shallow.reconstruct(nestObjects(4), [])).toThrow(
+        FormatDepthExceededError
+      );
+    });
+
+    it('defaults to a ceiling that clears any realistic i18n file but not a stack overflow', () => {
+      const defaultParser = new JsonFormatParser();
+      expect(() =>
+        defaultParser.extract(nestObjects(DEFAULT_JSON_MAX_DEPTH))
+      ).not.toThrow();
+      // The point of the default: a deeply nested file fails with a named error
+      // instead of a RangeError from a blown stack.
+      expect(() =>
+        defaultParser.extract(nestObjects(DEFAULT_JSON_MAX_DEPTH + 1))
+      ).toThrow(FormatDepthExceededError);
+      expect(() => defaultParser.extract(nestObjects(8000))).toThrow(
+        FormatDepthExceededError
+      );
+    });
+  });
 });
diff --git a/tests/unit/formats/yaml.test.ts b/tests/unit/formats/yaml.test.ts
index efcd8bb7..56f8f8e7 100644
--- a/tests/unit/formats/yaml.test.ts
+++ b/tests/unit/formats/yaml.test.ts
@@ -1,6 +1,9 @@
 import { createDefaultRegistry } from '../../../src/formats/index';
 import { YamlFormatParser } from '../../../src/formats/yaml';
-import type { TranslatedEntry } from '../../../src/formats/format';
+import {
+  FormatDepthExceededError,
+  type TranslatedEntry,
+} from '../../../src/formats/format';
 
 const parser = new YamlFormatParser();
 
@@ -545,4 +548,24 @@ describe('yaml parser', () => {
       expect(entries[0]!.value).toBe('numeric key value');
     });
   });
+
+  describe('deeply nested documents', () => {
+    // The yaml library builds its tree recursively and reports a blown stack as
+    // a parse diagnostic, so this fails inside the library rather than in our
+    // walker — which is why bounding our own recursion cannot prevent it. It is
+    // classified so the sync walker can skip the one file instead of dying.
+    it('reports stack exhaustion as a depth rejection, not a bare parse error', () => {
+      const flow = `a: ${'{k: '.repeat(8000)}deep${'}'.repeat(8000)}\n`;
+
+      expect(() => parser.extract(flow)).toThrow(FormatDepthExceededError);
+      expect(() => parser.extract(flow)).toThrow(/nesting depth/i);
+    });
+
+    it('leaves an ordinary parse error unclassified', () => {
+      expect(() => parser.extract('a: [1, 2\n')).toThrow(/YAML parse error/);
+      expect(() => parser.extract('a: [1, 2\n')).not.toThrow(
+        FormatDepthExceededError
+      );
+    });
+  });
 });
diff --git a/tests/unit/structured-file-translation.test.ts b/tests/unit/structured-file-translation.test.ts
index 7633079c..750d4f29 100644
--- a/tests/unit/structured-file-translation.test.ts
+++ b/tests/unit/structured-file-translation.test.ts
@@ -805,4 +805,42 @@ describe('StructuredFileTranslationService', () => {
       ).rejects.toThrow('Aborting to prevent misaligned output');
     });
   });
+
+  describe('deeply nested input', () => {
+    it('should reject a file nested past the depth ceiling with a named error', async () => {
+      const inputPath = path.join(testDir, 'deep.json');
+      const outputPath = path.join(testDir, 'deep-es.json');
+
+      // 8,000 nested arrays, ~16KB — well under any size limit, but enough to
+      // exhaust the stack in a recursive walk.
+      fs.writeFileSync(
+        inputPath,
+        `{"a":${'['.repeat(8000)}"x"${']'.repeat(8000)}}`
+      );
+
+      await expect(
+        service.translateFile(inputPath, outputPath, { targetLang: 'es' })
+      ).rejects.toThrow(/nesting depth/i);
+
+      expect(mockTranslationService.translateBatch).not.toHaveBeenCalled();
+      expect(fs.existsSync(outputPath)).toBe(false);
+    });
+
+    it('should still translate a file nested well within the ceiling', async () => {
+      const inputPath = path.join(testDir, 'ok-deep.json');
+      const outputPath = path.join(testDir, 'ok-deep-es.json');
+
+      let inner = '"Hello"';
+      for (let i = 0; i < 20; i++) inner = `{"k${i}":${inner}}`;
+      fs.writeFileSync(inputPath, inner);
+
+      mockTranslationService.translateBatch.mockResolvedValue([
+        { text: 'Hola', detectedSourceLang: 'en' },
+      ]);
+
+      await service.translateFile(inputPath, outputPath, { targetLang: 'es' });
+
+      expect(fs.readFileSync(outputPath, 'utf-8')).toContain('Hola');
+    });
+  });
 });

From 4fddedca52e148431974dee44ca38c6931348c71 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 22:28:44 +0200
Subject: [PATCH 123/256] test(sync): guard the php-parser stack-overflow skip
 against regression
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

php-parser has no recursion guard and throws from inside parseCode, before
php-arrays' own max_depth guard, which walks the AST only once a parse has
succeeded. A 100KB lang file of deeply nested parentheses — well under
max_file_bytes — therefore reached the walker as a bare RangeError and was
rethrown, ending the run with 'Error: Maximum call stack size exceeded' at
exit 1.

The behaviour fix landed with the JSON/YAML depth work in b9ab98a, whose
per-file RangeError backstop covers this case; verified by removing that
handler and rebuilding, which reproduces exit 1, against exit 0 and
'Skipping lang/en.php: nesting depth exhausted the stack while parsing (…)'
with it in place. That arm had no test of its own, since JSON and YAML both
reach the walker as a classified FormatDepthExceededError instead, so this
adds the case that actually exercises it and asserts the rest of the corpus
still walks.

The comment on that arm named the yaml library as its example, which is now
wrong: yaml is classified at the parser. It names php-parser instead.

Refs: cli-8kr2.21

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 ++
 src/sync/sync-bucket-walker.ts                |  9 ++++----
 .../sync-php-arrays.integration.test.ts       | 23 +++++++++++++++++++
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1d7d6931..f34e7b19 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a Laravel PHP lang file that overflows `php-parser` is skipped with a warning instead of ending the run.** `php-parser` has no recursion guard, and it throws from inside `parseCode` — before `php-arrays`' own `max_depth` guard, which only walks the AST once a parse has succeeded — so a 100KB file of deeply nested parentheses, well under `max_file_bytes`, arrived at the walker as a bare `RangeError` and was rethrown: `Error: Maximum call stack size exceeded`, exit 1. Verified before and after by removing the new handler and rebuilding: exit 1 with that message, versus exit 0 and `Skipping lang/en.php: nesting depth exhausted the stack while parsing (…)` with it. Covered by the same per-file boundary added for the JSON/YAML depth work below, so any parser that lets a `RangeError` escape now costs one file rather than the run.
+
 - **sync, translate**: **a deeply nested JSON or YAML file no longer ends the whole run with `Error: Maximum call stack size exceeded`.** The JSON and YAML walkers recurse once per nesting level with no depth guard, so a 16KB file of 8,000 nested arrays — far below the 4 MiB `sync.limits.max_file_bytes` default, so the pre-read size check never sees it — killed `deepl sync`, `deepl sync validate` and `deepl translate <file>` alike. In a sync it was worse than a crash: a healthy file earlier in the bucket had already been translated, billed and written, and because the run died before the lockfile was written that work was unrecorded, so the next run paid for it again. `sync.limits.max_depth` (default 32, ceiling 64) existed for exactly this and was wired only to the Laravel PHP parser, which `sync-bucket-walker.ts` documented in a comment rather than fixing. Three changes: `JsonFormatParser` takes a `maxDepth` and rejects past it with a catchable error naming the key path; the walker now applies `sync.limits.max_depth` to **any** parser that accepts one — via a new optional `withMaxDepth` on `FormatParser`, so a future recursive parser opts in rather than needing a new special case — and always, rather than only when the user overrode the default; and one file exceeding the cap is skipped with a warning while the run finishes and records what it did. Verified end to end: a bucket holding one healthy and one 8,000-deep file now completes at exit 0, writes the healthy target, writes the lockfile, and prints `Skipping deep/en.json: JSON: max nesting depth 32 exceeded at 'a.0.0.0…'`. **YAML is bounded differently, because bounding our own recursion could not have helped it:** the `yaml` library builds its tree recursively and reports the blown stack as a parse diagnostic, so it fails inside the library before any walker of ours runs — measured in both flow and block style. That diagnostic is now recognised as a depth rejection and skipped like any other, and a `RangeError` escaping any parser is caught at the same boundary as a backstop. The direct `deepl translate <file>` path has no `.deepl-sync.yaml` and so no configured limit; it gets a fixed ceiling of 100 levels, which clears any realistic i18n file by a wide margin and sits far below the ~2,000 levels at which the stack actually gives out, so its only effect is to turn an opaque stack overflow into a named error.
 
 - **sync**: **two keys whose placeholders protect to the same text no longer receive each other's variables.** `preserveVariables` replaces every variable with a positional token, so `Hello {name}` and `Hello {user}` both become `Hello __VAR_0__` — one text on the wire, and `TranslationService.translateBatch` deduplicates them, which is the point. It then assigned the *same* result object to every index the duplicate covered, and the restore loop in `sync-locale-translator.ts` edited `result.text` **in place**: the first key's restore consumed the token, so the second key found none left and was written with the first key's variable. `{alpha: 'Hello {name}', beta: 'Hello {user}'}` produced `beta: 'XX Hello {name}'`, and the far more common `%s`/`%d` pair — `{delta: 'Deleted %s files', epsilon: 'Deleted %d files'}` — produced `epsilon: 'XX Deleted %s files'`, a format specifier that no longer matches its argument. This needed no hostile input, only two strings that differ solely in their variable. The run reported `5/5 keys` at exit 0, the lockfile recorded the affected key as `translated`, and the next sync reported it `current`, so the corruption was permanent. `translateBatch` now gives each index its own copy of the result — the array is typed as one result per index, and no caller can alias two logical results any more — and both restore loops replace their entry instead of editing it. Verified end to end: every key gets its own placeholder back, and the two validation errors and two warnings the run previously emitted (advisory, exit 0, details not printed) are gone, since they were reporting exactly this. `deepl translate` was never affected; its single-text path already returned a new string.
diff --git a/src/sync/sync-bucket-walker.ts b/src/sync/sync-bucket-walker.ts
index f0111c81..1038b2bf 100644
--- a/src/sync/sync-bucket-walker.ts
+++ b/src/sync/sync-bucket-walker.ts
@@ -183,10 +183,11 @@ export async function* walkBuckets(
           continue;
         }
         // A RangeError here is a parser that recursed past the stack rather than
-        // past a cap it enforces itself — the yaml library does this on a deeply
-        // nested document, before any of our own walkers run. One hostile file
-        // must not end the run, discarding the lockfile for work already
-        // translated, billed and written.
+        // past a cap it enforces itself. php-parser does this on deeply nested
+        // parentheses, from inside parseCode — before php-arrays' own max_depth
+        // guard, which walks the AST only once a parse has succeeded. One
+        // hostile file must not end the run, discarding the lockfile for work
+        // already translated, billed and written.
         if (err instanceof RangeError) {
           Logger.warn(
             `Skipping ${path.relative(config.projectRoot, sourceFile)}: ` +
diff --git a/tests/integration/sync-php-arrays.integration.test.ts b/tests/integration/sync-php-arrays.integration.test.ts
index d08b6db2..7d341fff 100644
--- a/tests/integration/sync-php-arrays.integration.test.ts
+++ b/tests/integration/sync-php-arrays.integration.test.ts
@@ -146,6 +146,29 @@ describe('sync-php-arrays corpus integration', () => {
     expect(result.some((w) => w.sourceFile === bigPath)).toBe(false);
   });
 
+  it('skips a file that overflows php-parser instead of ending the walk', async () => {
+    // php-parser has no recursion guard of its own, and it throws from inside
+    // parseCode — before php-arrays' own max_depth guard, which walks the AST
+    // only after a successful parse. So this arrives as a bare RangeError, not
+    // as a PhpArraysCapExceededError.
+    const overflowPath = path.join(projectRoot, 'overflow.php');
+    const nesting = 50_000;
+    fs.writeFileSync(
+      overflowPath,
+      `<?php return ['a' => ${'('.repeat(nesting)}'x'${')'.repeat(nesting)}];`,
+      'utf-8'
+    );
+
+    const config = makeConfig(projectRoot);
+    const result = await collect(walkBuckets(config, makeRegistry()));
+
+    expect(result.some((w) => w.sourceFile === overflowPath)).toBe(false);
+    // The rest of the corpus still walks: one hostile file must not end the run.
+    expect(result.length).toBeGreaterThan(0);
+
+    fs.unlinkSync(overflowPath);
+  });
+
   it('instantiates laravel_php with an override max_depth when sync.limits.max_depth is set', async () => {
     // Shallow cap forces all fixtures that have ≥2 levels of nesting
     // (06, 08, 09, 10, 15) to be skipped via PhpArraysCapExceededError.

From 1a99187a3abd91f9ea8af8e8cb18b0ad2f93a6cc Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 22:46:34 +0200
Subject: [PATCH 124/256] fix(sync): restore overwritten targets on interrupt
 instead of deleting backups
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The SIGINT/SIGTERM handler ran the same cleanup as a successful run — unlink
every .deepl.bak taken this run. That is right for a run that finished and
catastrophic for one that did not: the backup was the only remaining copy of
content the run had already overwritten.

Reproduced with a delaying endpoint and two locales. At the moment of the
interrupt locales/de.json held machine output and locales/de.json.deepl.bak
held the human translations. After kill -INT the backup was gone, the
machine output stayed, and no lockfile had been written — it is written once
at the end of the walk — so the human translations were unrecoverable and
the de translation was billed but unrecorded, at exit 130.

Each backup is now copied back over its target before being removed, in that
order, so an interrupt during the restore leaves the backup rather than
nothing. The run says what it undid:

  Interrupted — restored 1 file(s) from backup: locales/de.json. No lockfile
  was written, so nothing was recorded; re-run to translate again.

Restoring rather than merely leaving the .bak in place is deliberate: the
startup sweep retires backups on age, so "leave it and print the path" would
have given the user a five-minute recovery window. Restoring returns the
tree to its pre-run state, which is what interrupting a tool that rewrites
tracked files should mean.

The handler stays synchronous because installSignalExit defers the exit by
one setImmediate, so only work done synchronously in a handler is guaranteed
to finish. A successful run is unaffected — it unlinks from its own path in
runSync. sync --watch is unaffected: it owns its backup tracker and cleanup,
and the restore is gated on the same !isOuterWatchRun condition as before.

Verified end to end: locales/de.json is byte-identical to its pre-run
content after the interrupt.

Refs: cli-8kr2.13

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +
 src/sync/sync-service.ts                      |  38 +++-
 .../sync-interrupt.integration.test.ts        | 168 ++++++++++++++++++
 3 files changed, 204 insertions(+), 4 deletions(-)
 create mode 100644 tests/integration/sync-interrupt.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f34e7b19..74179d78 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **Ctrl-C during a sync now restores the files it had already overwritten, instead of deleting their backups.** The signal handler ran the same cleanup as a successful run — unlink every `.deepl.bak` taken this run — which is right for a run that finished and catastrophic for one that did not: the backup was the only remaining copy of content the run had already replaced. Reproduced with a delaying endpoint and two locales: at the moment of the interrupt `locales/de.json` held machine output and `locales/de.json.deepl.bak` held the human translations; after `kill -INT` the backup was gone, the machine output stayed, and no lockfile had been written (it is written once at the end), so the human translations were unrecoverable and unrecorded at exit 130. Each backup is now copied back over its target before being removed — that order, so an interrupt during the restore leaves the backup rather than nothing — and the run reports what it undid: `Interrupted — restored 1 file(s) from backup: locales/de.json. No lockfile was written, so nothing was recorded; re-run to translate again.` Verified end to end: `locales/de.json` is byte-identical to its pre-run content. The restore is synchronous because `installSignalExit` defers the exit by one `setImmediate`, so only synchronous handler work is guaranteed to finish. A successful run is unaffected — it still unlinks, from its own path. `sync --watch` is unchanged: it owns its own backup tracker and cleanup.
+
 - **sync**: **a Laravel PHP lang file that overflows `php-parser` is skipped with a warning instead of ending the run.** `php-parser` has no recursion guard, and it throws from inside `parseCode` — before `php-arrays`' own `max_depth` guard, which only walks the AST once a parse has succeeded — so a 100KB file of deeply nested parentheses, well under `max_file_bytes`, arrived at the walker as a bare `RangeError` and was rethrown: `Error: Maximum call stack size exceeded`, exit 1. Verified before and after by removing the new handler and rebuilding: exit 1 with that message, versus exit 0 and `Skipping lang/en.php: nesting depth exhausted the stack while parsing (…)` with it. Covered by the same per-file boundary added for the JSON/YAML depth work below, so any parser that lets a `RangeError` escape now costs one file rather than the run.
 
 - **sync, translate**: **a deeply nested JSON or YAML file no longer ends the whole run with `Error: Maximum call stack size exceeded`.** The JSON and YAML walkers recurse once per nesting level with no depth guard, so a 16KB file of 8,000 nested arrays — far below the 4 MiB `sync.limits.max_file_bytes` default, so the pre-read size check never sees it — killed `deepl sync`, `deepl sync validate` and `deepl translate <file>` alike. In a sync it was worse than a crash: a healthy file earlier in the bucket had already been translated, billed and written, and because the run died before the lockfile was written that work was unrecorded, so the next run paid for it again. `sync.limits.max_depth` (default 32, ceiling 64) existed for exactly this and was wired only to the Laravel PHP parser, which `sync-bucket-walker.ts` documented in a comment rather than fixing. Three changes: `JsonFormatParser` takes a `maxDepth` and rejects past it with a catchable error naming the key path; the walker now applies `sync.limits.max_depth` to **any** parser that accepts one — via a new optional `withMaxDepth` on `FormatParser`, so a future recursive parser opts in rather than needing a new special case — and always, rather than only when the user overrode the default; and one file exceeding the cap is skipped with a warning while the run finishes and records what it did. Verified end to end: a bucket holding one healthy and one 8,000-deep file now completes at exit 0, writes the healthy target, writes the lockfile, and prints `Skipping deep/en.json: JSON: max nesting depth 32 exceeded at 'a.0.0.0…'`. **YAML is bounded differently, because bounding our own recursion could not have helped it:** the `yaml` library builds its tree recursively and reports the blown stack as a parse diagnostic, so it fails inside the library before any walker of ours runs — measured in both flow and block style. That diagnostic is now recognised as a depth rejection and skipped like any other, and a `RangeError` escaping any parser is caught at the same boundary as a backstop. The direct `deepl translate <file>` path has no `.deepl-sync.yaml` and so no configured limit; it gets a fixed ceiling of 100 levels, which clears any realistic i18n file by a wide margin and sits far below the ~2,000 levels at which the stack actually gives out, so its only effect is to turn an opaque stack overflow into a named error.
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index 7ed713f5..3573e6f3 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -6,7 +6,11 @@ import type { GlossaryService } from '../services/glossary.js';
 import type { FormatRegistry } from '../formats/index.js';
 import { SyncLockManager } from './sync-lock.js';
 import { acquireSyncProcessLock } from './sync-process-lock.js';
-import { sweepStaleBackups, resolveBakSweepAgeMs } from './sync-bak-cleanup.js';
+import {
+  sweepStaleBackups,
+  resolveBakSweepAgeMs,
+  BACKUP_SUFFIX,
+} from './sync-bak-cleanup.js';
 import { ValidationError } from '../utils/errors.js';
 import { walkBuckets } from './sync-bucket-walker.js';
 import type { BucketFileCache } from './sync-bucket-walker.js';
@@ -135,19 +139,45 @@ export class SyncService {
     const isOuterWatchRun = options?.backupTracker !== undefined;
     const runBackupPaths = options?.backupTracker ?? new Set<string>();
 
-    const cleanupBackups = (): void => {
+    /**
+     * Undo the writes this run has already made. Reached only from the signal
+     * path, where the run is abandoned partway through: the lockfile is written
+     * once at the end, so an interrupted run records nothing, and the targets it
+     * has rewritten hold machine output that nothing accounts for.
+     *
+     * This used to unlink the backups instead, which is right for a run that
+     * finished and wrong for one that did not — it deleted the only remaining
+     * copy of content the run had already overwritten, at which point the user's
+     * translations were gone with no record and no recovery path.
+     *
+     * Synchronous on purpose: `installSignalExit` defers the exit by one
+     * `setImmediate`, so only work done synchronously in a handler is guaranteed
+     * to complete. Each file is copied back before its backup is removed, so an
+     * interrupt during the restore leaves the backup rather than nothing.
+     */
+    const restoreBackups = (): void => {
+      const restored: string[] = [];
       for (const bakPath of runBackupPaths) {
+        const targetPath = bakPath.slice(0, -BACKUP_SUFFIX.length);
         try {
+          fs.copyFileSync(bakPath, targetPath);
           fs.unlinkSync(bakPath);
+          restored.push(path.relative(config.projectRoot, targetPath));
         } catch {
-          /* ignore — already gone or never landed */
+          /* Leave the backup in place: it may be the only copy left. */
         }
       }
       runBackupPaths.clear();
+      if (restored.length > 0) {
+        Logger.warn(
+          `Interrupted — restored ${restored.length} file(s) from backup: ${restored.join(', ')}. ` +
+            'No lockfile was written, so nothing was recorded; re-run to translate again.'
+        );
+      }
     };
 
     const onSignal = (): void => {
-      if (!isOuterWatchRun) cleanupBackups();
+      if (!isOuterWatchRun) restoreBackups();
       processLock.release();
     };
     process.once('SIGINT', onSignal);
diff --git a/tests/integration/sync-interrupt.integration.test.ts b/tests/integration/sync-interrupt.integration.test.ts
new file mode 100644
index 00000000..d3f0f8aa
--- /dev/null
+++ b/tests/integration/sync-interrupt.integration.test.ts
@@ -0,0 +1,168 @@
+/**
+ * Integration tests for what a sync leaves behind when it does not finish:
+ * an interrupted run (SIGINT/SIGTERM, where the handler gets to act) and a
+ * recovery run after a crash (SIGKILL, where nothing got to act and the
+ * previous run's `.deepl.bak` is the only surviving copy of the user's file).
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import nock from 'nock';
+import { SyncService } from '../../src/sync/sync-service';
+import { TranslationService } from '../../src/services/translation';
+import { GlossaryService } from '../../src/services/glossary';
+import { DeepLClient } from '../../src/api/deepl-client';
+import { FormatRegistry } from '../../src/formats/index';
+import { JsonFormatParser } from '../../src/formats/json';
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { BACKUP_SUFFIX } from '../../src/sync/sync-bak-cleanup';
+import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
+
+const CONFIG_YAML = `version: 1
+source_locale: en
+target_locales:
+  - de
+  - fr
+sync:
+  concurrency: 1
+buckets:
+  json:
+    include:
+      - "locales/en.json"
+`;
+
+const SOURCE = JSON.stringify({ a: 'Alpha', b: 'Beta' }, null, 2) + '\n';
+const HUMAN_DE =
+  JSON.stringify({ a: 'HUMAN-DE-Alpha', b: 'HUMAN-DE-Beta' }, null, 2) + '\n';
+const HUMAN_FR =
+  JSON.stringify({ a: 'HUMAN-FR-Alpha', b: 'HUMAN-FR-Beta' }, null, 2) + '\n';
+
+function createServices(): { client: DeepLClient; syncService: SyncService } {
+  const client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
+  const mockConfig = createMockConfigService({
+    get: jest.fn(() => ({
+      auth: {},
+      api: { baseUrl: '', usePro: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
+      cache: { enabled: false },
+      output: { format: 'text', color: false },
+      proxy: {},
+    })),
+    getValue: jest.fn(() => false),
+  });
+  const translationService = new TranslationService(
+    client,
+    mockConfig,
+    createMockCacheService()
+  );
+  const registry = new FormatRegistry();
+  registry.register(new JsonFormatParser());
+  const syncService = new SyncService(
+    translationService,
+    new GlossaryService(client),
+    registry
+  );
+  return { client, syncService };
+}
+
+function replyWithMachineTranslations(body: unknown): {
+  translations: Array<{ text: string; detected_source_language: string }>;
+} {
+  const params = new URLSearchParams(String(body));
+  return {
+    translations: params.getAll('text').map((text) => ({
+      text: `MT ${text}`,
+      detected_source_language: 'EN',
+    })),
+  };
+}
+
+async function waitFor(
+  predicate: () => boolean,
+  timeoutMs = 5000
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) {
+      throw new Error('timed out waiting for condition');
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+}
+
+describe('sync interruption and crash recovery', () => {
+  let tmpDir: string;
+  let client: DeepLClient;
+  let syncService: SyncService;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-interrupt-'));
+    const services = createServices();
+    client = services.client;
+    syncService = services.syncService;
+
+    fs.mkdirSync(path.join(tmpDir, 'locales'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.deepl-sync.yaml'), CONFIG_YAML);
+    fs.writeFileSync(path.join(tmpDir, 'locales', 'en.json'), SOURCE);
+    fs.writeFileSync(path.join(tmpDir, 'locales', 'de.json'), HUMAN_DE);
+    fs.writeFileSync(path.join(tmpDir, 'locales', 'fr.json'), HUMAN_FR);
+  });
+
+  afterEach(() => {
+    client.destroy();
+    nock.cleanAll();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  const dePath = (): string => path.join(tmpDir, 'locales', 'de.json');
+  const deBakPath = (): string => dePath() + BACKUP_SUFFIX;
+
+  it('restores an overwritten target on SIGINT instead of deleting its backup', async () => {
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => replyWithMachineTranslations(body));
+    // The second locale is held until the assertions are done, so the run is
+    // still in flight when the signal arrives — the only moment at which the
+    // handler matters.
+    let releaseSecondLocale = (): void => {};
+    const secondLocale = new Promise<void>((resolve) => {
+      releaseSecondLocale = resolve;
+    });
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .reply(200, async (_uri, body) => {
+        await secondLocale;
+        return replyWithMachineTranslations(body);
+      });
+
+    const config = await loadSyncConfig(tmpDir);
+    // In production the process exits on the signal; here the run is left to
+    // settle after the assertions so the suite does not outlive it.
+    const running = syncService.sync(config).catch(() => undefined);
+
+    await waitFor(
+      () =>
+        fs.existsSync(deBakPath()) &&
+        fs.readFileSync(dePath(), 'utf-8') !== HUMAN_DE
+    );
+
+    process.emit('SIGINT');
+
+    expect(fs.readFileSync(dePath(), 'utf-8')).toBe(HUMAN_DE);
+    expect(fs.existsSync(deBakPath())).toBe(false);
+
+    releaseSecondLocale();
+    await running;
+  });
+});

From e3aea515846585b399b5a91630abd5f67cf0a7f3 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Thu, 6 Aug 2026 22:51:31 +0200
Subject: [PATCH 125/256] fix(sync): never overwrite a backup left by a run
 that did not finish
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After a kill -9 mid-sync the lockfile was never written and
locales/de.json.deepl.bak held the ONLY surviving copy of the user's file.
The natural recovery action — re-running deepl sync — destroyed it. The
"already backed up this run" guard is a per-process Set, so a fresh run saw
no reason not to copy the machine-translated target over the existing
backup, and the success path then unlinked it.

Reproduced end to end: after the recovery run the human content was gone at
exit 0, and the translations run 1 had already completed were re-billed.

The copy now passes COPYFILE_EXCL. On EEXIST the existing backup is left
alone with a warning naming it, and deliberately NOT tracked as this run's,
so the success path does not unlink it either. The stale-backup sweep still
retires it on age. A run with no pre-existing backup is unchanged: back up,
write, unlink on success.

Two fs mocks had to gain `constants`, taken from the real module rather than
hand-written: without it `fs.constants.COPYFILE_EXCL` threw before copyFile
was ever called, which is a mock that no longer describes the module under
test rather than a behaviour change. Two assertions that pinned the exact
two-argument call now assert the flag as well.

Not addressed, and worth its own bead: the startup sweep still retires any
.deepl.bak older than bak_sweep_max_age_seconds (default 300), so a user who
recovers more than five minutes after a crash can still lose the backup to
the sweep before this guard ever runs. That is the backup retention policy,
not the clobber bug.

Refs: cli-8kr2.14

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 ++
 src/sync/sync-locale-translator.ts            | 28 +++++++++++++---
 .../sync-interrupt.integration.test.ts        | 33 +++++++++++++++++++
 .../unit/sync/sync-locale-translator.test.ts  |  3 ++
 tests/unit/sync/sync-service.test.ts          | 11 +++++--
 5 files changed, 71 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 74179d78..882dacfc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a backup left behind by a crashed run is no longer overwritten by the run you start to recover from it.** After a `kill -9` mid-sync the lockfile was never written and `locales/de.json.deepl.bak` held the only surviving copy of the user's file — and the natural recovery action, re-running `deepl sync`, destroyed it: the "already backed up" guard is a per-process `Set`, so the run copied the machine-translated target over the existing backup and then unlinked it on success. Reproduced end to end: after the recovery run the human content was gone at exit 0, and the already-completed translations were re-billed. The copy now uses `COPYFILE_EXCL`, and on `EEXIST` the existing backup is left alone with a warning naming it — and deliberately not tracked as this run's, so the success path does not unlink it either. The stale-backup sweep still retires it on age. A run with no pre-existing backup behaves exactly as before: back up, write, unlink on success.
+
 - **sync**: **Ctrl-C during a sync now restores the files it had already overwritten, instead of deleting their backups.** The signal handler ran the same cleanup as a successful run — unlink every `.deepl.bak` taken this run — which is right for a run that finished and catastrophic for one that did not: the backup was the only remaining copy of content the run had already replaced. Reproduced with a delaying endpoint and two locales: at the moment of the interrupt `locales/de.json` held machine output and `locales/de.json.deepl.bak` held the human translations; after `kill -INT` the backup was gone, the machine output stayed, and no lockfile had been written (it is written once at the end), so the human translations were unrecoverable and unrecorded at exit 130. Each backup is now copied back over its target before being removed — that order, so an interrupt during the restore leaves the backup rather than nothing — and the run reports what it undid: `Interrupted — restored 1 file(s) from backup: locales/de.json. No lockfile was written, so nothing was recorded; re-run to translate again.` Verified end to end: `locales/de.json` is byte-identical to its pre-run content. The restore is synchronous because `installSignalExit` defers the exit by one `setImmediate`, so only synchronous handler work is guaranteed to finish. A successful run is unaffected — it still unlinks, from its own path. `sync --watch` is unchanged: it owns its own backup tracker and cleanup.
 
 - **sync**: **a Laravel PHP lang file that overflows `php-parser` is skipped with a warning instead of ending the run.** `php-parser` has no recursion guard, and it throws from inside `parseCode` — before `php-arrays`' own `max_depth` guard, which only walks the AST once a parse has succeeded — so a 100KB file of deeply nested parentheses, well under `max_file_bytes`, arrived at the walker as a bare `RangeError` and was rethrown: `Error: Maximum call stack size exceeded`, exit 1. Verified before and after by removing the new handler and rebuilding: exit 1 with that message, versus exit 0 and `Skipping lang/en.php: nesting depth exhausted the stack while parsing (…)` with it. Covered by the same per-file boundary added for the JSON/YAML depth work below, so any parser that lets a `RangeError` escape now costs one file rather than the run.
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index f6ab23ac..54b17e0a 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -714,12 +714,32 @@ export class LocaleTranslator {
     ) {
       const bakPath = targetAbsPath + BACKUP_SUFFIX;
       try {
-        await fs.promises.copyFile(targetAbsPath, bakPath);
+        // COPYFILE_EXCL, because a backup already on disk is not ours to
+        // replace. The guard above is per-process, so after a crash — where the
+        // lockfile was never written and the backup holds the only surviving
+        // copy of the user's file — the natural recovery action of re-running
+        // sync used to overwrite that copy with machine output and then unlink
+        // it on success, destroying the data at exit 0.
+        await fs.promises.copyFile(
+          targetAbsPath,
+          bakPath,
+          fs.constants.COPYFILE_EXCL
+        );
         this.backupPaths.add(bakPath);
       } catch (err) {
-        Logger.warn(
-          `Failed to backup ${targetRelPath}: ${err instanceof Error ? err.message : String(err)}`
-        );
+        if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+          // Deliberately not tracked, so this run's success path does not
+          // unlink it either. The stale-backup sweep retires it on age.
+          Logger.warn(
+            `Keeping the existing backup ${targetRelPath}${BACKUP_SUFFIX} rather than replacing it: ` +
+              'it is from an earlier run that did not finish and may hold content this run is about to overwrite. ' +
+              `Move it aside to let ${targetRelPath} be backed up again.`
+          );
+        } else {
+          Logger.warn(
+            `Failed to backup ${targetRelPath}: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
       }
     }
 
diff --git a/tests/integration/sync-interrupt.integration.test.ts b/tests/integration/sync-interrupt.integration.test.ts
index d3f0f8aa..106e2cd3 100644
--- a/tests/integration/sync-interrupt.integration.test.ts
+++ b/tests/integration/sync-interrupt.integration.test.ts
@@ -165,4 +165,37 @@ describe('sync interruption and crash recovery', () => {
     releaseSecondLocale();
     await running;
   });
+  it('leaves a backup from an earlier crashed run untouched', async () => {
+    // What a `kill -9` mid-sync leaves behind: the target already machine
+    // translated, and the only copy of the human file in the .bak sibling.
+    fs.writeFileSync(dePath(), JSON.stringify({ a: 'MT Alpha' }, null, 2));
+    fs.writeFileSync(deBakPath(), HUMAN_DE);
+
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .times(2)
+      .reply(200, (_uri, body) => replyWithMachineTranslations(body));
+
+    const config = await loadSyncConfig(tmpDir);
+    const result = await syncService.sync(config);
+
+    expect(result.success).toBe(true);
+    // Neither clobbered by this run's copyFile nor unlinked by its success path.
+    expect(fs.existsSync(deBakPath())).toBe(true);
+    expect(fs.readFileSync(deBakPath(), 'utf-8')).toBe(HUMAN_DE);
+  });
+
+  it('still backs up and cleans up normally when no stale backup exists', async () => {
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .times(2)
+      .reply(200, (_uri, body) => replyWithMachineTranslations(body));
+
+    const config = await loadSyncConfig(tmpDir);
+    const result = await syncService.sync(config);
+
+    expect(result.success).toBe(true);
+    expect(fs.readFileSync(dePath(), 'utf-8')).toContain('MT Alpha');
+    expect(fs.existsSync(deBakPath())).toBe(false);
+  });
 });
diff --git a/tests/unit/sync/sync-locale-translator.test.ts b/tests/unit/sync/sync-locale-translator.test.ts
index 6e2344b9..9769e07d 100644
--- a/tests/unit/sync/sync-locale-translator.test.ts
+++ b/tests/unit/sync/sync-locale-translator.test.ts
@@ -13,6 +13,9 @@ jest.mock('fs', () => ({
     mkdir: jest.fn(),
     copyFile: jest.fn(),
   },
+  // Real values: the backup copy passes COPYFILE_EXCL, so a mock without
+  // `constants` makes the call throw before it is ever made.
+  constants: jest.requireActual<typeof import('fs')>('fs').constants,
 }));
 
 jest.mock('../../../src/utils/atomic-write', () => ({
diff --git a/tests/unit/sync/sync-service.test.ts b/tests/unit/sync/sync-service.test.ts
index 24beac34..991cd282 100644
--- a/tests/unit/sync/sync-service.test.ts
+++ b/tests/unit/sync/sync-service.test.ts
@@ -31,6 +31,11 @@ jest.mock('fs', () => ({
     copyFile: jest.fn().mockResolvedValue(undefined),
     unlink: jest.fn().mockResolvedValue(undefined),
   },
+  copyFileSync: jest.fn(),
+  unlinkSync: jest.fn(),
+  // Real values: the backup copy passes COPYFILE_EXCL, so a mock without
+  // `constants` makes the call throw before it is ever made.
+  constants: jest.requireActual<typeof import('fs')>('fs').constants,
 }));
 
 jest.mock('../../../src/sync/sync-process-lock', () => ({
@@ -426,7 +431,8 @@ describe('SyncService', () => {
 
       expect(mockCopyFile).toHaveBeenCalledWith(
         '/test/locales/de.json',
-        '/test/locales/de.json.deepl.bak'
+        '/test/locales/de.json.deepl.bak',
+        fs.constants.COPYFILE_EXCL
       );
       expect(mockUnlink).toHaveBeenCalledWith(
         '/test/locales/de.json.deepl.bak'
@@ -660,7 +666,8 @@ describe('SyncService', () => {
       expect(mockCopyFile).toHaveBeenCalledTimes(1);
       expect(mockCopyFile).toHaveBeenCalledWith(
         '/test/Localizable.xcstrings',
-        '/test/Localizable.xcstrings.deepl.bak'
+        '/test/Localizable.xcstrings.deepl.bak',
+        fs.constants.COPYFILE_EXCL
       );
     });
 

From a997c644ab263e48c58634c2a2bc847574a762bb Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 10:30:34 +0200
Subject: [PATCH 126/256] fix(sync): fail the run on any failed key, not only a
 locale that failed entirely
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A locale counted as failed only when it translated nothing, so 10 keys
succeeding and 50 failing was not a failed locale: ok:true, exit 0, and the
50 failed keys missing from the target file. The comment above the check
already cited the documented exit-12 contract that the code did not
implement. --auto-commit is gated on result.success, so the truncated locale
file was committed too.

Any failure count above zero now fails the run. A locale that translated
nothing and failed nothing is still a success, since that is a locale already
up to date. docs/API.md's exit-code table said "at least one failed locale"
and now says "at least one failed key", matching the prose two sections down
that already defined 12 as a mixed result.

The progress stream lied about the same runs: all five key-translated
emission sites fired after dispatching a batch and before inspecting any
result, so a run where every key failed still printed translated: 60 of 60.
Each site now emits only for a key whose translateBatch slot came back
non-empty, counting successes rather than loop position.

Refs cli-8kr2.10

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  4 +++
 docs/API.md                                   |  4 +--
 src/sync/sync-finalize.ts                     | 15 ++++-----
 src/sync/sync-locale-translator.ts            | 32 ++++++++++++-------
 tests/unit/sync/sync-finalize-failure.test.ts | 10 +++---
 tests/unit/sync/sync-service.test.ts          | 29 ++++++++++++++++-
 6 files changed, 66 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 882dacfc..8ea0a964 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a run that lost most of its strings no longer exits 0.** A locale counted as failed only when it translated *nothing* (`fr.translated === 0 && fr.failed > 0`), so 10 keys succeeding and 50 failing was not a failed locale: `{"ok": true, "translated": 10, "failed": 50}` at exit 0, with the 50 failed keys absent from `locales/de.json` entirely. The comment directly above the check already cited the documented contract for exit 12 and the code did not implement it. Any failure count above zero now fails the run, so `deepl sync` exits 12 and `--auto-commit` — gated on `result.success` — no longer commits a truncated locale file. A locale that translated nothing *and* failed nothing is still a success: that is a locale which is already up to date. **CI impact**: a pipeline that previously went green on a partially failed sync now sees exit 12, which is the point; branch on `$? -eq 12` and re-run with `--locale` per the retry model in `docs/API.md`. The exit-code table there described 12 as "at least one failed locale" and now says "at least one failed key", matching the prose two sections down that already defined 12 as a mixed result.
+
+- **sync**: **the progress stream no longer reports keys as translated that failed.** All five `key-translated` emission sites fired unconditionally after dispatching a batch, before any result was inspected, so a run in which every key failed still printed `translated: 60, totalKeys: 60` on the way to writing nothing. Each site now emits only when that key's `translateBatch` slot came back non-null, and the running count is a single counter over the successes rather than a loop index, so the number the stream reports agrees with the number the summary reports.
+
 - **sync**: **a backup left behind by a crashed run is no longer overwritten by the run you start to recover from it.** After a `kill -9` mid-sync the lockfile was never written and `locales/de.json.deepl.bak` held the only surviving copy of the user's file — and the natural recovery action, re-running `deepl sync`, destroyed it: the "already backed up" guard is a per-process `Set`, so the run copied the machine-translated target over the existing backup and then unlinked it on success. Reproduced end to end: after the recovery run the human content was gone at exit 0, and the already-completed translations were re-billed. The copy now uses `COPYFILE_EXCL`, and on `EEXIST` the existing backup is left alone with a warning naming it — and deliberately not tracked as this run's, so the success path does not unlink it either. The stale-backup sweep still retires it on age. A run with no pre-existing backup behaves exactly as before: back up, write, unlink on success.
 
 - **sync**: **Ctrl-C during a sync now restores the files it had already overwritten, instead of deleting their backups.** The signal handler ran the same cleanup as a successful run — unlink every `.deepl.bak` taken this run — which is right for a run that finished and catastrophic for one that did not: the backup was the only remaining copy of content the run had already replaced. Reproduced with a delaying endpoint and two locales: at the moment of the interrupt `locales/de.json` held machine output and `locales/de.json.deepl.bak` held the human translations; after `kill -INT` the backup was gone, the machine output stayed, and no lockfile had been written (it is written once at the end), so the human translations were unrecoverable and unrecorded at exit 130. Each backup is now copied back over its target before being removed — that order, so an interrupt during the restore leaves the backup rather than nothing — and the run reports what it undid: `Interrupted — restored 1 file(s) from backup: locales/de.json. No lockfile was written, so nothing was recorded; re-run to translate again.` Verified end to end: `locales/de.json` is byte-identical to its pre-run content. The restore is synchronous because `installSignalExit` defers the exit by one `setImmediate`, so only synchronous handler work is guaranteed to finish. A successful run is unaffected — it still unlinks, from its own path. `sync --watch` is unchanged: it owns its own backup tracker and cleanup.
diff --git a/docs/API.md b/docs/API.md
index b2ef06e1..b804d501 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3251,7 +3251,7 @@ Retryable codes are `3` (rate limit) and `5` (network); everything else should b
 | 9    | VoiceError     | Voice API unavailable or session failed                        | No        |
 | 10   | SyncDrift      | `sync --frozen` detected translations out of date              | No        |
 | 11   | SyncConflict   | `sync resolve` could not auto-resolve lockfile conflicts       | No        |
-| 12   | PartialFailure | `deepl sync` completed with at least one failed locale         | Yes (per-locale retry) |
+| 12   | PartialFailure | `deepl sync` completed with at least one failed key            | Yes (per-locale retry) |
 
 ### Code details
 
@@ -3357,7 +3357,7 @@ Remediation: open `.deepl-sync.lock`, resolve the remaining `<<<<<<<` / `=======
 
 #### 12 — PartialFailure
 
-`deepl sync` completed, but at least one locale failed while at least one other locale succeeded. The successful locales' target files and lockfile entries are written; the failed locales' files are not touched. Emitted only by `deepl sync` (the root command).
+`deepl sync` completed, but at least one key failed to translate. This covers both a locale that failed entirely and a locale that translated some of its keys and failed the rest — a failed key is absent from the written target file, so any failure count above zero means the run did not produce a complete result. The successful translations' target files and lockfile entries are written; a locale that failed entirely has its file left untouched. Emitted only by `deepl sync` (the root command).
 
 Authentication failures (401/403) abort the entire run and surface as exit code 2 (`AuthError`) instead of 12. Network / rate-limit / quota failures bubble up as 5 / 3 / 4 respectively. Code 12 specifically means "the run proceeded far enough to attempt per-locale work, and the result was mixed."
 
diff --git a/src/sync/sync-finalize.ts b/src/sync/sync-finalize.ts
index 8c02a38a..598654ef 100644
--- a/src/sync/sync-finalize.ts
+++ b/src/sync/sync-finalize.ts
@@ -31,16 +31,15 @@ export function finalizeSyncResult(i: FinalizeInputs): SyncResult {
   }
   const hasStrategy = contextCount > 0 || instructionCount > 0;
 
-  // docs/API.md defines exit 12 as "completed with at least one failed
-  // locale", so this is `some`, not `every`: one locale failing completely
-  // must fail the run even when the others succeeded.
-  // A locale that translated nothing and has no failures is simply up to date.
-  const anyLocaleFailed = i.fileResults.some(
-    (fr) => fr.translated === 0 && fr.failed > 0
-  );
+  // docs/API.md defines exit 12 as a mixed result, so any failed key fails the
+  // run: failed keys are absent from the written file, and gating on a locale
+  // failing *entirely* would report success for a run that lost most of its
+  // strings. A locale with no failures translated nothing because it is up to
+  // date, which is still success.
+  const anyKeyFailed = i.fileResults.some((fr) => fr.failed > 0);
 
   return {
-    success: !i.driftDetected && !anyLocaleFailed,
+    success: !i.driftDetected && !anyKeyFailed,
     totalKeys: i.totalKeys,
     newKeys: i.newKeys,
     staleKeys: i.staleKeys,
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 54b17e0a..1da3c8d9 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -146,6 +146,9 @@ export class LocaleTranslator {
 
     // Three-way translation: per-key context vs. element instruction batch vs. plain batch
     let results: (TranslationResult | null)[];
+    // Counts keys that actually came back translated, so the progress stream
+    // never claims a key succeeded that translateBatch left empty.
+    let completed = 0;
     const contextSentKeys = new Set<string>();
     const instructionSentKeys = new Set<string>();
     const instructionGroupCounts = new Map<string, number>();
@@ -169,12 +172,14 @@ export class LocaleTranslator {
         translationOpts
       );
       for (let i = 0; i < localeDiffs.length; i++) {
+        if (!results[i]) continue;
+        completed++;
         this.onProgress?.({
           type: 'key-translated',
           locale,
           file: relPath,
           key: localeDiffs[i]!.key,
-          translated: i + 1,
+          translated: completed,
           totalKeys: localeDiffs.length,
         });
       }
@@ -242,20 +247,21 @@ export class LocaleTranslator {
         for (let bi = 0; bi < batchPMapIndices.length; bi++) {
           results[batchPMapIndices[bi]!] = batchResults[bi] ?? null;
         }
-        for (let bi = 0; bi < batchIndices.length; bi++) {
+        for (const idx of batchIndices) {
+          if (!results[idx]) continue;
+          completed++;
           this.onProgress?.({
             type: 'key-translated',
             locale,
             file: relPath,
-            key: localeDiffs[batchIndices[bi]!]!.key,
-            translated: bi + 1,
+            key: localeDiffs[idx]!.key,
+            translated: completed,
             totalKeys: localeDiffs.length,
           });
         }
       }
 
       // Path C: batch by element type with shared custom_instructions
-      let pathCCompleted = batchIndices.length;
       for (const [elementType, indices] of instructionGroups) {
         instructionGroupCounts.set(
           elementType,
@@ -300,20 +306,20 @@ export class LocaleTranslator {
           results[groupPMapIndices[gi]!] = groupResults[gi] ?? null;
         }
         for (const idx of indices) {
-          pathCCompleted++;
+          if (!results[idx]) continue;
+          completed++;
           this.onProgress?.({
             type: 'key-translated',
             locale,
             file: relPath,
             key: localeDiffs[idx]!.key,
-            translated: pathCCompleted,
+            translated: completed,
             totalKeys: localeDiffs.length,
           });
         }
       }
 
       // Path B: context keys — batch by section where possible, per-key for overrides
-      let perKeyCompleted = pathCCompleted;
       if (contextIndices.length > 0) {
         for (const idx of contextIndices) {
           contextSentKeys.add(localeDiffs[idx]!.key);
@@ -389,13 +395,14 @@ export class LocaleTranslator {
             results[groupPMapIndices[gi]!] = groupResults[gi] ?? null;
           }
           for (const idx of indices) {
-            perKeyCompleted++;
+            if (!results[idx]) continue;
+            completed++;
             this.onProgress?.({
               type: 'key-translated',
               locale,
               file: relPath,
               key: localeDiffs[idx]!.key,
-              translated: perKeyCompleted,
+              translated: completed,
               totalKeys: localeDiffs.length,
             });
           }
@@ -468,13 +475,14 @@ export class LocaleTranslator {
               for (let ki = 0; ki < keyTextIndices.length; ki++) {
                 results[keyTextIndices[ki]!] = keyResults[ki] ?? null;
               }
-              perKeyCompleted++;
+              if (!results[idx]) return;
+              completed++;
               this.onProgress?.({
                 type: 'key-translated',
                 locale,
                 file: relPath,
                 key: diff.key,
-                translated: perKeyCompleted,
+                translated: completed,
                 totalKeys: localeDiffs.length,
               });
             },
diff --git a/tests/unit/sync/sync-finalize-failure.test.ts b/tests/unit/sync/sync-finalize-failure.test.ts
index 81173604..ea79581b 100644
--- a/tests/unit/sync/sync-finalize-failure.test.ts
+++ b/tests/unit/sync/sync-finalize-failure.test.ts
@@ -87,14 +87,14 @@ describe('finalizeSyncResult failure reporting', () => {
     expect(result.success).toBe(true);
   });
 
-  it('should report success when a locale partly succeeded', () => {
-    // docs/API.md:3056 scopes exit 12 to "at least one failed locale", so a
-    // locale that translated some keys is not a failed locale — the file is
-    // written and the per-key failures are reported in the summary.
+  it('should not report success when a locale partly failed', () => {
+    // Exit 12 means "the result was mixed". The failed keys are absent from
+    // the written file, so reporting success would let a run that lost most
+    // of its strings pass a CI gate watching exit codes.
     const result = finalize([
       fileResult({ locale: 'de', translated: 1, failed: 1, written: true }),
     ]);
 
-    expect(result.success).toBe(true);
+    expect(result.success).toBe(false);
   });
 });
diff --git a/tests/unit/sync/sync-service.test.ts b/tests/unit/sync/sync-service.test.ts
index 991cd282..99ba9b1e 100644
--- a/tests/unit/sync/sync-service.test.ts
+++ b/tests/unit/sync/sync-service.test.ts
@@ -1530,7 +1530,9 @@ describe('SyncService', () => {
 
       const result = await service.sync(makeConfig());
 
-      expect(result.success).toBe(true);
+      // The run finishes and reports both outcomes, but a failed key makes the
+      // result mixed, which is exit 12 rather than 0.
+      expect(result.success).toBe(false);
       expect(result.newKeys).toBe(3);
       expect(result.fileResults).toHaveLength(1);
       const fileResult = result.fileResults[0]!;
@@ -1815,6 +1817,31 @@ describe('SyncService', () => {
       expect(lastKeyIdx).toBeLessThan(localeIdx);
     });
 
+    it('should not count a key whose translation came back null', async () => {
+      setupLockManager(makeEmptyLockFile());
+      // translateBatch returns a sparse array: the second key failed.
+      const translateBatch = jest
+        .fn()
+        .mockResolvedValue([{ text: 'Auf Wiedersehen', billedCharacters: 15 }]);
+      const { service } = createService({ translateBatch });
+
+      mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
+      mockReadFile.mockImplementation(async (p: unknown) => {
+        if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
+        throw new Error('ENOENT');
+      });
+
+      const events: Array<{ type: string; translated: number }> = [];
+      await service.sync(makeConfig(), {
+        onProgress: (event) =>
+          events.push({ type: event.type, translated: event.translated }),
+      });
+
+      const keyEvents = events.filter((e) => e.type === 'key-translated');
+      expect(keyEvents).toHaveLength(1);
+      expect(keyEvents[0]!.translated).toBe(1);
+    });
+
     it('should not fire onProgress in dry-run mode', async () => {
       setupLockManager(makeEmptyLockFile());
       const { service } = createService();

From a41ec44ece7a5ae0e71ac16e765142f7bcf3cc6c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 10:34:10 +0200
Subject: [PATCH 127/256] fix(sync): stop a failed new-locale backfill from
 writing source text as the translation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a current key's translation failed while bootstrapping a new target
locale, the backfill path pushed the English source as the translation and
only counted a failure. Any value present in the target file counts as an
existing translation, so those strings were skipped on every later run:
sync status reported them missing, sync reported the file current and
refused to retranslate, and validate rated it a warning at exit 0 — the
strings were reported missing and unfixable at the same time, forever.

The main translation path in the same file already pushed nothing on
failure, and the guard comment 60 lines above the bug stated the reason.
The backfill path now matches it, so the key stays out of the target file
and the next run retries it.

No lockfile entry is recorded for the failure. A status:'failed' entry
would make sync status count the key as outdated when it is missing, and
would trip the "lockfile records a translation but the target file has
none" path on every retry.

Refs cli-8kr2.11

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +
 src/sync/sync-locale-translator.ts            | 10 ++--
 .../unit/sync/sync-locale-translator.test.ts  | 46 ++++++++++++++++++-
 3 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ea0a964..8c0b28c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a failed backfill for a newly added locale no longer writes the source text in as the translation.** When a current key's translation failed while bootstrapping a new target locale, the backfill path pushed `{ translation: cd.value }` — the English source — and only incremented `failed`. Because any value present in the target file counts as an existing translation, those strings were then skipped on every later run: `sync status` reported `fr 17% (50 missing, 0 outdated)` while `deepl sync` said `60 current` and refused to retranslate them, and `sync validate` rated it a warning at exit 0. The tool reported the strings as missing *and* declined to fix them, permanently, with no error anywhere. The same file's main translation path already handled this correctly, and the guard comment 60 lines up spelled out the reason: "Writing the source value here would record untranslated text as translated, which no later run would correct." The backfill path now pushes nothing, so the key stays out of the target file and the next run picks it up. Nothing is recorded in the lockfile for it either — deliberately, since a `status: 'failed'` entry would make `sync status` count the key as *outdated* when it is genuinely *missing*, and would trip the "lockfile records a translation but the target file has none" path on every retry.
+
 - **sync**: **a run that lost most of its strings no longer exits 0.** A locale counted as failed only when it translated *nothing* (`fr.translated === 0 && fr.failed > 0`), so 10 keys succeeding and 50 failing was not a failed locale: `{"ok": true, "translated": 10, "failed": 50}` at exit 0, with the 50 failed keys absent from `locales/de.json` entirely. The comment directly above the check already cited the documented contract for exit 12 and the code did not implement it. Any failure count above zero now fails the run, so `deepl sync` exits 12 and `--auto-commit` — gated on `result.success` — no longer commits a truncated locale file. A locale that translated nothing *and* failed nothing is still a success: that is a locale which is already up to date. **CI impact**: a pipeline that previously went green on a partially failed sync now sees exit 12, which is the point; branch on `$? -eq 12` and re-run with `--locale` per the retry model in `docs/API.md`. The exit-code table there described 12 as "at least one failed locale" and now says "at least one failed key", matching the prose two sections down that already defined 12 as a mixed result.
 
 - **sync**: **the progress stream no longer reports keys as translated that failed.** All five `key-translated` emission sites fired unconditionally after dispatching a batch, before any result was inspected, so a run in which every key failed still printed `translated: 60, totalKeys: 60` on the way to writing nothing. Each site now emits only when that key's `translateBatch` slot came back non-null, and the running count is a single counter over the successes rather than a loop index, so the number the stream reports agrees with the number the summary reports.
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 1da3c8d9..5cde5cf8 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -677,12 +677,10 @@ export class LocaleTranslator {
               localeBilled += nlResult.billedCharacters;
             }
           } else {
-            allTranslatedEntries.push({
-              key,
-              value: cd.value!,
-              translation: cd.value!,
-              metadata: cd.metadata,
-            });
+            // Push nothing, matching the main path above. Writing cd.value as
+            // the translation would record untranslated source text, which the
+            // next run reads back as an existing translation and skips — the
+            // source language would be frozen into the locale file for good.
             failed++;
           }
         }
diff --git a/tests/unit/sync/sync-locale-translator.test.ts b/tests/unit/sync/sync-locale-translator.test.ts
index 9769e07d..b311b1b6 100644
--- a/tests/unit/sync/sync-locale-translator.test.ts
+++ b/tests/unit/sync/sync-locale-translator.test.ts
@@ -931,7 +931,11 @@ describe('LocaleTranslator', () => {
       expect(result.targetEntries.get('welcome')).toMatch(/Hallo/);
     });
 
-    it('should fall back to source text when the new-locale translateBatch returns null', async () => {
+    it('should omit the key when the new-locale translateBatch returns null', async () => {
+      // Writing the source value would record untranslated text as a
+      // translation: the next run reads it back as an existing translation and
+      // skips the key, so the source language is frozen into the locale file
+      // permanently. Leaving the key out keeps it retryable.
       const config = makeConfig();
       const diffs: SyncDiff[] = [
         { key: 'existing_key', value: 'Existing value', status: 'current' },
@@ -949,9 +953,47 @@ describe('LocaleTranslator', () => {
 
       const result = await makeTranslator(mock, config).translate(ctx);
 
-      expect(result.targetEntries.get('existing_key')).toBe('Existing value');
+      expect(result.targetEntries.has('existing_key')).toBe(false);
+      expect(result.successfulKeys).not.toContain('existing_key');
       expect(result.fileResult.failed).toBe(1);
     });
+
+    it('should keep a failed backfill key retryable on the next run', async () => {
+      // The next run must see the key as untranslated. That is decided by the
+      // target file, so a key the failed run left out is picked up again even
+      // though nothing recorded the failure.
+      const config = makeConfig();
+      const diffs: SyncDiff[] = [
+        { key: 'existing_key', value: 'Existing value', status: 'current' },
+      ];
+      const failing = createMockTranslationService({
+        translateBatch: jest.fn().mockResolvedValue([null]),
+      });
+
+      const firstCtx: LocaleTranslatorContext = {
+        ...makeCtx(diffs, new Map()),
+        existingTargetEntries: new Map(),
+        fileLockEntries: {},
+      };
+      firstCtx.toTranslate = [];
+      const first = await makeTranslator(failing, config).translate(firstCtx);
+
+      const { mock, calls } = captureTranslateBatch(['Existierender Wert']);
+      const secondCtx: LocaleTranslatorContext = {
+        ...makeCtx(diffs, new Map()),
+        // What the failed run left behind is what the second run reads back.
+        existingTargetEntries: new Map([['de', first.targetEntries]]),
+        fileLockEntries: {},
+      };
+      secondCtx.toTranslate = [];
+      const second = await makeTranslator(mock, config).translate(secondCtx);
+
+      expect(calls.some((c) => c.texts.includes('Existing value'))).toBe(true);
+      expect(second.targetEntries.get('existing_key')).toBe(
+        'Existierender Wert'
+      );
+      expect(second.fileResult.failed).toBe(0);
+    });
   });
 
   // ---------------------------------------------------------------------------

From 4b4c48732b7f7f6bf63d83d18324a9d9a1ba392b Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 10:43:44 +0200
Subject: [PATCH 128/256] fix(sync): make the process lock actually exclusive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Measured with six processes racing over a planted stale pidfile, 100 rounds:
93 rounds had overlapping lock holders before, up to five at once, and 0 do
after. Two separate defects had to go.

The stale-pidfile reclaim was read/unlink/create with no atomicity, so a
process whose staleness verdict had been overtaken deleted the live pidfile
the winner had just written, and both held what each believed was an
exclusive lock. The create after the unlink was also the one call outside
the EEXIST handling, so a lost race surfaced as an unhandled EEXIST rather
than "another sync is running". A stale file is now removed only after
taking possession with rename(2) and confirming the captured inode is the
one proven stale; a process that captures a different file puts it back.
Acquisition always goes through the guarded create, and the retry loop is
bounded at 5 attempts with its own error rather than spinning.

That alone did not close it. The pidfile was created empty through an
O_EXCL descriptor and filled afterwards, so a live lock momentarily read as
malformed — and malformed counts as stale, so a concurrent sync deleted it
and took over. No identity check can catch that: the file it inspected is
the file it removed. The payload now goes to a private staging path and is
link(2)ed into place, publishing name and content in one step, which is
also the atomic acquisition.

Refs cli-8kr2.15

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                              |   2 +
 src/sync/sync-process-lock.ts             | 166 ++++++++++++++++++----
 tests/unit/sync/sync-process-lock.test.ts | 111 +++++++++++++++
 3 files changed, 251 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c0b28c4..1e447681 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **two syncs no longer run concurrently in the same directory, which is the entire purpose of the process lock.** Measured with six processes racing over a planted stale pidfile, 100 rounds: **93 rounds had overlapping lock holders before this change — up to five at once — and 0 do after.** Two independent defects had to be fixed to get there. First, the stale-pidfile reclaim was a read/unlink/create sequence with no atomicity, so a process whose staleness verdict had already been overtaken deleted the *live* pidfile the winner had just written, after which both held what each believed was an exclusive lock; and the create that followed the unlink was the one call not wrapped in the EEXIST handling, so a lost race surfaced as an unhandled `Error: EEXIST: file already exists, open '.deepl-sync.lock.pidfile'` instead of the intended "another sync is running". A stale file is now removed only after taking possession of it with `rename(2)` — atomic, so exactly one of several racers can move a given entry aside — and confirming the captured inode is the one proven stale; a process that captures a different file puts it back rather than deleting someone's lock. Acquisition always goes through the same guarded create, so a lost race reports the running sync, and the retry loop is bounded (5 attempts) with its own error rather than spinning. Second, and the defect that actually accounted for the remaining overlap once the reclaim was atomic: the pidfile was created empty through an `O_EXCL` descriptor and filled afterwards, leaving a window in which a **live** lock read as malformed — and malformed counts as stale, so a concurrent sync deleted it and took over. No identity check downstream can catch that, because the file it inspected really is the file it removed. The payload is now written to a private staging path and `link(2)`ed into place, which publishes the name and the content in one step and doubles as the atomic acquisition. CI relevance: a runner retrying a timed-out job is exactly the double-start trigger.
+
 - **sync**: **a failed backfill for a newly added locale no longer writes the source text in as the translation.** When a current key's translation failed while bootstrapping a new target locale, the backfill path pushed `{ translation: cd.value }` — the English source — and only incremented `failed`. Because any value present in the target file counts as an existing translation, those strings were then skipped on every later run: `sync status` reported `fr 17% (50 missing, 0 outdated)` while `deepl sync` said `60 current` and refused to retranslate them, and `sync validate` rated it a warning at exit 0. The tool reported the strings as missing *and* declined to fix them, permanently, with no error anywhere. The same file's main translation path already handled this correctly, and the guard comment 60 lines up spelled out the reason: "Writing the source value here would record untranslated text as translated, which no later run would correct." The backfill path now pushes nothing, so the key stays out of the target file and the next run picks it up. Nothing is recorded in the lockfile for it either — deliberately, since a `status: 'failed'` entry would make `sync status` count the key as *outdated* when it is genuinely *missing*, and would trip the "lockfile records a translation but the target file has none" path on every retry.
 
 - **sync**: **a run that lost most of its strings no longer exits 0.** A locale counted as failed only when it translated *nothing* (`fr.translated === 0 && fr.failed > 0`), so 10 keys succeeding and 50 failing was not a failed locale: `{"ok": true, "translated": 10, "failed": 50}` at exit 0, with the 50 failed keys absent from `locales/de.json` entirely. The comment directly above the check already cited the documented contract for exit 12 and the code did not implement it. Any failure count above zero now fails the run, so `deepl sync` exits 12 and `--auto-commit` — gated on `result.success` — no longer commits a truncated locale file. A locale that translated nothing *and* failed nothing is still a success: that is a locale which is already up to date. **CI impact**: a pipeline that previously went green on a partially failed sync now sees exit 12, which is the point; branch on `$? -eq 12` and re-run with `--locale` per the retry model in `docs/API.md`. The exit-code table there described 12 as "at least one failed locale" and now says "at least one failed key", matching the prose two sections down that already defined 12 as a mixed result.
diff --git a/src/sync/sync-process-lock.ts b/src/sync/sync-process-lock.ts
index 4571ddaa..57f0663a 100644
--- a/src/sync/sync-process-lock.ts
+++ b/src/sync/sync-process-lock.ts
@@ -5,6 +5,8 @@ import { Logger } from '../utils/logger.js';
 
 export const PROCESS_LOCK_FILE_NAME = '.deepl-sync.lock.pidfile';
 
+const MAX_ACQUIRE_ATTEMPTS = 5;
+
 interface PidFilePayload {
   pid: number;
   startedAt: string;
@@ -35,10 +37,23 @@ function isProcessAlive(pid: number): boolean {
   }
 }
 
-function readExistingPidFile(pidFilePath: string): PidFilePayload | null {
-  let raw: string;
+interface PidFileInspection {
+  /** null when the file holds content no sync wrote, which counts as stale. */
+  payload: PidFilePayload | null;
+  /** Identity of the file that was read, so a later reclaim can confirm it is
+   * removing that same file rather than a replacement. */
+  ino: number;
+  dev: number;
+}
+
+/**
+ * Reads the pidfile and its identity through a single descriptor, so the
+ * payload and the inode cannot describe two different files.
+ */
+function inspectPidFile(pidFilePath: string): PidFileInspection | null {
+  let fd: number;
   try {
-    raw = fs.readFileSync(pidFilePath, 'utf-8');
+    fd = fs.openSync(pidFilePath, fs.constants.O_RDONLY);
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;
     if (code === 'ENOENT') return null;
@@ -46,22 +61,94 @@ function readExistingPidFile(pidFilePath: string): PidFilePayload | null {
   }
 
   try {
-    const parsed: unknown = JSON.parse(raw);
-    if (isPidFilePayload(parsed)) return parsed;
+    const stats = fs.fstatSync(fd);
+    const raw = fs.readFileSync(fd, 'utf-8');
+    let payload: PidFilePayload | null = null;
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (isPidFilePayload(parsed)) payload = parsed;
+    } catch {
+      // Malformed content counts as stale, handled by the caller.
+    }
+    return { payload, ino: stats.ino, dev: stats.dev };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Removes a pidfile already proven stale, without ever removing one this
+ * process has not taken possession of.
+ *
+ * rename(2) is atomic, so of several syncs racing to break the same stale lock
+ * exactly one can move that directory entry aside; the others get ENOENT.
+ * Checking the inode *after* the move is what closes the read/unlink race: a
+ * process whose staleness verdict has been overtaken by a winner captures the
+ * winner's file, sees a different inode, and puts it back instead of deleting a
+ * live lock.
+ *
+ * Returns true when the stale file is gone and the lock is free to retake.
+ */
+function reclaimStalePidFile(
+  pidFilePath: string,
+  stale: PidFileInspection
+): boolean {
+  const capturedPath = `${pidFilePath}.stale.${process.pid}`;
+  try {
+    fs.renameSync(pidFilePath, capturedPath);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return false;
+    throw err;
+  }
+
+  let captured: fs.Stats;
+  try {
+    captured = fs.statSync(capturedPath);
   } catch {
-    // fall through — treat malformed content as stale below
+    return false;
   }
-  return null;
+
+  if (captured.ino !== stale.ino || captured.dev !== stale.dev) {
+    try {
+      fs.renameSync(capturedPath, pidFilePath);
+    } catch {
+      // The restore failed, so the path is left free rather than holding
+      // someone else's lock. The caller re-reads either way.
+    }
+    return false;
+  }
+
+  try {
+    fs.unlinkSync(capturedPath);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT') throw err;
+  }
+  return true;
 }
 
+/**
+ * Creates the pidfile, already holding its full payload, or throws EEXIST if
+ * another process holds the lock.
+ *
+ * The payload is written to a private path and link(2)ed into place rather than
+ * written through an O_EXCL descriptor at the final path. Creating it empty and
+ * filling it afterwards leaves a window in which a live lock reads as malformed
+ * — and a reader that catches that window judges the lock stale and deletes it,
+ * which no identity check downstream can detect, because the file it inspected
+ * really is the file it removed. link(2) publishes the name and the content in
+ * one step and fails EEXIST if it loses, so it is also the atomic acquisition.
+ */
 function writePidFile(pidFilePath: string): void {
   const payload: PidFilePayload = {
     pid: process.pid,
     startedAt: new Date().toISOString(),
   };
+  const stagingPath = `${pidFilePath}.new.${process.pid}`;
   const fd = fs.openSync(
-    pidFilePath,
-    fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY,
+    stagingPath,
+    fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_WRONLY,
     0o644
   );
   try {
@@ -69,6 +156,16 @@ function writePidFile(pidFilePath: string): void {
   } finally {
     fs.closeSync(fd);
   }
+  try {
+    fs.linkSync(stagingPath, pidFilePath);
+  } finally {
+    try {
+      fs.unlinkSync(stagingPath);
+    } catch {
+      // Best effort: a leftover staging file is reused by this pid's next
+      // attempt, and must not mask the link result.
+    }
+  }
 }
 
 export interface ProcessLockHandle {
@@ -79,31 +176,44 @@ export interface ProcessLockHandle {
 export function acquireSyncProcessLock(projectRoot: string): ProcessLockHandle {
   const pidFilePath = path.join(projectRoot, PROCESS_LOCK_FILE_NAME);
 
-  try {
-    writePidFile(pidFilePath);
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code !== 'EEXIST') throw err;
+  // Every acquisition goes through the same O_EXCL create, including the one
+  // after a stale file is cleared: taking the lock is the only step that may
+  // decide the winner, so a create that loses reports another running sync
+  // rather than crashing with a raw EEXIST.
+  for (let attempt = 1; ; attempt++) {
+    try {
+      writePidFile(pidFilePath);
+      break;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== 'EEXIST') throw err;
+    }
 
-    const existing = readExistingPidFile(pidFilePath);
-    if (existing && isProcessAlive(existing.pid)) {
+    const existing = inspectPidFile(pidFilePath);
+    if (existing?.payload && isProcessAlive(existing.payload.pid)) {
       throw new ConfigError(
-        `Another \`deepl sync\` process is running in this directory (PID=${existing.pid}, started ${existing.startedAt}). Wait for it to finish or kill it before retrying.`,
+        `Another \`deepl sync\` process is running in this directory (PID=${existing.payload.pid}, started ${existing.payload.startedAt}). Wait for it to finish or kill it before retrying.`,
         `If the process is definitely not running, remove ${PROCESS_LOCK_FILE_NAME} manually and retry.`
       );
     }
 
-    const stalePidLabel = existing ? `PID=${existing.pid}` : 'unknown PID';
-    Logger.warn(
-      `Removing stale ${PROCESS_LOCK_FILE_NAME} (${stalePidLabel} is not alive); reclaiming lock.`
-    );
-    try {
-      fs.unlinkSync(pidFilePath);
-    } catch (unlinkErr) {
-      const unlinkCode = (unlinkErr as NodeJS.ErrnoException).code;
-      if (unlinkCode !== 'ENOENT') throw unlinkErr;
+    if (attempt >= MAX_ACQUIRE_ATTEMPTS) {
+      throw new ConfigError(
+        `Could not take the \`deepl sync\` lock in this directory: ${PROCESS_LOCK_FILE_NAME} keeps being replaced by another process (${MAX_ACQUIRE_ATTEMPTS} attempts).`,
+        `Wait for the other sync to finish, or remove ${PROCESS_LOCK_FILE_NAME} manually and retry.`
+      );
+    }
+
+    // A pidfile that vanished between the failed create and the read needs no
+    // reclaim; retry the create directly.
+    if (existing !== null && reclaimStalePidFile(pidFilePath, existing)) {
+      const stalePidLabel = existing.payload
+        ? `PID=${existing.payload.pid}`
+        : 'unknown PID';
+      Logger.warn(
+        `Removed stale ${PROCESS_LOCK_FILE_NAME} (${stalePidLabel} is not alive); reclaiming lock.`
+      );
     }
-    writePidFile(pidFilePath);
   }
 
   let released = false;
@@ -111,7 +221,7 @@ export function acquireSyncProcessLock(projectRoot: string): ProcessLockHandle {
     if (released) return;
     released = true;
     try {
-      const current = readExistingPidFile(pidFilePath);
+      const current = inspectPidFile(pidFilePath)?.payload;
       if (current && current.pid !== process.pid) {
         // Another process reclaimed the lock; don't remove its pidfile.
         return;
diff --git a/tests/unit/sync/sync-process-lock.test.ts b/tests/unit/sync/sync-process-lock.test.ts
index f5625d12..41703a40 100644
--- a/tests/unit/sync/sync-process-lock.test.ts
+++ b/tests/unit/sync/sync-process-lock.test.ts
@@ -76,6 +76,36 @@ describe('acquireSyncProcessLock', () => {
       expect(fs.existsSync(pidFilePath)).toBe(false);
     });
 
+    /**
+     * A pidfile that exists before its payload does reads as malformed, and a
+     * concurrent sync that catches that window judges the live lock stale and
+     * removes it. No identity check downstream can catch that: the file it
+     * inspected really is the file it deleted.
+     */
+    it('writes the payload before the pidfile appears at its final path', () => {
+      const realWriteSync = fsModule.writeSync;
+      let finalPathExisted: boolean | undefined;
+      jest.spyOn(fsModule, 'writeSync').mockImplementation(((
+        ...args: Parameters<typeof fs.writeSync>
+      ) => {
+        finalPathExisted ??= fs.existsSync(pidFilePath);
+        return realWriteSync(...args);
+      }) as typeof fs.writeSync);
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(finalPathExisted).toBe(false);
+      expect(ownerPid()).toBe(process.pid);
+      handle.release();
+    });
+
+    it('leaves no staging file behind', () => {
+      const handle = acquireSyncProcessLock(projectRoot);
+      handle.release();
+
+      expect(fs.readdirSync(projectRoot)).toEqual([]);
+    });
+
     it('propagates a pidfile write failure that is not EEXIST', () => {
       let caught: unknown;
       try {
@@ -231,6 +261,87 @@ describe('acquireSyncProcessLock', () => {
 
       expect(() => acquireSyncProcessLock(projectRoot)).toThrow('EACCES');
     });
+
+    /**
+     * The reclaim is a check followed by a removal, so a sync that wins the
+     * race writes a LIVE pidfile into the window between the two. Removing it
+     * would leave both processes believing they hold the lock, writing the same
+     * target files and the same lockfile.
+     */
+    it('leaves a live pidfile alone when a racing sync reclaims the lock first', () => {
+      const winnerPid = 5555;
+      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      const realKill = process.kill.bind(process);
+      jest
+        .spyOn(process, 'kill')
+        .mockImplementation((pid: number, signal?: string | number) => {
+          if (pid === 4242) {
+            // A racing sync takes the lock between this staleness verdict and
+            // the reclaim it authorises. Unlink-then-create, as a real winner
+            // does, so the replacement is a different inode.
+            fs.rmSync(pidFilePath, { force: true });
+            plantPidFile({
+              pid: winnerPid,
+              startedAt: '2026-06-01T00:00:00.000Z',
+            });
+            throw errnoError('ESRCH');
+          }
+          if (pid === winnerPid) return true;
+          return realKill(pid, signal);
+        });
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+      expect(ownerPid()).toBe(winnerPid);
+    });
+
+    it('reports the running sync rather than a raw EEXIST when the freed slot is taken first', () => {
+      const winnerPid = 5555;
+      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      jest.spyOn(process, 'kill').mockImplementation((pid: number) => {
+        if (pid === 4242) throw errnoError('ESRCH');
+        return true;
+      });
+      const realUnlink = fsModule.unlinkSync;
+      let taken = false;
+      jest.spyOn(fsModule, 'unlinkSync').mockImplementation((target) => {
+        realUnlink(target);
+        if (!taken) {
+          taken = true;
+          // The winner claims the now-vacant path before this process can.
+          plantPidFile({
+            pid: winnerPid,
+            startedAt: '2026-06-01T00:00:00.000Z',
+          });
+        }
+      });
+
+      let caught: unknown;
+      try {
+        acquireSyncProcessLock(projectRoot);
+      } catch (error) {
+        caught = error;
+      }
+
+      expect(caught).toBeInstanceOf(ConfigError);
+      expect((caught as Error).message).toMatch(/PID=5555/);
+      expect(ownerPid()).toBe(winnerPid);
+    });
+
+    it('gives up with a clear error when the pidfile keeps being replaced', () => {
+      plantPidFile('not json at all');
+      const realRename = fsModule.renameSync;
+      jest.spyOn(fsModule, 'renameSync').mockImplementation((from, to) => {
+        realRename(from, to);
+        // A phantom process recreates a stale pidfile every time this one is
+        // cleared, so the retry loop must terminate rather than spin.
+        plantPidFile('not json at all');
+      });
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(
+        /keeps being replaced/
+      );
+    });
   });
 
   describe('release', () => {

From 3efce0fd0b4470ed97bcae51115dfe73b9584f3c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 12:45:17 +0200
Subject: [PATCH 129/256] chore(tests): drop an unnecessary type assertion in
 the process-lock test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

eslint's no-unnecessary-type-assertion rejects the `as typeof fs.writeSync`
cast on the writeSync spy implementation, so `npm run lint` failed at
--max-warnings 0 on a clean tree. The parameter annotation alone gives the
mock the right signature.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/unit/sync/sync-process-lock.test.ts | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/tests/unit/sync/sync-process-lock.test.ts b/tests/unit/sync/sync-process-lock.test.ts
index 41703a40..87e93a65 100644
--- a/tests/unit/sync/sync-process-lock.test.ts
+++ b/tests/unit/sync/sync-process-lock.test.ts
@@ -85,12 +85,12 @@ describe('acquireSyncProcessLock', () => {
     it('writes the payload before the pidfile appears at its final path', () => {
       const realWriteSync = fsModule.writeSync;
       let finalPathExisted: boolean | undefined;
-      jest.spyOn(fsModule, 'writeSync').mockImplementation(((
-        ...args: Parameters<typeof fs.writeSync>
-      ) => {
-        finalPathExisted ??= fs.existsSync(pidFilePath);
-        return realWriteSync(...args);
-      }) as typeof fs.writeSync);
+      jest
+        .spyOn(fsModule, 'writeSync')
+        .mockImplementation((...args: Parameters<typeof fs.writeSync>) => {
+          finalPathExisted ??= fs.existsSync(pidFilePath);
+          return realWriteSync(...args);
+        });
 
       const handle = acquireSyncProcessLock(projectRoot);
 

From 4a994e29585261d7a2a858b7826c68696b809749 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 12:46:00 +0200
Subject: [PATCH 130/256] fix(cli): neutralize terminal control sequences
 before rendering untrusted text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Translation text went from the API to stdout raw, and i18n keys went from a
checkout to stdout raw, so either could carry terminal control sequences.
Measured against a stub endpoint with a real pty on stdout: 4 raw ESC and 1
BEL before — OSC 0 setting the window title, CSI 2K erasing the line — and 2
ESC and 0 BEL after, both of them SGR colour. The key sink needs no API key
and no network: an evil checkout plus `deepl sync validate` exits 8 with an
OSC 52 clipboard write and a CSI 2J screen erase verbatim in its output, and
`hooks install` puts that command in the pre-commit hook, so it fires on
every commit. sanitizeForTerminal already existed and was used in ten other
files, just not on the primary render paths.

Two layers. Untrusted values interpolated into report lines are sanitized at
the call site, unconditionally: the locale, key and message in sync validate,
and the choice labels in the write/correct interactive prompts, where the
value handed back to the caller stays raw so only the display changes. The
logger then neutralizes control sequences centrally, covering all 111
Logger.output call sites, every stderr sink, and future ones by construction
— including error paths that echo a hostile value, such as the JSON parser's
duplicate-key report.

stderr is sanitized whether or not it is a TTY: a redirected stderr is still
rendered by CI log viewers that interpret ANSI. stdout is sanitized only when
it is a terminal, because redirected stdout is data — `deepl translate >
out.txt` and command substitution must reproduce the API's bytes exactly, and
a control sequence can only act on a terminal that interprets one. This is
the rule ls and git apply to nonprintables. Report lines do not depend on
that gate; layer one covers them either way.

SGR sequences are allowed through, since chalk-formatted strings reach the
logger already rendered and stripping them would drop all colour. That
concedes text attributes only; OSC title and clipboard writes, CSI erase and
cursor moves, and the status queries whose reply is typed back on the shell's
stdin all require a non-SGR sequence and are neutralized.

The stream filter is a separate, narrower function rather than
sanitizeForTerminal, which cannot be applied to a whole stream: it replaces
newlines and tabs, and replaces U+200B-U+200F, so using it on translation
output would have turned every multi-line result into ?-separated text and
corrupted the ZWNJ, ZWJ and bidi marks that are legitimate content in
Persian, Arabic, Devanagari and emoji sequences — silent corruption of the
main command's output in place of the bug being fixed. For the same reason
the suggested wrapping of the two `return result.text` sites in
text-translation-handler.ts is not what landed: those returns are the piped
data path.

Refs cli-8kr2.16
Refs cli-8kr2.43

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +
 docs/API.md                                   | 16 ++++
 .../commands/sync/register-sync-validate.ts   |  5 +-
 src/cli/commands/write.ts                     | 32 ++++---
 src/utils/control-chars.ts                    | 31 +++++++
 src/utils/logger.ts                           | 48 +++++++---
 tests/e2e/cli-sync.e2e.test.ts                | 21 +++++
 tests/unit/logger.test.ts                     | 87 +++++++++++++++++++
 tests/unit/utils/control-chars.test.ts        | 83 +++++++++++++++++-
 tests/unit/write-command.test.ts              | 27 ++++++
 10 files changed, 329 insertions(+), 23 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e447681..a439736c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -375,6 +375,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **cli, sync**: **text the CLI did not author can no longer drive the terminal that renders it.** Translation text went from the API to stdout raw, and i18n keys went from a checkout to stdout raw, so both could carry terminal control sequences. Measured against a stub endpoint with a real pty on stdout: the run emitted **4 raw ESC and 1 BEL before this change — setting the window title via OSC 0 and erasing the line via CSI 2K — and 2 ESC and 0 BEL after, both of them SGR colour**. The key sink needs no API key and no network: an evil checkout plus `deepl sync validate` exits 8 with an OSC 52 clipboard write and a CSI 2J screen erase verbatim in its output, and `hooks install` puts that command in the pre-commit hook, so it fires on every commit. `sanitizeForTerminal` already existed and was applied in ten other files, just not on the primary render paths. Two layers close it. **Untrusted values interpolated into report lines are sanitized at the call site, unconditionally**: the locale, key and message in `sync validate`, and the choice labels in `write --interactive` / `correct --interactive`, where the value handed back to the caller stays raw so only the display is affected. **The logger neutralizes control sequences centrally**, which covers all 111 `Logger.output` call sites, every stderr sink, and future ones by construction — including error paths that echo a hostile value, such as the JSON parser's duplicate-key report. stderr is sanitized whether or not it is a TTY, because a redirected stderr is still rendered by CI log viewers that interpret ANSI. **stdout is sanitized only when it is a terminal**, because redirected stdout is data: `deepl translate ... > out.txt` and `$(deepl translate ...)` must reproduce the API's bytes exactly, and a control sequence can only act on a terminal that interprets one — the same rule `ls` and `git` apply to nonprintables. Colour (SGR) sequences survive, since chalk-formatted strings are passed to the logger already rendered and stripping them would drop all colour; that concedes only text attributes, while the primitives that let injected text take over a session — OSC title and clipboard writes, CSI erase and cursor moves, and the status queries whose reply is typed back on the shell's stdin — are all neutralized. The stream filter is a **separate, narrower function** from `sanitizeForTerminal`, which cannot be used on a whole stream: it replaces newlines and tabs, and replaces U+200B–U+200F, so applying it to translation output would have turned every multi-line result into `?`-separated text and corrupted the ZWNJ, ZWJ and bidi marks that are legitimate content in Persian, Arabic, Devanagari and emoji sequences — silent corruption of the main command's output, in place of the bug being fixed.
+
 - **api**: a batch translation response that returns the submitted texts themselves, rearranged, is now refused instead of written out. `POST /v2/translate` correlates a translation to its request item by position and by nothing else, and the only check on the response was that it had the same number of entries — so an endpoint returning the request's own texts rotated by one wrote each translation under the wrong i18n key at exit 0, reporting full success. `{confirm_delete: 'Delete account permanently', cancel: 'Cancel', save: 'Save changes'}` came back as `{confirm_delete: 'Cancel', cancel: 'Save changes', save: 'Delete account permanently'}`, hiding a destructive action behind the cancel label; the placeholder validator cannot see it, because plain UI strings carry no placeholders to compare. Verified end to end against a rotating stub: exit 5 and no file written, where the same run previously exited 0 with the keys transposed, and an honest endpoint on the same fixture is unaffected. The check requires **both** that the returned texts are a multiset match for the submitted ones and that at least one has moved position, so it cannot fire on a legitimate identity translation (source language equal to target, where nothing moves) or on one item whose translation happens to equal another item's source text, which a partially translated file produces. It is deliberately narrow: this catches the one reordering that is provable from the response alone, and an endpoint returning plausible **translations** in the wrong order remains undetectable, because the protocol carries no per-item identity to verify. It applies to every batch caller — `translate` on all 11 structured i18n formats, plain-text batches, and `sync` — since it sits in the one client method they share.
 
 - **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
diff --git a/docs/API.md b/docs/API.md
index b804d501..3f10b485 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -37,6 +37,7 @@ Complete reference for all DeepL CLI commands, options, and configuration.
   - Administration
     - [admin](#admin)
 - [Configuration](#configuration)
+- [Terminal Output Safety](#terminal-output-safety)
 - [Environment Variables](#environment-variables)
 - [Exit Codes](#exit-codes)
 
@@ -3122,6 +3123,21 @@ Existing `~/.deepl-cli/` installations continue to work with no changes needed.
 
 ---
 
+## Terminal Output Safety
+
+Translations, i18n keys, glossary entries and API error messages can all contain bytes the CLI did not author. Terminal control sequences hidden in that text can set the window title, write the clipboard (OSC 52), erase the screen, or forge a plausible-looking result line. The CLI neutralizes them, replacing each with `?`:
+
+| Stream                                                              | When                    | Behavior                                                                                                   |
+| ------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **stderr** (progress, warnings, errors)                             | Always                  | Control sequences replaced. Non-TTY stderr is still rendered by CI log viewers that interpret ANSI.          |
+| **stdout**, when it is a terminal                                   | Always                  | Control sequences replaced.                                                                                 |
+| **stdout**, when redirected to a file, a pipe or command substitution | Never                   | Byte-for-byte identical to what the API returned, so `deepl translate ... > out.txt` is lossless.           |
+| **Report lines** that interpolate untrusted values (for example the key in `deepl sync validate`) | Always | Control sequences replaced whether or not stdout is a terminal, since these are diagnostics, not data.       |
+
+Colour (SGR) sequences are preserved so `deepl` output stays readable; use [`NO_COLOR`](#no_color) to turn colour off. Tabs, newlines, carriage returns and Unicode formatting characters that are legitimate translation content — zero-width joiners, and the bidi marks used in Arabic, Hebrew and Persian text — are never altered on stdout.
+
+---
+
 ## Environment Variables
 
 ### `DEEPL_API_KEY`
diff --git a/src/cli/commands/sync/register-sync-validate.ts b/src/cli/commands/sync/register-sync-validate.ts
index 7b605518..045ddd2a 100644
--- a/src/cli/commands/sync/register-sync-validate.ts
+++ b/src/cli/commands/sync/register-sync-validate.ts
@@ -1,6 +1,7 @@
 import { Command, Option } from 'commander';
 import chalk from 'chalk';
 import { Logger } from '../../../utils/logger.js';
+import { sanitizeForTerminal } from '../../../utils/control-chars.js';
 import { ExitCode } from '../../../utils/exit-codes.js';
 import type { ServiceDeps } from '../service-factory.js';
 import {
@@ -76,7 +77,9 @@ async function handleSyncValidate(
               ? chalk.red('ERROR')
               : chalk.yellow('WARN');
           Logger.output(
-            `  ${icon}  ${issue.locale}/${issue.key}: ${issue.issues.map((i) => i.message).join(', ')}`
+            `  ${icon}  ${sanitizeForTerminal(issue.locale)}/${sanitizeForTerminal(issue.key)}: ${issue.issues
+              .map((i) => sanitizeForTerminal(i.message))
+              .join(', ')}`
           );
         }
         Logger.output(
diff --git a/src/cli/commands/write.ts b/src/cli/commands/write.ts
index be0a2a20..64507d5b 100644
--- a/src/cli/commands/write.ts
+++ b/src/cli/commands/write.ts
@@ -14,6 +14,7 @@ import chalk from 'chalk';
 import { formatWriteJson } from '../../utils/formatters.js';
 import { safeReadFile } from '../../utils/safe-read-file.js';
 import { Logger } from '../../utils/logger.js';
+import { sanitizeForTerminal } from '../../utils/control-chars.js';
 import { ValidationError } from '../../utils/errors.js';
 import { errorMessage } from '../../utils/error-message.js';
 
@@ -341,16 +342,21 @@ export class WriteCommand {
       );
 
       const maxLen = this.getPreviewWidth();
+      // Prompt labels are rendered straight into the terminal by inquirer, so
+      // control characters are replaced for display. The value handed back to
+      // the caller stays raw.
+      const originalPreview = sanitizeForTerminal(text);
+      const improvedPreview = sanitizeForTerminal(improvements[0]!.text);
       const choices = [
         {
-          name: `${chalk.yellow('Keep original')} - "${this.truncate(text, maxLen)}"`,
+          name: `${chalk.yellow('Keep original')} - "${this.truncate(originalPreview, maxLen)}"`,
           value: -1,
-          description: text,
+          description: originalPreview,
         },
         {
-          name: `${chalk.bold(options.correct ? 'Corrected' : 'Improved')} - "${this.truncate(improvements[0]!.text, maxLen)}"`,
+          name: `${chalk.bold(options.correct ? 'Corrected' : 'Improved')} - "${this.truncate(improvedPreview, maxLen)}"`,
           value: 0,
-          description: improvements[0]!.text,
+          description: improvedPreview,
         },
       ];
 
@@ -403,17 +409,21 @@ export class WriteCommand {
 
     // Create choices with style labels
     const maxLen = this.getPreviewWidth();
+    const originalPreview = sanitizeForTerminal(text);
     const choices = [
       {
-        name: `${chalk.yellow('Keep original')} - "${this.truncate(text, maxLen)}"`,
+        name: `${chalk.yellow('Keep original')} - "${this.truncate(originalPreview, maxLen)}"`,
         value: -1,
-        description: text,
+        description: originalPreview,
       },
-      ...uniqueImprovements.map((improvement, index) => ({
-        name: `${chalk.bold(improvement.label)} - "${this.truncate(improvement.text, maxLen)}"`,
-        value: index,
-        description: improvement.text,
-      })),
+      ...uniqueImprovements.map((improvement, index) => {
+        const preview = sanitizeForTerminal(improvement.text);
+        return {
+          name: `${chalk.bold(improvement.label)} - "${this.truncate(preview, maxLen)}"`,
+          value: index,
+          description: preview,
+        };
+      }),
     ];
 
     // Prompt user to select
diff --git a/src/utils/control-chars.ts b/src/utils/control-chars.ts
index 0ddc2561..d63d0cf0 100644
--- a/src/utils/control-chars.ts
+++ b/src/utils/control-chars.ts
@@ -19,3 +19,34 @@ const TERMINAL_UNSAFE_CHARS = /[\x00-\x1f\x7f\u200b-\u200f\u2028-\u202f]/g;
 export function sanitizeForTerminal(input: string): string {
   return input.replace(TERMINAL_UNSAFE_CHARS, '?');
 }
+
+/**
+ * Replace only the characters a terminal interprets as the start of a control
+ * sequence, leaving every other codepoint — including tab, newline, carriage
+ * return and zero-width/bidi marks — byte-for-byte intact. Used as a whole-
+ * stream filter in the logger, where `sanitizeForTerminal` cannot be applied:
+ * it would turn newlines into `?` and mangle ZWNJ/ZWJ/LRM/RLM that are
+ * legitimate content in Persian, Arabic, Devanagari and emoji sequences.
+ *
+ * The regex covers:
+ *   - `\x1b` not followed by an SGR `CSI…m` body — ESC is what makes OSC, DCS
+ *     and non-SGR CSI sequences actionable; replacing it leaves the remainder
+ *     as inert printable text
+ *   - `\x00-\x08`, `\x0b`, `\x0c`, `\x0e-\x1a`, `\x1c-\x1f`, `\x7f` — C0
+ *     controls and DEL, minus tab/LF/CR which carry document structure
+ *   - `\u0080-\u009f` — C1 controls, including U+009B, the single-byte CSI
+ *
+ * SGR sequences are allowed through because chalk-formatted strings are passed
+ * to the logger already rendered, so stripping them would drop all colour.
+ * They can only change text attributes; the primitives that let injected text
+ * take over a session — OSC title/clipboard writes, CSI erase and cursor
+ * moves, and the status queries whose reply is typed back on stdin — all
+ * require a non-SGR sequence and are neutralized.
+ */
+const TERMINAL_CONTROL_SEQUENCES =
+  // eslint-disable-next-line no-control-regex -- intentional: matching terminal control introducers in untrusted input before rendering
+  /\x1b(?!\[[\d;:]*m)|[\x00-\x08\x0b\x0c\x0e-\x1a\x1c-\x1f\x7f\u0080-\u009f]/g;
+
+export function neutralizeTerminalControls(input: string): string {
+  return input.replace(TERMINAL_CONTROL_SEQUENCES, '?');
+}
diff --git a/src/utils/logger.ts b/src/utils/logger.ts
index 628c00d4..7d44f468 100644
--- a/src/utils/logger.ts
+++ b/src/utils/logger.ts
@@ -3,6 +3,8 @@
  * Centralized logging with quiet mode support
  */
 
+import { neutralizeTerminalControls } from './control-chars.js';
+
 class LoggerClass {
   private quiet: boolean = false;
   private verboseMode: boolean = false;
@@ -36,22 +38,33 @@ class LoggerClass {
   }
 
   private sanitize(value: unknown): unknown {
-    return this.sanitizeValue(value, new WeakSet());
+    return this.mapStrings(value, new WeakSet(), (text) =>
+      this.sanitizeString(text)
+    );
+  }
+
+  private neutralize(value: unknown): unknown {
+    return this.mapStrings(value, new WeakSet(), neutralizeTerminalControls);
   }
 
   /**
-   * Recursively redact strings inside plain objects, arrays and Errors so a
-   * dumped axios error (config.headers.Authorization etc.) cannot leak
-   * credentials via util.inspect. Other object types pass through unchanged.
+   * Recursively apply `transform` to strings inside plain objects, arrays and
+   * Errors so a dumped axios error (config.headers.Authorization etc.) cannot
+   * leak credentials via util.inspect. Other object types pass through
+   * unchanged.
    */
-  private sanitizeValue(value: unknown, seen: WeakSet<object>): unknown {
-    if (typeof value === 'string') return this.sanitizeString(value);
+  private mapStrings(
+    value: unknown,
+    seen: WeakSet<object>,
+    transform: (text: string) => string
+  ): unknown {
+    if (typeof value === 'string') return transform(value);
     if (value === null || typeof value !== 'object') return value;
     if (seen.has(value)) return '[Circular]';
     seen.add(value);
 
     if (Array.isArray(value)) {
-      return value.map((item) => this.sanitizeValue(item, seen));
+      return value.map((item) => this.mapStrings(item, seen, transform));
     }
 
     if (value instanceof Error) {
@@ -68,7 +81,7 @@ class LoggerClass {
             ? descriptor.value
             : (value as unknown as Record<string, unknown>)[key];
         Object.defineProperty(copy, key, {
-          value: this.sanitizeValue(raw, seen),
+          value: this.mapStrings(raw, seen, transform),
           writable: true,
           configurable: true,
           enumerable: descriptor.enumerable,
@@ -81,7 +94,7 @@ class LoggerClass {
     if (proto === Object.prototype || proto === null) {
       const result: Record<string, unknown> = {};
       for (const [key, entry] of Object.entries(value)) {
-        result[key] = this.sanitizeValue(entry, seen);
+        result[key] = this.mapStrings(entry, seen, transform);
       }
       return result;
     }
@@ -124,7 +137,11 @@ class LoggerClass {
     if (tmsToken) {
       result = result.replaceAll(tmsToken, '[REDACTED]');
     }
-    return result;
+    // Everything routed here goes to stderr, which is diagnostics rather than
+    // data: no caller consumes it as bytes, and a non-TTY stderr is still
+    // routinely rendered by an ANSI-interpreting CI log viewer, so control
+    // sequences are neutralized unconditionally.
+    return neutralizeTerminalControls(result);
   }
 
   /**
@@ -173,8 +190,19 @@ class LoggerClass {
   /**
    * Log essential output (ALWAYS shown, even in quiet mode)
    * Use this for translation results, command output, etc.
+   *
+   * Terminal control sequences are neutralized only when stdout is a TTY.
+   * Redirected stdout is data — `deepl translate ... > out.txt` and command
+   * substitution must reproduce the translation byte for byte — and a control
+   * sequence can only act on a terminal that interprets it. Untrusted values
+   * interpolated into report lines are sanitized at their call site instead,
+   * so those stay safe whether or not stdout is a terminal.
    */
   output(...args: unknown[]): void {
+    if (process.stdout.isTTY) {
+      console.log(...args.map((arg) => this.neutralize(arg)));
+      return;
+    }
     console.log(...args);
   }
 
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index ad51b61b..777cc292 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -785,6 +785,27 @@ describe('CLI Sync E2E', () => {
       expect(result.status).toBe(8);
       expect(result.output.toLowerCase()).toMatch(/placeholder|welcome/);
     });
+
+    it('does not emit raw terminal control characters from a hostile i18n key', () => {
+      writeSyncConfig(testFiles.path, ['de']);
+      const dir = path.join(testFiles.path, 'locales');
+      fs.mkdirSync(dir, { recursive: true });
+      const hostileKey = 'welcome\u001b]52;c;cHduZWQ=\u0007\u001b[2J';
+      fs.writeFileSync(
+        path.join(dir, 'en.json'),
+        JSON.stringify({ [hostileKey]: 'Hello {name}' }, null, 2) + '\n'
+      );
+      fs.writeFileSync(
+        path.join(dir, 'de.json'),
+        JSON.stringify({ [hostileKey]: 'Hallo' }, null, 2) + '\n'
+      );
+
+      const result = runSyncExpectError('validate');
+      expect(result.status).toBe(8);
+      expect(result.output).toContain('welcome');
+      // eslint-disable-next-line no-control-regex -- asserting the absence of control chars in rendered output
+      expect(result.output).not.toMatch(/[\x00-\x08\x0b\x0c\x0e-\x1f]/);
+    });
   });
 
   describe('flag combination rejection', () => {
diff --git a/tests/unit/logger.test.ts b/tests/unit/logger.test.ts
index 468ed365..a6eef4ce 100644
--- a/tests/unit/logger.test.ts
+++ b/tests/unit/logger.test.ts
@@ -659,4 +659,91 @@ describe('Logger', () => {
       expect(logged['url']).toBe('https://host?api_key=[REDACTED]');
     });
   });
+
+  describe('terminal control sequence handling', () => {
+    const OSC_TITLE = '\x1b]0;PWNED\x07';
+    let originalIsTTY: boolean | undefined;
+
+    function setStdoutTTY(value: boolean | undefined): void {
+      Object.defineProperty(process.stdout, 'isTTY', {
+        value,
+        configurable: true,
+      });
+    }
+
+    beforeEach(() => {
+      originalIsTTY = process.stdout.isTTY;
+    });
+
+    afterEach(() => {
+      setStdoutTTY(originalIsTTY);
+    });
+
+    it('should neutralize escape sequences on stdout when stdout is a TTY', () => {
+      setStdoutTTY(true);
+      Logger.output(`${OSC_TITLE}Bonjour`);
+      expect(consoleLogSpy).toHaveBeenCalledWith('?]0;PWNED?Bonjour');
+    });
+
+    it('should neutralize a forged clean result built from erase and cursor moves', () => {
+      setStdoutTTY(true);
+      Logger.output('\x1b[2K\x1b[1;1HAll good');
+      expect(consoleLogSpy).toHaveBeenCalledWith('?[2K?[1;1HAll good');
+    });
+
+    it('should keep chalk colour codes on stdout when stdout is a TTY', () => {
+      setStdoutTTY(true);
+      Logger.output('\x1b[32mgreen\x1b[39m');
+      expect(consoleLogSpy).toHaveBeenCalledWith('\x1b[32mgreen\x1b[39m');
+    });
+
+    it('should keep piped stdout byte-faithful when stdout is not a TTY', () => {
+      setStdoutTTY(undefined);
+      const translated = `line one\nline two\tindented\nنمی\u200cخواهم${OSC_TITLE}`;
+      Logger.output(translated);
+      expect(consoleLogSpy).toHaveBeenCalledWith(translated);
+    });
+
+    it('should keep newlines and zero-width joiners in TTY stdout translations', () => {
+      setStdoutTTY(true);
+      Logger.output('erste Zeile\nzweite\tZeile\nنمی\u200cخواهم');
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'erste Zeile\nzweite\tZeile\nنمی\u200cخواهم'
+      );
+    });
+
+    it('should neutralize escape sequences nested in objects on TTY stdout', () => {
+      setStdoutTTY(true);
+      Logger.output({ text: `${OSC_TITLE}hi` });
+      expect(consoleLogSpy).toHaveBeenCalledWith({ text: '?]0;PWNED?hi' });
+    });
+
+    it('should neutralize escape sequences on stderr regardless of TTY', () => {
+      setStdoutTTY(undefined);
+      Logger.error(`API error: ${OSC_TITLE}`);
+      Logger.warn(`warn: ${OSC_TITLE}`);
+      Logger.info(`info: ${OSC_TITLE}`);
+      Logger.success(`success: ${OSC_TITLE}`);
+      Logger.setVerbose(true);
+      Logger.verbose(`verbose: ${OSC_TITLE}`);
+      expect(consoleErrorSpy.mock.calls.map((call) => call[0])).toEqual([
+        'API error: ?]0;PWNED?',
+        'warn: ?]0;PWNED?',
+        'info: ?]0;PWNED?',
+        'success: ?]0;PWNED?',
+        'verbose: ?]0;PWNED?',
+      ]);
+    });
+
+    it('should keep chalk colour codes on stderr', () => {
+      Logger.error('\x1b[31mred\x1b[39m');
+      expect(consoleErrorSpy).toHaveBeenCalledWith('\x1b[31mred\x1b[39m');
+    });
+
+    it('should neutralize escape sequences inside a redacted Error message', () => {
+      Logger.error(new Error(`boom ${OSC_TITLE} DeepL-Auth-Key secret-value`));
+      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Error;
+      expect(logged.message).toBe('boom ?]0;PWNED? DeepL-Auth-Key [REDACTED]');
+    });
+  });
 });
diff --git a/tests/unit/utils/control-chars.test.ts b/tests/unit/utils/control-chars.test.ts
index e86a6cd9..b4dad5ed 100644
--- a/tests/unit/utils/control-chars.test.ts
+++ b/tests/unit/utils/control-chars.test.ts
@@ -1,4 +1,7 @@
-import { sanitizeForTerminal } from '../../../src/utils/control-chars';
+import {
+  neutralizeTerminalControls,
+  sanitizeForTerminal,
+} from '../../../src/utils/control-chars';
 
 describe('sanitizeForTerminal', () => {
   it('replaces NUL bytes with ?', () => {
@@ -41,3 +44,81 @@ describe('sanitizeForTerminal', () => {
     expect(sanitizeForTerminal('\x00\x01\x02\x7f')).toBe('????');
   });
 });
+
+describe('neutralizeTerminalControls', () => {
+  it('neutralizes an OSC title-set sequence so the terminal cannot act on it', () => {
+    expect(neutralizeTerminalControls('\x1b]0;PWNED\x07done')).toBe(
+      '?]0;PWNED?done'
+    );
+  });
+
+  it('neutralizes an OSC 52 clipboard-write sequence', () => {
+    expect(neutralizeTerminalControls('\x1b]52;c;cm0=\x07')).toBe(
+      '?]52;c;cm0=?'
+    );
+  });
+
+  it('neutralizes CSI erase and cursor-movement sequences', () => {
+    expect(neutralizeTerminalControls('\x1b[2J\x1b[1;1H')).toBe('?[2J?[1;1H');
+  });
+
+  it('neutralizes a CSI 6n cursor-position query whose reply lands on the shell stdin', () => {
+    expect(neutralizeTerminalControls('\x1b[6n')).toBe('?[6n');
+  });
+
+  it('preserves SGR colour sequences so chalk output survives', () => {
+    expect(neutralizeTerminalControls('\x1b[31mred\x1b[0m')).toBe(
+      '\x1b[31mred\x1b[0m'
+    );
+  });
+
+  it('preserves truecolor SGR sequences in both semicolon and colon forms', () => {
+    expect(neutralizeTerminalControls('\x1b[38;2;1;2;3mx\x1b[39m')).toBe(
+      '\x1b[38;2;1;2;3mx\x1b[39m'
+    );
+    expect(neutralizeTerminalControls('\x1b[38:2::1:2:3mx')).toBe(
+      '\x1b[38:2::1:2:3mx'
+    );
+  });
+
+  it('preserves tabs, newlines and carriage returns so piped text keeps its structure', () => {
+    expect(neutralizeTerminalControls('a\tb\nc\r\nd')).toBe('a\tb\nc\r\nd');
+  });
+
+  it('preserves zero-width joiners and bidi marks that are legitimate translation content', () => {
+    // ZWNJ is orthographically required in Persian; LRM/RLM appear in DeepL's
+    // bidi output; ZWJ builds emoji sequences.
+    const persian = 'نمی\u200cخواهم';
+    const bidi = '\u200fשלום\u200e';
+    const emoji = '\u{1f468}\u200d\u{1f469}\u200d\u{1f467}';
+    expect(neutralizeTerminalControls(persian)).toBe(persian);
+    expect(neutralizeTerminalControls(bidi)).toBe(bidi);
+    expect(neutralizeTerminalControls(emoji)).toBe(emoji);
+  });
+
+  it('replaces C0 controls other than tab, newline and carriage return', () => {
+    expect(neutralizeTerminalControls('a\x00b\x07c\x08d\x0be\x1ff')).toBe(
+      'a?b?c?d?e?f'
+    );
+  });
+
+  it('replaces DEL', () => {
+    expect(neutralizeTerminalControls('bad\x7fthing')).toBe('bad?thing');
+  });
+
+  it('replaces C1 controls, including the single-byte CSI introducer', () => {
+    expect(neutralizeTerminalControls('a\u009b2Jb\u0090c\u009fd')).toBe(
+      'a?2Jb?c?d'
+    );
+  });
+
+  it('leaves plain text unchanged', () => {
+    expect(neutralizeTerminalControls('Grüße — 你好 123')).toBe(
+      'Grüße — 你好 123'
+    );
+  });
+
+  it('handles empty string', () => {
+    expect(neutralizeTerminalControls('')).toBe('');
+  });
+});
diff --git a/tests/unit/write-command.test.ts b/tests/unit/write-command.test.ts
index 8980ec54..8d496cce 100644
--- a/tests/unit/write-command.test.ts
+++ b/tests/unit/write-command.test.ts
@@ -935,6 +935,33 @@ describe('WriteCommand', () => {
       expect(selectConfig.choices.length).toBe(3); // Keep original + 2 unique
     });
 
+    it('should sanitize control characters in prompt labels while returning the raw text', async () => {
+      const hostile = 'Improved\u001b]0;PWNED\u0007 text.';
+      mockWriteService.improve.mockResolvedValue([
+        { text: hostile, targetLanguage: 'en-US' },
+      ]);
+      mockSelect.mockResolvedValue(0);
+
+      const result = await writeCommand.improveInteractive('Original text.', {
+        lang: 'en-us',
+        style: 'business',
+      });
+
+      const selectConfig = mockSelect.mock.calls[0]![0] as unknown as {
+        choices: Array<{ name: string; description: string }>;
+      };
+      const rendered = selectConfig.choices
+        .map((choice) => `${choice.name}${choice.description}`)
+        .join('');
+      // eslint-disable-next-line no-control-regex -- asserting the absence of control chars in prompt labels
+      expect(rendered).not.toMatch(/[\x00-\x08\x0b\x0c\x0e-\x1a\x1c-\x1f]/);
+      expect(selectConfig.choices[1]!.description).toBe(
+        'Improved?]0;PWNED? text.'
+      );
+      // The value handed back to the caller is untouched.
+      expect(result).toBe(hostile);
+    });
+
     it('should handle file input in interactive mode', async () => {
       await fs.mkdir(testDir, { recursive: true });
       const testFile = join(testDir, 'test.txt');

From 98defb7635fb938184deb2ae08f61b576f05f3ec Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 12:46:51 +0200
Subject: [PATCH 131/256] fix(sync): make sync export emit well-formed XLIFF
 for control characters in keys
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

escapeXml escaped &, <, > and " only, so a key holding a C0 control was
written straight into the id= and resname= attributes. C0 other than tab,
newline and carriage return has no representation at all in XML 1.0 — not
even as a character reference — so the export was not well-formed and a
translator's tool rejects the file whole rather than one unit. Those
characters are now replaced with ?, which costs one odd character in one id
instead of an unusable handoff file.

Independent of any hostile input: a tab, newline or carriage return inside a
key was emitted literally, and every conforming parser normalizes those to a
space inside an attribute value, so a multi-line key came back different from
the key that was exported. They are now emitted as &#9;, &#10; and &#13;,
which round-trip exactly.

C1 (U+0080-U+009F) is left alone, against the finding's suggestion to strip
it: those are valid XML 1.0 characters and round-trip unchanged, and an
export is a data file, so it is not mutated further than validity requires.
Control characters that make an XLIFF dangerous to cat are handled where the
bytes reach a terminal, not by rewriting the file.

Refs cli-8kr2.43

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                        |  2 ++
 docs/API.md                         |  2 ++
 src/sync/sync-export.ts             | 25 ++++++++++++++++++++-----
 tests/unit/sync/sync-export.test.ts | 27 +++++++++++++++++++++++++++
 4 files changed, 51 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a439736c..7a778cea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`sync export` produces well-formed XLIFF for keys that contain control characters, and no longer changes a key on the way out.** `escapeXml` escaped `&`, `<`, `>` and `"` only, so a key holding a C0 control was written straight into the `id=` and `resname=` attributes — and C0 other than tab, newline and carriage return has no representation at all in XML 1.0, not even as a character reference, so the file was not well-formed and a translator's tool would reject it whole. Those characters are now replaced with `?`, which costs one odd character in one id rather than an unreadable handoff file. Separately, and independent of any hostile input: a tab, newline or carriage return inside a key was emitted literally, and every conforming XML parser **normalizes those to a space inside an attribute value** — so a multi-line key silently came back different from the key that was exported. They are now emitted as `&#9;`, `&#10;` and `&#13;`, which round-trip exactly. C1 (U+0080–U+009F) is deliberately left alone: those are valid XML 1.0 characters that round-trip unchanged, and an export is a data file, so it is mutated no further than validity requires.
+
 - **sync**: **two syncs no longer run concurrently in the same directory, which is the entire purpose of the process lock.** Measured with six processes racing over a planted stale pidfile, 100 rounds: **93 rounds had overlapping lock holders before this change — up to five at once — and 0 do after.** Two independent defects had to be fixed to get there. First, the stale-pidfile reclaim was a read/unlink/create sequence with no atomicity, so a process whose staleness verdict had already been overtaken deleted the *live* pidfile the winner had just written, after which both held what each believed was an exclusive lock; and the create that followed the unlink was the one call not wrapped in the EEXIST handling, so a lost race surfaced as an unhandled `Error: EEXIST: file already exists, open '.deepl-sync.lock.pidfile'` instead of the intended "another sync is running". A stale file is now removed only after taking possession of it with `rename(2)` — atomic, so exactly one of several racers can move a given entry aside — and confirming the captured inode is the one proven stale; a process that captures a different file puts it back rather than deleting someone's lock. Acquisition always goes through the same guarded create, so a lost race reports the running sync, and the retry loop is bounded (5 attempts) with its own error rather than spinning. Second, and the defect that actually accounted for the remaining overlap once the reclaim was atomic: the pidfile was created empty through an `O_EXCL` descriptor and filled afterwards, leaving a window in which a **live** lock read as malformed — and malformed counts as stale, so a concurrent sync deleted it and took over. No identity check downstream can catch that, because the file it inspected really is the file it removed. The payload is now written to a private staging path and `link(2)`ed into place, which publishes the name and the content in one step and doubles as the atomic acquisition. CI relevance: a runner retrying a timed-out job is exactly the double-start trigger.
 
 - **sync**: **a failed backfill for a newly added locale no longer writes the source text in as the translation.** When a current key's translation failed while bootstrapping a new target locale, the backfill path pushed `{ translation: cd.value }` — the English source — and only incremented `failed`. Because any value present in the target file counts as an existing translation, those strings were then skipped on every later run: `sync status` reported `fr 17% (50 missing, 0 outdated)` while `deepl sync` said `60 current` and refused to retranslate them, and `sync validate` rated it a warning at exit 0. The tool reported the strings as missing *and* declined to fix them, permanently, with no error anywhere. The same file's main translation path already handled this correctly, and the guard comment 60 lines up spelled out the reason: "Writing the source value here would record untranslated text as translated, which no later run would correct." The backfill path now pushes nothing, so the key stays out of the target file and the next run picks it up. Nothing is recorded in the lockfile for it either — deliberately, since a `status: 'failed'` entry would make `sync status` count the key as *outdated* when it is genuinely *missing*, and would trip the "lockfile records a translation but the target file has none" path on every retry.
diff --git a/docs/API.md b/docs/API.md
index 3f10b485..9cd3498f 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3136,6 +3136,8 @@ Translations, i18n keys, glossary entries and API error messages can all contain
 
 Colour (SGR) sequences are preserved so `deepl` output stays readable; use [`NO_COLOR`](#no_color) to turn colour off. Tabs, newlines, carriage returns and Unicode formatting characters that are legitimate translation content — zero-width joiners, and the bidi marks used in Arabic, Hebrew and Persian text — are never altered on stdout.
 
+`deepl sync export` writes XLIFF rather than terminal output. There, tab, newline and carriage return are emitted as the character references `&#9;`, `&#10;` and `&#13;` so a key survives XML attribute-value normalization unchanged, and the remaining C0 control characters — which XML 1.0 cannot represent at all — are replaced with `?`.
+
 ---
 
 ## Environment Variables
diff --git a/src/sync/sync-export.ts b/src/sync/sync-export.ts
index 27f1ff4c..39fc9355 100644
--- a/src/sync/sync-export.ts
+++ b/src/sync/sync-export.ts
@@ -68,10 +68,25 @@ export async function exportTranslations(
   return { files: fileCount, keys: units.length, content: xliff };
 }
 
+/**
+ * Tab, newline and carriage return become numeric character references because
+ * an XML parser normalizes them to a space inside an attribute value, which
+ * would silently change a `trans-unit` id. The remaining C0 controls have no
+ * representation at all in XML 1.0 — not even as a character reference — so
+ * they are replaced. C1 (U+0080-U+009F) is left alone: those are valid XML 1.0
+ * characters and round-trip unchanged.
+ */
 function escapeXml(s: string): string {
-  return s
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
+  return (
+    s
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/\t/g, '&#9;')
+      .replace(/\n/g, '&#10;')
+      .replace(/\r/g, '&#13;')
+      // eslint-disable-next-line no-control-regex -- intentional: C0 controls have no XML 1.0 representation
+      .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '?')
+  );
 }
diff --git a/tests/unit/sync/sync-export.test.ts b/tests/unit/sync/sync-export.test.ts
index 1597e99e..78beaf17 100644
--- a/tests/unit/sync/sync-export.test.ts
+++ b/tests/unit/sync/sync-export.test.ts
@@ -106,6 +106,33 @@ describe('exportTranslations()', () => {
     expect(result.keys).toBe(3);
   });
 
+  it('should replace control characters that XML 1.0 cannot represent', async () => {
+    mockedFg.mockResolvedValue(['/project/locales/en/common.json'] as never);
+    mockedReadFile.mockResolvedValue(
+      JSON.stringify({ 'a\u001b]0;PWNED\u0007b': 'v\u0000w' })
+    );
+
+    const result = await exportTranslations(makeConfig(), makeRegistry());
+
+    // eslint-disable-next-line no-control-regex -- asserting the absence of control chars in generated XML
+    expect(result.content).not.toMatch(/[\x00-\x08\x0b\x0c\x0e-\x1f]/);
+    expect(result.content).toContain('id="a?]0;PWNED?b"');
+    expect(result.content).toContain('resname="a?]0;PWNED?b"');
+    expect(result.content).toContain('<source>v?w</source>');
+  });
+
+  it('should escape tab, newline and carriage return so attribute values survive XML normalization', async () => {
+    mockedFg.mockResolvedValue(['/project/locales/en/common.json'] as never);
+    mockedReadFile.mockResolvedValue(
+      JSON.stringify({ 'a\tb\nc\rd': 'one\ntwo' })
+    );
+
+    const result = await exportTranslations(makeConfig(), makeRegistry());
+
+    expect(result.content).toContain('id="a&#9;b&#10;c&#13;d"');
+    expect(result.content).toContain('<source>one&#10;two</source>');
+  });
+
   it('should handle empty bucket (no files matched)', async () => {
     mockedFg.mockResolvedValue([] as never);
 

From f71d808329d1e2e2813c502561ac1280f6ed6193 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 13:25:43 +0200
Subject: [PATCH 132/256] fix(api): bound response size and enforce a real
 wall-clock request deadline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The shared axios instance never set maxContentLength or maxBodyLength, which
axios defaults to -1 (unbounded), and `timeout` reaches the socket as an
inactivity timeout that every arriving chunk resets. All ten API clients
inherited both gaps.

Measured against a stub streaming 1MiB chunks forever with timeout: 5000 —
peak RSS 8572MB, still running un-aborted at 20s, four times past the
deadline; after, rejected in 24ms with RSS flat. A stub trickling one byte
per second proves a byte cap alone is not enough: it stays under any cap
indefinitely and also ran past 20s untouched, and now aborts at 5005ms. With
--max-retries 3 the whole call bounds at 10093ms, matching the twice-timeout
budget that was documented but only held for an endpoint that said nothing.

The finding proposed reusing the TMS client's single 32MiB cap. That would
have broken `deepl translate report.pdf --to de`: DeepL accepts documents up
to 30MB and a translated result can exceed its source when output_format
converts between types, and the result endpoint is single-use and never
retried, so rejecting there destroys an already-billed translation. The cap
is therefore 32MiB for responses generally, raised to 128MiB per request for
the document download via the RequestPolicy mechanism that already widens its
timeout; the request-body cap is 128MiB for every client so no legitimate
upload regresses. Verified that axios 1.18.1 enforces maxContentLength on the
buffered and arraybuffer paths alike, which is every path this repo uses.

A deadline abort is restated as the socket timeout it stands in for, because
axios surfaces a mid-body cancellation as a CanceledError still carrying the
200 response and classification reported that as `API error: canceled`. A
size-cap rejection is not replayed: the verdict is deterministic, so three
extra attempts on a 32MiB body were 128MiB of discarded transfer.

Refs cli-8kr2.17
---
 CHANGELOG.md                                  |   2 +
 docs/API.md                                   |   2 +
 src/api/document-client.ts                    |  12 +-
 src/api/http-client.ts                        | 104 ++++++++--
 .../http-transfer-limits.integration.test.ts  | 182 ++++++++++++++++++
 5 files changed, 289 insertions(+), 13 deletions(-)
 create mode 100644 tests/integration/http-transfer-limits.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a778cea..61c647ca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -377,6 +377,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **api**: **an endpoint that keeps sending is now bounded in both bytes and wall-clock time.** The shared axios instance set `baseURL`, `timeout` and agents but never `maxContentLength` or `maxBodyLength`, which axios defaults to `-1` — unbounded — so a response body was buffered into memory until the process died; all ten API clients inherited that. Worse, `--timeout` did not save the run, because axios delivers it to the socket as an *inactivity* timeout and this client goes out over the follow-redirects transport, where that is the only timeout armed: every arriving chunk reset it, so it never fired. Measured against a stub streaming 1 MiB chunks forever with `timeout: 5000`: **peak RSS 8572 MB and still running, un-aborted, at 20 s — four times past the configured deadline. After: rejected in 24 ms with RSS flat.** A second, nastier shape proves a size cap alone would not have been enough: a stub trickling **one byte per second** stays under any byte cap indefinitely while pinning the process, and also ran past 20 s untouched; it now aborts at 5005 ms, the configured timeout. With retries enabled the whole call is bounded too — 10093 ms for `--max-retries 3`, matching the twice-`--timeout` budget that was already documented but that only held for an endpoint which said nothing at all. Two changes, and the second is the load-bearing one. **A finite response cap of 32 MiB and body cap of 128 MiB on the shared instance**, verified to be enforced by axios on the buffered and `arraybuffer` paths alike, which is every path this repo uses. **An `AbortController` deadline armed per attempt inside the retry loop**, wall-clock and therefore not resettable by the peer. The caps are deliberately **not** the single 32 MiB used by `sync`'s TMS client, which the finding suggested reusing: DeepL accepts documents up to 30 MB and a translated result can exceed its source — `output_format` converts between types — so a 32 MiB response cap would have rejected a legitimate translated document on `deepl translate report.pdf --to de`, at the one endpoint whose result is single-use and deliberately never retried. Rejecting there destroys an already-billed translation permanently, so the cap would have caused the very data loss it was meant to prevent; the document download therefore raises its response cap to 128 MiB per request, riding the same `RequestPolicy` mechanism it already uses to widen `timeout`, while status polling and the other nine clients keep the tighter default. Two smaller consequences of the same work: a deadline abort is restated as the socket timeout it stands in for, because axios surfaces a mid-body cancellation as a `CanceledError` that still carries the 200 response and classification would have reported that as `API error: canceled` rather than a timeout; and a size-cap rejection is **not** retried, since the verdict is deterministic and replaying it only re-downloads bytes that will be discarded again — three extra attempts on a 32 MiB body were 128 MiB of pointless transfer. Both bounds surface as `NetworkError` (exit 5), the size cap naming the limit it hit rather than axios's internal `maxContentLength size of 33554432 exceeded`.
+
 - **cli, sync**: **text the CLI did not author can no longer drive the terminal that renders it.** Translation text went from the API to stdout raw, and i18n keys went from a checkout to stdout raw, so both could carry terminal control sequences. Measured against a stub endpoint with a real pty on stdout: the run emitted **4 raw ESC and 1 BEL before this change — setting the window title via OSC 0 and erasing the line via CSI 2K — and 2 ESC and 0 BEL after, both of them SGR colour**. The key sink needs no API key and no network: an evil checkout plus `deepl sync validate` exits 8 with an OSC 52 clipboard write and a CSI 2J screen erase verbatim in its output, and `hooks install` puts that command in the pre-commit hook, so it fires on every commit. `sanitizeForTerminal` already existed and was applied in ten other files, just not on the primary render paths. Two layers close it. **Untrusted values interpolated into report lines are sanitized at the call site, unconditionally**: the locale, key and message in `sync validate`, and the choice labels in `write --interactive` / `correct --interactive`, where the value handed back to the caller stays raw so only the display is affected. **The logger neutralizes control sequences centrally**, which covers all 111 `Logger.output` call sites, every stderr sink, and future ones by construction — including error paths that echo a hostile value, such as the JSON parser's duplicate-key report. stderr is sanitized whether or not it is a TTY, because a redirected stderr is still rendered by CI log viewers that interpret ANSI. **stdout is sanitized only when it is a terminal**, because redirected stdout is data: `deepl translate ... > out.txt` and `$(deepl translate ...)` must reproduce the API's bytes exactly, and a control sequence can only act on a terminal that interprets one — the same rule `ls` and `git` apply to nonprintables. Colour (SGR) sequences survive, since chalk-formatted strings are passed to the logger already rendered and stripping them would drop all colour; that concedes only text attributes, while the primitives that let injected text take over a session — OSC title and clipboard writes, CSI erase and cursor moves, and the status queries whose reply is typed back on the shell's stdin — are all neutralized. The stream filter is a **separate, narrower function** from `sanitizeForTerminal`, which cannot be used on a whole stream: it replaces newlines and tabs, and replaces U+200B–U+200F, so applying it to translation output would have turned every multi-line result into `?`-separated text and corrupted the ZWNJ, ZWJ and bidi marks that are legitimate content in Persian, Arabic, Devanagari and emoji sequences — silent corruption of the main command's output, in place of the bug being fixed.
 
 - **api**: a batch translation response that returns the submitted texts themselves, rearranged, is now refused instead of written out. `POST /v2/translate` correlates a translation to its request item by position and by nothing else, and the only check on the response was that it had the same number of entries — so an endpoint returning the request's own texts rotated by one wrote each translation under the wrong i18n key at exit 0, reporting full success. `{confirm_delete: 'Delete account permanently', cancel: 'Cancel', save: 'Save changes'}` came back as `{confirm_delete: 'Cancel', cancel: 'Save changes', save: 'Delete account permanently'}`, hiding a destructive action behind the cancel label; the placeholder validator cannot see it, because plain UI strings carry no placeholders to compare. Verified end to end against a rotating stub: exit 5 and no file written, where the same run previously exited 0 with the keys transposed, and an honest endpoint on the same fixture is unaffected. The check requires **both** that the returned texts are a multiset match for the submitted ones and that at least one has moved position, so it cannot fire on a legitimate identity translation (source language equal to target, where nothing moves) or on one item whose translation happens to equal another item's source text, which a partially translated file produces. It is deliberately narrow: this catches the one reordering that is provable from the response alone, and an endpoint returning plausible **translations** in the wrong order remains undetectable, because the protocol carries no per-item identity to verify. It applies to every batch caller — `translate` on all 11 structured i18n formats, plain-text batches, and `sync` — since it sits in the one client method they share.
diff --git a/docs/API.md b/docs/API.md
index 9cd3498f..655689e5 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -60,6 +60,8 @@ Options that work with all commands:
 
 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.
 
+`--timeout` is an enforced wall-clock deadline per attempt, not merely a socket inactivity timeout: an endpoint that keeps a response body trickling is aborted at the deadline just like one that never answers at all. Responses are additionally capped at 32 MiB, raised to 128 MiB for the document download, which must accommodate a whole translated file. Exceeding either bound is a `NetworkError` (exit code 5); a size-cap rejection is deterministic and is never retried.
+
 **Examples:**
 
 ```bash
diff --git a/src/api/document-client.ts b/src/api/document-client.ts
index 6e4bf905..540d72d5 100644
--- a/src/api/document-client.ts
+++ b/src/api/document-client.ts
@@ -1,4 +1,8 @@
-import { HttpClient, DeepLClientOptions } from './http-client.js';
+import {
+  HttpClient,
+  DeepLClientOptions,
+  MAX_TRANSFER_BYTES,
+} from './http-client.js';
 import {
   DocumentTranslationOptions,
   DocumentHandle,
@@ -155,7 +159,11 @@ export class DocumentClient extends HttpClient {
             responseType: 'arraybuffer',
           };
         },
-        { maxRetries: 0, timeout: this.transferTimeout }
+        {
+          maxRetries: 0,
+          timeout: this.transferTimeout,
+          maxContentLength: MAX_TRANSFER_BYTES,
+        }
       );
 
       return Buffer.from(response);
diff --git a/src/api/http-client.ts b/src/api/http-client.ts
index d35ea0c1..2b224b91 100644
--- a/src/api/http-client.ts
+++ b/src/api/http-client.ts
@@ -98,10 +98,41 @@ const CLIENT_ABORT_CODES = new Set([
   'ERR_CANCELED',
 ]);
 
-/** Per-request overrides for the retry policy and timeouts. */
+/**
+ * Ceiling on a buffered response body. Every DeepL endpoint except the
+ * document result returns JSON small enough to fit many times over; the cap
+ * exists so a hostile or malfunctioning endpoint cannot stream bytes into this
+ * process until it dies.
+ */
+export const MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
+
+/**
+ * Ceiling on a whole-file transfer. DeepL accepts documents up to 30MB and a
+ * translated result may exceed its source — notably when `output_format`
+ * converts between types — so the file paths need headroom the JSON paths do
+ * not. Applied as the request-body cap for every client and, per request, as
+ * the response cap for the document download.
+ */
+export const MAX_TRANSFER_BYTES = 128 * 1024 * 1024;
+
+/** Per-request overrides for the retry policy, timeouts and transfer caps. */
 export interface RequestPolicy {
   maxRetries?: number;
   timeout?: number;
+  maxContentLength?: number;
+}
+
+/**
+ * Whether axios refused a response for exceeding `maxContentLength`. The
+ * verdict is deterministic — the same endpoint returns the same oversized body
+ * — so a replay only re-downloads bytes that will be discarded again.
+ */
+function isResponseTooLarge(error: AxiosError): boolean {
+  return (
+    error.code === 'ERR_BAD_RESPONSE' &&
+    !error.response &&
+    /^maxContentLength size of \d+ exceeded$/.test(error.message ?? '')
+  );
 }
 
 /**
@@ -240,6 +271,12 @@ export class HttpClient {
     const axiosConfig: Record<string, unknown> = {
       baseURL,
       timeout: options.timeout ?? DEFAULT_TIMEOUT,
+      // Axios defaults both of these to -1, meaning unbounded, so a server that
+      // streams without end is buffered until the process dies. The response
+      // cap is deliberately the tighter of the two; the document download
+      // raises it per request.
+      maxContentLength: MAX_RESPONSE_BYTES,
+      maxBodyLength: MAX_TRANSFER_BYTES,
       headers: {
         Authorization: `DeepL-Auth-Key ${apiKey}`,
         'User-Agent': USER_AGENT,
@@ -390,6 +427,20 @@ export class HttpClient {
     let traceId: string | undefined;
 
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const attemptTimeout = Math.min(requestTimeout, remainingBudget);
+      // The axios `timeout` reaches the socket as an inactivity timeout, so a
+      // response body that trickles indefinitely resets it on every chunk and
+      // it never fires. This deadline is wall-clock and cannot be reset by the
+      // peer.
+      const controller = new AbortController();
+      let deadlineExpired = false;
+      const deadline =
+        attemptTimeout > 0
+          ? setTimeout(() => {
+              deadlineExpired = true;
+              controller.abort();
+            }, attemptTimeout)
+          : undefined;
       const requestStart = Date.now();
       try {
         const config = buildConfig();
@@ -398,7 +449,11 @@ export class HttpClient {
           method,
           url: path,
           ...config,
-          timeout: Math.min(requestTimeout, remainingBudget),
+          timeout: attemptTimeout,
+          signal: controller.signal,
+          ...(policy?.maxContentLength !== undefined && {
+            maxContentLength: policy.maxContentLength,
+          }),
         });
         const requestElapsed = Date.now() - requestStart;
         Logger.verbose(
@@ -413,21 +468,32 @@ export class HttpClient {
 
         return response.data;
       } catch (error) {
+        // An abort the deadline caused surfaces as a CanceledError that still
+        // carries the 200 response, which classification would report as an
+        // "API error". Restate it as the socket timeout it stands in for so
+        // every downstream decision — replay eligibility, classification,
+        // message — matches what a non-trickling timeout produces.
+        const failure = deadlineExpired
+          ? new AxiosError(
+              `timeout of ${attemptTimeout}ms exceeded`,
+              AxiosError.ETIMEDOUT
+            )
+          : error;
         remainingBudget -= Date.now() - requestStart;
-        lastError = error as Error;
+        lastError = failure as Error;
 
-        if (this.isAxiosError(error)) {
-          const responseTraceId = error.response?.headers?.['x-trace-id'] as
+        if (this.isAxiosError(failure)) {
+          const responseTraceId = failure.response?.headers?.['x-trace-id'] as
             string | undefined;
           if (responseTraceId) {
             traceId = responseTraceId;
             this._lastTraceId = responseTraceId;
           }
 
-          const status = error.response?.status;
+          const status = failure.response?.status;
           if (status === 429 && attempt < maxRetries) {
             const retryAfterDelay = this.parseRetryAfter(
-              error.response?.headers?.['retry-after'] as string | undefined
+              failure.response?.headers?.['retry-after'] as string | undefined
             );
             // Respect Retry-After verbatim when present; otherwise use
             // backoff with full jitter. Jitter prevents concurrent sync
@@ -441,18 +507,18 @@ export class HttpClient {
             continue;
           }
           if (status && status >= 400 && status < 500) {
-            throw this.handleError(error, undefined, traceId);
+            throw this.handleError(failure, undefined, traceId);
           }
         }
 
         if (
           attempt < maxRetries &&
           remainingBudget > 0 &&
-          this.isReplayable(method, error)
+          this.isReplayable(method, failure)
         ) {
           const delay = computeBackoffWithJitter(attempt);
-          const status = this.isAxiosError(error)
-            ? error.response?.status
+          const status = this.isAxiosError(failure)
+            ? failure.response?.status
             : undefined;
           Logger.verbose(
             `[verbose] HTTP ${method} ${path} retry ${attempt + 1}/${maxRetries} in ${delay}ms (${status ? `status ${status}` : 'network error'}, jitter backoff)`
@@ -462,6 +528,8 @@ export class HttpClient {
         }
 
         break;
+      } finally {
+        clearTimeout(deadline);
       }
     }
 
@@ -479,6 +547,9 @@ export class HttpClient {
     if (!this.isAxiosError(error)) {
       return false;
     }
+    if (isResponseTooLarge(error)) {
+      return false;
+    }
     if (!error.response && error.code && UNSENT_REQUEST_CODES.has(error.code)) {
       return true;
     }
@@ -576,6 +647,17 @@ export class HttpClient {
   }
 
   private transportError(error: AxiosError): NetworkError {
+    if (isResponseTooLarge(error)) {
+      const cap = error.config?.maxContentLength;
+      const limit =
+        typeof cap === 'number' && cap > 0
+          ? `${Math.round(cap / (1024 * 1024))}MiB`
+          : 'configured';
+      return new NetworkError(
+        `Network error: response body exceeded the ${limit} size limit`
+      );
+    }
+
     const detail = sanitizeForTerminal(error.message ?? '');
     const label =
       error.code && CLIENT_ABORT_CODES.has(error.code)
diff --git a/tests/integration/http-transfer-limits.integration.test.ts b/tests/integration/http-transfer-limits.integration.test.ts
new file mode 100644
index 00000000..da81b72a
--- /dev/null
+++ b/tests/integration/http-transfer-limits.integration.test.ts
@@ -0,0 +1,182 @@
+import * as http from 'http';
+import type { AddressInfo } from 'net';
+import nock from 'nock';
+import {
+  HttpClient,
+  MAX_RESPONSE_BYTES,
+  MAX_TRANSFER_BYTES,
+  RequestPolicy,
+} from '../../src/api/http-client';
+import { DocumentClient } from '../../src/api/document-client';
+import { NetworkError } from '../../src/utils/errors';
+
+class TestHttpClient extends HttpClient {
+  requestsFor<T>(path: string, policy?: RequestPolicy): Promise<T> {
+    return this.makeRawRequest<T>('GET', path, () => ({}), policy);
+  }
+
+  get axiosDefaults(): Record<string, unknown> {
+    return this.client.defaults;
+  }
+}
+
+interface Harness {
+  url: string;
+  requestCount: () => number;
+  close: () => Promise<void>;
+}
+
+async function startServer(
+  handler: (req: http.IncomingMessage, res: http.ServerResponse) => void
+): Promise<Harness> {
+  let requests = 0;
+  const sockets = new Set<import('net').Socket>();
+  const server = http.createServer((req, res) => {
+    requests++;
+    handler(req, res);
+  });
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+  });
+  server.on('clientError', () => {});
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address() as AddressInfo;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    requestCount: () => requests,
+    close: () =>
+      new Promise<void>((resolve) => {
+        for (const socket of sockets) socket.destroy();
+        server.close(() => resolve());
+      }),
+  };
+}
+
+describe('HttpClient transfer limits', () => {
+  let harness: Harness | undefined;
+  let client: TestHttpClient | undefined;
+
+  beforeEach(() => {
+    // setup.ts disables net connect globally; these cases need the real
+    // loopback server because nock cannot trickle a body.
+    nock.enableNetConnect('127.0.0.1');
+  });
+
+  afterEach(async () => {
+    client?.destroy();
+    client = undefined;
+    await harness?.close();
+    harness = undefined;
+  });
+
+  describe('configured caps', () => {
+    it('should apply a finite response and body cap to the shared axios instance', () => {
+      client = new TestHttpClient('test-key');
+
+      expect(client.axiosDefaults['maxContentLength']).toBe(MAX_RESPONSE_BYTES);
+      expect(client.axiosDefaults['maxBodyLength']).toBe(MAX_TRANSFER_BYTES);
+    });
+  });
+
+  describe('oversized response bodies', () => {
+    it('should reject a body larger than the cap instead of buffering it', async () => {
+      harness = await startServer((_req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ pad: 'x'.repeat(16 * 1024) }));
+      });
+      client = new TestHttpClient('test-key', {
+        baseUrl: harness.url,
+        maxRetries: 0,
+      });
+
+      await expect(
+        client.requestsFor('/v2/usage', { maxContentLength: 1024 })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('should name the exceeded limit rather than surface the axios internal', async () => {
+      harness = await startServer((_req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ pad: 'x'.repeat(4 * 1024 * 1024) }));
+      });
+      client = new TestHttpClient('test-key', {
+        baseUrl: harness.url,
+        maxRetries: 0,
+      });
+
+      await expect(
+        client.requestsFor('/v2/usage', { maxContentLength: 1024 * 1024 })
+      ).rejects.toThrow(/response body exceeded the 1MiB size limit/);
+    });
+
+    it('should not replay a size-cap rejection on an idempotent method', async () => {
+      harness = await startServer((_req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ pad: 'x'.repeat(16 * 1024) }));
+      });
+      client = new TestHttpClient('test-key', {
+        baseUrl: harness.url,
+        maxRetries: 3,
+      });
+
+      await expect(
+        client.requestsFor('/v2/usage', { maxContentLength: 1024 })
+      ).rejects.toThrow(NetworkError);
+      expect(harness.requestCount()).toBe(1);
+    });
+  });
+
+  describe('trickling response bodies', () => {
+    it('should abort on the request deadline even while bytes keep arriving', async () => {
+      harness = await startServer((_req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.write('{"pad":"');
+        const timer = setInterval(() => res.write('x'), 20);
+        res.on('close', () => clearInterval(timer));
+      });
+      client = new TestHttpClient('test-key', {
+        baseUrl: harness.url,
+        timeout: 300,
+        maxRetries: 0,
+      });
+
+      const start = Date.now();
+      await expect(client.requestsFor('/v2/usage')).rejects.toThrow(
+        /Network timeout/
+      );
+      expect(Date.now() - start).toBeLessThan(3000);
+    }, 15000);
+  });
+
+  describe('DocumentClient', () => {
+    it('should raise the response cap for the single-use download only', async () => {
+      const documentClient = new DocumentClient('test-key');
+      const spy = jest
+        .spyOn(
+          documentClient as unknown as {
+            executeWithRetry: (
+              method: string,
+              path: string,
+              buildConfig: () => Record<string, unknown>,
+              policy?: RequestPolicy
+            ) => Promise<unknown>;
+          },
+          'executeWithRetry'
+        )
+        .mockResolvedValue(Buffer.from('translated'));
+
+      await documentClient.downloadDocument({
+        documentId: 'doc-1',
+        documentKey: 'key-1',
+      });
+
+      expect(spy.mock.calls[0]?.[3]).toEqual({
+        maxRetries: 0,
+        timeout: 300_000,
+        maxContentLength: MAX_TRANSFER_BYTES,
+      });
+      documentClient.destroy();
+    });
+  });
+});

From 443a3fbce7f0b252b4a9af750a5a8d84192325ff Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 13:35:57 +0200
Subject: [PATCH 133/256] fix(sync): stop a __proto__ i18n key from vanishing
 from the lockfile
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every write into the lockfile's entry maps was a plain assignment, and for
that one key name the assignment reaches the prototype setter instead of
creating a property. A source file holding {greeting, __proto__, normal}
synced as "3/3 keys" and wrote all three translations, but the lockfile came
back with two entries and "total_keys": 2 — so every later run diffed the
missing key as new, sent it, and was billed again, never converging. A source
path named __proto__ fell out of lockFile.entries wholesale, taking every key
in that file with it.

Only the serialization side of this had been fixed, and by then the key is
already gone. Three shared accessors in sync-lock.ts now cover all fourteen
access sites, following the setOwn pattern formats/json.ts already uses for
the same hazard on the translation side.

The read side needed guarding for a reason the finding did not cover: plain
indexing hands back inherited Object.prototype members, so keys named
constructor, toString, valueOf or hasOwnProperty read as an existing entry
missing every field. computeDiff classified all four as stale rather than new
on a first sync, and one path would have dereferenced .translations on Object
itself had a hash ever matched. Two sites beyond the finding's list needed it
too, in sync-status.ts and sync-locale-translator.ts.

sync-status.test.ts was the one sibling using a bare automock of sync-lock,
which also replaced the module's pure accessors; narrowed to stub only
SyncLockManager, matching its three sibling files.

Refs cli-8kr2.19
---
 CHANGELOG.md                                  |   2 +
 src/sync/sync-differ.ts                       |   4 +-
 src/sync/sync-locale-translator.ts            |   3 +-
 src/sync/sync-lock.ts                         |  49 +++-
 src/sync/sync-process-bucket.ts               |  32 +--
 src/sync/sync-status.ts                       |   6 +-
 src/sync/sync-tms.ts                          |  16 +-
 .../sync-prototype-keys.integration.test.ts   | 218 ++++++++++++++++++
 tests/unit/sync/sync-status.test.ts           |   7 +-
 9 files changed, 309 insertions(+), 28 deletions(-)
 create mode 100644 tests/integration/sync-prototype-keys.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 61c647ca..8ff59415 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -377,6 +377,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync**: **an i18n key named `__proto__` is now recorded in the lockfile instead of vanishing from it, so it is no longer re-translated and re-billed on every run, forever.** Every write into the lockfile's entry maps was a plain assignment — `fileEntryMap[diff.key] = {...}` in `sync-process-bucket.ts` and `sync-tms.ts`, `lockFile.entries[filePath][key] = entry` in `sync-lock.ts` — and for that one key name the assignment reaches the prototype setter rather than creating a property. With `locales/en.json` holding `{greeting, __proto__, normal}`, `deepl sync` reported `3/3 keys` and wrote all three translations into `de.json`, but the lockfile came back with two entries and `"total_keys": 2`; each subsequent run diffed the missing key as new, sent it to the API, and was billed for it again, with no run ever converging. The hazard was already documented one file over — `sync-lock.ts` carries a null-prototype comment about exactly this — but only the **serialization** side had been fixed, and by the time serialization runs the key is already gone. The same shape applied to a **source path** named `__proto__`, which fell out of `lockFile.entries` wholesale, taking every key in that file with it. Fixed with three shared accessors in `sync-lock.ts` (`setOwnMember` / `getOwnMember` / `ensureFileEntries`) applied at all fourteen access sites across six files, following the `setOwn` pattern `formats/json.ts` already uses for this hazard on the translation side. The read side needed the same treatment and for a **different** reason the finding did not cover: plain indexing hands back inherited `Object.prototype` members, so keys named `constructor`, `toString`, `valueOf` or `hasOwnProperty` read as an existing lock entry that is missing every field it should have — `computeDiff` classified all four as **stale** rather than new on a first sync (`newKeys: 0, staleKeys: 4` where both should have been 4/0), and one code path would have dereferenced `.translations` on `Object` itself had a hash ever matched. Two sites beyond the fourteen the finding listed also needed it, in `sync-status.ts` and `sync-locale-translator.ts`. Verified end to end against a recording stub: the key is translated once, the lockfile round-trips all three entries with `total_keys: 3`, `de.json` holds the translated value as an own property, and a second sync sends **no** request and reports 3 current keys.
+
 - **api**: **an endpoint that keeps sending is now bounded in both bytes and wall-clock time.** The shared axios instance set `baseURL`, `timeout` and agents but never `maxContentLength` or `maxBodyLength`, which axios defaults to `-1` — unbounded — so a response body was buffered into memory until the process died; all ten API clients inherited that. Worse, `--timeout` did not save the run, because axios delivers it to the socket as an *inactivity* timeout and this client goes out over the follow-redirects transport, where that is the only timeout armed: every arriving chunk reset it, so it never fired. Measured against a stub streaming 1 MiB chunks forever with `timeout: 5000`: **peak RSS 8572 MB and still running, un-aborted, at 20 s — four times past the configured deadline. After: rejected in 24 ms with RSS flat.** A second, nastier shape proves a size cap alone would not have been enough: a stub trickling **one byte per second** stays under any byte cap indefinitely while pinning the process, and also ran past 20 s untouched; it now aborts at 5005 ms, the configured timeout. With retries enabled the whole call is bounded too — 10093 ms for `--max-retries 3`, matching the twice-`--timeout` budget that was already documented but that only held for an endpoint which said nothing at all. Two changes, and the second is the load-bearing one. **A finite response cap of 32 MiB and body cap of 128 MiB on the shared instance**, verified to be enforced by axios on the buffered and `arraybuffer` paths alike, which is every path this repo uses. **An `AbortController` deadline armed per attempt inside the retry loop**, wall-clock and therefore not resettable by the peer. The caps are deliberately **not** the single 32 MiB used by `sync`'s TMS client, which the finding suggested reusing: DeepL accepts documents up to 30 MB and a translated result can exceed its source — `output_format` converts between types — so a 32 MiB response cap would have rejected a legitimate translated document on `deepl translate report.pdf --to de`, at the one endpoint whose result is single-use and deliberately never retried. Rejecting there destroys an already-billed translation permanently, so the cap would have caused the very data loss it was meant to prevent; the document download therefore raises its response cap to 128 MiB per request, riding the same `RequestPolicy` mechanism it already uses to widen `timeout`, while status polling and the other nine clients keep the tighter default. Two smaller consequences of the same work: a deadline abort is restated as the socket timeout it stands in for, because axios surfaces a mid-body cancellation as a `CanceledError` that still carries the 200 response and classification would have reported that as `API error: canceled` rather than a timeout; and a size-cap rejection is **not** retried, since the verdict is deterministic and replaying it only re-downloads bytes that will be discarded again — three extra attempts on a 32 MiB body were 128 MiB of pointless transfer. Both bounds surface as `NetworkError` (exit 5), the size cap naming the limit it hit rather than axios's internal `maxContentLength size of 33554432 exceeded`.
 
 - **cli, sync**: **text the CLI did not author can no longer drive the terminal that renders it.** Translation text went from the API to stdout raw, and i18n keys went from a checkout to stdout raw, so both could carry terminal control sequences. Measured against a stub endpoint with a real pty on stdout: the run emitted **4 raw ESC and 1 BEL before this change — setting the window title via OSC 0 and erasing the line via CSI 2K — and 2 ESC and 0 BEL after, both of them SGR colour**. The key sink needs no API key and no network: an evil checkout plus `deepl sync validate` exits 8 with an OSC 52 clipboard write and a CSI 2J screen erase verbatim in its output, and `hooks install` puts that command in the pre-commit hook, so it fires on every commit. `sanitizeForTerminal` already existed and was applied in ten other files, just not on the primary render paths. Two layers close it. **Untrusted values interpolated into report lines are sanitized at the call site, unconditionally**: the locale, key and message in `sync validate`, and the choice labels in `write --interactive` / `correct --interactive`, where the value handed back to the caller stays raw so only the display is affected. **The logger neutralizes control sequences centrally**, which covers all 111 `Logger.output` call sites, every stderr sink, and future ones by construction — including error paths that echo a hostile value, such as the JSON parser's duplicate-key report. stderr is sanitized whether or not it is a TTY, because a redirected stderr is still rendered by CI log viewers that interpret ANSI. **stdout is sanitized only when it is a terminal**, because redirected stdout is data: `deepl translate ... > out.txt` and `$(deepl translate ...)` must reproduce the API's bytes exactly, and a control sequence can only act on a terminal that interprets one — the same rule `ls` and `git` apply to nonprintables. Colour (SGR) sequences survive, since chalk-formatted strings are passed to the logger already rendered and stripping them would drop all colour; that concedes only text attributes, while the primitives that let injected text take over a session — OSC title and clipboard writes, CSI erase and cursor moves, and the status queries whose reply is typed back on the shell's stdin — are all neutralized. The stream filter is a **separate, narrower function** from `sanitizeForTerminal`, which cannot be used on a whole stream: it replaces newlines and tabs, and replaces U+200B–U+200F, so applying it to translation output would have turned every multi-line result into `?`-separated text and corrupted the ZWNJ, ZWJ and bidi marks that are legitimate content in Persian, Arabic, Devanagari and emoji sequences — silent corruption of the main command's output, in place of the bug being fixed.
diff --git a/src/sync/sync-differ.ts b/src/sync/sync-differ.ts
index b47e9fd6..437a958a 100644
--- a/src/sync/sync-differ.ts
+++ b/src/sync/sync-differ.ts
@@ -1,6 +1,6 @@
 import type { ExtractedEntry } from '../formats/format.js';
 import type { SyncLockEntry, SyncDiff } from './types.js';
-import { computeSourceHash } from './sync-lock.js';
+import { computeSourceHash, getOwnMember } from './sync-lock.js';
 
 /**
  * Is any of `targetLocales` out of date for this entry?
@@ -38,7 +38,7 @@ export function computeDiff(
   const diffs: SyncDiff[] = [];
 
   for (const [key, entry] of currentMap) {
-    const lockEntry = lockEntries[key];
+    const lockEntry = getOwnMember(lockEntries, key);
     if (!lockEntry) {
       diffs.push({
         key,
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 5cde5cf8..5c0a649f 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -15,6 +15,7 @@ import {
   mergeInstructions,
   generateLengthInstruction,
 } from './sync-instructions.js';
+import { getOwnMember } from './sync-lock.js';
 import { validateBatch } from './translation-validator.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
@@ -598,7 +599,7 @@ export class LocaleTranslator {
     for (const cd of currentDiffs) {
       if (cd.value === undefined) continue;
       const existingTranslation = existingTranslations.get(cd.key);
-      const lockEntry = fileLockEntries[cd.key];
+      const lockEntry = getOwnMember(fileLockEntries, cd.key);
       const hasLocaleTranslation =
         lockEntry?.translations[locale] !== undefined;
       if (existingTranslation !== undefined) {
diff --git a/src/sync/sync-lock.ts b/src/sync/sync-lock.ts
index b53c21d5..2aac219d 100644
--- a/src/sync/sync-lock.ts
+++ b/src/sync/sync-lock.ts
@@ -5,6 +5,50 @@ import { Logger } from '../utils/logger.js';
 import type { SyncLockFile, SyncLockEntry } from './types.js';
 import { LOCK_FILE_VERSION, LOCK_FILE_COMMENT } from './types.js';
 
+/**
+ * Stores an own, enumerable member. Plain assignment cannot be used: an i18n
+ * key or a source path named `__proto__` reaches the prototype setter instead
+ * of creating a property, so the member never lands in the lockfile and the key
+ * is re-translated and re-billed on every run.
+ */
+export function setOwnMember<T>(
+  map: Record<string, T>,
+  key: string,
+  value: T
+): void {
+  Object.defineProperty(map, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}
+
+/**
+ * Reads a member only when the map actually holds one. Plain indexing hands
+ * back inherited `Object.prototype` members for keys named `constructor`,
+ * `toString`, `valueOf` and `hasOwnProperty`, which read as an existing entry
+ * that happens to be missing every field it should have.
+ */
+export function getOwnMember<T>(
+  map: Record<string, T>,
+  key: string
+): T | undefined {
+  return Object.hasOwn(map, key) ? map[key] : undefined;
+}
+
+/** The per-file entry map, created on demand and setter-proof either way. */
+export function ensureFileEntries(
+  lockFile: SyncLockFile,
+  filePath: string
+): Record<string, SyncLockEntry> {
+  const existing = getOwnMember(lockFile.entries, filePath);
+  if (existing) return existing;
+  const created: Record<string, SyncLockEntry> = {};
+  setOwnMember(lockFile.entries, filePath, created);
+  return created;
+}
+
 function filesystemSafeTimestamp(): string {
   return new Date().toISOString().replace(/:/g, '-').replace(/\.\d+/, '');
 }
@@ -210,15 +254,14 @@ export class SyncLockManager {
     entry: SyncLockEntry
   ): Promise<void> {
     const lockFile = await this.read();
-    lockFile.entries[filePath] ??= {};
-    lockFile.entries[filePath][key] = entry;
+    setOwnMember(ensureFileEntries(lockFile, filePath), key, entry);
     bumpMutationVersion(lockFile);
     await this.write(lockFile);
   }
 
   async removeEntry(filePath: string, key: string): Promise<void> {
     const lockFile = await this.read();
-    const fileEntries = lockFile.entries[filePath];
+    const fileEntries = getOwnMember(lockFile.entries, filePath);
     if (fileEntries) {
       delete fileEntries[key];
       if (Object.keys(fileEntries).length === 0) {
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index 5b51715a..ab4d0efa 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -7,7 +7,12 @@ import {
 } from '../utils/concurrency.js';
 import { ValidationError } from '../utils/errors.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
-import { computeSourceHash } from './sync-lock.js';
+import {
+  computeSourceHash,
+  ensureFileEntries,
+  getOwnMember,
+  setOwnMember,
+} from './sync-lock.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncLockFile, SyncLockTranslation } from './types.js';
 import type { KeyContext } from './sync-context.js';
@@ -97,7 +102,7 @@ export async function processBucket(
 
   const out: BucketContribution = { ...EMPTY, fileResults: [] };
 
-  const fileLockEntries = lockFile.entries[relPath] ?? {};
+  const fileLockEntries = getOwnMember(lockFile.entries, relPath) ?? {};
   // Pass the configured locales so staleness is judged per locale: a key whose
   // source is unchanged still needs work if any target locale's stored hash
   // lags behind, or if that locale previously failed.
@@ -137,7 +142,8 @@ export async function processBucket(
     if (localeFilter?.length && !localeFilter.includes(locale)) return false;
     return diffs.some(
       (d) =>
-        d.status === 'current' && !fileLockEntries[d.key]?.translations[locale]
+        d.status === 'current' &&
+        !getOwnMember(fileLockEntries, d.key)?.translations[locale]
     );
   });
 
@@ -185,7 +191,7 @@ export async function processBucket(
         diffs.some(
           (d) =>
             d.status === 'current' &&
-            !fileLockEntries[d.key]?.translations[locale]
+            !getOwnMember(fileLockEntries, d.key)?.translations[locale]
         )
       ).length;
       out.estimatedCharactersDelta += currentChars * newLocaleCount;
@@ -194,7 +200,7 @@ export async function processBucket(
   }
 
   if (deletedDiffs.length > 0) {
-    const fileEntryMap = (lockFile.entries[relPath] ??= {});
+    const fileEntryMap = ensureFileEntries(lockFile, relPath);
     for (const diff of deletedDiffs) {
       delete fileEntryMap[diff.key];
     }
@@ -240,7 +246,7 @@ export async function processBucket(
         diffs.some(
           (d) =>
             d.status === 'current' &&
-            !fileLockEntries[d.key]?.translations[locale]
+            !getOwnMember(fileLockEntries, d.key)?.translations[locale]
         )
       ).length;
       estimatedChars += currentChars * newLocaleCount;
@@ -415,10 +421,10 @@ export async function processBucket(
     concurrency
   );
 
-  const fileEntryMap = (lockFile.entries[relPath] ??= {});
+  const fileEntryMap = ensureFileEntries(lockFile, relPath);
   for (const diff of toTranslate) {
     if (diff.value === undefined) continue;
-    const existingEntry = fileEntryMap[diff.key];
+    const existingEntry = getOwnMember(fileEntryMap, diff.key);
     const existingTranslations = existingEntry?.translations ?? {};
 
     const newTranslations: Record<string, SyncLockTranslation> = {
@@ -440,11 +446,11 @@ export async function processBucket(
       };
     }
 
-    fileEntryMap[diff.key] = {
+    setOwnMember(fileEntryMap, diff.key, {
       source_hash: computeSourceHash(diff.value, diff.metadata),
       source_text: diff.value,
       translations: newTranslations,
-    };
+    });
     out.lockDirty = true;
   }
 
@@ -453,7 +459,7 @@ export async function processBucket(
     if (diff.status !== 'current' || diff.value === undefined) continue;
     const successSet = localeSuccessMap.get(diff.key);
     if (!successSet || successSet.size === 0) continue;
-    const existingEntry = fileEntryMap[diff.key];
+    const existingEntry = getOwnMember(fileEntryMap, diff.key);
     const existingTranslations = existingEntry?.translations ?? {};
     let updated = false;
     const newTranslations = { ...existingTranslations };
@@ -472,11 +478,11 @@ export async function processBucket(
       }
     }
     if (updated) {
-      fileEntryMap[diff.key] = {
+      setOwnMember(fileEntryMap, diff.key, {
         source_hash: computeSourceHash(diff.value, diff.metadata),
         source_text: diff.value,
         translations: newTranslations,
-      };
+      });
       out.lockDirty = true;
     }
   }
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index c045370f..ebb2345b 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -1,6 +1,6 @@
 import * as path from 'path';
 import type { FormatRegistry } from '../formats/index.js';
-import { SyncLockManager } from './sync-lock.js';
+import { SyncLockManager, getOwnMember } from './sync-lock.js';
 import { computeDiff } from './sync-differ.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import { LOCK_FILE_NAME } from './types.js';
@@ -50,7 +50,7 @@ export async function computeSyncStatus(
     totalKeys += entries.length + skippedEntries.length;
     skippedKeys += skippedEntries.length;
 
-    const fileLockEntries = lockFile.entries[relPath] ?? {};
+    const fileLockEntries = getOwnMember(lockFile.entries, relPath) ?? {};
     const diffs = computeDiff(fileLockEntries, entries);
 
     for (const locale of config.target_locales) {
@@ -59,7 +59,7 @@ export async function computeSyncStatus(
 
       for (const diff of diffs) {
         if (diff.status === 'deleted') continue;
-        const lockEntry = fileLockEntries[diff.key];
+        const lockEntry = getOwnMember(fileLockEntries, diff.key);
         const translation = lockEntry?.translations[locale];
         const hasTranslation = translation !== undefined;
         // Judge staleness for THIS locale rather than inheriting the shared
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index 8e8cdbbd..e9be9117 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -3,7 +3,13 @@ import * as path from 'path';
 import type { ExtractedEntry, FormatRegistry } from '../formats/index.js';
 import type { TmsClient } from './tms-client.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
-import { SyncLockManager, computeSourceHash } from './sync-lock.js';
+import {
+  SyncLockManager,
+  computeSourceHash,
+  ensureFileEntries,
+  getOwnMember,
+  setOwnMember,
+} from './sync-lock.js';
 import {
   resolveTargetPath,
   assertPathWithinRoot,
@@ -248,12 +254,12 @@ export async function pullTranslations(
       await atomicWriteFile(targetAbsPath, reconstructed, 'utf-8');
       pulled += pulledEntries.length;
 
-      const fileEntryMap = (lockFile.entries[relPath] ??= {});
+      const fileEntryMap = ensureFileEntries(lockFile, relPath);
       for (const entry of pulledEntries) {
-        const existing = fileEntryMap[entry.key];
+        const existing = getOwnMember(fileEntryMap, entry.key);
         const existingTranslations = existing?.translations ?? {};
         const sourceHash = computeSourceHash(entry.value, entry.metadata);
-        fileEntryMap[entry.key] = {
+        setOwnMember(fileEntryMap, entry.key, {
           source_hash: sourceHash,
           source_text: existing?.source_text ?? entry.value,
           translations: {
@@ -265,7 +271,7 @@ export async function pullTranslations(
               review_status: 'human_reviewed' as const,
             },
           },
-        };
+        });
       }
     }
   }
diff --git a/tests/integration/sync-prototype-keys.integration.test.ts b/tests/integration/sync-prototype-keys.integration.test.ts
new file mode 100644
index 00000000..17640c00
--- /dev/null
+++ b/tests/integration/sync-prototype-keys.integration.test.ts
@@ -0,0 +1,218 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as querystring from 'querystring';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+import { SyncService } from '../../src/sync/sync-service';
+import { TranslationService } from '../../src/services/translation';
+import { GlossaryService } from '../../src/services/glossary';
+import { DeepLClient } from '../../src/api/deepl-client';
+import { FormatRegistry } from '../../src/formats/index';
+import { JsonFormatParser } from '../../src/formats/json';
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { SyncLockManager } from '../../src/sync/sync-lock';
+import { LOCK_FILE_NAME } from '../../src/sync/types';
+import type { SyncLockEntry } from '../../src/sync/types';
+import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
+
+const CONFIG_YAML = `version: 1
+source_locale: en
+target_locales:
+  - de
+buckets:
+  json:
+    include:
+      - "locales/en.json"
+`;
+
+function getTexts(body: unknown): string[] {
+  const parsed =
+    typeof body === 'string'
+      ? (querystring.parse(body) as Record<string, string | string[]>)
+      : (body as Record<string, string | string[]>);
+  const text = parsed['text'];
+  return Array.isArray(text) ? text : text ? [text] : [];
+}
+
+function createServices(): { client: DeepLClient; syncService: SyncService } {
+  const client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
+  const mockConfig = createMockConfigService({
+    get: jest.fn(() => ({
+      auth: {},
+      api: { baseUrl: '', usePro: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
+      cache: { enabled: false },
+      output: { format: 'text', color: true },
+      proxy: {},
+    })),
+    getValue: jest.fn(() => false),
+  });
+  const registry = new FormatRegistry();
+  registry.register(new JsonFormatParser());
+  const syncService = new SyncService(
+    new TranslationService(client, mockConfig, createMockCacheService()),
+    new GlossaryService(client),
+    registry
+  );
+  return { client, syncService };
+}
+
+describe('Sync with prototype-named i18n keys', () => {
+  let tmpDir: string;
+  let client: DeepLClient;
+  let syncService: SyncService;
+  let sentTexts: string[][];
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-proto-'));
+    const services = createServices();
+    client = services.client;
+    syncService = services.syncService;
+    sentTexts = [];
+    nock(DEEPL_FREE_API_URL)
+      .persist()
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => {
+        const texts = getTexts(body);
+        sentTexts.push(texts);
+        return {
+          translations: texts.map((t) => ({
+            text: `de:${t}`,
+            detected_source_language: 'EN',
+            billed_characters: t.length,
+          })),
+        };
+      });
+  });
+
+  afterEach(() => {
+    client.destroy();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  function writeSource(keys: Record<string, string>): void {
+    fs.writeFileSync(path.join(tmpDir, '.deepl-sync.yaml'), CONFIG_YAML);
+    const absPath = path.join(tmpDir, 'locales', 'en.json');
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, JSON.stringify(keys, null, 2) + '\n', 'utf-8');
+  }
+
+  function readLock(): {
+    entries: Record<string, Record<string, SyncLockEntry>>;
+    stats: { total_keys: number };
+  } {
+    return JSON.parse(
+      fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8')
+    );
+  }
+
+  it('should record a __proto__ key in the lockfile so it is not re-translated forever', async () => {
+    writeSource({
+      greeting: 'Hello',
+      ['__proto__']: 'Polluted',
+      normal: 'World',
+    });
+    const config = await loadSyncConfig(tmpDir);
+
+    const first = await syncService.sync(config);
+    expect(first.success).toBe(true);
+    expect(sentTexts.flat()).toContain('Polluted');
+
+    const lockEntries = readLock().entries['locales/en.json'];
+    expect(Object.keys(lockEntries ?? {}).sort()).toEqual([
+      '__proto__',
+      'greeting',
+      'normal',
+    ]);
+    expect(readLock().stats.total_keys).toBe(3);
+
+    const translated = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'locales', 'de.json'), 'utf-8')
+    ) as Record<string, string>;
+    expect(Object.hasOwn(translated, '__proto__')).toBe(true);
+    expect(
+      Object.getOwnPropertyDescriptor(translated, '__proto__')?.value
+    ).toBe('de:Polluted');
+
+    sentTexts = [];
+    const second = await syncService.sync(await loadSyncConfig(tmpDir));
+    expect(second.success).toBe(true);
+    expect(sentTexts.flat()).toEqual([]);
+    expect(second.currentKeys).toBe(3);
+  });
+
+  it('should not treat an inherited Object.prototype member as an existing lock entry', async () => {
+    writeSource({
+      constructor: 'Build',
+      toString: 'Render',
+      valueOf: 'Unwrap',
+      hasOwnProperty: 'Owns',
+    });
+
+    const first = await syncService.sync(await loadSyncConfig(tmpDir));
+    expect(first.success).toBe(true);
+    expect(first.newKeys).toBe(4);
+    expect(first.staleKeys).toBe(0);
+
+    sentTexts = [];
+    const second = await syncService.sync(await loadSyncConfig(tmpDir));
+    expect(sentTexts.flat()).toEqual([]);
+    expect(second.currentKeys).toBe(4);
+  });
+
+  it('should not lose a __proto__ key written through the lock manager', async () => {
+    const lockPath = path.join(tmpDir, LOCK_FILE_NAME);
+    const manager = new SyncLockManager(lockPath);
+    const entry: SyncLockEntry = {
+      source_hash: 'abc123',
+      source_text: 'Polluted',
+      translations: {
+        de: {
+          hash: 'abc123',
+          translated_at: '2026-08-07T00:00:00.000Z',
+          status: 'translated',
+        },
+      },
+    };
+
+    await manager.updateEntry('locales/en.json', 'greeting', entry);
+    await manager.updateEntry('locales/en.json', '__proto__', entry);
+
+    const reread = await manager.read();
+    const stored = reread.entries['locales/en.json'] ?? {};
+    expect(Object.keys(stored).sort()).toEqual(['__proto__', 'greeting']);
+    expect(reread.stats.total_keys).toBe(2);
+
+    await manager.removeEntry('locales/en.json', '__proto__');
+    const afterRemoval = await manager.read();
+    expect(Object.keys(afterRemoval.entries['locales/en.json'] ?? {})).toEqual([
+      'greeting',
+    ]);
+  });
+
+  it('should keep a file path named __proto__ in the entries map', async () => {
+    const manager = new SyncLockManager(path.join(tmpDir, LOCK_FILE_NAME));
+    await manager.updateEntry('__proto__', 'greeting', {
+      source_hash: 'abc123',
+      source_text: 'Hello',
+      translations: {},
+    });
+
+    const reread = await manager.read();
+    expect(Object.keys(reread.entries)).toEqual(['__proto__']);
+  });
+});
diff --git a/tests/unit/sync/sync-status.test.ts b/tests/unit/sync/sync-status.test.ts
index 2ccc7705..80d18601 100644
--- a/tests/unit/sync/sync-status.test.ts
+++ b/tests/unit/sync/sync-status.test.ts
@@ -13,7 +13,12 @@ jest.mock('fs', () => ({
   },
 }));
 jest.mock('fast-glob', () => jest.fn());
-jest.mock('../../../src/sync/sync-lock');
+// Only SyncLockManager is stubbed. A bare automock would also replace the
+// module's pure entry-map accessors, which the code under test relies on.
+jest.mock('../../../src/sync/sync-lock', () => {
+  const actual = jest.requireActual('../../../src/sync/sync-lock');
+  return { ...actual, SyncLockManager: jest.fn() };
+});
 jest.mock('../../../src/sync/sync-differ');
 
 import * as fs from 'fs';

From c786e52cd4f3848759830c7cf5a4c76a27ade141 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 16:24:35 +0200
Subject: [PATCH 134/256] fix(sync): stop a repo-supplied tms.server from
 exfiltrating the operator's TMS_API_KEY

`.deepl-sync.yaml` chooses `tms.server` while TMS_API_KEY/TMS_TOKEN come from
the operator's environment, and createTmsClient wired the two together with the
only destination guard being scheme, not identity: buildUrl requires https:
(waived for localhost/127.0.0.1) and nothing checked who was on the other end.
Nothing secret had to be in the repo.

Reproduced end to end: a checkout with `tms: {enabled: true, server:
http://127.0.0.1:<port>, project_id: victim-project}` plus an exported
TMS_API_KEY printed "Pushed 1 translations to TMS" at exit 0 while the listener
captured `PUT /api/projects/victim-project/keys/greeting` with `authorization:
ApiKey TMS-SECRET-CREDENTIAL-1234`. resolveTmsCredentials warned only about
credentials inlined in the YAML, never about the YAML choosing the destination,
and the success line named a count and no host.

Gated with a hybrid allowlist plus trust-on-first-use, in createTmsClient so
one choke point covers both `sync push` and `sync pull`: the hostname must be
in the new user-level `tms.allowedServers`, or approved once at a prompt naming
the host and stating that the credential and every translated string would go
to it. An accepted answer is recorded in USER config, never in the repository.
Under --no-input or on a non-TTY the run fails closed at exit 7 naming the host
and the exact `deepl config set tms.allowedServers <hosts>` command, with the
already-approved hosts preserved in the suggested value so following it is not
destructive. Verified under a real pty (script(1) cannot be used here):
declining exits 7 with nothing sent and nothing recorded; accepting exits 0,
writes allowedServers to the isolated config dir, and a later non-TTY run
proceeds without prompting.

Four calls the finding did not settle:

- The gate keys on credential PROVENANCE, not merely on a repo-supplied host. A
  credential inlined as tms.api_key/tms.token is not gated: it belongs to the
  same file that chose the destination, so nothing of the operator's leaks.
  Provenance is computed for the credential getAuthHeader will actually attach,
  which prefers api_key, so an env-held token behind a config-held key does not
  trigger a prompt it could never leak through.
- Allowlist-only was rejected (breaks every existing TMS user with no migration
  path) and TOFU-only was rejected (leaves --no-input CI unable to pre-approve).
- Matching is exact and case-insensitive on the parsed hostname, ignoring
  scheme, port and path: a listed example.com does not approve tms.example.com,
  nor does tms.example.com approve evil-tms.example.com. No wildcards. Entries
  carrying a scheme, port, path or `*` are rejected at `deepl config set`
  rather than stored as approval that could never match.
- Loopback is NOT exempt, unlike in buildUrl's HTTPS check: a co-tenant process
  listening on 127.0.0.1 is as much an exfiltration sink as a remote host,
  which is the shape the reproduction used.

`deepl config set` needed two adjacent fixes for the key to be usable at all:
mergeWithDefaults dropped any block absent from its hardcoded list, so a
written allowlist would not have survived a reload, and parseValue only
produced an array for a comma-bearing value, so a single hostname would have
been stored as a bare string the gate could never match.

Independently and unconditionally, push and pull now print the resolved
destination origin on success in both text and JSON output, so a redirected
destination is visible in logs even for an already-approved host -- the origin
only, never a repo-controlled path or query, and terminal-sanitized.

The 17 existing TMS tests that passed an env credential to an arbitrary host
encoded the pre-fix permissiveness; they now pre-approve their destination
explicitly, since what they assert is credential precedence and wire contract,
not destination trust.

Note: the recorded design says "exit 7 (ValidationError)", but ValidationError
is exit 6 and ConfigError is exit 7. ConfigError is used, honouring the numeric
requirement and matching the other TMS misconfiguration errors in these two
commands.

Refs cli-8kr2.8
---
 CHANGELOG.md                                  |   2 +
 README.md                                     |  10 +
 docs/API.md                                   |  29 +-
 docs/SYNC.md                                  |  21 +-
 examples/40-sync-tms-destination-trust.sh     | 150 ++++++++
 examples/README.md                            |  13 +-
 examples/run-all.sh                           |   2 +
 src/cli/commands/config.ts                    |  10 +-
 src/cli/commands/sync/register-sync-pull.ts   |   9 +-
 src/cli/commands/sync/register-sync-push.ts   |   8 +-
 src/storage/config.ts                         |  59 ++-
 src/sync/tms-client.ts                        |  31 +-
 src/sync/tms-server-trust.ts                  | 128 +++++++
 src/types/config.ts                           |   9 +
 tests/e2e/cli-sync-push-pull.e2e.test.ts      | 108 +++++-
 tests/e2e/cli-sync-tms.e2e.test.ts            |   3 +
 tests/helpers/tms-nock.ts                     |  12 +
 .../sync-symlink-safety.integration.test.ts   |  11 +-
 .../integration/sync-tms.integration.test.ts  | 118 +++++-
 tests/unit/config-command.test.ts             |  20 ++
 tests/unit/config-service.test.ts             |  92 +++++
 tests/unit/sync/tms-client.test.ts            | 151 +++++++-
 tests/unit/sync/tms-server-trust.test.ts      | 338 ++++++++++++++++++
 tests/unit/translation-service.test.ts        |   2 +
 24 files changed, 1298 insertions(+), 38 deletions(-)
 create mode 100755 examples/40-sync-tms-destination-trust.sh
 create mode 100644 src/sync/tms-server-trust.ts
 create mode 100644 tests/unit/sync/tms-server-trust.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ff59415..197a1e7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -377,6 +377,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync**: **a `tms.server` value in the checkout can no longer redirect the operator's environment-held `TMS_API_KEY` to a host of its choosing.** `.deepl-sync.yaml` picks the destination, `TMS_API_KEY`/`TMS_TOKEN` come from the operator's environment, and `createTmsClient` wired the two together with the only destination guard being **scheme, not identity** — `buildUrl` requires `https:` (waived for `localhost`/`127.0.0.1`) and nothing checked *who* was on the other end. Nothing secret had to be in the repo. Reproduced end to end: a hostile checkout with `tms: {enabled: true, server: http://127.0.0.1:<port>, project_id: victim-project}`, an operator with `TMS_API_KEY` exported (normal for cross-project use), `deepl sync push` → **`Pushed 1 translations to TMS`, exit 0**, while the listener captured `PUT /api/projects/victim-project/keys/greeting` with `authorization: ApiKey TMS-SECRET-CREDENTIAL-1234` and the translated string in the body. `resolveTmsCredentials` did warn — but only about credentials *inlined in the YAML*, never about the YAML choosing the *destination*, and the success line named a count and no host. Now a **hybrid allowlist plus trust-on-first-use** gates it, in `createTmsClient` so both `sync push` and `sync pull` are covered by one choke point: the hostname must appear in a new user-level `tms.allowedServers` list, or be approved once at a prompt that names the host and states that the credential and every translated string would go to it. An accepted answer is recorded in **user** config (`~/.config/deepl-cli/config.json`), never in the repository, so it survives a fresh clone and does not travel with the repo. Under `--no-input` or on a non-TTY the run **fails closed with exit 7** naming the host and the exact `deepl config set tms.allowedServers <hosts>` command, with the already-approved hosts preserved in the suggested value so following it is not destructive. Verified under a real pty: declining exits 7 with nothing sent and nothing recorded; accepting exits 0, writes `allowedServers: ['localhost']` to the isolated config dir, and a later non-TTY run proceeds without prompting. Four scoping decisions the finding did not settle. The gate keys on **credential provenance**, not merely on a repo-supplied host: a credential inlined as `tms.api_key`/`tms.token` is not gated, because it belongs to the same file that chose the destination and nothing of the operator's leaks — and provenance is computed for the credential `getAuthHeader` will *actually* attach, which prefers `api_key`, so an env-held token sitting behind a config-held key does not trigger a prompt it could never leak through. Allowlist-only was rejected as it breaks every existing TMS user with no migration path, and TOFU-only was rejected as it leaves `--no-input` CI with no way to pre-approve. Matching is **exact and case-insensitive on the parsed hostname**, ignoring scheme, port and path, so a listed `example.com` does not approve `tms.example.com` and `tms.example.com` does not approve `evil-tms.example.com`; there are no wildcards, and entries carrying a scheme, port, path or `*` are **rejected at `deepl config set`** rather than stored as approval that could never match. And **loopback is not exempt**, unlike in `buildUrl`'s HTTPS check: a co-tenant process listening on `127.0.0.1` is as much an exfiltration sink as a remote host, which is exactly the shape the reproduction used. Independently and unconditionally, both commands now **print the resolved destination origin** on success in text and JSON output (`Pushed 3 translations to TMS at https://tms.example.com`; `"server": "https://tms.example.com"`), so a redirected destination is visible in logs even when the host was already approved — the origin only, never a repo-controlled path or query, and terminal-sanitized.
+
 - **sync**: **an i18n key named `__proto__` is now recorded in the lockfile instead of vanishing from it, so it is no longer re-translated and re-billed on every run, forever.** Every write into the lockfile's entry maps was a plain assignment — `fileEntryMap[diff.key] = {...}` in `sync-process-bucket.ts` and `sync-tms.ts`, `lockFile.entries[filePath][key] = entry` in `sync-lock.ts` — and for that one key name the assignment reaches the prototype setter rather than creating a property. With `locales/en.json` holding `{greeting, __proto__, normal}`, `deepl sync` reported `3/3 keys` and wrote all three translations into `de.json`, but the lockfile came back with two entries and `"total_keys": 2`; each subsequent run diffed the missing key as new, sent it to the API, and was billed for it again, with no run ever converging. The hazard was already documented one file over — `sync-lock.ts` carries a null-prototype comment about exactly this — but only the **serialization** side had been fixed, and by the time serialization runs the key is already gone. The same shape applied to a **source path** named `__proto__`, which fell out of `lockFile.entries` wholesale, taking every key in that file with it. Fixed with three shared accessors in `sync-lock.ts` (`setOwnMember` / `getOwnMember` / `ensureFileEntries`) applied at all fourteen access sites across six files, following the `setOwn` pattern `formats/json.ts` already uses for this hazard on the translation side. The read side needed the same treatment and for a **different** reason the finding did not cover: plain indexing hands back inherited `Object.prototype` members, so keys named `constructor`, `toString`, `valueOf` or `hasOwnProperty` read as an existing lock entry that is missing every field it should have — `computeDiff` classified all four as **stale** rather than new on a first sync (`newKeys: 0, staleKeys: 4` where both should have been 4/0), and one code path would have dereferenced `.translations` on `Object` itself had a hash ever matched. Two sites beyond the fourteen the finding listed also needed it, in `sync-status.ts` and `sync-locale-translator.ts`. Verified end to end against a recording stub: the key is translated once, the lockfile round-trips all three entries with `total_keys: 3`, `de.json` holds the translated value as an own property, and a second sync sends **no** request and reports 3 current keys.
 
 - **api**: **an endpoint that keeps sending is now bounded in both bytes and wall-clock time.** The shared axios instance set `baseURL`, `timeout` and agents but never `maxContentLength` or `maxBodyLength`, which axios defaults to `-1` — unbounded — so a response body was buffered into memory until the process died; all ten API clients inherited that. Worse, `--timeout` did not save the run, because axios delivers it to the socket as an *inactivity* timeout and this client goes out over the follow-redirects transport, where that is the only timeout armed: every arriving chunk reset it, so it never fired. Measured against a stub streaming 1 MiB chunks forever with `timeout: 5000`: **peak RSS 8572 MB and still running, un-aborted, at 20 s — four times past the configured deadline. After: rejected in 24 ms with RSS flat.** A second, nastier shape proves a size cap alone would not have been enough: a stub trickling **one byte per second** stays under any byte cap indefinitely while pinning the process, and also ran past 20 s untouched; it now aborts at 5005 ms, the configured timeout. With retries enabled the whole call is bounded too — 10093 ms for `--max-retries 3`, matching the twice-`--timeout` budget that was already documented but that only held for an endpoint which said nothing at all. Two changes, and the second is the load-bearing one. **A finite response cap of 32 MiB and body cap of 128 MiB on the shared instance**, verified to be enforced by axios on the buffered and `arraybuffer` paths alike, which is every path this repo uses. **An `AbortController` deadline armed per attempt inside the retry loop**, wall-clock and therefore not resettable by the peer. The caps are deliberately **not** the single 32 MiB used by `sync`'s TMS client, which the finding suggested reusing: DeepL accepts documents up to 30 MB and a translated result can exceed its source — `output_format` converts between types — so a 32 MiB response cap would have rejected a legitimate translated document on `deepl translate report.pdf --to de`, at the one endpoint whose result is single-use and deliberately never retried. Rejecting there destroys an already-billed translation permanently, so the cap would have caused the very data loss it was meant to prevent; the document download therefore raises its response cap to 128 MiB per request, riding the same `RequestPolicy` mechanism it already uses to widen `timeout`, while status polling and the other nine clients keep the tighter default. Two smaller consequences of the same work: a deadline abort is restated as the socket timeout it stands in for, because axios surfaces a mid-body cancellation as a `CanceledError` that still carries the 200 response and classification would have reported that as `API error: canceled` rather than a timeout; and a size-cap rejection is **not** retried, since the verdict is deterministic and replaying it only re-downloads bytes that will be discarded again — three extra attempts on a 32 MiB body were 128 MiB of pointless transfer. Both bounds surface as `NetworkError` (exit 5), the size cap naming the limit it hit rather than axios's internal `maxContentLength size of 33554432 exceeded`.
diff --git a/README.md b/README.md
index ce3e0887..5a7206c5 100644
--- a/README.md
+++ b/README.md
@@ -813,8 +813,14 @@ deepl sync resolve
 # Optional TMS integration (requires a tms: block in .deepl-sync.yaml)
 deepl sync push
 deepl sync pull
+
+# .deepl-sync.yaml picks the TMS host, so an environment-supplied TMS_API_KEY
+# only goes to a host you have approved. Approve one up front:
+deepl config set tms.allowedServers tms.example.com
 ```
 
+Because `tms.server` is chosen by `.deepl-sync.yaml` in the checkout while `TMS_API_KEY`/`TMS_TOKEN` come from your environment, `push`/`pull` will not send an environment-supplied credential to a hostname you have not approved: it asks once in a terminal (recording the answer in your **user** config, outside the repo) and fails closed with exit 7 under `--no-input` or in CI. Both commands also print the destination origin on success. See [TMS destination trust](./docs/SYNC.md#tms-destination-trust).
+
 See **[docs/SYNC.md](./docs/SYNC.md)** for configuration (`.deepl-sync.yaml`), the lockfile model, CI/CD recipes, and the TMS REST contract, and [docs/API.md#sync](./docs/API.md#sync) for the full flag reference.
 
 ### Watch Mode
@@ -1101,6 +1107,10 @@ deepl config get cache.enabled
 deepl config set defaults.targetLangs es,fr,de
 # ✓ Configuration updated: defaults.targetLangs = ["es","fr","de"]
 
+# Approve TMS destinations for an environment-supplied TMS_API_KEY / TMS_TOKEN
+deepl config set tms.allowedServers tms.example.com,tms2.example.com
+# ✓ Set tms.allowedServers = tms.example.com,tms2.example.com
+
 # Set cache size (in bytes)
 deepl config set cache.maxSize 2147483648
 # ✓ Configuration updated: cache.maxSize = 2147483648
diff --git a/docs/API.md b/docs/API.md
index 655689e5..98953a2a 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1497,7 +1497,17 @@ Push local translations to a TMS for human review.
 
 **Requires TMS integration.** Add a `tms:` block to `.deepl-sync.yaml` (at minimum `enabled: true`, `server`, `project_id`) and supply credentials via the `TMS_API_KEY` or `TMS_TOKEN` environment variable. Running `push` without a configured `tms:` block exits 7 (ConfigError). See [docs/SYNC.md#tms-rest-contract](./SYNC.md#tms-rest-contract) for the full field reference and REST contract.
 
-**JSON success envelope (stable within a major version):** `{ "ok": true, "pushed": <n>, "skipped": [...] }`
+**TMS destination trust.** `tms.server` is chosen by `.deepl-sync.yaml`, which lives in the checkout, while `TMS_API_KEY` / `TMS_TOKEN` come from your environment. Before an **environment-supplied** credential is attached to a request, the destination hostname must be one you have approved:
+
+- Approved if the hostname appears in the user-level `tms.allowedServers` list (`deepl config set tms.allowedServers tms.example.com`, comma-separate several).
+- Otherwise, in an interactive terminal, the CLI names the host and what would be sent and asks once. Answering yes records the hostname in **user** config (`~/.config/deepl-cli/config.json`), never in the repository.
+- Otherwise — under `--no-input`, or on a non-TTY such as CI — the run fails closed with exit 7 (ConfigError) naming the host and the exact `deepl config set tms.allowedServers ...` command. No credential and no translated string is sent.
+
+The gate applies only to environment-supplied credentials. A credential inlined as `tms.api_key` / `tms.token` in `.deepl-sync.yaml` is not gated: it belongs to the same file that chose the destination, so nothing of yours leaks. Loopback hosts (`localhost`, `127.0.0.1`) are **not** exempt — a co-tenant process listening locally is still an exfiltration sink.
+
+Both commands print the resolved destination origin on success, in text and JSON output, so a redirected destination is visible in logs even when the host was already approved.
+
+**JSON success envelope (stable within a major version):** `{ "ok": true, "pushed": <n>, "skipped": [...], "server": "<origin>" }`
 
 ##### `pull`
 
@@ -1511,7 +1521,17 @@ Pull approved translations from a TMS back into local files.
 
 **Requires TMS integration.** Add a `tms:` block to `.deepl-sync.yaml` (at minimum `enabled: true`, `server`, `project_id`) and supply credentials via the `TMS_API_KEY` or `TMS_TOKEN` environment variable. Running `pull` without a configured `tms:` block exits 7 (ConfigError). See [docs/SYNC.md#tms-rest-contract](./SYNC.md#tms-rest-contract) for the full field reference and REST contract.
 
-**JSON success envelope (stable within a major version):** `{ "ok": true, "pulled": <n>, "skipped": [...] }`
+**TMS destination trust.** `tms.server` is chosen by `.deepl-sync.yaml`, which lives in the checkout, while `TMS_API_KEY` / `TMS_TOKEN` come from your environment. Before an **environment-supplied** credential is attached to a request, the destination hostname must be one you have approved:
+
+- Approved if the hostname appears in the user-level `tms.allowedServers` list (`deepl config set tms.allowedServers tms.example.com`, comma-separate several).
+- Otherwise, in an interactive terminal, the CLI names the host and what would be sent and asks once. Answering yes records the hostname in **user** config (`~/.config/deepl-cli/config.json`), never in the repository.
+- Otherwise — under `--no-input`, or on a non-TTY such as CI — the run fails closed with exit 7 (ConfigError) naming the host and the exact `deepl config set tms.allowedServers ...` command. No credential and no translated string is sent.
+
+The gate applies only to environment-supplied credentials. A credential inlined as `tms.api_key` / `tms.token` in `.deepl-sync.yaml` is not gated: it belongs to the same file that chose the destination, so nothing of yours leaks. Loopback hosts (`localhost`, `127.0.0.1`) are **not** exempt — a co-tenant process listening locally is still an exfiltration sink.
+
+Both commands print the resolved destination origin on success, in text and JSON output, so a redirected destination is visible in logs even when the host was already approved.
+
+**JSON success envelope (stable within a major version):** `{ "ok": true, "pulled": <n>, "skipped": [...], "server": "<origin>" }`
 
 #### Examples
 
@@ -3114,6 +3134,9 @@ Existing `~/.deepl-cli/` installations continue to work with no changes needed.
     "debounceMs": 500,
     "autoCommit": false,
     "pattern": "*.md"
+  },
+  "tms": {
+    "allowedServers": []
   }
 }
 ```
@@ -3121,6 +3144,7 @@ Existing `~/.deepl-cli/` installations continue to work with no changes needed.
 **Configuration Notes:**
 
 - **`baseUrl`** — when set to a custom/regional endpoint (e.g. `https://api-jp.deepl.com`), it overrides all auto-detection. Standard DeepL URLs (`api.deepl.com`, `api-free.deepl.com`) are treated as tier defaults and do **not** override key-based auto-detection. By default, the endpoint is auto-detected from the API key: keys ending with `:fx` use the Free API (`api-free.deepl.com`), all others use the Pro API (`api.deepl.com`). The `usePro` flag serves as a backward-compatible fallback for non-`:fx` keys.
+- **`tms.allowedServers`** — hostnames approved as TMS destinations for an environment-supplied `TMS_API_KEY` / `TMS_TOKEN`. Empty by default, so no destination is trusted implicitly. Entries must be bare hostnames (no scheme, port, path, or wildcard) because they are matched against a parsed URL hostname, exactly and case-insensitively — a listed `example.com` does not approve `tms.example.com`. Set it with `deepl config set tms.allowedServers a.example.com,b.example.com`; a single host is still stored as a one-element array. See [`sync push`](#push) for how the gate behaves.
 - Most users configure settings via `deepl config set` command rather than editing the file directly.
 
 ---
@@ -3335,6 +3359,7 @@ The configuration file or a configuration value is invalid. Emitted by:
 - 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)
+- `sync push` / `sync pull` when `.deepl-sync.yaml` names a `tms.server` hostname that is not in `tms.allowedServers` and the approval prompt is unavailable (`--no-input`, non-TTY) or declined
 - `glossary` when a named glossary cannot be resolved
 
 Remediation: run `deepl config get` to inspect the current config, or edit the file directly and re-run.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index a36acea1..7cf8d84d 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -286,7 +286,7 @@ Optional integration with a translation management system (TMS) for collaborativ
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `enabled` | `boolean` | Yes | -- | Enable TMS integration |
-| `server` | `string` | Yes | -- | TMS server URL (HTTPS required except for `localhost`/`127.0.0.1`) |
+| `server` | `string` | Yes | -- | TMS server URL (HTTPS required except for `localhost`/`127.0.0.1`). When the credential comes from the environment, the hostname must also be approved -- see [TMS destination trust](#tms-destination-trust) |
 | `project_id` | `string` | Yes | -- | TMS project identifier |
 | `api_key` | `string` | No | -- | API key for TMS authentication (prefer `TMS_API_KEY` env var) |
 | `token` | `string` | No | -- | Bearer token for TMS authentication (prefer `TMS_TOKEN` env var) |
@@ -296,6 +296,25 @@ Optional integration with a translation management system (TMS) for collaborativ
 | `timeout_ms` | `number` | No | `30000` | Per-request timeout in milliseconds for TMS HTTP calls (positive integer). Aborts the request via `AbortController` when exceeded. |
 | `push_concurrency` | `number` | No | `10` | Maximum number of in-flight `PUT /keys/{keyPath}` requests during `deepl sync push`. Positive integer. Applied per (file, locale) batch of entries; aborts remaining pushes on first failure. |
 
+##### TMS destination trust
+
+`server` is chosen by this file, which lives in the checkout, while `TMS_API_KEY` / `TMS_TOKEN` come from the operator's environment. A checkout you do not control could therefore name the host that receives your credential and every translated string. Before an **environment-supplied** credential is attached to a request, the destination hostname must be approved in the operator's own configuration:
+
+```bash
+# Approve a destination up front (comma-separate several hosts)
+deepl config set tms.allowedServers tms.example.com
+```
+
+- Listed in `tms.allowedServers` → the run proceeds silently.
+- Not listed, interactive terminal → the CLI names the host and what would be sent, and asks once. Answering yes records the hostname in **user** config (`~/.config/deepl-cli/config.json`), never in the repository, so the answer survives a fresh clone of the same project and does not travel with the repo.
+- Not listed, no terminal (`--no-input`, CI) or declined → exit 7 (`ConfigError`) naming the host and the exact `deepl config set` command. Nothing is sent.
+
+Matching is against a parsed URL hostname: exact and case-insensitive, ignoring scheme, port and path. A listed `example.com` does **not** approve `tms.example.com`, and there are no wildcards. `localhost` and `127.0.0.1` are **not** exempt — a co-tenant process listening on loopback is still an exfiltration sink, even though `buildUrl` waives the HTTPS requirement for them.
+
+The gate does not apply to a credential inlined as `api_key` / `token` in this file: it belongs to the same file that chose the destination, so nothing of the operator's leaks. Inlining a credential is still discouraged (it commits a secret), and the CLI warns about it separately.
+
+`deepl sync push` and `deepl sync pull` print the resolved destination origin on success in both text and JSON output, so a redirected destination is visible in logs even for an already-approved host.
+
 ##### TMS reliability: timeouts and retries
 
 Each TMS HTTP request is bounded by `tms.timeout_ms` (default 30000 ms) using an `AbortController`. If the configured timeout elapses before the server responds, the client raises a `TmsTimeoutError` rather than hanging indefinitely.
diff --git a/examples/40-sync-tms-destination-trust.sh b/examples/40-sync-tms-destination-trust.sh
new file mode 100755
index 00000000..576b3f53
--- /dev/null
+++ b/examples/40-sync-tms-destination-trust.sh
@@ -0,0 +1,150 @@
+#!/bin/bash
+# Sync — TMS destination trust
+# Demonstrates that a repo-supplied tms.server cannot redirect an
+# environment-held TMS_API_KEY to a host you have not approved
+
+set -e  # Exit on error
+
+echo "=== DeepL CLI: Sync — TMS Destination Trust ==="
+echo
+
+# push talks to a TMS, not to DeepL, so no DeepL API key is needed. The TMS here
+# is a throwaway listener on loopback, so this example needs no network either.
+echo "No API key needed: push talks to a TMS, and this example runs its own."
+echo
+
+PROJECT_DIR="/tmp/deepl-tms-trust-demo"
+CONFIG_DIR="/tmp/deepl-tms-trust-config"
+rm -rf "$PROJECT_DIR" "$CONFIG_DIR"
+mkdir -p "$PROJECT_DIR/locales" "$CONFIG_DIR"
+
+LISTENER_PID=""
+cleanup() {
+  [ -n "$LISTENER_PID" ] && kill "$LISTENER_PID" 2>/dev/null || true
+  rm -rf "$PROJECT_DIR" "$CONFIG_DIR"
+}
+trap cleanup EXIT
+
+# An isolated config dir, so the example cannot touch your real allowlist.
+export DEEPL_CONFIG_DIR="$CONFIG_DIR"
+
+cd "$PROJECT_DIR"
+
+# 1. A stand-in TMS that records what it receives. Stands in for the attacker's
+#    listener in the refusal step and for a legitimate TMS in the last one.
+cat > tms.mjs << 'EOF'
+import http from 'node:http';
+const srv = http.createServer((req, res) => {
+  let body = '';
+  req.on('data', (c) => (body += c));
+  req.on('end', () => {
+    console.error(`  [tms] ${req.method} ${req.url}`);
+    console.error(`  [tms]   authorization: ${req.headers['authorization']}`);
+    console.error(`  [tms]   body: ${body}`);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end('{}');
+  });
+});
+srv.listen(0, '127.0.0.1', () =>
+  console.log(`PORT=${srv.address().port}`)
+);
+EOF
+
+node tms.mjs > port.txt 2> tms.log &
+LISTENER_PID=$!
+for _ in $(seq 1 50); do
+  grep -q PORT= port.txt 2>/dev/null && break
+  sleep 0.1
+done
+PORT=$(sed 's/PORT=//' port.txt | tr -d '[:space:]')
+
+# 2. The checkout chooses the destination. In a hostile repository this is the
+#    attacker's host; the operator never typed it.
+echo "1. A checkout whose .deepl-sync.yaml picks the TMS host"
+cat > .deepl-sync.yaml << EOF
+version: 1
+source_locale: en
+target_locales:
+  - de
+buckets:
+  json:
+    include:
+      - "locales/en.json"
+tms:
+  enabled: true
+  server: http://localhost:$PORT
+  project_id: victim-project
+EOF
+cat .deepl-sync.yaml
+echo
+
+echo '{ "greeting": "Hello" }' > locales/en.json
+echo '{ "greeting": "Hallo" }' > locales/de.json
+
+# 3. The credential comes from the operator's environment, which is the
+#    recommended setup and normal for cross-project use. Nothing secret is in
+#    the repo, and that is the point: the repo only has to name the host.
+echo "2. Push with an environment-supplied credential, non-interactively"
+echo "   (tms.allowedServers is empty, so this must not send anything)"
+set +e
+TMS_API_KEY='TMS-SECRET-CREDENTIAL-1234' deepl --no-input sync push
+STATUS=$?
+set -e
+echo "   exit code: $STATUS  (7 = ConfigError)"
+echo
+
+echo "3. What the stand-in TMS received"
+if [ -s tms.log ]; then
+  cat tms.log
+else
+  echo "  (nothing — the credential never left the machine)"
+fi
+echo
+
+# 4. The approval lives in USER config, outside the repository, so it survives a
+#    fresh clone of the same project and does not travel with the repo.
+echo "4. Approve the destination once, in your own configuration"
+deepl config set tms.allowedServers localhost
+deepl config get tms.allowedServers
+echo
+echo "   Recorded in \$DEEPL_CONFIG_DIR/config.json, not in the checkout:"
+grep -c allowedServers "$CONFIG_DIR/config.json" > /dev/null && \
+  echo "   ✓ $CONFIG_DIR/config.json"
+test ! -f "$PROJECT_DIR/config.json" && echo "   ✓ nothing written to $PROJECT_DIR"
+echo
+
+# 5. Now the same command proceeds, and names the destination it used.
+echo "5. Push again — approved, and the destination origin is reported"
+TMS_API_KEY='TMS-SECRET-CREDENTIAL-1234' deepl --no-input sync push
+echo
+echo "   What the TMS received:"
+cat tms.log
+echo
+
+# 6. Machine-readable output carries the destination too, so a pipeline can
+#    assert on it rather than trusting the count alone.
+echo "6. JSON output includes the resolved destination"
+TMS_API_KEY='TMS-SECRET-CREDENTIAL-1234' deepl --no-input sync push --format json
+echo
+
+cat << 'EOF'
+
+Notes:
+  - The gate applies only to an ENVIRONMENT-supplied credential. A credential
+    inlined as tms.api_key / tms.token in .deepl-sync.yaml is not gated: it
+    belongs to the same file that chose the destination, so nothing of yours
+    leaks. Inlining a secret is still discouraged, and warned about separately.
+  - In an interactive terminal an unapproved host prompts once, naming the host
+    and what would be sent, and records a yes in your user config. This example
+    passes --no-input to show the non-interactive path, which fails closed.
+  - Matching is exact and case-insensitive on the parsed hostname, ignoring
+    scheme, port and path. A listed "example.com" does NOT approve
+    "tms.example.com", and there are no wildcards.
+  - Loopback is not exempt. This example approved "localhost" explicitly; a
+    co-tenant process listening on 127.0.0.1 is as much an exfiltration sink as
+    a remote host.
+  - See docs/SYNC.md#tms-destination-trust for the full contract.
+
+EOF
+
+echo "=== TMS destination trust example complete ==="
diff --git a/examples/README.md b/examples/README.md
index 124c7ef8..45f16e1d 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -44,11 +44,14 @@ This directory contains practical, real-world examples of using the DeepL CLI.
 - [Sync — Laravel PHP arrays](./25-sync-laravel-php.sh) - `laravel_php` format parser: AST allowlist, span-surgical reconstruct, pipe-pluralization warning gate, `sync.limits` caps
 - [Sync — Resolve Lockfile Conflicts](./26-sync-resolve.sh) - Auto-resolving a `.deepl-sync.lock` left conflicted by `git merge`, and previewing the decisions first
 - [Sync — Audit Translation Consistency](./27-sync-audit.sh) - Finding one source term translated two different ways across a project
-
-`deepl sync push` and `deepl sync pull` have no example script here. They need a
-reachable TMS endpoint and a `TMS_API_KEY`, so an example could not run
-unattended as part of `run-all.sh`; see [docs/SYNC.md](../docs/SYNC.md) for their
-reference documentation.
+- [Sync — TMS Destination Trust](./40-sync-tms-destination-trust.sh) - Why a repo-supplied `tms.server` cannot redirect an environment-held `TMS_API_KEY`, and how `tms.allowedServers` approves one
+
+`deepl sync push` and `deepl sync pull` have no general example script here. They
+need a reachable TMS endpoint and a `TMS_API_KEY`, so an example could not
+exercise a real workflow unattended as part of `run-all.sh`; see
+[docs/SYNC.md](../docs/SYNC.md) for their reference documentation. The destination-trust
+example above is the exception — it runs its own throwaway TMS on loopback, so it
+needs neither an API key nor a network.
 
 ### Configuration
 
diff --git a/examples/run-all.sh b/examples/run-all.sh
index d74f330a..7d2e7829 100755
--- a/examples/run-all.sh
+++ b/examples/run-all.sh
@@ -79,6 +79,7 @@ EXAMPLES=(
   "25-sync-laravel-php.sh"
   "26-sync-resolve.sh"
   "27-sync-audit.sh"
+  "40-sync-tms-destination-trust.sh"
   # Configuration
   "28-configuration.sh"
   "29-custom-config-files.sh"
@@ -132,6 +133,7 @@ if [ "$FAST_MODE" = true ]; then
     "25-sync-laravel-php.sh"
     "26-sync-resolve.sh"
     "27-sync-audit.sh"
+    "40-sync-tms-destination-trust.sh"
     # Configuration
     "28-configuration.sh"
     "29-custom-config-files.sh"
diff --git a/src/cli/commands/config.ts b/src/cli/commands/config.ts
index 345ae9cf..66660126 100644
--- a/src/cli/commands/config.ts
+++ b/src/cli/commands/config.ts
@@ -16,6 +16,10 @@ const BOOLEAN_KEYS = [
 
 const NUMERIC_KEYS = ['cache.maxSize', 'cache.ttl', 'watch.debounceMs'];
 
+// Keys whose value is always a list, so a single entry still arrives as an
+// array rather than a bare string.
+const ARRAY_KEYS = ['tms.allowedServers'];
+
 export class ConfigCommand {
   private config: ConfigService;
 
@@ -115,7 +119,11 @@ export class ConfigCommand {
    */
   private parseValue(key: string, value: string): unknown {
     // Handle array values (comma-separated)
-    if (key.includes('targetLangs') || value.includes(',')) {
+    if (
+      ARRAY_KEYS.includes(key) ||
+      key.includes('targetLangs') ||
+      value.includes(',')
+    ) {
       return value.split(',').map((v) => v.trim());
     }
 
diff --git a/src/cli/commands/sync/register-sync-pull.ts b/src/cli/commands/sync/register-sync-pull.ts
index 3a39e8a8..b877e9b0 100644
--- a/src/cli/commands/sync/register-sync-pull.ts
+++ b/src/cli/commands/sync/register-sync-pull.ts
@@ -80,7 +80,11 @@ export async function handleSyncPull(
 
     const processLock = acquireSyncProcessLock(config.projectRoot);
     try {
-      const client = createTmsClient(config.tms);
+      const client = await createTmsClient(config.tms);
+      const { tmsServerOrigin } =
+        await import('../../../sync/tms-server-trust.js');
+      const server = tmsServerOrigin(config.tms.server);
+
       const registry = await createDefaultRegistry();
       const result = await pullTranslations(config, client, registry, {
         localeFilter,
@@ -91,11 +95,12 @@ export async function handleSyncPull(
             ok: true,
             pulled: result.pulled,
             skipped: result.skipped,
+            server,
           }) + '\n'
         );
       } else {
         Logger.info(
-          `Pulled ${result.pulled} translations from TMS${formatSkippedSummary(result.skipped)}`
+          `Pulled ${result.pulled} translations from TMS at ${server}${formatSkippedSummary(result.skipped)}`
         );
       }
     } finally {
diff --git a/src/cli/commands/sync/register-sync-push.ts b/src/cli/commands/sync/register-sync-push.ts
index 2e277a6b..bd2d00f1 100644
--- a/src/cli/commands/sync/register-sync-push.ts
+++ b/src/cli/commands/sync/register-sync-push.ts
@@ -75,7 +75,10 @@ async function handleSyncPush(
       );
     }
 
-    const client = createTmsClient(config.tms);
+    const client = await createTmsClient(config.tms);
+    const { tmsServerOrigin } =
+      await import('../../../sync/tms-server-trust.js');
+    const server = tmsServerOrigin(config.tms.server);
 
     const registry = await createDefaultRegistry();
     const result = await pushTranslations(config, client, registry, {
@@ -87,11 +90,12 @@ async function handleSyncPush(
           ok: true,
           pushed: result.pushed,
           skipped: result.skipped,
+          server,
         }) + '\n'
       );
     } else {
       Logger.info(
-        `Pushed ${result.pushed} translations to TMS${formatSkippedSummary(result.skipped)}`
+        `Pushed ${result.pushed} translations to TMS at ${server}${formatSkippedSummary(result.skipped)}`
       );
     }
   } catch (error) {
diff --git a/src/storage/config.ts b/src/storage/config.ts
index 85d75572..ed6b2e26 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -53,6 +53,47 @@ const FORBIDDEN_KEY_SEGMENTS = new Set([
   'prototype',
 ]);
 
+export const ALLOWED_SERVERS_PATH = 'tms.allowedServers';
+
+/**
+ * What `URL.hostname` yields, and nothing else: a bare host, or a bracketed
+ * IPv6 literal. The allowlist is compared against a parsed hostname, so an
+ * entry carrying a scheme, port, path, or wildcard could never match and would
+ * read as approval that silently does not apply.
+ */
+const TMS_HOSTNAME_PATTERN =
+  /^(?:\[[0-9a-f:.]+\]|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*)$/;
+
+function parseAllowedServers(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    throw new ConfigError(
+      `${ALLOWED_SERVERS_PATH} must be an array of hostnames`,
+      `Run: deepl config set ${ALLOWED_SERVERS_PATH} tms.example.com  (comma-separate several hosts)`
+    );
+  }
+
+  return value.map((entry) => {
+    if (typeof entry !== 'string') {
+      throw new ConfigError(
+        `${ALLOWED_SERVERS_PATH} entries must be strings, got ${entry === null ? 'null' : typeof entry}`
+      );
+    }
+    const host = entry.trim().toLowerCase();
+    if (host === '') {
+      throw new ConfigError(
+        `${ALLOWED_SERVERS_PATH} entries must not be empty`
+      );
+    }
+    if (!TMS_HOSTNAME_PATTERN.test(host)) {
+      throw new ConfigError(
+        `Invalid TMS host "${entry}" for ${ALLOWED_SERVERS_PATH}: expected a bare hostname such as tms.example.com`,
+        'Drop the scheme, port, path, and any wildcard. The allowlist matches a parsed hostname exactly.'
+      );
+    }
+    return host;
+  });
+}
+
 const DEFAULT_CACHE_SIZE = 1024 * 1024 * 1024; // 1GB
 const DEFAULT_CACHE_TTL = 30 * 24 * 60 * 60; // 30 days in seconds
 /** Debounce delay applied by `watch` when neither the flag nor configuration
@@ -63,9 +104,10 @@ export const DEFAULT_DEBOUNCE_MS = 500;
 /**
  * Language values are stored lowercase, matching what `deepl languages` prints
  * and what the translate paths normalize their flags to, so a config written as
- * `DE` does not read back as a code the registry cannot look up.
+ * `DE` does not read back as a code the registry cannot look up. TMS hostnames
+ * are stored the same way, since they are matched against a parsed hostname.
  */
-function normalizeLanguageValue(path: string, value: unknown): unknown {
+function normalizeConfigValue(path: string, value: unknown): unknown {
   if (path === 'defaults.sourceLang' && typeof value === 'string') {
     return value.toLowerCase();
   }
@@ -74,6 +116,9 @@ function normalizeLanguageValue(path: string, value: unknown): unknown {
       typeof lang === 'string' ? lang.toLowerCase() : lang
     );
   }
+  if (path === ALLOWED_SERVERS_PATH) {
+    return parseAllowedServers(value);
+  }
   return value;
 }
 
@@ -102,7 +147,7 @@ export class ConfigService {
 
     const keys = key.split('.');
     this.validatePath(keys, value);
-    value = normalizeLanguageValue(keys.join('.'), value);
+    value = normalizeConfigValue(keys.join('.'), value);
 
     let current: Record<string, unknown> = this.config as unknown as Record<
       string,
@@ -247,6 +292,9 @@ export class ConfigService {
         autoCommit: false,
         pattern: '*.md',
       },
+      tms: {
+        allowedServers: [],
+      },
     };
   }
 
@@ -345,6 +393,7 @@ export class ConfigService {
       cache: { ...defaults.cache, ...loaded.cache },
       output: { ...defaults.output, ...loaded.output },
       watch: { ...defaults.watch, ...loaded.watch },
+      tms: { ...defaults.tms, ...loaded.tms },
     };
   }
 
@@ -419,6 +468,10 @@ export class ConfigService {
       }
     }
 
+    if (path === ALLOWED_SERVERS_PATH) {
+      parseAllowedServers(value);
+    }
+
     if (path === 'api.baseUrl') {
       try {
         validateApiUrl(value as string);
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index c657181c..9a65cd36 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -4,6 +4,11 @@ import { sanitizeUrl } from '../utils/sanitize-url.js';
 import { Logger } from '../utils/logger.js';
 import type { ExtractedEntry } from '../formats/format.js';
 import type { SyncTmsConfig } from './types.js';
+import {
+  ensureTmsServerApproved,
+  type TmsCredentialSource,
+  type TmsServerTrustDeps,
+} from './tms-server-trust.js';
 
 const MAX_PULL_VALUE_BYTES = 64 * 1024;
 export const MAX_PULL_KEY_COUNT = 50000;
@@ -372,7 +377,7 @@ export class TmsClient {
 export function resolveTmsCredentials(config: {
   api_key?: string;
   token?: string;
-}): { apiKey?: string; token?: string } {
+}): { apiKey?: string; token?: string; source: TmsCredentialSource } {
   const apiKey = process.env['TMS_API_KEY'] ?? config.api_key;
   const token = process.env['TMS_TOKEN'] ?? config.token;
 
@@ -387,14 +392,32 @@ export function resolveTmsCredentials(config: {
     );
   }
 
-  return { apiKey, token };
+  return { apiKey, token, source: credentialSource(apiKey, token) };
 }
 
-export function createTmsClient(config: SyncTmsConfig): TmsClient {
-  const { apiKey, token } = resolveTmsCredentials({
+/**
+ * Where the credential that `getAuthHeader` will actually attach came from.
+ * It prefers apiKey, so an env-held token behind a config-held api_key is
+ * never sent and does not make the destination a leak.
+ */
+function credentialSource(
+  apiKey: string | undefined,
+  token: string | undefined
+): TmsCredentialSource {
+  if (apiKey) return process.env['TMS_API_KEY'] ? 'env' : 'config';
+  if (token) return process.env['TMS_TOKEN'] ? 'env' : 'config';
+  return 'none';
+}
+
+export async function createTmsClient(
+  config: SyncTmsConfig,
+  trustDeps: TmsServerTrustDeps = {}
+): Promise<TmsClient> {
+  const { apiKey, token, source } = resolveTmsCredentials({
     api_key: config.api_key,
     token: config.token,
   });
+  await ensureTmsServerApproved(config.server, source, trustDeps);
   return new TmsClient({
     serverUrl: config.server,
     projectId: config.project_id,
diff --git a/src/sync/tms-server-trust.ts b/src/sync/tms-server-trust.ts
new file mode 100644
index 00000000..21cbd6d1
--- /dev/null
+++ b/src/sync/tms-server-trust.ts
@@ -0,0 +1,128 @@
+/**
+ * Destination trust for the TMS integration.
+ *
+ * `tms.server` is chosen by `.deepl-sync.yaml`, which lives in the checkout
+ * rather than under the user's control, while TMS_API_KEY/TMS_TOKEN come from
+ * the user's environment. Attaching the second to a host named by the first
+ * hands the credential -- and every translated string -- to whoever wrote the
+ * YAML, so an env-sourced credential only reaches a hostname the user has
+ * approved, either up front in `tms.allowedServers` or at a prompt whose answer
+ * is recorded in user config, outside the repo.
+ */
+
+import { ConfigError } from '../utils/errors.js';
+import { sanitizeForTerminal } from '../utils/control-chars.js';
+import { confirm, isNoInput } from '../utils/confirm.js';
+import { ConfigService } from '../storage/config.js';
+
+export const ALLOWED_SERVERS_CONFIG_KEY = 'tms.allowedServers';
+
+export type TmsCredentialSource = 'env' | 'config' | 'none';
+
+export interface TmsServerTrustDeps {
+  readAllowedServers?: () => string[];
+  approveServer?: (hostname: string) => void;
+  promptForApproval?: (message: string) => Promise<boolean>;
+  canPrompt?: () => boolean;
+}
+
+function parseServerUrl(serverUrl: string): URL | undefined {
+  try {
+    return new URL(serverUrl);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The origin alone, so the message names the destination without echoing a
+ * repo-controlled path or query back to the terminal.
+ */
+export function tmsServerOrigin(serverUrl: string): string {
+  const parsed = parseServerUrl(serverUrl);
+  return sanitizeForTerminal(parsed ? parsed.origin : serverUrl);
+}
+
+function readStringArray(service: ConfigService): string[] {
+  const value = service.getValue<unknown>(ALLOWED_SERVERS_CONFIG_KEY);
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+}
+
+function defaultReadAllowedServers(): string[] {
+  return readStringArray(new ConfigService());
+}
+
+function defaultApproveServer(hostname: string): void {
+  const service = new ConfigService();
+  const existing = readStringArray(service);
+  if (existing.some((entry) => entry.trim().toLowerCase() === hostname)) return;
+  service.set(ALLOWED_SERVERS_CONFIG_KEY, [...existing, hostname]);
+}
+
+function approvalCommand(existing: string[], hostname: string): string {
+  const hosts = [...existing.map((entry) => entry.toLowerCase()), hostname];
+  return `deepl config set ${ALLOWED_SERVERS_CONFIG_KEY} ${[...new Set(hosts)].join(',')}`;
+}
+
+function refuse(
+  reason: string,
+  existing: string[],
+  hostname: string
+): ConfigError {
+  return new ConfigError(
+    reason,
+    `Approve it once with:\n  ${approvalCommand(existing, hostname)}\n` +
+      `Or remove the tms.server value from .deepl-sync.yaml if you did not expect this checkout to name a TMS.`
+  );
+}
+
+export async function ensureTmsServerApproved(
+  serverUrl: string,
+  credentialSource: TmsCredentialSource,
+  deps: TmsServerTrustDeps = {}
+): Promise<void> {
+  if (credentialSource !== 'env') return;
+
+  // An unparseable URL never reaches the network: TmsClient.buildUrl rejects it
+  // with a message that names the malformed value.
+  const parsed = parseServerUrl(serverUrl);
+  if (!parsed) return;
+
+  const hostname = sanitizeForTerminal(parsed.hostname.toLowerCase());
+  const readAllowedServers =
+    deps.readAllowedServers ?? defaultReadAllowedServers;
+  const existing = readAllowedServers();
+  if (existing.some((entry) => entry.trim().toLowerCase() === hostname)) return;
+
+  const canPrompt =
+    deps.canPrompt ?? (() => !isNoInput() && !!process.stdin.isTTY);
+  if (!canPrompt()) {
+    throw refuse(
+      `Refusing to send an environment-supplied TMS credential to "${hostname}", which is not in ${ALLOWED_SERVERS_CONFIG_KEY}. ` +
+        `The destination was chosen by .deepl-sync.yaml in this checkout, and there is no terminal to confirm it on.`,
+      existing,
+      hostname
+    );
+  }
+
+  const promptForApproval =
+    deps.promptForApproval ?? ((message: string) => confirm({ message }));
+  const approved = await promptForApproval(
+    `.deepl-sync.yaml in this checkout points TMS sync at "${hostname}".\n` +
+      `  Continuing sends your TMS_API_KEY/TMS_TOKEN and every translated string to that host.\n` +
+      `  Trust "${hostname}" as a TMS destination from now on?`
+  );
+
+  if (!approved) {
+    throw refuse(
+      `TMS sync to "${hostname}" was not approved, so no credential or translation was sent.`,
+      existing,
+      hostname
+    );
+  }
+
+  const approveServer = deps.approveServer ?? defaultApproveServer;
+  approveServer(hostname);
+}
diff --git a/src/types/config.ts b/src/types/config.ts
index 9a009471..f204a7c7 100644
--- a/src/types/config.ts
+++ b/src/types/config.ts
@@ -33,4 +33,13 @@ export interface DeepLConfig {
     autoCommit: boolean;
     pattern: string;
   };
+  tms: {
+    /**
+     * Hostnames the user has approved as TMS destinations. `.deepl-sync.yaml`
+     * chooses `tms.server`, so a checkout the user does not control can name
+     * the host that an env-held TMS_API_KEY is sent to; only a hostname listed
+     * here (or approved at the prompt) receives an env-sourced credential.
+     */
+    allowedServers: string[];
+  };
 }
diff --git a/tests/e2e/cli-sync-push-pull.e2e.test.ts b/tests/e2e/cli-sync-push-pull.e2e.test.ts
index 5405fbb5..2b4f0b3e 100644
--- a/tests/e2e/cli-sync-push-pull.e2e.test.ts
+++ b/tests/e2e/cli-sync-push-pull.e2e.test.ts
@@ -124,6 +124,9 @@ describe('CLI sync push/pull dispatch E2E', () => {
       cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+      // The mock TMS runs on loopback; approve it as a destination so the
+      // env-supplied TMS_API_KEY is not withheld by the trust gate.
+      tms: { allowedServers: ['127.0.0.1'] },
     };
     fs.writeFileSync(
       path.join(testConfig.path, 'config.json'),
@@ -135,10 +138,15 @@ describe('CLI sync push/pull dispatch E2E', () => {
     opts: {
       targetLocales?: string[];
       includeTmsBlock?: boolean;
+      tmsServer?: string;
     } = {}
   ): void {
     const tms = opts.includeTmsBlock
-      ? { enabled: true, server: baseUrl, project_id: PROJECT_ID }
+      ? {
+          enabled: true,
+          server: opts.tmsServer ?? baseUrl,
+          project_id: PROJECT_ID,
+        }
       : undefined;
     const yaml = buildSyncConfigYaml({
       targetLocales: opts.targetLocales ?? ['de'],
@@ -241,6 +249,7 @@ describe('CLI sync push/pull dispatch E2E', () => {
       expect(run.status).toBe(0);
       const combined = run.stdout + run.stderr;
       expect(combined).toMatch(/Pushed \d+ translations to TMS/);
+      expect(combined).toContain(baseUrl);
 
       const state = await inspectMockServer();
       expect(state.requests.length).toBeGreaterThan(0);
@@ -274,6 +283,7 @@ describe('CLI sync push/pull dispatch E2E', () => {
       expect(run.status).toBe(0);
       const combined = run.stdout + run.stderr;
       expect(combined).toMatch(/Pulled \d+ translations from TMS/);
+      expect(combined).toContain(baseUrl);
 
       const targetFile = path.join(testFiles.path, 'locales', 'de.json');
       expect(fs.existsSync(targetFile)).toBe(true);
@@ -296,6 +306,98 @@ describe('CLI sync push/pull dispatch E2E', () => {
     });
   });
 
+  describe('repo-chosen destination not in tms.allowedServers', () => {
+    // The config dir approves 127.0.0.1 only, so pointing tms.server at
+    // "localhost" names an unapproved host that resolves to the SAME live mock
+    // TMS. If the gate did not fire, the push would succeed and the request
+    // would show up in the mock server's inspection state.
+    function unapprovedServer(): string {
+      return baseUrl.replace('127.0.0.1', 'localhost');
+    }
+
+    it('push: exits 7 without sending the env-supplied credential anywhere', async () => {
+      writeSyncYaml({ includeTmsBlock: true, tmsServer: unapprovedServer() });
+      writeSource({ greeting: 'Hello' });
+      writeTarget('de', { greeting: 'Hallo' });
+      await configureMockServer({});
+
+      const run = runCli(['sync', 'push'], {
+        TMS_API_KEY: 'must-not-leak',
+      });
+
+      expect(run.status).toBe(7);
+      const combined = run.stdout + run.stderr;
+      expect(combined).toContain('localhost');
+      expect(combined).toContain('deepl config set tms.allowedServers');
+      expect(combined).not.toContain('must-not-leak');
+
+      const state = await inspectMockServer();
+      expect(state.requests).toEqual([]);
+    });
+
+    it('pull: exits 7 without contacting the unapproved host', async () => {
+      writeSyncYaml({ includeTmsBlock: true, tmsServer: unapprovedServer() });
+      writeSource({ greeting: 'Hello' });
+      await configureMockServer({
+        pullResponses: { de: { greeting: 'Hallo (approved)' } },
+      });
+
+      const run = runCli(['sync', 'pull'], { TMS_API_KEY: 'must-not-leak' });
+
+      expect(run.status).toBe(7);
+      const combined = run.stdout + run.stderr;
+      expect(combined).toContain('deepl config set tms.allowedServers');
+
+      const state = await inspectMockServer();
+      expect(state.requests).toEqual([]);
+      expect(
+        fs.existsSync(path.join(testFiles.path, 'locales', 'de.json'))
+      ).toBe(false);
+    });
+
+    it('push --format json: emits the canonical ConfigError envelope', async () => {
+      writeSyncYaml({ includeTmsBlock: true, tmsServer: unapprovedServer() });
+      writeSource({ greeting: 'Hello' });
+      writeTarget('de', { greeting: 'Hallo' });
+      await configureMockServer({});
+
+      const run = runCli(['sync', 'push', '--format', 'json'], {
+        TMS_API_KEY: 'must-not-leak',
+      });
+
+      expect(run.status).toBe(7);
+      const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+      expect(envelope.error.message).toContain('localhost');
+      expect(envelope.error.suggestion).toContain(
+        'deepl config set tms.allowedServers'
+      );
+    });
+
+    it('push: a credential inlined in the repo YAML is not gated', async () => {
+      const yaml = buildSyncConfigYaml({
+        targetLocales: ['de'],
+        buckets: { json: { include: ['locales/en.json'] } },
+        tms: {
+          enabled: true,
+          server: unapprovedServer(),
+          project_id: PROJECT_ID,
+          api_key: 'inlined-in-repo',
+        },
+      });
+      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.yaml'), yaml);
+      writeSource({ greeting: 'Hello' });
+      writeTarget('de', { greeting: 'Hallo' });
+      await configureMockServer({});
+
+      const run = runCli(['sync', 'push']);
+
+      expect(run.status).toBe(0);
+      const state = await inspectMockServer();
+      expect(state.requests.length).toBeGreaterThan(0);
+      expect(state.requests[0]!.authHeader).toBe('ApiKey inlined-in-repo');
+    });
+  });
+
   describe('ConfigError when tms block absent', () => {
     it('push with no tms block: exits 7 with ConfigError, actionable remediation on stderr', () => {
       writeSyncYaml({ includeTmsBlock: false });
@@ -426,10 +528,12 @@ describe('CLI sync push/pull dispatch E2E', () => {
         ok: boolean;
         pushed: number;
         skipped: unknown[];
+        server: string;
       };
       expect(envelope.ok).toBe(true);
       expect(typeof envelope.pushed).toBe('number');
       expect(Array.isArray(envelope.skipped)).toBe(true);
+      expect(envelope.server).toBe(baseUrl);
     });
 
     it('pull --format json on success: exits 0, emits JSON success envelope on stdout', async () => {
@@ -449,10 +553,12 @@ describe('CLI sync push/pull dispatch E2E', () => {
         ok: boolean;
         pulled: number;
         skipped: unknown[];
+        server: string;
       };
       expect(envelope.ok).toBe(true);
       expect(typeof envelope.pulled).toBe('number');
       expect(Array.isArray(envelope.skipped)).toBe(true);
+      expect(envelope.server).toBe(baseUrl);
     });
 
     it('push --format json with missing tms block: emits canonical error envelope on stderr, exit 7', () => {
diff --git a/tests/e2e/cli-sync-tms.e2e.test.ts b/tests/e2e/cli-sync-tms.e2e.test.ts
index 12e4e1d8..3df68ea3 100644
--- a/tests/e2e/cli-sync-tms.e2e.test.ts
+++ b/tests/e2e/cli-sync-tms.e2e.test.ts
@@ -93,6 +93,9 @@ describe('CLI Sync TMS E2E', () => {
       cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: false },
       watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+      // The mock TMS runs on loopback; approve it as a destination so the
+      // env-supplied TMS_API_KEY is not withheld by the trust gate.
+      tms: { allowedServers: ['127.0.0.1'] },
     };
     fs.writeFileSync(
       path.join(configDir, 'config.json'),
diff --git a/tests/helpers/tms-nock.ts b/tests/helpers/tms-nock.ts
index d656609f..8c495545 100644
--- a/tests/helpers/tms-nock.ts
+++ b/tests/helpers/tms-nock.ts
@@ -12,7 +12,19 @@
 
 import nock from 'nock';
 
+import type { TmsServerTrustDeps } from '../../src/sync/tms-server-trust';
+
 export const TMS_BASE = 'https://tms.test';
+export const TMS_HOSTNAME = 'tms.test';
+
+/**
+ * Pre-approves TMS_BASE as a destination. `createTmsClient` refuses to attach
+ * an env-sourced TMS credential to a host the user's own config has not
+ * approved, and these suites drive that credential path deliberately.
+ */
+export const approvedTmsTrust: TmsServerTrustDeps = {
+  readAllowedServers: () => [TMS_HOSTNAME],
+};
 export const TMS_PROJECT = 'proj-42';
 export const TMS_API_KEY = 'tms-test-api-key';
 export const TMS_TOKEN = 'tms-test-token';
diff --git a/tests/integration/sync-symlink-safety.integration.test.ts b/tests/integration/sync-symlink-safety.integration.test.ts
index 5239074a..5c3a09d1 100644
--- a/tests/integration/sync-symlink-safety.integration.test.ts
+++ b/tests/integration/sync-symlink-safety.integration.test.ts
@@ -25,7 +25,12 @@ import { validateTranslations } from '../../src/sync/sync-validate';
 import { loadSyncConfig } from '../../src/sync/sync-config';
 
 import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
-import { expectTmsPush, expectTmsPull, tmsConfig } from '../helpers/tms-nock';
+import {
+  expectTmsPush,
+  expectTmsPull,
+  tmsConfig,
+  approvedTmsTrust,
+} from '../helpers/tms-nock';
 
 function writeJson(dir: string, relPath: string, obj: unknown): void {
   const abs = path.join(dir, relPath);
@@ -121,7 +126,7 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
     process.env['TMS_API_KEY'] = 'env-key';
 
     const config = await loadSyncConfig(projectDir);
-    const client = createTmsClient(config.tms!);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
 
     // Only the real file's key is expected on the wire; the symlinked secret
     // must not be read or transmitted.
@@ -153,7 +158,7 @@ describe('sync symlink safety (push/pull/export/validate)', () => {
     process.env['TMS_API_KEY'] = 'env-key';
 
     const config = await loadSyncConfig(projectDir);
-    const client = createTmsClient(config.tms!);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
 
     // The TMS server returns translations for BOTH "greeting" and
     // "exfiltrated". If the symlinked source is read, pullTranslations will
diff --git a/tests/integration/sync-tms.integration.test.ts b/tests/integration/sync-tms.integration.test.ts
index 6d9aa93f..5355abd2 100644
--- a/tests/integration/sync-tms.integration.test.ts
+++ b/tests/integration/sync-tms.integration.test.ts
@@ -20,14 +20,17 @@ import { pushTranslations, pullTranslations } from '../../src/sync/sync-tms';
 import { loadSyncConfig } from '../../src/sync/sync-config';
 import { LOCK_FILE_NAME } from '../../src/sync/types';
 import { ConfigError } from '../../src/utils/errors';
+import { ConfigService } from '../../src/storage/config';
 
 import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
 import {
   TMS_BASE,
+  TMS_HOSTNAME,
   TMS_PROJECT,
   expectTmsPush,
   expectTmsPull,
   tmsConfig,
+  approvedTmsTrust,
 } from '../helpers/tms-nock';
 
 function writeJson(dir: string, relPath: string, obj: unknown): void {
@@ -73,7 +76,7 @@ describe('sync push/pull (TMS integration)', () => {
     process.env['TMS_API_KEY'] = 'env-key';
 
     const config = await loadSyncConfig(tmpDir);
-    const client = createTmsClient(config.tms!);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
 
     const scopes = [
       expectTmsPush('farewell', 'de', 'Auf Wiedersehen', {
@@ -105,7 +108,7 @@ describe('sync push/pull (TMS integration)', () => {
     process.env['TMS_API_KEY'] = 'env-key';
 
     const config = await loadSyncConfig(tmpDir);
-    const client = createTmsClient(config.tms!);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
 
     const pullScope = expectTmsPull(
       'de',
@@ -161,7 +164,7 @@ describe('sync push/pull (TMS integration)', () => {
     process.env['TMS_API_KEY'] = 'from-env';
 
     const config = await loadSyncConfig(tmpDir);
-    const client = createTmsClient(config.tms!);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
 
     const scope = expectTmsPush('k', 'de', 'Hallo', {
       auth: { apiKey: 'from-env' },
@@ -180,7 +183,7 @@ describe('sync push/pull (TMS integration)', () => {
     process.env['TMS_TOKEN'] = 'the-token';
 
     const config = await loadSyncConfig(tmpDir);
-    const client = createTmsClient(config.tms!);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
 
     const scope = expectTmsPush('k', 'de', 'Hallo', {
       auth: { token: 'the-token' },
@@ -199,7 +202,7 @@ describe('sync push/pull (TMS integration)', () => {
       .mockImplementation(() => undefined);
     try {
       const config = await loadSyncConfig(tmpDir);
-      createTmsClient(config.tms!);
+      await createTmsClient(config.tms!, approvedTmsTrust);
       expect(warn).toHaveBeenCalledWith(
         expect.stringMatching(/TMS API key found in config file.*TMS_API_KEY/)
       );
@@ -246,7 +249,7 @@ describe('sync push/pull (TMS integration)', () => {
     process.env['TMS_API_KEY'] = 'bogus';
 
     const config = await loadSyncConfig(tmpDir);
-    const client = createTmsClient(config.tms!);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
 
     nock(TMS_BASE)
       .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
@@ -264,3 +267,106 @@ describe('sync push/pull (TMS integration)', () => {
     ).rejects.toThrow(/TMS authentication failed \(401/);
   });
 });
+
+describe('TMS destination trust (real user config store)', () => {
+  let tmpDir: string;
+  let configDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+  let envSnapshot: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    envSnapshot = { ...process.env };
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-tms-trust-'));
+    configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-tms-cfg-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    process.env['DEEPL_CONFIG_DIR'] = configDir;
+    process.env['TMS_API_KEY'] = 'MUST-NOT-LEAK';
+    delete process.env['TMS_TOKEN'];
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    for (const dir of [tmpDir, configDir]) {
+      if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+    process.env = envSnapshot;
+  });
+
+  function seedRepo(): void {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeJson(tmpDir, 'locales/en.json', { greeting: 'Hello' });
+    writeJson(tmpDir, 'locales/de.json', { greeting: 'Hallo' });
+  }
+
+  it('refuses an unapproved host and sends nothing, reading the real user config', async () => {
+    seedRepo();
+    const scope = expectTmsPush('greeting', 'de', 'Hallo');
+
+    const config = await loadSyncConfig(tmpDir);
+    await expect(
+      createTmsClient(config.tms!, { canPrompt: () => false })
+    ).rejects.toThrow(ConfigError);
+    expect(scope.isDone()).toBe(false);
+  });
+
+  it('proceeds when the host was pre-approved with deepl config set', async () => {
+    new ConfigService().set('tms.allowedServers', [TMS_HOSTNAME]);
+    seedRepo();
+    const scope = expectTmsPush('greeting', 'de', 'Hallo', {
+      auth: { apiKey: 'MUST-NOT-LEAK' },
+    });
+
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, {
+      canPrompt: () => false,
+    });
+    const result = await pushTranslations(config, client, harness.registry);
+    expect(result.pushed).toBe(1);
+    expect(scope.isDone()).toBe(true);
+  });
+
+  it('records an accepted prompt in the user config, outside the repo', async () => {
+    seedRepo();
+    const config = await loadSyncConfig(tmpDir);
+    await createTmsClient(config.tms!, {
+      canPrompt: () => true,
+      promptForApproval: async () => true,
+    });
+
+    expect(new ConfigService().getValue('tms.allowedServers')).toEqual([
+      TMS_HOSTNAME,
+    ]);
+    expect(fs.existsSync(path.join(configDir, 'config.json'))).toBe(true);
+    expect(fs.readdirSync(tmpDir)).not.toContain('config.json');
+  });
+
+  it('does not prompt again on a later run once approved', async () => {
+    seedRepo();
+    const config = await loadSyncConfig(tmpDir);
+    const promptForApproval = jest.fn(async () => true);
+    await createTmsClient(config.tms!, {
+      canPrompt: () => true,
+      promptForApproval,
+    });
+    await createTmsClient(config.tms!, {
+      canPrompt: () => true,
+      promptForApproval,
+    });
+    expect(promptForApproval).toHaveBeenCalledTimes(1);
+  });
+
+  it('records the approval only once when the same host is approved twice', async () => {
+    seedRepo();
+    const config = await loadSyncConfig(tmpDir);
+    for (let i = 0; i < 2; i++) {
+      await createTmsClient(config.tms!, {
+        canPrompt: () => true,
+        promptForApproval: async () => true,
+      });
+    }
+    expect(new ConfigService().getValue('tms.allowedServers')).toEqual([
+      TMS_HOSTNAME,
+    ]);
+  });
+});
diff --git a/tests/unit/config-command.test.ts b/tests/unit/config-command.test.ts
index 7b818555..3ed62087 100644
--- a/tests/unit/config-command.test.ts
+++ b/tests/unit/config-command.test.ts
@@ -103,6 +103,26 @@ describe('ConfigCommand', () => {
       );
     });
 
+    it('should parse a single tms.allowedServers hostname as a one-element array', async () => {
+      await configCommand.set('tms.allowedServers', 'tms.example.com');
+
+      expect(mockConfigService.set).toHaveBeenCalledWith('tms.allowedServers', [
+        'tms.example.com',
+      ]);
+    });
+
+    it('should parse comma-separated tms.allowedServers hostnames as an array', async () => {
+      await configCommand.set(
+        'tms.allowedServers',
+        'a.example.com,b.example.com'
+      );
+
+      expect(mockConfigService.set).toHaveBeenCalledWith('tms.allowedServers', [
+        'a.example.com',
+        'b.example.com',
+      ]);
+    });
+
     it('should set boolean values', async () => {
       await configCommand.set('cache.enabled', 'false');
 
diff --git a/tests/unit/config-service.test.ts b/tests/unit/config-service.test.ts
index 73aaba82..84dac620 100644
--- a/tests/unit/config-service.test.ts
+++ b/tests/unit/config-service.test.ts
@@ -266,6 +266,98 @@ describe('ConfigService', () => {
     });
   });
 
+  describe('tms.allowedServers', () => {
+    it('defaults to an empty list, so no destination is trusted implicitly', () => {
+      expect(configService.get().tms.allowedServers).toEqual([]);
+    });
+
+    it('accepts an array of hostnames', () => {
+      configService.set('tms.allowedServers', [
+        'tms.example.com',
+        'tms2.example.com',
+      ]);
+      expect(configService.getValue('tms.allowedServers')).toEqual([
+        'tms.example.com',
+        'tms2.example.com',
+      ]);
+    });
+
+    it('lowercases stored hostnames so matching is not case-sensitive on disk', () => {
+      configService.set('tms.allowedServers', ['TMS.Example.COM']);
+      expect(configService.getValue('tms.allowedServers')).toEqual([
+        'tms.example.com',
+      ]);
+    });
+
+    it('trims surrounding whitespace from each hostname', () => {
+      configService.set('tms.allowedServers', ['  tms.example.com  ']);
+      expect(configService.getValue('tms.allowedServers')).toEqual([
+        'tms.example.com',
+      ]);
+    });
+
+    it('rejects a bare string — a single host must still be a one-element array', () => {
+      expect(() => {
+        configService.set('tms.allowedServers', 'tms.example.com');
+      }).toThrow(/tms\.allowedServers must be an array of hostnames/);
+    });
+
+    it('rejects a non-string entry', () => {
+      expect(() => {
+        configService.set('tms.allowedServers', ['tms.example.com', 42]);
+      }).toThrow(/tms\.allowedServers entries must be strings/);
+    });
+
+    it('rejects an empty hostname', () => {
+      expect(() => {
+        configService.set('tms.allowedServers', ['tms.example.com', '  ']);
+      }).toThrow(/tms\.allowedServers entries must not be empty/);
+    });
+
+    it('rejects a full URL, naming the hostname-only expectation', () => {
+      expect(() => {
+        configService.set('tms.allowedServers', ['https://tms.example.com']);
+      }).toThrow(/bare hostname/);
+    });
+
+    it('rejects a host:port pair', () => {
+      expect(() => {
+        configService.set('tms.allowedServers', ['tms.example.com:8443']);
+      }).toThrow(/bare hostname/);
+    });
+
+    it('rejects an entry with a path', () => {
+      expect(() => {
+        configService.set('tms.allowedServers', ['tms.example.com/api']);
+      }).toThrow(/bare hostname/);
+    });
+
+    it('rejects an entry containing whitespace', () => {
+      expect(() => {
+        configService.set('tms.allowedServers', ['tms example.com']);
+      }).toThrow(/bare hostname/);
+    });
+
+    it('rejects a wildcard, which is not supported', () => {
+      expect(() => {
+        configService.set('tms.allowedServers', ['*.example.com']);
+      }).toThrow(/bare hostname/);
+    });
+
+    it('accepts a bracketed IPv6 literal, matching URL.hostname', () => {
+      configService.set('tms.allowedServers', ['[::1]']);
+      expect(configService.getValue('tms.allowedServers')).toEqual(['[::1]']);
+    });
+
+    it('preserves a loaded allowlist across a reload rather than dropping the block', () => {
+      configService.set('tms.allowedServers', ['tms.example.com']);
+      const reloaded = new ConfigService(mockConfigPath);
+      expect(reloaded.getValue('tms.allowedServers')).toEqual([
+        'tms.example.com',
+      ]);
+    });
+  });
+
   describe('edge cases', () => {
     it('should handle empty string values', () => {
       configService.set('auth.apiKey', '');
diff --git a/tests/unit/sync/tms-client.test.ts b/tests/unit/sync/tms-client.test.ts
index a0eb551b..27195526 100644
--- a/tests/unit/sync/tms-client.test.ts
+++ b/tests/unit/sync/tms-client.test.ts
@@ -6,6 +6,7 @@ import {
   createTmsClient,
 } from '../../../src/sync/tms-client';
 import type { SyncTmsConfig } from '../../../src/sync/types';
+import type { TmsServerTrustDeps } from '../../../src/sync/tms-server-trust';
 import { ConfigError, ValidationError } from '../../../src/utils/errors';
 import { ExitCode, exitCodeForError } from '../../../src/utils/exit-codes';
 
@@ -577,11 +578,136 @@ describe('resolveTmsCredentials', () => {
     expect(result.apiKey).toBeUndefined();
     expect(result.token).toBeUndefined();
   });
+
+  describe('credential provenance', () => {
+    it('reports env when TMS_API_KEY supplied the key', () => {
+      process.env['TMS_API_KEY'] = 'env-key';
+      expect(resolveTmsCredentials({ api_key: 'config-key' }).source).toBe(
+        'env'
+      );
+    });
+
+    it('reports env when TMS_TOKEN supplied the only credential', () => {
+      process.env['TMS_TOKEN'] = 'env-token';
+      expect(resolveTmsCredentials({}).source).toBe('env');
+    });
+
+    it('reports config when the credential was inlined in the repo YAML', () => {
+      expect(resolveTmsCredentials({ api_key: 'config-key' }).source).toBe(
+        'config'
+      );
+    });
+
+    it('reports config for an inlined token', () => {
+      expect(resolveTmsCredentials({ token: 'config-token' }).source).toBe(
+        'config'
+      );
+    });
+
+    it('reports none when there is no credential', () => {
+      expect(resolveTmsCredentials({}).source).toBe('none');
+    });
+
+    it('reports config when the api_key that will actually be sent came from config', () => {
+      // getAuthHeader prefers apiKey, so an env token is never attached here.
+      process.env['TMS_TOKEN'] = 'env-token';
+      expect(resolveTmsCredentials({ api_key: 'config-key' }).source).toBe(
+        'config'
+      );
+    });
+
+    it('reports env when an empty TMS_API_KEY falls through to an env token', () => {
+      process.env['TMS_API_KEY'] = '';
+      process.env['TMS_TOKEN'] = 'env-token';
+      expect(resolveTmsCredentials({}).source).toBe('env');
+    });
+  });
+});
+
+describe('createTmsClient destination trust', () => {
+  let envSnapshot: NodeJS.ProcessEnv;
+
+  const baseConfig: SyncTmsConfig = {
+    enabled: true,
+    server: 'https://tms.evil.test',
+    project_id: 'proj-1',
+  };
+
+  beforeEach(() => {
+    envSnapshot = { ...process.env };
+    delete process.env['TMS_API_KEY'];
+    delete process.env['TMS_TOKEN'];
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    process.env = envSnapshot;
+  });
+
+  it('refuses to build a client that would send an env credential to an unapproved host', async () => {
+    process.env['TMS_API_KEY'] = 'TMS-SECRET-CREDENTIAL-1234';
+    await expect(
+      createTmsClient(baseConfig, {
+        readAllowedServers: () => [],
+        canPrompt: () => false,
+      })
+    ).rejects.toThrow(ConfigError);
+  });
+
+  it('never issues a request when the destination is refused', async () => {
+    process.env['TMS_API_KEY'] = 'TMS-SECRET-CREDENTIAL-1234';
+    await expect(
+      createTmsClient(baseConfig, {
+        readAllowedServers: () => [],
+        canPrompt: () => false,
+      })
+    ).rejects.toThrow();
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('builds a client when the host is already approved', async () => {
+    process.env['TMS_API_KEY'] = 'env-key';
+    const client = await createTmsClient(baseConfig, {
+      readAllowedServers: () => ['tms.evil.test'],
+    });
+    mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
+    await client.pushKey('k', 'de', 'v');
+    expect(mockFetch).toHaveBeenCalled();
+  });
+
+  it('builds a client without gating when the credential is inlined in the repo YAML', async () => {
+    const promptForApproval = jest.fn(async () => true);
+    const client = await createTmsClient(
+      { ...baseConfig, api_key: 'config-key' },
+      { promptForApproval, canPrompt: () => true }
+    );
+    mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
+    await client.pushKey('k', 'de', 'v');
+    expect(promptForApproval).not.toHaveBeenCalled();
+  });
+
+  it('records the approval when the user accepts at the prompt', async () => {
+    process.env['TMS_API_KEY'] = 'env-key';
+    const approveServer = jest.fn();
+    await createTmsClient(baseConfig, {
+      readAllowedServers: () => [],
+      canPrompt: () => true,
+      promptForApproval: async () => true,
+      approveServer,
+    });
+    expect(approveServer).toHaveBeenCalledWith('tms.evil.test');
+  });
 });
 
 describe('createTmsClient', () => {
   let envSnapshot: NodeJS.ProcessEnv;
 
+  // These cases assert credential precedence, not destination trust, so the
+  // hosts they use are pre-approved.
+  const approved: TmsServerTrustDeps = {
+    readAllowedServers: () => ['tms.example.com', 'custom.example.com'],
+  };
+
   beforeEach(() => {
     envSnapshot = { ...process.env };
     delete process.env['TMS_API_KEY'];
@@ -601,7 +727,10 @@ describe('createTmsClient', () => {
 
   it('should read TMS_API_KEY env var when building the client (in preference to config.api_key)', async () => {
     process.env['TMS_API_KEY'] = 'env-key';
-    const client = createTmsClient({ ...baseConfig, api_key: 'config-key' });
+    const client = await createTmsClient(
+      { ...baseConfig, api_key: 'config-key' },
+      approved
+    );
 
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('k', 'de', 'v');
@@ -614,7 +743,7 @@ describe('createTmsClient', () => {
 
   it('should read TMS_TOKEN env var when building the client', async () => {
     process.env['TMS_TOKEN'] = 'env-token';
-    const client = createTmsClient({ ...baseConfig });
+    const client = await createTmsClient({ ...baseConfig }, approved);
 
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('k', 'de', 'v');
@@ -626,7 +755,10 @@ describe('createTmsClient', () => {
   });
 
   it('should fall back to config credentials when no env vars set', async () => {
-    const client = createTmsClient({ ...baseConfig, api_key: 'config-key' });
+    const client = await createTmsClient(
+      { ...baseConfig, api_key: 'config-key' },
+      approved
+    );
 
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('k', 'de', 'v');
@@ -639,11 +771,14 @@ describe('createTmsClient', () => {
 
   it('should pass server URL and project_id to the constructed client', async () => {
     process.env['TMS_API_KEY'] = 'env-key';
-    const client = createTmsClient({
-      ...baseConfig,
-      server: 'https://custom.example.com',
-      project_id: 'custom-proj',
-    });
+    const client = await createTmsClient(
+      {
+        ...baseConfig,
+        server: 'https://custom.example.com',
+        project_id: 'custom-proj',
+      },
+      approved
+    );
 
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await client.pushKey('greeting', 'de', 'Hallo');
diff --git a/tests/unit/sync/tms-server-trust.test.ts b/tests/unit/sync/tms-server-trust.test.ts
new file mode 100644
index 00000000..320ba4a1
--- /dev/null
+++ b/tests/unit/sync/tms-server-trust.test.ts
@@ -0,0 +1,338 @@
+/**
+ * Tests for the TMS destination trust gate.
+ *
+ * The hostile input is `.deepl-sync.yaml` naming `tms.server`; the secret at
+ * risk is TMS_API_KEY / TMS_TOKEN from the user's environment.
+ */
+
+import {
+  ensureTmsServerApproved,
+  tmsServerOrigin,
+} from '../../../src/sync/tms-server-trust';
+import { ConfigError } from '../../../src/utils/errors';
+import { setNoInput } from '../../../src/utils/confirm';
+
+interface Harness {
+  readAllowedServers: jest.Mock<string[], []>;
+  approveServer: jest.Mock<void, [string]>;
+  promptForApproval: jest.Mock<Promise<boolean>, [string]>;
+  canPrompt: jest.Mock<boolean, []>;
+}
+
+function harness(overrides: Partial<Harness> = {}): Harness {
+  return {
+    readAllowedServers: jest.fn<string[], []>(() => []),
+    approveServer: jest.fn<void, [string]>(),
+    promptForApproval: jest.fn<Promise<boolean>, [string]>(async () => true),
+    canPrompt: jest.fn<boolean, []>(() => true),
+    ...overrides,
+  };
+}
+
+describe('ensureTmsServerApproved', () => {
+  describe('credential provenance', () => {
+    it('does not gate a credential inlined in the repo YAML (nothing of the user’s leaks)', async () => {
+      const deps = harness();
+      await expect(
+        ensureTmsServerApproved('https://tms.evil.test', 'config', deps)
+      ).resolves.toBeUndefined();
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+      expect(deps.readAllowedServers).not.toHaveBeenCalled();
+    });
+
+    it('does not gate when there is no credential at all', async () => {
+      const deps = harness();
+      await expect(
+        ensureTmsServerApproved('https://tms.evil.test', 'none', deps)
+      ).resolves.toBeUndefined();
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+    });
+
+    it('gates an env-sourced credential against an unapproved host', async () => {
+      const deps = harness({
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      await expect(
+        ensureTmsServerApproved('https://tms.evil.test', 'env', deps)
+      ).rejects.toThrow(ConfigError);
+    });
+  });
+
+  describe('allowlist', () => {
+    it('approves silently when the hostname is listed', async () => {
+      const deps = harness({
+        readAllowedServers: jest.fn<string[], []>(() => ['tms.example.com']),
+      });
+      await expect(
+        ensureTmsServerApproved('https://tms.example.com', 'env', deps)
+      ).resolves.toBeUndefined();
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+      expect(deps.approveServer).not.toHaveBeenCalled();
+    });
+
+    it('matches the hostname case-insensitively', async () => {
+      const deps = harness({
+        readAllowedServers: jest.fn<string[], []>(() => ['TMS.Example.COM']),
+      });
+      await expect(
+        ensureTmsServerApproved('https://tms.example.com', 'env', deps)
+      ).resolves.toBeUndefined();
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+    });
+
+    it('ignores the port, path, and scheme when matching', async () => {
+      const deps = harness({
+        readAllowedServers: jest.fn<string[], []>(() => ['tms.example.com']),
+      });
+      await expect(
+        ensureTmsServerApproved(
+          'https://tms.example.com:8443/base/path',
+          'env',
+          deps
+        )
+      ).resolves.toBeUndefined();
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+    });
+
+    it('does not treat a listed host as approving a subdomain of it', async () => {
+      const deps = harness({
+        readAllowedServers: jest.fn<string[], []>(() => ['example.com']),
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      await expect(
+        ensureTmsServerApproved('https://tms.example.com', 'env', deps)
+      ).rejects.toThrow(ConfigError);
+    });
+
+    it('does not treat a listed host as approving a suffix-matching impostor', async () => {
+      const deps = harness({
+        readAllowedServers: jest.fn<string[], []>(() => ['tms.example.com']),
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      await expect(
+        ensureTmsServerApproved('https://evil-tms.example.com', 'env', deps)
+      ).rejects.toThrow(ConfigError);
+    });
+
+    it('gates a loopback host too — a co-tenant listener is still an exfiltration sink', async () => {
+      const deps = harness({
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      await expect(
+        ensureTmsServerApproved('http://127.0.0.1:9999', 'env', deps)
+      ).rejects.toThrow(ConfigError);
+    });
+  });
+
+  describe('trust on first use', () => {
+    it('prompts naming the host and what would be sent', async () => {
+      const deps = harness();
+      await ensureTmsServerApproved('https://tms.evil.test', 'env', deps);
+      const message = deps.promptForApproval.mock.calls[0]?.[0] ?? '';
+      expect(message).toContain('tms.evil.test');
+      expect(message).toMatch(/TMS_API_KEY|credential/i);
+      expect(message).toMatch(/translat/i);
+    });
+
+    it('records the approval outside the repo when the user accepts', async () => {
+      const deps = harness();
+      await expect(
+        ensureTmsServerApproved('https://tms.evil.test', 'env', deps)
+      ).resolves.toBeUndefined();
+      expect(deps.approveServer).toHaveBeenCalledWith('tms.evil.test');
+    });
+
+    it('records the hostname lowercased, not the full URL', async () => {
+      const deps = harness();
+      await ensureTmsServerApproved(
+        'https://TMS.Example.TEST:8443/x',
+        'env',
+        deps
+      );
+      expect(deps.approveServer).toHaveBeenCalledWith('tms.example.test');
+    });
+
+    it('fails closed and records nothing when the user declines', async () => {
+      const deps = harness({
+        promptForApproval: jest.fn<Promise<boolean>, [string]>(
+          async () => false
+        ),
+      });
+      await expect(
+        ensureTmsServerApproved('https://tms.evil.test', 'env', deps)
+      ).rejects.toThrow(ConfigError);
+      expect(deps.approveServer).not.toHaveBeenCalled();
+    });
+
+    it('prompts with the parsed hostname, not the raw configured URL', async () => {
+      const deps = harness();
+      await ensureTmsServerApproved(
+        'https://tms.evil.test/base?ignored#frag',
+        'env',
+        deps
+      );
+      const message = deps.promptForApproval.mock.calls[0]?.[0] ?? '';
+      expect(message).toContain('tms.evil.test');
+      expect(message).not.toContain('#frag');
+    });
+  });
+
+  describe('non-interactive fail-closed', () => {
+    it('never prompts when prompting is unavailable', async () => {
+      const deps = harness({
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      await expect(
+        ensureTmsServerApproved('https://tms.evil.test', 'env', deps)
+      ).rejects.toThrow(ConfigError);
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+    });
+
+    it('exits 7 so the failure is a config error, not a generic one', async () => {
+      const deps = harness({
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      expect.assertions(2);
+      try {
+        await ensureTmsServerApproved('https://tms.evil.test', 'env', deps);
+      } catch (err) {
+        expect(err).toBeInstanceOf(ConfigError);
+        expect((err as ConfigError).exitCode).toBe(7);
+      }
+    });
+
+    it('names the host and the exact config command to approve it', async () => {
+      const deps = harness({
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      expect.assertions(2);
+      try {
+        await ensureTmsServerApproved('https://tms.evil.test', 'env', deps);
+      } catch (err) {
+        const text = `${(err as ConfigError).message}\n${(err as ConfigError).suggestion ?? ''}`;
+        expect(text).toContain('tms.evil.test');
+        expect(text).toContain(
+          'deepl config set tms.allowedServers tms.evil.test'
+        );
+      }
+    });
+
+    it('preserves already-approved hosts in the suggested command', async () => {
+      const deps = harness({
+        readAllowedServers: jest.fn<string[], []>(() => [
+          'tms.a.example',
+          'tms.b.example',
+        ]),
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      expect.assertions(1);
+      try {
+        await ensureTmsServerApproved('https://tms.new.example', 'env', deps);
+      } catch (err) {
+        expect((err as ConfigError).suggestion).toContain(
+          'deepl config set tms.allowedServers tms.a.example,tms.b.example,tms.new.example'
+        );
+      }
+    });
+  });
+
+  describe('default canPrompt', () => {
+    let originalIsTTY: boolean | undefined;
+
+    beforeEach(() => {
+      originalIsTTY = process.stdin.isTTY;
+    });
+
+    afterEach(() => {
+      setNoInput(false);
+      Object.defineProperty(process.stdin, 'isTTY', {
+        value: originalIsTTY,
+        writable: true,
+        configurable: true,
+      });
+    });
+
+    function setTTY(value: boolean | undefined): void {
+      Object.defineProperty(process.stdin, 'isTTY', {
+        value,
+        writable: true,
+        configurable: true,
+      });
+    }
+
+    it('fails closed on a non-TTY stdin even when a prompt would be answered', async () => {
+      setTTY(undefined);
+      const deps = harness();
+      await expect(
+        ensureTmsServerApproved('https://tms.evil.test', 'env', {
+          readAllowedServers: deps.readAllowedServers,
+          approveServer: deps.approveServer,
+          promptForApproval: deps.promptForApproval,
+        })
+      ).rejects.toThrow(ConfigError);
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+    });
+
+    it('fails closed under --no-input even on a TTY', async () => {
+      setTTY(true);
+      setNoInput(true);
+      const deps = harness();
+      await expect(
+        ensureTmsServerApproved('https://tms.evil.test', 'env', {
+          readAllowedServers: deps.readAllowedServers,
+          approveServer: deps.approveServer,
+          promptForApproval: deps.promptForApproval,
+        })
+      ).rejects.toThrow(ConfigError);
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+    });
+
+    it('prompts on a TTY without --no-input', async () => {
+      setTTY(true);
+      const deps = harness();
+      await ensureTmsServerApproved('https://tms.evil.test', 'env', {
+        readAllowedServers: deps.readAllowedServers,
+        approveServer: deps.approveServer,
+        promptForApproval: deps.promptForApproval,
+      });
+      expect(deps.promptForApproval).toHaveBeenCalled();
+    });
+  });
+
+  describe('malformed server URLs', () => {
+    it('defers an unparseable URL to the client’s own validation', async () => {
+      const deps = harness({
+        canPrompt: jest.fn<boolean, []>(() => false),
+      });
+      await expect(
+        ensureTmsServerApproved('not a url', 'env', deps)
+      ).resolves.toBeUndefined();
+      expect(deps.promptForApproval).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe('tmsServerOrigin', () => {
+  it('reduces a server URL to its origin', () => {
+    expect(tmsServerOrigin('https://tms.example.com/base/path')).toBe(
+      'https://tms.example.com'
+    );
+  });
+
+  it('keeps a non-default port', () => {
+    expect(tmsServerOrigin('https://tms.example.com:8443/x')).toBe(
+      'https://tms.example.com:8443'
+    );
+  });
+
+  it('falls back to a sanitized value for an unparseable URL', () => {
+    expect(tmsServerOrigin('not a url')).toBe('not a url');
+  });
+
+  it('neutralizes terminal control sequences in the unparseable fallback', () => {
+    const hostile = 'ht tp://x\u001b]0;pwned\u0007';
+    const rendered = tmsServerOrigin(hostile);
+    expect(rendered).not.toContain('\u001b');
+    expect(rendered).not.toContain('\u0007');
+  });
+});
diff --git a/tests/unit/translation-service.test.ts b/tests/unit/translation-service.test.ts
index 60292bc5..098f207a 100644
--- a/tests/unit/translation-service.test.ts
+++ b/tests/unit/translation-service.test.ts
@@ -105,6 +105,7 @@ describe('TranslationService', () => {
         auth: {},
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
+        tms: { allowedServers: [] },
       });
 
       mockDeepLClient.translate.mockResolvedValue({
@@ -140,6 +141,7 @@ describe('TranslationService', () => {
         auth: {},
         output: { format: 'text', color: true, verbose: false },
         watch: { debounceMs: 500, autoCommit: false, pattern: '**/*' },
+        tms: { allowedServers: [] },
       });
 
       mockDeepLClient.translate.mockResolvedValue({

From 8d8dd687ee944748bdac109f8d491560260b7bc1 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 16:36:39 +0200
Subject: [PATCH 135/256] fix(sync): refuse a sync target path whose first
 segment begins with "-"

A rendered target path reaches git as a single argv entry, where a leading
dash is parsed as an option rather than a pathspec. Both `git add` and
`git commit` already pass `--`, so this is the defense-in-depth half:
target_path_pattern: --pathspec-from-file={locale} satisfied every existing
check and rendered verbatim.

Three routes produce a dash-leading target, not the one the report named:
the literal pattern, a {basename} taken from a dash-leading source filename,
and the default locale-substitution branch over a dash-leading source
directory. The first fails at config load (ConfigError, exit 7); all three
fail in resolveTargetPath (ValidationError, exit 6), which is the only tier
the latter two pass through.

Only the first segment is checked, so res/values-{locale}/strings.xml,
locales/zh-Hans.json and locales/-legacy/{locale}.json still resolve.

Refs cli-8kr2.48
---
 CHANGELOG.md                        |  2 ++
 docs/SYNC.md                        |  2 ++
 src/sync/sync-config.ts             | 11 ++++++
 src/sync/sync-utils.ts              | 34 +++++++++++++++---
 tests/unit/sync/sync-config.test.ts | 32 +++++++++++++++++
 tests/unit/sync/sync-utils.test.ts  | 55 +++++++++++++++++++++++++++++
 6 files changed, 131 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 197a1e7a..b8acfd7e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -377,6 +377,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync**: **a sync target path can no longer begin with `-`**, closing the defense-in-depth half of the `git add`/`git commit` option-injection fix. The argv side was already fixed — both call sites pass `--` before the pathspec — but `.deepl-sync.yaml` could still name a target that *looks* like an option, and validation accepted it: `target_path_pattern: --pathspec-from-file={locale}` satisfies all four existing checks (a string, contains `{locale}`, no `..`, no `.git`/`.github` segment) and `resolveTargetPath` rendered it verbatim to `--pathspec-from-file=de`. Reproduced by execution, and the finding named only one of **three** routes to a dash-leading target: the literal pattern, a `{basename}` taken from a source file the glob discovered whose own name begins with `-` (`--pathspec-from-file=x.json` + `{basename}.{locale}.json` → `--pathspec-from-file=x.json.de.json`), and the default locale-substitution branch running over a dash-leading source directory (`-o/en.json` → `-o/de.json`), which involves no pattern at all. Rejecting the pattern alone would therefore have left two thirds of the class open. Two tiers, mirroring how `FORBIDDEN_TARGET_SEGMENTS` is already enforced twice: a literal pattern beginning with `-` fails at config load with `ConfigError` (exit 7), and every path `resolveTargetPath` renders is checked again and fails with `ValidationError` (exit 6), which is the only tier the `{basename}` and locale-substitution routes pass through. **Only the first segment** is checked, because the rendered path is one argv entry and a dash later in it is never option-like — `res/values-{locale}/strings.xml`, `locales/zh-Hans.json` and `locales/-legacy/{locale}.json` all still resolve, verified alongside the three refusals.
+
 - **sync**: **a `tms.server` value in the checkout can no longer redirect the operator's environment-held `TMS_API_KEY` to a host of its choosing.** `.deepl-sync.yaml` picks the destination, `TMS_API_KEY`/`TMS_TOKEN` come from the operator's environment, and `createTmsClient` wired the two together with the only destination guard being **scheme, not identity** — `buildUrl` requires `https:` (waived for `localhost`/`127.0.0.1`) and nothing checked *who* was on the other end. Nothing secret had to be in the repo. Reproduced end to end: a hostile checkout with `tms: {enabled: true, server: http://127.0.0.1:<port>, project_id: victim-project}`, an operator with `TMS_API_KEY` exported (normal for cross-project use), `deepl sync push` → **`Pushed 1 translations to TMS`, exit 0**, while the listener captured `PUT /api/projects/victim-project/keys/greeting` with `authorization: ApiKey TMS-SECRET-CREDENTIAL-1234` and the translated string in the body. `resolveTmsCredentials` did warn — but only about credentials *inlined in the YAML*, never about the YAML choosing the *destination*, and the success line named a count and no host. Now a **hybrid allowlist plus trust-on-first-use** gates it, in `createTmsClient` so both `sync push` and `sync pull` are covered by one choke point: the hostname must appear in a new user-level `tms.allowedServers` list, or be approved once at a prompt that names the host and states that the credential and every translated string would go to it. An accepted answer is recorded in **user** config (`~/.config/deepl-cli/config.json`), never in the repository, so it survives a fresh clone and does not travel with the repo. Under `--no-input` or on a non-TTY the run **fails closed with exit 7** naming the host and the exact `deepl config set tms.allowedServers <hosts>` command, with the already-approved hosts preserved in the suggested value so following it is not destructive. Verified under a real pty: declining exits 7 with nothing sent and nothing recorded; accepting exits 0, writes `allowedServers: ['localhost']` to the isolated config dir, and a later non-TTY run proceeds without prompting. Four scoping decisions the finding did not settle. The gate keys on **credential provenance**, not merely on a repo-supplied host: a credential inlined as `tms.api_key`/`tms.token` is not gated, because it belongs to the same file that chose the destination and nothing of the operator's leaks — and provenance is computed for the credential `getAuthHeader` will *actually* attach, which prefers `api_key`, so an env-held token sitting behind a config-held key does not trigger a prompt it could never leak through. Allowlist-only was rejected as it breaks every existing TMS user with no migration path, and TOFU-only was rejected as it leaves `--no-input` CI with no way to pre-approve. Matching is **exact and case-insensitive on the parsed hostname**, ignoring scheme, port and path, so a listed `example.com` does not approve `tms.example.com` and `tms.example.com` does not approve `evil-tms.example.com`; there are no wildcards, and entries carrying a scheme, port, path or `*` are **rejected at `deepl config set`** rather than stored as approval that could never match. And **loopback is not exempt**, unlike in `buildUrl`'s HTTPS check: a co-tenant process listening on `127.0.0.1` is as much an exfiltration sink as a remote host, which is exactly the shape the reproduction used. Independently and unconditionally, both commands now **print the resolved destination origin** on success in text and JSON output (`Pushed 3 translations to TMS at https://tms.example.com`; `"server": "https://tms.example.com"`), so a redirected destination is visible in logs even when the host was already approved — the origin only, never a repo-controlled path or query, and terminal-sanitized.
 
 - **sync**: **an i18n key named `__proto__` is now recorded in the lockfile instead of vanishing from it, so it is no longer re-translated and re-billed on every run, forever.** Every write into the lockfile's entry maps was a plain assignment — `fileEntryMap[diff.key] = {...}` in `sync-process-bucket.ts` and `sync-tms.ts`, `lockFile.entries[filePath][key] = entry` in `sync-lock.ts` — and for that one key name the assignment reaches the prototype setter rather than creating a property. With `locales/en.json` holding `{greeting, __proto__, normal}`, `deepl sync` reported `3/3 keys` and wrote all three translations into `de.json`, but the lockfile came back with two entries and `"total_keys": 2`; each subsequent run diffed the missing key as new, sent it to the API, and was billed for it again, with no run ever converging. The hazard was already documented one file over — `sync-lock.ts` carries a null-prototype comment about exactly this — but only the **serialization** side had been fixed, and by the time serialization runs the key is already gone. The same shape applied to a **source path** named `__proto__`, which fell out of `lockFile.entries` wholesale, taking every key in that file with it. Fixed with three shared accessors in `sync-lock.ts` (`setOwnMember` / `getOwnMember` / `ensureFileEntries`) applied at all fourteen access sites across six files, following the `setOwn` pattern `formats/json.ts` already uses for this hazard on the translation side. The read side needed the same treatment and for a **different** reason the finding did not cover: plain indexing hands back inherited `Object.prototype` members, so keys named `constructor`, `toString`, `valueOf` or `hasOwnProperty` read as an existing lock entry that is missing every field it should have — `computeDiff` classified all four as **stale** rather than new on a first sync (`newKeys: 0, staleKeys: 4` where both should have been 4/0), and one code path would have dereferenced `.translations` on `Object` itself had a hash ever matched. Two sites beyond the fourteen the finding listed also needed it, in `sync-status.ts` and `sync-locale-translator.ts`. Verified end to end against a recording stub: the key is translated once, the lockfile round-trips all three entries with `total_keys: 3`, `de.json` holds the translated value as an own property, and a second sync sends **no** request and reports 3 current keys.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 7cf8d84d..ea044849 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -155,6 +155,8 @@ Each bucket maps a format name to a set of file patterns. The format name must b
 | `target_path_pattern` | `string` | No | Template for target file paths. Use `{locale}` for the target locale and `{basename}` for the source filename. Required for formats where the source locale is not in the source file path (e.g., Android XML, XLIFF). |
 | `key_style` | `string` | No | Key format: `nested` (dot-separated keys become nested objects) or `flat` (keys preserved as-is). |
 
+**Target path bounds.** A `target_path_pattern` may not contain `..` and may not resolve into `.git/` or `.github/`. It also may not begin with `-`, and neither may the target path it renders to: a rendered path is handed to `git` as a single argument, where a leading dash is parsed as an option rather than a filename. A dash anywhere else is fine, so the canonical Android `res/values-{locale}/strings.xml` is unaffected. A dash-leading pattern fails at config load with `ConfigError` (exit 7); a dash-leading rendered path — which `{basename}` and the default locale-substitution path can both produce from a source file whose own name begins with `-` — fails with `ValidationError` (exit 6), naming the path.
+
 **Glob pattern bounds.** Every glob string in the config — `include`, `exclude`, top-level `ignore`, and `context.scan_paths` — must expand to at most 1000 paths through its brace groups and be at most 4096 characters long. Both bounds are fixed and cannot be raised in the config: brace expansion is a product, so `{a,b}` repeated 20 times is only 107 characters but expands to over a million paths and exhausts the heap before any file is read. A pattern past either bound fails at config load with `ConfigError` (exit 7), naming the field. Realistic patterns are far below the cap — `{en,de,fr}/**/*.{json,yaml,yml}` expands to 9.
 
 #### `translation`
diff --git a/src/sync/sync-config.ts b/src/sync/sync-config.ts
index b250e050..c8279429 100644
--- a/src/sync/sync-config.ts
+++ b/src/sync/sync-config.ts
@@ -432,6 +432,17 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
           `Remove ".." from buckets.${safeName}.target_path_pattern in .deepl-sync.yaml.`
         );
       }
+      // A rendered target path is passed as a single argv entry to git, so a
+      // leading dash on its first segment is an option, not a path. Checked
+      // here against the literal pattern and again in resolveTargetPath
+      // against the rendered result, which {basename} and the default
+      // locale-substitution branch can also make dash-leading.
+      if (b['target_path_pattern'].startsWith('-')) {
+        throw new ConfigError(
+          `Sync config bucket "${safeName}" target_path_pattern must not begin with "-"`,
+          `Remove the leading "-" from buckets.${safeName}.target_path_pattern in .deepl-sync.yaml.`
+        );
+      }
       const forbidden = b['target_path_pattern']
         .split(/[/\\]/)
         .find((seg) => FORBIDDEN_TARGET_SEGMENTS.has(seg.toLowerCase()));
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index df57d071..c5614821 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -50,9 +50,11 @@ export function resolveTargetPath(
   targetPathPattern?: string
 ): string {
   if (targetPathPattern) {
-    return targetPathPattern
-      .replace(/\{locale\}/g, targetLocale)
-      .replace(/\{basename\}/g, path.basename(sourcePath));
+    return assertNotDashLeading(
+      targetPathPattern
+        .replace(/\{locale\}/g, targetLocale)
+        .replace(/\{basename\}/g, path.basename(sourcePath))
+    );
   }
 
   const escaped = sourceLocale.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -66,7 +68,7 @@ export function resolveTargetPath(
       new RegExp(`${escaped}(\\.[^./]+)$`),
       (_match: string, p1: string) => targetLocale + p1
     );
-    if (result2 !== sourcePath) return result2;
+    if (result2 !== sourcePath) return assertNotDashLeading(result2);
   }
 
   if (result === sourcePath) {
@@ -76,7 +78,29 @@ export function resolveTargetPath(
     );
   }
 
-  return result;
+  return assertNotDashLeading(result);
+}
+
+/**
+ * Reject a repo-relative target path whose first segment begins with `-`.
+ *
+ * Such a path is a single argv entry by the time it reaches `git add` or
+ * `git commit`, where a leading dash is parsed as an option rather than a
+ * pathspec. Only the first segment matters: a dash further along the path is
+ * never option-like, and `res/values-de/strings.xml` is the canonical Android
+ * target. The three sources of a dash-leading first segment are a literal
+ * `target_path_pattern` (also rejected at config load), a `{basename}` taken
+ * from a dash-leading source filename, and the default locale-substitution
+ * branch running over a dash-leading source directory.
+ */
+function assertNotDashLeading(targetPath: string): string {
+  if (targetPath.startsWith('-')) {
+    throw new ValidationError(
+      `Refusing to use target path "${sanitizeForTerminal(targetPath)}": its first path segment begins with "-", which command-line tools parse as an option.`,
+      'Rename the source file or adjust target_path_pattern so the target path does not begin with "-".'
+    );
+  }
+  return targetPath;
 }
 
 /**
diff --git a/tests/unit/sync/sync-config.test.ts b/tests/unit/sync/sync-config.test.ts
index 462acc78..1aa8762a 100644
--- a/tests/unit/sync/sync-config.test.ts
+++ b/tests/unit/sync/sync-config.test.ts
@@ -779,6 +779,38 @@ describe('sync-config', () => {
       ).toThrow('target_path_pattern must not contain ".."');
     });
 
+    it('should throw when target_path_pattern starts with "-"', () => {
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: {
+            json: {
+              include: ['a.json'],
+              target_path_pattern: '--pathspec-from-file={locale}',
+            },
+          },
+        })
+      ).toThrow('target_path_pattern must not begin with "-"');
+    });
+
+    it('should accept a dash inside a target_path_pattern segment', () => {
+      expect(() =>
+        validateSyncConfig({
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: {
+            xml: {
+              include: ['res/values/strings.xml'],
+              target_path_pattern: 'res/values-{locale}/strings.xml',
+            },
+          },
+        })
+      ).not.toThrow();
+    });
+
     describe('translation_memory_threshold validation', () => {
       const baseConfig = {
         version: 1,
diff --git a/tests/unit/sync/sync-utils.test.ts b/tests/unit/sync/sync-utils.test.ts
index 11a01a69..de004f41 100644
--- a/tests/unit/sync/sync-utils.test.ts
+++ b/tests/unit/sync/sync-utils.test.ts
@@ -142,6 +142,61 @@ describe('resolveTargetPath() with targetPathPattern', () => {
   });
 });
 
+describe('resolveTargetPath() dash-leading rendered paths', () => {
+  it('should reject a rendered path whose first segment comes from a dash-leading {basename}', () => {
+    expect(() =>
+      resolveTargetPath(
+        '--pathspec-from-file=x.json',
+        'en',
+        'de',
+        '{basename}.{locale}.json'
+      )
+    ).toThrow(ValidationError);
+  });
+
+  it('should reject a rendered path whose first segment comes from a dash-leading source directory', () => {
+    expect(() => resolveTargetPath('-o/en.json', 'en', 'de')).toThrow(
+      ValidationError
+    );
+  });
+
+  it('should reject a literal dash-leading pattern reaching resolveTargetPath', () => {
+    expect(() =>
+      resolveTargetPath(
+        'locales/en.json',
+        'en',
+        'de',
+        '--pathspec-from-file={locale}'
+      )
+    ).toThrow(ValidationError);
+  });
+
+  it('should allow a dash inside a rendered segment', () => {
+    expect(resolveTargetPath('locales/en.json', 'en', 'zh-Hans')).toBe(
+      'locales/zh-Hans.json'
+    );
+    expect(
+      resolveTargetPath(
+        'res/values/strings.xml',
+        'en',
+        'de',
+        'res/values-{locale}/strings.xml'
+      )
+    ).toBe('res/values-de/strings.xml');
+  });
+
+  it('should allow a dash-leading segment that is not the first', () => {
+    expect(
+      resolveTargetPath(
+        'src/f.txt',
+        'en',
+        'de',
+        'locales/-legacy/{locale}.json'
+      )
+    ).toBe('locales/-legacy/de.json');
+  });
+});
+
 describe('assertPathWithinRoot()', () => {
   it('should pass for a valid path within root', () => {
     expect(() =>

From 488549305c548739e0d3eddf40fa2072fb20d7c0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 16:59:34 +0200
Subject: [PATCH 136/256] fix(cli): announce a non-standard API endpoint before
 sending the key to it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

isStandardDeepLUrl() existed solely to detect a redirected endpoint and was
consumed by no warning path. Reproduced against a loopback stub: the key
arrived as `DeepL-Auth-Key SECRET-KEY-1234` and the run printed only the
translation at exit 0, with `-v` naming method and path but never the host.
A config.json holding api.baseUrl did the same with no flag typed at all.

The resolved endpoint is now checked at both CLI client-construction points
and, when it is neither standard DeepL host, a warning names the origin and
where the redirect came from: `--api-url`, or `api.baseUrl in <config file>`
using the real resolved path. Only the origin is rendered — a redirect
controls the path and query — and it is terminal-sanitized.

Not gated behind --verbose, since a user who does not know they are
redirected has no reason to pass it. On stderr, so redirected stdout stays
pure translation output. Loopback is not exempt, matching the TMS trust gate.
Once per run rather than once per client.

The verbose request line now names the resolved origin, and ConfigService
gained configFilePath so a message about a setting can name its source file.

Refs cli-8kr2.22
---
 CHANGELOG.md                              |   2 +
 docs/API.md                               |   4 +-
 src/api/http-client.ts                    |  11 +-
 src/cli/index.ts                          |  33 +++++-
 src/storage/config.ts                     |   9 ++
 src/utils/resolve-endpoint.ts             |  44 ++++++++
 tests/e2e/cli-endpoint-notice.e2e.test.ts | 128 ++++++++++++++++++++++
 tests/unit/resolve-endpoint.test.ts       |  61 +++++++++++
 8 files changed, 289 insertions(+), 3 deletions(-)
 create mode 100644 tests/e2e/cli-endpoint-notice.e2e.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b8acfd7e..16fb2b17 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -377,6 +377,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **cli**: **pointing the CLI at a non-DeepL endpoint is now announced, so the API key no longer travels to an unexpected host in silence.** `isStandardDeepLUrl()` existed solely to detect this case and was consumed by nothing — `grep` returned the definition and one internal precedence test, no warning path. Reproduced against a loopback stub with `DEEPL_API_KEY=SECRET-KEY-1234`: **the key arrived as `authorization: DeepL-Auth-Key SECRET-KEY-1234` and the run printed only the translation, at exit 0.** Adding `-v` did not help — the verbose line was `[verbose] HTTP POST /v2/translate completed in 12ms (status 200)`, method and path only, never the host. The worst of the three cases needed no flag at all: a `config.json` holding `api.baseUrl` redirected every request with nothing on any channel to say so, and the CLI never reported which config file it had loaded either. Now the resolved endpoint is checked and, when it is neither `api.deepl.com` nor `api-free.deepl.com`, an unconditional `Logger.warn` names the **origin** the key is going to and where the redirect came from: `set by --api-url`, or `set by api.baseUrl in /path/to/config.json` — the real path, resolved from the several locations searched and any `-c` override, which is what makes a substituted config visible. Only the origin is rendered, never the path or query, because those are chosen by whatever did the redirecting and echoing them would put attacker-picked text in front of the user; it is terminal-sanitized on the way out. Four scoping decisions. The notice is **not** gated behind `--verbose`, since a user who does not already know their key is being redirected has no reason to pass it; `--quiet` still suppresses it, matching every other warning. It goes to **stderr**, so `deepl translate ... > out.txt` and `$(deepl translate ...)` keep capturing only translation output. **Loopback is not exempt**, consistent with the TMS destination-trust gate — a co-tenant process on `127.0.0.1` receives the key exactly as a remote host does, and that is the shape the reproduction used. And it fires **once per run rather than once per client**, because a single command may build several (translation, usage, glossary) from the same endpoint and the notice is about the destination, not the client. Regional endpoints such as `api-jp.deepl.com` are included: they are not one of the two hosts the key is issued for. Separately, the verbose request line now names the resolved origin (`[verbose] HTTP POST http://127.0.0.1:56295/v2/translate completed in 12ms (status 200)`), and `ConfigService` gained a `configFilePath` accessor so any message about a setting can name the file that supplied it.
+
 - **sync**: **a sync target path can no longer begin with `-`**, closing the defense-in-depth half of the `git add`/`git commit` option-injection fix. The argv side was already fixed — both call sites pass `--` before the pathspec — but `.deepl-sync.yaml` could still name a target that *looks* like an option, and validation accepted it: `target_path_pattern: --pathspec-from-file={locale}` satisfies all four existing checks (a string, contains `{locale}`, no `..`, no `.git`/`.github` segment) and `resolveTargetPath` rendered it verbatim to `--pathspec-from-file=de`. Reproduced by execution, and the finding named only one of **three** routes to a dash-leading target: the literal pattern, a `{basename}` taken from a source file the glob discovered whose own name begins with `-` (`--pathspec-from-file=x.json` + `{basename}.{locale}.json` → `--pathspec-from-file=x.json.de.json`), and the default locale-substitution branch running over a dash-leading source directory (`-o/en.json` → `-o/de.json`), which involves no pattern at all. Rejecting the pattern alone would therefore have left two thirds of the class open. Two tiers, mirroring how `FORBIDDEN_TARGET_SEGMENTS` is already enforced twice: a literal pattern beginning with `-` fails at config load with `ConfigError` (exit 7), and every path `resolveTargetPath` renders is checked again and fails with `ValidationError` (exit 6), which is the only tier the `{basename}` and locale-substitution routes pass through. **Only the first segment** is checked, because the rendered path is one argv entry and a dash later in it is never option-like — `res/values-{locale}/strings.xml`, `locales/zh-Hans.json` and `locales/-legacy/{locale}.json` all still resolve, verified alongside the three refusals.
 
 - **sync**: **a `tms.server` value in the checkout can no longer redirect the operator's environment-held `TMS_API_KEY` to a host of its choosing.** `.deepl-sync.yaml` picks the destination, `TMS_API_KEY`/`TMS_TOKEN` come from the operator's environment, and `createTmsClient` wired the two together with the only destination guard being **scheme, not identity** — `buildUrl` requires `https:` (waived for `localhost`/`127.0.0.1`) and nothing checked *who* was on the other end. Nothing secret had to be in the repo. Reproduced end to end: a hostile checkout with `tms: {enabled: true, server: http://127.0.0.1:<port>, project_id: victim-project}`, an operator with `TMS_API_KEY` exported (normal for cross-project use), `deepl sync push` → **`Pushed 1 translations to TMS`, exit 0**, while the listener captured `PUT /api/projects/victim-project/keys/greeting` with `authorization: ApiKey TMS-SECRET-CREDENTIAL-1234` and the translated string in the body. `resolveTmsCredentials` did warn — but only about credentials *inlined in the YAML*, never about the YAML choosing the *destination*, and the success line named a count and no host. Now a **hybrid allowlist plus trust-on-first-use** gates it, in `createTmsClient` so both `sync push` and `sync pull` are covered by one choke point: the hostname must appear in a new user-level `tms.allowedServers` list, or be approved once at a prompt that names the host and states that the credential and every translated string would go to it. An accepted answer is recorded in **user** config (`~/.config/deepl-cli/config.json`), never in the repository, so it survives a fresh clone and does not travel with the repo. Under `--no-input` or on a non-TTY the run **fails closed with exit 7** naming the host and the exact `deepl config set tms.allowedServers <hosts>` command, with the already-approved hosts preserved in the suggested value so following it is not destructive. Verified under a real pty: declining exits 7 with nothing sent and nothing recorded; accepting exits 0, writes `allowedServers: ['localhost']` to the isolated config dir, and a later non-TTY run proceeds without prompting. Four scoping decisions the finding did not settle. The gate keys on **credential provenance**, not merely on a repo-supplied host: a credential inlined as `tms.api_key`/`tms.token` is not gated, because it belongs to the same file that chose the destination and nothing of the operator's leaks — and provenance is computed for the credential `getAuthHeader` will *actually* attach, which prefers `api_key`, so an env-held token sitting behind a config-held key does not trigger a prompt it could never leak through. Allowlist-only was rejected as it breaks every existing TMS user with no migration path, and TOFU-only was rejected as it leaves `--no-input` CI with no way to pre-approve. Matching is **exact and case-insensitive on the parsed hostname**, ignoring scheme, port and path, so a listed `example.com` does not approve `tms.example.com` and `tms.example.com` does not approve `evil-tms.example.com`; there are no wildcards, and entries carrying a scheme, port, path or `*` are **rejected at `deepl config set`** rather than stored as approval that could never match. And **loopback is not exempt**, unlike in `buildUrl`'s HTTPS check: a co-tenant process listening on `127.0.0.1` is as much an exfiltration sink as a remote host, which is exactly the shape the reproduction used. Independently and unconditionally, both commands now **print the resolved destination origin** on success in text and JSON output (`Pushed 3 translations to TMS at https://tms.example.com`; `"server": "https://tms.example.com"`), so a redirected destination is visible in logs even when the host was already approved — the origin only, never a repo-controlled path or query, and terminal-sanitized.
diff --git a/docs/API.md b/docs/API.md
index 98953a2a..a6e3635f 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -264,9 +264,11 @@ Translate text directly, from stdin, from files, or entire directories. Supports
 
 **API Options:**
 
-- `--api-url URL` - Custom API endpoint URL (for testing or private instances)
+- `--api-url URL` - Custom API endpoint URL (for testing or private instances). Any host other than `api.deepl.com` and `api-free.deepl.com` prints a warning to **stderr** naming the origin the key is about to be sent to — see "Non-standard endpoint notice" below
 - `--show-billed-characters` - Request and display actual billed character count for cost transparency
 
+**Non-standard endpoint notice.** The API key is attached to every request, so whatever host the CLI is pointed at receives it along with the text being translated. Whenever the resolved endpoint is not one of the two standard DeepL hosts, the CLI prints an unconditional warning to stderr naming the **origin** (scheme, host, port — never a path or query, which the redirect may control) and stating where the redirect came from: `set by --api-url`, or `set by api.baseUrl in <config file>` with the actual file path, since several config locations are searched and `-c` can override them. Regional endpoints such as `api-jp.deepl.com` are included, as is loopback — a co-tenant process listening on `127.0.0.1` receives the key just as a remote host does, the same reasoning the TMS destination-trust gate applies. The notice is **not** gated behind `--verbose`, because it is the user's only signal that a substituted config file has redirected their key; it is suppressed by `--quiet` like every other warning, and it goes to stderr so `deepl translate ... > out.txt` still captures only translation output. It is printed once per run, not once per API client. Under `--verbose`, each request line also names the resolved origin (`[verbose] HTTP POST https://api.deepl.com/v2/translate completed in 12ms (status 200)`).
+
 **Batch Options (for directories):**
 
 - `--no-recursive` - Do not recurse into subdirectories (recursive is the default)
diff --git a/src/api/http-client.ts b/src/api/http-client.ts
index 2b224b91..d75db2a0 100644
--- a/src/api/http-client.ts
+++ b/src/api/http-client.ts
@@ -166,6 +166,8 @@ export class HttpClient {
   protected requestTimeout: number;
   protected totalTimeout: number;
   protected _lastTraceId?: string;
+  /** Origin of `baseURL`, so a verbose request line says where it went. */
+  private readonly baseOrigin: string;
 
   /**
    * Standard NO_PROXY matching: `*` bypasses everything, a leading dot or `*.`
@@ -262,6 +264,13 @@ export class HttpClient {
     }
 
     const baseURL = resolveClientBaseUrl(options);
+    this.baseOrigin = (() => {
+      try {
+        return new URL(baseURL).origin;
+      } catch {
+        return baseURL;
+      }
+    })();
 
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.requestTimeout = options.timeout ?? DEFAULT_TIMEOUT;
@@ -457,7 +466,7 @@ export class HttpClient {
         });
         const requestElapsed = Date.now() - requestStart;
         Logger.verbose(
-          `[verbose] HTTP ${method} ${path} completed in ${requestElapsed}ms (status ${response.status})`
+          `[verbose] HTTP ${method} ${this.baseOrigin}${path} completed in ${requestElapsed}ms (status ${response.status})`
         );
 
         const responseTraceId = response.headers?.['x-trace-id'] as
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 7485e397..9974fd47 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -43,7 +43,11 @@ import { registerInit } from './commands/register-init.js';
 import { registerDetect } from './commands/register-detect.js';
 import { registerDescribe } from './commands/register-describe.js';
 import { validateApiUrl } from '../utils/validate-url.js';
-import { resolveEndpoint } from '../utils/resolve-endpoint.js';
+import {
+  resolveEndpoint,
+  nonStandardEndpointWarning,
+  type EndpointSource,
+} from '../utils/resolve-endpoint.js';
 import { installSignalExit } from '../utils/signal-exit.js';
 import { assertSupportedNodeVersion } from './node-version-check.js';
 
@@ -105,6 +109,31 @@ function parseIntOption(raw: string, flag: string, min: number): number {
   return value;
 }
 
+// Origins already announced this process. A run may build several API clients
+// (translation, usage, glossary) from the same endpoint, and the notice is about
+// the destination, not the client, so it is worth saying exactly once.
+const announcedEndpoints = new Set<string>();
+
+/**
+ * Announce a redirected endpoint before the API key is sent to it.
+ *
+ * Deliberately not gated behind --verbose: the user has no other way to learn
+ * where their key is going, and a `baseUrl` in a substituted config file is
+ * invisible otherwise. Logger.warn still respects --quiet.
+ */
+function announceEndpoint(baseUrl: string, override?: string): void {
+  const source: EndpointSource =
+    override !== undefined && override === baseUrl
+      ? { kind: 'flag' }
+      : { kind: 'config', path: configService.configFilePath };
+  const message = nonStandardEndpointWarning(baseUrl, source);
+  if (!message) return;
+  const key = `${source.kind}:${baseUrl}`;
+  if (announcedEndpoints.has(key)) return;
+  announcedEndpoints.add(key);
+  Logger.warn(message);
+}
+
 /**
  * Create DeepL client with API key from config or env
  */
@@ -134,6 +163,7 @@ async function createDeepLClient(
   if (baseUrl) {
     const { validateApiUrl } = await import('../utils/validate-url.js');
     validateApiUrl(baseUrl);
+    announceEndpoint(baseUrl, overrideBaseUrl);
   }
 
   const { DeepLClient: Client } = await import('../api/deepl-client.js');
@@ -268,6 +298,7 @@ function getApiKeyAndOptions(): {
   const baseUrl = resolveEndpoint({ apiKey: key, configBaseUrl, usePro });
   if (baseUrl) {
     validateApiUrl(baseUrl);
+    announceEndpoint(baseUrl);
   }
 
   return { apiKey: key, options: { baseUrl, ...httpOptions } };
diff --git a/src/storage/config.ts b/src/storage/config.ts
index ed6b2e26..86c0d995 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -131,6 +131,15 @@ export class ConfigService {
     this.config = this.load();
   }
 
+  /**
+   * The file this instance reads and writes. Exposed so a message about a
+   * setting can name the file that supplied it — several paths are searched and
+   * a `-c` override is possible, so the user cannot otherwise tell which won.
+   */
+  get configFilePath(): string {
+    return this.configPath;
+  }
+
   /**
    * Get the entire configuration
    * Returns a readonly reference to prevent accidental mutations
diff --git a/src/utils/resolve-endpoint.ts b/src/utils/resolve-endpoint.ts
index 8fd79566..fa0a47f9 100644
--- a/src/utils/resolve-endpoint.ts
+++ b/src/utils/resolve-endpoint.ts
@@ -1,4 +1,5 @@
 import { FREE_API_URL, PRO_API_URL } from '../api/endpoints.js';
+import { sanitizeForTerminal } from './control-chars.js';
 
 export interface ResolveEndpointOptions {
   apiKey: string;
@@ -27,6 +28,49 @@ export function isStandardDeepLUrl(url?: string): boolean {
   }
 }
 
+/** Where a non-standard base URL came from, so the notice can say so. */
+export type EndpointSource =
+  { kind: 'flag' } | { kind: 'config'; path: string };
+
+/**
+ * The notice to show before sending the API key to something other than the two
+ * standard DeepL hosts, or undefined when the endpoint is standard.
+ *
+ * Only the ORIGIN is rendered: a base URL may carry a path or query chosen by
+ * whatever redirected the request, and echoing those would put attacker-picked
+ * text in front of the user. The origin is also what identifies the recipient of
+ * the key, which is the whole point of the notice.
+ *
+ * Loopback is not exempt, matching the TMS destination-trust gate: a co-tenant
+ * process listening on 127.0.0.1 receives the key just as a remote host does.
+ */
+export function nonStandardEndpointWarning(
+  baseUrl: string,
+  source: EndpointSource
+): string | undefined {
+  if (isStandardDeepLUrl(baseUrl)) return undefined;
+
+  let origin: string;
+  try {
+    origin = new URL(baseUrl).origin;
+  } catch {
+    // validateApiUrl rejects an unparseable URL before this runs, so this is a
+    // fallback rather than a path the CLI reaches.
+    origin = baseUrl;
+  }
+
+  const attribution =
+    source.kind === 'flag'
+      ? 'set by --api-url'
+      : `set by api.baseUrl in ${sanitizeForTerminal(source.path)}`;
+
+  return (
+    `Warning: sending your DeepL API key to ${sanitizeForTerminal(origin)}, ` +
+    `which is not a DeepL API endpoint (${attribution}). ` +
+    `That host receives the key and every text you translate.`
+  );
+}
+
 /**
  * Resolves the effective API base URL.
  *
diff --git a/tests/e2e/cli-endpoint-notice.e2e.test.ts b/tests/e2e/cli-endpoint-notice.e2e.test.ts
new file mode 100644
index 00000000..a29d7908
--- /dev/null
+++ b/tests/e2e/cli-endpoint-notice.e2e.test.ts
@@ -0,0 +1,128 @@
+/**
+ * E2E Tests for the non-standard-endpoint notice.
+ *
+ * The API key is attached to every request, so a redirected endpoint receives
+ * it. These tests assert the redirect is announced on stderr without --verbose,
+ * that stdout stays pure translation output, and that the notice names where the
+ * redirect came from.
+ */
+
+import { spawn, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, makeNodeRunCLI } from '../helpers';
+
+describe('CLI non-standard endpoint notice E2E', () => {
+  const testConfig = createTestConfigDir('e2e-endpoint-notice');
+  let runner: ReturnType<typeof makeNodeRunCLI>;
+  let server: ChildProcess;
+  let baseUrl: string;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const serverScript = path.join(__dirname, 'mock-deepl-server.cjs');
+      const child = spawn('node', [serverScript], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      server = child;
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = output.match(/PORT=(\d+)/);
+        if (match) resolve(parseInt(match[1]!, 10));
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  beforeAll(async () => {
+    runner = makeNodeRunCLI(testConfig.path, { apiKey: 'test-api-key' });
+    const port = await startMockServer();
+    baseUrl = `http://127.0.0.1:${port}`;
+  });
+
+  afterAll(() => {
+    server.kill();
+    testConfig.cleanup();
+  });
+
+  const configFile = () => path.join(testConfig.path, 'config.json');
+
+  afterEach(() => {
+    if (fs.existsSync(configFile())) fs.unlinkSync(configFile());
+  });
+
+  it('announces an --api-url redirect on stderr without --verbose', () => {
+    const output = runner.runCLIAll(
+      `translate "Hello" --to es --api-url ${baseUrl}`,
+      { noColor: true }
+    );
+
+    expect(output).toContain(baseUrl);
+    expect(output).toMatch(/API key/i);
+    expect(output).toContain('--api-url');
+    expect(output).toContain('Hola');
+  });
+
+  it('keeps the notice off stdout so redirected output stays pure data', () => {
+    const stdoutOnly = runner.runCLI(
+      `translate "Hello" --to es --api-url ${baseUrl}`,
+      { noColor: true }
+    );
+
+    expect(stdoutOnly).toContain('Hola');
+    expect(stdoutOnly).not.toContain(baseUrl);
+    expect(stdoutOnly).not.toMatch(/Warning/i);
+  });
+
+  it('announces a config-file redirect and names the config file', () => {
+    fs.writeFileSync(
+      configFile(),
+      JSON.stringify({ api: { baseUrl } }, null, 2)
+    );
+
+    const output = runner.runCLIAll('translate "Hello" --to es', {
+      noColor: true,
+    });
+
+    expect(output).toContain(baseUrl);
+    expect(output).toContain('api.baseUrl');
+    expect(output).toContain(configFile());
+    expect(output).toContain('Hola');
+  });
+
+  it('announces the redirect once, not once per API client', () => {
+    const output = runner.runCLIAll(
+      `translate "Hello world" --to es --api-url ${baseUrl}`,
+      { noColor: true }
+    );
+
+    const occurrences = output.split(baseUrl).length - 1;
+    expect(occurrences).toBe(1);
+  });
+
+  it('names the resolved origin on the verbose HTTP line', () => {
+    const output = runner.runCLIAll(
+      `-v translate "Good morning" --to es --api-url ${baseUrl}`,
+      { noColor: true }
+    );
+
+    expect(output).toMatch(
+      new RegExp(`\\[verbose\\] HTTP POST ${baseUrl}/v2/translate`)
+    );
+  });
+
+  it('suppresses the notice under --quiet, like every other warning', () => {
+    const output = runner.runCLIAll(
+      `--quiet translate "Translate me" --to es --api-url ${baseUrl}`,
+      { noColor: true }
+    );
+
+    expect(output).not.toMatch(/API key/i);
+    expect(output).toContain('Traduceme');
+  });
+});
diff --git a/tests/unit/resolve-endpoint.test.ts b/tests/unit/resolve-endpoint.test.ts
index 6cc0abb1..16702240 100644
--- a/tests/unit/resolve-endpoint.test.ts
+++ b/tests/unit/resolve-endpoint.test.ts
@@ -2,6 +2,7 @@ import {
   resolveEndpoint,
   isStandardDeepLUrl,
   isFreeKey,
+  nonStandardEndpointWarning,
 } from '../../src/utils/resolve-endpoint';
 
 const FREE = 'https://api-free.deepl.com';
@@ -46,6 +47,66 @@ describe('isStandardDeepLUrl', () => {
   });
 });
 
+describe('nonStandardEndpointWarning', () => {
+  it.each([
+    ['pro', PRO],
+    ['free', FREE],
+    ['pro with path', 'https://api.deepl.com/v2/translate'],
+  ])('returns undefined for a standard endpoint: %s', (_label, url) => {
+    expect(nonStandardEndpointWarning(url, { kind: 'flag' })).toBeUndefined();
+  });
+
+  it('names the origin and the --api-url flag', () => {
+    const msg = nonStandardEndpointWarning('http://127.0.0.1:8732/v2', {
+      kind: 'flag',
+    });
+    expect(msg).toContain('http://127.0.0.1:8732');
+    expect(msg).toContain('--api-url');
+    expect(msg).toMatch(/API key/i);
+  });
+
+  it('names the origin and the config file that redirected it', () => {
+    const msg = nonStandardEndpointWarning('https://evil.example.com', {
+      kind: 'config',
+      path: '/home/u/.config/deepl-cli/config.json',
+    });
+    expect(msg).toContain('https://evil.example.com');
+    expect(msg).toContain('api.baseUrl');
+    expect(msg).toContain('/home/u/.config/deepl-cli/config.json');
+  });
+
+  it('reports the origin only, never a path or query from the URL', () => {
+    const msg = nonStandardEndpointWarning(
+      'https://evil.example.com/leak?key=SECRET#frag',
+      { kind: 'flag' }
+    );
+    expect(msg).toContain('https://evil.example.com');
+    expect(msg).not.toContain('/leak');
+    expect(msg).not.toContain('SECRET');
+    expect(msg).not.toContain('frag');
+  });
+
+  it('warns for a regional DeepL endpoint, which is not one of the two standard hosts', () => {
+    expect(
+      nonStandardEndpointWarning('https://api-jp.deepl.com', { kind: 'flag' })
+    ).toContain('https://api-jp.deepl.com');
+  });
+
+  it('warns for loopback, which is as much an exfiltration sink as a remote host', () => {
+    expect(
+      nonStandardEndpointWarning('http://localhost:9999', { kind: 'flag' })
+    ).toContain('http://localhost:9999');
+  });
+
+  it('still warns, and neutralizes control sequences, when the URL does not parse', () => {
+    const msg = nonStandardEndpointWarning('://not-a-url\u001b[2K', {
+      kind: 'flag',
+    });
+    expect(msg).toBeDefined();
+    expect(msg).not.toContain('\u001b');
+  });
+});
+
 describe('resolveEndpoint', () => {
   it.each<[string, Parameters<typeof resolveEndpoint>[0], string]>([
     [

From 0e1a633a87f2dce27aa0461ae22bf96fe4a59f4c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 17:09:31 +0200
Subject: [PATCH 137/256] fix(api): validate the shape of translate and write
 response bodies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A response body is untrusted input — the endpoint can be redirected by
--api-url, api.baseUrl or a proxy — and a declared TypeScript interface
asserts nothing at runtime. Reproduced at exit 0: {"translations":"notarray"}
printed the literal text "undefined", because a string has a truthy .length
so both the truthiness guard and the length comparison passed; a numeric or
object text printed 12345 and { a: 1, b: [ 2, 3 ] }; a null body crashed on a
raw TypeError. All six cases now exit 5 naming the field and the type.

The finding scoped this to the translation client, but write/correct had the
identical hole in mapImprovements, so both are fixed as one defect class.
Both bodies are now requested as `unknown`.

An absent or null translations/improvements field is treated as empty rather
than as a type error: the callers already describe that case better, which is
why the pre-existing "No translation returned" assertions still hold. In a
batch every element is validated before any is used. Wrong-typed optional
metadata (billed_characters, detected_source_language, model_type_used) is
dropped rather than failing a translation that is already billed.

Refs cli-8kr2.28
---
 CHANGELOG.md                          |   2 +
 src/api/response-shape.ts             | 110 +++++++++++++
 src/api/translation-client.ts         |  97 +++++------
 src/api/write-client.ts               |  18 ++-
 tests/unit/api-response-shape.test.ts | 222 ++++++++++++++++++++++++++
 5 files changed, 398 insertions(+), 51 deletions(-)
 create mode 100644 src/api/response-shape.ts
 create mode 100644 tests/unit/api-response-shape.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16fb2b17..0d4be62a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -377,6 +377,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **api**: **a `/v2/translate` or `/v2/write` response body of the wrong shape is now refused instead of being carried into output.** The bodies were typed by a TypeScript interface, which asserts nothing at runtime, and checked only for truthiness and a length match. Reproduced by execution, one stub body per case, all at **exit 0** before this change: `{"translations":"notarray"}` printed the literal text **`undefined`** — a string has a truthy `.length`, so the guard and the length comparison both passed and `[0]` yielded nothing, meaning `deepl translate ... > out.txt` wrote the word "undefined" while reporting success; `{"translations":[{"text":12345}]}` printed `12345`; `{"translations":[{"text":{"a":1,"b":[2,3]}}]}` printed `{ a: 1, b: [ 2, 3 ] }`; `{"translations":{"0":{"text":"x"}}}` printed `x`. A body of `null` crashed on a raw `Cannot read properties of null` at exit 1. All six now exit 5 naming the field and the offending type — `Unexpected API response: "translations[0].text" must be a string, got number.` — and the `--output` path can no longer reach `fs.writeFile` with a non-string and die on `ERR_INVALID_ARG_TYPE`. The checks live in a new `src/api/response-shape.ts` following the contract `sanitizePullKeysResponse` already sets for the TMS: reject rather than coerce, and name the type so the endpoint is diagnosable. **The finding scoped this to the translation client; `write`/`correct` had the identical hole** — `mapImprovements` did the same truthiness-and-length check and passed `improvement.text` through unvalidated — so both are fixed together as one defect class, and the response bodies are now requested as `unknown` rather than as an interface that was never enforced. Three deliberate distinctions. **An absent or null `translations`/`improvements` field is not a type error**: it means nothing came back, which the callers' own messages already describe better ("No translation returned from DeepL API"), so it becomes an empty array and falls through to their existing length check — this is why three pre-existing tests that assert those messages still pass unchanged. **In a batch, every element is validated before any is used**, so a bad element late in the array cannot leave earlier translations already written. And the optional metadata fields — `billed_characters`, `detected_source_language`, `model_type_used` — are **dropped when wrong-typed rather than rejecting the response**, because they are not the translation: a bogus `billed_characters` must not be summed into a cost report or written to a lockfile, but it is no reason to discard a translation that has already been billed.
+
 - **cli**: **pointing the CLI at a non-DeepL endpoint is now announced, so the API key no longer travels to an unexpected host in silence.** `isStandardDeepLUrl()` existed solely to detect this case and was consumed by nothing — `grep` returned the definition and one internal precedence test, no warning path. Reproduced against a loopback stub with `DEEPL_API_KEY=SECRET-KEY-1234`: **the key arrived as `authorization: DeepL-Auth-Key SECRET-KEY-1234` and the run printed only the translation, at exit 0.** Adding `-v` did not help — the verbose line was `[verbose] HTTP POST /v2/translate completed in 12ms (status 200)`, method and path only, never the host. The worst of the three cases needed no flag at all: a `config.json` holding `api.baseUrl` redirected every request with nothing on any channel to say so, and the CLI never reported which config file it had loaded either. Now the resolved endpoint is checked and, when it is neither `api.deepl.com` nor `api-free.deepl.com`, an unconditional `Logger.warn` names the **origin** the key is going to and where the redirect came from: `set by --api-url`, or `set by api.baseUrl in /path/to/config.json` — the real path, resolved from the several locations searched and any `-c` override, which is what makes a substituted config visible. Only the origin is rendered, never the path or query, because those are chosen by whatever did the redirecting and echoing them would put attacker-picked text in front of the user; it is terminal-sanitized on the way out. Four scoping decisions. The notice is **not** gated behind `--verbose`, since a user who does not already know their key is being redirected has no reason to pass it; `--quiet` still suppresses it, matching every other warning. It goes to **stderr**, so `deepl translate ... > out.txt` and `$(deepl translate ...)` keep capturing only translation output. **Loopback is not exempt**, consistent with the TMS destination-trust gate — a co-tenant process on `127.0.0.1` receives the key exactly as a remote host does, and that is the shape the reproduction used. And it fires **once per run rather than once per client**, because a single command may build several (translation, usage, glossary) from the same endpoint and the notice is about the destination, not the client. Regional endpoints such as `api-jp.deepl.com` are included: they are not one of the two hosts the key is issued for. Separately, the verbose request line now names the resolved origin (`[verbose] HTTP POST http://127.0.0.1:56295/v2/translate completed in 12ms (status 200)`), and `ConfigService` gained a `configFilePath` accessor so any message about a setting can name the file that supplied it.
 
 - **sync**: **a sync target path can no longer begin with `-`**, closing the defense-in-depth half of the `git add`/`git commit` option-injection fix. The argv side was already fixed — both call sites pass `--` before the pathspec — but `.deepl-sync.yaml` could still name a target that *looks* like an option, and validation accepted it: `target_path_pattern: --pathspec-from-file={locale}` satisfies all four existing checks (a string, contains `{locale}`, no `..`, no `.git`/`.github` segment) and `resolveTargetPath` rendered it verbatim to `--pathspec-from-file=de`. Reproduced by execution, and the finding named only one of **three** routes to a dash-leading target: the literal pattern, a `{basename}` taken from a source file the glob discovered whose own name begins with `-` (`--pathspec-from-file=x.json` + `{basename}.{locale}.json` → `--pathspec-from-file=x.json.de.json`), and the default locale-substitution branch running over a dash-leading source directory (`-o/en.json` → `-o/de.json`), which involves no pattern at all. Rejecting the pattern alone would therefore have left two thirds of the class open. Two tiers, mirroring how `FORBIDDEN_TARGET_SEGMENTS` is already enforced twice: a literal pattern beginning with `-` fails at config load with `ConfigError` (exit 7), and every path `resolveTargetPath` renders is checked again and fails with `ValidationError` (exit 6), which is the only tier the `{basename}` and locale-substitution routes pass through. **Only the first segment** is checked, because the rendered path is one argv entry and a dash later in it is never option-like — `res/values-{locale}/strings.xml`, `locales/zh-Hans.json` and `locales/-legacy/{locale}.json` all still resolve, verified alongside the three refusals.
diff --git a/src/api/response-shape.ts b/src/api/response-shape.ts
new file mode 100644
index 00000000..243f6200
--- /dev/null
+++ b/src/api/response-shape.ts
@@ -0,0 +1,110 @@
+import { NetworkError } from '../utils/errors.js';
+
+/**
+ * Shape checks for DeepL response bodies.
+ *
+ * A response body is untrusted input: the endpoint can be redirected by
+ * `--api-url`, an `api.baseUrl` in the config, or a proxy, and a redirected host
+ * can return well-formed JSON of any shape. Declaring a TypeScript interface for
+ * the body asserts nothing at runtime, so without these checks a wrong-shaped
+ * value is carried all the way into terminal output, a written file, or an i18n
+ * bucket.
+ *
+ * Follows the contract `sanitizePullKeysResponse` sets for the TMS: reject
+ * rather than coerce, and name the offending type so the endpoint is
+ * diagnosable.
+ */
+
+function describe(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+/**
+ * Require `body` to be `{ [field]: Array<object> }` and return that array.
+ *
+ * The string case is the one that mattered most in practice: a string has a
+ * truthy `.length`, so a `!body[field]` guard followed by a length comparison
+ * passed, `[0]` yielded `undefined`, and `undefined` was printed as the
+ * translation at exit 0.
+ */
+export function requireItemArray(
+  body: unknown,
+  field: string,
+  context: string
+): Record<string, unknown>[] {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    throw new NetworkError(
+      `Unexpected API response: expected a JSON object with "${field}", got ${describe(body)}. ${context}`
+    );
+  }
+
+  const items = (body as Record<string, unknown>)[field];
+
+  // A missing or null field means nothing was returned, which is not a type
+  // error: callers already describe that case better than a shape message can
+  // ("No translation returned from DeepL API"), so it becomes an empty array and
+  // falls through to their own length check.
+  if (items === undefined || items === null) return [];
+
+  if (!Array.isArray(items)) {
+    throw new NetworkError(
+      `Unexpected API response: "${field}" must be an array, got ${describe(items)}. ${context}`
+    );
+  }
+
+  return items as Record<string, unknown>[];
+}
+
+/**
+ * Require `items[index]` to be an object whose `text` is a string, and return
+ * that string.
+ */
+export function requireItemText(
+  items: Record<string, unknown>[],
+  index: number,
+  field: string,
+  context: string
+): string {
+  const item = items[index];
+  if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+    throw new NetworkError(
+      `Unexpected API response: "${field}[${index}]" must be an object, got ${describe(item)}. ${context}`
+    );
+  }
+  const text = item['text'];
+  if (typeof text !== 'string') {
+    throw new NetworkError(
+      `Unexpected API response: "${field}[${index}].text" must be a string, got ${describe(text)}. ${context}`
+    );
+  }
+  return text;
+}
+
+/**
+ * An optional response field, kept only when it is actually the expected type.
+ *
+ * Dropping a wrong-typed value rather than rejecting the whole response is
+ * deliberate: these are metadata, not the translation. A bogus
+ * `billed_characters` must not be summed into a cost report or land in a
+ * lockfile, but it is no reason to discard a translation that is already billed.
+ */
+export function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function optionalNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+/** `optionalNumber` for a field of a body whose shape is not yet narrowed. */
+export function optionalNumberField(
+  body: unknown,
+  name: string
+): number | undefined {
+  if (body === null || typeof body !== 'object') return undefined;
+  return optionalNumber((body as Record<string, unknown>)[name]);
+}
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index 44828527..cf73b833 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -1,4 +1,11 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
+import {
+  requireItemArray,
+  requireItemText,
+  optionalString,
+  optionalNumber,
+  optionalNumberField,
+} from './response-shape.js';
 import {
   TranslationOptions,
   Language,
@@ -16,16 +23,6 @@ import { Logger } from '../utils/logger.js';
 export const TRANSLATION_MEMORY_LIST_PAGE_SIZE = 25;
 export const MAX_TRANSLATION_MEMORY_LIST_PAGES = 20;
 
-interface DeepLTranslateResponse {
-  translations: Array<{
-    detected_source_language?: string;
-    text: string;
-    billed_characters?: number;
-    model_type_used?: string;
-  }>;
-  billed_characters?: number;
-}
-
 interface DeepLUsageResponse {
   character_count: number;
   character_limit: number;
@@ -175,33 +172,36 @@ export class TranslationClient extends HttpClient {
     const params = this.buildTranslationParams([text], options);
 
     try {
-      const response = await this.makeRequest<DeepLTranslateResponse>(
+      // Deliberately `unknown`: a declared interface asserts nothing at
+      // runtime, and a redirected endpoint can return any shape.
+      const response = await this.makeRequest<unknown>(
         'POST',
         '/v2/translate',
         params
       );
 
-      if (!response.translations || response.translations.length === 0) {
-        throw new NetworkError(
-          `No translation returned from DeepL API. Request: translate text (${text.length} chars) to ${options.targetLang}`
-        );
-      }
+      const context = `Request: translate text (${text.length} chars) to ${options.targetLang}`;
+      const items = requireItemArray(response, 'translations', context);
 
-      const translation = response.translations[0];
-      if (!translation) {
+      if (items.length === 0) {
         throw new NetworkError(
-          `Empty translation in API response. Request: translate text (${text.length} chars) to ${options.targetLang}`
+          `No translation returned from DeepL API. ${context}`
         );
       }
 
+      const translated = requireItemText(items, 0, 'translations', context);
+      const item = items[0]!;
+      const detected = optionalString(item['detected_source_language']);
+
       return {
-        text: translation.text,
-        detectedSourceLang: translation.detected_source_language
-          ? this.normalizeLanguage(translation.detected_source_language)
+        text: translated,
+        detectedSourceLang: detected
+          ? this.normalizeLanguage(detected)
           : undefined,
         billedCharacters:
-          translation.billed_characters ?? response.billed_characters,
-        modelTypeUsed: translation.model_type_used,
+          optionalNumber(item['billed_characters']) ??
+          optionalNumberField(response, 'billed_characters'),
+        modelTypeUsed: optionalString(item['model_type_used']),
       };
     } catch (error) {
       throw this.handleError(error);
@@ -219,30 +219,30 @@ export class TranslationClient extends HttpClient {
     const params = this.buildTranslationParams(texts, options);
 
     try {
-      const response = await this.makeRequest<DeepLTranslateResponse>(
+      // Deliberately `unknown`: a declared interface asserts nothing at
+      // runtime, and a redirected endpoint can return any shape.
+      const response = await this.makeRequest<unknown>(
         'POST',
         '/v2/translate',
         params
       );
 
-      if (!response.translations) {
-        throw new NetworkError(
-          'Unexpected API response. Please retry your translation. If the issue persists, report it at https://github.com/DeepL/deepl-cli/issues'
-        );
-      }
+      const context = `Request: translate ${texts.length} texts to ${options.targetLang}`;
+      const items = requireItemArray(response, 'translations', context);
 
-      if (response.translations.length !== texts.length) {
+      if (items.length !== texts.length) {
         throw new NetworkError(
           'Unexpected API response. Please retry your translation. If the issue persists, report it at https://github.com/DeepL/deepl-cli/issues'
         );
       }
 
-      if (
-        isReorderedEcho(
-          texts,
-          response.translations.map((translation) => translation.text)
-        )
-      ) {
+      // Every text is validated before any is used, so a bad element late in
+      // the array cannot leave earlier ones already written.
+      const translatedTexts = items.map((_item, index) =>
+        requireItemText(items, index, 'translations', context)
+      );
+
+      if (isReorderedEcho(texts, translatedTexts)) {
         throw new NetworkError(
           'The endpoint returned the submitted texts in a different order, so each translation ' +
             'would be stored against the wrong entry. Nothing was written. Check which endpoint ' +
@@ -250,15 +250,20 @@ export class TranslationClient extends HttpClient {
         );
       }
 
-      return response.translations.map((translation) => ({
-        text: translation.text,
-        detectedSourceLang: translation.detected_source_language
-          ? this.normalizeLanguage(translation.detected_source_language)
-          : undefined,
-        billedCharacters:
-          translation.billed_characters ?? response.billed_characters,
-        modelTypeUsed: translation.model_type_used,
-      }));
+      const topBilled = optionalNumberField(response, 'billed_characters');
+
+      return items.map((item, index) => {
+        const detected = optionalString(item['detected_source_language']);
+        return {
+          text: translatedTexts[index]!,
+          detectedSourceLang: detected
+            ? this.normalizeLanguage(detected)
+            : undefined,
+          billedCharacters:
+            optionalNumber(item['billed_characters']) ?? topBilled,
+          modelTypeUsed: optionalString(item['model_type_used']),
+        };
+      });
     } catch (error) {
       throw this.handleError(error);
     }
diff --git a/src/api/write-client.ts b/src/api/write-client.ts
index 393ac511..1192bd83 100644
--- a/src/api/write-client.ts
+++ b/src/api/write-client.ts
@@ -1,4 +1,9 @@
 import { HttpClient, DeepLClientOptions } from './http-client.js';
+import {
+  requireItemArray,
+  requireItemText,
+  optionalString,
+} from './response-shape.js';
 import {
   WriteOptions,
   CorrectOptions,
@@ -87,14 +92,17 @@ export class WriteClient extends HttpClient {
   }
 
   private mapImprovements(response: DeepLWriteResponse): WriteImprovement[] {
-    if (!response.improvements || response.improvements.length === 0) {
+    const context = 'Request: rephrase or correct text';
+    const items = requireItemArray(response, 'improvements', context);
+
+    if (items.length === 0) {
       throw new NetworkError('No improvements returned');
     }
 
-    return response.improvements.map((improvement) => ({
-      text: improvement.text,
-      targetLanguage: improvement.target_language,
-      detectedSourceLanguage: improvement.detected_source_language,
+    return items.map((item, index) => ({
+      text: requireItemText(items, index, 'improvements', context),
+      targetLanguage: optionalString(item['target_language']) ?? '',
+      detectedSourceLanguage: optionalString(item['detected_source_language']),
     }));
   }
 }
diff --git a/tests/unit/api-response-shape.test.ts b/tests/unit/api-response-shape.test.ts
new file mode 100644
index 00000000..d7d2b814
--- /dev/null
+++ b/tests/unit/api-response-shape.test.ts
@@ -0,0 +1,222 @@
+/**
+ * Tests for shape validation of untrusted /v2/translate and /v2/write response
+ * bodies. A redirected or malfunctioning endpoint can return well-formed JSON of
+ * the wrong shape; these assert it is refused rather than carried into output.
+ */
+
+import { TranslationClient } from '../../src/api/translation-client.js';
+import { WriteClient } from '../../src/api/write-client.js';
+import { NetworkError } from '../../src/utils/errors.js';
+import axios from 'axios';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('untrusted response shape', () => {
+  let mockAxiosInstance: any;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockAxiosInstance = { request: jest.fn() };
+    mockedAxios.create = jest.fn().mockReturnValue(mockAxiosInstance);
+    jest.spyOn(axios, 'isAxiosError').mockReturnValue(false);
+  });
+
+  function reply(data: unknown): void {
+    mockAxiosInstance.request.mockResolvedValue({
+      data,
+      status: 200,
+      headers: {},
+    });
+  }
+
+  describe('TranslationClient.translate()', () => {
+    let client: TranslationClient;
+
+    beforeEach(() => {
+      client = new TranslationClient('test-api-key');
+    });
+    afterEach(() => client.destroy());
+
+    // The worst case: a string has a truthy .length, so [0] yielded undefined
+    // and the CLI printed the literal text "undefined" at exit 0.
+    it('rejects translations as a string rather than printing undefined', async () => {
+      reply({ translations: 'notarray' });
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('rejects translations as an object with numeric keys', async () => {
+      reply({ translations: { '0': { text: 'x' } } });
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('rejects a null response body instead of crashing on a raw TypeError', async () => {
+      reply(null);
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('rejects a numeric text', async () => {
+      reply({ translations: [{ text: 12345 }] });
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('rejects an object text', async () => {
+      reply({ translations: [{ text: { a: 1, b: [2, 3] } }] });
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('names the offending type so the endpoint is diagnosable', async () => {
+      expect.assertions(2);
+      reply({ translations: [{ text: 12345 }] });
+      try {
+        await client.translate('Hello', { targetLang: 'es' });
+      } catch (err) {
+        expect(err).toBeInstanceOf(NetworkError);
+        expect((err as Error).message).toMatch(/number/);
+      }
+    });
+
+    it('ignores a non-numeric billed_characters rather than reporting it', async () => {
+      reply({ translations: [{ text: 'Hola', billed_characters: 'lots' }] });
+      const result = await client.translate('Hello', { targetLang: 'es' });
+      expect(result.text).toBe('Hola');
+      expect(result.billedCharacters).toBeUndefined();
+    });
+
+    it('ignores a non-string detected_source_language', async () => {
+      reply({ translations: [{ text: 'Hola', detected_source_language: 7 }] });
+      const result = await client.translate('Hello', { targetLang: 'es' });
+      expect(result.text).toBe('Hola');
+      expect(result.detectedSourceLang).toBeUndefined();
+    });
+
+    it('ignores a non-string model_type_used', async () => {
+      reply({ translations: [{ text: 'Hola', model_type_used: { m: 1 } }] });
+      const result = await client.translate('Hello', { targetLang: 'es' });
+      expect(result.modelTypeUsed).toBeUndefined();
+    });
+
+    // An absent or null field means nothing came back, which the caller
+    // describes better than a shape message can. Kept distinct from a field
+    // that is present with the wrong type.
+    it('reports an absent translations field as no translation returned', async () => {
+      reply({});
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow('No translation returned from DeepL API');
+    });
+
+    it('reports a null translations field as no translation returned', async () => {
+      reply({ translations: null });
+      await expect(
+        client.translate('Hello', { targetLang: 'es' })
+      ).rejects.toThrow('No translation returned from DeepL API');
+    });
+
+    it('still accepts a well-formed response', async () => {
+      reply({
+        translations: [
+          {
+            text: 'Hola',
+            detected_source_language: 'EN',
+            billed_characters: 5,
+            model_type_used: 'quality_optimized',
+          },
+        ],
+      });
+      const result = await client.translate('Hello', { targetLang: 'es' });
+      expect(result.text).toBe('Hola');
+      expect(result.detectedSourceLang).toBe('en');
+      expect(result.billedCharacters).toBe(5);
+      expect(result.modelTypeUsed).toBe('quality_optimized');
+    });
+  });
+
+  describe('TranslationClient.translateBatch()', () => {
+    let client: TranslationClient;
+
+    beforeEach(() => {
+      client = new TranslationClient('test-api-key');
+    });
+    afterEach(() => client.destroy());
+
+    it('rejects translations as a string', async () => {
+      reply({ translations: 'ab' });
+      await expect(
+        client.translateBatch(['a', 'b'], { targetLang: 'es' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('rejects a non-string text among otherwise valid entries', async () => {
+      reply({ translations: [{ text: 'Hola' }, { text: null }] });
+      await expect(
+        client.translateBatch(['Hello', 'World'], { targetLang: 'es' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('rejects a null element', async () => {
+      reply({ translations: [{ text: 'Hola' }, null] });
+      await expect(
+        client.translateBatch(['Hello', 'World'], { targetLang: 'es' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('still accepts a well-formed batch response', async () => {
+      reply({ translations: [{ text: 'Hola' }, { text: 'Mundo' }] });
+      const results = await client.translateBatch(['Hello', 'World'], {
+        targetLang: 'es',
+      });
+      expect(results.map((r) => r.text)).toEqual(['Hola', 'Mundo']);
+    });
+  });
+
+  describe('WriteClient', () => {
+    let client: WriteClient;
+
+    beforeEach(() => {
+      client = new WriteClient('test-api-key');
+    });
+    afterEach(() => client.destroy());
+
+    it('rejects improvements as a string', async () => {
+      reply({ improvements: 'notarray' });
+      await expect(
+        client.improveText('Hello', { targetLang: 'en-us' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('rejects a null response body', async () => {
+      reply(null);
+      await expect(
+        client.improveText('Hello', { targetLang: 'en-us' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('rejects a numeric improvement text', async () => {
+      reply({ improvements: [{ text: 999 }] });
+      await expect(
+        client.improveText('Hello', { targetLang: 'en-us' })
+      ).rejects.toThrow(NetworkError);
+    });
+
+    it('still accepts a well-formed response', async () => {
+      reply({
+        improvements: [{ text: 'Hello there', target_language: 'en-US' }],
+      });
+      const results = await client.improveText('Hello', {
+        targetLang: 'en-us',
+      });
+      expect(results[0]!.text).toBe('Hello there');
+    });
+  });
+});

From af1818e4188a40f53ae202d89dbe0f01095f757c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 19:03:49 +0200
Subject: [PATCH 138/256] fix(sync): make a translation entry the unit of merge
 in the lockfile

The lockfile serialized each field of a translation on its own line, so
git's unit of merge was a FIELD rather than a translation. Two P1 data
losses followed from that one cause, both measured with real `git merge`
on real serializer output against a stashed-old-code control.

Silent case, which never reached `sync resolve` at all. Keys are sorted,
so the on-disk order is hash, review_status, status, translated_at. A
branch that changed only review_status and a branch that changed only
translated_at touch non-adjacent lines with `status` unchanged between
them, so git merged both hunks cleanly:

  ours    review_status=machine_translated  translated_at=2026-09-09
  theirs  review_status=human_reviewed      translated_at=2026-01-01
  merged  review_status=human_reviewed      translated_at=2026-09-09

That entry existed on neither branch. It marks machine output as
human-approved, and the timestamp it carries makes the staleness
invisible to any later comparison. No conflict, exit 0.

`sync resolve` case. Where git did conflict, the region was the entry's
field list, so it parsed to three scalars and isTranslationEntry was
asked about the string "machine output" rather than about an entry. The
entry-level translated_at branch was unreachable and every field took
the terminal "kept ours: scalar conflict, defaulting to ours" path,
discarding a newer human_reviewed translation for older machine output
and reporting it as resolved. Side-dependent, so it silently did the
right thing whenever the newer edit happened to be on the local branch.

Each translation is now serialized on ONE line, which makes the smallest
region git can produce a whole entry: the overlap above conflicts instead
of merging, and a conflict reaches the timestamp comparison, which picks
one whole coherent side.

Two further changes are needed for that to hold, neither of them implied
by the format change:

  - A region inside an object carries a trailing comma joining it to the
    member that follows, and JSON.parse('{' + region + '}') fails on it.
    Measured: without this, every entry but the last locale in its map
    fell straight back to the length heuristic and kept discarding the
    newer side, so the format change alone fixed nothing for the common
    case. The terminator now comes off before parsing and goes back
    after. Sides that DISAGREE on it -- one deleted what the other
    modified -- still fall to the heuristic, because no terminator is
    correct for both and guessing could emit invalid JSON.
  - Resolving rebuilds each region with its own indentation, so the
    resolved file is written back in canonical form. Otherwise
    committing a resolved lockfile leaves entries expanded across lines
    for the next merge to recombine.

sortedKeysReplacer is gone: sorting now happens in the serializer, which
enumerates with Object.entries and never assigns to a plain object, so
the prototype-named-key hazard it existed to avoid cannot arise. Its six
prototype-key-safety cases move to serializeLockFile and assert the same
guarantee end to end.

The e2e case that forced a parse error with a trailing comma had to
change fixture: that shape parses now by design. It uses delete-vs-modify
instead, which reaches the same fallback for a real reason.

Upgrading reformats every existing lockfile on the next write, producing
one large diff. It is formatting only; no entry's content changes. A
changed translation is now a one-line diff rather than three or four,
which is what the pretty-printing was for.

Refs cli-8kr2.55, cli-8kr2.56
---
 CHANGELOG.md                            |   2 +
 docs/SYNC.md                            |  16 ++
 src/sync/sync-lock.ts                   | 113 ++++++++---
 src/sync/sync-resolve.ts                |  55 +++++-
 tests/e2e/cli-sync.e2e.test.ts          |  13 +-
 tests/unit/prototype-key-safety.test.ts |  44 +++--
 tests/unit/sync/sync-lock.test.ts       | 147 ++++++++++++++
 tests/unit/sync/sync-resolve.test.ts    | 246 +++++++++++++++++++++++-
 8 files changed, 568 insertions(+), 68 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d4be62a..f87e834f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **the lockfile no longer lets `git merge` invent a translation that existed on neither branch, and `sync resolve` now actually applies its documented `translated_at` tie-break.** One root cause behind both: entries were serialized one field per line, making git's unit of merge a *field* rather than a *translation*. Measured with real `git merge` on real serializer output, against a stashed-old-code control. **The silent case, which never reached `sync resolve` at all:** a branch that changed only `review_status` and a branch that changed only `translated_at` are non-adjacent lines with `status` unchanged between them, so git merged both hunks cleanly and produced `review_status: human_reviewed` from one side carrying `translated_at` from the other — a combination on neither branch, marking machine output as human-approved with a timestamp that makes the staleness invisible to any later timestamp comparison, at exit 0 with no conflict reported. **The `sync resolve` case:** where git *did* conflict, the region was the entry's field list, so it parsed to three scalars and the resolver's entry-level branch was unreachable; every field took the terminal `kept ours: scalar conflict, defaulting to ours` path. Measured discarding a newer `human_reviewed` translation in favour of older machine output, reported as resolved at exit 0 — the exact opposite of the documented rule, and side-dependent, so it silently did the right thing whenever the newer edit happened to be on the local branch. **Each translation is now written on a single line**, which makes the smallest region git can produce a whole entry: the field-level overlap conflicts instead of merging, and the conflict reaches the timestamp comparison, which picks one whole coherent side. Two changes were needed to make that hold, neither of them obvious from the format change alone. A region inside an object carries a trailing comma joining it to the next member, and `JSON.parse('{' + region + '}')` fails on it — so *every* entry but the last locale in its map would have fallen straight back to the length heuristic and kept discarding the newer side; the terminator is now taken off before parsing and put back after. And because resolving rebuilds each region with its own indentation, the resolved file is now written back in canonical form, so committing it cannot leave entries expanded across lines for the next merge to recombine. Where the two sides *disagree* on the terminator — one deleted what the other modified — no terminator is correct for both and the region still falls to the length heuristic rather than risk invalid JSON. **Upgrading reformats every existing lockfile on the next write, producing one large diff; it is formatting only and no entry's content changes.** Keys are sorted within the line, so a changed translation is now a one-line diff rather than three or four.
+
 - **sync**: **`sync export` produces well-formed XLIFF for keys that contain control characters, and no longer changes a key on the way out.** `escapeXml` escaped `&`, `<`, `>` and `"` only, so a key holding a C0 control was written straight into the `id=` and `resname=` attributes — and C0 other than tab, newline and carriage return has no representation at all in XML 1.0, not even as a character reference, so the file was not well-formed and a translator's tool would reject it whole. Those characters are now replaced with `?`, which costs one odd character in one id rather than an unreadable handoff file. Separately, and independent of any hostile input: a tab, newline or carriage return inside a key was emitted literally, and every conforming XML parser **normalizes those to a space inside an attribute value** — so a multi-line key silently came back different from the key that was exported. They are now emitted as `&#9;`, `&#10;` and `&#13;`, which round-trip exactly. C1 (U+0080–U+009F) is deliberately left alone: those are valid XML 1.0 characters that round-trip unchanged, and an export is a data file, so it is mutated no further than validity requires.
 
 - **sync**: **two syncs no longer run concurrently in the same directory, which is the entire purpose of the process lock.** Measured with six processes racing over a planted stale pidfile, 100 rounds: **93 rounds had overlapping lock holders before this change — up to five at once — and 0 do after.** Two independent defects had to be fixed to get there. First, the stale-pidfile reclaim was a read/unlink/create sequence with no atomicity, so a process whose staleness verdict had already been overtaken deleted the *live* pidfile the winner had just written, after which both held what each believed was an exclusive lock; and the create that followed the unlink was the one call not wrapped in the EEXIST handling, so a lost race surfaced as an unhandled `Error: EEXIST: file already exists, open '.deepl-sync.lock.pidfile'` instead of the intended "another sync is running". A stale file is now removed only after taking possession of it with `rename(2)` — atomic, so exactly one of several racers can move a given entry aside — and confirming the captured inode is the one proven stale; a process that captures a different file puts it back rather than deleting someone's lock. Acquisition always goes through the same guarded create, so a lost race reports the running sync, and the retry loop is bounded (5 attempts) with its own error rather than spinning. Second, and the defect that actually accounted for the remaining overlap once the reclaim was atomic: the pidfile was created empty through an `O_EXCL` descriptor and filled afterwards, leaving a window in which a **live** lock read as malformed — and malformed counts as stale, so a concurrent sync deleted it and took over. No identity check downstream can catch that, because the file it inspected really is the file it removed. The payload is now written to a private staging path and `link(2)`ed into place, which publishes the name and the content in one step and doubles as the atomic acquisition. CI relevance: a runner retrying a timed-out job is exactly the double-start trigger.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index ea044849..eb2a3e1c 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -364,6 +364,18 @@ Each translation entry in the lockfile records:
 | `context_sent` | `true` when source code context was included in the API request |
 | `review_status` | `machine_translated` or `human_reviewed` (set by `--flag-for-review`) |
 
+**Formatting.** Containers are written one key per line, but each translation entry is written on a **single line**:
+
+```json
+"translations": {
+  "de": {"hash": "185f8db32271", "review_status": "human_reviewed", "status": "translated", "translated_at": "2026-04-20T08:12:03Z"}
+}
+```
+
+This is a merge-safety property, not a style choice. A translation is only meaningful whole — its hash, timestamp and review status all describe one act of translating. With one field per line, `git merge` treats those fields as independently mergeable units: a branch that changed only `review_status` and a branch that changed only `translated_at` merge **with no conflict at all** into an entry that existed on neither branch, labelling machine output `human_reviewed` while carrying a timestamp from the other branch. One line per entry makes the smallest region git can produce a whole entry, so such an overlap conflicts and reaches [`deepl sync resolve`](#deepl-sync-resolve) instead of being silently combined. Keys are sorted, so the diff for a changed translation is a single line.
+
+Upgrading from an earlier release reformats every existing lockfile on the next write, which produces one large diff. It is a formatting change only — no entry's content changes.
+
 ### Multiple Buckets
 
 You can define multiple buckets to handle different file formats in the same project:
@@ -702,6 +714,10 @@ WARN  locales/de/app.json:<conflict-region> — parse-error fallback used, JSON.
 Resolved 3 conflicts (1 theirs, 1 ours, 1 length-heuristic). Run "deepl sync" to fill any gaps.
 ```
 
+**Region terminators.** A conflict region that sits inside an object is a sequence of members, and unless it is the last one it ends with a comma joining it to the member that follows. The resolver takes that comma off before parsing the region and puts it back afterwards — without this, every region but the last failed to parse and fell to the length heuristic below, so the documented `translated_at` tie-break never ran. When the two sides *disagree* on whether the region ends a member list — one side deleted what the other modified — no terminator can be correct for both, so the region falls to the heuristic rather than risk emitting invalid JSON.
+
+**Canonical output.** Resolving rebuilds each merged region, so the resolved lockfile is written back in the canonical format described under [`.deepl-sync.lock`](#deepl-sync-lock) rather than with the resolver's own indentation. Committing a resolved lockfile therefore cannot leave translations expanded across lines for the next merge to recombine.
+
 **Fallback behavior.** When `JSON.parse` fails on a conflict fragment (e.g., conflict markers landed mid-entry and split the JSON), the resolver falls back to a length-heuristic: the longer side wins. This is now **loud** — it logs a `WARN` line naming the file + conflict region with the truncated parse error, and the decision is tagged `length-heuristic` in the report. Earlier releases ran this heuristic silently, making auto-resolve a data-loss risk the user could not audit without a diff against git history. Inspect any `length-heuristic` entries and consider resolving them by hand.
 
 **Dry-run.** `--dry-run` runs the full decision pipeline and prints the per-entry report without touching the lockfile. Use it to preview what `sync resolve` would do, especially when the report includes `length-heuristic` fallback warnings.
diff --git a/src/sync/sync-lock.ts b/src/sync/sync-lock.ts
index 2aac219d..a4a43e2d 100644
--- a/src/sync/sync-lock.ts
+++ b/src/sync/sync-lock.ts
@@ -104,42 +104,88 @@ export function createEmptyLockFile(sourceLocale: string): SyncLockFile {
   };
 }
 
+// Depth of `entries.<source file>.<i18n key>.translations.<locale>`, the level a
+// translation entry sits at. Matched on the path rather than on the key name so
+// an i18n key called `translations` is not mistaken for the container itself.
+const TRANSLATION_DEPTH = 5;
+
+function isTranslation(path: readonly string[]): boolean {
+  return (
+    path.length === TRANSLATION_DEPTH &&
+    path[0] === 'entries' &&
+    path[3] === 'translations'
+  );
+}
+
 /**
- * JSON.stringify replacer that emits plain objects with sorted keys, so the
- * lockfile is never materialized twice in memory: the replacer is invoked
- * lazily as stringify recurses, so only a single sorted-key shell lives at
- * each level of the tree.
- * Objects whose own-enumeration order is already sorted are returned as-is so
- * leaf shells (translations, stats) don't allocate.
+ * Own, enumerable, serializable members in key order. Enumerated as pairs rather
+ * than read back by key: an i18n key named `__proto__` is a real own property,
+ * and indexing a plain object for it would reach the prototype instead.
  */
-export function sortedKeysReplacer(_key: string, value: unknown): unknown {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    return value;
+function sortedMembers(value: object): [string, unknown][] {
+  return Object.entries(value)
+    .filter(
+      ([, member]) => member !== undefined && typeof member !== 'function'
+    )
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** One line, no indentation, keys still sorted. */
+function serializeInline(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value) ?? 'null';
   }
-  const src = value as Record<string, unknown>;
-  const keys = Object.keys(src);
-  let alreadySorted = true;
-  for (let i = 1; i < keys.length; i++) {
-    if (keys[i - 1]! > keys[i]!) {
-      alreadySorted = false;
-      break;
-    }
+  if (Array.isArray(value)) {
+    return `[${value.map(serializeInline).join(', ')}]`;
   }
-  if (alreadySorted) {
-    return value;
+  const members = sortedMembers(value).map(
+    ([key, member]) => `${JSON.stringify(key)}: ${serializeInline(member)}`
+  );
+  return members.length === 0 ? '{}' : `{${members.join(', ')}}`;
+}
+
+// `path` is mutated in place rather than copied per member: a lockfile carries
+// one node per translation per key, and a fresh array at each would allocate
+// once for every one of them.
+function serializeNode(value: unknown, indent: string, path: string[]): string {
+  if (isTranslation(path) || value === null || typeof value !== 'object') {
+    return serializeInline(value);
+  }
+  const childIndent = `${indent}  `;
+  const members: string[] = [];
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      path.push(String(index));
+      members.push(childIndent + serializeNode(item, childIndent, path));
+      path.pop();
+    });
+    return members.length === 0
+      ? '[]'
+      : `[\n${members.join(',\n')}\n${indent}]`;
   }
-  const sortedKeys = keys.slice().sort();
-  // Null-prototype: `out['__proto__'] = v` on a plain object invokes the
-  // prototype setter, so an i18n key of that name would vanish from the
-  // serialized lockfile on every write.
-  const out: Record<string, unknown> = Object.create(null) as Record<
-    string,
-    unknown
-  >;
-  for (const k of sortedKeys) {
-    out[k] = src[k];
+  for (const [key, member] of sortedMembers(value)) {
+    path.push(key);
+    members.push(
+      `${childIndent}${JSON.stringify(key)}: ${serializeNode(member, childIndent, path)}`
+    );
+    path.pop();
   }
-  return out;
+  return members.length === 0 ? '{}' : `{\n${members.join(',\n')}\n${indent}}`;
+}
+
+/**
+ * The canonical on-disk form of a lock file, including its trailing newline.
+ *
+ * Every container is expanded one key per line, but each translation is emitted
+ * on a single line. A translation is only meaningful whole — its hash, timestamp
+ * and review status all describe one act of translating — and one field per line
+ * makes those fields independently mergeable units, so `git merge` can combine
+ * one side's hash with the other's review status and produce a translation that
+ * existed on neither branch, with no conflict raised. One line per translation
+ * makes the smallest region git can produce a whole entry.
+ */
+export function serializeLockFile(lockFile: SyncLockFile): string {
+  return `${serializeNode(lockFile, '', [])}\n`;
 }
 
 // Per-manager memo of the entries-mutation counter value that `stats` were
@@ -244,8 +290,11 @@ export class SyncLockManager {
     }
     lockFile.generated_at = new Date().toISOString();
     lockFile._comment = LOCK_FILE_COMMENT;
-    const serialized = JSON.stringify(lockFile, sortedKeysReplacer, 2) + '\n';
-    await atomicWriteFile(this.lockFilePath, serialized, 'utf-8');
+    await atomicWriteFile(
+      this.lockFilePath,
+      serializeLockFile(lockFile),
+      'utf-8'
+    );
   }
 
   async updateEntry(
diff --git a/src/sync/sync-resolve.ts b/src/sync/sync-resolve.ts
index c3300e82..9e61e5fb 100644
--- a/src/sync/sync-resolve.ts
+++ b/src/sync/sync-resolve.ts
@@ -1,4 +1,5 @@
 import * as fs from 'fs';
+import { serializeLockFile } from './sync-lock.js';
 import type { SyncLockFile } from './types.js';
 
 const CONFLICT_START = /^<{7}/m;
@@ -84,6 +85,18 @@ export function resolveConflicts(
   return { resolved: result.join('\n'), mergeCount, decisions };
 }
 
+/**
+ * Splits off a region's structural trailing comma, which joins it to the member
+ * that follows the conflict. A region is a sequence of object members, so the
+ * comma has to come off before the region can be parsed as an object body and go
+ * back on afterwards.
+ */
+function splitTerminator(fragment: string): { body: string; comma: string } {
+  const match = /,\s*$/.exec(fragment);
+  if (!match) return { body: fragment, comma: '' };
+  return { body: fragment.slice(0, match.index), comma: match[0] };
+}
+
 function mergeConflictSections(
   ours: string,
   theirs: string,
@@ -93,15 +106,33 @@ function mergeConflictSections(
   let theirsObj: Record<string, unknown> | undefined;
   let parseError: string | undefined;
 
-  try {
-    oursObj = JSON.parse(`{${ours}}`) as Record<string, unknown>;
-  } catch (err) {
-    parseError = err instanceof Error ? err.message : String(err);
+  const oursSplit = splitTerminator(ours);
+  const theirsSplit = splitTerminator(theirs);
+  // The member following the region is context shared by both sides, so a
+  // well-formed pair of regions agrees on whether it needs a comma. Disagreement
+  // means this is not a sequence of members and guessing a terminator could
+  // produce invalid JSON, so leave it to the fallback below.
+  const sameTerminator =
+    (oursSplit.comma === '') === (theirsSplit.comma === '');
+
+  if (!sameTerminator) {
+    parseError = 'sides disagree on whether the region ends a member list';
+  }
+
+  if (!parseError) {
+    try {
+      oursObj = JSON.parse(`{${oursSplit.body}}`) as Record<string, unknown>;
+    } catch (err) {
+      parseError = err instanceof Error ? err.message : String(err);
+    }
   }
 
   if (!parseError) {
     try {
-      theirsObj = JSON.parse(`{${theirs}}`) as Record<string, unknown>;
+      theirsObj = JSON.parse(`{${theirsSplit.body}}`) as Record<
+        string,
+        unknown
+      >;
     } catch (err) {
       parseError = err instanceof Error ? err.message : String(err);
     }
@@ -115,7 +146,7 @@ function mergeConflictSections(
       ''
     );
     const json = JSON.stringify(merged, null, 2);
-    return { merged: json.slice(2, -2), decisions };
+    return { merged: json.slice(2, -2) + oursSplit.comma, decisions };
   }
 
   const preview = truncate(ours.trim().split('\n')[0] ?? '', 10);
@@ -285,14 +316,22 @@ export async function resolveLockFile(
     file: lockPath,
   });
 
+  let parsed: unknown;
   try {
-    JSON.parse(resolved) as SyncLockFile;
+    parsed = JSON.parse(resolved);
   } catch {
     return { hadConflicts: true, resolved: false, entriesMerged: 0, decisions };
   }
 
   if (!options.dryRun) {
-    await fs.promises.writeFile(lockPath, resolved, 'utf-8');
+    // Merging rebuilds each region with its own indentation, so writing
+    // `resolved` verbatim would leave translations expanded across lines again
+    // and re-arm the field-level auto-merge the canonical form prevents.
+    const canonical =
+      typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+        ? serializeLockFile(parsed as SyncLockFile)
+        : resolved;
+    await fs.promises.writeFile(lockPath, canonical, 'utf-8');
   }
   return {
     hadConflicts: true,
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 777cc292..8a83ff46 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -943,14 +943,10 @@ describe('CLI Sync E2E', () => {
       writeSyncConfig(testFiles.path, ['de']);
       writeSourceFile(testFiles.path);
 
-      // Both halves end with a trailing comma, so the per-region JSON.parse
-      // fails and the length heuristic kicks in; the following non-conflicted
-      // entry keeps the merged document valid.
-      const ourEntry = {
-        hash: 'a',
-        translated_at: '2026-04-20T09:33:15Z',
-        status: 'translated',
-      };
+      // One side deleted the entry the other modified, so the halves disagree on
+      // whether the region ends a member list. Guessing a terminator there could
+      // emit invalid JSON, so the region falls to the length heuristic instead;
+      // the following non-conflicted entry keeps the merged document valid.
       const theirEntry = {
         hash: 'b',
         translated_at: '2026-04-20T08:12:03Z',
@@ -964,7 +960,6 @@ describe('CLI Sync E2E', () => {
         '  "entries": {',
         '    "locales/en.json": {',
         '<<<<<<< HEAD',
-        `      "greeting": { "source_hash": "src1", "source_text": "Hello", "translations": { "de": ${JSON.stringify(ourEntry)} } },`,
         '=======',
         `      "greeting": { "source_hash": "src2", "source_text": "Hello", "translations": { "de": ${JSON.stringify(theirEntry)} } },`,
         '>>>>>>> feature/other',
diff --git a/tests/unit/prototype-key-safety.test.ts b/tests/unit/prototype-key-safety.test.ts
index e62b1acc..fa6ce993 100644
--- a/tests/unit/prototype-key-safety.test.ts
+++ b/tests/unit/prototype-key-safety.test.ts
@@ -18,7 +18,8 @@
 import { JsonFormatParser } from '../../src/formats/json';
 import { sanitizePullKeysResponse } from '../../src/sync/tms-client';
 import { GlossaryService } from '../../src/services/glossary';
-import { sortedKeysReplacer } from '../../src/sync/sync-lock';
+import { serializeLockFile } from '../../src/sync/sync-lock';
+import type { SyncLockFile } from '../../src/sync/types';
 import { Logger } from '../../src/utils/logger';
 
 const PROTO_KEYS = [
@@ -225,26 +226,35 @@ describe('prototype-named key safety', () => {
     });
   });
 
-  describe('sortedKeysReplacer', () => {
+  describe('serializeLockFile', () => {
     it.each(PROTO_KEYS)(
-      'should preserve a %s lockfile key when sorting',
+      'should preserve a %s source-file key when sorting',
       (key) => {
         // Built by JSON.parse so the prototype-named key is a real own property.
-        const src = JSON.parse(
-          `{"zebra": 1, ${JSON.stringify(key)}: 2, "alpha": 3}`
-        ) as Record<string, unknown>;
-
-        const out = sortedKeysReplacer('entries', src) as Record<
-          string,
-          unknown
-        >;
-
-        expect(Object.hasOwn(out, key)).toBe(true);
-        expect(out[key]).toBe(2);
-        expect(
-          JSON.parse(JSON.stringify(out)) as Record<string, unknown>
-        ).toHaveProperty(key, 2);
+        const lockFile = JSON.parse(
+          `{"version": 1, "entries": {"zebra.json": {}, ${JSON.stringify(key)}: {}, "alpha.json": {}}}`
+        ) as SyncLockFile;
+
+        const out = JSON.parse(serializeLockFile(lockFile)) as {
+          entries: Record<string, unknown>;
+        };
+
+        expect(Object.hasOwn(out.entries, key)).toBe(true);
       }
     );
+
+    it.each(PROTO_KEYS)('should preserve a %s i18n key', (key) => {
+      const lockFile = JSON.parse(
+        `{"version": 1, "entries": {"locales/en.json": {"zebra": {"source_hash": "z"}, ${JSON.stringify(key)}: {"source_hash": "p"}}}}`
+      ) as SyncLockFile;
+
+      const out = JSON.parse(serializeLockFile(lockFile)) as {
+        entries: Record<string, Record<string, { source_hash: string }>>;
+      };
+
+      const fileEntries = out.entries['locales/en.json']!;
+      expect(Object.hasOwn(fileEntries, key)).toBe(true);
+      expect(fileEntries[key]!.source_hash).toBe('p');
+    });
   });
 });
diff --git a/tests/unit/sync/sync-lock.test.ts b/tests/unit/sync/sync-lock.test.ts
index 97345a7b..dbbf8f8f 100644
--- a/tests/unit/sync/sync-lock.test.ts
+++ b/tests/unit/sync/sync-lock.test.ts
@@ -4,6 +4,7 @@ import * as os from 'os';
 import {
   computeSourceHash,
   createEmptyLockFile,
+  serializeLockFile,
   SyncLockManager,
 } from '../../../src/sync/sync-lock';
 import { Logger } from '../../../src/utils/logger';
@@ -84,6 +85,152 @@ describe('computeSourceHash()', () => {
   });
 });
 
+describe('serializeLockFile()', () => {
+  function lockWith(
+    translations: Record<string, unknown>,
+    extra: Record<string, Record<string, SyncLockEntry>> = {}
+  ): SyncLockFile {
+    const lockFile = createEmptyLockFile('en');
+    lockFile.entries['locales/en.json'] = {
+      greeting: {
+        source_hash: '185f8db32271',
+        source_text: 'Hello',
+        translations: translations as SyncLockEntry['translations'],
+      },
+    };
+    Object.assign(lockFile.entries, extra);
+    return lockFile;
+  }
+
+  const de = {
+    hash: 'h1',
+    translated_at: '2026-01-01T00:00:00.000Z',
+    status: 'translated',
+    review_status: 'machine_translated',
+  };
+  const fr = {
+    hash: 'h2',
+    translated_at: '2026-01-02T00:00:00.000Z',
+    status: 'translated',
+    review_status: 'human_reviewed',
+  };
+
+  function localeLines(serialized: string): string[] {
+    return serialized.split('\n').filter((line) => /^\s*"(de|fr)":/.test(line));
+  }
+
+  // A translation is only meaningful as a whole: its hash, timestamp and review
+  // status describe one act of translating. Splitting it across lines lets git
+  // merge the fields independently and fabricate a combination that existed on
+  // neither branch, so each one occupies a single line.
+  it('should put every translation on one line', () => {
+    const lines = localeLines(serializeLockFile(lockWith({ de, fr })));
+
+    expect(lines).toHaveLength(2);
+    for (const line of lines) {
+      expect(line.trimEnd().replace(/,$/, '')).toMatch(/\}$/);
+    }
+  });
+
+  it('should keep every field of a translation on that one line', () => {
+    const [line] = localeLines(serializeLockFile(lockWith({ de })));
+
+    expect(line).toContain('"hash": "h1"');
+    expect(line).toContain('"translated_at": "2026-01-01T00:00:00.000Z"');
+    expect(line).toContain('"status": "translated"');
+    expect(line).toContain('"review_status": "machine_translated"');
+  });
+
+  it('should still expand the containers above a translation', () => {
+    const serialized = serializeLockFile(lockWith({ de }));
+
+    expect(serialized).toContain('\n  "entries": {\n');
+    expect(serialized).toContain('\n    "locales/en.json": {\n');
+    expect(serialized).toContain('\n      "greeting": {\n');
+    expect(serialized).toContain('\n        "translations": {\n');
+  });
+
+  it('should round-trip to an identical object', () => {
+    const lockFile = lockWith({ de, fr });
+
+    expect(JSON.parse(serializeLockFile(lockFile))).toEqual(
+      JSON.parse(JSON.stringify(lockFile))
+    );
+  });
+
+  it('should sort the keys inside a one-line translation', () => {
+    const [line] = localeLines(serializeLockFile(lockWith({ de })));
+
+    expect(line!.indexOf('"hash"')).toBeLessThan(
+      line!.indexOf('"review_status"')
+    );
+    expect(line!.indexOf('"review_status"')).toBeLessThan(
+      line!.indexOf('"status"')
+    );
+  });
+
+  it('should sort container keys and end with a newline', () => {
+    const serialized = serializeLockFile(
+      lockWith({ fr, de }, { 'z.json': {}, 'a.json': {} })
+    );
+
+    expect(serialized.indexOf('"a.json"')).toBeLessThan(
+      serialized.indexOf('"z.json"')
+    );
+    expect(serialized.indexOf('"de"')).toBeLessThan(serialized.indexOf('"fr"'));
+    expect(serialized.endsWith('\n')).toBe(true);
+  });
+
+  // An i18n key of this name is a real possibility and must not be mistaken for
+  // the translations container that sits one level deeper.
+  it('should not compact an entry under an i18n key named translations', () => {
+    const lockFile = createEmptyLockFile('en');
+    lockFile.entries['locales/en.json'] = {
+      translations: {
+        source_hash: 'abc',
+        source_text: 'Hello',
+        translations: { de: de as never },
+      },
+    };
+
+    const serialized = serializeLockFile(lockFile);
+
+    expect(serialized).toContain('\n      "translations": {\n');
+    expect(serialized).toContain('\n        "source_hash": "abc",\n');
+  });
+
+  // No field of the lock file is an array today, but `sync resolve` serializes
+  // whatever it parsed out of a conflicted file, which may have been written by
+  // a version that added one. Rewriting it as {"0": ...} would be silent damage.
+  describe('array members', () => {
+    it('should keep an array in a container an array', () => {
+      const lockFile = JSON.parse(
+        '{"version": 1, "notes": ["a", "b"], "empty": [], "entries": {}}'
+      ) as SyncLockFile;
+
+      const out = JSON.parse(serializeLockFile(lockFile)) as {
+        notes: string[];
+        empty: string[];
+      };
+
+      expect(out.notes).toEqual(['a', 'b']);
+      expect(out.empty).toEqual([]);
+    });
+
+    it('should keep an array inside a translation on the one line', () => {
+      const lockFile = JSON.parse(
+        '{"version": 1, "entries": {"locales/en.json": {"greeting": {"translations": {"de": {"hash": "h", "tags": ["x", "y"], "nested": [{"k": 1}]}}}}}}'
+      ) as SyncLockFile;
+
+      const serialized = serializeLockFile(lockFile);
+
+      expect(serialized).toContain(
+        '"de": {"hash": "h", "nested": [{"k": 1}], "tags": ["x", "y"]}'
+      );
+    });
+  });
+});
+
 describe('createEmptyLockFile()', () => {
   it('should create lock file with correct version', () => {
     const lockFile = createEmptyLockFile('en');
diff --git a/tests/unit/sync/sync-resolve.test.ts b/tests/unit/sync/sync-resolve.test.ts
index 08385d22..42c23dc3 100644
--- a/tests/unit/sync/sync-resolve.test.ts
+++ b/tests/unit/sync/sync-resolve.test.ts
@@ -148,7 +148,7 @@ describe('resolveConflicts()', () => {
         '<<<<<<< HEAD',
         entry('ours_hash', ourStamp),
         '=======',
-        entry('theirs_hash', theirStamp),
+        entry('them_hash', theirStamp),
         '>>>>>>> feature/de-updates',
         '    }',
         '  }',
@@ -172,7 +172,7 @@ describe('resolveConflicts()', () => {
         conflictedLock('2026-02-01T00:00:00.000Z', '2026-03-01T00:00:00.000Z')
       );
 
-      expect(survivingHash(resolved)).toBe('theirs_hash');
+      expect(survivingHash(resolved)).toBe('them_hash');
       expect(
         decisions.some(
           (d) => d.source === 'theirs' && /newer translated_at/.test(d.reason)
@@ -226,6 +226,194 @@ describe('resolveConflicts()', () => {
     });
   });
 
+  // The lockfile puts each translation on one line, so the smallest region git
+  // can produce is a whole `"<locale>": {...}` pair. Unless that pair is the
+  // last in its map it carries a trailing comma, which is the shape the resolver
+  // actually has to read.
+  describe("git's conflict shape for a one-line-per-translation lockfile", () => {
+    function conflictedLock(
+      ours: string,
+      theirs: string,
+      trailing: ',' | '' = ','
+    ): string {
+      return [
+        '{',
+        '  "version": 1,',
+        '  "entries": {',
+        '    "locales/en.json": {',
+        '      "greeting": {',
+        '        "source_hash": "185f8db32271",',
+        '        "source_text": "Hello",',
+        '        "translations": {',
+        '<<<<<<< HEAD',
+        `          "de": ${ours}${trailing}`,
+        '=======',
+        `          "de": ${theirs}${trailing}`,
+        '>>>>>>> feature/de-updates',
+        trailing === ','
+          ? '          "fr": {"hash": "fr_hash", "status": "translated", "translated_at": "2026-01-01T00:00:00.000Z"}'
+          : '',
+        '        }',
+        '      }',
+        '    }',
+        '  }',
+        '}',
+      ]
+        .filter((line) => line !== '')
+        .join('\n');
+    }
+
+    function translation(
+      hash: string,
+      stamp: string,
+      review = 'machine_translated'
+    ): string {
+      return `{"hash": "${hash}", "review_status": "${review}", "status": "translated", "translated_at": "${stamp}"}`;
+    }
+
+    function surviving(resolved: string): Record<string, unknown> {
+      const parsed = JSON.parse(resolved) as {
+        entries: Record<
+          string,
+          Record<
+            string,
+            { translations: Record<string, Record<string, unknown>> }
+          >
+        >;
+      };
+      return parsed.entries['locales/en.json']!['greeting']!.translations[
+        'de'
+      ]!;
+    }
+
+    it('should take theirs on the newer translated_at despite the trailing comma', () => {
+      const { resolved, decisions } = resolveConflicts(
+        conflictedLock(
+          translation('ours_hash', '2026-02-01T00:00:00.000Z'),
+          translation('them_hash', '2026-03-01T00:00:00.000Z')
+        )
+      );
+
+      expect(surviving(resolved)['hash']).toBe('them_hash');
+      expect(
+        decisions.some(
+          (d) => d.source === 'theirs' && /newer translated_at/.test(d.reason)
+        )
+      ).toBe(true);
+    });
+
+    it('should not fall back to the length heuristic for that shape', () => {
+      const { decisions } = resolveConflicts(
+        conflictedLock(
+          translation('ours_hash', '2026-02-01T00:00:00.000Z'),
+          translation('them_hash', '2026-03-01T00:00:00.000Z')
+        )
+      );
+
+      expect(decisions.filter((d) => d.source === 'length-heuristic')).toEqual(
+        []
+      );
+      expect(decisions.map((d) => d.key)).toEqual(['de']);
+    });
+
+    it('should leave the locale that followed the conflict intact', () => {
+      const { resolved } = resolveConflicts(
+        conflictedLock(
+          translation('ours_hash', '2026-02-01T00:00:00.000Z'),
+          translation('them_hash', '2026-03-01T00:00:00.000Z')
+        )
+      );
+
+      const parsed = JSON.parse(resolved) as {
+        entries: Record<
+          string,
+          Record<string, { translations: Record<string, { hash: string }> }>
+        >;
+      };
+      expect(
+        parsed.entries['locales/en.json']!['greeting']!.translations['fr']!.hash
+      ).toBe('fr_hash');
+    });
+
+    it('should resolve the shape without a trailing comma too', () => {
+      const { resolved, decisions } = resolveConflicts(
+        conflictedLock(
+          translation('ours_hash', '2026-02-01T00:00:00.000Z'),
+          translation('them_hash', '2026-03-01T00:00:00.000Z'),
+          ''
+        )
+      );
+
+      expect(surviving(resolved)['hash']).toBe('them_hash');
+      expect(decisions.filter((d) => d.source === 'length-heuristic')).toEqual(
+        []
+      );
+    });
+
+    // The failure this format exists to prevent: never emit a translation whose
+    // fields come from both sides.
+    it('should keep one whole side when the timestamps are equal', () => {
+      const stamp = '2026-01-01T00:00:00.000Z';
+      const { resolved } = resolveConflicts(
+        conflictedLock(
+          translation('machine_hash', stamp, 'machine_translated'),
+          translation('human_hash', stamp, 'human_reviewed')
+        )
+      );
+
+      const winner = surviving(resolved);
+      expect([
+        { hash: 'machine_hash', review: 'machine_translated' },
+        { hash: 'human_hash', review: 'human_reviewed' },
+      ]).toContainEqual({
+        hash: winner['hash'],
+        review: winner['review_status'],
+      });
+    });
+  });
+
+  describe('sides that disagree on the region terminator', () => {
+    // The member following a region is context shared by both sides, so a region
+    // that is a member list carries the same terminator on both. Disagreement
+    // means one side deleted what the other kept, and inventing a terminator
+    // there can only produce invalid JSON.
+    function deleteVersusModify(): string {
+      return [
+        '{',
+        '  "entries": {',
+        '    "locales/en.json": {',
+        '<<<<<<< HEAD',
+        '=======',
+        '      "greeting": {"source_hash": "src2", "translations": {}},',
+        '>>>>>>> feature/other',
+        '      "farewell": {"source_hash": "src3", "translations": {}}',
+        '    }',
+        '  }',
+        '}',
+      ].join('\n');
+    }
+
+    it('should fall back rather than guess a terminator', () => {
+      const { decisions } = resolveConflicts(deleteVersusModify());
+
+      expect(decisions).toHaveLength(1);
+      expect(decisions[0]!.source).toBe('length-heuristic');
+      expect(decisions[0]!.reason).toMatch(/ends a member list/);
+    });
+
+    it('should still leave the document parseable', () => {
+      const { resolved } = resolveConflicts(deleteVersusModify());
+
+      const parsed = JSON.parse(resolved) as {
+        entries: Record<string, Record<string, unknown>>;
+      };
+      expect(Object.keys(parsed.entries['locales/en.json']!).sort()).toEqual([
+        'farewell',
+        'greeting',
+      ]);
+    });
+  });
+
   describe('fallback to longer side when JSON does not parse', () => {
     it('should pick the longer side when neither side is valid JSON', () => {
       const content = [
@@ -365,6 +553,60 @@ describe('resolveLockFile()', () => {
     expect(parsed.extra).toBe(true);
   });
 
+  // Resolving rebuilds the fragment with its own indentation, so without writing
+  // the canonical form back the file would leave the resolver's own output in a
+  // shape the next merge can field-mix again.
+  it('should write the resolved lock file back in canonical form', async () => {
+    const translation = (hash: string, stamp: string): string =>
+      `{"hash": "${hash}", "status": "translated", "translated_at": "${stamp}"}`;
+    mockReadFile.mockResolvedValue(
+      [
+        '{',
+        '  "version": 1,',
+        '  "entries": {',
+        '    "locales/en.json": {',
+        '      "greeting": {',
+        '        "source_hash": "185f8db32271",',
+        '        "source_text": "Hello",',
+        '        "translations": {',
+        '<<<<<<< HEAD',
+        `          "de": ${translation('ours_hash', '2026-02-01T00:00:00.000Z')},`,
+        '=======',
+        `          "de": ${translation('them_hash', '2026-03-01T00:00:00.000Z')},`,
+        '>>>>>>> branch',
+        `          "fr": ${translation('fr_hash', '2026-01-01T00:00:00.000Z')}`,
+        '        }',
+        '      }',
+        '    }',
+        '  }',
+        '}',
+      ].join('\n')
+    );
+    mockWriteFile.mockResolvedValue(undefined);
+
+    const result = await resolveLockFile(lockPath);
+
+    expect(result.resolved).toBe(true);
+    const written = mockWriteFile.mock.calls[0]![1] as string;
+    const localeLines = written
+      .split('\n')
+      .filter((line) => /^\s*"(de|fr)":/.test(line));
+    expect(localeLines).toHaveLength(2);
+    for (const line of localeLines) {
+      expect(line.trimEnd().replace(/,$/, '')).toMatch(/\}$/);
+    }
+    const parsed = JSON.parse(written) as {
+      entries: Record<
+        string,
+        Record<string, { translations: Record<string, { hash: string }> }>
+      >;
+    };
+    const translations =
+      parsed.entries['locales/en.json']!['greeting']!.translations;
+    expect(translations['de']!.hash).toBe('them_hash');
+    expect(translations['fr']!.hash).toBe('fr_hash');
+  });
+
   it('should return hadConflicts=false for a clean file', async () => {
     const cleanContent = JSON.stringify({ entries: {}, version: 1 });
     mockReadFile.mockResolvedValue(cleanContent);

From 2a965460c477aaf878ac9c5c0abd947db513dc61 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 19:12:39 +0200
Subject: [PATCH 139/256] fix(sync): name the failed-translation count in the
 sync summary

A run that translated 50 of 200 keys and rate-limited on the rest printed
these two lines, in this order:

  x de: 50/200 keys (locales/en.json)
  Sync complete: 200 new

They contradict each other, and the accurate one is the easier to miss in
a CI log. The key counts come from the diff -- how many keys were new,
updated or current -- not from how many were successfully translated, so
"200 new" is a true statement about the diff that reads as an
accomplishment under the word "complete". It now reads:

  Sync complete: 200 new (150 translations failed)

Totalled across locales, and omitted entirely when nothing failed. The
count comes from fileResults, which already carries per-locale `failed`,
so SyncResult gains no field and the --format json contract is untouched.
The diff counts are unchanged; they were accurate about the diff all
along. Exit 12 on partial failure is unchanged.

The larger claim filed against this finding did NOT reproduce and no code
changed for it -- see the bead for the measurement. sync already records
status: 'failed' for a key whose translation failed, and sync-differ.ts
honours that, which is why recovery works.

Refs cli-8kr2.57
---
 CHANGELOG.md                         |  2 +
 docs/SYNC.md                         |  9 +++
 src/cli/commands/sync-command.ts     | 13 +++-
 tests/unit/sync/sync-command.test.ts | 89 ++++++++++++++++++++++++++++
 4 files changed, 112 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f87e834f..229dacb8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **the `Sync complete:` summary names how many translations failed**, instead of reading as though every diffed key had landed. The key counts in that line come from the diff, not from what was successfully translated, so a run that translated 50 of 200 keys and rate-limited on the rest printed `✗ de: 50/200 keys` and then `Sync complete: 200 new` directly beneath it — two lines flatly contradicting each other, with the accurate one being the easier to miss in a CI log. It now reads `Sync complete: 200 new (150 translations failed)`. The count totals every locale, and nothing is appended when nothing failed. Exit code 12 on partial failure is unchanged, as are the diff counts themselves, which were accurate about the diff all along.
+
 - **sync**: **the lockfile no longer lets `git merge` invent a translation that existed on neither branch, and `sync resolve` now actually applies its documented `translated_at` tie-break.** One root cause behind both: entries were serialized one field per line, making git's unit of merge a *field* rather than a *translation*. Measured with real `git merge` on real serializer output, against a stashed-old-code control. **The silent case, which never reached `sync resolve` at all:** a branch that changed only `review_status` and a branch that changed only `translated_at` are non-adjacent lines with `status` unchanged between them, so git merged both hunks cleanly and produced `review_status: human_reviewed` from one side carrying `translated_at` from the other — a combination on neither branch, marking machine output as human-approved with a timestamp that makes the staleness invisible to any later timestamp comparison, at exit 0 with no conflict reported. **The `sync resolve` case:** where git *did* conflict, the region was the entry's field list, so it parsed to three scalars and the resolver's entry-level branch was unreachable; every field took the terminal `kept ours: scalar conflict, defaulting to ours` path. Measured discarding a newer `human_reviewed` translation in favour of older machine output, reported as resolved at exit 0 — the exact opposite of the documented rule, and side-dependent, so it silently did the right thing whenever the newer edit happened to be on the local branch. **Each translation is now written on a single line**, which makes the smallest region git can produce a whole entry: the field-level overlap conflicts instead of merging, and the conflict reaches the timestamp comparison, which picks one whole coherent side. Two changes were needed to make that hold, neither of them obvious from the format change alone. A region inside an object carries a trailing comma joining it to the next member, and `JSON.parse('{' + region + '}')` fails on it — so *every* entry but the last locale in its map would have fallen straight back to the length heuristic and kept discarding the newer side; the terminator is now taken off before parsing and put back after. And because resolving rebuilds each region with its own indentation, the resolved file is now written back in canonical form, so committing it cannot leave entries expanded across lines for the next merge to recombine. Where the two sides *disagree* on the terminator — one deleted what the other modified — no terminator is correct for both and the region still falls to the length heuristic rather than risk invalid JSON. **Upgrading reformats every existing lockfile on the next write, producing one large diff; it is formatting only and no entry's content changes.** Keys are sorted within the line, so a changed translation is now a one-line diff rather than three or four.
 
 - **sync**: **`sync export` produces well-formed XLIFF for keys that contain control characters, and no longer changes a key on the way out.** `escapeXml` escaped `&`, `<`, `>` and `"` only, so a key holding a C0 control was written straight into the `id=` and `resname=` attributes — and C0 other than tab, newline and carriage return has no representation at all in XML 1.0, not even as a character reference, so the file was not well-formed and a translator's tool would reject it whole. Those characters are now replaced with `?`, which costs one odd character in one id rather than an unreadable handoff file. Separately, and independent of any hostile input: a tab, newline or carriage return inside a key was emitted literally, and every conforming XML parser **normalizes those to a space inside an attribute value** — so a multi-line key silently came back different from the key that was exported. They are now emitted as `&#9;`, `&#10;` and `&#13;`, which round-trip exactly. C1 (U+0080–U+009F) is deliberately left alone: those are valid XML 1.0 characters that round-trip unchanged, and an export is a data file, so it is mutated no further than validity requires.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index eb2a3e1c..238a7afe 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -481,6 +481,15 @@ Sync complete: 2 new, 1 updated, 7 current (100 chars, ~$0.00) (Pro tier estimat
 
 Each locale shows `✓` when all translations succeeded, or `✗` when some failed. The format is `locale: translated/attempted`.
 
+When some translations failed, the summary line names how many. The key counts describe the **diff** — how many keys were new, updated or current — not how many were successfully translated, so without this the line read as though every diffed key had landed:
+
+```
+  ✗ de: 50/200 keys (locales/en.json)
+Sync complete: 200 new (150 translations failed)
+```
+
+The count totals every locale, so a run failing 4 keys in `de` and 3 in `fr` reports `7 translations failed`. Exit code is 12 (partial failure).
+
 In `--dry-run` mode, the output includes estimated characters and cost (computed from source string lengths × target locales, no API calls):
 
 ```
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index 4c9fcbea..1a395a49 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -736,6 +736,17 @@ export class SyncCommand {
     if (result.deletedKeys > 0) parts.push(`${result.deletedKeys} deleted`);
 
     const summary = parts.length > 0 ? parts.join(', ') : 'no changes';
+    // The key counts above describe the diff, not what landed, so on a partial
+    // failure the line would otherwise read as if every diffed key had been
+    // translated — contradicting the per-locale progress lines above it.
+    const failedTranslations = result.fileResults.reduce(
+      (total, fileResult) => total + fileResult.failed,
+      0
+    );
+    const failures =
+      failedTranslations > 0
+        ? ` (${failedTranslations.toLocaleString()} translations failed)`
+        : '';
     const localeInfo =
       result.dryRun && result.targetLocaleCount > 0
         ? ` across ${result.targetLocaleCount} language${result.targetLocaleCount === 1 ? '' : 's'}`
@@ -745,7 +756,7 @@ export class SyncCommand {
       chars = ` (${result.totalCharactersBilled.toLocaleString()} chars, ${formatCostEstimate(result.totalCharactersBilled)} (Pro tier estimate))`;
     }
 
-    Logger.info(`Sync complete: ${summary}${localeInfo}${chars}`);
+    Logger.info(`Sync complete: ${summary}${failures}${localeInfo}${chars}`);
 
     if (result.strategy) {
       const stratParts: string[] = [];
diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index e7c4c7f1..42294c81 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -433,6 +433,95 @@ describe('SyncCommand', () => {
       expect(infoOutput).toContain('1 deleted');
     });
 
+    // The key counts come from the diff, not from what landed, so on a partial
+    // failure "Sync complete: 200 new" reads as if all 200 were translated —
+    // directly contradicting the per-locale line above it.
+    describe('partial translation failure', () => {
+      function failedRun(): SyncResult {
+        return makeResult({
+          newKeys: 200,
+          staleKeys: 0,
+          currentKeys: 0,
+          fileResults: [
+            {
+              file: 'locales/en.json',
+              locale: 'de',
+              translated: 50,
+              skipped: 0,
+              failed: 150,
+              written: true,
+            },
+          ],
+        });
+      }
+
+      async function summaryLine(result: SyncResult): Promise<string> {
+        const command = new SyncCommand(createMockSyncService(result));
+        await command.run({});
+        return (
+          logInfoSpy.mock.calls
+            .map((c) => String(c[0]))
+            .find((line) => line.startsWith('Sync complete:')) ?? ''
+        );
+      }
+
+      it('should report the failure count in the summary', async () => {
+        expect(await summaryLine(failedRun())).toContain(
+          '150 translations failed'
+        );
+      });
+
+      it('should still report the diffed key counts', async () => {
+        expect(await summaryLine(failedRun())).toContain('200 new');
+      });
+
+      it('should say nothing about failures when there were none', async () => {
+        const line = await summaryLine(
+          makeResult({
+            fileResults: [
+              {
+                file: 'locales/en.json',
+                locale: 'de',
+                translated: 50,
+                skipped: 0,
+                failed: 0,
+                written: true,
+              },
+            ],
+          })
+        );
+
+        expect(line).not.toContain('failed');
+      });
+
+      it('should total failures across locales', async () => {
+        const line = await summaryLine(
+          makeResult({
+            fileResults: [
+              {
+                file: 'locales/en.json',
+                locale: 'de',
+                translated: 1,
+                skipped: 0,
+                failed: 4,
+                written: true,
+              },
+              {
+                file: 'locales/en.json',
+                locale: 'fr',
+                translated: 2,
+                skipped: 0,
+                failed: 3,
+                written: true,
+              },
+            ],
+          })
+        );
+
+        expect(line).toContain('7 translations failed');
+      });
+    });
+
     it('should pass flagForReview through to sync options', async () => {
       const result = makeResult();
       const mockService = createMockSyncService(result);

From c92b0cdadcd95bb6718c50f0ff19c5f47aaef470 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 19:39:31 +0200
Subject: [PATCH 140/256] fix(logger): redact the credential actually in use,
 and only real ones

Three defects in one function, all in the redactor that every stderr
message passes through. Two of them let a credential out; the third
corrupted the diagnostics of every run that had a short key set.

Non-plain objects were returned live. The bail-out contradicted the
function's own documented guarantee, which names a dumped axios error
specifically. Measured: an Error whose config.headers is an AxiosHeaders
instance printed

  headers: AxiosHeaders {
    Authorization: 'DeepL-Auth-Key SUPER-SECRET-KEY-FROM-CONFIG'
  }

while the plain-object field beside it on the same error was redacted.
Map and Set were worse than that, because their contents are not own
properties at all and util.inspect prints them anyway:
Map(1) { 'Authorization' => 'DeepL-Auth-Key SECRET' } never reached the
string transform.

Every object is now rebuilt property by property on its own prototype,
so util.inspect still names the class -- AxiosHeaders { Authorization:
'DeepL-Auth-Key [REDACTED]' } -- but never receives the instance the
caller passed. Map and Set are rebuilt with their keys and members
mapped. Handing back a foreign instance untouched is the wrong default
for a redactor; copying is the fail-closed one.

Four types stay pass-through on purpose. Date, RegExp, ArrayBuffer and
its views hold nothing in string-keyed own properties, so a rebuilt copy
would either lose the payload -- Date {} rather than the timestamp -- or,
for a Buffer, define one own property per byte, which turns a logged 1 MB
buffer into a million-property copy. util.inspect renders a buffer as
hex, so none of the four prints a credential as readable text.

The literal-value backstop read only process.env, and the config-file key
takes precedence over it. src/cli/index.ts resolves apiKey ?? envKey, so
the value on the wire is exactly the one the redactor could not see.
Measured against a loopback stub with both set: the captured header was

  authorization: DeepL-Auth-Key CONFIG-FILE-KEY-WINS:fx

and Logger.error redacted only ENV-KEY-LOSES:fx, printing the config key
in full. Logger.registerSecret now takes the resolved credential, called
from the HttpClient constructor -- the one place that sees whichever key
won precedence, because it is where the key is attached to every request
-- and from the TmsClient constructor, which covers a tms.api_key or
tms.token inlined in .deepl-sync.yaml. That chokepoint beats the CLI's
key-resolution seams: five call sites read auth.apiKey and a per-seam fix
goes stale on the sixth.

Neither hole is a live leak on its own -- no call site hands a raw axios
error to the logger -- but the second is reachable through a server that
echoes the key back in its own error body, which surfaces as
API error: <key>. The e2e drives that path and asserts on the bare value
rather than the whole Authorization header, so the pre-existing header
pattern cannot mask a missing registration.

The env-versus-config precedence is deliberately left alone. Registering
the resolved credential makes redaction independent of which side wins,
which is the property that was missing.

Third defect: the literal replace had no length floor, so any message
containing the credential inside an ordinary word was mangled. One real
run with DEEPL_API_KEY=k against a closed port printed

  Warning: sending your DeepL API [REDACTED]ey to ...
  Error: Networ[REDACTED] error: connect ECONNREFUSED
  Suggestion: Chec[REDACTED] your internet connection and proxy settings

with the config path in the first line rendered /Users/[REDACTED]wey/...
A literal value is now replaced only at 8 characters or more; below that
the header and query-parameter patterns still apply, so nothing shaped
like a credential in transit goes unredacted. A real key is UUID-shaped
with a :fx or hyphenated suffix and TMS credentials are longer, so the
floor excludes nothing genuine -- the shortest key in this repo's own
suites is 12 characters. Matching on a token boundary was rejected
instead of the floor: it would silently MISS a real key printed before a
word character, and failing to redact a real credential is the more
expensive error than failing to redact a value too short to be one.

One existing test was replaced rather than kept. "should pass non-plain
objects through unchanged" asserted the hole, down to a token=class-secret
inside the instance it expected through untouched.

Refs cli-8kr2.23, cli-8kr2.58
---
 CHANGELOG.md                                  |   4 +
 README.md                                     |   1 +
 src/api/http-client.ts                        |   5 +
 src/sync/tms-client.ts                        |   5 +
 src/utils/logger.ts                           | 118 ++++++++++---
 .../e2e/cli-credential-redaction.e2e.test.ts  | 128 ++++++++++++++
 tests/unit/http-client.test.ts                |  23 +++
 tests/unit/logger.test.ts                     | 164 +++++++++++++++++-
 tests/unit/sync/tms-client.test.ts            |  39 +++++
 9 files changed, 460 insertions(+), 27 deletions(-)
 create mode 100644 tests/e2e/cli-credential-redaction.e2e.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 229dacb8..1ee8767d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -111,6 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **logger**: **a short credential value no longer corrupts every diagnostic message.** The redactor's last step substring-replaced the literal credential with `[REDACTED]`, with no length floor and no token boundary, so any message containing the value inside an ordinary word was mangled. With `DEEPL_API_KEY=k` — a mistyped or throwaway value — a single real CLI run against a closed port printed `Warning: sending your DeepL API [REDACTED]ey to …`, `Error: Networ[REDACTED] error: connect ECONNREFUSED`, `Suggestion: Chec[REDACTED] your internet connection and proxy settings`, and a config path rendered as `/Users/[REDACTED]wey/…`: four lines of nonsense at the moment the user most needs to read them, and the mangling was itself how this was noticed, in the harness output of two unrelated findings. A literal value is now only replaced when it is **at least 8 characters**; below that, the auth-header and `token=`/`api_key=` query-parameter patterns still apply, so nothing that is shaped like a credential in transit goes unredacted. A real DeepL key is UUID-shaped with a `:fx` or hyphenated suffix and TMS credentials are longer still, so the floor excludes nothing genuine — the shortest key in this repo's own test suites is 12 characters. The alternative of matching on a token boundary was rejected: it would silently **miss** a real key printed immediately before a word character, which is the more expensive of the two errors, where a floor can only fail to redact a value too short to be a credential.
+
 - **sync**: **the `Sync complete:` summary names how many translations failed**, instead of reading as though every diffed key had landed. The key counts in that line come from the diff, not from what was successfully translated, so a run that translated 50 of 200 keys and rate-limited on the rest printed `✗ de: 50/200 keys` and then `Sync complete: 200 new` directly beneath it — two lines flatly contradicting each other, with the accurate one being the easier to miss in a CI log. It now reads `Sync complete: 200 new (150 translations failed)`. The count totals every locale, and nothing is appended when nothing failed. Exit code 12 on partial failure is unchanged, as are the diff counts themselves, which were accurate about the diff all along.
 
 - **sync**: **the lockfile no longer lets `git merge` invent a translation that existed on neither branch, and `sync resolve` now actually applies its documented `translated_at` tie-break.** One root cause behind both: entries were serialized one field per line, making git's unit of merge a *field* rather than a *translation*. Measured with real `git merge` on real serializer output, against a stashed-old-code control. **The silent case, which never reached `sync resolve` at all:** a branch that changed only `review_status` and a branch that changed only `translated_at` are non-adjacent lines with `status` unchanged between them, so git merged both hunks cleanly and produced `review_status: human_reviewed` from one side carrying `translated_at` from the other — a combination on neither branch, marking machine output as human-approved with a timestamp that makes the staleness invisible to any later timestamp comparison, at exit 0 with no conflict reported. **The `sync resolve` case:** where git *did* conflict, the region was the entry's field list, so it parsed to three scalars and the resolver's entry-level branch was unreachable; every field took the terminal `kept ours: scalar conflict, defaulting to ours` path. Measured discarding a newer `human_reviewed` translation in favour of older machine output, reported as resolved at exit 0 — the exact opposite of the documented rule, and side-dependent, so it silently did the right thing whenever the newer edit happened to be on the local branch. **Each translation is now written on a single line**, which makes the smallest region git can produce a whole entry: the field-level overlap conflicts instead of merging, and the conflict reaches the timestamp comparison, which picks one whole coherent side. Two changes were needed to make that hold, neither of them obvious from the format change alone. A region inside an object carries a trailing comma joining it to the next member, and `JSON.parse('{' + region + '}')` fails on it — so *every* entry but the last locale in its map would have fallen straight back to the length heuristic and kept discarding the newer side; the terminator is now taken off before parsing and put back after. And because resolving rebuilds each region with its own indentation, the resolved file is now written back in canonical form, so committing it cannot leave entries expanded across lines for the next merge to recombine. Where the two sides *disagree* on the terminator — one deleted what the other modified — no terminator is correct for both and the region still falls to the length heuristic rather than risk invalid JSON. **Upgrading reformats every existing lockfile on the next write, producing one large diff; it is formatting only and no entry's content changes.** Keys are sorted within the line, so a changed translation is now a one-line diff rather than three or four.
@@ -381,6 +383,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **logger**: **the credential redactor no longer has two holes that between them defeat its own documented invariant.** It promised that "a dumped axios error (config.headers.Authorization etc.) cannot leak credentials via util.inspect", and neither half of that held. **Hole one: any object that was not a plain object, an array or an `Error` was returned live.** Reproduced by execution — an `Error` whose `config.headers` is an `AxiosHeaders` instance printed `headers: AxiosHeaders { Authorization: 'DeepL-Auth-Key SUPER-SECRET-KEY-FROM-CONFIG' }` verbatim, while the sibling plain-object field on the same error was redacted correctly. `Map` and `Set` leaked the same way and worse, since their contents are not own properties at all: `util.inspect` prints `Map(1) { 'Authorization' => 'DeepL-Auth-Key SECRET' }` and the redactor never saw a string. Every object is now **rebuilt property by property on its own prototype**, so `util.inspect` still names the class (`AxiosHeaders { Authorization: 'DeepL-Auth-Key [REDACTED]' }`) but never receives the original instance, and `Map`/`Set` are rebuilt with their keys and members mapped. Returning a foreign instance untouched was the wrong default for a redactor; the fail-closed one is to copy. Four types are still passed through deliberately — `Date`, `RegExp`, `ArrayBuffer` and its views — because their payload is not in string-keyed own properties, so a rebuilt copy would either lose it (`Date {}` instead of the timestamp) or, for a `Buffer`, enumerate one own property per byte; none of them renders a credential as readable text, since `util.inspect` prints a buffer as hex. Properties are `defineProperty`'d rather than assigned, so an own key named `__proto__` — which `JSON.parse` can produce — lands on the copy instead of reaching the prototype setter. **Hole two: the literal-value backstop read only `process.env`, and the config-file key wins precedence over it.** `src/cli/index.ts` resolves `apiKey ?? envKey`, so with a key in `config.json` and a different one in `DEEPL_API_KEY`, the value on the wire is precisely the one the redactor could not see. Reproduced against a loopback stub: the captured header was `authorization: DeepL-Auth-Key CONFIG-FILE-KEY-WINS:fx` while `Logger.error` redacted only `ENV-KEY-LOSES:fx` and printed the config key in full. A new `Logger.registerSecret()` closes it, called from the **`HttpClient` constructor** — the one place that sees whichever key won precedence, because it is where the key is attached to every request — and from the **`TmsClient` constructor**, which covers a `tms.api_key` or `tms.token` inlined in `.deepl-sync.yaml`. That chokepoint was chosen over the CLI's key-resolution seams because five call sites read `auth.apiKey` and a per-seam fix would go stale on the sixth. Stated honestly, hole one was a protection-mechanism failure rather than a live leak: no current call site hands a raw axios error to the logger. Hole two is reachable today — a server that echoes the key back in its own error body surfaces as `API error: <key>`, which is the path the new E2E test drives, asserting on the bare value rather than the whole `Authorization` header so the pre-existing header pattern cannot mask a missing registration. The env-versus-config precedence itself is left alone: registration makes redaction independent of which side wins. One existing unit test was replaced rather than kept — `should pass non-plain objects through unchanged` asserted the hole, down to a `token=class-secret` inside the instance it expected to pass through.
+
 - **api**: **a `/v2/translate` or `/v2/write` response body of the wrong shape is now refused instead of being carried into output.** The bodies were typed by a TypeScript interface, which asserts nothing at runtime, and checked only for truthiness and a length match. Reproduced by execution, one stub body per case, all at **exit 0** before this change: `{"translations":"notarray"}` printed the literal text **`undefined`** — a string has a truthy `.length`, so the guard and the length comparison both passed and `[0]` yielded nothing, meaning `deepl translate ... > out.txt` wrote the word "undefined" while reporting success; `{"translations":[{"text":12345}]}` printed `12345`; `{"translations":[{"text":{"a":1,"b":[2,3]}}]}` printed `{ a: 1, b: [ 2, 3 ] }`; `{"translations":{"0":{"text":"x"}}}` printed `x`. A body of `null` crashed on a raw `Cannot read properties of null` at exit 1. All six now exit 5 naming the field and the offending type — `Unexpected API response: "translations[0].text" must be a string, got number.` — and the `--output` path can no longer reach `fs.writeFile` with a non-string and die on `ERR_INVALID_ARG_TYPE`. The checks live in a new `src/api/response-shape.ts` following the contract `sanitizePullKeysResponse` already sets for the TMS: reject rather than coerce, and name the type so the endpoint is diagnosable. **The finding scoped this to the translation client; `write`/`correct` had the identical hole** — `mapImprovements` did the same truthiness-and-length check and passed `improvement.text` through unvalidated — so both are fixed together as one defect class, and the response bodies are now requested as `unknown` rather than as an interface that was never enforced. Three deliberate distinctions. **An absent or null `translations`/`improvements` field is not a type error**: it means nothing came back, which the callers' own messages already describe better ("No translation returned from DeepL API"), so it becomes an empty array and falls through to their existing length check — this is why three pre-existing tests that assert those messages still pass unchanged. **In a batch, every element is validated before any is used**, so a bad element late in the array cannot leave earlier translations already written. And the optional metadata fields — `billed_characters`, `detected_source_language`, `model_type_used` — are **dropped when wrong-typed rather than rejecting the response**, because they are not the translation: a bogus `billed_characters` must not be summed into a cost report or written to a lockfile, but it is no reason to discard a translation that has already been billed.
 
 - **cli**: **pointing the CLI at a non-DeepL endpoint is now announced, so the API key no longer travels to an unexpected host in silence.** `isStandardDeepLUrl()` existed solely to detect this case and was consumed by nothing — `grep` returned the definition and one internal precedence test, no warning path. Reproduced against a loopback stub with `DEEPL_API_KEY=SECRET-KEY-1234`: **the key arrived as `authorization: DeepL-Auth-Key SECRET-KEY-1234` and the run printed only the translation, at exit 0.** Adding `-v` did not help — the verbose line was `[verbose] HTTP POST /v2/translate completed in 12ms (status 200)`, method and path only, never the host. The worst of the three cases needed no flag at all: a `config.json` holding `api.baseUrl` redirected every request with nothing on any channel to say so, and the CLI never reported which config file it had loaded either. Now the resolved endpoint is checked and, when it is neither `api.deepl.com` nor `api-free.deepl.com`, an unconditional `Logger.warn` names the **origin** the key is going to and where the redirect came from: `set by --api-url`, or `set by api.baseUrl in /path/to/config.json` — the real path, resolved from the several locations searched and any `-c` override, which is what makes a substituted config visible. Only the origin is rendered, never the path or query, because those are chosen by whatever did the redirecting and echoing them would put attacker-picked text in front of the user; it is terminal-sanitized on the way out. Four scoping decisions. The notice is **not** gated behind `--verbose`, since a user who does not already know their key is being redirected has no reason to pass it; `--quiet` still suppresses it, matching every other warning. It goes to **stderr**, so `deepl translate ... > out.txt` and `$(deepl translate ...)` keep capturing only translation output. **Loopback is not exempt**, consistent with the TMS destination-trust gate — a co-tenant process on `127.0.0.1` receives the key exactly as a remote host does, and that is the shape the reproduction used. And it fires **once per run rather than once per client**, because a single command may build several (translation, usage, glossary) from the same endpoint and the notice is about the destination, not the client. Regional endpoints such as `api-jp.deepl.com` are included: they are not one of the two hosts the key is issued for. Separately, the verbose request line now names the resolved origin (`[verbose] HTTP POST http://127.0.0.1:56295/v2/translate completed in 12ms (status 200)`), and `ConfigService` gained a `configFilePath` accessor so any message about a setting can name the file that supplied it.
diff --git a/README.md b/README.md
index 5a7206c5..1dcb3e8c 100644
--- a/README.md
+++ b/README.md
@@ -1676,6 +1676,7 @@ See [docs/API.md#environment-variables](./docs/API.md#environment-variables) for
 ## 🔒 Security & Privacy
 
 - **API key storage** - Keys are stored as **plaintext** in `config.json` with `0600` file permissions (owner read/write only). For CI/CD or shared environments, prefer the `DEEPL_API_KEY` environment variable instead. Avoid committing `config.json` to version control — it is gitignored by default.
+- **Credential redaction in diagnostics** - Errors, warnings and `--verbose` output are scrubbed before they reach stderr: auth headers and `token=`/`api_key=` query parameters are replaced by `[REDACTED]`, as is the literal value of whichever credential the run is using, whether it came from the environment, `config.json`, or `.deepl-sync.yaml`. A credential value shorter than 8 characters is matched only by the header and query-parameter patterns, not by its literal value — a substring that short corrupts ordinary words in the diagnostics without protecting anything real. `deepl translate` output on stdout is never rewritten.
 - **Local caching** - All cached data stored locally in SQLite, never shared
 - **No telemetry** - Zero usage tracking or data collection
 - **Environment variable support** - Use `DEEPL_API_KEY` environment variable for CI/CD
diff --git a/src/api/http-client.ts b/src/api/http-client.ts
index d75db2a0..0b1d1e58 100644
--- a/src/api/http-client.ts
+++ b/src/api/http-client.ts
@@ -263,6 +263,11 @@ export class HttpClient {
       throw new AuthError('API key is required');
     }
 
+    // The key is attached to every request below, so this is the one place that
+    // sees whichever key won precedence — including a config-file key, which
+    // the redactor cannot discover from the environment.
+    Logger.registerSecret(apiKey);
+
     const baseURL = resolveClientBaseUrl(options);
     this.baseOrigin = (() => {
       try {
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index 9a65cd36..9eeb36bb 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -201,6 +201,11 @@ export class TmsClient {
   private readonly retry: Required<TmsClientRetryOptions>;
 
   constructor(private readonly options: TmsClientOptions) {
+    // Either credential may have come from .deepl-sync.yaml rather than the
+    // environment, where the redactor cannot find it.
+    Logger.registerSecret(options.apiKey);
+    Logger.registerSecret(options.token);
+
     this.timeoutMs = options.timeoutMs ?? DEFAULT_TMS_TIMEOUT_MS;
     this.retry = {
       maxAttempts: options.retry?.maxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS,
diff --git a/src/utils/logger.ts b/src/utils/logger.ts
index 7d44f468..7587dac3 100644
--- a/src/utils/logger.ts
+++ b/src/utils/logger.ts
@@ -5,9 +5,36 @@
 
 import { neutralizeTerminalControls } from './control-chars.js';
 
+/**
+ * Shortest credential value redacted by literal substring match. A DeepL key is
+ * UUID-shaped and TMS credentials are longer still, so nothing real is below
+ * this; anything that is would corrupt ordinary prose instead, because the
+ * match has no token boundary — a one-character key turns every "Check" in
+ * every diagnostic into "Chec[REDACTED]".
+ */
+const MIN_REDACTABLE_SECRET_LENGTH = 8;
+
 class LoggerClass {
   private quiet: boolean = false;
   private verboseMode: boolean = false;
+  private readonly registeredSecrets = new Set<string>();
+
+  /**
+   * Register a credential the redactor cannot find in the environment: an API
+   * key read from config.json, or TMS credentials inlined in .deepl-sync.yaml.
+   * A config-file key takes precedence over DEEPL_API_KEY, so without this the
+   * credential actually on the wire is the one value the redactor cannot see.
+   */
+  registerSecret(value: string | undefined): void {
+    if (value) this.registeredSecrets.add(value);
+  }
+
+  /**
+   * Forget every credential passed to `registerSecret`.
+   */
+  clearSecrets(): void {
+    this.registeredSecrets.clear();
+  }
 
   /**
    * Enable or disable quiet mode
@@ -48,10 +75,9 @@ class LoggerClass {
   }
 
   /**
-   * Recursively apply `transform` to strings inside plain objects, arrays and
-   * Errors so a dumped axios error (config.headers.Authorization etc.) cannot
-   * leak credentials via util.inspect. Other object types pass through
-   * unchanged.
+   * Recursively apply `transform` to every string reachable from `value` so a
+   * dumped axios error (config.headers.Authorization etc.) cannot leak
+   * credentials via util.inspect.
    */
   private mapStrings(
     value: unknown,
@@ -67,6 +93,34 @@ class LoggerClass {
       return value.map((item) => this.mapStrings(item, seen, transform));
     }
 
+    if (value instanceof Map) {
+      return new Map(
+        Array.from(value, ([key, entry]) => [
+          this.mapStrings(key, seen, transform),
+          this.mapStrings(entry, seen, transform),
+        ])
+      );
+    }
+
+    if (value instanceof Set) {
+      return new Set(
+        Array.from(value, (entry) => this.mapStrings(entry, seen, transform))
+      );
+    }
+
+    // Values whose payload does not live in string-keyed own properties: a
+    // rebuilt copy would either lose it (Date, RegExp) or enumerate every byte
+    // (Buffer and the other views over an ArrayBuffer). None of them renders a
+    // credential as readable text, so they are returned as they are.
+    if (
+      value instanceof Date ||
+      value instanceof RegExp ||
+      value instanceof ArrayBuffer ||
+      ArrayBuffer.isView(value)
+    ) {
+      return value;
+    }
+
     if (value instanceof Error) {
       const copy = Object.create(
         Object.getPrototypeOf(value) as object
@@ -90,16 +144,43 @@ class LoggerClass {
       return copy;
     }
 
-    const proto: unknown = Object.getPrototypeOf(value);
-    if (proto === Object.prototype || proto === null) {
-      const result: Record<string, unknown> = {};
-      for (const [key, entry] of Object.entries(value)) {
-        result[key] = this.mapStrings(entry, seen, transform);
-      }
-      return result;
+    // Every remaining object — a plain one, an axios AxiosHeaders, a
+    // ClientRequest — is rebuilt property by property on its own prototype, so
+    // util.inspect still names the class but never sees the live original.
+    // Handing a redactor's caller the untouched instance is the wrong default.
+    // Properties are defined rather than assigned so a key named `__proto__`
+    // becomes an own property of the copy instead of reaching the setter.
+    const copy = Object.create(
+      Object.getPrototypeOf(value) as object | null
+    ) as object;
+    for (const [key, entry] of Object.entries(value)) {
+      Object.defineProperty(copy, key, {
+        value: this.mapStrings(entry, seen, transform),
+        writable: true,
+        configurable: true,
+        enumerable: true,
+      });
     }
+    return copy;
+  }
 
-    return value;
+  /**
+   * Credential values long enough to redact by literal match — the environment
+   * ones plus whatever the CLI registered from a config file. The header and
+   * query-parameter patterns above cover the shapes a credential is normally
+   * printed in; this is the backstop for a key echoed somewhere they do not
+   * reach, such as a server's own error message.
+   */
+  private literalSecrets(): string[] {
+    return [
+      process.env['DEEPL_API_KEY'],
+      process.env['TMS_API_KEY'],
+      process.env['TMS_TOKEN'],
+      ...this.registeredSecrets,
+    ].filter(
+      (secret): secret is string =>
+        secret !== undefined && secret.length >= MIN_REDACTABLE_SECRET_LENGTH
+    );
   }
 
   private sanitizeString(value: string): string {
@@ -125,17 +206,8 @@ class LoggerClass {
       /X-Auth-Token:\s+\S+/gi,
       'X-Auth-Token: [REDACTED]'
     );
-    const apiKey = process.env['DEEPL_API_KEY'];
-    if (apiKey) {
-      result = result.replaceAll(apiKey, '[REDACTED]');
-    }
-    const tmsApiKey = process.env['TMS_API_KEY'];
-    if (tmsApiKey) {
-      result = result.replaceAll(tmsApiKey, '[REDACTED]');
-    }
-    const tmsToken = process.env['TMS_TOKEN'];
-    if (tmsToken) {
-      result = result.replaceAll(tmsToken, '[REDACTED]');
+    for (const secret of this.literalSecrets()) {
+      result = result.replaceAll(secret, '[REDACTED]');
     }
     // Everything routed here goes to stderr, which is diagnostics rather than
     // data: no caller consumes it as bytes, and a non-TTY stderr is still
diff --git a/tests/e2e/cli-credential-redaction.e2e.test.ts b/tests/e2e/cli-credential-redaction.e2e.test.ts
new file mode 100644
index 00000000..dffb8171
--- /dev/null
+++ b/tests/e2e/cli-credential-redaction.e2e.test.ts
@@ -0,0 +1,128 @@
+/**
+ * E2E tests for credential redaction in CLI diagnostics.
+ *
+ * These drive the built CLI binary as a subprocess because the credential the
+ * redactor has to cover is the one the CLI resolved for itself: a config-file
+ * key wins over DEEPL_API_KEY, so only a real run proves it is registered.
+ * The mock server echoes the bare key value rather than the whole
+ * `Authorization` header, so the header pattern cannot mask a missing
+ * registration.
+ */
+
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as http from 'http';
+import type { AddressInfo } from 'net';
+import * as path from 'path';
+import { createTestConfigDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const CONFIG_KEY = 'CONFIG-FILE-KEY-WINS:fx';
+const ENV_KEY = 'ENV-KEY-LOSES-TO-CONFIG:fx';
+
+interface CLIResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+function runCLI(
+  args: string[],
+  env: Record<string, string | undefined>
+): Promise<CLIResult> {
+  return new Promise((resolve) => {
+    const child = spawn('node', [CLI_PATH, ...args], {
+      env: { ...process.env, NO_COLOR: '1', ...env },
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk: Buffer) => (stdout += chunk.toString()));
+    child.stderr.on('data', (chunk: Buffer) => (stderr += chunk.toString()));
+    child.on('close', (status) => resolve({ status, stdout, stderr }));
+  });
+}
+
+async function reserveClosedPort(): Promise<number> {
+  const probe = http.createServer();
+  await new Promise<void>((resolve) => probe.listen(0, '127.0.0.1', resolve));
+  const { port } = probe.address() as AddressInfo;
+  await new Promise<void>((resolve) => probe.close(() => resolve()));
+  return port;
+}
+
+describe('CLI credential redaction E2E', () => {
+  const testConfig = createTestConfigDir('e2e-credential-redaction');
+
+  afterAll(() => {
+    testConfig.cleanup();
+  });
+
+  describe('a config-file key echoed back by the server', () => {
+    let server: http.Server;
+    let baseUrl: string;
+
+    beforeAll(async () => {
+      server = http.createServer((req, res) => {
+        const header = req.headers['authorization'] ?? '';
+        const bareKey = header.replace(/^DeepL-Auth-Key\s+/i, '');
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ message: `credential rejected: ${bareKey}` }));
+      });
+      await new Promise<void>((resolve) =>
+        server.listen(0, '127.0.0.1', resolve)
+      );
+      const { port } = server.address() as AddressInfo;
+      baseUrl = `http://127.0.0.1:${port}`;
+      fs.writeFileSync(
+        path.join(testConfig.path, 'config.json'),
+        JSON.stringify({
+          auth: { apiKey: CONFIG_KEY },
+          api: { baseUrl },
+        })
+      );
+    });
+
+    afterAll(async () => {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    });
+
+    it('should redact the config-file key from the error message', async () => {
+      const result = await runCLI(
+        ['translate', 'hello', '--to', 'de', '--no-cache'],
+        { DEEPL_CONFIG_DIR: testConfig.path, DEEPL_API_KEY: ENV_KEY }
+      );
+
+      expect(result.stderr).toContain('credential rejected: [REDACTED]');
+      expect(result.stderr).not.toContain(CONFIG_KEY);
+      expect(result.status).toBe(6);
+    });
+  });
+
+  describe('a one-character DEEPL_API_KEY', () => {
+    let configDir: string;
+
+    beforeAll(async () => {
+      const closedPort = await reserveClosedPort();
+      configDir = path.join(testConfig.path, 'short-key');
+      fs.mkdirSync(configDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(configDir, 'config.json'),
+        JSON.stringify({ api: { baseUrl: `http://127.0.0.1:${closedPort}` } })
+      );
+    });
+
+    it('should leave ordinary words in the diagnostics intact', async () => {
+      const result = await runCLI(
+        ['translate', 'hello', '--to', 'de', '--no-cache'],
+        { DEEPL_CONFIG_DIR: configDir, DEEPL_API_KEY: 'k' }
+      );
+
+      expect(result.stderr).toContain(
+        'Check your internet connection and proxy settings'
+      );
+      expect(result.stderr).toContain('Network error');
+      expect(result.stderr).not.toContain('[REDACTED]');
+      expect(result.status).toBe(5);
+    });
+  });
+});
diff --git a/tests/unit/http-client.test.ts b/tests/unit/http-client.test.ts
index bd37ce03..66f0cc93 100644
--- a/tests/unit/http-client.test.ts
+++ b/tests/unit/http-client.test.ts
@@ -1,6 +1,7 @@
 import nock from 'nock';
 import { HttpClient } from '../../src/api/http-client';
 import { NetworkError } from '../../src/utils/errors';
+import { Logger } from '../../src/utils/logger';
 
 class TestHttpClient extends HttpClient {
   async get<T>(path: string, params?: Record<string, unknown>): Promise<T> {
@@ -373,4 +374,26 @@ describe('HttpClient', () => {
       expect(proxyFor('https://api.deepl.com')).toBeUndefined();
     });
   });
+
+  describe('credential registration', () => {
+    let errorSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      Logger.clearSecrets();
+      errorSpy = jest.spyOn(console, 'error').mockImplementation();
+    });
+
+    afterEach(() => {
+      errorSpy.mockRestore();
+      Logger.clearSecrets();
+    });
+
+    it('should register the key it attaches so diagnostics redact it', () => {
+      new TestHttpClient('CONFIG-FILE-KEY-WINS:fx');
+
+      Logger.error('API error: CONFIG-FILE-KEY-WINS:fx');
+
+      expect(errorSpy).toHaveBeenCalledWith('API error: [REDACTED]');
+    });
+  });
 });
diff --git a/tests/unit/logger.test.ts b/tests/unit/logger.test.ts
index a6eef4ce..6d2e79d6 100644
--- a/tests/unit/logger.test.ts
+++ b/tests/unit/logger.test.ts
@@ -21,6 +21,7 @@ describe('Logger', () => {
     // Reset logger state
     Logger.setQuiet(false);
     Logger.setVerbose(false);
+    Logger.clearSecrets();
   });
 
   describe('setQuiet()', () => {
@@ -638,14 +639,68 @@ describe('Logger', () => {
       );
     });
 
-    it('should pass non-plain objects through unchanged', () => {
+    it('should redact inside a class instance while keeping its class', () => {
       class Custom {
         value = 'https://host?token=class-secret';
       }
       const instance = new Custom();
-      const map = new Map([['k', 'v']]);
-      Logger.error(instance, map);
-      expect(consoleErrorSpy).toHaveBeenCalledWith(instance, map);
+      Logger.error(instance);
+      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Custom;
+      expect(logged).toBeInstanceOf(Custom);
+      expect(logged.value).toBe('https://host?token=[REDACTED]');
+      // The caller's instance is not mutated.
+      expect(instance.value).toBe('https://host?token=class-secret');
+    });
+
+    it('should redact an auth header held on a class instance inside an Error', () => {
+      class AxiosHeaders {
+        Authorization = 'DeepL-Auth-Key SUPER-SECRET-KEY-FROM-CONFIG';
+      }
+      const err = new Error('boom') as Error & { config?: unknown };
+      err.config = { headers: new AxiosHeaders() };
+      Logger.error(err);
+      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Error & {
+        config?: { headers?: { Authorization?: string } };
+      };
+      expect(logged.config?.headers?.Authorization).toBe(
+        'DeepL-Auth-Key [REDACTED]'
+      );
+    });
+
+    it('should redact Map keys and values while keeping it a Map', () => {
+      const map = new Map([
+        ['url', 'https://host?token=map-secret'],
+        ['https://host?api_key=key-secret', 'value'],
+      ]);
+      Logger.error(map);
+      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Map<string, string>;
+      expect(logged).toBeInstanceOf(Map);
+      expect(logged.get('url')).toBe('https://host?token=[REDACTED]');
+      expect(logged.get('https://host?api_key=[REDACTED]')).toBe('value');
+    });
+
+    it('should redact Set members while keeping it a Set', () => {
+      Logger.error(new Set(['https://host?token=set-secret', 'safe']));
+      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Set<string>;
+      expect(logged).toBeInstanceOf(Set);
+      expect([...logged]).toEqual(['https://host?token=[REDACTED]', 'safe']);
+    });
+
+    it.each([
+      ['a Date', new Date(0)],
+      ['a RegExp', /token=secret/],
+      ['an ArrayBuffer', new ArrayBuffer(8)],
+    ])('should pass %s through unchanged', (_label, value) => {
+      Logger.error(value);
+      expect(consoleErrorSpy).toHaveBeenCalledWith(value);
+    });
+
+    it('should pass a Buffer through without enumerating its bytes', () => {
+      const buffer = Buffer.from('DeepL-Auth-Key not-text-in-inspect');
+      Logger.error(buffer);
+      const logged = consoleErrorSpy.mock.calls[0]?.[0] as Buffer;
+      expect(Buffer.isBuffer(logged)).toBe(true);
+      expect(logged).toBe(buffer);
     });
 
     it('should redact values in null-prototype objects', () => {
@@ -660,6 +715,107 @@ describe('Logger', () => {
     });
   });
 
+  describe('registerSecret()', () => {
+    it('should redact a registered credential the environment does not hold', () => {
+      Logger.registerSecret('CONFIG-FILE-KEY-WINS:fx');
+      Logger.error('rejected credential CONFIG-FILE-KEY-WINS:fx');
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'rejected credential [REDACTED]'
+      );
+    });
+
+    it('should redact a registered credential nested in an object', () => {
+      Logger.registerSecret('CONFIG-FILE-KEY-WINS:fx');
+      Logger.error({ body: { message: 'CONFIG-FILE-KEY-WINS:fx' } });
+      expect(consoleErrorSpy).toHaveBeenCalledWith({
+        body: { message: '[REDACTED]' },
+      });
+    });
+
+    it('should redact every registered credential', () => {
+      Logger.registerSecret('first-registered-key');
+      Logger.registerSecret('second-registered-key');
+      Logger.error('first-registered-key and second-registered-key');
+      expect(consoleErrorSpy).toHaveBeenCalledWith('[REDACTED] and [REDACTED]');
+    });
+
+    it('should ignore an undefined credential', () => {
+      Logger.registerSecret(undefined);
+      Logger.error('nothing to redact here');
+      expect(consoleErrorSpy).toHaveBeenCalledWith('nothing to redact here');
+    });
+
+    it('should stop redacting a credential after clearSecrets()', () => {
+      Logger.registerSecret('CONFIG-FILE-KEY-WINS:fx');
+      Logger.clearSecrets();
+      Logger.error('CONFIG-FILE-KEY-WINS:fx');
+      expect(consoleErrorSpy).toHaveBeenCalledWith('CONFIG-FILE-KEY-WINS:fx');
+    });
+  });
+
+  describe('minimum length for literal credential redaction', () => {
+    const withEnv = (name: string, value: string, run: () => void): void => {
+      const original = process.env[name];
+      process.env[name] = value;
+      try {
+        run();
+      } finally {
+        if (original === undefined) {
+          delete process.env[name];
+        } else {
+          process.env[name] = original;
+        }
+      }
+    };
+
+    it('should leave ordinary words intact when DEEPL_API_KEY is one character', () => {
+      withEnv('DEEPL_API_KEY', 'k', () => {
+        Logger.error('Check your internet connection and proxy settings');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+          'Check your internet connection and proxy settings'
+        );
+      });
+    });
+
+    it('should not redact a DEEPL_API_KEY shorter than eight characters', () => {
+      withEnv('DEEPL_API_KEY', 'env-key', () => {
+        Logger.error('Using key env-key for request');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+          'Using key env-key for request'
+        );
+      });
+    });
+
+    it('should redact a DEEPL_API_KEY of exactly eight characters', () => {
+      withEnv('DEEPL_API_KEY', 'env-keys', () => {
+        Logger.error('Using key env-keys for request');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+          'Using key [REDACTED] for request'
+        );
+      });
+    });
+
+    it('should not redact a TMS_API_KEY shorter than eight characters', () => {
+      withEnv('TMS_API_KEY', 'tms', () => {
+        Logger.error('tms transport failed');
+        expect(consoleErrorSpy).toHaveBeenCalledWith('tms transport failed');
+      });
+    });
+
+    it('should not redact a TMS_TOKEN shorter than eight characters', () => {
+      withEnv('TMS_TOKEN', 'tok', () => {
+        Logger.error('token exchange failed');
+        expect(consoleErrorSpy).toHaveBeenCalledWith('token exchange failed');
+      });
+    });
+
+    it('should not redact a registered credential shorter than eight characters', () => {
+      Logger.registerSecret('short');
+      Logger.error('a short message');
+      expect(consoleErrorSpy).toHaveBeenCalledWith('a short message');
+    });
+  });
+
   describe('terminal control sequence handling', () => {
     const OSC_TITLE = '\x1b]0;PWNED\x07';
     let originalIsTTY: boolean | undefined;
diff --git a/tests/unit/sync/tms-client.test.ts b/tests/unit/sync/tms-client.test.ts
index 27195526..17b77dc3 100644
--- a/tests/unit/sync/tms-client.test.ts
+++ b/tests/unit/sync/tms-client.test.ts
@@ -9,6 +9,7 @@ import type { SyncTmsConfig } from '../../../src/sync/types';
 import type { TmsServerTrustDeps } from '../../../src/sync/tms-server-trust';
 import { ConfigError, ValidationError } from '../../../src/utils/errors';
 import { ExitCode, exitCodeForError } from '../../../src/utils/exit-codes';
+import { Logger } from '../../../src/utils/logger';
 
 const mockFetch = jest.fn();
 (global as unknown as Record<string, unknown>)['fetch'] = mockFetch;
@@ -951,3 +952,41 @@ describe('TmsClient.pullKeys response validation', () => {
     expect(Object.keys(result)).toHaveLength(50000);
   });
 });
+
+describe('TmsClient credential registration', () => {
+  let errorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    Logger.clearSecrets();
+    errorSpy = jest.spyOn(console, 'error').mockImplementation();
+  });
+
+  afterEach(() => {
+    errorSpy.mockRestore();
+    Logger.clearSecrets();
+  });
+
+  it('should register a yaml-held api_key so diagnostics redact it', () => {
+    new TmsClient({
+      serverUrl: 'https://tms.example.com',
+      projectId: 'p',
+      apiKey: 'YAML-HELD-TMS-API-KEY',
+    });
+
+    Logger.error('server rejected YAML-HELD-TMS-API-KEY');
+
+    expect(errorSpy).toHaveBeenCalledWith('server rejected [REDACTED]');
+  });
+
+  it('should register a yaml-held token so diagnostics redact it', () => {
+    new TmsClient({
+      serverUrl: 'https://tms.example.com',
+      projectId: 'p',
+      token: 'YAML-HELD-TMS-TOKEN',
+    });
+
+    Logger.error('server rejected YAML-HELD-TMS-TOKEN');
+
+    expect(errorSpy).toHaveBeenCalledWith('server rejected [REDACTED]');
+  });
+});

From bc610bd182e2e6cb3b81e65109eb6f999c496f4a Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 19:54:37 +0200
Subject: [PATCH 141/256] fix(config): enforce the private mode on the key file
 rather than assume it

config.json is created 0600 and its directory 0700, and neither was ever
checked again. load() read the file with no stat, no repair and no
warning, so a config.json restored from a tar or dotfiles backup, copied
by rsync, or written by hand kept whatever mode it arrived with while
README promised 0600.

Measured: a 0777 config directory was still 0777 after `auth set-key`,
and a config.json chmod'd to 0644 was read by `config list` at exit 0 and
left at 0644.

A group- or world-reachable config file is now tightened back to 0600 on
load, and the run says what it found:

  Warning: <path> was mode 0644, which other users on this machine can
  read. Tightened to 0600. Your API key may already have been read;
  consider rotating it with: deepl auth set-key

A repair says nothing about who read the file first, which is why it
warns at all. The warning is self-extinguishing: the next run finds 0600.

THE DIRECTORY IS REPORTED, NOT REPAIRED. Probing the obvious fix --
chmod(path.dirname(configPath), 0o700) -- showed it is destructive:
`deepl -c ~/deepl.json` would chmod the user's home directory to 0700,
and this repo's own ConfigService tests, which use
/tmp/deepl-cli-test-config.json, would chmod /tmp. A directory that
already existed was created by someone else for reasons the CLI cannot
know, so it names the mode and the chmod that would close it and changes
nothing.

Only the WRITE bits are reported. A traversable 0755 directory does not
let anyone replace the file inside it, and warning about that on every
run is noise. Sticky directories are exempt: the first implementation
printed `Run: chmod 700 /tmp`, which would break a shared temp
directory, when mode 1777 is exactly what makes it safe -- only a file's
owner can rename or remove it there.

The cache directory gets the same report; cache.db needed nothing, being
chmod 0600 on every open already. Both mkdir sites become unconditional
recursive calls instead of existsSync-then-create, closing the window
where a directory can appear between the two.

Nothing refuses to run over a permission. The mode of the file is not a
reason to reject the settings in it, and load() turns any throw into a
silent fall back to defaults, so the check swallows its own failures.

One existing test changed fixture only: the corrupt-config case wrote its
config.json at the default 0644 and asserted a single console.error, so
it now writes at 0600 -- the mode the CLI itself writes. Its assertions
are unchanged.

Refs cli-8kr2.24
---
 CHANGELOG.md                                  |   2 +
 README.md                                     |   2 +-
 src/storage/cache.ts                          |   9 +-
 src/storage/config.ts                         |  36 ++++-
 src/utils/private-mode.ts                     |  99 ++++++++++++
 tests/unit/cache-service.test.ts              |  21 +++
 tests/unit/config-service.test.ts             |  80 ++++++++++
 tests/unit/private-mode-chmod-failure.test.ts |  47 ++++++
 tests/unit/private-mode.test.ts               | 151 ++++++++++++++++++
 9 files changed, 439 insertions(+), 8 deletions(-)
 create mode 100644 src/utils/private-mode.ts
 create mode 100644 tests/unit/private-mode-chmod-failure.test.ts
 create mode 100644 tests/unit/private-mode.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ee8767d..708e11d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -383,6 +383,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **config**: **the `0600` mode on the file holding the plaintext API key is now enforced on every load, not just asserted at creation.** `config.json` is created `0600` and its directory `0700`, and neither was ever checked again — so a file restored from a tar or dotfiles backup, copied by `rsync`, or written by hand kept whatever mode it arrived with, forever, and `load()` read it with no `stat`, no repair and no warning while README promised `0600`. Reproduced by execution: a `0777` config directory was still `0777` after `auth set-key`, and a `config.json` chmod'd to `0644` was read by `config list` at exit 0 and left `0644`. A group- or world-reachable config file is now tightened back to `0600` on load, and the run says what it found — `… was mode 0644, which other users on this machine can read. Tightened to 0600. Your API key may already have been read; consider rotating it with: deepl auth set-key` — because a repair says nothing about who read the file before it. The warning is self-extinguishing: the next run finds `0600` and is silent. **The directory is deliberately reported rather than repaired**, which is where the filed remediation had to be rejected after probing it: it proposed `chmod(path.dirname(configPath), 0o700)`, and that dirname is not always a directory the CLI owns — `deepl -c ~/deepl.json` would have chmod'd the user's home directory to `0700`, and this repo's own `ConfigService` unit tests would have chmod'd `/tmp`. A directory that already existed was created by someone else for reasons the CLI cannot know, so it names the mode and the `chmod 700` that would close it and changes nothing. Only the **write** bits are reported (`0o022`): a merely traversable `0755` directory does not let anyone replace the file inside it, and warning about it on every run would be noise nobody reads. **Sticky directories are exempt**, which execution also forced — the first implementation told the user to `chmod 700 /tmp`, advice that would break a shared temp directory, when mode `1777` is exactly the arrangement that makes it safe: only a file's owner can rename or remove it. The cache directory gets the same report, and `cache.db` needed nothing, as it is already `chmod 0600` on every open. Both `mkdir` sites are now unconditional recursive calls rather than `existsSync`-then-create, closing the window where a directory could appear between the two. Nothing refuses to run over a permission: the mode of the file is not a reason to reject the settings in it.
+
 - **logger**: **the credential redactor no longer has two holes that between them defeat its own documented invariant.** It promised that "a dumped axios error (config.headers.Authorization etc.) cannot leak credentials via util.inspect", and neither half of that held. **Hole one: any object that was not a plain object, an array or an `Error` was returned live.** Reproduced by execution — an `Error` whose `config.headers` is an `AxiosHeaders` instance printed `headers: AxiosHeaders { Authorization: 'DeepL-Auth-Key SUPER-SECRET-KEY-FROM-CONFIG' }` verbatim, while the sibling plain-object field on the same error was redacted correctly. `Map` and `Set` leaked the same way and worse, since their contents are not own properties at all: `util.inspect` prints `Map(1) { 'Authorization' => 'DeepL-Auth-Key SECRET' }` and the redactor never saw a string. Every object is now **rebuilt property by property on its own prototype**, so `util.inspect` still names the class (`AxiosHeaders { Authorization: 'DeepL-Auth-Key [REDACTED]' }`) but never receives the original instance, and `Map`/`Set` are rebuilt with their keys and members mapped. Returning a foreign instance untouched was the wrong default for a redactor; the fail-closed one is to copy. Four types are still passed through deliberately — `Date`, `RegExp`, `ArrayBuffer` and its views — because their payload is not in string-keyed own properties, so a rebuilt copy would either lose it (`Date {}` instead of the timestamp) or, for a `Buffer`, enumerate one own property per byte; none of them renders a credential as readable text, since `util.inspect` prints a buffer as hex. Properties are `defineProperty`'d rather than assigned, so an own key named `__proto__` — which `JSON.parse` can produce — lands on the copy instead of reaching the prototype setter. **Hole two: the literal-value backstop read only `process.env`, and the config-file key wins precedence over it.** `src/cli/index.ts` resolves `apiKey ?? envKey`, so with a key in `config.json` and a different one in `DEEPL_API_KEY`, the value on the wire is precisely the one the redactor could not see. Reproduced against a loopback stub: the captured header was `authorization: DeepL-Auth-Key CONFIG-FILE-KEY-WINS:fx` while `Logger.error` redacted only `ENV-KEY-LOSES:fx` and printed the config key in full. A new `Logger.registerSecret()` closes it, called from the **`HttpClient` constructor** — the one place that sees whichever key won precedence, because it is where the key is attached to every request — and from the **`TmsClient` constructor**, which covers a `tms.api_key` or `tms.token` inlined in `.deepl-sync.yaml`. That chokepoint was chosen over the CLI's key-resolution seams because five call sites read `auth.apiKey` and a per-seam fix would go stale on the sixth. Stated honestly, hole one was a protection-mechanism failure rather than a live leak: no current call site hands a raw axios error to the logger. Hole two is reachable today — a server that echoes the key back in its own error body surfaces as `API error: <key>`, which is the path the new E2E test drives, asserting on the bare value rather than the whole `Authorization` header so the pre-existing header pattern cannot mask a missing registration. The env-versus-config precedence itself is left alone: registration makes redaction independent of which side wins. One existing unit test was replaced rather than kept — `should pass non-plain objects through unchanged` asserted the hole, down to a `token=class-secret` inside the instance it expected to pass through.
 
 - **api**: **a `/v2/translate` or `/v2/write` response body of the wrong shape is now refused instead of being carried into output.** The bodies were typed by a TypeScript interface, which asserts nothing at runtime, and checked only for truthiness and a length match. Reproduced by execution, one stub body per case, all at **exit 0** before this change: `{"translations":"notarray"}` printed the literal text **`undefined`** — a string has a truthy `.length`, so the guard and the length comparison both passed and `[0]` yielded nothing, meaning `deepl translate ... > out.txt` wrote the word "undefined" while reporting success; `{"translations":[{"text":12345}]}` printed `12345`; `{"translations":[{"text":{"a":1,"b":[2,3]}}]}` printed `{ a: 1, b: [ 2, 3 ] }`; `{"translations":{"0":{"text":"x"}}}` printed `x`. A body of `null` crashed on a raw `Cannot read properties of null` at exit 1. All six now exit 5 naming the field and the offending type — `Unexpected API response: "translations[0].text" must be a string, got number.` — and the `--output` path can no longer reach `fs.writeFile` with a non-string and die on `ERR_INVALID_ARG_TYPE`. The checks live in a new `src/api/response-shape.ts` following the contract `sanitizePullKeysResponse` already sets for the TMS: reject rather than coerce, and name the type so the endpoint is diagnosable. **The finding scoped this to the translation client; `write`/`correct` had the identical hole** — `mapImprovements` did the same truthiness-and-length check and passed `improvement.text` through unvalidated — so both are fixed together as one defect class, and the response bodies are now requested as `unknown` rather than as an interface that was never enforced. Three deliberate distinctions. **An absent or null `translations`/`improvements` field is not a type error**: it means nothing came back, which the callers' own messages already describe better ("No translation returned from DeepL API"), so it becomes an empty array and falls through to their existing length check — this is why three pre-existing tests that assert those messages still pass unchanged. **In a batch, every element is validated before any is used**, so a bad element late in the array cannot leave earlier translations already written. And the optional metadata fields — `billed_characters`, `detected_source_language`, `model_type_used` — are **dropped when wrong-typed rather than rejecting the response**, because they are not the translation: a bogus `billed_characters` must not be summed into a cost report or written to a lockfile, but it is no reason to discard a translation that has already been billed.
diff --git a/README.md b/README.md
index 1dcb3e8c..926f1a9e 100644
--- a/README.md
+++ b/README.md
@@ -1675,7 +1675,7 @@ See [docs/API.md#environment-variables](./docs/API.md#environment-variables) for
 
 ## 🔒 Security & Privacy
 
-- **API key storage** - Keys are stored as **plaintext** in `config.json` with `0600` file permissions (owner read/write only). For CI/CD or shared environments, prefer the `DEEPL_API_KEY` environment variable instead. Avoid committing `config.json` to version control — it is gitignored by default.
+- **API key storage** - Keys are stored as **plaintext** in `config.json` with `0600` file permissions (owner read/write only). That mode is checked on every load, not only when the file is created: a `config.json` that arrives from a backup, an `rsync`, or another tool with a looser mode is tightened back to `0600` and the run says so, since the key may already have been readable. The containing directory is created `0700`; one that already existed and lets other users **write** to it is reported with the `chmod` that would close it, but is not changed — the CLI does not lock other users out of a directory it did not create (a sticky directory such as `/tmp` is exempt, since only a file's owner can replace it there). For CI/CD or shared environments, prefer the `DEEPL_API_KEY` environment variable instead. Avoid committing `config.json` to version control — it is gitignored by default.
 - **Credential redaction in diagnostics** - Errors, warnings and `--verbose` output are scrubbed before they reach stderr: auth headers and `token=`/`api_key=` query parameters are replaced by `[REDACTED]`, as is the literal value of whichever credential the run is using, whether it came from the environment, `config.json`, or `.deepl-sync.yaml`. A credential value shorter than 8 characters is matched only by the header and query-parameter patterns, not by its literal value — a substring that short corrupts ordinary words in the diagnostics without protecting anything real. `deepl translate` output on stdout is never rewritten.
 - **Local caching** - All cached data stored locally in SQLite, never shared
 - **No telemetry** - Zero usage tracking or data collection
diff --git a/src/storage/cache.ts b/src/storage/cache.ts
index 4af0fc97..3f772334 100644
--- a/src/storage/cache.ts
+++ b/src/storage/cache.ts
@@ -10,6 +10,7 @@ import { resolvePaths } from '../utils/paths.js';
 import { ConfigError } from '../utils/errors.js';
 import { Logger } from '../utils/logger.js';
 import { errorMessage } from '../utils/error-message.js';
+import { warnOnWritableDirectory } from '../utils/private-mode.js';
 
 export interface CacheServiceOptions {
   dbPath?: string;
@@ -183,9 +184,11 @@ export class CacheService {
 
   private openDatabase(dbPath: string): void {
     const dir = path.dirname(dbPath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    }
+    // Unconditional: a recursive mkdir does not fail on a directory that already
+    // exists, and the existsSync it replaces left a window for one to appear
+    // between the check and the create.
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    warnOnWritableDirectory(dir);
     this.db = new DatabaseSync(dbPath);
     this.db.exec(`PRAGMA busy_timeout = ${this.busyTimeoutMs}`);
     fs.chmodSync(dbPath, 0o600);
diff --git a/src/storage/config.ts b/src/storage/config.ts
index 86c0d995..dafdbb34 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -21,6 +21,10 @@ import { ConfigError } from '../utils/errors.js';
 import { validateApiUrl } from '../utils/validate-url.js';
 import { Logger } from '../utils/logger.js';
 import { errorMessage } from '../utils/error-message.js';
+import {
+  repairPrivateFileMode,
+  warnOnWritableDirectory,
+} from '../utils/private-mode.js';
 
 const VALID_FORMALITY: readonly Formality[] = [
   'default',
@@ -313,6 +317,7 @@ export class ConfigService {
   private load(): DeepLConfig {
     try {
       if (fs.existsSync(this.configPath)) {
+        this.checkPermissions();
         const data = fs.readFileSync(this.configPath, 'utf-8');
         const loaded = JSON.parse(data) as DeepLConfig;
         const merged = this.mergeWithDefaults(loaded);
@@ -329,6 +334,26 @@ export class ConfigService {
     return ConfigService.getDefaults();
   }
 
+  /**
+   * Checked on every load rather than only when the file is created, because
+   * that is the moment a file arriving from somewhere else — a dotfiles
+   * restore, an rsync, another tool — is first read. Failures are swallowed:
+   * the permissions of the file are not a reason to refuse the settings in it,
+   * and `load` turns any throw into a fall back to defaults.
+   */
+  private checkPermissions(): void {
+    try {
+      repairPrivateFileMode(
+        this.configPath,
+        0o600,
+        'Your API key may already have been read; consider rotating it with: deepl auth set-key'
+      );
+      warnOnWritableDirectory(path.dirname(this.configPath));
+    } catch {
+      /* ignore */
+    }
+  }
+
   /**
    * Validates a config read from disk, and normalizes its language codes in
    * place. A file written before codes were stored lowercase -- or edited by
@@ -368,10 +393,13 @@ export class ConfigService {
     // following whatever is already there.
     const tmpPath = `${this.configPath}.tmp.${process.pid}.${randomBytes(6).toString('hex')}`;
     try {
-      const dir = path.dirname(this.configPath);
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-      }
+      // Unconditional: a recursive mkdir does not fail on a directory that
+      // already exists, and the existsSync it replaces left a window for one to
+      // appear between the check and the create.
+      fs.mkdirSync(path.dirname(this.configPath), {
+        recursive: true,
+        mode: 0o700,
+      });
       fs.writeFileSync(tmpPath, JSON.stringify(this.config, null, 2), {
         encoding: 'utf-8',
         mode: 0o600,
diff --git a/src/utils/private-mode.ts b/src/utils/private-mode.ts
new file mode 100644
index 00000000..3fdcb088
--- /dev/null
+++ b/src/utils/private-mode.ts
@@ -0,0 +1,99 @@
+/**
+ * Permission enforcement for the files the CLI keeps private.
+ *
+ * The 0600 file mode and 0700 directory mode are applied when the CLI creates
+ * them and were never checked again, so a config file restored from a backup,
+ * copied by another tool, or written by hand kept whatever mode it arrived
+ * with — and `config.json` holds the API key in plaintext.
+ */
+
+import * as fs from 'fs';
+import { Logger } from './logger.js';
+import { errorMessage } from './error-message.js';
+
+/** Any permission bit that lets a user other than the owner reach the path. */
+const OTHER_USER_ACCESS = 0o077;
+
+/** The bits that let another user add to or replace what is in a directory. */
+const OTHER_USER_WRITE = 0o022;
+
+/**
+ * The restricted-deletion flag. On a sticky directory only the owner of a file
+ * can rename or remove it, which is what makes a shared `/tmp` — mode 1777 by
+ * design — a safe place to keep a private file after all.
+ */
+const STICKY = 0o1000;
+
+const warnedDirectories = new Set<string>();
+
+function modeOf(target: string): number | undefined {
+  try {
+    return fs.statSync(target).mode;
+  } catch {
+    return undefined;
+  }
+}
+
+function octal(mode: number): string {
+  return `0${mode.toString(8).padStart(3, '0')}`;
+}
+
+/**
+ * Restore `mode` on a file the CLI owns and wrote itself, when any other user
+ * can currently reach it. The warning fires once in practice, because the next
+ * run finds the repaired mode — but it fires at all because a repair says
+ * nothing about who read the file before it.
+ */
+export function repairPrivateFileMode(
+  target: string,
+  mode: number,
+  advice?: string
+): void {
+  const stat = modeOf(target);
+  if (stat === undefined) return;
+  const found = stat & 0o777;
+  if ((found & OTHER_USER_ACCESS) === 0) return;
+
+  const suffix = advice === undefined ? '' : ` ${advice}`;
+  try {
+    fs.chmodSync(target, mode);
+    Logger.warn(
+      `Warning: ${target} was mode ${octal(found)}, which other users on this machine can read. Tightened to ${octal(mode)}.${suffix}`
+    );
+  } catch (error) {
+    Logger.warn(
+      `Warning: ${target} is mode ${octal(found)}, which other users on this machine can read, and it could not be tightened to ${octal(mode)}: ${errorMessage(error)}${suffix}`
+    );
+  }
+}
+
+/**
+ * Report a directory another user can write to, naming the command that would
+ * close it. The mode is deliberately left alone: unlike a file the CLI wrote, a
+ * directory that already existed was created by someone else for reasons the
+ * CLI cannot know — `path.dirname` of a `-c` override can be a home directory
+ * or a scratch directory shared with other work — so locking other users out is
+ * the user's call. Only the write bits are reported, because a merely
+ * traversable directory does not let anyone replace the file inside it, and a
+ * sticky one does not either.
+ */
+export function warnOnWritableDirectory(target: string): void {
+  const stat = modeOf(target);
+  if (stat === undefined || (stat & STICKY) !== 0) return;
+  const found = stat & 0o777;
+  if ((found & OTHER_USER_WRITE) === 0) return;
+  if (warnedDirectories.has(target)) return;
+  warnedDirectories.add(target);
+
+  Logger.warn(
+    `Warning: ${target} is mode ${octal(found)}, so other users on this machine can replace the files in it, including the one holding your API key. Run: chmod 700 ${target}`
+  );
+}
+
+/**
+ * Forget which directories have been reported, so a long-lived process — or a
+ * test — sees the warning again rather than only once per process.
+ */
+export function resetWritableDirectoryWarnings(): void {
+  warnedDirectories.clear();
+}
diff --git a/tests/unit/cache-service.test.ts b/tests/unit/cache-service.test.ts
index 6ba12b5a..04c9820f 100644
--- a/tests/unit/cache-service.test.ts
+++ b/tests/unit/cache-service.test.ts
@@ -18,6 +18,7 @@ jest.mock('../../src/utils/logger', () => ({
 
 import { Logger } from '../../src/utils/logger';
 import { CacheService } from '../../src/storage/cache';
+import { resetWritableDirectoryWarnings } from '../../src/utils/private-mode';
 
 describe('CacheService', () => {
   let cacheService: CacheService;
@@ -73,6 +74,26 @@ describe('CacheService', () => {
       expect(stats.enabled).toBe(true);
     });
 
+    it('should warn about a world-writable cache directory', () => {
+      const openDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-cache-ww-'));
+      fs.chmodSync(openDir, 0o777);
+      resetWritableDirectoryWarnings();
+
+      const service = new CacheService({
+        dbPath: path.join(openDir, 'cache.db'),
+      });
+
+      try {
+        const warned = (Logger.warn as jest.Mock).mock.calls
+          .map((call) => call.join(' '))
+          .join('\n');
+        expect(warned).toContain(openDir);
+      } finally {
+        service.close();
+        fs.rmSync(openDir, { recursive: true, force: true });
+      }
+    });
+
     it('should use WAL journal mode', () => {
       const db = (cacheService as any).db;
       const result = db.prepare('PRAGMA journal_mode').get();
diff --git a/tests/unit/config-service.test.ts b/tests/unit/config-service.test.ts
index 84dac620..50c301de 100644
--- a/tests/unit/config-service.test.ts
+++ b/tests/unit/config-service.test.ts
@@ -6,6 +6,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { ConfigService } from '../../src/storage/config';
+import { resetWritableDirectoryWarnings } from '../../src/utils/private-mode';
 
 describe('ConfigService', () => {
   let configService: ConfigService;
@@ -444,6 +445,82 @@ describe('ConfigService', () => {
       fs.rmSync(uniqueDir, { recursive: true, force: true });
     });
 
+    describe('permissions found on disk', () => {
+      let uniqueDir: string;
+      let configPath: string;
+      let consoleErrorSpy: jest.SpyInstance;
+
+      beforeEach(() => {
+        uniqueDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-perm-load-'));
+        fs.chmodSync(uniqueDir, 0o700);
+        configPath = path.join(uniqueDir, 'config.json');
+        consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
+        resetWritableDirectoryWarnings();
+      });
+
+      afterEach(() => {
+        consoleErrorSpy.mockRestore();
+        fs.rmSync(uniqueDir, { recursive: true, force: true });
+      });
+
+      function warnings(): string {
+        return consoleErrorSpy.mock.calls
+          .map((call) => call.join(' '))
+          .join('\n');
+      }
+
+      it('should tighten a group-readable config file on load', () => {
+        fs.writeFileSync(configPath, JSON.stringify({ auth: { apiKey: 'k' } }));
+        fs.chmodSync(configPath, 0o644);
+
+        const service = new ConfigService(configPath);
+
+        expect(fs.statSync(configPath).mode & 0o777).toBe(0o600);
+        expect(service.getValue('auth.apiKey')).toBe('k');
+      });
+
+      it('should say what it found and that the key may have been exposed', () => {
+        fs.writeFileSync(configPath, JSON.stringify({ auth: { apiKey: 'k' } }));
+        fs.chmodSync(configPath, 0o644);
+
+        new ConfigService(configPath);
+
+        expect(warnings()).toContain(configPath);
+        expect(warnings()).toContain('0644');
+        expect(warnings()).toMatch(/rotat/i);
+      });
+
+      it('should say nothing about an already private config file', () => {
+        fs.writeFileSync(configPath, JSON.stringify({ auth: { apiKey: 'k' } }));
+        fs.chmodSync(configPath, 0o600);
+
+        new ConfigService(configPath);
+
+        expect(consoleErrorSpy).not.toHaveBeenCalled();
+      });
+
+      it('should warn about a world-writable config directory without changing it', () => {
+        fs.writeFileSync(configPath, JSON.stringify({}));
+        fs.chmodSync(configPath, 0o600);
+        fs.chmodSync(uniqueDir, 0o777);
+
+        new ConfigService(configPath);
+
+        expect(warnings()).toContain(uniqueDir);
+        expect(fs.statSync(uniqueDir).mode & 0o777).toBe(0o777);
+      });
+
+      it('should say nothing about a traversable config directory', () => {
+        fs.writeFileSync(configPath, JSON.stringify({}));
+        fs.chmodSync(configPath, 0o600);
+        fs.chmodSync(uniqueDir, 0o755);
+
+        new ConfigService(configPath);
+
+        expect(consoleErrorSpy).not.toHaveBeenCalled();
+      });
+    });
+
     describe('temp file safety', () => {
       // The API key is written in plaintext, so the intermediate file must not
       // land on a path anyone else could have prepared in advance.
@@ -515,6 +592,9 @@ describe('ConfigService', () => {
       const badConfigDir = path.dirname(badConfigPath);
       fs.mkdirSync(badConfigDir, { recursive: true });
       fs.writeFileSync(badConfigPath, '{ invalid json !!!');
+      // The mode the CLI itself writes; a permissive fixture would add a
+      // permission warning ahead of the one under test.
+      fs.chmodSync(badConfigPath, 0o600);
 
       // Creating a ConfigService with a corrupt config file triggers load() which should log
       const service = new ConfigService(badConfigPath);
diff --git a/tests/unit/private-mode-chmod-failure.test.ts b/tests/unit/private-mode-chmod-failure.test.ts
new file mode 100644
index 00000000..c34c1403
--- /dev/null
+++ b/tests/unit/private-mode-chmod-failure.test.ts
@@ -0,0 +1,47 @@
+/**
+ * The one branch of repairPrivateFileMode that a real filesystem cannot be
+ * talked into on demand: a mode the process is not allowed to change. It needs
+ * `fs` mocked wholesale, which is why it is not in private-mode.test.ts.
+ */
+
+jest.mock('fs');
+
+import * as fs from 'fs';
+import { repairPrivateFileMode } from '../../src/utils/private-mode';
+
+describe('repairPrivateFileMode() when chmod is refused', () => {
+  let consoleErrorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
+    (fs.statSync as jest.Mock).mockReturnValue({ mode: 0o100644 });
+    (fs.chmodSync as jest.Mock).mockImplementation(() => {
+      throw new Error('EPERM: operation not permitted');
+    });
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('should report the mode it could not repair rather than failing silently', () => {
+    repairPrivateFileMode('/somewhere/config.json', 0o600);
+
+    const warned = consoleErrorSpy.mock.calls
+      .map((call) => call.join(' '))
+      .join('\n');
+    expect(warned).toContain('/somewhere/config.json');
+    expect(warned).toContain('0644');
+    expect(warned).toContain('EPERM');
+  });
+
+  it('should still pass the caller advice on', () => {
+    repairPrivateFileMode('/somewhere/config.json', 0o600, 'Rotate the key.');
+
+    const warned = consoleErrorSpy.mock.calls
+      .map((call) => call.join(' '))
+      .join('\n');
+    expect(warned).toContain('Rotate the key.');
+  });
+});
diff --git a/tests/unit/private-mode.test.ts b/tests/unit/private-mode.test.ts
new file mode 100644
index 00000000..6daf841d
--- /dev/null
+++ b/tests/unit/private-mode.test.ts
@@ -0,0 +1,151 @@
+/**
+ * Tests for the private-mode enforcement helpers.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  repairPrivateFileMode,
+  warnOnWritableDirectory,
+  resetWritableDirectoryWarnings,
+} from '../../src/utils/private-mode';
+
+describe('private mode enforcement', () => {
+  let dir: string;
+  let consoleErrorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-private-mode-'));
+    fs.chmodSync(dir, 0o700);
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
+    resetWritableDirectoryWarnings();
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  function warnings(): string {
+    return consoleErrorSpy.mock.calls.map((call) => call.join(' ')).join('\n');
+  }
+
+  describe('repairPrivateFileMode()', () => {
+    it('should tighten a group- and world-readable file to the required mode', () => {
+      const file = path.join(dir, 'config.json');
+      fs.writeFileSync(file, '{}');
+      fs.chmodSync(file, 0o644);
+
+      repairPrivateFileMode(file, 0o600);
+
+      expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+    });
+
+    it('should name the path and the mode it found', () => {
+      const file = path.join(dir, 'config.json');
+      fs.writeFileSync(file, '{}');
+      fs.chmodSync(file, 0o644);
+
+      repairPrivateFileMode(file, 0o600);
+
+      expect(warnings()).toContain(file);
+      expect(warnings()).toContain('0644');
+      expect(warnings()).toContain('0600');
+    });
+
+    it('should append the caller advice to the warning', () => {
+      const file = path.join(dir, 'config.json');
+      fs.writeFileSync(file, '{}');
+      fs.chmodSync(file, 0o604);
+
+      repairPrivateFileMode(file, 0o600, 'Consider rotating the key.');
+
+      expect(warnings()).toContain('Consider rotating the key.');
+    });
+
+    it('should leave an already private file alone and say nothing', () => {
+      const file = path.join(dir, 'config.json');
+      fs.writeFileSync(file, '{}');
+      fs.chmodSync(file, 0o600);
+
+      repairPrivateFileMode(file, 0o600);
+
+      expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('should do nothing when the path does not exist', () => {
+      repairPrivateFileMode(path.join(dir, 'absent.json'), 0o600);
+
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('warnOnWritableDirectory()', () => {
+    it('should warn about a world-writable directory', () => {
+      fs.chmodSync(dir, 0o777);
+
+      warnOnWritableDirectory(dir);
+
+      expect(warnings()).toContain(dir);
+      expect(warnings()).toContain('0777');
+    });
+
+    it('should warn about a group-writable directory', () => {
+      fs.chmodSync(dir, 0o770);
+
+      warnOnWritableDirectory(dir);
+
+      expect(warnings()).toContain(dir);
+    });
+
+    it('should leave the mode alone rather than tightening it', () => {
+      fs.chmodSync(dir, 0o777);
+
+      warnOnWritableDirectory(dir);
+
+      expect(fs.statSync(dir).mode & 0o777).toBe(0o777);
+    });
+
+    it('should say nothing about a world-writable directory with the sticky bit set', () => {
+      fs.chmodSync(dir, 0o1777);
+
+      warnOnWritableDirectory(dir);
+
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('should say nothing about a merely traversable directory', () => {
+      fs.chmodSync(dir, 0o755);
+
+      warnOnWritableDirectory(dir);
+
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('should say nothing about a private directory', () => {
+      fs.chmodSync(dir, 0o700);
+
+      warnOnWritableDirectory(dir);
+
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+
+    it('should warn once per path however many callers check it', () => {
+      fs.chmodSync(dir, 0o777);
+
+      warnOnWritableDirectory(dir);
+      warnOnWritableDirectory(dir);
+      warnOnWritableDirectory(dir);
+
+      expect(consoleErrorSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should do nothing when the path does not exist', () => {
+      warnOnWritableDirectory(path.join(dir, 'absent'));
+
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+  });
+});

From 4b6799e2e2772041938d8fc5f7eb3b5e2c5eb0ef Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 20:07:18 +0200
Subject: [PATCH 142/256] fix(hooks): confirm a hooks directory the repository
 put outside the tree

resolveHooksDir asks `git rev-parse --git-path hooks`, which faithfully
honours core.hooksPath -- including an absolute path anywhere on the
filesystem -- and install then did an unconditional writeFileSync plus
chmod 0755 with no containment check. core.hooksPath is repository-local
git config, so it travels with a checkout rather than coming from the
person running the command.

Measured: `git config core.hooksPath <outside>` then
`deepl hooks install pre-commit` printed "Installed pre-commit hook",
exited 0, and left an 0755 script in <outside>, with nothing on any
channel to say the write had left the project.

The content written is the CLI's own static template, so this is a
wrong-destination defect rather than an arbitrary-code one. The
destination was still the checkout's choice.

An install whose hooks directory falls outside the working tree now names
the configured value and the resolved directory and asks first.
Declining, or having no terminal to ask on, exits 6 and writes nothing.
`-y, --yes` accepts it and still prints the notice to stderr, so a
scripted install records where the executable went.

The refusal lives in GitHooksService.install, which needs an explicit
allowExternal to proceed. The prompt has to live in the CLI layer because
confirm() is async and install() is not, and putting the default refusal
in the service means the gate cannot be skipped by a caller that forgets
to ask.

Three scoping decisions.

Only the REPOSITORY-LOCAL setting is consulted. A global core.hooksPath
is the user's own machine-wide choice, and reading --local also means a
repository that sets nothing is never reported -- which is what keeps
LINKED WORKTREES AND SUBMODULES quiet. There `--git-path hooks`
legitimately answers with the hooks directory of the repository that owns
them, which is outside this working tree by design, so a naive
containment check would have gated the two setups this project's own
CLAUDE.md tells contributors to use.

Containment is checked THROUGH SYMLINKS, so a relative core.hooksPath
pointing at a symlink that leaves the tree is caught rather than passing
a lexical check.

`uninstall` is left alone. It already refuses to remove anything that is
not a DeepL hook, so the worst it can do at a redirected path is clean up
a file this CLI wrote.

isWithinDirectory and realpathOrAncestor move to src/utils/paths.ts from
the copy that was private to sync-utils.ts, so assertPathWithinRoot and
the hooks check compare paths the same way rather than by two hand-kept
comparisons.

Two existing tests changed CALL SHAPE only: install() gained an options
argument, so the two assertions that pinned its exact arguments now name
it. Their subjects are unchanged.

Refs cli-8kr2.25
---
 CHANGELOG.md                                  |   2 +
 README.md                                     |   1 +
 docs/API.md                                   |   9 ++
 src/cli/commands/hooks.ts                     |  20 +++-
 src/cli/commands/register-hooks.ts            |  37 +++++-
 src/services/git-hooks.ts                     |  94 ++++++++++++++-
 src/sync/sync-utils.ts                        |  39 +------
 src/utils/paths.ts                            |  43 +++++++
 tests/e2e/cli-hooks.e2e.test.ts               |  34 ++++++
 .../git-hooks-resolution.integration.test.ts  | 108 ++++++++++++++++++
 tests/unit/hooks-command.test.ts              |   7 +-
 tests/unit/register-hooks.test.ts             |  49 +++++++-
 12 files changed, 394 insertions(+), 49 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 708e11d5..97822f8c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -383,6 +383,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **hooks**: **`deepl hooks install` no longer writes an executable outside the repository because the repository told it to.** `resolveHooksDir` asks `git rev-parse --git-path hooks`, which faithfully honours `core.hooksPath` — including an absolute path anywhere on the filesystem — and the install then did an unconditional `writeFileSync` plus `chmod 0755` with no containment check. `core.hooksPath` is repository-local git config, so it travels with a checkout rather than coming from the person running the command. Reproduced by execution: `git config core.hooksPath /outside/dir` followed by `deepl hooks install pre-commit` printed `✓ Installed pre-commit hook`, exited `0`, and left an `0755` script in `/outside/dir`, with nothing on any channel to say the write had left the project. The content written is the CLI's own static template, so this was a wrong-destination defect rather than an arbitrary-code one — but the destination was the checkout's choice. An install whose hooks directory falls outside the working tree now names the configured value and the resolved directory and asks first: declining, or having no terminal to ask on, **exits 6 and writes nothing**, and `-y, --yes` accepts it while still printing the notice to stderr so a scripted install records where the executable went. The refusal lives in `GitHooksService.install`, which needs an explicit `allowExternal` to proceed, so the gate cannot be skipped by a caller that forgets to prompt. Three scoping decisions. Only the **repository-local** setting is consulted: a global `core.hooksPath` is the user's own machine-wide choice, and reading `--local` also means a repository that sets nothing is never reported — which is what keeps **linked worktrees and submodules** quiet, since there `--git-path hooks` legitimately answers with the hooks directory of the repository that owns them, outside this working tree by design. Containment is checked **through symlinks**, so a relative `core.hooksPath` pointing at a symlink that leaves the tree is caught rather than passing a lexical check. And **`uninstall` is left alone**: it already refuses to remove anything that is not a DeepL hook, so the worst it can do at a redirected path is clean up a file this CLI wrote. The containment predicate is now `isWithinDirectory` in `src/utils/paths.ts`, extracted from the copy that was private to `sync-utils.ts` along with `realpathOrAncestor`, so `assertPathWithinRoot` and the hooks check compare paths the same way.
+
 - **config**: **the `0600` mode on the file holding the plaintext API key is now enforced on every load, not just asserted at creation.** `config.json` is created `0600` and its directory `0700`, and neither was ever checked again — so a file restored from a tar or dotfiles backup, copied by `rsync`, or written by hand kept whatever mode it arrived with, forever, and `load()` read it with no `stat`, no repair and no warning while README promised `0600`. Reproduced by execution: a `0777` config directory was still `0777` after `auth set-key`, and a `config.json` chmod'd to `0644` was read by `config list` at exit 0 and left `0644`. A group- or world-reachable config file is now tightened back to `0600` on load, and the run says what it found — `… was mode 0644, which other users on this machine can read. Tightened to 0600. Your API key may already have been read; consider rotating it with: deepl auth set-key` — because a repair says nothing about who read the file before it. The warning is self-extinguishing: the next run finds `0600` and is silent. **The directory is deliberately reported rather than repaired**, which is where the filed remediation had to be rejected after probing it: it proposed `chmod(path.dirname(configPath), 0o700)`, and that dirname is not always a directory the CLI owns — `deepl -c ~/deepl.json` would have chmod'd the user's home directory to `0700`, and this repo's own `ConfigService` unit tests would have chmod'd `/tmp`. A directory that already existed was created by someone else for reasons the CLI cannot know, so it names the mode and the `chmod 700` that would close it and changes nothing. Only the **write** bits are reported (`0o022`): a merely traversable `0755` directory does not let anyone replace the file inside it, and warning about it on every run would be noise nobody reads. **Sticky directories are exempt**, which execution also forced — the first implementation told the user to `chmod 700 /tmp`, advice that would break a shared temp directory, when mode `1777` is exactly the arrangement that makes it safe: only a file's owner can rename or remove it. The cache directory gets the same report, and `cache.db` needed nothing, as it is already `chmod 0600` on every open. Both `mkdir` sites are now unconditional recursive calls rather than `existsSync`-then-create, closing the window where a directory could appear between the two. Nothing refuses to run over a permission: the mode of the file is not a reason to reject the settings in it.
 
 - **logger**: **the credential redactor no longer has two holes that between them defeat its own documented invariant.** It promised that "a dumped axios error (config.headers.Authorization etc.) cannot leak credentials via util.inspect", and neither half of that held. **Hole one: any object that was not a plain object, an array or an `Error` was returned live.** Reproduced by execution — an `Error` whose `config.headers` is an `AxiosHeaders` instance printed `headers: AxiosHeaders { Authorization: 'DeepL-Auth-Key SUPER-SECRET-KEY-FROM-CONFIG' }` verbatim, while the sibling plain-object field on the same error was redacted correctly. `Map` and `Set` leaked the same way and worse, since their contents are not own properties at all: `util.inspect` prints `Map(1) { 'Authorization' => 'DeepL-Auth-Key SECRET' }` and the redactor never saw a string. Every object is now **rebuilt property by property on its own prototype**, so `util.inspect` still names the class (`AxiosHeaders { Authorization: 'DeepL-Auth-Key [REDACTED]' }`) but never receives the original instance, and `Map`/`Set` are rebuilt with their keys and members mapped. Returning a foreign instance untouched was the wrong default for a redactor; the fail-closed one is to copy. Four types are still passed through deliberately — `Date`, `RegExp`, `ArrayBuffer` and its views — because their payload is not in string-keyed own properties, so a rebuilt copy would either lose it (`Date {}` instead of the timestamp) or, for a `Buffer`, enumerate one own property per byte; none of them renders a credential as readable text, since `util.inspect` prints a buffer as hex. Properties are `defineProperty`'d rather than assigned, so an own key named `__proto__` — which `JSON.parse` can produce — lands on the copy instead of reaching the prototype setter. **Hole two: the literal-value backstop read only `process.env`, and the config-file key wins precedence over it.** `src/cli/index.ts` resolves `apiKey ?? envKey`, so with a key in `config.json` and a different one in `DEEPL_API_KEY`, the value on the wire is precisely the one the redactor could not see. Reproduced against a loopback stub: the captured header was `authorization: DeepL-Auth-Key CONFIG-FILE-KEY-WINS:fx` while `Logger.error` redacted only `ENV-KEY-LOSES:fx` and printed the config key in full. A new `Logger.registerSecret()` closes it, called from the **`HttpClient` constructor** — the one place that sees whichever key won precedence, because it is where the key is attached to every request — and from the **`TmsClient` constructor**, which covers a `tms.api_key` or `tms.token` inlined in `.deepl-sync.yaml`. That chokepoint was chosen over the CLI's key-resolution seams because five call sites read `auth.apiKey` and a per-seam fix would go stale on the sixth. Stated honestly, hole one was a protection-mechanism failure rather than a live leak: no current call site hands a raw axios error to the logger. Hole two is reachable today — a server that echoes the key back in its own error body surfaces as `API error: <key>`, which is the path the new E2E test drives, asserting on the bare value rather than the whole `Authorization` header so the pre-existing header pattern cannot mask a missing registration. The env-versus-config precedence itself is left alone: registration makes redaction independent of which side wins. One existing unit test was replaced rather than kept — `should pass non-plain objects through unchanged` asserted the hole, down to a `token=class-secret` inside the instance it expected to pass through.
diff --git a/README.md b/README.md
index 926f1a9e..64a06c3e 100644
--- a/README.md
+++ b/README.md
@@ -917,6 +917,7 @@ deepl hooks uninstall pre-commit
 **Features:**
 
 - 🔒 Safe installation with automatic backup of existing hooks
+- 🚧 Confirmation before writing an executable outside the working tree — a repository-local `core.hooksPath` travels with the repository, so an install that would land outside the checkout names the configured value and the resolved directory and asks first (`--yes` to accept, exit `6` and nothing written if declined). Paths inside the working tree, linked worktrees, and submodules are unaffected
 - 🎯 Only validates changed files (pre-commit)
 - ⚡ Lightweight and fast
 - 🔧 Customizable hook scripts
diff --git a/docs/API.md b/docs/API.md
index a6e3635f..4225e4db 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1629,6 +1629,12 @@ Install a git hook.
 
 - `hook-type` - Hook type: `pre-commit`, `pre-push`, `commit-msg`, `post-commit`
 
+**Options:**
+
+- `-y, --yes` - Skip the confirmation prompt when this repository sends hooks outside the working tree
+
+**Hooks directory outside the repository:** the hook is written wherever git reads hooks from, which a repository-local `core.hooksPath` can point anywhere — including an absolute path outside the checkout. Because that setting travels with the repository rather than coming from you, an install that would land outside the working tree names the configured value and the resolved directory and asks first. Declining, or running without a terminal, exits `6` and writes nothing; `--yes` installs there and prints the same notice to stderr. A `core.hooksPath` that stays inside the working tree (`.husky/_`, for example) is not affected, and neither are linked worktrees or submodules, where git legitimately reads hooks from the repository that owns them.
+
 **Examples:**
 
 ```bash
@@ -1636,6 +1642,9 @@ deepl hooks install pre-commit
 deepl hooks install pre-push
 deepl hooks install commit-msg
 deepl hooks install post-commit
+
+# Accept a hooks directory outside the working tree without prompting
+deepl hooks install pre-commit --yes
 ```
 
 ##### `uninstall <hook-type>`
diff --git a/src/cli/commands/hooks.ts b/src/cli/commands/hooks.ts
index b4e43a0c..6974172e 100644
--- a/src/cli/commands/hooks.ts
+++ b/src/cli/commands/hooks.ts
@@ -24,14 +24,30 @@ export class HooksCommand {
   /**
    * Install a git hook
    */
-  install(hookType: HookType): string {
+  /**
+   * The `core.hooksPath` this repository uses to send hooks outside the working
+   * tree, or null. The CLI asks before writing there; `install` refuses on its
+   * own if nobody did.
+   */
+  externalHooksPath(): string | null {
+    return this.gitHooksService?.externalHooksPath ?? null;
+  }
+
+  hooksDirectory(): string | null {
+    return this.gitHooksService?.hooksDirectory ?? null;
+  }
+
+  install(
+    hookType: HookType,
+    options: { allowExternal?: boolean } = {}
+  ): string {
     if (!this.gitHooksService) {
       throw new ValidationError(
         'Not in a git repository. Run this command from within a git repository.'
       );
     }
 
-    const result = this.gitHooksService.install(hookType);
+    const result = this.gitHooksService.install(hookType, options);
 
     const lines = [chalk.green(`✓ Installed ${hookType} hook`)];
     if (result?.hookPath) {
diff --git a/src/cli/commands/register-hooks.ts b/src/cli/commands/register-hooks.ts
index 1f982c93..edbb1ed0 100644
--- a/src/cli/commands/register-hooks.ts
+++ b/src/cli/commands/register-hooks.ts
@@ -19,6 +19,7 @@ export function registerHooks(
 Examples:
   $ deepl hooks install pre-commit
   $ deepl hooks install post-commit
+  $ deepl hooks install pre-commit --yes
   $ deepl hooks uninstall pre-commit
   $ deepl hooks list
   $ deepl hooks path pre-commit
@@ -31,11 +32,43 @@ Examples:
           '<hook-type>',
           'Hook type: pre-commit, pre-push, commit-msg, or post-commit'
         )
-        .action(async (hookType: string) => {
+        .option(
+          '-y, --yes',
+          'Skip the confirmation prompt when this repository sends hooks outside the working tree'
+        )
+        .action(async (hookType: string, options: { yes?: boolean }) => {
           try {
             const { HooksCommand } = await import('./hooks.js');
             const hooksCommand = new HooksCommand();
-            const result = hooksCommand.install(hookType as HookType);
+
+            // A repository-local core.hooksPath is chosen by the checkout, not
+            // by the user running the command, so a target outside the working
+            // tree is confirmed before an executable is written to it.
+            let allowExternal = false;
+            const external = hooksCommand.externalHooksPath();
+            if (external !== null) {
+              const { externalHooksPathMessage } =
+                await import('../../services/git-hooks.js');
+              const notice = externalHooksPathMessage(
+                external,
+                hooksCommand.hooksDirectory() ?? ''
+              );
+              if (options.yes === true) {
+                // Announced rather than asked, so a scripted install still
+                // records where the executable went.
+                Logger.warn(notice);
+                allowExternal = true;
+              } else {
+                const { confirm } = await import('../../utils/confirm.js');
+                allowExternal = await confirm({
+                  message: `${notice}\nInstall the hook there?`,
+                });
+              }
+            }
+
+            const result = hooksCommand.install(hookType as HookType, {
+              allowExternal,
+            });
             Logger.output(result);
           } catch (error) {
             handleError(error);
diff --git a/src/services/git-hooks.ts b/src/services/git-hooks.ts
index 7db9b8a1..7c8b8ed0 100644
--- a/src/services/git-hooks.ts
+++ b/src/services/git-hooks.ts
@@ -8,6 +8,8 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import { execFileSync } from 'child_process';
 import { ValidationError } from '../utils/errors.js';
+import { isWithinDirectory } from '../utils/paths.js';
+import { sanitizeForTerminal } from '../utils/control-chars.js';
 
 export type HookType = 'pre-commit' | 'pre-push' | 'commit-msg' | 'post-commit';
 
@@ -35,15 +37,52 @@ const MARKER_VERSION = 1;
 const LEGACY_MARKER = '# DeepL CLI Hook';
 const MARKER_PATTERN = /^# DeepL CLI Hook v(\d+) \[sha256:([a-f0-9]{64})\]$/m;
 
+interface HooksDirResolution {
+  dir: string;
+  /** The `core.hooksPath` that sent `dir` outside the working tree, or null. */
+  externalRedirect: string | null;
+}
+
+/**
+ * One wording for the refusal and for the prompt that offers to go ahead, so
+ * the two cannot drift. The configured value comes from the checkout, so it is
+ * terminal-sanitized before it is interpolated.
+ */
+export function externalHooksPathMessage(
+  configured: string,
+  hooksDir: string
+): string {
+  return (
+    `This repository's core.hooksPath ("${sanitizeForTerminal(configured)}") puts git hooks outside the working tree, ` +
+    `at ${sanitizeForTerminal(hooksDir)}. Installing writes an executable there, and git runs it on every matching operation in this repository.`
+  );
+}
+
 export class GitHooksService {
   private hooksDir: string;
+  private externalRedirect: string | null;
 
   constructor(gitDir: string) {
     if (!fs.existsSync(gitDir)) {
       throw new ValidationError('Git directory not found: ' + gitDir);
     }
 
-    this.hooksDir = GitHooksService.resolveHooksDir(gitDir);
+    const resolution = GitHooksService.resolveHooksDir(gitDir);
+    this.hooksDir = resolution.dir;
+    this.externalRedirect = resolution.externalRedirect;
+  }
+
+  /**
+   * The repository-local `core.hooksPath` when it sends the hooks directory
+   * outside the working tree, or null. Non-null means installing writes an
+   * executable to a location the checkout chose rather than the user did.
+   */
+  get externalHooksPath(): string | null {
+    return this.externalRedirect;
+  }
+
+  get hooksDirectory(): string {
+    return this.hooksDir;
   }
 
   /**
@@ -53,7 +92,7 @@ export class GitHooksService {
    * and resolves the `gitdir:` pointer used by linked worktrees and submodules,
    * where `<root>/.git` is a file rather than a directory.
    */
-  private static resolveHooksDir(gitDir: string): string {
+  private static resolveHooksDir(gitDir: string): HooksDirResolution {
     const workDir = path.dirname(gitDir);
 
     try {
@@ -67,7 +106,11 @@ export class GitHooksService {
         }
       ).trim();
       if (resolved) {
-        return path.resolve(workDir, resolved);
+        const dir = path.resolve(workDir, resolved);
+        return {
+          dir,
+          externalRedirect: GitHooksService.externalRedirectFor(workDir, dir),
+        };
       }
     } catch {
       // git unavailable, or workDir is not a working tree — fall back below.
@@ -80,14 +123,55 @@ export class GitHooksService {
       );
     }
 
-    return path.join(gitDir, 'hooks');
+    return { dir: path.join(gitDir, 'hooks'), externalRedirect: null };
+  }
+
+  /**
+   * The configured `core.hooksPath` when the directory it resolves to lies
+   * outside the working tree.
+   *
+   * Only the repository-local setting is consulted, for two reasons. It is the
+   * one an untrusted checkout can carry, which is the case worth confirming —
+   * a global setting is the user's own machine-wide choice. And a repository
+   * that sets nothing is never reported, which is what keeps linked worktrees
+   * and submodules quiet: there `--git-path hooks` legitimately answers with
+   * the hooks directory of the repository that owns them, which is outside
+   * this working tree by design.
+   */
+  private static externalRedirectFor(
+    workDir: string,
+    hooksDir: string
+  ): string | null {
+    let configured: string;
+    try {
+      configured = execFileSync(
+        'git',
+        ['config', '--local', '--get', 'core.hooksPath'],
+        { cwd: workDir, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }
+      ).trim();
+    } catch {
+      // Exit status 1 means the key is not set.
+      return null;
+    }
+
+    if (!configured) return null;
+    return isWithinDirectory(workDir, hooksDir) ? null : configured;
   }
 
   /**
    * Install a git hook
    */
-  install(hookType: HookType): InstallResult {
+  install(
+    hookType: HookType,
+    options: { allowExternal?: boolean } = {}
+  ): InstallResult {
     this.validateHookType(hookType);
+    if (this.externalRedirect !== null && options.allowExternal !== true) {
+      throw new ValidationError(
+        externalHooksPathMessage(this.externalRedirect, this.hooksDir),
+        'Pass --yes to install there anyway, or drop the redirect with: git config --unset core.hooksPath'
+      );
+    }
 
     const hookPath = this.getHookPath(hookType);
     const hookContent = this.generateHookContent(hookType);
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index c5614821..46d54190 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -1,5 +1,4 @@
 import * as path from 'path';
-import * as fs from 'fs';
 import type {
   ExtractedEntry,
   FormatRegistry,
@@ -8,6 +7,7 @@ import type {
 } from '../formats/index.js';
 import { ValidationError } from '../utils/errors.js';
 import { sanitizeForTerminal } from '../utils/control-chars.js';
+import { isWithinDirectory, realpathOrAncestor } from '../utils/paths.js';
 import { FORBIDDEN_TARGET_SEGMENTS } from './sync-config.js';
 
 export function getParserForBucket(
@@ -103,38 +103,6 @@ function assertNotDashLeading(targetPath: string): string {
   return targetPath;
 }
 
-/**
- * Resolve `absPath` to its symlink-followed real path.
- *
- * `path.resolve` performs lexical normalization only — it does not follow
- * symlinks — so two paths that point at the same inode via different
- * symlink chains (e.g. `/tmp` vs `/private/tmp` on macOS) compare as
- * different strings. `fs.realpathSync` follows symlinks, but only works
- * for paths that already exist on disk; output paths typically don't.
- *
- * This helper handles the output-path case by walking up to the closest
- * existing ancestor, realpath'ing that, and re-appending the unresolved
- * tail. If no ancestor exists (rare — implies a path on a missing volume)
- * it falls back to the lexically-resolved path.
- */
-function realpathOrAncestor(absPath: string): string {
-  let current = path.resolve(absPath);
-  const tail: string[] = [];
-  while (true) {
-    try {
-      const real = fs.realpathSync(current);
-      return tail.length > 0 ? path.join(real, ...tail) : real;
-    } catch {
-      const parent = path.dirname(current);
-      if (parent === current) {
-        return path.resolve(absPath);
-      }
-      tail.unshift(path.basename(current));
-      current = parent;
-    }
-  }
-}
-
 /**
  * Verify that an absolute path is one the sync pipeline may read or write:
  * inside the project root, and outside the repository's own control
@@ -162,10 +130,7 @@ export function assertPathWithinRoot(
 ): void {
   const resolvedRoot = realpathOrAncestor(projectRoot);
   const resolvedPath = realpathOrAncestor(absPath);
-  if (
-    !resolvedPath.startsWith(resolvedRoot + path.sep) &&
-    resolvedPath !== resolvedRoot
-  ) {
+  if (!isWithinDirectory(resolvedRoot, resolvedPath)) {
     throw new ValidationError(
       `Target path escapes project root: ${sanitizeForTerminal(absPath)}`
     );
diff --git a/src/utils/paths.ts b/src/utils/paths.ts
index 2ec95b54..2b150952 100644
--- a/src/utils/paths.ts
+++ b/src/utils/paths.ts
@@ -9,6 +9,49 @@ export interface ResolvedPaths {
   cacheFile: string;
 }
 
+/**
+ * Resolve `absPath` through any symlinks in it, tolerating a path that does not
+ * exist yet.
+ *
+ * Containment checks compare resolved strings, so two paths that reach the same
+ * inode through different symlink chains (`/tmp` vs `/private/tmp` on macOS)
+ * would otherwise compare as different. `fs.realpathSync` only works on paths
+ * that already exist, so this walks up to the closest existing ancestor,
+ * realpaths that, and re-appends the unresolved tail. If nothing on the path
+ * exists — a missing volume — it falls back to the lexically resolved form.
+ */
+export function realpathOrAncestor(absPath: string): string {
+  let current = path.resolve(absPath);
+  const tail: string[] = [];
+  while (true) {
+    try {
+      const real = fs.realpathSync(current);
+      return tail.length > 0 ? path.join(real, ...tail) : real;
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) {
+        return path.resolve(absPath);
+      }
+      tail.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Whether `target` is `root` itself or lies beneath it, with both sides
+ * resolved through their symlinks first — so a symlink inside `root` that
+ * points outside it is not counted as contained.
+ */
+export function isWithinDirectory(root: string, target: string): boolean {
+  const resolvedRoot = realpathOrAncestor(root);
+  const resolvedTarget = realpathOrAncestor(target);
+  return (
+    resolvedTarget === resolvedRoot ||
+    resolvedTarget.startsWith(resolvedRoot + path.sep)
+  );
+}
+
 export function resolvePaths(): ResolvedPaths {
   const home = os.homedir();
 
diff --git a/tests/e2e/cli-hooks.e2e.test.ts b/tests/e2e/cli-hooks.e2e.test.ts
index 896cdf7a..6fb42c00 100644
--- a/tests/e2e/cli-hooks.e2e.test.ts
+++ b/tests/e2e/cli-hooks.e2e.test.ts
@@ -97,4 +97,38 @@ describe('Hooks Command E2E', () => {
     expect(status).toBeGreaterThan(0);
     expect(output).toContain('Invalid hook type');
   });
+
+  describe('a repository that sends hooks outside the working tree', () => {
+    let outside: string;
+
+    beforeEach(() => {
+      outside = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-hooks-out-'));
+      execSync(`git config core.hooksPath ${outside}`, {
+        cwd: tmpDir,
+        stdio: 'ignore',
+      });
+    });
+
+    afterEach(() => {
+      fs.rmSync(outside, { recursive: true, force: true });
+    });
+
+    it('should refuse to install and write nothing without confirmation', () => {
+      const result = runExpectError('hooks install pre-commit');
+
+      expect(result.status).toBe(6);
+      expect(result.output).toContain('core.hooksPath');
+      expect(result.output).toContain(outside);
+      expect(result.output).toContain('git config --unset core.hooksPath');
+      expect(fs.existsSync(path.join(outside, 'pre-commit'))).toBe(false);
+    });
+
+    it('should install there when --yes is passed', () => {
+      const output = run('hooks install pre-commit --yes');
+
+      expect(output).toContain('core.hooksPath');
+      expect(output).toContain('Installed pre-commit hook');
+      expect(fs.existsSync(path.join(outside, 'pre-commit'))).toBe(true);
+    });
+  });
 });
diff --git a/tests/integration/git-hooks-resolution.integration.test.ts b/tests/integration/git-hooks-resolution.integration.test.ts
index 43dfd695..b8295409 100644
--- a/tests/integration/git-hooks-resolution.integration.test.ts
+++ b/tests/integration/git-hooks-resolution.integration.test.ts
@@ -9,6 +9,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { execFileSync } from 'child_process';
 import { GitHooksService } from '../../src/services/git-hooks.js';
+import { ValidationError } from '../../src/utils/errors.js';
 
 function git(cwd: string, ...args: string[]): string {
   return execFileSync('git', args, {
@@ -164,6 +165,113 @@ describe('GitHooksService hooks directory resolution', () => {
     });
   });
 
+  describe('containment of a repo-chosen hooks path', () => {
+    it('should report an absolute core.hooksPath that leaves the working tree', () => {
+      const repo = path.join(tmpRoot, 'escaping-repo');
+      initRepo(repo);
+      const outside = path.join(tmpRoot, 'outside-hooks');
+      fs.mkdirSync(outside, { recursive: true });
+      git(repo, 'config', 'core.hooksPath', outside);
+
+      const service = new GitHooksService(path.join(repo, '.git'));
+
+      expect(service.externalHooksPath).toBe(outside);
+      expect(service.hooksDirectory).toBe(outside);
+    });
+
+    it('should refuse to install into it unless the caller allows it', () => {
+      const repo = path.join(tmpRoot, 'refusing-repo');
+      initRepo(repo);
+      const outside = path.join(tmpRoot, 'outside-refuse');
+      fs.mkdirSync(outside, { recursive: true });
+      git(repo, 'config', 'core.hooksPath', outside);
+
+      const service = new GitHooksService(path.join(repo, '.git'));
+
+      expect(() => service.install('pre-commit')).toThrow(ValidationError);
+      expect(fs.existsSync(path.join(outside, 'pre-commit'))).toBe(false);
+    });
+
+    it('should install into it once the caller allows it', () => {
+      const repo = path.join(tmpRoot, 'allowing-repo');
+      initRepo(repo);
+      const outside = path.join(tmpRoot, 'outside-allow');
+      fs.mkdirSync(outside, { recursive: true });
+      git(repo, 'config', 'core.hooksPath', outside);
+
+      const service = new GitHooksService(path.join(repo, '.git'));
+      service.install('pre-commit', { allowExternal: true });
+
+      expect(fs.existsSync(path.join(outside, 'pre-commit'))).toBe(true);
+    });
+
+    it('should report a relative core.hooksPath that symlinks out of the tree', () => {
+      const repo = path.join(tmpRoot, 'symlink-repo');
+      initRepo(repo);
+      const outside = path.join(tmpRoot, 'outside-symlink');
+      fs.mkdirSync(outside, { recursive: true });
+      fs.symlinkSync(outside, path.join(repo, 'hooks-link'));
+      git(repo, 'config', 'core.hooksPath', 'hooks-link');
+
+      const service = new GitHooksService(path.join(repo, '.git'));
+
+      expect(service.externalHooksPath).toBe('hooks-link');
+      expect(() => service.install('pre-commit')).toThrow(ValidationError);
+    });
+
+    it('should not report a core.hooksPath inside the working tree', () => {
+      const repo = path.join(tmpRoot, 'husky-contained');
+      initRepo(repo);
+      fs.mkdirSync(path.join(repo, '.husky', '_'), { recursive: true });
+      git(repo, 'config', 'core.hooksPath', '.husky/_');
+
+      const service = new GitHooksService(path.join(repo, '.git'));
+
+      expect(service.externalHooksPath).toBeNull();
+      expect(() => service.install('pre-commit')).not.toThrow();
+    });
+
+    it('should not report the shared hooks directory of a linked worktree', () => {
+      const repo = path.join(tmpRoot, 'wt-main');
+      initRepo(repo);
+      git(repo, 'commit', '-q', '--allow-empty', '-m', 'init');
+      const linked = path.join(tmpRoot, 'wt-linked');
+      git(repo, 'worktree', 'add', '-q', linked, '-b', 'contained');
+
+      const service = new GitHooksService(path.join(linked, '.git'));
+
+      expect(service.externalHooksPath).toBeNull();
+      expect(() => service.install('pre-commit')).not.toThrow();
+    });
+
+    it('should not report the git directory of a submodule', () => {
+      const upstream = path.join(tmpRoot, 'sub-upstream');
+      initRepo(upstream);
+      fs.writeFileSync(path.join(upstream, 'README.md'), '# upstream\n');
+      git(upstream, 'add', '.');
+      git(upstream, 'commit', '-q', '-m', 'init');
+
+      const parent = path.join(tmpRoot, 'sub-parent');
+      initRepo(parent);
+      git(parent, 'commit', '-q', '--allow-empty', '-m', 'init');
+      git(
+        parent,
+        '-c',
+        'protocol.file.allow=always',
+        'submodule',
+        'add',
+        '-q',
+        upstream,
+        'sub'
+      );
+
+      const service = new GitHooksService(path.join(parent, 'sub', '.git'));
+
+      expect(service.externalHooksPath).toBeNull();
+      expect(() => service.install('pre-commit')).not.toThrow();
+    });
+  });
+
   describe('backup safety', () => {
     it('should not clobber an existing .backup on repeat install', () => {
       const repo = path.join(tmpRoot, 'backup-repo');
diff --git a/tests/unit/hooks-command.test.ts b/tests/unit/hooks-command.test.ts
index 2340c2c2..d09b8af0 100644
--- a/tests/unit/hooks-command.test.ts
+++ b/tests/unit/hooks-command.test.ts
@@ -81,7 +81,10 @@ describe('HooksCommand', () => {
 
       const result = command.install('pre-commit');
 
-      expect(mockGitHooksService.install).toHaveBeenCalledWith('pre-commit');
+      expect(mockGitHooksService.install).toHaveBeenCalledWith(
+        'pre-commit',
+        {}
+      );
       expect(result).toContain('Installed pre-commit hook');
       expect(result).toContain('/path/to/.git/hooks/pre-commit');
     });
@@ -109,7 +112,7 @@ describe('HooksCommand', () => {
 
       const result = command.install('pre-push');
 
-      expect(mockGitHooksService.install).toHaveBeenCalledWith('pre-push');
+      expect(mockGitHooksService.install).toHaveBeenCalledWith('pre-push', {});
       expect(result).toContain('Installed pre-push hook');
     });
 
diff --git a/tests/unit/register-hooks.test.ts b/tests/unit/register-hooks.test.ts
index 1e1e3902..695ae200 100644
--- a/tests/unit/register-hooks.test.ts
+++ b/tests/unit/register-hooks.test.ts
@@ -8,11 +8,14 @@ jest.mock('../../src/utils/logger', () => ({
     error: jest.fn(),
     info: jest.fn(),
     success: jest.fn(),
+    warn: jest.fn(),
   },
 }));
 
 const mockHooksCommand = {
   install: jest.fn(),
+  externalHooksPath: jest.fn().mockReturnValue(null),
+  hooksDirectory: jest.fn().mockReturnValue('/repo/.git/hooks'),
   uninstall: jest.fn(),
   list: jest.fn(),
   showPath: jest.fn(),
@@ -38,6 +41,8 @@ describe('registerHooks', () => {
     // Re-apply the constructor mock after clearAllMocks
     const { HooksCommand } = require('../../src/cli/commands/hooks');
     HooksCommand.mockImplementation(() => mockHooksCommand);
+    mockHooksCommand.externalHooksPath.mockReturnValue(null);
+    mockHooksCommand.hooksDirectory.mockReturnValue('/repo/.git/hooks');
   });
 
   describe('hooks install', () => {
@@ -53,10 +58,52 @@ describe('registerHooks', () => {
         'pre-commit',
       ]);
 
-      expect(mockHooksCommand.install).toHaveBeenCalledWith('pre-commit');
+      expect(mockHooksCommand.install).toHaveBeenCalledWith('pre-commit', {
+        allowExternal: false,
+      });
       expect(Logger.output).toHaveBeenCalledWith('Installed pre-commit hook');
     });
 
+    it('should announce and allow an external hooks path with --yes', async () => {
+      mockHooksCommand.externalHooksPath.mockReturnValue('/outside/hooks');
+      mockHooksCommand.install.mockReturnValue('Installed pre-commit hook');
+      const { program } = makeProgram();
+
+      await program.parseAsync([
+        'node',
+        'test',
+        'hooks',
+        'install',
+        'pre-commit',
+        '--yes',
+      ]);
+
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('core.hooksPath')
+      );
+      expect(mockHooksCommand.install).toHaveBeenCalledWith('pre-commit', {
+        allowExternal: true,
+      });
+    });
+
+    it('should not allow an external hooks path when it cannot prompt', async () => {
+      mockHooksCommand.externalHooksPath.mockReturnValue('/outside/hooks');
+      mockHooksCommand.install.mockReturnValue('Installed pre-commit hook');
+      const { program } = makeProgram();
+
+      await program.parseAsync([
+        'node',
+        'test',
+        'hooks',
+        'install',
+        'pre-commit',
+      ]);
+
+      expect(mockHooksCommand.install).toHaveBeenCalledWith('pre-commit', {
+        allowExternal: false,
+      });
+    });
+
     it('should call handleError on failure', async () => {
       mockHooksCommand.install.mockImplementation(() => {
         throw new Error('install failed');

From bcb83f690e8bd3a223aa0c15fbe57f0a5a642df3 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 20:40:03 +0200
Subject: [PATCH 143/256] fix(hooks): report what a hook is, not that a marker
 appears in it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`hooks list` reported a boolean per hook, and the test behind it was a
substring match: any file containing the line `# DeepL CLI Hook` anywhere,
in any context, counted as a hook this CLI installed. `verifyIntegrity()`
already parsed the versioned marker, rehashed the body and compared, but
nothing outside its own unit tests called it, so the recorded hash was
never checked on a path a user could reach.

A repository shipping a tracked `.githooks/pre-commit` with a forged marker
and an all-zero hash, wired up with `git config core.hooksPath .githooks`,
was therefore reported as `✓ pre-commit installed`.

`list()` now returns one of four states per hook, derived from
verifyIntegrity: installed, modified, unverified, not-installed. The
legacy marker is anchored to a whole line the way the versioned one always
was — it was only ever emitted that way — so a file that merely quotes it
reads as not installed, and uninstall refuses to delete it while install
backs it up rather than overwriting.

The output says what the hash is worth in both directions. It cannot
establish authorship: it is unkeyed, so anyone who can write the hook can
compute a marker to agree with it. A mismatch also has an innocent reading
the CLI cannot distinguish, since the README invites customizing a hook by
editing it, so the note gives both rather than accusing either way.

`--format json` reports the state strings instead of booleans. A
truthiness test on those passes for every state, so consumers have to gate
on `state === "installed"`.

Refs cli-8kr2.26
---
 CHANGELOG.md                                  |   4 +
 README.md                                     |  14 +-
 docs/API.md                                   |  23 ++-
 src/cli/commands/hooks.ts                     |  60 +++++++-
 src/services/git-hooks.ts                     |  52 ++++++-
 tests/e2e/cli-hooks.e2e.test.ts               |  32 ++++
 .../integration/cli-hooks.integration.test.ts |  31 ++--
 .../git-hooks-resolution.integration.test.ts  |   2 +-
 tests/unit/hooks-command.test.ts              | 106 ++++++++++---
 tests/unit/services/git-hooks.test.ts         | 141 ++++++++++++++++--
 10 files changed, 405 insertions(+), 60 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 97822f8c..975ccabe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **hooks**: **`deepl hooks list --format json` reports a state string per hook instead of a boolean** — `"installed"`, `"modified"`, `"unverified"` or `"not-installed"` (see Security for why a boolean could not tell the truth). Scripts must gate on `state === "installed"`; a truthiness test now passes for every state, `"not-installed"` included, so it has to be replaced rather than left alone. The text output gains the same distinction, and a hook you customized by hand — which the README invites — reports `!` from then on, since its body no longer matches the hash recorded at install. `GitHooksService.list()` returns those states as well; `isInstalled()` still answers the narrower "a DeepL marker is present" question and is unchanged.
+
 - **translate**: **`--tag-handling` requests now pin `tag_handling_version=v2`** instead of letting the API pick. The CLI previously sent the parameter only when `--tag-handling-version` was passed, so everyone else inherited the server default — which DeepL documents as moving from v1 (deprecation-bound) to v2 at an unannounced date. That flip would have changed tag-handling output with no CLI change to point at, and worse, would have gone unnoticed by the cache: a request that omits the version hashes identically before and after, so cached v1 output would have kept being served after the API started returning v2. Adopting v2 now makes that one output shift deliberate and dated, and DeepL's own docs recommend v2 for structure handling. **`--tag-handling xml`/`html` output may differ from previous releases**; pass `--tag-handling-version v1` to keep the old behaviour, which is still honoured and always wins over the default. Requests without `--tag-handling` send no version. Cached translations from earlier versions are retired on first open regardless — see the cache entry under Fixed — so no tag-handling entry can be served stale.
 
 - **translate**: **A glossary referenced by name is checked against the requested language pair before any translation request.** Previously only translation memories did this; a glossary whose dictionaries did not cover the pair reached the API and came back as `No dictionary found for language pair EN-DE in glossary <uuid>`, naming a UUID the user never typed. It now fails locally, exit 7, naming what the glossary actually covers: `Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.` This costs no extra request, because the glossary list is already fetched to resolve the name. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr is not treated as covering en→fr, and when translating to several targets at once every one of them must be covered. Both sides are compared on their **base** language, because glossary dictionaries only ever name base languages while `--to` accepts regional variants: a de→en glossary covers `--to en-us`, which the API accepts, and demanding an exact match would have made glossaries unusable for every regional target — `en-us`, `en-gb`, `pt-br`, `pt-pt`, `zh-hans`, `es-419`, `fr-ca` — including the ones DeepL steers users towards over bare `en`/`pt`. The check is therefore deliberately permissive at the edges: a pair it lets through is still the API's to reject, which is much the cheaper mistake. Two deliberate exemptions: a glossary passed as a **UUID** is trusted and left to the API, matching how translation-memory resolution already behaves and giving an escape hatch if the check is ever wrong; and a glossary the API reports with no dictionaries is left alone, since that says nothing about coverage.
@@ -383,6 +385,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **hooks**: **`deepl hooks list` no longer reports attacker-authored content as an installed DeepL hook, and the integrity check it already had is now on a path a user can reach.** Two halves of one false-assurance defect. `isDeepLHook()` was `MARKER_PATTERN.test(content) || content.includes('# DeepL CLI Hook')`, and that second test is a **bare substring match**: a file mentioning the marker anywhere, on any line, in any context, passed as a hook this CLI installed. And `verifyIntegrity()` — which parses the `# DeepL CLI Hook v1 [sha256:...]` marker, rehashes the body and compares — was referenced by nothing but its own definition and its unit tests, so no command ever called it and the recorded hash was never checked outside the test suite. Reproduced by execution: a repository shipping a tracked `.githooks/pre-commit` that carries a forged marker with an all-zero hash plus a payload, wired up with `git config core.hooksPath .githooks` (the husky pattern, commonly set by a `prepare` script), and a second file whose only claim to the marker was the sentence `# borrowed from a # DeepL CLI Hook someone posted`. Before: `✓ pre-commit installed`, `✓ pre-push installed`, and `--format json` reporting `{"pre-commit": true, "pre-push": true}` for two files this CLI had never touched. **`list` now reports one of four states per hook** rather than a boolean — `installed` (versioned marker present and the body hashes to what it records), `modified` (marker present, body does not hash to it), `unverified` (legacy pre-1.0 marker, no hash to check), `not-installed` (no file, or no marker) — so the forged hook reads `! pre-commit installed, content does not match its recorded hash` and the quoted-marker file reads `not installed`. The legacy marker is now anchored to a whole line the way the versioned one always was, which is safe because it was only ever emitted as a line of its own. **The output states plainly what the hash is and is not worth**: it detects a change made after the marker was written, and it **cannot establish authorship**, because it is unkeyed — anyone who can write the hook can compute a marker that agrees with their content. That limit is why the fix is honest reporting rather than a stronger claim, and why the marker should be read as change detection, not provenance. A mismatch also has an innocent reading the CLI cannot distinguish — the README invites customizing an installed hook by editing it — so `modified` renders in yellow and the note gives both readings instead of accusing: expected if you edited it yourself, otherwise reinstall. Tightening `isDeepLHook` also tightens two paths that consult it, both fail-safe: `uninstall` refuses to delete a file whose marker is only quoted (it would previously have removed it), and `install` backs such a file up instead of overwriting it.
+
 - **hooks**: **`deepl hooks install` no longer writes an executable outside the repository because the repository told it to.** `resolveHooksDir` asks `git rev-parse --git-path hooks`, which faithfully honours `core.hooksPath` — including an absolute path anywhere on the filesystem — and the install then did an unconditional `writeFileSync` plus `chmod 0755` with no containment check. `core.hooksPath` is repository-local git config, so it travels with a checkout rather than coming from the person running the command. Reproduced by execution: `git config core.hooksPath /outside/dir` followed by `deepl hooks install pre-commit` printed `✓ Installed pre-commit hook`, exited `0`, and left an `0755` script in `/outside/dir`, with nothing on any channel to say the write had left the project. The content written is the CLI's own static template, so this was a wrong-destination defect rather than an arbitrary-code one — but the destination was the checkout's choice. An install whose hooks directory falls outside the working tree now names the configured value and the resolved directory and asks first: declining, or having no terminal to ask on, **exits 6 and writes nothing**, and `-y, --yes` accepts it while still printing the notice to stderr so a scripted install records where the executable went. The refusal lives in `GitHooksService.install`, which needs an explicit `allowExternal` to proceed, so the gate cannot be skipped by a caller that forgets to prompt. Three scoping decisions. Only the **repository-local** setting is consulted: a global `core.hooksPath` is the user's own machine-wide choice, and reading `--local` also means a repository that sets nothing is never reported — which is what keeps **linked worktrees and submodules** quiet, since there `--git-path hooks` legitimately answers with the hooks directory of the repository that owns them, outside this working tree by design. Containment is checked **through symlinks**, so a relative `core.hooksPath` pointing at a symlink that leaves the tree is caught rather than passing a lexical check. And **`uninstall` is left alone**: it already refuses to remove anything that is not a DeepL hook, so the worst it can do at a redirected path is clean up a file this CLI wrote. The containment predicate is now `isWithinDirectory` in `src/utils/paths.ts`, extracted from the copy that was private to `sync-utils.ts` along with `realpathOrAncestor`, so `assertPathWithinRoot` and the hooks check compare paths the same way.
 
 - **config**: **the `0600` mode on the file holding the plaintext API key is now enforced on every load, not just asserted at creation.** `config.json` is created `0600` and its directory `0700`, and neither was ever checked again — so a file restored from a tar or dotfiles backup, copied by `rsync`, or written by hand kept whatever mode it arrived with, forever, and `load()` read it with no `stat`, no repair and no warning while README promised `0600`. Reproduced by execution: a `0777` config directory was still `0777` after `auth set-key`, and a `config.json` chmod'd to `0644` was read by `config list` at exit 0 and left `0644`. A group- or world-reachable config file is now tightened back to `0600` on load, and the run says what it found — `… was mode 0644, which other users on this machine can read. Tightened to 0600. Your API key may already have been read; consider rotating it with: deepl auth set-key` — because a repair says nothing about who read the file before it. The warning is self-extinguishing: the next run finds `0600` and is silent. **The directory is deliberately reported rather than repaired**, which is where the filed remediation had to be rejected after probing it: it proposed `chmod(path.dirname(configPath), 0o700)`, and that dirname is not always a directory the CLI owns — `deepl -c ~/deepl.json` would have chmod'd the user's home directory to `0700`, and this repo's own `ConfigService` unit tests would have chmod'd `/tmp`. A directory that already existed was created by someone else for reasons the CLI cannot know, so it names the mode and the `chmod 700` that would close it and changes nothing. Only the **write** bits are reported (`0o022`): a merely traversable `0755` directory does not let anyone replace the file inside it, and warning about it on every run would be noise nobody reads. **Sticky directories are exempt**, which execution also forced — the first implementation told the user to `chmod 700 /tmp`, advice that would break a shared temp directory, when mode `1777` is exactly the arrangement that makes it safe: only a file's owner can rename or remove it. The cache directory gets the same report, and `cache.db` needed nothing, as it is already `chmod 0600` on every open. Both `mkdir` sites are now unconditional recursive calls rather than `existsSync`-then-create, closing the window where a directory could appear between the two. Nothing refuses to run over a permission: the mode of the file is not a reason to reject the settings in it.
diff --git a/README.md b/README.md
index 64a06c3e..f0088ad2 100644
--- a/README.md
+++ b/README.md
@@ -931,12 +931,20 @@ $ deepl hooks list
 Git Hooks Status:
 
   ✓ pre-commit      installed
-  ✗ pre-push        not installed
-  ✗ commit-msg      not installed
+  ! pre-push        installed, content does not match its recorded hash
+  ? commit-msg      installed, no hash recorded (legacy marker)
   ✗ post-commit     not installed
+
+The content of a hook no longer matches the hash its marker records. That
+is expected if you edited the hook yourself. If you did not, replace it:
+  deepl hooks install <hook-type>
+A recorded hash detects a change made after the marker was written. It
+cannot establish that a hook came from this CLI.
 ```
 
-**Note:** The hooks are generated with placeholder validation logic. You can customize them based on your project's translation workflow by editing the hook files directly at `.git/hooks/pre-commit` or `.git/hooks/pre-push`.
+Every hook this CLI installs carries a marker recording the SHA-256 of its body, and `hooks list` checks it rather than reporting a bare "installed". A `!` means the file at that path is not what its own marker says it is — you edited it, or something else wrote it. The hash is unkeyed, so a match shows a hook has not changed since its marker was written, not that this CLI wrote it: anyone who can write the hook can write a marker to agree with it. `--format json` reports these states as strings (`installed`, `modified`, `unverified`, `not-installed`) rather than booleans.
+
+**Note:** The hooks are generated with placeholder validation logic. You can customize them based on your project's translation workflow by editing the hook files directly at `.git/hooks/pre-commit` or `.git/hooks/pre-push`. A customized hook reports as `!` from then on, since its body no longer matches the hash recorded when it was installed.
 
 See [examples/20-git-hooks.sh](./examples/20-git-hooks.sh) for a complete git hooks example demonstrating installation, usage, and management.
 
diff --git a/docs/API.md b/docs/API.md
index 4225e4db..dc6f1f1f 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1662,7 +1662,22 @@ deepl hooks uninstall post-commit
 
 ##### `list`
 
-List all hooks and their installation status.
+List all hooks and what the file at each hook path is.
+
+Each hook installed by this CLI carries a marker line recording the SHA-256 of
+its body, and `list` checks it. Four states are reported:
+
+| State           | Meaning                                                              |
+| --------------- | -------------------------------------------------------------------- |
+| `installed`     | A versioned marker is present and the body hashes to the value it records |
+| `modified`      | A marker is present and the body does not hash to it — an edit made after installation, or a forged marker |
+| `unverified`    | A legacy (pre-1.0) marker with no recorded hash to check against      |
+| `not-installed` | No hook file, or a file carrying no DeepL marker                      |
+
+The hash is unkeyed, so `installed` establishes that a hook has not changed
+since its marker was written — not that this CLI wrote it. Anyone who can write
+the hook can write a marker that agrees with their own content. Treat the marker
+as detection of changes to a hook, not as proof of its origin.
 
 **Options:**
 
@@ -1675,9 +1690,13 @@ deepl hooks list
 
 # JSON output for CI/CD scripting
 deepl hooks list --format json
-# { "pre-commit": true, "pre-push": false, "commit-msg": false, "post-commit": false }
+# { "pre-commit": "installed", "pre-push": "modified", "commit-msg": "unverified", "post-commit": "not-installed" }
 ```
 
+The JSON values are these state strings, not booleans. Gate on
+`state === "installed"`; a truthiness test passes for every state, including
+`"not-installed"`.
+
 ##### `path <hook-type>`
 
 Show the path to a hook file.
diff --git a/src/cli/commands/hooks.ts b/src/cli/commands/hooks.ts
index 6974172e..79b27ef4 100644
--- a/src/cli/commands/hooks.ts
+++ b/src/cli/commands/hooks.ts
@@ -4,9 +4,46 @@
  */
 
 import chalk from 'chalk';
-import { GitHooksService, HookType } from '../../services/git-hooks.js';
+import {
+  GitHooksService,
+  HookState,
+  HookType,
+} from '../../services/git-hooks.js';
 import { ValidationError } from '../../utils/errors.js';
 
+const HOOK_STATE_DISPLAY: Record<HookState, { icon: string; text: string }> = {
+  installed: { icon: chalk.green('✓'), text: chalk.green('installed') },
+  unverified: {
+    icon: chalk.yellow('?'),
+    text: chalk.yellow('installed, no hash recorded (legacy marker)'),
+  },
+  modified: {
+    icon: chalk.yellow('!'),
+    text: chalk.yellow('installed, content does not match its recorded hash'),
+  },
+  'not-installed': { icon: chalk.gray('✗'), text: chalk.gray('not installed') },
+};
+
+/**
+ * A mismatch has two readings the CLI cannot tell apart — a hook the user
+ * customized, which the documentation invites, and content this CLI never
+ * wrote — so the note gives both rather than accusing either way.
+ */
+const MISMATCH_NOTE = [
+  'The content of a hook no longer matches the hash its marker records. That',
+  'is expected if you edited the hook yourself. If you did not, replace it:',
+  '  deepl hooks install <hook-type>',
+];
+
+/**
+ * The hash is unkeyed, so a matching one is not evidence of authorship: anyone
+ * who can write the hook can write a marker that agrees with it.
+ */
+const AUTHORSHIP_NOTE = [
+  'A recorded hash detects a change made after the marker was written. It',
+  'cannot establish that a hook came from this CLI.',
+];
+
 export class HooksCommand {
   private gitHooksService: GitHooksService | null = null;
 
@@ -80,7 +117,7 @@ export class HooksCommand {
   /**
    * Return raw hook status data (for JSON output)
    */
-  listData(): Record<string, boolean> {
+  listData(): Record<string, HookState> {
     if (!this.gitHooksService) {
       return {};
     }
@@ -98,14 +135,23 @@ export class HooksCommand {
     const status = this.gitHooksService.list();
     const lines = ['Git Hooks Status:', ''];
 
-    for (const [hook, installed] of Object.entries(status)) {
-      const icon = installed ? chalk.green('✓') : chalk.gray('✗');
-      const text = installed
-        ? chalk.green('installed')
-        : chalk.gray('not installed');
+    for (const [hook, state] of Object.entries(status)) {
+      const { icon, text } = HOOK_STATE_DISPLAY[state];
       lines.push(`  ${icon} ${hook.padEnd(15)} ${text}`);
     }
 
+    const states = Object.values(status);
+    const notes: string[] = [];
+    if (states.includes('modified')) {
+      notes.push(...MISMATCH_NOTE);
+    }
+    if (states.includes('modified') || states.includes('unverified')) {
+      notes.push(...AUTHORSHIP_NOTE);
+    }
+    if (notes.length > 0) {
+      lines.push('', ...notes.map((note) => chalk.gray(note)));
+    }
+
     return lines.join('\n');
   }
 
diff --git a/src/services/git-hooks.ts b/src/services/git-hooks.ts
index 7c8b8ed0..a99e6f30 100644
--- a/src/services/git-hooks.ts
+++ b/src/services/git-hooks.ts
@@ -13,8 +13,24 @@ import { sanitizeForTerminal } from '../utils/control-chars.js';
 
 export type HookType = 'pre-commit' | 'pre-push' | 'commit-msg' | 'post-commit';
 
+/**
+ * What the hook file at the expected path is, as far as its recorded marker can
+ * establish.
+ *
+ * `installed` means a versioned marker is present and the body hashes to the
+ * value the marker records. `modified` means the marker is present and the body
+ * does not hash to it — a hand-edit after installation, or a forged marker.
+ * `unverified` means a legacy marker with no hash to check against.
+ *
+ * The hash is unkeyed, so `installed` establishes that the file has not changed
+ * since its marker was written, not that this CLI wrote it: anyone can write a
+ * marker and compute a matching hash.
+ */
+export type HookState =
+  'not-installed' | 'installed' | 'unverified' | 'modified';
+
 export interface HookStatus {
-  [key: string]: boolean;
+  [key: string]: HookState;
 }
 
 export interface InstallResult {
@@ -36,6 +52,12 @@ export interface HookIntegrity {
 const MARKER_VERSION = 1;
 const LEGACY_MARKER = '# DeepL CLI Hook';
 const MARKER_PATTERN = /^# DeepL CLI Hook v(\d+) \[sha256:([a-f0-9]{64})\]$/m;
+/**
+ * The pre-1.0 marker, anchored the way the versioned one is. It was only ever
+ * emitted as a line of its own, so requiring a whole line costs nothing and
+ * keeps a file that merely quotes the string from passing as an installed hook.
+ */
+const LEGACY_MARKER_PATTERN = /^# DeepL CLI Hook$/m;
 
 interface HooksDirResolution {
   dir: string;
@@ -252,7 +274,25 @@ export class GitHooksService {
   }
 
   /**
-   * Check if a hook is installed
+   * Classify the hook file at the expected path.
+   */
+  hookState(hookType: HookType): HookState {
+    const integrity = this.verifyIntegrity(hookType);
+
+    if (!integrity.installed) {
+      return 'not-installed';
+    }
+    if (integrity.hashMatch === null) {
+      return 'unverified';
+    }
+    return integrity.hashMatch ? 'installed' : 'modified';
+  }
+
+  /**
+   * Whether a DeepL marker is present in the hook at the expected path.
+   *
+   * Presence is not integrity: a hook whose body no longer matches its recorded
+   * hash still answers true here. Use `hookState` to tell those apart.
    */
   isInstalled(hookType: HookType): boolean {
     this.validateHookType(hookType);
@@ -268,7 +308,7 @@ export class GitHooksService {
   }
 
   /**
-   * List all hooks and their installation status
+   * List all hooks and what the file at each expected path is
    */
   list(): HookStatus {
     const hooks: HookType[] = [
@@ -280,7 +320,7 @@ export class GitHooksService {
     const status: HookStatus = {};
 
     for (const hook of hooks) {
-      status[hook] = this.isInstalled(hook);
+      status[hook] = this.hookState(hook);
     }
 
     return status;
@@ -347,7 +387,7 @@ export class GitHooksService {
     const markerMatch = content.match(MARKER_PATTERN);
 
     if (!markerMatch) {
-      if (content.includes(LEGACY_MARKER)) {
+      if (LEGACY_MARKER_PATTERN.test(content)) {
         return {
           installed: true,
           markerVersion: 'legacy',
@@ -563,7 +603,7 @@ exit 0
    * Check if content is a DeepL CLI hook (supports both legacy and versioned markers)
    */
   private isDeepLHook(content: string): boolean {
-    return MARKER_PATTERN.test(content) || content.includes(LEGACY_MARKER);
+    return MARKER_PATTERN.test(content) || LEGACY_MARKER_PATTERN.test(content);
   }
 
   /**
diff --git a/tests/e2e/cli-hooks.e2e.test.ts b/tests/e2e/cli-hooks.e2e.test.ts
index 6fb42c00..56d8a255 100644
--- a/tests/e2e/cli-hooks.e2e.test.ts
+++ b/tests/e2e/cli-hooks.e2e.test.ts
@@ -98,6 +98,38 @@ describe('Hooks Command E2E', () => {
     expect(output).toContain('Invalid hook type');
   });
 
+  describe('a repository that ships its own hooks', () => {
+    const FORGED = `#!/bin/sh\n# DeepL CLI Hook v1 [sha256:${'0'.repeat(64)}]\necho "attacker payload"\n`;
+
+    beforeEach(() => {
+      fs.mkdirSync(path.join(tmpDir, '.githooks'));
+      fs.writeFileSync(path.join(tmpDir, '.githooks', 'pre-commit'), FORGED, {
+        mode: 0o755,
+      });
+      execSync('git config core.hooksPath .githooks', {
+        cwd: tmpDir,
+        stdio: 'ignore',
+      });
+    });
+
+    it('should not report tracked content with a forged marker as installed', () => {
+      const output = run('hooks list');
+
+      expect(output).toContain('does not match its recorded hash');
+      expect(output).toContain('cannot establish');
+      expect(
+        fs.readFileSync(path.join(tmpDir, '.githooks', 'pre-commit'), 'utf-8')
+      ).toBe(FORGED);
+    });
+
+    it('should report the state rather than a bare boolean in JSON', () => {
+      const parsed = JSON.parse(run('hooks list --format json'));
+
+      expect(parsed['pre-commit']).toBe('modified');
+      expect(parsed['pre-push']).toBe('not-installed');
+    });
+  });
+
   describe('a repository that sends hooks outside the working tree', () => {
     let outside: string;
 
diff --git a/tests/integration/cli-hooks.integration.test.ts b/tests/integration/cli-hooks.integration.test.ts
index 6fd2e648..e429db0e 100644
--- a/tests/integration/cli-hooks.integration.test.ts
+++ b/tests/integration/cli-hooks.integration.test.ts
@@ -203,10 +203,10 @@ describe('Git Hooks Service Integration', () => {
     it('should list all hooks as not installed initially', () => {
       const status = hooksService.list();
 
-      expect(status['pre-commit']).toBe(false);
-      expect(status['pre-push']).toBe(false);
-      expect(status['commit-msg']).toBe(false);
-      expect(status['post-commit']).toBe(false);
+      expect(status['pre-commit']).toBe('not-installed');
+      expect(status['pre-push']).toBe('not-installed');
+      expect(status['commit-msg']).toBe('not-installed');
+      expect(status['post-commit']).toBe('not-installed');
     });
 
     it('should show installed hooks', () => {
@@ -215,10 +215,10 @@ describe('Git Hooks Service Integration', () => {
 
       const status = hooksService.list();
 
-      expect(status['pre-commit']).toBe(true);
-      expect(status['pre-push']).toBe(true);
-      expect(status['commit-msg']).toBe(false);
-      expect(status['post-commit']).toBe(false);
+      expect(status['pre-commit']).toBe('installed');
+      expect(status['pre-push']).toBe('installed');
+      expect(status['commit-msg']).toBe('not-installed');
+      expect(status['post-commit']).toBe('not-installed');
     });
 
     it('should not show non-DeepL hooks as installed', () => {
@@ -227,7 +227,20 @@ describe('Git Hooks Service Integration', () => {
       fs.writeFileSync(hookPath, '#!/bin/sh\necho "Custom"', 'utf-8');
 
       const status = hooksService.list();
-      expect(status['pre-commit']).toBe(false);
+      expect(status['pre-commit']).toBe('not-installed');
+    });
+
+    it('should not vouch for a hook whose marker was forged', () => {
+      const hookPath = hooksService.getHookPath('pre-commit');
+      fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+      fs.writeFileSync(
+        hookPath,
+        `#!/bin/sh\n# DeepL CLI Hook v1 [sha256:${'0'.repeat(64)}]\necho "attacker payload"\n`,
+        'utf-8'
+      );
+
+      const status = hooksService.list();
+      expect(status['pre-commit']).toBe('modified');
     });
   });
 
diff --git a/tests/integration/git-hooks-resolution.integration.test.ts b/tests/integration/git-hooks-resolution.integration.test.ts
index b8295409..96b82d0f 100644
--- a/tests/integration/git-hooks-resolution.integration.test.ts
+++ b/tests/integration/git-hooks-resolution.integration.test.ts
@@ -86,7 +86,7 @@ describe('GitHooksService hooks directory resolution', () => {
       expect(fs.existsSync(path.join(repo, 'hooks-dir', 'commit-msg'))).toBe(
         true
       );
-      expect(service.list()['commit-msg']).toBe(true);
+      expect(service.list()['commit-msg']).toBe('installed');
       expect(service.isInstalled('commit-msg')).toBe(true);
     });
 
diff --git a/tests/unit/hooks-command.test.ts b/tests/unit/hooks-command.test.ts
index d09b8af0..cb8afca7 100644
--- a/tests/unit/hooks-command.test.ts
+++ b/tests/unit/hooks-command.test.ts
@@ -182,8 +182,8 @@ describe('HooksCommand', () => {
   describe('list()', () => {
     it('should list hooks when both are installed', () => {
       mockGitHooksService.list.mockReturnValue({
-        'pre-commit': true,
-        'pre-push': true,
+        'pre-commit': 'installed',
+        'pre-push': 'installed',
       });
       const command = new HooksCommand('/path/to/.git');
 
@@ -198,8 +198,8 @@ describe('HooksCommand', () => {
 
     it('should list hooks when none are installed', () => {
       mockGitHooksService.list.mockReturnValue({
-        'pre-commit': false,
-        'pre-push': false,
+        'pre-commit': 'not-installed',
+        'pre-push': 'not-installed',
       });
       const command = new HooksCommand('/path/to/.git');
 
@@ -213,8 +213,8 @@ describe('HooksCommand', () => {
 
     it('should list hooks with mixed status', () => {
       mockGitHooksService.list.mockReturnValue({
-        'pre-commit': true,
-        'pre-push': false,
+        'pre-commit': 'installed',
+        'pre-push': 'not-installed',
       });
       const command = new HooksCommand('/path/to/.git');
 
@@ -234,6 +234,76 @@ describe('HooksCommand', () => {
 
       expect(result).toContain('Not in a git repository');
     });
+
+    it('should not report a hook whose hash does not match as simply installed', () => {
+      mockGitHooksService.list.mockReturnValue({
+        'pre-commit': 'modified',
+      });
+      const command = new HooksCommand('/path/to/.git');
+
+      const result = command.list();
+
+      expect(result).toContain('does not match its recorded hash');
+    });
+
+    it('should mark a legacy hook as carrying no hash', () => {
+      mockGitHooksService.list.mockReturnValue({
+        'pre-commit': 'unverified',
+      });
+      const command = new HooksCommand('/path/to/.git');
+
+      const result = command.list();
+
+      expect(result).toContain('no hash recorded');
+    });
+
+    it('should explain what the hash does and does not establish when a hook is not verified', () => {
+      mockGitHooksService.list.mockReturnValue({
+        'pre-commit': 'modified',
+        'pre-push': 'installed',
+      });
+      const command = new HooksCommand('/path/to/.git');
+
+      const result = command.list();
+
+      expect(result).toContain('cannot establish');
+      expect(result).toContain('deepl hooks install');
+    });
+
+    it('should allow for a hook the user edited on purpose', () => {
+      mockGitHooksService.list.mockReturnValue({
+        'pre-commit': 'modified',
+      });
+      const command = new HooksCommand('/path/to/.git');
+
+      const result = command.list();
+
+      expect(result).toContain('edited the hook yourself');
+    });
+
+    it('should not suggest replacing a hook that is merely unverified', () => {
+      mockGitHooksService.list.mockReturnValue({
+        'pre-commit': 'unverified',
+      });
+      const command = new HooksCommand('/path/to/.git');
+
+      const result = command.list();
+
+      expect(result).toContain('cannot establish');
+      expect(result).not.toContain('deepl hooks install');
+    });
+
+    it('should not add the caveat when every hook verifies or is absent', () => {
+      mockGitHooksService.list.mockReturnValue({
+        'pre-commit': 'installed',
+        'pre-push': 'not-installed',
+      });
+      const command = new HooksCommand('/path/to/.git');
+
+      const result = command.list();
+
+      expect(result).not.toContain('cannot establish');
+    });
   });
 
   describe('showPath()', () => {
@@ -291,16 +361,16 @@ describe('HooksCommand', () => {
   describe('listData()', () => {
     it('should return raw status object when hooks are installed', () => {
       mockGitHooksService.list.mockReturnValue({
-        'pre-commit': true,
-        'pre-push': false,
+        'pre-commit': 'installed',
+        'pre-push': 'not-installed',
       });
       const command = new HooksCommand('/path/to/.git');
 
       const data = command.listData();
 
       expect(data).toEqual({
-        'pre-commit': true,
-        'pre-push': false,
+        'pre-commit': 'installed',
+        'pre-push': 'not-installed',
       });
     });
 
@@ -316,10 +386,10 @@ describe('HooksCommand', () => {
 
     it('should produce valid parseable JSON', () => {
       mockGitHooksService.list.mockReturnValue({
-        'pre-commit': true,
-        'pre-push': true,
-        'commit-msg': false,
-        'post-commit': false,
+        'pre-commit': 'installed',
+        'pre-push': 'installed',
+        'commit-msg': 'not-installed',
+        'post-commit': 'not-installed',
       });
       const command = new HooksCommand('/path/to/.git');
 
@@ -327,10 +397,10 @@ describe('HooksCommand', () => {
       const json = JSON.stringify(data, null, 2);
       const parsed = JSON.parse(json);
 
-      expect(parsed['pre-commit']).toBe(true);
-      expect(parsed['pre-push']).toBe(true);
-      expect(parsed['commit-msg']).toBe(false);
-      expect(parsed['post-commit']).toBe(false);
+      expect(parsed['pre-commit']).toBe('installed');
+      expect(parsed['pre-push']).toBe('installed');
+      expect(parsed['commit-msg']).toBe('not-installed');
+      expect(parsed['post-commit']).toBe('not-installed');
     });
   });
 });
diff --git a/tests/unit/services/git-hooks.test.ts b/tests/unit/services/git-hooks.test.ts
index c15660fb..804b11d1 100644
--- a/tests/unit/services/git-hooks.test.ts
+++ b/tests/unit/services/git-hooks.test.ts
@@ -316,10 +316,10 @@ describe('GitHooksService', () => {
       expect(status).toHaveProperty('pre-push');
       expect(status).toHaveProperty('commit-msg');
       expect(status).toHaveProperty('post-commit');
-      expect(status['pre-commit']).toBe(false);
-      expect(status['pre-push']).toBe(false);
-      expect(status['commit-msg']).toBe(false);
-      expect(status['post-commit']).toBe(false);
+      expect(status['pre-commit']).toBe('not-installed');
+      expect(status['pre-push']).toBe('not-installed');
+      expect(status['commit-msg']).toBe('not-installed');
+      expect(status['post-commit']).toBe('not-installed');
     });
 
     it('should show correct status when some hooks are installed', () => {
@@ -328,10 +328,10 @@ describe('GitHooksService', () => {
 
       const status = gitHooksService.list();
 
-      expect(status['pre-commit']).toBe(true);
-      expect(status['pre-push']).toBe(false);
-      expect(status['commit-msg']).toBe(true);
-      expect(status['post-commit']).toBe(false);
+      expect(status['pre-commit']).toBe('installed');
+      expect(status['pre-push']).toBe('not-installed');
+      expect(status['commit-msg']).toBe('installed');
+      expect(status['post-commit']).toBe('not-installed');
     });
 
     it('should show all installed when all hooks are installed', () => {
@@ -342,10 +342,10 @@ describe('GitHooksService', () => {
 
       const status = gitHooksService.list();
 
-      expect(status['pre-commit']).toBe(true);
-      expect(status['pre-push']).toBe(true);
-      expect(status['commit-msg']).toBe(true);
-      expect(status['post-commit']).toBe(true);
+      expect(status['pre-commit']).toBe('installed');
+      expect(status['pre-push']).toBe('installed');
+      expect(status['commit-msg']).toBe('installed');
+      expect(status['post-commit']).toBe('installed');
     });
   });
 
@@ -542,10 +542,17 @@ describe('GitHooksService', () => {
       expect((gitHooksService as any).isDeepLHook(customContent)).toBe(false);
     });
 
-    it('should match hook containing legacy marker as substring', () => {
+    it('should reject a line the legacy marker is only a prefix of', () => {
       const content = '#!/bin/sh\n# DeepL CLI Hooks\necho "test"';
 
-      expect((gitHooksService as any).isDeepLHook(content)).toBe(true);
+      expect((gitHooksService as any).isDeepLHook(content)).toBe(false);
+    });
+
+    it('should reject a line that merely quotes the legacy marker', () => {
+      const content =
+        '#!/bin/sh\n# adapted from a # DeepL CLI Hook\necho "test"';
+
+      expect((gitHooksService as any).isDeepLHook(content)).toBe(false);
     });
   });
 
@@ -693,6 +700,112 @@ describe('GitHooksService', () => {
     });
   });
 
+  describe('hookState()', () => {
+    const BOGUS_HASH = '0'.repeat(64);
+
+    beforeEach(() => {
+      fs.mkdirSync(testHooksDir, { recursive: true });
+    });
+
+    function writeHook(content: string): void {
+      fs.writeFileSync(path.join(testHooksDir, 'pre-commit'), content, 'utf-8');
+    }
+
+    it('should report not-installed when no hook file exists', () => {
+      expect(gitHooksService.hookState('pre-commit')).toBe('not-installed');
+    });
+
+    it('should report not-installed for a hook with no DeepL marker', () => {
+      writeHook('#!/bin/sh\necho "someone else\'s hook"');
+
+      expect(gitHooksService.hookState('pre-commit')).toBe('not-installed');
+    });
+
+    it('should report installed for a hook this service just wrote', () => {
+      gitHooksService.install('pre-commit');
+
+      expect(gitHooksService.hookState('pre-commit')).toBe('installed');
+    });
+
+    it('should report modified when a forged marker records a hash the body does not have', () => {
+      writeHook(
+        `#!/bin/sh\n# DeepL CLI Hook v1 [sha256:${BOGUS_HASH}]\necho "attacker payload"\n`
+      );
+
+      expect(gitHooksService.hookState('pre-commit')).toBe('modified');
+    });
+
+    it('should report modified when an installed hook is edited afterwards', () => {
+      gitHooksService.install('pre-commit');
+      const hookPath = path.join(testHooksDir, 'pre-commit');
+      fs.appendFileSync(hookPath, '\necho "injected"\n');
+
+      expect(gitHooksService.hookState('pre-commit')).toBe('modified');
+    });
+
+    it('should report unverified for a legacy marker with no hash to check', () => {
+      writeHook('#!/bin/sh\n# DeepL CLI Hook\necho "old style"');
+
+      expect(gitHooksService.hookState('pre-commit')).toBe('unverified');
+    });
+
+    it('should surface each state through list()', () => {
+      gitHooksService.install('pre-commit');
+      fs.writeFileSync(
+        path.join(testHooksDir, 'pre-push'),
+        `#!/bin/sh\n# DeepL CLI Hook v1 [sha256:${BOGUS_HASH}]\necho "attacker payload"\n`,
+        'utf-8'
+      );
+      fs.writeFileSync(
+        path.join(testHooksDir, 'commit-msg'),
+        '#!/bin/sh\n# DeepL CLI Hook\necho "old style"',
+        'utf-8'
+      );
+
+      expect(gitHooksService.list()).toEqual({
+        'pre-commit': 'installed',
+        'pre-push': 'modified',
+        'commit-msg': 'unverified',
+        'post-commit': 'not-installed',
+      });
+    });
+  });
+
+  describe('the legacy marker is a whole line, not a substring', () => {
+    const INLINE_MENTION =
+      '#!/bin/sh\n# borrowed from a # DeepL CLI Hook someone posted\necho "payload"\n';
+
+    beforeEach(() => {
+      fs.mkdirSync(testHooksDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(testHooksDir, 'pre-commit'),
+        INLINE_MENTION,
+        'utf-8'
+      );
+    });
+
+    it('should not report a file that only mentions the marker as installed', () => {
+      expect(gitHooksService.hookState('pre-commit')).toBe('not-installed');
+      expect(gitHooksService.isInstalled('pre-commit')).toBe(false);
+    });
+
+    it('should refuse to uninstall it', () => {
+      expect(() => gitHooksService.uninstall('pre-commit')).toThrow(
+        'not a DeepL CLI hook'
+      );
+      expect(
+        fs.readFileSync(path.join(testHooksDir, 'pre-commit'), 'utf-8')
+      ).toBe(INLINE_MENTION);
+    });
+
+    it('should back it up rather than overwrite it on install', () => {
+      const result = gitHooksService.install('pre-commit');
+
+      expect(result.backupPath).not.toBeNull();
+      expect(fs.readFileSync(result.backupPath!, 'utf-8')).toBe(INLINE_MENTION);
+    });
+  });
+
   describe('backward compatibility', () => {
     beforeEach(() => {
       fs.mkdirSync(testHooksDir, { recursive: true });

From 956eeac1d71381581d901c7251ac64bf3a2bc051 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 20:52:25 +0200
Subject: [PATCH 144/256] fix(sync): check the shape of a lockfile before sync
 relies on it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

read() validated `version` and that `entries` was an object, then cast the
rest of the repository's JSON to SyncLockFile. Every level below that was
dereferenced unguarded, so a lockfile a hostile or merge-mangled repository
ships decided how sync failed.

Reproduced against a mock endpoint. A missing `stats` crashed with "Cannot
set properties of undefined (setting 'total_keys')" and exit 1 after the
endpoint had been hit and the target file written, leaving the attacker's
stub in place so the next run re-billed everything. An entry with no
`translations` crashed reading 'de', and took read-only `sync status` down
with it. A per-file map that was a string crashed deleting property '0'.
`entries` as an array was accepted silently: the run's results were set on
named properties of the array, the serializer dropped them, and the
lockfile recorded "entries": [] beside total_keys: 2, so every later run
re-billed the project in silence. Probing found two more — a null
translation, one level deeper than a container check reaches, and `stats`
as a string.

Malformed members are now dropped individually rather than the file being
discarded. A key that loses its entry is translated and billed again, so
resetting a whole lockfile over one bad member would hand whoever wrote it
a full re-translation of the project. The count is warned and the original
backed up. `entries` that is not a map has nothing to salvage and takes the
existing full-sync path.

`stats` is no longer trusted at all. It is derived from `entries`,
recomputed on every write that follows a mutation, and nothing reads the
on-disk values for their own sake, so read() recomputes the counts from the
surviving entries. They can no longer disagree with the entries they
describe.

Refs cli-8kr2.27
---
 CHANGELOG.md                      |   2 +
 docs/SYNC.md                      |   2 +
 src/sync/sync-lock.ts             | 125 ++++++++++++++-
 tests/e2e/cli-sync.e2e.test.ts    |  70 ++++++++
 tests/unit/sync/sync-lock.test.ts | 254 ++++++++++++++++++++++++++++++
 5 files changed, 452 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 975ccabe..23c7e12e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -385,6 +385,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync**: **a lockfile is now checked member by member before sync uses it, instead of being version-checked and then cast.** `SyncLockManager.read()` validated `version` and that `entries` was an object, then cast the rest of the repository's JSON to `SyncLockFile` — so `stats`, each per-file map, each entry and each translation were dereferenced unguarded. Four shapes reproduced by execution against a mock endpoint, all from a lockfile a hostile or merge-mangled repository ships: **a missing `stats`** crashed with `Error: Cannot set properties of undefined (setting 'total_keys')` and exit 1 **after the endpoint had been hit and `de.json` written**, leaving the lockfile as the attacker's stub so the next run re-billed everything; **an entry with no `translations` container** crashed with `Cannot read properties of undefined (reading 'de')`, and the same lockfile took `sync status` — a read-only command — down with `Cannot convert undefined or null to object`; **a per-file map that is a string** crashed with `Cannot delete property '0' of [object String]`; and **`entries` as an array** was accepted silently, exit 0, with the run's results written onto named properties of that array and then discarded by the serializer, so the lockfile recorded `"entries": []` beside `total_keys: 2` and every later run re-billed the project in silence, forever. Two more shapes found while probing: **a null translation** crashed with `Cannot read properties of null (reading 'status')` — one level deeper than the shape check the finding proposed — and **`stats` as a string** crashed with `Cannot create property 'total_keys' on string`. Every one of them now exits 0 with a well-formed lockfile. **Malformed members are dropped individually, not by discarding the file**: a key that loses its entry is translated and billed again, so resetting a whole lockfile over one bad member would hand whoever wrote it a full re-translation of the project. The count is reported at WARN level and the original is copied to `.deepl-sync.lock.bak-v1-malformed-<timestamp>`. `entries` that is not a map at all has nothing to salvage and takes the existing full-sync path with its own `-entries-not-a-map` tag. **`stats` is no longer trusted at all**: it is derived from `entries` and recomputed on every write that follows a mutation, and nothing reads the on-disk values for their own sake, so read() recomputes the counts from the surviving entries rather than validating what the file claims — which also means the counts can no longer disagree with the entries they describe. The repaired `entries` is rebuilt with `setOwnMember`, so a source path or i18n key named `__proto__` is carried across as an own property. In-repo precedent for the shape of the fix: `sync/tms-client.ts` already validated an untrusted map this way for pulled keys.
+
 - **hooks**: **`deepl hooks list` no longer reports attacker-authored content as an installed DeepL hook, and the integrity check it already had is now on a path a user can reach.** Two halves of one false-assurance defect. `isDeepLHook()` was `MARKER_PATTERN.test(content) || content.includes('# DeepL CLI Hook')`, and that second test is a **bare substring match**: a file mentioning the marker anywhere, on any line, in any context, passed as a hook this CLI installed. And `verifyIntegrity()` — which parses the `# DeepL CLI Hook v1 [sha256:...]` marker, rehashes the body and compares — was referenced by nothing but its own definition and its unit tests, so no command ever called it and the recorded hash was never checked outside the test suite. Reproduced by execution: a repository shipping a tracked `.githooks/pre-commit` that carries a forged marker with an all-zero hash plus a payload, wired up with `git config core.hooksPath .githooks` (the husky pattern, commonly set by a `prepare` script), and a second file whose only claim to the marker was the sentence `# borrowed from a # DeepL CLI Hook someone posted`. Before: `✓ pre-commit installed`, `✓ pre-push installed`, and `--format json` reporting `{"pre-commit": true, "pre-push": true}` for two files this CLI had never touched. **`list` now reports one of four states per hook** rather than a boolean — `installed` (versioned marker present and the body hashes to what it records), `modified` (marker present, body does not hash to it), `unverified` (legacy pre-1.0 marker, no hash to check), `not-installed` (no file, or no marker) — so the forged hook reads `! pre-commit installed, content does not match its recorded hash` and the quoted-marker file reads `not installed`. The legacy marker is now anchored to a whole line the way the versioned one always was, which is safe because it was only ever emitted as a line of its own. **The output states plainly what the hash is and is not worth**: it detects a change made after the marker was written, and it **cannot establish authorship**, because it is unkeyed — anyone who can write the hook can compute a marker that agrees with their content. That limit is why the fix is honest reporting rather than a stronger claim, and why the marker should be read as change detection, not provenance. A mismatch also has an innocent reading the CLI cannot distinguish — the README invites customizing an installed hook by editing it — so `modified` renders in yellow and the note gives both readings instead of accusing: expected if you edited it yourself, otherwise reinstall. Tightening `isDeepLHook` also tightens two paths that consult it, both fail-safe: `uninstall` refuses to delete a file whose marker is only quoted (it would previously have removed it), and `install` backs such a file up instead of overwriting it.
 
 - **hooks**: **`deepl hooks install` no longer writes an executable outside the repository because the repository told it to.** `resolveHooksDir` asks `git rev-parse --git-path hooks`, which faithfully honours `core.hooksPath` — including an absolute path anywhere on the filesystem — and the install then did an unconditional `writeFileSync` plus `chmod 0755` with no containment check. `core.hooksPath` is repository-local git config, so it travels with a checkout rather than coming from the person running the command. Reproduced by execution: `git config core.hooksPath /outside/dir` followed by `deepl hooks install pre-commit` printed `✓ Installed pre-commit hook`, exited `0`, and left an `0755` script in `/outside/dir`, with nothing on any channel to say the write had left the project. The content written is the CLI's own static template, so this was a wrong-destination defect rather than an arbitrary-code one — but the destination was the checkout's choice. An install whose hooks directory falls outside the working tree now names the configured value and the resolved directory and asks first: declining, or having no terminal to ask on, **exits 6 and writes nothing**, and `-y, --yes` accepts it while still printing the notice to stderr so a scripted install records where the executable went. The refusal lives in `GitHooksService.install`, which needs an explicit `allowExternal` to proceed, so the gate cannot be skipped by a caller that forgets to prompt. Three scoping decisions. Only the **repository-local** setting is consulted: a global `core.hooksPath` is the user's own machine-wide choice, and reading `--local` also means a repository that sets nothing is never reported — which is what keeps **linked worktrees and submodules** quiet, since there `--git-path hooks` legitimately answers with the hooks directory of the repository that owns them, outside this working tree by design. Containment is checked **through symlinks**, so a relative `core.hooksPath` pointing at a symlink that leaves the tree is caught rather than passing a lexical check. And **`uninstall` is left alone**: it already refuses to remove anything that is not a DeepL hook, so the worst it can do at a redirected path is clean up a file this CLI wrote. The containment predicate is now `isWithinDirectory` in `src/utils/paths.ts`, extracted from the copy that was private to `sync-utils.ts` along with `realpathOrAncestor`, so `assertPathWithinRoot` and the hooks check compare paths the same way.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 238a7afe..5baa6b04 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -353,6 +353,8 @@ The lockfile is auto-generated and should be committed to version control. It st
 
 **Recovery.** If sync encounters a lockfile with an unsupported `version` or invalid JSON, it copies the existing file to `.deepl-sync.lock.bak-<tag>-<timestamp>` (tag is `corrupt`, `v-unknown`, or `v<N>`) before resetting in-memory state and continuing with a full re-sync. The backup path is logged at WARN level so you can restore it from the working tree if needed.
 
+**Malformed structure.** A lockfile that parses as JSON at the supported version is still checked member by member before it is used, because it is read from the repository and every level of it can be wrong. A per-file map, an entry, an entry's `translations` container or an individual translation that is not an object is **dropped**, and the keys behind it are translated again on that run. Dropping is per member rather than per file: discarding a whole lockfile over one bad entry would re-translate — and re-bill — the entire project. The count is reported at WARN level with a `-malformed` backup, so the original is recoverable. `entries` that is not a map at all (an array, for instance) carries nothing to salvage and takes the full re-sync path above, tagged `-entries-not-a-map`. The `stats` block is never read for its own sake — it is derived from `entries` and recomputed on write — so it is recomputed on read rather than trusted, and a missing or malformed `stats` is repaired silently.
+
 Each translation entry in the lockfile records:
 
 | Field | Description |
diff --git a/src/sync/sync-lock.ts b/src/sync/sync-lock.ts
index a4a43e2d..411c6357 100644
--- a/src/sync/sync-lock.ts
+++ b/src/sync/sync-lock.ts
@@ -188,6 +188,85 @@ export function serializeLockFile(lockFile: SyncLockFile): string {
   return `${serializeNode(lockFile, '', [])}\n`;
 }
 
+/** A member that can carry lock file structure: an object, not null, not an array. */
+function isContainer(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The recorded sync timestamp when the file carries a usable one. */
+function lastSyncOf(stats: unknown): string {
+  if (isContainer(stats) && typeof stats['last_sync'] === 'string') {
+    return stats['last_sync'];
+  }
+  return new Date().toISOString();
+}
+
+interface ShapeRepair {
+  /** Members dropped for not having the shape the sync code dereferences. */
+  dropped: number;
+  entries: Record<string, Record<string, SyncLockEntry>>;
+  totalKeys: number;
+  totalTranslations: number;
+}
+
+/**
+ * Rebuild `entries` from the members that have the shape the rest of sync
+ * dereferences, and count what survives.
+ *
+ * A lock file is read from the repository, so every level of it is untrusted.
+ * Malformed members are dropped one at a time rather than the file being
+ * discarded whole: a key that loses its entry is translated again and billed
+ * again, so discarding an entire lock file over one bad member would hand
+ * whoever wrote it a full re-translation of the project.
+ *
+ * The result is a fresh object built with `setOwnMember`, so a file path or i18n
+ * key named `__proto__` is carried across as an own property rather than
+ * reaching a prototype setter.
+ */
+function repairEntryShape(entries: Record<string, unknown>): ShapeRepair {
+  const repaired: Record<string, Record<string, SyncLockEntry>> = {};
+  let dropped = 0;
+  let totalKeys = 0;
+  let totalTranslations = 0;
+
+  for (const [filePath, fileEntries] of Object.entries(entries)) {
+    if (!isContainer(fileEntries)) {
+      dropped++;
+      continue;
+    }
+
+    const repairedFile: Record<string, SyncLockEntry> = {};
+    for (const [key, entry] of Object.entries(fileEntries)) {
+      if (!isContainer(entry) || !isContainer(entry['translations'])) {
+        dropped++;
+        continue;
+      }
+
+      const translations: Record<string, unknown> = {};
+      for (const [locale, translation] of Object.entries(
+        entry['translations']
+      )) {
+        if (!isContainer(translation)) {
+          dropped++;
+          continue;
+        }
+        setOwnMember(translations, locale, translation);
+        totalTranslations++;
+      }
+
+      setOwnMember(repairedFile, key, {
+        ...entry,
+        translations,
+      } as unknown as SyncLockEntry);
+      totalKeys++;
+    }
+
+    setOwnMember(repaired, filePath, repairedFile);
+  }
+
+  return { dropped, entries: repaired, totalKeys, totalTranslations };
+}
+
 // Per-manager memo of the entries-mutation counter value that `stats` were
 // last computed for. Avoids walking every entry twice on each updateEntry /
 // removeEntry (once in the method, once again in write()).
@@ -275,8 +354,52 @@ export class SyncLockManager {
       Logger.warn(`Lock file missing entries, performing full sync.${suffix}`);
       return createEmptyLockFile('');
     }
+    // An array cannot carry entries keyed by source path, so there is nothing
+    // to salvage from one. Left to the full-sync path rather than repaired,
+    // unlike a malformed member inside a real map.
+    if (Array.isArray(obj['entries'])) {
+      const backup = backupLockFile(
+        this.lockFilePath,
+        raw,
+        `v${LOCK_FILE_VERSION}-entries-not-a-map`
+      );
+      const suffix = backup
+        ? ` Previous lock file backed up to ${backup}.`
+        : '';
+      Logger.warn(
+        `Lock file entries is not a map of source paths, performing full sync.${suffix}`
+      );
+      return createEmptyLockFile('');
+    }
+
+    const repair = repairEntryShape(obj['entries'] as Record<string, unknown>);
+    if (repair.dropped > 0) {
+      const backup = backupLockFile(
+        this.lockFilePath,
+        raw,
+        `v${LOCK_FILE_VERSION}-malformed`
+      );
+      const suffix = backup
+        ? ` Previous lock file backed up to ${backup}.`
+        : '';
+      Logger.warn(
+        `Lock file contained ${repair.dropped} malformed ${repair.dropped === 1 ? 'entry' : 'entries'}, now dropped; the affected keys will be translated again.${suffix}`
+      );
+    }
+
+    const lockFile = parsed as SyncLockFile;
+    lockFile.entries = repair.entries;
+    // `stats` is derived from `entries` and recomputed on every write that
+    // follows a mutation, so the values on disk are never read for their own
+    // sake. Replacing them outright is cheaper than validating them and cannot
+    // leave the counts disagreeing with the entries they describe.
+    lockFile.stats = {
+      total_keys: repair.totalKeys,
+      total_translations: repair.totalTranslations,
+      last_sync: lastSyncOf(obj['stats']),
+    };
 
-    return parsed as SyncLockFile;
+    return lockFile;
   }
 
   async write(lockFile: SyncLockFile): Promise<void> {
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 8a83ff46..1096dbcf 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -249,6 +249,76 @@ describe('CLI Sync E2E', () => {
     });
   });
 
+  describe('a lock file the repository controls', () => {
+    const lockPath = () => path.join(testFiles.path, '.deepl-sync.lock');
+
+    function syncWithLock(lock: string): string {
+      writeSyncConfig(testFiles.path, ['de']);
+      writeSourceFile(testFiles.path);
+      fs.writeFileSync(lockPath(), lock);
+      return runSyncAll();
+    }
+
+    it('should not crash after billing when stats is missing', () => {
+      const output = syncWithLock(
+        '{"version":1,"source_locale":"en","entries":{}}'
+      );
+
+      expect(output).not.toContain('Cannot set properties of undefined');
+      expect(output).toContain('Sync complete');
+      const written = JSON.parse(fs.readFileSync(lockPath(), 'utf-8')) as {
+        stats: { total_keys: number };
+      };
+      expect(written.stats.total_keys).toBe(2);
+    });
+
+    it('should drop an entry with no translations container and record the run', () => {
+      const output = syncWithLock(
+        JSON.stringify({
+          version: 1,
+          source_locale: 'en',
+          entries: {
+            'locales/en.json': {
+              greeting: { source_hash: '185f8db32271', source_text: 'Hello' },
+            },
+          },
+          stats: { total_keys: 1, total_translations: 1, last_sync: 'x' },
+        })
+      );
+
+      expect(output).not.toContain('Cannot read properties of undefined');
+      expect(output).toContain('malformed');
+      const written = JSON.parse(fs.readFileSync(lockPath(), 'utf-8')) as {
+        entries: Record<string, Record<string, unknown>>;
+      };
+      expect(Object.keys(written.entries['locales/en.json']!)).toContain(
+        'greeting'
+      );
+    });
+
+    it('should not leave a per-file map that is a string unrecorded', () => {
+      const output = syncWithLock(
+        '{"version":1,"source_locale":"en","entries":{"locales/en.json":"pwn"},"stats":{"total_keys":0,"total_translations":0,"last_sync":"x"}}'
+      );
+
+      expect(output).not.toContain('Cannot delete property');
+      expect(output).toContain('Sync complete');
+    });
+
+    it('should record entries when the lock file arrives with entries as an array', () => {
+      const output = syncWithLock(
+        '{"version":1,"source_locale":"en","entries":[],"stats":{"total_keys":0,"total_translations":0,"last_sync":"x"}}'
+      );
+
+      expect(output).toContain('performing full sync');
+      const written = JSON.parse(fs.readFileSync(lockPath(), 'utf-8')) as {
+        entries: Record<string, Record<string, unknown>>;
+      };
+      expect(Array.isArray(written.entries)).toBe(false);
+      expect(Object.keys(written.entries['locales/en.json']!)).toHaveLength(2);
+    });
+  });
+
   describe('frozen mode', () => {
     it('should exit 10 on frozen with drift', () => {
       writeSyncConfig(testFiles.path, ['de']);
diff --git a/tests/unit/sync/sync-lock.test.ts b/tests/unit/sync/sync-lock.test.ts
index dbbf8f8f..7cdd47ca 100644
--- a/tests/unit/sync/sync-lock.test.ts
+++ b/tests/unit/sync/sync-lock.test.ts
@@ -440,6 +440,260 @@ describe('SyncLockManager', () => {
       expect(result.entries).toEqual({});
     });
 
+    describe('a lock file whose structure the repository controls', () => {
+      let warnSpy: jest.SpyInstance;
+
+      beforeEach(() => {
+        warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+      });
+
+      afterEach(() => {
+        warnSpy.mockRestore();
+      });
+
+      function writeLock(lock: unknown): void {
+        fs.writeFileSync(lockFilePath, JSON.stringify(lock));
+      }
+
+      function goodEntry(): unknown {
+        return {
+          source_hash: '185f8db32271',
+          source_text: 'Hello',
+          translations: {
+            de: {
+              hash: '185f8db32271',
+              translated_at: '2026-01-01T00:00:00.000Z',
+              status: 'translated',
+            },
+          },
+        };
+      }
+
+      function backups(): string[] {
+        return fs
+          .readdirSync(tmpDir)
+          .filter((name) => name.includes('.deepl-sync.lock.bak-'));
+      }
+
+      it('should drop a per-file map that is not an object', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: { 'locales/en.json': 'pwn' },
+          stats: { total_keys: 0, total_translations: 0, last_sync: 'x' },
+        });
+
+        const result = await manager.read();
+
+        expect(result.entries['locales/en.json']).toBeUndefined();
+      });
+
+      it('should drop a per-file map that is an array', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: { 'locales/en.json': [] },
+          stats: { total_keys: 0, total_translations: 0, last_sync: 'x' },
+        });
+
+        const result = await manager.read();
+
+        expect(result.entries['locales/en.json']).toBeUndefined();
+      });
+
+      it('should drop an entry that is not an object', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: { 'locales/en.json': { greeting: 'pwn' } },
+          stats: { total_keys: 1, total_translations: 0, last_sync: 'x' },
+        });
+
+        const result = await manager.read();
+
+        expect(result.entries['locales/en.json']).toEqual({});
+      });
+
+      it('should drop an entry with no translations container', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: {
+            'locales/en.json': { greeting: { source_hash: '185f8db32271' } },
+          },
+          stats: { total_keys: 1, total_translations: 0, last_sync: 'x' },
+        });
+
+        const result = await manager.read();
+
+        expect(result.entries['locales/en.json']).toEqual({});
+      });
+
+      it('should drop an entry whose translations is not an object', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: {
+            'locales/en.json': {
+              greeting: { source_hash: '185f8db32271', translations: 'pwn' },
+            },
+          },
+          stats: { total_keys: 1, total_translations: 1, last_sync: 'x' },
+        });
+
+        const result = await manager.read();
+
+        expect(result.entries['locales/en.json']).toEqual({});
+      });
+
+      it('should drop a null translation and keep the entry it sat in', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: {
+            'locales/en.json': {
+              greeting: {
+                source_hash: '185f8db32271',
+                source_text: 'Hello',
+                translations: {
+                  de: null,
+                  es: {
+                    hash: '185f8db32271',
+                    translated_at: '2026-01-01T00:00:00.000Z',
+                    status: 'translated',
+                  },
+                },
+              },
+            },
+          },
+          stats: { total_keys: 1, total_translations: 2, last_sync: 'x' },
+        });
+
+        const result = await manager.read();
+
+        const entry = result.entries['locales/en.json']!['greeting']!;
+        expect(Object.keys(entry.translations)).toEqual(['es']);
+      });
+
+      it('should keep the well-formed entries beside the dropped ones', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: {
+            'locales/en.json': { greeting: goodEntry(), farewell: 'pwn' },
+          },
+          stats: { total_keys: 2, total_translations: 1, last_sync: 'x' },
+        });
+
+        const result = await manager.read();
+
+        expect(Object.keys(result.entries['locales/en.json']!)).toEqual([
+          'greeting',
+        ]);
+      });
+
+      it('should recompute stats rather than believe what the file claims', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: { 'locales/en.json': { greeting: goodEntry() } },
+          stats: {
+            total_keys: 999,
+            total_translations: 999,
+            last_sync: '2020-01-01T00:00:00.000Z',
+          },
+        });
+
+        const result = await manager.read();
+
+        expect(result.stats.total_keys).toBe(1);
+        expect(result.stats.total_translations).toBe(1);
+      });
+
+      it.each([
+        ['missing', undefined],
+        ['a string', 'pwn'],
+        ['an array', []],
+        ['null', null],
+      ])('should synthesize stats when the field is %s', async (_, stats) => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: { 'locales/en.json': { greeting: goodEntry() } },
+          stats,
+        });
+
+        const result = await manager.read();
+
+        expect(result.stats.total_keys).toBe(1);
+        expect(result.stats.total_translations).toBe(1);
+        expect(typeof result.stats.last_sync).toBe('string');
+      });
+
+      it('should warn and back up the file when it drops anything', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: { 'locales/en.json': { greeting: 'pwn' } },
+          stats: { total_keys: 1, total_translations: 0, last_sync: 'x' },
+        });
+
+        await manager.read();
+
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('malformed')
+        );
+        expect(backups()).toHaveLength(1);
+      });
+
+      it('should neither warn nor back up a well-formed lock file', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: { 'locales/en.json': { greeting: goodEntry() } },
+          stats: { total_keys: 1, total_translations: 1, last_sync: 'x' },
+        });
+
+        await manager.read();
+
+        expect(warnSpy).not.toHaveBeenCalled();
+        expect(backups()).toHaveLength(0);
+      });
+
+      it('should degrade to a full sync when entries is an array', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: [],
+          stats: { total_keys: 0, total_translations: 0, last_sync: 'x' },
+        });
+
+        const result = await manager.read();
+
+        expect(Array.isArray(result.entries)).toBe(false);
+        expect(result.entries).toEqual({});
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('entries')
+        );
+        expect(backups()).toHaveLength(1);
+      });
+
+      it('should survive a write after repairing what it read', async () => {
+        writeLock({
+          version: LOCK_FILE_VERSION,
+          source_locale: 'en',
+          entries: { 'locales/en.json': { greeting: goodEntry() } },
+        });
+
+        const result = await manager.read();
+        await manager.write(result);
+
+        const reread = await manager.read();
+        expect(reread.stats.total_keys).toBe(1);
+        expect(reread.entries['locales/en.json']!['greeting']).toBeDefined();
+      });
+    });
+
     it('should read lock file with multiple entries', async () => {
       const lockFile: SyncLockFile = {
         _comment: LOCK_FILE_COMMENT,

From be4d139ccaa5926005c71f98e55d96db7dc69986 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 21:06:54 +0200
Subject: [PATCH 145/256] fix(formats): stop dropping an .arb key that collides
 with Object.prototype
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

arb.ts gated new-key insertion on `key in data`, and `in` reports inherited
members, so `toString`, `valueOf`, `constructor`, `hasOwnProperty`,
`isPrototypeOf` and `__proto__` all read as already present and their
translations were discarded. json.ts documents the same defect as fixed,
with the reason in a comment above its check.

The trigger is a source file gaining a key, not a first sync: sync seeds a
new target from the source, so those keys arrive on the in-place path. It is
the second run, inserting into a target that already exists, that loses
them. Reproduced end to end — adding `hasOwnProperty` and `constructor` to
app_en.arb reported "✓ de: 3/3 keys" and "3 new", wrote one of the three to
app_de.arb and exited 0. The lockfile records all three as translated, so
the next run reports "6 current" and never retries them: the strings are
lost permanently and silently rather than re-billed.

Insertion now tests Object.hasOwn and writes through setOwnMember, so a key
named `__proto__` becomes an own property rather than reaching the prototype
setter.

setOwnMember/getOwnMember move to utils/own-members.ts to make that
possible: formats/ importing from sync/ would invert the dependency, and a
third copy of the same defineProperty helper was not worth writing. The five
sync modules that use them are unchanged apart from the import path.

Refs cli-8kr2.29
---
 CHANGELOG.md                       |  3 ++
 src/formats/arb.ts                 | 11 ++++--
 src/sync/sync-differ.ts            |  3 +-
 src/sync/sync-locale-translator.ts |  2 +-
 src/sync/sync-lock.ts              | 33 +----------------
 src/sync/sync-process-bucket.ts    |  8 +---
 src/sync/sync-status.ts            |  3 +-
 src/sync/sync-tms.ts               |  3 +-
 src/utils/own-members.ts           | 30 +++++++++++++++
 tests/e2e/cli-sync.e2e.test.ts     | 50 +++++++++++++++++++++++++
 tests/unit/formats/arb.test.ts     | 59 ++++++++++++++++++++++++++++++
 11 files changed, 159 insertions(+), 46 deletions(-)
 create mode 100644 src/utils/own-members.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 23c7e12e..8ac44a7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -113,6 +113,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **formats**: **an `.arb` key whose name collides with an `Object.prototype` member is no longer dropped from the file it was billed for.** `arb.ts` gated new-key insertion on `key in data`, and `in` reports inherited members — so `toString`, `valueOf`, `constructor`, `hasOwnProperty`, `isPrototypeOf` and `__proto__` all read as already present and their translations were discarded. The sibling `json.ts` documents this exact defect as fixed, with the reason in a comment above the check; same repo, same class, one fixed and one not. Measured at the parser: asked to insert six keys into a target that lacked them, `arb` dropped five and `json` dropped none. **The trigger is a source file gaining a key**, not a first sync — sync seeds a new target from the source, so the keys land on the in-place path; it is the second run, inserting into a target that already exists, that loses them. Reproduced end to end against a mock endpoint: adding `hasOwnProperty` and `constructor` to `app_en.arb` reported `✓ de: 3/3 keys` and `Sync complete: 3 new`, wrote only the third key to `app_de.arb`, and exited 0. The lockfile records all three as translated, so the next run reports `6 current` and **never retries them** — the strings are lost silently and permanently rather than re-billed each run. Insertion now tests `Object.hasOwn` and writes through the shared `setOwnMember`, so a key named `__proto__` becomes an own property instead of reaching the prototype setter. `setOwnMember`/`getOwnMember` moved from `sync/sync-lock.ts` to `utils/own-members.ts` for this: `formats/` cannot import from `sync/` without inverting the dependency, and a third copy of the same `defineProperty` helper was not worth writing. No behaviour change for the five sync modules that use them.
+
+
 - **logger**: **a short credential value no longer corrupts every diagnostic message.** The redactor's last step substring-replaced the literal credential with `[REDACTED]`, with no length floor and no token boundary, so any message containing the value inside an ordinary word was mangled. With `DEEPL_API_KEY=k` — a mistyped or throwaway value — a single real CLI run against a closed port printed `Warning: sending your DeepL API [REDACTED]ey to …`, `Error: Networ[REDACTED] error: connect ECONNREFUSED`, `Suggestion: Chec[REDACTED] your internet connection and proxy settings`, and a config path rendered as `/Users/[REDACTED]wey/…`: four lines of nonsense at the moment the user most needs to read them, and the mangling was itself how this was noticed, in the harness output of two unrelated findings. A literal value is now only replaced when it is **at least 8 characters**; below that, the auth-header and `token=`/`api_key=` query-parameter patterns still apply, so nothing that is shaped like a credential in transit goes unredacted. A real DeepL key is UUID-shaped with a `:fx` or hyphenated suffix and TMS credentials are longer still, so the floor excludes nothing genuine — the shortest key in this repo's own test suites is 12 characters. The alternative of matching on a token boundary was rejected: it would silently **miss** a real key printed immediately before a word character, which is the more expensive of the two errors, where a floor can only fail to redact a value too short to be a credential.
 
 - **sync**: **the `Sync complete:` summary names how many translations failed**, instead of reading as though every diffed key had landed. The key counts in that line come from the diff, not from what was successfully translated, so a run that translated 50 of 200 keys and rate-limited on the rest printed `✗ de: 50/200 keys` and then `Sync complete: 200 new` directly beneath it — two lines flatly contradicting each other, with the accurate one being the easier to miss in a CI log. It now reads `Sync complete: 200 new (150 translations failed)`. The count totals every locale, and nothing is appended when nothing failed. Exit code 12 on partial failure is unchanged, as are the diff counts themselves, which were accurate about the diff all along.
diff --git a/src/formats/arb.ts b/src/formats/arb.ts
index 778c055b..1ff59b30 100644
--- a/src/formats/arb.ts
+++ b/src/formats/arb.ts
@@ -4,6 +4,7 @@ import type {
   TranslatedEntry,
 } from './format.js';
 import { detectIndent } from './util/detect-indent.js';
+import { setOwnMember } from '../utils/own-members.js';
 
 /** JSON.parse rejects a leading BOM, which editors on Windows add routinely. */
 function stripBom(content: string): string {
@@ -72,15 +73,19 @@ export class ArbFormatParser implements FormatParser {
     for (const key of Object.keys(data)) {
       if (!key.startsWith('@') && !translations.has(key)) {
         delete data[key];
-        if (`@${key}` in data) {
+        if (Object.hasOwn(data, `@${key}`)) {
           delete data[`@${key}`];
         }
       }
     }
 
+    // Own-property tests, not `key in data`: an i18n key named `toString` or
+    // `__proto__` collides with an Object.prototype member, so a membership test
+    // reports it as already present and the translation is dropped from the file
+    // it was billed for.
     for (const [key, translation] of translations) {
-      if (!(key in data)) {
-        data[key] = translation;
+      if (!Object.hasOwn(data, key)) {
+        setOwnMember(data, key, translation);
       }
     }
 
diff --git a/src/sync/sync-differ.ts b/src/sync/sync-differ.ts
index 437a958a..d4af3fc3 100644
--- a/src/sync/sync-differ.ts
+++ b/src/sync/sync-differ.ts
@@ -1,6 +1,7 @@
 import type { ExtractedEntry } from '../formats/format.js';
 import type { SyncLockEntry, SyncDiff } from './types.js';
-import { computeSourceHash, getOwnMember } from './sync-lock.js';
+import { computeSourceHash } from './sync-lock.js';
+import { getOwnMember } from '../utils/own-members.js';
 
 /**
  * Is any of `targetLocales` out of date for this entry?
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 5c0a649f..e31b2205 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -15,7 +15,7 @@ import {
   mergeInstructions,
   generateLengthInstruction,
 } from './sync-instructions.js';
-import { getOwnMember } from './sync-lock.js';
+import { getOwnMember } from '../utils/own-members.js';
 import { validateBatch } from './translation-validator.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
diff --git a/src/sync/sync-lock.ts b/src/sync/sync-lock.ts
index 411c6357..316b4c19 100644
--- a/src/sync/sync-lock.ts
+++ b/src/sync/sync-lock.ts
@@ -2,41 +2,10 @@ import * as fs from 'fs';
 import * as crypto from 'crypto';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { Logger } from '../utils/logger.js';
+import { getOwnMember, setOwnMember } from '../utils/own-members.js';
 import type { SyncLockFile, SyncLockEntry } from './types.js';
 import { LOCK_FILE_VERSION, LOCK_FILE_COMMENT } from './types.js';
 
-/**
- * Stores an own, enumerable member. Plain assignment cannot be used: an i18n
- * key or a source path named `__proto__` reaches the prototype setter instead
- * of creating a property, so the member never lands in the lockfile and the key
- * is re-translated and re-billed on every run.
- */
-export function setOwnMember<T>(
-  map: Record<string, T>,
-  key: string,
-  value: T
-): void {
-  Object.defineProperty(map, key, {
-    value,
-    writable: true,
-    enumerable: true,
-    configurable: true,
-  });
-}
-
-/**
- * Reads a member only when the map actually holds one. Plain indexing hands
- * back inherited `Object.prototype` members for keys named `constructor`,
- * `toString`, `valueOf` and `hasOwnProperty`, which read as an existing entry
- * that happens to be missing every field it should have.
- */
-export function getOwnMember<T>(
-  map: Record<string, T>,
-  key: string
-): T | undefined {
-  return Object.hasOwn(map, key) ? map[key] : undefined;
-}
-
 /** The per-file entry map, created on demand and setter-proof either way. */
 export function ensureFileEntries(
   lockFile: SyncLockFile,
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index ab4d0efa..c33613cb 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -7,12 +7,8 @@ import {
 } from '../utils/concurrency.js';
 import { ValidationError } from '../utils/errors.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
-import {
-  computeSourceHash,
-  ensureFileEntries,
-  getOwnMember,
-  setOwnMember,
-} from './sync-lock.js';
+import { computeSourceHash, ensureFileEntries } from './sync-lock.js';
+import { getOwnMember, setOwnMember } from '../utils/own-members.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncLockFile, SyncLockTranslation } from './types.js';
 import type { KeyContext } from './sync-context.js';
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index ebb2345b..8b123d6f 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -1,6 +1,7 @@
 import * as path from 'path';
 import type { FormatRegistry } from '../formats/index.js';
-import { SyncLockManager, getOwnMember } from './sync-lock.js';
+import { SyncLockManager } from './sync-lock.js';
+import { getOwnMember } from '../utils/own-members.js';
 import { computeDiff } from './sync-differ.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import { LOCK_FILE_NAME } from './types.js';
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index e9be9117..dc18cc0b 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -7,9 +7,8 @@ import {
   SyncLockManager,
   computeSourceHash,
   ensureFileEntries,
-  getOwnMember,
-  setOwnMember,
 } from './sync-lock.js';
+import { getOwnMember, setOwnMember } from '../utils/own-members.js';
 import {
   resolveTargetPath,
   assertPathWithinRoot,
diff --git a/src/utils/own-members.ts b/src/utils/own-members.ts
new file mode 100644
index 00000000..efaf669d
--- /dev/null
+++ b/src/utils/own-members.ts
@@ -0,0 +1,30 @@
+/**
+ * Stores an own, enumerable member. Plain assignment cannot be used: a key named
+ * `__proto__` reaches the prototype setter instead of creating a property, so
+ * the member never lands in the object it was meant for.
+ */
+export function setOwnMember<T>(
+  map: Record<string, T>,
+  key: string,
+  value: T
+): void {
+  Object.defineProperty(map, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}
+
+/**
+ * Reads a member only when the map actually holds one. Plain indexing hands
+ * back inherited `Object.prototype` members for keys named `constructor`,
+ * `toString`, `valueOf` and `hasOwnProperty`, which read as an existing member
+ * that happens to be missing every field it should have.
+ */
+export function getOwnMember<T>(
+  map: Record<string, T>,
+  key: string
+): T | undefined {
+  return Object.hasOwn(map, key) ? map[key] : undefined;
+}
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 1096dbcf..34f7ea93 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -249,6 +249,56 @@ describe('CLI Sync E2E', () => {
     });
   });
 
+  // A key colliding with an Object.prototype member reaches the insertion path
+  // the second time round: the target file already exists, so a key the source
+  // has just gained has to be added to it.
+  describe('an .arb key named like an Object.prototype member', () => {
+    const sourcePath = () => path.join(testFiles.path, 'locales', 'app_en.arb');
+    const targetPath = () => path.join(testFiles.path, 'locales', 'app_de.arb');
+
+    function writeArbConfig(): void {
+      const yaml =
+        [
+          'version: 1',
+          'source_locale: en',
+          'target_locales:',
+          '  - de',
+          'buckets:',
+          '  arb:',
+          '    include:',
+          '      - "locales/app_en.arb"',
+        ].join('\n') + '\n';
+      fs.writeFileSync(path.join(testFiles.path, '.deepl-sync.yaml'), yaml);
+    }
+
+    function writeSource(keys: Record<string, string>): void {
+      fs.mkdirSync(path.join(testFiles.path, 'locales'), { recursive: true });
+      fs.writeFileSync(sourcePath(), JSON.stringify(keys, null, 2) + '\n');
+    }
+
+    it('should write a key the source gained into the existing target', () => {
+      writeArbConfig();
+      writeSource({ greeting: 'Hello' });
+      runSyncAll();
+
+      writeSource({
+        greeting: 'Hello',
+        toString: 'Convert to text',
+        hasOwnProperty: 'Check the property',
+        plainNewKey: 'A plain new key',
+      });
+      const output = runSyncAll();
+
+      expect(output).toContain('Sync complete');
+      const written = JSON.parse(
+        fs.readFileSync(targetPath(), 'utf-8')
+      ) as Record<string, unknown>;
+      expect(Object.hasOwn(written, 'toString')).toBe(true);
+      expect(Object.hasOwn(written, 'hasOwnProperty')).toBe(true);
+      expect(Object.hasOwn(written, 'plainNewKey')).toBe(true);
+    });
+  });
+
   describe('a lock file the repository controls', () => {
     const lockPath = () => path.join(testFiles.path, '.deepl-sync.lock');
 
diff --git a/tests/unit/formats/arb.test.ts b/tests/unit/formats/arb.test.ts
index 90f51a21..345ed7c9 100644
--- a/tests/unit/formats/arb.test.ts
+++ b/tests/unit/formats/arb.test.ts
@@ -64,6 +64,65 @@ describe('arb parser', () => {
     });
   });
 
+  // A key colliding with an Object.prototype member is plausible in a real
+  // Flutter project, and the insertion path is reached whenever the source gains
+  // a key the existing target file does not have.
+  describe('reconstruct inserts a key that collides with Object.prototype', () => {
+    const COLLIDING = [
+      'toString',
+      'valueOf',
+      'constructor',
+      'hasOwnProperty',
+      'isPrototypeOf',
+      '__proto__',
+    ];
+
+    const template = JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n';
+
+    it.each(COLLIDING)('should insert a key named %s', (key) => {
+      const entries: TranslatedEntry[] = [
+        { key: 'greeting', value: 'Hello', translation: 'Hola' },
+        { key, value: `Source ${key}`, translation: `Translated ${key}` },
+      ];
+
+      const parsed = JSON.parse(
+        parser.reconstruct(template, entries)
+      ) as Record<string, unknown>;
+
+      expect(Object.hasOwn(parsed, key)).toBe(true);
+      expect(parsed[key]).toBe(`Translated ${key}`);
+    });
+
+    it('should insert every colliding key in one pass', () => {
+      const entries: TranslatedEntry[] = COLLIDING.map((key) => ({
+        key,
+        value: `Source ${key}`,
+        translation: `Translated ${key}`,
+      }));
+
+      const parsed = JSON.parse(
+        parser.reconstruct(template, entries)
+      ) as Record<string, unknown>;
+
+      expect(Object.keys(parsed).sort()).toEqual([...COLLIDING].sort());
+    });
+
+    it('should not reach the prototype setter when inserting __proto__', () => {
+      const entries: TranslatedEntry[] = [
+        { key: '__proto__', value: 'Source', translation: 'Translated' },
+      ];
+
+      const parsed = JSON.parse(
+        parser.reconstruct(template, entries)
+      ) as Record<string, unknown>;
+
+      expect(Object.getPrototypeOf(parsed)).toBe(Object.prototype);
+      expect(({} as Record<string, unknown>)['__proto__']).toBe(
+        Object.prototype
+      );
+    });
+  });
+
   describe('reconstruct() applies translations to existing keys', () => {
     it('should update values for all existing keys', () => {
       const content =

From f6c8079403fb3bc69db31227bc7ae9829a366625 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 21:41:23 +0200
Subject: [PATCH 146/256] fix(sync): decide a translation is usable before
 writing it, not after
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The placeholder/ICU validator ran after the target file was written, after the
lockfile was committed, and after the `.deepl.bak` backups were unlinked, so it
could neither prevent nor roll back anything. Its results were counted and
never acted on, and `validation.fail_on_error` defaults to false, so a run that
lost a placeholder printed one line of `1 validation error(s)` and exited 0
with the corrupt value on disk and the key recorded `translated` — which the
next run reads as `current` and never retries.

The new-locale backfill path was not validated at all: keys already `current`
in the lockfile are translated in a second batch that never reached
`validateBatch`, so adding a target locale wrote corrupt output at exit 0 with
zero validation errors reported.

An `error`-severity result now decides acceptance before the write, on both
paths. A withheld key is counted as failed and recorded `status: "failed"`, so
the run is a partial failure (exit 12, or 6 with `fail_on_error`) and the next
sync retries it. Warnings are unaffected.

Two things a naive exclusion gets wrong, both measured:

- Leaving the entry out deletes the key. The entry list is the complete desired
  key set a parser reconstructs from, so omitting a withheld key removed it
  from the target file along with any previous translation. A withheld key now
  carries whatever the target file already held, as an untouched `current` key
  does.
- The plural write-backs copy translated text into the metadata the PO and
  Android parsers reconstruct from. They are skipped for withheld entries, or
  the forms would go in corrupt behind a preserved scalar.

`fail_on_error` keeps its `false` default: the protection no longer depends on
it, and the flag retains its documented meaning of promoting a partial failure
to a hard `ValidationError`. Backups are still cleaned up, since the corrupt
value never reaches the file and a retained backup would make the next run
report an unfinished earlier run that did not happen.

Refs cli-8kr2.30
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   2 +
 docs/SYNC.md                                  |  20 +-
 src/sync/sync-locale-translator.ts            | 189 ++++++++++--
 src/sync/sync-message-preprocess.ts           |  11 +-
 .../sync-validation-gate.integration.test.ts  | 207 +++++++++++++
 .../unit/sync/sync-locale-translator.test.ts  | 284 ++++++++++++++++++
 tests/unit/sync/sync-service.test.ts          |   4 +-
 8 files changed, 687 insertions(+), 34 deletions(-)
 create mode 100644 tests/integration/sync-validation-gate.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ac44a7c..3571d45b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **a validation error now fails the run.** `deepl sync` previously exited 0 with a one-line `N validation error(s)` warning while writing the corrupt translation; the key is now withheld and counted as failed, so the run exits 12 (`PartialFailure`) — or 6 with `validation.fail_on_error: true`, as before. CI that treats `deepl sync` exit 0 as "translations are complete and correct" gets the right answer for the first time; CI that ignored the warning line starts failing on input it was already mistranslating. `SyncResult.success` is `false` for the same runs. See Fixed for the measurements and for why the `fail_on_error` default was left alone.
+
 - **hooks**: **`deepl hooks list --format json` reports a state string per hook instead of a boolean** — `"installed"`, `"modified"`, `"unverified"` or `"not-installed"` (see Security for why a boolean could not tell the truth). Scripts must gate on `state === "installed"`; a truthiness test now passes for every state, `"not-installed"` included, so it has to be replaced rather than left alone. The text output gains the same distinction, and a hook you customized by hand — which the README invites — reports `!` from then on, since its body no longer matches the hash recorded at install. `GitHooksService.list()` returns those states as well; `isInstalled()` still answers the narrower "a DeepL marker is present" question and is unchanged.
 
 - **translate**: **`--tag-handling` requests now pin `tag_handling_version=v2`** instead of letting the API pick. The CLI previously sent the parameter only when `--tag-handling-version` was passed, so everyone else inherited the server default — which DeepL documents as moving from v1 (deprecation-bound) to v2 at an unannounced date. That flip would have changed tag-handling output with no CLI change to point at, and worse, would have gone unnoticed by the cache: a request that omits the version hashes identically before and after, so cached v1 output would have kept being served after the API started returning v2. Adopting v2 now makes that one output shift deliberate and dated, and DeepL's own docs recommend v2 for structure handling. **`--tag-handling xml`/`html` output may differ from previous releases**; pass `--tag-handling-version v1` to keep the old behaviour, which is still honoured and always wins over the default. Requests without `--tag-handling` send no version. Cached translations from earlier versions are retired on first open regardless — see the cache entry under Fixed — so no tag-handling entry can be served stale.
@@ -113,6 +115,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a translation the engine corrupted is withheld from the target file instead of being written and recorded as done.** The placeholder/ICU validator is the only defence against corrupt machine output, and it ran too late to be one: the write at `sync-locale-translator.ts` happened first, then the lockfile, then the `.deepl.bak` backups were unlinked, and only then was `validation.fail_on_error` consulted. Its results were counted, never acted on. Measured against a mock endpoint that drops the `__VAR_n__` tokens the CLI substitutes for placeholders: `"greeting": "Hello {name}, welcome back"` reported `✓ de: 2/2 keys`, `Sync complete: 2 new`, one line of `1 validation error(s)`, and **exit 0** — with `de.json` holding `"[DE] Hello , welcome back"`, the lockfile recording the key `translated`, and the next run reporting `2 current` and never retrying, so the placeholder was gone permanently. `fail_on_error: true` only changed the exit code to 6 after the same damage was done, and where the target file already existed the previous good translation had been overwritten and its backup deleted on the way out. **The new-locale backfill path was not validated at all**: adding `fr` to `target_locales` translated the already-`current` keys through a second batch that never reached `validateBatch`, so `fr.json` was written corrupt at `✓ fr: 2/2 keys`, exit 0, and **zero validation errors reported** — the bulk-translation case was the silent one. An `error`-severity result (a lost placeholder, an ICU bracket or selector rewritten) is now decided before the write, on both paths: the key is withheld, counted as failed, and recorded `status: "failed"`, so the same run reads `✗ de: 1/2 keys`, `Sync complete: 2 new (1 translations failed)`, exit 12, and the next run retries the key. Warnings still pass through and are still written. Two things the fix cannot do naively: simply leaving the entry out **deletes** the key, because the entry list is the complete desired key set a parser reconstructs from — measured, `de.json` lost `greeting` entirely and a previous `"Hallo {name}, willkommen zurueck"` with it — so a withheld key now carries whatever the target file already held, exactly as an untouched `current` key does; and the plural write-backs, which copy translated text into the metadata the PO and Android parsers reconstruct from, are skipped for withheld entries, or the forms would have gone in corrupt behind a preserved scalar. `validation.fail_on_error` keeps its `false` default rather than being flipped: a withheld key already fails the run, so the protection no longer depends on the setting, and the flag retains its documented meaning of promoting that to a hard `ValidationError`. The backups are still cleaned up on the way out — with the corrupt value never written, there is nothing to roll back to, and keeping them would make the next run report an unfinished earlier run that did not happen.
+
 - **formats**: **an `.arb` key whose name collides with an `Object.prototype` member is no longer dropped from the file it was billed for.** `arb.ts` gated new-key insertion on `key in data`, and `in` reports inherited members — so `toString`, `valueOf`, `constructor`, `hasOwnProperty`, `isPrototypeOf` and `__proto__` all read as already present and their translations were discarded. The sibling `json.ts` documents this exact defect as fixed, with the reason in a comment above the check; same repo, same class, one fixed and one not. Measured at the parser: asked to insert six keys into a target that lacked them, `arb` dropped five and `json` dropped none. **The trigger is a source file gaining a key**, not a first sync — sync seeds a new target from the source, so the keys land on the in-place path; it is the second run, inserting into a target that already exists, that loses them. Reproduced end to end against a mock endpoint: adding `hasOwnProperty` and `constructor` to `app_en.arb` reported `✓ de: 3/3 keys` and `Sync complete: 3 new`, wrote only the third key to `app_de.arb`, and exited 0. The lockfile records all three as translated, so the next run reports `6 current` and **never retries them** — the strings are lost silently and permanently rather than re-billed each run. Insertion now tests `Object.hasOwn` and writes through the shared `setOwnMember`, so a key named `__proto__` becomes an own property instead of reaching the prototype setter. `setOwnMember`/`getOwnMember` moved from `sync/sync-lock.ts` to `utils/own-members.ts` for this: `formats/` cannot import from `sync/` without inverting the dependency, and a third copy of the same `defineProperty` helper was not worth writing. No behaviour change for the five sync modules that use them.
 
 
diff --git a/docs/API.md b/docs/API.md
index dc6f1f1f..8be62181 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3434,6 +3434,8 @@ Remediation: open `.deepl-sync.lock`, resolve the remaining `<<<<<<<` / `=======
 
 `deepl sync` completed, but at least one key failed to translate. This covers both a locale that failed entirely and a locale that translated some of its keys and failed the rest — a failed key is absent from the written target file, so any failure count above zero means the run did not produce a complete result. The successful translations' target files and lockfile entries are written; a locale that failed entirely has its file left untouched. Emitted only by `deepl sync` (the root command).
 
+A key whose translation failed placeholder/ICU validation counts as failed here too: it is withheld from the target file rather than written corrupt. See [`validation`](SYNC.md#validation) in the sync configuration reference. With `validation.fail_on_error: true` the same run raises `ValidationError` (exit 6) instead.
+
 Authentication failures (401/403) abort the entire run and surface as exit code 2 (`AuthError`) instead of 12. Network / rate-limit / quota failures bubble up as 5 / 3 / 4 respectively. Code 12 specifically means "the run proceeded far enough to attempt per-locale work, and the result was mixed."
 
 **Retry model.** Re-running `deepl sync` (optionally with `--locale <failed,comma,separated>`) will retry only the locales whose lockfile entries weren't written. This is the canonical CI recovery path: branch on `$? -eq 12`, inspect the per-locale error report, and re-run with the failed locales as the filter.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 5baa6b04..5a210c31 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -260,12 +260,26 @@ In JSON output (`--format json`), the `strategy` field provides the breakdown:
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `check_placeholders` | `boolean` | No | `true` | Validate placeholder preservation in translations |
-| `fail_on_error` | `boolean` | No | `false` | Fail sync when validation errors are detected |
-| `validate_after_sync` | `boolean` | No | `true` | Run validation after each sync |
+| `check_placeholders` | `boolean` | No | `true` | Validate placeholder and ICU preservation in translations. Set `false` to write translations that fail validation |
+| `fail_on_error` | `boolean` | No | `false` | Raise `ValidationError` (exit 6) instead of finishing as a partial failure when validation errors are detected |
+| `validate_after_sync` | `boolean` | No | `true` | Run validation on each translation before it is written |
 | `fail_on_missing` | `boolean` | No | `true` | With `--frozen`, fail on new/missing translations |
 | `fail_on_stale` | `boolean` | No | `true` | With `--frozen`, fail on stale (source-changed) translations |
 
+**Corrupt translations are withheld, not written.** A translation that loses a
+placeholder or has its ICU structure rewritten by the engine (an
+`error`-severity check) never reaches the target file. The key keeps whatever
+the target file already held, the lock records it as `status: "failed"`, and the
+next sync retries it — so a run with validation errors reports at least one
+failed key and exits 12 (or 6 with `fail_on_error: true`). Warnings — an extra
+placeholder, a missing HTML tag, an untranslated string, an unusual length
+ratio — are reported but still written.
+
+Because a withheld key is retried, an engine that keeps returning the same
+corrupt output is billed again on every run. The warning names the affected keys
+and the check that rejected them; set `check_placeholders: false` to accept the
+output instead, or fix the source string.
+
 #### `sync`
 
 | Field | Type | Required | Default | Description |
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index e31b2205..1ed932a9 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -16,7 +16,10 @@ import {
   generateLengthInstruction,
 } from './sync-instructions.js';
 import { getOwnMember } from '../utils/own-members.js';
-import { validateBatch } from './translation-validator.js';
+import {
+  validateBatch,
+  type ValidationResult,
+} from './translation-validator.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
@@ -50,6 +53,88 @@ export interface LocaleTranslatorContext {
   isMultiLocale: boolean;
 }
 
+interface ScreenedTranslations {
+  /** Entries safe to write. */
+  accepted: TranslatedEntry[];
+  /** Entries withheld because a check reported `error` severity. */
+  withheld: ValidationResult[];
+  warnings: number;
+  errors: number;
+}
+
+/**
+ * Split freshly translated entries into the ones that may be written and the
+ * ones a validation check rejected.
+ *
+ * An entry with an `error`-severity issue has lost a placeholder or had its ICU
+ * structure rewritten by the engine, so writing it would put machine
+ * scaffolding into the user's locale file. The caller keeps whatever the target
+ * file already held for a withheld key and counts it as failed, so the lockfile
+ * records `failed` and the next sync retries it.
+ */
+function screenTranslations(
+  entries: readonly TranslatedEntry[],
+  config: ResolvedSyncConfig
+): ScreenedTranslations {
+  if (
+    entries.length === 0 ||
+    config.validation?.validate_after_sync === false ||
+    config.validation?.check_placeholders === false
+  ) {
+    return { accepted: [...entries], withheld: [], warnings: 0, errors: 0 };
+  }
+
+  const results = validateBatch(
+    entries.map((e) => ({
+      key: e.key,
+      source: e.value,
+      translation: e.translation,
+    }))
+  );
+
+  const accepted: TranslatedEntry[] = [];
+  const withheld: ValidationResult[] = [];
+  let warnings = 0;
+  let errors = 0;
+
+  for (let i = 0; i < entries.length; i++) {
+    const result = results[i];
+    for (const issue of result?.issues ?? []) {
+      if (issue.severity === 'warn') warnings++;
+      if (issue.severity === 'error') errors++;
+    }
+    if (result?.severity === 'error') {
+      withheld.push(result);
+    } else {
+      accepted.push(entries[i]!);
+    }
+  }
+
+  return { accepted, withheld, warnings, errors };
+}
+
+function withheldKeysWarning(
+  locale: string,
+  targetRelPath: string,
+  withheld: readonly ValidationResult[]
+): string {
+  const shown = withheld.slice(0, 3).map((w) => {
+    const first =
+      w.issues.find((i) => i.severity === 'error')?.message ??
+      'validation error';
+    return `"${w.key}" (${first})`;
+  });
+  const more = withheld.length > shown.length ? ', …' : '';
+  const one = withheld.length === 1;
+  return (
+    `${locale}: withheld ${withheld.length} ${one ? 'translation' : 'translations'} from ` +
+    `${targetRelPath} that failed validation: ${shown.join(', ')}${more}. ` +
+    `${one ? 'It was' : 'They were'} not written and ${one ? 'is' : 'are'} recorded as failed, ` +
+    `so the next sync retries ${one ? 'it' : 'them'}. Set validation.check_placeholders: false ` +
+    `to write ${one ? 'it' : 'them'} anyway.`
+  );
+}
+
 export interface TranslateLocaleResult {
   fileResult: SyncFileResult;
   successfulKeys: string[];
@@ -513,12 +598,41 @@ export class LocaleTranslator {
       icuMappings,
       baseTranslationOpts
     );
-    writebackPlurals(results, pluralSlots, localeDiffs);
+    // Validate before the plural write-backs below, which mutate the metadata
+    // the parser reconstructs from: a withheld entry has to leave those forms in
+    // the state an untouched key's would be in. `result.text` is already final
+    // here — the write-backs only copy it into metadata.
+    const screened = screenTranslations(
+      localeDiffs.flatMap((diff, i) => {
+        const result = results[i];
+        return result && diff.value !== undefined
+          ? [
+              {
+                key: diff.key,
+                value: diff.value,
+                translation: result.text,
+                metadata: diff.metadata,
+              },
+            ]
+          : [];
+      }),
+      config
+    );
+    const withheld: ValidationResult[] = [...screened.withheld];
+    const withheldKeys = new Set(screened.withheld.map((w) => w.key));
+    let localeValidationWarnings = screened.warnings;
+    let localeValidationErrors = screened.errors;
+
+    const withheldDiffIndices = new Set(
+      localeDiffs.flatMap((diff, i) => (withheldKeys.has(diff.key) ? [i] : []))
+    );
+
+    writebackPlurals(results, pluralSlots, localeDiffs, withheldDiffIndices);
 
     for (let i = 0; i < localeDiffs.length; i++) {
       const diff = localeDiffs[i]!;
       const result = results[i];
-      if (!result || !diff.metadata) continue;
+      if (!result || !diff.metadata || withheldDiffIndices.has(i)) continue;
 
       if (diff.metadata['msgid_plural'] !== undefined) {
         const forms =
@@ -545,6 +659,16 @@ export class LocaleTranslator {
       const diff = localeDiffs[i]!;
       const result = results[i];
       if (result && diff.value !== undefined) {
+        // Billed whether or not the translation is usable, so the reported
+        // spend and the lock entry both record what was actually charged.
+        if (result.billedCharacters) {
+          localeBilled += result.billedCharacters;
+          billedPerKey.set(diff.key, result.billedCharacters);
+        }
+        if (withheldKeys.has(diff.key)) {
+          failed++;
+          continue;
+        }
         translatedEntries.push({
           key: diff.key,
           value: diff.value,
@@ -552,10 +676,6 @@ export class LocaleTranslator {
           metadata: diff.metadata,
         });
         translated++;
-        if (result.billedCharacters) {
-          localeBilled += result.billedCharacters;
-          billedPerKey.set(diff.key, result.billedCharacters);
-        }
       } else {
         failed++;
       }
@@ -569,30 +689,26 @@ export class LocaleTranslator {
 
     const successfulKeys: string[] = translatedEntries.map((te) => te.key);
 
-    let localeValidationWarnings = 0;
-    let localeValidationErrors = 0;
-    if (
-      config.validation?.validate_after_sync !== false &&
-      config.validation?.check_placeholders !== false
-    ) {
-      const validationInputs = translatedEntries.map((e) => ({
-        key: e.key,
-        source: e.value,
-        translation: e.translation,
-      }));
-      const validationResults = validateBatch(validationInputs);
-      for (const vr of validationResults) {
-        for (const issue of vr.issues) {
-          if (issue.severity === 'warn') localeValidationWarnings++;
-          if (issue.severity === 'error') localeValidationErrors++;
-        }
-      }
-    }
-
     // Use target file translations for current keys
     const existingTranslations =
       existingTargetEntries.get(locale) ?? new Map<string, string>();
     const allTranslatedEntries: TranslatedEntry[] = [...translatedEntries];
+
+    // A withheld key still needs an entry: the list is the complete desired key
+    // set, so leaving it out deletes the key from the target file rather than
+    // leaving it alone. Carry the value the target file already had — the same
+    // treatment a `current` key gets — and omit it only when the file has none.
+    for (const rejected of screened.withheld) {
+      const previous = existingTranslations.get(rejected.key);
+      if (previous === undefined) continue;
+      const diff = localeDiffs.find((d) => d.key === rejected.key);
+      allTranslatedEntries.push({
+        key: rejected.key,
+        value: rejected.source,
+        translation: previous,
+        metadata: diff?.metadata,
+      });
+    }
     const currentDiffs = diffs.filter((d) => d.status === 'current');
     const currentDiffByKey = new Map(currentDiffs.map((d) => [d.key, d]));
     const untranslatedCurrentKeys: string[] = [];
@@ -661,18 +777,18 @@ export class LocaleTranslator {
           }
         }
 
+        const newLocaleEntries: TranslatedEntry[] = [];
         for (let nli = 0; nli < untranslatedCurrentKeys.length; nli++) {
           const key = untranslatedCurrentKeys[nli]!;
           const cd = currentDiffByKey.get(key)!;
           const nlResult = newLocaleResults[nli];
           if (nlResult) {
-            allTranslatedEntries.push({
+            newLocaleEntries.push({
               key,
               value: cd.value!,
               translation: nlResult.text,
               metadata: cd.metadata,
             });
-            successfulKeys.push(key);
             translated++;
             if (nlResult.billedCharacters) {
               localeBilled += nlResult.billedCharacters;
@@ -685,6 +801,17 @@ export class LocaleTranslator {
             failed++;
           }
         }
+
+        const nlScreened = screenTranslations(newLocaleEntries, config);
+        localeValidationWarnings += nlScreened.warnings;
+        localeValidationErrors += nlScreened.errors;
+        withheld.push(...nlScreened.withheld);
+        translated -= nlScreened.withheld.length;
+        failed += nlScreened.withheld.length;
+        for (const entry of nlScreened.accepted) {
+          allTranslatedEntries.push(entry);
+          successfulKeys.push(entry.key);
+        }
       }
     }
 
@@ -699,6 +826,10 @@ export class LocaleTranslator {
     const targetAbsPath = path.join(config.projectRoot, targetRelPath);
     assertPathWithinRoot(targetAbsPath, config.projectRoot);
 
+    if (withheld.length > 0) {
+      Logger.warn(withheldKeysWarning(locale, targetRelPath, withheld));
+    }
+
     let templateContent = content;
     let targetExists = false;
     try {
diff --git a/src/sync/sync-message-preprocess.ts b/src/sync/sync-message-preprocess.ts
index 09ef8a6a..5bc4c1a8 100644
--- a/src/sync/sync-message-preprocess.ts
+++ b/src/sync/sync-message-preprocess.ts
@@ -149,14 +149,23 @@ export async function reassembleIcu(
   }
 }
 
+/**
+ * Copy translated plural forms into each diff's metadata, which is what the
+ * parsers reconstruct plural entries from.
+ *
+ * `skipDiffIndices` names diffs whose translation will not be written, so their
+ * metadata must keep the forms it was extracted with.
+ */
 export function writebackPlurals(
   results: (TranslationResult | null)[],
   pluralSlots: PluralSlot[],
-  localeDiffs: SyncDiff[]
+  localeDiffs: SyncDiff[],
+  skipDiffIndices?: ReadonlySet<number>
 ): void {
   for (const slot of pluralSlots) {
     const result = results[slot.textIndex];
     if (!result) continue;
+    if (skipDiffIndices?.has(slot.diffIndex)) continue;
     const diff = localeDiffs[slot.diffIndex]!;
     if (!diff.metadata) continue;
 
diff --git a/tests/integration/sync-validation-gate.integration.test.ts b/tests/integration/sync-validation-gate.integration.test.ts
new file mode 100644
index 00000000..14092f2a
--- /dev/null
+++ b/tests/integration/sync-validation-gate.integration.test.ts
@@ -0,0 +1,207 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as querystring from 'querystring';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+import { SyncService } from '../../src/sync/sync-service';
+import { TranslationService } from '../../src/services/translation';
+import { GlossaryService } from '../../src/services/glossary';
+import { DeepLClient } from '../../src/api/deepl-client';
+import { FormatRegistry } from '../../src/formats/index';
+import { JsonFormatParser } from '../../src/formats/json';
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { LOCK_FILE_NAME } from '../../src/sync/types';
+import type { SyncLockEntry } from '../../src/sync/types';
+import { DEEPL_FREE_API_URL, TEST_API_KEY } from '../helpers/nock-setup';
+import {
+  createMockConfigService,
+  createMockCacheService,
+} from '../helpers/mock-factories';
+
+const CONFIG_YAML = `version: 1
+source_locale: en
+target_locales:
+  - de
+buckets:
+  json:
+    include:
+      - "locales/en.json"
+`;
+
+function getTexts(body: unknown): string[] {
+  const parsed =
+    typeof body === 'string'
+      ? (querystring.parse(body) as Record<string, string | string[]>)
+      : (body as Record<string, string | string[]>);
+  const text = parsed['text'];
+  return Array.isArray(text) ? text : text ? [text] : [];
+}
+
+function createServices(): { client: DeepLClient; syncService: SyncService } {
+  const client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
+  const mockConfig = createMockConfigService({
+    get: jest.fn(() => ({
+      auth: {},
+      api: { baseUrl: '', usePro: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: false,
+      },
+      cache: { enabled: false },
+      output: { format: 'text', color: true },
+      proxy: {},
+    })),
+    getValue: jest.fn(() => false),
+  });
+  const registry = new FormatRegistry();
+  registry.register(new JsonFormatParser());
+  const syncService = new SyncService(
+    new TranslationService(client, mockConfig, createMockCacheService()),
+    new GlossaryService(client),
+    registry
+  );
+  return { client, syncService };
+}
+
+/**
+ * An engine that drops the `__VAR_n__` tokens the CLI substitutes for
+ * placeholders, so every string carrying a placeholder comes back corrupt and
+ * every string without one comes back fine.
+ */
+describe('Sync when the engine returns corrupt output', () => {
+  let tmpDir: string;
+  let client: DeepLClient;
+  let syncService: SyncService;
+  let sentTexts: string[][];
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-valgate-'));
+    const services = createServices();
+    client = services.client;
+    syncService = services.syncService;
+    sentTexts = [];
+    nock(DEEPL_FREE_API_URL)
+      .persist()
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => {
+        const texts = getTexts(body);
+        sentTexts.push(texts);
+        return {
+          translations: texts.map((t) => ({
+            text: `de:${t
+              .replace(/__VAR_\d+__/g, '')
+              .replace(/\s+/g, ' ')
+              .trim()}`,
+            detected_source_language: 'EN',
+            billed_characters: t.length,
+          })),
+        };
+      });
+  });
+
+  afterEach(() => {
+    client.destroy();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  function writeSource(keys: Record<string, string>): void {
+    fs.writeFileSync(path.join(tmpDir, '.deepl-sync.yaml'), CONFIG_YAML);
+    const absPath = path.join(tmpDir, 'locales', 'en.json');
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, JSON.stringify(keys, null, 2) + '\n', 'utf-8');
+  }
+
+  function readTarget(locale = 'de'): Record<string, string> {
+    return JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'locales', `${locale}.json`), 'utf-8')
+    ) as Record<string, string>;
+  }
+
+  function readLockEntries(): Record<string, SyncLockEntry> {
+    const lock = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8')
+    ) as { entries: Record<string, Record<string, SyncLockEntry>> };
+    return lock.entries['locales/en.json'] ?? {};
+  }
+
+  it('should not write a translation that lost a placeholder', async () => {
+    writeSource({
+      greeting: 'Hello {name}, welcome back',
+      plain: 'This sentence has no placeholders at all',
+    });
+
+    const result = await syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.validationErrors).toBe(1);
+    expect(result.success).toBe(false);
+    expect(readTarget()).toEqual({
+      plain: 'de:This sentence has no placeholders at all',
+    });
+  });
+
+  it('should record a withheld key as failed so the next sync retries it', async () => {
+    writeSource({ greeting: 'Hello {name}, welcome back' });
+
+    await syncService.sync(await loadSyncConfig(tmpDir));
+    expect(readLockEntries()['greeting']?.translations['de']?.status).toBe(
+      'failed'
+    );
+
+    sentTexts = [];
+    const second = await syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(sentTexts.flat()).toEqual(['Hello __VAR_0__, welcome back']);
+    expect(second.staleKeys).toBe(1);
+  });
+
+  it('should leave the previous translation in place rather than deleting the key', async () => {
+    writeSource({ greeting: 'Hello {name}' });
+    fs.writeFileSync(
+      path.join(tmpDir, 'locales', 'de.json'),
+      JSON.stringify({ greeting: 'Hallo {name}' }, null, 2) + '\n',
+      'utf-8'
+    );
+
+    await syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(readTarget()).toEqual({ greeting: 'Hallo {name}' });
+  });
+
+  it('should validate translations produced for a newly added target locale', async () => {
+    writeSource({ greeting: 'Hello {name}' });
+    // First sync establishes de; then fr is added, so greeting is `current`
+    // in the lockfile but missing for fr — the backfill path.
+    await syncService.sync(await loadSyncConfig(tmpDir));
+    fs.writeFileSync(
+      path.join(tmpDir, '.deepl-sync.yaml'),
+      CONFIG_YAML.replace('  - de\n', '  - de\n  - fr\n')
+    );
+
+    const second = await syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(second.validationErrors).toBeGreaterThanOrEqual(1);
+    expect(second.success).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'locales', 'fr.json'))).toBe(true);
+    expect(Object.hasOwn(readTarget('fr'), 'greeting')).toBe(false);
+  });
+
+  it('should write the translation when placeholder checking is disabled', async () => {
+    writeSource({ greeting: 'Hello {name}' });
+    fs.writeFileSync(
+      path.join(tmpDir, '.deepl-sync.yaml'),
+      `${CONFIG_YAML}validation:\n  check_placeholders: false\n`
+    );
+
+    const result = await syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.success).toBe(true);
+    expect(readTarget()).toEqual({ greeting: 'de:Hello' });
+  });
+});
diff --git a/tests/unit/sync/sync-locale-translator.test.ts b/tests/unit/sync/sync-locale-translator.test.ts
index b311b1b6..ed5d5ac1 100644
--- a/tests/unit/sync/sync-locale-translator.test.ts
+++ b/tests/unit/sync/sync-locale-translator.test.ts
@@ -49,6 +49,7 @@ import {
   assertPathWithinRoot,
 } from '../../../src/sync/sync-utils';
 import { validateBatch } from '../../../src/sync/translation-validator';
+import { Logger } from '../../../src/utils/logger';
 
 const mockReadFile = fs.promises.readFile as jest.MockedFunction<
   typeof fs.promises.readFile
@@ -1651,4 +1652,287 @@ describe('LocaleTranslator', () => {
       );
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // 16. Validation gate — error-severity translations are withheld
+  // ---------------------------------------------------------------------------
+  describe('validation gate', () => {
+    function writtenKeys(parser: FormatParser): string[] {
+      const call = (parser.reconstruct as jest.Mock).mock.calls[0];
+      const entries = call?.[1] as Array<{ key: string }> | undefined;
+      return (entries ?? []).map((e) => e.key);
+    }
+
+    function validatingConfig(): ResolvedSyncConfig {
+      return makeConfig({
+        validation: { validate_after_sync: true, check_placeholders: true },
+      });
+    }
+
+    it('should keep an error-severity translation out of the written file', async () => {
+      mockValidateBatch.mockReturnValueOnce([
+        {
+          key: 'a',
+          source: 'Alpha',
+          translation: 'A',
+          severity: 'pass',
+          issues: [],
+        },
+        {
+          key: 'b',
+          source: 'Beta {name}',
+          translation: 'B',
+          severity: 'error',
+          issues: [
+            {
+              check: 'placeholders',
+              severity: 'error',
+              message: 'Missing placeholders in translation: {name}',
+            },
+          ],
+        },
+      ]);
+
+      const diffs = [makeDiff('a', 'Alpha'), makeDiff('b', 'Beta {name}')];
+      const { mock } = captureTranslateBatch(['A', 'B']);
+      const parser = makeParser();
+
+      const result = await makeTranslator(mock, validatingConfig()).translate({
+        ...makeCtx(diffs, new Map()),
+        parser,
+      });
+
+      expect(writtenKeys(parser)).toEqual(['a']);
+      expect(result.targetEntries.has('b')).toBe(false);
+    });
+
+    it('should record an error-severity key as failed rather than translated', async () => {
+      mockValidateBatch.mockReturnValueOnce([
+        {
+          key: 'a',
+          source: 'Alpha',
+          translation: 'A',
+          severity: 'pass',
+          issues: [],
+        },
+        {
+          key: 'b',
+          source: 'Beta {name}',
+          translation: 'B',
+          severity: 'error',
+          issues: [
+            {
+              check: 'placeholders',
+              severity: 'error',
+              message: 'Missing placeholders in translation: {name}',
+            },
+          ],
+        },
+      ]);
+
+      const diffs = [makeDiff('a', 'Alpha'), makeDiff('b', 'Beta {name}')];
+      const { mock } = captureTranslateBatch(['A', 'B']);
+
+      const result = await makeTranslator(mock, validatingConfig()).translate(
+        makeCtx(diffs, new Map())
+      );
+
+      expect(result.successfulKeys).toEqual(['a']);
+      expect(result.fileResult.translated).toBe(1);
+      expect(result.fileResult.failed).toBe(1);
+    });
+
+    it('should keep the previous target translation for a withheld key', async () => {
+      mockValidateBatch.mockReturnValueOnce([
+        {
+          key: 'b',
+          source: 'Beta {name}',
+          translation: 'B',
+          severity: 'error',
+          issues: [
+            {
+              check: 'placeholders',
+              severity: 'error',
+              message: 'Missing placeholders in translation: {name}',
+            },
+          ],
+        },
+      ]);
+
+      const diffs = [makeDiff('b', 'Beta {name}')];
+      const { mock } = captureTranslateBatch(['B']);
+      const parser = makeParser();
+
+      const result = await makeTranslator(mock, validatingConfig()).translate({
+        ...makeCtx(diffs, new Map()),
+        parser,
+        existingTargetEntries: new Map([
+          ['de', new Map([['b', 'Beta {name} auf Deutsch']])],
+        ]),
+      });
+
+      const entries = (parser.reconstruct as jest.Mock).mock
+        .calls[0]![1] as Array<{ key: string; translation: string }>;
+      expect(entries).toEqual([
+        expect.objectContaining({
+          key: 'b',
+          translation: 'Beta {name} auf Deutsch',
+        }),
+      ]);
+      // Preserved for the file, but not a success: the lock must retry it.
+      expect(result.successfulKeys).toEqual([]);
+      expect(result.fileResult.failed).toBe(1);
+    });
+
+    it('should still write a warn-severity translation', async () => {
+      mockValidateBatch.mockReturnValueOnce([
+        {
+          key: 'a',
+          source: 'Alpha <b>bold</b>',
+          translation: 'A',
+          severity: 'warn',
+          issues: [
+            {
+              check: 'html-tags',
+              severity: 'warn',
+              message: 'Missing HTML tags in translation: <b>',
+            },
+          ],
+        },
+      ]);
+
+      const diffs = [makeDiff('a', 'Alpha <b>bold</b>')];
+      const { mock } = captureTranslateBatch(['A']);
+      const parser = makeParser();
+
+      const result = await makeTranslator(mock, validatingConfig()).translate({
+        ...makeCtx(diffs, new Map()),
+        parser,
+      });
+
+      expect(writtenKeys(parser)).toEqual(['a']);
+      expect(result.successfulKeys).toEqual(['a']);
+      expect(result.fileResult.failed).toBe(0);
+    });
+
+    it('should name the withheld keys in a warning', async () => {
+      mockValidateBatch.mockReturnValueOnce([
+        {
+          key: 'b',
+          source: 'Beta {name}',
+          translation: 'B',
+          severity: 'error',
+          issues: [
+            {
+              check: 'placeholders',
+              severity: 'error',
+              message: 'Missing placeholders in translation: {name}',
+            },
+          ],
+        },
+      ]);
+
+      const diffs = [makeDiff('b', 'Beta {name}')];
+      const { mock } = captureTranslateBatch(['B']);
+
+      await makeTranslator(mock, validatingConfig()).translate(
+        makeCtx(diffs, new Map())
+      );
+
+      const warnings = (Logger.warn as jest.Mock).mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
+      expect(warnings).toContain('"b"');
+      expect(warnings).toContain('Missing placeholders in translation: {name}');
+      expect(warnings).toContain('check_placeholders');
+    });
+
+    it('should reconstruct a withheld entry from the plural forms it was extracted with', async () => {
+      mockValidateBatch.mockReturnValueOnce([
+        {
+          key: 'items',
+          source: '1 item',
+          translation: '1 Element',
+          severity: 'error',
+          issues: [
+            {
+              check: 'placeholders',
+              severity: 'error',
+              message: 'Missing placeholders in translation: %d',
+            },
+          ],
+        },
+      ]);
+
+      const diffs: SyncDiff[] = [
+        {
+          key: 'items',
+          value: '1 item',
+          status: 'new',
+          metadata: {
+            plurals: [
+              { quantity: 'one', value: '1 item' },
+              { quantity: 'other', value: '%d items' },
+            ],
+          },
+        },
+      ];
+      const { mock } = captureTranslateBatch(['1 Element', '%d Elemente']);
+      const parser = makeParser();
+
+      await makeTranslator(mock, validatingConfig()).translate({
+        ...makeCtx(diffs, new Map()),
+        parser,
+        existingTargetEntries: new Map([
+          ['de', new Map([['items', '1 Element (vorher)']])],
+        ]),
+      });
+
+      const entries = (parser.reconstruct as jest.Mock).mock
+        .calls[0]![1] as Array<{
+        key: string;
+        metadata?: Record<string, unknown>;
+      }>;
+      expect(entries).toHaveLength(1);
+      expect(entries[0]!.metadata?.['plurals']).toEqual([
+        { quantity: 'one', value: '1 item' },
+        { quantity: 'other', value: '%d items' },
+      ]);
+    });
+
+    it('should validate the new-locale backfill batch and withhold its errors', async () => {
+      mockValidateBatch.mockReturnValueOnce([
+        {
+          key: 'c',
+          source: 'Gamma {count}',
+          translation: 'C',
+          severity: 'error',
+          issues: [
+            {
+              check: 'placeholders',
+              severity: 'error',
+              message: 'Missing placeholders in translation: {count}',
+            },
+          ],
+        },
+      ]);
+
+      const diffs: SyncDiff[] = [
+        { key: 'c', value: 'Gamma {count}', status: 'current' },
+      ];
+      const { mock } = captureTranslateBatch(['C']);
+      const parser = makeParser();
+
+      const result = await makeTranslator(mock, validatingConfig()).translate({
+        ...makeCtx(diffs, new Map()),
+        parser,
+      });
+
+      expect(mockValidateBatch).toHaveBeenCalledTimes(1);
+      expect(writtenKeys(parser)).toEqual([]);
+      expect(result.successfulKeys).toEqual([]);
+      expect(result.validationErrors).toBe(1);
+      expect(result.fileResult.failed).toBe(1);
+    });
+  });
 });
diff --git a/tests/unit/sync/sync-service.test.ts b/tests/unit/sync/sync-service.test.ts
index 99ba9b1e..362cdb1c 100644
--- a/tests/unit/sync/sync-service.test.ts
+++ b/tests/unit/sync/sync-service.test.ts
@@ -2271,7 +2271,9 @@ describe('SyncService', () => {
 
       const result = await service.sync(config);
       expect(result.validationErrors).toBeGreaterThan(0);
-      expect(result.success).toBe(true);
+      // Not a hard error, but not a success either: the key was withheld from
+      // the target file, so the run is a partial failure and retries next time.
+      expect(result.success).toBe(false);
     });
   });
 

From a0fe1b0106e010bb4b90b3c1bd1ac3b4f54b71ec Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 21:54:24 +0200
Subject: [PATCH 147/256] fix(sync): refuse --force when nothing can confirm
 it, rather than assume yes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The guard threw for `CI=true` and prompted on a TTY, and had no third branch.
In a git hook, cron job, `make` target, container entrypoint, or plain
`deepl sync --force < /dev/null`, the prompt was skipped and the run proceeded —
inverting the convention `confirm()` exists to enforce. It returns false for a
non-TTY, deliberately fail-closed, and the seven other destructive sites inherit
that auto-NO. This one turned it into auto-YES, for the most destructive
operation the CLI has.

Measured on a fully synced project whose `locales/de.json` had been hand-edited
to stand in for human review: `env -u CI deepl sync --force < /dev/null`
reported `✓ de: 3/3 keys`, `Sync complete: 3 new`, exit 0, and replaced all
three reviewed strings with machine output. No `.deepl.bak` survives a
successful run, so the edits were unrecoverable. `--no-input` was ignored on the
same path, though it documents itself as aborting instead of prompting.

Both now exit 6 with a message naming `--yes`. Refusing rather than aborting
quietly, which is what `confirm()`'s auto-NO would have given: it matches the
existing `CI=true` branch and the TMS destination-trust gate, and unlike
`cache clear`, declining here abandons the whole sync — exit 0 would report an
up-to-date project for a run that did nothing.

An interactive decline is unchanged at exit 0, and now prints `Aborted.` like
its seven siblings. Verified on a real terminal through a pty: the prompt
appears, `n` aborts with the edits intact, `y` proceeds.

The gate is a single `canPrompt()` in `utils/confirm.ts`, which `confirm()`
itself now uses, so the two cannot drift apart. `tms-server-trust.ts` had an
identically-bodied local lambda of the same name as its injectable default; it
now defaults to the exported one.

Refs cli-8kr2.31
---
 CHANGELOG.md                                |  4 ++
 docs/API.md                                 |  3 +-
 docs/SYNC.md                                |  4 +-
 src/cli/commands/sync/register-sync-root.ts | 31 +++++++----
 src/sync/tms-server-trust.ts                |  5 +-
 src/utils/confirm.ts                        | 14 ++++-
 tests/e2e/cli-sync-force-guard.e2e.test.ts  | 59 ++++++++++++++++-----
 tests/e2e/cli-sync.e2e.test.ts              |  4 +-
 tests/unit/confirm.test.ts                  | 33 +++++++++++-
 9 files changed, 126 insertions(+), 31 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3571d45b..f26dd27d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **`deepl sync --force` without `--yes` now exits 6 wherever it cannot prompt**, not just under `CI=true`. Any automation that runs it from a git hook, cron job, `make` target or container entrypoint — anything with piped or closed stdin, plus `--no-input` — has to add `--yes`. See Security for why it was doing the opposite and what that cost.
+
 - **sync**: **a validation error now fails the run.** `deepl sync` previously exited 0 with a one-line `N validation error(s)` warning while writing the corrupt translation; the key is now withheld and counted as failed, so the run exits 12 (`PartialFailure`) — or 6 with `validation.fail_on_error: true`, as before. CI that treats `deepl sync` exit 0 as "translations are complete and correct" gets the right answer for the first time; CI that ignored the warning line starts failing on input it was already mistranslating. `SyncResult.success` is `false` for the same runs. See Fixed for the measurements and for why the `fail_on_error` default was left alone.
 
 - **hooks**: **`deepl hooks list --format json` reports a state string per hook instead of a boolean** — `"installed"`, `"modified"`, `"unverified"` or `"not-installed"` (see Security for why a boolean could not tell the truth). Scripts must gate on `state === "installed"`; a truthiness test now passes for every state, `"not-installed"` included, so it has to be replaced rather than left alone. The text output gains the same distinction, and a hook you customized by hand — which the README invites — reports `!` from then on, since its body no longer matches the hash recorded at install. `GitHooksService.list()` returns those states as well; `isInstalled()` still answers the narrower "a DeepL marker is present" question and is unchanged.
@@ -392,6 +394,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync**: **`--force` is refused when there is no terminal to confirm it on, instead of treating "nobody can answer" as yes.** The guard threw for `CI=true` and prompted on a TTY, and had no third branch — so in a git hook, cron job, `make` target, container entrypoint, Jenkins agent, or plain `deepl sync --force < /dev/null`, the prompt was skipped and the run **proceeded**. This inverted the convention `confirm()` exists to enforce: it returns `false` for a non-TTY, deliberately fail-closed, and the seven other destructive sites (`cache clear`, `admin`, `config`, two in `glossary`, two in `style-rules`) all inherit that auto-NO. This one site turned it into auto-YES, for the single most destructive operation the CLI has. Measured on a fully synced project whose `locales/de.json` had been hand-edited to stand in for human review: `env -u CI deepl sync --force < /dev/null` printed no prompt and no warning, reported `✓ de: 3/3 keys`, `Sync complete: 3 new`, **exit 0**, and replaced all three reviewed strings with machine output — with no `.deepl.bak` surviving, so the edits were unrecoverable. **`--no-input` was ignored on the same path**, though it documents itself as "abort instead of prompting": `deepl --no-input sync --force` destroyed the same edits at exit 0. Both now exit 6 with a message naming `--yes` as the only way to run `--force` unattended, and `--yes` still works everywhere it did. Refusing rather than aborting quietly, matching the existing `CI=true` branch and the TMS destination-trust gate: unlike `cache clear`, declining here abandons the whole sync, so exit 0 would report an up-to-date project for a run that did nothing. An interactive decline is unchanged at exit 0, and now prints `Aborted.` like its seven siblings. Verified on a real terminal through a pty: the prompt appears, `n` aborts with the edits intact, `y` proceeds. The gate is a single `canPrompt()` in `utils/confirm.ts`, which `confirm()` itself now uses, so the two cannot drift apart.
+
 - **sync**: **a lockfile is now checked member by member before sync uses it, instead of being version-checked and then cast.** `SyncLockManager.read()` validated `version` and that `entries` was an object, then cast the rest of the repository's JSON to `SyncLockFile` — so `stats`, each per-file map, each entry and each translation were dereferenced unguarded. Four shapes reproduced by execution against a mock endpoint, all from a lockfile a hostile or merge-mangled repository ships: **a missing `stats`** crashed with `Error: Cannot set properties of undefined (setting 'total_keys')` and exit 1 **after the endpoint had been hit and `de.json` written**, leaving the lockfile as the attacker's stub so the next run re-billed everything; **an entry with no `translations` container** crashed with `Cannot read properties of undefined (reading 'de')`, and the same lockfile took `sync status` — a read-only command — down with `Cannot convert undefined or null to object`; **a per-file map that is a string** crashed with `Cannot delete property '0' of [object String]`; and **`entries` as an array** was accepted silently, exit 0, with the run's results written onto named properties of that array and then discarded by the serializer, so the lockfile recorded `"entries": []` beside `total_keys: 2` and every later run re-billed the project in silence, forever. Two more shapes found while probing: **a null translation** crashed with `Cannot read properties of null (reading 'status')` — one level deeper than the shape check the finding proposed — and **`stats` as a string** crashed with `Cannot create property 'total_keys' on string`. Every one of them now exits 0 with a well-formed lockfile. **Malformed members are dropped individually, not by discarding the file**: a key that loses its entry is translated and billed again, so resetting a whole lockfile over one bad member would hand whoever wrote it a full re-translation of the project. The count is reported at WARN level and the original is copied to `.deepl-sync.lock.bak-v1-malformed-<timestamp>`. `entries` that is not a map at all has nothing to salvage and takes the existing full-sync path with its own `-entries-not-a-map` tag. **`stats` is no longer trusted at all**: it is derived from `entries` and recomputed on every write that follows a mutation, and nothing reads the on-disk values for their own sake, so read() recomputes the counts from the surviving entries rather than validating what the file claims — which also means the counts can no longer disagree with the entries they describe. The repaired `entries` is rebuilt with `setOwnMember`, so a source path or i18n key named `__proto__` is carried across as an own property. In-repo precedent for the shape of the fix: `sync/tms-client.ts` already validated an untrusted map this way for pulled keys.
 
 - **hooks**: **`deepl hooks list` no longer reports attacker-authored content as an installed DeepL hook, and the integrity check it already had is now on a path a user can reach.** Two halves of one false-assurance defect. `isDeepLHook()` was `MARKER_PATTERN.test(content) || content.includes('# DeepL CLI Hook')`, and that second test is a **bare substring match**: a file mentioning the marker anywhere, on any line, in any context, passed as a hook this CLI installed. And `verifyIntegrity()` — which parses the `# DeepL CLI Hook v1 [sha256:...]` marker, rehashes the body and compares — was referenced by nothing but its own definition and its unit tests, so no command ever called it and the recorded hash was never checked outside the test suite. Reproduced by execution: a repository shipping a tracked `.githooks/pre-commit` that carries a forged marker with an all-zero hash plus a payload, wired up with `git config core.hooksPath .githooks` (the husky pattern, commonly set by a `prepare` script), and a second file whose only claim to the marker was the sentence `# borrowed from a # DeepL CLI Hook someone posted`. Before: `✓ pre-commit installed`, `✓ pre-push installed`, and `--format json` reporting `{"pre-commit": true, "pre-push": true}` for two files this CLI had never touched. **`list` now reports one of four states per hook** rather than a boolean — `installed` (versioned marker present and the body hashes to what it records), `modified` (marker present, body does not hash to it), `unverified` (legacy pre-1.0 marker, no hash to check), `not-installed` (no file, or no marker) — so the forged hook reads `! pre-commit installed, content does not match its recorded hash` and the quoted-marker file reads `not installed`. The legacy marker is now anchored to a whole line the way the versioned one always was, which is safe because it was only ever emitted as a line of its own. **The output states plainly what the hash is and is not worth**: it detects a change made after the marker was written, and it **cannot establish authorship**, because it is unkeyed — anyone who can write the hook can compute a marker that agrees with their content. That limit is why the fix is honest reporting rather than a stronger claim, and why the marker should be read as change detection, not provenance. A mismatch also has an innocent reading the CLI cannot distinguish — the README invites customizing an installed hook by editing it — so `modified` renders in yellow and the note gives both readings instead of accusing: expected if you edited it yourself, otherwise reinstall. Tightening `isDeepLHook` also tightens two paths that consult it, both fail-safe: `uninstall` refuses to delete a file whose marker is only quoted (it would previously have removed it), and `install` backs such a file up instead of overwriting it.
diff --git a/docs/API.md b/docs/API.md
index 8be62181..5d738fdd 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1234,8 +1234,9 @@ Scan, translate, and sync i18n resource files. The sync engine reads `.deepl-syn
   - `--watch --force` is rejected at startup with a `ValidationError` (exit 6) to prevent unbounded billing from a forced re-translation on every file save.
   - In an interactive terminal, `--force` prompts for confirmation before bypassing the cost cap. Pass `--yes` (`-y`) to skip the prompt in scripts.
   - In CI environments (`CI=true`), `--force` requires an explicit `--yes`; otherwise the process exits 6 with an actionable hint naming the missing flag.
+  - Anywhere else the prompt cannot be shown — a git hook, cron job, `make` target, container entrypoint, `deepl sync --force < /dev/null`, or `--no-input` — `--force` is **refused** with exit 6 rather than assumed to be confirmed. `--yes` is the only way to run it unattended. `--force` overwrites every target file, including translations edited by hand, and no `.deepl.bak` survives a successful run, so there is nothing to recover from afterwards.
 
-- `--yes, -y` - Skip the `--force` confirmation prompt (required when `CI=true`)
+- `--yes, -y` - Skip the `--force` confirmation prompt (required when `CI=true`, and whenever there is no terminal to prompt on)
 
 **Filtering:**
 
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 5a210c31..9e88c0b1 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -254,7 +254,7 @@ In JSON output (`--format json`), the `strategy` field provides the breakdown:
 - Keys with manual `context.overrides` always use per-key translation regardless of batching mode.
 - No-op syncs (nothing changed) complete in <200ms on typical projects.
 
-**Rollback:** If auto-generated instructions or section context produce an undesirable translation for a specific key, edit the target file manually. The lock file preserves translations by source hash — manual edits persist across syncs as long as the source text is unchanged. Use `--force` to re-translate all keys (this overwrites manual edits).
+**Rollback:** If auto-generated instructions or section context produce an undesirable translation for a specific key, edit the target file manually. The lock file preserves translations by source hash — manual edits persist across syncs as long as the source text is unchanged. Use `--force` to re-translate all keys (this overwrites manual edits, and no `.deepl.bak` survives a successful run — which is why `--force` needs a terminal to confirm on, or an explicit `--yes`).
 
 #### `validation`
 
@@ -435,7 +435,7 @@ deepl sync [OPTIONS]
 | `--dry-run` | Preview changes without translating |
 | `--frozen` | Fail (exit 10) if any translations are missing or outdated; for CI/CD |
 | `--ci` | Alias for `--frozen` |
-| `--force` | Re-translate all strings, ignoring the lockfile. **Also bypasses the `sync.max_characters` cost cap** — a forced run can re-bill every key. Preview cost with `--dry-run` first. Billing safety guards: `--watch --force` is rejected at startup with `ValidationError` (exit 6); interactive mode prompts for confirmation (add `--yes`/`-y` to skip in scripts); in CI (`CI=true`), `--force` requires explicit `--yes` or exits 6. |
+| `--force` | Re-translate all strings, ignoring the lockfile. **Also bypasses the `sync.max_characters` cost cap** — a forced run can re-bill every key. Preview cost with `--dry-run` first. Billing safety guards: `--watch --force` is rejected at startup with `ValidationError` (exit 6); interactive mode prompts for confirmation (add `--yes`/`-y` to skip in scripts); **without a terminal to prompt on — CI, a git hook, cron, a container entrypoint, `< /dev/null`, `--no-input` — `--force` is refused with exit 6, so `--yes` is the only way to run it unattended.** |
 | `--locale <langs>` | Sync only specific target locales (comma-separated) |
 | `--concurrency <n>` | Max parallel locale translations (default: 5) |
 | `--batch` | Force plain batch mode (fastest, no context or instructions). |
diff --git a/src/cli/commands/sync/register-sync-root.ts b/src/cli/commands/sync/register-sync-root.ts
index a5c4e8ad..cbdb7e7e 100644
--- a/src/cli/commands/sync/register-sync-root.ts
+++ b/src/cli/commands/sync/register-sync-root.ts
@@ -1,6 +1,7 @@
 import { Command, Option } from 'commander';
 import { ExitCode } from '../../../utils/exit-codes.js';
 import { ValidationError } from '../../../utils/errors.js';
+import { Logger } from '../../../utils/logger.js';
 import { createSyncCommand, type ServiceDeps } from '../service-factory.js';
 import { emitJsonErrorAndExit } from './sync-options.js';
 import { parsePositiveIntOption } from '../parse-int-option.js';
@@ -158,15 +159,27 @@ async function handleSyncRoot(
           'Cannot use --force in CI without --yes: add --yes to confirm intentional use and acknowledge the billing risk.'
         );
       }
-      if (process.stdin.isTTY) {
-        const { confirm } = await import('../../../utils/confirm.js');
-        const confirmed = await confirm({
-          message: 'Retranslate all keys and bypass cost cap?',
-        });
-        if (!confirmed) {
-          process.exitCode = ExitCode.Success;
-          return;
-        }
+      const { confirm, canPrompt } = await import('../../../utils/confirm.js');
+      // Refused rather than auto-answered. --force overwrites every target file,
+      // including human-reviewed translations, and no backup survives a
+      // successful run — so a git hook, cron job or container entrypoint must
+      // not be able to trigger it by being unable to answer. Erroring rather
+      // than aborting quietly, because unlike the other destructive commands
+      // declining here abandons the whole sync, and exit 0 would report an
+      // up-to-date project for a run that did nothing.
+      if (!canPrompt()) {
+        throw new ValidationError(
+          'Cannot use --force without --yes when there is no terminal to confirm at: it retranslates every key and overwrites every target file, including edits made by hand.',
+          'Add --yes to confirm intentional use and acknowledge the billing risk, or run it from a terminal.'
+        );
+      }
+      const confirmed = await confirm({
+        message: 'Retranslate all keys and bypass cost cap?',
+      });
+      if (!confirmed) {
+        Logger.info('Aborted.');
+        process.exitCode = ExitCode.Success;
+        return;
       }
     }
     const syncCommand = await createSyncCommand(deps);
diff --git a/src/sync/tms-server-trust.ts b/src/sync/tms-server-trust.ts
index 21cbd6d1..444e36ee 100644
--- a/src/sync/tms-server-trust.ts
+++ b/src/sync/tms-server-trust.ts
@@ -12,7 +12,7 @@
 
 import { ConfigError } from '../utils/errors.js';
 import { sanitizeForTerminal } from '../utils/control-chars.js';
-import { confirm, isNoInput } from '../utils/confirm.js';
+import { confirm, canPrompt as defaultCanPrompt } from '../utils/confirm.js';
 import { ConfigService } from '../storage/config.js';
 
 export const ALLOWED_SERVERS_CONFIG_KEY = 'tms.allowedServers';
@@ -96,8 +96,7 @@ export async function ensureTmsServerApproved(
   const existing = readAllowedServers();
   if (existing.some((entry) => entry.trim().toLowerCase() === hostname)) return;
 
-  const canPrompt =
-    deps.canPrompt ?? (() => !isNoInput() && !!process.stdin.isTTY);
+  const canPrompt = deps.canPrompt ?? defaultCanPrompt;
   if (!canPrompt()) {
     throw refuse(
       `Refusing to send an environment-supplied TMS credential to "${hostname}", which is not in ${ALLOWED_SERVERS_CONFIG_KEY}. ` +
diff --git a/src/utils/confirm.ts b/src/utils/confirm.ts
index 596dfb37..60ef3045 100644
--- a/src/utils/confirm.ts
+++ b/src/utils/confirm.ts
@@ -10,6 +10,18 @@ export function isNoInput(): boolean {
   return noInput;
 }
 
+/**
+ * Can a question actually be put to someone?
+ *
+ * False in a git hook, cron job, container entrypoint, CI runner or under
+ * `--no-input`, where `confirm()` answers no on the user's behalf. A caller
+ * whose command is too destructive to decline silently checks this first and
+ * refuses with an error naming its own `--yes` flag.
+ */
+export function canPrompt(): boolean {
+  return !noInput && Boolean(process.stdin.isTTY);
+}
+
 export interface ConfirmOptions {
   message?: string;
   /** Injected for testing; defaults to readline.createInterface */
@@ -20,7 +32,7 @@ export async function confirm(options: ConfirmOptions = {}): Promise<boolean> {
   const message = options.message ?? 'Are you sure?';
   const prompt = `${message} [y/N] `;
 
-  if (noInput || !process.stdin.isTTY) {
+  if (!canPrompt()) {
     return false;
   }
 
diff --git a/tests/e2e/cli-sync-force-guard.e2e.test.ts b/tests/e2e/cli-sync-force-guard.e2e.test.ts
index 9a384ad3..13250adf 100644
--- a/tests/e2e/cli-sync-force-guard.e2e.test.ts
+++ b/tests/e2e/cli-sync-force-guard.e2e.test.ts
@@ -3,7 +3,7 @@
  *
  * Covers:
  *  - --watch --force is rejected at startup (ValidationError, exit 6)
- *  - --force in non-TTY (piped stdin) proceeds without prompt
+ *  - --force in non-TTY (piped stdin) or under --no-input is refused, exit 6
  *  - --force --yes skips prompt and proceeds
  *  - CI=true --force without --yes exits 6
  *  - CI=true --force --yes proceeds
@@ -68,10 +68,18 @@ interface RunResult {
 function run(
   args: string[],
   opts: { cwd: string; env?: NodeJS.ProcessEnv; input?: string }
+): RunResult {
+  return runRaw(['sync', ...args], opts);
+}
+
+/** Same, but without the implied `sync`, so global flags can precede it. */
+function runRaw(
+  args: string[],
+  opts: { cwd: string; env?: NodeJS.ProcessEnv; input?: string }
 ): RunResult {
   const result: SpawnSyncReturns<string> = spawnSync(
     'node',
-    [CLI_PATH, 'sync', ...args],
+    [CLI_PATH, ...args],
     {
       encoding: 'utf-8',
       cwd: opts.cwd,
@@ -186,22 +194,47 @@ describe('deepl sync --force billing defense', () => {
   });
 
   describe('non-TTY stdin (piped) without --yes', () => {
-    it('proceeds without prompting when stdin is not a TTY', () => {
-      // spawnSync with input= sets stdin to a pipe, so isTTY is false.
-      // CI is stripped so the CI-guard branch does not pre-empt the TTY branch
-      // this test is designed to exercise (GitHub Actions / GitLab CI set CI=true).
+    // spawnSync with input= sets stdin to a pipe, so isTTY is false. CI is
+    // stripped in these cases so the CI-guard branch does not pre-empt the
+    // no-terminal branch they exercise (GitHub Actions / GitLab CI set CI=true).
+    function envWithoutCI(): NodeJS.ProcessEnv {
       const { CI: _ci, ...baseEnv } = process.env;
-      const result = run(['--force', '--dry-run'], {
+      return {
+        ...baseEnv,
+        DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'),
+        NO_COLOR: '1',
+      };
+    }
+
+    it('refuses to run when there is no terminal to confirm at', () => {
+      const result = run(['--force'], {
         cwd: tmpDir,
-        env: {
-          ...baseEnv,
-          DEEPL_CONFIG_DIR: path.join(tmpDir, 'config'),
-          NO_COLOR: '1',
-        },
+        env: envWithoutCI(),
+        input: 'y\n',
+      });
+
+      expect(result.status).toBe(6);
+      expect(result.combined).toMatch(/--yes/);
+    });
+
+    it('refuses under --no-input, which documents itself as aborting', () => {
+      const result = runRaw(['--no-input', 'sync', '--force'], {
+        cwd: tmpDir,
+        env: envWithoutCI(),
+        input: 'y\n',
+      });
+
+      expect(result.status).toBe(6);
+      expect(result.combined).toMatch(/--yes/);
+    });
+
+    it('still proceeds when --yes is given', () => {
+      const result = run(['--force', '--yes', '--dry-run'], {
+        cwd: tmpDir,
+        env: envWithoutCI(),
         input: 'y\n',
       });
 
-      // Piped stdin: no TTY, no prompt expected; proceeds to sync (may fail on API, not guard)
       expect(result.status).not.toBe(6);
     });
   });
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 34f7ea93..30c16730 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -450,7 +450,9 @@ describe('CLI Sync E2E', () => {
       const targetFile = path.join(testFiles.path, 'locales', 'de.json');
       expect(fs.existsSync(targetFile)).toBe(true);
 
-      const output = runSyncAll('--force');
+      // --yes is required: execSync gives the CLI no TTY, and --force refuses
+      // rather than assuming confirmation when it cannot prompt.
+      const output = runSyncAll('--force --yes');
       expect(output).toBeDefined();
       expect(fs.existsSync(targetFile)).toBe(true);
     });
diff --git a/tests/unit/confirm.test.ts b/tests/unit/confirm.test.ts
index c9f76b34..2352c5e6 100644
--- a/tests/unit/confirm.test.ts
+++ b/tests/unit/confirm.test.ts
@@ -2,7 +2,12 @@
  * Tests for confirm utility
  */
 
-import { confirm, setNoInput, isNoInput } from '../../src/utils/confirm';
+import {
+  confirm,
+  setNoInput,
+  isNoInput,
+  canPrompt,
+} from '../../src/utils/confirm';
 
 describe('confirm()', () => {
   let originalIsTTY: boolean | undefined;
@@ -261,6 +266,32 @@ describe('confirm()', () => {
     });
   });
 
+  describe('canPrompt', () => {
+    function setIsTTY(value: boolean): void {
+      Object.defineProperty(process.stdin, 'isTTY', {
+        value,
+        writable: true,
+        configurable: true,
+      });
+    }
+
+    it('should be true on a TTY with input enabled', () => {
+      setIsTTY(true);
+      expect(canPrompt()).toBe(true);
+    });
+
+    it('should be false when stdin is not a TTY', () => {
+      setIsTTY(false);
+      expect(canPrompt()).toBe(false);
+    });
+
+    it('should be false under noInput even on a TTY', () => {
+      setIsTTY(true);
+      setNoInput(true);
+      expect(canPrompt()).toBe(false);
+    });
+  });
+
   describe('setNoInput / isNoInput', () => {
     it('should default to false', () => {
       expect(isNoInput()).toBe(false);

From 27f5505d83b12c2254ab1311908746b8529770ee Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Fri, 7 Aug 2026 22:40:09 +0200
Subject: [PATCH 148/256] fix(translate): tell a text that was never sent apart
 from one that failed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`translateBatch` left a `null` slot for both an empty input text and a text
whose request was rejected, and declared its return type `TranslationResult[]`,
so nothing was forced to distinguish them. An empty i18n value crashed
`deepl translate <file>` with a TypeError at exit 1 and no output file, and
reached sync as a key deleted from the target and recorded permanently failed.

An empty input now returns an empty translation with `billedCharacters: 0`, and
the return type is `(TranslationResult | null)[]` so the remaining failure case
is the compiler's business rather than a comment's.

Structured file translation caps batches at `TRANSLATE_BATCH_SIZE` as well as by
byte size, matching `BatchTranslationService`. One call is then one request, so a
rejection propagates with its own exit code (3 for a rate limit) instead of
arriving as holes to dereference; the dead length guards gain a per-index check.
`BatchTranslationService` records a missing result as that file's failure.

`reassembleIcu` accepts an empty plural branch as translated. Its check read an
empty segment as a failed one, which lost the whole message — the same defect on
a path the report did not name.

The cache-state notice is announced once per run rather than once per request,
which the batch cap would otherwise have repeated per API call.

Refs cli-8kr2.32, cli-8kr2.35

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   8 +
 docs/API.md                                   |   2 +
 docs/SYNC.md                                  |   2 +
 src/services/batch-translation.ts             |  16 +-
 src/services/structured-file-translation.ts   |  71 ++--
 src/services/translation.ts                   |  49 ++-
 src/sync/sync-message-preprocess.ts           |   6 +-
 tests/e2e/cli-sync.e2e.test.ts                |  29 ++
 ...uctured-file-translate.integration.test.ts |  76 +++++
 .../translate-batch-skip-cache.test.ts        |   2 +-
 .../translate-batch-sparse-contract.test.ts   | 308 ++++++++++++++++++
 .../unit/structured-file-translation.test.ts  |  26 +-
 .../unit/sync/sync-message-preprocess.test.ts |  41 +++
 13 files changed, 585 insertions(+), 51 deletions(-)
 create mode 100644 tests/unit/services/translate-batch-sparse-contract.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f26dd27d..836a9e45 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **translate/sync**: **two exit codes move for files containing an empty string value.** `deepl translate <file>` exits 0 and writes its output where it used to crash with exit 1, and `deepl sync` exits 0 where it used to exit 12 on every run forever. A rate limit part-way through a large structured file now exits 3 rather than 1, so a CI wrapper that treats 3 as retryable starts retrying it. See Fixed for the measurements.
+
 - **sync**: **`deepl sync --force` without `--yes` now exits 6 wherever it cannot prompt**, not just under `CI=true`. Any automation that runs it from a git hook, cron job, `make` target or container entrypoint — anything with piped or closed stdin, plus `--no-input` — has to add `--yes`. See Security for why it was doing the opposite and what that cost.
 
 - **sync**: **a validation error now fails the run.** `deepl sync` previously exited 0 with a one-line `N validation error(s)` warning while writing the corrupt translation; the key is now withheld and counted as failed, so the run exits 12 (`PartialFailure`) — or 6 with `validation.fail_on_error: true`, as before. CI that treats `deepl sync` exit 0 as "translations are complete and correct" gets the right answer for the first time; CI that ignored the warning line starts failing on input it was already mistranslating. `SyncResult.success` is `false` for the same runs. See Fixed for the measurements and for why the `fail_on_error` default was left alone.
@@ -117,6 +119,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **translate/sync**: **an empty string value in an i18n file is no longer mistaken for a failed translation.** `TranslationService.translateBatch` skips a text that is empty — nothing to send, nothing to bill — but left that slot `null`, the same value it uses for a text whose request failed, and declared its return type `TranslationResult[]` so nothing was forced to tell the two apart. Three separate consequences, all measured against a mock endpoint. **`deepl translate` crashed:** `{"title": "Hello world", "placeholder": "", "footer": "Goodbye"}` printed a false `⚠️  Warning: 1 of 3 translations failed` (nothing had failed) then `Error: Cannot read properties of null (reading 'text')`, **exit 1**, and no output file at all — one empty value cost the whole file. **`deepl sync` deleted the key:** the same content wrote a `de.json` containing only `title` and `footer`, recorded `placeholder` as `status: "failed"`, and every later run reported `✗ de: 0/1 keys` and **exit 12 forever**, since the retry could never succeed. It now reports `✓ de: 3/3 keys`, exit 0, writes `"placeholder": ""`, and settles in the lockfile as translated. **An ICU message with an empty plural branch was lost the same way:** `{count, plural, one {} other {# items}}` had its empty branch read as a failed segment, so the entire message was withheld and the key dropped from the target — found by looking for the same defect on a path the report did not name. Empty input now returns an empty translation with `billedCharacters: 0`, `translateBatch` is declared `(TranslationResult | null)[]` so the compiler forces the remaining failure case to be handled at each of the five call sites, and the `N of M translations failed` warning counts only real failures. `BatchTranslationService` records a missing per-index result as that one file's failure instead of dereferencing it.
+
+- **translate**: **a rate limit part-way through a large structured file now exits 3 instead of 1.** `deepl translate <file>` grouped strings for the API by byte size only (128 KB), never by count, so a file of more than 50 strings became several API requests inside one `translateBatch` call; when a later request was rejected, the surviving batches came back with holes and the caller dereferenced one. Measured on a 60-key JSON file with a 429 on the second request: `Error: Cannot read properties of null (reading 'text')` and **exit 1** — `GeneralError` — so a CI wrapper branching on `$? -eq 3` did not retry. Batches are now capped at 50 strings as well as by size, which is what `BatchTranslationService` already did, so each call is a single request and a rejection propagates with its own classified code: the same run reports `Error: Rate limit exceeded: Too many requests`, its retry suggestion, and **exit 3**, with no partial output file written. The unreachable "expected N results but got M" length guards are kept and joined by a per-index check.
+
+- **translate**: `ℹ️  Cache is disabled` and `ℹ️  Cache bypassed for this request (--no-cache)` are announced once per run rather than once per API request. The cache state is a property of the invocation, so a file needing ten requests repeated the same line ten times.
+
 - **sync**: **a translation the engine corrupted is withheld from the target file instead of being written and recorded as done.** The placeholder/ICU validator is the only defence against corrupt machine output, and it ran too late to be one: the write at `sync-locale-translator.ts` happened first, then the lockfile, then the `.deepl.bak` backups were unlinked, and only then was `validation.fail_on_error` consulted. Its results were counted, never acted on. Measured against a mock endpoint that drops the `__VAR_n__` tokens the CLI substitutes for placeholders: `"greeting": "Hello {name}, welcome back"` reported `✓ de: 2/2 keys`, `Sync complete: 2 new`, one line of `1 validation error(s)`, and **exit 0** — with `de.json` holding `"[DE] Hello , welcome back"`, the lockfile recording the key `translated`, and the next run reporting `2 current` and never retrying, so the placeholder was gone permanently. `fail_on_error: true` only changed the exit code to 6 after the same damage was done, and where the target file already existed the previous good translation had been overwritten and its backup deleted on the way out. **The new-locale backfill path was not validated at all**: adding `fr` to `target_locales` translated the already-`current` keys through a second batch that never reached `validateBatch`, so `fr.json` was written corrupt at `✓ fr: 2/2 keys`, exit 0, and **zero validation errors reported** — the bulk-translation case was the silent one. An `error`-severity result (a lost placeholder, an ICU bracket or selector rewritten) is now decided before the write, on both paths: the key is withheld, counted as failed, and recorded `status: "failed"`, so the same run reads `✗ de: 1/2 keys`, `Sync complete: 2 new (1 translations failed)`, exit 12, and the next run retries the key. Warnings still pass through and are still written. Two things the fix cannot do naively: simply leaving the entry out **deletes** the key, because the entry list is the complete desired key set a parser reconstructs from — measured, `de.json` lost `greeting` entirely and a previous `"Hallo {name}, willkommen zurueck"` with it — so a withheld key now carries whatever the target file already held, exactly as an untouched `current` key does; and the plural write-backs, which copy translated text into the metadata the PO and Android parsers reconstruct from, are skipped for withheld entries, or the forms would have gone in corrupt behind a preserved scalar. `validation.fail_on_error` keeps its `false` default rather than being flipped: a withheld key already fails the run, so the protection no longer depends on the setting, and the flag retains its documented meaning of promoting that to a hard `ValidationError`. The backups are still cleaned up on the way out — with the corrupt value never written, there is nothing to roll back to, and keeping them would make the next run report an unfinished earlier run that did not happen.
 
 - **formats**: **an `.arb` key whose name collides with an `Object.prototype` member is no longer dropped from the file it was billed for.** `arb.ts` gated new-key insertion on `key in data`, and `in` reports inherited members — so `toString`, `valueOf`, `constructor`, `hasOwnProperty`, `isPrototypeOf` and `__proto__` all read as already present and their translations were discarded. The sibling `json.ts` documents this exact defect as fixed, with the reason in a comment above the check; same repo, same class, one fixed and one not. Measured at the parser: asked to insert six keys into a target that lacked them, `arb` dropped five and `json` dropped none. **The trigger is a source file gaining a key**, not a first sync — sync seeds a new target from the source, so the keys land on the in-place path; it is the second run, inserting into a target that already exists, that loses them. Reproduced end to end against a mock endpoint: adding `hasOwnProperty` and `constructor` to `app_en.arb` reported `✓ de: 3/3 keys` and `Sync complete: 3 new`, wrote only the third key to `app_de.arb`, and exited 0. The lockfile records all three as translated, so the next run reports `6 current` and **never retries them** — the strings are lost silently and permanently rather than re-billed each run. Insertion now tests `Object.hasOwn` and writes through the shared `setOwnMember`, so a key named `__proto__` becomes an own property instead of reaching the prototype setter. `setOwnMember`/`getOwnMember` moved from `sync/sync-lock.ts` to `utils/own-members.ts` for this: `formats/` cannot import from `sync/` without inverting the dependency, and a third copy of the same `defineProperty` helper was not worth writing. No behaviour change for the five sync modules that use them.
diff --git a/docs/API.md b/docs/API.md
index 5d738fdd..86fa29a6 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -355,6 +355,8 @@ The following structured formats are parsed to extract only string values, trans
 - `.json` - JSON files (i18n locale files, config files)
 - `.yaml`, `.yml` - YAML files (Rails i18n, config files)
 
+An empty string value is copied to the output unchanged and is never sent to the API, so a placeholder key you have not written copy for yet costs nothing and stays in the file. Requests are capped at 50 strings each; if one of them fails, no output file is written and the command exits with that failure's own code (for example 3 for a rate limit), because a partly translated file is indistinguishable from a complete one.
+
 ```bash
 # Translate JSON locale file
 deepl translate en.json --to es --output es.json
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 9e88c0b1..3b713fc0 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -50,6 +50,8 @@ deepl sync
 
 The lockfile tracks content hashes for every source string. On subsequent runs, only strings whose hash has changed (or that are newly added) are sent to DeepL. Deleted keys are removed from target files. This makes sync fast and cost-efficient -- you only pay for what actually changed.
 
+A key whose source value is an empty string is written to each target as an empty string without a request. It counts as translated, so it settles in the lockfile on the first run instead of being retried on every run. The same holds for an empty ICU plural branch such as `one {}` -- the branch stays empty and the rest of the message is translated normally.
+
 All sync commands (`sync`, `sync push`, `sync pull`, `sync export`, `sync validate`) refuse to follow symbolic links when scanning `include` globs. A symlink matching a bucket pattern is silently skipped, preventing a hostile symlink (e.g., `locales/en.json` -> `/etc/passwd`) from exfiltrating files outside the project root to the TMS server or into an exported XLIFF.
 
 Sync also refuses to read or write any path resolving into `.git/` or `.github/`, whether it arrives as an `include` match or as a resolved target path. Translating a file into `.github/workflows/` would turn a target-locale filename into CI workflow code whose body came from the translation endpoint, so a bucket rooted there fails with exit 6 rather than being silently skipped. The check compares segments relative to the project root, so a checkout that itself lives under a `.github` directory is unaffected.
diff --git a/src/services/batch-translation.ts b/src/services/batch-translation.ts
index 2dd93a90..e4b56da0 100644
--- a/src/services/batch-translation.ts
+++ b/src/services/batch-translation.ts
@@ -346,8 +346,22 @@ export class BatchTranslationService {
 
         for (let i = 0; i < batch.length; i++) {
           const entry = batch[i]!;
+          const result = results[i];
+          if (!result) {
+            failed.push({
+              file: entry.file,
+              error: 'No translation returned for this file',
+            });
+            completed++;
+            onProgress?.({
+              completed,
+              total: totalFiles,
+              current: entry.file,
+            });
+            continue;
+          }
           const translatedText = restorePlaceholders(
-            results[i]!.text,
+            result.text,
             entry.preservationMap
           );
 
diff --git a/src/services/structured-file-translation.ts b/src/services/structured-file-translation.ts
index 57452ba5..6ca7270b 100644
--- a/src/services/structured-file-translation.ts
+++ b/src/services/structured-file-translation.ts
@@ -7,7 +7,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as YAML from 'yaml';
-import { TranslationService, MAX_TEXT_BYTES } from './translation.js';
+import {
+  TranslationService,
+  MAX_TEXT_BYTES,
+  TRANSLATE_BATCH_SIZE,
+} from './translation.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { TranslationOptions, Language } from '../types/index.js';
 import { safeReadFile } from '../utils/safe-read-file.js';
@@ -342,6 +346,12 @@ export class StructuredFileTranslationService {
     return result;
   }
 
+  /**
+   * One output file cannot be partly translated, so a batch that comes back
+   * incomplete aborts the run. Batches are capped at `TRANSLATE_BATCH_SIZE` as
+   * well as by size, which keeps each call to a single API request: a rejection
+   * then surfaces with its own exit code instead of arriving as empty slots.
+   */
   private async translateStringsInBatches(
     strings: string[],
     options: TranslationOptions,
@@ -351,33 +361,11 @@ export class StructuredFileTranslationService {
     let batch: string[] = [];
     let batchBytes = 0;
 
-    for (const str of strings) {
-      const strBytes = Buffer.byteLength(str, 'utf-8');
-
-      if (batch.length > 0 && batchBytes + strBytes > MAX_TEXT_BYTES) {
-        const batchResults = await this.translationService.translateBatch(
-          batch,
-          options,
-          { skipCache: fileOptions.skipCache }
-        );
-        if (batchResults.length !== batch.length) {
-          throw new NetworkError(
-            `Translation batch failed: expected ${batch.length} results but got ${batchResults.length}. ` +
-              'Aborting to prevent misaligned output.'
-          );
-        }
-        for (const r of batchResults) {
-          results.push(r.text);
-        }
-        batch = [];
-        batchBytes = 0;
+    const flush = async (): Promise<void> => {
+      if (batch.length === 0) {
+        return;
       }
-
-      batch.push(str);
-      batchBytes += strBytes;
-    }
-
-    if (batch.length > 0) {
+      const offset = results.length;
       const batchResults = await this.translationService.translateBatch(
         batch,
         options,
@@ -389,11 +377,36 @@ export class StructuredFileTranslationService {
             'Aborting to prevent misaligned output.'
         );
       }
-      for (const r of batchResults) {
-        results.push(r.text);
+      for (let i = 0; i < batch.length; i++) {
+        const result = batchResults[i];
+        if (!result) {
+          throw new NetworkError(
+            `Translation batch failed: no translation returned for string ${offset + i + 1} of ${strings.length}. ` +
+              'Aborting to prevent misaligned output.'
+          );
+        }
+        results.push(result.text);
       }
+      batch = [];
+      batchBytes = 0;
+    };
+
+    for (const str of strings) {
+      const strBytes = Buffer.byteLength(str, 'utf-8');
+
+      if (
+        batch.length >= TRANSLATE_BATCH_SIZE ||
+        (batch.length > 0 && batchBytes + strBytes > MAX_TEXT_BYTES)
+      ) {
+        await flush();
+      }
+
+      batch.push(str);
+      batchBytes += strBytes;
     }
 
+    await flush();
+
     return results;
   }
 }
diff --git a/src/services/translation.ts b/src/services/translation.ts
index 5bda7ec7..7913718a 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -76,6 +76,7 @@ export class TranslationService {
     { data: LanguageInfo[]; timestamp: number }
   > = new Map();
   private readonly LANGUAGE_CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours
+  private announcedCacheNotices = new Set<string>();
 
   constructor(
     client: DeepLClient,
@@ -87,6 +88,23 @@ export class TranslationService {
     this.cache = cache;
   }
 
+  /**
+   * The cache state is a property of the run, not of one request, so repeat it
+   * no more than once. A file of more than `TRANSLATE_BATCH_SIZE` strings needs
+   * several requests, and one notice per request buried the output.
+   */
+  private announceCacheMode(cacheEnabled: boolean, skipCache: boolean): void {
+    const notice = !cacheEnabled
+      ? 'ℹ️  Cache is disabled'
+      : skipCache
+        ? 'ℹ️  Cache bypassed for this request (--no-cache)'
+        : undefined;
+    if (notice && !this.announcedCacheNotices.has(notice)) {
+      this.announcedCacheNotices.add(notice);
+      Logger.info(notice);
+    }
+  }
+
   /**
    * Translate text with optional code/variable preservation
    */
@@ -140,12 +158,7 @@ export class TranslationService {
     const cacheEnabled = this.config.getValue<boolean>('cache.enabled') ?? true;
     const shouldUseCache = cacheEnabled && !serviceOptions.skipCache;
 
-    // Log when cache is bypassed
-    if (!cacheEnabled) {
-      Logger.info('ℹ️  Cache is disabled');
-    } else if (serviceOptions.skipCache) {
-      Logger.info('ℹ️  Cache bypassed for this request (--no-cache)');
-    }
+    this.announceCacheMode(cacheEnabled, serviceOptions.skipCache === true);
 
     const cacheKey = this.generateCacheKey(processedText, translationOptions);
 
@@ -194,12 +207,17 @@ export class TranslationService {
    *   cache write, matching `translate()`. Without it, `--no-cache` was a
    *   silent no-op for every structured i18n format, so a corrupt translation
    *   could not be re-fetched and the natural remedy did nothing.
+   * @returns One slot per input text, in input order. A slot is `null` when the
+   *   request carrying that text failed; the surviving batches are still
+   *   returned so callers that track failure per item can retry only those.
+   *   Callers needing all-or-nothing should submit at most
+   *   `TRANSLATE_BATCH_SIZE` texts, which makes any failure a rejection.
    */
   async translateBatch(
     texts: string[],
     options: TranslationOptions,
     serviceOptions: TranslateBatchServiceOptions = {}
-  ): Promise<TranslationResult[]> {
+  ): Promise<(TranslationResult | null)[]> {
     if (texts.length === 0) {
       return [];
     }
@@ -224,11 +242,7 @@ export class TranslationService {
     const cacheEnabled = this.config.getValue<boolean>('cache.enabled') ?? true;
     const shouldUseCache = cacheEnabled && !serviceOptions.skipCache;
 
-    if (!cacheEnabled) {
-      Logger.info('ℹ️  Cache is disabled');
-    } else if (serviceOptions.skipCache) {
-      Logger.info('ℹ️  Cache bypassed for this request (--no-cache)');
-    }
+    this.announceCacheMode(cacheEnabled, serviceOptions.skipCache === true);
 
     // Merge options with defaults
     const translationOptions: TranslationOptions = {
@@ -249,6 +263,11 @@ export class TranslationService {
     for (let i = 0; i < texts.length; i++) {
       const text = texts[i];
       if (!text) {
+        // An empty source value has an empty translation. Sending it would be
+        // billed for nothing, and leaving the slot null made a text that was
+        // never sent indistinguishable from a request that failed — which
+        // crashed file translation and cost sync the key outright.
+        results[i] = { text: '', billedCharacters: 0 };
         continue;
       }
 
@@ -278,7 +297,7 @@ export class TranslationService {
 
     // If all texts were cached, return results preserving positional correspondence
     if (textsToTranslate.length === 0) {
-      return results as TranslationResult[];
+      return results;
     }
 
     // Use batch API to translate all non-cached texts in a single request
@@ -359,9 +378,7 @@ export class TranslationService {
       );
     }
 
-    // Return sparse array preserving positional correspondence with input texts.
-    // Callers must check for null/undefined at each index.
-    return results as TranslationResult[];
+    return results;
   }
 
   /**
diff --git a/src/sync/sync-message-preprocess.ts b/src/sync/sync-message-preprocess.ts
index 5bc4c1a8..43b2d6f6 100644
--- a/src/sync/sync-message-preprocess.ts
+++ b/src/sync/sync-message-preprocess.ts
@@ -123,16 +123,18 @@ export async function reassembleIcu(
     // Every segment must come back. Substituting the source segment for a failed
     // one would emit a part-source message reported as successfully translated,
     // so leave the result unset — the message is marked failed and retried.
+    // An empty branch (`one {}`) translates to an empty string, which is a
+    // result: treating it as a failure lost the whole message permanently.
     const anySegmentFailed =
       segResults.length !== segTexts.length ||
-      segResults.some((sr) => !sr?.text);
+      segResults.some((sr) => typeof sr?.text !== 'string');
     if (anySegmentFailed) {
       results[icu.textIndex] = null;
       continue;
     }
 
     const translatedSegments = segResults.map((sr, si) => {
-      let translated = sr.text;
+      let translated = sr?.text ?? '';
       const pMap = segTexts[si]!.pMap;
       if (pMap.size > 0) translated = restorePlaceholders(translated, pMap);
       return translated;
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 30c16730..ec6d76f8 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -237,6 +237,35 @@ describe('CLI Sync E2E', () => {
       expect(parsed['farewell']).toBeDefined();
     });
 
+    it('should carry an empty source value into the target rather than dropping the key', () => {
+      writeSyncConfig(testFiles.path, ['de']);
+      const dir = path.join(testFiles.path, 'locales');
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'en.json'),
+        JSON.stringify(
+          { title: 'Hello world', placeholder: '', footer: 'Goodbye' },
+          null,
+          2
+        ) + '\n'
+      );
+
+      const first = runSyncExpectError();
+
+      expect(first.status).toBe(0);
+      expect(first.output).toContain('3/3 keys');
+      const parsed = JSON.parse(
+        fs.readFileSync(path.join(dir, 'de.json'), 'utf-8')
+      ) as Record<string, string>;
+      expect(parsed['placeholder']).toBe('');
+      expect(Object.keys(parsed)).toHaveLength(3);
+
+      // The empty key is settled, not queued for a retry that can never succeed.
+      const second = runSyncExpectError();
+      expect(second.status).toBe(0);
+      expect(second.output).toContain('3 current');
+    });
+
     it('should show dry-run preview without creating files', () => {
       writeSyncConfig(testFiles.path, ['de']);
       writeSourceFile(testFiles.path);
diff --git a/tests/integration/cli-structured-file-translate.integration.test.ts b/tests/integration/cli-structured-file-translate.integration.test.ts
index 26b72fb6..027dcf24 100644
--- a/tests/integration/cli-structured-file-translate.integration.test.ts
+++ b/tests/integration/cli-structured-file-translate.integration.test.ts
@@ -117,6 +117,82 @@ describe('Structured File Translation service integration', () => {
       expect(result.farewell).toBe('Adiós');
     });
 
+    it('should write an empty value back unchanged without sending it', async () => {
+      const inputPath = path.join(testDir, 'svc-empty-en.json');
+      const outputPath = path.join(testDir, 'svc-empty-de.json');
+
+      fs.writeFileSync(
+        inputPath,
+        JSON.stringify(
+          {
+            title: 'Hello world',
+            placeholder: '',
+            footer: 'Goodbye',
+          },
+          null,
+          2
+        )
+      );
+
+      let sentTexts: string[] = [];
+      nock(FREE_API_URL)
+        .post('/v2/translate', (body: Record<string, unknown>) => {
+          sentTexts = body['text'] as string[];
+          return true;
+        })
+        .reply(200, {
+          translations: [
+            { text: 'Hallo Welt', detected_source_language: 'EN' },
+            { text: 'Auf Wiedersehen', detected_source_language: 'EN' },
+          ],
+        });
+
+      await fileTranslationService.translateFile(inputPath, outputPath, {
+        targetLang: 'de',
+      });
+
+      expect(sentTexts).toEqual(['Hello world', 'Goodbye']);
+      expect(JSON.parse(fs.readFileSync(outputPath, 'utf-8'))).toEqual({
+        title: 'Hallo Welt',
+        placeholder: '',
+        footer: 'Auf Wiedersehen',
+      });
+    });
+
+    it('should surface a rate limit on the second request as exit code 3', async () => {
+      const inputPath = path.join(testDir, 'svc-partial-en.json');
+      const outputPath = path.join(testDir, 'svc-partial-de.json');
+
+      const data: Record<string, string> = {};
+      for (let i = 0; i < 60; i++) {
+        data[`k${i}`] = `String number ${i}`;
+      }
+      fs.writeFileSync(inputPath, JSON.stringify(data, null, 2));
+
+      nock(FREE_API_URL)
+        .post('/v2/translate')
+        .reply(200, {
+          translations: Object.values(data)
+            .slice(0, 50)
+            .map((v) => ({ text: `DE ${v}`, detected_source_language: 'EN' })),
+        });
+      nock(FREE_API_URL)
+        .post('/v2/translate')
+        .times(6)
+        .reply(429, { message: 'Too many requests' });
+
+      expect.assertions(3);
+      try {
+        await fileTranslationService.translateFile(inputPath, outputPath, {
+          targetLang: 'de',
+        });
+      } catch (error) {
+        expect((error as Error).message).not.toMatch(/Cannot read properties/);
+        expect((error as { exitCode?: number }).exitCode).toBe(3);
+      }
+      expect(fs.existsSync(outputPath)).toBe(false);
+    });
+
     it('should refuse to write a file when the endpoint reorders the batch', async () => {
       const inputPath = path.join(testDir, 'svc-reorder-en.json');
       const outputPath = path.join(testDir, 'svc-reorder-de.json');
diff --git a/tests/unit/services/translate-batch-skip-cache.test.ts b/tests/unit/services/translate-batch-skip-cache.test.ts
index fcbf46f7..581cce39 100644
--- a/tests/unit/services/translate-batch-skip-cache.test.ts
+++ b/tests/unit/services/translate-batch-skip-cache.test.ts
@@ -118,7 +118,7 @@ describe('translateBatch honours skipCache', () => {
       { skipCache: true }
     );
 
-    expect(results.map((r) => r.text)).toEqual([
+    expect(results.map((r) => r?.text)).toEqual([
       'FRESH(one)',
       'FRESH(two)',
       'FRESH(three)',
diff --git a/tests/unit/services/translate-batch-sparse-contract.test.ts b/tests/unit/services/translate-batch-sparse-contract.test.ts
new file mode 100644
index 00000000..fa656ce1
--- /dev/null
+++ b/tests/unit/services/translate-batch-sparse-contract.test.ts
@@ -0,0 +1,308 @@
+/**
+ * `translateBatch` returns one slot per input text, but leaves a slot `null`
+ * both when a chunk request failed and when the input text was empty and
+ * therefore never sent. Its declared return type was `TranslationResult[]`,
+ * so no consumer was forced to handle either case: an empty i18n value crashed
+ * structured file translation with a TypeError before any output was written,
+ * and reached sync as a permanent per-key failure.
+ *
+ * An empty input now round-trips as an empty translation — a result, not a
+ * failure — and the remaining null case is in the type.
+ */
+
+import { StructuredFileTranslationService } from '../../../src/services/structured-file-translation';
+import {
+  TranslationService,
+  TRANSLATE_BATCH_SIZE,
+} from '../../../src/services/translation';
+import { BatchTranslationService } from '../../../src/services/batch-translation';
+import type { FileTranslationService } from '../../../src/services/file-translation';
+import type { DeepLClient } from '../../../src/api/deepl-client';
+import type { ConfigService } from '../../../src/storage/config';
+import type { TranslationResult } from '../../../src/api/translation-client';
+import { DeepLCLIError, RateLimitError } from '../../../src/utils/errors';
+import { Logger } from '../../../src/utils/logger';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+type BatchImpl = (texts: string[]) => Promise<TranslationResult[]>;
+
+function makeService(impl?: BatchImpl): {
+  service: TranslationService;
+  clientCalls: string[][];
+} {
+  const clientCalls: string[][] = [];
+  const client = {
+    resolvedBaseUrl: 'https://api-free.deepl.com',
+    translateBatch: (texts: string[]) => {
+      clientCalls.push([...texts]);
+      return (
+        impl?.(texts) ??
+        Promise.resolve(texts.map((t) => ({ text: `DE(${t})` })))
+      );
+    },
+    translate: (text: string) => Promise.resolve({ text: `DE(${text})` }),
+  } as unknown as DeepLClient;
+
+  const config = {
+    get: () => ({ defaults: {} }),
+    getValue: (key: string) => (key === 'cache.enabled' ? false : undefined),
+  } as unknown as ConfigService;
+
+  return {
+    service: new TranslationService(client, config),
+    clientCalls,
+  };
+}
+
+/** Succeeds for a full chunk, rejects for the short trailing one. */
+const failSecondChunk: BatchImpl = (batch) =>
+  batch.length === TRANSLATE_BATCH_SIZE
+    ? Promise.resolve(batch.map((t) => ({ text: `DE(${t})` })))
+    : Promise.reject(new RateLimitError('Too many requests'));
+
+function silenceLogger(): void {
+  jest.spyOn(Logger, 'error').mockImplementation(() => {});
+  jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+}
+
+describe('translateBatch sparse-array contract', () => {
+  describe('empty input texts', () => {
+    it('should return an empty translation rather than a null slot', async () => {
+      const { service } = makeService();
+
+      const results = await service.translateBatch(['Hello', '', 'Goodbye'], {
+        targetLang: 'de',
+      });
+
+      expect(results).toHaveLength(3);
+      expect(results[0]?.text).toBe('DE(Hello)');
+      expect(results[1]).not.toBeNull();
+      expect(results[1]?.text).toBe('');
+      expect(results[2]?.text).toBe('DE(Goodbye)');
+    });
+
+    it('should not send the empty text to the API or bill for it', async () => {
+      const { service, clientCalls } = makeService();
+
+      const results = await service.translateBatch(['Hello', '', 'Goodbye'], {
+        targetLang: 'de',
+      });
+
+      expect(clientCalls).toEqual([['Hello', 'Goodbye']]);
+      expect(results[1]?.billedCharacters).toBe(0);
+    });
+
+    it('should not warn that a translation failed', async () => {
+      const { service } = makeService();
+      const warnings: string[] = [];
+      jest.spyOn(Logger, 'warn').mockImplementation((...args: unknown[]) => {
+        warnings.push(String(args[0]));
+      });
+
+      await service.translateBatch(['Hello', '', 'Goodbye'], {
+        targetLang: 'de',
+      });
+
+      expect(warnings.filter((w) => w.includes('translations failed'))).toEqual(
+        []
+      );
+    });
+  });
+
+  describe('cache-state notice', () => {
+    it('should announce a disabled cache once per run, not once per batch', async () => {
+      const { service } = makeService();
+      const notices: string[] = [];
+      jest.spyOn(Logger, 'info').mockImplementation((...args: unknown[]) => {
+        notices.push(String(args[0]));
+      });
+
+      await service.translateBatch(['a'], { targetLang: 'de' });
+      await service.translateBatch(['b'], { targetLang: 'de' });
+      await service.translate('c', { targetLang: 'de' });
+
+      expect(
+        notices.filter((n) => n.includes('Cache is disabled'))
+      ).toHaveLength(1);
+    });
+  });
+
+  describe('failed chunks', () => {
+    it('should still leave a null slot so per-key consumers can retry', async () => {
+      // Two chunks: the second rejects, so its texts have no result.
+      const texts = Array.from(
+        { length: TRANSLATE_BATCH_SIZE + 2 },
+        (_, i) => `t${i}`
+      );
+      const { service } = makeService(failSecondChunk);
+      silenceLogger();
+
+      const results = await service.translateBatch(texts, {
+        targetLang: 'de',
+      });
+
+      expect(results).toHaveLength(texts.length);
+      expect(results[0]?.text).toBe('DE(t0)');
+      expect(results[TRANSLATE_BATCH_SIZE]).toBeNull();
+      expect(results[TRANSLATE_BATCH_SIZE + 1]).toBeNull();
+    });
+  });
+});
+
+describe('StructuredFileTranslationService batching', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sparse-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  function writeJson(name: string, data: unknown): string {
+    const p = path.join(testDir, name);
+    fs.writeFileSync(p, JSON.stringify(data, null, 2) + '\n');
+    return p;
+  }
+
+  it('should preserve an empty value and translate the rest', async () => {
+    const { service: translation } = makeService();
+    const structured = new StructuredFileTranslationService(translation);
+    const inputPath = writeJson('en.json', {
+      title: 'Hello world',
+      placeholder: '',
+      footer: 'Goodbye',
+    });
+    const outputPath = path.join(testDir, 'de.json');
+
+    await structured.translateFile(inputPath, outputPath, {
+      targetLang: 'de',
+    });
+
+    expect(JSON.parse(fs.readFileSync(outputPath, 'utf-8'))).toEqual({
+      title: 'DE(Hello world)',
+      placeholder: '',
+      footer: 'DE(Goodbye)',
+    });
+  });
+
+  function manyStrings(count: number): Record<string, string> {
+    const data: Record<string, string> = {};
+    for (let i = 0; i < count; i++) {
+      data[`k${i}`] = `String number ${i}`;
+    }
+    return data;
+  }
+
+  it('should cap each translateBatch call at TRANSLATE_BATCH_SIZE texts', async () => {
+    const { service: translation } = makeService();
+    const spy = jest.spyOn(translation, 'translateBatch');
+    const structured = new StructuredFileTranslationService(translation);
+    const inputPath = writeJson(
+      'en.json',
+      manyStrings(TRANSLATE_BATCH_SIZE + 10)
+    );
+
+    await structured.translateFile(inputPath, path.join(testDir, 'de.json'), {
+      targetLang: 'de',
+    });
+
+    expect(spy.mock.calls.map((c) => c[0].length)).toEqual([
+      TRANSLATE_BATCH_SIZE,
+      10,
+    ]);
+  });
+
+  it('should classify a partly failed batch instead of crashing with a TypeError', async () => {
+    const { service: translation } = makeService(failSecondChunk);
+    const structured = new StructuredFileTranslationService(translation);
+    const inputPath = writeJson(
+      'en.json',
+      manyStrings(TRANSLATE_BATCH_SIZE + 10)
+    );
+    const outputPath = path.join(testDir, 'de.json');
+    silenceLogger();
+
+    expect.assertions(4);
+    try {
+      await structured.translateFile(inputPath, outputPath, {
+        targetLang: 'de',
+      });
+    } catch (error) {
+      expect(error).toBeInstanceOf(DeepLCLIError);
+      expect((error as Error).message).not.toMatch(/Cannot read properties/);
+      expect((error as DeepLCLIError).exitCode).toBe(3);
+    }
+    expect(fs.existsSync(outputPath)).toBe(false);
+  });
+
+  it('should reject a missing per-index result with a typed error', async () => {
+    const translation = {
+      translateBatch: jest
+        .fn<Promise<(TranslationResult | null)[]>, [string[]]>()
+        .mockImplementation((texts: string[]) =>
+          Promise.resolve(texts.map((t, i) => (i === 1 ? null : { text: t })))
+        ),
+    } as unknown as TranslationService;
+    const structured = new StructuredFileTranslationService(translation);
+    const inputPath = writeJson('en.json', { a: 'A', b: 'B', c: 'C' });
+    const outputPath = path.join(testDir, 'de.json');
+
+    expect.assertions(3);
+    try {
+      await structured.translateFile(inputPath, outputPath, {
+        targetLang: 'de',
+      });
+    } catch (error) {
+      expect(error).toBeInstanceOf(DeepLCLIError);
+      expect((error as Error).message).not.toMatch(/Cannot read properties/);
+    }
+    expect(fs.existsSync(outputPath)).toBe(false);
+  });
+});
+
+describe('BatchTranslationService null results', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sparse-batch-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('should record a missing per-index result as a per-file failure', async () => {
+    const files = [path.join(testDir, 'a.txt'), path.join(testDir, 'b.txt')];
+    fs.writeFileSync(files[0]!, 'Alpha\n');
+    fs.writeFileSync(files[1]!, 'Beta\n');
+    const outDir = path.join(testDir, 'out');
+
+    const translation = {
+      translateBatch: jest
+        .fn<Promise<(TranslationResult | null)[]>, [string[]]>()
+        .mockImplementation((texts: string[]) =>
+          Promise.resolve(texts.map((t, i) => (i === 0 ? null : { text: t })))
+        ),
+    } as unknown as TranslationService;
+    const fileTranslation = {
+      isSupportedFile: () => true,
+    } as unknown as FileTranslationService;
+    const batch = new BatchTranslationService(fileTranslation, {
+      translationService: translation,
+    });
+
+    const result = await batch.translateFiles(
+      files,
+      { targetLang: 'de' },
+      { outputDir: outDir }
+    );
+
+    expect(result.failed).toHaveLength(1);
+    expect(result.successful).toHaveLength(1);
+    expect(result.failed[0]?.error).not.toMatch(/Cannot read properties/);
+  });
+});
diff --git a/tests/unit/structured-file-translation.test.ts b/tests/unit/structured-file-translation.test.ts
index 750d4f29..30d34390 100644
--- a/tests/unit/structured-file-translation.test.ts
+++ b/tests/unit/structured-file-translation.test.ts
@@ -505,12 +505,12 @@ describe('StructuredFileTranslationService', () => {
   });
 
   describe('batching', () => {
-    it('should batch strings under 128KB into a single call', async () => {
+    it('should batch strings well under 128KB into a single call', async () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
 
       const data: Record<string, string> = {};
-      for (let i = 0; i < 100; i++) {
+      for (let i = 0; i < 10; i++) {
         data[`key${i}`] = `Value ${i}`;
       }
       fs.writeFileSync(inputPath, JSON.stringify(data, null, 2));
@@ -532,6 +532,28 @@ describe('StructuredFileTranslationService', () => {
       );
     });
 
+    it('should split at TRANSLATE_BATCH_SIZE even when far under 128KB', async () => {
+      const inputPath = path.join(testDir, 'en.json');
+      const outputPath = path.join(testDir, 'es.json');
+
+      const data: Record<string, string> = {};
+      for (let i = 0; i < 100; i++) {
+        data[`key${i}`] = `Value ${i}`;
+      }
+      fs.writeFileSync(inputPath, JSON.stringify(data, null, 2));
+
+      mockTranslationService.translateBatch.mockImplementation(
+        (texts: string[]) =>
+          Promise.resolve(texts.map((t) => ({ text: `Translated ${t}` })))
+      );
+
+      await service.translateFile(inputPath, outputPath, { targetLang: 'es' });
+
+      expect(
+        mockTranslationService.translateBatch.mock.calls.map((c) => c[0].length)
+      ).toEqual([50, 50]);
+    });
+
     it('should split strings into multiple batches when over 128KB', async () => {
       const inputPath = path.join(testDir, 'en.json');
       const outputPath = path.join(testDir, 'es.json');
diff --git a/tests/unit/sync/sync-message-preprocess.test.ts b/tests/unit/sync/sync-message-preprocess.test.ts
index 39751192..f028716a 100644
--- a/tests/unit/sync/sync-message-preprocess.test.ts
+++ b/tests/unit/sync/sync-message-preprocess.test.ts
@@ -1,10 +1,12 @@
 import {
   expandPlurals,
   detectIcu,
+  reassembleIcu,
   writebackPlurals,
 } from '../../../src/sync/sync-message-preprocess';
 import type { SyncDiff } from '../../../src/sync/types';
 import type { TranslationResult } from '../../../src/api/translation-client';
+import type { TranslationService } from '../../../src/services/translation';
 
 function makeDiff(partial: Partial<SyncDiff>): SyncDiff {
   return {
@@ -86,6 +88,45 @@ describe('detectIcu', () => {
   });
 });
 
+describe('reassembleIcu', () => {
+  function serviceReturning(
+    impl: (texts: string[]) => (TranslationResult | null)[]
+  ): TranslationService {
+    return {
+      translateBatch: (texts: string[]) => Promise.resolve(impl(texts)),
+    } as unknown as TranslationService;
+  }
+
+  it('accepts an empty plural branch as translated', async () => {
+    const source = '{count, plural, one {} other {# items}}';
+    const { extendedTexts, icuMappings } = detectIcu([source]);
+    const results: (TranslationResult | null)[] = [null];
+    const service = serviceReturning((texts) =>
+      texts.map((t) => ({ text: t === '' ? '' : `DE ${t}` }))
+    );
+
+    await reassembleIcu(service, results, icuMappings, { targetLang: 'de' });
+
+    expect(extendedTexts[0]).toBe('__ICU_PLACEHOLDER_0__');
+    expect(results[0]).not.toBeNull();
+    expect(results[0]?.text).toBe('{count, plural, one {} other {DE # items}}');
+  });
+
+  it('still marks the message failed when a segment has no result at all', async () => {
+    const { icuMappings } = detectIcu([
+      '{count, plural, one {# item} other {# items}}',
+    ]);
+    const results: (TranslationResult | null)[] = [null];
+    const service = serviceReturning((texts) =>
+      texts.map((t, i) => (i === 0 ? null : { text: `DE ${t}` }))
+    );
+
+    await reassembleIcu(service, results, icuMappings, { targetLang: 'de' });
+
+    expect(results[0]).toBeNull();
+  });
+});
+
 describe('writebackPlurals', () => {
   it('writes translated Android plural quantity values back into diff.metadata.plurals', () => {
     const diff = makeDiff({

From e8d2a2f598e80822807691815ebd7e86a71dd0d9 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 00:09:05 +0200
Subject: [PATCH 149/256] fix(sync): protect every ICU block in a message, not
 only the first
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Detection matched one block with a single non-global exec, then pushed the whole
remaining suffix as one ordinary prose segment. Every block after the first was
submitted to the MT engine as translatable text — the exposure the module exists
to prevent. An engine translating `other` to `andere` leaves a message with no
`other` branch, which throws at render time.

parseIcu now walks the string, emitting each run of prose between blocks as its
own segment and each block through the same brace-counting parser, with leaf
references reindexed into one combined segment list. The reindexing that nested
blocks already needed is now shared. The safe fallback is unchanged and applies
to the whole message: a string holding any unparseable block passes through
untouched rather than half-protected.

An ICU string's slot in the main batch held `__ICU_PLACEHOLDER_<n>__`, which was
sent to the API as a text, billed, and cached under its own key. The slot now
holds nothing to translate, so translateBatch skips it; reassembleIcu overwrites
every mapped index, so the blank cannot reach a target file.

Refs cli-8kr2.33

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   4 +
 docs/SYNC.md                                  |   2 +-
 src/sync/sync-message-preprocess.ts           |   8 +-
 src/utils/icu-preservation.ts                 | 101 +++++++++-----
 tests/integration/sync.integration.test.ts    |  57 ++++----
 .../message-preprocess.property.test.ts       |   5 +-
 tests/unit/icu-multiple-blocks.test.ts        | 123 ++++++++++++++++++
 .../unit/sync/sync-locale-translator.test.ts  |  39 ++++++
 .../unit/sync/sync-message-preprocess.test.ts |   9 +-
 9 files changed, 270 insertions(+), 78 deletions(-)
 create mode 100644 tests/unit/icu-multiple-blocks.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 836a9e45..7c9e7983 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -119,6 +119,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **every ICU block in a message is protected, not just the first.** `parseIcu` found one block with a single non-global match, then pushed the entire remaining suffix as one ordinary prose segment — so the second and later blocks were submitted to the MT engine as translatable text, which is the exact exposure the module exists to prevent. Measured against a mock endpoint with `You have {n, plural, one {# item} other {# items}} and {m, plural, one {# gift} other {# gifts}} waiting.`, the outbound request was `["You have ", "__VAR_HASH_0__ item", "__VAR_HASH_0__ items", " and {m, plural, one {# gift} other {# gifts}} waiting."]` — the first block's selectors and `#` correctly protected, the second block's full syntax sent as prose. A real engine translating `other` to `andere` yields a message with no `other` branch, which throws at render time. Detection now walks the whole string, emitting each run of prose between blocks as its own segment and each block through the same brace-counting parser, with leaf references reindexed into one combined segment list; the same request is now `["You have ", "__VAR_HASH_0__ item", "__VAR_HASH_0__ items", " and ", "__VAR_HASH_0__ gift", "__VAR_HASH_0__ gifts", " waiting."]`. Adjacent blocks with no prose between them, three or more blocks, and nested ICU are all covered. The documented safe fallback is unchanged and now applies to the whole message: a string holding **any** block that will not parse passes through untouched rather than half-protected.
+
+- **sync**: **the internal ICU marker is no longer submitted and billed as a text.** A string routed to segment-by-segment ICU translation had its slot in the main batch filled with `__ICU_PLACEHOLDER_<n>__`, which went to the API as an ordinary text, was billed, and was cached under its own key — measured as a whole extra request per batch containing an ICU string. The slot now holds nothing to translate, so `translateBatch` skips it (see the empty-value entry above); `reassembleIcu` overwrites every mapped index, so the blank cannot reach a target file.
+
 - **translate/sync**: **an empty string value in an i18n file is no longer mistaken for a failed translation.** `TranslationService.translateBatch` skips a text that is empty — nothing to send, nothing to bill — but left that slot `null`, the same value it uses for a text whose request failed, and declared its return type `TranslationResult[]` so nothing was forced to tell the two apart. Three separate consequences, all measured against a mock endpoint. **`deepl translate` crashed:** `{"title": "Hello world", "placeholder": "", "footer": "Goodbye"}` printed a false `⚠️  Warning: 1 of 3 translations failed` (nothing had failed) then `Error: Cannot read properties of null (reading 'text')`, **exit 1**, and no output file at all — one empty value cost the whole file. **`deepl sync` deleted the key:** the same content wrote a `de.json` containing only `title` and `footer`, recorded `placeholder` as `status: "failed"`, and every later run reported `✗ de: 0/1 keys` and **exit 12 forever**, since the retry could never succeed. It now reports `✓ de: 3/3 keys`, exit 0, writes `"placeholder": ""`, and settles in the lockfile as translated. **An ICU message with an empty plural branch was lost the same way:** `{count, plural, one {} other {# items}}` had its empty branch read as a failed segment, so the entire message was withheld and the key dropped from the target — found by looking for the same defect on a path the report did not name. Empty input now returns an empty translation with `billedCharacters: 0`, `translateBatch` is declared `(TranslationResult | null)[]` so the compiler forces the remaining failure case to be handled at each of the five call sites, and the `N of M translations failed` warning counts only real failures. `BatchTranslationService` records a missing per-index result as that one file's failure instead of dereferencing it.
 
 - **translate**: **a rate limit part-way through a large structured file now exits 3 instead of 1.** `deepl translate <file>` grouped strings for the API by byte size only (128 KB), never by count, so a file of more than 50 strings became several API requests inside one `translateBatch` call; when a later request was rejected, the surviving batches came back with holes and the caller dereferenced one. Measured on a 60-key JSON file with a 429 on the second request: `Error: Cannot read properties of null (reading 'text')` and **exit 1** — `GeneralError` — so a CI wrapper branching on `$? -eq 3` did not retry. Batches are now capped at 50 strings as well as by size, which is what `BatchTranslationService` already did, so each call is a single request and a rejection propagates with its own classified code: the same run reports `Error: Rate limit exceeded: Too many requests`, its retry suggestion, and **exit 3**, with no partial output file written. The unreachable "expected N results but got M" length guards are kept and joined by a per-index check.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 3b713fc0..8d87937c 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -1011,7 +1011,7 @@ Run `deepl sync validate` to detect placeholder issues. Consider adding a glossa
 The sync engine automatically preserves these placeholder formats during translation:
 - Simple variables: `{name}`, `{{count}}`, `${userId}`
 - Printf-style: `%s`, `%d`, `%1$s`, `%2$d`
-- ICU MessageFormat: `{count, plural, one {# item} other {# items}}` — structural keywords (`plural`, `select`, `selectordinal`, `one`, `other`, `few`, `many`, `zero`, `two`) and variable names are preserved; only leaf text is translated. Nested ICU (e.g., select inside plural) is supported.
+- ICU MessageFormat: `{count, plural, one {# item} other {# items}}` — structural keywords (`plural`, `select`, `selectordinal`, `one`, `other`, `few`, `many`, `zero`, `two`) and variable names are preserved; only leaf text is translated. Nested ICU (e.g., select inside plural) is supported, as are several blocks in one message (`You have {n, plural, ...} and {m, plural, ...} waiting.`) and prose between them. A message containing a block that will not parse is left untouched rather than partly protected.
 
 ### Rate limiting (HTTP 429)
 
diff --git a/src/sync/sync-message-preprocess.ts b/src/sync/sync-message-preprocess.ts
index 43b2d6f6..0803cb77 100644
--- a/src/sync/sync-message-preprocess.ts
+++ b/src/sync/sync-message-preprocess.ts
@@ -86,8 +86,12 @@ export function detectIcu(extendedTexts: string[]): {
     const icuResult = parseIcu(out[ti]!);
     if (icuResult.isIcu && icuResult.segments.length > 0) {
       icuMappings.push({ textIndex: ti, icuResult });
-      // ICU strings skip the main batch and get translated segment-by-segment.
-      out[ti] = `__ICU_PLACEHOLDER_${ti}__`;
+      // ICU strings skip the main batch and get translated segment-by-segment,
+      // so the slot holds nothing to translate. A marker token here was itself
+      // submitted as a text, billed, and cached under its own key.
+      // `reassembleIcu` overwrites every mapped index, so the blank never
+      // reaches a target file.
+      out[ti] = '';
     }
   }
 
diff --git a/src/utils/icu-preservation.ts b/src/utils/icu-preservation.ts
index 86be530f..e80dd645 100644
--- a/src/utils/icu-preservation.ts
+++ b/src/utils/icu-preservation.ts
@@ -35,36 +35,54 @@ export interface IcuParseResult {
  * If parsing fails, returns the same (safe fallback — string passes through unchanged).
  */
 export function parseIcu(text: string): IcuParseResult {
-  const match = ICU_DETECT_RE.exec(text);
-  if (!match) {
+  if (!ICU_DETECT_RE.test(text)) {
     return { isIcu: false, segments: [], reassemble: () => text };
   }
 
   try {
-    const blockStart = match.index;
-    const result = parseIcuBlock(text, blockStart);
-    if (!result) {
-      return { isIcu: false, segments: [], reassemble: () => text };
-    }
-
-    // Text on either side of the block is ordinary prose and must be
-    // translated too — dropping it from the template silently deleted it.
-    const prefix = text.slice(0, blockStart);
-    // endIndex points AT the block's closing brace, which result.template
-    // already includes, so the suffix starts one past it.
-    const suffix = text.slice(result.endIndex + 1);
     const segments: IcuSegment[] = [];
     let template = '';
+    let pos = 0;
+
+    // Every block is protected, not just the first. Pushing the whole suffix as
+    // one prose segment submitted the remaining blocks' syntax to the engine,
+    // which translates the keyword and the selectors.
+    for (;;) {
+      const match = ICU_DETECT_RE.exec(text.slice(pos));
+      if (!match) break;
+
+      const blockStart = pos + match.index;
+      const block = parseIcuBlock(text, blockStart);
+      if (!block) {
+        // Documented safe fallback: a string holding a block that will not
+        // parse passes through untouched rather than partly protected.
+        return { isIcu: false, segments: [], reassemble: () => text };
+      }
+
+      // Text between blocks is ordinary prose and must be translated too —
+      // dropping it from the template silently deleted it.
+      const prose = text.slice(pos, blockStart);
+      if (prose !== '') {
+        template += `__ICU_LEAF_${segments.length}__`;
+        segments.push({ text: prose, isPluralBranch: false });
+      }
+
+      template += reindexLeaves(
+        block.template,
+        block.segments,
+        segments.length
+      );
+      segments.push(...block.segments);
 
-    if (prefix !== '') {
-      template += `__ICU_LEAF_P__`;
-      segments.push({ text: prefix, isPluralBranch: false });
+      // endIndex points AT the block's closing brace, which block.template
+      // already includes, so the next scan starts one past it.
+      pos = block.endIndex + 1;
     }
-    template += result.template;
-    segments.push(...result.segments);
-    if (suffix !== '') {
-      template += `__ICU_LEAF_S__`;
-      segments.push({ text: suffix, isPluralBranch: false });
+
+    const tail = text.slice(pos);
+    if (tail !== '') {
+      template += `__ICU_LEAF_${segments.length}__`;
+      segments.push({ text: tail, isPluralBranch: false });
     }
 
     return {
@@ -78,10 +96,9 @@ export function parseIcu(text: string): IcuParseResult {
             `ICU reassemble expected ${segments.length} translations, received ${translations.length}`
           );
         }
-        let idx = 0;
         return template.replace(
-          /__ICU_LEAF_(?:\d+|P|S)__/g,
-          () => translations[idx++] ?? ''
+          /__ICU_LEAF_(\d+)__/g,
+          (_, index: string) => translations[Number(index)] ?? ''
         );
       },
     };
@@ -90,6 +107,24 @@ export function parseIcu(text: string): IcuParseResult {
   }
 }
 
+/**
+ * Shifts a sub-template's leaf references by `offset` so they index the combined
+ * segment list. Descending order keeps a rewritten reference from being rewritten
+ * again by a lower index.
+ */
+function reindexLeaves(
+  template: string,
+  segments: IcuSegment[],
+  offset: number
+): string {
+  if (offset === 0) return template;
+  let out = template;
+  for (let j = segments.length - 1; j >= 0; j--) {
+    out = out.replace(`__ICU_LEAF_${j}__`, `__ICU_LEAF_${offset + j}__`);
+  }
+  return out;
+}
+
 interface ParseBlockResult {
   template: string;
   segments: IcuSegment[];
@@ -216,21 +251,17 @@ function tryParseNestedContent(
   const nested = parseIcuBlock(trimmed, 0, inPluralContext);
   if (!nested || nested.endIndex < trimmed.length - 1) return null;
 
+  const reindexed = reindexLeaves(
+    nested.template,
+    nested.segments,
+    segments.length
+  );
+
   // Merge nested segments into parent segments array
-  const baseIndex = segments.length;
   for (const seg of nested.segments) {
     segments.push(seg);
   }
 
-  // Reindex the nested template's leaf references
-  let reindexed = nested.template;
-  for (let j = nested.segments.length - 1; j >= 0; j--) {
-    reindexed = reindexed.replace(
-      `__ICU_LEAF_${j}__`,
-      `__ICU_LEAF_${baseIndex + j}__`
-    );
-  }
-
   return { template: reindexed };
 }
 
diff --git a/tests/integration/sync.integration.test.ts b/tests/integration/sync.integration.test.ts
index 32033a81..fbc44c14 100644
--- a/tests/integration/sync.integration.test.ts
+++ b/tests/integration/sync.integration.test.ts
@@ -1106,7 +1106,7 @@ buckets:
       writeYamlConfig(tmpDir, icuConfig);
 
       // Keys sorted alphabetically by JsonFormatParser: greeting (idx 0), items (idx 1)
-      // The ICU string at idx 1 becomes __ICU_PLACEHOLDER_1__ in the main batch.
+      // The ICU string at idx 1 is blanked in the main batch and never sent.
       const sourceContent =
         JSON.stringify(
           {
@@ -1118,35 +1118,28 @@ buckets:
         ) + '\n';
       writeSourceFile(tmpDir, 'locales/en.json', sourceContent);
 
-      // Main batch: "Hello" at idx 0 and the ICU placeholder at idx 1
+      // Main batch: "Hello" alone — the ICU slot carries nothing to translate
       const mainScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const texts = getTexts(body);
-          return (
-            texts.some((t) => t === 'Hello') &&
-            texts.some((t) => t.startsWith('__ICU_PLACEHOLDER_'))
-          );
+          return texts.length === 1 && texts[0] === 'Hello';
         })
-        .reply(200, (_uri: string, rawBody: unknown) => {
-          const texts = getTexts(rawBody);
-          return {
-            translations: texts.map((t) => ({
-              text: t.startsWith('__ICU_PLACEHOLDER_') ? t : 'Hallo',
+        .reply(200, () => ({
+          translations: [
+            {
+              text: 'Hallo',
               detected_source_language: 'EN',
               billed_characters: 5,
-            })),
-          };
-        });
+            },
+          ],
+        }));
 
       // ICU segments batch: the leaf texts extracted from the plural branches
       // "# item" and "# items" — with # protected as __VAR_HASH_0__
       const icuScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const texts = getTexts(body);
-          return (
-            texts.length === 2 &&
-            !texts.some((t) => t.startsWith('__ICU_PLACEHOLDER_'))
-          );
+          return texts.length === 2;
         })
         .reply(200, (_uri: string, rawBody: unknown) => {
           const texts = getTexts(rawBody);
@@ -1212,35 +1205,29 @@ buckets:
 `;
       writeSourceFile(tmpDir, 'locales/en/strings.xml', sourceXml);
 
-      // Main batch: "Hello" plus one or two ICU placeholders for the plural quantities
+      // Main batch: "Hello" alone — the ICU plural quantities carry nothing to
+      // translate in the main batch and are never sent as texts of their own
       const mainScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const texts = getTexts(body);
-          return (
-            texts.some((t) => t === 'Hello') &&
-            texts.some((t) => t.startsWith('__ICU_PLACEHOLDER_'))
-          );
+          return texts.length === 1 && texts[0] === 'Hello';
         })
-        .reply(200, (_uri: string, rawBody: unknown) => {
-          const texts = getTexts(rawBody);
-          return {
-            translations: texts.map((t) => ({
-              text: t.startsWith('__ICU_PLACEHOLDER_') ? t : 'Hallo',
+        .reply(200, () => ({
+          translations: [
+            {
+              text: 'Hallo',
               detected_source_language: 'EN',
               billed_characters: 5,
-            })),
-          };
-        });
+            },
+          ],
+        }));
 
       // ICU segments batch: the leaf texts from the plural branches ("# widget", "# widgets")
       // — with # protected via __VAR_HASH_N__ preservation
       const icuScope = nock(DEEPL_FREE_API_URL)
         .post('/v2/translate', (body: Record<string, unknown>) => {
           const texts = getTexts(body);
-          return (
-            texts.length >= 1 &&
-            !texts.some((t) => t.startsWith('__ICU_PLACEHOLDER_'))
-          );
+          return texts.length >= 1 && texts[0] !== 'Hello';
         })
         .reply(200, (_uri: string, rawBody: unknown) => {
           const texts = getTexts(rawBody);
diff --git a/tests/property/message-preprocess.property.test.ts b/tests/property/message-preprocess.property.test.ts
index 3180f57e..cc9baa1b 100644
--- a/tests/property/message-preprocess.property.test.ts
+++ b/tests/property/message-preprocess.property.test.ts
@@ -108,7 +108,7 @@ describe('sync message-preprocess pipeline positions', () => {
     );
   });
 
-  it('P3: detectIcu preserves length and rewrites exactly the ICU positions', () => {
+  it('P3: detectIcu preserves length and blanks exactly the ICU positions', () => {
     const icuText = 'You have {count, plural, one {# item} other {# items}}.';
     fc.assert(
       fc.property(
@@ -120,7 +120,8 @@ describe('sync message-preprocess pipeline positions', () => {
           const icuIndices = new Set(icuMappings.map((m) => m.textIndex));
           for (let i = 0; i < texts.length; i++) {
             if (icuIndices.has(i)) {
-              expect(extendedTexts[i]).toBe(`__ICU_PLACEHOLDER_${i}__`);
+              // Nothing to translate: the segments carry the text instead.
+              expect(extendedTexts[i]).toBe('');
             } else {
               expect(extendedTexts[i]).toBe(texts[i]);
             }
diff --git a/tests/unit/icu-multiple-blocks.test.ts b/tests/unit/icu-multiple-blocks.test.ts
new file mode 100644
index 00000000..ae90117a
--- /dev/null
+++ b/tests/unit/icu-multiple-blocks.test.ts
@@ -0,0 +1,123 @@
+/**
+ * A string may contain more than one ICU block.
+ *
+ * Detection found one block and pushed the whole remaining suffix as a single
+ * prose segment, so every block after the first was submitted to the MT engine
+ * as translatable text — the exact exposure the module exists to prevent. The
+ * engine translates the keyword and the selectors:
+ *
+ *   in  You have {n, plural, one {# item} other {# items}} and
+ *       {m, plural, one {# gift} other {# gifts}} waiting.
+ *   out ... und {m, Plural, ein {# gift} andere {# gifts}} wartet.
+ *
+ * leaving a message with no valid format type and no `other` branch, which
+ * throws at render time.
+ */
+
+import { parseIcu } from '../../src/utils/icu-preservation';
+
+const TWO_BLOCKS =
+  'You have {n, plural, one {# item} other {# items}} and ' +
+  '{m, plural, one {# gift} other {# gifts}} waiting.';
+
+describe('a string with several ICU blocks', () => {
+  it('should send no ICU syntax to the engine', () => {
+    const { segments } = parseIcu(TWO_BLOCKS);
+
+    for (const segment of segments) {
+      expect(segment.text).not.toMatch(/\bplural\b/);
+      expect(segment.text).not.toMatch(/\bother\b/);
+    }
+  });
+
+  it('should expose every branch and every prose run as its own segment', () => {
+    const texts = parseIcu(TWO_BLOCKS).segments.map((s) => s.text);
+
+    expect(texts).toEqual([
+      'You have ',
+      '# item',
+      '# items',
+      ' and ',
+      '# gift',
+      '# gifts',
+      ' waiting.',
+    ]);
+  });
+
+  it('should mark the branches of the second block as plural branches', () => {
+    const { segments } = parseIcu(TWO_BLOCKS);
+
+    expect(segments.filter((s) => s.isPluralBranch).map((s) => s.text)).toEqual(
+      ['# item', '# items', '# gift', '# gifts']
+    );
+  });
+
+  it('should reassemble both blocks with their structure intact', () => {
+    const result = parseIcu(TWO_BLOCKS);
+    const translated = result.segments.map((s) => `[de]${s.text}`);
+
+    expect(result.reassemble(translated)).toBe(
+      '[de]You have {n, plural, one {[de]# item} other {[de]# items}}' +
+        '[de] and {m, plural, one {[de]# gift} other {[de]# gifts}}[de] waiting.'
+    );
+  });
+
+  it('should handle adjacent blocks with no prose between them', () => {
+    const source =
+      '{n, plural, one {# item} other {# items}}' +
+      '{m, plural, one {# gift} other {# gifts}}';
+    const result = parseIcu(source);
+
+    expect(result.segments.map((s) => s.text)).toEqual([
+      '# item',
+      '# items',
+      '# gift',
+      '# gifts',
+    ]);
+    expect(result.reassemble(result.segments.map((s) => s.text))).toBe(source);
+  });
+
+  it('should handle three blocks', () => {
+    const source =
+      'A {a, plural, one {# x} other {# xs}} B ' +
+      '{b, select, male {he} other {they}} C ' +
+      '{c, plural, one {# y} other {# ys}} D';
+    const result = parseIcu(source);
+
+    expect(result.segments.map((s) => s.text)).toEqual([
+      'A ',
+      '# x',
+      '# xs',
+      ' B ',
+      'he',
+      'they',
+      ' C ',
+      '# y',
+      '# ys',
+      ' D',
+    ]);
+    expect(result.reassemble(result.segments.map((s) => s.text))).toBe(source);
+  });
+
+  it('should still pass the whole string through when a block is malformed', () => {
+    // An unterminated block is the documented safe fallback: the string is not
+    // treated as ICU at all rather than partly protected.
+    const source = 'Text {n, plural, one {# item} other {# items';
+    const result = parseIcu(source);
+
+    expect(result.isIcu).toBe(false);
+    expect(result.segments).toEqual([]);
+    expect(result.reassemble([])).toBe(source);
+  });
+
+  it('should pass the whole string through when a later block is malformed', () => {
+    // The first block parses; protecting it and sending the malformed remainder
+    // as prose would leave a half-protected message.
+    const source =
+      '{n, plural, one {# item} other {# items}} then {m, plural, one {# gift';
+    const result = parseIcu(source);
+
+    expect(result.isIcu).toBe(false);
+    expect(result.reassemble([])).toBe(source);
+  });
+});
diff --git a/tests/unit/sync/sync-locale-translator.test.ts b/tests/unit/sync/sync-locale-translator.test.ts
index ed5d5ac1..9a43f0ed 100644
--- a/tests/unit/sync/sync-locale-translator.test.ts
+++ b/tests/unit/sync/sync-locale-translator.test.ts
@@ -1935,4 +1935,43 @@ describe('LocaleTranslator', () => {
       expect(result.fileResult.failed).toBe(1);
     });
   });
+
+  describe('ICU messages', () => {
+    it('should not submit an internal ICU marker as a translatable text', async () => {
+      const diffs = [
+        makeDiff('greeting', 'Hello'),
+        makeDiff('items', '{n, plural, one {# item} other {# items}}'),
+      ];
+      const { mock, calls } = captureTranslateBatch([]);
+
+      await makeTranslator(mock, makeConfig(), true).translate(
+        makeCtx(diffs, new Map())
+      );
+
+      const sent = calls.flatMap((c) => c.texts);
+      expect(sent.some((t) => t.includes('__ICU_PLACEHOLDER_'))).toBe(false);
+      // The branches still go out, one segment each.
+      expect(sent).toContain('__VAR_HASH_0__ item');
+      expect(sent).toContain('__VAR_HASH_0__ items');
+    });
+
+    it('should protect every ICU block in a message, not only the first', async () => {
+      const diffs = [
+        makeDiff(
+          'both',
+          'You have {n, plural, one {# item} other {# items}} and ' +
+            '{m, plural, one {# gift} other {# gifts}} waiting.'
+        ),
+      ];
+      const { mock, calls } = captureTranslateBatch([]);
+
+      await makeTranslator(mock, makeConfig(), true).translate(
+        makeCtx(diffs, new Map())
+      );
+
+      const sent = calls.flatMap((c) => c.texts);
+      expect(sent.some((t) => t.includes('plural'))).toBe(false);
+      expect(sent.some((t) => t.includes('other {'))).toBe(false);
+    });
+  });
 });
diff --git a/tests/unit/sync/sync-message-preprocess.test.ts b/tests/unit/sync/sync-message-preprocess.test.ts
index f028716a..de9720b5 100644
--- a/tests/unit/sync/sync-message-preprocess.test.ts
+++ b/tests/unit/sync/sync-message-preprocess.test.ts
@@ -68,13 +68,16 @@ describe('expandPlurals', () => {
 });
 
 describe('detectIcu', () => {
-  it('replaces ICU positions with __ICU_PLACEHOLDER_{ti}__ and preserves positions', () => {
+  it('blanks ICU positions and preserves positions', () => {
     const input = ['plain text', '{n, plural, one {# item} other {# items}}'];
 
     const { extendedTexts, icuMappings } = detectIcu(input);
 
     expect(extendedTexts[0]).toBe('plain text');
-    expect(extendedTexts[1]).toBe('__ICU_PLACEHOLDER_1__');
+    // An ICU string is translated segment-by-segment, so its slot in the main
+    // batch holds nothing to translate. A marker token was itself submitted and
+    // billed as a text, and cached under its own key.
+    expect(extendedTexts[1]).toBe('');
     expect(icuMappings).toHaveLength(1);
     expect(icuMappings[0]!.textIndex).toBe(1);
   });
@@ -107,7 +110,7 @@ describe('reassembleIcu', () => {
 
     await reassembleIcu(service, results, icuMappings, { targetLang: 'de' });
 
-    expect(extendedTexts[0]).toBe('__ICU_PLACEHOLDER_0__');
+    expect(extendedTexts[0]).toBe('');
     expect(results[0]).not.toBeNull();
     expect(results[0]?.text).toBe('{count, plural, one {} other {DE # items}}');
   });

From 8e07ac08a5b17f1357d6c3876fd21c32baa81b88 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 09:22:41 +0200
Subject: [PATCH 150/256] fix(translate): refuse a translation that lost a
 placeholder, rather than write the token
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

restorePlaceholders substituted every token it could find and silently left the
rest alone, with nothing checking that the tokens the CLI injected came back.
Re-casing or re-spacing an unfamiliar token is ordinary MT behaviour, so
`__VAR_0__` returning as `__ Var_0 __` printed the CLI's own scaffolding to
stdout, wrote it to a single output file, and wrote it across a whole directory —
every time at exit 0 with no warning. Only sync caught it, because only sync has
a placeholder validator.

unresolvedPlaceholders() names the originals whose tokens are absent, which
restorePlaceholders cannot report for itself. translate() asserts on it and
fails with exit 5; the batch path fails the one file, since a file with no
placeholders in it is unaffected and still translates.

The assertion runs before the cache write, so a response that lost a placeholder
cannot become an entry that reproduces the same output offline, and a poisoned
entry from an earlier version is refused on read.

sync is deliberately untouched: its validator already withholds the key and
retries it, and validation.check_placeholders: false remains the documented way
to write such a translation on purpose.

Refs cli-8kr2.34

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   2 +
 src/services/batch-translation.ts             |  28 ++-
 src/services/translation.ts                   |   6 +
 src/utils/text-preservation.ts                |  62 ++++++
 .../cli-placeholder-postcondition.e2e.test.ts | 113 ++++++++++
 tests/e2e/mangling-server.cjs                 |  56 +++++
 .../file-translation.integration.test.ts      |  35 +++
 tests/unit/placeholder-postcondition.test.ts  | 205 ++++++++++++++++++
 9 files changed, 501 insertions(+), 10 deletions(-)
 create mode 100644 tests/e2e/cli-placeholder-postcondition.e2e.test.ts
 create mode 100644 tests/e2e/mangling-server.cjs
 create mode 100644 tests/unit/placeholder-postcondition.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7c9e7983..365c7534 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **translate**: **a translation that lost one of your placeholders is now a failure rather than output.** `deepl translate` exits 5 and writes nothing where it previously printed or wrote the CLI's internal `__ Var_0 __` scaffolding at exit 0, and a directory run reports those files as failed. Anything scraping `translate` output was already receiving unusable text in this case; it now sees a non-zero exit instead. See Fixed.
+
 - **translate/sync**: **two exit codes move for files containing an empty string value.** `deepl translate <file>` exits 0 and writes its output where it used to crash with exit 1, and `deepl sync` exits 0 where it used to exit 12 on every run forever. A rate limit part-way through a large structured file now exits 3 rather than 1, so a CI wrapper that treats 3 as retryable starts retrying it. See Fixed for the measurements.
 
 - **sync**: **`deepl sync --force` without `--yes` now exits 6 wherever it cannot prompt**, not just under `CI=true`. Any automation that runs it from a git hook, cron job, `make` target or container entrypoint — anything with piped or closed stdin, plus `--no-input` — has to add `--yes`. See Security for why it was doing the opposite and what that cost.
@@ -119,6 +121,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **translate**: **the CLI's own internal placeholder tokens can no longer be written into your text.** `restorePlaceholders` substituted every `__VAR_n__` it could find and silently left the rest alone, with nothing checking that the tokens the CLI had injected came back at all. Re-casing and re-spacing an unfamiliar token is ordinary MT behaviour, so `__VAR_0__` returning as `__ Var_0 __` produced, measured against a mock endpoint that does exactly that: `deepl translate "Welcome back, {username}!" --to de` printing `XX Welcome back, __ Var_0 __!` at **exit 0** with no warning; `deepl translate a.txt --output a.de.txt` writing the same to disk at exit 0; and a directory run writing it into every file at `✓ Successful: 2`. Only `sync` caught it, because only `sync` has a placeholder validator. All three paths now check the post-condition: `translate` fails with exit 5 naming the variables it lost (`The translation lost the placeholder {username}. … Nothing was written.`) and a suggestion pointing at the endpoint, and a directory run fails only the affected files — a file with no placeholders in it is unaffected and still translated. The check runs **before** the cache write, so a response that lost a placeholder never becomes a cache entry that reproduces the same output offline; a poisoned entry from an earlier version is refused on read for the same reason. `sync` is deliberately unchanged: its validator already withholds the key, counts it failed and retries it next run, and `validation.check_placeholders: false` stays the documented way to write such a translation anyway.
+
 - **sync**: **every ICU block in a message is protected, not just the first.** `parseIcu` found one block with a single non-global match, then pushed the entire remaining suffix as one ordinary prose segment — so the second and later blocks were submitted to the MT engine as translatable text, which is the exact exposure the module exists to prevent. Measured against a mock endpoint with `You have {n, plural, one {# item} other {# items}} and {m, plural, one {# gift} other {# gifts}} waiting.`, the outbound request was `["You have ", "__VAR_HASH_0__ item", "__VAR_HASH_0__ items", " and {m, plural, one {# gift} other {# gifts}} waiting."]` — the first block's selectors and `#` correctly protected, the second block's full syntax sent as prose. A real engine translating `other` to `andere` yields a message with no `other` branch, which throws at render time. Detection now walks the whole string, emitting each run of prose between blocks as its own segment and each block through the same brace-counting parser, with leaf references reindexed into one combined segment list; the same request is now `["You have ", "__VAR_HASH_0__ item", "__VAR_HASH_0__ items", " and ", "__VAR_HASH_0__ gift", "__VAR_HASH_0__ gifts", " waiting."]`. Adjacent blocks with no prose between them, three or more blocks, and nested ICU are all covered. The documented safe fallback is unchanged and now applies to the whole message: a string holding **any** block that will not parse passes through untouched rather than half-protected.
 
 - **sync**: **the internal ICU marker is no longer submitted and billed as a text.** A string routed to segment-by-segment ICU translation had its slot in the main batch filled with `__ICU_PLACEHOLDER_<n>__`, which went to the API as an ordinary text, was billed, and was cached under its own key — measured as a whole extra request per batch containing an ICU string. The slot now holds nothing to translate, so `translateBatch` skips it (see the empty-value entry above); `reassembleIcu` overwrites every mapped index, so the blank cannot reach a target file.
diff --git a/docs/API.md b/docs/API.md
index 86fa29a6..b9eb6fef 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3368,6 +3368,8 @@ Remediation: run `deepl usage` to see remaining characters, or upgrade the plan
 
 Connection-layer failure or transient server outage. Covers TCP errors (`ECONNREFUSED`, `ENOTFOUND`, `ECONNRESET`, `ETIMEDOUT`, socket hang up), timeouts, proxy misconfigurations, and HTTP 503 responses. Also emitted for malformed or empty API responses thrown from `src/api/translation-client.ts` and `src/api/write-client.ts`, and from document/structured-file translation when the polling response is unparseable.
 
+A response that came back without the placeholder tokens the CLI substituted for your variables counts as malformed here too: `translate` names the variables it lost (`{username}`, `%s`) and writes nothing rather than leaving its own internal tokens in your text. A directory run fails only the affected files and reports each one in the summary, so its exit code follows the usual batch mapping (`1` when nothing translated, `12` when some did).
+
 Remediation: check connectivity and `HTTPS_PROXY` / `HTTP_PROXY` env vars, then retry.
 
 #### 6 — InvalidInput
diff --git a/src/services/batch-translation.ts b/src/services/batch-translation.ts
index e4b56da0..ef3995d9 100644
--- a/src/services/batch-translation.ts
+++ b/src/services/batch-translation.ts
@@ -18,6 +18,8 @@ import {
   preserveCodeBlocks,
   preserveVariables,
   restorePlaceholders,
+  unresolvedPlaceholders,
+  unresolvedPlaceholderMessage,
 } from '../utils/text-preservation.js';
 import { TranslationOptions } from '../types/index.js';
 import { safeReadFile } from '../utils/safe-read-file.js';
@@ -347,17 +349,23 @@ export class BatchTranslationService {
         for (let i = 0; i < batch.length; i++) {
           const entry = batch[i]!;
           const result = results[i];
-          if (!result) {
-            failed.push({
-              file: entry.file,
-              error: 'No translation returned for this file',
-            });
+          // A batch run fails the one file rather than the whole request, so an
+          // unusable translation is reported here rather than thrown.
+          const rejectFile = (error: string): void => {
+            failed.push({ file: entry.file, error });
             completed++;
-            onProgress?.({
-              completed,
-              total: totalFiles,
-              current: entry.file,
-            });
+            onProgress?.({ completed, total: totalFiles, current: entry.file });
+          };
+          if (!result) {
+            rejectFile('No translation returned for this file');
+            continue;
+          }
+          const unresolved = unresolvedPlaceholders(
+            result.text,
+            entry.preservationMap
+          );
+          if (unresolved.length > 0) {
+            rejectFile(unresolvedPlaceholderMessage(unresolved));
             continue;
           }
           const translatedText = restorePlaceholders(
diff --git a/src/services/translation.ts b/src/services/translation.ts
index 7913718a..1a24d959 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -31,6 +31,7 @@ import {
   preserveCodeBlocks,
   preserveVariables,
   restorePlaceholders,
+  assertPlaceholdersSurvived,
 } from '../utils/text-preservation.js';
 
 export { MULTI_TARGET_CONCURRENCY };
@@ -166,6 +167,7 @@ export class TranslationService {
       const cachedResult = this.cache?.get(cacheKey, isTranslationResult);
       if (cachedResult) {
         Logger.verbose('[verbose] Cache hit');
+        assertPlaceholdersSurvived(cachedResult.text, preservationMap);
         return {
           ...cachedResult,
           text: restorePlaceholders(cachedResult.text, preservationMap),
@@ -184,6 +186,10 @@ export class TranslationService {
     const elapsed = Date.now() - startTime;
     Logger.verbose(`[verbose] API response time: ${elapsed}ms`);
 
+    // Checked before the cache write: a response that lost a placeholder must
+    // not become a cache entry that reproduces the same output offline.
+    assertPlaceholdersSurvived(result.text, preservationMap);
+
     // Store in cache
     if (shouldUseCache) {
       this.cache?.set(cacheKey, result);
diff --git a/src/utils/text-preservation.ts b/src/utils/text-preservation.ts
index 6fc6cf85..4aab54d9 100644
--- a/src/utils/text-preservation.ts
+++ b/src/utils/text-preservation.ts
@@ -3,6 +3,8 @@
  * Preserves code blocks and variables during translation by replacing them with placeholders
  */
 
+import { NetworkError } from './errors.js';
+
 export function preserveCodeBlocks(
   text: string,
   preservationMap: Map<string, string>
@@ -54,6 +56,66 @@ export function preserveVariables(
   return processed;
 }
 
+/**
+ * The originals whose placeholder tokens are absent from `text`, in the order
+ * they were preserved.
+ *
+ * `restorePlaceholders` cannot report this itself: it replaces what it finds and
+ * has no way to say what it did not. An engine that re-cases or re-spaces a
+ * token it does not recognise (`__VAR_0__` → `__ Var_0 __`) leaves the CLI's own
+ * scaffolding in the output, so an empty result is the post-condition every
+ * caller without a validator needs to check.
+ */
+export function unresolvedPlaceholders(
+  text: string,
+  preservationMap: Map<string, string>
+): string[] {
+  const missing: string[] = [];
+  for (const [placeholder, original] of preservationMap.entries()) {
+    if (!text.includes(placeholder)) {
+      missing.push(original);
+    }
+  }
+  return missing;
+}
+
+/**
+ * Names what was lost, for a caller that reports rather than throws.
+ */
+export function unresolvedPlaceholderMessage(unresolved: string[]): string {
+  const one = unresolved.length === 1;
+  return (
+    `The translation lost ${one ? 'the placeholder' : 'the placeholders'} ${unresolved.join(', ')}. ` +
+    `The endpoint returned the ${one ? 'token' : 'tokens'} the CLI substituted for ` +
+    `${one ? 'it' : 'them'} in an altered form, so the text would carry the CLI's ` +
+    'internal placeholders instead. Nothing was written.'
+  );
+}
+
+const UNRESOLVED_PLACEHOLDER_SUGGESTION =
+  'Retry; if it repeats, check which endpoint this run used (--api-url, or ' +
+  'api.baseUrl in your config) — it is rewriting the placeholder tokens rather ' +
+  'than returning them unchanged.';
+
+/**
+ * Throws when the engine's output no longer carries every token that was
+ * substituted into the request. Callers with their own validator — sync, which
+ * withholds the key and offers `validation.check_placeholders: false` as an
+ * escape hatch — do not use this.
+ */
+export function assertPlaceholdersSurvived(
+  text: string,
+  preservationMap: Map<string, string>
+): void {
+  const unresolved = unresolvedPlaceholders(text, preservationMap);
+  if (unresolved.length > 0) {
+    throw new NetworkError(
+      unresolvedPlaceholderMessage(unresolved),
+      UNRESOLVED_PLACEHOLDER_SUGGESTION
+    );
+  }
+}
+
 export function restorePlaceholders(
   text: string,
   preservationMap: Map<string, string>
diff --git a/tests/e2e/cli-placeholder-postcondition.e2e.test.ts b/tests/e2e/cli-placeholder-postcondition.e2e.test.ts
new file mode 100644
index 00000000..5215971b
--- /dev/null
+++ b/tests/e2e/cli-placeholder-postcondition.e2e.test.ts
@@ -0,0 +1,113 @@
+/**
+ * E2E tests for the placeholder post-condition on the three translate paths.
+ *
+ * An engine that re-cases or re-spaces the `__VAR_n__` token the CLI substituted
+ * for a user's `{username}` used to have that token printed to stdout, written to
+ * a file, and written across a whole directory — every time at exit 0, with no
+ * warning. Only `sync` caught it, because only `sync` has a validator.
+ */
+
+import { spawn, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir, makeNodeRunCLI } from '../helpers';
+
+describe('CLI placeholder post-condition E2E', () => {
+  const testConfig = createTestConfigDir('e2e-placeholder-postcondition');
+  const testFiles = createTestDir('e2e-placeholder-postcondition-files');
+  let runner: ReturnType<typeof makeNodeRunCLI>;
+  let server: ChildProcess;
+  let baseUrl: string;
+
+  function startManglingServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'node',
+        [path.join(__dirname, 'mangling-server.cjs')],
+        {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: { ...process.env },
+        }
+      );
+
+      server = child;
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = output.match(/PORT=(\d+)/);
+        if (match) resolve(parseInt(match[1]!, 10));
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Mangling server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  beforeAll(async () => {
+    runner = makeNodeRunCLI(testConfig.path, { apiKey: 'test-api-key' });
+    const port = await startManglingServer();
+    baseUrl = `http://127.0.0.1:${port}`;
+  }, 30000);
+
+  afterAll(() => {
+    server.kill();
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  it('refuses to print a translation that lost the placeholder', () => {
+    const result = runner.runCLIExpectError(
+      `translate "Welcome back, {username}!" --to de --no-cache --api-url ${baseUrl}`,
+      { timeout: 30000 }
+    );
+
+    expect(result.status).toBe(5);
+    expect(result.output).toContain('{username}');
+    expect(result.output).not.toContain('Var_0');
+  });
+
+  it('writes no output file when a single file lost the placeholder', () => {
+    const input = path.join(testFiles.path, 'one.txt');
+    const output = path.join(testFiles.path, 'one.de.txt');
+    fs.writeFileSync(input, 'Welcome back, {username}!\n');
+
+    const result = runner.runCLIExpectError(
+      `translate ${input} --to de --no-cache --output ${output} --api-url ${baseUrl}`,
+      { timeout: 30000 }
+    );
+
+    expect(result.status).toBe(5);
+    expect(fs.existsSync(output)).toBe(false);
+  });
+
+  it('fails only the affected files in a directory run', () => {
+    const dir = path.join(testFiles.path, 'src');
+    const out = path.join(testFiles.path, 'out');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'with.txt'), 'Welcome back, {username}!\n');
+    fs.writeFileSync(path.join(dir, 'without.txt'), 'Nothing to preserve\n');
+
+    const result = runner.runCLIExpectError(
+      `translate ${dir} --to de --no-cache --output ${out} --api-url ${baseUrl}`,
+      { timeout: 30000 }
+    );
+
+    // The per-file reason is on stdout, which this helper drops when the
+    // endpoint notice has written to stderr; the unit suite covers its wording.
+    expect(result.status).not.toBe(0);
+    expect(fs.existsSync(path.join(out, 'with.de.txt'))).toBe(false);
+    // A file with no placeholders is unaffected and still translated.
+    expect(fs.existsSync(path.join(out, 'without.de.txt'))).toBe(true);
+  });
+
+  it('translates normally when the text has no placeholders', () => {
+    const output = runner.runCLIAll(
+      `translate "Nothing to preserve" --to de --no-cache --api-url ${baseUrl}`,
+      { timeout: 30000 }
+    );
+
+    expect(output).toContain('[de] Nothing to preserve');
+  });
+});
diff --git a/tests/e2e/mangling-server.cjs b/tests/e2e/mangling-server.cjs
new file mode 100644
index 00000000..156aeb1a
--- /dev/null
+++ b/tests/e2e/mangling-server.cjs
@@ -0,0 +1,56 @@
+/**
+ * A translation endpoint that re-cases and re-spaces the `__VAR_n__` tokens the
+ * CLI substitutes for a user's placeholders — ordinary MT behaviour for a token
+ * the engine does not recognise, and the shape that used to write the CLI's own
+ * scaffolding into a user's file at exit 0.
+ *
+ * Prints `PORT=<port>` on stdout once listening. Runs in its own process because
+ * the test driver blocks its event loop on execSync.
+ *
+ * Usage: node tests/e2e/mangling-server.cjs
+ */
+
+const http = require('http');
+const { URLSearchParams } = require('url');
+
+function mangle(text) {
+  return text.replace(/__VAR_(\d+)__/g, '__ Var_$1 __');
+}
+
+const server = http.createServer((req, res) => {
+  let body = '';
+  req.on('data', (chunk) => (body += chunk));
+  req.on('end', () => {
+    res.setHeader('Content-Type', 'application/json');
+
+    if ((req.url || '').startsWith('/v2/usage')) {
+      res.writeHead(200);
+      return res.end(
+        JSON.stringify({ character_count: 0, character_limit: 1000000 })
+      );
+    }
+
+    if (!(req.url || '').startsWith('/v2/translate')) {
+      res.writeHead(404);
+      return res.end(JSON.stringify({ message: 'not found' }));
+    }
+
+    const texts = new URLSearchParams(body).getAll('text');
+    res.writeHead(200);
+    res.end(
+      JSON.stringify({
+        translations: texts.map((text) => ({
+          text: `[de] ${mangle(text)}`,
+          detected_source_language: 'EN',
+          billed_characters: text.length,
+        })),
+      })
+    );
+  });
+});
+
+server.on('clientError', () => {});
+
+server.listen(0, '127.0.0.1', () => {
+  process.stdout.write(`PORT=${server.address().port}\n`);
+});
diff --git a/tests/integration/file-translation.integration.test.ts b/tests/integration/file-translation.integration.test.ts
index 4dd88cc4..d2298bbd 100644
--- a/tests/integration/file-translation.integration.test.ts
+++ b/tests/integration/file-translation.integration.test.ts
@@ -76,6 +76,41 @@ describe('FileTranslation Integration', () => {
       expect(output).toBe('Hola mundo');
     });
 
+    it('should write no file when the endpoint alters a placeholder token', async () => {
+      const inputPath = path.join(testDir, 'greeting.txt');
+      const outputPath = path.join(testDir, 'greeting.de.txt');
+      fs.writeFileSync(inputPath, 'Welcome back, {username}!');
+
+      let sent = '';
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate', (body: Record<string, unknown>) => {
+          sent = String(body['text']);
+          return true;
+        })
+        .reply(200, () => ({
+          translations: [
+            {
+              // Re-casing and re-spacing an unrecognised token is ordinary MT
+              // behaviour; the CLI must not restore around it silently.
+              text: `[de] ${sent.replace(/__VAR_(\d+)__/g, '__ Var_$1 __')}`,
+              detected_source_language: 'EN',
+            },
+          ],
+        }));
+
+      expect.assertions(4);
+      try {
+        await service.translateFile(inputPath, outputPath, {
+          targetLang: 'de',
+        });
+      } catch (error) {
+        expect((error as { exitCode?: number }).exitCode).toBe(5);
+        expect((error as Error).message).toContain('{username}');
+      }
+      expect(sent).toBe('Welcome back, __VAR_0__!');
+      expect(fs.existsSync(outputPath)).toBe(false);
+    });
+
     it('should translate a .md file via API', async () => {
       const inputPath = path.join(testDir, 'readme.md');
       const outputPath = path.join(testDir, 'readme-de.md');
diff --git a/tests/unit/placeholder-postcondition.test.ts b/tests/unit/placeholder-postcondition.test.ts
new file mode 100644
index 00000000..a5fed1d3
--- /dev/null
+++ b/tests/unit/placeholder-postcondition.test.ts
@@ -0,0 +1,205 @@
+/**
+ * `restorePlaceholders` replaced the placeholders it could find and silently
+ * left the rest alone, with nothing verifying that the tokens the CLI injected
+ * came back intact. Re-casing or re-spacing an unknown token is ordinary MT
+ * behaviour, so `__VAR_0__` returning as `__ Var_0 __` wrote the CLI's own
+ * internal scaffolding into the user's file — or printed it to stdout — at
+ * exit 0 with no warning.
+ *
+ * The sync path already catches this in the placeholder validator. The three
+ * translate paths had no validator at all.
+ */
+
+import {
+  preserveVariables,
+  restorePlaceholders,
+  unresolvedPlaceholders,
+  unresolvedPlaceholderMessage,
+} from '../../src/utils/text-preservation';
+import { TranslationService } from '../../src/services/translation';
+import { BatchTranslationService } from '../../src/services/batch-translation';
+import type { FileTranslationService } from '../../src/services/file-translation';
+import type { DeepLClient } from '../../src/api/deepl-client';
+import type { ConfigService } from '../../src/storage/config';
+import type { CacheService } from '../../src/storage/cache';
+import type { TranslationResult } from '../../src/api/translation-client';
+import { NetworkError } from '../../src/utils/errors';
+import { Logger } from '../../src/utils/logger';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+/** How an engine commonly mangles a token it does not recognise. */
+function mangle(text: string): string {
+  return text.replace(/__VAR_(\d+)__/g, '__ Var_$1 __');
+}
+
+describe('unresolvedPlaceholders', () => {
+  it('should name the originals whose tokens are missing from the text', () => {
+    const map = new Map<string, string>();
+    const processed = preserveVariables('Hi {name}, you have %d left', map);
+
+    expect(unresolvedPlaceholders(mangle(processed), map)).toEqual([
+      '{name}',
+      '%d',
+    ]);
+  });
+
+  it('should report only the tokens that are actually missing', () => {
+    const map = new Map<string, string>();
+    const processed = preserveVariables('Hi {name}, you have %d left', map);
+    const partly = processed.replace('__VAR_0__', '__ Var_0 __');
+
+    expect(unresolvedPlaceholders(partly, map)).toEqual(['{name}']);
+  });
+
+  it('should report nothing when every token survived', () => {
+    const map = new Map<string, string>();
+    const processed = preserveVariables('Hi {name}', map);
+
+    expect(unresolvedPlaceholders(`[de] ${processed}`, map)).toEqual([]);
+    expect(unresolvedPlaceholders('anything', new Map())).toEqual([]);
+  });
+
+  it('should read as a sentence for one placeholder and for several', () => {
+    expect(unresolvedPlaceholderMessage(['{name}'])).toBe(
+      'The translation lost the placeholder {name}. The endpoint returned the ' +
+        'token the CLI substituted for it in an altered form, so the text would ' +
+        "carry the CLI's internal placeholders instead. Nothing was written."
+    );
+    expect(unresolvedPlaceholderMessage(['{name}', '%d'])).toBe(
+      'The translation lost the placeholders {name}, %d. The endpoint returned ' +
+        'the tokens the CLI substituted for them in an altered form, so the text ' +
+        "would carry the CLI's internal placeholders instead. Nothing was written."
+    );
+  });
+
+  it('should leave restorePlaceholders itself unchanged', () => {
+    const map = new Map([['__VAR_0__', '{name}']]);
+
+    expect(restorePlaceholders('Hi __VAR_0__', map)).toBe('Hi {name}');
+    expect(restorePlaceholders('Hi __ Var_0 __', map)).toBe('Hi __ Var_0 __');
+  });
+});
+
+interface Harness {
+  service: TranslationService;
+  cacheSets: TranslationResult[];
+}
+
+function makeService(
+  reply: (text: string) => string,
+  cached?: TranslationResult
+): Harness {
+  const cacheSets: TranslationResult[] = [];
+  const client = {
+    resolvedBaseUrl: 'https://api-free.deepl.com',
+    translate: (text: string) => Promise.resolve({ text: reply(text) }),
+  } as unknown as DeepLClient;
+  const config = {
+    get: () => ({ defaults: {} }),
+    getValue: (key: string) => (key === 'cache.enabled' ? true : undefined),
+  } as unknown as ConfigService;
+  const cache = {
+    get: () => cached ?? null,
+    set: (_key: string, value: TranslationResult) => {
+      cacheSets.push(value);
+    },
+  } as unknown as CacheService;
+
+  return {
+    service: new TranslationService(client, config, cache),
+    cacheSets,
+  };
+}
+
+describe('TranslationService.translate placeholder post-condition', () => {
+  it('should refuse a translation that lost the token, naming the variable', async () => {
+    const { service } = makeService((t) => `[de] ${mangle(t)}`);
+
+    expect.assertions(3);
+    try {
+      await service.translate('Welcome back, {username}!', {
+        targetLang: 'de',
+      });
+    } catch (error) {
+      expect(error).toBeInstanceOf(NetworkError);
+      expect((error as Error).message).toContain('{username}');
+      expect((error as NetworkError).exitCode).toBe(5);
+    }
+  });
+
+  it('should not cache a response whose placeholders were lost', async () => {
+    const { service, cacheSets } = makeService((t) => `[de] ${mangle(t)}`);
+
+    await expect(
+      service.translate('Hi {name}', { targetLang: 'de' })
+    ).rejects.toThrow(NetworkError);
+    expect(cacheSets).toEqual([]);
+  });
+
+  it('should refuse a cached entry whose placeholders were already lost', async () => {
+    const { service } = makeService((t) => t, { text: '[de] __ Var_0 __' });
+
+    await expect(
+      service.translate('Hi {name}', { targetLang: 'de' })
+    ).rejects.toThrow(/\{name\}/);
+  });
+
+  it('should pass an intact translation through and cache it', async () => {
+    const { service, cacheSets } = makeService((t) => `[de] ${t}`);
+
+    const result = await service.translate('Welcome back, {username}!', {
+      targetLang: 'de',
+    });
+
+    expect(result.text).toBe('[de] Welcome back, {username}!');
+    expect(cacheSets).toHaveLength(1);
+  });
+});
+
+describe('BatchTranslationService placeholder post-condition', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-postcond-'));
+    jest.spyOn(Logger, 'error').mockImplementation(() => {});
+    jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('should fail the file rather than write the internal token into it', async () => {
+    const good = path.join(testDir, 'good.txt');
+    const bad = path.join(testDir, 'bad.txt');
+    fs.writeFileSync(good, 'Plain sentence\n');
+    fs.writeFileSync(bad, 'Welcome back, {username}!\n');
+    const outDir = path.join(testDir, 'out');
+
+    const translation = {
+      translateBatch: (texts: string[]) =>
+        Promise.resolve(texts.map((t) => ({ text: `[de] ${mangle(t)}` }))),
+    } as unknown as TranslationService;
+    const batch = new BatchTranslationService(
+      { isSupportedFile: () => true } as unknown as FileTranslationService,
+      { translationService: translation }
+    );
+
+    const result = await batch.translateFiles(
+      [good, bad],
+      { targetLang: 'de' },
+      { outputDir: outDir }
+    );
+
+    expect(result.failed.map((f) => path.basename(f.file))).toEqual([
+      'bad.txt',
+    ]);
+    expect(result.failed[0]?.error).toContain('{username}');
+    expect(result.successful.map((s) => path.basename(s.file))).toEqual([
+      'good.txt',
+    ]);
+    expect(fs.existsSync(path.join(outDir, 'bad.de.txt'))).toBe(false);
+  });
+});

From 3890d32edaece8bc2f3826a982b083fe60e09ee2 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 10:04:53 +0200
Subject: [PATCH 151/256] fix(sync): stop sync pull writing source text and
 claiming a review it cannot verify
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The merge that applies a TMS pull response read
`pulledKeys[key] ?? existingTarget.get(key) ?? entry.value`, so a key the
export omits and the target file lacks was filled in with the source string.
Measured against a mock TMS whose `de` export carried only `greeting`, a
`locales/de.json` came back holding `"brand_new": "Only in source"` at exit 0.
The final fallback is gone: a key with a value on neither side is omitted from
the entry list, which is what `reconstruct` needs to leave it out of the file,
and matches what the locale translator already does for a key it could not
translate. That also covers the case the finding did not name — with no target
file yet, the source is the reconstruction template, so every untranslated key
was written into the new locale as source text.

Every pulled key was also stamped `review_status: human_reviewed`. The export
contract is a flat `{ key: value }` map with no per-entry review flag, so there
was nothing to base that on, and a TMS exporting machine-translation drafts had
them recorded as human-reviewed in a committed file. Pulled entries now record
`status: translated` and no `review_status`, which is the type's way of saying
"unknown".

The pulled value still wins over the local one — neither side carries a
timestamp, so "which is newer" is unanswerable, and pull exists to bring the
reviewed copy in — but the overwrite was silent. Pull now counts the existing
local translations it replaced and names the count, with --verbose naming each
key and file, and `sync pull --dry-run` previews the whole thing without
writing a target file or the lockfile.

Refs cli-8kr2.36
---
 CHANGELOG.md                                  |  8 ++
 docs/SYNC.md                                  |  9 +-
 src/cli/commands/sync/register-sync-pull.ts   | 29 +++++-
 src/sync/sync-tms.ts                          | 30 +++++--
 src/sync/sync-utils.ts                        | 36 +++++---
 tests/e2e/cli-sync-push-pull.e2e.test.ts      | 72 +++++++++++++++
 .../integration/sync-tms.integration.test.ts  | 90 ++++++++++++++++++-
 .../register-sync.commander-snapshot.test.ts  | 21 ++++-
 tests/unit/sync/sync-utils.test.ts            | 31 ++++++-
 9 files changed, 298 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 365c7534..8ee230c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **sync**: `deepl sync pull --dry-run` previews a pull without writing anything — no target file, no `.deepl-sync.lock`. It reports how many translations would be pulled and how many existing local translations would be replaced, and `--verbose` names each key and file whose TMS value differs from the local one. `--format json` carries `replaced` and `dryRun` alongside `pulled`. Pull is the one sync command that replaces hand edits with content the CLI has no way to date, and it was the only writing sync command with no preview mode; `sync` itself and `sync resolve` both have one. The flag is also accepted on the parent (`deepl sync --dry-run pull`), matching how `sync resolve` reads it.
+
 - **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API). It was previously accepted and then silently discarded with a "document mode does not support --glossary" warning, even though `POST /v2/document` supports glossaries. Repeating the flag works here too, with the same merge behaviour and the same API-decided conflict resolution. `--from` is required, because the API rejects a document glossary without a source language; `--translation-memory` remains unsupported for documents. Note that glossary matching is context-dependent for documents exactly as it is for text — a term applied in one sentence may be left alone in another.
 
 - **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply. When several glossaries define the same source term, **which mapping wins is the API's choice and does not follow flag order** — verified live with two glossaries defining the same term, where the same one won in both orderings in five of six trials and the first-listed one won in the sixth, so position is not a way to override a term. The order is still sent as given and never sorted, because it is part of the cache key: reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API: `POST /v2/translate` accepts `glossary_ids` as repeated form fields and resolves them in order, rejects a sixth with `A maximum of 5 glossaries can be specified per request.`, and rejects `glossary_id` and `glossary_ids` together with `Specify either glossary_id or glossary_ids, not both.` -- which is why the CLI collapses a single glossary to `glossary_id` rather than sending both. The multipart `POST /v2/document` takes one comma-joined value, since multipart does not parse repeated fields as a list. Both halves of that are now confirmed against the live API with two real single-entry glossaries: a comma-joined `glossary_ids` applies the terms from both, while sending the same two IDs as repeated multipart fields applies only the first and reports no error, so the comma-joining is required rather than merely sufficient.
@@ -35,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **`sync pull`'s lockfile and output shapes both change.** Pulled keys no longer carry `review_status` at all (see Security), so anything reading `review_status === "human_reviewed"` out of `.deepl-sync.lock` to find reviewed strings stops matching pulled entries — an absent field means "unknown", which is all the export response supports. A key with no translation in the export and none in the target file is now **absent** from the written target file rather than present holding the source string (see Fixed). `sync pull --format json` gains `replaced` and `dryRun` fields, and the text output gains a second line naming the replaced count when it is non-zero.
+
 - **translate**: **a translation that lost one of your placeholders is now a failure rather than output.** `deepl translate` exits 5 and writes nothing where it previously printed or wrote the CLI's internal `__ Var_0 __` scaffolding at exit 0, and a directory run reports those files as failed. Anything scraping `translate` output was already receiving unusable text in this case; it now sees a non-zero exit instead. See Fixed.
 
 - **translate/sync**: **two exit codes move for files containing an empty string value.** `deepl translate <file>` exits 0 and writes its output where it used to crash with exit 1, and `deepl sync` exits 0 where it used to exit 12 on every run forever. A rate limit part-way through a large structured file now exits 3 rather than 1, so a CI wrapper that treats 3 as retryable starts retrying it. See Fixed for the measurements.
@@ -121,6 +125,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`sync pull` no longer writes source-language text into a target locale file, and no longer replaces a local translation without saying so.** The merge that applies a pull response read `pulledKeys[key] ?? existingTarget.get(key) ?? entry.value`, so a key the TMS export omits **and** the target file lacks was filled in with the source string. Measured against a mock TMS whose `de` export carried only `greeting`: a source file holding `greeting`/`farewell`/`brand_new` and a `locales/de.json` holding the first two produced a German file containing `"brand_new": "Only in source"` — English, indistinguishable from a translation to anything reading the file — at **exit 0**, with the one-line summary `Pulled 1 translations from TMS`. The final `?? entry.value` is gone; a key with a value on neither side is now omitted from the entry list, which is what `reconstruct` needs to leave it out of the file, and matches what the locale translator already does for a key it could not translate (it pushes nothing rather than the source). An empty string is a translation and is still preserved. The same change fixes the case the finding did not name: when the target file does not exist yet, the source file is used as the reconstruction template, so **every** untranslated key was written into the new locale as English; only the keys the export actually carries are written now. Separately, the pulled value has always won over the local one and always will — neither side of the documented export contract carries a timestamp, so "which is newer" is not a question that can be answered, and pull exists to bring the reviewed copy in — but the overwrite was completely silent. Pull now counts the existing local translations it replaced and names the count (`Replaced 1 existing local translation with the TMS version. Use --dry-run to preview a pull before it overwrites local edits.`), with `--verbose` naming each key and file. See Added for the preview mode.
+
 - **translate**: **the CLI's own internal placeholder tokens can no longer be written into your text.** `restorePlaceholders` substituted every `__VAR_n__` it could find and silently left the rest alone, with nothing checking that the tokens the CLI had injected came back at all. Re-casing and re-spacing an unfamiliar token is ordinary MT behaviour, so `__VAR_0__` returning as `__ Var_0 __` produced, measured against a mock endpoint that does exactly that: `deepl translate "Welcome back, {username}!" --to de` printing `XX Welcome back, __ Var_0 __!` at **exit 0** with no warning; `deepl translate a.txt --output a.de.txt` writing the same to disk at exit 0; and a directory run writing it into every file at `✓ Successful: 2`. Only `sync` caught it, because only `sync` has a placeholder validator. All three paths now check the post-condition: `translate` fails with exit 5 naming the variables it lost (`The translation lost the placeholder {username}. … Nothing was written.`) and a suggestion pointing at the endpoint, and a directory run fails only the affected files — a file with no placeholders in it is unaffected and still translated. The check runs **before** the cache write, so a response that lost a placeholder never becomes a cache entry that reproduces the same output offline; a poisoned entry from an earlier version is refused on read for the same reason. `sync` is deliberately unchanged: its validator already withholds the key, counts it failed and retries it next run, and `validation.check_placeholders: false` stays the documented way to write such a translation anyway.
 
 - **sync**: **every ICU block in a message is protected, not just the first.** `parseIcu` found one block with a single non-global match, then pushed the entire remaining suffix as one ordinary prose segment — so the second and later blocks were submitted to the MT engine as translatable text, which is the exact exposure the module exists to prevent. Measured against a mock endpoint with `You have {n, plural, one {# item} other {# items}} and {m, plural, one {# gift} other {# gifts}} waiting.`, the outbound request was `["You have ", "__VAR_HASH_0__ item", "__VAR_HASH_0__ items", " and {m, plural, one {# gift} other {# gifts}} waiting."]` — the first block's selectors and `#` correctly protected, the second block's full syntax sent as prose. A real engine translating `other` to `andere` yields a message with no `other` branch, which throws at render time. Detection now walks the whole string, emitting each run of prose between blocks as its own segment and each block through the same brace-counting parser, with leaf references reindexed into one combined segment list; the same request is now `["You have ", "__VAR_HASH_0__ item", "__VAR_HASH_0__ items", " and ", "__VAR_HASH_0__ gift", "__VAR_HASH_0__ gifts", " waiting."]`. Adjacent blocks with no prose between them, three or more blocks, and nested ICU are all covered. The documented safe fallback is unchanged and now applies to the whole message: a string holding **any** block that will not parse passes through untouched rather than half-protected.
@@ -410,6 +416,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync**: **`sync pull` no longer records `review_status: human_reviewed` for content it never verified was reviewed.** Every key a pull applied was stamped `human_reviewed` in `.deepl-sync.lock`, unconditionally. The documented export contract is `GET /keys/export` returning `{ "key": "translated value", … }` — a flat map with no per-entry review flag — so there was nothing in the response to base that claim on, and a TMS that exports machine-translation drafts had them recorded in a committed file as human-reviewed. Where the `tms.server` in a checkout is not one the operator chose, the endpoint controls the strings *and* the review label attached to them. Measured: a mock export returning `{"greeting":"Hallo vom TMS"}` produced `"de": {"hash":"185f8db32271","review_status":"human_reviewed","status":"translated","translated_at":"…"}`. Pulled entries now record `status: translated` with **no** `review_status`, which is the type's way of saying "unknown"; `human_reviewed` is still honoured when a person or another tool writes it, and `--flag-for-review` still writes `machine_translated`, so nothing else in the lockfile changes. Nothing in the CLI reads `review_status` today, which is exactly why a false value could sit there unnoticed until something did — including the `tms.require_review` gate the config schema advertised.
+
 - **sync**: **`--force` is refused when there is no terminal to confirm it on, instead of treating "nobody can answer" as yes.** The guard threw for `CI=true` and prompted on a TTY, and had no third branch — so in a git hook, cron job, `make` target, container entrypoint, Jenkins agent, or plain `deepl sync --force < /dev/null`, the prompt was skipped and the run **proceeded**. This inverted the convention `confirm()` exists to enforce: it returns `false` for a non-TTY, deliberately fail-closed, and the seven other destructive sites (`cache clear`, `admin`, `config`, two in `glossary`, two in `style-rules`) all inherit that auto-NO. This one site turned it into auto-YES, for the single most destructive operation the CLI has. Measured on a fully synced project whose `locales/de.json` had been hand-edited to stand in for human review: `env -u CI deepl sync --force < /dev/null` printed no prompt and no warning, reported `✓ de: 3/3 keys`, `Sync complete: 3 new`, **exit 0**, and replaced all three reviewed strings with machine output — with no `.deepl.bak` surviving, so the edits were unrecoverable. **`--no-input` was ignored on the same path**, though it documents itself as "abort instead of prompting": `deepl --no-input sync --force` destroyed the same edits at exit 0. Both now exit 6 with a message naming `--yes` as the only way to run `--force` unattended, and `--yes` still works everywhere it did. Refusing rather than aborting quietly, matching the existing `CI=true` branch and the TMS destination-trust gate: unlike `cache clear`, declining here abandons the whole sync, so exit 0 would report an up-to-date project for a run that did nothing. An interactive decline is unchanged at exit 0, and now prints `Aborted.` like its seven siblings. Verified on a real terminal through a pty: the prompt appears, `n` aborts with the edits intact, `y` proceeds. The gate is a single `canPrompt()` in `utils/confirm.ts`, which `confirm()` itself now uses, so the two cannot drift apart.
 
 - **sync**: **a lockfile is now checked member by member before sync uses it, instead of being version-checked and then cast.** `SyncLockManager.read()` validated `version` and that `entries` was an object, then cast the rest of the repository's JSON to `SyncLockFile` — so `stats`, each per-file map, each entry and each translation were dereferenced unguarded. Four shapes reproduced by execution against a mock endpoint, all from a lockfile a hostile or merge-mangled repository ships: **a missing `stats`** crashed with `Error: Cannot set properties of undefined (setting 'total_keys')` and exit 1 **after the endpoint had been hit and `de.json` written**, leaving the lockfile as the attacker's stub so the next run re-billed everything; **an entry with no `translations` container** crashed with `Cannot read properties of undefined (reading 'de')`, and the same lockfile took `sync status` — a read-only command — down with `Cannot convert undefined or null to object`; **a per-file map that is a string** crashed with `Cannot delete property '0' of [object String]`; and **`entries` as an array** was accepted silently, exit 0, with the run's results written onto named properties of that array and then discarded by the serializer, so the lockfile recorded `"entries": []` beside `total_keys: 2` and every later run re-billed the project in silence, forever. Two more shapes found while probing: **a null translation** crashed with `Cannot read properties of null (reading 'status')` — one level deeper than the shape check the finding proposed — and **`stats` as a string** crashed with `Cannot create property 'total_keys' on string`. Every one of them now exits 0 with a well-formed lockfile. **Malformed members are dropped individually, not by discarding the file**: a key that loses its entry is translated and billed again, so resetting a whole lockfile over one bad member would hand whoever wrote it a full re-translation of the project. The count is reported at WARN level and the original is copied to `.deepl-sync.lock.bak-v1-malformed-<timestamp>`. `entries` that is not a map at all has nothing to salvage and takes the existing full-sync path with its own `-entries-not-a-map` tag. **`stats` is no longer trusted at all**: it is derived from `entries` and recomputed on every write that follows a mutation, and nothing reads the on-disk values for their own sake, so read() recomputes the counts from the surviving entries rather than validating what the file claims — which also means the counts can no longer disagree with the entries they describe. The repaired `entries` is rebuilt with `setOwnMember`, so a source path or i18n key named `__proto__` is carried across as an own property. In-repo precedent for the shape of the fix: `sync/tms-client.ts` already validated an untrusted map this way for pulled keys.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 8d87937c..5ba74117 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -380,7 +380,7 @@ Each translation entry in the lockfile records:
 | `status` | `translated`, `failed`, or `pending` |
 | `character_count` | Characters billed by the DeepL API for this translation |
 | `context_sent` | `true` when source code context was included in the API request |
-| `review_status` | `machine_translated` or `human_reviewed` (set by `--flag-for-review`) |
+| `review_status` | `machine_translated` (set by `--flag-for-review`) or `human_reviewed`. The CLI only ever writes `machine_translated`; `human_reviewed` is honoured when a person or another tool sets it, and is never inferred from a TMS pull. Absent means unknown |
 
 **Formatting.** Containers are written one key per line, but each translation entry is written on a **single line**:
 
@@ -842,9 +842,16 @@ deepl sync pull [OPTIONS]
 | `--locale <langs>` | Pull specific locales only |
 | `--format <fmt>` | Output format: `text` (default), `json` |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
+| `--dry-run` | Preview what the pull would change without writing any file |
 
 Each target locale's approved dictionary is fetched exactly once per `sync pull` run (one GET per locale from the TMS export endpoint), then applied to every matching source file locally. Projects with many source files per bucket do not multiply wire bytes by the source-file count.
 
+**The TMS wins, and pull says how often it did.** For a key the export carries, the TMS value replaces whatever the target file holds -- there is no timestamp on either side to compare, so "which is newer" is not a question the CLI can answer. That is the intended direction of `pull` (the export is the reviewed copy), but it means a hand edit made locally since the last push is overwritten. Pull therefore reports the count of existing local translations it replaced, and `--verbose` names each key and file. Run `deepl sync pull --dry-run` first to see that count -- and, with `--verbose`, the exact keys -- before anything is written. `--dry-run` writes neither target files nor `.deepl-sync.lock`; the JSON output carries `replaced` and `dryRun` alongside `pulled`.
+
+**A key with no translation anywhere is left out.** When the export omits a key and the target file has no value for it either, the key is omitted from the reconstructed target rather than filled in with the source string. Writing the source text would put the source language in the target file and record it in the lockfile as translated, which no later run revisits. An empty string counts as a translation and is preserved.
+
+**Pull does not claim human review.** The export endpoint returns `{ "key": "value" }` with no per-entry review flag, so pulled entries are recorded with `status: translated` and **no** `review_status`, meaning "unknown". Earlier releases stamped `review_status: human_reviewed` on every pulled key, asserting a review the CLI had not verified and the response did not describe.
+
 **Key-count limit:** The pull response is capped at **50,000 keys** (`MAX_PULL_KEY_COUNT`). Responses exceeding this limit are rejected with a `ValidationError` before any data is written. If your TMS project exceeds this threshold, partition the export by locale or paginate the pull on the TMS side before invoking `deepl sync pull`.
 
 **Note:** `push` and `pull` require a TMS that implements the REST contract documented above. They are optional -- `deepl sync` works entirely locally with just the DeepL Translation API.
diff --git a/src/cli/commands/sync/register-sync-pull.ts b/src/cli/commands/sync/register-sync-pull.ts
index b877e9b0..cf711db6 100644
--- a/src/cli/commands/sync/register-sync-pull.ts
+++ b/src/cli/commands/sync/register-sync-pull.ts
@@ -14,6 +14,7 @@ interface PullOptions {
   locale?: string;
   syncConfig?: string;
   format?: string;
+  dryRun?: boolean;
 }
 
 export function registerSyncPull(
@@ -30,6 +31,10 @@ export function registerSyncPull(
         .default('text')
     )
     .option('--sync-config <path>', 'Path to .deepl-sync.yaml')
+    .option(
+      '--dry-run',
+      'Preview what the pull would change without writing any file'
+    )
     .addHelpText(
       'after',
       `
@@ -49,10 +54,19 @@ full field list and REST contract.
       options.format = resolveFormat(options, command);
       options.locale = resolveLocale(options, command);
       options.syncConfig = resolveSyncConfig(options, command);
+      // Commander routes --dry-run on the invocation line to the parent `sync`
+      // command (which also defines --dry-run). Fall back to the parent's value.
+      const parentDryRun = command.parent?.opts()['dryRun'] as
+        boolean | undefined;
+      options.dryRun = options.dryRun ?? parentDryRun ?? false;
       return handleSyncPull(options, deps.handleError);
     });
 }
 
+function plural(count: number): string {
+  return count === 1 ? 'translation' : 'translations';
+}
+
 export async function handleSyncPull(
   options: PullOptions,
   handleError: (err: Error) => void
@@ -85,23 +99,36 @@ export async function handleSyncPull(
         await import('../../../sync/tms-server-trust.js');
       const server = tmsServerOrigin(config.tms.server);
 
+      const dryRun = options.dryRun ?? false;
       const registry = await createDefaultRegistry();
       const result = await pullTranslations(config, client, registry, {
         localeFilter,
+        dryRun,
       });
       if (options.format === 'json') {
         process.stdout.write(
           JSON.stringify({
             ok: true,
             pulled: result.pulled,
+            replaced: result.replaced,
             skipped: result.skipped,
             server,
+            dryRun,
           }) + '\n'
         );
       } else {
+        const verb = dryRun ? 'Would pull' : 'Pulled';
+        const suffix = dryRun ? ' (dry-run: no files written)' : '';
         Logger.info(
-          `Pulled ${result.pulled} translations from TMS at ${server}${formatSkippedSummary(result.skipped)}`
+          `${verb} ${result.pulled} translations from TMS at ${server}${formatSkippedSummary(result.skipped)}${suffix}`
         );
+        if (result.replaced > 0) {
+          Logger.info(
+            dryRun
+              ? `Would replace ${result.replaced} existing local ${plural(result.replaced)} with the TMS version.`
+              : `Replaced ${result.replaced} existing local ${plural(result.replaced)} with the TMS version. Use --dry-run to preview a pull before it overwrites local edits.`
+          );
+        }
       }
     } finally {
       processLock.release();
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index dc18cc0b..78150a5a 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -18,10 +18,12 @@ import { LOCK_FILE_NAME } from './types.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency, PUSH_CONCURRENCY } from '../utils/concurrency.js';
 import { partitionEntries, walkBuckets } from './sync-bucket-walker.js';
+import { Logger } from '../utils/logger.js';
 import { sweepStaleBackups, resolveBakSweepAgeMs } from './sync-bak-cleanup.js';
 
 export interface SyncPushPullOptions {
   localeFilter?: string[];
+  dryRun?: boolean;
 }
 
 export type SkipReason = 'target_missing' | 'no_matches' | 'pipe_pluralization';
@@ -40,6 +42,7 @@ export interface PushResult {
 
 export interface PullResult {
   pulled: number;
+  replaced: number;
   skipped: SkippedRecord[];
 }
 
@@ -157,6 +160,7 @@ export async function pullTranslations(
   const lockFile = await lockManager.read();
 
   let pulled = 0;
+  let replaced = 0;
   const skipped: SkippedRecord[] = [];
 
   try {
@@ -246,11 +250,24 @@ export async function pullTranslations(
         existingTargetEntries
       );
 
+      for (const entry of pulledEntries) {
+        const local = existingTargetEntries.get(entry.key);
+        if (local === undefined || local === entry.translation) continue;
+        replaced++;
+        Logger.verbose(
+          `[verbose] ${locale}: the TMS version of "${entry.key}" differs from the local translation in ${targetRelPath}`
+        );
+      }
+
       const reconstructed = isMultiLocale
         ? parser.reconstruct(templateContent, translatedEntries, locale)
         : parser.reconstruct(templateContent, translatedEntries);
-      await fs.promises.mkdir(path.dirname(targetAbsPath), { recursive: true });
-      await atomicWriteFile(targetAbsPath, reconstructed, 'utf-8');
+      if (!options?.dryRun) {
+        await fs.promises.mkdir(path.dirname(targetAbsPath), {
+          recursive: true,
+        });
+        await atomicWriteFile(targetAbsPath, reconstructed, 'utf-8');
+      }
       pulled += pulledEntries.length;
 
       const fileEntryMap = ensureFileEntries(lockFile, relPath);
@@ -263,11 +280,14 @@ export async function pullTranslations(
           source_text: existing?.source_text ?? entry.value,
           translations: {
             ...existingTranslations,
+            // No review_status: the export endpoint returns `{ key: value }`
+            // and carries no per-entry review flag, so the pull has nothing to
+            // base a claim of human review on. Leaving the field unset says
+            // "unknown" rather than asserting a review nobody verified.
             [locale]: {
               hash: sourceHash,
               translated_at: new Date().toISOString(),
               status: 'translated' as const,
-              review_status: 'human_reviewed' as const,
             },
           },
         });
@@ -275,9 +295,9 @@ export async function pullTranslations(
     }
   }
 
-  if (pulled > 0) {
+  if (pulled > 0 && !options?.dryRun) {
     await lockManager.write(lockFile);
   }
 
-  return { pulled, skipped };
+  return { pulled, replaced, skipped };
 }
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index 46d54190..c0e2d8f6 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -17,21 +17,37 @@ export function getParserForBucket(
   return formatRegistry.getParserByFormatKey(formatKey);
 }
 
+/**
+ * Merge a TMS pull response over whatever the target file already holds: the
+ * pulled value wins, an existing target value is kept when the response omits
+ * the key, and a key neither side has is omitted from the result.
+ *
+ * Omitting matters because `reconstruct` writes exactly the entries it is
+ * handed. Handing it `entry.value` for a key with no translation anywhere
+ * would put source-language text in the target file and let the lockfile call
+ * it translated, which no later run revisits — the same reason the locale
+ * translator pushes nothing for a key it could not translate. An empty string
+ * is a translation and is preserved.
+ */
 export function mergePulledTranslations(
   sourceEntries: ExtractedEntry[],
   pulledKeys: Record<string, string>,
   existingTargetEntries: Map<string, string> = new Map()
 ): TranslatedEntry[] {
-  return sourceEntries.map((entry) => ({
-    key: entry.key,
-    value: entry.value,
-    context: entry.context,
-    metadata: entry.metadata,
-    translation:
-      pulledKeys[entry.key] ??
-      existingTargetEntries.get(entry.key) ??
-      entry.value,
-  }));
+  const merged: TranslatedEntry[] = [];
+  for (const entry of sourceEntries) {
+    const translation =
+      pulledKeys[entry.key] ?? existingTargetEntries.get(entry.key);
+    if (translation === undefined) continue;
+    merged.push({
+      key: entry.key,
+      value: entry.value,
+      context: entry.context,
+      metadata: entry.metadata,
+      translation,
+    });
+  }
+  return merged;
 }
 
 /**
diff --git a/tests/e2e/cli-sync-push-pull.e2e.test.ts b/tests/e2e/cli-sync-push-pull.e2e.test.ts
index 2b4f0b3e..98fdb12e 100644
--- a/tests/e2e/cli-sync-push-pull.e2e.test.ts
+++ b/tests/e2e/cli-sync-push-pull.e2e.test.ts
@@ -552,13 +552,85 @@ describe('CLI sync push/pull dispatch E2E', () => {
       const envelope = JSON.parse(run.stdout) as {
         ok: boolean;
         pulled: number;
+        replaced: number;
         skipped: unknown[];
         server: string;
+        dryRun: boolean;
       };
       expect(envelope.ok).toBe(true);
       expect(typeof envelope.pulled).toBe('number');
+      expect(typeof envelope.replaced).toBe('number');
       expect(Array.isArray(envelope.skipped)).toBe(true);
       expect(envelope.server).toBe(baseUrl);
+      expect(envelope.dryRun).toBe(false);
+    });
+
+    it('pull --dry-run: leaves the hand-edited target and the lockfile untouched, exit 0', async () => {
+      await configureMockServer({
+        pullResponses: { de: { greeting: 'Hallo vom TMS' } },
+      });
+
+      writeSyncYaml({ includeTmsBlock: true });
+      writeSource({ greeting: 'Hello' });
+      writeTarget('de', { greeting: 'Von Hand redigiert' });
+      const targetPath = path.join(testFiles.path, 'locales', 'de.json');
+      const before = fs.readFileSync(targetPath, 'utf-8');
+
+      const run = runCli(['sync', 'pull', '--dry-run'], {
+        TMS_API_KEY: 'push-pull-key',
+      });
+
+      expect(run.status).toBe(0);
+      expect(fs.readFileSync(targetPath, 'utf-8')).toBe(before);
+      expect(fs.existsSync(path.join(testFiles.path, '.deepl-sync.lock'))).toBe(
+        false
+      );
+    });
+
+    it('pull: discloses the local translation it replaced', async () => {
+      await configureMockServer({
+        pullResponses: { de: { greeting: 'Hallo vom TMS' } },
+      });
+
+      writeSyncYaml({ includeTmsBlock: true });
+      writeSource({ greeting: 'Hello' });
+      writeTarget('de', { greeting: 'Von Hand redigiert' });
+
+      const run = runCli(['sync', 'pull'], { TMS_API_KEY: 'push-pull-key' });
+
+      expect(run.status).toBe(0);
+      expect(run.stdout + run.stderr).toMatch(
+        /Replaced 1 existing local translation with the TMS version/
+      );
+      const target = JSON.parse(
+        fs.readFileSync(
+          path.join(testFiles.path, 'locales', 'de.json'),
+          'utf-8'
+        )
+      ) as Record<string, string>;
+      expect(target['greeting']).toBe('Hallo vom TMS');
+    });
+
+    it('pull: never writes source text for a key the TMS does not carry', async () => {
+      await configureMockServer({
+        pullResponses: { de: { greeting: 'Hallo vom TMS' } },
+      });
+
+      writeSyncYaml({ includeTmsBlock: true });
+      writeSource({ greeting: 'Hello', brand_new: 'Only in source' });
+      writeTarget('de', { greeting: 'Alt' });
+
+      const run = runCli(['sync', 'pull'], { TMS_API_KEY: 'push-pull-key' });
+
+      expect(run.status).toBe(0);
+      const target = JSON.parse(
+        fs.readFileSync(
+          path.join(testFiles.path, 'locales', 'de.json'),
+          'utf-8'
+        )
+      ) as Record<string, string>;
+      expect(target['greeting']).toBe('Hallo vom TMS');
+      expect(target).not.toHaveProperty('brand_new');
     });
 
     it('push --format json with missing tms block: emits canonical error envelope on stderr, exit 7', () => {
diff --git a/tests/integration/sync-tms.integration.test.ts b/tests/integration/sync-tms.integration.test.ts
index 5355abd2..57cd2161 100644
--- a/tests/integration/sync-tms.integration.test.ts
+++ b/tests/integration/sync-tms.integration.test.ts
@@ -94,7 +94,7 @@ describe('sync push/pull (TMS integration)', () => {
   });
 
   // ---- Case 2: pull happy path ----
-  it('pull: fetches translations, writes target file, updates lockfile with review_status=human_reviewed', async () => {
+  it('pull: fetches translations, writes target file, and does not claim human review', async () => {
     writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
     writeJson(tmpDir, 'locales/en.json', {
       greeting: 'Hello',
@@ -144,9 +144,11 @@ describe('sync push/pull (TMS integration)', () => {
       >;
     };
     const bucketEntries = lockContent.entries['locales/en.json']!;
-    expect(bucketEntries['greeting']!.translations['de']!.review_status).toBe(
-      'human_reviewed'
-    );
+    // The export endpoint returns `{ key: value }` with no per-entry review
+    // flag, so the pull has nothing to base a review claim on.
+    expect(
+      bucketEntries['greeting']!.translations['de']!.review_status
+    ).toBeUndefined();
     expect(bucketEntries['greeting']!.translations['de']!.status).toBe(
       'translated'
     );
@@ -155,6 +157,86 @@ describe('sync push/pull (TMS integration)', () => {
     ).toBe('string');
   });
 
+  // ---- Case 2b: a key with no translation on either side ----
+  it('pull: omits a key the TMS and the target file both lack instead of writing source text', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeJson(tmpDir, 'locales/en.json', {
+      greeting: 'Hello',
+      brand_new: 'Only in source',
+    });
+    writeJson(tmpDir, 'locales/de.json', { greeting: 'ALT' });
+
+    process.env['TMS_API_KEY'] = 'env-key';
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+    expectTmsPull('de', { greeting: 'Hallo' }, { auth: { apiKey: 'env-key' } });
+
+    const result = await pullTranslations(config, client, harness.registry);
+    expect(result.pulled).toBe(1);
+
+    const target = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8')
+    ) as Record<string, string>;
+    expect(target['greeting']).toBe('Hallo');
+    expect(target).not.toHaveProperty('brand_new');
+  });
+
+  // ---- Case 2c: overwriting an existing local translation is disclosed ----
+  it('pull: counts the existing local translations it replaced', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeJson(tmpDir, 'locales/en.json', {
+      greeting: 'Hello',
+      farewell: 'Goodbye',
+      thanks: 'Thanks',
+    });
+    // greeting differs from the TMS value, farewell matches it, thanks is
+    // absent locally — only the first is a replacement.
+    writeJson(tmpDir, 'locales/de.json', {
+      greeting: 'Von Hand redigiert',
+      farewell: 'Tschüss',
+    });
+
+    process.env['TMS_API_KEY'] = 'env-key';
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+    expectTmsPull(
+      'de',
+      { greeting: 'Hallo', farewell: 'Tschüss', thanks: 'Danke' },
+      { auth: { apiKey: 'env-key' } }
+    );
+
+    const result = await pullTranslations(config, client, harness.registry);
+    expect(result.pulled).toBe(3);
+    expect(result.replaced).toBe(1);
+  });
+
+  // ---- Case 2d: dry run ----
+  it('pull --dry-run: reports what it would do and writes neither target nor lockfile', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeJson(tmpDir, 'locales/en.json', { greeting: 'Hello' });
+    writeJson(tmpDir, 'locales/de.json', { greeting: 'Von Hand redigiert' });
+    const targetBefore = fs.readFileSync(
+      path.join(tmpDir, 'locales/de.json'),
+      'utf-8'
+    );
+
+    process.env['TMS_API_KEY'] = 'env-key';
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+    expectTmsPull('de', { greeting: 'Hallo' }, { auth: { apiKey: 'env-key' } });
+
+    const result = await pullTranslations(config, client, harness.registry, {
+      dryRun: true,
+    });
+    expect(result.pulled).toBe(1);
+    expect(result.replaced).toBe(1);
+
+    expect(fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8')).toBe(
+      targetBefore
+    );
+    expect(fs.existsSync(path.join(tmpDir, LOCK_FILE_NAME))).toBe(false);
+  });
+
   // ---- Case 3: TMS_API_KEY env var precedence over config ----
   it('credential resolution: TMS_API_KEY env var overrides config.api_key', async () => {
     writeSyncConfig(tmpDir, { tms: tmsConfig({ api_key: 'from-config' }) });
diff --git a/tests/unit/cli/register-sync.commander-snapshot.test.ts b/tests/unit/cli/register-sync.commander-snapshot.test.ts
index 18601b77..a0b74430 100644
--- a/tests/unit/cli/register-sync.commander-snapshot.test.ts
+++ b/tests/unit/cli/register-sync.commander-snapshot.test.ts
@@ -159,6 +159,18 @@ const RESOLVE_DRY_RUN: OptionSnapshot = {
   mandatory: false,
 };
 
+const PULL_DRY_RUN: OptionSnapshot = {
+  flags: '--dry-run',
+  description: 'Preview what the pull would change without writing any file',
+  defaultValue: undefined,
+  negate: false,
+  choices: undefined,
+  required: false,
+  optional: false,
+  variadic: false,
+  mandatory: false,
+};
+
 const PARENT_SYNC_CONFIG_OPT: OptionSnapshot = {
   flags: '--sync-config <path>',
   description: 'Path to .deepl-sync.yaml (default: auto-detect)',
@@ -550,9 +562,12 @@ const EXPECTED: CommandSnapshot = {
     {
       name: 'pull',
       description: 'Pull approved translations from a TMS',
-      options: [FORMAT_OPT, LOCALE_FILTER_OPT, SYNC_CONFIG_OPT].sort((a, b) =>
-        a.flags.localeCompare(b.flags)
-      ),
+      options: [
+        FORMAT_OPT,
+        LOCALE_FILTER_OPT,
+        PULL_DRY_RUN,
+        SYNC_CONFIG_OPT,
+      ].sort((a, b) => a.flags.localeCompare(b.flags)),
       subcommands: [],
     },
     {
diff --git a/tests/unit/sync/sync-utils.test.ts b/tests/unit/sync/sync-utils.test.ts
index de004f41..876e3dbe 100644
--- a/tests/unit/sync/sync-utils.test.ts
+++ b/tests/unit/sync/sync-utils.test.ts
@@ -373,7 +373,7 @@ describe('mergePulledTranslations()', () => {
     ]);
   });
 
-  it('should fall back to source text when no existing target translation is available', () => {
+  it('should omit a key the pull response and the target file both lack', () => {
     const merged = mergePulledTranslations(
       [
         { key: 'greeting', value: 'Hello' },
@@ -390,13 +390,36 @@ describe('mergePulledTranslations()', () => {
         context: undefined,
         metadata: undefined,
       },
+    ]);
+  });
+
+  it('should keep an empty target translation rather than treating it as absent', () => {
+    const merged = mergePulledTranslations(
+      [{ key: 'optional_suffix', value: 'Ltd.' }],
+      {},
+      new Map([['optional_suffix', '']])
+    );
+
+    expect(merged).toEqual([
       {
-        key: 'farewell',
-        value: 'Goodbye',
-        translation: 'Goodbye',
+        key: 'optional_suffix',
+        value: 'Ltd.',
+        translation: '',
         context: undefined,
         metadata: undefined,
       },
     ]);
   });
+
+  it('should omit every key when the pull response is empty and no target exists', () => {
+    expect(
+      mergePulledTranslations(
+        [
+          { key: 'greeting', value: 'Hello' },
+          { key: 'farewell', value: 'Goodbye' },
+        ],
+        {}
+      )
+    ).toEqual([]);
+  });
 });

From 8923560c09cfff664c30b6a54a7130fd713ee316 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 10:13:02 +0200
Subject: [PATCH 152/256] fix(sync): reject the tms fields that were documented
 but never wired up
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

tms.auto_push, tms.auto_pull and tms.require_review were on KNOWN_TMS_KEYS and
in the tms table in docs/SYNC.md, and nothing read any of them. That allowlist
membership was the only reason they were tolerated, since every other unknown
tms: field throws. Measured: a .deepl-sync.yaml with `require_review: [de]`
passed `deepl sync validate` at exit 0, and `deepl sync pull` then replaced a
hand-edited German string with the mock TMS's "Unreviewed TMS draft" at exit 0.
The near-miss hint pointed at the inert key too: `auto_pushh` was answered with
`Did you mean "auto_push"?`.

require_review cannot be implemented from this side — the documented export
contract is a flat { key: value } map with no per-entry review flag, so there
is nothing to gate on, and inventing a response shape would be unverifiable
against a real server. auto_push/auto_pull are one explicit `deepl sync push` /
`deepl sync pull` away, which keeps the credential-and-destination decision on
a command someone typed rather than making a plain `deepl sync` in an untrusted
checkout ship every string to the tms.server that checkout names.

All three are rejected by name rather than as unknown fields: "unknown" reads
as a typo and sends the reader looking for the right spelling of something that
never existed. SyncTmsConfig drops them as well, so a TypeScript consumer
setting one stops compiling instead of being ignored at runtime.

Refs cli-8kr2.37
---
 CHANGELOG.md                                  |  2 +
 docs/SYNC.md                                  |  5 +-
 src/sync/sync-config.ts                       | 34 ++++++---
 src/sync/types.ts                             |  3 -
 tests/e2e/cli-sync-push-pull.e2e.test.ts      | 32 +++++++++
 .../integration/sync-tms.integration.test.ts  | 19 +++++
 tests/unit/sync/sync-config.test.ts           | 69 ++++++++++++++++++-
 7 files changed, 147 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ee230c5..34eb50db 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -109,6 +109,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+- **sync**: **BREAKING**: `tms.auto_push`, `tms.auto_pull` and `tms.require_review` are gone from the config schema. All three were on the `tms:` allowlist and in the `tms` table in docs/SYNC.md, and **no code read any of them** — the allowlist membership was the entire reason they were tolerated, since every other unknown `tms:` field throws. Measured: a `.deepl-sync.yaml` with `require_review: [de]` passed `deepl sync validate` at exit 0 and then `deepl sync pull` replaced a hand-edited German string with the mock TMS's `"Unreviewed TMS draft"` at exit 0 — a documented safety control that did nothing and said nothing. The near-miss hint made it worse: a typo'd `auto_pushh` was answered with `Did you mean "auto_push"?`, steering the reader onto the inert key. Each now fails config load with a `ConfigError` (exit 7) that says so by name — `tms.require_review was never implemented and has been removed` — rather than as a generic unknown field, because "unknown" reads as a typo and sends the reader hunting for the right spelling of something that never existed. `require_review` is not implementable from this side: the documented export contract is a flat `{ key: value }` map with no per-entry review flag, so there is nothing to gate on; use `deepl sync pull --dry-run` to preview and review a pull instead. `auto_push`/`auto_pull` are one explicit `deepl sync push` / `deepl sync pull` away, which also keeps the credential-and-destination decision on a command someone typed — implementing `auto_push` would have made a plain `deepl sync` in a checkout you do not control ship every translated string to the `tms.server` that checkout names. `SyncTmsConfig` drops the three fields too, so a TypeScript consumer setting them stops compiling rather than being ignored at runtime.
+
 - **cli**: **BREAKING**: The `--enable-beta-languages` flag on `translate` is gone. The API deprecated the underlying `enable_beta_languages` parameter with "has no effect" — beta languages are simply part of the regular language set now — so the flag had become a silent no-op. Scripts passing it will exit with an unknown-option error; remove the flag.
 
 - **usage**: The dedicated "Speech-to-Text Usage" section (text output) and "Speech-to-text" row (table output) are gone, along with the `speechToTextMilliseconds*` fields they read. The API deprecated `speech_to_text_milliseconds_count`/`_limit` on `GET /v2/usage` ("Always returns 0"), so the section could only ever display zero. Voice usage remains visible in the Product Breakdown, which reads the live per-product minutes data. The Admin API's per-key `speech_to_text_milliseconds` usage limit is a different, still-current field and is unaffected.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 5ba74117..fc74de7c 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -308,12 +308,11 @@ Optional integration with a translation management system (TMS) for collaborativ
 | `project_id` | `string` | Yes | -- | TMS project identifier |
 | `api_key` | `string` | No | -- | API key for TMS authentication (prefer `TMS_API_KEY` env var) |
 | `token` | `string` | No | -- | Bearer token for TMS authentication (prefer `TMS_TOKEN` env var) |
-| `auto_push` | `boolean` | No | `false` | Automatically push after sync |
-| `auto_pull` | `boolean` | No | `false` | Automatically pull before sync |
-| `require_review` | `string[]` | No | -- | Locales that require human review before pull |
 | `timeout_ms` | `number` | No | `30000` | Per-request timeout in milliseconds for TMS HTTP calls (positive integer). Aborts the request via `AbortController` when exceeded. |
 | `push_concurrency` | `number` | No | `10` | Maximum number of in-flight `PUT /keys/{keyPath}` requests during `deepl sync push`. Positive integer. Applied per (file, locale) batch of entries; aborts remaining pushes on first failure. |
 
+**Removed fields.** `auto_push`, `auto_pull` and `require_review` were accepted by the schema and listed in this table, and no code ever read any of them -- a `require_review` a user configured expecting a human gate before pull got no gate and no warning. All three now fail config load with a `ConfigError` (exit 7) naming them, rather than being silently tolerated. Push and pull after or before a sync by running `deepl sync push` / `deepl sync pull` explicitly, which also keeps the credential and destination decision on a command you typed. A review gate cannot be enforced from the CLI side because the export contract below carries no per-entry review flag; use [`deepl sync pull --dry-run`](#deepl-sync-pull) to preview a pull and review the result before committing it.
+
 ##### TMS destination trust
 
 `server` is chosen by this file, which lives in the checkout, while `TMS_API_KEY` / `TMS_TOKEN` come from the operator's environment. A checkout you do not control could therefore name the host that receives your credential and every translated string. Before an **environment-supplied** credential is attached to a request, the destination hostname must be approved in the operator's own configuration:
diff --git a/src/sync/sync-config.ts b/src/sync/sync-config.ts
index c8279429..4e3f566c 100644
--- a/src/sync/sync-config.ts
+++ b/src/sync/sync-config.ts
@@ -168,13 +168,27 @@ const KNOWN_TMS_KEYS: readonly string[] = [
   'project_id',
   'api_key',
   'token',
-  'auto_push',
-  'auto_pull',
-  'require_review',
   'timeout_ms',
   'push_concurrency',
 ];
 
+/**
+ * `tms:` fields the schema once accepted, and documented, without any code
+ * reading them. Membership in `KNOWN_TMS_KEYS` was the whole reason they were
+ * tolerated, so a review gate a user configured did nothing and said nothing.
+ * They are rejected by name rather than as unknown fields, because "unknown"
+ * reads as a typo and sends the reader looking for the correct spelling of
+ * something that never existed.
+ */
+const RETIRED_TMS_KEYS: Readonly<Record<string, string>> = {
+  auto_push:
+    'Run "deepl sync push" after "deepl sync" instead, which also keeps the credential and destination decision on an explicit command.',
+  auto_pull:
+    'Run "deepl sync pull" before "deepl sync" instead, which also keeps the credential and destination decision on an explicit command.',
+  require_review:
+    'The TMS export contract carries no per-entry review flag, so this gate cannot be enforced. Preview a pull with "deepl sync pull --dry-run" and review the result before committing it.',
+};
+
 function levenshtein(a: string, b: string): number {
   if (a === b) return 0;
   if (a.length === 0) return b.length;
@@ -583,11 +597,15 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
     }
   }
   if (obj['tms'] !== undefined) {
-    assertOnlyKnownKeys(
-      obj['tms'] as Record<string, unknown>,
-      KNOWN_TMS_KEYS,
-      'tms'
-    );
+    const tmsBlock = obj['tms'] as Record<string, unknown>;
+    for (const [key, alternative] of Object.entries(RETIRED_TMS_KEYS)) {
+      if (tmsBlock[key] === undefined) continue;
+      throw new ConfigError(
+        `tms.${key} was never implemented and has been removed`,
+        alternative
+      );
+    }
+    assertOnlyKnownKeys(tmsBlock, KNOWN_TMS_KEYS, 'tms');
   }
   if (
     obj['context'] !== undefined &&
diff --git a/src/sync/types.ts b/src/sync/types.ts
index f78e2ca3..90f0d0cd 100644
--- a/src/sync/types.ts
+++ b/src/sync/types.ts
@@ -101,9 +101,6 @@ export interface SyncTmsConfig {
   project_id: string;
   api_key?: string;
   token?: string;
-  auto_push?: boolean;
-  auto_pull?: boolean;
-  require_review?: string[];
   timeout_ms?: number;
   push_concurrency?: number;
 }
diff --git a/tests/e2e/cli-sync-push-pull.e2e.test.ts b/tests/e2e/cli-sync-push-pull.e2e.test.ts
index 98fdb12e..53e53c67 100644
--- a/tests/e2e/cli-sync-push-pull.e2e.test.ts
+++ b/tests/e2e/cli-sync-push-pull.e2e.test.ts
@@ -633,6 +633,38 @@ describe('CLI sync push/pull dispatch E2E', () => {
       expect(target).not.toHaveProperty('brand_new');
     });
 
+    it.each(['auto_push', 'auto_pull', 'require_review'])(
+      'tms.%s in the YAML fails the run with exit 7 instead of being ignored',
+      (field) => {
+        const yaml = buildSyncConfigYaml({
+          targetLocales: ['de'],
+          buckets: { json: { include: ['locales/en.json'] } },
+          tms: {
+            enabled: true,
+            server: baseUrl,
+            project_id: PROJECT_ID,
+            [field]: field === 'require_review' ? ['de'] : true,
+          },
+        });
+        fs.writeFileSync(
+          path.join(testFiles.path, '.deepl-sync.yaml'),
+          yaml,
+          'utf-8'
+        );
+        writeSource({ greeting: 'Hello' });
+
+        const run = runCli(['sync', 'pull', '--format', 'json'], {
+          TMS_API_KEY: 'push-pull-key',
+        });
+
+        expect(run.status).toBe(7);
+        const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+        expect(envelope.error.message).toBe(
+          `tms.${field} was never implemented and has been removed`
+        );
+      }
+    );
+
     it('push --format json with missing tms block: emits canonical error envelope on stderr, exit 7', () => {
       writeSyncYaml({ includeTmsBlock: false });
       writeSource();
diff --git a/tests/integration/sync-tms.integration.test.ts b/tests/integration/sync-tms.integration.test.ts
index 57cd2161..9ea5aadf 100644
--- a/tests/integration/sync-tms.integration.test.ts
+++ b/tests/integration/sync-tms.integration.test.ts
@@ -237,6 +237,25 @@ describe('sync push/pull (TMS integration)', () => {
     expect(fs.existsSync(path.join(tmpDir, LOCK_FILE_NAME))).toBe(false);
   });
 
+  // ---- Case 2e: retired tms fields fail config load ----
+  it.each(['auto_push', 'auto_pull', 'require_review'])(
+    'loadSyncConfig rejects tms.%s written in real YAML',
+    async (field) => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['de'],
+        tms: tmsConfig({
+          [field]: field === 'require_review' ? ['de'] : true,
+        }),
+      });
+      writeJson(tmpDir, 'locales/en.json', { greeting: 'Hello' });
+
+      await expect(loadSyncConfig(tmpDir)).rejects.toThrow(ConfigError);
+      await expect(loadSyncConfig(tmpDir)).rejects.toThrow(
+        `tms.${field} was never implemented and has been removed`
+      );
+    }
+  );
+
   // ---- Case 3: TMS_API_KEY env var precedence over config ----
   it('credential resolution: TMS_API_KEY env var overrides config.api_key', async () => {
     writeSyncConfig(tmpDir, { tms: tmsConfig({ api_key: 'from-config' }) });
diff --git a/tests/unit/sync/sync-config.test.ts b/tests/unit/sync/sync-config.test.ts
index 1aa8762a..edb4d388 100644
--- a/tests/unit/sync/sync-config.test.ts
+++ b/tests/unit/sync/sync-config.test.ts
@@ -1268,14 +1268,77 @@ describe('sync-config', () => {
             project_id: 'test',
             api_key: 'secret',
             token: 'bearer',
-            auto_push: false,
-            auto_pull: false,
-            require_review: ['de'],
             timeout_ms: 30000,
           },
         };
         expect(() => validateSyncConfig(raw)).not.toThrow();
       });
+
+      describe.each(['auto_push', 'auto_pull', 'require_review'])(
+        'tms.%s',
+        (field) => {
+          function configWith(value: unknown): unknown {
+            return {
+              version: 1,
+              source_locale: 'en',
+              target_locales: ['de'],
+              buckets: { json: { include: ['locales/en.json'] } },
+              tms: {
+                enabled: true,
+                server: 'https://example.com',
+                project_id: 'test',
+                [field]: value,
+              },
+            };
+          }
+
+          it('is rejected rather than accepted and ignored', () => {
+            const raw = configWith(field === 'require_review' ? ['de'] : true);
+            expect(() => validateSyncConfig(raw)).toThrow(ConfigError);
+          });
+
+          it('says it was never implemented instead of calling it a typo', () => {
+            const raw = configWith(field === 'require_review' ? ['de'] : true);
+            let message = '';
+            let suggestion = '';
+            try {
+              validateSyncConfig(raw);
+            } catch (err) {
+              message = (err as ConfigError).message;
+              suggestion = (err as ConfigError).suggestion ?? '';
+            }
+            expect(message).toContain(`tms.${field}`);
+            expect(message).toMatch(/never implemented/i);
+            expect(suggestion).toMatch(/deepl sync (push|pull)/);
+            // The levenshtein hint must not offer it back as a near miss.
+            expect(suggestion).not.toMatch(/Did you mean/);
+          });
+        }
+      );
+
+      it('no longer suggests a removed key for a near-miss typo', () => {
+        const raw = {
+          version: 1,
+          source_locale: 'en',
+          target_locales: ['de'],
+          buckets: { json: { include: ['locales/en.json'] } },
+          tms: {
+            enabled: true,
+            server: 'https://example.com',
+            project_id: 'test',
+            auto_pushh: true,
+          },
+        };
+        let suggestion = '';
+        expect.assertions(2);
+        try {
+          validateSyncConfig(raw);
+        } catch (err) {
+          expect(err).toBeInstanceOf(ConfigError);
+          suggestion = (err as ConfigError).suggestion ?? '';
+        }
+        expect(suggestion).not.toMatch(/Did you mean/);
+      });
     });
 
     describe('ConfigError suggestion contract', () => {

From b214faa632f2364c2d2b7ceebf2a75ba02422b83 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 10:24:39 +0200
Subject: [PATCH 153/256] fix(api): refuse a document ID that would redirect
 the client's own requests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The document_id from POST /v2/document went into POST /v2/document/{id} and
POST /v2/document/{id}/result unencoded and unchecked, and the endpoint that
supplies it is redirectable by --api-url, api.baseUrl or a proxy. Measured
against a stub answering document_id: '../../v3/glossaries%3fpwned=1', the next
two request lines arrived as POST /v3/glossaries%3fpwned=1 and
POST /v3/glossaries%3fpwned=1/result, and the run finished at exit 0 reporting
"Translated report.pdf -> out.pdf" after writing the stub's JSON body into the
output file.

Checked against [A-Za-z0-9_-]+ at both interpolation sites rather than once on
the upload response, so a handle assembled anywhere else is covered too. The
alphabet is wider than DeepL's uppercase hex to leave room for a format change,
and narrow enough to exclude anything that can restructure a path. A response
with no document_id at all was reaching the wire as the literal path
/v2/document/undefined; the same check refuses it.

NetworkError rather than ValidationError, because nothing the user typed is
wrong — which is why this reads differently from
GlossaryClient.validateGlossaryId, guarding an ID the user supplied.

This was the last unguarded interpolation of an untrusted value into a URL path
in the API layer: GlossaryClient validates at all 7 of its sites and
StyleRulesClient encodes at all 8. The polling loop re-sends the original
handle rather than the document_id each status response echoes, so a clean
first response cannot be followed by a poisoned second one.

Refs cli-8kr2.38
---
 CHANGELOG.md                                  |   2 +
 docs/API.md                                   |   2 +
 src/api/document-client.ts                    |  33 ++++-
 tests/e2e/cli-document-hostile-id.e2e.test.ts | 131 ++++++++++++++++++
 tests/e2e/hostile-document-server.cjs         |  80 +++++++++++
 ...i-document-translation.integration.test.ts |  33 +++++
 tests/unit/document-client.test.ts            |  74 ++++++++++
 7 files changed, 354 insertions(+), 1 deletion(-)
 create mode 100644 tests/e2e/cli-document-hostile-id.e2e.test.ts
 create mode 100644 tests/e2e/hostile-document-server.cjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 34eb50db..457a64ef 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -418,6 +418,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **translate**: **a document upload response can no longer choose where this client sends its own follow-up requests.** The `document_id` from `POST /v2/document` was interpolated into `POST /v2/document/{id}` and `POST /v2/document/{id}/result` with no encoding and no format check, and the endpoint supplying it is redirectable via `--api-url`, `api.baseUrl` or a proxy. Measured against a stub answering `document_id: '../../v3/glossaries%3fpwned=1'`, the client's next two request lines arrived as `POST /v3/glossaries%3fpwned=1` and `POST /v3/glossaries%3fpwned=1/result` — the traversal collapsed exactly as crafted, on a completely different route from `/v2/document/{id}` — and the run finished at **exit 0** reporting `Translated report.pdf -> out.pdf` after writing the stub's JSON body into the output file as if it were a translated PDF. `document_id` is now checked against `[A-Za-z0-9_-]+` at both interpolation sites, so a redirected first response stops the workflow at exit 5 (`NetworkError`, since nothing the user typed is wrong) with the ID quoted back, nothing further sent, and no output file written. A response with no `document_id` at all was reaching the wire as the literal path `/v2/document/undefined`; that is refused by the same check. This was the last unguarded interpolation of an untrusted value into a URL path in the API layer — `GlossaryClient` validates its ID at all 7 sites and `StyleRulesClient` encodes at all 8, and the document client was the one exception among the ten clients. The polling loop was also checked: it re-sends the original handle rather than the `document_id` echoed by each status response, so a clean first response cannot be followed by a poisoned second one.
+
 - **sync**: **`sync pull` no longer records `review_status: human_reviewed` for content it never verified was reviewed.** Every key a pull applied was stamped `human_reviewed` in `.deepl-sync.lock`, unconditionally. The documented export contract is `GET /keys/export` returning `{ "key": "translated value", … }` — a flat map with no per-entry review flag — so there was nothing in the response to base that claim on, and a TMS that exports machine-translation drafts had them recorded in a committed file as human-reviewed. Where the `tms.server` in a checkout is not one the operator chose, the endpoint controls the strings *and* the review label attached to them. Measured: a mock export returning `{"greeting":"Hallo vom TMS"}` produced `"de": {"hash":"185f8db32271","review_status":"human_reviewed","status":"translated","translated_at":"…"}`. Pulled entries now record `status: translated` with **no** `review_status`, which is the type's way of saying "unknown"; `human_reviewed` is still honoured when a person or another tool writes it, and `--flag-for-review` still writes `machine_translated`, so nothing else in the lockfile changes. Nothing in the CLI reads `review_status` today, which is exactly why a false value could sit there unnoticed until something did — including the `tms.require_review` gate the config schema advertised.
 
 - **sync**: **`--force` is refused when there is no terminal to confirm it on, instead of treating "nobody can answer" as yes.** The guard threw for `CI=true` and prompted on a TTY, and had no third branch — so in a git hook, cron job, `make` target, container entrypoint, Jenkins agent, or plain `deepl sync --force < /dev/null`, the prompt was skipped and the run **proceeded**. This inverted the convention `confirm()` exists to enforce: it returns `false` for a non-TTY, deliberately fail-closed, and the seven other destructive sites (`cache clear`, `admin`, `config`, two in `glossary`, two in `style-rules`) all inherit that auto-NO. This one site turned it into auto-YES, for the single most destructive operation the CLI has. Measured on a fully synced project whose `locales/de.json` had been hand-edited to stand in for human review: `env -u CI deepl sync --force < /dev/null` printed no prompt and no warning, reported `✓ de: 3/3 keys`, `Sync complete: 3 new`, **exit 0**, and replaced all three reviewed strings with machine output — with no `.deepl.bak` surviving, so the edits were unrecoverable. **`--no-input` was ignored on the same path**, though it documents itself as "abort instead of prompting": `deepl --no-input sync --force` destroyed the same edits at exit 0. Both now exit 6 with a message naming `--yes` as the only way to run `--force` unattended, and `--yes` still works everywhere it did. Refusing rather than aborting quietly, matching the existing `CI=true` branch and the TMS destination-trust gate: unlike `cache clear`, declining here abandons the whole sync, so exit 0 would report an up-to-date project for a run that did nothing. An interactive decline is unchanged at exit 0, and now prints `Aborted.` like its seven siblings. Verified on a real terminal through a pty: the prompt appears, `n` aborts with the edits intact, `y` proceeds. The gate is a single `canPrompt()` in `utils/confirm.ts`, which `confirm()` itself now uses, so the two cannot drift apart.
diff --git a/docs/API.md b/docs/API.md
index b9eb6fef..63f858ea 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3370,6 +3370,8 @@ Connection-layer failure or transient server outage. Covers TCP errors (`ECONNRE
 
 A response that came back without the placeholder tokens the CLI substituted for your variables counts as malformed here too: `translate` names the variables it lost (`{username}`, `%s`) and writes nothing rather than leaving its own internal tokens in your text. A directory run fails only the affected files and reports each one in the summary, so its exit code follows the usual batch mapping (`1` when nothing translated, `12` when some did).
 
+A document upload response whose `document_id` is not a document identifier is rejected here as well. That value is interpolated into the path of every follow-up request (`POST /v2/document/{id}`, `POST /v2/document/{id}/result`), so an ID containing `..` or `/` would send this client's own requests to a different route on the endpoint. Anything outside `[A-Za-z0-9_-]+` is refused before the next request is sent, the ID is quoted back in the message, and no output file is written.
+
 Remediation: check connectivity and `HTTPS_PROXY` / `HTTP_PROXY` env vars, then retry.
 
 #### 6 — InvalidInput
diff --git a/src/api/document-client.ts b/src/api/document-client.ts
index 540d72d5..e0a0b921 100644
--- a/src/api/document-client.ts
+++ b/src/api/document-client.ts
@@ -8,7 +8,7 @@ import {
   DocumentHandle,
   DocumentStatus,
 } from '../types/index.js';
-import { ValidationError } from '../utils/errors.js';
+import { NetworkError, ValidationError } from '../utils/errors.js';
 import { normalizeFormality } from '../utils/formality.js';
 import {
   resolveGlossaryWireParams,
@@ -32,6 +32,35 @@ interface DeepLDocumentStatusResponse {
  *  than the interactive request timeout. */
 const TRANSFER_TIMEOUT_MS = 300_000;
 
+/**
+ * A document ID is opaque to this client and goes straight into a URL path, so
+ * only characters that cannot change the path's structure are allowed. DeepL
+ * returns uppercase hex; the wider alphabet leaves room for a format change
+ * without leaving room for `..`, `/`, `%`, `?` or `#`.
+ */
+const DOCUMENT_ID_RE = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * The document ID reaching `/v2/document/{id}` comes from the upload response,
+ * which is untrusted: `--api-url`, `api.baseUrl` or a proxy can redirect the
+ * endpoint, and a redirected host that answers with
+ * `document_id: '../../v3/glossaries'` steers the client's own follow-up
+ * requests onto a different route. Checked at each interpolation site rather
+ * than once on the upload response, so a handle assembled anywhere else is
+ * covered too.
+ *
+ * `NetworkError` rather than `ValidationError`: nothing the user typed is
+ * wrong. That is also why this reads differently from
+ * `GlossaryClient.validateGlossaryId`, which guards an ID the user supplied.
+ */
+function assertUsableDocumentId(documentId: string): void {
+  if (typeof documentId === 'string' && DOCUMENT_ID_RE.test(documentId)) return;
+  throw new NetworkError(
+    `Unexpected API response: document_id must be a document identifier, got ${JSON.stringify(documentId)}. The endpoint that returned it can redirect this client's own requests.`,
+    'Check the endpoint in use (--api-url, api.baseUrl, or a proxy). No further document request was sent.'
+  );
+}
+
 export class DocumentClient extends HttpClient {
   constructor(apiKey: string, options: DeepLClientOptions = {}) {
     super(apiKey, options);
@@ -119,6 +148,7 @@ export class DocumentClient extends HttpClient {
   }
 
   async getDocumentStatus(handle: DocumentHandle): Promise<DocumentStatus> {
+    assertUsableDocumentId(handle.documentId);
     try {
       const response = await this.makeRequest<DeepLDocumentStatusResponse>(
         'POST',
@@ -144,6 +174,7 @@ export class DocumentClient extends HttpClient {
    * permanently, so this request is never retried.
    */
   async downloadDocument(handle: DocumentHandle): Promise<Buffer> {
+    assertUsableDocumentId(handle.documentId);
     try {
       const response = await this.makeRawRequest<Buffer>(
         'POST',
diff --git a/tests/e2e/cli-document-hostile-id.e2e.test.ts b/tests/e2e/cli-document-hostile-id.e2e.test.ts
new file mode 100644
index 00000000..9bd5db31
--- /dev/null
+++ b/tests/e2e/cli-document-hostile-id.e2e.test.ts
@@ -0,0 +1,131 @@
+/**
+ * E2E test for a hostile `document_id` in a document upload response.
+ *
+ * The upload response chooses the path of every follow-up request the client
+ * makes, so a redirected endpoint that answers with `../../v3/glossaries`
+ * steers those requests onto a different route. The unit tests assert against
+ * a mocked axios instance; this one asserts against a real socket, so what is
+ * proven here is that the redirected request line never reaches the wire.
+ *
+ * Uses a dedicated mock (tests/e2e/hostile-document-server.cjs) run as a child
+ * process so the CLI subprocess can reach it over TCP.
+ */
+
+import { spawn, ChildProcess, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import nock from 'nock';
+
+import { createTestConfigDir, createTestDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const MOCK_SERVER_SCRIPT = path.join(__dirname, 'hostile-document-server.cjs');
+
+describe('CLI document translation against a hostile document_id E2E', () => {
+  const testConfig = createTestConfigDir('e2e-hostile-doc');
+  const testFiles = createTestDir('e2e-hostile-doc-files');
+  let mockServerProcess: ChildProcess;
+  let baseUrl: string;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const child = spawn('node', [MOCK_SERVER_SCRIPT], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+      mockServerProcess = child;
+      let output = '';
+
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = output.match(/PORT=(\d+)/);
+        if (match) resolve(parseInt(match[1]!, 10));
+      });
+      child.stderr.on('data', (data: Buffer) => {
+        const msg = data.toString();
+        if (
+          !msg.includes('ExperimentalWarning') &&
+          !msg.includes('--experimental')
+        ) {
+          process.stderr.write(`[hostile-doc stderr] ${msg}`);
+        }
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  async function recordedRequests(): Promise<
+    { method: string; url: string }[]
+  > {
+    const res = await fetch(`${baseUrl}/__requests`);
+    return (await res.json()) as { method: string; url: string }[];
+  }
+
+  beforeAll(async () => {
+    nock.enableNetConnect('127.0.0.1');
+    const port = await startMockServer();
+    baseUrl = `http://127.0.0.1:${port}`;
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+      })
+    );
+  }, 30000);
+
+  beforeEach(() => {
+    nock.enableNetConnect('127.0.0.1');
+  });
+
+  afterAll(() => {
+    if (mockServerProcess) mockServerProcess.kill('SIGTERM');
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  it('refuses the traversal, sends no follow-up request, and writes no output file', async () => {
+    const input = path.join(testFiles.path, 'report.pdf');
+    const output = path.join(testFiles.path, 'report.de.pdf');
+    fs.writeFileSync(input, Buffer.from('%PDF-1.4 test content'));
+
+    const run = spawnSync(
+      'node',
+      [
+        CLI_PATH,
+        'translate',
+        input,
+        '--to',
+        'de',
+        '--output',
+        output,
+        '--api-url',
+        baseUrl,
+      ],
+      {
+        encoding: 'utf-8',
+        cwd: testFiles.path,
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: testConfig.path,
+          NO_COLOR: '1',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 20000,
+      }
+    );
+
+    // NetworkError: the endpoint is at fault, not anything the user typed.
+    expect(run.status).toBe(5);
+    expect(run.stderr).toContain('Unexpected API response: document_id');
+    expect(fs.existsSync(output)).toBe(false);
+
+    const requests = await recordedRequests();
+    expect(requests).toEqual([{ method: 'POST', url: '/v2/document' }]);
+  }, 30000);
+});
diff --git a/tests/e2e/hostile-document-server.cjs b/tests/e2e/hostile-document-server.cjs
new file mode 100644
index 00000000..1b408749
--- /dev/null
+++ b/tests/e2e/hostile-document-server.cjs
@@ -0,0 +1,80 @@
+/**
+ * Mock DeepL endpoint whose document upload answers with a hostile
+ * `document_id`, used by tests/e2e/cli-document-hostile-id.e2e.test.ts.
+ *
+ * Purpose-specific rather than a mode on mock-deepl-server.cjs: ~20 suites
+ * share that fixture, and this one has to answer every path so a redirected
+ * follow-up request would succeed if one were ever issued. It records every
+ * request line, which is the whole point — the assertion is about the path the
+ * client asks for, not the response it gets.
+ *
+ * Usage: node tests/e2e/hostile-document-server.cjs
+ * Prints "PORT=<number>" to stdout on startup.
+ *
+ *   GET  /__requests   dump the recorded { method, url } list
+ */
+
+/* eslint-disable @typescript-eslint/no-var-requires */
+const http = require('http');
+
+const HOSTILE_DOCUMENT_ID = '../../v3/glossaries%3fpwned=1';
+
+var requests = [];
+
+const server = http.createServer(function (req, res) {
+  let body = '';
+  req.on('data', function (chunk) {
+    body += chunk.toString('binary');
+  });
+  req.on('end', function () {
+    const url = req.url || '';
+    const method = req.method || '';
+
+    if (method === 'GET' && url === '/__requests') {
+      res.setHeader('Content-Type', 'application/json');
+      res.writeHead(200);
+      res.end(JSON.stringify(requests));
+      return;
+    }
+
+    requests.push({ method: method, url: url });
+
+    res.setHeader('Content-Type', 'application/json');
+    res.setHeader('Connection', 'close');
+    res.writeHead(200);
+    if (method === 'POST' && url === '/v2/document') {
+      res.end(
+        JSON.stringify({
+          document_id: HOSTILE_DOCUMENT_ID,
+          document_key: 'hostile-key',
+        })
+      );
+      return;
+    }
+    // Every other path reports a finished document, so the upload -> poll ->
+    // download sequence runs to completion when nothing stops it.
+    res.end(
+      JSON.stringify({ document_id: HOSTILE_DOCUMENT_ID, status: 'done' })
+    );
+  });
+});
+
+server.keepAliveTimeout = 0;
+
+server.listen(0, '127.0.0.1', function () {
+  const addr = server.address();
+  if (addr && typeof addr === 'object') {
+    process.stdout.write('PORT=' + addr.port + '\n');
+  }
+});
+
+process.on('SIGTERM', function () {
+  server.close(function () {
+    process.exit(0);
+  });
+});
+process.on('SIGINT', function () {
+  server.close(function () {
+    process.exit(0);
+  });
+});
diff --git a/tests/integration/cli-document-translation.integration.test.ts b/tests/integration/cli-document-translation.integration.test.ts
index fd63f8c8..81239e34 100644
--- a/tests/integration/cli-document-translation.integration.test.ts
+++ b/tests/integration/cli-document-translation.integration.test.ts
@@ -874,6 +874,39 @@ describe('Document Translation Integration', () => {
     });
   });
 
+  describe('Service-level: a hostile document_id in the upload response', () => {
+    it('aborts the workflow, issues no follow-up request, and writes no output', async () => {
+      const client = new DeepLClient(API_KEY, { maxRetries: 0 });
+      clients.push(client);
+      const service = new DocumentTranslationService(client);
+
+      const inputPath = path.join(testDir, 'input-traversal.pdf');
+      const outputPath = path.join(testDir, 'output-traversal.pdf');
+      fs.writeFileSync(inputPath, Buffer.from('%PDF-1.4 test content'));
+
+      const uploadScope = nock(FREE_API_URL).post('/v2/document').reply(200, {
+        document_id: '../../v3/glossaries%3fpwned=1',
+        document_key: 'kt1',
+      });
+
+      // The route the traversal collapses onto. Left unmatched deliberately:
+      // nock rejects an unmatched request, so this interceptor existing and
+      // staying pending is what proves the request was never issued.
+      const traversedScope = nock(FREE_API_URL)
+        .post('/v3/glossaries%3fpwned=1')
+        .reply(200, { document_id: 'x', status: 'done' });
+
+      await expect(
+        service.translateDocument(inputPath, outputPath, { targetLang: 'de' })
+      ).rejects.toThrow(/Unexpected API response: document_id/);
+
+      expect(uploadScope.isDone()).toBe(true);
+      expect(traversedScope.isDone()).toBe(false);
+      expect(fs.existsSync(outputPath)).toBe(false);
+      nock.cleanAll();
+    });
+  });
+
   describe('Service-level: abort signal support', () => {
     it('should cancel translation when abort signal fires', async () => {
       const client = new DeepLClient(API_KEY, { maxRetries: 0 });
diff --git a/tests/unit/document-client.test.ts b/tests/unit/document-client.test.ts
index 891ad0cc..65548b97 100644
--- a/tests/unit/document-client.test.ts
+++ b/tests/unit/document-client.test.ts
@@ -223,6 +223,80 @@ describe('DocumentClient', () => {
     });
   });
 
+  describe('server-supplied document ID reaching the URL path', () => {
+    const REJECTED: ReadonlyArray<[string, unknown]> = [
+      ['a traversal segment', '../../v3/glossaries%3fpwned=1'],
+      ['a bare parent segment', '..'],
+      ['a leading slash', '/v3/glossaries'],
+      ['an encoded slash', 'doc%2F..%2Fglossaries'],
+      ['a query string', 'doc-1?pwned=1'],
+      ['a fragment', 'doc-1#frag'],
+      ['a dot segment', 'doc/./1'],
+      ['whitespace', 'doc 1'],
+      ['an empty string', ''],
+      ['a missing id', undefined],
+      ['a non-string id', 42],
+    ];
+
+    describe.each(REJECTED)('rejects %s', (_label, documentId) => {
+      it('on getDocumentStatus, without issuing the request', async () => {
+        await expect(
+          client.getDocumentStatus({
+            documentId: documentId as string,
+            documentKey: 'key-abc',
+          })
+        ).rejects.toThrow(/document/i);
+        expect(mockAxiosInstance.request).not.toHaveBeenCalled();
+      });
+
+      it('on downloadDocument, without issuing the request', async () => {
+        await expect(
+          client.downloadDocument({
+            documentId: documentId as string,
+            documentKey: 'key-abc',
+          })
+        ).rejects.toThrow(/document/i);
+        expect(mockAxiosInstance.request).not.toHaveBeenCalled();
+      });
+    });
+
+    it('names the endpoint as the cause rather than the user', async () => {
+      let error: unknown;
+      expect.assertions(3);
+      try {
+        await client.getDocumentStatus({
+          documentId: '../../v3/glossaries',
+          documentKey: 'key-abc',
+        });
+      } catch (err) {
+        error = err;
+      }
+      expect((error as Error).name).toBe('NetworkError');
+      expect((error as Error).message).toMatch(/Unexpected API response/);
+      expect((error as Error).message).toContain('../../v3/glossaries');
+    });
+
+    it.each([
+      ['DeepL uppercase hex', 'A1B2C3D4E5F60718293A4B5C6D7E8F90'],
+      ['a hyphenated id', 'abc123-document-id'],
+      ['an underscored id', 'doc_1'],
+      ['a long numeric id', '1234567890'],
+    ])('accepts %s', async (_label, documentId) => {
+      mockAxiosInstance.request.mockResolvedValue({
+        data: { document_id: documentId, status: 'done' },
+        status: 200,
+        headers: {},
+      });
+
+      await expect(
+        client.getDocumentStatus({ documentId, documentKey: 'key-abc' })
+      ).resolves.toMatchObject({ status: 'done' });
+      expect(mockAxiosInstance.request).toHaveBeenCalledWith(
+        expect.objectContaining({ url: `/v2/document/${documentId}` })
+      );
+    });
+  });
+
   describe('getDocumentStatus()', () => {
     it('should return document status', async () => {
       mockAxiosInstance.request.mockResolvedValue({

From 55ad694494bf42faf7e68f63598d1173adc8cf34 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 10:37:09 +0200
Subject: [PATCH 154/256] fix(translate): bound the size of a structured file
 before parsing it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The direct `deepl translate <file.json|.yaml>` route read and fully parsed
whatever it was handed, while both sibling routes of the same command were
already bounded — text at 100 KiB, documents at 30 MB — and sync skips anything
over sync.limits.max_file_bytes. Measured peak RSS with a dead endpoint, so
only parse and extract are counted: 4.7 MB -> 129 MB, 19.2 MB -> 251 MB,
80.9 MB -> 684 MB, 163.8 MB -> 1178 MB, linear and unbounded.

The multi-target path multiplies it: it parses a fresh copy per target language,
up to MULTI_TARGET_CONCURRENCY at a time, so the same 19.2 MB file peaked at
252 MB for --to de and 483 MB for --to de,fr,es,it,nl.

The ceiling is 10 MiB, matching HARD_MAX_SYNC_LIMITS.max_file_bytes — the value
sync refuses to be configured above — so nothing sync can be made to accept is
refused here. A document stays capped far higher because it is streamed to the
API once and never becomes an object graph.

fs.stat runs before the read, in the one function both entry points funnel
through, so an oversize file is never resident: the 163.8 MB fixture exits 6 in
0.17 s at 86 MB RSS instead of 7.8 s at 1178 MB. The message names the file, its
size and the limit and points at `deepl sync`; a directory run fails only that
file and keeps its own reason in the summary.

Refs cli-8kr2.39
---
 CHANGELOG.md                                  |  2 +
 docs/API.md                                   |  2 +
 src/services/structured-file-translation.ts   | 39 +++++++++
 tests/e2e/cli-structured-file.e2e.test.ts     | 75 +++++++++++++++-
 .../unit/structured-file-translation.test.ts  | 87 +++++++++++++++++++
 5 files changed, 204 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 457a64ef..0dd6347d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -127,6 +127,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **translate**: **`deepl translate <file.json|.yaml>` now has a size ceiling, so a huge locale file cannot exhaust memory mid-run.** The structured-file route read and fully parsed whatever it was given, while both sibling routes of the same command were already bounded — text at 100 KiB, documents at 30 MB (`MAX_DOCUMENT_FILE_SIZE`) — and `deepl sync` skips anything over `sync.limits.max_file_bytes`. Measured peak RSS against a dead endpoint, so only parse and extract are counted: 4.7 MB → 129 MB, 19.2 MB → 251 MB, 80.9 MB → 684 MB, 163.8 MB → 1178 MB, linear and unbounded. The finding did not name the multiplier: the multi-target path parses a **fresh copy per target language**, up to `MULTI_TARGET_CONCURRENCY` (5) at once, so the same 19.2 MB file peaked at 252 MB for `--to de` and **483 MB** for `--to de,fr,es,it,nl`. The ceiling is 10 MiB, matching `HARD_MAX_SYNC_LIMITS.max_file_bytes` — the value `sync` refuses to be configured above — so nothing sync can be made to accept is refused here, and the worst case stays a few hundred MB rather than gigabytes. The check is a `fs.stat` before the read, at the one function both entry points funnel through, so an oversize file is never resident: the 163.8 MB fixture now exits 6 in 0.17 s at 86 MB RSS instead of 7.8 s at 1178 MB. The message names the file, its size and the limit, and points at `deepl sync` for anything larger; a directory run fails only that file and keeps its per-file reason in the summary. A document at 25 MB is still accepted, deliberately — it is streamed to the API rather than parsed.
+
 - **sync**: **`sync pull` no longer writes source-language text into a target locale file, and no longer replaces a local translation without saying so.** The merge that applies a pull response read `pulledKeys[key] ?? existingTarget.get(key) ?? entry.value`, so a key the TMS export omits **and** the target file lacks was filled in with the source string. Measured against a mock TMS whose `de` export carried only `greeting`: a source file holding `greeting`/`farewell`/`brand_new` and a `locales/de.json` holding the first two produced a German file containing `"brand_new": "Only in source"` — English, indistinguishable from a translation to anything reading the file — at **exit 0**, with the one-line summary `Pulled 1 translations from TMS`. The final `?? entry.value` is gone; a key with a value on neither side is now omitted from the entry list, which is what `reconstruct` needs to leave it out of the file, and matches what the locale translator already does for a key it could not translate (it pushes nothing rather than the source). An empty string is a translation and is still preserved. The same change fixes the case the finding did not name: when the target file does not exist yet, the source file is used as the reconstruction template, so **every** untranslated key was written into the new locale as English; only the keys the export actually carries are written now. Separately, the pulled value has always won over the local one and always will — neither side of the documented export contract carries a timestamp, so "which is newer" is not a question that can be answered, and pull exists to bring the reviewed copy in — but the overwrite was completely silent. Pull now counts the existing local translations it replaced and names the count (`Replaced 1 existing local translation with the TMS version. Use --dry-run to preview a pull before it overwrites local edits.`), with `--verbose` naming each key and file. See Added for the preview mode.
 
 - **translate**: **the CLI's own internal placeholder tokens can no longer be written into your text.** `restorePlaceholders` substituted every `__VAR_n__` it could find and silently left the rest alone, with nothing checking that the tokens the CLI had injected came back at all. Re-casing and re-spacing an unfamiliar token is ordinary MT behaviour, so `__VAR_0__` returning as `__ Var_0 __` produced, measured against a mock endpoint that does exactly that: `deepl translate "Welcome back, {username}!" --to de` printing `XX Welcome back, __ Var_0 __!` at **exit 0** with no warning; `deepl translate a.txt --output a.de.txt` writing the same to disk at exit 0; and a directory run writing it into every file at `✓ Successful: 2`. Only `sync` caught it, because only `sync` has a placeholder validator. All three paths now check the post-condition: `translate` fails with exit 5 naming the variables it lost (`The translation lost the placeholder {username}. … Nothing was written.`) and a suggestion pointing at the endpoint, and a directory run fails only the affected files — a file with no placeholders in it is unaffected and still translated. The check runs **before** the cache write, so a response that lost a placeholder never becomes a cache entry that reproduces the same output offline; a poisoned entry from an earlier version is refused on read for the same reason. `sync` is deliberately unchanged: its validator already withholds the key, counts it failed and retries it next run, and `validation.check_placeholders: false` stays the documented way to write such a translation anyway.
diff --git a/docs/API.md b/docs/API.md
index 63f858ea..f921eb00 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -357,6 +357,8 @@ The following structured formats are parsed to extract only string values, trans
 
 An empty string value is copied to the output unchanged and is never sent to the API, so a placeholder key you have not written copy for yet costs nothing and stays in the file. Requests are capped at 50 strings each; if one of them fails, no output file is written and the command exits with that failure's own code (for example 3 for a rate limit), because a partly translated file is indistinguishable from a complete one.
 
+**Size ceiling: 10 MiB.** A structured file above that is refused with a `ValidationError` (exit 6) naming its size, before it is read, and a directory run fails just that file. The limit is lower than the 30 MB document ceiling because these two routes cost very different amounts of memory: a document is streamed to the API once, while a structured file is parsed into an object graph — roughly 7-13x its size resident — and the multi-target path (`--to de,fr,es`) builds a fresh copy per language, up to 5 at a time. 10 MiB matches the ceiling `sync.limits.max_file_bytes` can never be configured above, so nothing [`deepl sync`](SYNC.md) accepts is refused here. For anything larger, split the file or use `deepl sync`, which walks a locale directory file by file and translates only the keys that changed.
+
 ```bash
 # Translate JSON locale file
 deepl translate en.json --to es --output es.json
diff --git a/src/services/structured-file-translation.ts b/src/services/structured-file-translation.ts
index 6ca7270b..0bd73ca4 100644
--- a/src/services/structured-file-translation.ts
+++ b/src/services/structured-file-translation.ts
@@ -30,6 +30,22 @@ import { describeKeyPath } from '../formats/format.js';
  */
 export const MAX_STRUCTURED_DEPTH = 100;
 
+/**
+ * Size ceiling for the direct `deepl translate <file.json|.yaml>` path, which
+ * has no `.deepl-sync.yaml` and therefore no `sync.limits.max_file_bytes` to
+ * consult. It matches `HARD_MAX_SYNC_LIMITS.max_file_bytes`, the value sync
+ * refuses to be configured above, so nothing sync can be made to accept is
+ * refused here.
+ *
+ * Parsing a structured file costs roughly 7-13x its size in resident memory,
+ * and the multi-target path parses a fresh copy per target language up to
+ * `MULTI_TARGET_CONCURRENCY` at a time: measured, a 19.2 MB file peaked at
+ * 252 MB for one target and 483 MB for five. The document route is capped far
+ * higher (`MAX_DOCUMENT_FILE_SIZE`, 30 MB) because it streams the bytes to the
+ * API once and never builds an object graph from them.
+ */
+export const MAX_STRUCTURED_FILE_BYTES = 10 * 1024 * 1024;
+
 interface FileTranslationOptions {
   preserveCode?: boolean;
   /** Bypasses the cache read and write, so `--no-cache` reaches the batch
@@ -179,6 +195,29 @@ export class StructuredFileTranslationService {
   }
 
   private async readFile(filePath: string): Promise<string> {
+    // Sized before the read, not after, so an oversize file is never resident:
+    // both entry points funnel through here, which is the only place the bound
+    // cannot be bypassed by a caller that forgets it.
+    try {
+      const stat = await fs.promises.stat(filePath);
+      if (stat.size > MAX_STRUCTURED_FILE_BYTES) {
+        const sizeMiB = (stat.size / (1024 * 1024)).toFixed(1);
+        const limitMiB = (MAX_STRUCTURED_FILE_BYTES / (1024 * 1024)).toFixed(0);
+        throw new ValidationError(
+          `${path.basename(filePath)} is ${sizeMiB} MiB, which exceeds the maximum of ${limitMiB} MiB for a JSON or YAML file translated in one command.`,
+          `Split the file, or use "deepl sync", which walks a locale directory file by file and translates only the keys that changed.`
+        );
+      }
+    } catch (err: unknown) {
+      if (err instanceof ValidationError) throw err;
+      const nodeErr = err as Error & { code?: string };
+      if (nodeErr.code === 'ENOENT') {
+        throw new ValidationError(`Input file not found: ${filePath}`);
+      }
+      // Any other stat failure flows through to the read below, which reports
+      // it in the terms the caller already handles.
+    }
+
     try {
       return await safeReadFile(filePath, 'utf-8');
     } catch (err: unknown) {
diff --git a/tests/e2e/cli-structured-file.e2e.test.ts b/tests/e2e/cli-structured-file.e2e.test.ts
index 52ae63b0..23e2c079 100644
--- a/tests/e2e/cli-structured-file.e2e.test.ts
+++ b/tests/e2e/cli-structured-file.e2e.test.ts
@@ -11,7 +11,7 @@ describe('Structured File Translation E2E', () => {
   const testConfig = createTestConfigDir('structured-e2e-config');
   const testFiles = createTestDir('structured-e2e');
   const testDir = testFiles.path;
-  const { runCLI } = makeRunCLI(testConfig.path, {
+  const { runCLI, runCLIAll, runCLIExpectError } = makeRunCLI(testConfig.path, {
     apiKey: 'fake-key-for-e2e',
   });
 
@@ -219,6 +219,79 @@ describe('Structured File Translation E2E', () => {
     });
   });
 
+  describe('input size ceiling', () => {
+    const OVER_CEILING_BYTES = 11 * 1024 * 1024;
+
+    /** Streams a large JSON file out without holding it in memory. */
+    function writeOversizeJson(filePath: string): void {
+      const handle = fs.openSync(filePath, 'w');
+      try {
+        fs.writeSync(handle, '{\n');
+        let written = 2;
+        let i = 0;
+        while (written < OVER_CEILING_BYTES) {
+          const line = `  "key_${i}": "value ${i}",\n`;
+          fs.writeSync(handle, line);
+          written += line.length;
+          i += 1;
+        }
+        fs.writeSync(handle, '  "last": "value"\n}\n');
+      } finally {
+        fs.closeSync(handle);
+      }
+    }
+
+    it('exits 6 naming the size and the limit, and writes no output', () => {
+      const inputPath = path.join(testDir, 'oversize.json');
+      const outputPath = path.join(testDir, 'oversize-es.json');
+      writeOversizeJson(inputPath);
+
+      const result = runCLIExpectError(
+        `deepl translate "${inputPath}" --to es --output "${outputPath}"`
+      );
+
+      expect(result.status).toBe(6);
+      expect(result.output).toMatch(/oversize\.json is 1[0-9.]+ MiB/);
+      expect(result.output).toContain('exceeds the maximum of 10 MiB');
+      expect(result.output).toContain('deepl sync');
+      expect(fs.existsSync(outputPath)).toBe(false);
+
+      fs.unlinkSync(inputPath);
+    });
+
+    it('fails only the oversize file in a directory run', () => {
+      const inputDir = path.join(testDir, 'oversize-dir');
+      const outputDir = path.join(testDir, 'oversize-dir-out');
+      fs.mkdirSync(inputDir, { recursive: true });
+      writeOversizeJson(path.join(inputDir, 'big.json'));
+      fs.writeFileSync(
+        path.join(inputDir, 'small.json'),
+        JSON.stringify({ a: 'Hello' })
+      );
+
+      // runCLIExpectError returns stderr whenever stderr is non-empty, which
+      // drops the per-file summary on stdout. runCLIAll merges the two with
+      // 2>&1, so the merged text survives on the thrown error's stdout.
+      let output: string;
+      try {
+        output = runCLIAll(
+          `deepl translate "${inputDir}" --to es --output "${outputDir}"`
+        );
+      } catch (error) {
+        output =
+          (error as { stdout?: Buffer | string }).stdout?.toString() ?? '';
+      }
+
+      // Both files fail here — big.json on the ceiling, small.json because the
+      // e2e key reaches no API — so the assertion is about which reason is
+      // reported for which file, not about the exit code.
+      expect(output).toMatch(/big\.json: big\.json is 1[0-9.]+ MiB/);
+      expect(output).not.toMatch(/small\.json: small\.json is/);
+
+      fs.rmSync(inputDir, { recursive: true, force: true });
+    });
+  });
+
   describe('file type detection', () => {
     it('should recognize JSON file by extension', () => {
       const inputPath = path.join(testDir, 'detect-test.json');
diff --git a/tests/unit/structured-file-translation.test.ts b/tests/unit/structured-file-translation.test.ts
index 30d34390..c10b0473 100644
--- a/tests/unit/structured-file-translation.test.ts
+++ b/tests/unit/structured-file-translation.test.ts
@@ -580,6 +580,93 @@ describe('StructuredFileTranslationService', () => {
     });
   });
 
+  describe('input size ceiling', () => {
+    /**
+     * Writes a JSON file of at least `bytes` without holding it in memory.
+     * A real file is needed because the guard reads `fs.stat`, not the content.
+     */
+    function writeJsonOfSize(filePath: string, bytes: number): void {
+      const handle = fs.openSync(filePath, 'w');
+      try {
+        fs.writeSync(handle, '{\n');
+        let written = 2;
+        let i = 0;
+        while (written < bytes) {
+          const line = `  "key_${i}": "value ${i}",\n`;
+          fs.writeSync(handle, line);
+          written += line.length;
+          i += 1;
+        }
+        fs.writeSync(handle, '  "last": "value"\n}\n');
+      } finally {
+        fs.closeSync(handle);
+      }
+    }
+
+    it('refuses a file over the ceiling before reading or translating it', async () => {
+      const inputPath = path.join(testDir, 'huge.json');
+      writeJsonOfSize(inputPath, 11 * 1024 * 1024);
+
+      await expect(
+        service.translateFile(inputPath, path.join(testDir, 'huge.de.json'), {
+          targetLang: 'de',
+        } as never)
+      ).rejects.toThrow(/exceeds the maximum/i);
+      expect(mockTranslationService.translateBatch).not.toHaveBeenCalled();
+      expect(fs.existsSync(path.join(testDir, 'huge.de.json'))).toBe(false);
+    });
+
+    it('refuses it on the multi-target path too', async () => {
+      const inputPath = path.join(testDir, 'huge-multi.json');
+      writeJsonOfSize(inputPath, 11 * 1024 * 1024);
+
+      await expect(
+        service.translateFileToMultiple(inputPath, ['de', 'fr'], {
+          outputDir: testDir,
+        })
+      ).rejects.toThrow(/exceeds the maximum/i);
+      expect(mockTranslationService.translateBatch).not.toHaveBeenCalled();
+    });
+
+    it('names the size, the limit and a way forward', async () => {
+      const inputPath = path.join(testDir, 'huge-msg.json');
+      writeJsonOfSize(inputPath, 11 * 1024 * 1024);
+
+      let error: unknown;
+      expect.assertions(4);
+      try {
+        await service.translateFile(inputPath, path.join(testDir, 'out.json'), {
+          targetLang: 'de',
+        } as never);
+      } catch (err) {
+        error = err;
+      }
+      expect((error as Error).name).toBe('ValidationError');
+      expect((error as Error).message).toMatch(/huge-msg\.json/);
+      expect((error as Error).message).toMatch(/10 MiB/);
+      expect((error as Error & { suggestion?: string }).suggestion).toMatch(
+        /deepl sync/
+      );
+    });
+
+    it('translates a file just under the ceiling', async () => {
+      const inputPath = path.join(testDir, 'large-ok.json');
+      writeJsonOfSize(inputPath, 9 * 1024 * 1024);
+      mockTranslationService.translateBatch.mockImplementation(
+        async (texts: string[]) =>
+          texts.map((t) => ({ text: `[de] ${t}`, billedCharacters: t.length }))
+      );
+
+      await service.translateFile(
+        inputPath,
+        path.join(testDir, 'large-ok.de.json'),
+        { targetLang: 'de' } as never
+      );
+
+      expect(fs.existsSync(path.join(testDir, 'large-ok.de.json'))).toBe(true);
+    }, 120000);
+  });
+
   describe('translateFileToMultiple()', () => {
     it('should translate to multiple target languages', async () => {
       const inputPath = path.join(testDir, 'en.json');

From 11b007094765e48bd5ff5f75b5506bc74999a7ec Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 11:26:45 +0200
Subject: [PATCH 155/256] fix(formats): refuse a file whose strings cannot be
 given distinct keys
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five parsers encode hierarchical key identity in-band with no escaping: PO
joins msgctxt and msgid with U+0004, YAML joins path segments with U+0000,
and JSON, Laravel PHP and Android XML join with '.'. A key component holding
the separator resolved to the same key as an unrelated entry, and the two
control bytes print as nothing, so the source diff showed an ordinary string.

Measured: a smuggled `msgid "menu<U+0004>Save"` beside a normal
`msgctxt "menu" / msgid "Save"` pair put the smuggled entry's translation into
the legitimate pair's msgstr. The stronger case needs no collision at all — one
smuggled msgid in a catalog with no msgctxt anywhere forged
`msgctxt "menu" / msgid "Save" / msgstr "ATTACKER-TEXT"` in every target
locale, which a duplicate-key check alone would have missed. YAML forges a
nested mapping the same way via doc.setIn. For the '.' formats the outcome is
loss or corruption: the Android `<string name="items.0">` element is deleted,
and the repo's own 11-dot-key-vs-nested.php fixture reconstructs to PHP that
fails to re-parse with `unexpected 'LAT' (T_STRING), expecting ']'`.

PO and YAML now reject the reserved byte at both key-construction sites, and
quote it back escaped rather than echoing a byte that prints as nothing. JSON,
Laravel PHP and Android XML assert distinct extract keys, which for those three
is equivalent to detecting a separator collision because their containers
already guarantee distinct sibling keys. .properties and XLIFF are excluded: a
literally repeated key is legal in both, so a blanket duplicate check would
have rejected files that work today.

walkBuckets skips the one file with a warning and finishes the run, following
the FormatDepthExceededError and max_entries_per_file convention. sync pull
reading a colliding target file leaves it untouched under a new key_collision
skip reason, rather than falling through to the source template — measured,
that fallback rebuilt locales/de.json down to the single key the export
carried, discarding a hand-written translation.

Refs cli-8kr2.40
---
 CHANGELOG.md                                  |   2 +
 docs/SYNC.md                                  |  12 +
 src/formats/android-xml.ts                    |  11 +-
 src/formats/format.ts                         |  39 ++++
 src/formats/index.ts                          |   2 +-
 src/formats/json.ts                           |   2 +
 src/formats/php-arrays.ts                     |   2 +
 src/formats/po.ts                             |  39 +++-
 src/formats/yaml.ts                           |  25 +++
 src/sync/sync-bucket-walker.ts                |   6 +-
 src/sync/sync-tms.ts                          |  21 +-
 tests/e2e/cli-sync-key-collision.e2e.test.ts  | 183 +++++++++++++++
 ...sync-tms-key-collision.integration.test.ts | 138 ++++++++++++
 tests/unit/formats/key-collision.test.ts      | 208 ++++++++++++++++++
 tests/unit/formats/php-arrays.test.ts         |  26 +--
 tests/unit/sync/sync-bucket-walker.test.ts    |  29 +++
 16 files changed, 714 insertions(+), 31 deletions(-)
 create mode 100644 tests/e2e/cli-sync-key-collision.e2e.test.ts
 create mode 100644 tests/integration/sync-tms-key-collision.integration.test.ts
 create mode 100644 tests/unit/formats/key-collision.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0dd6347d..b59faf67 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -420,6 +420,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync**: **a source catalog can no longer smuggle one string into another string's key.** Five parsers encode hierarchical key identity in-band with no escaping: PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.`. A key component holding the separator therefore resolved to the same key as an unrelated entry, and the two control bytes **print as nothing**, so the source diff showed an ordinary string. Measured: a PO catalog carrying `msgid "menu␄Save"` beside a normal `msgctxt "menu" / msgid "Save"` pair extracted two entries with the identical key `menu␄Save`, and reconstruct wrote the smuggled entry's translation into the legitimate pair's `msgstr` — the attacker picks the source text, DeepL translates it, and the result lands in the victim key's slot in **every** locale. **The stronger case needs no collision at all**: one smuggled `msgid "menu␄Save"` in a catalog with no `msgctxt` anywhere produced `msgctxt "menu"` / `msgid "Save"` / `msgstr "ATTACKER-TEXT"` in every target `.po`, forging a context-qualified entry the source never had — so a duplicate-key check alone would have missed it. YAML behaves the same way: a source key `"a\0b"` became a genuine nested `a: { b: ATTACKER-TEXT }` via `doc.setIn`. For the `.` formats the damage is a lost or corrupt file rather than a forgery: `{"a.b":"FLAT","a":{"b":"NESTED"}}` rewrote both slots to one translation and dropped the flat key's own; the Android `<string name="items.0">` colliding with `<string-array name="items">` was **deleted** from the output; and the Laravel case emitted PHP the CLI's own parser then refuses — the repo's `11-dot-key-vs-nested.php` fixture reconstructs to `'b' => 'PWNED<NESTED>'LAT>',`, failing to re-read with `syntax error, unexpected 'LAT' (T_STRING), expecting ']'`, because `collectStringLocs` maps a key to one source offset and the two replacements splice over each other. Each parser now refuses the file: PO and YAML reject the reserved byte at both key-construction sites (extract and the target-file read inside reconstruct), quoting it back escaped as `\u0004` / `\u0000` rather than echoing a byte that prints as nothing; JSON, Laravel PHP and Android XML assert their extract output has distinct keys, which for those three is exactly equivalent to detecting a separator collision because their containers already guarantee distinct sibling keys. `sync` skips the one file with a warning naming the colliding key and finishes the rest of the run at exit 0, following the existing `FormatDepthExceededError` and `max_entries_per_file` convention — one hostile file must not discard the lockfile for work already translated, billed and written. `.properties` and XLIFF are deliberately excluded: a literally repeated key is legal in both (Java `Properties.load` is last-wins), so a blanket duplicate check would have rejected files that work today. `sync pull` reading a **target** file whose keys collide leaves it untouched and records a `key_collision` skip, rather than falling through to the source template — measured, that fallback would have rebuilt `locales/de.json` from source down to the single key the export carried, discarding a hand-written translation.
+
 - **translate**: **a document upload response can no longer choose where this client sends its own follow-up requests.** The `document_id` from `POST /v2/document` was interpolated into `POST /v2/document/{id}` and `POST /v2/document/{id}/result` with no encoding and no format check, and the endpoint supplying it is redirectable via `--api-url`, `api.baseUrl` or a proxy. Measured against a stub answering `document_id: '../../v3/glossaries%3fpwned=1'`, the client's next two request lines arrived as `POST /v3/glossaries%3fpwned=1` and `POST /v3/glossaries%3fpwned=1/result` — the traversal collapsed exactly as crafted, on a completely different route from `/v2/document/{id}` — and the run finished at **exit 0** reporting `Translated report.pdf -> out.pdf` after writing the stub's JSON body into the output file as if it were a translated PDF. `document_id` is now checked against `[A-Za-z0-9_-]+` at both interpolation sites, so a redirected first response stops the workflow at exit 5 (`NetworkError`, since nothing the user typed is wrong) with the ID quoted back, nothing further sent, and no output file written. A response with no `document_id` at all was reaching the wire as the literal path `/v2/document/undefined`; that is refused by the same check. This was the last unguarded interpolation of an untrusted value into a URL path in the API layer — `GlossaryClient` validates its ID at all 7 sites and `StyleRulesClient` encodes at all 8, and the document client was the one exception among the ten clients. The polling loop was also checked: it re-sends the original handle rather than the `document_id` echoed by each status response, so a clean first response cannot be followed by a poisoned second one.
 
 - **sync**: **`sync pull` no longer records `review_status: human_reviewed` for content it never verified was reviewed.** Every key a pull applied was stamped `human_reviewed` in `.deepl-sync.lock`, unconditionally. The documented export contract is `GET /keys/export` returning `{ "key": "translated value", … }` — a flat map with no per-entry review flag — so there was nothing in the response to base that claim on, and a TMS that exports machine-translation drafts had them recorded in a committed file as human-reviewed. Where the `tms.server` in a checkout is not one the operator chose, the endpoint controls the strings *and* the review label attached to them. Measured: a mock export returning `{"greeting":"Hallo vom TMS"}` produced `"de": {"hash":"185f8db32271","review_status":"human_reviewed","status":"translated","translated_at":"…"}`. Pulled entries now record `status: translated` with **no** `review_status`, which is the type's way of saying "unknown"; `human_reviewed` is still honoured when a person or another tool writes it, and `--flag-for-review` still writes `machine_translated`, so nothing else in the lockfile changes. Nothing in the CLI reads `review_status` today, which is exactly why a false value could sit there unnoticed until something did — including the `tms.require_review` gate the config schema advertised.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index fc74de7c..711475a6 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -92,6 +92,16 @@ All parsers preserve format-specific metadata:
 
 The sync engine also supports **multi-locale formats** where all locales are stored in a single file (e.g., Apple `.xcstrings`). For these formats, the engine automatically serializes locale writes to prevent race conditions and passes the locale to the parser so it can scope extract/reconstruct operations to the correct locale section.
 
+### Key separators and colliding keys
+
+Every parser reduces a string's position in the file to a flat key, using a separator the format does not otherwise carry: PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.`. A key component containing that separator makes two different strings share one key, and there is no correct way to write them back — one translation lands in the other's slot.
+
+Such a file is **skipped with a warning naming the colliding key**, and the rest of the run continues at its normal exit code, the same way a file exceeding `limits.max_depth` is skipped. For PO and YAML the reserved byte is refused outright, and quoted back escaped (`\u0004`, `\u0000`) rather than printed, since it renders as nothing in a terminal or a diff. For the three `.`-separated formats the refusal triggers on two entries resolving to one key, which in those formats can only happen via the separator.
+
+`.properties` and XLIFF are exempt: a literally repeated key is legal in both (`Properties.load` is last-wins), so a repeat there is not evidence of a collision.
+
+On `deepl sync pull`, a **target** file whose keys collide is left exactly as it stands and reported under the `key_collision` skip reason. Pull does not fall back to rebuilding it from the source file, which would discard every local translation the TMS export does not carry.
+
 ## Configuration
 
 ### `.deepl-sync.yaml`
@@ -851,6 +861,8 @@ Each target locale's approved dictionary is fetched exactly once per `sync pull`
 
 **Pull does not claim human review.** The export endpoint returns `{ "key": "value" }` with no per-entry review flag, so pulled entries are recorded with `status: translated` and **no** `review_status`, meaning "unknown". Earlier releases stamped `review_status: human_reviewed` on every pulled key, asserting a review the CLI had not verified and the response did not describe.
 
+**A target file whose keys collide is left untouched.** Pull reads the existing target file so it can keep translations the export does not carry. If that file cannot be keyed unambiguously (see [Key separators and colliding keys](#key-separators-and-colliding-keys)), the locale is skipped with a warning and reported under the `key_collision` reason, and the file is not written. Pull deliberately does not fall back to reconstructing it from the source file in this case: that would replace the whole file with just the keys the export happened to carry.
+
 **Key-count limit:** The pull response is capped at **50,000 keys** (`MAX_PULL_KEY_COUNT`). Responses exceeding this limit are rejected with a `ValidationError` before any data is written. If your TMS project exceeds this threshold, partition the export by locale or paginate the pull on the TMS side before invoking `deepl sync pull`.
 
 **Note:** `push` and `pull` require a TMS that implements the REST contract documented above. They are optional -- `deepl sync` works entirely locally with just the DeepL Translation API.
diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index 796d5586..20e7b507 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -1,7 +1,8 @@
-import type {
-  ExtractedEntry,
-  FormatParser,
-  TranslatedEntry,
+import {
+  assertDistinctKeys,
+  type ExtractedEntry,
+  type FormatParser,
+  type TranslatedEntry,
 } from './format.js';
 import { ValidationError } from '../utils/errors.js';
 import {
@@ -158,6 +159,8 @@ export class AndroidXmlFormatParser implements FormatParser {
     this.extractPlurals(content, entries);
     this.extractStringArrays(content, entries);
 
+    assertDistinctKeys(entries, 'Android XML', '.');
+
     return entries;
   }
 
diff --git a/src/formats/format.ts b/src/formats/format.ts
index 9490554c..4912978b 100644
--- a/src/formats/format.ts
+++ b/src/formats/format.ts
@@ -54,6 +54,45 @@ export class FormatDepthExceededError extends Error {
   }
 }
 
+/**
+ * Thrown when a parser cannot give a file's strings distinct keys: a key
+ * component contains the byte the format uses to encode hierarchy, so two
+ * unrelated strings resolve to one key and reconstruct writes one translation
+ * into the other's slot. Walkers treat it like a depth rejection and skip the
+ * one file, since rewriting it is what does the damage.
+ */
+export class FormatKeyCollisionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FormatKeyCollisionError';
+  }
+}
+
+/**
+ * Refuse extract output in which two entries share a key. Only for formats
+ * whose container already guarantees distinct sibling keys, where a repeat
+ * therefore proves a separator collision rather than a duplicate the format
+ * permits — `.properties` and XLIFF allow literal repeats and must not use it.
+ */
+export function assertDistinctKeys(
+  entries: readonly ExtractedEntry[],
+  format: string,
+  separator: string
+): void {
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    if (seen.has(entry.key)) {
+      throw new FormatKeyCollisionError(
+        `${format}: '${describeKeyPath(entry.key)}' is the key of two different strings. ` +
+          `A literal '${separator}' inside a key is indistinguishable from the separator ` +
+          `between levels, so one translation would be written over the other. ` +
+          `Rename one of them.`
+      );
+    }
+    seen.add(entry.key);
+  }
+}
+
 /**
  * Renders a key path for a depth-limit message. At the depth these fire, the
  * full path is dozens of segments of no diagnostic value beyond the first few,
diff --git a/src/formats/index.ts b/src/formats/index.ts
index 8b28e33b..cc11c8e0 100644
--- a/src/formats/index.ts
+++ b/src/formats/index.ts
@@ -77,4 +77,4 @@ export type {
   ExtractedEntry,
   TranslatedEntry,
 } from './format.js';
-export { FormatDepthExceededError } from './format.js';
+export { FormatDepthExceededError, FormatKeyCollisionError } from './format.js';
diff --git a/src/formats/json.ts b/src/formats/json.ts
index 4890487e..8f34a4d5 100644
--- a/src/formats/json.ts
+++ b/src/formats/json.ts
@@ -1,5 +1,6 @@
 import {
   FormatDepthExceededError,
+  assertDistinctKeys,
   describeKeyPath,
   type ExtractedEntry,
   type FormatParser,
@@ -65,6 +66,7 @@ export class JsonFormatParser implements FormatParser {
     const data: unknown = JSON.parse(clean);
     const entries: ExtractedEntry[] = [];
     this.walk(data, '', entries);
+    assertDistinctKeys(entries, 'JSON', '.');
     return entries;
   }
 
diff --git a/src/formats/php-arrays.ts b/src/formats/php-arrays.ts
index e2cf9a36..6a918637 100644
--- a/src/formats/php-arrays.ts
+++ b/src/formats/php-arrays.ts
@@ -1,5 +1,6 @@
 import {
   FormatDepthExceededError,
+  assertDistinctKeys,
   type ExtractedEntry,
   type FormatParser,
   type TranslatedEntry,
@@ -144,6 +145,7 @@ export class PhpArraysFormatParser implements FormatParser {
 
     const entries: ExtractedEntry[] = [];
     walkArray(returnNode.expr as PhpArray, '', entries, 1, this.maxDepth);
+    assertDistinctKeys(entries, 'Laravel PHP', '.');
     return entries;
   }
 
diff --git a/src/formats/po.ts b/src/formats/po.ts
index fa87dc82..e5df83fc 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -1,7 +1,9 @@
-import type {
-  ExtractedEntry,
-  FormatParser,
-  TranslatedEntry,
+import {
+  FormatKeyCollisionError,
+  describeKeyPath,
+  type ExtractedEntry,
+  type FormatParser,
+  type TranslatedEntry,
 } from './format.js';
 
 interface PoEntry {
@@ -84,8 +86,33 @@ function isHeaderEntry(entry: PoEntry): boolean {
 
 const CONTEXT_SEPARATOR = '\x04';
 
+/**
+ * gettext reserves U+0004 as the msgctxt/msgid separator, so a msgid carrying
+ * one is indistinguishable from a context-qualified entry. Left alone it lets a
+ * plain msgid claim the key of an unrelated `msgctxt "x" / msgid "y"` pair, or —
+ * where no such pair exists — makes reconstruct emit a msgctxt the source
+ * catalog never had. The byte prints as nothing, so the source diff shows an
+ * ordinary string.
+ */
+function assertNoContextSeparator(field: string, value: string): void {
+  if (value.includes(CONTEXT_SEPARATOR)) {
+    // Escaped, not echoed: the byte prints as nothing, so quoting it verbatim
+    // would show the reader the string they already believe they have.
+    const shown = describeKeyPath(value)
+      .split(CONTEXT_SEPARATOR)
+      .join('\\u0004');
+    throw new FormatKeyCollisionError(
+      `PO: ${field} "${shown}" contains a U+0004 byte, which gettext reserves ` +
+        `as the msgctxt separator, so the entry is indistinguishable from a ` +
+        `msgctxt/msgid pair. Remove the byte.`
+    );
+  }
+}
+
 function makeKey(entry: PoEntry): string {
+  assertNoContextSeparator('msgid', entry.msgid);
   if (entry.msgctxt !== undefined) {
+    assertNoContextSeparator('msgctxt', entry.msgctxt);
     return `${entry.msgctxt}${CONTEXT_SEPARATOR}${entry.msgid}`;
   }
   return entry.msgid;
@@ -412,6 +439,10 @@ export class PoFormatParser implements FormatParser {
         continue;
       }
 
+      assertNoContextSeparator('msgid', entryMsgid);
+      if (entryMsgctxt !== undefined) {
+        assertNoContextSeparator('msgctxt', entryMsgctxt);
+      }
       const key =
         entryMsgctxt !== undefined
           ? `${entryMsgctxt}${CONTEXT_SEPARATOR}${entryMsgid}`
diff --git a/src/formats/yaml.ts b/src/formats/yaml.ts
index 21f5e46e..f3826f71 100644
--- a/src/formats/yaml.ts
+++ b/src/formats/yaml.ts
@@ -1,6 +1,8 @@
 import * as YAML from 'yaml';
 import {
   FormatDepthExceededError,
+  FormatKeyCollisionError,
+  describeKeyPath,
   type FormatParser,
   type ExtractedEntry,
   type TranslatedEntry,
@@ -25,6 +27,28 @@ function assertNotStackExhaustion(messages: string): void {
   }
 }
 
+const PATH_SEPARATOR = '\0';
+
+/**
+ * Path segments are joined with U+0000 to form a key, so a mapping key holding
+ * one resolves to the same key as an unrelated nested path. Where no such path
+ * exists, `doc.setIn` splits the key back apart and reconstruct writes a nested
+ * mapping the source never had. The byte prints as nothing, so the source diff
+ * shows an ordinary key.
+ */
+function assertNoPathSeparator(key: string): void {
+  if (key.includes(PATH_SEPARATOR)) {
+    // Escaped, not echoed: the byte prints as nothing, so quoting it verbatim
+    // would show the reader the key they already believe they have.
+    const shown = describeKeyPath(key).split(PATH_SEPARATOR).join('\\u0000');
+    throw new FormatKeyCollisionError(
+      `YAML: key "${shown}" contains a U+0000 byte, which separates path ` +
+        `segments, so the key is indistinguishable from a nested path. ` +
+        `Remove the byte.`
+    );
+  }
+}
+
 type StringSlot =
   | { path: string[]; value: string; parent: YAML.YAMLMap; pair: YAML.Pair }
   | { path: string[]; value: string; parent: YAML.YAMLSeq; index: number };
@@ -169,6 +193,7 @@ export class YamlFormatParser implements FormatParser {
           const key = String(
             YAML.isScalar(pair.key) ? pair.key.value : pair.key
           );
+          assertNoPathSeparator(key);
           const childPath = [...path, key];
           const value = pair.value;
           recordAnchor(value);
diff --git a/src/sync/sync-bucket-walker.ts b/src/sync/sync-bucket-walker.ts
index 1038b2bf..ca0245f7 100644
--- a/src/sync/sync-bucket-walker.ts
+++ b/src/sync/sync-bucket-walker.ts
@@ -3,6 +3,7 @@ import * as path from 'path';
 import fg from 'fast-glob';
 import {
   FormatDepthExceededError,
+  FormatKeyCollisionError,
   type ExtractedEntry,
   type FormatParser,
   type FormatRegistry,
@@ -176,7 +177,10 @@ export async function* walkBuckets(
             ? parser.extract(content, config.source_locale)
             : parser.extract(content);
       } catch (err) {
-        if (err instanceof FormatDepthExceededError) {
+        if (
+          err instanceof FormatDepthExceededError ||
+          err instanceof FormatKeyCollisionError
+        ) {
           Logger.warn(
             `Skipping ${path.relative(config.projectRoot, sourceFile)}: ${err.message}`
           );
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index 78150a5a..eca3f6fe 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -1,6 +1,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import type { ExtractedEntry, FormatRegistry } from '../formats/index.js';
+import {
+  FormatKeyCollisionError,
+  type ExtractedEntry,
+  type FormatRegistry,
+} from '../formats/index.js';
 import type { TmsClient } from './tms-client.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import {
@@ -26,7 +30,8 @@ export interface SyncPushPullOptions {
   dryRun?: boolean;
 }
 
-export type SkipReason = 'target_missing' | 'no_matches' | 'pipe_pluralization';
+export type SkipReason =
+  'target_missing' | 'no_matches' | 'pipe_pluralization' | 'key_collision';
 
 export interface SkippedRecord {
   file: string;
@@ -50,6 +55,7 @@ const SKIP_REASON_LABELS: Record<SkipReason, string> = {
   target_missing: 'target file not yet present',
   no_matches: 'no matching keys',
   pipe_pluralization: 'pipe-pluralization (never sent to TMS)',
+  key_collision: 'target file keys collide (left untouched)',
 };
 
 /**
@@ -226,7 +232,16 @@ export async function pullTranslations(
         existingTargetEntries = new Map(
           existingEntries.map((entry) => [entry.key, entry.value])
         );
-      } catch {
+      } catch (err) {
+        // A target file whose keys collide cannot be merged into — and must not
+        // fall through to the source template either, which would rebuild it
+        // from source text and discard every local translation the export does
+        // not carry. Leave the file as it stands.
+        if (err instanceof FormatKeyCollisionError) {
+          Logger.warn(`Skipping ${targetRelPath}: ${err.message}`);
+          skipped.push({ file: relPath, locale, reason: 'key_collision' });
+          continue;
+        }
         templateContent = sourceContent;
       }
 
diff --git a/tests/e2e/cli-sync-key-collision.e2e.test.ts b/tests/e2e/cli-sync-key-collision.e2e.test.ts
new file mode 100644
index 00000000..eb23629e
--- /dev/null
+++ b/tests/e2e/cli-sync-key-collision.e2e.test.ts
@@ -0,0 +1,183 @@
+/**
+ * E2E regression for in-band key separators in a repo-supplied source catalog.
+ *
+ * PO joins msgctxt and msgid with U+0004, which prints as nothing: a source
+ * msgid holding one reviews as an ordinary string, yet reconstruct splits
+ * it back apart and writes `msgctxt "menu" / msgid "Save"` — attacker-chosen
+ * text under a key the source catalog never had — into every target locale, at
+ * exit 0. JSON's separator is '.', so a flat `"a.b"` beside a nested `a: { b }`
+ * resolves to one key and one translation lands in both slots.
+ *
+ * Both files must be skipped with a warning while the rest of the bucket still
+ * translates: one hostile file must not end a run whose other files are already
+ * billed.
+ */
+
+import { spawn, spawnSync, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const CONTEXT_SEPARATOR = '\u0004';
+
+describe('CLI sync key-collision containment', () => {
+  const testConfig = createTestConfigDir('e2e-sync-key-collision');
+  const testFiles = createTestDir('e2e-sync-key-collision-files');
+  let mockServer: ChildProcess;
+  let baseUrl: string;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'node',
+        [path.join(__dirname, 'mock-deepl-server.cjs')],
+        { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env } }
+      );
+      mockServer = child;
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = /PORT=(\d+)/.exec(output);
+        if (match) resolve(parseInt(match[1]!, 10));
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  function runCli(args: string[]): {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+  } {
+    const { CI: _ci, DEEPL_API_KEY: _key, ...rest } = process.env;
+    const result = spawnSync('node', [CLI_PATH, ...args], {
+      encoding: 'utf-8',
+      cwd: testFiles.path,
+      env: { ...rest, DEEPL_CONFIG_DIR: testConfig.path, NO_COLOR: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60000,
+    });
+    return {
+      status: result.status,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  beforeAll(async () => {
+    const port = await startMockServer();
+    baseUrl = `http://127.0.0.1:${port}`;
+
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl, usePro: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+      })
+    );
+
+    fs.writeFileSync(
+      path.join(testFiles.path, '.deepl-sync.yaml'),
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - de',
+        'buckets:',
+        '  po:',
+        '    include:',
+        '      - "locales/en/*.po"',
+        '  json:',
+        '    include:',
+        '      - "locales/*.en.json"',
+        '',
+      ].join('\n')
+    );
+
+    const poDir = path.join(testFiles.path, 'locales', 'en');
+    fs.mkdirSync(poDir, { recursive: true });
+    const header = [
+      'msgid ""',
+      'msgstr ""',
+      '"Content-Type: text/plain; charset=UTF-8\\n"',
+      '',
+    ];
+    fs.writeFileSync(
+      path.join(poDir, 'hostile.po'),
+      [...header, `msgid "menu${CONTEXT_SEPARATOR}Save"`, 'msgstr ""', ''].join(
+        '\n'
+      )
+    );
+    fs.writeFileSync(
+      path.join(poDir, 'clean.po'),
+      [...header, 'msgid "Hello"', 'msgstr ""', ''].join('\n')
+    );
+
+    fs.writeFileSync(
+      path.join(testFiles.path, 'locales', 'shadowed.en.json'),
+      JSON.stringify({ 'a.b': 'Hello', a: { b: 'Good morning' } }, null, 2) +
+        '\n'
+    );
+    fs.writeFileSync(
+      path.join(testFiles.path, 'locales', 'plain.en.json'),
+      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
+    );
+  }, 30000);
+
+  afterAll(() => {
+    if (mockServer) mockServer.kill('SIGTERM');
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  it('translates the clean files and skips only the colliding ones', () => {
+    const result = runCli(['sync', '--yes']);
+    const merged = result.stdout + result.stderr;
+
+    expect(result.status).toBe(0);
+    expect(merged).toContain('Skipping locales/en/hostile.po');
+    expect(merged).toContain('Skipping locales/shadowed.en.json');
+    expect(merged).toContain('U+0004');
+
+    expect(
+      fs.existsSync(path.join(testFiles.path, 'locales', 'de', 'clean.po'))
+    ).toBe(true);
+    expect(
+      fs.existsSync(path.join(testFiles.path, 'locales', 'plain.de.json'))
+    ).toBe(true);
+  }, 60000);
+
+  it('writes no forged msgctxt entry into the target catalog', () => {
+    const deDir = path.join(testFiles.path, 'locales', 'de');
+    const written = fs
+      .readdirSync(deDir)
+      .map((f) => fs.readFileSync(path.join(deDir, f), 'utf-8'))
+      .join('\n');
+
+    expect(written).not.toContain('msgctxt');
+    expect(written).not.toContain(CONTEXT_SEPARATOR);
+    expect(fs.existsSync(path.join(deDir, 'hostile.po'))).toBe(false);
+    // The clean sibling really was translated, so the skip is selective and not
+    // a bucket that failed before reaching the API.
+    expect(written).toContain('msgstr "Hola"');
+  });
+
+  it('writes no target file for the shadowed JSON source', () => {
+    expect(
+      fs.existsSync(path.join(testFiles.path, 'locales', 'shadowed.de.json'))
+    ).toBe(false);
+  });
+});
diff --git a/tests/integration/sync-tms-key-collision.integration.test.ts b/tests/integration/sync-tms-key-collision.integration.test.ts
new file mode 100644
index 00000000..71a50a11
--- /dev/null
+++ b/tests/integration/sync-tms-key-collision.integration.test.ts
@@ -0,0 +1,138 @@
+/**
+ * Integration tests for a key collision in a TMS pull's target file.
+ *
+ * pullTranslations reads the existing target file to keep local translations the
+ * export does not carry. That read is wrapped in a catch whose fallback is the
+ * source content — correct for "target does not exist yet", ruinous for a file
+ * that parses but cannot be keyed, since rebuilding from source discards every
+ * local translation. A collision therefore has to leave the file untouched
+ * rather than reach either the merge or the fallback.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { createTmsClient } from '../../src/sync/tms-client';
+import { pullTranslations } from '../../src/sync/sync-tms';
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { Logger } from '../../src/utils/logger';
+
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import {
+  expectTmsPull,
+  tmsConfig,
+  approvedTmsTrust,
+} from '../helpers/tms-nock';
+
+function writeFile(dir: string, relPath: string, content: string): void {
+  const abs = path.join(dir, relPath);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, 'utf-8');
+}
+
+describe('sync pull with a colliding target file', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+  let envSnapshot: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    envSnapshot = { ...process.env };
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-collide-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    delete process.env['TMS_API_KEY'];
+    delete process.env['TMS_TOKEN'];
+    process.env['TMS_API_KEY'] = 'env-key';
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+    process.env = envSnapshot;
+  });
+
+  it('leaves the target file byte-identical and records a key_collision skip', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeFile(
+      tmpDir,
+      'locales/en.json',
+      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n'
+    );
+    // Parses, but `a.b` names both the flat key and the nested path.
+    const hostileTarget =
+      JSON.stringify(
+        {
+          greeting: 'Hallo (hand-written)',
+          'a.b': 'FLAT',
+          a: { b: 'NESTED' },
+        },
+        null,
+        2
+      ) + '\n';
+    writeFile(tmpDir, 'locales/de.json', hostileTarget);
+
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+    const pullScope = expectTmsPull(
+      'de',
+      { greeting: 'Hallo (from TMS)' },
+      { auth: { apiKey: 'env-key' } }
+    );
+
+    const warnings: string[] = [];
+    jest.spyOn(Logger, 'warn').mockImplementation((...args: unknown[]) => {
+      warnings.push(args.join(' '));
+    });
+
+    const result = await pullTranslations(config, client, harness.registry);
+
+    expect(pullScope.isDone()).toBe(true);
+    expect(result.pulled).toBe(0);
+    expect(result.skipped).toEqual([
+      { file: 'locales/en.json', locale: 'de', reason: 'key_collision' },
+    ]);
+    expect(warnings.join('\n')).toContain('Skipping locales/de.json');
+
+    expect(fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8')).toBe(
+      hostileTarget
+    );
+  });
+
+  it('still pulls into a target file whose keys are distinct', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeFile(
+      tmpDir,
+      'locales/en.json',
+      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
+    );
+    writeFile(
+      tmpDir,
+      'locales/de.json',
+      JSON.stringify({ greeting: 'ALT' }, null, 2) + '\n'
+    );
+
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+    expectTmsPull(
+      'de',
+      { greeting: 'Hallo (from TMS)' },
+      { auth: { apiKey: 'env-key' } }
+    );
+
+    const result = await pullTranslations(config, client, harness.registry);
+
+    expect(result.pulled).toBe(1);
+    expect(result.skipped).toEqual([]);
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8')
+    ) as Record<string, string>;
+    expect(written['greeting']).toBe('Hallo (from TMS)');
+  });
+});
diff --git a/tests/unit/formats/key-collision.test.ts b/tests/unit/formats/key-collision.test.ts
new file mode 100644
index 00000000..ed90a6d2
--- /dev/null
+++ b/tests/unit/formats/key-collision.test.ts
@@ -0,0 +1,208 @@
+/**
+ * Tests that a parser refuses a file whose strings cannot be given distinct
+ * keys, instead of rewriting it.
+ *
+ * Four parsers encode hierarchy in-band: PO joins msgctxt and msgid with
+ * U+0004, YAML joins path segments with U+0000, JSON / Laravel PHP / Android XML
+ * join with '.'. A key component holding the separator therefore resolves to the
+ * same key as an unrelated entry, and reconstruct writes one string's
+ * translation into the other's slot — invisibly, for the two control bytes.
+ */
+
+import { PoFormatParser } from '../../../src/formats/po';
+import { YamlFormatParser } from '../../../src/formats/yaml';
+import { JsonFormatParser } from '../../../src/formats/json';
+import { PhpArraysFormatParser } from '../../../src/formats/php-arrays';
+import { AndroidXmlFormatParser } from '../../../src/formats/android-xml';
+import { PropertiesFormatParser } from '../../../src/formats/properties';
+import { XliffFormatParser } from '../../../src/formats/xliff';
+import {
+  FormatKeyCollisionError,
+  type TranslatedEntry,
+} from '../../../src/formats/format';
+
+const EOT = '\u0004';
+const NUL = '\u0000';
+
+const PO_HEADER = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '',
+].join('\n');
+
+describe('PO msgctxt separator smuggled into a msgid', () => {
+  const parser = new PoFormatParser();
+
+  it('should refuse a msgid holding the U+0004 context separator', () => {
+    const po = [PO_HEADER, `msgid "menu${EOT}Save"`, 'msgstr ""', ''].join(
+      '\n'
+    );
+
+    expect(() => parser.extract(po)).toThrow(FormatKeyCollisionError);
+  });
+
+  it('should refuse a msgctxt holding the U+0004 context separator', () => {
+    const po = [
+      PO_HEADER,
+      `msgctxt "menu${EOT}extra"`,
+      'msgid "Save"',
+      'msgstr ""',
+      '',
+    ].join('\n');
+
+    expect(() => parser.extract(po)).toThrow(FormatKeyCollisionError);
+  });
+
+  it('should name the offending codepoint so an invisible byte is actionable', () => {
+    const po = [PO_HEADER, `msgid "menu${EOT}Save"`, 'msgstr ""', ''].join(
+      '\n'
+    );
+
+    expect(() => parser.extract(po)).toThrow(/U\+0004/);
+  });
+
+  it('should refuse the same byte in an existing target catalog on reconstruct', () => {
+    const target = [PO_HEADER, `msgid "menu${EOT}Save"`, 'msgstr "x"', ''].join(
+      '\n'
+    );
+    const entries: TranslatedEntry[] = [
+      { key: 'Save', value: 'Save', translation: 'Speichern' },
+    ];
+
+    expect(() => parser.reconstruct(target, entries)).toThrow(
+      FormatKeyCollisionError
+    );
+  });
+
+  it('should still accept a legitimate msgctxt/msgid pair', () => {
+    const po = [
+      PO_HEADER,
+      'msgctxt "menu"',
+      'msgid "Save"',
+      'msgstr ""',
+      '',
+    ].join('\n');
+
+    const entries = parser.extract(po);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.key).toBe(`menu${EOT}Save`);
+  });
+});
+
+describe('YAML path separator smuggled into a key', () => {
+  const parser = new YamlFormatParser();
+
+  it('should refuse a key holding the U+0000 path separator', () => {
+    expect(() => parser.extract(`? "a\\0b"\n: Save\n`)).toThrow(
+      FormatKeyCollisionError
+    );
+  });
+
+  it('should name the offending codepoint', () => {
+    expect(() => parser.extract(`? "a\\0b"\n: Save\n`)).toThrow(/U\+0000/);
+  });
+
+  it('should refuse the same byte in an existing target file on reconstruct', () => {
+    const entries: TranslatedEntry[] = [
+      { key: 'other', value: 'Other', translation: 'Andere' },
+    ];
+
+    expect(() =>
+      parser.reconstruct(`? "a\\0b"\n: Save\nother: Other\n`, entries)
+    ).toThrow(FormatKeyCollisionError);
+  });
+
+  it('should still accept a nested mapping', () => {
+    const entries = parser.extract('a:\n  b: Save\n');
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.key).toBe(`a${NUL}b`);
+  });
+});
+
+describe('dotted-path parsers refuse a key that collides with a nested path', () => {
+  it('JSON should refuse a flat dotted key shadowing a nested path', () => {
+    const json = JSON.stringify({ 'a.b': 'FLAT', a: { b: 'NESTED' } }, null, 2);
+
+    expect(() => new JsonFormatParser().extract(json)).toThrow(
+      FormatKeyCollisionError
+    );
+  });
+
+  it('Laravel PHP should refuse a flat dotted key shadowing a nested path', () => {
+    const php =
+      "<?php\nreturn [\n  'a.b' => 'FLAT',\n  'a' => [\n    'b' => 'NESTED',\n  ],\n];\n";
+
+    expect(() => new PhpArraysFormatParser().extract(php)).toThrow(
+      FormatKeyCollisionError
+    );
+  });
+
+  it('Android XML should refuse a string name colliding with a string-array index', () => {
+    const xml = [
+      '<?xml version="1.0" encoding="utf-8"?>',
+      '<resources>',
+      '  <string name="items.0">FLAT</string>',
+      '  <string-array name="items">',
+      '    <item>NESTED</item>',
+      '  </string-array>',
+      '</resources>',
+      '',
+    ].join('\n');
+
+    expect(() => new AndroidXmlFormatParser().extract(xml)).toThrow(
+      FormatKeyCollisionError
+    );
+  });
+
+  it('should report the colliding key so the user knows which to rename', () => {
+    const json = JSON.stringify({ 'a.b': 'FLAT', a: { b: 'NESTED' } }, null, 2);
+
+    expect(() => new JsonFormatParser().extract(json)).toThrow(/'a\.b'/);
+  });
+
+  it('JSON should still accept a flat dotted key with no nested counterpart', () => {
+    const json = JSON.stringify({ 'a.b': 'FLAT', c: 'OTHER' }, null, 2);
+
+    const entries = new JsonFormatParser().extract(json);
+    expect(entries.map((e) => e.key)).toEqual(['a.b', 'c']);
+  });
+
+  it('Android XML should still accept string-array indices', () => {
+    const xml = [
+      '<?xml version="1.0" encoding="utf-8"?>',
+      '<resources>',
+      '  <string-array name="items">',
+      '    <item>one</item>',
+      '    <item>two</item>',
+      '  </string-array>',
+      '</resources>',
+      '',
+    ].join('\n');
+
+    const entries = new AndroidXmlFormatParser().extract(xml);
+    expect(entries.map((e) => e.key)).toEqual(['items.0', 'items.1']);
+  });
+});
+
+describe('formats that permit a literal repeated key are left alone', () => {
+  it('.properties should keep extracting a legally repeated key', () => {
+    const entries = new PropertiesFormatParser().extract('a=one\na=two\n');
+    expect(entries.map((e) => e.key)).toEqual(['a', 'a']);
+  });
+
+  it('XLIFF should keep extracting a repeated trans-unit id', () => {
+    const xliff = [
+      '<?xml version="1.0"?>',
+      '<xliff version="1.2"><file source-language="en" target-language="de" datatype="plaintext" original="x">',
+      '<body>',
+      '<trans-unit id="a"><source>one</source></trans-unit>',
+      '<trans-unit id="a"><source>two</source></trans-unit>',
+      '</body></file></xliff>',
+      '',
+    ].join('\n');
+
+    const entries = new XliffFormatParser().extract(xliff);
+    expect(entries.map((e) => e.key)).toEqual(['a', 'a']);
+  });
+});
diff --git a/tests/unit/formats/php-arrays.test.ts b/tests/unit/formats/php-arrays.test.ts
index c4788311..b7fd95e7 100644
--- a/tests/unit/formats/php-arrays.test.ts
+++ b/tests/unit/formats/php-arrays.test.ts
@@ -6,6 +6,7 @@ import {
   SKIP_REASON_PIPE_PLURALIZATION,
 } from '../../../src/formats/php-arrays';
 import { createDefaultRegistry } from '../../../src/formats/index';
+import { FormatKeyCollisionError } from '../../../src/formats/format';
 import { ValidationError } from '../../../src/utils/errors';
 import { Logger } from '../../../src/utils/logger';
 
@@ -550,24 +551,13 @@ return [
         expect(keys).toEqual(['errors.required', 'welcome']);
       });
 
-      it('11: literal-dot key coexists with a nested `user.name` path', () => {
-        const entries = parser.extract(load('11-dot-key-vs-nested.php'));
-        const map = Object.fromEntries(entries.map((e) => [e.key, e.value]));
-        // Both keys exist and collide at the dot-path level — this is a
-        // known Laravel ambiguity. The extract faithfully surfaces both;
-        // downstream diff/translate logic is responsible for choosing a
-        // resolution strategy (currently last-write-wins via Map semantics).
-        expect(map['user.name']).toBeDefined();
-        expect(
-          entries.some(
-            (e) => e.key === 'user.name' && e.value === 'Literal dot key'
-          )
-        ).toBe(true);
-        expect(
-          entries.some(
-            (e) => e.key === 'user.name' && e.value === 'Nested under user.name'
-          )
-        ).toBe(true);
+      it('11: a literal-dot key colliding with a nested path is refused', () => {
+        // Both strings resolve to the key `user.name`, and reconstruct maps a
+        // key to one source offset, so the two replacements splice over each
+        // other: the emitted file no longer parses. Refusing beats rewriting.
+        expect(() => parser.extract(load('11-dot-key-vs-nested.php'))).toThrow(
+          FormatKeyCollisionError
+        );
       });
 
       it('12: `"\\$100"` and `"\\${currency}"` decode to literal `$`', () => {
diff --git a/tests/unit/sync/sync-bucket-walker.test.ts b/tests/unit/sync/sync-bucket-walker.test.ts
index 7636ca11..9398dffc 100644
--- a/tests/unit/sync/sync-bucket-walker.test.ts
+++ b/tests/unit/sync/sync-bucket-walker.test.ts
@@ -7,6 +7,7 @@ import { FormatRegistry } from '../../../src/formats/index';
 import { JsonFormatParser } from '../../../src/formats/json';
 import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
 import { ValidationError } from '../../../src/utils/errors';
+import { Logger } from '../../../src/utils/logger';
 
 jest.mock('fast-glob', () => ({ __esModule: true, default: jest.fn() }));
 jest.mock('fs', () => {
@@ -248,6 +249,34 @@ describe('walkBuckets', () => {
       expect(result).toHaveLength(0);
     });
   });
+
+  describe('key-collision rejection', () => {
+    it('skips a file whose keys collide rather than ending the run', async () => {
+      mockFg.mockResolvedValue([
+        '/test/locales/en.json',
+        '/test/locales/other.json',
+      ] as never);
+      mockReadFile.mockImplementation((p: string) =>
+        Promise.resolve(
+          p.endsWith('en.json')
+            ? '{"a.b":"FLAT","a":{"b":"NESTED"}}'
+            : '{"ok":"Hello"}'
+        )
+      );
+
+      const warn = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+      const seen: string[] = [];
+      for await (const walked of walkBuckets(makeConfig(), makeRegistry())) {
+        seen.push(walked.relPath);
+      }
+
+      expect(seen).toEqual(['locales/other.json']);
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('Skipping locales/en.json')
+      );
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining("'a.b'"));
+    });
+  });
 });
 
 describe('extractTranslatable', () => {

From 7efc5b9c94c82988dce0212abd5b331b6feb5325 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 11:34:38 +0200
Subject: [PATCH 156/256] fix(formats): treat only an odd trailing backslash
 run as a .properties continuation

escapeValue writes a literal trailing backslash as `\\`, but the reader's
continuation test was line.endsWith('\\') with no parity check, so it read that
escape as "this line continues", consumed the following line and appended its
raw text to the previous value.

Measured: a source of greeting=Hello / api_key=SECRET_VALUE / footer=Bye with
greeting translated to `Hallo\` was written as `greeting=Hallo\\` and
re-extracted as [{greeting: "Halloapi_key=SECRET_VALUE"}, {footer: "Bye"}] --
the middle entry gone, at exit 0.

The finding called this data loss; it is also a disclosure. sync push extracts
the target file and sends each value to the TMS, so the swallowed line leaves the
machine under an unrelated key's name: under control the push body for greeting
was `Halloapi_key=SECRET_VALUE`, api_key was never pushed at all, and 2 keys went
out where the file had 3. The same misread hits a hand-written source on its very
first read, so a legitimate `path=C:\\` was enough on its own.

Both continuation tests (extract and reconstruct) now count the trailing
backslash run and continue only on an odd count, which is the rule escapeValue
was already writing for. Round-trip is verified for x\, \, a\b\, C:\ and a\\b;
the first four all previously ate the next entry.

Refs cli-8kr2.41
---
 CHANGELOG.md                                  |  2 +
 docs/SYNC.md                                  |  2 +-
 src/formats/properties.ts                     | 19 +++-
 ...roperties-continuation.integration.test.ts | 99 +++++++++++++++++++
 tests/unit/formats/properties.test.ts         | 63 ++++++++++++
 5 files changed, 182 insertions(+), 3 deletions(-)
 create mode 100644 tests/integration/sync-properties-continuation.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b59faf67..15727411 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -127,6 +127,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **formats**: **a `.properties` value ending in a backslash no longer deletes the entry after it.** `escapeValue` correctly writes a literal trailing backslash as `\\`, but the reader's continuation test was `line.endsWith('\\')` with no parity check, so it read that escape as "this line continues", consumed the following line and appended its raw text to the previous value. Measured: a source of `greeting=Hello` / `api_key=SECRET_VALUE` / `footer=Bye` with `greeting` translated to `Hallo\` was written as `greeting=Hallo\\`, and re-extracted as `[{greeting: "Hallo api_key=SECRET_VALUE"}, {footer: "Bye"}]` — the middle entry **gone**, at exit 0. The finding called this data loss; it is also a disclosure. `sync push` extracts the target file and sends each value to the TMS, so the swallowed line left the machine under an unrelated key's name: measured, the push body for `greeting` was `Hallo api_key=SECRET_VALUE`, and `api_key` itself was never pushed at all — 2 keys sent where the file had 3. The same misread hits a *hand-written* source on its very first read, so a legitimate Windows path such as `path=C:\\` was enough on its own. Both continuation tests (extract and reconstruct) now count the trailing backslash run and continue only on an odd count, which is the rule `escapeValue` was already writing for. Round-trip is now verified for the values `x\`, `\`, `a\b\`, `C:\` and `a\\b`; the first four all previously ate the next entry.
+
 - **translate**: **`deepl translate <file.json|.yaml>` now has a size ceiling, so a huge locale file cannot exhaust memory mid-run.** The structured-file route read and fully parsed whatever it was given, while both sibling routes of the same command were already bounded — text at 100 KiB, documents at 30 MB (`MAX_DOCUMENT_FILE_SIZE`) — and `deepl sync` skips anything over `sync.limits.max_file_bytes`. Measured peak RSS against a dead endpoint, so only parse and extract are counted: 4.7 MB → 129 MB, 19.2 MB → 251 MB, 80.9 MB → 684 MB, 163.8 MB → 1178 MB, linear and unbounded. The finding did not name the multiplier: the multi-target path parses a **fresh copy per target language**, up to `MULTI_TARGET_CONCURRENCY` (5) at once, so the same 19.2 MB file peaked at 252 MB for `--to de` and **483 MB** for `--to de,fr,es,it,nl`. The ceiling is 10 MiB, matching `HARD_MAX_SYNC_LIMITS.max_file_bytes` — the value `sync` refuses to be configured above — so nothing sync can be made to accept is refused here, and the worst case stays a few hundred MB rather than gigabytes. The check is a `fs.stat` before the read, at the one function both entry points funnel through, so an oversize file is never resident: the 163.8 MB fixture now exits 6 in 0.17 s at 86 MB RSS instead of 7.8 s at 1178 MB. The message names the file, its size and the limit, and points at `deepl sync` for anything larger; a directory run fails only that file and keeps its per-file reason in the summary. A document at 25 MB is still accepted, deliberately — it is streamed to the API rather than parsed.
 
 - **sync**: **`sync pull` no longer writes source-language text into a target locale file, and no longer replaces a local translation without saying so.** The merge that applies a pull response read `pulledKeys[key] ?? existingTarget.get(key) ?? entry.value`, so a key the TMS export omits **and** the target file lacks was filled in with the source string. Measured against a mock TMS whose `de` export carried only `greeting`: a source file holding `greeting`/`farewell`/`brand_new` and a `locales/de.json` holding the first two produced a German file containing `"brand_new": "Only in source"` — English, indistinguishable from a translation to anything reading the file — at **exit 0**, with the one-line summary `Pulled 1 translations from TMS`. The final `?? entry.value` is gone; a key with a value on neither side is now omitted from the entry list, which is what `reconstruct` needs to leave it out of the file, and matches what the locale translator already does for a key it could not translate (it pushes nothing rather than the source). An empty string is a translation and is still preserved. The same change fixes the case the finding did not name: when the target file does not exist yet, the source file is used as the reconstruction template, so **every** untranslated key was written into the new locale as English; only the keys the export actually carries are written now. Separately, the pulled value has always won over the local one and always will — neither side of the documented export contract carries a timestamp, so "which is newer" is not a question that can be answered, and pull exists to bring the reviewed copy in — but the overwrite was completely silent. Pull now counts the existing local translations it replaced and names the count (`Replaced 1 existing local translation with the TMS version. Use --dry-run to preview a pull before it overwrites local edits.`), with `--verbose` naming each key and file. See Added for the preview mode.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 711475a6..5353d33c 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -87,7 +87,7 @@ All parsers preserve format-specific metadata:
 - **ARB**: `@key` metadata (description, placeholders, type)
 - **XLIFF**: `<note>` elements, state attributes, translation units
 - **TOML**: `#` comments, blank lines between sections, key order within a section, per-value quote style (double-quoted vs literal single-quoted), irregular whitespace around `=`, and every byte outside a replaced string literal round-trip verbatim via span-surgical reconstruct. Multi-line triple-quoted strings are passed through as-is (not translated).
-- **Properties**: comments, Unicode escapes (`\uXXXX`), line continuations, separator style
+- **Properties**: comments, Unicode escapes (`\uXXXX`), line continuations, separator style. A trailing backslash continues the line only when the run of backslashes ending it is odd, so a value ending in a literal `\` (written as `\\`) round-trips instead of swallowing the next entry.
 - **Laravel PHP arrays**: PHPDoc/line/block comments, quote style (single vs double), trailing commas, irregular whitespace, and every byte outside a replaced string literal round-trip verbatim. Span-surgical reconstruct — the AST is used for string-literal offsets only, never reprinted. Allowlist rejects double-quoted interpolation (`"Hello $name"`), heredoc, nowdoc, and string concatenation; Laravel pipe-pluralization values (`|{n}` / `|[n,m]` / `|[n,*]`) are excluded from the translation batch and counted separately in `deepl sync status`.
 
 The sync engine also supports **multi-locale formats** where all locales are stored in a single file (e.g., Apple `.xcstrings`). For these formats, the engine automatically serializes locale writes to prevent race conditions and passes the locale to the parser so it can scope extract/reconstruct operations to the correct locale section.
diff --git a/src/formats/properties.ts b/src/formats/properties.ts
index fc77adf2..369a3a71 100644
--- a/src/formats/properties.ts
+++ b/src/formats/properties.ts
@@ -8,6 +8,21 @@ import { PendingCommentBuffer } from './pending-comment-buffer.js';
 const ENTRY_RE = /^([^=:#!\s][^=:]*?)\s*[=:]\s*(.*)/;
 const COMMENT_RE = /^\s*[#!]/;
 
+/**
+ * A trailing backslash continues the line only when the run of backslashes
+ * ending it is odd; an even run is one or more escaped literal backslashes,
+ * which is exactly what escapeValue emits for a value ending in `\`. Testing
+ * `endsWith('\\')` instead consumed the following entry and appended its raw
+ * `key=value` text to the previous value.
+ */
+function continuesOnNextLine(line: string): boolean {
+  let backslashes = 0;
+  for (let i = line.length - 1; i >= 0 && line[i] === '\\'; i--) {
+    backslashes++;
+  }
+  return backslashes % 2 === 1;
+}
+
 export class PropertiesFormatParser implements FormatParser {
   readonly name = 'Java Properties';
   readonly configKey = 'properties';
@@ -33,7 +48,7 @@ export class PropertiesFormatParser implements FormatParser {
       }
 
       // Handle line continuations (trailing backslash)
-      while (line.endsWith('\\') && i + 1 < lines.length) {
+      while (continuesOnNextLine(line) && i + 1 < lines.length) {
         i++;
         line = line.slice(0, -1) + lines[i]!.trimStart();
       }
@@ -80,7 +95,7 @@ export class PropertiesFormatParser implements FormatParser {
 
       // Handle line continuations
       const startLine = i;
-      while (line.endsWith('\\') && i + 1 < lines.length) {
+      while (continuesOnNextLine(line) && i + 1 < lines.length) {
         i++;
         line = line.slice(0, -1) + lines[i]!.trimStart();
       }
diff --git a/tests/integration/sync-properties-continuation.integration.test.ts b/tests/integration/sync-properties-continuation.integration.test.ts
new file mode 100644
index 00000000..18a1d909
--- /dev/null
+++ b/tests/integration/sync-properties-continuation.integration.test.ts
@@ -0,0 +1,99 @@
+/**
+ * Integration test for a `.properties` value ending in a backslash.
+ *
+ * `escapeValue` writes a literal trailing backslash as `\\`, which the reader's
+ * continuation test read as "this line continues": the next entry was consumed
+ * and its raw `key=value` text appended to the previous value. `sync push`
+ * extracts the target file and sends each value to the TMS, so the swallowed
+ * line's contents — key name included — left the machine as the translation of
+ * the preceding key, and the swallowed key was never pushed at all.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { createTmsClient } from '../../src/sync/tms-client';
+import { pushTranslations } from '../../src/sync/sync-tms';
+import { loadSyncConfig } from '../../src/sync/sync-config';
+
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import {
+  TMS_BASE,
+  TMS_PROJECT,
+  tmsConfig,
+  approvedTmsTrust,
+} from '../helpers/tms-nock';
+
+function write(dir: string, relPath: string, content: string): void {
+  const abs = path.join(dir, relPath);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, 'utf-8');
+}
+
+describe('sync push with a .properties value ending in a backslash', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+  let envSnapshot: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    envSnapshot = { ...process.env };
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-props-'));
+    harness = createSyncHarness({ parsers: ['properties'] });
+    process.env['TMS_API_KEY'] = 'env-key';
+    delete process.env['TMS_TOKEN'];
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+    process.env = envSnapshot;
+  });
+
+  it('pushes every key, and no key carries its neighbour raw text', async () => {
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['de'],
+      tms: tmsConfig(),
+      buckets: { properties: { include: ['locales/messages_en.properties'] } },
+    });
+    write(
+      tmpDir,
+      'locales/messages_en.properties',
+      'greeting=Hello\napi_key=SECRET_VALUE\nfooter=Bye\n'
+    );
+    // As `escapeValue` would have written it: `Hallo\` escaped to `Hallo\\`.
+    write(
+      tmpDir,
+      'locales/messages_de.properties',
+      'greeting=Hallo\\\\\napi_key=SECRET_VALUE\nfooter=Tschuess\n'
+    );
+
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+    const sent: Record<string, string> = {};
+    nock(TMS_BASE)
+      .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
+      .times(3)
+      .reply(200, function reply(uri: string, body: unknown) {
+        const key = decodeURIComponent(uri.split('/keys/')[1]!);
+        sent[key] = (body as { value: string }).value;
+        return {};
+      });
+
+    const result = await pushTranslations(config, client, harness.registry);
+
+    expect(result.pushed).toBe(3);
+    expect(Object.keys(sent).sort()).toEqual(['api_key', 'footer', 'greeting']);
+    expect(sent['greeting']).toBe('Hallo\\');
+    expect(sent['greeting']).not.toContain('SECRET_VALUE');
+    expect(sent['api_key']).toBe('SECRET_VALUE');
+  });
+});
diff --git a/tests/unit/formats/properties.test.ts b/tests/unit/formats/properties.test.ts
index aea49fcb..eb2b1c55 100644
--- a/tests/unit/formats/properties.test.ts
+++ b/tests/unit/formats/properties.test.ts
@@ -295,6 +295,69 @@ describe('PropertiesFormatParser', () => {
     });
   });
 
+  describe('escaped trailing backslash is not a line continuation', () => {
+    // The writer escapes a literal trailing backslash as `\\`, which the
+    // continuation test read as "this line continues" — swallowing the next
+    // entry and appending its raw `key=value` text to the previous value.
+    it('should not treat an even-length trailing backslash run as a continuation', () => {
+      const entries = parser.extract('greeting=Hallo\\\\\nnext=KEEPME\n');
+
+      expect(entries.map((e) => e.key)).toEqual(['greeting', 'next']);
+      expect(entries[0]!.value).toBe('Hallo\\');
+      expect(entries[1]!.value).toBe('KEEPME');
+    });
+
+    it('should still honour an odd-length trailing backslash run', () => {
+      const entries = parser.extract('greeting=Hallo\\\\\\\n  more\n');
+
+      expect(entries).toHaveLength(1);
+      expect(entries[0]!.value).toBe('Hallo\\more');
+    });
+
+    it('should still honour a single trailing backslash', () => {
+      const entries = parser.extract('greeting=Hallo\\\n  world\n');
+
+      expect(entries).toHaveLength(1);
+      expect(entries[0]!.value).toBe('Halloworld');
+    });
+
+    it.each([
+      ['x\\', 'x\\'],
+      ['\\', '\\'],
+      ['a\\b\\', 'a\\b\\'],
+      ['C:\\', 'C:\\'],
+      ['a\\\\b', 'a\\\\b'],
+    ])(
+      'should round-trip the value %j through reconstruct and back',
+      (value, expected) => {
+        const source = 'k=placeholder\nnext=KEEPME\n';
+        const written = parser.reconstruct(source, [
+          { key: 'k', value: 'placeholder', translation: value },
+          { key: 'next', value: 'KEEPME', translation: 'KEEPME' },
+        ]);
+        const back = parser.extract(written);
+
+        expect(back.find((e) => e.key === 'k')!.value).toBe(expected);
+        expect(back.find((e) => e.key === 'next')).toBeDefined();
+      }
+    );
+
+    it('should not swallow the following entry during reconstruct either', () => {
+      const source = 'greeting=Hello\napi_key=SECRET_VALUE\nfooter=Bye\n';
+      const written = parser.reconstruct(source, [
+        { key: 'greeting', value: 'Hello', translation: 'Hallo\\' },
+        { key: 'api_key', value: 'SECRET_VALUE', translation: 'SECRET_VALUE' },
+        { key: 'footer', value: 'Bye', translation: 'Bye' },
+      ]);
+
+      expect(written).toContain('api_key=SECRET_VALUE');
+      const back = parser.extract(written);
+      expect(back.map((e) => e.key)).toEqual(['greeting', 'api_key', 'footer']);
+      expect(back[0]!.value).toBe('Hallo\\');
+      expect(back[0]!.value).not.toContain('SECRET_VALUE');
+    });
+  });
+
   describe('escapeValue()', () => {
     it('should escape \\r in output', () => {
       const content = 'key=Hello\n';

From 81a962445e110b8ff8594b535f736a03cce28a9a Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 11:56:02 +0200
Subject: [PATCH 157/256] fix(formats): stop six writers emitting raw C0
 control bytes into repo files

toml, properties, ios-strings, po, android-xml and xliff escaped only their own
quoting characters plus \n, \r and \t, so any other control byte in a
translation went out untouched. json, yaml and arb were already clean because
they delegate to JSON.stringify and the yaml emitter.

No API call is needed to trigger it. A contributor commits a VALID
locales/app.de.toml holding greeting = "Hola\u001B[2J" -- smol-toml decodes the
escape to a raw ESC. The key is then current, so it is never translated and
never screened: the locale translator carries the existing target value forward
and the writer put the byte back out raw. TOML then refuses its own output
("control characters are not allowed in strings").

The bead said every later run fails. Measured, it is quieter and worse: `sync`
exits 0 and says nothing, because the target-file read sits in a catch that
treats a parse failure as "no existing translations"; `sync status` exits 0
reporting `de [####] 100% (0 missing, 0 outdated)` for a file it cannot parse;
only `sync validate` fails, at the untyped exit 1. The file is also only
rewritten when a SIBLING key changes -- an all-current run does not rewrite it,
so the bead's trigger needs that extra step.

Android XML and XLIFF are worse: every C0 byte except tab, LF and CR is outside
XML 1.0's Char production, so there is no escape and no numeric character
reference. expat rejects both written files as "not well-formed (invalid
token)", which means aapt2 and conforming CAT tools do too.

One shared rule now lives in src/formats/util/control-chars.ts and each writer
applies it as its own format allows: TOML escapes \uXXXX, promotes a literal
string to the double-quoted form, and also escapes U+007F (verified rejected raw
by smol-toml); properties extends its existing \uXXXX rule below U+0020;
ios-strings emits \UXXXX, which its own reader already decodes; po gains the
missing \r escape and refuses the rest; android-xml and xliff refuse. A refusal
is a ValidationError naming the resource or entry plus the codepoint, matching
the assertNoCdata stance both XML parsers already take.

Refs cli-8kr2.42
---
 CHANGELOG.md                                 |   2 +
 docs/SYNC.md                                 |  15 ++
 src/formats/android-xml.ts                   |  30 ++-
 src/formats/ios-strings.ts                   |   8 +-
 src/formats/po.ts                            |  31 +++
 src/formats/properties.ts                    |   9 +-
 src/formats/toml.ts                          |  28 ++-
 src/formats/util/control-chars.ts            |  56 +++++
 src/formats/xliff.ts                         |  24 ++
 tests/e2e/cli-sync-control-chars.e2e.test.ts | 135 +++++++++++
 tests/unit/formats/control-chars.test.ts     | 221 +++++++++++++++++++
 11 files changed, 551 insertions(+), 8 deletions(-)
 create mode 100644 src/formats/util/control-chars.ts
 create mode 100644 tests/e2e/cli-sync-control-chars.e2e.test.ts
 create mode 100644 tests/unit/formats/control-chars.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 15727411..66d4e68d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -422,6 +422,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **formats**: **no writer emits a raw C0 control byte into a repo file any more.** Six of the nine writers escaped only their own quoting characters plus `\n`/`\r`/`\t`, so any other control byte in a translation was written through untouched; JSON, YAML and ARB were already clean because they delegate to `JSON.stringify` and the YAML emitter. That put live terminal-control sequences into source-controlled files, where `git diff`, `cat`, `less` and CI log viewers all render them — with no CLI output path involved. **No API call is needed to trigger it.** A contributor commits a *valid* `locales/app.de.toml` holding `greeting = "Hola\u001B[2J"` (TOML basic strings legally carry `\uXXXX`, and smol-toml decodes it to a raw ESC). The key is then `current`, so it is never translated and never validated: the locale translator carries the existing target value forward and the writer put the byte back out raw. Measured through the real CLI: the rewritten file contained `greeting = "Hola␛[2J"`, and `TomlFormatParser.extract` then refuses it — `Invalid TOML document: control characters are not allowed in strings`. The finding said every later run fails; **measured, it is quieter and worse than that.** `deepl sync` exits 0 and says nothing, because the target-file read is inside a catch that treats a parse failure as "no existing translations", so the file's translations simply stop being visible to sync. `deepl sync status` exits 0 reporting **`de [####] 100% (0 missing, 0 outdated)`** for a file it cannot parse. Only `deepl sync validate` fails, at the untyped exit 1. Android XML and XLIFF are worse still: every C0 byte except tab, LF and CR is outside XML 1.0's `Char` production, so there is no escape and no numeric character reference for it — expat rejects both written files as `not well-formed (invalid token)`, which means `aapt2` and every conforming CAT tool reject them too. One shared rule now lives in `src/formats/util/control-chars.ts`, and each writer applies it the way its own format allows: TOML escapes as `\uXXXX` (and forces the double-quoted form for a value a literal string could not escape, plus U+007F, which smol-toml also rejects raw — verified against the library); `.properties` extends its existing `\uXXXX` rule below U+0020; iOS Strings emits `\UXXXX`, which its own reader already decodes; PO gains the missing `\r` escape and refuses the rest with a `ValidationError` naming the entry, since its escape set cannot spell them and `unquote` could not read them back; Android XML and XLIFF refuse with a `ValidationError` naming the resource or trans-unit, matching the stance both already take on CDATA. Each message names the codepoint (`U+001B`) rather than quoting a byte that prints as nothing.
+
 - **sync**: **a source catalog can no longer smuggle one string into another string's key.** Five parsers encode hierarchical key identity in-band with no escaping: PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.`. A key component holding the separator therefore resolved to the same key as an unrelated entry, and the two control bytes **print as nothing**, so the source diff showed an ordinary string. Measured: a PO catalog carrying `msgid "menu␄Save"` beside a normal `msgctxt "menu" / msgid "Save"` pair extracted two entries with the identical key `menu␄Save`, and reconstruct wrote the smuggled entry's translation into the legitimate pair's `msgstr` — the attacker picks the source text, DeepL translates it, and the result lands in the victim key's slot in **every** locale. **The stronger case needs no collision at all**: one smuggled `msgid "menu␄Save"` in a catalog with no `msgctxt` anywhere produced `msgctxt "menu"` / `msgid "Save"` / `msgstr "ATTACKER-TEXT"` in every target `.po`, forging a context-qualified entry the source never had — so a duplicate-key check alone would have missed it. YAML behaves the same way: a source key `"a\0b"` became a genuine nested `a: { b: ATTACKER-TEXT }` via `doc.setIn`. For the `.` formats the damage is a lost or corrupt file rather than a forgery: `{"a.b":"FLAT","a":{"b":"NESTED"}}` rewrote both slots to one translation and dropped the flat key's own; the Android `<string name="items.0">` colliding with `<string-array name="items">` was **deleted** from the output; and the Laravel case emitted PHP the CLI's own parser then refuses — the repo's `11-dot-key-vs-nested.php` fixture reconstructs to `'b' => 'PWNED<NESTED>'LAT>',`, failing to re-read with `syntax error, unexpected 'LAT' (T_STRING), expecting ']'`, because `collectStringLocs` maps a key to one source offset and the two replacements splice over each other. Each parser now refuses the file: PO and YAML reject the reserved byte at both key-construction sites (extract and the target-file read inside reconstruct), quoting it back escaped as `\u0004` / `\u0000` rather than echoing a byte that prints as nothing; JSON, Laravel PHP and Android XML assert their extract output has distinct keys, which for those three is exactly equivalent to detecting a separator collision because their containers already guarantee distinct sibling keys. `sync` skips the one file with a warning naming the colliding key and finishes the rest of the run at exit 0, following the existing `FormatDepthExceededError` and `max_entries_per_file` convention — one hostile file must not discard the lockfile for work already translated, billed and written. `.properties` and XLIFF are deliberately excluded: a literally repeated key is legal in both (Java `Properties.load` is last-wins), so a blanket duplicate check would have rejected files that work today. `sync pull` reading a **target** file whose keys collide leaves it untouched and records a `key_collision` skip, rather than falling through to the source template — measured, that fallback would have rebuilt `locales/de.json` from source down to the single key the export carried, discarding a hand-written translation.
 
 - **translate**: **a document upload response can no longer choose where this client sends its own follow-up requests.** The `document_id` from `POST /v2/document` was interpolated into `POST /v2/document/{id}` and `POST /v2/document/{id}/result` with no encoding and no format check, and the endpoint supplying it is redirectable via `--api-url`, `api.baseUrl` or a proxy. Measured against a stub answering `document_id: '../../v3/glossaries%3fpwned=1'`, the client's next two request lines arrived as `POST /v3/glossaries%3fpwned=1` and `POST /v3/glossaries%3fpwned=1/result` — the traversal collapsed exactly as crafted, on a completely different route from `/v2/document/{id}` — and the run finished at **exit 0** reporting `Translated report.pdf -> out.pdf` after writing the stub's JSON body into the output file as if it were a translated PDF. `document_id` is now checked against `[A-Za-z0-9_-]+` at both interpolation sites, so a redirected first response stops the workflow at exit 5 (`NetworkError`, since nothing the user typed is wrong) with the ID quoted back, nothing further sent, and no output file written. A response with no `document_id` at all was reaching the wire as the literal path `/v2/document/undefined`; that is refused by the same check. This was the last unguarded interpolation of an untrusted value into a URL path in the API layer — `GlossaryClient` validates its ID at all 7 sites and `StyleRulesClient` encodes at all 8, and the document client was the one exception among the ten clients. The polling loop was also checked: it re-sends the original handle rather than the `document_id` echoed by each status response, so a clean first response cannot be followed by a poisoned second one.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 5353d33c..14530478 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -92,6 +92,21 @@ All parsers preserve format-specific metadata:
 
 The sync engine also supports **multi-locale formats** where all locales are stored in a single file (e.g., Apple `.xcstrings`). For these formats, the engine automatically serializes locale writes to prevent race conditions and passes the locale to the parser so it can scope extract/reconstruct operations to the correct locale section.
 
+### Control characters in a translation
+
+No writer emits a raw C0 control byte. Tab, newline and carriage return are escaped or legally emitted as usual; every other byte below U+0020 is either escaped or refused, because written raw it would survive into git — where `git diff`, `cat`, `less` and CI log viewers render an ESC sequence as a live terminal command — and because two of the formats cannot read it back:
+
+| Format | Behaviour |
+|--------|-----------|
+| JSON, YAML, ARB, Xcode String Catalog | Escaped by the underlying emitter |
+| TOML | Escaped as `\uXXXX`; a literal (single-quoted) string is promoted to the double-quoted form, which is the only one with an escape. U+007F is escaped too — TOML rejects it raw |
+| Java Properties | Escaped as `\uXXXX`, extending the existing rule for non-ASCII |
+| iOS Strings | Escaped as `\UXXXX` |
+| Gettext PO | `\r` escaped; anything else in C0 is refused, since the PO escape set cannot spell it |
+| Android XML, XLIFF | Refused. XML 1.0 has no escape and no numeric character reference for these bytes, so the file would stop being well-formed and `aapt2` or a CAT tool would reject it |
+
+A refusal is a `ValidationError` naming the resource or entry and the codepoint (`U+001B`) — never the byte itself, which prints as nothing.
+
 ### Key separators and colliding keys
 
 Every parser reduces a string's position in the file to a flat key, using a separator the format does not otherwise carry: PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.`. A key component containing that separator makes two different strings share one key, and there is no correct way to write them back — one translation lands in the other's slot.
diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index 20e7b507..721b4d0c 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -5,6 +5,10 @@ import {
   type TranslatedEntry,
 } from './format.js';
 import { ValidationError } from '../utils/errors.js';
+import {
+  describeControlChar,
+  findForbiddenControlChar,
+} from './util/control-chars.js';
 import {
   replaceElements,
   scanElements,
@@ -138,6 +142,24 @@ function escapeAndroid(value: string): string {
  * Fail fast rather than rewrite the value into something the round-trip
  * cannot reproduce, matching the XLIFF parser's stance on CDATA.
  */
+/**
+ * Refuse a value XML 1.0 cannot carry. Every C0 byte except tab, LF and CR is
+ * outside the `Char` production, so there is no escape and no numeric character
+ * reference for it: written raw the file stops being well-formed and aapt2
+ * rejects the resource. Fail fast naming the resource, matching this parser's
+ * existing stance on a CDATA breakout.
+ */
+function assertNoControlChars(name: string, value: string): void {
+  const found = findForbiddenControlChar(value);
+  if (found !== undefined) {
+    throw new ValidationError(
+      `Android resource "${name}" would contain ${describeControlChar(found)}, ` +
+        `which XML 1.0 cannot represent in any form.`,
+      'Remove the control character from the translation, or from the source string it came from.'
+    );
+  }
+}
+
 function assertNoCdataBreakout(value: string): void {
   if (value.includes(']]>')) {
     throw new ValidationError(
@@ -212,7 +234,7 @@ export class AndroidXmlFormatParser implements FormatParser {
       }
       return this.rewriteInner(
         el,
-        this.escapeForReconstruct(el.inner, translation)
+        this.escapeForReconstruct(el.groups[0]!, el.inner, translation)
       );
     });
 
@@ -228,7 +250,7 @@ export class AndroidXmlFormatParser implements FormatParser {
         }
         return this.rewriteInner(
           item,
-          this.escapeForReconstruct(item.inner, translation)
+          this.escapeForReconstruct(el.groups[0]!, item.inner, translation)
         );
       });
       return this.rewriteInner(el, inner);
@@ -248,7 +270,7 @@ export class AndroidXmlFormatParser implements FormatParser {
         }
         return this.rewriteInner(
           item,
-          this.escapeForReconstruct(item.inner, translation)
+          this.escapeForReconstruct(el.groups[0]!, item.inner, translation)
         );
       });
       return this.rewriteInner(el, inner);
@@ -324,9 +346,11 @@ export class AndroidXmlFormatParser implements FormatParser {
   }
 
   private escapeForReconstruct(
+    name: string,
     originalInner: string,
     translation: string
   ): string {
+    assertNoControlChars(name, translation);
     if (originalInner.startsWith('<![CDATA[')) {
       assertNoCdataBreakout(translation);
       return `<![CDATA[${translation}]]>`;
diff --git a/src/formats/ios-strings.ts b/src/formats/ios-strings.ts
index bf3fc5bc..c7d2f33e 100644
--- a/src/formats/ios-strings.ts
+++ b/src/formats/ios-strings.ts
@@ -3,6 +3,7 @@ import type {
   FormatParser,
   TranslatedEntry,
 } from './format.js';
+import { isForbiddenControlChar } from './util/control-chars.js';
 
 const ENTRY_RE = /^\s*"((?:[^"\\]|\\.)*)"\s*=\s*"((?:[^"\\]|\\.)*)"\s*;\s*$/;
 
@@ -211,7 +212,12 @@ export class IosStringsFormatParser implements FormatParser {
           result += '\\0';
           break;
         default:
-          result += ch;
+          // `\UXXXX`, which unescape() already decodes, for the remaining C0
+          // controls: written raw they survive into git, where a `git diff` or
+          // a CI log viewer renders an ESC sequence as a live terminal command.
+          result += isForbiddenControlChar(ch.charCodeAt(0))
+            ? '\\U' + ch.charCodeAt(0).toString(16).padStart(4, '0')
+            : ch;
           break;
       }
     }
diff --git a/src/formats/po.ts b/src/formats/po.ts
index e5df83fc..5f4c08fe 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -5,6 +5,11 @@ import {
   type FormatParser,
   type TranslatedEntry,
 } from './format.js';
+import {
+  describeControlChar,
+  findForbiddenControlChar,
+} from './util/control-chars.js';
+import { ValidationError } from '../utils/errors.js';
 
 interface PoEntry {
   translatorComments: string[];
@@ -52,6 +57,7 @@ function quote(value: string): string {
       .replace(/\\/g, '\\\\')
       .replace(/"/g, '\\"')
       .replace(/\n/g, '\\n')
+      .replace(/\r/g, '\\r')
       .replace(/\t/g, '\\t') +
     '"'
   );
@@ -62,6 +68,7 @@ function quoteLong(value: string): string {
     .replace(/\\/g, '\\\\')
     .replace(/"/g, '\\"')
     .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
     .replace(/\t/g, '\\t');
 
   if (escaped.length <= 74) return `"${escaped}"`;
@@ -109,6 +116,24 @@ function assertNoContextSeparator(field: string, value: string): void {
   }
 }
 
+/**
+ * Refuse a translation carrying a control byte the PO escape set cannot spell.
+ * `\n`, `\r` and `\t` are escaped above; everything else in C0 has no escape
+ * this parser's own `unquote` understands, so writing it would put a live
+ * terminal-control sequence into a committed catalog that no later read could
+ * recover as text.
+ */
+function assertNoControlChars(key: string, value: string): void {
+  const found = findForbiddenControlChar(value);
+  if (found !== undefined) {
+    throw new ValidationError(
+      `PO entry "${describeKeyPath(key)}" would contain ` +
+        `${describeControlChar(found)}, which the PO escape set cannot represent.`,
+      'Remove the control character from the translation, or from the source string it came from.'
+    );
+  }
+}
+
 function makeKey(entry: PoEntry): string {
   assertNoContextSeparator('msgid', entry.msgid);
   if (entry.msgctxt !== undefined) {
@@ -338,6 +363,12 @@ export class PoFormatParser implements FormatParser {
   reconstruct(content: string, entries: TranslatedEntry[]): string {
     const translationMap = new Map<string, TranslatedEntry>();
     for (const entry of entries) {
+      assertNoControlChars(entry.key, entry.translation);
+      const plurals = entry.metadata?.['plural_forms'] as
+        Record<string, string> | undefined;
+      for (const form of Object.values(plurals ?? {})) {
+        assertNoControlChars(entry.key, form);
+      }
       translationMap.set(entry.key, entry);
     }
 
diff --git a/src/formats/properties.ts b/src/formats/properties.ts
index 369a3a71..cb74193a 100644
--- a/src/formats/properties.ts
+++ b/src/formats/properties.ts
@@ -4,6 +4,7 @@ import type {
   TranslatedEntry,
 } from './format.js';
 import { PendingCommentBuffer } from './pending-comment-buffer.js';
+import { isForbiddenControlChar } from './util/control-chars.js';
 
 const ENTRY_RE = /^([^=:#!\s][^=:]*?)\s*[=:]\s*(.*)/;
 const COMMENT_RE = /^\s*[#!]/;
@@ -215,7 +216,13 @@ export class PropertiesFormatParser implements FormatParser {
           result += '\\\\';
           break;
         default: {
-          if (ch.codePointAt(0)! > 0x7e) {
+          // `\uXXXX` also carries the C0 controls the earlier cases do not:
+          // written raw they survive into git, where a `git diff` or a CI log
+          // viewer renders an ESC sequence as a live terminal command.
+          if (
+            ch.codePointAt(0)! > 0x7e ||
+            isForbiddenControlChar(ch.codePointAt(0)!)
+          ) {
             // Emit every UTF-16 code unit: an astral character such as an
             // emoji is a surrogate pair, and writing only charCodeAt(0)
             // leaves a lone high surrogate that cannot be decoded back.
diff --git a/src/formats/toml.ts b/src/formats/toml.ts
index 677c9d57..47e53b25 100644
--- a/src/formats/toml.ts
+++ b/src/formats/toml.ts
@@ -5,6 +5,10 @@ import type {
   TranslatedEntry,
 } from './format.js';
 import { PendingCommentBuffer } from './pending-comment-buffer.js';
+import {
+  escapeControlChars,
+  findForbiddenControlChar,
+} from './util/control-chars.js';
 
 // `[section]` or `[a.b.c]` — captures the path. Matches only at the start of a
 // trimmed line; trailing whitespace and a `# comment` tail are allowed.
@@ -262,13 +266,29 @@ export class TomlFormatParser implements FormatParser {
   }
 }
 
+/** TOML rejects a raw U+007F in a string as well as the shared C0 set. */
+function isTomlDelete(code: number): boolean {
+  return code === 0x7f;
+}
+
+function tomlUnicodeEscape(code: number): string {
+  return '\\u' + code.toString(16).padStart(4, '0');
+}
+
 function encodeTomlString(value: string, useDoubleQuote: boolean): string {
   if (!useDoubleQuote) {
     // Literal strings (single-quoted) are raw — no escapes, cannot contain `'`
     // or a newline. U+2028/U+2029 also force the double-quoted fallback: left
     // raw they break ENTRY_LINE_RE on the next pass (JS `.` excludes line
-    // separators), so the key is re-appended as a duplicate.
-    if (value.includes("'") || /[\n\r\u2028\u2029]/.test(value)) {
+    // separators), so the key is re-appended as a duplicate. A control
+    // character forces it for a blunter reason: a literal string has no escape
+    // for one, and smol-toml then refuses its own output on the next read.
+    if (
+      value.includes("'") ||
+      /[\n\r\u2028\u2029]/.test(value) ||
+      findForbiddenControlChar(value) !== undefined ||
+      value.includes('\u{7f}')
+    ) {
       return encodeTomlString(value, true);
     }
     return `'${value}'`;
@@ -285,5 +305,7 @@ function encodeTomlString(value: string, useDoubleQuote: boolean): string {
     .replace(/\t/g, '\\t')
     .replace(/\u2028/g, '\\u2028')
     .replace(/\u2029/g, '\\u2029');
-  return `"${escaped}"`;
+  // Applied last, so the backslashes it introduces are not doubled by the chain
+  // above.
+  return `"${escapeControlChars(escaped, tomlUnicodeEscape, isTomlDelete)}"`;
 }
diff --git a/src/formats/util/control-chars.ts b/src/formats/util/control-chars.ts
new file mode 100644
index 00000000..f859fbe0
--- /dev/null
+++ b/src/formats/util/control-chars.ts
@@ -0,0 +1,56 @@
+/**
+ * Shared rule for control characters a locale file must not carry raw.
+ *
+ * Tab, LF and CR are excluded: every writer already escapes or legally emits
+ * them, and they are the three C0 bytes XML 1.0 and gettext both accept. The
+ * rest are never legitimate in a translation. Written raw they reach git, where
+ * `git diff`, `cat`, `less` and a CI log viewer render an ESC sequence as a live
+ * terminal command; TOML rejects its own output on the next read; and XML 1.0
+ * cannot represent them at all, not even as a numeric character reference.
+ *
+ * Writers that have an escape for them use {@link escapeControlChars}; the two
+ * XML formats, which do not, use {@link findForbiddenControlChar} to refuse the
+ * value instead.
+ */
+export function isForbiddenControlChar(code: number): boolean {
+  return code < 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d;
+}
+
+/** The first forbidden control character in `value`, or `undefined`. */
+export function findForbiddenControlChar(value: string): string | undefined {
+  for (const ch of value) {
+    if (isForbiddenControlChar(ch.codePointAt(0)!)) return ch;
+  }
+  return undefined;
+}
+
+/**
+ * Renders a control character as `U+001B`. A message must never quote the byte
+ * itself: it prints as nothing, so the reader would be shown the string they
+ * already believe they have.
+ */
+export function describeControlChar(char: string): string {
+  return (
+    'U+' + char.codePointAt(0)!.toString(16).toUpperCase().padStart(4, '0')
+  );
+}
+
+/**
+ * Replace every forbidden control character with `render(code)`, the escape
+ * syntax of the calling format. `alsoEscape` extends the set for a format whose
+ * own spec forbids more than the shared rule does — TOML also rejects a raw
+ * U+007F.
+ */
+export function escapeControlChars(
+  value: string,
+  render: (code: number) => string,
+  alsoEscape?: (code: number) => boolean
+): string {
+  let result = '';
+  for (const ch of value) {
+    const code = ch.codePointAt(0)!;
+    result +=
+      isForbiddenControlChar(code) || alsoEscape?.(code) ? render(code) : ch;
+  }
+  return result;
+}
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index 91b6d403..134ff680 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -4,6 +4,10 @@ import type {
   TranslatedEntry,
 } from './format.js';
 import { ValidationError } from '../utils/errors.js';
+import {
+  describeControlChar,
+  findForbiddenControlChar,
+} from './util/control-chars.js';
 import {
   findElement,
   replaceElements,
@@ -110,6 +114,24 @@ function assertNoCdataInTranslatable(content: string): void {
   }
 }
 
+/**
+ * Refuse a value XML 1.0 cannot carry. Every C0 byte except tab, LF and CR is
+ * outside the `Char` production, so there is no escape and no numeric character
+ * reference for it: written raw the file stops being well-formed and every
+ * conforming consumer rejects it. Fail fast naming the unit, the same stance
+ * this parser already takes on CDATA.
+ */
+function assertNoControlChars(id: string, value: string): void {
+  const found = findForbiddenControlChar(value);
+  if (found !== undefined) {
+    throw new ValidationError(
+      `XLIFF trans-unit "${id}" would contain ${describeControlChar(found)}, ` +
+        `which XML 1.0 cannot represent in any form.`,
+      'Remove the control character from the translation, or from the source string it came from.'
+    );
+  }
+}
+
 function escapeXml(value: string): string {
   return value
     .replace(/&/g, '&amp;')
@@ -239,6 +261,7 @@ export class XliffFormatParser implements FormatParser {
     const result = replaceElements(content, TRANS_UNIT_EL, (element) => {
       const translation = translations.get(element.groups[0]!);
       if (translation === undefined) return '';
+      assertNoControlChars(element.groups[0]!, translation);
       return rewriteInner(
         element,
         applyTarget(element.inner, escapeXml(translation))
@@ -254,6 +277,7 @@ export class XliffFormatParser implements FormatParser {
     const result = replaceElements(content, UNIT_EL, (element) => {
       const translation = translations.get(element.groups[0]!);
       if (translation === undefined) return '';
+      assertNoControlChars(element.groups[0]!, translation);
 
       const segment = findElement(element.inner, SEGMENT_EL);
       if (!segment) return element.text;
diff --git a/tests/e2e/cli-sync-control-chars.e2e.test.ts b/tests/e2e/cli-sync-control-chars.e2e.test.ts
new file mode 100644
index 00000000..4b7f45ba
--- /dev/null
+++ b/tests/e2e/cli-sync-control-chars.e2e.test.ts
@@ -0,0 +1,135 @@
+/**
+ * E2E regression for the TOML self-DoS in cli-8kr2.42.
+ *
+ * A contributor can commit a *valid* `locales/app.de.toml` holding
+ * `greeting = "Hola"` — TOML basic strings legally carry `\uXXXX`, and
+ * smol-toml decodes it to a raw ESC. On the next sync the key is `current`, so
+ * it is never translated and never validated: the locale translator carries the
+ * existing target value forward and the writer used to put the byte back out
+ * raw. smol-toml then refuses its own output — "control characters are not
+ * allowed in strings" — so that file never syncs again, including from the
+ * generated pre-commit hook.
+ *
+ * The file is only rewritten when something in it actually changes, so the run
+ * that triggers this is one where a *sibling* key is new.
+ */
+
+import { spawn, spawnSync, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const ESC = String.fromCharCode(0x1b);
+
+describe('CLI sync control-character containment', () => {
+  const testConfig = createTestConfigDir('e2e-sync-control-chars');
+  const testFiles = createTestDir('e2e-sync-control-chars-files');
+  let mockServer: ChildProcess;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'node',
+        [path.join(__dirname, 'mock-deepl-server.cjs')],
+        { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env } }
+      );
+      mockServer = child;
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = /PORT=(\d+)/.exec(output);
+        if (match) resolve(parseInt(match[1]!, 10));
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  function runSync(): { status: number | null; output: string } {
+    const { CI: _ci, DEEPL_API_KEY: _key, ...rest } = process.env;
+    const result = spawnSync('node', [CLI_PATH, 'sync', '--yes'], {
+      encoding: 'utf-8',
+      cwd: testFiles.path,
+      env: { ...rest, DEEPL_CONFIG_DIR: testConfig.path, NO_COLOR: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60000,
+    });
+    return {
+      status: result.status,
+      output: (result.stdout ?? '') + (result.stderr ?? ''),
+    };
+  }
+
+  const sourcePath = () => path.join(testFiles.path, 'locales', 'app.en.toml');
+  const targetPath = () => path.join(testFiles.path, 'locales', 'app.de.toml');
+
+  beforeAll(async () => {
+    const port = await startMockServer();
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+      })
+    );
+    fs.writeFileSync(
+      path.join(testFiles.path, '.deepl-sync.yaml'),
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - de',
+        'buckets:',
+        '  toml:',
+        '    include:',
+        '      - "locales/*.en.toml"',
+        '',
+      ].join('\n')
+    );
+    fs.mkdirSync(path.join(testFiles.path, 'locales'), { recursive: true });
+    fs.writeFileSync(sourcePath(), 'greeting = "Hello"\n');
+  }, 30000);
+
+  afterAll(() => {
+    if (mockServer) mockServer.kill('SIGTERM');
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  it('keeps the file parseable across the run that re-emits a hostile value', () => {
+    // Run 1: establish the lockfile so `greeting` becomes a `current` key.
+    expect(runSync().status).toBe(0);
+
+    // A contributor commits a valid TOML file whose escape decodes to a raw ESC,
+    // and adds a sibling key so the file must be rewritten next run.
+    fs.writeFileSync(targetPath(), 'greeting = "Hola\\u001B[2J"\n');
+    fs.appendFileSync(sourcePath(), 'added = "Translate me"\n');
+
+    const second = runSync();
+    expect(second.status).toBe(0);
+
+    const written = fs.readFileSync(targetPath(), 'utf-8');
+    expect(written).not.toContain(ESC);
+    expect(written).toContain('\\u001b');
+    expect(written).toContain('Traduceme');
+
+    // The whole point: the file still syncs. A raw ESC makes smol-toml reject
+    // it, so a third run would report a parse failure instead of `current`.
+    const third = runSync();
+    expect(third.status).toBe(0);
+    expect(third.output).not.toContain('control characters');
+    expect(fs.readFileSync(targetPath(), 'utf-8')).not.toContain(ESC);
+  }, 90000);
+});
diff --git a/tests/unit/formats/control-chars.test.ts b/tests/unit/formats/control-chars.test.ts
new file mode 100644
index 00000000..3d29f7c5
--- /dev/null
+++ b/tests/unit/formats/control-chars.test.ts
@@ -0,0 +1,221 @@
+/**
+ * Tests that no writer emits a raw C0 control byte into a repo file.
+ *
+ * A hostile contributor can commit a *valid* locale file carrying an escaped
+ * ESC sequence — TOML basic strings and Java `.properties` both decode `\uXXXX`
+ * to a raw byte. The key is then `current`, so it is never translated and never
+ * screened: the locale translator re-emits the existing target value verbatim
+ * and the writer puts the byte back out raw. TOML then refuses its own output,
+ * and quietly: `sync` swallows the parse failure as "no existing translations"
+ * and `sync status` reports the file 100% complete. Android XML and XLIFF output
+ * stops being well-formed XML, which `aapt2` and CAT tools reject. In every case
+ * a live terminal-control sequence lands in source control, where `git diff`,
+ * `cat`, `less` and CI log viewers render it.
+ */
+
+import { TomlFormatParser } from '../../../src/formats/toml';
+import { PropertiesFormatParser } from '../../../src/formats/properties';
+import { IosStringsFormatParser } from '../../../src/formats/ios-strings';
+import { PoFormatParser } from '../../../src/formats/po';
+import { AndroidXmlFormatParser } from '../../../src/formats/android-xml';
+import { XliffFormatParser } from '../../../src/formats/xliff';
+import type { FormatParser } from '../../../src/formats/format';
+import { ValidationError } from '../../../src/utils/errors';
+
+const ESC = String.fromCharCode(0x1b);
+const BEL = String.fromCharCode(0x07);
+const NUL = String.fromCharCode(0x00);
+const DEL = String.fromCharCode(0x7f);
+const CR = String.fromCharCode(0x0d);
+
+/** ESC [ 2 J clears the screen when a terminal renders the file. */
+const HOSTILE = `Hallo${ESC}[2J${BEL}${NUL}Welt`;
+
+function rawControlBytes(s: string): string[] {
+  return [
+    ...new Set(
+      [...s]
+        .filter((c) => {
+          const code = c.codePointAt(0)!;
+          return code < 0x20 && c !== '\n' && c !== '\t';
+        })
+        .map((c) => 'U+' + c.codePointAt(0)!.toString(16).padStart(4, '0'))
+    ),
+  ];
+}
+
+const PO_SOURCE = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '',
+  'msgid "Hello"',
+  'msgstr ""',
+  '',
+].join('\n');
+
+const ANDROID_SOURCE = [
+  '<?xml version="1.0" encoding="utf-8"?>',
+  '<resources>',
+  '  <string name="greeting">Hello</string>',
+  '</resources>',
+  '',
+].join('\n');
+
+const XLIFF_SOURCE = [
+  '<?xml version="1.0"?>',
+  '<xliff version="1.2"><file source-language="en" target-language="de" datatype="plaintext" original="x">',
+  '<body>',
+  '<trans-unit id="greeting"><source>Hello</source></trans-unit>',
+  '</body></file></xliff>',
+  '',
+].join('\n');
+
+function writeTranslation(
+  parser: FormatParser,
+  source: string,
+  translation: string
+): string {
+  const entries = parser.extract(source);
+  return parser.reconstruct(
+    source,
+    entries.map((e) => ({ ...e, translation }))
+  );
+}
+
+describe('writers that can escape a control character do so', () => {
+  const CASES: Array<{
+    label: string;
+    parser: () => FormatParser;
+    source: string;
+    /** How the format spells an escaped ESC in its own syntax. */
+    expectedEscape: string;
+  }> = [
+    {
+      label: 'TOML',
+      parser: () => new TomlFormatParser(),
+      source: 'greeting = "Hello"\n',
+      expectedEscape: '\\u001b',
+    },
+    {
+      label: 'Java Properties',
+      parser: () => new PropertiesFormatParser(),
+      source: 'greeting=Hello\n',
+      expectedEscape: '\\u001b',
+    },
+    {
+      label: 'iOS Strings',
+      parser: () => new IosStringsFormatParser(),
+      source: '"greeting" = "Hello";\n',
+      expectedEscape: '\\U001b',
+    },
+  ];
+
+  describe.each(CASES)('$label', ({ parser, source, expectedEscape }) => {
+    it('should write no raw control byte', () => {
+      const out = writeTranslation(parser(), source, HOSTILE);
+
+      expect(rawControlBytes(out)).toEqual([]);
+      expect(out).toContain(expectedEscape);
+    });
+
+    it('should read the escaped value back unchanged', () => {
+      const p = parser();
+      const out = writeTranslation(p, source, HOSTILE);
+
+      expect(p.extract(out)[0]!.value).toBe(HOSTILE);
+    });
+
+    it('should leave an ordinary translation alone', () => {
+      const out = writeTranslation(parser(), source, 'Hallo Welt');
+
+      expect(out).toContain('Hallo Welt');
+    });
+  });
+
+  it('TOML should also escape U+007F, which its own parser rejects raw', () => {
+    const parser = new TomlFormatParser();
+    const out = writeTranslation(parser, 'greeting = "Hello"\n', `a${DEL}b`);
+
+    expect(out).not.toContain(DEL);
+    expect(out).toContain('\\u007f');
+    expect(parser.extract(out)[0]!.value).toBe(`a${DEL}b`);
+  });
+
+  it('TOML should not emit a literal string it cannot escape into', () => {
+    const parser = new TomlFormatParser();
+    const out = writeTranslation(parser, "greeting = 'Hello'\n", HOSTILE);
+
+    expect(rawControlBytes(out)).toEqual([]);
+    expect(parser.extract(out)[0]!.value).toBe(HOSTILE);
+  });
+
+  it('PO should escape a carriage return rather than write it raw', () => {
+    const parser = new PoFormatParser();
+    const out = writeTranslation(parser, PO_SOURCE, `Hallo${CR}Welt`);
+
+    expect(out).toContain('\\r');
+    expect(rawControlBytes(out)).toEqual([]);
+  });
+});
+
+describe('writers that cannot escape a control character refuse the value', () => {
+  const CASES: Array<{
+    label: string;
+    parser: () => FormatParser;
+    source: string;
+  }> = [
+    { label: 'PO', parser: () => new PoFormatParser(), source: PO_SOURCE },
+    {
+      label: 'Android XML',
+      parser: () => new AndroidXmlFormatParser(),
+      source: ANDROID_SOURCE,
+    },
+    {
+      label: 'XLIFF',
+      parser: () => new XliffFormatParser(),
+      source: XLIFF_SOURCE,
+    },
+  ];
+
+  describe.each(CASES)('$label', ({ parser, source }) => {
+    it('should throw ValidationError rather than write the byte', () => {
+      expect(() => writeTranslation(parser(), source, HOSTILE)).toThrow(
+        ValidationError
+      );
+    });
+
+    it('should name the codepoint, which prints as nothing', () => {
+      expect(() => writeTranslation(parser(), source, HOSTILE)).toThrow(
+        /U\+001B/
+      );
+    });
+
+    it('should name the key so the offending string can be found', () => {
+      expect(() => writeTranslation(parser(), source, HOSTILE)).toThrow(
+        /greeting|Hello/
+      );
+    });
+
+    it('should leave an ordinary translation alone', () => {
+      const out = writeTranslation(parser(), source, 'Hallo Welt');
+
+      expect(out).toContain('Hallo Welt');
+      expect(rawControlBytes(out)).toEqual([]);
+    });
+  });
+
+  it('Android XML should refuse the byte inside a CDATA value too', () => {
+    const source = [
+      '<?xml version="1.0" encoding="utf-8"?>',
+      '<resources>',
+      '  <string name="greeting"><![CDATA[Hello]]></string>',
+      '</resources>',
+      '',
+    ].join('\n');
+
+    expect(() =>
+      writeTranslation(new AndroidXmlFormatParser(), source, HOSTILE)
+    ).toThrow(ValidationError);
+  });
+});

From 13e74cca1aa10ca15eee6efb37339f7f433cdc53 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 12:45:08 +0200
Subject: [PATCH 158/256] fix(sync): read the translation, not the source, from
 a bilingual target file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PO and XLIFF carry both sides in one file, so their `extract().value` is the
source text even when the file being read is a target. Six sync paths built
their "translations this target file already holds" map as `key ->
extract().value` and therefore handed the source back as a translation:

- `sync` carried the msgid into its own msgstr on any run that rewrote the
  file for a sibling key, replacing a reviewed translation with English at
  exit 0 while the lockfile still called the key translated
- `sync push` uploaded the msgid as the locale's translation, so the TMS
  became the authority for a key whose recorded translation was English
- `sync validate` compared the source against itself: every entry warned
  "identical to source text" and a placeholder-dropping msgstr passed at
  exit 0
- `sync pull` fell back to the msgid for a key the export omits
- `sync audit` measured terminology across source strings

`FormatParser.extractTranslations` lets a parser own the target-side read;
PO and XLIFF implement it and every call site goes through one helper,
`extractExistingTranslations`. An empty msgstr, a missing `<target>` and an
empty `<target></target>` read as untranslated rather than as a translation,
so such a key is translated instead of having the source pinned into it —
monolingual formats keep preserving a deliberately empty value.
`TmsClient.pushEntry` now takes the translation as a required argument, and
push skips a key with none under a new `untranslated` skip reason rather
than uploading its source text.

`sync validate` exits 8 where it passed at 0, and push reports a lower
count on a bucket with untranslated keys.

Refs cli-8kr2.59
---
 CHANGELOG.md                                  |   8 +
 docs/SYNC.md                                  |  16 +
 src/cli/commands/sync/register-sync-audit.ts  |  10 +-
 src/formats/format.ts                         |  15 +
 src/formats/po.ts                             |  36 ++
 src/formats/xliff.ts                          |  33 ++
 src/sync/sync-bucket-walker.ts                |  28 ++
 src/sync/sync-process-bucket.ts               |   8 +-
 src/sync/sync-tms.ts                          |  53 ++-
 src/sync/sync-validate.ts                     |  13 +-
 src/sync/tms-client.ts                        |  13 +-
 .../e2e/cli-sync-bilingual-target.e2e.test.ts | 191 +++++++++
 .../sync-bilingual-target.integration.test.ts | 289 ++++++++++++++
 tests/unit/formats/bilingual-target.test.ts   | 369 ++++++++++++++++++
 tests/unit/sync/sync-bucket-walker.test.ts    |  79 ++++
 tests/unit/sync/sync-tms.test.ts              |  19 +-
 16 files changed, 1145 insertions(+), 35 deletions(-)
 create mode 100644 tests/e2e/cli-sync-bilingual-target.e2e.test.ts
 create mode 100644 tests/integration/sync-bilingual-target.integration.test.ts
 create mode 100644 tests/unit/formats/bilingual-target.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 66d4e68d..fff498e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **two output shapes change for PO and XLIFF buckets.** `deepl sync validate` now **exits 8** on a project it previously passed at exit 0, because the check finally reads the translation (see Security) — a CI job treating that command's exit 0 as "translations are sound" will start failing on input it was already shipping broken. And `deepl sync push` now reports a lower pushed count on any PO or XLIFF bucket with keys not yet translated: those keys are skipped rather than uploaded as their own source text (see Fixed), under a new `untranslated` skip reason that appears in the `(N skipped: ...)` summary line and in `--format json`. Monolingual buckets are unaffected on both counts.
+
 - **sync**: **`sync pull`'s lockfile and output shapes both change.** Pulled keys no longer carry `review_status` at all (see Security), so anything reading `review_status === "human_reviewed"` out of `.deepl-sync.lock` to find reviewed strings stops matching pulled entries — an absent field means "unknown", which is all the export response supports. A key with no translation in the export and none in the target file is now **absent** from the written target file rather than present holding the source string (see Fixed). `sync pull --format json` gains `replaced` and `dryRun` fields, and the text output gains a second line naming the replaced count when it is non-zero.
 
 - **translate**: **a translation that lost one of your placeholders is now a failure rather than output.** `deepl translate` exits 5 and writes nothing where it previously printed or wrote the CLI's internal `__ Var_0 __` scaffolding at exit 0, and a directory run reports those files as failed. Anything scraping `translate` output was already receiving unusable text in this case; it now sees a non-zero exit instead. See Fixed.
@@ -127,6 +129,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a reviewed PO or XLIFF translation is no longer replaced with source text.** Gettext PO and XLIFF are bilingual — one file carries the source in `msgid` / `<source>` and the translation in `msgstr` / `<target>` — and their `extract().value` is the *source* even when the file being read is a target. Every sync path that needed "the translation this target file already holds" built its map as `key -> extract().value`, so all of them read the source side. Measured through the real CLI against a mock endpoint, on the run that rewrites a file because a **sibling** key is new: `msgstr "REVIEWED-PO"` became `msgstr "Hello"` and `<target>REVIEWED-XLF</target>` became `<target>Hello</target>`, at exit 0, with the lockfile still recording the key as `translated` so no later run corrects it. The identical scenario on a `json` bucket correctly kept its hand-edited value, which is what made this format-specific rather than general. The finding named three call sites; there were **six**, and the two it did not name are the worse ones — see the `sync push` measurement below and the `sync validate` entry under Security. `deepl sync pull` had the same blind spot in its merge base, writing the msgid for a key the TMS export does not carry, and `deepl sync audit` measured terminology consistency across source strings rather than translations. Parsers may now override the target-side read (`FormatParser.extractTranslations`), PO and XLIFF do, and all six call sites go through one helper instead of reaching for `value`. An empty `msgstr`, a missing `<target>` and an empty `<target></target>` now read as *untranslated* rather than as a translation, so such a key is translated instead of having the source pinned into it; this differs deliberately from the monolingual formats, where an empty value is a deliberate translation and is still preserved.
+
+- **sync**: **`deepl sync push` no longer uploads English as a locale's translation.** Push reads each target file and previously sent `entry.value`, which for a PO or XLIFF target is the msgid / `<source>`. Measured against a mock TMS: a `locales/es/app.po` holding `msgstr "Hola amigo"` produced the PUT body `{"locale":"es","value":"Hello {name}"}` and a TMS store of `{"es":{"Hello {name}":"Hello {name}"}}` — the reviewed Spanish never left the machine, and the TMS became the authority for a key whose recorded translation was the English source, so the next `deepl sync pull` would write English back into the target file. `TmsClient.pushEntry` now takes the translation as a required argument rather than reading it off `entry.value`, which is why no caller can reintroduce this by omission.
+
 - **formats**: **a `.properties` value ending in a backslash no longer deletes the entry after it.** `escapeValue` correctly writes a literal trailing backslash as `\\`, but the reader's continuation test was `line.endsWith('\\')` with no parity check, so it read that escape as "this line continues", consumed the following line and appended its raw text to the previous value. Measured: a source of `greeting=Hello` / `api_key=SECRET_VALUE` / `footer=Bye` with `greeting` translated to `Hallo\` was written as `greeting=Hallo\\`, and re-extracted as `[{greeting: "Hallo api_key=SECRET_VALUE"}, {footer: "Bye"}]` — the middle entry **gone**, at exit 0. The finding called this data loss; it is also a disclosure. `sync push` extracts the target file and sends each value to the TMS, so the swallowed line left the machine under an unrelated key's name: measured, the push body for `greeting` was `Hallo api_key=SECRET_VALUE`, and `api_key` itself was never pushed at all — 2 keys sent where the file had 3. The same misread hits a *hand-written* source on its very first read, so a legitimate Windows path such as `path=C:\\` was enough on its own. Both continuation tests (extract and reconstruct) now count the trailing backslash run and continue only on an odd count, which is the rule `escapeValue` was already writing for. Round-trip is now verified for the values `x\`, `\`, `a\b\`, `C:\` and `a\\b`; the first four all previously ate the next entry.
 
 - **translate**: **`deepl translate <file.json|.yaml>` now has a size ceiling, so a huge locale file cannot exhaust memory mid-run.** The structured-file route read and fully parsed whatever it was given, while both sibling routes of the same command were already bounded — text at 100 KiB, documents at 30 MB (`MAX_DOCUMENT_FILE_SIZE`) — and `deepl sync` skips anything over `sync.limits.max_file_bytes`. Measured peak RSS against a dead endpoint, so only parse and extract are counted: 4.7 MB → 129 MB, 19.2 MB → 251 MB, 80.9 MB → 684 MB, 163.8 MB → 1178 MB, linear and unbounded. The finding did not name the multiplier: the multi-target path parses a **fresh copy per target language**, up to `MULTI_TARGET_CONCURRENCY` (5) at once, so the same 19.2 MB file peaked at 252 MB for `--to de` and **483 MB** for `--to de,fr,es,it,nl`. The ceiling is 10 MiB, matching `HARD_MAX_SYNC_LIMITS.max_file_bytes` — the value `sync` refuses to be configured above — so nothing sync can be made to accept is refused here, and the worst case stays a few hundred MB rather than gigabytes. The check is a `fs.stat` before the read, at the one function both entry points funnel through, so an oversize file is never resident: the 163.8 MB fixture now exits 6 in 0.17 s at 86 MB RSS instead of 7.8 s at 1178 MB. The message names the file, its size and the limit, and points at `deepl sync` for anything larger; a directory run fails only that file and keeps its per-file reason in the summary. A document at 25 MB is still accepted, deliberately — it is streamed to the API rather than parsed.
@@ -422,6 +428,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **sync**: **`deepl sync validate` was inert for PO and XLIFF buckets and reported the opposite of the truth.** The gate compares each target value against its source, but for a bilingual format it read the msgid / `<source>` on both sides, so it was comparing the source against itself. Measured through the real CLI on a `locales/es/app.po` whose `msgstr "Hola amigo"` drops the `{name}` placeholder the msgid carries: `deepl sync validate` **exited 0** reporting `1 warning(s)` — and the warning was `Translation is identical to source text`, which is a false positive raised against every entry in every PO and XLIFF bucket, correct translations included. The genuinely broken translation passed. It now exits 8 with `ERROR es/Hello {name}: Missing placeholders in translation: {name}`. Anything using `deepl sync validate` as a CI gate on a PO or XLIFF project was gating on nothing: the check that was meant to catch a placeholder-dropping translation could not see the translation at all.
+
 - **formats**: **no writer emits a raw C0 control byte into a repo file any more.** Six of the nine writers escaped only their own quoting characters plus `\n`/`\r`/`\t`, so any other control byte in a translation was written through untouched; JSON, YAML and ARB were already clean because they delegate to `JSON.stringify` and the YAML emitter. That put live terminal-control sequences into source-controlled files, where `git diff`, `cat`, `less` and CI log viewers all render them — with no CLI output path involved. **No API call is needed to trigger it.** A contributor commits a *valid* `locales/app.de.toml` holding `greeting = "Hola\u001B[2J"` (TOML basic strings legally carry `\uXXXX`, and smol-toml decodes it to a raw ESC). The key is then `current`, so it is never translated and never validated: the locale translator carries the existing target value forward and the writer put the byte back out raw. Measured through the real CLI: the rewritten file contained `greeting = "Hola␛[2J"`, and `TomlFormatParser.extract` then refuses it — `Invalid TOML document: control characters are not allowed in strings`. The finding said every later run fails; **measured, it is quieter and worse than that.** `deepl sync` exits 0 and says nothing, because the target-file read is inside a catch that treats a parse failure as "no existing translations", so the file's translations simply stop being visible to sync. `deepl sync status` exits 0 reporting **`de [####] 100% (0 missing, 0 outdated)`** for a file it cannot parse. Only `deepl sync validate` fails, at the untyped exit 1. Android XML and XLIFF are worse still: every C0 byte except tab, LF and CR is outside XML 1.0's `Char` production, so there is no escape and no numeric character reference for it — expat rejects both written files as `not well-formed (invalid token)`, which means `aapt2` and every conforming CAT tool reject them too. One shared rule now lives in `src/formats/util/control-chars.ts`, and each writer applies it the way its own format allows: TOML escapes as `\uXXXX` (and forces the double-quoted form for a value a literal string could not escape, plus U+007F, which smol-toml also rejects raw — verified against the library); `.properties` extends its existing `\uXXXX` rule below U+0020; iOS Strings emits `\UXXXX`, which its own reader already decodes; PO gains the missing `\r` escape and refuses the rest with a `ValidationError` naming the entry, since its escape set cannot spell them and `unquote` could not read them back; Android XML and XLIFF refuse with a `ValidationError` naming the resource or trans-unit, matching the stance both already take on CDATA. Each message names the codepoint (`U+001B`) rather than quoting a byte that prints as nothing.
 
 - **sync**: **a source catalog can no longer smuggle one string into another string's key.** Five parsers encode hierarchical key identity in-band with no escaping: PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.`. A key component holding the separator therefore resolved to the same key as an unrelated entry, and the two control bytes **print as nothing**, so the source diff showed an ordinary string. Measured: a PO catalog carrying `msgid "menu␄Save"` beside a normal `msgctxt "menu" / msgid "Save"` pair extracted two entries with the identical key `menu␄Save`, and reconstruct wrote the smuggled entry's translation into the legitimate pair's `msgstr` — the attacker picks the source text, DeepL translates it, and the result lands in the victim key's slot in **every** locale. **The stronger case needs no collision at all**: one smuggled `msgid "menu␄Save"` in a catalog with no `msgctxt` anywhere produced `msgctxt "menu"` / `msgid "Save"` / `msgstr "ATTACKER-TEXT"` in every target `.po`, forging a context-qualified entry the source never had — so a duplicate-key check alone would have missed it. YAML behaves the same way: a source key `"a\0b"` became a genuine nested `a: { b: ATTACKER-TEXT }` via `doc.setIn`. For the `.` formats the damage is a lost or corrupt file rather than a forgery: `{"a.b":"FLAT","a":{"b":"NESTED"}}` rewrote both slots to one translation and dropped the flat key's own; the Android `<string name="items.0">` colliding with `<string-array name="items">` was **deleted** from the output; and the Laravel case emitted PHP the CLI's own parser then refuses — the repo's `11-dot-key-vs-nested.php` fixture reconstructs to `'b' => 'PWNED<NESTED>'LAT>',`, failing to re-read with `syntax error, unexpected 'LAT' (T_STRING), expecting ']'`, because `collectStringLocs` maps a key to one source offset and the two replacements splice over each other. Each parser now refuses the file: PO and YAML reject the reserved byte at both key-construction sites (extract and the target-file read inside reconstruct), quoting it back escaped as `\u0004` / `\u0000` rather than echoing a byte that prints as nothing; JSON, Laravel PHP and Android XML assert their extract output has distinct keys, which for those three is exactly equivalent to detecting a separator collision because their containers already guarantee distinct sibling keys. `sync` skips the one file with a warning naming the colliding key and finishes the rest of the run at exit 0, following the existing `FormatDepthExceededError` and `max_entries_per_file` convention — one hostile file must not discard the lockfile for work already translated, billed and written. `.properties` and XLIFF are deliberately excluded: a literally repeated key is legal in both (Java `Properties.load` is last-wins), so a blanket duplicate check would have rejected files that work today. `sync pull` reading a **target** file whose keys collide leaves it untouched and records a `key_collision` skip, rather than falling through to the source template — measured, that fallback would have rebuilt `locales/de.json` from source down to the single key the export carried, discarding a hand-written translation.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 14530478..c87106ed 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -117,6 +117,20 @@ Such a file is **skipped with a warning naming the colliding key**, and the rest
 
 On `deepl sync pull`, a **target** file whose keys collide is left exactly as it stands and reported under the `key_collision` skip reason. Pull does not fall back to rebuilding it from the source file, which would discard every local translation the TMS export does not carry.
 
+### Bilingual formats: PO and XLIFF
+
+Nine of the eleven formats are monolingual -- a target file holds translations and nothing else, so its values *are* the translations. Gettext PO and XLIFF are **bilingual**: one file carries both sides, the source in `msgid` / `<source>` and the translation in `msgstr` / `<target>`. Every sync path that needs "the translation this target file already holds" therefore reads the translation side, never the source side:
+
+| Path | What it reads from a PO / XLIFF target |
+|------|----------------------------------------|
+| `deepl sync` | The existing `msgstr` / `<target>` is carried forward for a key the lockfile calls up to date, so a reviewed translation survives a run that rewrites the file because a *sibling* key changed |
+| `deepl sync push` | The `msgstr` / `<target>` is what gets uploaded |
+| `deepl sync validate` | Placeholder and structure checks compare the `msgstr` against the `msgid` |
+| `deepl sync pull` | For a key the export does not carry, the existing `msgstr` is kept |
+| `deepl sync audit` | Terminology consistency is measured across translations |
+
+**An empty translation side means untranslated, not empty.** A `msgstr ""`, a `<trans-unit>` with no `<target>`, and an empty `<target></target>` all read as "this key has no translation yet": `sync` translates the key rather than pinning the empty string, and `push` skips it (see below). This differs from the monolingual formats, where an empty value is a deliberate translation and is preserved.
+
 ## Configuration
 
 ### `.deepl-sync.yaml`
@@ -851,6 +865,8 @@ deepl sync push [OPTIONS]
 | `--format <fmt>` | Output format: `text` (default), `json` |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 
+**A key with no translation yet is not pushed.** Push reads each target file and uploads the translation it holds. A bilingual target file (see [Bilingual formats: PO and XLIFF](#bilingual-formats-po-and-xliff)) lists every key the source has, translated or not, so pushing such a key would upload its source text as the locale's translation and make the TMS the authority for it -- a later `pull` would then write English into the target file. Those keys are skipped and reported under the `untranslated` reason, with the pushed count reflecting only what was actually sent. For a monolingual format nothing is skipped on this account: every key the target file lists has a value.
+
 ### `deepl sync pull`
 
 Pull approved translations from a TMS back into local files.
diff --git a/src/cli/commands/sync/register-sync-audit.ts b/src/cli/commands/sync/register-sync-audit.ts
index 762c6aef..e552bfc7 100644
--- a/src/cli/commands/sync/register-sync-audit.ts
+++ b/src/cli/commands/sync/register-sync-audit.ts
@@ -68,7 +68,7 @@ async function handleSyncAudit(
     const { LOCK_FILE_NAME } = await import('../../../sync/types.js');
     const { generateGlossaryReport } =
       await import('../../../sync/sync-glossary-report.js');
-    const { extractTranslatable } =
+    const { extractExistingTranslations } =
       await import('../../../sync/sync-bucket-walker.js');
     const { createDefaultRegistry } = await import('../../../formats/index.js');
     const { resolveTargetPath } = await import('../../../sync/sync-utils.js');
@@ -100,10 +100,10 @@ async function handleSyncAudit(
             const targetAbs = pathMod.join(config.projectRoot, targetRel);
             if (!fsMod.existsSync(targetAbs)) continue;
             const content = await fsMod.promises.readFile(targetAbs, 'utf-8');
-            const entries = extractTranslatable(parser, content, locale);
-            const keyMap = new Map<string, string>();
-            for (const entry of entries) keyMap.set(entry.key, entry.value);
-            fileLocaleMap.set(locale, keyMap);
+            fileLocaleMap.set(
+              locale,
+              extractExistingTranslations(parser, content, locale)
+            );
           } catch {
             // Unreadable / unparseable target file — reported as a missing target.
           }
diff --git a/src/formats/format.ts b/src/formats/format.ts
index 4912978b..824be8a8 100644
--- a/src/formats/format.ts
+++ b/src/formats/format.ts
@@ -33,6 +33,21 @@ export interface FormatParser {
   ): string;
   /** Optional: extract context for a specific key from file content */
   extractContext?(content: string, key: string): string | undefined;
+  /**
+   * Optional: the translations a *target* file already holds, keyed the way
+   * `extract` keys them. Bilingual formats — one file carrying both sides, as
+   * PO does with `msgid`/`msgstr` and XLIFF with `<source>`/`<target>` — must
+   * implement it, because their `extract().value` is the SOURCE text even when
+   * reading a target file. A key the file has no translation for yet is left
+   * out of the map rather than mapped to the empty string, which is how a caller
+   * separates an untranslated key from a deliberately empty translation. An
+   * implementation must also leave out any key it tags `metadata.skipped`, since
+   * the map bypasses the walker's skip partition.
+   *
+   * Monolingual formats leave it undefined: for them `extract().value` on a
+   * target read already is the translation.
+   */
+  extractTranslations?(content: string, locale?: string): Map<string, string>;
   /**
    * Optional: a copy of this parser bounded to `maxDepth` levels of nesting.
    * Parsers that walk their tree recursively implement it so `sync` can apply
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 5f4c08fe..6479ef2d 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -355,6 +355,42 @@ export class PoFormatParser implements FormatParser {
     return entries;
   }
 
+  /**
+   * PO is bilingual, so `extract().value` is the msgid even when the file being
+   * read is a target. The translation is the msgstr, and an empty msgstr is
+   * gettext's spelling of "not translated yet" — such a key is left out so a
+   * caller re-translates it rather than pinning the empty string.
+   *
+   * A plural entry has no bare msgstr; its first non-empty msgstr[n] stands in,
+   * which is enough to report the entry as translated. The per-form values
+   * travel separately in `metadata.plural_forms`.
+   */
+  extractTranslations(content: string): Map<string, string> {
+    const translations = new Map<string, string>();
+    if (!content.trim()) {
+      return translations;
+    }
+
+    for (const pe of parseEntries(content)) {
+      if (isHeaderEntry(pe)) {
+        continue;
+      }
+
+      const singular = pe.msgstr[0];
+      const translation =
+        singular !== undefined && singular !== ''
+          ? singular
+          : [...pe.msgstrPlural.values()].find((v) => v !== '');
+      if (translation === undefined) {
+        continue;
+      }
+
+      translations.set(makeKey(pe), translation);
+    }
+
+    return translations;
+  }
+
   // Comment bookkeeping is local rather than via PendingCommentBuffer: po
   // backtracks into `result` at entry-start to slice trailing contiguous
   // `#`-runs into `commentLines`, for pop-on-delete or splice-with-fuzzy-strip
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index 134ff680..afe554d6 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -193,6 +193,39 @@ export class XliffFormatParser implements FormatParser {
     return entries;
   }
 
+  /**
+   * XLIFF is bilingual, so `extract().value` is `<source>` even when the file
+   * being read is a target. The translation is `<target>`; a unit with no
+   * `<target>`, or an empty one, is untranslated and is left out so a caller
+   * re-translates it. The element is located exactly as `applyTarget` locates
+   * the one it overwrites, so the map reports what a write would replace.
+   */
+  extractTranslations(content: string): Map<string, string> {
+    assertNoCdataInTranslatable(content);
+    const isV2 = detectVersion(content) === '2.0';
+    const translations = new Map<string, string>();
+
+    for (const element of scanElements(
+      content,
+      isV2 ? UNIT_EL : TRANS_UNIT_EL
+    )) {
+      const scope = isV2
+        ? findElement(element.inner, SEGMENT_EL)?.inner
+        : element.inner;
+      if (scope === undefined) continue;
+      if (!findElement(scope, SOURCE_EL)) continue;
+
+      const target = findElement(scope, TARGET_EL);
+      if (!target) continue;
+      const translation = unescapeXml(target.inner);
+      if (translation === '') continue;
+
+      translations.set(element.groups[0]!, translation);
+    }
+
+    return translations;
+  }
+
   reconstruct(content: string, entries: TranslatedEntry[]): string {
     assertNoCdataInTranslatable(content);
     const version = detectVersion(content);
diff --git a/src/sync/sync-bucket-walker.ts b/src/sync/sync-bucket-walker.ts
index ca0245f7..129cf074 100644
--- a/src/sync/sync-bucket-walker.ts
+++ b/src/sync/sync-bucket-walker.ts
@@ -83,6 +83,34 @@ export function extractTranslatable(
   return partitionEntries(raw).entries;
 }
 
+/**
+ * The translations `content` — a *target*-file read — already holds, keyed the
+ * way `extract` keys them.
+ *
+ * Never build this map from `extract(...).value`. A bilingual format carries
+ * both sides in one file and reports the SOURCE text as `value`, so that map
+ * hands the source string back as though it were the translation: `sync`
+ * carries English into `msgstr`, `sync push` uploads English as the locale's
+ * translation, and `sync validate` compares the source against itself. Parsers
+ * that need it override the read via `extractTranslations`; for the rest
+ * `value` already is the translation.
+ */
+export function extractExistingTranslations(
+  parser: FormatParser,
+  content: string,
+  locale?: string
+): Map<string, string> {
+  if (parser.extractTranslations) {
+    return parser.extractTranslations(
+      content,
+      parser.multiLocale ? locale : undefined
+    );
+  }
+  return new Map(
+    extractTranslatable(parser, content, locale).map((e) => [e.key, e.value])
+  );
+}
+
 // Cache of already-read+parsed bucket source files, keyed by absolute path.
 // Populated opportunistically by the template-pattern prep pass in sync-service
 // so walkBuckets can skip re-reading the same files on the main translation loop.
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index c33613cb..611b3f6d 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -14,7 +14,7 @@ import type { SyncLockFile, SyncLockTranslation } from './types.js';
 import type { KeyContext } from './sync-context.js';
 import { Logger } from '../utils/logger.js';
 import {
-  extractTranslatable,
+  extractExistingTranslations,
   type WalkedBucketFile,
 } from './sync-bucket-walker.js';
 import type { LocaleTranslator } from './sync-locale-translator.js';
@@ -262,10 +262,9 @@ export async function processBucket(
   const existingTargetEntries = new Map<string, Map<string, string>>();
   for (const locale of locales) {
     if (isMultiLocale) {
-      const targetParsed = extractTranslatable(parser, content, locale);
       existingTargetEntries.set(
         locale,
-        new Map(targetParsed.map((e) => [e.key, e.value]))
+        extractExistingTranslations(parser, content, locale)
       );
     } else {
       const targetRelPath = resolveTargetPath(
@@ -281,10 +280,9 @@ export async function processBucket(
           targetAbsPath,
           'utf-8'
         );
-        const targetParsed = extractTranslatable(parser, targetContent);
         existingTargetEntries.set(
           locale,
-          new Map(targetParsed.map((e) => [e.key, e.value]))
+          extractExistingTranslations(parser, targetContent)
         );
       } catch {
         existingTargetEntries.set(locale, new Map());
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index eca3f6fe..f4545d85 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -21,7 +21,11 @@ import {
 import { LOCK_FILE_NAME } from './types.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency, PUSH_CONCURRENCY } from '../utils/concurrency.js';
-import { partitionEntries, walkBuckets } from './sync-bucket-walker.js';
+import {
+  extractExistingTranslations,
+  partitionEntries,
+  walkBuckets,
+} from './sync-bucket-walker.js';
 import { Logger } from '../utils/logger.js';
 import { sweepStaleBackups, resolveBakSweepAgeMs } from './sync-bak-cleanup.js';
 
@@ -31,7 +35,11 @@ export interface SyncPushPullOptions {
 }
 
 export type SkipReason =
-  'target_missing' | 'no_matches' | 'pipe_pluralization' | 'key_collision';
+  | 'target_missing'
+  | 'no_matches'
+  | 'pipe_pluralization'
+  | 'key_collision'
+  | 'untranslated';
 
 export interface SkippedRecord {
   file: string;
@@ -56,6 +64,7 @@ const SKIP_REASON_LABELS: Record<SkipReason, string> = {
   no_matches: 'no matching keys',
   pipe_pluralization: 'pipe-pluralization (never sent to TMS)',
   key_collision: 'target file keys collide (left untouched)',
+  untranslated: 'no translation in the target file',
 };
 
 /**
@@ -108,10 +117,16 @@ export async function pushTranslations(
       try {
         let entries: ExtractedEntry[];
         let skippedEntries: ExtractedEntry[];
+        let translations: Map<string, string>;
         if (isMultiLocale) {
           ({ entries, skippedEntries } = partitionEntries(
             parser.extract(sourceContent, locale)
           ));
+          translations = extractExistingTranslations(
+            parser,
+            sourceContent,
+            locale
+          );
         } else {
           const targetPath = resolveTargetPath(
             relPath,
@@ -125,6 +140,7 @@ export async function pushTranslations(
           ({ entries, skippedEntries } = partitionEntries(
             parser.extract(content)
           ));
+          translations = extractExistingTranslations(parser, content);
         }
         for (const skippedEntry of skippedEntries) {
           skipped.push({
@@ -134,10 +150,28 @@ export async function pushTranslations(
             key: skippedEntry.key,
           });
         }
+        // A bilingual target file lists every key the source has, translated or
+        // not. Pushing such a key would upload its source text as the locale's
+        // translation and make the TMS the authority for it.
+        const pushable: Array<{ entry: ExtractedEntry; translation: string }> =
+          [];
+        for (const entry of entries) {
+          const translation = translations.get(entry.key);
+          if (translation === undefined) {
+            skipped.push({
+              file: relPath,
+              locale,
+              reason: 'untranslated',
+              key: entry.key,
+            });
+            continue;
+          }
+          pushable.push({ entry, translation });
+        }
         await mapWithConcurrency(
-          entries,
-          async (entry) => {
-            await client.pushEntry(entry, locale);
+          pushable,
+          async ({ entry, translation }) => {
+            await client.pushEntry(entry, locale, translation);
             pushed++;
           },
           pushConcurrency
@@ -226,11 +260,10 @@ export async function pullTranslations(
       let existingTargetEntries = new Map<string, string>();
       try {
         templateContent = await fs.promises.readFile(targetAbsPath, 'utf-8');
-        const { entries: existingEntries } = isMultiLocale
-          ? partitionEntries(parser.extract(templateContent, locale))
-          : partitionEntries(parser.extract(templateContent));
-        existingTargetEntries = new Map(
-          existingEntries.map((entry) => [entry.key, entry.value])
+        existingTargetEntries = extractExistingTranslations(
+          parser,
+          templateContent,
+          locale
         );
       } catch (err) {
         // A target file whose keys collide cannot be merged into — and must not
diff --git a/src/sync/sync-validate.ts b/src/sync/sync-validate.ts
index be131d77..4ee482fa 100644
--- a/src/sync/sync-validate.ts
+++ b/src/sync/sync-validate.ts
@@ -7,7 +7,10 @@ import {
 } from './translation-validator.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
-import { extractTranslatable, walkBuckets } from './sync-bucket-walker.js';
+import {
+  extractExistingTranslations,
+  walkBuckets,
+} from './sync-bucket-walker.js';
 
 export interface ValidateIssue extends ValidationResult {
   locale: string;
@@ -40,12 +43,12 @@ export async function validateTranslations(
     } = walked;
 
     for (const locale of config.target_locales) {
-      let targetEntries;
+      let targetMap: Map<string, string>;
       let targetRelPath: string;
 
       if (isMultiLocale) {
         targetRelPath = relPath;
-        targetEntries = extractTranslatable(parser, sourceContent, locale);
+        targetMap = extractExistingTranslations(parser, sourceContent, locale);
       } else {
         targetRelPath = resolveTargetPath(
           relPath,
@@ -66,11 +69,9 @@ export async function validateTranslations(
           targetAbsPath,
           'utf-8'
         );
-        targetEntries = extractTranslatable(parser, targetContent);
+        targetMap = extractExistingTranslations(parser, targetContent);
       }
 
-      const targetMap = new Map(targetEntries.map((e) => [e.key, e.value]));
-
       const pairs = sourceEntries
         .filter((se) => targetMap.has(se.key))
         .map((se) => ({
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index 9eeb36bb..43f6a944 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -354,7 +354,16 @@ export class TmsClient {
     });
   }
 
-  async pushEntry(entry: ExtractedEntry, locale: string): Promise<void> {
+  /**
+   * `translation` is passed explicitly rather than read off `entry.value`: for a
+   * bilingual format `value` is the source text even when the entry came from a
+   * target file, so defaulting to it would upload English as the translation.
+   */
+  async pushEntry(
+    entry: ExtractedEntry,
+    locale: string,
+    translation: string
+  ): Promise<void> {
     if (entry.metadata && 'skipped' in entry.metadata) {
       throw new Error(
         `TmsClient.pushEntry refused to push key "${entry.key}" (locale=${locale}): ` +
@@ -362,7 +371,7 @@ export class TmsClient {
           `skip-partition (partitionEntries in src/sync/sync-bucket-walker.ts) before reaching push.`
       );
     }
-    await this.pushKey(entry.key, locale, entry.value);
+    await this.pushKey(entry.key, locale, translation);
   }
 
   async pullKeys(locale: string): Promise<Record<string, string>> {
diff --git a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
new file mode 100644
index 00000000..27d97518
--- /dev/null
+++ b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
@@ -0,0 +1,191 @@
+/**
+ * E2E regression for cli-8kr2.59.
+ *
+ * PO and XLIFF carry both the source and the translation in one file, and their
+ * `extract().value` is the source. `sync` built its "translations the target
+ * file already has" map from that value, so on any run that rewrote the file —
+ * one where a sibling key is new — a `current` key had the msgid carried
+ * forward into its own msgstr. A reviewed translation became English, silently,
+ * at exit 0, and the lockfile still called the key translated so no later run
+ * corrected it.
+ */
+
+import { spawn, spawnSync, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+
+const PO_HEADER = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '',
+  '',
+].join('\n');
+
+describe('CLI sync with a bilingual target file', () => {
+  const testConfig = createTestConfigDir('e2e-sync-bilingual');
+  const testFiles = createTestDir('e2e-sync-bilingual-files');
+  let mockServer: ChildProcess;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'node',
+        [path.join(__dirname, 'mock-deepl-server.cjs')],
+        { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env } }
+      );
+      mockServer = child;
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = /PORT=(\d+)/.exec(output);
+        if (match) resolve(parseInt(match[1]!, 10));
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  function runSync(): { status: number | null; output: string } {
+    const { CI: _ci, DEEPL_API_KEY: _key, ...rest } = process.env;
+    const result = spawnSync('node', [CLI_PATH, 'sync', '--yes'], {
+      encoding: 'utf-8',
+      cwd: testFiles.path,
+      env: { ...rest, DEEPL_CONFIG_DIR: testConfig.path, NO_COLOR: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60000,
+    });
+    return {
+      status: result.status,
+      output: (result.stdout ?? '') + (result.stderr ?? ''),
+    };
+  }
+
+  beforeAll(async () => {
+    const port = await startMockServer();
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+      })
+    );
+    fs.writeFileSync(
+      path.join(testFiles.path, '.deepl-sync.yaml'),
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - es',
+        'buckets:',
+        '  po:',
+        '    include:',
+        '      - "locales/en/app.po"',
+        '  xliff:',
+        '    include:',
+        '      - "locales/en/app.xlf"',
+        '',
+      ].join('\n')
+    );
+    fs.mkdirSync(path.join(testFiles.path, 'locales', 'en'), {
+      recursive: true,
+    });
+    fs.writeFileSync(
+      path.join(testFiles.path, 'locales', 'en', 'app.po'),
+      PO_HEADER + 'msgid "Hello"\nmsgstr ""\n'
+    );
+    fs.writeFileSync(
+      path.join(testFiles.path, 'locales', 'en', 'app.xlf'),
+      [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<xliff version="1.2">',
+        '  <file source-language="en" datatype="plaintext" original="app">',
+        '    <body>',
+        '      <trans-unit id="greeting">',
+        '        <source>Hello</source>',
+        '      </trans-unit>',
+        '    </body>',
+        '  </file>',
+        '</xliff>',
+        '',
+      ].join('\n')
+    );
+  }, 30000);
+
+  afterAll(() => {
+    if (mockServer) mockServer.kill('SIGTERM');
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  const poTarget = () => path.join(testFiles.path, 'locales', 'es', 'app.po');
+  const xlfTarget = () => path.join(testFiles.path, 'locales', 'es', 'app.xlf');
+
+  it('keeps a reviewed translation when a sibling key forces a rewrite', () => {
+    // Run 1 establishes the lockfile, so `Hello` / `greeting` become `current`.
+    expect(runSync().status).toBe(0);
+    expect(fs.readFileSync(poTarget(), 'utf-8')).toContain('msgstr "Hola"');
+    expect(fs.readFileSync(xlfTarget(), 'utf-8')).toContain('<target>Hola<');
+
+    // A reviewer improves both machine translations by hand.
+    fs.writeFileSync(
+      poTarget(),
+      fs
+        .readFileSync(poTarget(), 'utf-8')
+        .replace('msgstr "Hola"', 'msgstr "REVIEWED-PO"')
+    );
+    fs.writeFileSync(
+      xlfTarget(),
+      fs
+        .readFileSync(xlfTarget(), 'utf-8')
+        .replace('<target>Hola</target>', '<target>REVIEWED-XLF</target>')
+    );
+
+    // A contributor adds a sibling key, so both target files are rewritten.
+    fs.appendFileSync(
+      path.join(testFiles.path, 'locales', 'en', 'app.po'),
+      '\nmsgid "Translate me"\nmsgstr ""\n'
+    );
+    const xlfSource = path.join(testFiles.path, 'locales', 'en', 'app.xlf');
+    fs.writeFileSync(
+      xlfSource,
+      fs
+        .readFileSync(xlfSource, 'utf-8')
+        .replace(
+          '    </body>',
+          [
+            '      <trans-unit id="added">',
+            '        <source>Translate me</source>',
+            '      </trans-unit>',
+            '    </body>',
+          ].join('\n')
+        )
+    );
+
+    const second = runSync();
+    expect(second.status).toBe(0);
+
+    const po = fs.readFileSync(poTarget(), 'utf-8');
+    expect(po).toContain('msgstr "REVIEWED-PO"');
+    expect(po).not.toContain('msgstr "Hello"');
+    expect(po).toContain('msgstr "Traduceme"');
+
+    const xlf = fs.readFileSync(xlfTarget(), 'utf-8');
+    expect(xlf).toContain('<target>REVIEWED-XLF</target>');
+    expect(xlf).not.toContain('<target>Hello</target>');
+  }, 120000);
+});
diff --git a/tests/integration/sync-bilingual-target.integration.test.ts b/tests/integration/sync-bilingual-target.integration.test.ts
new file mode 100644
index 00000000..3c9a8e37
--- /dev/null
+++ b/tests/integration/sync-bilingual-target.integration.test.ts
@@ -0,0 +1,289 @@
+/**
+ * Integration tests for the PO/XLIFF target-file read.
+ *
+ * Every sync path that needs "the translation this target file already holds"
+ * built its map as `key -> extract().value`. For a bilingual format that value
+ * is the SOURCE text, so each path handed English back as though a translator
+ * had written it:
+ *
+ *   push     uploads the msgid as the locale's translation, and the reviewed
+ *            msgstr never leaves the machine.
+ *   validate compares the source against itself — every entry is reported
+ *            "identical to source" and a translation that drops a placeholder
+ *            passes.
+ *   pull     falls back to the msgid for a key the export does not carry,
+ *            overwriting the reviewed msgstr with source text.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { createTmsClient } from '../../src/sync/tms-client';
+import { pushTranslations, pullTranslations } from '../../src/sync/sync-tms';
+import { validateTranslations } from '../../src/sync/sync-validate';
+import { loadSyncConfig } from '../../src/sync/sync-config';
+
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import {
+  TMS_BASE,
+  TMS_PROJECT,
+  tmsConfig,
+  approvedTmsTrust,
+} from '../helpers/tms-nock';
+
+const PO_HEADER = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '',
+  '',
+].join('\n');
+
+function write(dir: string, relPath: string, content: string): void {
+  const abs = path.join(dir, relPath);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, 'utf-8');
+}
+
+describe('sync paths that read a bilingual target file', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+  let envSnapshot: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    envSnapshot = { ...process.env };
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-bilingual-'));
+    harness = createSyncHarness({ parsers: ['po', 'xliff'] });
+    process.env['TMS_API_KEY'] = 'env-key';
+    delete process.env['TMS_TOKEN'];
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+    process.env = envSnapshot;
+  });
+
+  describe('push', () => {
+    it('sends the msgstr, never the msgid', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        tms: tmsConfig(),
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hello"\nmsgstr ""\n'
+      );
+      write(
+        tmpDir,
+        'locales/es/app.po',
+        PO_HEADER + 'msgid "Hello"\nmsgstr "Hola"\n'
+      );
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+      const sent: Record<string, string> = {};
+      nock(TMS_BASE)
+        .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
+        .reply(200, function reply(uri: string, body: unknown) {
+          sent[decodeURIComponent(uri.split('/keys/')[1]!)] = (
+            body as { value: string }
+          ).value;
+          return {};
+        });
+
+      const result = await pushTranslations(config, client, harness.registry);
+
+      expect(result.pushed).toBe(1);
+      expect(sent['Hello']).toBe('Hola');
+    });
+
+    it('sends the <target>, never the <source>', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        tms: tmsConfig(),
+        buckets: { xliff: { include: ['locales/en/app.xlf'] } },
+      });
+      const unit = (inner: string): string =>
+        [
+          '<?xml version="1.0"?>',
+          '<xliff version="1.2"><file source-language="en" datatype="plaintext" original="app">',
+          '<body>',
+          `<trans-unit id="greeting">${inner}</trans-unit>`,
+          '</body></file></xliff>',
+          '',
+        ].join('\n');
+      write(tmpDir, 'locales/en/app.xlf', unit('<source>Hello</source>'));
+      write(
+        tmpDir,
+        'locales/es/app.xlf',
+        unit('<source>Hello</source><target>Hola</target>')
+      );
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+      const sent: Record<string, string> = {};
+      nock(TMS_BASE)
+        .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
+        .reply(200, function reply(uri: string, body: unknown) {
+          sent[decodeURIComponent(uri.split('/keys/')[1]!)] = (
+            body as { value: string }
+          ).value;
+          return {};
+        });
+
+      const result = await pushTranslations(config, client, harness.registry);
+
+      expect(result.pushed).toBe(1);
+      expect(sent['greeting']).toBe('Hola');
+    });
+
+    it('skips an untranslated key rather than uploading its source text', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        tms: tmsConfig(),
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hello"\nmsgstr ""\n\nmsgid "Bye"\nmsgstr ""\n'
+      );
+      write(
+        tmpDir,
+        'locales/es/app.po',
+        PO_HEADER + 'msgid "Hello"\nmsgstr "Hola"\n\nmsgid "Bye"\nmsgstr ""\n'
+      );
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+      const sent: Record<string, string> = {};
+      nock(TMS_BASE)
+        .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
+        .times(2)
+        .reply(200, function reply(uri: string, body: unknown) {
+          sent[decodeURIComponent(uri.split('/keys/')[1]!)] = (
+            body as { value: string }
+          ).value;
+          return {};
+        });
+
+      const result = await pushTranslations(config, client, harness.registry);
+
+      expect(Object.keys(sent)).toEqual(['Hello']);
+      expect(result.pushed).toBe(1);
+      expect(result.skipped).toEqual([
+        {
+          file: 'locales/en/app.po',
+          locale: 'es',
+          reason: 'untranslated',
+          key: 'Bye',
+        },
+      ]);
+    });
+  });
+
+  describe('validate', () => {
+    it('checks the msgstr, so a translation that drops a placeholder is an issue', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hello {name}"\nmsgstr ""\n'
+      );
+      write(
+        tmpDir,
+        'locales/es/app.po',
+        PO_HEADER + 'msgid "Hello {name}"\nmsgstr "Hola amigo"\n'
+      );
+
+      const config = await loadSyncConfig(tmpDir);
+      const result = await validateTranslations(config, harness.registry);
+
+      expect(result.totalChecked).toBe(1);
+      expect(result.issues).toHaveLength(1);
+      expect(result.issues[0]!.translation).toBe('Hola amigo');
+      expect(result.issues[0]!.issues.map((i) => i.check)).toContain(
+        'placeholders'
+      );
+    });
+
+    it('does not report a correct translation as identical to its source', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hello {name}"\nmsgstr ""\n'
+      );
+      write(
+        tmpDir,
+        'locales/es/app.po',
+        PO_HEADER + 'msgid "Hello {name}"\nmsgstr "Hola {name}"\n'
+      );
+
+      const config = await loadSyncConfig(tmpDir);
+      const result = await validateTranslations(config, harness.registry);
+
+      expect(result.totalChecked).toBe(1);
+      expect(result.issues).toEqual([]);
+    });
+  });
+
+  describe('pull', () => {
+    it('keeps the existing msgstr for a key the export does not carry', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        tms: tmsConfig(),
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hello"\nmsgstr ""\n\nmsgid "Bye"\nmsgstr ""\n'
+      );
+      write(
+        tmpDir,
+        'locales/es/app.po',
+        PO_HEADER +
+          'msgid "Hello"\nmsgstr "REVIEWED"\n\nmsgid "Bye"\nmsgstr "Adios"\n'
+      );
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+      nock(TMS_BASE)
+        .get(`/api/projects/${TMS_PROJECT}/keys/export`)
+        .query(true)
+        .reply(200, { Bye: 'Adios (from TMS)' });
+
+      await pullTranslations(config, client, harness.registry);
+
+      const written = fs.readFileSync(
+        path.join(tmpDir, 'locales/es/app.po'),
+        'utf-8'
+      );
+      expect(written).toContain('msgstr "REVIEWED"');
+      expect(written).toContain('msgstr "Adios (from TMS)"');
+      expect(written).not.toContain('msgstr "Hello"');
+    });
+  });
+});
diff --git a/tests/unit/formats/bilingual-target.test.ts b/tests/unit/formats/bilingual-target.test.ts
new file mode 100644
index 00000000..104501dd
--- /dev/null
+++ b/tests/unit/formats/bilingual-target.test.ts
@@ -0,0 +1,369 @@
+/**
+ * Tests that reading a target file's translations never yields the source text.
+ *
+ * Most formats are monolingual: a target file holds only the translation, so
+ * `extract(...).value` on a target read IS the translation. PO and XLIFF are
+ * bilingual — one file carries both sides — and report the SOURCE as `value`
+ * even when the file is a target. Callers that need the translation therefore
+ * have to go through `extractTranslations`, and every format has to agree on
+ * what "the translation this file holds" means: the value a reviewer would see,
+ * with an untranslated key absent from the map rather than mapped to the source
+ * or to the empty string.
+ */
+
+import { AndroidXmlFormatParser } from '../../../src/formats/android-xml';
+import { ArbFormatParser } from '../../../src/formats/arb';
+import { IosStringsFormatParser } from '../../../src/formats/ios-strings';
+import { JsonFormatParser } from '../../../src/formats/json';
+import { PhpArraysFormatParser } from '../../../src/formats/php-arrays';
+import { PoFormatParser } from '../../../src/formats/po';
+import { PropertiesFormatParser } from '../../../src/formats/properties';
+import { TomlFormatParser } from '../../../src/formats/toml';
+import { XcstringsFormatParser } from '../../../src/formats/xcstrings';
+import { XliffFormatParser } from '../../../src/formats/xliff';
+import { YamlFormatParser } from '../../../src/formats/yaml';
+import type { FormatParser } from '../../../src/formats/format';
+
+const PO_SOURCE = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '',
+  'msgid "Hello"',
+  'msgstr ""',
+  '',
+].join('\n');
+
+const XLIFF_12_SOURCE = [
+  '<?xml version="1.0"?>',
+  '<xliff version="1.2"><file source-language="en" target-language="de" datatype="plaintext" original="x">',
+  '<body>',
+  '<trans-unit id="greeting"><source>Hello</source></trans-unit>',
+  '</body></file></xliff>',
+  '',
+].join('\n');
+
+const XLIFF_20_SOURCE = [
+  '<?xml version="1.0"?>',
+  '<xliff version="2.0" srcLang="en" trgLang="de"><file id="f1">',
+  '<unit id="greeting"><segment><source>Hello</source></segment></unit>',
+  '</file></xliff>',
+  '',
+].join('\n');
+
+const XCSTRINGS_SOURCE =
+  JSON.stringify(
+    {
+      sourceLanguage: 'en',
+      version: '1.0',
+      strings: {
+        greeting: {
+          localizations: {
+            en: { stringUnit: { state: 'translated', value: 'Hello' } },
+          },
+        },
+      },
+    },
+    null,
+    2
+  ) + '\n';
+
+/**
+ * The contract every caller relies on, spelled out with the parser surface
+ * alone: a parser that overrides the read owns it, and the rest report `value`.
+ */
+function readTranslations(
+  parser: FormatParser,
+  content: string,
+  locale?: string
+): Map<string, string> {
+  if (parser.extractTranslations) {
+    return parser.extractTranslations(
+      content,
+      parser.multiLocale ? locale : undefined
+    );
+  }
+  const entries = parser.multiLocale
+    ? parser.extract(content, locale)
+    : parser.extract(content);
+  return new Map(entries.map((e) => [e.key, e.value]));
+}
+
+describe('reading the translations a target file holds', () => {
+  const CASES: Array<{
+    label: string;
+    parser: () => FormatParser;
+    /** A source-locale file holding one key whose source text is "Hello". */
+    source: string;
+    key: string;
+    locale?: string;
+  }> = [
+    {
+      label: 'JSON',
+      parser: () => new JsonFormatParser(),
+      source: '{\n  "greeting": "Hello"\n}\n',
+      key: 'greeting',
+    },
+    {
+      label: 'YAML',
+      parser: () => new YamlFormatParser(),
+      source: 'greeting: Hello\n',
+      key: 'greeting',
+    },
+    {
+      label: 'Java Properties',
+      parser: () => new PropertiesFormatParser(),
+      source: 'greeting=Hello\n',
+      key: 'greeting',
+    },
+    {
+      label: 'TOML',
+      parser: () => new TomlFormatParser(),
+      source: 'greeting = "Hello"\n',
+      key: 'greeting',
+    },
+    {
+      label: 'iOS Strings',
+      parser: () => new IosStringsFormatParser(),
+      source: '"greeting" = "Hello";\n',
+      key: 'greeting',
+    },
+    {
+      label: 'Android XML',
+      parser: () => new AndroidXmlFormatParser(),
+      source: [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<resources>',
+        '  <string name="greeting">Hello</string>',
+        '</resources>',
+        '',
+      ].join('\n'),
+      key: 'greeting',
+    },
+    {
+      label: 'Laravel PHP',
+      parser: () => new PhpArraysFormatParser(),
+      source: "<?php\nreturn [\n    'greeting' => 'Hello',\n];\n",
+      key: 'greeting',
+    },
+    {
+      label: 'ARB',
+      parser: () => new ArbFormatParser(),
+      source: '{\n  "greeting": "Hello"\n}\n',
+      key: 'greeting',
+    },
+    {
+      label: 'PO',
+      parser: () => new PoFormatParser(),
+      source: PO_SOURCE,
+      key: 'Hello',
+    },
+    {
+      label: 'XLIFF 1.2',
+      parser: () => new XliffFormatParser(),
+      source: XLIFF_12_SOURCE,
+      key: 'greeting',
+    },
+    {
+      label: 'XLIFF 2.0',
+      parser: () => new XliffFormatParser(),
+      source: XLIFF_20_SOURCE,
+      key: 'greeting',
+    },
+    {
+      label: 'xcstrings',
+      parser: () => new XcstringsFormatParser(),
+      source: XCSTRINGS_SOURCE,
+      key: 'greeting',
+      locale: 'de',
+    },
+  ];
+
+  describe.each(CASES)('$label', ({ parser, source, key, locale }) => {
+    /** The target file a first sync produces from `source`. */
+    function writeTarget(p: FormatParser, translation: string): string {
+      const entries = p.multiLocale
+        ? p.extract(source, 'en')
+        : p.extract(source);
+      return p.reconstruct(
+        source,
+        entries.map((e) => ({ ...e, translation })),
+        locale
+      );
+    }
+
+    it('should report the translation the file holds, not the source text', () => {
+      const p = parser();
+      const target = writeTarget(p, 'Hallo');
+
+      expect(readTranslations(p, target, locale).get(key)).toBe('Hallo');
+    });
+
+    it('should report a hand-edited translation verbatim', () => {
+      const p = parser();
+      const target = writeTarget(p, 'REVIEWED');
+
+      expect(readTranslations(p, target, locale).get(key)).toBe('REVIEWED');
+    });
+  });
+});
+
+describe('PoFormatParser.extractTranslations', () => {
+  const parser = new PoFormatParser();
+
+  it('should return the msgstr, never the msgid', () => {
+    const target = [
+      PO_SOURCE.trimEnd(),
+      '',
+      'msgid "Goodbye"',
+      'msgstr "Adios"',
+      '',
+    ].join('\n');
+
+    const map = parser.extractTranslations(target);
+
+    expect(map.get('Goodbye')).toBe('Adios');
+    expect([...map.values()]).not.toContain('Goodbye');
+  });
+
+  it('should omit a key whose msgstr is empty rather than report the msgid', () => {
+    const map = parser.extractTranslations(PO_SOURCE);
+
+    expect(map.has('Hello')).toBe(false);
+  });
+
+  it('should key a msgctxt entry the way extract keys it', () => {
+    const target = [
+      'msgctxt "menu"',
+      'msgid "Save"',
+      'msgstr "Guardar"',
+      '',
+    ].join('\n');
+
+    const extractedKey = parser.extract(target)[0]!.key;
+
+    expect(parser.extractTranslations(target).get(extractedKey)).toBe(
+      'Guardar'
+    );
+  });
+
+  it('should skip the header entry', () => {
+    const map = parser.extractTranslations(PO_SOURCE);
+
+    expect(map.has('')).toBe(false);
+  });
+
+  it('should report a plural entry as translated so it is not re-translated', () => {
+    const target = [
+      'msgid "One file"',
+      'msgid_plural "%d files"',
+      'msgstr[0] "Un archivo"',
+      'msgstr[1] "%d archivos"',
+      '',
+    ].join('\n');
+
+    const map = parser.extractTranslations(target);
+
+    expect(map.get('One file')).toBe('Un archivo');
+  });
+
+  it('should omit a plural entry whose forms are all empty', () => {
+    const target = [
+      'msgid "One file"',
+      'msgid_plural "%d files"',
+      'msgstr[0] ""',
+      'msgstr[1] ""',
+      '',
+    ].join('\n');
+
+    expect(parser.extractTranslations(target).has('One file')).toBe(false);
+  });
+
+  it('should return an empty map for empty content', () => {
+    expect(parser.extractTranslations('').size).toBe(0);
+  });
+});
+
+describe('XliffFormatParser.extractTranslations', () => {
+  const parser = new XliffFormatParser();
+
+  it('should return the target element, never the source element (1.2)', () => {
+    const target = XLIFF_12_SOURCE.replace(
+      '<source>Hello</source>',
+      '<source>Hello</source><target>Hola</target>'
+    );
+
+    const map = parser.extractTranslations(target);
+
+    expect(map.get('greeting')).toBe('Hola');
+    expect([...map.values()]).not.toContain('Hello');
+  });
+
+  it('should return the target element from inside a segment (2.0)', () => {
+    const target = XLIFF_20_SOURCE.replace(
+      '<source>Hello</source>',
+      '<source>Hello</source><target>Hola</target>'
+    );
+
+    expect(parser.extractTranslations(target).get('greeting')).toBe('Hola');
+  });
+
+  it('should omit a unit with no target element', () => {
+    expect(parser.extractTranslations(XLIFF_12_SOURCE).has('greeting')).toBe(
+      false
+    );
+    expect(parser.extractTranslations(XLIFF_20_SOURCE).has('greeting')).toBe(
+      false
+    );
+  });
+
+  it('should omit a unit whose target element is empty', () => {
+    const target = XLIFF_12_SOURCE.replace(
+      '<source>Hello</source>',
+      '<source>Hello</source><target></target>'
+    );
+
+    expect(parser.extractTranslations(target).has('greeting')).toBe(false);
+  });
+
+  it('should preserve a target that carries a state attribute', () => {
+    const target = XLIFF_12_SOURCE.replace(
+      '<source>Hello</source>',
+      '<source>Hello</source><target state="translated">Hola</target>'
+    );
+
+    expect(parser.extractTranslations(target).get('greeting')).toBe('Hola');
+  });
+
+  it('should decode entities in the target text', () => {
+    const target = XLIFF_12_SOURCE.replace(
+      '<source>Hello</source>',
+      '<source>Hello</source><target>Tom &amp; Jerry</target>'
+    );
+
+    expect(parser.extractTranslations(target).get('greeting')).toBe(
+      'Tom & Jerry'
+    );
+  });
+});
+
+describe('monolingual parsers leave the read alone', () => {
+  const MONOLINGUAL: Array<[string, FormatParser]> = [
+    ['JSON', new JsonFormatParser()],
+    ['YAML', new YamlFormatParser()],
+    ['Java Properties', new PropertiesFormatParser()],
+    ['TOML', new TomlFormatParser()],
+    ['iOS Strings', new IosStringsFormatParser()],
+    ['Android XML', new AndroidXmlFormatParser()],
+    ['Laravel PHP', new PhpArraysFormatParser()],
+    ['ARB', new ArbFormatParser()],
+    ['xcstrings', new XcstringsFormatParser()],
+  ];
+
+  it.each(MONOLINGUAL)(
+    '%s should not override extractTranslations',
+    (_label, parser) => {
+      expect(parser.extractTranslations).toBeUndefined();
+    }
+  );
+});
diff --git a/tests/unit/sync/sync-bucket-walker.test.ts b/tests/unit/sync/sync-bucket-walker.test.ts
index 9398dffc..061e788e 100644
--- a/tests/unit/sync/sync-bucket-walker.test.ts
+++ b/tests/unit/sync/sync-bucket-walker.test.ts
@@ -1,4 +1,5 @@
 import {
+  extractExistingTranslations,
   extractTranslatable,
   walkBuckets,
 } from '../../../src/sync/sync-bucket-walker';
@@ -326,3 +327,81 @@ describe('extractTranslatable', () => {
     expect(extractTranslatable(parser, '<content>')).toEqual([]);
   });
 });
+
+describe('extractExistingTranslations', () => {
+  function makeParser(
+    entries: ExtractedEntry[],
+    opts: {
+      multiLocale?: boolean;
+      translations?: Map<string, string>;
+    } = {}
+  ): FormatParser {
+    return {
+      multiLocale: opts.multiLocale,
+      extract: jest.fn((_content: string, _locale?: string) => entries),
+      reconstruct: jest.fn(),
+      ...(opts.translations && {
+        extractTranslations: jest.fn(
+          (_content: string, _locale?: string) => opts.translations
+        ),
+      }),
+      format: 'json',
+    } as unknown as FormatParser;
+  }
+
+  it('reads value for a parser that does not override the read', () => {
+    const parser = makeParser([
+      { key: 'greeting', value: 'Hallo' },
+      { key: 'farewell', value: 'Tschuess' },
+    ]);
+
+    expect([...extractExistingTranslations(parser, '<content>')]).toEqual([
+      ['greeting', 'Hallo'],
+      ['farewell', 'Tschuess'],
+    ]);
+  });
+
+  it('drops skipped entries on the value path, as the diff paths do', () => {
+    const parser = makeParser([
+      { key: 'greeting', value: 'Hallo' },
+      {
+        key: 'plural',
+        value: '|{n} item',
+        metadata: { skipped: 'pipe_pluralization' },
+      },
+    ]);
+
+    expect([
+      ...extractExistingTranslations(parser, '<content>').keys(),
+    ]).toEqual(['greeting']);
+  });
+
+  it('prefers the parser override, so the source text is never returned', () => {
+    const parser = makeParser([{ key: 'Hello', value: 'Hello' }], {
+      translations: new Map([['Hello', 'Hola']]),
+    });
+
+    expect(extractExistingTranslations(parser, '<content>').get('Hello')).toBe(
+      'Hola'
+    );
+  });
+
+  it('forwards locale to the override only when multiLocale is true', () => {
+    const multi = makeParser([], {
+      multiLocale: true,
+      translations: new Map(),
+    });
+    extractExistingTranslations(multi, '<content>', 'de');
+    expect(multi.extractTranslations).toHaveBeenCalledWith('<content>', 'de');
+
+    const single = makeParser([], {
+      multiLocale: false,
+      translations: new Map(),
+    });
+    extractExistingTranslations(single, '<content>', 'de');
+    expect(single.extractTranslations).toHaveBeenCalledWith(
+      '<content>',
+      undefined
+    );
+  });
+});
diff --git a/tests/unit/sync/sync-tms.test.ts b/tests/unit/sync/sync-tms.test.ts
index 93cbfec9..3d276433 100644
--- a/tests/unit/sync/sync-tms.test.ts
+++ b/tests/unit/sync/sync-tms.test.ts
@@ -214,12 +214,16 @@ describe('TmsClient.pushEntry — runtime skip-partition guard', () => {
       metadata: { skipped: { reason: SKIP_REASON_PIPE_PLURALIZATION } },
     };
 
-    await expect(client.pushEntry(skipped, 'de')).rejects.toThrow(/walker/i);
-    await expect(client.pushEntry(skipped, 'de')).rejects.toThrow(/skipped/i);
+    await expect(client.pushEntry(skipped, 'de', 'x')).rejects.toThrow(
+      /walker/i
+    );
+    await expect(client.pushEntry(skipped, 'de', 'x')).rejects.toThrow(
+      /skipped/i
+    );
     expect(pushKeySpy).not.toHaveBeenCalled();
   });
 
-  it('forwards translatable entries to pushKey unchanged', async () => {
+  it('sends the caller-supplied translation, not the entry value', async () => {
     const client = new TmsClient({
       serverUrl: 'https://tms.test',
       projectId: 'p',
@@ -228,7 +232,8 @@ describe('TmsClient.pushEntry — runtime skip-partition guard', () => {
     const pushKeySpy = jest
       .spyOn(client, 'pushKey')
       .mockResolvedValue(undefined);
-    await client.pushEntry({ key: 'greeting', value: 'Hallo' }, 'de');
+    // A bilingual format's entry carries the SOURCE as `value`.
+    await client.pushEntry({ key: 'greeting', value: 'Hello' }, 'de', 'Hallo');
     expect(pushKeySpy).toHaveBeenCalledWith('greeting', 'de', 'Hallo');
   });
 });
@@ -258,7 +263,7 @@ describe('pushTranslations — skip-partition invariant at inline extract sites'
       },
       { key: 'farewell', value: 'Tschüss' },
     ];
-    const parser = makeStubParser([mixedEntries, mixedEntries]);
+    const parser = makeStubParser(mixedEntries);
     const client = makeTmsClient();
 
     const result = await pushTranslations(
@@ -294,7 +299,7 @@ describe('pushTranslations — skip-partition invariant at inline extract sites'
         metadata: { skipped: { reason: SKIP_REASON_PIPE_PLURALIZATION } },
       },
     ];
-    const parser = makeStubParser([mixedEntries, mixedEntries], {
+    const parser = makeStubParser(mixedEntries, {
       multiLocale: true,
       configKey: 'xcstrings',
     });
@@ -327,7 +332,7 @@ describe('pushTranslations — skip-partition invariant at inline extract sites'
         metadata: { skipped: { reason: SKIP_REASON_PIPE_PLURALIZATION } },
       },
     ];
-    const parser = makeStubParser([mixedEntries, mixedEntries, mixedEntries]);
+    const parser = makeStubParser(mixedEntries);
     const client = makeTmsClient();
 
     const config = makeConfig({ target_locales: ['de', 'fr'] });

From d61521874036eef0227eb96466f180b52fef4bd8 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 13:27:44 +0200
Subject: [PATCH 159/256] fix(formats): write a source key added after the
 first sync, not drop it

From the second sync onwards the target file is the `reconstruct` template --
that is how the translations it already holds survive -- so a key added to
the source since has no slot in it. Six parsers appended such an entry;
`properties`, `ios_strings`, `laravel_php`, `android_xml` and `xliff`
discarded it, and nothing downstream could tell, because a run records
success from the translation call rather than from the write. Measured
through the real CLI on each of the five, with `json` as a control on the
same run:

  exit 0, "OK es: 1/1 keys", "Sync complete: 1 new, 1 current"
  target file:         the key ABSENT
  .deepl-sync.lock:    added.translations.es = {status: "translated"}
  deepl sync status:   exit 0, es [####] 100% (0 missing, 0 outdated)
  deepl sync --frozen: exit 0, "2 current"   <- the CI drift gate
  deepl sync validate: exit 0, "Checked 1 translations ... All passed"

The characters were billed, and the lockfile's `translated` claim is what
stopped a later run correcting it, so the string was permanently absent from
the shipped locale.

Each parser now writes the entry in the layout the file already uses:
`.properties` and `.strings` append a line, keeping the trailing newline and
any dangling comment in place; `laravel_php` splices an element into the
array that owns the key, matching its quote style, indentation,
one-line-or-many layout and trailing-comma style, for `array(...)` as well
as `[...]`; `android_xml` writes a `<string>` or a whole `<plurals>` before
`</resources>`; XLIFF writes a `<trans-unit>` in 1.2 and a
`<unit><segment>` in 2.0, carrying the namespace prefix of the unit it sits
beside. XLIFF 2.0 was affected too, which the finding did not measure.

Two cases stay out, because writing them means inventing structure the
source file already defines: a new `<string-array>` item in `android_xml`,
whose `name.index` key cannot be told apart from a plain resource named with
a trailing dot-integer, and a `laravel_php` key whose parent array is absent
from the target.

An already-affected project recovers on its next sync that has any work to
do, re-billing the key; a run with nothing else to do writes nothing and
`status` still reports complete, because `status` and `--frozen` compare the
source against the lockfile and never read the target file.

Refs cli-8kr2.60
---
 CHANGELOG.md                                  |   3 +
 docs/SYNC.md                                  |  16 +
 src/formats/android-xml.ts                    |  85 ++++-
 src/formats/ios-strings.ts                    |  13 +
 src/formats/php-arrays.ts                     | 165 ++++++++-
 src/formats/properties.ts                     |  13 +
 src/formats/util/append-lines.ts              |  22 ++
 src/formats/xliff.ts                          |  96 ++++-
 src/formats/xml-scan.ts                       |  26 ++
 tests/e2e/cli-sync-new-source-key.e2e.test.ts | 215 +++++++++++
 tests/helpers/sync-harness.ts                 |   6 +-
 .../sync-new-source-key.integration.test.ts   | 217 +++++++++++
 tests/unit/formats/android-xml.test.ts        | 117 ++++++
 tests/unit/formats/ios-strings.test.ts        |  33 ++
 tests/unit/formats/new-key-insert.test.ts     | 342 ++++++++++++++++++
 tests/unit/formats/php-arrays.test.ts         |  88 ++++-
 tests/unit/formats/properties.test.ts         |  36 ++
 tests/unit/formats/xliff.test.ts              | 104 ++++++
 18 files changed, 1582 insertions(+), 15 deletions(-)
 create mode 100644 src/formats/util/append-lines.ts
 create mode 100644 tests/e2e/cli-sync-new-source-key.e2e.test.ts
 create mode 100644 tests/integration/sync-new-source-key.integration.test.ts
 create mode 100644 tests/unit/formats/new-key-insert.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fff498e8..1427df8c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **a project already missing strings from this defect recovers on its next sync that has any work to do, and re-bills them.** Measured on a `properties` project whose target file was missing a key the lockfile called `translated`: the next `deepl sync` that had a further key to translate reported `es: 2/2 keys` — the new key plus the recovered one — and wrote both. A run with nothing else to do reported `2 current`, wrote nothing, and `sync status` still said `100% (0 missing)`, because `status` and `--frozen` compare the source against the **lockfile** and never read the target file. So a project where nothing has changed since is not repaired by upgrading alone: add a string and sync, or delete the target file to have it rebuilt. See Fixed for the defect itself.
+
 - **sync**: **two output shapes change for PO and XLIFF buckets.** `deepl sync validate` now **exits 8** on a project it previously passed at exit 0, because the check finally reads the translation (see Security) — a CI job treating that command's exit 0 as "translations are sound" will start failing on input it was already shipping broken. And `deepl sync push` now reports a lower pushed count on any PO or XLIFF bucket with keys not yet translated: those keys are skipped rather than uploaded as their own source text (see Fixed), under a new `untranslated` skip reason that appears in the `(N skipped: ...)` summary line and in `--format json`. Monolingual buckets are unaffected on both counts.
 
 - **sync**: **`sync pull`'s lockfile and output shapes both change.** Pulled keys no longer carry `review_status` at all (see Security), so anything reading `review_status === "human_reviewed"` out of `.deepl-sync.lock` to find reviewed strings stops matching pulled entries — an absent field means "unknown", which is all the export response supports. A key with no translation in the export and none in the target file is now **absent** from the written target file rather than present holding the source string (see Fixed). `sync pull --format json` gains `replaced` and `dryRun` fields, and the text output gains a second line naming the replaced count when it is non-zero.
@@ -129,6 +131,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a string added to a source file after the first sync is no longer silently dropped from five of the eleven formats.** From the second run onwards `sync` uses the existing target file as the `reconstruct` template — that is how the translations it already holds survive — so a key added to the source since has no slot in it. Six parsers appended such an entry; `properties`, `ios_strings`, `laravel_php`, `android_xml` and `xliff` discarded it, and nothing downstream could tell, because the run recorded success from the translation call rather than from the write. Measured through the real CLI against a mock endpoint, run 2 of 2 on each of the five, with `json` as a control on the same run: exit 0, `OK es: 1/1 keys`, `Sync complete: 1 new, 1 current`, the target file **without** the key, `.deepl-sync.lock` recording `added.translations.es = {status: "translated"}`, `deepl sync status` reporting `es [####] 100% (0 missing, 0 outdated)`, `deepl sync --frozen` — the CI drift gate whose whole purpose is catching a missing translation — exiting 0 with `2 current`, and `deepl sync validate` passing with `Checked 1 translations ... All passed` because it only sees keys the file actually has. The characters were billed on every affected key, and the lockfile's `translated` claim is what stopped any later run correcting it, so the string was permanently absent from the shipped locale. Each of the five now writes the entry in the file's own layout: `.properties` and `.strings` append a line keeping the trailing newline and any dangling comment in place; `laravel_php` splices an array element at the offset of the array that owns it, matching the file's quote style, indentation, one-line-or-many layout and trailing-comma style, and handling `array(...)` as well as `[...]`; `android_xml` writes a `<string>` (or a whole `<plurals>` block) before `</resources>`; XLIFF writes a `<trans-unit>` in 1.2 and a `<unit><segment>` in 2.0, carrying the namespace prefix of the unit it is written beside. **XLIFF 2.0 was affected too** and the finding only measured 1.2. Two cases are deliberately still left out, because writing them would mean inventing structure the source file already defines: a new `<string-array>` item in `android_xml` (its `name.index` key is indistinguishable from a plain resource whose name ends in a dot-integer), and a `laravel_php` key whose parent array does not exist in the target. Verified after the fix with `xmllint --noout` on both XML outputs and `plutil -lint` on the `.strings` output.
 - **sync**: **a reviewed PO or XLIFF translation is no longer replaced with source text.** Gettext PO and XLIFF are bilingual — one file carries the source in `msgid` / `<source>` and the translation in `msgstr` / `<target>` — and their `extract().value` is the *source* even when the file being read is a target. Every sync path that needed "the translation this target file already holds" built its map as `key -> extract().value`, so all of them read the source side. Measured through the real CLI against a mock endpoint, on the run that rewrites a file because a **sibling** key is new: `msgstr "REVIEWED-PO"` became `msgstr "Hello"` and `<target>REVIEWED-XLF</target>` became `<target>Hello</target>`, at exit 0, with the lockfile still recording the key as `translated` so no later run corrects it. The identical scenario on a `json` bucket correctly kept its hand-edited value, which is what made this format-specific rather than general. The finding named three call sites; there were **six**, and the two it did not name are the worse ones — see the `sync push` measurement below and the `sync validate` entry under Security. `deepl sync pull` had the same blind spot in its merge base, writing the msgid for a key the TMS export does not carry, and `deepl sync audit` measured terminology consistency across source strings rather than translations. Parsers may now override the target-side read (`FormatParser.extractTranslations`), PO and XLIFF do, and all six call sites go through one helper instead of reaching for `value`. An empty `msgstr`, a missing `<target>` and an empty `<target></target>` now read as *untranslated* rather than as a translation, so such a key is translated instead of having the source pinned into it; this differs deliberately from the monolingual formats, where an empty value is a deliberate translation and is still preserved.
 
 - **sync**: **`deepl sync push` no longer uploads English as a locale's translation.** Push reads each target file and previously sent `entry.value`, which for a PO or XLIFF target is the msgid / `<source>`. Measured against a mock TMS: a `locales/es/app.po` holding `msgstr "Hola amigo"` produced the PUT body `{"locale":"es","value":"Hello {name}"}` and a TMS store of `{"es":{"Hello {name}":"Hello {name}"}}` — the reviewed Spanish never left the machine, and the TMS became the authority for a key whose recorded translation was the English source, so the next `deepl sync pull` would write English back into the target file. `TmsClient.pushEntry` now takes the translation as a required argument rather than reading it off `entry.value`, which is why no caller can reintroduce this by omission.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index c87106ed..4ecf8f9a 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -107,6 +107,22 @@ No writer emits a raw C0 control byte. Tab, newline and carriage return are esca
 
 A refusal is a `ValidationError` naming the resource or entry and the codepoint (`U+001B`) — never the byte itself, which prints as nothing.
 
+### A string added after the first sync
+
+The first sync has no target file, so the **source** file is the template every translation is written into, and every key has a slot. From the second run onwards the **target** file is the template -- that is how the translations it already holds survive -- and a key added to the source since has no slot in it. Every parser writes such an entry rather than dropping it, in the layout the target file already uses:
+
+| Format | Where the new string is written |
+|--------|---------------------------------|
+| JSON, YAML, TOML, ARB, Xcode String Catalog, Gettext PO | Appended by the underlying emitter, at the detected indentation |
+| Java Properties, iOS Strings | Appended as a line, keeping the file's trailing newline and leaving any dangling comment where it was |
+| Laravel PHP | Spliced into the array that owns the key, matching the file's quote style, indentation, one-line-or-many layout and trailing-comma style. `array(...)` and `[...]` are both handled |
+| Android XML | A `<string>`, or a whole `<plurals>` block, before `</resources>` |
+| XLIFF | A `<trans-unit>` with `<source>` and `<target>` in 1.2, a `<unit><segment>` in 2.0, carrying the namespace prefix of the unit it is written beside |
+
+Two cases are deliberately left out, because writing them would mean inventing structure the source file already defines: a new **`<string-array>` item** in Android XML, whose `name.index` key cannot be told apart from a plain resource whose name ends in a dot-integer; and a **Laravel PHP key whose parent array is absent** from the target file. Add the containing element to the target file once and the key is written on the next sync.
+
+Note that `deepl sync status` and `deepl sync --frozen` compare the source file against `.deepl-sync.lock`, not against the target file. A target file edited by hand to remove a key the lockfile records as translated therefore still reports complete; the key is restored on the next sync that has anything to translate, or immediately if you delete the target file and let it be rebuilt.
+
 ### Key separators and colliding keys
 
 Every parser reduces a string's position in the file to a flat key, using a separator the format does not otherwise carry: PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.`. A key component containing that separator makes two different strings share one key, and there is no correct way to write them back — one translation lands in the other's slot.
diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index 721b4d0c..5278cb6a 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -10,6 +10,9 @@ import {
   findForbiddenControlChar,
 } from './util/control-chars.js';
 import {
+  findElement,
+  insertBlocksAt,
+  lineIndentAt,
   replaceElements,
   scanElements,
   type ElementPattern,
@@ -48,6 +51,19 @@ const ARRAY_ITEM_EL: ElementPattern = {
   close: /<\/item>/y,
 };
 
+const RESOURCES_EL: ElementPattern = {
+  open: /<resources(?:\s[^><]*)?>/y,
+  close: /<\/resources>/y,
+};
+
+const INDENT_STEP = '    ';
+
+// A `<string-array>` element's entries are keyed `<name>.<index>`, so a key
+// ending in a dot-integer cannot be told apart from a plain resource whose name
+// happens to end that way. Writing a new resource for one would invent a
+// `<string>` named after an array slot, so those are left to the caller.
+const ARRAY_ITEM_KEY_RE = /\.\d+$/;
+
 const TRANSLATABLE_FALSE_RE = /\btranslatable\s*=\s*"false"/;
 
 const XML_ENTITY_RE = /&(?:#x([0-9a-fA-F]+)|#(\d+)|(amp|lt|gt|quot|apos));/g;
@@ -276,7 +292,74 @@ export class AndroidXmlFormatParser implements FormatParser {
       return this.rewriteInner(el, inner);
     });
 
-    return result;
+    return this.writeMissingResources(result, translations, pluralTranslations);
+  }
+
+  /**
+   * Write a resource for every entry the document has no element for. Such an
+   * entry is a key added to the source file after this target was written: the
+   * target is the reconstruct template, so it has no slot, and dropping the
+   * entry loses the string with nothing to distinguish it from a key never
+   * asked for.
+   *
+   * A new `<string-array>` item is not written — see ARRAY_ITEM_KEY_RE.
+   */
+  private writeMissingResources(
+    content: string,
+    translations: Map<string, string>,
+    pluralTranslations: Map<string, Map<string, string>>
+  ): string {
+    const strings = scanElements(content, STRING_EL);
+    const plurals = scanElements(content, PLURALS_EL);
+    const arrays = scanElements(content, STRING_ARRAY_EL);
+    const slotted = new Set(
+      [...strings, ...plurals, ...arrays].map((el) => el.groups[0]!)
+    );
+
+    const missingStrings = [...translations].filter(
+      ([name]) => !slotted.has(name) && !ARRAY_ITEM_KEY_RE.test(name)
+    );
+    const missingPlurals = [...pluralTranslations].filter(
+      ([name, quantities]) => !slotted.has(name) && quantities.size > 0
+    );
+    if (missingStrings.length === 0 && missingPlurals.length === 0) {
+      return content;
+    }
+
+    const anchor =
+      strings[strings.length - 1] ??
+      plurals[plurals.length - 1] ??
+      arrays[arrays.length - 1];
+    let at: number;
+    let indent: string;
+    if (anchor) {
+      at = anchor.end;
+      indent = lineIndentAt(content, anchor.start);
+    } else {
+      const resources = findElement(content, RESOURCES_EL);
+      if (!resources) return content;
+      at = resources.start + resources.openTag.length;
+      indent = lineIndentAt(content, resources.start) + INDENT_STEP;
+    }
+
+    const blocks = [
+      ...missingStrings.map(([name, translation]) => {
+        assertNoControlChars(name, translation);
+        return `<string name="${name}">${escapeAndroid(translation)}</string>`;
+      }),
+      ...missingPlurals.map(([name, quantities]) =>
+        [
+          `<plurals name="${name}">`,
+          ...[...quantities].map(([quantity, value]) => {
+            assertNoControlChars(name, value);
+            return `${indent}${INDENT_STEP}<item quantity="${quantity}">${escapeAndroid(value)}</item>`;
+          }),
+          `${indent}</plurals>`,
+        ].join('\n')
+      ),
+    ];
+
+    return insertBlocksAt(content, at, indent, blocks);
   }
 
   private rewriteInner(element: ScannedElement, inner: string): string {
diff --git a/src/formats/ios-strings.ts b/src/formats/ios-strings.ts
index c7d2f33e..a7ff1de4 100644
--- a/src/formats/ios-strings.ts
+++ b/src/formats/ios-strings.ts
@@ -3,6 +3,7 @@ import type {
   FormatParser,
   TranslatedEntry,
 } from './format.js';
+import { appendEntryLines } from './util/append-lines.js';
 import { isForbiddenControlChar } from './util/control-chars.js';
 
 const ENTRY_RE = /^\s*"((?:[^"\\]|\\.)*)"\s*=\s*"((?:[^"\\]|\\.)*)"\s*;\s*$/;
@@ -83,6 +84,7 @@ export class IosStringsFormatParser implements FormatParser {
 
     const lines = content.split(/\r?\n/);
     const result: string[] = [];
+    const slotted = new Set<string>();
     let pendingComments: string[] = [];
     let inBlockComment = false;
 
@@ -98,6 +100,7 @@ export class IosStringsFormatParser implements FormatParser {
       const match = ENTRY_RE.exec(line);
       if (match) {
         const key = this.unescape(match[1]!);
+        slotted.add(key);
         const translation = translations.get(key);
         if (translation !== undefined) {
           result.push(...pendingComments);
@@ -129,6 +132,16 @@ export class IosStringsFormatParser implements FormatParser {
     }
     result.push(...pendingComments);
 
+    // A key with no line in the template is one added to the source since this
+    // target file was written. Dropping it loses the string with no trace: the
+    // caller has no way to tell a key it asked for from one it did not.
+    const appended: string[] = [];
+    for (const [key, translation] of translations) {
+      if (slotted.has(key)) continue;
+      appended.push(`"${this.escape(key)}" = "${this.escape(translation)}";`);
+    }
+    appendEntryLines(result, appended);
+
     return result.join('\n');
   }
 
diff --git a/src/formats/php-arrays.ts b/src/formats/php-arrays.ts
index 6a918637..f326493f 100644
--- a/src/formats/php-arrays.ts
+++ b/src/formats/php-arrays.ts
@@ -62,12 +62,14 @@ interface PhpString extends PhpNode {
 interface PhpArray extends PhpNode {
   readonly kind: 'array';
   readonly items: readonly PhpEntry[];
+  readonly loc?: PhpLoc;
 }
 
 interface PhpEntry extends PhpNode {
   readonly kind: 'entry';
   readonly key: PhpNode | null;
   readonly value: PhpNode;
+  readonly loc?: PhpLoc;
 }
 
 interface PhpReturn extends PhpNode {
@@ -173,11 +175,6 @@ export class PhpArraysFormatParser implements FormatParser {
     const locMap = new Map<string, StringLoc>();
     collectStringLocs(returnNode.expr as PhpArray, '', locMap);
 
-    interface Replacement {
-      start: number;
-      end: number;
-      literal: string;
-    }
     const replacements: Replacement[] = [];
     for (const entry of entries) {
       const loc = locMap.get(entry.key);
@@ -188,6 +185,13 @@ export class PhpArraysFormatParser implements FormatParser {
         literal: encodePhpString(entry.translation, loc.isDoubleQuote),
       });
     }
+    replacements.push(
+      ...planInsertions(
+        body,
+        returnNode.expr as PhpArray,
+        entries.filter((entry) => !locMap.has(entry.key))
+      )
+    );
     replacements.sort((a, b) => b.start - a.start);
 
     let result = body;
@@ -204,6 +208,157 @@ interface StringLoc {
   readonly isDoubleQuote: boolean;
 }
 
+/** A span of `body` to overwrite; an insertion has `start === end`. */
+interface Replacement {
+  start: number;
+  end: number;
+  literal: string;
+}
+
+const PHP_INDENT_STEP = '    ';
+
+/** The run of spaces and tabs starting the line `offset` falls on. */
+function lineIndentAt(body: string, offset: number): string {
+  const lineStart = body.lastIndexOf('\n', offset - 1) + 1;
+  return /^[ \t]*/.exec(body.slice(lineStart, offset))![0];
+}
+
+function collectArrays(
+  arr: PhpArray,
+  prefix: string,
+  out: Map<string, PhpArray>
+): void {
+  out.set(prefix, arr);
+  for (const item of arr.items) {
+    if (item.kind !== 'entry' || item.key?.kind !== 'string') continue;
+    const keyStr = (item.key as PhpString).value;
+    const dotPath = prefix ? `${prefix}.${keyStr}` : keyStr;
+    if (item.value.kind === 'array') {
+      collectArrays(item.value as PhpArray, dotPath, out);
+    }
+  }
+}
+
+/** Where a new element goes in `arr`, and the style to write it in. */
+interface ArraySlot {
+  /** Offset to splice at. */
+  at: number;
+  /** Text opening each new element, carrying the array's own line layout. */
+  lead: string;
+  /** Text preceding the first new element, separating it from the last one. */
+  prefix: string;
+  /** Text following the last new element. */
+  suffix: string;
+  keyIsDoubleQuote: boolean;
+  valueIsDoubleQuote: boolean;
+}
+
+function arraySlot(body: string, arr: PhpArray): ArraySlot | undefined {
+  if (!arr.loc) return undefined;
+  const closeAt = arr.loc.end.offset - 1;
+  // An array written on one line stays on one line; one already spanning lines
+  // gets a line per element, indented like the element it follows.
+  const multiline = body
+    .slice(arr.loc.start.offset, arr.loc.end.offset)
+    .includes('\n');
+  const lastItem = arr.items[arr.items.length - 1];
+
+  if (!lastItem?.loc) {
+    // An empty array has no element to sit beside, so the new ones become its
+    // body, written just inside the opening bracket — `[` for the short form,
+    // `(` for `array(...)`. Writing before the closing bracket instead would
+    // leave the newline already separating the two, and emit a blank line.
+    const open = /[[(]/.exec(body.slice(arr.loc.start.offset, closeAt + 1));
+    if (!open) return undefined;
+    return {
+      at: arr.loc.start.offset + open.index + 1,
+      lead: multiline
+        ? `\n${lineIndentAt(body, arr.loc.start.offset)}${PHP_INDENT_STEP}`
+        : '',
+      prefix: '',
+      suffix: '',
+      keyIsDoubleQuote: false,
+      valueIsDoubleQuote: false,
+    };
+  }
+
+  // A trailing comma after the last element is optional in PHP. Where one is
+  // there the new elements follow it and keep it; where it is not, adding one
+  // to the previous last element is unavoidable but adding another to the new
+  // one would change a style the file chose.
+  const tail = body.slice(lastItem.loc.end.offset, closeAt);
+  const commaAt = tail.indexOf(',');
+  const terminated = commaAt !== -1 && tail.slice(0, commaAt).trim() === '';
+  const lastValue = lastItem.value;
+  return {
+    at: terminated
+      ? lastItem.loc.end.offset + commaAt + 1
+      : lastItem.loc.end.offset,
+    lead: multiline
+      ? `\n${lineIndentAt(body, lastItem.loc.start.offset)}`
+      : ' ',
+    prefix: terminated ? '' : ',',
+    suffix: terminated ? ',' : '',
+    keyIsDoubleQuote:
+      lastItem.key?.kind === 'string' &&
+      (lastItem.key as PhpString).isDoubleQuote,
+    valueIsDoubleQuote:
+      lastValue.kind === 'string' && (lastValue as PhpString).isDoubleQuote,
+  };
+}
+
+/**
+ * Plan an element for every entry the file has no string literal for. Such an
+ * entry is a key added to the source file after this target was written: the
+ * target is the reconstruct template, so a span-surgical rewrite has nothing to
+ * overwrite, and dropping the entry loses the string with nothing to
+ * distinguish it from a key never asked for.
+ *
+ * A key whose parent array is itself absent is left out: creating the
+ * intervening arrays would guess at a structure the source file already
+ * defines.
+ */
+function planInsertions(
+  body: string,
+  root: PhpArray,
+  missing: readonly TranslatedEntry[]
+): Replacement[] {
+  if (missing.length === 0) return [];
+
+  const arrays = new Map<string, PhpArray>();
+  collectArrays(root, '', arrays);
+
+  const byParent = new Map<string, TranslatedEntry[]>();
+  for (const entry of missing) {
+    const lastDot = entry.key.lastIndexOf('.');
+    const parent = lastDot === -1 ? '' : entry.key.slice(0, lastDot);
+    if (!arrays.has(parent)) continue;
+    const group = byParent.get(parent);
+    if (group) group.push(entry);
+    else byParent.set(parent, [entry]);
+  }
+
+  const insertions: Replacement[] = [];
+  for (const [parent, group] of byParent) {
+    const slot = arraySlot(body, arrays.get(parent)!);
+    if (!slot) continue;
+    const elements = group.map((entry) => {
+      const leaf = parent ? entry.key.slice(parent.length + 1) : entry.key;
+      return (
+        slot.lead +
+        `${encodePhpString(leaf, slot.keyIsDoubleQuote)} => ` +
+        `${encodePhpString(entry.translation, slot.valueIsDoubleQuote)}`
+      );
+    });
+    insertions.push({
+      start: slot.at,
+      end: slot.at,
+      literal: slot.prefix + elements.join(',') + slot.suffix,
+    });
+  }
+  return insertions;
+}
+
 function collectStringLocs(
   arr: PhpArray,
   prefix: string,
diff --git a/src/formats/properties.ts b/src/formats/properties.ts
index cb74193a..72cff890 100644
--- a/src/formats/properties.ts
+++ b/src/formats/properties.ts
@@ -4,6 +4,7 @@ import type {
   TranslatedEntry,
 } from './format.js';
 import { PendingCommentBuffer } from './pending-comment-buffer.js';
+import { appendEntryLines } from './util/append-lines.js';
 import { isForbiddenControlChar } from './util/control-chars.js';
 
 const ENTRY_RE = /^([^=:#!\s][^=:]*?)\s*[=:]\s*(.*)/;
@@ -79,6 +80,7 @@ export class PropertiesFormatParser implements FormatParser {
     const lines = content.split(/\r?\n/);
     const result: string[] = [];
     const pending = new PendingCommentBuffer();
+    const slotted = new Set<string>();
 
     for (let i = 0; i < lines.length; i++) {
       let line = lines[i]!;
@@ -104,6 +106,7 @@ export class PropertiesFormatParser implements FormatParser {
       const match = ENTRY_RE.exec(line);
       if (match) {
         const key = this.unescapeKey(match[1]!.trim());
+        slotted.add(key);
         const translation = translations.get(key);
         if (translation !== undefined) {
           pending.flushToOutput(result);
@@ -125,6 +128,16 @@ export class PropertiesFormatParser implements FormatParser {
     }
     pending.flushToOutput(result);
 
+    // A key with no line in the template is one added to the source since this
+    // target file was written. Dropping it loses the string with no trace: the
+    // caller has no way to tell a key it asked for from one it did not.
+    const appended: string[] = [];
+    for (const [key, translation] of translations) {
+      if (slotted.has(key)) continue;
+      appended.push(`${this.escapeKey(key)}=${this.escapeValue(translation)}`);
+    }
+    appendEntryLines(result, appended);
+
     return result.join('\n');
   }
 
diff --git a/src/formats/util/append-lines.ts b/src/formats/util/append-lines.ts
new file mode 100644
index 00000000..e56fc003
--- /dev/null
+++ b/src/formats/util/append-lines.ts
@@ -0,0 +1,22 @@
+/**
+ * Append lines to a line-based `reconstruct` result.
+ *
+ * The result array comes from splitting on the line terminator, so a file that
+ * ends with a newline leaves a final empty element. Pushing onto the end of that
+ * would emit a blank line before the new content and leave the file without a
+ * terminator, so the empty element is lifted over the appended lines.
+ *
+ * Shared by the .properties and iOS .strings parsers.
+ */
+export function appendEntryLines(
+  result: string[],
+  lines: readonly string[]
+): void {
+  if (lines.length === 0) return;
+  const trailing =
+    result.length > 0 && result[result.length - 1] === ''
+      ? result.pop()
+      : undefined;
+  result.push(...lines);
+  if (trailing !== undefined) result.push(trailing);
+}
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index afe554d6..8b5c641c 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -10,6 +10,8 @@ import {
 } from './util/control-chars.js';
 import {
   findElement,
+  insertBlocksAt,
+  lineIndentAt,
   replaceElements,
   scanElements,
   type ElementPattern,
@@ -51,6 +53,20 @@ const SEGMENT_EL: ElementPattern = {
   close: /<\/(?:\w+:)?segment>/iy,
 };
 
+// The element a new unit is written into when the document holds none to sit
+// beside: `<body>` in 1.2, `<file>` in 2.0 (which has no `<body>`).
+const BODY_EL: ElementPattern = {
+  open: /<(?:\w+:)?body(?:\s[^><]*)?>/iy,
+  close: /<\/(?:\w+:)?body>/iy,
+};
+
+const FILE_EL: ElementPattern = {
+  open: /<(?:\w+:)?file(?:\s[^><]*)?>/iy,
+  close: /<\/(?:\w+:)?file>/iy,
+};
+
+const INDENT_STEP = '  ';
+
 const TRANSLATABLE_EL: ElementPattern = {
   open: /<(?:\w+:)?(?:source|target)(?:\s[^><]*)?>/iy,
   close: /<\/(?:\w+:)?(?:source|target)>/iy,
@@ -228,16 +244,17 @@ export class XliffFormatParser implements FormatParser {
 
   reconstruct(content: string, entries: TranslatedEntry[]): string {
     assertNoCdataInTranslatable(content);
-    const version = detectVersion(content);
+    const isV2 = detectVersion(content) === '2.0';
     const translations = new Map<string, string>();
     for (const entry of entries) {
       translations.set(entry.key, entry.translation);
     }
 
-    if (version === '2.0') {
-      return this.reconstructV2(content, translations);
-    }
-    return this.reconstructV12(content, translations);
+    const slotted = new Set<string>();
+    const rewritten = isV2
+      ? this.reconstructV2(content, translations, slotted)
+      : this.reconstructV12(content, translations, slotted);
+    return this.writeMissingUnits(rewritten, entries, slotted, isV2);
   }
 
   extractContext(content: string, key: string): string | undefined {
@@ -287,11 +304,74 @@ export class XliffFormatParser implements FormatParser {
     return entry;
   }
 
+  /**
+   * Write a unit for every entry the document has no `id` for. Such an entry is
+   * a key added to the source file after this target was written: the target is
+   * the reconstruct template, so it has no slot, and dropping the entry loses
+   * the string with nothing to distinguish it from a key never asked for.
+   */
+  private writeMissingUnits(
+    content: string,
+    entries: readonly TranslatedEntry[],
+    slotted: ReadonlySet<string>,
+    isV2: boolean
+  ): string {
+    const missing = entries.filter((entry) => !slotted.has(entry.key));
+    if (missing.length === 0) return content;
+
+    const units = scanElements(content, isV2 ? UNIT_EL : TRANS_UNIT_EL);
+    const anchor = units[units.length - 1];
+    let at: number;
+    let indent: string;
+    if (anchor) {
+      at = anchor.end;
+      indent = lineIndentAt(content, anchor.start);
+    } else {
+      const container = findElement(content, isV2 ? FILE_EL : BODY_EL);
+      if (!container) return content;
+      at = container.start + container.openTag.length;
+      indent = lineIndentAt(content, container.start) + INDENT_STEP;
+    }
+    // Namespace prefix taken from the element being written beside, the way
+    // applyTarget takes it from the <source> it inserts after.
+    const ns =
+      (anchor ? /^<(\w+:)/.exec(anchor.openTag)?.[1] : undefined) ?? '';
+
+    const blocks = missing.map((entry) => {
+      assertNoControlChars(entry.key, entry.translation);
+      const inner = isV2
+        ? indent + INDENT_STEP.repeat(2)
+        : indent + INDENT_STEP;
+      const body = [
+        `${inner}<${ns}source>${escapeXml(entry.value)}</${ns}source>`,
+        `${inner}<${ns}target>${escapeXml(entry.translation)}</${ns}target>`,
+      ];
+      if (!isV2) {
+        return [
+          `<${ns}trans-unit id="${entry.key}">`,
+          ...body,
+          `${indent}</${ns}trans-unit>`,
+        ].join('\n');
+      }
+      return [
+        `<${ns}unit id="${entry.key}">`,
+        `${indent}${INDENT_STEP}<${ns}segment>`,
+        ...body,
+        `${indent}${INDENT_STEP}</${ns}segment>`,
+        `${indent}</${ns}unit>`,
+      ].join('\n');
+    });
+
+    return insertBlocksAt(content, at, indent, blocks);
+  }
+
   private reconstructV12(
     content: string,
-    translations: Map<string, string>
+    translations: Map<string, string>,
+    slotted: Set<string>
   ): string {
     const result = replaceElements(content, TRANS_UNIT_EL, (element) => {
+      slotted.add(element.groups[0]!);
       const translation = translations.get(element.groups[0]!);
       if (translation === undefined) return '';
       assertNoControlChars(element.groups[0]!, translation);
@@ -305,9 +385,11 @@ export class XliffFormatParser implements FormatParser {
 
   private reconstructV2(
     content: string,
-    translations: Map<string, string>
+    translations: Map<string, string>,
+    slotted: Set<string>
   ): string {
     const result = replaceElements(content, UNIT_EL, (element) => {
+      slotted.add(element.groups[0]!);
       const translation = translations.get(element.groups[0]!);
       if (translation === undefined) return '';
       assertNoControlChars(element.groups[0]!, translation);
diff --git a/src/formats/xml-scan.ts b/src/formats/xml-scan.ts
index 6b553f2c..375cf2e8 100644
--- a/src/formats/xml-scan.ts
+++ b/src/formats/xml-scan.ts
@@ -147,6 +147,32 @@ export function findElement(
   return nextElement(content, 0, pattern);
 }
 
+/** The run of spaces and tabs starting the line `index` falls on. */
+export function lineIndentAt(content: string, index: number): string {
+  const lineStart = content.lastIndexOf('\n', index - 1) + 1;
+  return /^[ \t]*/.exec(content.slice(lineStart, index))![0];
+}
+
+/**
+ * Splice `blocks` into `content` at `at`, each opening on its own line at
+ * `indent`. Used to write an element the document has no slot for; a block
+ * spanning several lines carries its own indentation for the lines after the
+ * first.
+ */
+export function insertBlocksAt(
+  content: string,
+  at: number,
+  indent: string,
+  blocks: readonly string[]
+): string {
+  if (blocks.length === 0) return content;
+  return (
+    content.slice(0, at) +
+    blocks.map((block) => `\n${indent}${block}`).join('') +
+    content.slice(at)
+  );
+}
+
 /**
  * Rewrite every element matching `pattern`. Returning null drops the element
  * along with its leading indentation and the whitespace that follows it.
diff --git a/tests/e2e/cli-sync-new-source-key.e2e.test.ts b/tests/e2e/cli-sync-new-source-key.e2e.test.ts
new file mode 100644
index 00000000..256bf6b1
--- /dev/null
+++ b/tests/e2e/cli-sync-new-source-key.e2e.test.ts
@@ -0,0 +1,215 @@
+/**
+ * E2E regression for cli-8kr2.60.
+ *
+ * `deepl sync` uses an existing target file as the reconstruct template, so a
+ * key added to the source after the first run has no slot in it. Five parsers
+ * dropped such an entry, and every reporting surface then agreed the work was
+ * done: the run exited 0 claiming the key translated, the lockfile recorded
+ * `status: "translated"`, `sync status` reported the locale 100% complete with 0
+ * missing, `sync --frozen` — the CI drift gate — exited 0, and `sync validate`
+ * passed because it only sees keys the target file actually has. The characters
+ * were billed and the string was permanently absent from the shipped locale.
+ */
+
+import { spawn, spawnSync, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+
+interface FormatCase {
+  label: string;
+  bucket: string;
+  file: string;
+  v1: string;
+  v2: string;
+}
+
+const CASES: FormatCase[] = [
+  {
+    label: 'properties',
+    bucket: 'properties',
+    file: 'app.properties',
+    v1: 'greeting=Hello\n',
+    v2: 'greeting=Hello\nadded=Translate me\n',
+  },
+  {
+    label: 'ios_strings',
+    bucket: 'ios_strings',
+    file: 'app.strings',
+    v1: '"greeting" = "Hello";\n',
+    v2: '"greeting" = "Hello";\n"added" = "Translate me";\n',
+  },
+  {
+    label: 'laravel_php',
+    bucket: 'laravel_php',
+    file: 'app.php',
+    v1: "<?php\n\nreturn [\n    'greeting' => 'Hello',\n];\n",
+    v2: "<?php\n\nreturn [\n    'greeting' => 'Hello',\n    'added' => 'Translate me',\n];\n",
+  },
+  {
+    label: 'android_xml',
+    bucket: 'android_xml',
+    file: 'strings.xml',
+    v1: '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n    <string name="greeting">Hello</string>\n</resources>\n',
+    v2: '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n    <string name="greeting">Hello</string>\n    <string name="added">Translate me</string>\n</resources>\n',
+  },
+  {
+    label: 'xliff',
+    bucket: 'xliff',
+    file: 'app.xlf',
+    v1: [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<xliff version="1.2">',
+      '  <file source-language="en" datatype="plaintext" original="app">',
+      '    <body>',
+      '      <trans-unit id="greeting">',
+      '        <source>Hello</source>',
+      '      </trans-unit>',
+      '    </body>',
+      '  </file>',
+      '</xliff>',
+      '',
+    ].join('\n'),
+    v2: [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<xliff version="1.2">',
+      '  <file source-language="en" datatype="plaintext" original="app">',
+      '    <body>',
+      '      <trans-unit id="greeting">',
+      '        <source>Hello</source>',
+      '      </trans-unit>',
+      '      <trans-unit id="added">',
+      '        <source>Translate me</source>',
+      '      </trans-unit>',
+      '    </body>',
+      '  </file>',
+      '</xliff>',
+      '',
+    ].join('\n'),
+  },
+];
+
+describe('CLI sync with a key added to the source after the first run', () => {
+  const testConfig = createTestConfigDir('e2e-sync-newkey');
+  const testFiles = createTestDir('e2e-sync-newkey-files');
+  let mockServer: ChildProcess;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'node',
+        [path.join(__dirname, 'mock-deepl-server.cjs')],
+        { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env } }
+      );
+      mockServer = child;
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = /PORT=(\d+)/.exec(output);
+        if (match) resolve(parseInt(match[1]!, 10));
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  function run(
+    cwd: string,
+    args: string[]
+  ): { status: number | null; output: string } {
+    const { CI: _ci, DEEPL_API_KEY: _key, ...rest } = process.env;
+    const result = spawnSync('node', [CLI_PATH, ...args], {
+      encoding: 'utf-8',
+      cwd,
+      env: { ...rest, DEEPL_CONFIG_DIR: testConfig.path, NO_COLOR: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60000,
+    });
+    return {
+      status: result.status,
+      output: (result.stdout ?? '') + (result.stderr ?? ''),
+    };
+  }
+
+  beforeAll(async () => {
+    const port = await startMockServer();
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+      })
+    );
+  }, 30000);
+
+  afterAll(() => {
+    if (mockServer) mockServer.kill('SIGTERM');
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  describe.each(CASES)('$label', ({ bucket, file, v1, v2 }) => {
+    it('writes the key, and every reporting surface agrees', () => {
+      const projectRoot = path.join(testFiles.path, bucket);
+      fs.mkdirSync(path.join(projectRoot, 'locales', 'en'), {
+        recursive: true,
+      });
+      fs.writeFileSync(
+        path.join(projectRoot, '.deepl-sync.yaml'),
+        [
+          'version: 1',
+          'source_locale: en',
+          'target_locales:',
+          '  - es',
+          'buckets:',
+          `  ${bucket}:`,
+          '    include:',
+          `      - "locales/en/${file}"`,
+          '',
+        ].join('\n')
+      );
+      const sourcePath = path.join(projectRoot, 'locales', 'en', file);
+      const targetPath = path.join(projectRoot, 'locales', 'es', file);
+
+      fs.writeFileSync(sourcePath, v1);
+      expect(run(projectRoot, ['sync', '--yes']).status).toBe(0);
+      expect(fs.readFileSync(targetPath, 'utf-8')).toContain('Hola');
+
+      // A contributor adds a string to the source and syncs again.
+      fs.writeFileSync(sourcePath, v2);
+      const second = run(projectRoot, ['sync', '--yes']);
+      expect(second.status).toBe(0);
+
+      const written = fs.readFileSync(targetPath, 'utf-8');
+      expect(written).toContain('Traduceme');
+      expect(written).toContain('Hola');
+
+      // The lockfile's `translated` claim now describes the file on disk, so
+      // the gates that read it are telling the truth rather than agreeing with
+      // a record of work that never landed.
+      const status = run(projectRoot, ['sync', 'status']);
+      expect(status.status).toBe(0);
+      expect(status.output).toContain('100%');
+      expect(status.output).toContain('0 missing');
+
+      expect(run(projectRoot, ['sync', '--frozen']).status).toBe(0);
+
+      const validate = run(projectRoot, ['sync', 'validate']);
+      expect(validate.status).toBe(0);
+      expect(validate.output).toContain('Checked 2 translations');
+    }, 60000);
+  });
+});
diff --git a/tests/helpers/sync-harness.ts b/tests/helpers/sync-harness.ts
index bf3f519c..d6cd2e5e 100644
--- a/tests/helpers/sync-harness.ts
+++ b/tests/helpers/sync-harness.ts
@@ -29,6 +29,7 @@ import { TomlFormatParser } from '../../src/formats/toml';
 import { ArbFormatParser } from '../../src/formats/arb';
 import { IosStringsFormatParser } from '../../src/formats/ios-strings';
 import { PropertiesFormatParser } from '../../src/formats/properties';
+import { PhpArraysFormatParser } from '../../src/formats/php-arrays';
 import type { FormatParser } from '../../src/formats/index';
 import type { SyncLockFile, SyncLockEntry } from '../../src/sync/types';
 import {
@@ -52,7 +53,8 @@ export type SupportedParser =
   | 'toml'
   | 'arb'
   | 'ios_strings'
-  | 'properties';
+  | 'properties'
+  | 'laravel_php';
 
 export interface SyncHarness {
   client: DeepLClient;
@@ -123,6 +125,8 @@ function parserFor(name: SupportedParser): FormatParser {
       return new IosStringsFormatParser();
     case 'properties':
       return new PropertiesFormatParser();
+    case 'laravel_php':
+      return new PhpArraysFormatParser();
   }
 }
 
diff --git a/tests/integration/sync-new-source-key.integration.test.ts b/tests/integration/sync-new-source-key.integration.test.ts
new file mode 100644
index 00000000..98cefd9f
--- /dev/null
+++ b/tests/integration/sync-new-source-key.integration.test.ts
@@ -0,0 +1,217 @@
+/**
+ * Integration tests for a key added to a source file after the first sync.
+ *
+ * From the second run onwards the target file is the reconstruct template —
+ * that is how the translations it already holds survive — so a key added to the
+ * source since has no slot in it. Five of the eleven parsers used to drop such
+ * an entry, and nothing downstream could tell: the key was translated, billed,
+ * and recorded in the lockfile as `translated` while never reaching the file, so
+ * `status` reported the locale complete and no later run revisited the string.
+ *
+ * The run that matters is therefore the second one, against a target that
+ * already exists.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import type { SupportedParser } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import type { SyncLockFile } from '../../src/sync/types';
+
+interface FormatCase {
+  label: string;
+  parser: SupportedParser;
+  file: string;
+  /** Source holding `greeting` only. */
+  v1: string;
+  /** The same source with `added` appended. */
+  v2: string;
+}
+
+const CASES: FormatCase[] = [
+  {
+    label: 'Java Properties',
+    parser: 'properties',
+    file: 'app.properties',
+    v1: 'greeting=Hello\n',
+    v2: 'greeting=Hello\nadded=Translate me\n',
+  },
+  {
+    label: 'iOS .strings',
+    parser: 'ios_strings',
+    file: 'app.strings',
+    v1: '"greeting" = "Hello";\n',
+    v2: '"greeting" = "Hello";\n"added" = "Translate me";\n',
+  },
+  {
+    label: 'Laravel PHP',
+    parser: 'laravel_php',
+    file: 'app.php',
+    v1: "<?php\n\nreturn [\n    'greeting' => 'Hello',\n];\n",
+    v2: "<?php\n\nreturn [\n    'greeting' => 'Hello',\n    'added' => 'Translate me',\n];\n",
+  },
+  {
+    label: 'Android XML',
+    parser: 'android_xml',
+    file: 'strings.xml',
+    v1: '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n    <string name="greeting">Hello</string>\n</resources>\n',
+    v2: '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n    <string name="greeting">Hello</string>\n    <string name="added">Translate me</string>\n</resources>\n',
+  },
+  {
+    label: 'XLIFF 1.2',
+    parser: 'xliff',
+    file: 'app.xlf',
+    v1: [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<xliff version="1.2">',
+      '  <file source-language="en" datatype="plaintext" original="app">',
+      '    <body>',
+      '      <trans-unit id="greeting">',
+      '        <source>Hello</source>',
+      '      </trans-unit>',
+      '    </body>',
+      '  </file>',
+      '</xliff>',
+      '',
+    ].join('\n'),
+    v2: [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<xliff version="1.2">',
+      '  <file source-language="en" datatype="plaintext" original="app">',
+      '    <body>',
+      '      <trans-unit id="greeting">',
+      '        <source>Hello</source>',
+      '      </trans-unit>',
+      '      <trans-unit id="added">',
+      '        <source>Translate me</source>',
+      '      </trans-unit>',
+      '    </body>',
+      '  </file>',
+      '</xliff>',
+      '',
+    ].join('\n'),
+  },
+  {
+    label: 'JSON',
+    parser: 'json',
+    file: 'app.json',
+    v1: '{\n  "greeting": "Hello"\n}\n',
+    v2: '{\n  "greeting": "Hello",\n  "added": "Translate me"\n}\n',
+  },
+];
+
+function replyWith(text: string): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .post('/v2/translate')
+    .reply(200, {
+      translations: [
+        {
+          text,
+          detected_source_language: 'EN',
+          billed_characters: text.length,
+        },
+      ],
+    });
+}
+
+describe('sync with a key added to the source after the first run', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  describe.each(CASES)('$label', ({ parser, file, v1, v2 }) => {
+    it('writes the new key into the existing target file', async () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-newkey-'));
+      harness = createSyncHarness({ parsers: [parser] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { [parser]: { include: [`locales/en/${file}`] } },
+      });
+      const sourcePath = path.join(tmpDir, 'locales', 'en', file);
+      fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+
+      fs.writeFileSync(sourcePath, v1, 'utf-8');
+      replyWith('Hola');
+      const first = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+      expect(first.success).toBe(true);
+
+      const targetPath = path.join(tmpDir, 'locales', 'es', file);
+      expect(fs.readFileSync(targetPath, 'utf-8')).toContain('Hola');
+
+      fs.writeFileSync(sourcePath, v2, 'utf-8');
+      replyWith('Traduceme');
+      const second = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(second.success).toBe(true);
+      expect(second.newKeys).toBe(1);
+
+      const written = fs.readFileSync(targetPath, 'utf-8');
+      const translations = harness.registry
+        .getParserByFormatKey(parser)!
+        .extract(written);
+      const keys = translations.map((e) => e.key);
+      expect(keys).toContain('added');
+      expect(keys).toContain('greeting');
+
+      // The reviewed translation the file already held is untouched.
+      expect(written).toContain('Hola');
+      expect(written).toContain('Traduceme');
+    });
+
+    it('records the new key as translated only because it was written', async () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-newkey-'));
+      harness = createSyncHarness({ parsers: [parser] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { [parser]: { include: [`locales/en/${file}`] } },
+      });
+      const sourcePath = path.join(tmpDir, 'locales', 'en', file);
+      fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+
+      fs.writeFileSync(sourcePath, v1, 'utf-8');
+      replyWith('Hola');
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      fs.writeFileSync(sourcePath, v2, 'utf-8');
+      replyWith('Traduceme');
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      const lock = JSON.parse(
+        fs.readFileSync(path.join(tmpDir, '.deepl-sync.lock'), 'utf-8')
+      ) as SyncLockFile;
+      const fileEntries = Object.values(lock.entries)[0]!;
+      expect(fileEntries['added']?.translations['es']?.status).toBe(
+        'translated'
+      );
+
+      const written = fs.readFileSync(
+        path.join(tmpDir, 'locales', 'es', file),
+        'utf-8'
+      );
+      const holds = harness.registry
+        .getParserByFormatKey(parser)!
+        .extract(written)
+        .map((e) => e.key);
+      expect(holds).toContain('added');
+    });
+  });
+});
diff --git a/tests/unit/formats/android-xml.test.ts b/tests/unit/formats/android-xml.test.ts
index e024546c..a9a68d3f 100644
--- a/tests/unit/formats/android-xml.test.ts
+++ b/tests/unit/formats/android-xml.test.ts
@@ -320,6 +320,123 @@ describe('android-xml parser', () => {
     });
   });
 
+  describe('writing a resource the document has no element for', () => {
+    it('should write into a <resources> holding nothing', () => {
+      const xml = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<resources>',
+        '</resources>',
+        '',
+      ].join('\n');
+      const result = parser.reconstruct(xml, [
+        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+      ]);
+
+      expect(result).toContain('    <string name="greeting">Hallo</string>');
+      expect(parser.extract(result).map((e) => e.key)).toEqual(['greeting']);
+    });
+
+    it('should write a <plurals> block with every quantity', () => {
+      const xml = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<resources>',
+        '    <string name="greeting">Hallo</string>',
+        '</resources>',
+        '',
+      ].join('\n');
+      const entries: TranslatedEntry[] = [
+        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+        {
+          key: 'items',
+          value: 'items',
+          translation: 'Elemente',
+          metadata: {
+            plurals: [
+              { quantity: 'one', value: 'Ein Element' },
+              { quantity: 'other', value: 'Elemente' },
+            ],
+          },
+        },
+      ];
+      const result = parser.reconstruct(xml, entries);
+
+      expect(result).toContain('    <plurals name="items">');
+      expect(result).toContain(
+        '        <item quantity="one">Ein Element</item>'
+      );
+      expect(result).toContain(
+        '        <item quantity="other">Elemente</item>'
+      );
+      expect(result).toContain('    </plurals>');
+
+      const reread = parser.extract(result);
+      expect(reread.map((e) => e.key).sort()).toEqual(['greeting', 'items']);
+      expect(
+        reread.find((e) => e.key === 'items')?.metadata?.['plurals']
+      ).toEqual([
+        { quantity: 'one', value: 'Ein Element' },
+        { quantity: 'other', value: 'Elemente' },
+      ]);
+    });
+
+    it('should anchor beside a <plurals> when the file holds no <string>', () => {
+      const xml = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<resources>',
+        '    <plurals name="items">',
+        '        <item quantity="other">Elemente</item>',
+        '    </plurals>',
+        '</resources>',
+        '',
+      ].join('\n');
+      const result = parser.reconstruct(xml, [
+        {
+          key: 'items',
+          value: 'items',
+          translation: 'Elemente',
+          metadata: { plurals: [{ quantity: 'other', value: 'Elemente' }] },
+        },
+        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+      ]);
+
+      expect(result).toContain('    </plurals>\n    <string name="greeting">');
+      expect(
+        parser
+          .extract(result)
+          .map((e) => e.key)
+          .sort()
+      ).toEqual(['greeting', 'items']);
+    });
+
+    it('should leave a <string-array> item key alone rather than invent a resource for it', () => {
+      const xml = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<resources>',
+        '    <string-array name="colours">',
+        '        <item>Rot</item>',
+        '    </string-array>',
+        '</resources>',
+        '',
+      ].join('\n');
+      const result = parser.reconstruct(xml, [
+        { key: 'colours.0', value: 'Red', translation: 'Rot' },
+        { key: 'colours.1', value: 'Blue', translation: 'Blau' },
+      ]);
+
+      expect(result).not.toContain('name="colours.1"');
+      expect(parser.extract(result).map((e) => e.key)).toEqual(['colours.0']);
+    });
+
+    it('should leave a resource out when the document has no <resources>', () => {
+      const notResources = '<?xml version="1.0"?>\n<other/>\n';
+      expect(
+        parser.reconstruct(notResources, [
+          { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+        ])
+      ).toBe(notResources);
+    });
+  });
+
   describe('elements with no closing tag', () => {
     const unclosed = `<?xml version="1.0" encoding="utf-8"?>
 <resources>
diff --git a/tests/unit/formats/ios-strings.test.ts b/tests/unit/formats/ios-strings.test.ts
index 2f4d388f..e3465444 100644
--- a/tests/unit/formats/ios-strings.test.ts
+++ b/tests/unit/formats/ios-strings.test.ts
@@ -222,6 +222,39 @@ describe('ios-strings parser', () => {
     });
   });
 
+  describe('reconstruct writing a key the file has no line for', () => {
+    it('should write the key and keep the trailing newline', () => {
+      const result = parser.reconstruct('"greeting" = "Hello";\n', [
+        { key: 'greeting', value: 'Hello', translation: 'Hola' },
+        { key: 'added', value: 'Goodbye', translation: 'Adios' },
+      ]);
+      expect(result).toBe('"greeting" = "Hola";\n"added" = "Adios";\n');
+    });
+
+    it('should keep a dangling comment above a written key', () => {
+      const result = parser.reconstruct('/* Header */\n', [
+        { key: 'added', value: 'Goodbye', translation: 'Adios' },
+      ]);
+      expect(result).toBe('/* Header */\n"added" = "Adios";\n');
+    });
+
+    it('should escape a written key and value', () => {
+      const result = parser.reconstruct('"greeting" = "Hello";\n', [
+        { key: 'greeting', value: 'Hello', translation: 'Hola' },
+        { key: 'say "it"', value: 'x', translation: 'di "eso"' },
+      ]);
+      expect(result).toContain('"say \\"it\\"" = "di \\"eso\\"";');
+      expect(
+        new Map(parser.extract(result).map((e) => [e.key, e.value]))
+      ).toEqual(
+        new Map([
+          ['greeting', 'Hola'],
+          ['say "it"', 'di "eso"'],
+        ])
+      );
+    });
+  });
+
   describe('reconstruct with $-patterns in translations', () => {
     it('should preserve literal dollar signs like Pay $5.99', () => {
       const content = '"price_label" = "Price";';
diff --git a/tests/unit/formats/new-key-insert.test.ts b/tests/unit/formats/new-key-insert.test.ts
new file mode 100644
index 00000000..13f8dd60
--- /dev/null
+++ b/tests/unit/formats/new-key-insert.test.ts
@@ -0,0 +1,342 @@
+/**
+ * Tests that `reconstruct` writes an entry the template has no slot for.
+ *
+ * On the first sync there is no target file, so the SOURCE is the template and
+ * every key already has a slot. From the second run onwards the target file is
+ * the template — which is how the existing translations survive — and a key
+ * added to the source since has no slot in it. A parser that only rewrites the
+ * slots it finds drops that entry, and `sync` has no way to tell: it records the
+ * key as translated, so `status` reports the locale complete, `--frozen` passes,
+ * and no later run revisits the string.
+ *
+ * The contract is therefore the same for all eleven formats regardless of how
+ * each one writes: every entry handed to `reconstruct` is readable back out.
+ */
+
+import { AndroidXmlFormatParser } from '../../../src/formats/android-xml';
+import { ArbFormatParser } from '../../../src/formats/arb';
+import { IosStringsFormatParser } from '../../../src/formats/ios-strings';
+import { JsonFormatParser } from '../../../src/formats/json';
+import { PhpArraysFormatParser } from '../../../src/formats/php-arrays';
+import { PoFormatParser } from '../../../src/formats/po';
+import { PropertiesFormatParser } from '../../../src/formats/properties';
+import { TomlFormatParser } from '../../../src/formats/toml';
+import { XcstringsFormatParser } from '../../../src/formats/xcstrings';
+import { XliffFormatParser } from '../../../src/formats/xliff';
+import { YamlFormatParser } from '../../../src/formats/yaml';
+import type {
+  FormatParser,
+  TranslatedEntry,
+} from '../../../src/formats/format';
+
+const PO_TARGET = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '',
+  'msgid "Hello"',
+  'msgstr "Hola"',
+  '',
+].join('\n');
+
+const XLIFF_12_TARGET = [
+  '<?xml version="1.0" encoding="UTF-8"?>',
+  '<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">',
+  '  <file source-language="en" target-language="es" datatype="plaintext" original="app">',
+  '    <body>',
+  '      <trans-unit id="greeting">',
+  '        <source>Hello</source>',
+  '        <target>Hola</target>',
+  '      </trans-unit>',
+  '    </body>',
+  '  </file>',
+  '</xliff>',
+  '',
+].join('\n');
+
+const XLIFF_20_TARGET = [
+  '<?xml version="1.0" encoding="UTF-8"?>',
+  '<xliff version="2.0" srcLang="en" trgLang="es" xmlns="urn:oasis:names:tc:xliff:document:2.0">',
+  '  <file id="f1">',
+  '    <unit id="greeting">',
+  '      <segment>',
+  '        <source>Hello</source>',
+  '        <target>Hola</target>',
+  '      </segment>',
+  '    </unit>',
+  '  </file>',
+  '</xliff>',
+  '',
+].join('\n');
+
+const ANDROID_TARGET = [
+  '<?xml version="1.0" encoding="utf-8"?>',
+  '<resources>',
+  '    <string name="greeting">Hola</string>',
+  '</resources>',
+  '',
+].join('\n');
+
+const xcstringsTarget = (): string =>
+  JSON.stringify(
+    {
+      sourceLanguage: 'en',
+      version: '1.0',
+      strings: {
+        greeting: {
+          localizations: {
+            es: { stringUnit: { state: 'translated', value: 'Hola' } },
+          },
+        },
+      },
+    },
+    null,
+    2
+  ) + '\n';
+
+/** The translations a file holds, read the way `sync` reads a target file. */
+function readTranslations(
+  parser: FormatParser,
+  content: string,
+  locale?: string
+): Map<string, string> {
+  if (parser.extractTranslations) {
+    return parser.extractTranslations(
+      content,
+      parser.multiLocale ? locale : undefined
+    );
+  }
+  const entries = parser.multiLocale
+    ? parser.extract(content, locale)
+    : parser.extract(content);
+  return new Map(entries.map((e) => [e.key, e.value]));
+}
+
+function extractKeys(
+  parser: FormatParser,
+  content: string,
+  locale?: string
+): string[] {
+  const entries = parser.multiLocale
+    ? parser.extract(content, locale)
+    : parser.extract(content);
+  return entries.map((e) => e.key);
+}
+
+function write(
+  parser: FormatParser,
+  content: string,
+  entries: TranslatedEntry[],
+  locale?: string
+): string {
+  return parser.multiLocale
+    ? parser.reconstruct(content, entries, locale)
+    : parser.reconstruct(content, entries);
+}
+
+interface InsertCase {
+  label: string;
+  parser: () => FormatParser;
+  /** A target-locale file holding `existingKey` already translated. */
+  target: string;
+  existingKey: string;
+  existingTranslation: string;
+  /** A key added to the source file after the target was written. */
+  newKey: string;
+  newSource: string;
+  newTranslation: string;
+  locale?: string;
+}
+
+const CASES: InsertCase[] = [
+  {
+    label: 'JSON',
+    parser: () => new JsonFormatParser(),
+    target: '{\n  "greeting": "Hola"\n}\n',
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'YAML',
+    parser: () => new YamlFormatParser(),
+    target: 'greeting: Hola\n',
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'TOML',
+    parser: () => new TomlFormatParser(),
+    target: 'greeting = "Hola"\n',
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'ARB',
+    parser: () => new ArbFormatParser(),
+    target: '{\n  "greeting": "Hola"\n}\n',
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'xcstrings',
+    parser: () => new XcstringsFormatParser(),
+    target: xcstringsTarget(),
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+    locale: 'es',
+  },
+  {
+    label: 'PO',
+    parser: () => new PoFormatParser(),
+    target: PO_TARGET,
+    existingKey: 'Hello',
+    existingTranslation: 'Hola',
+    newKey: 'Translate me',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'Java Properties',
+    parser: () => new PropertiesFormatParser(),
+    target: 'greeting=Hola\n',
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'iOS .strings',
+    parser: () => new IosStringsFormatParser(),
+    target: '"greeting" = "Hola";\n',
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'Laravel PHP',
+    parser: () => new PhpArraysFormatParser(),
+    target: "<?php\n\nreturn [\n    'greeting' => 'Hola',\n];\n",
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'Android XML',
+    parser: () => new AndroidXmlFormatParser(),
+    target: ANDROID_TARGET,
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'XLIFF 1.2',
+    parser: () => new XliffFormatParser(),
+    target: XLIFF_12_TARGET,
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+  {
+    label: 'XLIFF 2.0',
+    parser: () => new XliffFormatParser(),
+    target: XLIFF_20_TARGET,
+    existingKey: 'greeting',
+    existingTranslation: 'Hola',
+    newKey: 'added',
+    newSource: 'Translate me',
+    newTranslation: 'Traduceme',
+  },
+];
+
+describe('reconstruct with an entry the template has no slot for', () => {
+  describe.each(CASES)(
+    '$label',
+    ({
+      parser: makeParser,
+      target,
+      existingKey,
+      existingTranslation,
+      newKey,
+      newSource,
+      newTranslation,
+      locale,
+    }) => {
+      const allEntries = (): TranslatedEntry[] => [
+        {
+          key: existingKey,
+          value: 'Hello',
+          translation: existingTranslation,
+        },
+        { key: newKey, value: newSource, translation: newTranslation },
+      ];
+
+      it('should write the new key into the target file', () => {
+        const parser = makeParser();
+        const out = write(parser, target, allEntries(), locale);
+
+        expect(extractKeys(parser, out, locale)).toContain(newKey);
+        expect(readTranslations(parser, out, locale).get(newKey)).toBe(
+          newTranslation
+        );
+      });
+
+      it('should keep the translation the target file already held', () => {
+        const parser = makeParser();
+        const out = write(parser, target, allEntries(), locale);
+
+        expect(readTranslations(parser, out, locale).get(existingKey)).toBe(
+          existingTranslation
+        );
+      });
+
+      it('should not duplicate the new key on a second write', () => {
+        const parser = makeParser();
+        const once = write(parser, target, allEntries(), locale);
+        const twice = write(parser, once, allEntries(), locale);
+
+        const keys = extractKeys(parser, twice, locale);
+        expect(keys.filter((k) => k === newKey)).toHaveLength(1);
+        expect(keys.filter((k) => k === existingKey)).toHaveLength(1);
+        expect(
+          readTranslations(parser, twice, locale).get(newTranslation)
+        ).toBe(undefined);
+      });
+
+      it('should not invent a key no entry asked for', () => {
+        const parser = makeParser();
+        const out = write(
+          parser,
+          target,
+          [{ key: existingKey, value: 'Hello', translation: 'Cambiado' }],
+          locale
+        );
+
+        expect(extractKeys(parser, out, locale)).not.toContain(newKey);
+      });
+    }
+  );
+});
diff --git a/tests/unit/formats/php-arrays.test.ts b/tests/unit/formats/php-arrays.test.ts
index b7fd95e7..50f8f55e 100644
--- a/tests/unit/formats/php-arrays.test.ts
+++ b/tests/unit/formats/php-arrays.test.ts
@@ -378,15 +378,101 @@ return [
       );
     });
 
-    it('silently skips keys that are not present in the source (no insertion)', () => {
+    it('writes a key the file has no literal for, keeping the array on one line', () => {
       const content = `<?php return ['a' => 'one'];`;
       const out = parser.reconstruct(content, [
         { key: 'a', value: 'one', translation: 'uno' },
         { key: 'not_in_source', value: 'new', translation: 'nuevo' },
       ]);
+      expect(out).toBe(
+        `<?php return ['a' => 'uno', 'not_in_source' => 'nuevo'];`
+      );
+    });
+
+    it('leaves a nested key out when its parent array is absent', () => {
+      const content = `<?php return ['a' => 'one'];`;
+      const out = parser.reconstruct(content, [
+        { key: 'a', value: 'one', translation: 'uno' },
+        { key: 'missing.deep', value: 'new', translation: 'nuevo' },
+      ]);
       expect(out).toBe(`<?php return ['a' => 'uno'];`);
     });
 
+    it('writes a new element into the nested array that owns it', () => {
+      const content = `<?php\n\nreturn [\n    'grp' => [\n        'a' => 'one',\n    ],\n];\n`;
+      const out = parser.reconstruct(content, [
+        { key: 'grp.a', value: 'one', translation: 'uno' },
+        { key: 'grp.b', value: 'two', translation: 'dos' },
+      ]);
+      expect(out).toBe(
+        `<?php\n\nreturn [\n    'grp' => [\n        'a' => 'uno',\n        'b' => 'dos',\n    ],\n];\n`
+      );
+    });
+
+    it('adds the separating comma when the last element has none', () => {
+      const content = `<?php\n\nreturn [\n    'a' => 'one'\n];\n`;
+      const out = parser.reconstruct(content, [
+        { key: 'a', value: 'one', translation: 'uno' },
+        { key: 'b', value: 'two', translation: 'dos' },
+      ]);
+      expect(out).toBe(
+        `<?php\n\nreturn [\n    'a' => 'uno',\n    'b' => 'dos'\n];\n`
+      );
+    });
+
+    it('writes a new element in the quote style of the one it follows', () => {
+      const content = `<?php\n\nreturn [\n    "a" => "one",\n];\n`;
+      const out = parser.reconstruct(content, [
+        { key: 'a', value: 'one', translation: 'uno' },
+        { key: 'b', value: 'two', translation: 'dos' },
+      ]);
+      expect(out).toBe(
+        `<?php\n\nreturn [\n    "a" => "uno",\n    "b" => "dos",\n];\n`
+      );
+    });
+
+    it('writes into an empty array literal', () => {
+      const out = parser.reconstruct(`<?php\n\nreturn [\n];\n`, [
+        { key: 'a', value: 'one', translation: 'uno' },
+      ]);
+      expect(out).toBe(`<?php\n\nreturn [\n    'a' => 'uno'\n];\n`);
+      expect(parser.extract(out).map((e) => e.key)).toEqual(['a']);
+    });
+
+    it('writes into a long-form array() literal', () => {
+      const content = `<?php\n\nreturn array(\n    'a' => 'one',\n);\n`;
+      const out = parser.reconstruct(content, [
+        { key: 'a', value: 'one', translation: 'uno' },
+        { key: 'b', value: 'two', translation: 'dos' },
+      ]);
+      expect(out).toBe(
+        `<?php\n\nreturn array(\n    'a' => 'uno',\n    'b' => 'dos',\n);\n`
+      );
+    });
+
+    it('writes a new element at the indentation of the one it follows', () => {
+      const content = `<?php\n\nreturn [\n\t'a' => 'one',\n];\n`;
+      const out = parser.reconstruct(content, [
+        { key: 'a', value: 'one', translation: 'uno' },
+        { key: 'b', value: 'two', translation: 'dos' },
+      ]);
+      expect(out).toBe(
+        `<?php\n\nreturn [\n\t'a' => 'uno',\n\t'b' => 'dos',\n];\n`
+      );
+    });
+
+    it('escapes a written value the way an overwritten one is escaped', () => {
+      const content = `<?php\n\nreturn [\n    'a' => 'one',\n];\n`;
+      const out = parser.reconstruct(content, [
+        { key: 'a', value: 'one', translation: 'uno' },
+        { key: 'b', value: 'two', translation: "it's \\ here" },
+      ]);
+      expect(out).toContain(`'b' => 'it\\'s \\\\ here'`);
+      expect(
+        new Map(parser.extract(out).map((e) => [e.key, e.value])).get('b')
+      ).toBe("it's \\ here");
+    });
+
     it('preserves comments, PHPDoc, trailing commas, and irregular whitespace', () => {
       const content = `<?php
 /**
diff --git a/tests/unit/formats/properties.test.ts b/tests/unit/formats/properties.test.ts
index eb2b1c55..60e9fae4 100644
--- a/tests/unit/formats/properties.test.ts
+++ b/tests/unit/formats/properties.test.ts
@@ -96,6 +96,42 @@ describe('PropertiesFormatParser', () => {
       expect(result).not.toContain('farewell');
     });
 
+    it('should write a key with no line, keeping the trailing newline', () => {
+      const result = parser.reconstruct('greeting=Hello\n', [
+        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+        { key: 'added', value: 'Goodbye', translation: 'Tschuess' },
+      ]);
+      expect(result).toBe('greeting=Hallo\nadded=Tschuess\n');
+    });
+
+    it('should write a key with no line into a file with no trailing newline', () => {
+      const result = parser.reconstruct('greeting=Hello', [
+        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+        { key: 'added', value: 'Goodbye', translation: 'Tschuess' },
+      ]);
+      expect(result).toBe('greeting=Hallo\nadded=Tschuess');
+    });
+
+    it('should keep a dangling comment above a written key', () => {
+      const result = parser.reconstruct('# Header\n', [
+        { key: 'added', value: 'Goodbye', translation: 'Tschuess' },
+      ]);
+      expect(result).toBe('# Header\nadded=Tschuess\n');
+    });
+
+    it('should escape a written value the way an in-place one is escaped', () => {
+      const result = parser.reconstruct('greeting=Hello\n', [
+        { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+        { key: 'added', value: 'x', translation: 'line\tone\\two' },
+      ]);
+      expect(result).toContain('added=line\\tone\\\\two');
+      expect(
+        new Map(parser.extract(result).map((e) => [e.key, e.value])).get(
+          'added'
+        )
+      ).toBe('line\tone\\two');
+    });
+
     it('should preserve comments for kept keys', () => {
       const content = '# Welcome\ngreeting=Hello\n';
       const entries: TranslatedEntry[] = [
diff --git a/tests/unit/formats/xliff.test.ts b/tests/unit/formats/xliff.test.ts
index a5ca7ad1..7221940c 100644
--- a/tests/unit/formats/xliff.test.ts
+++ b/tests/unit/formats/xliff.test.ts
@@ -238,6 +238,110 @@ describe('xliff parser', () => {
     });
   });
 
+  describe('reconstruct writing a unit the document has no id for', () => {
+    it('should write into an empty <body> in v1.2', () => {
+      const xliff = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<xliff version="1.2">',
+        '  <file source-language="en" target-language="de" original="x">',
+        '    <body>',
+        '    </body>',
+        '  </file>',
+        '</xliff>',
+        '',
+      ].join('\n');
+      const result = parser.reconstruct(xliff, [
+        { key: 'msg1', value: 'Welcome', translation: 'Willkommen' },
+      ]);
+
+      expect(parser.extract(result).map((e) => e.key)).toEqual(['msg1']);
+      expect(result).toContain('      <trans-unit id="msg1">');
+      expect(parser.extractTranslations(result).get('msg1')).toBe('Willkommen');
+    });
+
+    it('should write into a <file> holding no units in v2.0', () => {
+      const xliff = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<xliff version="2.0" srcLang="en" trgLang="de">',
+        '  <file id="f1">',
+        '  </file>',
+        '</xliff>',
+        '',
+      ].join('\n');
+      const result = parser.reconstruct(xliff, [
+        { key: 'msg1', value: 'Welcome', translation: 'Willkommen' },
+      ]);
+
+      expect(parser.extract(result).map((e) => e.key)).toEqual(['msg1']);
+      expect(result).toContain('<segment>');
+      expect(parser.extractTranslations(result).get('msg1')).toBe('Willkommen');
+    });
+
+    it('should carry the namespace prefix of the unit it is written beside', () => {
+      const xliff = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<x:xliff version="1.2" xmlns:x="urn:oasis:names:tc:xliff:document:1.2">',
+        '  <x:file source-language="en" target-language="de" original="x">',
+        '    <x:body>',
+        '      <x:trans-unit id="msg1">',
+        '        <x:source>Welcome</x:source>',
+        '        <x:target>Willkommen</x:target>',
+        '      </x:trans-unit>',
+        '    </x:body>',
+        '  </x:file>',
+        '</x:xliff>',
+        '',
+      ].join('\n');
+      const result = parser.reconstruct(xliff, [
+        { key: 'msg1', value: 'Welcome', translation: 'Willkommen' },
+        { key: 'msg2', value: 'Bye', translation: 'Tschuess' },
+      ]);
+
+      expect(result).toContain('<x:trans-unit id="msg2">');
+      expect(result).toContain('<x:target>Tschuess</x:target>');
+      expect(result).not.toContain('<trans-unit');
+      expect(parser.extract(result).map((e) => e.key)).toEqual([
+        'msg1',
+        'msg2',
+      ]);
+    });
+
+    it('should escape XML metacharacters in a written source and target', () => {
+      const xliff = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<xliff version="1.2">',
+        '  <file source-language="en" target-language="de" original="x">',
+        '    <body>',
+        '      <trans-unit id="msg1">',
+        '        <source>Welcome</source>',
+        '      </trans-unit>',
+        '    </body>',
+        '  </file>',
+        '</xliff>',
+        '',
+      ].join('\n');
+      const result = parser.reconstruct(xliff, [
+        { key: 'msg1', value: 'Welcome', translation: 'Willkommen' },
+        { key: 'msg2', value: 'a < b & c', translation: 'x > y' },
+      ]);
+
+      expect(result).toContain('<source>a &lt; b &amp; c</source>');
+      expect(result).toContain('<target>x &gt; y</target>');
+      const reread = parser.extract(result);
+      expect(reread.find((e) => e.key === 'msg2')?.value).toBe('a < b & c');
+      expect(parser.extractTranslations(result).get('msg2')).toBe('x > y');
+    });
+
+    it('should leave a unit out when the document has no container for it', () => {
+      const notXliff = '<?xml version="1.0"?>\n<other/>\n';
+      expect(
+        parser.reconstruct(notXliff, [
+          { key: 'msg1', value: 'Welcome', translation: 'Willkommen' },
+        ])
+      ).toBe(notXliff);
+    });
+  });
+
   describe('reconstruct with $-patterns in translations', () => {
     it('should preserve literal $1 and $& in v1.2 target replacement', () => {
       const xliff = `<?xml version="1.0" encoding="UTF-8"?>

From f1927b199f7db24c68c54e4e343fc355bdedbe34 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 13:42:45 +0200
Subject: [PATCH 160/256] fix(sync): record a key as translated only once the
 write held it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A run marked a key `translated` on the strength of the translation call, not
of the write. That is the mechanism behind the format defect fixed in
d615218: a parser that could not place an entry lost the string at exit 0
while the lockfile called it translated, and `status`, `--frozen` and
`validate` all read that record as complete. Fixing the five writers leaves
the mechanism intact for the next such bug, and for the two shapes those
writers still deliberately decline.

Every key is now read back out of the content just written, through
`extractExistingTranslations`, before the lockfile is updated. A key the file
does not hold is recorded `failed`: the run warns naming the file, the locale
and the key and what to do about it, the file line reads `✗ es: 0/1 keys`
rather than `✓ es: 1/1 keys`, and the next sync retries it.

Measured on the two shapes that are still not written -- a new
`<string-array>` item, and a Laravel key whose parent array is absent from
the target -- both of which reproduced the full signature until now:

                        before        after
  run 2 exit            0             12
  lockfile status       translated    failed
  deepl sync status     100%          50%
  deepl sync --frozen   0             10

Presence is the test, not byte equality, which is the per-parser escaping
contract. A translation that is deliberately the empty string is exempt,
because PO and XLIFF read an empty translation side as untranslated by
design. Content a parser has just produced and cannot read back counts as
holding none of its keys, rather than taking the run down after the file is
already on disk.

The translator's stub parser in the unit tests now honours reconstruct, since
one returning `{}` for every input modelled a parser that drops everything.

Refs cli-8kr2.60
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   2 +
 docs/SYNC.md                                  |   2 +
 src/sync/sync-locale-translator.ts            |  78 +++++++++++-
 tests/e2e/cli-sync-new-source-key.e2e.test.ts |  64 ++++++++++
 .../sync-new-source-key.integration.test.ts   |  72 +++++++++++
 .../unit/sync/sync-locale-translator.test.ts  | 115 +++++++++++++++++-
 7 files changed, 332 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1427df8c..47670553 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **`deepl sync` exits 12 where it exited 0 on a key it could not write into the target file.** Any automation treating that command's exit 0 as "the locale is up to date" will start failing on a project it was already shipping incomplete — which is the point: the alternative was a lockfile entry claiming a translation the file does not contain. `sync --frozen` exits 10 and `sync status` counts the key against the locale for the same reason. See Fixed.
+
 - **sync**: **a project already missing strings from this defect recovers on its next sync that has any work to do, and re-bills them.** Measured on a `properties` project whose target file was missing a key the lockfile called `translated`: the next `deepl sync` that had a further key to translate reported `es: 2/2 keys` — the new key plus the recovered one — and wrote both. A run with nothing else to do reported `2 current`, wrote nothing, and `sync status` still said `100% (0 missing)`, because `status` and `--frozen` compare the source against the **lockfile** and never read the target file. So a project where nothing has changed since is not repaired by upgrading alone: add a string and sync, or delete the target file to have it rebuilt. See Fixed for the defect itself.
 
 - **sync**: **two output shapes change for PO and XLIFF buckets.** `deepl sync validate` now **exits 8** on a project it previously passed at exit 0, because the check finally reads the translation (see Security) — a CI job treating that command's exit 0 as "translations are sound" will start failing on input it was already shipping broken. And `deepl sync push` now reports a lower pushed count on any PO or XLIFF bucket with keys not yet translated: those keys are skipped rather than uploaded as their own source text (see Fixed), under a new `untranslated` skip reason that appears in the `(N skipped: ...)` summary line and in `--format json`. Monolingual buckets are unaffected on both counts.
@@ -131,6 +133,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **the lockfile now records what reached the target file, not what the API returned.** A run marked a key `translated` on the strength of the translation call, so a key `reconstruct` could not place was recorded as done and every gate read that as complete — the mechanism behind the format defect below, and one that would have hidden the next such bug just as completely. Every key is now read back out of the content just written before the lockfile is updated. A key the file does not hold is recorded `failed` instead: the run warns naming the file, the locale and the key, the file line reads `✗ es: 0/1 keys` rather than `✓ es: 1/1 keys`, and the run exits 12. Measured on the two shapes that are still deliberately not written — a new `<string-array>` item and a Laravel key whose parent array is absent from the target — where before this every surface agreed the locale was complete: run 2 now exits **12** with `status: "failed"` in `.deepl-sync.lock`, `deepl sync status` reporting 50% rather than 100%, and `deepl sync --frozen` exiting **10**. Presence is the test, not byte equality, which is the per-parser escaping contract; a translation that is deliberately the empty string is exempt, because PO and XLIFF read an empty translation side as untranslated by design. Content a parser has just produced and cannot read back counts as holding none of the keys.
+
 - **sync**: **a string added to a source file after the first sync is no longer silently dropped from five of the eleven formats.** From the second run onwards `sync` uses the existing target file as the `reconstruct` template — that is how the translations it already holds survive — so a key added to the source since has no slot in it. Six parsers appended such an entry; `properties`, `ios_strings`, `laravel_php`, `android_xml` and `xliff` discarded it, and nothing downstream could tell, because the run recorded success from the translation call rather than from the write. Measured through the real CLI against a mock endpoint, run 2 of 2 on each of the five, with `json` as a control on the same run: exit 0, `OK es: 1/1 keys`, `Sync complete: 1 new, 1 current`, the target file **without** the key, `.deepl-sync.lock` recording `added.translations.es = {status: "translated"}`, `deepl sync status` reporting `es [####] 100% (0 missing, 0 outdated)`, `deepl sync --frozen` — the CI drift gate whose whole purpose is catching a missing translation — exiting 0 with `2 current`, and `deepl sync validate` passing with `Checked 1 translations ... All passed` because it only sees keys the file actually has. The characters were billed on every affected key, and the lockfile's `translated` claim is what stopped any later run correcting it, so the string was permanently absent from the shipped locale. Each of the five now writes the entry in the file's own layout: `.properties` and `.strings` append a line keeping the trailing newline and any dangling comment in place; `laravel_php` splices an array element at the offset of the array that owns it, matching the file's quote style, indentation, one-line-or-many layout and trailing-comma style, and handling `array(...)` as well as `[...]`; `android_xml` writes a `<string>` (or a whole `<plurals>` block) before `</resources>`; XLIFF writes a `<trans-unit>` in 1.2 and a `<unit><segment>` in 2.0, carrying the namespace prefix of the unit it is written beside. **XLIFF 2.0 was affected too** and the finding only measured 1.2. Two cases are deliberately still left out, because writing them would mean inventing structure the source file already defines: a new `<string-array>` item in `android_xml` (its `name.index` key is indistinguishable from a plain resource whose name ends in a dot-integer), and a `laravel_php` key whose parent array does not exist in the target. Verified after the fix with `xmllint --noout` on both XML outputs and `plutil -lint` on the `.strings` output.
 - **sync**: **a reviewed PO or XLIFF translation is no longer replaced with source text.** Gettext PO and XLIFF are bilingual — one file carries the source in `msgid` / `<source>` and the translation in `msgstr` / `<target>` — and their `extract().value` is the *source* even when the file being read is a target. Every sync path that needed "the translation this target file already holds" built its map as `key -> extract().value`, so all of them read the source side. Measured through the real CLI against a mock endpoint, on the run that rewrites a file because a **sibling** key is new: `msgstr "REVIEWED-PO"` became `msgstr "Hello"` and `<target>REVIEWED-XLF</target>` became `<target>Hello</target>`, at exit 0, with the lockfile still recording the key as `translated` so no later run corrects it. The identical scenario on a `json` bucket correctly kept its hand-edited value, which is what made this format-specific rather than general. The finding named three call sites; there were **six**, and the two it did not name are the worse ones — see the `sync push` measurement below and the `sync validate` entry under Security. `deepl sync pull` had the same blind spot in its merge base, writing the msgid for a key the TMS export does not carry, and `deepl sync audit` measured terminology consistency across source strings rather than translations. Parsers may now override the target-side read (`FormatParser.extractTranslations`), PO and XLIFF do, and all six call sites go through one helper instead of reaching for `value`. An empty `msgstr`, a missing `<target>` and an empty `<target></target>` now read as *untranslated* rather than as a translation, so such a key is translated instead of having the source pinned into it; this differs deliberately from the monolingual formats, where an empty value is a deliberate translation and is still preserved.
 
diff --git a/docs/API.md b/docs/API.md
index f921eb00..ce4ce812 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3445,6 +3445,8 @@ Remediation: open `.deepl-sync.lock`, resolve the remaining `<<<<<<<` / `=======
 
 A key whose translation failed placeholder/ICU validation counts as failed here too: it is withheld from the target file rather than written corrupt. See [`validation`](SYNC.md#validation) in the sync configuration reference. With `validation.fail_on_error: true` the same run raises `ValidationError` (exit 6) instead.
 
+A key that translated successfully but that the target file's format could not be given a slot for also counts as failed. Every key is read back out of the content just written before the lockfile is updated, so the run reports it rather than recording a translation the file does not contain. See [A string added after the first sync](SYNC.md#a-string-added-after-the-first-sync).
+
 Authentication failures (401/403) abort the entire run and surface as exit code 2 (`AuthError`) instead of 12. Network / rate-limit / quota failures bubble up as 5 / 3 / 4 respectively. Code 12 specifically means "the run proceeded far enough to attempt per-locale work, and the result was mixed."
 
 **Retry model.** Re-running `deepl sync` (optionally with `--locale <failed,comma,separated>`) will retry only the locales whose lockfile entries weren't written. This is the canonical CI recovery path: branch on `$? -eq 12`, inspect the per-locale error report, and re-run with the failed locales as the filter.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 4ecf8f9a..ef3933bb 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -121,6 +121,8 @@ The first sync has no target file, so the **source** file is the template every
 
 Two cases are deliberately left out, because writing them would mean inventing structure the source file already defines: a new **`<string-array>` item** in Android XML, whose `name.index` key cannot be told apart from a plain resource whose name ends in a dot-integer; and a **Laravel PHP key whose parent array is absent** from the target file. Add the containing element to the target file once and the key is written on the next sync.
 
+Whatever the reason a key does not land, the run says so rather than recording it as translated. Every key is read back out of the content just written before the lockfile is updated, so a key the file does not hold is recorded `failed`: the run warns naming the file, the locale and the key, reports `✗ es: 0/1 keys` and exits **12** (`PartialFailure`), `deepl sync status` counts it against the locale, and `deepl sync --frozen` exits **10**. The next sync retries it.
+
 Note that `deepl sync status` and `deepl sync --frozen` compare the source file against `.deepl-sync.lock`, not against the target file. A target file edited by hand to remove a key the lockfile records as translated therefore still reports complete; the key is restored on the next sync that has anything to translate, or immediately if you delete the target file and let it be rebuilt.
 
 ### Key separators and colliding keys
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 1ed932a9..0b93fce3 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -23,6 +23,7 @@ import {
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
+import { extractExistingTranslations } from './sync-bucket-walker.js';
 import { BACKUP_SUFFIX } from './sync-bak-cleanup.js';
 import { Logger } from '../utils/logger.js';
 import {
@@ -113,6 +114,62 @@ function screenTranslations(
   return { accepted, withheld, warnings, errors };
 }
 
+/**
+ * The keys `reconstruct` did not put into the content it returned.
+ *
+ * A run records a key as translated on the strength of the translation call, so
+ * without this a parser that cannot place an entry — one added to the source
+ * since the target file was written, and so with no slot in the template — lost
+ * the string at exit 0, with the lockfile calling it translated and every gate
+ * reading that as complete. Verifying the write is what keeps the lockfile a
+ * record of the file rather than of the API call.
+ *
+ * Presence is the test, not equality: whether a written value round-trips
+ * byte-for-byte is the escaping contract, checked per parser. A translation that
+ * is deliberately the empty string is exempt, because PO and XLIFF read an empty
+ * translation side as untranslated and leave the key out of the map by design.
+ */
+function unwrittenKeys(
+  parser: FormatParser,
+  written: string,
+  entries: readonly TranslatedEntry[],
+  locale: string | undefined
+): Set<string> {
+  const expected = entries.filter((entry) => entry.translation !== '');
+  if (expected.length === 0) return new Set();
+
+  let held: Map<string, string>;
+  try {
+    held = extractExistingTranslations(parser, written, locale);
+  } catch {
+    // Content this parser just produced and cannot read back is not a file any
+    // of these keys can be claimed to be in.
+    return new Set(expected.map((entry) => entry.key));
+  }
+  return new Set(
+    expected.filter((entry) => !held.has(entry.key)).map((entry) => entry.key)
+  );
+}
+
+function unwrittenKeysWarning(
+  locale: string,
+  targetRelPath: string,
+  unwritten: ReadonlySet<string>
+): string {
+  const keys = [...unwritten];
+  const shown = keys.slice(0, 3).map((key) => `"${key}"`);
+  const more = keys.length > shown.length ? ', …' : '';
+  const one = keys.length === 1;
+  return (
+    `${locale}: ${targetRelPath} could not be given ${keys.length} translated ` +
+    `${one ? 'key' : 'keys'}: ${shown.join(', ')}${more}. ` +
+    `${one ? 'It is' : 'They are'} recorded as failed rather than translated, so ` +
+    `${one ? 'it' : 'they'} will not be reported as complete and the next sync retries ` +
+    `${one ? 'it' : 'them'}. This usually means the target file has no element to hold ` +
+    `${one ? 'it' : 'them'} — add the containing array or group to ${targetRelPath} and sync again.`
+  );
+}
+
 function withheldKeysWarning(
   locale: string,
   targetRelPath: string,
@@ -887,11 +944,30 @@ export class LocaleTranslator {
     await fs.promises.mkdir(path.dirname(targetAbsPath), { recursive: true });
     await atomicWriteFile(targetAbsPath, reconstructed, 'utf-8');
 
+    const unwritten = unwrittenKeys(
+      parser,
+      reconstructed,
+      allTranslatedEntries,
+      isMultiLocale ? locale : undefined
+    );
+
     const targetEntries = new Map<string, string>();
     for (const te of allTranslatedEntries) {
+      if (unwritten.has(te.key)) continue;
       targetEntries.set(te.key, te.translation);
     }
 
+    let writtenSuccessfulKeys = successfulKeys;
+    if (unwritten.size > 0) {
+      Logger.warn(unwrittenKeysWarning(locale, targetRelPath, unwritten));
+      writtenSuccessfulKeys = successfulKeys.filter(
+        (key) => !unwritten.has(key)
+      );
+      const lost = successfulKeys.length - writtenSuccessfulKeys.length;
+      translated -= lost;
+      failed += lost;
+    }
+
     return {
       fileResult: {
         file: targetRelPath,
@@ -901,7 +977,7 @@ export class LocaleTranslator {
         failed,
         written: true,
       },
-      successfulKeys,
+      successfulKeys: writtenSuccessfulKeys,
       charactersBilled: localeBilled,
       billedPerKey,
       contextSentKeys,
diff --git a/tests/e2e/cli-sync-new-source-key.e2e.test.ts b/tests/e2e/cli-sync-new-source-key.e2e.test.ts
index 256bf6b1..183c6d06 100644
--- a/tests/e2e/cli-sync-new-source-key.e2e.test.ts
+++ b/tests/e2e/cli-sync-new-source-key.e2e.test.ts
@@ -212,4 +212,68 @@ describe('CLI sync with a key added to the source after the first run', () => {
       expect(validate.output).toContain('Checked 2 translations');
     }, 60000);
   });
+
+  /**
+   * The two shapes that are deliberately not written must stop the run claiming
+   * them. Recording a key the file does not hold is what made every gate agree
+   * the locale was complete.
+   */
+  describe.each([
+    {
+      label: 'a new <string-array> item',
+      bucket: 'android_xml',
+      file: 'strings.xml',
+      v1: '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n    <string-array name="colours">\n        <item>Hello</item>\n    </string-array>\n</resources>\n',
+      v2: '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n    <string-array name="colours">\n        <item>Hello</item>\n        <item>Translate me</item>\n    </string-array>\n</resources>\n',
+    },
+    {
+      label: 'a Laravel key whose parent array is absent',
+      bucket: 'laravel_php',
+      file: 'app.php',
+      v1: "<?php\n\nreturn [\n    'greeting' => 'Hello',\n];\n",
+      v2: "<?php\n\nreturn [\n    'greeting' => 'Hello',\n    'grp' => [\n        'deep' => 'Translate me',\n    ],\n];\n",
+    },
+  ])('$label', ({ bucket, file, v1, v2 }) => {
+    it('reports the key as failed rather than the locale as complete', () => {
+      const projectRoot = path.join(testFiles.path, `unwritable-${bucket}`);
+      fs.mkdirSync(path.join(projectRoot, 'locales', 'en'), {
+        recursive: true,
+      });
+      fs.writeFileSync(
+        path.join(projectRoot, '.deepl-sync.yaml'),
+        [
+          'version: 1',
+          'source_locale: en',
+          'target_locales:',
+          '  - es',
+          'buckets:',
+          `  ${bucket}:`,
+          '    include:',
+          `      - "locales/en/${file}"`,
+          '',
+        ].join('\n')
+      );
+      const sourcePath = path.join(projectRoot, 'locales', 'en', file);
+
+      fs.writeFileSync(sourcePath, v1);
+      expect(run(projectRoot, ['sync', '--yes']).status).toBe(0);
+
+      fs.writeFileSync(sourcePath, v2);
+      const second = run(projectRoot, ['sync', '--yes']);
+
+      // Exit 12 is PartialFailure: the run says so rather than exiting 0.
+      expect(second.status).toBe(12);
+      expect(second.output).toContain('could not be given 1 translated key');
+      expect(second.output).toContain('sync again');
+
+      const target = path.join(projectRoot, 'locales', 'es', file);
+      expect(fs.readFileSync(target, 'utf-8')).not.toContain('Traduceme');
+
+      const status = run(projectRoot, ['sync', 'status']);
+      expect(status.output).not.toContain('100%');
+
+      // Exit 10 is the drift the CI gate exists to catch.
+      expect(run(projectRoot, ['sync', '--frozen']).status).toBe(10);
+    }, 60000);
+  });
 });
diff --git a/tests/integration/sync-new-source-key.integration.test.ts b/tests/integration/sync-new-source-key.integration.test.ts
index 98cefd9f..e19cd62c 100644
--- a/tests/integration/sync-new-source-key.integration.test.ts
+++ b/tests/integration/sync-new-source-key.integration.test.ts
@@ -108,6 +108,35 @@ const CASES: FormatCase[] = [
   },
 ];
 
+/** A key whose containing element the target file does not have. */
+interface UnwritableCase {
+  label: string;
+  parser: SupportedParser;
+  file: string;
+  key: string;
+  v1: string;
+  v2: string;
+}
+
+const UNWRITABLE_CASES: UnwritableCase[] = [
+  {
+    label: 'a new <string-array> item',
+    parser: 'android_xml',
+    file: 'strings.xml',
+    key: 'colours.1',
+    v1: '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n    <string-array name="colours">\n        <item>Hello</item>\n    </string-array>\n</resources>\n',
+    v2: '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n    <string-array name="colours">\n        <item>Hello</item>\n        <item>Translate me</item>\n    </string-array>\n</resources>\n',
+  },
+  {
+    label: 'a Laravel key whose parent array is absent',
+    parser: 'laravel_php',
+    file: 'app.php',
+    key: 'grp.deep',
+    v1: "<?php\n\nreturn [\n    'greeting' => 'Hello',\n];\n",
+    v2: "<?php\n\nreturn [\n    'greeting' => 'Hello',\n    'grp' => [\n        'deep' => 'Translate me',\n    ],\n];\n",
+  },
+];
+
 function replyWith(text: string): nock.Scope {
   return nock(DEEPL_FREE_API_URL)
     .post('/v2/translate')
@@ -214,4 +243,47 @@ describe('sync with a key added to the source after the first run', () => {
       expect(holds).toContain('added');
     });
   });
+
+  /**
+   * Two shapes are deliberately not written, because placing them would mean
+   * inventing structure the source file already defines. Those must be recorded
+   * as failed rather than translated: a lockfile that claims a key the file does
+   * not hold is what makes `status` and `--frozen` report the locale complete.
+   */
+  describe.each(UNWRITABLE_CASES)('$label', ({ parser, file, key, v1, v2 }) => {
+    it('is recorded as failed, not translated', async () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-newkey-'));
+      harness = createSyncHarness({ parsers: [parser] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { [parser]: { include: [`locales/en/${file}`] } },
+      });
+      const sourcePath = path.join(tmpDir, 'locales', 'en', file);
+      fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+
+      fs.writeFileSync(sourcePath, v1, 'utf-8');
+      replyWith('Hola');
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      fs.writeFileSync(sourcePath, v2, 'utf-8');
+      replyWith('Traduceme');
+      const second = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      const written = fs.readFileSync(
+        path.join(tmpDir, 'locales', 'es', file),
+        'utf-8'
+      );
+      expect(written).not.toContain('Traduceme');
+
+      const lock = JSON.parse(
+        fs.readFileSync(path.join(tmpDir, '.deepl-sync.lock'), 'utf-8')
+      ) as SyncLockFile;
+      const fileEntries = Object.values(lock.entries)[0]!;
+      expect(fileEntries[key]?.translations['es']?.status).toBe('failed');
+      expect(second.fileResults.map((r) => r.failed)).toEqual([1]);
+      expect(second.fileResults.map((r) => r.translated)).toEqual([0]);
+    });
+  });
 });
diff --git a/tests/unit/sync/sync-locale-translator.test.ts b/tests/unit/sync/sync-locale-translator.test.ts
index 9a43f0ed..28cd2d0a 100644
--- a/tests/unit/sync/sync-locale-translator.test.ts
+++ b/tests/unit/sync/sync-locale-translator.test.ts
@@ -3,7 +3,10 @@ import type { LocaleTranslatorContext } from '../../../src/sync/sync-locale-tran
 import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
 import type { SyncDiff } from '../../../src/sync/types';
 import type { KeyContext } from '../../../src/sync/sync-context';
-import type { FormatParser } from '../../../src/formats/format';
+import type {
+  FormatParser,
+  TranslatedEntry,
+} from '../../../src/formats/format';
 import type { TranslationOptions } from '../../../src/types/api';
 import { createMockTranslationService } from '../../helpers/mock-factories';
 
@@ -114,13 +117,27 @@ function makeConfig(
   };
 }
 
-function makeParser(): FormatParser {
+/**
+ * A parser that honours `reconstruct`: every entry it is handed is readable
+ * back out, which is what the translator verifies before recording a key as
+ * translated. `overrides` models one that does not.
+ */
+function makeParser(overrides: Partial<FormatParser> = {}): FormatParser {
   return {
     name: 'JSON',
     configKey: 'json',
     extensions: ['.json'],
-    extract: jest.fn().mockReturnValue([]),
-    reconstruct: jest.fn().mockReturnValue('{}'),
+    extract: jest.fn((content: string) =>
+      Object.entries(JSON.parse(content) as Record<string, string>).map(
+        ([key, value]) => ({ key, value })
+      )
+    ),
+    reconstruct: jest.fn((_content: string, entries: TranslatedEntry[]) =>
+      JSON.stringify(
+        Object.fromEntries(entries.map((e) => [e.key, e.translation]))
+      )
+    ),
+    ...overrides,
   };
 }
 
@@ -1974,4 +1991,94 @@ describe('LocaleTranslator', () => {
       expect(sent.some((t) => t.includes('other {'))).toBe(false);
     });
   });
+  // -------------------------------------------------------------------------
+  // 16. A key the write did not land
+  // -------------------------------------------------------------------------
+
+  describe('a key reconstruct did not write', () => {
+    /** A parser that writes every entry except the ones named. */
+    function droppingParser(...dropped: string[]): FormatParser {
+      return makeParser({
+        reconstruct: jest.fn((_content: string, entries: TranslatedEntry[]) =>
+          JSON.stringify(
+            Object.fromEntries(
+              entries
+                .filter((e) => !dropped.includes(e.key))
+                .map((e) => [e.key, e.translation])
+            )
+          )
+        ),
+      });
+    }
+
+    it('should not report a dropped key as translated', async () => {
+      const diffs = [makeDiff('a', 'Alpha'), makeDiff('b', 'Beta')];
+      const { mock } = captureTranslateBatch(['A', 'B']);
+      const ctx = { ...makeCtx(diffs, new Map()), parser: droppingParser('b') };
+
+      const result = await makeTranslator(mock, makeConfig()).translate(ctx);
+
+      expect(result.successfulKeys).toEqual(['a']);
+      expect(result.fileResult.translated).toBe(1);
+      expect(result.fileResult.failed).toBe(1);
+      expect(result.targetEntries.has('b')).toBe(false);
+    });
+
+    it('should warn naming the file, the locale and the key', async () => {
+      const diffs = [makeDiff('a', 'Alpha'), makeDiff('b', 'Beta')];
+      const { mock } = captureTranslateBatch(['A', 'B']);
+      const ctx = { ...makeCtx(diffs, new Map()), parser: droppingParser('b') };
+
+      await makeTranslator(mock, makeConfig()).translate(ctx);
+
+      const warning = (Logger.warn as jest.Mock).mock.calls
+        .map((c) => String(c[0]))
+        .find((m) => m.includes('"b"'));
+      expect(warning).toContain('de');
+      expect(warning).toContain('locales/de.json');
+    });
+
+    it('should still record the keys that were written', async () => {
+      const diffs = [
+        makeDiff('a', 'Alpha'),
+        makeDiff('b', 'Beta'),
+        makeDiff('c', 'Gamma'),
+      ];
+      const { mock } = captureTranslateBatch(['A', 'B', 'C']);
+      const ctx = { ...makeCtx(diffs, new Map()), parser: droppingParser('b') };
+
+      const result = await makeTranslator(mock, makeConfig()).translate(ctx);
+
+      expect(result.successfulKeys.sort()).toEqual(['a', 'c']);
+      expect(result.targetEntries.get('a')).toBe('A');
+      expect(result.targetEntries.get('c')).toBe('C');
+    });
+
+    it('should report every key unwritten when the file it wrote cannot be read back', async () => {
+      const diffs = [makeDiff('a', 'Alpha')];
+      const { mock } = captureTranslateBatch(['A']);
+      const ctx = {
+        ...makeCtx(diffs, new Map()),
+        parser: makeParser({
+          reconstruct: jest.fn().mockReturnValue('not json at all'),
+        }),
+      };
+
+      const result = await makeTranslator(mock, makeConfig()).translate(ctx);
+
+      expect(result.successfulKeys).toEqual([]);
+      expect(result.fileResult.failed).toBe(1);
+    });
+
+    it('should record a key whose translation is deliberately empty', async () => {
+      const diffs = [makeDiff('a', 'Alpha')];
+      const { mock } = captureTranslateBatch(['']);
+      const ctx = makeCtx(diffs, new Map());
+
+      const result = await makeTranslator(mock, makeConfig()).translate(ctx);
+
+      expect(result.successfulKeys).toEqual(['a']);
+      expect(result.fileResult.failed).toBe(0);
+    });
+  });
 });

From 2a1c3101c60019d05789edc2cc2685e9a301f035 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 15:27:36 +0200
Subject: [PATCH 161/256] fix(watch): translate one version of a file at a time

The debounce entry was dropped when the timer fired rather than when the
translation finished, so an edit arriving during an in-flight translation
started a second translation of the same file. The concurrency limiter
(default 5) let both run and both wrote the same output path in
API-completion order, so a slower translation of older content overwrote a
newer one and nothing ever corrected it: the source file does not change
again, so no further watch event fires.

Measured through the built CLI against a mock endpoint answering the first
request after 6000ms and the second after 200ms: out/doc.de.md held the
translation of the pre-edit source at exit 0, with two "Translated" lines
and no warning. Six edits during one slow translation cost 7 API calls and
left the translation of the FIRST edit on disk.

A path now has at most one translation in flight. An edit arriving while one
runs records a single re-run, dispatched from finally so a failed
translation still picks up the edit that arrived while it ran. Same harness
after the fix: the second request is issued after the first response, the
file ends as the newest version, and the six-edit storm costs 2 calls.
Translations of different files still overlap up to --concurrency.

Verified against a control on all three levels: reverting only
src/services/watch.ts fails the 4 new unit tests, the 2 new integration
tests and the new e2e, with the two deliberately-green
different-files-overlap guards staying green.

Refs cli-8kr2.44
---
 CHANGELOG.md                                  |   2 +
 docs/API.md                                   |   3 +-
 src/services/watch.ts                         |  77 +++++--
 tests/e2e/cli-watch-ordering.e2e.test.ts      | 195 +++++++++++++++++
 tests/e2e/watch-delay-server.cjs              | Bin 0 -> 2482 bytes
 .../watch-ordering.integration.test.ts        | 139 ++++++++++++
 tests/unit/services/watch.test.ts             | 204 ++++++++++++++++++
 7 files changed, 597 insertions(+), 23 deletions(-)
 create mode 100644 tests/e2e/cli-watch-ordering.e2e.test.ts
 create mode 100644 tests/e2e/watch-delay-server.cjs
 create mode 100644 tests/integration/watch-ordering.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 47670553..9008832c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -133,6 +133,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **a slower translation of older content no longer overwrites a newer one, leaving the output permanently stale.** `deepl watch` dropped its debounce bookkeeping when the timer fired rather than when the translation finished, so an edit arriving during an in-flight translation started a *second* translation of the same file; `--concurrency` (default 5) let both run, and both wrote the same output path in API-completion order. Measured through the real CLI against a mock endpoint answering the first request after 6000 ms and the second after 200 ms: request 1 carried `VERSION-A`, request 2 carried `VERSION-B`, the newer translation was written first and the older one then overwrote it, leaving `out/doc.de.md` holding the translation of the **pre-edit** source at exit 0 with two `✓ Translated` lines and no warning. Nothing recovers from that state on its own — the file will not change again, so no further watch event ever fires. A file is now translated one version at a time: an edit arriving while its translation runs queues exactly one re-translation, which starts only after the running one has written, so the last write is always the newest source. Verified on the same harness, where request 2 is now issued after response 1 and the file ends as the translation of `VERSION-B`. Coalescing also collapses an edit storm: six edits during one slow translation cost **7 API calls before and 2 after** (the in-flight one plus one re-translation of the final content), and the final file went from the translation of the *first* edit to the translation of the last. Translations of *different* files still overlap up to `--concurrency`, which is what that option is for.
+
 - **sync**: **the lockfile now records what reached the target file, not what the API returned.** A run marked a key `translated` on the strength of the translation call, so a key `reconstruct` could not place was recorded as done and every gate read that as complete — the mechanism behind the format defect below, and one that would have hidden the next such bug just as completely. Every key is now read back out of the content just written before the lockfile is updated. A key the file does not hold is recorded `failed` instead: the run warns naming the file, the locale and the key, the file line reads `✗ es: 0/1 keys` rather than `✓ es: 1/1 keys`, and the run exits 12. Measured on the two shapes that are still deliberately not written — a new `<string-array>` item and a Laravel key whose parent array is absent from the target — where before this every surface agreed the locale was complete: run 2 now exits **12** with `status: "failed"` in `.deepl-sync.lock`, `deepl sync status` reporting 50% rather than 100%, and `deepl sync --frozen` exiting **10**. Presence is the test, not byte equality, which is the per-parser escaping contract; a translation that is deliberately the empty string is exempt, because PO and XLIFF read an empty translation side as untranslated by design. Content a parser has just produced and cannot read back counts as holding none of the keys.
 
 - **sync**: **a string added to a source file after the first sync is no longer silently dropped from five of the eleven formats.** From the second run onwards `sync` uses the existing target file as the `reconstruct` template — that is how the translations it already holds survive — so a key added to the source since has no slot in it. Six parsers appended such an entry; `properties`, `ios_strings`, `laravel_php`, `android_xml` and `xliff` discarded it, and nothing downstream could tell, because the run recorded success from the translation call rather than from the write. Measured through the real CLI against a mock endpoint, run 2 of 2 on each of the five, with `json` as a control on the same run: exit 0, `OK es: 1/1 keys`, `Sync complete: 1 new, 1 current`, the target file **without** the key, `.deepl-sync.lock` recording `added.translations.es = {status: "translated"}`, `deepl sync status` reporting `es [####] 100% (0 missing, 0 outdated)`, `deepl sync --frozen` — the CI drift gate whose whole purpose is catching a missing translation — exiting 0 with `2 current`, and `deepl sync validate` passing with `Checked 1 translations ... All passed` because it only sees keys the file actually has. The characters were billed on every affected key, and the lockfile's `translated` claim is what stopped any later run correcting it, so the string was permanently absent from the shipped locale. Each of the five now writes the entry in the file's own layout: `.properties` and `.strings` append a line keeping the trailing newline and any dangling comment in place; `laravel_php` splices an array element at the offset of the array that owns it, matching the file's quote style, indentation, one-line-or-many layout and trailing-comma style, and handling `array(...)` as well as `[...]`; `android_xml` writes a `<string>` (or a whole `<plurals>` block) before `</resources>`; XLIFF writes a `<trans-unit>` in 1.2 and a `<unit><segment>` in 2.0, carrying the namespace prefix of the unit it is written beside. **XLIFF 2.0 was affected too** and the finding only measured 1.2. Two cases are deliberately still left out, because writing them would mean inventing structure the source file already defines: a new `<string-array>` item in `android_xml` (its `name.index` key is indistinguishable from a plain resource whose name ends in a dot-integer), and a `laravel_php` key whose parent array does not exist in the target. Verified after the fix with `xmllint --noout` on both XML outputs and `plutil -lint` on the `.strings` output.
diff --git a/docs/API.md b/docs/API.md
index ce4ce812..d5bd6fa3 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1113,6 +1113,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 - Shows translation statistics on exit
 - Detects file changes using filesystem watch
 - Debounces rapid changes to avoid duplicate translations
+- Translates one version of a file at a time. An edit arriving while a file's translation is still running queues exactly one re-translation, which starts after the running one has written. Two translations of the same file never overlap, so a slower translation of older content cannot overwrite a newer one, and an edit storm costs two translations rather than one per event
 
 #### Options
 
@@ -1122,7 +1123,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 - `--output, -o DIR` - Output directory (default: `<path>/translations` for directories, same dir for files)
 - `--pattern GLOB` - File pattern filter (e.g., `*.md`, `**/*.json`)
 - `--debounce MS` - Debounce delay in milliseconds. The flag wins, then the configured `watch.debounceMs`, then the default of 500
-- `--concurrency NUM` - Maximum parallel translations (default: 5)
+- `--concurrency NUM` - Maximum parallel translations across *different* files (default: 5). A single file is always translated one version at a time, whatever this is set to
 
 **Translation Options:**
 
diff --git a/src/services/watch.ts b/src/services/watch.ts
index 0b235cc0..1d38884a 100644
--- a/src/services/watch.ts
+++ b/src/services/watch.ts
@@ -70,6 +70,8 @@ export class WatchService {
   private options: WatchServiceOptions;
   private watchOptions: WatchOptions | null = null;
   private debounceTimers: Map<string, NodeJS.Timeout> = new Map();
+  private activeTranslations: Set<string> = new Set();
+  private pendingTranslations: Set<string> = new Set();
   private limit: LimitFunction;
   private stats: WatchStats = {
     isWatching: false,
@@ -243,33 +245,61 @@ export class WatchService {
         this.debounceTimers.delete(filePath);
       }
       // Wrap async code to handle Promise properly (void operator tells TypeScript we intentionally ignore the Promise)
-      void (async () => {
-        try {
-          if (!this.stats.isWatching) {
-            return;
-          }
-
-          if (this.watchOptions?.abortSignal?.aborted) {
-            return;
-          }
-
-          await this.limit(() => this.translateFile(filePath));
-        } catch (error) {
-          this.stats.errorsCount++;
-          if (this.watchOptions?.onError) {
-            this.watchOptions.onError(filePath, error as Error);
-          }
-          Logger.error(
-            `Translation failed for ${filePath}:`,
-            errorMessage(error)
-          );
-        }
-      })();
+      void this.runTranslation(filePath);
     }, this.options.debounceMs);
 
     this.debounceTimers.set(filePath, timer);
   }
 
+  /**
+   * Translate one path, reporting any failure through onError.
+   *
+   * At most one translation per path is in flight. A change arriving while one
+   * runs records a single re-run instead of starting a second translation:
+   * two concurrent runs write the same output path in API-completion order, so
+   * a slower translation of older content would overwrite a newer one and the
+   * output would stay stale until the next edit. Coalescing also collapses an
+   * edit storm into one re-translation rather than one per event.
+   *
+   * The re-run is dispatched from `finally` so a failed translation still picks
+   * up the edit that arrived while it was running.
+   */
+  private async runTranslation(filePath: string): Promise<void> {
+    if (this.activeTranslations.has(filePath)) {
+      this.pendingTranslations.add(filePath);
+      return;
+    }
+
+    this.activeTranslations.add(filePath);
+    try {
+      if (!this.stats.isWatching) {
+        return;
+      }
+
+      if (this.watchOptions?.abortSignal?.aborted) {
+        return;
+      }
+
+      await this.limit(() => this.translateFile(filePath));
+    } catch (error) {
+      this.stats.errorsCount++;
+      if (this.watchOptions?.onError) {
+        this.watchOptions.onError(filePath, error as Error);
+      }
+      Logger.error(`Translation failed for ${filePath}:`, errorMessage(error));
+    } finally {
+      this.activeTranslations.delete(filePath);
+      const hadPending = this.pendingTranslations.delete(filePath);
+      if (
+        hadPending &&
+        this.stats.isWatching &&
+        !this.watchOptions?.abortSignal?.aborted
+      ) {
+        void this.runTranslation(filePath);
+      }
+    }
+  }
+
   /**
    * Check if a file looks like a translated output file.
    * Detects patterns like name.{langCode}.ext where langCode matches a configured target language.
@@ -385,6 +415,9 @@ export class WatchService {
       clearTimeout(timer);
     }
     this.debounceTimers.clear();
+    // A translation already in flight keeps its slot in activeTranslations so
+    // its own cleanup runs; only the queued re-run is abandoned.
+    this.pendingTranslations.clear();
 
     if (this.watcher) {
       await this.watcher.close();
diff --git a/tests/e2e/cli-watch-ordering.e2e.test.ts b/tests/e2e/cli-watch-ordering.e2e.test.ts
new file mode 100644
index 00000000..ee9c8e5b
--- /dev/null
+++ b/tests/e2e/cli-watch-ordering.e2e.test.ts
@@ -0,0 +1,195 @@
+/**
+ * E2E subprocess test for `deepl watch` write ordering.
+ *
+ * The built CLI runs as a child process against a mock translate endpoint that
+ * answers the first edit's text slowly and the second's quickly, so the API
+ * completes out of request order. The file left in the output directory must
+ * hold the translation of the newest source version.
+ */
+
+import { spawn, type ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const SERVER_PATH = path.join(
+  process.cwd(),
+  'tests/e2e/watch-delay-server.cjs'
+);
+
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+describe('deepl watch write ordering (subprocess)', () => {
+  let tmpDir: string;
+  let configDir: string;
+  let srcDir: string;
+  let outDir: string;
+  let child: ChildProcess | null = null;
+  let server: ChildProcess | null = null;
+  let cliOutput = '';
+  let serverLog = '';
+
+  async function startServer(): Promise<number> {
+    server = spawn('node', [SERVER_PATH], {
+      env: {
+        ...process.env,
+        SLOW_MATCH: 'VERSION-A',
+        SLOW_MS: '2500',
+        FAST_MS: '100',
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    server.stderr?.on('data', (chunk: Buffer) => {
+      serverLog += chunk.toString();
+    });
+    return new Promise<number>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error('mock server did not start')),
+        10000
+      );
+      server?.stdout?.on('data', (chunk: Buffer) => {
+        const match = /PORT=(\d+)/.exec(chunk.toString());
+        if (match) {
+          clearTimeout(timer);
+          resolve(Number(match[1]));
+        }
+      });
+    });
+  }
+
+  function waitUntil(
+    predicate: () => boolean,
+    timeoutMs: number
+  ): Promise<boolean> {
+    return new Promise((resolve) => {
+      const start = Date.now();
+      const check = (): void => {
+        if (predicate()) return resolve(true);
+        if (Date.now() - start >= timeoutMs) return resolve(false);
+        setTimeout(check, 50);
+      };
+      check();
+    });
+  }
+
+  /** Lines the mock logged for texts carrying `marker`, in order. */
+  const linesFor = (marker: string): string[] =>
+    serverLog.split('\n').filter((line) => line.includes(marker));
+
+  /**
+   * Write `content` until the mock reports a request for it. "Watching for
+   * changes" prints before chokidar's initial scan completes, and an edit made
+   * during that scan is folded into the baseline rather than reported, so a
+   * single write is not enough to know the watcher is live.
+   */
+  async function writeUntilRequested(
+    file: string,
+    content: string,
+    marker: string
+  ): Promise<boolean> {
+    const deadline = Date.now() + 30000;
+    while (Date.now() < deadline) {
+      fs.writeFileSync(file, content);
+      if (await waitUntil(() => linesFor(marker).length > 0, 1500)) return true;
+    }
+    return false;
+  }
+
+  beforeEach(() => {
+    configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ord-cfg-'));
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ord-'));
+    srcDir = path.join(tmpDir, 'src');
+    outDir = path.join(tmpDir, 'out');
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(outDir, { recursive: true });
+    cliOutput = '';
+    serverLog = '';
+  });
+
+  afterEach(async () => {
+    if (child && !child.killed && child.exitCode === null) {
+      child.kill('SIGKILL');
+      await new Promise<void>((resolve) => {
+        if (child?.exitCode === null) child.once('exit', () => resolve());
+        else resolve();
+      });
+    }
+    child = null;
+    if (server && !server.killed) server.kill('SIGKILL');
+    server = null;
+    for (const dir of [tmpDir, configDir]) {
+      if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('writes the newest source version even when its translation returns first', async () => {
+    const port = await startServer();
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        watch: { debounceMs: 150, autoCommit: false },
+      })
+    );
+
+    const source = path.join(srcDir, 'doc.md');
+    fs.writeFileSync(source, 'BASE\n');
+
+    const env: NodeJS.ProcessEnv = {
+      ...process.env,
+      DEEPL_CONFIG_DIR: configDir,
+      NO_COLOR: '1',
+    };
+    delete env['DEEPL_API_KEY'];
+
+    child = spawn(
+      'node',
+      [CLI_PATH, 'watch', srcDir, '--to', 'de', '--output', outDir],
+      { cwd: tmpDir, env, stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+    const collect = (chunk: Buffer): void => {
+      cliOutput += chunk.toString();
+    };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+
+    expect(
+      await waitUntil(() => /Watching for changes/.test(cliOutput), 20000)
+    ).toBe(true);
+
+    // The second edit has to land while the first translation is in flight, so
+    // wait for the first request rather than for a fixed delay.
+    expect(await writeUntilRequested(source, 'VERSION-A\n', 'VERSION-A')).toBe(
+      true
+    );
+    fs.writeFileSync(source, 'VERSION-B\n');
+
+    // Read the file only once both translations have been answered, or the
+    // assertion could catch a value the losing writer then replaces.
+    expect(
+      await waitUntil(
+        () =>
+          linesFor('RESP').filter((l) => l.includes('VERSION-')).length >= 2,
+        40000
+      )
+    ).toBe(true);
+    await sleep(500);
+
+    const output = path.join(outDir, 'doc.de.md');
+    expect(fs.existsSync(output)).toBe(true);
+    expect(fs.readFileSync(output, 'utf-8')).toBe('de:VERSION-B\n');
+
+    // VERSION-B is requested only after VERSION-A has been answered.
+    expect(linesFor('VERSION-')).toEqual([
+      'REQ ["VERSION-A\\n"]',
+      'RESP ["VERSION-A\\n"]',
+      'REQ ["VERSION-B\\n"]',
+      'RESP ["VERSION-B\\n"]',
+    ]);
+  }, 120000);
+});
diff --git a/tests/e2e/watch-delay-server.cjs b/tests/e2e/watch-delay-server.cjs
new file mode 100644
index 0000000000000000000000000000000000000000..e20375d53be3a0558e0e54a4ccf0f2f1811d782d
GIT binary patch
literal 2482
zcmaJ@+j84R4DGYN0&k>jiIP3(bViBXdQzux>suwI=|g9fH3?a?sU^F+l%jF;?>*p6
z7dy4b9&51x4h{~m?j0Sq=!mY<@QHq9&aTKArEQ`d6YD5TW9?`)Pc4&So243mM4YHK
z#g;-j*L1%oH)nGE)k&;-j`hPfOf(<`-+yzqbtJh-VXB>qwWaaZ?dR$B`Q-gaiHYPZ
zHXM<fIW`inw2wP5t=(K=a{?5Foj#n8C)4Y3K!5OBOsOscGf*1^R0hzL#<4`IQKTk<
z;R)s15_!B3U+dI;!Zc4;yo7y$d<3MXfe&=3(iT-N)Dv4U6T@SrVkZG+sic$7E-X@~
z0JC7qvjFJ@!K5NL29cx;NW*oT<|ZupqgCwYG&vvrb}^aWjV?Z1{!Ou_nE_dKj89fQ
z@L-3w;a?Y{@#XDJ_ndSZNg(TNk59Q*0O=O}>RL9aDhMB~0J$@0tfjl#(Pa2e=Zkwb
zXXH|F5T&^j8o`EfKu(`cjEFd5`ZBuslio@D?AaGeV$Bk3HHQemOe36{XJt&hgsaj~
z?LNNS_b;7eht^A|ru!unHl_o5D%vSTCzVAZ1;8pxuhAtcVw131q8CC|uhr@u5nJGN
z-6*z2cYkr~jBRM*%ymmsPp93bGF^!mBbYcsoKWlBxr~N|Y+&#``Rujdwkq?EaEFwc
zG-PW7*2`eW@a-FUKWNdD_jb>1jKG;PmM^vQUpkLTJWqe@_q`6C^pUiLRO$VD&b3*b
zPY!+eWwj4^-zM%64*<DJTZ#u+g@Pb7jQub!1m(|i9XjZld=S`?Ezzdu7E!{E?$c-u
zCl7&0Xbe*Ady#SqMQ#1Ud9I&ICn{ZzhuAGR6t@j(-#TL_?fKSjB|EuEkWLcGUs6Sp
zS=?=4*?nY%$@jhY7$>ZV?gUyuI8S9+5{F94=snt0OOpv-FWod3#fnpyVEYwvkgM^G
zd?XEG9r4%OneX+Mr@dT8)oasmIHZ0JwG6wGsS-T?X<ynaF-i+c^nV}U-UQZRNFU<a
z+J6Qe%BT?fo`z|z-GKU?owEcB3};XazQEW{JeM0?M&GoGB(DN(X7?r7lG$SB!L8;M
zeHvYjS($Kt2TTj=OPAZh1H1Di@jba&^GC9bF-VViMzGR{#T#J*`RIFxmlAc)(!PV*
zi_A?y^`u}=VL1c^i@qmo$)jT`LmZR$Pt(F0LiuP7D=1BywximnGc<{QuHPFP)Q?Nu
z90+I<FBtoANA%mSQnLdN!C~or7v2A<VXKEq9wLzgdY*So)a+n+Uj`N13zhBQ6*_k@
zOGwEhIw|J1Jg9$1?4Wp#rsX3wO_YAfi}%O7xbZrB$;C&)4-Ou%<Kp!2?xv=-Otoq6
zUf8so$W7}vo$^1A=AZ<<CvF+o?PR^_zo{<E`Kxoaz|Jnq(W%1&o@@NSBF&NoQVo)9
zAo*!kPiPWbY!4q3=$)MY6!h_Z^2$;wrLUsMK-871d_qRQfVHD#XsXt7@gxfZxf^6D
K9=k@+g5p0Xvi(T_

literal 0
HcmV?d00001

diff --git a/tests/integration/watch-ordering.integration.test.ts b/tests/integration/watch-ordering.integration.test.ts
new file mode 100644
index 00000000..09b2da61
--- /dev/null
+++ b/tests/integration/watch-ordering.integration.test.ts
@@ -0,0 +1,139 @@
+/**
+ * Integration tests for watch-mode write ordering.
+ *
+ * Real files, real FileTranslationService and real atomicWriteFile; only the
+ * translation call is stubbed, with a per-call delay so the API returns out of
+ * request order. The invariant under test is the content left on disk: the
+ * translation of the newest source version, never an older one.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.mock('p-limit', () => ({
+  __esModule: true,
+  default: (_concurrency: number) => {
+    return (fn: () => Promise<unknown>) => fn();
+  },
+}));
+
+import { WatchService } from '../../src/services/watch.js';
+import { FileTranslationService } from '../../src/services/file-translation.js';
+import { TranslationService } from '../../src/services/translation.js';
+import { createMockTranslationService } from '../helpers/mock-factories';
+
+const DEBOUNCE_MS = 20;
+
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+describe('Watch write ordering integration', () => {
+  let tmpDir: string;
+  let outDir: string;
+  let watchService: WatchService;
+  let translationService: jest.Mocked<TranslationService>;
+  let requestedTexts: string[];
+
+  /** delays[n] is the delay applied to the nth translate call. */
+  function stubDelays(delays: number[]): void {
+    let call = 0;
+    translationService.translate.mockImplementation(async (text: string) => {
+      const n = call++;
+      requestedTexts.push(text);
+      await sleep(delays[Math.min(n, delays.length - 1)]!);
+      return {
+        text: `R${n}|${text}`,
+        detectedSourceLang: 'en',
+        targetLang: 'de',
+        billedCharacters: text.length,
+      } as Awaited<ReturnType<TranslationService['translate']>>;
+    });
+  }
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-order-'));
+    outDir = path.join(tmpDir, 'out');
+    fs.mkdirSync(outDir, { recursive: true });
+    requestedTexts = [];
+    translationService = createMockTranslationService();
+    watchService = new WatchService(
+      new FileTranslationService(translationService),
+      { debounceMs: DEBOUNCE_MS }
+    );
+  });
+
+  afterEach(async () => {
+    await watchService.stop();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('leaves the newest source version on disk when an older translation finishes last', async () => {
+    const source = path.join(tmpDir, 'doc.md');
+    const output = path.join(outDir, 'doc.de.md');
+    fs.writeFileSync(source, 'BASE\n');
+
+    watchService.watch(tmpDir, { targetLangs: ['de'], outputDir: outDir });
+    stubDelays([600, 30]);
+
+    fs.writeFileSync(source, 'VERSION-A\n');
+    watchService.handleFileChange(source);
+    await sleep(DEBOUNCE_MS * 3);
+
+    fs.writeFileSync(source, 'VERSION-B\n');
+    watchService.handleFileChange(source);
+    await sleep(DEBOUNCE_MS * 3);
+
+    await sleep(900);
+
+    expect(requestedTexts).toEqual(['VERSION-A\n', 'VERSION-B\n']);
+    expect(fs.readFileSync(output, 'utf-8')).toBe('R1|VERSION-B\n');
+  }, 15000);
+
+  it('collapses an edit storm during one translation into a single re-translation', async () => {
+    const source = path.join(tmpDir, 'doc.md');
+    const output = path.join(outDir, 'doc.de.md');
+    fs.writeFileSync(source, 'BASE\n');
+
+    watchService.watch(tmpDir, { targetLangs: ['de'], outputDir: outDir });
+    stubDelays([600, 30]);
+
+    fs.writeFileSync(source, 'EDIT-0\n');
+    watchService.handleFileChange(source);
+    await sleep(DEBOUNCE_MS * 3);
+
+    for (let i = 1; i <= 5; i++) {
+      fs.writeFileSync(source, `EDIT-${i}\n`);
+      watchService.handleFileChange(source);
+      await sleep(DEBOUNCE_MS * 3);
+    }
+
+    await sleep(900);
+
+    expect(requestedTexts).toEqual(['EDIT-0\n', 'EDIT-5\n']);
+    expect(fs.readFileSync(output, 'utf-8')).toBe('R1|EDIT-5\n');
+    expect(watchService.getStats().translationsCount).toBe(2);
+  }, 15000);
+
+  it('still overlaps translations of two different files', async () => {
+    const fileA = path.join(tmpDir, 'a.md');
+    const fileB = path.join(tmpDir, 'b.md');
+    fs.writeFileSync(fileA, 'AAA\n');
+    fs.writeFileSync(fileB, 'BBB\n');
+
+    watchService.watch(tmpDir, { targetLangs: ['de'], outputDir: outDir });
+    stubDelays([400, 400]);
+
+    const started = Date.now();
+    watchService.handleFileChange(fileA);
+    watchService.handleFileChange(fileB);
+    await sleep(DEBOUNCE_MS * 3);
+    await sleep(600);
+
+    expect(requestedTexts.sort()).toEqual(['AAA\n', 'BBB\n']);
+    expect(fs.existsSync(path.join(outDir, 'a.de.md'))).toBe(true);
+    expect(fs.existsSync(path.join(outDir, 'b.de.md'))).toBe(true);
+    // Serialized runs would need 800ms of translation time, not ~400ms.
+    expect(Date.now() - started).toBeLessThan(800);
+  }, 15000);
+});
diff --git a/tests/unit/services/watch.test.ts b/tests/unit/services/watch.test.ts
index c7714e61..390f20d7 100644
--- a/tests/unit/services/watch.test.ts
+++ b/tests/unit/services/watch.test.ts
@@ -1529,4 +1529,208 @@ describe('WatchService', () => {
       expect(mockFileTranslationService.translateFile).toHaveBeenCalledTimes(1);
     });
   });
+
+  describe('per-path serialization', () => {
+    const DEBOUNCE_MS = 5;
+    const tick = (ms: number) =>
+      new Promise<void>((resolve) => setTimeout(resolve, ms));
+    const afterDebounce = () => tick(DEBOUNCE_MS * 4);
+
+    /**
+     * translateFile stub whose calls are resolved by the test, recording the
+     * highest number ever in flight for a single path.
+     */
+    const makeGatedService = () => {
+      const pending: Array<{ filePath: string; release: () => void }> = [];
+      const active = new Map<string, number>();
+      let maxActivePerPath = 0;
+      const impl = (filePath: string) => {
+        const next = (active.get(filePath) ?? 0) + 1;
+        active.set(filePath, next);
+        maxActivePerPath = Math.max(maxActivePerPath, next);
+        return new Promise<void>((resolve) => {
+          pending.push({
+            filePath,
+            release: () => {
+              active.set(filePath, (active.get(filePath) ?? 1) - 1);
+              resolve();
+            },
+          });
+        });
+      };
+      return { pending, impl, max: () => maxActivePerPath };
+    };
+
+    it('never runs two translations of the same file at once', async () => {
+      const gate = makeGatedService();
+      mockFileTranslationService.translateFile.mockImplementation(gate.impl);
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      const testFile = path.join(testDir, 'doc.txt');
+      fs.writeFileSync(testFile, 'v1');
+
+      service.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      });
+
+      service.handleFileChange(testFile);
+      await afterDebounce();
+      expect(gate.pending).toHaveLength(1);
+
+      // A second edit lands while the first translation is still in flight.
+      service.handleFileChange(testFile);
+      await afterDebounce();
+
+      expect(gate.pending).toHaveLength(1);
+      expect(gate.max()).toBe(1);
+
+      gate.pending[0]!.release();
+      await afterDebounce();
+
+      expect(gate.pending).toHaveLength(2);
+      expect(gate.max()).toBe(1);
+      gate.pending[1]!.release();
+      await afterDebounce();
+      await service.stop();
+    });
+
+    it('coalesces an edit storm during one translation into a single re-run', async () => {
+      const gate = makeGatedService();
+      mockFileTranslationService.translateFile.mockImplementation(gate.impl);
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      const testFile = path.join(testDir, 'doc.txt');
+      fs.writeFileSync(testFile, 'v1');
+
+      service.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      });
+
+      service.handleFileChange(testFile);
+      await afterDebounce();
+
+      for (let i = 0; i < 4; i++) {
+        service.handleFileChange(testFile);
+        await afterDebounce();
+      }
+
+      expect(gate.pending).toHaveLength(1);
+      gate.pending[0]!.release();
+      await afterDebounce();
+
+      expect(gate.pending).toHaveLength(2);
+      gate.pending[1]!.release();
+      await afterDebounce();
+      expect(gate.pending).toHaveLength(2);
+      await service.stop();
+    });
+
+    it('still translates two different files concurrently', async () => {
+      const gate = makeGatedService();
+      mockFileTranslationService.translateFile.mockImplementation(gate.impl);
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      const fileA = path.join(testDir, 'a.txt');
+      const fileB = path.join(testDir, 'b.txt');
+      fs.writeFileSync(fileA, 'a');
+      fs.writeFileSync(fileB, 'b');
+
+      service.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      });
+
+      service.handleFileChange(fileA);
+      service.handleFileChange(fileB);
+      await afterDebounce();
+
+      expect(gate.pending).toHaveLength(2);
+      expect(gate.max()).toBe(1);
+      gate.pending[0]!.release();
+      gate.pending[1]!.release();
+      await afterDebounce();
+      await service.stop();
+    });
+
+    it('runs the coalesced re-run even when the first translation fails', async () => {
+      const onError = jest.fn();
+      const events: string[] = [];
+      let call = 0;
+      let releaseFirst: (() => void) | undefined;
+      mockFileTranslationService.translateFile.mockImplementation(() => {
+        call++;
+        events.push(`start${call}`);
+        if (call === 1) {
+          return new Promise<void>((_resolve, reject) => {
+            releaseFirst = () => {
+              events.push('fail1');
+              reject(new Error('boom'));
+            };
+          });
+        }
+        return Promise.resolve();
+      });
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      const testFile = path.join(testDir, 'doc.txt');
+      fs.writeFileSync(testFile, 'v1');
+
+      service.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+        onError,
+      });
+
+      service.handleFileChange(testFile);
+      await afterDebounce();
+      service.handleFileChange(testFile);
+      await afterDebounce();
+
+      releaseFirst!();
+      await afterDebounce();
+
+      expect(events).toEqual(['start1', 'fail1', 'start2']);
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(mockFileTranslationService.translateFile).toHaveBeenCalledTimes(2);
+      expect(service.getStats().errorsCount).toBe(1);
+      await service.stop();
+    });
+
+    it('drops a coalesced re-run when stop() is called first', async () => {
+      const gate = makeGatedService();
+      mockFileTranslationService.translateFile.mockImplementation(gate.impl);
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      const testFile = path.join(testDir, 'doc.txt');
+      fs.writeFileSync(testFile, 'v1');
+
+      service.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      });
+
+      service.handleFileChange(testFile);
+      await afterDebounce();
+      service.handleFileChange(testFile);
+      await afterDebounce();
+
+      await service.stop();
+      gate.pending[0]!.release();
+      await afterDebounce();
+
+      expect(gate.pending).toHaveLength(1);
+    });
+  });
 });

From a20c227bd9d4e3f922a13d38611959a4b4a3450c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 15:37:35 +0200
Subject: [PATCH 162/256] fix(watch): scope the output-file loop guard to the
 output directory

The guard that stops the CLI's own output re-triggering the watcher matched
on the file NAME alone, anywhere under the watched path. A source file whose
name carries a target-language segment was therefore skipped for the whole
session: measured through the built CLI, pricing.es.md under --to es
produced no request, no output file and not even a "Change detected" line,
while plain.md beside it translated normally.

Every file this service writes lands in the output directory, so the guard
now also requires containment in it. That leaves the loop protection
complete and lets any such file outside it through. Verified on the same
harness: pricing.es.md now yields out/pricing.es.es.md, and with --output
pointing at the watched directory doc.md still translates to doc.es.md
exactly once, with no second request for the file just written.

The same-directory layout keeps the skip, since the name really is
ambiguous there, but no longer does it in silence: a match the CLI did not
write is reported once per file, naming the output directory to move it out
of. Own writes are tracked and skipped without a word, because that is the
guard working rather than a file being ignored.

Verified against a control (guard unscoped, warning suppressed): exactly the
4 new discriminating tests fail and the 3 deliberately-green guards -- the
two own-write cases and the outside-the-output-dir non-warning -- stay green.

Refs cli-8kr2.44
---
 CHANGELOG.md                                  |   2 +
 docs/API.md                                   |   1 +
 src/services/watch.ts                         |  41 ++++++-
 .../watch-output-guard.integration.test.ts    | 113 ++++++++++++++++++
 tests/unit/services/watch.test.ts             |  71 +++++++++++
 5 files changed, 227 insertions(+), 1 deletion(-)
 create mode 100644 tests/integration/watch-output-guard.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9008832c..e6002505 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -133,6 +133,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **a source file whose name carries a target-language segment is translated instead of being skipped for the whole session.** The loop guard that stops the CLI's own output re-triggering the watcher matched on the *name* alone, anywhere under the watched path, so `pricing.es.md` under `--to es` was silently dropped: measured through the real CLI, no request, no output file, and not even a `📝 Change detected` line, while `plain.md` in the same directory translated normally. Every file the watcher writes lands in the output directory, so the guard now also requires the file to be *inside* it — which leaves the loop protection complete and lets any such file outside it through. Verified on the same harness: `pricing.es.md` now produces `out/pricing.es.es.md`, and pointing `--output` at the watched directory still translates `doc.md` to `doc.es.md` exactly once with no further request. In that same-directory layout a file the CLI did not write is still skipped — the name is genuinely ambiguous there — but now says so once per file instead of doing nothing, naming the file and the output directory to move it out of. The CLI's own writes are skipped in silence, since that is the guard working.
+
 - **watch**: **a slower translation of older content no longer overwrites a newer one, leaving the output permanently stale.** `deepl watch` dropped its debounce bookkeeping when the timer fired rather than when the translation finished, so an edit arriving during an in-flight translation started a *second* translation of the same file; `--concurrency` (default 5) let both run, and both wrote the same output path in API-completion order. Measured through the real CLI against a mock endpoint answering the first request after 6000 ms and the second after 200 ms: request 1 carried `VERSION-A`, request 2 carried `VERSION-B`, the newer translation was written first and the older one then overwrote it, leaving `out/doc.de.md` holding the translation of the **pre-edit** source at exit 0 with two `✓ Translated` lines and no warning. Nothing recovers from that state on its own — the file will not change again, so no further watch event ever fires. A file is now translated one version at a time: an edit arriving while its translation runs queues exactly one re-translation, which starts only after the running one has written, so the last write is always the newest source. Verified on the same harness, where request 2 is now issued after response 1 and the file ends as the translation of `VERSION-B`. Coalescing also collapses an edit storm: six edits during one slow translation cost **7 API calls before and 2 after** (the in-flight one plus one re-translation of the final content), and the final file went from the translation of the *first* edit to the translation of the last. Translations of *different* files still overlap up to `--concurrency`, which is what that option is for.
 
 - **sync**: **the lockfile now records what reached the target file, not what the API returned.** A run marked a key `translated` on the strength of the translation call, so a key `reconstruct` could not place was recorded as done and every gate read that as complete — the mechanism behind the format defect below, and one that would have hidden the next such bug just as completely. Every key is now read back out of the content just written before the lockfile is updated. A key the file does not hold is recorded `failed` instead: the run warns naming the file, the locale and the key, the file line reads `✗ es: 0/1 keys` rather than `✓ es: 1/1 keys`, and the run exits 12. Measured on the two shapes that are still deliberately not written — a new `<string-array>` item and a Laravel key whose parent array is absent from the target — where before this every surface agreed the locale was complete: run 2 now exits **12** with `status: "failed"` in `.deepl-sync.lock`, `deepl sync status` reporting 50% rather than 100%, and `deepl sync --frozen` exiting **10**. Presence is the test, not byte equality, which is the per-parser escaping contract; a translation that is deliberately the empty string is exempt, because PO and XLIFF read an empty translation side as untranslated by design. Content a parser has just produced and cannot read back counts as holding none of the keys.
diff --git a/docs/API.md b/docs/API.md
index d5bd6fa3..36472a0e 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1114,6 +1114,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 - Detects file changes using filesystem watch
 - Debounces rapid changes to avoid duplicate translations
 - Translates one version of a file at a time. An edit arriving while a file's translation is still running queues exactly one re-translation, which starts after the running one has written. Two translations of the same file never overlap, so a slower translation of older content cannot overwrite a newer one, and an edit storm costs two translations rather than one per event
+- Skips files inside the output directory whose name carries a target-language segment (`doc.es.md` with `--to es`), so the CLI's own output does not re-trigger the watcher. The check is limited to the output directory, so a *source* file named that way — `pricing.es.md` translated to `es` — is translated normally as long as it lives outside it. When such a file is skipped and the CLI did not write it, the reason is printed once per file
 
 #### Options
 
diff --git a/src/services/watch.ts b/src/services/watch.ts
index 1d38884a..02e400a1 100644
--- a/src/services/watch.ts
+++ b/src/services/watch.ts
@@ -13,6 +13,7 @@ import { Language, TranslationOptions } from '../types/index.js';
 import { Logger } from '../utils/logger.js';
 import { ValidationError } from '../utils/errors.js';
 import { errorMessage } from '../utils/error-message.js';
+import { isWithinDirectory } from '../utils/paths.js';
 
 export interface FileTranslationResult {
   targetLang: Language;
@@ -72,6 +73,8 @@ export class WatchService {
   private debounceTimers: Map<string, NodeJS.Timeout> = new Map();
   private activeTranslations: Set<string> = new Set();
   private pendingTranslations: Set<string> = new Set();
+  private writtenOutputs: Set<string> = new Set();
+  private warnedOutputs: Set<string> = new Set();
   private limit: LimitFunction;
   private stats: WatchStats = {
     isWatching: false,
@@ -208,6 +211,7 @@ export class WatchService {
 
     // Check if file is a translated output file to prevent infinite loops
     if (this.isTranslatedOutputFile(filePath)) {
+      this.warnOnceAboutSkippedOutput(filePath);
       return;
     }
 
@@ -302,13 +306,22 @@ export class WatchService {
 
   /**
    * Check if a file looks like a translated output file.
-   * Detects patterns like name.{langCode}.ext where langCode matches a configured target language.
+   * Detects patterns like name.{langCode}.ext where langCode matches a
+   * configured target language, and only inside the output directory — every
+   * file this service writes lands there, so requiring containment keeps the
+   * loop guard complete while letting a source file that merely carries a
+   * target-language segment in its name (pricing.es.md with --to es) be
+   * translated instead of skipped for the lifetime of the session.
    */
   private isTranslatedOutputFile(filePath: string): boolean {
     if (!this.watchOptions) {
       return false;
     }
 
+    if (!isWithinDirectory(this.watchOptions.outputDir, filePath)) {
+      return false;
+    }
+
     const basename = path.basename(filePath);
     const parts = basename.split('.');
     // Need at least 3 parts: name, langCode, extension
@@ -328,6 +341,24 @@ export class WatchService {
     return false;
   }
 
+  /**
+   * Say once why a file inside the output directory is being left alone.
+   *
+   * A file this session wrote is skipped in silence — that is the loop guard
+   * working. Any other match is a file the user put there, and skipping it
+   * without a word is indistinguishable from the watcher not seeing it.
+   */
+  private warnOnceAboutSkippedOutput(filePath: string): void {
+    const resolved = path.resolve(filePath);
+    if (this.writtenOutputs.has(resolved) || this.warnedOutputs.has(resolved)) {
+      return;
+    }
+    this.warnedOutputs.add(resolved);
+    Logger.warn(
+      `Skipping ${filePath}: it is inside the output directory and named like a translated output, so it is read as a translation rather than a source. Move it outside ${this.watchOptions?.outputDir ?? 'the output directory'} to have it translated.`
+    );
+  }
+
   /**
    * Translate a file with the configured options
    */
@@ -379,6 +410,7 @@ export class WatchService {
         { preserveCode }
       );
 
+      this.writtenOutputs.add(path.resolve(outputPath));
       this.stats.translationsCount++;
 
       if (this.watchOptions.onTranslate) {
@@ -396,6 +428,11 @@ export class WatchService {
         { ...baseOptions, outputDir, preserveCode }
       );
 
+      for (const result of results) {
+        if (result.outputPath) {
+          this.writtenOutputs.add(path.resolve(result.outputPath));
+        }
+      }
       this.stats.translationsCount += results.length;
 
       if (this.watchOptions.onTranslate) {
@@ -418,6 +455,8 @@ export class WatchService {
     // A translation already in flight keeps its slot in activeTranslations so
     // its own cleanup runs; only the queued re-run is abandoned.
     this.pendingTranslations.clear();
+    this.writtenOutputs.clear();
+    this.warnedOutputs.clear();
 
     if (this.watcher) {
       await this.watcher.close();
diff --git a/tests/integration/watch-output-guard.integration.test.ts b/tests/integration/watch-output-guard.integration.test.ts
new file mode 100644
index 00000000..a48f13c7
--- /dev/null
+++ b/tests/integration/watch-output-guard.integration.test.ts
@@ -0,0 +1,113 @@
+/**
+ * Integration tests for the watch loop guard.
+ *
+ * The guard exists so a file the CLI writes into a watched directory does not
+ * re-trigger the watcher. It is scoped to the output directory, so a source
+ * file that merely carries a target-language segment in its name is still
+ * translated. Real files and a real write path; only the translation call is
+ * stubbed.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.mock('p-limit', () => ({
+  __esModule: true,
+  default: (_concurrency: number) => {
+    return (fn: () => Promise<unknown>) => fn();
+  },
+}));
+
+import { WatchService } from '../../src/services/watch.js';
+import { FileTranslationService } from '../../src/services/file-translation.js';
+import { TranslationService } from '../../src/services/translation.js';
+import { Logger } from '../../src/utils/logger.js';
+import { createMockTranslationService } from '../helpers/mock-factories';
+
+const DEBOUNCE_MS = 20;
+
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+describe('Watch output-file guard integration', () => {
+  let tmpDir: string;
+  let watchService: WatchService;
+  let translationService: jest.Mocked<TranslationService>;
+  let warnings: string[];
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-guard-'));
+    warnings = [];
+    jest.spyOn(Logger, 'warn').mockImplementation((...args: unknown[]) => {
+      warnings.push(args.join(' '));
+    });
+    translationService = createMockTranslationService();
+    translationService.translate.mockImplementation(async (text: string) => ({
+      text: `es:${text}`,
+      detectedSourceLang: 'en',
+      targetLang: 'es',
+      billedCharacters: text.length,
+    }));
+    watchService = new WatchService(
+      new FileTranslationService(translationService),
+      { debounceMs: DEBOUNCE_MS }
+    );
+  });
+
+  afterEach(async () => {
+    await watchService.stop();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('translates a source file whose name carries a target-language segment', async () => {
+    const outDir = path.join(tmpDir, 'out');
+    fs.mkdirSync(outDir, { recursive: true });
+    const source = path.join(tmpDir, 'pricing.es.md');
+    fs.writeFileSync(source, 'Precios\n');
+
+    watchService.watch(tmpDir, { targetLangs: ['es'], outputDir: outDir });
+    watchService.handleFileChange(source);
+    await sleep(DEBOUNCE_MS * 5);
+
+    expect(
+      fs.readFileSync(path.join(outDir, 'pricing.es.es.md'), 'utf-8')
+    ).toBe('es:Precios\n');
+    expect(warnings).toEqual([]);
+  });
+
+  it('does not re-translate the file it just wrote into the watched directory', async () => {
+    const source = path.join(tmpDir, 'doc.md');
+    fs.writeFileSync(source, 'Hello\n');
+
+    // Output directory is the watched directory, so the output is watched too.
+    watchService.watch(tmpDir, { targetLangs: ['es'], outputDir: tmpDir });
+    watchService.handleFileChange(source);
+    await sleep(DEBOUNCE_MS * 5);
+
+    const output = path.join(tmpDir, 'doc.es.md');
+    expect(fs.readFileSync(output, 'utf-8')).toBe('es:Hello\n');
+
+    watchService.handleFileChange(output);
+    await sleep(DEBOUNCE_MS * 5);
+
+    expect(translationService.translate).toHaveBeenCalledTimes(1);
+    expect(fs.existsSync(path.join(tmpDir, 'doc.es.es.md'))).toBe(false);
+    expect(warnings).toEqual([]);
+  });
+
+  it('says once why it skips a user file sitting in the output directory', async () => {
+    const source = path.join(tmpDir, 'pricing.es.md');
+    fs.writeFileSync(source, 'Precios\n');
+
+    watchService.watch(tmpDir, { targetLangs: ['es'], outputDir: tmpDir });
+    watchService.handleFileChange(source);
+    watchService.handleFileChange(source);
+    await sleep(DEBOUNCE_MS * 5);
+
+    expect(translationService.translate).not.toHaveBeenCalled();
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('pricing.es.md');
+    expect(warnings[0]).toContain('output directory');
+  });
+});
diff --git a/tests/unit/services/watch.test.ts b/tests/unit/services/watch.test.ts
index 390f20d7..d41eeb20 100644
--- a/tests/unit/services/watch.test.ts
+++ b/tests/unit/services/watch.test.ts
@@ -9,6 +9,7 @@ import * as chokidar from 'chokidar';
 import pLimit from 'p-limit';
 import { WatchService } from '../../../src/services/watch';
 import { FileTranslationService } from '../../../src/services/file-translation';
+import { Logger } from '../../../src/utils/logger';
 import { createMockFileTranslationService } from '../../helpers/mock-factories';
 
 // Mock chokidar
@@ -1160,6 +1161,76 @@ describe('WatchService', () => {
       expect(onChange).toHaveBeenCalledWith(testFile);
     });
 
+    it('should translate a source file named like an output file when it is outside the output directory', async () => {
+      const testFile = path.join(testDir, 'pricing.es.md');
+      fs.writeFileSync(testFile, 'Precios');
+
+      const onChange = jest.fn();
+      watchService.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+        onChange,
+      });
+      watchService.handleFileChange(testFile);
+
+      expect(onChange).toHaveBeenCalledWith(testFile);
+    });
+
+    it('should still ignore an output-named file inside the output directory', async () => {
+      const outputDir = path.join(testDir, 'output');
+      fs.mkdirSync(outputDir, { recursive: true });
+      const testFile = path.join(outputDir, 'pricing.es.md');
+      fs.writeFileSync(testFile, 'Precios');
+
+      const onChange = jest.fn();
+      watchService.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir,
+        onChange,
+      });
+      watchService.handleFileChange(testFile);
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('should warn once per file when it skips a file it did not write', async () => {
+      const warn = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+      const testFile = path.join(testDir, 'pricing.es.md');
+      fs.writeFileSync(testFile, 'Precios');
+
+      watchService.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: testDir,
+      });
+      watchService.handleFileChange(testFile);
+      watchService.handleFileChange(testFile);
+
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0]!.join(' ')).toContain('pricing.es.md');
+    });
+
+    it('should not warn about an output file it wrote itself', async () => {
+      jest.useFakeTimers({ doNotFake: ['nextTick'] });
+      const warn = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+      const testFile = path.join(testDir, 'doc.md');
+      fs.writeFileSync(testFile, 'Hello');
+
+      mockFileTranslationService.translateFile.mockResolvedValue(undefined);
+
+      watchService.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: testDir,
+      });
+      watchService.handleFileChange(testFile);
+      jest.advanceTimersByTime(350);
+      await flushPromises();
+
+      watchService.handleFileChange(path.join(testDir, 'doc.es.md'));
+
+      expect(mockFileTranslationService.translateFile).toHaveBeenCalledTimes(1);
+      expect(warn).not.toHaveBeenCalled();
+    });
+
     it('should ignore output files case-insensitively for language codes', async () => {
       const testFile = path.join(testDir, 'test.ES.txt');
       fs.writeFileSync(testFile, 'Hola');

From ee75389b60bfd470353fe7250aff5c7f0581cec0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 15:49:54 +0200
Subject: [PATCH 163/256] fix(watch): await onTranslate and queue the
 auto-commit git work

WatchService.onTranslate was typed => void and called without await, so the
async callback the watch command supplies -- the one that awaits autoCommit --
had its promise discarded. The git work therefore ran outside the
translation's concurrency slot, unbounded and untracked, and git holds
.git/index.lock for the duration of an add or a commit, so parallel
auto-commits knocked each other out.

Measured through the built CLI in a real repository, six watched files edited
at once with a 300ms stub delay: 6 translations, 2 commits, 4 auto-commit
failures (three git add, one git commit, all lock contention), three output
files left untracked and a fourth left staged but uncommitted, where an
unrelated later commit would have swept it in. Exit 0.

onTranslate may now return a promise and both call sites await it, so the
callback runs inside the translation's slot and a rejection reaches onError
instead of vanishing. The git work is additionally queued one add/commit pair
at a time. Same harness after: 6 translations, 6 commits, 0 failures, nothing
left untracked or staged. Translations of different files still run in
parallel; only the git step is serialized.

A session that recorded a failure also stops claiming success: Ctrl+C exits 12
where it always exited 0, and the auto-commit failure count is printed beside
the translation total.

Three controls, one per layer, each with the fixed sources copied aside first:
A (onTranslate promise discarded again) fails exactly the 3 new unit tests;
B (git queue removed) fails exactly the new serialization integration test,
3 runs out of 3; C (exit code forced to 0) fails exactly the new exit-12 e2e
while its exit-0 sibling stays green.

Refs cli-8kr2.46
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   8 +-
 src/cli/commands/watch.ts                     |  35 +++-
 src/services/watch.ts                         |  15 +-
 tests/e2e/cli-watch-auto-commit.e2e.test.ts   | 196 ++++++++++++++++++
 .../watch-auto-commit.integration.test.ts     |  41 ++++
 tests/unit/services/watch.test.ts             | 115 ++++++++++
 7 files changed, 407 insertions(+), 7 deletions(-)
 create mode 100644 tests/e2e/cli-watch-auto-commit.e2e.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e6002505..1d3ca3ea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **watch**: **a `deepl watch` session now exits 12 rather than 0 when it recorded a failure.** Ctrl+C used to end every session at exit 0 with failed translations and failed auto-commits only logged, so a script wrapping `deepl watch` could not tell a clean run from one that lost work. A session that recorded any translation error or any `--auto-commit` failure now exits **12** (`PartialFailure`), and the auto-commit failure count is printed beside the translation total. A session with no failures still exits 0. See Fixed.
+
 - **sync**: **`deepl sync` exits 12 where it exited 0 on a key it could not write into the target file.** Any automation treating that command's exit 0 as "the locale is up to date" will start failing on a project it was already shipping incomplete — which is the point: the alternative was a lockfile entry claiming a translation the file does not contain. `sync --frozen` exits 10 and `sync status` counts the key against the locale for the same reason. See Fixed.
 
 - **sync**: **a project already missing strings from this defect recovers on its next sync that has any work to do, and re-bills them.** Measured on a `properties` project whose target file was missing a key the lockfile called `translated`: the next `deepl sync` that had a further key to translate reported `es: 2/2 keys` — the new key plus the recovered one — and wrote both. A run with nothing else to do reported `2 current`, wrote nothing, and `sync status` still said `100% (0 missing)`, because `status` and `--frozen` compare the source against the **lockfile** and never read the target file. So a project where nothing has changed since is not repaired by upgrading alone: add a string and sync, or delete the target file to have it rebuilt. See Fixed for the defect itself.
@@ -133,6 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **`--auto-commit` no longer loses most commits under an edit storm.** `WatchService.onTranslate` was typed `=> void` and called without `await`, so the async callback the watch command supplies — the one that awaits `autoCommit` — had its promise discarded. The git work therefore ran outside the translation's concurrency slot, unbounded and untracked, and git holds `.git/index.lock` for the duration of an `add` or a `commit`, so parallel auto-commits knocked each other out. Measured through the real CLI in a real repository, six watched files edited at once with a 300 ms stub delay: **6 translations, 2 commits, 4 auto-commit failures** (three `git add` and one `git commit`, all lock contention), three output files left untracked and a fourth left staged but uncommitted — where an unrelated later commit would have swept it in. The session still exited 0. `onTranslate` may now return a promise and it is awaited, so the callback runs inside the translation's slot and a rejection reaches `onError`; the git work is additionally queued one `add`/`commit` pair at a time. Same harness after the fix: **6 translations, 6 commits, 0 failures**, nothing left untracked or staged. Translations of different files still run in parallel — only the git step is serialized.
+
 - **watch**: **a source file whose name carries a target-language segment is translated instead of being skipped for the whole session.** The loop guard that stops the CLI's own output re-triggering the watcher matched on the *name* alone, anywhere under the watched path, so `pricing.es.md` under `--to es` was silently dropped: measured through the real CLI, no request, no output file, and not even a `📝 Change detected` line, while `plain.md` in the same directory translated normally. Every file the watcher writes lands in the output directory, so the guard now also requires the file to be *inside* it — which leaves the loop protection complete and lets any such file outside it through. Verified on the same harness: `pricing.es.md` now produces `out/pricing.es.es.md`, and pointing `--output` at the watched directory still translates `doc.md` to `doc.es.md` exactly once with no further request. In that same-directory layout a file the CLI did not write is still skipped — the name is genuinely ambiguous there — but now says so once per file instead of doing nothing, naming the file and the output directory to move it out of. The CLI's own writes are skipped in silence, since that is the guard working.
 
 - **watch**: **a slower translation of older content no longer overwrites a newer one, leaving the output permanently stale.** `deepl watch` dropped its debounce bookkeeping when the timer fired rather than when the translation finished, so an edit arriving during an in-flight translation started a *second* translation of the same file; `--concurrency` (default 5) let both run, and both wrote the same output path in API-completion order. Measured through the real CLI against a mock endpoint answering the first request after 6000 ms and the second after 200 ms: request 1 carried `VERSION-A`, request 2 carried `VERSION-B`, the newer translation was written first and the older one then overwrote it, leaving `out/doc.de.md` holding the translation of the **pre-edit** source at exit 0 with two `✓ Translated` lines and no warning. Nothing recovers from that state on its own — the file will not change again, so no further watch event ever fires. A file is now translated one version at a time: an edit arriving while its translation runs queues exactly one re-translation, which starts only after the running one has written, so the last write is always the newest source. Verified on the same harness, where request 2 is now issued after response 1 and the file ends as the translation of `VERSION-B`. Coalescing also collapses an edit storm: six edits during one slow translation cost **7 API calls before and 2 after** (the in-flight one plus one re-translation of the final content), and the final file went from the translation of the *first* edit to the translation of the last. Translations of *different* files still overlap up to `--concurrency`, which is what that option is for.
diff --git a/docs/API.md b/docs/API.md
index 36472a0e..37ffa418 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1110,7 +1110,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 **Behavior:**
 
 - Runs continuously until interrupted (Ctrl+C)
-- Shows translation statistics on exit
+- Shows translation statistics on exit, and exits **12** rather than 0 when the session recorded any failed translation or failed auto-commit
 - Detects file changes using filesystem watch
 - Debounces rapid changes to avoid duplicate translations
 - Translates one version of a file at a time. An edit arriving while a file's translation is still running queues exactly one re-translation, which starts after the running one has written. Two translations of the same file never overlap, so a slower translation of older content cannot overwrite a newer one, and an edit storm costs two translations rather than one per event
@@ -1136,7 +1136,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 
 **Git Integration:**
 
-- `--auto-commit` - Auto-commit translations to git after each change
+- `--auto-commit` - Auto-commit translations to git after each change. One commit per translated source file, queued one at a time: git holds `.git/index.lock` for the duration of an `add` or a `commit`, so parallel translations cannot commit in parallel. A failed commit is reported and counted, and the session exits 12 rather than 0 (see below)
 - `--git-staged` - Only watch git-staged files (snapshot taken once at startup)
 - `--dry-run` - Show what would be watched without starting the watcher
 
@@ -3332,7 +3332,7 @@ Retryable codes are `3` (rate limit) and `5` (network); everything else should b
 | 9    | VoiceError     | Voice API unavailable or session failed                        | No        |
 | 10   | SyncDrift      | `sync --frozen` detected translations out of date              | No        |
 | 11   | SyncConflict   | `sync resolve` could not auto-resolve lockfile conflicts       | No        |
-| 12   | PartialFailure | `deepl sync` completed with at least one failed key            | Yes (per-locale retry) |
+| 12   | PartialFailure | `deepl sync` completed with at least one failed key, or a `deepl watch` session ended with a failed translation or auto-commit | Yes (per-locale retry) |
 
 ### Code details
 
@@ -3449,6 +3449,8 @@ A key whose translation failed placeholder/ICU validation counts as failed here
 
 A key that translated successfully but that the target file's format could not be given a slot for also counts as failed. Every key is read back out of the content just written before the lockfile is updated, so the run reports it rather than recording a translation the file does not contain. See [A string added after the first sync](SYNC.md#a-string-added-after-the-first-sync).
 
+`deepl watch` uses the same code when the session ends: on Ctrl+C (SIGINT/SIGTERM) it exits 12 rather than 0 if it recorded any failed translation or any failed `--auto-commit`, so a script driving a watch session can tell a clean run from one that lost work. The counts are printed beside the translation total before the process exits.
+
 Authentication failures (401/403) abort the entire run and surface as exit code 2 (`AuthError`) instead of 12. Network / rate-limit / quota failures bubble up as 5 / 3 / 4 respectively. Code 12 specifically means "the run proceeded far enough to attempt per-locale work, and the result was mixed."
 
 **Retry model.** Re-running `deepl sync` (optionally with `--locale <failed,comma,separated>`) will retry only the locales whose lockfile entries weren't written. This is the canonical CI recovery path: branch on `$? -eq 12`, inspect the per-locale error report, and re-run with the failed locales as the filter.
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index d5326ecb..b03ddbcf 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -6,6 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
+import pLimit, { type LimitFunction } from 'p-limit';
 import { WatchService } from '../../services/watch.js';
 import { FileTranslationService } from '../../services/file-translation.js';
 import { TranslationService } from '../../services/translation.js';
@@ -44,6 +45,14 @@ export class WatchCommand {
   private glossaryService: GlossaryService;
   private config?: ConfigService;
   private watchService?: WatchService;
+  /**
+   * git takes `.git/index.lock` for the duration of an `add` or a `commit`, so
+   * two auto-commits running at once make one of them fail. Translations of
+   * different files do run in parallel, so the git work is queued one at a
+   * time behind this.
+   */
+  private gitLimit: LimitFunction = pLimit(1);
+  private autoCommitFailures = 0;
 
   /**
    * `config` supplies `defaults.sourceLang` for the glossary requirement below.
@@ -279,8 +288,13 @@ export class WatchCommand {
         Logger.info(chalk.gray(`Translations: ${stats.translationsCount}`));
         Logger.info(chalk.gray(`Errors: ${stats.errorsCount}`));
       }
+      if (this.autoCommitFailures > 0) {
+        Logger.info(
+          chalk.gray(`Auto-commit failures: ${this.autoCommitFailures}`)
+        );
+      }
       Logger.success(chalk.green('✓ Watch stopped'));
-      process.exit(0);
+      process.exit(this.sessionExitCode());
     };
 
     process.on('SIGINT', () => void cleanup());
@@ -299,6 +313,13 @@ export class WatchCommand {
   private async autoCommit(
     sourceFile: string,
     result: WatchTranslationResult
+  ): Promise<void> {
+    return this.gitLimit(() => this.commitTranslations(sourceFile, result));
+  }
+
+  private async commitTranslations(
+    sourceFile: string,
+    result: WatchTranslationResult
   ): Promise<void> {
     try {
       const { execFile } = await import('child_process');
@@ -357,6 +378,7 @@ export class WatchCommand {
 
       Logger.success(chalk.green('✓ Auto-committed translations'));
     } catch (error) {
+      this.autoCommitFailures++;
       Logger.error(
         chalk.red('✗ Auto-commit failed:'),
         error instanceof Error ? error.message : 'Unknown error'
@@ -364,6 +386,17 @@ export class WatchCommand {
     }
   }
 
+  /**
+   * Exit code for a watch session ending on SIGINT/SIGTERM. A translation or an
+   * auto-commit that failed during the session is a partial failure, not a
+   * clean run: the session used to report exit 0 with the failures only logged,
+   * so a script driving `deepl watch` had no way to notice.
+   */
+  private sessionExitCode(): number {
+    const errors = this.watchService?.getStats().errorsCount ?? 0;
+    return errors > 0 || this.autoCommitFailures > 0 ? 12 : 0;
+  }
+
   /**
    * Stop watching
    */
diff --git a/src/services/watch.ts b/src/services/watch.ts
index 02e400a1..382f681d 100644
--- a/src/services/watch.ts
+++ b/src/services/watch.ts
@@ -43,7 +43,16 @@ export interface WatchOptions {
   abortSignal?: AbortSignal;
   onReady?: () => void;
   onChange?: (filePath: string) => void;
-  onTranslate?: (filePath: string, result: WatchTranslationResult) => void;
+  /**
+   * Called once a file's translations are on disk. A promise returned here is
+   * awaited before the path is considered done, so follow-up work such as
+   * `--auto-commit` runs inside the translation's slot and its failure is
+   * reported instead of being dropped.
+   */
+  onTranslate?: (
+    filePath: string,
+    result: WatchTranslationResult
+  ) => void | Promise<void>;
   onError?: (filePath: string, error: Error) => void;
 }
 
@@ -414,7 +423,7 @@ export class WatchService {
       this.stats.translationsCount++;
 
       if (this.watchOptions.onTranslate) {
-        this.watchOptions.onTranslate(filePath, {
+        await this.watchOptions.onTranslate(filePath, {
           text: '',
           outputPath,
           targetLang,
@@ -436,7 +445,7 @@ export class WatchService {
       this.stats.translationsCount += results.length;
 
       if (this.watchOptions.onTranslate) {
-        this.watchOptions.onTranslate(filePath, results);
+        await this.watchOptions.onTranslate(filePath, results);
       }
     }
   }
diff --git a/tests/e2e/cli-watch-auto-commit.e2e.test.ts b/tests/e2e/cli-watch-auto-commit.e2e.test.ts
new file mode 100644
index 00000000..8a97212a
--- /dev/null
+++ b/tests/e2e/cli-watch-auto-commit.e2e.test.ts
@@ -0,0 +1,196 @@
+/**
+ * E2E subprocess test for `deepl watch --auto-commit` reporting.
+ *
+ * A watch session that failed to commit a translation used to exit 0 with the
+ * failure only logged. The real CLI runs against a real git repository, with
+ * the output directory in .gitignore so `git add` fails deterministically.
+ */
+
+import { spawn, type ChildProcess } from 'child_process';
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const SERVER_PATH = path.join(
+  process.cwd(),
+  'tests/e2e/watch-delay-server.cjs'
+);
+
+describe('deepl watch --auto-commit exit status (subprocess)', () => {
+  let tmpDir: string;
+  let configDir: string;
+  let srcDir: string;
+  let outDir: string;
+  let child: ChildProcess | null = null;
+  let server: ChildProcess | null = null;
+  let cliOutput = '';
+
+  async function startServer(): Promise<number> {
+    server = spawn('node', [SERVER_PATH], {
+      env: { ...process.env, FAST_MS: '50' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return new Promise<number>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error('mock server did not start')),
+        10000
+      );
+      server?.stdout?.on('data', (chunk: Buffer) => {
+        const match = /PORT=(\d+)/.exec(chunk.toString());
+        if (match) {
+          clearTimeout(timer);
+          resolve(Number(match[1]));
+        }
+      });
+    });
+  }
+
+  function waitUntil(
+    predicate: () => boolean,
+    timeoutMs: number
+  ): Promise<boolean> {
+    return new Promise((resolve) => {
+      const start = Date.now();
+      const check = (): void => {
+        if (predicate()) return resolve(true);
+        if (Date.now() - start >= timeoutMs) return resolve(false);
+        setTimeout(check, 50);
+      };
+      check();
+    });
+  }
+
+  function git(args: string[]): void {
+    execFileSync('git', args, { cwd: tmpDir, stdio: 'ignore' });
+  }
+
+  async function startWatch(port: number): Promise<void> {
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        watch: { debounceMs: 150, autoCommit: false },
+      })
+    );
+    const env: NodeJS.ProcessEnv = {
+      ...process.env,
+      DEEPL_CONFIG_DIR: configDir,
+      NO_COLOR: '1',
+    };
+    delete env['DEEPL_API_KEY'];
+
+    child = spawn(
+      'node',
+      [
+        CLI_PATH,
+        'watch',
+        srcDir,
+        '--to',
+        'de',
+        '--output',
+        outDir,
+        '--auto-commit',
+      ],
+      { cwd: tmpDir, env, stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+    const collect = (chunk: Buffer): void => {
+      cliOutput += chunk.toString();
+    };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+
+    expect(
+      await waitUntil(() => /Watching for changes/.test(cliOutput), 20000)
+    ).toBe(true);
+  }
+
+  /** Edit until the watcher reacts: readiness precedes chokidar's first scan. */
+  async function editUntilTranslated(file: string): Promise<boolean> {
+    const deadline = Date.now() + 30000;
+    let n = 0;
+    while (Date.now() < deadline) {
+      fs.writeFileSync(file, `EDIT-${n++}\n`);
+      if (await waitUntil(() => /Translated/.test(cliOutput), 1500))
+        return true;
+    }
+    return false;
+  }
+
+  function stopAndWait(): Promise<number | null> {
+    return new Promise((resolve) => {
+      child?.once('exit', (code) => resolve(code));
+      child?.kill('SIGINT');
+    });
+  }
+
+  beforeEach(() => {
+    configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ac-cfg-'));
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ac-'));
+    srcDir = path.join(tmpDir, 'src');
+    outDir = path.join(tmpDir, 'out');
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(outDir, { recursive: true });
+    cliOutput = '';
+
+    git(['init', '-q']);
+    git(['config', 'user.email', 'test@test.com']);
+    git(['config', 'user.name', 'Test']);
+    fs.writeFileSync(path.join(srcDir, 'doc.md'), 'BASE\n');
+    git(['add', '-A']);
+    git(['commit', '-qm', 'init']);
+  });
+
+  afterEach(async () => {
+    if (child && !child.killed && child.exitCode === null) {
+      child.kill('SIGKILL');
+      await new Promise<void>((resolve) => {
+        if (child?.exitCode === null) child.once('exit', () => resolve());
+        else resolve();
+      });
+    }
+    child = null;
+    if (server && !server.killed) server.kill('SIGKILL');
+    server = null;
+    for (const dir of [tmpDir, configDir]) {
+      if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('exits 12 when an auto-commit failed during the session', async () => {
+    // git refuses to add an ignored path, so every auto-commit fails.
+    fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'out/\n');
+    git(['add', '.gitignore']);
+    git(['commit', '-qm', 'ignore out']);
+
+    const port = await startServer();
+    await startWatch(port);
+    expect(await editUntilTranslated(path.join(srcDir, 'doc.md'))).toBe(true);
+    expect(
+      await waitUntil(() => /Auto-commit failed/.test(cliOutput), 15000)
+    ).toBe(true);
+
+    const code = await stopAndWait();
+
+    expect(cliOutput).toContain('Auto-commit failures: 1');
+    expect(code).toBe(12);
+  }, 90000);
+
+  it('exits 0 when every auto-commit succeeded', async () => {
+    const port = await startServer();
+    await startWatch(port);
+    expect(await editUntilTranslated(path.join(srcDir, 'doc.md'))).toBe(true);
+    expect(await waitUntil(() => /Auto-committed/.test(cliOutput), 15000)).toBe(
+      true
+    );
+
+    const code = await stopAndWait();
+
+    expect(cliOutput).not.toContain('Auto-commit failed');
+    expect(code).toBe(0);
+  }, 90000);
+});
diff --git a/tests/integration/watch-auto-commit.integration.test.ts b/tests/integration/watch-auto-commit.integration.test.ts
index 8787f073..af8540f6 100644
--- a/tests/integration/watch-auto-commit.integration.test.ts
+++ b/tests/integration/watch-auto-commit.integration.test.ts
@@ -208,4 +208,45 @@ describe('Watch auto-commit integration', () => {
       expect.any(String)
     );
   });
+
+  it('serializes concurrent auto-commits so every translation lands', async () => {
+    const files = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
+    for (const name of files) {
+      fs.writeFileSync(path.join(tmpDir, `${name}.es.md`), `Hola ${name}`);
+    }
+
+    const origCwd = process.cwd();
+    process.chdir(tmpDir);
+    try {
+      await Promise.all(
+        files.map((name) =>
+          callAutoCommit(`${name}.md`, {
+            targetLang: 'es',
+            text: `Hola ${name}`,
+            outputPath: path.join(tmpDir, `${name}.es.md`),
+          })
+        )
+      );
+    } finally {
+      process.chdir(origCwd);
+    }
+
+    const failures = (Logger.error as jest.Mock).mock.calls.filter((call) =>
+      String(call[0]).includes('Auto-commit failed')
+    );
+    expect(failures).toEqual([]);
+
+    const log = execSync('git log --oneline', {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    });
+    for (const name of files) {
+      expect(log).toContain(`auto-translate ${name}.md to es`);
+    }
+    const status = execSync('git status --porcelain', {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    });
+    expect(status.trim()).toBe('');
+  }, 60000);
 });
diff --git a/tests/unit/services/watch.test.ts b/tests/unit/services/watch.test.ts
index d41eeb20..7453b3c7 100644
--- a/tests/unit/services/watch.test.ts
+++ b/tests/unit/services/watch.test.ts
@@ -1804,4 +1804,119 @@ describe('WatchService', () => {
       expect(gate.pending).toHaveLength(1);
     });
   });
+
+  describe('onTranslate completion', () => {
+    const DEBOUNCE_MS = 5;
+    const settle = () =>
+      new Promise<void>((resolve) => setTimeout(resolve, DEBOUNCE_MS * 4));
+
+    it('waits for an async onTranslate before the path is free again', async () => {
+      let releaseNotify: (() => void) | undefined;
+      const onTranslate = jest.fn(
+        () =>
+          new Promise<void>((resolve) => {
+            releaseNotify = resolve;
+          })
+      );
+      mockFileTranslationService.translateFile.mockResolvedValue(undefined);
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      const testFile = path.join(testDir, 'doc.txt');
+      fs.writeFileSync(testFile, 'v1');
+
+      service.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+        onTranslate,
+      });
+
+      service.handleFileChange(testFile);
+      await settle();
+      expect(onTranslate).toHaveBeenCalledTimes(1);
+
+      service.handleFileChange(testFile);
+      await settle();
+      expect(mockFileTranslationService.translateFile).toHaveBeenCalledTimes(1);
+
+      releaseNotify!();
+      await settle();
+      expect(mockFileTranslationService.translateFile).toHaveBeenCalledTimes(2);
+      await service.stop();
+    });
+
+    it('reports a rejected onTranslate through onError', async () => {
+      const onError = jest.fn();
+      const onTranslate = jest.fn(() =>
+        Promise.reject(new Error('commit failed'))
+      );
+      mockFileTranslationService.translateFile.mockResolvedValue(undefined);
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      const testFile = path.join(testDir, 'doc.txt');
+      fs.writeFileSync(testFile, 'v1');
+
+      service.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+        onTranslate,
+        onError,
+      });
+
+      service.handleFileChange(testFile);
+      await settle();
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(onError.mock.calls[0]![1]).toEqual(
+        expect.objectContaining({ message: 'commit failed' })
+      );
+      expect(service.getStats().errorsCount).toBe(1);
+      await service.stop();
+    });
+
+    it('waits for an async onTranslate on the multiple-target path', async () => {
+      let releaseNotify: (() => void) | undefined;
+      const onTranslate = jest.fn(
+        () =>
+          new Promise<void>((resolve) => {
+            releaseNotify = resolve;
+          })
+      );
+      mockFileTranslationService.translateFileToMultiple.mockResolvedValue([
+        { targetLang: 'es', text: 'Hola', outputPath: '/out/doc.es.txt' },
+        { targetLang: 'fr', text: 'Bonjour', outputPath: '/out/doc.fr.txt' },
+      ]);
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      const testFile = path.join(testDir, 'doc.txt');
+      fs.writeFileSync(testFile, 'v1');
+
+      service.watch(testDir, {
+        targetLangs: ['es' as const, 'fr' as const],
+        outputDir: path.join(testDir, 'output'),
+        onTranslate,
+      });
+
+      service.handleFileChange(testFile);
+      await settle();
+      service.handleFileChange(testFile);
+      await settle();
+
+      expect(
+        mockFileTranslationService.translateFileToMultiple
+      ).toHaveBeenCalledTimes(1);
+
+      releaseNotify!();
+      await settle();
+      expect(
+        mockFileTranslationService.translateFileToMultiple
+      ).toHaveBeenCalledTimes(2);
+      await service.stop();
+    });
+  });
 });

From d00596d365aa06c5a514f7442e4b685206f649b1 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 16:02:56 +0200
Subject: [PATCH 164/256] fix(sync): hold the process lock in sync resolve and
 write the lockfile by rename

The process lock was honoured by two call sites, `deepl sync` and
`deepl sync pull`. `sync resolve` took none, and wrote the lockfile with a
plain fs.writeFile rather than the atomic rename every other lockfile writer
uses.

Measured through the built CLI with a slow sync holding the lock: a second
`deepl sync` was correctly refused at exit 7, while `deepl sync resolve`
proceeded, reported "Resolved 1 conflict" and wrote the merged lockfile at
exit 0 -- and once the sync finished, also exit 0, the merged entry was gone.
The sync had read the pre-merge lockfile at startup and wrote its whole
in-memory copy at the end. Both steps reported success, so the merge-conflict
recovery path lost the merge in silence.

resolve now takes the lock, --dry-run included to match sync pull, and its
write goes through atomicWriteFile: a crash part-way through leaves the
previous lockfile instead of a truncated one, and SyncLockManager.read() reads
a truncated lockfile as corrupt and replaces it with an empty one, which costs
a full re-translation.

A hand edit, a git merge or another tool takes no lock at all, so
SyncLockManager now remembers the identity of the file it read and warns when
the write is about to replace something else. It warns rather than refusing:
the guard would land after the target files are written and the translations
billed, so declining to record them would bill every one again next run --
the trap cli-8kr2.60 identified. Living in the manager covers all three
writers at once.

Three controls, one per layer, fixed sources copied aside first: plain write
back -> the 4 write-path unit tests fail; lock removed -> exactly the new e2e
fails with 53 others green; change warning suppressed -> exactly its own test
fails with its 4 over-rejection guards green.

The e2e beforeEach now also clears a leftover pidfile: a test that fails
part-way through while holding one made every following `sync` in the file
exit 7, which is how the control run surfaced it.

Refs cli-8kr2.45
---
 CHANGELOG.md                                  |   2 +
 docs/SYNC.md                                  |  13 ++
 .../commands/sync/register-sync-resolve.ts    | 119 ++++++++++--------
 src/sync/sync-lock.ts                         |  49 ++++++++
 src/sync/sync-resolve.ts                      |   7 +-
 tests/e2e/cli-sync.e2e.test.ts                |  72 +++++++++++
 tests/unit/sync/sync-lock.test.ts             |  82 ++++++++++++
 tests/unit/sync/sync-resolve.test.ts          |  41 +++++-
 8 files changed, 331 insertions(+), 54 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1d3ca3ea..5917f501 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -135,6 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`sync resolve`'s merge is no longer erased by a concurrent sync, and no longer risks truncating the lockfile.** The process lock was honoured by exactly two call sites — `deepl sync` and `deepl sync pull` — and `sync resolve` took none, while writing the lockfile with a plain `fs.writeFile` rather than the rename every other lockfile writer uses. Measured through the real CLI with a slow sync holding the lock: a second `deepl sync` was correctly refused at exit 7, while `deepl sync resolve` **proceeded**, reported `Resolved 1 conflict` and wrote the merged lockfile at exit 0 — and when the sync finished (also exit 0) the merged entry was gone, because the sync had read the pre-merge lockfile at startup and wrote its whole in-memory copy at the end. Both steps reported success, so the merge-conflict recovery path lost data silently. `sync resolve` now takes the lock — `--dry-run` included, matching `sync pull` — and exits 7 with the same "Another `deepl sync` process is running" message while one is held, leaving the conflict markers in place for after the sync. Its write goes through the atomic rename, so a crash part-way through leaves the previous lockfile instead of a truncated one; a truncated lockfile reads as corrupt and is replaced with an empty one, which costs a full re-translation of the project. And because a hand edit, a `git merge` or another tool takes no lock at all, a run whose lockfile changed on disk between its read and its write now says so and still records what it did — warning rather than refusing, since by that point the target files are written and the translations billed, and declining to record them would bill every one of them again on the next run.
+
 - **watch**: **`--auto-commit` no longer loses most commits under an edit storm.** `WatchService.onTranslate` was typed `=> void` and called without `await`, so the async callback the watch command supplies — the one that awaits `autoCommit` — had its promise discarded. The git work therefore ran outside the translation's concurrency slot, unbounded and untracked, and git holds `.git/index.lock` for the duration of an `add` or a `commit`, so parallel auto-commits knocked each other out. Measured through the real CLI in a real repository, six watched files edited at once with a 300 ms stub delay: **6 translations, 2 commits, 4 auto-commit failures** (three `git add` and one `git commit`, all lock contention), three output files left untracked and a fourth left staged but uncommitted — where an unrelated later commit would have swept it in. The session still exited 0. `onTranslate` may now return a promise and it is awaited, so the callback runs inside the translation's slot and a rejection reaches `onError`; the git work is additionally queued one `add`/`commit` pair at a time. Same harness after the fix: **6 translations, 6 commits, 0 failures**, nothing left untracked or staged. Translations of different files still run in parallel — only the git step is serialized.
 
 - **watch**: **a source file whose name carries a target-language segment is translated instead of being skipped for the whole session.** The loop guard that stops the CLI's own output re-triggering the watcher matched on the *name* alone, anywhere under the watched path, so `pricing.es.md` under `--to es` was silently dropped: measured through the real CLI, no request, no output file, and not even a `📝 Change detected` line, while `plain.md` in the same directory translated normally. Every file the watcher writes lands in the output directory, so the guard now also requires the file to be *inside* it — which leaves the loop protection complete and lets any such file outside it through. Verified on the same harness: `pricing.es.md` now produces `out/pricing.es.es.md`, and pointing `--output` at the watched directory still translates `doc.md` to `doc.es.md` exactly once with no further request. In that same-directory layout a file the CLI did not write is still skipped — the name is genuinely ambiguous there — but now says so once per file instead of doing nothing, naming the file and the output directory to move it out of. The CLI's own writes are skipped in silence, since that is the guard working.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index ef3933bb..c2c372d0 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -60,6 +60,17 @@ Sync also refuses to read or write any path resolving into `.git/` or `.github/`
 
 Only one `deepl sync` run is supported at a time per project directory. At startup, sync writes a `.deepl-sync.lock.pidfile` containing its PID; a second invocation that sees an existing pidfile whose PID is still alive exits with `ConfigError` (exit code 7). If the PID is dead (e.g., a previous run crashed), sync removes the stale pidfile with a warning and proceeds. The pidfile is deleted automatically on normal completion and on SIGINT/SIGTERM.
 
+Every command that writes `.deepl-sync.lock` takes the lock: `deepl sync`, `deepl sync pull` and `deepl sync resolve`, the last of these including `--dry-run`. A run reads the lockfile when it starts and writes its whole in-memory copy when it finishes, so anything written in between would be replaced. Read-only commands (`sync status`, `sync validate`, `sync audit`, `sync export`) do not take it.
+
+If the lockfile changes on disk between a run's read and its write anyway — a hand edit, a `git merge` or another tool, none of which take the lock — the run says so and still writes what it recorded:
+
+```
+.deepl-sync.lock changed on disk since this run read it; overwriting it with what this run recorded.
+Check the file into git before re-running if another tool or a merge wrote it.
+```
+
+It warns rather than refusing because by that point the target files are written and their translations billed; declining to record them would leave the next run to translate and bill all of them again.
+
 ## Supported File Formats
 
 | Format | Extensions | Used By |
@@ -805,6 +816,8 @@ Resolved 3 conflicts (1 theirs, 1 ours, 1 length-heuristic). Run "deepl sync" to
 
 **Dry-run.** `--dry-run` runs the full decision pipeline and prints the per-entry report without touching the lockfile. Use it to preview what `sync resolve` would do, especially when the report includes `length-heuristic` fallback warnings.
 
+**Concurrency.** `sync resolve` takes the process lock described under [Concurrent sync](#concurrent-sync), `--dry-run` included, and exits 7 while another sync holds it. Without the lock a resolve landing mid-sync was erased: the running sync had already read the pre-merge lockfile and overwrote the merged one when it finished, both steps at exit 0. The resolved lockfile is written by rename, so an interrupted resolve leaves the previous lockfile rather than a truncated one — a truncated lockfile reads as corrupt and costs a full re-translation.
+
 After resolving, run `deepl sync` to fill any translation gaps.
 
 ### Watch Mode (`deepl sync --watch`)
diff --git a/src/cli/commands/sync/register-sync-resolve.ts b/src/cli/commands/sync/register-sync-resolve.ts
index 0952560e..6def2430 100644
--- a/src/cli/commands/sync/register-sync-resolve.ts
+++ b/src/cli/commands/sync/register-sync-resolve.ts
@@ -50,72 +50,87 @@ async function handleSyncResolve(
     const { loadSyncConfig } = await import('../../../sync/sync-config.js');
     const { LOCK_FILE_NAME } = await import('../../../sync/types.js');
     const { resolveLockFile } = await import('../../../sync/sync-resolve.js');
+    const { acquireSyncProcessLock } =
+      await import('../../../sync/sync-process-lock.js');
     const pathMod = await import('path');
 
     const config = await loadSyncConfig(process.cwd(), {
       configPath: resolveSyncConfig(options, command),
     });
     const lockPath = pathMod.join(config.projectRoot, LOCK_FILE_NAME);
-    const result = await resolveLockFile(lockPath, { dryRun });
+    // `sync` reads the lockfile when it starts and writes its whole in-memory
+    // copy when it finishes, so a resolve landing in between is erased by the
+    // sync's own write. Held for a dry run too, matching `sync pull`: the file
+    // the report describes is about to be rewritten.
+    const processLock = acquireSyncProcessLock(config.projectRoot);
+    try {
+      const result = await resolveLockFile(lockPath, { dryRun });
 
-    if (!result.hadConflicts) {
-      if (options.format === 'json') {
-        process.stdout.write(
-          JSON.stringify({ ok: true, resolved: 0, decisions: [] }) + '\n'
-        );
-      } else {
-        Logger.info('No merge conflicts found in lock file.');
+      if (!result.hadConflicts) {
+        if (options.format === 'json') {
+          process.stdout.write(
+            JSON.stringify({ ok: true, resolved: 0, decisions: [] }) + '\n'
+          );
+        } else {
+          Logger.info('No merge conflicts found in lock file.');
+        }
+        return;
       }
-      return;
-    }
 
-    const decisions = result.decisions ?? [];
-    const counts = { ours: 0, theirs: 0, lengthHeuristic: 0, unresolved: 0 };
-    for (const d of decisions) {
-      const label = d.file ? pathMod.relative(config.projectRoot, d.file) : '';
-      const prefix = label ? `${label}:${d.key}` : d.key;
-      if (d.source === 'length-heuristic') {
-        counts.lengthHeuristic++;
-        Logger.warn(`WARN  ${prefix} — parse-error fallback used, ${d.reason}`);
-      } else if (d.source === 'unresolved') {
-        counts.unresolved++;
-        Logger.warn(`UNRESOLVED ${prefix} — ${d.reason}`);
-      } else {
-        if (d.source === 'ours') counts.ours++;
-        else counts.theirs++;
-        Logger.info(`Resolved ${prefix} (${d.reason})`);
+      const decisions = result.decisions ?? [];
+      const counts = { ours: 0, theirs: 0, lengthHeuristic: 0, unresolved: 0 };
+      for (const d of decisions) {
+        const label = d.file
+          ? pathMod.relative(config.projectRoot, d.file)
+          : '';
+        const prefix = label ? `${label}:${d.key}` : d.key;
+        if (d.source === 'length-heuristic') {
+          counts.lengthHeuristic++;
+          Logger.warn(
+            `WARN  ${prefix} — parse-error fallback used, ${d.reason}`
+          );
+        } else if (d.source === 'unresolved') {
+          counts.unresolved++;
+          Logger.warn(`UNRESOLVED ${prefix} — ${d.reason}`);
+        } else {
+          if (d.source === 'ours') counts.ours++;
+          else counts.theirs++;
+          Logger.info(`Resolved ${prefix} (${d.reason})`);
+        }
       }
-    }
 
-    if (result.resolved) {
-      if (options.format === 'json') {
-        process.stdout.write(
-          JSON.stringify({
-            ok: true,
-            resolved: result.entriesMerged,
-            decisions: decisions,
-          }) + '\n'
-        );
+      if (result.resolved) {
+        if (options.format === 'json') {
+          process.stdout.write(
+            JSON.stringify({
+              ok: true,
+              resolved: result.entriesMerged,
+              decisions: decisions,
+            }) + '\n'
+          );
+        } else {
+          const summaryParts = [
+            `${counts.theirs} theirs`,
+            `${counts.ours} ours`,
+            `${counts.lengthHeuristic} length-heuristic`,
+          ];
+          if (counts.unresolved > 0)
+            summaryParts.push(`${counts.unresolved} unresolved`);
+          const dryRunSuffix = dryRun ? ' (dry-run: no files written)' : '';
+          Logger.info(
+            `Resolved ${result.entriesMerged} conflict${
+              result.entriesMerged === 1 ? '' : 's'
+            } (${summaryParts.join(', ')}).${dryRunSuffix} Run "deepl sync" to fill any gaps.`
+          );
+        }
       } else {
-        const summaryParts = [
-          `${counts.theirs} theirs`,
-          `${counts.ours} ours`,
-          `${counts.lengthHeuristic} length-heuristic`,
-        ];
-        if (counts.unresolved > 0)
-          summaryParts.push(`${counts.unresolved} unresolved`);
-        const dryRunSuffix = dryRun ? ' (dry-run: no files written)' : '';
-        Logger.info(
-          `Resolved ${result.entriesMerged} conflict${
-            result.entriesMerged === 1 ? '' : 's'
-          } (${summaryParts.join(', ')}).${dryRunSuffix} Run "deepl sync" to fill any gaps.`
+        throw new SyncConflictError(
+          'Could not automatically resolve lock file conflicts. Manual resolution required.',
+          'Edit .deepl-sync.lock to resolve conflict markers manually, then run `deepl sync` to fill gaps.'
         );
       }
-    } else {
-      throw new SyncConflictError(
-        'Could not automatically resolve lock file conflicts. Manual resolution required.',
-        'Edit .deepl-sync.lock to resolve conflict markers manually, then run `deepl sync` to fill gaps.'
-      );
+    } finally {
+      processLock.release();
     }
   } catch (error) {
     if (options.format === 'json') {
diff --git a/src/sync/sync-lock.ts b/src/sync/sync-lock.ts
index 316b4c19..e78fb1bd 100644
--- a/src/sync/sync-lock.ts
+++ b/src/sync/sync-lock.ts
@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as crypto from 'crypto';
+import * as path from 'path';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { Logger } from '../utils/logger.js';
 import { getOwnMember, setOwnMember } from '../utils/own-members.js';
@@ -264,10 +265,35 @@ function recomputeStats(lockFile: SyncLockFile): void {
 
 export class SyncLockManager {
   private readonly statsComputedFor = new WeakMap<SyncLockFile, number>();
+  /**
+   * Identity of the lock file as this instance last saw it, or `undefined`
+   * before the first read. `null` records "no file there".
+   */
+  private lastSeen: string | null | undefined;
 
   constructor(private readonly lockFilePath: string) {}
 
+  /**
+   * Identity of the file on disk right now. Size and mtime alone can repeat
+   * across a same-length rewrite within one mtime tick, so the inode is part of
+   * it — every writer here replaces the file by rename, which changes it.
+   */
+  private async fingerprint(): Promise<string | null> {
+    try {
+      const stats = await fs.promises.stat(this.lockFilePath);
+      return `${stats.mtimeMs}:${stats.size}:${stats.ino}`;
+    } catch {
+      return null;
+    }
+  }
+
   async read(): Promise<SyncLockFile> {
+    const lockFile = await this.readLockFile();
+    this.lastSeen = await this.fingerprint();
+    return lockFile;
+  }
+
+  private async readLockFile(): Promise<SyncLockFile> {
     try {
       await fs.promises.access(this.lockFilePath);
     } catch {
@@ -382,11 +408,34 @@ export class SyncLockManager {
     }
     lockFile.generated_at = new Date().toISOString();
     lockFile._comment = LOCK_FILE_COMMENT;
+    await this.warnIfChangedSinceRead();
     await atomicWriteFile(
       this.lockFilePath,
       serializeLockFile(lockFile),
       'utf-8'
     );
+    this.lastSeen = await this.fingerprint();
+  }
+
+  /**
+   * A run reads the lock file when it starts and writes its whole in-memory
+   * copy when it finishes, so anything written in between is replaced. Every
+   * writing sync command holds the process lock, which is what stops two of
+   * them overlapping; this catches the rest — a hand edit, a `git merge`, or
+   * another tool — where the alternative is losing the other write in silence.
+   *
+   * A warning rather than a refusal: by the time this runs the target files
+   * are already written and their translations billed, so declining to record
+   * them would leave the next run to translate and bill them all over again.
+   */
+  private async warnIfChangedSinceRead(): Promise<void> {
+    if (this.lastSeen === undefined) return;
+    const current = await this.fingerprint();
+    if (current === this.lastSeen) return;
+    Logger.warn(
+      `${path.basename(this.lockFilePath)} changed on disk since this run read it; overwriting it with what this run recorded. ` +
+        'Check the file into git before re-running if another tool or a merge wrote it.'
+    );
   }
 
   async updateEntry(
diff --git a/src/sync/sync-resolve.ts b/src/sync/sync-resolve.ts
index 9e61e5fb..7a953f4d 100644
--- a/src/sync/sync-resolve.ts
+++ b/src/sync/sync-resolve.ts
@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import { serializeLockFile } from './sync-lock.js';
+import { atomicWriteFile } from '../utils/atomic-write.js';
 import type { SyncLockFile } from './types.js';
 
 const CONFLICT_START = /^<{7}/m;
@@ -331,7 +332,11 @@ export async function resolveLockFile(
       typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
         ? serializeLockFile(parsed as SyncLockFile)
         : resolved;
-    await fs.promises.writeFile(lockPath, canonical, 'utf-8');
+    // Rename rather than rewrite: a crash part-way through a plain write
+    // truncates the lockfile, and SyncLockManager.read() treats a truncated
+    // lockfile as corrupt and replaces it with an empty one, discarding every
+    // translation record and forcing a full re-translation.
+    await atomicWriteFile(lockPath, canonical, 'utf-8');
   }
   return {
     hadConflicts: true,
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index ec6d76f8..e8925eeb 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -201,6 +201,10 @@ describe('CLI Sync E2E', () => {
     if (fs.existsSync(lockFile)) fs.unlinkSync(lockFile);
     const syncConfig = path.join(testFiles.path, '.deepl-sync.yaml');
     if (fs.existsSync(syncConfig)) fs.unlinkSync(syncConfig);
+    // A pidfile left behind by a test that failed part-way through would make
+    // every following `sync` in this file exit 7 on the process lock.
+    const pidFile = path.join(testFiles.path, '.deepl-sync.lock.pidfile');
+    if (fs.existsSync(pidFile)) fs.unlinkSync(pidFile);
   });
 
   afterAll(() => {
@@ -995,6 +999,39 @@ describe('CLI Sync E2E', () => {
     });
   });
 
+  /** A lockfile carrying real git conflict markers around one translation. */
+  function conflictedLockFixture(): string {
+    const entry = (hash: string): string =>
+      JSON.stringify({
+        hash,
+        translated_at: '2026-04-18T12:00:00Z',
+        status: 'translated',
+      });
+    return [
+      '{',
+      '  "version": 1,',
+      '  "generated_at": "2026-04-18T12:00:00Z",',
+      '  "source_locale": "en",',
+      '  "entries": {',
+      '    "locales/en.json": {',
+      '      "greeting": {',
+      '        "source_hash": "src1",',
+      '        "source_text": "Hello",',
+      '        "translations": {',
+      '<<<<<<< HEAD',
+      `          "de": ${entry('abc123')}`,
+      '=======',
+      `          "de": ${entry('xyz789')}`,
+      '>>>>>>> feature/other',
+      '        }',
+      '      }',
+      '    }',
+      '  },',
+      '  "stats": { "total_keys": 1, "total_translations": 1, "last_sync": "2026-04-18T12:00:00Z" }',
+      '}',
+    ].join('\n');
+  }
+
   describe('sync resolve on conflict-marked lockfile', () => {
     it('rewrites a lockfile that contains git conflict markers as valid JSON and exits 0', () => {
       writeSyncConfig(testFiles.path, ['de']);
@@ -1048,6 +1085,41 @@ describe('CLI Sync E2E', () => {
       expect(after).not.toContain('>>>>>>>');
     });
 
+    it('refuses to run while another sync holds the process lock, leaving the lockfile untouched', () => {
+      writeSyncConfig(testFiles.path, ['de']);
+      writeSourceFile(testFiles.path);
+      const lockPath = path.join(testFiles.path, '.deepl-sync.lock');
+      fs.writeFileSync(lockPath, conflictedLockFixture());
+
+      // This test process is alive, so the pidfile describes a running sync.
+      const pidFile = path.join(testFiles.path, '.deepl-sync.lock.pidfile');
+      fs.writeFileSync(
+        pidFile,
+        JSON.stringify({
+          pid: process.pid,
+          startedAt: new Date('2026-04-18T12:00:00Z').toISOString(),
+        })
+      );
+
+      const blocked = runSyncExpectError('resolve');
+
+      expect(blocked.status).toBe(7);
+      expect(blocked.output).toContain(
+        'Another `deepl sync` process is running'
+      );
+      // The merge result would be erased by the running sync's own lockfile
+      // write, so nothing may be written while the lock is held.
+      expect(fs.readFileSync(lockPath, 'utf-8')).toContain('<<<<<<<');
+
+      fs.unlinkSync(pidFile);
+      const output = runSyncAll('resolve');
+
+      expect(output.toLowerCase()).toMatch(/resolv/);
+      expect(fs.readFileSync(lockPath, 'utf-8')).not.toContain('<<<<<<<');
+      // The lock is released even though resolve wrote the lockfile.
+      expect(fs.existsSync(pidFile)).toBe(false);
+    });
+
     it('prints a per-entry decision report with summary line', () => {
       writeSyncConfig(testFiles.path, ['de']);
       writeSourceFile(testFiles.path);
diff --git a/tests/unit/sync/sync-lock.test.ts b/tests/unit/sync/sync-lock.test.ts
index 7cdd47ca..07c9a882 100644
--- a/tests/unit/sync/sync-lock.test.ts
+++ b/tests/unit/sync/sync-lock.test.ts
@@ -898,3 +898,85 @@ describe('SyncLockManager', () => {
     });
   });
 });
+
+describe('SyncLockManager change detection', () => {
+  let tmpDir: string;
+  let lockPath: string;
+  let warn: jest.SpyInstance;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-lock-change-'));
+    lockPath = path.join(tmpDir, '.deepl-sync.lock');
+    warn = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const warnings = (): string[] =>
+    warn.mock.calls.map((call) => String(call[0]));
+
+  it('warns when the file changed on disk between the read and the write', async () => {
+    const manager = new SyncLockManager(lockPath);
+    fs.writeFileSync(lockPath, serializeLockFile(createEmptyLockFile('en')));
+
+    const lockFile = await manager.read();
+
+    // Something outside this run replaces the file: a merge, a hand edit, or
+    // another tool. The write below is about to overwrite it wholesale.
+    const other = createEmptyLockFile('en');
+    other.entries['locales/en.json'] = {
+      greeting: {
+        source_hash: 'other',
+        translations: {},
+      } as unknown as SyncLockEntry,
+    };
+    fs.writeFileSync(lockPath, serializeLockFile(other));
+
+    await manager.write(lockFile);
+
+    expect(
+      warnings().filter((message) => /changed on disk/.test(message))
+    ).toHaveLength(1);
+  });
+
+  it('does not warn on an ordinary read-then-write', async () => {
+    const manager = new SyncLockManager(lockPath);
+    fs.writeFileSync(lockPath, serializeLockFile(createEmptyLockFile('en')));
+
+    const lockFile = await manager.read();
+    await manager.write(lockFile);
+
+    expect(warnings().filter((m) => /changed on disk/.test(m))).toEqual([]);
+  });
+
+  it('does not warn when there was no lock file to begin with', async () => {
+    const manager = new SyncLockManager(lockPath);
+
+    const lockFile = await manager.read();
+    await manager.write(lockFile);
+
+    expect(warnings().filter((m) => /changed on disk/.test(m))).toEqual([]);
+  });
+
+  it('does not warn when writing without having read first', async () => {
+    fs.writeFileSync(lockPath, serializeLockFile(createEmptyLockFile('en')));
+    const manager = new SyncLockManager(lockPath);
+
+    await manager.write(createEmptyLockFile('en'));
+
+    expect(warnings().filter((m) => /changed on disk/.test(m))).toEqual([]);
+  });
+
+  it('does not warn on a second write in the same run', async () => {
+    const manager = new SyncLockManager(lockPath);
+    fs.writeFileSync(lockPath, serializeLockFile(createEmptyLockFile('en')));
+
+    const lockFile = await manager.read();
+    await manager.write(lockFile);
+    await manager.write(lockFile);
+
+    expect(warnings().filter((m) => /changed on disk/.test(m))).toEqual([]);
+  });
+});
diff --git a/tests/unit/sync/sync-resolve.test.ts b/tests/unit/sync/sync-resolve.test.ts
index 42c23dc3..cc9b8eb5 100644
--- a/tests/unit/sync/sync-resolve.test.ts
+++ b/tests/unit/sync/sync-resolve.test.ts
@@ -5,6 +5,7 @@ import {
   resolveLockFile,
 } from '../../../src/sync/sync-resolve';
 import type { ResolveDecision } from '../../../src/sync/sync-resolve';
+import { atomicWriteFile } from '../../../src/utils/atomic-write';
 
 jest.mock('fs', () => {
   const actual = jest.requireActual('fs');
@@ -18,10 +19,22 @@ jest.mock('fs', () => {
   };
 });
 
+jest.mock('../../../src/utils/atomic-write', () => ({
+  atomicWriteFile: jest.fn(),
+}));
+
 const mockReadFile = fs.promises.readFile as jest.MockedFunction<
   typeof fs.promises.readFile
 >;
-const mockWriteFile = fs.promises.writeFile as jest.MockedFunction<
+/**
+ * The lockfile must be replaced by a rename, never rewritten in place: a crash
+ * part-way through a plain write truncates it, and SyncLockManager.read() reads
+ * a truncated lockfile as corrupt and discards every translation record in it.
+ */
+const mockWriteFile = atomicWriteFile as jest.MockedFunction<
+  typeof atomicWriteFile
+>;
+const mockRawWriteFile = fs.promises.writeFile as jest.MockedFunction<
   typeof fs.promises.writeFile
 >;
 
@@ -678,6 +691,32 @@ describe('resolveLockFile()', () => {
   });
 });
 
+describe('lockfile write durability', () => {
+  const lockPath = '/tmp/test-sync/.deepl-sync.lock.json';
+
+  it('replaces the lock file by rename rather than rewriting it in place', async () => {
+    mockReadFile.mockResolvedValue(
+      [
+        '<<<<<<< HEAD',
+        '{"greeting": {"source_hash": "abc", "translated_at": "2025-01-01T00:00:00Z"}}',
+        '=======',
+        '{"greeting": {"source_hash": "abc", "translated_at": "2025-06-01T00:00:00Z"}}',
+        '>>>>>>> branch',
+      ].join('\n')
+    );
+    mockWriteFile.mockResolvedValue(undefined);
+
+    await resolveLockFile(lockPath);
+
+    expect(mockWriteFile).toHaveBeenCalledWith(
+      lockPath,
+      expect.any(String),
+      'utf-8'
+    );
+    expect(mockRawWriteFile).not.toHaveBeenCalled();
+  });
+});
+
 describe('per-entry decision report', () => {
   it('resolveConflicts returns per-key decisions with source and reason', () => {
     const content = [

From 9d1245b41051c06e561fd8f62949995fc18f1b17 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 17:53:36 +0200
Subject: [PATCH 165/256] fix(sync): keep a stale backup whose target no longer
 holds its content

`deepl sync` refuses to overwrite an existing `<target>.deepl.bak` because
after a `kill -9` that backup holds the only surviving copy of the user's
translations. The startup sweep ran first and unlinked every `.deepl.bak`
older than `sync.bak_sweep_max_age_seconds` without reading it, so five
minutes after the crash there was nothing left for that guard to collide
with: the recovery run backed up the machine output afresh, translated, and
unlinked its own backup at exit 0.

A stale backup is now deleted only when the file beside it already holds the
same bytes. A run that reaches its end unlinks its own backups, so one still
on disk is from a run that did not, and there it is the last copy of
whatever that run had already overwritten. Sizes are compared before
contents. A backup whose target has diverged, or whose target is gone, is
kept however old it is and reported once per sweep by path. Retention is
bounded at one file per target because the backup's name is derived from the
target's.

Refs cli-8kr2.52
---
 CHANGELOG.md                                  |   2 +
 docs/SYNC.md                                  |  13 +-
 src/sync/sync-bak-cleanup.ts                  |  69 +++++++++-
 tests/e2e/cli-sync.e2e.test.ts                |  40 ++++++
 ...sync-watch-reliability.integration.test.ts |   3 +
 tests/integration/sync.integration.test.ts    |  46 +++++++
 tests/unit/sync/sync-bak-cleanup.test.ts      | 127 +++++++++++++++++-
 7 files changed, 288 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5917f501..9b819897 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -135,6 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **the startup stale-backup sweep no longer deletes a crashed run's backup, so recovery is no longer limited to the five minutes after the crash.** `deepl sync` refuses to overwrite an existing `<target>.deepl.bak` (`COPYFILE_EXCL`, warn, leave it alone) precisely because after a `kill -9` that backup holds the only surviving copy of the user's translations — but the sweep runs first, at startup, and unlinked every `.deepl.bak` older than `sync.bak_sweep_max_age_seconds` (default 300) without looking at its content, which left that guard nothing to collide with. Reproduced end to end against a mock endpoint: with `locales/de.json` holding machine output, `locales/de.json.deepl.bak` holding `"HUMAN TRANSLATION"`, no lockfile, and the backup's mtime backdated ten minutes, `deepl sync --yes` reported `✓ de: 1/1 keys`, `Sync complete: 1 new`, **exit 0**, and the human translation existed nowhere in the project afterwards — the same harm the `COPYFILE_EXCL` guard was added to prevent, reached around it. The identical run with the backup dated ten **seconds** earlier kept it and warned, which is what made age the whole of the bug. A stale backup is now deleted only when the file beside it already holds the same bytes: a run that reaches its end unlinks its own backups, so one still on disk is from a run that did not, and there it is the last copy of whatever that run had already overwritten. Size is compared first and the contents only when the sizes agree, so the common case (no backup at all) costs one `readdir` as before. A backup whose target has diverged, or whose target is gone, is kept however old it is and reported once per sweep, naming the file: `Keeping 1 leftover backup file whose content is not in the file beside it: locales/de.json.deepl.bak. It is from a run that did not finish, so it may hold the only copy of translations that run overwrote.` Retention is bounded at one file per target, since the backup's name is derived from the target's, so this cannot accumulate. `bak_sweep_max_age_seconds` keeps its meaning for redundant backups and no longer sets a deadline for recovering a crashed run. The fix is in `sweepStaleBackups`, which every caller shares — `deepl sync`, `sync push`, `sync pull`, `sync export` and `sync --watch`'s startup sweep. Three tests asserted the old policy by giving a stale backup no sibling or a differing one; those fixtures now say which case they mean.
+
 - **sync**: **`sync resolve`'s merge is no longer erased by a concurrent sync, and no longer risks truncating the lockfile.** The process lock was honoured by exactly two call sites — `deepl sync` and `deepl sync pull` — and `sync resolve` took none, while writing the lockfile with a plain `fs.writeFile` rather than the rename every other lockfile writer uses. Measured through the real CLI with a slow sync holding the lock: a second `deepl sync` was correctly refused at exit 7, while `deepl sync resolve` **proceeded**, reported `Resolved 1 conflict` and wrote the merged lockfile at exit 0 — and when the sync finished (also exit 0) the merged entry was gone, because the sync had read the pre-merge lockfile at startup and wrote its whole in-memory copy at the end. Both steps reported success, so the merge-conflict recovery path lost data silently. `sync resolve` now takes the lock — `--dry-run` included, matching `sync pull` — and exits 7 with the same "Another `deepl sync` process is running" message while one is held, leaving the conflict markers in place for after the sync. Its write goes through the atomic rename, so a crash part-way through leaves the previous lockfile instead of a truncated one; a truncated lockfile reads as corrupt and is replaced with an empty one, which costs a full re-translation of the project. And because a hand edit, a `git merge` or another tool takes no lock at all, a run whose lockfile changed on disk between its read and its write now says so and still records what it did — warning rather than refusing, since by that point the target files are written and the translations billed, and declining to record them would bill every one of them again on the next run.
 
 - **watch**: **`--auto-commit` no longer loses most commits under an edit storm.** `WatchService.onTranslate` was typed `=> void` and called without `await`, so the async callback the watch command supplies — the one that awaits `autoCommit` — had its promise discarded. The git work therefore ran outside the translation's concurrency slot, unbounded and untracked, and git holds `.git/index.lock` for the duration of an `add` or a `commit`, so parallel auto-commits knocked each other out. Measured through the real CLI in a real repository, six watched files edited at once with a 300 ms stub delay: **6 translations, 2 commits, 4 auto-commit failures** (three `git add` and one `git commit`, all lock contention), three output files left untracked and a fourth left staged but uncommitted — where an unrelated later commit would have swept it in. The session still exited 0. `onTranslate` may now return a promise and it is awaited, so the callback runs inside the translation's slot and a rejection reaches `onError`; the git work is additionally queued one `add`/`commit` pair at a time. Same harness after the fix: **6 translations, 6 commits, 0 failures**, nothing left untracked or staged. Translations of different files still run in parallel — only the git step is serialized.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index c2c372d0..613d156e 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -839,7 +839,18 @@ deepl sync --watch --dry-run
 
 **Event coalescing.** Only one sync runs at a time. If more file-change events arrive while a sync is in flight, they are coalesced into a **single** follow-up run that starts after the current sync completes — no matter how many bursts of edits fired in between. Earlier releases silently dropped these in-flight events, which could leave the final edit of a burst unsynced until the user triggered another change manually.
 
-**Stale `.deepl.bak` sweep.** On startup, the watcher sweeps for `.deepl.bak` siblings older than 5 minutes (files with any other suffix, including plain `.bak`, are never touched). The sweep only ever deletes: a stale backup is removed outright, and no target file is ever created or overwritten from one. Target writes go through an atomic write-then-rename, so a watcher killed mid-translation cannot leave a truncated or zero-length target that would need restoring. The sweep is scoped to the directories implied by each bucket's `include` globs; a glob that begins with a wildcard (`**/en.json`, `*.json`) has no literal directory prefix to scope to and is skipped, so a bucket configured that way may accumulate `.deepl.bak` files. Run with `--verbose` to see when a glob is skipped for this reason.
+**Stale `.deepl.bak` sweep.** On startup, the watcher sweeps for `.deepl.bak` siblings older than 5 minutes (files with any other suffix, including plain `.bak`, are never touched). The sweep only ever deletes: no target file is ever created or overwritten from a backup. Target writes go through an atomic write-then-rename, so a watcher killed mid-translation cannot leave a truncated or zero-length target that would need restoring. The sweep is scoped to the directories implied by each bucket's `include` globs; a glob that begins with a wildcard (`**/en.json`, `*.json`) has no literal directory prefix to scope to and is skipped, so a bucket configured that way may accumulate `.deepl.bak` files. Run with `--verbose` to see when a glob is skipped for this reason.
+
+**Age is not the only condition.** A stale backup is deleted only when the file beside it already holds the same bytes. A run that reaches its end unlinks its own backups, so a backup still on disk is from a run that did not — and there it holds the only surviving copy of whatever that run had already overwritten. One whose target has diverged is kept however old it is, and reported once per sweep:
+
+```
+Keeping 1 leftover backup file whose content is not in the file beside it:
+locales/de.json.deepl.bak. It is from a run that did not finish, so it may
+hold the only copy of translations that run overwrote. Compare it with the
+file it backs up before removing it; it is not swept while the two differ.
+```
+
+Retention is bounded at one file per target, because the backup's name is derived from the target's. `bak_sweep_max_age_seconds` still sets how long a redundant backup is left on disk; it no longer sets a deadline for recovering a crashed run.
 
 **Scope.** Watched paths are the `buckets.*.include` globs from `.deepl-sync.yaml`, plus `.deepl-sync.yaml` itself. When `.deepl-sync.yaml` changes, the config is reloaded from disk before the next sync cycle runs — YAML values like bucket definitions, `formality`, `glossary`, and `model_type` are picked up without restarting the watcher. Sending `SIGHUP` (`kill -HUP <pid>`) also force-reloads the config immediately, without waiting for a file-change event. Watch mode does not cross-talk with the separate `deepl watch` command (which is for translating individual plain-text files).
 
diff --git a/src/sync/sync-bak-cleanup.ts b/src/sync/sync-bak-cleanup.ts
index cee80955..695da67e 100644
--- a/src/sync/sync-bak-cleanup.ts
+++ b/src/sync/sync-bak-cleanup.ts
@@ -70,8 +70,20 @@ export function bucketSweepRoots(
 
 /**
  * Walk `projectRoot` breadth-first and remove `.deepl.bak` files whose mtime
- * is older than `maxAgeMs`. Nothing is ever written: the sweep only unlinks,
- * and files with any other suffix (including plain `.bak`) are left untouched.
+ * is older than `maxAgeMs` **and** whose content the file beside them already
+ * holds. Nothing is ever written: the sweep only unlinks, and files with any
+ * other suffix (including plain `.bak`) are left untouched.
+ *
+ * Age alone is not a safe test. A run that reaches its end unlinks its own
+ * backups, so a backup still on disk is from a run that did not — and there it
+ * holds the only surviving copy of whatever that run had already overwritten.
+ * Deleting it on age made the natural recovery action (re-run `deepl sync`)
+ * destroy the user's translations at exit 0 once the crash was more than
+ * `bak_sweep_max_age_seconds` old, because the recovery run's
+ * `COPYFILE_EXCL` guard has nothing left to collide with. A backup whose
+ * target holds the same bytes is the litter this sweep exists for; one whose
+ * target does not is kept indefinitely and reported. Retention is bounded at
+ * one file per target, since the backup name is derived from the target's.
  *
  * It used to restore a zero-length sibling from its backup first. Because
  * every target write goes through `atomicWriteFile`, which renames a
@@ -105,15 +117,58 @@ export async function sweepStaleBackups(
     }
     roots = [projectRoot];
   }
+  const kept: string[] = [];
   for (const root of roots) {
-    await sweepDir(root, visited, threshold);
+    await sweepDir(root, visited, threshold, kept);
+  }
+  if (kept.length > 0) {
+    Logger.warn(keptBackupsWarning(projectRoot, kept));
+  }
+}
+
+function keptBackupsWarning(projectRoot: string, kept: string[]): string {
+  const rel = kept.map((p) => path.relative(projectRoot, p)).sort();
+  const shown = rel.slice(0, 3);
+  const more = rel.length > shown.length ? ', …' : '';
+  const one = rel.length === 1;
+  return (
+    `Keeping ${rel.length} leftover backup ${one ? 'file' : 'files'} whose content is not in the ` +
+    `${one ? 'file' : 'files'} beside ${one ? 'it' : 'them'}: ${shown.join(', ')}${more}. ` +
+    `${one ? 'It is' : 'They are'} from a run that did not finish, so ${one ? 'it' : 'they'} may hold ` +
+    `the only ${one ? 'copy' : 'copies'} of translations that run overwrote. Compare ` +
+    `${one ? 'it' : 'each'} with the file it backs up before removing it; ` +
+    `${one ? 'it is' : 'they are'} not swept while the two differ.`
+  );
+}
+
+/**
+ * True when a backup holds bytes its target no longer has, which makes it the
+ * last copy of that content. Errors count as unique: a target that cannot be
+ * read cannot be shown to hold the backup's content.
+ */
+async function holdsUnsavedContent(
+  bakPath: string,
+  bakSize: number
+): Promise<boolean> {
+  const targetPath = bakPath.slice(0, -BACKUP_SUFFIX.length);
+  try {
+    const targetStat = await fs.promises.stat(targetPath);
+    if (!targetStat.isFile() || targetStat.size !== bakSize) return true;
+    const [bakContent, targetContent] = await Promise.all([
+      fs.promises.readFile(bakPath),
+      fs.promises.readFile(targetPath),
+    ]);
+    return !bakContent.equals(targetContent);
+  } catch {
+    return true;
   }
 }
 
 async function sweepDir(
   dir: string,
   visited: Set<string>,
-  threshold: number
+  threshold: number,
+  kept: string[]
 ): Promise<void> {
   const real = (() => {
     try {
@@ -134,13 +189,17 @@ async function sweepDir(
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === 'node_modules' || entry.name === '.git') continue;
-      await sweepDir(full, visited, threshold);
+      await sweepDir(full, visited, threshold, kept);
       continue;
     }
     if (!entry.isFile() || !entry.name.endsWith(BACKUP_SUFFIX)) continue;
     try {
       const stat = await fs.promises.stat(full);
       if (stat.mtimeMs >= threshold) continue;
+      if (await holdsUnsavedContent(full, stat.size)) {
+        kept.push(full);
+        continue;
+      }
       try {
         await fs.promises.unlink(full);
       } catch {
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index e8925eeb..281677ea 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -282,6 +282,46 @@ describe('CLI Sync E2E', () => {
     });
   });
 
+  // Recovering from a crash means re-running sync, and the startup sweep used
+  // to delete the crashed run's backup on age before that run's own
+  // COPYFILE_EXCL guard could protect it.
+  describe('recovery run over a backup left by a crashed run', () => {
+    it('keeps a stale backup whose target has diverged and says so', () => {
+      writeSyncConfig(testFiles.path, ['de']);
+      const dir = path.join(testFiles.path, 'locales');
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'en.json'),
+        JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
+      );
+      // What a `kill -9` mid-sync leaves behind: machine output in the target,
+      // the only copy of the human translations in the backup, no lockfile.
+      fs.writeFileSync(
+        path.join(dir, 'de.json'),
+        JSON.stringify({ greeting: 'machine output' }, null, 2) + '\n'
+      );
+      const bakPath = path.join(dir, 'de.json.deepl.bak');
+      fs.writeFileSync(
+        bakPath,
+        JSON.stringify({ greeting: 'Guten Tag' }, null, 2) + '\n'
+      );
+      const anHourAgo = new Date(Date.now() - 60 * 60_000);
+      fs.utimesSync(bakPath, anHourAgo, anHourAgo);
+
+      const result = runSyncExpectError('--yes');
+
+      expect(result.status).toBe(0);
+      expect(result.output).toContain('de.json.deepl.bak');
+      expect(result.output).toMatch(/from a run that did not finish/);
+      expect(fs.existsSync(bakPath)).toBe(true);
+      const parsed = JSON.parse(fs.readFileSync(bakPath, 'utf-8')) as Record<
+        string,
+        string
+      >;
+      expect(parsed['greeting']).toBe('Guten Tag');
+    });
+  });
+
   // A key colliding with an Object.prototype member reaches the insertion path
   // the second time round: the target file already exists, so a key the source
   // has just gained has to be added to it.
diff --git a/tests/integration/sync-watch-reliability.integration.test.ts b/tests/integration/sync-watch-reliability.integration.test.ts
index 6f6bbed6..30269c31 100644
--- a/tests/integration/sync-watch-reliability.integration.test.ts
+++ b/tests/integration/sync-watch-reliability.integration.test.ts
@@ -294,6 +294,9 @@ describe('watch mode reliability', () => {
       const staleBak = path.join(tmpDir, 'locales', 'de.json.deepl.bak');
       fs.mkdirSync(path.dirname(staleBak), { recursive: true });
       fs.writeFileSync(staleBak, 'stale', 'utf-8');
+      // The target holds the same bytes, so the backup is redundant — a
+      // backup whose target has diverged is kept whatever its age.
+      fs.writeFileSync(path.join(tmpDir, 'locales', 'de.json'), 'stale');
       // backdate the mtime by 10 minutes
       const tenMinAgo = new Date(Date.now() - 10 * 60_000);
       fs.utimesSync(staleBak, tenMinAgo, tenMinAgo);
diff --git a/tests/integration/sync.integration.test.ts b/tests/integration/sync.integration.test.ts
index fbc44c14..f8f7b0ef 100644
--- a/tests/integration/sync.integration.test.ts
+++ b/tests/integration/sync.integration.test.ts
@@ -849,6 +849,13 @@ buckets:
       const staleBak = path.join(tmpDir, 'locales', 'de.json.deepl.bak');
       fs.mkdirSync(path.dirname(staleBak), { recursive: true });
       fs.writeFileSync(staleBak, 'orphan from prior crash', 'utf-8');
+      // The target already holds the backup's content, so the backup is the
+      // litter this sweep exists to remove.
+      fs.writeFileSync(
+        path.join(tmpDir, 'locales', 'de.json'),
+        'orphan from prior crash',
+        'utf-8'
+      );
       // Backdate 10 minutes past the 5-minute default threshold.
       const tenMinAgo = new Date(Date.now() - 10 * 60_000);
       fs.utimesSync(staleBak, tenMinAgo, tenMinAgo);
@@ -879,6 +886,7 @@ sync:
       const staleBak = path.join(tmpDir, 'locales', 'de.json.deepl.bak');
       fs.mkdirSync(path.dirname(staleBak), { recursive: true });
       fs.writeFileSync(staleBak, 'orphan', 'utf-8');
+      fs.writeFileSync(path.join(tmpDir, 'locales', 'de.json'), 'orphan');
       // 2 minutes old — stale under the 60-second override, fresh under the default.
       const twoMinAgo = new Date(Date.now() - 2 * 60_000);
       fs.utimesSync(staleBak, twoMinAgo, twoMinAgo);
@@ -889,6 +897,44 @@ sync:
       expect(fs.existsSync(staleBak)).toBe(false);
     });
 
+    // A crashed run leaves the target holding machine output and the backup
+    // holding the only copy of the human translations. Re-running sync is the
+    // natural recovery action, and the startup sweep used to delete that
+    // backup on age before the run's own COPYFILE_EXCL guard could protect it.
+    it('keeps a backup from a crashed run however old it is when the target has diverged', async () => {
+      writeYamlConfig(tmpDir, BASIC_CONFIG_YAML);
+      writeSourceFile(tmpDir, 'locales/en.json', '{"greeting":"Hello"}\n');
+      writeSourceFile(
+        tmpDir,
+        'locales/de.json',
+        '{"greeting":"machine output"}\n'
+      );
+      const bakPath = path.join(tmpDir, 'locales', 'de.json.deepl.bak');
+      fs.writeFileSync(bakPath, '{"greeting":"Guten Tag"}\n', 'utf-8');
+      const anHourAgo = new Date(Date.now() - 60 * 60_000);
+      fs.utimesSync(bakPath, anHourAgo, anHourAgo);
+
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .reply(200, {
+          translations: [
+            {
+              text: 'Hallo',
+              detected_source_language: 'EN',
+              billed_characters: 5,
+            },
+          ],
+        });
+
+      const config = await loadSyncConfig(tmpDir);
+      await syncService.sync(config);
+
+      expect(fs.existsSync(bakPath)).toBe(true);
+      expect(fs.readFileSync(bakPath, 'utf-8')).toBe(
+        '{"greeting":"Guten Tag"}\n'
+      );
+    });
+
     it('leaves fresh .bak files alone', async () => {
       writeYamlConfig(tmpDir, BASIC_CONFIG_YAML);
       writeSourceFile(tmpDir, 'locales/en.json', '{}\n');
diff --git a/tests/unit/sync/sync-bak-cleanup.test.ts b/tests/unit/sync/sync-bak-cleanup.test.ts
index 294e508c..0e67b8e6 100644
--- a/tests/unit/sync/sync-bak-cleanup.test.ts
+++ b/tests/unit/sync/sync-bak-cleanup.test.ts
@@ -4,8 +4,10 @@ import * as path from 'path';
 import {
   sweepStaleBackups,
   bucketSweepRoots,
+  BACKUP_SUFFIX,
   DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS,
 } from '../../../src/sync/sync-bak-cleanup';
+import { Logger } from '../../../src/utils/logger';
 
 // ──────────────────────────────────────────────────────────────────────────────
 // bucketSweepRoots()
@@ -111,9 +113,11 @@ describe('sweepStaleBackups() with bucket config', () => {
     fs.mkdirSync(localesDir, { recursive: true });
     fs.mkdirSync(outsideDir, { recursive: true });
 
-    // Place a stale .deepl.bak in locales (should be swept)
+    // Place a stale .deepl.bak in locales (should be swept). Its target holds
+    // the same bytes, which is what makes the backup redundant and sweepable.
     const staleBak = path.join(localesDir, 'de.json.deepl.bak');
     fs.writeFileSync(staleBak, 'stale', 'utf-8');
+    fs.writeFileSync(path.join(localesDir, 'de.json'), 'stale', 'utf-8');
     const tenMinAgo = new Date(Date.now() - 10 * 60_000);
     fs.utimesSync(staleBak, tenMinAgo, tenMinAgo);
 
@@ -141,6 +145,7 @@ describe('sweepStaleBackups() with bucket config', () => {
 
     const staleBak = path.join(localesDir, 'fr.json.deepl.bak');
     fs.writeFileSync(staleBak, 'stale', 'utf-8');
+    fs.writeFileSync(path.join(localesDir, 'fr.json'), 'stale', 'utf-8');
     const tenMinAgo = new Date(Date.now() - 10 * 60_000);
     fs.utimesSync(staleBak, tenMinAgo, tenMinAgo);
 
@@ -198,7 +203,9 @@ describe('sweepStaleBackups() with bucket config', () => {
     });
 
     expect(fs.existsSync(sibling)).toBe(false);
-    expect(fs.existsSync(bakFile)).toBe(false);
+    // With no target to compare against, the backup is the only copy of its
+    // content, so it is kept rather than swept.
+    expect(fs.existsSync(bakFile)).toBe(true);
   });
 
   // The sweep used to overwrite any zero-length file from its `.deepl.bak`
@@ -207,7 +214,7 @@ describe('sweepStaleBackups() with bucket config', () => {
   // temp file into place and so can never leave a zero-length target, which
   // left the restore branch with no legitimate trigger and made it a way for a
   // hostile checkout to write chosen bytes into an empty tracked file.
-  it('leaves a zero-length sibling alone while removing the stale .deepl.bak', async () => {
+  it('leaves a zero-length sibling alone rather than restoring it from the .deepl.bak', async () => {
     const localesDir = path.join(tmpDir, 'locales');
     fs.mkdirSync(localesDir, { recursive: true });
 
@@ -223,7 +230,7 @@ describe('sweepStaleBackups() with bucket config', () => {
     });
 
     expect(fs.readFileSync(sibling, 'utf-8')).toBe('');
-    expect(fs.existsSync(bakFile)).toBe(false);
+    expect(fs.existsSync(bakFile)).toBe(true);
   });
 
   it('does not write attacker bytes into an unrelated empty source file', async () => {
@@ -267,7 +274,7 @@ describe('sweepStaleBackups() with bucket config', () => {
     expect(readdirCalls).toHaveLength(0);
   });
 
-  it('leaves a non-empty sibling untouched while removing the stale .deepl.bak', async () => {
+  it('leaves a non-empty sibling untouched when it differs from the stale .deepl.bak', async () => {
     const localesDir = path.join(tmpDir, 'locales');
     fs.mkdirSync(localesDir, { recursive: true });
 
@@ -283,7 +290,7 @@ describe('sweepStaleBackups() with bucket config', () => {
     });
 
     expect(fs.readFileSync(sibling, 'utf-8')).toBe('{"current":"content"}');
-    expect(fs.existsSync(bakFile)).toBe(false);
+    expect(fs.existsSync(bakFile)).toBe(true);
   });
 
   it('readdir call count is O(bucket dirs), not O(project)', async () => {
@@ -328,6 +335,7 @@ describe('sweepStaleBackups() without bucket config (fallback)', () => {
 
     const staleBak = path.join(nested, 'x.json.deepl.bak');
     fs.writeFileSync(staleBak, 'stale', 'utf-8');
+    fs.writeFileSync(path.join(nested, 'x.json'), 'stale', 'utf-8');
     const tenMinAgo = new Date(Date.now() - 10 * 60_000);
     fs.utimesSync(staleBak, tenMinAgo, tenMinAgo);
 
@@ -347,6 +355,113 @@ describe('sweepStaleBackups() without bucket config (fallback)', () => {
   });
 });
 
+// ──────────────────────────────────────────────────────────────────────────────
+// sweepStaleBackups() — retention of content the target no longer holds
+// ──────────────────────────────────────────────────────────────────────────────
+
+describe('sweepStaleBackups() retention', () => {
+  let tmpDir: string;
+  let localesDir: string;
+  const buckets = { json: { include: ['locales/**/*.json'] } };
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-bak-keep-'));
+    localesDir = path.join(tmpDir, 'locales');
+    fs.mkdirSync(localesDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeStaleBak(name: string, content: string): string {
+    const bakPath = path.join(localesDir, `${name}${BACKUP_SUFFIX}`);
+    fs.writeFileSync(bakPath, content, 'utf-8');
+    const tenMinAgo = new Date(Date.now() - 10 * 60_000);
+    fs.utimesSync(bakPath, tenMinAgo, tenMinAgo);
+    return bakPath;
+  }
+
+  it('keeps a stale backup whose target holds different content', async () => {
+    const bakPath = writeStaleBak('de.json', '{"greeting":"Guten Tag"}');
+    fs.writeFileSync(
+      path.join(localesDir, 'de.json'),
+      '{"greeting":"machine output"}',
+      'utf-8'
+    );
+
+    await sweepStaleBackups(tmpDir, 5 * 60_000, buckets);
+
+    expect(fs.existsSync(bakPath)).toBe(true);
+    expect(fs.readFileSync(bakPath, 'utf-8')).toBe('{"greeting":"Guten Tag"}');
+  });
+
+  it('keeps a stale backup whose target is the same size but different bytes', async () => {
+    const bakPath = writeStaleBak('fr.json', '{"a":"Bonjour!"}');
+    fs.writeFileSync(
+      path.join(localesDir, 'fr.json'),
+      '{"a":"Salut!!!"}'.padEnd('{"a":"Bonjour!"}'.length, ' '),
+      'utf-8'
+    );
+
+    await sweepStaleBackups(tmpDir, 5 * 60_000, buckets);
+
+    expect(fs.existsSync(bakPath)).toBe(true);
+  });
+
+  it('keeps a stale backup whose target no longer exists', async () => {
+    const bakPath = writeStaleBak('it.json', '{"greeting":"Buongiorno"}');
+
+    await sweepStaleBackups(tmpDir, 5 * 60_000, buckets);
+
+    expect(fs.existsSync(bakPath)).toBe(true);
+  });
+
+  it('names each kept backup and says what to do about it', async () => {
+    const warn = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+    writeStaleBak('de.json', '{"greeting":"Guten Tag"}');
+    fs.writeFileSync(path.join(localesDir, 'de.json'), 'other', 'utf-8');
+
+    await sweepStaleBackups(tmpDir, 5 * 60_000, buckets);
+
+    const messages = warn.mock.calls.map((c) => String(c[0]));
+    const kept = messages.find((m) => m.includes(`de.json${BACKUP_SUFFIX}`));
+    expect(kept).toBeDefined();
+    expect(kept).toMatch(/did not finish/);
+    expect(kept).toMatch(/only copy/);
+    expect(kept).toMatch(/before removing it/);
+  });
+
+  // Over-rejection guards: a backup the target already holds is litter, and
+  // sweeping it is the reason this function exists.
+  it('removes a stale backup whose target holds identical content', async () => {
+    const bakPath = writeStaleBak('es.json', '{"greeting":"Hola"}');
+    fs.writeFileSync(
+      path.join(localesDir, 'es.json'),
+      '{"greeting":"Hola"}',
+      'utf-8'
+    );
+
+    await sweepStaleBackups(tmpDir, 5 * 60_000, buckets);
+
+    expect(fs.existsSync(bakPath)).toBe(false);
+    expect(fs.readFileSync(path.join(localesDir, 'es.json'), 'utf-8')).toBe(
+      '{"greeting":"Hola"}'
+    );
+  });
+
+  it('says nothing when every stale backup was redundant', async () => {
+    const warn = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+    writeStaleBak('es.json', 'same');
+    fs.writeFileSync(path.join(localesDir, 'es.json'), 'same', 'utf-8');
+
+    await sweepStaleBackups(tmpDir, 5 * 60_000, buckets);
+
+    const messages = warn.mock.calls.map((c) => String(c[0]));
+    expect(messages.some((m) => m.includes(BACKUP_SUFFIX))).toBe(false);
+  });
+});
+
 // ──────────────────────────────────────────────────────────────────────────────
 // resolveBakSweepAgeMs / DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS
 // ──────────────────────────────────────────────────────────────────────────────

From 7d092390d64e3d5d9029d96f0e3d70bb39a001b2 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 18:05:50 +0200
Subject: [PATCH 166/256] fix(http): classify a response cut off mid-body as a
 transport failure

axios attaches the 200 response to the error it raises when a response
stream aborts, and classifyError let the presence of a response decide: it
took the HTTP-status branch and returned
`ValidationError('API error: stream has been aborted')`, so a truncated
response exited 6 and told the operator to check input that was never the
problem.

A rejection carrying a 2xx response can only have failed while the body was
being read, so the status decides it rather than the axios code, which varies
with how the peer failed. 3xx, 4xx and 5xx responses keep the classification
they had, and the client-side deadline path still restates its own aborts
before classification.

The replay policy is unchanged: a 200 means the server accepted, and may have
billed, the request, so the billable POST is still sent once and the
idempotent GET is still replayed. The request counts are asserted alongside
the exit code.

Refs cli-8kr2.53
---
 CHANGELOG.md                                 |   2 +
 docs/API.md                                  |   4 +-
 src/api/http-client.ts                       |  16 +++
 tests/e2e/cli-truncated-response.e2e.test.ts | 111 +++++++++++++++++++
 tests/e2e/truncating-server.cjs              |  52 +++++++++
 tests/unit/http-retry-policy.test.ts         |  96 ++++++++++++++++
 6 files changed, 280 insertions(+), 1 deletion(-)
 create mode 100644 tests/e2e/cli-truncated-response.e2e.test.ts
 create mode 100644 tests/e2e/truncating-server.cjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b819897..eb741f56 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -135,6 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **http**: **a response the endpoint cuts off mid-body is reported as a network failure (exit 5), not as invalid input (exit 6).** axios attaches the 200 response to the error it raises for an aborted response stream, and `classifyError` let the mere presence of a response decide: it took the HTTP-status branch and returned `ValidationError('API error: stream has been aborted')`, telling the operator to check input that was never the problem. Reproduced against a stub that declares a `Content-Length`, writes 12 bytes of the body and destroys the socket: `deepl translate "Hello" --to es --max-retries 3` printed `Error: API error: stream has been aborted` at **exit 6**, and `deepl usage` the same. Both now exit **5** with `Network error: the API answered HTTP 200 but its response body did not arrive intact: stream has been aborted`. The test is the status, not the axios code or message: a rejection carrying a 2xx response can only have failed while the body was read, whereas the code varies with how the peer failed (`ERR_BAD_RESPONSE` for an aborted stream, a socket or zlib code otherwise) — both the `Content-Length` and the chunked truncation shapes were measured to confirm it. 3xx, 4xx and 5xx responses keep the classification they had. **The replay policy is deliberately unchanged**, contrary to the finding's framing: the request counts were measured before and after and are identical, 1 for the POST and `--max-retries + 1` for the GET. A 200 means the server accepted — and may have billed — the request, so replaying the billable POST is exactly what must not happen here; the idempotent GET was already being replayed, so the "never retried" half of the report did not hold. The client-side deadline path is untouched: it still restates its own aborts as `ETIMEDOUT` before classification, so both routes end at `NetworkError`.
+
 - **sync**: **the startup stale-backup sweep no longer deletes a crashed run's backup, so recovery is no longer limited to the five minutes after the crash.** `deepl sync` refuses to overwrite an existing `<target>.deepl.bak` (`COPYFILE_EXCL`, warn, leave it alone) precisely because after a `kill -9` that backup holds the only surviving copy of the user's translations — but the sweep runs first, at startup, and unlinked every `.deepl.bak` older than `sync.bak_sweep_max_age_seconds` (default 300) without looking at its content, which left that guard nothing to collide with. Reproduced end to end against a mock endpoint: with `locales/de.json` holding machine output, `locales/de.json.deepl.bak` holding `"HUMAN TRANSLATION"`, no lockfile, and the backup's mtime backdated ten minutes, `deepl sync --yes` reported `✓ de: 1/1 keys`, `Sync complete: 1 new`, **exit 0**, and the human translation existed nowhere in the project afterwards — the same harm the `COPYFILE_EXCL` guard was added to prevent, reached around it. The identical run with the backup dated ten **seconds** earlier kept it and warned, which is what made age the whole of the bug. A stale backup is now deleted only when the file beside it already holds the same bytes: a run that reaches its end unlinks its own backups, so one still on disk is from a run that did not, and there it is the last copy of whatever that run had already overwritten. Size is compared first and the contents only when the sizes agree, so the common case (no backup at all) costs one `readdir` as before. A backup whose target has diverged, or whose target is gone, is kept however old it is and reported once per sweep, naming the file: `Keeping 1 leftover backup file whose content is not in the file beside it: locales/de.json.deepl.bak. It is from a run that did not finish, so it may hold the only copy of translations that run overwrote.` Retention is bounded at one file per target, since the backup's name is derived from the target's, so this cannot accumulate. `bak_sweep_max_age_seconds` keeps its meaning for redundant backups and no longer sets a deadline for recovering a crashed run. The fix is in `sweepStaleBackups`, which every caller shares — `deepl sync`, `sync push`, `sync pull`, `sync export` and `sync --watch`'s startup sweep. Three tests asserted the old policy by giving a stale backup no sibling or a differing one; those fixtures now say which case they mean.
 
 - **sync**: **`sync resolve`'s merge is no longer erased by a concurrent sync, and no longer risks truncating the lockfile.** The process lock was honoured by exactly two call sites — `deepl sync` and `deepl sync pull` — and `sync resolve` took none, while writing the lockfile with a plain `fs.writeFile` rather than the rename every other lockfile writer uses. Measured through the real CLI with a slow sync holding the lock: a second `deepl sync` was correctly refused at exit 7, while `deepl sync resolve` **proceeded**, reported `Resolved 1 conflict` and wrote the merged lockfile at exit 0 — and when the sync finished (also exit 0) the merged entry was gone, because the sync had read the pre-merge lockfile at startup and wrote its whole in-memory copy at the end. Both steps reported success, so the merge-conflict recovery path lost data silently. `sync resolve` now takes the lock — `--dry-run` included, matching `sync pull` — and exits 7 with the same "Another `deepl sync` process is running" message while one is held, leaving the conflict markers in place for after the sync. Its write goes through the atomic rename, so a crash part-way through leaves the previous lockfile instead of a truncated one; a truncated lockfile reads as corrupt and is replaced with an empty one, which costs a full re-translation of the project. And because a hand edit, a `git merge` or another tool takes no lock at all, a run whose lockfile changed on disk between its read and its write now says so and still records what it did — warning rather than refusing, since by that point the target files are written and the translations billed, and declining to record them would bill every one of them again on the next run.
diff --git a/docs/API.md b/docs/API.md
index 37ffa418..1661c98b 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3325,7 +3325,7 @@ Retryable codes are `3` (rate limit) and `5` (network); everything else should b
 | 2    | AuthError      | Authentication failed or API key missing                       | No        |
 | 3    | RateLimitError | Rate limit exceeded (HTTP 429)                                 | Yes       |
 | 4    | QuotaError     | Monthly character quota exhausted (HTTP 456)                   | No        |
-| 5    | NetworkError   | Connection timeout, refused, reset, or 503 Service Unavailable | Yes       |
+| 5    | NetworkError   | Connection timeout, refused, reset, truncated response body, or 503 Service Unavailable | Yes       |
 | 6    | InvalidInput   | Missing or malformed arguments, unsupported format             | No        |
 | 7    | ConfigError    | Configuration file or value invalid                            | No        |
 | 8    | CheckFailed    | A check-style command found actionable issues                  | No        |
@@ -3374,6 +3374,8 @@ Connection-layer failure or transient server outage. Covers TCP errors (`ECONNRE
 
 A response that came back without the placeholder tokens the CLI substituted for your variables counts as malformed here too: `translate` names the variables it lost (`{username}`, `%s`) and writes nothing rather than leaving its own internal tokens in your text. A directory run fails only the affected files and reports each one in the summary, so its exit code follows the usual batch mapping (`1` when nothing translated, `12` when some did).
 
+A response the endpoint cuts off mid-body is exit 5 as well, even though the status line said 200. The HTTP status is what decides it: a rejection carrying a 2xx response means the exchange was accepted and then failed while the body was read — truncated, or undecodable — so the message names the status and what went wrong (`Network error: the API answered HTTP 200 but its response body did not arrive intact: stream has been aborted`) rather than reporting an API error your input could fix. **The replay policy is unchanged by this.** A 200 says the server accepted, and may have billed, the request, so a truncated response to a `POST` (`translate`, `write`, a `sync` batch) is still sent exactly once; an idempotent `GET` is still replayed up to `--max-retries` times.
+
 A document upload response whose `document_id` is not a document identifier is rejected here as well. That value is interpolated into the path of every follow-up request (`POST /v2/document/{id}`, `POST /v2/document/{id}/result`), so an ID containing `..` or `/` would send this client's own requests to a different route on the endpoint. Anything outside `[A-Za-z0-9_-]+` is refused before the next request is sent, the ID is quoted back in the message, and no output file is written.
 
 Remediation: check connectivity and `HTTPS_PROXY` / `HTTP_PROXY` env vars, then retry.
diff --git a/src/api/http-client.ts b/src/api/http-client.ts
index 0b1d1e58..55353a76 100644
--- a/src/api/http-client.ts
+++ b/src/api/http-client.ts
@@ -646,6 +646,22 @@ export class HttpClient {
           if (!error.response) {
             return this.transportError(error);
           }
+          // A response whose status the server chose to signal success, on an
+          // error, means the exchange was accepted and then failed while its
+          // body was read — cut off mid-body, or a body the transport could
+          // not decode. The status is what decides it: the axios code varies
+          // with how the peer failed (ERR_BAD_RESPONSE for an aborted stream,
+          // a socket or zlib code otherwise), while the mere presence of a
+          // response used to send all of these to `ValidationError`, telling
+          // the operator to check input that was never the problem and
+          // charging them exit 6 for a transport failure. Deadline aborts are
+          // restated before classification (see `makeRequest`), so what
+          // arrives here is the peer's doing.
+          if (status !== undefined && status >= 200 && status < 300) {
+            return new NetworkError(
+              `Network error: the API answered HTTP ${status} but its response body did not arrive intact: ${message}${traceIdSuffix}`
+            );
+          }
           return new ValidationError(`API error: ${message}${traceIdSuffix}`);
       }
     }
diff --git a/tests/e2e/cli-truncated-response.e2e.test.ts b/tests/e2e/cli-truncated-response.e2e.test.ts
new file mode 100644
index 00000000..35661a39
--- /dev/null
+++ b/tests/e2e/cli-truncated-response.e2e.test.ts
@@ -0,0 +1,111 @@
+/**
+ * E2E tests for a response the server cuts off mid-body.
+ *
+ * The 200 status stays attached to the axios error, which used to make the
+ * failure read as an API error the caller's input could fix (exit 6). The
+ * request counts are asserted alongside the exit code because the replay
+ * policy must not change: a 200 says the server accepted — and may have billed
+ * — the request, so the billable POST is still sent exactly once.
+ */
+
+import { spawn, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir, makeNodeRunCLI } from '../helpers';
+
+describe('CLI truncated response E2E', () => {
+  const testConfig = createTestConfigDir('e2e-truncated-response');
+  const testFiles = createTestDir('e2e-truncated-response-files');
+  let runner: ReturnType<typeof makeNodeRunCLI>;
+  let server: ChildProcess;
+  let baseUrl: string;
+  let countFile: string;
+
+  function startServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const serverScript = path.join(__dirname, 'truncating-server.cjs');
+      const child = spawn('node', [serverScript, countFile], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+
+      server = child;
+      let output = '';
+
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = output.match(/PORT=(\d+)/);
+        if (match) {
+          resolve(parseInt(match[1]!, 10));
+        }
+      });
+
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Truncating server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  function requestCount(): number {
+    return parseInt(fs.readFileSync(countFile, 'utf-8'), 10);
+  }
+
+  beforeAll(async () => {
+    runner = makeNodeRunCLI(testConfig.path, { apiKey: 'test-api-key' });
+    countFile = path.join(testFiles.path, 'requests.txt');
+    const port = await startServer();
+    baseUrl = `http://127.0.0.1:${port}`;
+    // `--api-url` is a `translate` option, so the GET command needs the
+    // endpoint from config.
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'test-api-key' },
+        api: { baseUrl, usePro: false },
+        cache: { enabled: false },
+        output: { format: 'text', color: false },
+      })
+    );
+  });
+
+  afterAll(() => {
+    server.kill();
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  it('exits 5 (network error) rather than 6 when the response body is cut short', () => {
+    const result = runner.runCLIExpectError(
+      `--max-retries 3 translate "Hello" --to es --api-url ${baseUrl} --no-cache`,
+      { timeout: 30000 }
+    );
+
+    expect(result.status).toBe(5);
+    expect(result.output).not.toMatch(/API error/);
+    expect(result.output).toMatch(/body did not arrive intact/);
+  });
+
+  it('still sends the billable POST exactly once', () => {
+    const before = requestCount();
+
+    runner.runCLIExpectError(
+      `--max-retries 3 translate "Bonjour" --to es --api-url ${baseUrl} --no-cache`,
+      { timeout: 30000 }
+    );
+
+    expect(requestCount() - before).toBe(1);
+  });
+
+  it('still replays an idempotent GET up to --max-retries times', () => {
+    const before = requestCount();
+
+    const result = runner.runCLIExpectError('--max-retries 2 usage', {
+      timeout: 30000,
+    });
+
+    expect(result.status).toBe(5);
+    expect(requestCount() - before).toBe(3);
+  });
+});
diff --git a/tests/e2e/truncating-server.cjs b/tests/e2e/truncating-server.cjs
new file mode 100644
index 00000000..f1189aed
--- /dev/null
+++ b/tests/e2e/truncating-server.cjs
@@ -0,0 +1,52 @@
+/**
+ * A server that answers 200, declares a Content-Length, writes part of the
+ * body and then destroys the socket — a server-caused mid-body abort, which
+ * axios surfaces as ERR_BAD_RESPONSE / 'stream has been aborted' with the 200
+ * response still attached to the error.
+ *
+ * Prints `PORT=<port>` on stdout once listening, and rewrites the file given as
+ * argv[2] with the number of requests received so far. Runs in its own process
+ * because the test driver blocks its own event loop on execSync and would
+ * otherwise never accept the connection.
+ *
+ * Usage: node tests/e2e/truncating-server.cjs /path/to/count-file
+ */
+
+const http = require('http');
+const fs = require('fs');
+
+const countFile = process.argv[2];
+let requests = 0;
+
+const BODY = JSON.stringify({
+  translations: [
+    { text: 'Hola', detected_source_language: 'EN', billed_characters: 5 },
+  ],
+  character_count: 0,
+  character_limit: 1000000,
+});
+
+const server = http.createServer((req, res) => {
+  req.on('data', () => {});
+  req.on('end', () => {
+    requests++;
+    if (countFile) {
+      fs.writeFileSync(countFile, String(requests));
+    }
+    res.setHeader('Content-Type', 'application/json');
+    res.setHeader('Content-Length', String(Buffer.byteLength(BODY)));
+    res.writeHead(200);
+    res.write(BODY.slice(0, 12));
+    setTimeout(() => res.socket.destroy(), 20);
+  });
+});
+
+// Ignore mid-flight socket errors from clients that give up.
+server.on('clientError', () => {});
+
+server.listen(0, '127.0.0.1', () => {
+  if (countFile) {
+    fs.writeFileSync(countFile, '0');
+  }
+  process.stdout.write(`PORT=${server.address().port}\n`);
+});
diff --git a/tests/unit/http-retry-policy.test.ts b/tests/unit/http-retry-policy.test.ts
index c708123f..63508caa 100644
--- a/tests/unit/http-retry-policy.test.ts
+++ b/tests/unit/http-retry-policy.test.ts
@@ -7,6 +7,11 @@
  */
 
 import nock from 'nock';
+import {
+  AxiosError,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from 'axios';
 import { HttpClient } from '../../src/api/http-client';
 import {
   AuthError,
@@ -349,6 +354,97 @@ describe('HttpClient retry policy', () => {
     });
   });
 
+  // A response object is attached to the error, but its status is 200: the
+  // exchange was accepted and then failed while the body was being read.
+  // Measured shapes, both from a real loopback server — a declared
+  // Content-Length cut short and a chunked body with no terminating chunk —
+  // arrive as ERR_BAD_RESPONSE / 'stream has been aborted' / status 200.
+  describe('a response that fails while its body is read', () => {
+    function abortedStream(): AxiosError {
+      const config = { url: '/v2/translate' } as InternalAxiosRequestConfig;
+      const response = {
+        status: 200,
+        statusText: 'OK',
+        headers: {},
+        config,
+        data: undefined,
+      } as AxiosResponse;
+      return new AxiosError(
+        'stream has been aborted',
+        AxiosError.ERR_BAD_RESPONSE,
+        config,
+        {},
+        response
+      );
+    }
+
+    it('classifies a mid-body abort as a network error, not a validation error', () => {
+      const classified = makeClient().classify(abortedStream());
+
+      expect(classified).toBeInstanceOf(NetworkError);
+      expect(classified).not.toBeInstanceOf(ValidationError);
+      expect(exitCodeForError(classified)).toBe(ExitCode.NetworkError);
+    });
+
+    it('says the body was cut short rather than reporting an API error', () => {
+      const classified = makeClient().classify(abortedStream());
+
+      expect(classified.message).not.toMatch(/^API error/);
+      expect(classified.message).toMatch(/body/i);
+      expect(classified.message).toContain('stream has been aborted');
+    });
+
+    // Over-rejection guards: a status the server chose still speaks for
+    // itself, and the transport verdict must not swallow it.
+    it('still reports a 400 with a server message as a validation error', () => {
+      const config = { url: '/v2/translate' } as InternalAxiosRequestConfig;
+      const response = {
+        status: 400,
+        statusText: 'Bad Request',
+        headers: {},
+        config,
+        data: { message: 'Value for target_lang not supported' },
+      } as AxiosResponse;
+      const error = new AxiosError(
+        'Request failed with status code 400',
+        AxiosError.ERR_BAD_REQUEST,
+        config,
+        {},
+        response
+      );
+
+      const classified = makeClient().classify(error);
+
+      expect(classified).toBeInstanceOf(ValidationError);
+      expect(classified.message).toContain(
+        'API error: Value for target_lang not supported'
+      );
+    });
+
+    it('still reports a 500 as a network error naming the status', () => {
+      const config = { url: '/v2/translate' } as InternalAxiosRequestConfig;
+      const response = {
+        status: 500,
+        statusText: 'Internal Server Error',
+        headers: {},
+        config,
+        data: { message: 'boom' },
+      } as AxiosResponse;
+      const error = new AxiosError(
+        'Request failed with status code 500',
+        AxiosError.ERR_BAD_RESPONSE,
+        config,
+        {},
+        response
+      );
+
+      const classified = makeClient().classify(error);
+
+      expect(classified).toBeInstanceOf(NetworkError);
+      expect(classified.message).toContain('Server error (500)');
+    });
+  });
+
   describe('error messages', () => {
     it('does not double the "Network error" prefix', async () => {
       nock(BASE_URL).post('/v2/translate').replyWithError('Network error');

From b8dbb22315342b6c0c0a8f4da7921cfcafc98d8b Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 18:59:58 +0200
Subject: [PATCH 167/256] fix(formats): end a PO entry where gettext ends it,
 not at a blank line
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The blank-line separator between PO entries is a convention `msgfmt -c` does
not require, but both halves of the parser treated it as the only terminator.
A catalog written without it collapsed into a single entry: the reader
reported one key — the last — so every other message was absent from the key
set, and the writer put that one translation into every msgstr it walked
past, the header's included, deleting the charset and Plural-Forms
declarations. Four further shapes were measured: an entry with `#:` comments
was dropped from the output, an obsolete `#~` run deleted the header outright
so msgfmt rejected the result, a plural entry lost its plural rule, and
extractTranslations reported only the last entry as translated, so every
reviewed msgstr looked untranslated and was re-billed each run.

An entry now ends at the first line that cannot continue its translation: a
comment, a msgctxt, or the next msgid. Both the reader and the writer need
it — they scan entry blocks independently, and each is insufficient alone.
Layout is preserved, so a catalog that arrived without separators keeps that
shape.

Refs cli-8kr2.61
---
 CHANGELOG.md                                  |   2 +
 docs/SYNC.md                                  |   2 +
 src/formats/po.ts                             |  38 ++++
 .../sync-po-unseparated.integration.test.ts   | 143 +++++++++++++
 tests/unit/formats/po.test.ts                 | 191 ++++++++++++++++++
 tests/unit/formats/roundtrip.test.ts          |  45 +++++
 6 files changed, 421 insertions(+)
 create mode 100644 tests/integration/sync-po-unseparated.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index eb741f56..91ac7758 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -135,6 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a PO catalog written without blank lines between its entries is no longer collapsed into one entry.** The blank-line separator is a gettext convention, not a requirement — `msgfmt -c` exits 0 on every fixture below — but both halves of the PO parser treated it as the only thing that ends an entry, and the damage was total. Measured on a legal five-message catalog with no separators at all: `extract` reported **one** key (`Third`, the last one), so `Hello` and `Bye` were absent from the source key set entirely, and `reconstruct` wrote that single translation into **every** `msgstr` it walked past, the header's included — `msgstr ""` plus `"Content-Type: text/plain; charset=UTF-8\n"` and `"Plural-Forms: nplurals=2; plural=(n != 1);\n"` became `msgstr "[T]Third"`, and `msgfmt -c` on the output then warned `Charset missing in header. Message conversion to user's charset will not work.` Four more shapes were measured, none of them named in the original report: a catalog whose entries carry `#:` comments silently **lost** the whole first entry from the output; an obsolete `#~` run between two messages **deleted the header outright**, at which point `msgfmt -c` failed the output with `PO file header missing or invalid` (exit 1); a plural entry lost its `Plural-Forms` rule and failed `msgfmt -c` with `header entry lacks a "plural=EXPRESSION" attribute`; and `extractTranslations` — the bilingual target read used by `sync`, `push`, `pull`, `validate` and `audit` — reported only the last entry as translated, so every other reviewed `msgstr` looked untranslated and was re-translated and re-billed on every run. An entry now ends where gettext ends it: at the first line that is not a continuation of its translation, i.e. a comment, a `msgctxt`, or the next `msgid`. **Both the reader and the writer needed it** — they scan entry blocks independently, and each was proven to be insufficient alone with its own control: with only the writer fixed the header survives but the key set is still one entry; with only the reader fixed the keys are right but the header is still destroyed. All six catalogs now pass `msgfmt -c` on both input and output, keep their charset and plural rule, and are a fixed point across three successive syncs. Layout is untouched: a catalog that arrived without separators keeps that shape. The blank-line-separated form, multi-line `msgid`/`msgstr` continuations and plural entries are all unchanged.
+
 - **http**: **a response the endpoint cuts off mid-body is reported as a network failure (exit 5), not as invalid input (exit 6).** axios attaches the 200 response to the error it raises for an aborted response stream, and `classifyError` let the mere presence of a response decide: it took the HTTP-status branch and returned `ValidationError('API error: stream has been aborted')`, telling the operator to check input that was never the problem. Reproduced against a stub that declares a `Content-Length`, writes 12 bytes of the body and destroys the socket: `deepl translate "Hello" --to es --max-retries 3` printed `Error: API error: stream has been aborted` at **exit 6**, and `deepl usage` the same. Both now exit **5** with `Network error: the API answered HTTP 200 but its response body did not arrive intact: stream has been aborted`. The test is the status, not the axios code or message: a rejection carrying a 2xx response can only have failed while the body was read, whereas the code varies with how the peer failed (`ERR_BAD_RESPONSE` for an aborted stream, a socket or zlib code otherwise) — both the `Content-Length` and the chunked truncation shapes were measured to confirm it. 3xx, 4xx and 5xx responses keep the classification they had. **The replay policy is deliberately unchanged**, contrary to the finding's framing: the request counts were measured before and after and are identical, 1 for the POST and `--max-retries + 1` for the GET. A 200 means the server accepted — and may have billed — the request, so replaying the billable POST is exactly what must not happen here; the idempotent GET was already being replayed, so the "never retried" half of the report did not hold. The client-side deadline path is untouched: it still restates its own aborts as `ETIMEDOUT` before classification, so both routes end at `NetworkError`.
 
 - **sync**: **the startup stale-backup sweep no longer deletes a crashed run's backup, so recovery is no longer limited to the five minutes after the crash.** `deepl sync` refuses to overwrite an existing `<target>.deepl.bak` (`COPYFILE_EXCL`, warn, leave it alone) precisely because after a `kill -9` that backup holds the only surviving copy of the user's translations — but the sweep runs first, at startup, and unlinked every `.deepl.bak` older than `sync.bak_sweep_max_age_seconds` (default 300) without looking at its content, which left that guard nothing to collide with. Reproduced end to end against a mock endpoint: with `locales/de.json` holding machine output, `locales/de.json.deepl.bak` holding `"HUMAN TRANSLATION"`, no lockfile, and the backup's mtime backdated ten minutes, `deepl sync --yes` reported `✓ de: 1/1 keys`, `Sync complete: 1 new`, **exit 0**, and the human translation existed nowhere in the project afterwards — the same harm the `COPYFILE_EXCL` guard was added to prevent, reached around it. The identical run with the backup dated ten **seconds** earlier kept it and warned, which is what made age the whole of the bug. A stale backup is now deleted only when the file beside it already holds the same bytes: a run that reaches its end unlinks its own backups, so one still on disk is from a run that did not, and there it is the last copy of whatever that run had already overwritten. Size is compared first and the contents only when the sizes agree, so the common case (no backup at all) costs one `readdir` as before. A backup whose target has diverged, or whose target is gone, is kept however old it is and reported once per sweep, naming the file: `Keeping 1 leftover backup file whose content is not in the file beside it: locales/de.json.deepl.bak. It is from a run that did not finish, so it may hold the only copy of translations that run overwrote.` Retention is bounded at one file per target, since the backup's name is derived from the target's, so this cannot accumulate. `bak_sweep_max_age_seconds` keeps its meaning for redundant backups and no longer sets a deadline for recovering a crashed run. The fix is in `sweepStaleBackups`, which every caller shares — `deepl sync`, `sync push`, `sync pull`, `sync export` and `sync --watch`'s startup sweep. Three tests asserted the old policy by giving a stale backup no sibling or a differing one; those fixtures now say which case they mean.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 613d156e..2a61ffdb 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -160,6 +160,8 @@ Nine of the eleven formats are monolingual -- a target file holds translations a
 
 **An empty translation side means untranslated, not empty.** A `msgstr ""`, a `<trans-unit>` with no `<target>`, and an empty `<target></target>` all read as "this key has no translation yet": `sync` translates the key rather than pinning the empty string, and `push` skips it (see below). This differs from the monolingual formats, where an empty value is a deliberate translation and is preserved.
 
+**PO entries need no blank line between them.** The blank-line separator is a convention `msgfmt -c` does not require, and a catalog written without it — after the header or between messages — is read and written entry by entry all the same. An entry ends at the first line that is not a continuation of its translation: a comment, a `msgctxt`, or the next `msgid`. Layout is preserved either way, so a catalog that arrived without the separators keeps that shape on the way out.
+
 ## Configuration
 
 ### `.deepl-sync.yaml`
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 6479ef2d..0901e4ce 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -143,6 +143,34 @@ function makeKey(entry: PoEntry): string {
   return entry.msgid;
 }
 
+/**
+ * Whether `line` can only be the start of the next entry.
+ *
+ * gettext ends an entry at the first line that is not a continuation of its
+ * translation; the blank line convention is a convention, and `msgfmt -c`
+ * accepts a catalog with none. Treating a blank line as the only terminator
+ * collapsed such a catalog into a single entry, which cost the reader every
+ * key but the last and made the writer put one translation into every `msgstr`
+ * it walked past — the header's included, deleting the charset and
+ * `Plural-Forms` lines with it.
+ *
+ * Only a msgstr-ish `target` can be interrupted this way. Before that the
+ * entry is still assembling its `msgctxt`/`msgid`, where a second `msgid` line
+ * is malformed input rather than a new entry, and is left to the existing
+ * last-one-wins handling.
+ */
+function startsNextEntry(
+  line: string,
+  target: ParseTarget | undefined
+): boolean {
+  if (target !== 'msgstr' && !target?.startsWith('msgstr[')) {
+    return false;
+  }
+  return (
+    line.startsWith('#') || /^msgctxt\s/.test(line) || /^msgid\s/.test(line)
+  );
+}
+
 function parseEntries(content: string): PoEntry[] {
   const lines = content.split(/\r?\n/);
   const entries: PoEntry[] = [];
@@ -166,6 +194,13 @@ function parseEntries(content: string): PoEntry[] {
       continue;
     }
 
+    if (hasContent && startsNextEntry(line, target)) {
+      entries.push(current);
+      current = createEmptyEntry();
+      target = undefined;
+      hasContent = false;
+    }
+
     current.rawLines.push(line);
 
     if (line.startsWith('#. ')) {
@@ -449,6 +484,9 @@ export class PoFormatParser implements FormatParser {
         if (el.startsWith('#')) {
           break;
         }
+        if (startsNextEntry(el, target)) {
+          break;
+        }
         entryLines.push(el);
 
         const ctxtM = /^msgctxt\s+(.*)$/.exec(el);
diff --git a/tests/integration/sync-po-unseparated.integration.test.ts b/tests/integration/sync-po-unseparated.integration.test.ts
new file mode 100644
index 00000000..ab1882cc
--- /dev/null
+++ b/tests/integration/sync-po-unseparated.integration.test.ts
@@ -0,0 +1,143 @@
+/**
+ * Integration tests for a PO catalog whose entries are not separated by blank
+ * lines. `msgfmt -c` exits 0 on such a catalog, so it is legal input, and both
+ * hand-written and generated ones occur.
+ *
+ * Both halves of the parser used to treat a blank line as the only entry
+ * terminator, which cost a whole sync: the reader saw one entry — so every key
+ * but the last was missing from the source key set — and the writer put the one
+ * translation it had into every `msgstr` it walked past, the header's included,
+ * deleting the charset and `Plural-Forms` declarations with it.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+import * as querystring from 'querystring';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import type { SyncLockFile } from '../../src/sync/types';
+
+const HEADER = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"',
+].join('\n');
+
+// No blank line anywhere: not after the header, not between the messages.
+const SOURCE = [
+  HEADER,
+  'msgid "Hello"',
+  'msgstr ""',
+  'msgid "Goodbye"',
+  'msgstr ""',
+  '',
+].join('\n');
+
+function textsOf(body: unknown): string[] {
+  const parsed =
+    typeof body === 'string'
+      ? (querystring.parse(body) as Record<string, string | string[]>)
+      : (body as Record<string, string | string[]>);
+  const text = parsed['text'];
+  return Array.isArray(text) ? text : text ? [text] : [];
+}
+
+/** Echoes every text back with an `[es]` marker, however they are batched. */
+function replyWithMarkedTexts(): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .post('/v2/translate')
+    .times(4)
+    .reply(200, (_uri, body) => ({
+      translations: textsOf(body).map((t) => ({
+        text: `[es]${t}`,
+        detected_source_language: 'EN',
+        billed_characters: t.length,
+      })),
+    }));
+}
+
+describe('sync over a PO catalog with no blank-line separators', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-po-nosep-'));
+    harness = createSyncHarness({ parsers: ['po'] });
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es'],
+      buckets: { po: { include: ['locales/en/app.po'] } },
+    });
+    const sourcePath = path.join(tmpDir, 'locales', 'en', 'app.po');
+    fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+    fs.writeFileSync(sourcePath, SOURCE, 'utf-8');
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  function targetPath(): string {
+    return path.join(tmpDir, 'locales', 'es', 'app.po');
+  }
+
+  it('translates every key and keeps the header intact', async () => {
+    replyWithMarkedTexts();
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.success).toBe(true);
+    expect(result.newKeys).toBe(2);
+
+    const written = fs.readFileSync(targetPath(), 'utf-8');
+    expect(written).toContain('"Content-Type: text/plain; charset=UTF-8\\n"');
+    expect(written).toContain(
+      '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"'
+    );
+    expect(written).toContain('msgid "Hello"\nmsgstr "[es]Hello"');
+    expect(written).toContain('msgid "Goodbye"\nmsgstr "[es]Goodbye"');
+    // The header's own msgstr is not a translation slot.
+    expect(written).not.toContain('msgstr "[es]"');
+    expect(written).toMatch(/^msgid ""\nmsgstr ""\n/);
+  });
+
+  it('records both keys in the lockfile', async () => {
+    replyWithMarkedTexts();
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    const lock = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, '.deepl-sync.lock'), 'utf-8')
+    ) as SyncLockFile;
+    const fileEntries = Object.values(lock.entries)[0]!;
+    expect(Object.keys(fileEntries).sort()).toEqual(['Goodbye', 'Hello']);
+    expect(fileEntries['Hello']?.translations['es']?.status).toBe('translated');
+    expect(fileEntries['Goodbye']?.translations['es']?.status).toBe(
+      'translated'
+    );
+  });
+
+  it('reads its own output back and re-bills nothing on the next run', async () => {
+    replyWithMarkedTexts();
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+    const first = fs.readFileSync(targetPath(), 'utf-8');
+
+    const second = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(second.newKeys).toBe(0);
+    expect(second.currentKeys).toBe(2);
+    expect(second.totalCharactersBilled).toBe(0);
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toBe(first);
+  });
+});
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index 9dbf9935..84ae071d 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -420,3 +420,194 @@ describe('PoFormatParser — reconstruct coverage', () => {
     expect(result).toContain('python-format');
   });
 });
+
+// gettext does not require a blank line between entries: msgfmt -c exits 0 on
+// every fixture below. Both the reader and the writer treated a blank line as
+// the only entry terminator, so a catalog without them collapsed into one
+// entry — the key set lost every message but the last, and reconstruct wrote
+// one translation into every msgstr it found, the header's included.
+describe('PoFormatParser — entries with no blank line between them', () => {
+  const parser = new PoFormatParser();
+
+  const HEADER = [
+    'msgid ""',
+    'msgstr ""',
+    '"Project-Id-Version: demo\\n"',
+    '"Content-Type: text/plain; charset=UTF-8\\n"',
+    '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"',
+  ].join('\n');
+
+  function translateAll(content: string): string {
+    const entries = parser.extract(content).map((e) => ({
+      ...e,
+      translation: `[T]${e.value}`,
+    }));
+    return parser.reconstruct(content, entries);
+  }
+
+  it('extracts every entry when nothing separates them', () => {
+    const po = [
+      HEADER,
+      'msgid "Hello"',
+      'msgstr "REVIEWED-1"',
+      'msgid "Bye"',
+      'msgstr "REVIEWED-2"',
+      'msgid "Third"',
+      'msgstr "REVIEWED-3"',
+      '',
+    ].join('\n');
+
+    expect(parser.extract(po).map((e) => e.key)).toEqual([
+      'Hello',
+      'Bye',
+      'Third',
+    ]);
+  });
+
+  it('reads every existing translation out of an unseparated target', () => {
+    const po = [
+      HEADER,
+      'msgid "Hello"',
+      'msgstr "REVIEWED-1"',
+      'msgid "Bye"',
+      'msgstr "REVIEWED-2"',
+      '',
+    ].join('\n');
+
+    expect([...parser.extractTranslations(po)]).toEqual([
+      ['Hello', 'REVIEWED-1'],
+      ['Bye', 'REVIEWED-2'],
+    ]);
+  });
+
+  it('keeps the header and its charset when the first message follows it directly', () => {
+    const po = [HEADER, 'msgid "Hello"', 'msgstr "REVIEWED"', ''].join('\n');
+
+    const out = translateAll(po);
+
+    expect(out).toContain('"Content-Type: text/plain; charset=UTF-8\\n"');
+    expect(out).toContain('"Plural-Forms: nplurals=2; plural=(n != 1);\\n"');
+    expect(out).toContain('msgid ""\nmsgstr ""\n');
+    expect(out).toContain('msgstr "[T]Hello"');
+  });
+
+  it('writes each translation into its own entry rather than the first msgstr it finds', () => {
+    const po = [
+      HEADER,
+      'msgid "Hello"',
+      'msgstr "REVIEWED-1"',
+      'msgid "Bye"',
+      'msgstr "REVIEWED-2"',
+      '',
+    ].join('\n');
+
+    const out = translateAll(po);
+
+    expect(out).toContain('msgid "Hello"\nmsgstr "[T]Hello"');
+    expect(out).toContain('msgid "Bye"\nmsgstr "[T]Bye"');
+  });
+
+  it('keeps an unseparated entry that carries its own comments', () => {
+    const po = [
+      HEADER,
+      '#: src/a.js:1',
+      'msgid "Hello"',
+      'msgstr "REVIEWED-1"',
+      '#: src/b.js:2',
+      'msgid "Bye"',
+      'msgstr "REVIEWED-2"',
+      '',
+    ].join('\n');
+
+    const out = translateAll(po);
+
+    expect(out).toContain('msgid "Hello"');
+    expect(out).toContain('#: src/a.js:1');
+    expect(out).toContain('msgstr "[T]Hello"');
+    expect(out).toContain('msgstr "[T]Bye"');
+  });
+
+  it('keeps the header when an obsolete entry sits between two unseparated messages', () => {
+    const po = [
+      HEADER,
+      'msgid "Hello"',
+      'msgstr "REVIEWED-1"',
+      '#~ msgid "Gone"',
+      '#~ msgstr "Verschwunden"',
+      'msgid "Bye"',
+      'msgstr "REVIEWED-2"',
+      '',
+    ].join('\n');
+
+    const out = translateAll(po);
+
+    expect(out).toContain('"Content-Type: text/plain; charset=UTF-8\\n"');
+    expect(out).toContain('msgid "Hello"');
+    expect(out).toContain('#~ msgid "Gone"');
+    expect(out).toContain('msgstr "[T]Bye"');
+  });
+
+  it('keeps the header and the plural forms of an unseparated plural entry', () => {
+    const po = [
+      HEADER,
+      'msgid "One item"',
+      'msgid_plural "%d items"',
+      'msgstr[0] "REVIEWED-S"',
+      'msgstr[1] "REVIEWED-P"',
+      'msgid "Bye"',
+      'msgstr "REVIEWED-2"',
+      '',
+    ].join('\n');
+
+    expect(parser.extract(po).map((e) => e.key)).toEqual(['One item', 'Bye']);
+
+    const out = translateAll(po);
+
+    expect(out).toContain('"Plural-Forms: nplurals=2; plural=(n != 1);\\n"');
+    expect(out).toContain('msgid_plural "%d items"');
+    expect(out).toContain('msgstr[0] "REVIEWED-S"');
+  });
+
+  // Over-rejection guards: the separated form is the common case and its
+  // handling must not change, and a genuine continuation line must still be
+  // folded into the field it continues.
+  it('leaves a blank-line-separated catalog exactly as it was', () => {
+    const po = [
+      HEADER,
+      '',
+      'msgid "Hello"',
+      'msgstr "REVIEWED-1"',
+      '',
+      'msgid "Bye"',
+      'msgstr "REVIEWED-2"',
+      '',
+    ].join('\n');
+
+    expect(parser.extract(po).map((e) => e.key)).toEqual(['Hello', 'Bye']);
+
+    const out = translateAll(po);
+
+    expect(out).toContain('"Content-Type: text/plain; charset=UTF-8\\n"');
+    expect(out).toContain('msgid "Hello"\nmsgstr "[T]Hello"');
+    expect(out).toContain('msgid "Bye"\nmsgstr "[T]Bye"');
+  });
+
+  it('still folds a multi-line msgid and msgstr into one entry', () => {
+    const po = [
+      'msgid ""',
+      '"first "',
+      '"second"',
+      'msgstr ""',
+      '"uno "',
+      '"dos"',
+      '',
+    ].join('\n');
+
+    const entries = parser.extract(po);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.key).toBe('first second');
+    expect([...parser.extractTranslations(po)]).toEqual([
+      ['first second', 'uno dos'],
+    ]);
+  });
+});
diff --git a/tests/unit/formats/roundtrip.test.ts b/tests/unit/formats/roundtrip.test.ts
index 3bfbde42..6724d824 100644
--- a/tests/unit/formats/roundtrip.test.ts
+++ b/tests/unit/formats/roundtrip.test.ts
@@ -8,6 +8,7 @@
 import { AndroidXmlFormatParser } from '../../../src/formats/android-xml';
 import { PropertiesFormatParser } from '../../../src/formats/properties';
 import { TomlFormatParser } from '../../../src/formats/toml';
+import { PoFormatParser } from '../../../src/formats/po';
 
 describe('parser round-trip stability', () => {
   describe('Android XML entity escaping', () => {
@@ -164,4 +165,48 @@ describe('parser round-trip stability', () => {
       expect(() => parser.extract(out2)).not.toThrow();
     });
   });
+  // gettext does not require a blank line between entries, and `msgfmt -c`
+  // exits 0 on this catalog. Both the reader and the writer used to treat the
+  // blank line as the only entry terminator, so one sync collapsed the whole
+  // catalog into a single entry: the header lost its charset and the same
+  // translation was written into every msgstr.
+  describe('PO entries with no blank line between them', () => {
+    const source = [
+      'msgid ""',
+      'msgstr ""',
+      '"Content-Type: text/plain; charset=UTF-8\\n"',
+      '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"',
+      'msgid "Hello"',
+      'msgstr "Hallo"',
+      'msgid "Bye"',
+      'msgstr "Tschuess"',
+      '',
+    ].join('\n');
+
+    it('should be a fixed point across three successive syncs', () => {
+      const parser = new PoFormatParser();
+      let content = source;
+      const seen: string[] = [];
+
+      for (let run = 0; run < 3; run++) {
+        const entries = parser.extract(content);
+        content = parser.reconstruct(
+          content,
+          entries.map((e) => ({ ...e, translation: e.value }))
+        );
+        seen.push(content);
+      }
+
+      expect(seen[1]).toBe(seen[0]);
+      expect(seen[2]).toBe(seen[0]);
+      expect(parser.extract(content).map((e) => e.key)).toEqual([
+        'Hello',
+        'Bye',
+      ]);
+      expect(content).toContain('"Content-Type: text/plain; charset=UTF-8\\n"');
+      expect(content).toContain(
+        '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"'
+      );
+    });
+  });
 });

From 5789ee56658d6b88f7ca44b5c66a68309d41d1c7 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 19:33:03 +0200
Subject: [PATCH 168/256] fix(sync): check a target file against what the
 lockfile claims about it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Nothing did. `sync status` and `sync --frozen` both diffed the source file
against `.deepl-sync.lock` and never opened the target, and `sync` itself
returned early whenever the lockfile said there was nothing to do — so a
locale whose file had lost translations the lockfile records as translated
reported 100% complete at exit 0 on every surface, indefinitely, and was
never repaired.

For each key the lockfile records as translated against the current source
text, the locale's target file is now read and checked. A key it does not
hold is counted `unwritten` — its own category, distinct from `missing`
(absent from the lockfile) and `outdated` (recorded against an older source)
— and never counted as complete. `--frozen` treats it as drift and exits 10;
`sync` no longer returns early, so the existing current-key path translates
it again and writes it. A target file that cannot be read or parsed counts
all of its claimed keys.

A key whose source value is empty is exempt: an empty source can only
produce an empty translation, and PO and XLIFF read an empty translation side
as untranslated by design.

The read happens only where the answer would otherwise come from the lockfile
alone, and not at all for a locale the lockfile claims nothing for. Measured
on a 2.8 MiB XLIFF with 20,316 keys across 6 locales: status 410 -> 660 ms,
frozen 465 -> 970 ms.

Refs cli-8kr2.62
---
 CHANGELOG.md                                  |   2 +
 docs/API.md                                   |   4 +-
 docs/SYNC.md                                  |  18 +-
 src/cli/commands/sync-command.ts              |   8 +
 src/cli/commands/sync/register-sync-status.ts |  13 +-
 src/sync/sync-finalize.ts                     |   2 +
 src/sync/sync-process-bucket.ts               |  40 ++-
 src/sync/sync-service.ts                      |   9 +
 src/sync/sync-status.ts                       |  58 +++-
 src/sync/sync-target-audit.ts                 | 142 +++++++++
 tests/e2e/cli-sync.e2e.test.ts                |  66 ++++
 .../sync-target-drift.integration.test.ts     | 179 +++++++++++
 tests/unit/sync/sync-command.test.ts          |   1 +
 tests/unit/sync/sync-target-audit.test.ts     | 294 ++++++++++++++++++
 14 files changed, 828 insertions(+), 8 deletions(-)
 create mode 100644 src/sync/sync-target-audit.ts
 create mode 100644 tests/integration/sync-target-drift.integration.test.ts
 create mode 100644 tests/unit/sync/sync-target-audit.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 91ac7758..a900a753 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -135,6 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a target file that has lost translations the lock file records as translated is no longer reported as 100% complete.** Nothing compared the two: `deepl sync status` and `deepl sync --frozen` both diffed the SOURCE file against `.deepl-sync.lock` and never opened the target file, and `deepl sync` itself returned early whenever the lock file said there was nothing to do. Measured end to end on a healthy two-key project with one key's line deleted from `locales/es.properties` by hand: `sync status` printed `es [####################] 100% (0 missing, 0 outdated)` at exit 0, `sync --frozen` printed `Sync complete: 2 current` at exit 0, and `sync --yes` printed `Sync complete: 2 current` at exit 0 having written nothing — indefinitely, on every run. This is the residual half of the key-dropping finding fixed earlier in this release: the writers no longer drop keys, but a project already damaged by the old behaviour was not repaired by upgrading, and the workaround was to add a string and sync or delete the target file. It is not specific to that, either — a bad merge, a partial checkout, a hand deletion or a `git checkout` of an older locale file all read as complete, and `--frozen` is the CI drift gate whose entire purpose is catching a locale that is not up to date. For every key the lock file records as `translated` against the current source text, the locale's target file is now read and checked. A key it does not hold is counted **`unwritten`** — its own category, distinct from `missing` (absent from the lock file) and `outdated` (recorded against an older source), never counted as complete — so the same project now reports `es [##########..........] 50% (0 missing, 0 outdated, 1 unwritten)` plus a line naming the file and the key, `--frozen` exits **10** naming the count, and `sync` translates the key again and writes it. A target file that cannot be read or cannot be parsed counts all of its claimed keys, which also closes the pre-existing hole where any target-file parse failure read as "no existing translations". Two exemptions, both deliberate: a key whose **source value is empty** is never reported, because an empty source can only produce an empty translation and PO and XLIFF read an empty translation side as untranslated on purpose; and a key already recorded `failed` or against an older hash is not counted twice. `sync` is **not** made to rewrite target files to force agreement — the narrow action is to stop reporting complete and let the existing re-translation path run. **Cost, measured before adopting** on a 2.8 MiB XLIFF source with 20,316 keys across 6 locales (52 MiB of files): `sync status` 410 ms → 660 ms and 207 → ~307 MiB peak RSS; `sync --frozen` 465 ms → 970 ms and 216 → ~365 MiB. The read is skipped entirely for a locale the lock file claims nothing for, and a run that has translating to do never triggers it, since it reads every target file a few lines later anyway. New JSON fields on `sync status`: `unwritten` per locale and a top-level `unwrittenByLocale`; new field `unwrittenKeys` on the sync result.
+
 - **sync**: **a PO catalog written without blank lines between its entries is no longer collapsed into one entry.** The blank-line separator is a gettext convention, not a requirement — `msgfmt -c` exits 0 on every fixture below — but both halves of the PO parser treated it as the only thing that ends an entry, and the damage was total. Measured on a legal five-message catalog with no separators at all: `extract` reported **one** key (`Third`, the last one), so `Hello` and `Bye` were absent from the source key set entirely, and `reconstruct` wrote that single translation into **every** `msgstr` it walked past, the header's included — `msgstr ""` plus `"Content-Type: text/plain; charset=UTF-8\n"` and `"Plural-Forms: nplurals=2; plural=(n != 1);\n"` became `msgstr "[T]Third"`, and `msgfmt -c` on the output then warned `Charset missing in header. Message conversion to user's charset will not work.` Four more shapes were measured, none of them named in the original report: a catalog whose entries carry `#:` comments silently **lost** the whole first entry from the output; an obsolete `#~` run between two messages **deleted the header outright**, at which point `msgfmt -c` failed the output with `PO file header missing or invalid` (exit 1); a plural entry lost its `Plural-Forms` rule and failed `msgfmt -c` with `header entry lacks a "plural=EXPRESSION" attribute`; and `extractTranslations` — the bilingual target read used by `sync`, `push`, `pull`, `validate` and `audit` — reported only the last entry as translated, so every other reviewed `msgstr` looked untranslated and was re-translated and re-billed on every run. An entry now ends where gettext ends it: at the first line that is not a continuation of its translation, i.e. a comment, a `msgctxt`, or the next `msgid`. **Both the reader and the writer needed it** — they scan entry blocks independently, and each was proven to be insufficient alone with its own control: with only the writer fixed the header survives but the key set is still one entry; with only the reader fixed the keys are right but the header is still destroyed. All six catalogs now pass `msgfmt -c` on both input and output, keep their charset and plural rule, and are a fixed point across three successive syncs. Layout is untouched: a catalog that arrived without separators keeps that shape. The blank-line-separated form, multi-line `msgid`/`msgstr` continuations and plural entries are all unchanged.
 
 - **http**: **a response the endpoint cuts off mid-body is reported as a network failure (exit 5), not as invalid input (exit 6).** axios attaches the 200 response to the error it raises for an aborted response stream, and `classifyError` let the mere presence of a response decide: it took the HTTP-status branch and returned `ValidationError('API error: stream has been aborted')`, telling the operator to check input that was never the problem. Reproduced against a stub that declares a `Content-Length`, writes 12 bytes of the body and destroys the socket: `deepl translate "Hello" --to es --max-retries 3` printed `Error: API error: stream has been aborted` at **exit 6**, and `deepl usage` the same. Both now exit **5** with `Network error: the API answered HTTP 200 but its response body did not arrive intact: stream has been aborted`. The test is the status, not the axios code or message: a rejection carrying a 2xx response can only have failed while the body was read, whereas the code varies with how the peer failed (`ERR_BAD_RESPONSE` for an aborted stream, a socket or zlib code otherwise) — both the `Content-Length` and the chunked truncation shapes were measured to confirm it. 3xx, 4xx and 5xx responses keep the classification they had. **The replay policy is deliberately unchanged**, contrary to the finding's framing: the request counts were measured before and after and are identical, 1 for the POST and `--max-retries + 1` for the GET. A 200 means the server accepted — and may have billed — the request, so replaying the billable POST is exactly what must not happen here; the idempotent GET was already being replayed, so the "never retried" half of the report did not hold. The client-side deadline path is untouched: it still restates its own aborts as `ETIMEDOUT` before classification, so both routes end at `NetworkError`.
diff --git a/docs/API.md b/docs/API.md
index 1661c98b..44b347a4 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1391,6 +1391,8 @@ Source: en (142 keys)
   ja  [##################..]  91%  (12 missing, 0 outdated)
 ```
 
+A locale also reports **`unwritten`** keys — recorded as translated in `.deepl-sync.lock` but not in that locale's target file — when there are any, followed by a line naming the file and the keys. The suffix is omitted when the count is zero, so the line above is unchanged for a healthy project. `--format json` always carries `unwritten` on each locale plus a top-level `unwrittenByLocale` array of `{locale, file, keys}`. See [docs/SYNC.md](./SYNC.md#a-string-added-after-the-first-sync) for what is and is not counted.
+
 ##### `validate`
 
 Check translations for placeholder integrity and format consistency.
@@ -1604,7 +1606,7 @@ No other fields appear in the output. Fields not listed above are internal and m
 
 #### Notes
 
-- The `--frozen` flag makes no API calls. It compares the lockfile against source files and exits with code 10 if any translations are missing or outdated. This is the recommended mode for CI/CD pipelines.
+- The `--frozen` flag makes no API calls. It compares the lockfile against source files, and each target file against what the lockfile claims about it, and exits with code 10 if any translations are missing, outdated, or recorded as translated while absent from the target file. This is the recommended mode for CI/CD pipelines.
 - The lockfile (`.deepl-sync.lock`) should be committed to version control. It enables incremental sync by tracking content hashes.
 - The `push` and `pull` subcommands require a TMS that implements the REST contract documented in [docs/SYNC.md](./SYNC.md#tms-rest-contract). All other commands work with the standard DeepL Translation API.
 - By default, keys with extracted context are grouped by i18n section and translated in section batches. Use `--no-batch` to force individual per-key context translation. Use `--batch` to force all keys into plain batch calls (no context).
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 2a61ffdb..c80cb515 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -134,7 +134,23 @@ Two cases are deliberately left out, because writing them would mean inventing s
 
 Whatever the reason a key does not land, the run says so rather than recording it as translated. Every key is read back out of the content just written before the lockfile is updated, so a key the file does not hold is recorded `failed`: the run warns naming the file, the locale and the key, reports `✗ es: 0/1 keys` and exits **12** (`PartialFailure`), `deepl sync status` counts it against the locale, and `deepl sync --frozen` exits **10**. The next sync retries it.
 
-Note that `deepl sync status` and `deepl sync --frozen` compare the source file against `.deepl-sync.lock`, not against the target file. A target file edited by hand to remove a key the lockfile records as translated therefore still reports complete; the key is restored on the next sync that has anything to translate, or immediately if you delete the target file and let it be rebuilt.
+**A target file is also checked against what the lock file claims about it.** For every key the lock file records as `translated` against the current source text, `deepl sync status` and `deepl sync --frozen` open the locale's target file and check that the translation is in it. A key it does not hold is counted **`unwritten`** — a category of its own, distinct from `missing` (absent from the lock file) and `outdated` (recorded against an older source), and never counted as complete:
+
+```
+$ deepl sync status
+Source: en (2 keys)
+
+  es  [##########..........] 50%  (0 missing, 0 outdated, 1 unwritten)
+
+1 key is recorded as translated in the lock file but is not in the target file
+— es: locales/es.properties ("added"). Run `deepl sync` to translate it again.
+```
+
+`--frozen` treats it as drift and exits **10**; `deepl sync` no longer returns early on a project in that state, so the key is translated again and written. This catches a target file damaged by anything outside the CLI as well — a bad merge, a partial checkout, a hand deletion, a `git checkout` of an older locale file — and a target file that cannot be read or cannot be parsed, whose keys all count as `unwritten` because a file whose contents are unavailable cannot be shown to hold them.
+
+Two deliberate exemptions. A key whose **source value is empty** is never reported: an empty source can only produce an empty translation, and PO and XLIFF read an empty translation side as untranslated on purpose (see [Bilingual formats](#bilingual-formats-po-and-xliff)), so such a key is legitimately absent from a bilingual target. A key the lock file records as `failed`, or against an older source hash, is already reported as outdated and is not counted twice.
+
+The cost is one read and parse of each target file per locale, and it is only paid where the answer would otherwise come from the lock file alone: `sync status`, `sync --frozen`, and a `sync` run that has nothing else to do. A run with translating to do reads those files anyway. Measured on a 2.8 MiB XLIFF source with 20,316 keys across 6 locales (52 MiB of files): `sync status` 410 ms → 660 ms, `sync --frozen` 465 ms → 970 ms. A locale with no keys claimed by the lock file is not read at all.
 
 ### Key separators and colliding keys
 
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index 1a395a49..b93ae45e 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -721,11 +721,19 @@ export class SyncCommand {
       if (result.staleKeys > 0) driftParts.push(`${result.staleKeys} stale`);
       if (result.deletedKeys > 0)
         driftParts.push(`${result.deletedKeys} deleted`);
+      if (result.unwrittenKeys > 0)
+        driftParts.push(`${result.unwrittenKeys} unwritten`);
       const driftSummary =
         driftParts.length > 0
           ? driftParts.join(', ')
           : 'no key-level diffs surfaced';
       Logger.info(`Sync drift detected: ${driftSummary} keys.`);
+      if (result.unwrittenKeys > 0) {
+        Logger.info(
+          'Unwritten keys are recorded as translated in the lock file but are not in the target file. ' +
+            'Run `deepl sync status` to see which, and `deepl sync` to translate them again.'
+        );
+      }
       return;
     }
 
diff --git a/src/cli/commands/sync/register-sync-status.ts b/src/cli/commands/sync/register-sync-status.ts
index 608b1228..57cc38cb 100644
--- a/src/cli/commands/sync/register-sync-status.ts
+++ b/src/cli/commands/sync/register-sync-status.ts
@@ -73,10 +73,21 @@ async function handleSyncStatus(
         const bar = `${'#'.repeat(Math.floor(locale.coverage / 5))}${'.'.repeat(
           20 - Math.floor(locale.coverage / 5)
         )}`;
+        const unwrittenSuffix =
+          locale.unwritten > 0 ? `, ${locale.unwritten} unwritten` : '';
         Logger.output(
-          `  ${locale.locale}  [${bar}] ${locale.coverage}%  (${locale.missing} missing, ${locale.outdated} outdated)`
+          `  ${locale.locale}  [${bar}] ${locale.coverage}%  (${locale.missing} missing, ${locale.outdated} outdated${unwrittenSuffix})`
         );
       }
+      const unwritten = status.unwrittenByLocale.filter(
+        (u) => !localeFilter || localeFilter.includes(u.locale)
+      );
+      if (unwritten.length > 0) {
+        const { targetGapsWarning } =
+          await import('../../../sync/sync-target-audit.js');
+        Logger.output('');
+        Logger.warn(targetGapsWarning(unwritten));
+      }
     }
   } catch (error) {
     if (options.format === 'json') {
diff --git a/src/sync/sync-finalize.ts b/src/sync/sync-finalize.ts
index 598654ef..0a43c622 100644
--- a/src/sync/sync-finalize.ts
+++ b/src/sync/sync-finalize.ts
@@ -6,6 +6,7 @@ export interface FinalizeInputs {
   staleKeys: number;
   deletedKeys: number;
   currentKeys: number;
+  unwrittenKeys: number;
   totalCharsBilled: number;
   fileResults: SyncFileResult[];
   validationWarnings: number;
@@ -45,6 +46,7 @@ export function finalizeSyncResult(i: FinalizeInputs): SyncResult {
     staleKeys: i.staleKeys,
     deletedKeys: i.deletedKeys,
     currentKeys: i.currentKeys,
+    unwrittenKeys: i.unwrittenKeys,
     totalCharactersBilled: i.totalCharsBilled,
     fileResults: i.fileResults,
     validationWarnings: i.validationWarnings,
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index 611b3f6d..b065d3ea 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -17,6 +17,7 @@ import {
   extractExistingTranslations,
   type WalkedBucketFile,
 } from './sync-bucket-walker.js';
+import { findTargetGaps } from './sync-target-audit.js';
 import type { LocaleTranslator } from './sync-locale-translator.js';
 import type { SyncFileResult, SyncOptions } from './sync-service.js';
 
@@ -50,6 +51,8 @@ export interface BucketContribution {
   staleKeysDelta: number;
   deletedKeysDelta: number;
   currentKeysDelta: number;
+  /** Keys the lockfile calls translated that the target file does not hold. */
+  unwrittenKeysDelta: number;
   totalCharsBilledDelta: number;
   estimatedCharactersDelta: number;
   validationWarningsDelta: number;
@@ -65,6 +68,7 @@ const EMPTY: BucketContribution = {
   staleKeysDelta: 0,
   deletedKeysDelta: 0,
   currentKeysDelta: 0,
+  unwrittenKeysDelta: 0,
   totalCharsBilledDelta: 0,
   estimatedCharactersDelta: 0,
   validationWarningsDelta: 0,
@@ -143,14 +147,40 @@ export async function processBucket(
     );
   });
 
+  /**
+   * Keys the lockfile calls translated that the target file does not hold.
+   *
+   * Computed lazily, and only where a decision would otherwise be made on the
+   * lockfile alone: `--frozen`, whose whole purpose is catching a locale that is
+   * not up to date, and the early return below, which used to leave a damaged
+   * target unrepaired for as long as no other key needed work. A run that has
+   * translating to do reads every target file a few lines further down anyway.
+   */
+  const unwrittenTargetKeys = async (): Promise<number> => {
+    const effective = options?.localeFilter?.length
+      ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
+      : config.target_locales;
+    const gaps = await findTargetGaps(
+      config,
+      walked,
+      fileLockEntries,
+      effective
+    );
+    let count = 0;
+    for (const keys of gaps.values()) count += keys.size;
+    return count;
+  };
+
   if (options?.frozen) {
     const failMissing = config.validation?.fail_on_missing !== false;
     const failStale = config.validation?.fail_on_stale !== false;
     const hasNew = toTranslate.some((d) => d.status === 'new') || hasNewLocale;
     const hasStale = toTranslate.some((d) => d.status === 'stale');
+    const unwritten = failMissing ? await unwrittenTargetKeys() : 0;
     if (
       (failMissing && (hasNew || deletedDiffs.length > 0)) ||
-      (failStale && hasStale)
+      (failStale && hasStale) ||
+      unwritten > 0
     ) {
       // Promote current keys missing a target-locale translation into newKeysDelta
       // so the displayed count matches dry-run for the same input state.
@@ -158,6 +188,7 @@ export async function processBucket(
         const currentDiffs = diffs.filter((d) => d.status === 'current');
         out.newKeysDelta += currentDiffs.length;
       }
+      out.unwrittenKeysDelta += unwritten;
       out.driftDetected = true;
       return out;
     }
@@ -208,7 +239,12 @@ export async function processBucket(
 
   const hasDeleted = diffs.some((d) => d.status === 'deleted');
 
-  if (toTranslate.length === 0 && !hasDeleted && !hasNewLocale) {
+  if (
+    toTranslate.length === 0 &&
+    !hasDeleted &&
+    !hasNewLocale &&
+    (await unwrittenTargetKeys()) === 0
+  ) {
     return out;
   }
 
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index 3573e6f3..33d22622 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -103,6 +103,12 @@ export interface SyncResult {
   staleKeys: number;
   deletedKeys: number;
   currentKeys: number;
+  /**
+   * Keys the lockfile records as translated whose target file does not hold
+   * them. Counted only where a run stops on the lockfile alone — `--frozen` —
+   * since a run that proceeds re-translates them and reports them as work.
+   */
+  unwrittenKeys: number;
   totalCharactersBilled: number;
   fileResults: SyncFileResult[];
   validationWarnings: number;
@@ -247,6 +253,7 @@ export class SyncService {
     let validationWarnings = 0;
     let validationErrors = 0;
     let driftDetected = false;
+    let unwrittenKeys = 0;
     let lockDirty = false;
 
     // Resolution runs for a dry run too. It costs one listing per kind, the
@@ -460,6 +467,7 @@ export class SyncService {
       validationErrors += contribution.validationErrorsDelta;
       fileResults.push(...contribution.fileResults);
       if (contribution.driftDetected) driftDetected = true;
+      unwrittenKeys += contribution.unwrittenKeysDelta;
       if (contribution.lockDirty) lockDirty = true;
     }
 
@@ -585,6 +593,7 @@ export class SyncService {
       staleKeys,
       deletedKeys,
       currentKeys,
+      unwrittenKeys,
       totalCharsBilled,
       fileResults,
       validationWarnings,
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index 8b123d6f..00bdf473 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -6,12 +6,21 @@ import { computeDiff } from './sync-differ.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import { LOCK_FILE_NAME } from './types.js';
 import { walkBuckets } from './sync-bucket-walker.js';
+import { findTargetGaps } from './sync-target-audit.js';
+import { resolveTargetPath } from './sync-utils.js';
 
 export interface LocaleStatus {
   locale: string;
   complete: number;
   missing: number;
   outdated: number;
+  /**
+   * Keys the lockfile records as translated for this locale that the locale's
+   * target file does not hold. Counted separately from `missing` (absent from
+   * the lockfile) and `outdated` (recorded against an older source), and never
+   * counted as `complete`.
+   */
+  unwritten: number;
   coverage: number;
 }
 
@@ -25,6 +34,18 @@ export interface SyncStatusResult {
    */
   skippedKeys: number;
   locales: LocaleStatus[];
+  /**
+   * Per target file and locale, the keys behind each locale's `unwritten`
+   * count, so the report can name the file and the keys rather than only
+   * counting them.
+   */
+  unwrittenByLocale: UnwrittenTargetKeys[];
+}
+
+export interface UnwrittenTargetKeys {
+  locale: string;
+  file: string;
+  keys: string[];
 }
 
 export async function computeSyncStatus(
@@ -37,13 +58,19 @@ export async function computeSyncStatus(
   const lockFile = await lockManager.read();
   let totalKeys = 0;
   let skippedKeys = 0;
+  const unwrittenByLocale: UnwrittenTargetKeys[] = [];
   const localeStats = new Map<
     string,
-    { complete: number; missing: number; outdated: number }
+    { complete: number; missing: number; outdated: number; unwritten: number }
   >();
 
   for (const locale of config.target_locales) {
-    localeStats.set(locale, { complete: 0, missing: 0, outdated: 0 });
+    localeStats.set(locale, {
+      complete: 0,
+      missing: 0,
+      outdated: 0,
+      unwritten: 0,
+    });
   }
 
   for await (const walked of walkBuckets(config, formatRegistry)) {
@@ -53,6 +80,26 @@ export async function computeSyncStatus(
 
     const fileLockEntries = getOwnMember(lockFile.entries, relPath) ?? {};
     const diffs = computeDiff(fileLockEntries, entries);
+    // The lockfile alone cannot answer "is this locale complete": it records
+    // what a run intended, not what its target file ended up holding.
+    const gaps = await findTargetGaps(
+      config,
+      walked,
+      fileLockEntries,
+      config.target_locales
+    );
+    for (const [locale, keys] of gaps) {
+      unwrittenByLocale.push({
+        locale,
+        file: resolveTargetPath(
+          relPath,
+          config.source_locale,
+          locale,
+          walked.bucketConfig.target_path_pattern
+        ),
+        keys: [...keys],
+      });
+    }
 
     for (const locale of config.target_locales) {
       const stats = localeStats.get(locale);
@@ -76,6 +123,8 @@ export async function computeSyncStatus(
           stats.missing++;
         } else if (diff.status === 'stale' || localeOutdated) {
           stats.outdated++;
+        } else if (gaps.get(locale)?.has(diff.key)) {
+          stats.unwritten++;
         } else {
           stats.complete++;
         }
@@ -88,8 +137,10 @@ export async function computeSyncStatus(
       complete: 0,
       missing: 0,
       outdated: 0,
+      unwritten: 0,
     };
-    const total = stats.complete + stats.missing + stats.outdated;
+    const total =
+      stats.complete + stats.missing + stats.outdated + stats.unwritten;
     const coverage = total > 0 ? Math.round((stats.complete / total) * 100) : 0;
     return { locale, ...stats, coverage };
   });
@@ -99,5 +150,6 @@ export async function computeSyncStatus(
     totalKeys,
     skippedKeys,
     locales,
+    unwrittenByLocale,
   };
 }
diff --git a/src/sync/sync-target-audit.ts b/src/sync/sync-target-audit.ts
new file mode 100644
index 00000000..29de3ee3
--- /dev/null
+++ b/src/sync/sync-target-audit.ts
@@ -0,0 +1,142 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { ResolvedSyncConfig } from './sync-config.js';
+import type { SyncLockEntry } from './types.js';
+import { getOwnMember } from '../utils/own-members.js';
+import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
+import {
+  extractExistingTranslations,
+  type WalkedBucketFile,
+} from './sync-bucket-walker.js';
+
+/**
+ * Keys the lockfile records as translated for a locale that the locale's target
+ * file does not hold, keyed by locale. A locale with nothing missing is absent
+ * from the map.
+ */
+export type TargetGaps = Map<string, Set<string>>;
+
+/**
+ * Which keys a locale would be reported complete for on the strength of the
+ * lockfile alone: source unchanged since the recorded translation, and that
+ * translation recorded as succeeded.
+ *
+ * A key whose source value is empty is left out. An empty source can only
+ * produce an empty translation, and PO and XLIFF read an empty translation side
+ * as "not translated yet" on purpose, so such a key is legitimately absent from
+ * a bilingual target and must not be reported as a gap. This mirrors the
+ * write-verification guard in sync-locale-translator, which exempts an entry
+ * whose translation is the empty string.
+ */
+function claimedKeys(
+  walked: WalkedBucketFile,
+  fileLockEntries: Record<string, SyncLockEntry>,
+  locale: string
+): string[] {
+  const claimed: string[] = [];
+  for (const entry of walked.entries) {
+    if (entry.value === '') continue;
+    const lockEntry = getOwnMember(fileLockEntries, entry.key);
+    const translation = lockEntry?.translations[locale];
+    if (lockEntry === undefined || translation === undefined) continue;
+    if (translation.status !== 'translated') continue;
+    if (translation.hash !== lockEntry.source_hash) continue;
+    claimed.push(entry.key);
+  }
+  return claimed;
+}
+
+/**
+ * Compare a target file against what the lockfile claims about it.
+ *
+ * Nothing used to: `sync status` and `sync --frozen` both diffed the source
+ * file against `.deepl-sync.lock` and never opened the target, so a locale
+ * whose file had lost translations the lockfile calls translated — by an
+ * earlier version of this tool dropping them, a bad merge, a partial checkout,
+ * a hand deletion — reported 100% complete at exit 0 indefinitely, and `sync`
+ * itself returned early without repairing it.
+ *
+ * A file that cannot be read or cannot be parsed yields every claimed key: a
+ * file whose contents are unavailable cannot be shown to hold anything.
+ *
+ * The read is skipped entirely for a locale with no claimed keys, so a project
+ * mid-first-sync costs nothing.
+ */
+export async function findTargetGaps(
+  config: ResolvedSyncConfig,
+  walked: WalkedBucketFile,
+  fileLockEntries: Record<string, SyncLockEntry>,
+  locales: readonly string[]
+): Promise<TargetGaps> {
+  const gaps: TargetGaps = new Map();
+
+  for (const locale of locales) {
+    const claimed = claimedKeys(walked, fileLockEntries, locale);
+    if (claimed.length === 0) continue;
+
+    let held: Map<string, string> | undefined;
+    if (walked.isMultiLocale) {
+      try {
+        held = extractExistingTranslations(
+          walked.parser,
+          walked.content,
+          locale
+        );
+      } catch {
+        held = undefined;
+      }
+    } else {
+      const targetRelPath = resolveTargetPath(
+        walked.relPath,
+        config.source_locale,
+        locale,
+        walked.bucketConfig.target_path_pattern
+      );
+      const targetAbsPath = path.join(config.projectRoot, targetRelPath);
+      assertPathWithinRoot(targetAbsPath, config.projectRoot);
+      try {
+        const targetContent = await fs.promises.readFile(
+          targetAbsPath,
+          'utf-8'
+        );
+        held = extractExistingTranslations(walked.parser, targetContent);
+      } catch {
+        held = undefined;
+      }
+    }
+
+    const missing =
+      held === undefined
+        ? new Set(claimed)
+        : new Set(claimed.filter((key) => !held.has(key)));
+    if (missing.size > 0) {
+      gaps.set(locale, missing);
+    }
+  }
+
+  return gaps;
+}
+
+/**
+ * One line naming what the lockfile claims and the files do not hold, so the
+ * count in `sync status` is actionable rather than a number to puzzle over.
+ */
+export function targetGapsWarning(
+  entries: readonly { locale: string; file: string; keys: readonly string[] }[]
+): string {
+  const total = entries.reduce((sum, e) => sum + e.keys.length, 0);
+  const one = total === 1;
+  const shown = entries.slice(0, 3).map(
+    (e) =>
+      `${e.locale}: ${e.file} (${e.keys
+        .slice(0, 3)
+        .map((k) => `"${k}"`)
+        .join(', ')}${e.keys.length > 3 ? ', …' : ''})`
+  );
+  const more = entries.length > shown.length ? ', …' : '';
+  return (
+    `${total} ${one ? 'key is' : 'keys are'} recorded as translated in the lock file but ` +
+    `${one ? 'is' : 'are'} not in the target file — ${shown.join('; ')}${more}. ` +
+    `Run \`deepl sync\` to translate ${one ? 'it' : 'them'} again.`
+  );
+}
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 281677ea..2fd38a80 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -552,6 +552,72 @@ describe('CLI Sync E2E', () => {
       expect(output).toContain('de');
       expect(output).toMatch(/\d+\s*keys/);
     });
+
+    // A target file that has lost translations the lockfile calls translated
+    // used to report 100% complete at exit 0 on every surface.
+    describe('a target file the lockfile over-reports', () => {
+      function damageTarget(): void {
+        writeSyncConfig(testFiles.path, ['de']);
+        writeSourceFile(testFiles.path);
+        runSyncAll('--yes');
+        const targetPath = path.join(testFiles.path, 'locales', 'de.json');
+        const parsed = JSON.parse(
+          fs.readFileSync(targetPath, 'utf-8')
+        ) as Record<string, string>;
+        delete parsed['farewell'];
+        fs.writeFileSync(targetPath, JSON.stringify(parsed, null, 2) + '\n');
+      }
+
+      it('names the count and the file in status', () => {
+        damageTarget();
+
+        const output = runSyncAll('status');
+
+        expect(output).toContain('1 unwritten');
+        expect(output).toContain('locales/de.json');
+        expect(output).toMatch(/recorded as translated/);
+        expect(output).not.toContain('100%');
+      });
+
+      it('carries the count in --format json', () => {
+        damageTarget();
+
+        const parsed = JSON.parse(runSyncAll('status --format json')) as {
+          locales: { locale: string; unwritten: number; complete: number }[];
+          unwrittenByLocale: { locale: string; file: string; keys: string[] }[];
+        };
+
+        expect(parsed.locales[0]?.unwritten).toBe(1);
+        expect(parsed.unwrittenByLocale).toEqual([
+          { locale: 'de', file: 'locales/de.json', keys: ['farewell'] },
+        ]);
+      });
+
+      it('is drift for --frozen, at exit 10', () => {
+        damageTarget();
+
+        const result = runSyncExpectError('--frozen');
+
+        expect(result.status).toBe(10);
+        expect(result.output).toContain('1 unwritten');
+        expect(result.output).toMatch(/not in the target file/);
+      });
+
+      it('is repaired by the next sync', () => {
+        damageTarget();
+
+        const result = runSyncExpectError('--yes');
+
+        expect(result.status).toBe(0);
+        const parsed = JSON.parse(
+          fs.readFileSync(
+            path.join(testFiles.path, 'locales', 'de.json'),
+            'utf-8'
+          )
+        ) as Record<string, string>;
+        expect(parsed['farewell']).toBeDefined();
+      });
+    });
   });
 
   describe('subcommand: validate', () => {
diff --git a/tests/integration/sync-target-drift.integration.test.ts b/tests/integration/sync-target-drift.integration.test.ts
new file mode 100644
index 00000000..9791368d
--- /dev/null
+++ b/tests/integration/sync-target-drift.integration.test.ts
@@ -0,0 +1,179 @@
+/**
+ * Integration tests for a target file that has lost translations the lockfile
+ * records as translated.
+ *
+ * Nothing used to compare the two. `sync status` and `sync --frozen` diff the
+ * SOURCE file against `.deepl-sync.lock` and never opened the target, and
+ * `sync` itself returned early when the lockfile said there was nothing to do —
+ * so a locale damaged by an earlier version of this tool, a bad merge, a
+ * partial checkout or a hand deletion reported 100% complete at exit 0
+ * indefinitely and was never repaired.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { computeSyncStatus } from '../../src/sync/sync-status';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+
+describe('a target file missing translations the lockfile claims', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-drift-'));
+    harness = createSyncHarness({ parsers: ['properties'] });
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es'],
+      buckets: { properties: { include: ['locales/en.properties'] } },
+    });
+    const sourcePath = path.join(tmpDir, 'locales', 'en.properties');
+    fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+    fs.writeFileSync(
+      sourcePath,
+      'greeting=Hello\nadded=Translate me\n',
+      'utf-8'
+    );
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  function targetPath(): string {
+    return path.join(tmpDir, 'locales', 'es.properties');
+  }
+
+  function replyTranslating(times = 4): nock.Scope {
+    return nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .times(times)
+      .reply(200, (_uri, body) => {
+        const parsed = new URLSearchParams(body as string);
+        return {
+          translations: parsed.getAll('text').map((t) => ({
+            text: `[es]${t}`,
+            detected_source_language: 'EN',
+            billed_characters: t.length,
+          })),
+        };
+      });
+  }
+
+  /** A healthy project, then one key removed from the target by hand. */
+  async function damage(): Promise<void> {
+    replyTranslating();
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+    const kept = fs
+      .readFileSync(targetPath(), 'utf-8')
+      .split('\n')
+      .filter((line) => !line.startsWith('added='))
+      .join('\n');
+    fs.writeFileSync(targetPath(), kept, 'utf-8');
+    expect(fs.readFileSync(targetPath(), 'utf-8')).not.toContain('added=');
+  }
+
+  it('is reported by sync status rather than counted complete', async () => {
+    await damage();
+
+    const status = await computeSyncStatus(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const es = status.locales.find((l) => l.locale === 'es')!;
+    expect(es.unwritten).toBe(1);
+    expect(es.complete).toBe(1);
+    expect(es.coverage).toBe(50);
+  });
+
+  it('is drift as far as --frozen is concerned', async () => {
+    await damage();
+
+    const result = await harness.syncService.sync(
+      await loadSyncConfig(tmpDir),
+      { frozen: true }
+    );
+
+    expect(result.driftDetected).toBe(true);
+  });
+
+  it('is repaired by the next sync instead of being skipped', async () => {
+    await damage();
+    replyTranslating();
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.success).toBe(true);
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toContain(
+      'added=[es]Translate me'
+    );
+  });
+
+  it('reports a target file that was deleted outright', async () => {
+    await damage();
+    fs.unlinkSync(targetPath());
+
+    const status = await computeSyncStatus(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const es = status.locales.find((l) => l.locale === 'es')!;
+    expect(es.unwritten).toBe(2);
+    expect(es.complete).toBe(0);
+    expect(es.coverage).toBe(0);
+  });
+
+  // Over-rejection guards: a healthy project must keep reporting complete, and
+  // the check must not fire before there is anything to check.
+  it('reports a healthy project complete', async () => {
+    replyTranslating();
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    const status = await computeSyncStatus(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const es = status.locales.find((l) => l.locale === 'es')!;
+    expect(es.unwritten).toBe(0);
+    expect(es.complete).toBe(2);
+    expect(es.coverage).toBe(100);
+  });
+
+  it('says nothing about a project that has never been synced', async () => {
+    const status = await computeSyncStatus(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const es = status.locales.find((l) => l.locale === 'es')!;
+    expect(es.unwritten).toBe(0);
+    expect(es.missing).toBe(2);
+    expect(es.coverage).toBe(0);
+  });
+
+  it('leaves a healthy project alone on --frozen', async () => {
+    replyTranslating();
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    const result = await harness.syncService.sync(
+      await loadSyncConfig(tmpDir),
+      { frozen: true }
+    );
+
+    expect(result.driftDetected).toBe(false);
+  });
+});
diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index 42294c81..ecdbbae6 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -81,6 +81,7 @@ function makeResult(overrides: Partial<SyncResult> = {}): SyncResult {
     staleKeys: 1,
     deletedKeys: 0,
     currentKeys: 7,
+    unwrittenKeys: 0,
     totalCharactersBilled: 100,
     fileResults: [],
     validationWarnings: 0,
diff --git a/tests/unit/sync/sync-target-audit.test.ts b/tests/unit/sync/sync-target-audit.test.ts
new file mode 100644
index 00000000..c57b68f6
--- /dev/null
+++ b/tests/unit/sync/sync-target-audit.test.ts
@@ -0,0 +1,294 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import {
+  findTargetGaps,
+  targetGapsWarning,
+} from '../../../src/sync/sync-target-audit';
+import { PropertiesFormatParser } from '../../../src/formats/properties';
+import { XcstringsFormatParser } from '../../../src/formats/xcstrings';
+import { computeSourceHash } from '../../../src/sync/sync-lock';
+import type { ResolvedSyncConfig } from '../../../src/sync/sync-config';
+import type { SyncLockEntry } from '../../../src/sync/types';
+import type { WalkedBucketFile } from '../../../src/sync/sync-bucket-walker';
+import type { FormatParser } from '../../../src/formats/format';
+
+const SOURCE = 'greeting=Hello\nadded=Translate me\n';
+
+describe('findTargetGaps()', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-target-audit-'));
+    fs.mkdirSync(path.join(tmpDir, 'locales'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'locales', 'en.properties'), SOURCE);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function config(): ResolvedSyncConfig {
+    return {
+      version: 1,
+      source_locale: 'en',
+      target_locales: ['es'],
+      buckets: { properties: { include: ['locales/en.properties'] } },
+      configPath: path.join(tmpDir, '.deepl-sync.yaml'),
+      projectRoot: tmpDir,
+      overrides: {},
+    };
+  }
+
+  function walked(overrides: Partial<WalkedBucketFile> = {}): WalkedBucketFile {
+    const parser = new PropertiesFormatParser();
+    return {
+      bucket: 'properties',
+      bucketConfig: { include: ['locales/en.properties'] },
+      parser,
+      sourceFile: path.join(tmpDir, 'locales', 'en.properties'),
+      relPath: 'locales/en.properties',
+      content: SOURCE,
+      entries: parser.extract(SOURCE),
+      skippedEntries: [],
+      isMultiLocale: false,
+      ...overrides,
+    };
+  }
+
+  /** Both source keys recorded as translated for `es`. */
+  function lockEntries(
+    overrides: Record<string, Partial<SyncLockEntry>> = {}
+  ): Record<string, SyncLockEntry> {
+    const build = (value: string): SyncLockEntry => ({
+      source_hash: computeSourceHash(value),
+      source_text: value,
+      translations: {
+        es: {
+          hash: computeSourceHash(value),
+          translated_at: '2026-08-08T00:00:00.000Z',
+          status: 'translated',
+        },
+      },
+    });
+    return {
+      greeting: { ...build('Hello'), ...overrides['greeting'] },
+      added: { ...build('Translate me'), ...overrides['added'] },
+    };
+  }
+
+  function writeTarget(content: string): void {
+    fs.writeFileSync(path.join(tmpDir, 'locales', 'es.properties'), content);
+  }
+
+  it('names a key the target file does not hold', async () => {
+    writeTarget('greeting=Hola\n');
+
+    const gaps = await findTargetGaps(config(), walked(), lockEntries(), [
+      'es',
+    ]);
+
+    expect([...(gaps.get('es') ?? [])]).toEqual(['added']);
+  });
+
+  it('reports nothing when the target holds every claimed key', async () => {
+    writeTarget('greeting=Hola\nadded=Traduceme\n');
+
+    const gaps = await findTargetGaps(config(), walked(), lockEntries(), [
+      'es',
+    ]);
+
+    expect(gaps.size).toBe(0);
+  });
+
+  it('treats a target file that does not exist as holding nothing', async () => {
+    const gaps = await findTargetGaps(config(), walked(), lockEntries(), [
+      'es',
+    ]);
+
+    expect([...(gaps.get('es') ?? [])].sort()).toEqual(['added', 'greeting']);
+  });
+
+  it('treats a target file the parser refuses as holding nothing', async () => {
+    writeTarget('greeting=Hola\nadded=Traduceme\n');
+    const refusing: FormatParser = {
+      ...new PropertiesFormatParser(),
+      extract: () => {
+        throw new Error('duplicate key');
+      },
+    } as unknown as FormatParser;
+
+    const gaps = await findTargetGaps(
+      config(),
+      walked({
+        parser: refusing,
+        entries: new PropertiesFormatParser().extract(SOURCE),
+      }),
+      lockEntries(),
+      ['es']
+    );
+
+    expect([...(gaps.get('es') ?? [])].sort()).toEqual(['added', 'greeting']);
+  });
+
+  // An empty source can only produce an empty translation, and PO and XLIFF
+  // read an empty translation side as untranslated on purpose, so such a key is
+  // legitimately absent from a bilingual target.
+  it('exempts a key whose source value is empty', async () => {
+    const source = 'greeting=Hello\nblank=\n';
+    fs.writeFileSync(path.join(tmpDir, 'locales', 'en.properties'), source);
+    writeTarget('greeting=Hola\n');
+    const parser = new PropertiesFormatParser();
+    const entries = parser.extract(source);
+    const lock: Record<string, SyncLockEntry> = {
+      greeting: lockEntries()['greeting']!,
+      blank: {
+        source_hash: computeSourceHash(''),
+        source_text: '',
+        translations: {
+          es: {
+            hash: computeSourceHash(''),
+            translated_at: '2026-08-08T00:00:00.000Z',
+            status: 'translated',
+          },
+        },
+      },
+    };
+
+    const gaps = await findTargetGaps(
+      config(),
+      walked({ content: source, entries }),
+      lock,
+      ['es']
+    );
+
+    expect(gaps.size).toBe(0);
+  });
+
+  it('exempts a key whose last translation is recorded as failed', async () => {
+    writeTarget('greeting=Hola\n');
+    const lock = lockEntries();
+    lock['added']!.translations['es']!.status = 'failed';
+
+    const gaps = await findTargetGaps(config(), walked(), lock, ['es']);
+
+    expect(gaps.size).toBe(0);
+  });
+
+  it('exempts a key whose recorded hash lags the source', async () => {
+    writeTarget('greeting=Hola\n');
+    const lock = lockEntries();
+    lock['added']!.translations['es']!.hash = 'stale-hash';
+
+    const gaps = await findTargetGaps(config(), walked(), lock, ['es']);
+
+    expect(gaps.size).toBe(0);
+  });
+
+  it('does not read the target file when the lockfile claims nothing', async () => {
+    writeTarget('greeting=Hola\n');
+    const readFile = jest.spyOn(fs.promises, 'readFile');
+
+    const gaps = await findTargetGaps(config(), walked(), {}, ['es']);
+
+    expect(gaps.size).toBe(0);
+    expect(readFile).not.toHaveBeenCalled();
+  });
+});
+
+// A multi-locale format keeps every locale in the one file, so the gap check
+// reads the walked content rather than a sibling path.
+describe('findTargetGaps() over a multi-locale format', () => {
+  const CONTENT =
+    JSON.stringify(
+      {
+        sourceLanguage: 'en',
+        version: '1.0',
+        strings: {
+          greeting: {
+            localizations: {
+              en: { stringUnit: { state: 'translated', value: 'Hello' } },
+              es: { stringUnit: { state: 'translated', value: 'Hola' } },
+            },
+          },
+          farewell: {
+            localizations: {
+              en: { stringUnit: { state: 'translated', value: 'Goodbye' } },
+            },
+          },
+        },
+      },
+      null,
+      2
+    ) + '\n';
+
+  function lockEntries(): Record<string, SyncLockEntry> {
+    const build = (value: string): SyncLockEntry => ({
+      source_hash: computeSourceHash(value),
+      source_text: value,
+      translations: {
+        es: {
+          hash: computeSourceHash(value),
+          translated_at: '2026-08-08T00:00:00.000Z',
+          status: 'translated',
+        },
+      },
+    });
+    return { greeting: build('Hello'), farewell: build('Goodbye') };
+  }
+
+  it('names the key the file has no localization for', async () => {
+    const parser = new XcstringsFormatParser();
+    const gaps = await findTargetGaps(
+      {
+        version: 1,
+        source_locale: 'en',
+        target_locales: ['es'],
+        buckets: { xcstrings: { include: ['app.xcstrings'] } },
+        configPath: '/project/.deepl-sync.yaml',
+        projectRoot: '/project',
+        overrides: {},
+      },
+      {
+        bucket: 'xcstrings',
+        bucketConfig: { include: ['app.xcstrings'] },
+        parser,
+        sourceFile: '/project/app.xcstrings',
+        relPath: 'app.xcstrings',
+        content: CONTENT,
+        // The walker extracts a multi-locale source with the source locale.
+        entries: parser.extract(CONTENT, 'en'),
+        skippedEntries: [],
+        isMultiLocale: true,
+      },
+      lockEntries(),
+      ['es']
+    );
+
+    expect([...(gaps.get('es') ?? [])]).toEqual(['farewell']);
+  });
+});
+
+describe('targetGapsWarning()', () => {
+  it('names the locale, the file and the key for a single gap', () => {
+    const message = targetGapsWarning([
+      { locale: 'es', file: 'locales/es.properties', keys: ['added'] },
+    ]);
+
+    expect(message).toContain('1 key is recorded as translated');
+    expect(message).toContain('es: locales/es.properties ("added")');
+    expect(message).toContain('deepl sync');
+  });
+
+  it('counts every key and elides past the third', () => {
+    const message = targetGapsWarning([
+      { locale: 'es', file: 'es.json', keys: ['a', 'b', 'c', 'd'] },
+      { locale: 'de', file: 'de.json', keys: ['a'] },
+    ]);
+
+    expect(message).toContain('5 keys are recorded as translated');
+    expect(message).toContain('"a", "b", "c", …');
+    expect(message).toContain('de: de.json ("a")');
+  });
+});

From 6605f9937de87ba88a8bfd1388d5e13422d3ef9a Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 22:16:50 +0200
Subject: [PATCH 169/256] fix(sync): refuse a target file that cannot be read
 instead of rebuilding it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The pre-read of each locale's target file swallowed every failure into "this
locale has no existing translations", conflating a locale that has never been
synced with one whose file is on disk and unreadable. The lockfile records source
hashes rather than translated text, so that file is the only copy of its locale's
translations: the run re-translated and re-billed every key and then wrote the
result over it, at exit 0 and with nothing naming the file.

Measured on a two-key JSON project whose target was then given a flat
`"menu.save"` beside a nested `"menu": {"save"}`: `sync --yes` printed
`✓ es: 2/2 keys` at exit 0, made one billable request where a healthy repeat run
makes none, and replaced both reviewed translations plus the file's two other
keys with machine output. The same happened with the source changed, so this is
not an artefact of the `unwritten` repair path, and the same happened to a file
present but unreadable, which kept its mode so the loss left no trace. Of the
parsers that can refuse a file, json, laravel_php and android_xml each have a
reconstruct that accepts a template its own extract rejects and rebuilds it
silently; po and a JSON syntax error failed loudly, but only after the whole
locale had been re-billed.

ENOENT is now the only read failure that means absent — the distinction `sync
push` already drew. Any other errno, and any parse failure, marks that locale
unusable for that file before any translation is requested: the run names the
file and the reason, reports `✗ es: 0/2 keys`, exits 12, bills nothing, and
leaves the file byte-identical. A key the source has just gained is recorded
`failed` rather than `translated`. `sync pull` had the same conflation with a
carve-out for one cause and now routes every unreadable target to the same skip,
under a new `unusable_target` reason; measured on a target holding git conflict
markers, it had been replacing the file with just the keys the export carried.

`sync status` and `--frozen` stop saying such a file's keys "are not in the
target file" and stop advising a re-run that now declines — the two messages
contradicted each other about the same file. Counts are unchanged; status gains
its own sentence naming the file and the reason, and an `unusable` JSON field.

One reader answers absent / usable / unusable for all four call sites and costs
no extra I/O: it replaces a read already being made. Four controls, one per
layer, each failing only its own layer's tests. The fs stub in the sync-service
unit tests modelled a missing file as a message without an errno, which is not
what fs rejects with; it now carries `code: 'ENOENT'`, the idiom two other suites
already used.

Refs cli-8kr2.63
---
 CHANGELOG.md                                  |   6 +
 docs/API.md                                   |   4 +-
 docs/SYNC.md                                  |  50 ++++-
 src/cli/commands/sync-command.ts              |   5 +-
 src/sync/sync-process-bucket.ts               |  31 ++-
 src/sync/sync-status.ts                       |  12 +-
 src/sync/sync-target-audit.ts                 |  99 ++++++---
 src/sync/sync-target-read.ts                  |  68 ++++++
 src/sync/sync-tms.ts                          |  43 ++--
 .../e2e/cli-sync-unusable-target.e2e.test.ts  | 179 ++++++++++++++++
 tests/e2e/cli-sync.e2e.test.ts                |   5 +-
 .../sync-target-drift.integration.test.ts     | 113 ++++++++++
 ...sync-tms-key-collision.integration.test.ts | 107 ++++++++++
 .../sync-unusable-target.integration.test.ts  | 198 ++++++++++++++++++
 tests/unit/sync/sync-service.test.ts          | 121 ++++++-----
 tests/unit/sync/sync-target-audit.test.ts     |  93 +++++++-
 tests/unit/sync/sync-target-read.test.ts      | 132 ++++++++++++
 17 files changed, 1137 insertions(+), 129 deletions(-)
 create mode 100644 src/sync/sync-target-read.ts
 create mode 100644 tests/e2e/cli-sync-unusable-target.e2e.test.ts
 create mode 100644 tests/integration/sync-unusable-target.integration.test.ts
 create mode 100644 tests/unit/sync/sync-target-read.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a900a753..2592aa54 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,6 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **watch**: **a `deepl watch` session now exits 12 rather than 0 when it recorded a failure.** Ctrl+C used to end every session at exit 0 with failed translations and failed auto-commits only logged, so a script wrapping `deepl watch` could not tell a clean run from one that lost work. A session that recorded any translation error or any `--auto-commit` failure now exits **12** (`PartialFailure`), and the auto-commit failure count is printed beside the translation total. A session with no failures still exits 0. See Fixed.
 
+- **sync**: **`deepl sync` exits 12 where it exited 0 on a locale whose target file it cannot read**, and writes nothing for it rather than rebuilding the file from the source. Automation that treated exit 0 as "the locale is up to date" will start failing on a project whose target file is unparseable or unreadable — which is the point: the alternative was re-billing the locale and overwriting the only copy of its translations. `deepl sync pull` reports the same condition as a new `unusable_target` skip reason in its `(N skipped: …)` summary and in `--format json`, at its existing exit code, matching how a colliding target file is already handled. See Fixed.
+
 - **sync**: **`deepl sync` exits 12 where it exited 0 on a key it could not write into the target file.** Any automation treating that command's exit 0 as "the locale is up to date" will start failing on a project it was already shipping incomplete — which is the point: the alternative was a lockfile entry claiming a translation the file does not contain. `sync --frozen` exits 10 and `sync status` counts the key against the locale for the same reason. See Fixed.
 
 - **sync**: **a project already missing strings from this defect recovers on its next sync that has any work to do, and re-bills them.** Measured on a `properties` project whose target file was missing a key the lockfile called `translated`: the next `deepl sync` that had a further key to translate reported `es: 2/2 keys` — the new key plus the recovered one — and wrote both. A run with nothing else to do reported `2 current`, wrote nothing, and `sync status` still said `100% (0 missing)`, because `status` and `--frozen` compare the source against the **lockfile** and never read the target file. So a project where nothing has changed since is not repaired by upgrading alone: add a string and sync, or delete the target file to have it rebuilt. See Fixed for the defect itself.
@@ -135,6 +137,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a target file that cannot be read is left alone instead of being re-translated and overwritten.** The pre-read of each locale's target file swallowed every failure into "this locale has no existing translations", which cannot tell a locale that has never been synced — nothing to lose — from one whose file is on disk and unreadable, which holds the only copy of its translations, since the lock file records hashes rather than translated text. Measured end to end against a mock endpoint, on a healthy two-key JSON project whose `locales/es.json` was then given a flat `"menu.save"` beside a nested `"menu": {"save": …}`, the `.`-separator collision a bad merge produces and the JSON parser refuses: `deepl sync --yes` printed `✓ es: 2/2 keys` and `Sync complete: 2 current` at **exit 0**, made 1 billable translate request where a healthy repeat run makes 0, and rewrote the file as `{"greeting": "Hola", "added": "Traduceme"}` — both hand-reviewed translations replaced by fresh machine output and the file's two other keys deleted — with nothing in the output naming the file. The same happened with the source changed as well (2 requests, exit 0), so this was not an artefact of the `unwritten` repair path added earlier in this release, and the same happened to a file present but unreadable (`chmod 000`), which was rebuilt from the source template and kept its mode, so the damage was not even visible afterwards. The reach is wider than one format: of the parsers that can refuse a file, `json`, `laravel_php` and `android_xml` each have a `reconstruct` that accepts a template its own `extract` rejects and rebuilds it silently, while `po` and a JSON syntax error happened to fail loudly in `reconstruct` — but only after the whole locale had been re-billed. `ENOENT` is now the only read failure that means "absent". Any other errno, and any parse failure, marks that locale unusable for that file **before any translation is requested**: the run prints `Sync failed for locale "es" on "locales/en.json": target file locales/es.json is on disk but could not be read (<reason>) — it holds the only copy of this locale's translations, so it was left as it stands rather than rebuilt from the source. Fix it, then run `deepl sync` again.`, reports `✗ es: 0/2 keys`, exits **12**, bills **0** characters, and leaves the file byte-identical. A key the source has just gained is recorded `failed` rather than `translated`, so the next run retries it once the file is fixed. `deepl sync pull` had the same conflation with a carve-out for one cause (a key collision, added earlier in this release) and now routes every unreadable target to the same outcome: measured on a target file holding git conflict markers, pull printed `Pulled 1 translations` at exit 0 having replaced it with `{"greeting": "TMS-Hola"}`, discarding the local-only key the export does not carry; it now leaves the file byte-identical and records a new `unusable_target` skip reason. `deepl sync push` needed no change — it already propagates every error but `ENOENT`, which is the distinction this fix generalizes. One reader (`readTargetFile`) now answers absent / usable / unusable for all four call sites, and costs no extra I/O: it replaces a read that was already being made.
+
+- **sync**: **`sync status` no longer says the keys of an unreadable target file "are not in the target file", nor tells you to sync again.** Both halves of that sentence are wrong for a file nobody managed to open — its contents are unknown, and `deepl sync` now refuses to rebuild it — so the advice bounced the user between a `status` that said to run `sync` and a `sync` that declined. The count is unchanged, since a file whose contents are unavailable still cannot be shown to hold what the lock file claims; only the reporting is: such a file gets its own sentence naming it and the reason (`2 keys are recorded as translated in the lock file for a target file that could not be read — es: locales/es.json (JSON: 'menu.save' is the key of two different strings. …). Fix the file: \`deepl sync\` will not overwrite it.`), and a project with both kinds of gap gets both sentences rather than one that conflates them. `--format json` carries the reason as a new `unusable` field on the locale's `unwrittenByLocale` entry, absent when the file was read and genuinely lacks the keys. The `--frozen` drift line no longer asserts a cause it has not checked either, and points at `sync status` for the detail.
+
 - **sync**: **a target file that has lost translations the lock file records as translated is no longer reported as 100% complete.** Nothing compared the two: `deepl sync status` and `deepl sync --frozen` both diffed the SOURCE file against `.deepl-sync.lock` and never opened the target file, and `deepl sync` itself returned early whenever the lock file said there was nothing to do. Measured end to end on a healthy two-key project with one key's line deleted from `locales/es.properties` by hand: `sync status` printed `es [####################] 100% (0 missing, 0 outdated)` at exit 0, `sync --frozen` printed `Sync complete: 2 current` at exit 0, and `sync --yes` printed `Sync complete: 2 current` at exit 0 having written nothing — indefinitely, on every run. This is the residual half of the key-dropping finding fixed earlier in this release: the writers no longer drop keys, but a project already damaged by the old behaviour was not repaired by upgrading, and the workaround was to add a string and sync or delete the target file. It is not specific to that, either — a bad merge, a partial checkout, a hand deletion or a `git checkout` of an older locale file all read as complete, and `--frozen` is the CI drift gate whose entire purpose is catching a locale that is not up to date. For every key the lock file records as `translated` against the current source text, the locale's target file is now read and checked. A key it does not hold is counted **`unwritten`** — its own category, distinct from `missing` (absent from the lock file) and `outdated` (recorded against an older source), never counted as complete — so the same project now reports `es [##########..........] 50% (0 missing, 0 outdated, 1 unwritten)` plus a line naming the file and the key, `--frozen` exits **10** naming the count, and `sync` translates the key again and writes it. A target file that cannot be read or cannot be parsed counts all of its claimed keys, which also closes the pre-existing hole where any target-file parse failure read as "no existing translations". Two exemptions, both deliberate: a key whose **source value is empty** is never reported, because an empty source can only produce an empty translation and PO and XLIFF read an empty translation side as untranslated on purpose; and a key already recorded `failed` or against an older hash is not counted twice. `sync` is **not** made to rewrite target files to force agreement — the narrow action is to stop reporting complete and let the existing re-translation path run. **Cost, measured before adopting** on a 2.8 MiB XLIFF source with 20,316 keys across 6 locales (52 MiB of files): `sync status` 410 ms → 660 ms and 207 → ~307 MiB peak RSS; `sync --frozen` 465 ms → 970 ms and 216 → ~365 MiB. The read is skipped entirely for a locale the lock file claims nothing for, and a run that has translating to do never triggers it, since it reads every target file a few lines later anyway. New JSON fields on `sync status`: `unwritten` per locale and a top-level `unwrittenByLocale`; new field `unwrittenKeys` on the sync result.
 
 - **sync**: **a PO catalog written without blank lines between its entries is no longer collapsed into one entry.** The blank-line separator is a gettext convention, not a requirement — `msgfmt -c` exits 0 on every fixture below — but both halves of the PO parser treated it as the only thing that ends an entry, and the damage was total. Measured on a legal five-message catalog with no separators at all: `extract` reported **one** key (`Third`, the last one), so `Hello` and `Bye` were absent from the source key set entirely, and `reconstruct` wrote that single translation into **every** `msgstr` it walked past, the header's included — `msgstr ""` plus `"Content-Type: text/plain; charset=UTF-8\n"` and `"Plural-Forms: nplurals=2; plural=(n != 1);\n"` became `msgstr "[T]Third"`, and `msgfmt -c` on the output then warned `Charset missing in header. Message conversion to user's charset will not work.` Four more shapes were measured, none of them named in the original report: a catalog whose entries carry `#:` comments silently **lost** the whole first entry from the output; an obsolete `#~` run between two messages **deleted the header outright**, at which point `msgfmt -c` failed the output with `PO file header missing or invalid` (exit 1); a plural entry lost its `Plural-Forms` rule and failed `msgfmt -c` with `header entry lacks a "plural=EXPRESSION" attribute`; and `extractTranslations` — the bilingual target read used by `sync`, `push`, `pull`, `validate` and `audit` — reported only the last entry as translated, so every other reviewed `msgstr` looked untranslated and was re-translated and re-billed on every run. An entry now ends where gettext ends it: at the first line that is not a continuation of its translation, i.e. a comment, a `msgctxt`, or the next `msgid`. **Both the reader and the writer needed it** — they scan entry blocks independently, and each was proven to be insufficient alone with its own control: with only the writer fixed the header survives but the key set is still one entry; with only the reader fixed the keys are right but the header is still destroyed. All six catalogs now pass `msgfmt -c` on both input and output, keep their charset and plural rule, and are a fixed point across three successive syncs. Layout is untouched: a catalog that arrived without separators keeps that shape. The blank-line-separated form, multi-line `msgid`/`msgstr` continuations and plural entries are all unchanged.
diff --git a/docs/API.md b/docs/API.md
index 44b347a4..5a477242 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1391,7 +1391,7 @@ Source: en (142 keys)
   ja  [##################..]  91%  (12 missing, 0 outdated)
 ```
 
-A locale also reports **`unwritten`** keys — recorded as translated in `.deepl-sync.lock` but not in that locale's target file — when there are any, followed by a line naming the file and the keys. The suffix is omitted when the count is zero, so the line above is unchanged for a healthy project. `--format json` always carries `unwritten` on each locale plus a top-level `unwrittenByLocale` array of `{locale, file, keys}`. See [docs/SYNC.md](./SYNC.md#a-string-added-after-the-first-sync) for what is and is not counted.
+A locale also reports **`unwritten`** keys — recorded as translated in `.deepl-sync.lock` but not in that locale's target file — when there are any, followed by a line naming the file and the keys. The suffix is omitted when the count is zero, so the line above is unchanged for a healthy project. `--format json` always carries `unwritten` on each locale plus a top-level `unwrittenByLocale` array of `{locale, file, keys}`, each entry gaining an `unusable` field when the target file could not be read or parsed at all. See [docs/SYNC.md](./SYNC.md#a-string-added-after-the-first-sync) for what is and is not counted.
 
 ##### `validate`
 
@@ -3453,6 +3453,8 @@ A key whose translation failed placeholder/ICU validation counts as failed here
 
 A key that translated successfully but that the target file's format could not be given a slot for also counts as failed. Every key is read back out of the content just written before the lockfile is updated, so the run reports it rather than recording a translation the file does not contain. See [A string added after the first sync](SYNC.md#a-string-added-after-the-first-sync).
 
+A locale whose **target file is on disk but could not be read or parsed** fails here as well, and fails before any translation is requested, so nothing is billed for it and the file is not written. That file is the only copy of its locale's translations, since the lockfile records source hashes rather than translated text. See [A target file that cannot be read](SYNC.md#a-target-file-that-cannot-be-read).
+
 `deepl watch` uses the same code when the session ends: on Ctrl+C (SIGINT/SIGTERM) it exits 12 rather than 0 if it recorded any failed translation or any failed `--auto-commit`, so a script driving a watch session can tell a clean run from one that lost work. The counts are printed beside the translation total before the process exits.
 
 Authentication failures (401/403) abort the entire run and surface as exit code 2 (`AuthError`) instead of 12. Network / rate-limit / quota failures bubble up as 5 / 3 / 4 respectively. Code 12 specifically means "the run proceeded far enough to attempt per-locale work, and the result was mixed."
diff --git a/docs/SYNC.md b/docs/SYNC.md
index c80cb515..51df5c8d 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -146,12 +146,58 @@ Source: en (2 keys)
 — es: locales/es.properties ("added"). Run `deepl sync` to translate it again.
 ```
 
-`--frozen` treats it as drift and exits **10**; `deepl sync` no longer returns early on a project in that state, so the key is translated again and written. This catches a target file damaged by anything outside the CLI as well — a bad merge, a partial checkout, a hand deletion, a `git checkout` of an older locale file — and a target file that cannot be read or cannot be parsed, whose keys all count as `unwritten` because a file whose contents are unavailable cannot be shown to hold them.
+`--frozen` treats it as drift and exits **10**; `deepl sync` no longer returns early on a project in that state, so the key is translated again and written. This catches a target file damaged by anything outside the CLI as well — a bad merge, a partial checkout, a hand deletion, a `git checkout` of an older locale file.
+
+A target file that **cannot be read or cannot be parsed** also has all of its claimed keys counted `unwritten` — a file whose contents are unavailable cannot be shown to hold them — but it is reported as its own case, because neither half of the sentence above applies to it: nobody has been shown what it holds, and `deepl sync` refuses to rebuild it (see [A target file that cannot be read](#a-target-file-that-cannot-be-read)).
+
+```
+$ deepl sync status
+Source: en (2 keys)
+
+  es  [....................] 0%  (0 missing, 0 outdated, 2 unwritten)
+
+2 keys are recorded as translated in the lock file for a target file that could
+not be read — es: locales/es.json (JSON: 'menu.save' is the key of two different
+strings. …). Fix the file: `deepl sync` will not overwrite it.
+```
+
+In `--format json` the locale's entry in `unwrittenByLocale` carries an extra `unusable` field holding that reason; an entry without the field is a file that was read and genuinely lacks the keys.
 
 Two deliberate exemptions. A key whose **source value is empty** is never reported: an empty source can only produce an empty translation, and PO and XLIFF read an empty translation side as untranslated on purpose (see [Bilingual formats](#bilingual-formats-po-and-xliff)), so such a key is legitimately absent from a bilingual target. A key the lock file records as `failed`, or against an older source hash, is already reported as outdated and is not counted twice.
 
 The cost is one read and parse of each target file per locale, and it is only paid where the answer would otherwise come from the lock file alone: `sync status`, `sync --frozen`, and a `sync` run that has nothing else to do. A run with translating to do reads those files anyway. Measured on a 2.8 MiB XLIFF source with 20,316 keys across 6 locales (52 MiB of files): `sync status` 410 ms → 660 ms, `sync --frozen` 465 ms → 970 ms. A locale with no keys claimed by the lock file is not read at all.
 
+### A target file that cannot be read
+
+Every command that opens a locale's target file distinguishes three answers, and only the first two let it write:
+
+| The file is | What follows |
+| --- | --- |
+| **not there** (`ENOENT`) | The locale has nothing yet. `sync` writes it from the source template; `pull` creates it. |
+| **there and parseable** | Its translations are merged with the run's, so anything the run does not touch survives. |
+| **there and unreadable** — any other errno (`EACCES`, `EISDIR`, `EIO`), or content the parser refuses | Nothing is translated, nothing is billed, and the file is not written. |
+
+The third case matters because the lock file stores a hash of each source string and not the translated text, so a target file is the only copy of its locale's translations. Treating it as empty means re-translating and re-billing every key and then writing the result over that copy.
+
+`deepl sync` therefore fails that locale for that file, before requesting any translation:
+
+```
+$ deepl sync --yes
+Sync failed for locale "es" on "locales/en.json": target file locales/es.json is
+on disk but could not be read (JSON: 'menu.save' is the key of two different
+strings. …) — it holds the only copy of this locale's translations, so it was left
+as it stands rather than rebuilt from the source. Fix it, then run `deepl sync`
+again.
+  ✗ es: 0/2 keys (locales/en.json)
+Sync complete: 2 current (2 translations failed)
+```
+
+Exit **12** (`PartialFailure`), 0 characters billed, and the file is byte-identical. Other locales of the same file, and other files, are unaffected. A key the source has just gained is recorded `failed` rather than `translated`, so the next run retries it once the file is fixed. `deepl sync status` reports the file under its own sentence (see above) and `--frozen` exits 10.
+
+`deepl sync pull` skips the locale under the `unusable_target` skip reason — or `key_collision` when that is the cause, which has its own remediation (see below) — and leaves the file exactly as it stands. `deepl sync push` reports a file that is not there under `target_missing` and surfaces every other failure, since it only reads.
+
+The distinction is deliberately strict: an errno the CLI does not recognise refuses the file rather than admitting it. A file that is genuinely absent produces `ENOENT` and nothing else.
+
 ### Key separators and colliding keys
 
 Every parser reduces a string's position in the file to a flat key, using a separator the format does not otherwise carry: PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.`. A key component containing that separator makes two different strings share one key, and there is no correct way to write them back — one translation lands in the other's slot.
@@ -952,7 +998,7 @@ Each target locale's approved dictionary is fetched exactly once per `sync pull`
 
 **Pull does not claim human review.** The export endpoint returns `{ "key": "value" }` with no per-entry review flag, so pulled entries are recorded with `status: translated` and **no** `review_status`, meaning "unknown". Earlier releases stamped `review_status: human_reviewed` on every pulled key, asserting a review the CLI had not verified and the response did not describe.
 
-**A target file whose keys collide is left untouched.** Pull reads the existing target file so it can keep translations the export does not carry. If that file cannot be keyed unambiguously (see [Key separators and colliding keys](#key-separators-and-colliding-keys)), the locale is skipped with a warning and reported under the `key_collision` reason, and the file is not written. Pull deliberately does not fall back to reconstructing it from the source file in this case: that would replace the whole file with just the keys the export happened to carry.
+**A target file that cannot be read is left untouched.** Pull reads the existing target file so it can keep translations the export does not carry. If that file cannot be opened, cannot be parsed, or cannot be keyed unambiguously, the locale is skipped with a warning naming the file and the reason, and the file is not written — under the `key_collision` reason when keys collide (see [Key separators and colliding keys](#key-separators-and-colliding-keys)), which has its own remediation, and `unusable_target` otherwise. Pull deliberately does not fall back to reconstructing it from the source file in either case: that would replace the whole file with just the keys the export happened to carry. Only a file that is genuinely not there yet takes that fallback. See [A target file that cannot be read](#a-target-file-that-cannot-be-read).
 
 **Key-count limit:** The pull response is capped at **50,000 keys** (`MAX_PULL_KEY_COUNT`). Responses exceeding this limit are rejected with a `ValidationError` before any data is written. If your TMS project exceeds this threshold, partition the export by locale or paginate the pull on the TMS side before invoking `deepl sync pull`.
 
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index b93ae45e..8bff0e39 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -730,8 +730,9 @@ export class SyncCommand {
       Logger.info(`Sync drift detected: ${driftSummary} keys.`);
       if (result.unwrittenKeys > 0) {
         Logger.info(
-          'Unwritten keys are recorded as translated in the lock file but are not in the target file. ' +
-            'Run `deepl sync status` to see which, and `deepl sync` to translate them again.'
+          'Unwritten keys are recorded as translated in the lock file but could not be confirmed ' +
+            'in the target file. ' +
+            'Run `deepl sync status` to see which keys, in which file, and why.'
         );
       }
       return;
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index b065d3ea..a5f67e50 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -1,4 +1,3 @@
-import * as fs from 'fs';
 import * as path from 'path';
 import { computeDiff } from './sync-differ.js';
 import {
@@ -18,6 +17,7 @@ import {
   type WalkedBucketFile,
 } from './sync-bucket-walker.js';
 import { findTargetGaps } from './sync-target-audit.js';
+import { readTargetFile, unusableTargetMessage } from './sync-target-read.js';
 import type { LocaleTranslator } from './sync-locale-translator.js';
 import type { SyncFileResult, SyncOptions } from './sync-service.js';
 
@@ -167,7 +167,7 @@ export async function processBucket(
       effective
     );
     let count = 0;
-    for (const keys of gaps.values()) count += keys.size;
+    for (const gap of gaps.values()) count += gap.keys.size;
     return count;
   };
 
@@ -296,6 +296,13 @@ export async function processBucket(
 
   // Pre-read existing target files to get current translations
   const existingTargetEntries = new Map<string, Map<string, string>>();
+  /**
+   * Locales whose target file is on disk and could not be read, with the reason.
+   * Such a locale is not translated for this file: its translations exist only in
+   * that file, so treating it as empty would re-bill every key and then write the
+   * result over the copy nobody managed to read.
+   */
+  const unusableTargets = new Map<string, string>();
   for (const locale of locales) {
     if (isMultiLocale) {
       existingTargetEntries.set(
@@ -311,18 +318,18 @@ export async function processBucket(
       );
       const targetAbsPath = path.join(config.projectRoot, targetRelPath);
       assertPathWithinRoot(targetAbsPath, config.projectRoot);
-      try {
-        const targetContent = await fs.promises.readFile(
-          targetAbsPath,
-          'utf-8'
-        );
-        existingTargetEntries.set(
+      const read = await readTargetFile(parser, targetAbsPath);
+      if (read.state === 'unusable') {
+        unusableTargets.set(
           locale,
-          extractExistingTranslations(parser, targetContent)
+          unusableTargetMessage(targetRelPath, read.reason)
         );
-      } catch {
-        existingTargetEntries.set(locale, new Map());
+        continue;
       }
+      existingTargetEntries.set(
+        locale,
+        read.state === 'usable' ? read.translations : new Map()
+      );
     }
   }
 
@@ -351,6 +358,8 @@ export async function processBucket(
         return;
       }
       try {
+        const unusable = unusableTargets.get(locale);
+        if (unusable) throw new Error(unusable);
         const result = await localeTranslator.translate({
           locale,
           relPath,
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index 00bdf473..9b573d2f 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -46,6 +46,11 @@ export interface UnwrittenTargetKeys {
   locale: string;
   file: string;
   keys: string[];
+  /**
+   * Set when the file itself could not be read or parsed, in which case the keys
+   * are what the lockfile claims rather than what the file was shown to lack.
+   */
+  unusable?: string;
 }
 
 export async function computeSyncStatus(
@@ -88,7 +93,7 @@ export async function computeSyncStatus(
       fileLockEntries,
       config.target_locales
     );
-    for (const [locale, keys] of gaps) {
+    for (const [locale, gap] of gaps) {
       unwrittenByLocale.push({
         locale,
         file: resolveTargetPath(
@@ -97,7 +102,8 @@ export async function computeSyncStatus(
           locale,
           walked.bucketConfig.target_path_pattern
         ),
-        keys: [...keys],
+        keys: [...gap.keys],
+        ...(gap.unusable && { unusable: gap.unusable }),
       });
     }
 
@@ -123,7 +129,7 @@ export async function computeSyncStatus(
           stats.missing++;
         } else if (diff.status === 'stale' || localeOutdated) {
           stats.outdated++;
-        } else if (gaps.get(locale)?.has(diff.key)) {
+        } else if (gaps.get(locale)?.keys.has(diff.key)) {
           stats.unwritten++;
         } else {
           stats.complete++;
diff --git a/src/sync/sync-target-audit.ts b/src/sync/sync-target-audit.ts
index 29de3ee3..8aceeb1e 100644
--- a/src/sync/sync-target-audit.ts
+++ b/src/sync/sync-target-audit.ts
@@ -1,4 +1,3 @@
-import * as fs from 'fs';
 import * as path from 'path';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncLockEntry } from './types.js';
@@ -8,13 +7,23 @@ import {
   extractExistingTranslations,
   type WalkedBucketFile,
 } from './sync-bucket-walker.js';
+import { readTargetFile } from './sync-target-read.js';
 
 /**
  * Keys the lockfile records as translated for a locale that the locale's target
- * file does not hold, keyed by locale. A locale with nothing missing is absent
- * from the map.
+ * file does not hold. `unusable` carries the reason when the file could not be
+ * read or parsed at all, so a report can say that rather than claim the keys are
+ * missing from a file nobody managed to look inside.
  */
-export type TargetGaps = Map<string, Set<string>>;
+export interface TargetGap {
+  keys: Set<string>;
+  unusable?: string;
+}
+
+/**
+ * Gaps keyed by locale. A locale with nothing missing is absent from the map.
+ */
+export type TargetGaps = Map<string, TargetGap>;
 
 /**
  * Which keys a locale would be reported complete for on the strength of the
@@ -75,6 +84,7 @@ export async function findTargetGaps(
     if (claimed.length === 0) continue;
 
     let held: Map<string, string> | undefined;
+    let unusable: string | undefined;
     if (walked.isMultiLocale) {
       try {
         held = extractExistingTranslations(
@@ -82,8 +92,8 @@ export async function findTargetGaps(
           walked.content,
           locale
         );
-      } catch {
-        held = undefined;
+      } catch (err) {
+        unusable = err instanceof Error ? err.message : String(err);
       }
     } else {
       const targetRelPath = resolveTargetPath(
@@ -94,15 +104,9 @@ export async function findTargetGaps(
       );
       const targetAbsPath = path.join(config.projectRoot, targetRelPath);
       assertPathWithinRoot(targetAbsPath, config.projectRoot);
-      try {
-        const targetContent = await fs.promises.readFile(
-          targetAbsPath,
-          'utf-8'
-        );
-        held = extractExistingTranslations(walked.parser, targetContent);
-      } catch {
-        held = undefined;
-      }
+      const read = await readTargetFile(walked.parser, targetAbsPath);
+      if (read.state === 'usable') held = read.translations;
+      if (read.state === 'unusable') unusable = read.reason;
     }
 
     const missing =
@@ -110,7 +114,7 @@ export async function findTargetGaps(
         ? new Set(claimed)
         : new Set(claimed.filter((key) => !held.has(key)));
     if (missing.size > 0) {
-      gaps.set(locale, missing);
+      gaps.set(locale, { keys: missing, ...(unusable && { unusable }) });
     }
   }
 
@@ -122,21 +126,52 @@ export async function findTargetGaps(
  * count in `sync status` is actionable rather than a number to puzzle over.
  */
 export function targetGapsWarning(
-  entries: readonly { locale: string; file: string; keys: readonly string[] }[]
+  entries: readonly {
+    locale: string;
+    file: string;
+    keys: readonly string[];
+    unusable?: string;
+  }[]
 ): string {
-  const total = entries.reduce((sum, e) => sum + e.keys.length, 0);
-  const one = total === 1;
-  const shown = entries.slice(0, 3).map(
-    (e) =>
-      `${e.locale}: ${e.file} (${e.keys
-        .slice(0, 3)
-        .map((k) => `"${k}"`)
-        .join(', ')}${e.keys.length > 3 ? ', …' : ''})`
-  );
-  const more = entries.length > shown.length ? ', …' : '';
-  return (
-    `${total} ${one ? 'key is' : 'keys are'} recorded as translated in the lock file but ` +
-    `${one ? 'is' : 'are'} not in the target file — ${shown.join('; ')}${more}. ` +
-    `Run \`deepl sync\` to translate ${one ? 'it' : 'them'} again.`
-  );
+  const missing = entries.filter((e) => e.unusable === undefined);
+  const unreadable = entries.filter((e) => e.unusable !== undefined);
+  const lines: string[] = [];
+
+  if (missing.length > 0) {
+    const total = missing.reduce((sum, e) => sum + e.keys.length, 0);
+    const one = total === 1;
+    const shown = missing.slice(0, 3).map(
+      (e) =>
+        `${e.locale}: ${e.file} (${e.keys
+          .slice(0, 3)
+          .map((k) => `"${k}"`)
+          .join(', ')}${e.keys.length > 3 ? ', …' : ''})`
+    );
+    const more = missing.length > shown.length ? ', …' : '';
+    lines.push(
+      `${total} ${one ? 'key is' : 'keys are'} recorded as translated in the lock file but ` +
+        `${one ? 'is' : 'are'} not in the target file — ${shown.join('; ')}${more}. ` +
+        `Run \`deepl sync\` to translate ${one ? 'it' : 'them'} again.`
+    );
+  }
+
+  // A file nobody could open has not been shown to lack anything, and `deepl
+  // sync` leaves it alone rather than rebuilding it, so the sentence above would
+  // be wrong about both the cause and the cure.
+  if (unreadable.length > 0) {
+    const total = unreadable.reduce((sum, e) => sum + e.keys.length, 0);
+    const one = total === 1;
+    const shown = unreadable
+      .slice(0, 3)
+      .map((e) => `${e.locale}: ${e.file} (${e.unusable})`);
+    const more = unreadable.length > shown.length ? ', …' : '';
+    lines.push(
+      `${total} ${one ? 'key is' : 'keys are'} recorded as translated in the lock file for a ` +
+        `target file that could not be read — ${shown.join('; ')}${more}. ` +
+        `Fix the ${unreadable.length === 1 ? 'file' : 'files'}: \`deepl sync\` will not overwrite ` +
+        `${unreadable.length === 1 ? 'it' : 'them'}.`
+    );
+  }
+
+  return lines.join('\n\n');
 }
diff --git a/src/sync/sync-target-read.ts b/src/sync/sync-target-read.ts
new file mode 100644
index 00000000..9c3bbc53
--- /dev/null
+++ b/src/sync/sync-target-read.ts
@@ -0,0 +1,68 @@
+import * as fs from 'fs';
+
+import type { FormatParser } from '../formats/format.js';
+import { extractExistingTranslations } from './sync-bucket-walker.js';
+
+/**
+ * What reading a locale's target file turned out to yield.
+ *
+ * `absent` and `unusable` are deliberately separate states. A locale that has
+ * never been synced holds nothing, so a run may write its file from scratch. A
+ * file that is on disk but cannot be read or cannot be parsed holds the only
+ * copy of that locale's translations — the lockfile records hashes, not
+ * translated text — so treating it as empty re-translates every key and then
+ * overwrites the file with the result.
+ */
+export type TargetFileRead =
+  | { state: 'absent' }
+  | { state: 'usable'; content: string; translations: Map<string, string> }
+  | { state: 'unusable'; reason: string; error: unknown };
+
+/**
+ * Read a target file and extract the translations it holds.
+ *
+ * `locale` is only consulted for a multi-locale format; a bilingual or
+ * monolingual parser reads the file's own translation side.
+ */
+export async function readTargetFile(
+  parser: FormatParser,
+  absPath: string,
+  locale?: string
+): Promise<TargetFileRead> {
+  let content: string;
+  try {
+    content = await fs.promises.readFile(absPath, 'utf-8');
+  } catch (err) {
+    // Only "no such file" means the locale has nothing yet. Every other errno —
+    // EACCES, EISDIR, EIO — says something is at that path that this run failed
+    // to open, which is not the same as nothing being there.
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { state: 'absent' };
+    }
+    return { state: 'unusable', reason: describe(err), error: err };
+  }
+  try {
+    return {
+      state: 'usable',
+      content,
+      translations: extractExistingTranslations(parser, content, locale),
+    };
+  } catch (err) {
+    return { state: 'unusable', reason: describe(err), error: err };
+  }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Why a run left a target file alone, phrased for a user who has to fix it.
+ */
+export function unusableTargetMessage(relPath: string, reason: string): string {
+  return (
+    `target file ${relPath} is on disk but could not be read (${reason}) — ` +
+    "it holds the only copy of this locale's translations, so it was left as it " +
+    'stands rather than rebuilt from the source. Fix it, then run `deepl sync` again.'
+  );
+}
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index f4545d85..a881df00 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -28,6 +28,7 @@ import {
 } from './sync-bucket-walker.js';
 import { Logger } from '../utils/logger.js';
 import { sweepStaleBackups, resolveBakSweepAgeMs } from './sync-bak-cleanup.js';
+import { readTargetFile } from './sync-target-read.js';
 
 export interface SyncPushPullOptions {
   localeFilter?: string[];
@@ -39,6 +40,7 @@ export type SkipReason =
   | 'no_matches'
   | 'pipe_pluralization'
   | 'key_collision'
+  | 'unusable_target'
   | 'untranslated';
 
 export interface SkippedRecord {
@@ -64,6 +66,7 @@ const SKIP_REASON_LABELS: Record<SkipReason, string> = {
   no_matches: 'no matching keys',
   pipe_pluralization: 'pipe-pluralization (never sent to TMS)',
   key_collision: 'target file keys collide (left untouched)',
+  unusable_target: 'target file could not be read (left untouched)',
   untranslated: 'no translation in the target file',
 };
 
@@ -256,27 +259,27 @@ export async function pullTranslations(
       const targetAbsPath = path.join(config.projectRoot, targetRelPath);
       assertPathWithinRoot(targetAbsPath, config.projectRoot);
 
-      let templateContent: string;
-      let existingTargetEntries = new Map<string, string>();
-      try {
-        templateContent = await fs.promises.readFile(targetAbsPath, 'utf-8');
-        existingTargetEntries = extractExistingTranslations(
-          parser,
-          templateContent,
-          locale
-        );
-      } catch (err) {
-        // A target file whose keys collide cannot be merged into — and must not
-        // fall through to the source template either, which would rebuild it
-        // from source text and discard every local translation the export does
-        // not carry. Leave the file as it stands.
-        if (err instanceof FormatKeyCollisionError) {
-          Logger.warn(`Skipping ${targetRelPath}: ${err.message}`);
-          skipped.push({ file: relPath, locale, reason: 'key_collision' });
-          continue;
-        }
-        templateContent = sourceContent;
+      // A target file that cannot be read or parsed must not fall through to the
+      // source template, which would rebuild it from source text and discard
+      // every local translation the export does not carry. Only a file that is
+      // genuinely not there yet takes that fallback.
+      const read = await readTargetFile(parser, targetAbsPath, locale);
+      if (read.state === 'unusable') {
+        Logger.warn(`Skipping ${targetRelPath}: ${read.reason}`);
+        skipped.push({
+          file: relPath,
+          locale,
+          reason:
+            read.error instanceof FormatKeyCollisionError
+              ? 'key_collision'
+              : 'unusable_target',
+        });
+        continue;
       }
+      const templateContent =
+        read.state === 'usable' ? read.content : sourceContent;
+      const existingTargetEntries =
+        read.state === 'usable' ? read.translations : new Map<string, string>();
 
       const pulledEntries = sourceEntries
         .filter((entry) => keys[entry.key] !== undefined)
diff --git a/tests/e2e/cli-sync-unusable-target.e2e.test.ts b/tests/e2e/cli-sync-unusable-target.e2e.test.ts
new file mode 100644
index 00000000..5fe4c48a
--- /dev/null
+++ b/tests/e2e/cli-sync-unusable-target.e2e.test.ts
@@ -0,0 +1,179 @@
+/**
+ * E2E for a `deepl sync` run whose target file cannot be read.
+ *
+ * The pre-read of each locale's file swallowed every failure as "no existing
+ * translations", so a target file that was on disk but unparseable had its whole
+ * locale re-translated, re-billed and then overwritten with the result, at exit
+ * 0 and without naming the file. The lock file records hashes rather than
+ * translated text, so that file was the only copy of what it replaced.
+ */
+
+import { spawn, spawnSync, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createTestConfigDir, createTestDir } from '../helpers';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+
+describe('CLI sync over an unreadable target file', () => {
+  const testConfig = createTestConfigDir('e2e-sync-unusable-target');
+  const testFiles = createTestDir('e2e-sync-unusable-target-files');
+  let mockServer: ChildProcess;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'node',
+        [path.join(__dirname, 'mock-deepl-server.cjs')],
+        { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env } }
+      );
+      mockServer = child;
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = /PORT=(\d+)/.exec(output);
+        if (match) resolve(parseInt(match[1]!, 10));
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('Mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  function runCli(args: string[]): {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+  } {
+    const { CI: _ci, DEEPL_API_KEY: _key, ...rest } = process.env;
+    const result = spawnSync('node', [CLI_PATH, ...args], {
+      encoding: 'utf-8',
+      cwd: testFiles.path,
+      env: { ...rest, DEEPL_CONFIG_DIR: testConfig.path, NO_COLOR: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60000,
+    });
+    return {
+      status: result.status,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  const sourcePath = (): string =>
+    path.join(testFiles.path, 'locales', 'en.json');
+  const targetPath = (): string =>
+    path.join(testFiles.path, 'locales', 'es.json');
+
+  /** Parses, but `menu.save` names both the flat key and the nested path. */
+  const DAMAGED =
+    JSON.stringify(
+      {
+        greeting: 'REVIEWED Hola',
+        'menu.save': 'FLAT',
+        menu: { save: 'NESTED' },
+      },
+      null,
+      2
+    ) + '\n';
+
+  beforeAll(async () => {
+    const port = await startMockServer();
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        watch: { debounceMs: 500, autoCommit: false, pattern: '*.md' },
+      })
+    );
+    fs.writeFileSync(
+      path.join(testFiles.path, '.deepl-sync.yaml'),
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - es',
+        'buckets:',
+        '  json:',
+        '    include:',
+        '      - "locales/en.json"',
+        '',
+      ].join('\n')
+    );
+    fs.mkdirSync(path.join(testFiles.path, 'locales'), { recursive: true });
+    fs.writeFileSync(
+      sourcePath(),
+      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
+    );
+
+    // A first, healthy sync so the lock file records `greeting` as translated.
+    const first = runCli(['sync', '--yes']);
+    if (first.status !== 0 || !fs.existsSync(targetPath())) {
+      throw new Error(
+        `setup sync failed (${first.status}): ${first.stdout}${first.stderr}`
+      );
+    }
+
+    fs.writeFileSync(targetPath(), DAMAGED, 'utf-8');
+  });
+
+  afterAll(() => {
+    if (mockServer) mockServer.kill();
+    testConfig.cleanup();
+    testFiles.cleanup();
+  });
+
+  it('exits 12, names the file and the reason, and leaves the file alone', () => {
+    const result = runCli(['sync', '--yes']);
+    const output = result.stdout + result.stderr;
+
+    expect(result.status).toBe(12);
+    expect(output).toContain('locales/es.json');
+    expect(output).toContain("'menu.save' is the key of two different strings");
+    expect(output).toContain('left as it stands');
+    expect(output).toContain('✗ es: 0/1 keys');
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toBe(DAMAGED);
+  });
+
+  it('says the file could not be read rather than that its keys are missing', () => {
+    const result = runCli(['sync', 'status']);
+    const output = result.stdout + result.stderr;
+
+    expect(result.status).toBe(0);
+    expect(output).toContain('1 unwritten');
+    expect(output).toContain('could not be read');
+    expect(output).toContain('will not overwrite it');
+    expect(output).not.toContain('translate it again');
+  });
+
+  it('carries the reason in --format json', () => {
+    const result = runCli(['sync', 'status', '--format', 'json']);
+    const parsed = JSON.parse(result.stdout) as {
+      unwrittenByLocale: { locale: string; file: string; unusable?: string }[];
+    };
+
+    const es = parsed.unwrittenByLocale.find((u) => u.locale === 'es')!;
+    expect(es.file).toBe('locales/es.json');
+    expect(es.unusable).toContain('two different strings');
+  });
+
+  it('is drift for --frozen, which points at status rather than at a re-run', () => {
+    const result = runCli(['sync', '--frozen']);
+    const output = result.stdout + result.stderr;
+
+    expect(result.status).toBe(10);
+    expect(output).toContain('1 unwritten');
+    expect(output).toContain('deepl sync status');
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toBe(DAMAGED);
+  });
+});
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 2fd38a80..2789ea10 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -600,7 +600,10 @@ describe('CLI Sync E2E', () => {
 
         expect(result.status).toBe(10);
         expect(result.output).toContain('1 unwritten');
-        expect(result.output).toMatch(/not in the target file/);
+        expect(result.output).toMatch(
+          /could not be confirmed in the target file/
+        );
+        expect(result.output).toContain('deepl sync status');
       });
 
       it('is repaired by the next sync', () => {
diff --git a/tests/integration/sync-target-drift.integration.test.ts b/tests/integration/sync-target-drift.integration.test.ts
index 9791368d..944472ec 100644
--- a/tests/integration/sync-target-drift.integration.test.ts
+++ b/tests/integration/sync-target-drift.integration.test.ts
@@ -177,3 +177,116 @@ describe('a target file missing translations the lockfile claims', () => {
     expect(result.driftDetected).toBe(false);
   });
 });
+
+/**
+ * A target file that is on disk but cannot be read is a different report from one
+ * that is missing keys: nobody has been shown what it holds, and `deepl sync`
+ * refuses to rebuild it, so telling the user to re-run sync would loop them.
+ */
+describe('a target file that cannot be read at all', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-unusable-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es'],
+      buckets: { json: { include: ['locales/en.json'] } },
+    });
+    const sourcePath = path.join(tmpDir, 'locales', 'en.json');
+    fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+    fs.writeFileSync(
+      sourcePath,
+      JSON.stringify({ greeting: 'Hello', added: 'Translate me' }, null, 2),
+      'utf-8'
+    );
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  /** A healthy project, then a '.'-separator collision merged into the target. */
+  async function damage(): Promise<void> {
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => {
+        const parsed = new URLSearchParams(body as string);
+        return {
+          translations: parsed.getAll('text').map((t) => ({
+            text: `[es]${t}`,
+            detected_source_language: 'EN',
+            billed_characters: t.length,
+          })),
+        };
+      });
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+    fs.writeFileSync(
+      path.join(tmpDir, 'locales', 'es.json'),
+      JSON.stringify(
+        {
+          greeting: '[es]Hello',
+          added: '[es]Translate me',
+          'menu.save': 'FLAT',
+          menu: { save: 'NESTED' },
+        },
+        null,
+        2
+      ),
+      'utf-8'
+    );
+  }
+
+  it('is reported with the reason rather than as missing keys', async () => {
+    await damage();
+
+    const status = await computeSyncStatus(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const es = status.locales.find((l) => l.locale === 'es')!;
+    expect(es.unwritten).toBe(2);
+    const entry = status.unwrittenByLocale.find((u) => u.locale === 'es')!;
+    expect(entry.file).toBe('locales/es.json');
+    expect(entry.unusable).toContain(
+      "'menu.save' is the key of two different strings"
+    );
+  });
+
+  it('is drift as far as --frozen is concerned', async () => {
+    await damage();
+
+    const result = await harness.syncService.sync(
+      await loadSyncConfig(tmpDir),
+      { frozen: true }
+    );
+
+    expect(result.driftDetected).toBe(true);
+    expect(result.unwrittenKeys).toBe(2);
+  });
+
+  // Over-rejection guard: a file that reads fine keeps the missing-keys report.
+  it('reports a readable target that lacks a key as missing, not unreadable', async () => {
+    await damage();
+    fs.writeFileSync(
+      path.join(tmpDir, 'locales', 'es.json'),
+      JSON.stringify({ greeting: '[es]Hello' }, null, 2),
+      'utf-8'
+    );
+
+    const status = await computeSyncStatus(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const entry = status.unwrittenByLocale.find((u) => u.locale === 'es')!;
+    expect(entry.keys).toEqual(['added']);
+    expect(entry.unusable).toBeUndefined();
+  });
+});
diff --git a/tests/integration/sync-tms-key-collision.integration.test.ts b/tests/integration/sync-tms-key-collision.integration.test.ts
index 71a50a11..c02b1bc4 100644
--- a/tests/integration/sync-tms-key-collision.integration.test.ts
+++ b/tests/integration/sync-tms-key-collision.integration.test.ts
@@ -105,6 +105,113 @@ describe('sync pull with a colliding target file', () => {
     );
   });
 
+  // A collision is one of several ways a target file can turn out to be
+  // unreadable, and the fallback it was carved out of is ruinous for all of them.
+  it('leaves a target file that does not parse alone and records an unusable_target skip', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeFile(
+      tmpDir,
+      'locales/en.json',
+      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n'
+    );
+    const conflicted =
+      '<<<<<<< HEAD\n' +
+      JSON.stringify(
+        { greeting: 'Hallo (hand-written)', farewell: 'LOCAL ONLY' },
+        null,
+        2
+      ) +
+      '\n=======\n{}\n>>>>>>> theirs\n';
+    writeFile(tmpDir, 'locales/de.json', conflicted);
+
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+    expectTmsPull(
+      'de',
+      { greeting: 'Hallo (from TMS)' },
+      { auth: { apiKey: 'env-key' } }
+    );
+
+    const warnings: string[] = [];
+    jest.spyOn(Logger, 'warn').mockImplementation((...args: unknown[]) => {
+      warnings.push(args.join(' '));
+    });
+
+    const result = await pullTranslations(config, client, harness.registry);
+
+    expect(result.pulled).toBe(0);
+    expect(result.skipped).toEqual([
+      { file: 'locales/en.json', locale: 'de', reason: 'unusable_target' },
+    ]);
+    expect(warnings.join('\n')).toContain('Skipping locales/de.json');
+    expect(fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8')).toBe(
+      conflicted
+    );
+  });
+
+  it('leaves a target file it cannot open alone', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeFile(
+      tmpDir,
+      'locales/en.json',
+      JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n'
+    );
+    const handWritten =
+      JSON.stringify(
+        { greeting: 'Hallo (hand-written)', farewell: 'LOCAL ONLY' },
+        null,
+        2
+      ) + '\n';
+    writeFile(tmpDir, 'locales/de.json', handWritten);
+    fs.chmodSync(path.join(tmpDir, 'locales/de.json'), 0o000);
+
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+    expectTmsPull(
+      'de',
+      { greeting: 'Hallo (from TMS)' },
+      { auth: { apiKey: 'env-key' } }
+    );
+
+    const result = await pullTranslations(config, client, harness.registry);
+
+    expect(result.pulled).toBe(0);
+    expect(result.skipped).toEqual([
+      { file: 'locales/en.json', locale: 'de', reason: 'unusable_target' },
+    ]);
+    fs.chmodSync(path.join(tmpDir, 'locales/de.json'), 0o644);
+    expect(fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8')).toBe(
+      handWritten
+    );
+  });
+
+  // Over-rejection guards: a locale with no file yet is still created from the
+  // source template, and a file that parses is still merged into.
+  it('still creates a target file that does not exist yet', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeFile(
+      tmpDir,
+      'locales/en.json',
+      JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
+    );
+
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+    expectTmsPull(
+      'de',
+      { greeting: 'Hallo (from TMS)' },
+      { auth: { apiKey: 'env-key' } }
+    );
+
+    const result = await pullTranslations(config, client, harness.registry);
+
+    expect(result.pulled).toBe(1);
+    expect(result.skipped).toEqual([]);
+    expect(
+      JSON.parse(fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8'))
+    ).toEqual({ greeting: 'Hallo (from TMS)' });
+  });
+
   it('still pulls into a target file whose keys are distinct', async () => {
     writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
     writeFile(
diff --git a/tests/integration/sync-unusable-target.integration.test.ts b/tests/integration/sync-unusable-target.integration.test.ts
new file mode 100644
index 00000000..393d2e7a
--- /dev/null
+++ b/tests/integration/sync-unusable-target.integration.test.ts
@@ -0,0 +1,198 @@
+/**
+ * Integration tests for a `deepl sync` run over a target file it cannot read.
+ *
+ * The pre-read of each locale's file used to swallow every failure as "this
+ * locale has no existing translations", which cannot tell a locale that has
+ * never been synced from one whose file is on disk and unreadable. For the
+ * second case the run re-translated and re-billed every key and then wrote the
+ * result over the file — and the lockfile stores hashes rather than translated
+ * text, so that file was the only copy of the translations it replaced.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { Logger } from '../../src/utils/logger';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+
+const SOURCE =
+  JSON.stringify({ greeting: 'Hello', added: 'Translate me' }, null, 2) + '\n';
+
+/** Parses as JSON, but `menu.save` names both the flat key and the nested path. */
+const COLLIDING_TARGET =
+  JSON.stringify(
+    {
+      greeting: 'REVIEWED Hola',
+      added: 'REVIEWED Traduceme',
+      'menu.save': 'FLAT',
+      menu: { save: 'NESTED' },
+    },
+    null,
+    2
+  ) + '\n';
+
+describe('sync over a target file that cannot be read', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+  let errors: string[];
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-unusable-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es'],
+      buckets: { json: { include: ['locales/en.json'] } },
+    });
+    const sourcePath = path.join(tmpDir, 'locales', 'en.json');
+    fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+    fs.writeFileSync(sourcePath, SOURCE, 'utf-8');
+    errors = [];
+    jest.spyOn(Logger, 'error').mockImplementation((...args: unknown[]) => {
+      errors.push(args.join(' '));
+    });
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  function targetPath(): string {
+    return path.join(tmpDir, 'locales', 'es.json');
+  }
+
+  function replyTranslating(times = 4): nock.Scope {
+    return nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .times(times)
+      .reply(200, (_uri, body) => {
+        const parsed = new URLSearchParams(body as string);
+        return {
+          translations: parsed.getAll('text').map((t) => ({
+            text: `[es]${t}`,
+            detected_source_language: 'EN',
+            billed_characters: t.length,
+          })),
+        };
+      });
+  }
+
+  /** A healthy project, then the target replaced by one the parser refuses. */
+  async function damage(content = COLLIDING_TARGET): Promise<void> {
+    replyTranslating();
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+    fs.writeFileSync(targetPath(), content, 'utf-8');
+  }
+
+  it('leaves the file byte-identical instead of rebuilding it', async () => {
+    await damage();
+    replyTranslating();
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toBe(COLLIDING_TARGET);
+  });
+
+  it('bills nothing for a locale whose translations it cannot read', async () => {
+    await damage();
+    const scope = replyTranslating();
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.totalCharactersBilled).toBe(0);
+    expect(scope.isDone()).toBe(false);
+  });
+
+  it('fails the locale and names the file and the reason', async () => {
+    await damage();
+    replyTranslating();
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    const es = result.fileResults.find((r) => r.locale === 'es')!;
+    expect(es.translated).toBe(0);
+    expect(es.failed).toBeGreaterThan(0);
+    expect(errors.join('\n')).toContain('locales/es.json');
+    expect(errors.join('\n')).toContain(
+      "'menu.save' is the key of two different strings"
+    );
+  });
+
+  it('records a key the source has just gained as failed, not translated', async () => {
+    await damage();
+    fs.writeFileSync(
+      path.join(tmpDir, 'locales', 'en.json'),
+      JSON.stringify(
+        { greeting: 'Hello', added: 'Translate me', fresh: 'Good morning' },
+        null,
+        2
+      ) + '\n',
+      'utf-8'
+    );
+    replyTranslating();
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    const lock = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, '.deepl-sync.lock'), 'utf-8')
+    ) as {
+      entries: Record<
+        string,
+        Record<string, { translations: Record<string, { status: string }> }>
+      >;
+    };
+    expect(
+      lock.entries['locales/en.json']!['fresh']!.translations['es']!.status
+    ).toBe('failed');
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toBe(COLLIDING_TARGET);
+  });
+
+  it('leaves a target file that is on disk but unreadable alone', async () => {
+    await damage(SOURCE);
+    fs.chmodSync(targetPath(), 0o000);
+    const scope = replyTranslating();
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    fs.chmodSync(targetPath(), 0o644);
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toBe(SOURCE);
+    expect(result.totalCharactersBilled).toBe(0);
+    expect(scope.isDone()).toBe(false);
+  });
+
+  // Over-rejection guards: absent is not unusable, and a file that reads fine is
+  // still repaired.
+  it('still writes a locale that has never been synced', async () => {
+    replyTranslating();
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.totalCharactersBilled).toBeGreaterThan(0);
+    expect(JSON.parse(fs.readFileSync(targetPath(), 'utf-8'))).toEqual({
+      greeting: '[es]Hello',
+      added: '[es]Translate me',
+    });
+  });
+
+  it('still repairs a readable target that lost a key', async () => {
+    await damage(JSON.stringify({ greeting: '[es]Hello' }, null, 2) + '\n');
+    replyTranslating();
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(JSON.parse(fs.readFileSync(targetPath(), 'utf-8'))).toEqual({
+      greeting: '[es]Hello',
+      added: '[es]Translate me',
+    });
+  });
+});
diff --git a/tests/unit/sync/sync-service.test.ts b/tests/unit/sync/sync-service.test.ts
index 362cdb1c..b157bfe6 100644
--- a/tests/unit/sync/sync-service.test.ts
+++ b/tests/unit/sync/sync-service.test.ts
@@ -27,7 +27,11 @@ jest.mock('fs', () => ({
   promises: {
     readFile: jest.fn().mockResolvedValue('{}'),
     mkdir: jest.fn().mockResolvedValue(undefined),
-    access: jest.fn().mockRejectedValue(new Error('ENOENT')),
+    access: jest.fn().mockRejectedValue(
+      Object.assign(new Error('ENOENT: no such file or directory'), {
+        code: 'ENOENT',
+      })
+    ),
     copyFile: jest.fn().mockResolvedValue(undefined),
     unlink: jest.fn().mockResolvedValue(undefined),
   },
@@ -288,6 +292,17 @@ function setupLockManager(lockFile: SyncLockFile) {
   return { mockRead, mockWrite };
 }
 
+/**
+ * What `fs` rejects with for a missing file: the errno, not only a message. The
+ * sync write path tells "not there" from "there and unreadable" by the code, so a
+ * stub that carries no code models an unreadable file rather than an absent one.
+ */
+function enoent(): NodeJS.ErrnoException {
+  return Object.assign(new Error('ENOENT: no such file or directory'), {
+    code: 'ENOENT',
+  });
+}
+
 const SOURCE_JSON =
   JSON.stringify({ greeting: 'Hello', farewell: 'Goodbye' }, null, 2) + '\n';
 
@@ -305,7 +320,7 @@ describe('SyncService', () => {
       mockReadFile.mockImplementation(async (p: unknown) => {
         const filePath = String(p);
         if (filePath === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig();
@@ -334,7 +349,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig());
@@ -424,7 +439,7 @@ describe('SyncService', () => {
         const filePath = String(p);
         if (filePath === '/test/locales/en.json') return SOURCE_JSON;
         if (filePath === '/test/locales/de.json') return '{"greeting":"Alt"}';
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -492,7 +507,7 @@ describe('SyncService', () => {
         const filePath = String(p);
         if (filePath === '/test/locales/en.json') return SOURCE_JSON;
         if (filePath === '/test/locales/de.json') return '{"greeting":"Alt"}';
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig());
@@ -560,7 +575,7 @@ describe('SyncService', () => {
       mockReadFile.mockImplementation(async (p: unknown) => {
         const filePath = String(p);
         if (filePath === '/test/Localizable.xcstrings') return XCSTRINGS_SOURCE;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeMultiLocaleConfig());
@@ -606,7 +621,7 @@ describe('SyncService', () => {
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/Localizable.xcstrings')
           return XCSTRINGS_SOURCE;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeMultiLocaleConfig());
@@ -638,7 +653,7 @@ describe('SyncService', () => {
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/Localizable.xcstrings')
           return XCSTRINGS_SOURCE;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeMultiLocaleConfig());
@@ -793,7 +808,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig(), { force: true });
@@ -829,7 +844,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig(), { force: true });
@@ -855,7 +870,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({ target_locales: ['de', 'fr', 'es'] });
@@ -901,7 +916,7 @@ describe('SyncService', () => {
         const filePath = String(p);
         if (filePath === '/test/locales/en.json') return SOURCE_JSON;
         if (filePath === '/test/locales/de.json') return '';
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -926,7 +941,7 @@ describe('SyncService', () => {
         const filePath = String(p);
         if (filePath === '/test/locales/en.yaml') return 'greeting: Hello\n';
         if (filePath === '/test/locales/de.yaml') return '';
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -975,7 +990,7 @@ describe('SyncService', () => {
         if (filePath.endsWith('a.json') || filePath.endsWith('b.json')) {
           return JSON.stringify({ key: 'value' }, null, 2) + '\n';
         }
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -1001,7 +1016,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1041,7 +1056,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1071,7 +1086,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1109,7 +1124,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig());
@@ -1141,7 +1156,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig());
@@ -1196,7 +1211,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({ target_locales: ['de', 'fr'] });
@@ -1223,7 +1238,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({ target_locales: ['de', 'fr', 'es'] });
@@ -1302,7 +1317,7 @@ describe('SyncService', () => {
         const filePath = String(p);
         if (filePath === '/test/locales/en.json') return sourceJson;
         if (filePath === '/test/locales/de.json') return targetDeJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1340,7 +1355,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig());
@@ -1369,7 +1384,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return '{}';
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1409,7 +1424,7 @@ describe('SyncService', () => {
       );
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1456,7 +1471,7 @@ describe('SyncService', () => {
       );
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1483,7 +1498,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const { mockWrite } = setupLockManager(makeEmptyLockFile());
@@ -1525,7 +1540,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig());
@@ -1560,7 +1575,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1592,7 +1607,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -1624,7 +1639,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return singleKeyJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       mockExtractAllKeyContexts.mockResolvedValue({
@@ -1660,7 +1675,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       mockExtractAllKeyContexts.mockResolvedValue({
@@ -1703,7 +1718,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       mockExtractAllKeyContexts.mockResolvedValue({
@@ -1747,7 +1762,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return threeKeyJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       // Only 'greeting' has context; 'farewell' and 'other' do not
@@ -1789,7 +1804,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const events: Array<{ type: string; key?: string; translated: number }> =
@@ -1828,7 +1843,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const events: Array<{ type: string; translated: number }> = [];
@@ -1849,7 +1864,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const progressEvents: unknown[] = [];
@@ -1875,7 +1890,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return singleKeyJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       mockExtractAllKeyContexts.mockResolvedValue({
@@ -1909,7 +1924,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -1940,7 +1955,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -1982,7 +1997,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -2022,7 +2037,7 @@ describe('SyncService', () => {
       mockReadFile.mockImplementation(async (p: unknown) => {
         const filePath = String(p);
         if (filePath === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({ target_locales: ['de', 'fr'] });
@@ -2072,7 +2087,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -2135,7 +2150,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       await service.sync(makeConfig());
@@ -2174,7 +2189,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -2202,7 +2217,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -2232,7 +2247,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -2259,7 +2274,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -2290,7 +2305,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -2320,7 +2335,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig({
@@ -2374,7 +2389,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const result = await service.sync(makeConfig());
@@ -2973,7 +2988,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return sourceJson;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig();
@@ -3002,7 +3017,7 @@ describe('SyncService', () => {
       mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
       mockReadFile.mockImplementation(async (p: unknown) => {
         if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
-        throw new Error('ENOENT');
+        throw enoent();
       });
 
       const config = makeConfig();
diff --git a/tests/unit/sync/sync-target-audit.test.ts b/tests/unit/sync/sync-target-audit.test.ts
index c57b68f6..feb6451b 100644
--- a/tests/unit/sync/sync-target-audit.test.ts
+++ b/tests/unit/sync/sync-target-audit.test.ts
@@ -89,7 +89,7 @@ describe('findTargetGaps()', () => {
       'es',
     ]);
 
-    expect([...(gaps.get('es') ?? [])]).toEqual(['added']);
+    expect([...(gaps.get('es')?.keys ?? [])]).toEqual(['added']);
   });
 
   it('reports nothing when the target holds every claimed key', async () => {
@@ -107,7 +107,10 @@ describe('findTargetGaps()', () => {
       'es',
     ]);
 
-    expect([...(gaps.get('es') ?? [])].sort()).toEqual(['added', 'greeting']);
+    expect([...(gaps.get('es')?.keys ?? [])].sort()).toEqual([
+      'added',
+      'greeting',
+    ]);
   });
 
   it('treats a target file the parser refuses as holding nothing', async () => {
@@ -129,7 +132,51 @@ describe('findTargetGaps()', () => {
       ['es']
     );
 
-    expect([...(gaps.get('es') ?? [])].sort()).toEqual(['added', 'greeting']);
+    expect([...(gaps.get('es')?.keys ?? [])].sort()).toEqual([
+      'added',
+      'greeting',
+    ]);
+  });
+
+  it('carries the reason a target file could not be parsed', async () => {
+    writeTarget('greeting=Hola\nadded=Traduceme\n');
+    const refusing: FormatParser = {
+      ...new PropertiesFormatParser(),
+      extract: () => {
+        throw new Error('two strings share one key');
+      },
+    } as unknown as FormatParser;
+
+    const gaps = await findTargetGaps(
+      config(),
+      walked({
+        parser: refusing,
+        entries: new PropertiesFormatParser().extract(SOURCE),
+      }),
+      lockEntries(),
+      ['es']
+    );
+
+    expect(gaps.get('es')?.unusable).toBe('two strings share one key');
+  });
+
+  it('says nothing about usability when the file was read and simply lacks a key', async () => {
+    writeTarget('greeting=Hola\n');
+
+    const gaps = await findTargetGaps(config(), walked(), lockEntries(), [
+      'es',
+    ]);
+
+    expect(gaps.get('es')?.unusable).toBeUndefined();
+  });
+
+  it('says nothing about usability when the file is not there at all', async () => {
+    const gaps = await findTargetGaps(config(), walked(), lockEntries(), [
+      'es',
+    ]);
+
+    expect(gaps.get('es')?.keys.size).toBe(2);
+    expect(gaps.get('es')?.unusable).toBeUndefined();
   });
 
   // An empty source can only produce an empty translation, and PO and XLIFF
@@ -266,7 +313,7 @@ describe('findTargetGaps() over a multi-locale format', () => {
       ['es']
     );
 
-    expect([...(gaps.get('es') ?? [])]).toEqual(['farewell']);
+    expect([...(gaps.get('es')?.keys ?? [])]).toEqual(['farewell']);
   });
 });
 
@@ -291,4 +338,42 @@ describe('targetGapsWarning()', () => {
     expect(message).toContain('"a", "b", "c", …');
     expect(message).toContain('de: de.json ("a")');
   });
+
+  // A file nobody could read has not been shown to be missing anything, and
+  // `deepl sync` refuses to overwrite it — so neither half of the sentence above
+  // is true of it.
+  it('says a target file could not be read rather than that its keys are missing', () => {
+    const message = targetGapsWarning([
+      {
+        locale: 'es',
+        file: 'locales/es.json',
+        keys: ['greeting'],
+        unusable: "JSON: 'a.b' is the key of two different strings",
+      },
+    ]);
+
+    expect(message).toContain('could not be read');
+    expect(message).toContain(
+      "es: locales/es.json (JSON: 'a.b' is the key of two different strings)"
+    );
+    expect(message).not.toContain('is not in the target file');
+    expect(message).not.toContain('translate it again');
+  });
+
+  it('reports an unreadable file and a genuinely incomplete one separately', () => {
+    const message = targetGapsWarning([
+      {
+        locale: 'es',
+        file: 'locales/es.json',
+        keys: ['a'],
+        unusable: 'EISDIR',
+      },
+      { locale: 'de', file: 'locales/de.json', keys: ['b'] },
+    ]);
+
+    expect(message).toContain('1 key is recorded as translated');
+    expect(message).toContain('de: locales/de.json ("b")');
+    expect(message).toContain('could not be read');
+    expect(message).toContain('es: locales/es.json (EISDIR)');
+  });
 });
diff --git a/tests/unit/sync/sync-target-read.test.ts b/tests/unit/sync/sync-target-read.test.ts
new file mode 100644
index 00000000..e66b414e
--- /dev/null
+++ b/tests/unit/sync/sync-target-read.test.ts
@@ -0,0 +1,132 @@
+/**
+ * A target file that cannot be read is not a target file that is not there.
+ *
+ * Every caller that opens a locale's file has to tell the two apart: the
+ * lockfile stores hashes rather than translated text, so a file on disk holds
+ * the only copy of its locale's translations, while a file that has never been
+ * written holds nothing and is safe to create.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { readTargetFile } from '../../../src/sync/sync-target-read';
+import { PropertiesFormatParser } from '../../../src/formats/properties';
+import { XcstringsFormatParser } from '../../../src/formats/xcstrings';
+import { JsonFormatParser } from '../../../src/formats/json';
+import type { FormatParser } from '../../../src/formats/format';
+
+describe('readTargetFile()', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-target-read-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function target(): string {
+    return path.join(tmpDir, 'es.properties');
+  }
+
+  it('reports a file that is not there as absent', async () => {
+    const read = await readTargetFile(new PropertiesFormatParser(), target());
+
+    expect(read).toEqual({ state: 'absent' });
+  });
+
+  it('returns the content and the translations of a file it can parse', async () => {
+    fs.writeFileSync(target(), 'greeting=Hola\nadded=Traduceme\n');
+
+    const read = await readTargetFile(new PropertiesFormatParser(), target());
+
+    expect(read.state).toBe('usable');
+    if (read.state !== 'usable') return;
+    expect(read.content).toBe('greeting=Hola\nadded=Traduceme\n');
+    expect([...read.translations]).toEqual([
+      ['greeting', 'Hola'],
+      ['added', 'Traduceme'],
+    ]);
+  });
+
+  it('reports a file the parser refuses as unusable, with the reason', async () => {
+    fs.writeFileSync(target(), 'greeting=Hola\n');
+    const refusing = {
+      ...new PropertiesFormatParser(),
+      extract: () => {
+        throw new Error('two strings share one key');
+      },
+    } as unknown as FormatParser;
+
+    const read = await readTargetFile(refusing, target());
+
+    expect(read.state).toBe('unusable');
+    if (read.state !== 'unusable') return;
+    expect(read.reason).toBe('two strings share one key');
+    // The error itself travels with the reason so a caller can tell one cause
+    // apart from another — pull reports a collision under its own skip reason.
+    expect(read.error).toBeInstanceOf(Error);
+  });
+
+  it('reports a real collision in a JSON target as unusable', async () => {
+    const jsonTarget = path.join(tmpDir, 'es.json');
+    fs.writeFileSync(
+      jsonTarget,
+      JSON.stringify({ 'a.b': 'FLAT', a: { b: 'NESTED' } }, null, 2)
+    );
+
+    const read = await readTargetFile(new JsonFormatParser(), jsonTarget);
+
+    expect(read.state).toBe('unusable');
+    if (read.state !== 'unusable') return;
+    expect(read.reason).toContain("'a.b' is the key of two different strings");
+  });
+
+  it('reports a read failure that is not "no such file" as unusable', async () => {
+    // A directory where a file is expected fails with EISDIR, which says the
+    // path is occupied — the opposite of the absent case.
+    fs.mkdirSync(target());
+
+    const read = await readTargetFile(new PropertiesFormatParser(), target());
+
+    expect(read.state).toBe('unusable');
+    if (read.state !== 'unusable') return;
+    expect(read.reason).toContain('EISDIR');
+  });
+
+  it('reads the named locale out of a multi-locale file', async () => {
+    const xcstrings = path.join(tmpDir, 'app.xcstrings');
+    fs.writeFileSync(
+      xcstrings,
+      JSON.stringify(
+        {
+          sourceLanguage: 'en',
+          version: '1.0',
+          strings: {
+            greeting: {
+              localizations: {
+                en: { stringUnit: { state: 'translated', value: 'Hello' } },
+                es: { stringUnit: { state: 'translated', value: 'Hola' } },
+              },
+            },
+          },
+        },
+        null,
+        2
+      )
+    );
+
+    const read = await readTargetFile(
+      new XcstringsFormatParser(),
+      xcstrings,
+      'es'
+    );
+
+    expect(read.state).toBe('usable');
+    if (read.state !== 'usable') return;
+    expect(read.translations.get('greeting')).toBe('Hola');
+  });
+});

From 1e029dbc1f70c1a2f33756761df2cd0136377b73 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 22:26:53 +0200
Subject: [PATCH 170/256] fix(sync): say which URL spellings a plaintext TMS
 server may use

`TMS server URL must use HTTPS` was the whole of the refusal, so a developer
whose `.deepl-sync.yaml` named `http://[::1]:3000` learned at exit 7 that the
rule exists and nothing about how to satisfy it. Reproduced across eight
spellings with the built CLI and the trust gate pre-approved.

The waiver is deliberately not widened. It is the same pair the API base URL
waives in utils/validate-url.ts, and `http://localhost` was measured to be the
complete remedy: through the CLI it reaches a TMS bound only to `::1` (exit 0,
the `::1`-bound server logging the PUT), and a bare bind test confirms
`localhost` also reaches `0.0.0.0` and `127.0.0.1` binds. `0.0.0.0` is not a
loopback address, and `127.0.0.2` will not even bind here (EADDRNOTAVAIL without
aliasing lo0), so widening would admit spellings nothing can serve while making
this rule looser than the one for `--api-url`.

`http://0x7f.0.0.1`, `http://127.1` and `http://2130706433` were already
accepted, contrary to the finding: the URL parser normalizes all three to
127.0.0.1. Four tests pin that, and that `0.0.0.0` stays refused, so the message
change cannot widen the gate.

The refusal now echoes the URL and carries the remedy as its suggestion. The
destination-trust gate is untouched and still exempts no loopback address at all,
because it answers a different question.

Refs cli-8kr2.54
---
 CHANGELOG.md                       |  2 +
 docs/SYNC.md                       |  2 +-
 src/sync/tms-client.ts             | 14 ++++++-
 tests/unit/sync/tms-client.test.ts | 59 ++++++++++++++++++++++++++++++
 4 files changed, 75 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2592aa54..c5143195 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -137,6 +137,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`TMS server URL must use HTTPS` now says which spellings are waived and how to reach a local TMS.** Plain `http://` is accepted for `http://localhost` and `http://127.0.0.1` only — the same pair the DeepL API base URL waives — so a developer whose `.deepl-sync.yaml` named `http://[::1]:3000` got a one-line refusal at exit 7 with no way to act on it. The rule is unchanged; the error now echoes the URL and points at `http://localhost`, which was measured to reach a server bound to `::1` only (HTTP 200 through the CLI, the `::1`-bound server logging the `PUT`) as well as one bound to `0.0.0.0` or `127.0.0.1`, so it covers every local bind rather than being a partial answer. The waiver was deliberately **not** widened: it would make this rule more permissive than the one for `--api-url`, `0.0.0.0` is not a loopback address, and `127.0.0.2` is not bindable at all without aliasing the loopback interface (`EADDRNOTAVAIL` on macOS). `http://0x7f.0.0.1`, `http://127.1` and `http://2130706433` were already accepted, contrary to the finding: the URL parser normalizes all three to `127.0.0.1`, which four new tests pin so the change cannot widen the gate. The destination-trust gate still does not exempt loopback at all, and answers a different question.
+
 - **sync**: **a target file that cannot be read is left alone instead of being re-translated and overwritten.** The pre-read of each locale's target file swallowed every failure into "this locale has no existing translations", which cannot tell a locale that has never been synced — nothing to lose — from one whose file is on disk and unreadable, which holds the only copy of its translations, since the lock file records hashes rather than translated text. Measured end to end against a mock endpoint, on a healthy two-key JSON project whose `locales/es.json` was then given a flat `"menu.save"` beside a nested `"menu": {"save": …}`, the `.`-separator collision a bad merge produces and the JSON parser refuses: `deepl sync --yes` printed `✓ es: 2/2 keys` and `Sync complete: 2 current` at **exit 0**, made 1 billable translate request where a healthy repeat run makes 0, and rewrote the file as `{"greeting": "Hola", "added": "Traduceme"}` — both hand-reviewed translations replaced by fresh machine output and the file's two other keys deleted — with nothing in the output naming the file. The same happened with the source changed as well (2 requests, exit 0), so this was not an artefact of the `unwritten` repair path added earlier in this release, and the same happened to a file present but unreadable (`chmod 000`), which was rebuilt from the source template and kept its mode, so the damage was not even visible afterwards. The reach is wider than one format: of the parsers that can refuse a file, `json`, `laravel_php` and `android_xml` each have a `reconstruct` that accepts a template its own `extract` rejects and rebuilds it silently, while `po` and a JSON syntax error happened to fail loudly in `reconstruct` — but only after the whole locale had been re-billed. `ENOENT` is now the only read failure that means "absent". Any other errno, and any parse failure, marks that locale unusable for that file **before any translation is requested**: the run prints `Sync failed for locale "es" on "locales/en.json": target file locales/es.json is on disk but could not be read (<reason>) — it holds the only copy of this locale's translations, so it was left as it stands rather than rebuilt from the source. Fix it, then run `deepl sync` again.`, reports `✗ es: 0/2 keys`, exits **12**, bills **0** characters, and leaves the file byte-identical. A key the source has just gained is recorded `failed` rather than `translated`, so the next run retries it once the file is fixed. `deepl sync pull` had the same conflation with a carve-out for one cause (a key collision, added earlier in this release) and now routes every unreadable target to the same outcome: measured on a target file holding git conflict markers, pull printed `Pulled 1 translations` at exit 0 having replaced it with `{"greeting": "TMS-Hola"}`, discarding the local-only key the export does not carry; it now leaves the file byte-identical and records a new `unusable_target` skip reason. `deepl sync push` needed no change — it already propagates every error but `ENOENT`, which is the distinction this fix generalizes. One reader (`readTargetFile`) now answers absent / usable / unusable for all four call sites, and costs no extra I/O: it replaces a read that was already being made.
 
 - **sync**: **`sync status` no longer says the keys of an unreadable target file "are not in the target file", nor tells you to sync again.** Both halves of that sentence are wrong for a file nobody managed to open — its contents are unknown, and `deepl sync` now refuses to rebuild it — so the advice bounced the user between a `status` that said to run `sync` and a `sync` that declined. The count is unchanged, since a file whose contents are unavailable still cannot be shown to hold what the lock file claims; only the reporting is: such a file gets its own sentence naming it and the reason (`2 keys are recorded as translated in the lock file for a target file that could not be read — es: locales/es.json (JSON: 'menu.save' is the key of two different strings. …). Fix the file: \`deepl sync\` will not overwrite it.`), and a project with both kinds of gap gets both sentences rather than one that conflates them. `--format json` carries the reason as a new `unusable` field on the locale's `unwrittenByLocale` entry, absent when the file was read and genuinely lacks the keys. The `--frozen` drift line no longer asserts a cause it has not checked either, and points at `sync status` for the detail.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 51df5c8d..ac2fd671 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -436,7 +436,7 @@ Optional integration with a translation management system (TMS) for collaborativ
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `enabled` | `boolean` | Yes | -- | Enable TMS integration |
-| `server` | `string` | Yes | -- | TMS server URL (HTTPS required except for `localhost`/`127.0.0.1`). When the credential comes from the environment, the hostname must also be approved -- see [TMS destination trust](#tms-destination-trust) |
+| `server` | `string` | Yes | -- | TMS server URL. HTTPS required, waived only for `http://localhost` and `http://127.0.0.1` -- write a local TMS as `http://localhost`, which reaches it whether it is bound to `127.0.0.1`, to `::1` or to every interface; `http://[::1]` and other loopback spellings are refused. When the credential comes from the environment, the hostname must also be approved -- see [TMS destination trust](#tms-destination-trust) |
 | `project_id` | `string` | Yes | -- | TMS project identifier |
 | `api_key` | `string` | No | -- | API key for TMS authentication (prefer `TMS_API_KEY` env var) |
 | `token` | `string` | No | -- | Bearer token for TMS authentication (prefer `TMS_TOKEN` env var) |
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index 43f6a944..0fc03f84 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -267,10 +267,22 @@ export class TmsClient {
       );
     }
 
+    // Deliberately the same two spellings the API base URL waives
+    // (utils/validate-url.ts), and deliberately not widened to the rest of
+    // 127.0.0.0/8 or to [::1]: `http://localhost` reaches a server bound to
+    // ::1, to 0.0.0.0 or to 127.0.0.1 alike, so naming it in the refusal covers
+    // every local TMS without making this rule more permissive than that one.
+    // The URL parser normalizes 0x7f.0.0.1, 127.1 and 2130706433 to 127.0.0.1,
+    // so those spellings are already waived here.
     const isLocalhost =
       parsedUrl.hostname === 'localhost' || parsedUrl.hostname === '127.0.0.1';
     if (parsedUrl.protocol !== 'https:' && !isLocalhost) {
-      throw new ConfigError('TMS server URL must use HTTPS');
+      throw new ConfigError(
+        `TMS server URL must use HTTPS: ${sanitizeUrl(this.options.serverUrl)}`,
+        'Plain http:// is waived only for http://localhost and http://127.0.0.1. ' +
+          'Reach a local TMS as http://localhost — that resolves to this machine ' +
+          'whether the server is bound to 127.0.0.1, to ::1 or to every interface.'
+      );
     }
     if (parsedUrl.search || parsedUrl.hash) {
       throw new ConfigError(
diff --git a/tests/unit/sync/tms-client.test.ts b/tests/unit/sync/tms-client.test.ts
index 17b77dc3..8e83a645 100644
--- a/tests/unit/sync/tms-client.test.ts
+++ b/tests/unit/sync/tms-client.test.ts
@@ -161,6 +161,65 @@ describe('TmsClient HTTPS validation', () => {
     mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
     await expect(client.pushKey('k', 'de', 'v')).resolves.toBeUndefined();
   });
+
+  // Only those two spellings are waived, so a local TMS named any other way is
+  // refused correctly but has to be told how to proceed. `http://localhost`
+  // reaches a server bound to ::1 or to 0.0.0.0 as well as one bound to
+  // 127.0.0.1, which is why it is the whole of the remedy.
+  it('names the accepted spellings when refusing another loopback address', async () => {
+    const client = new TmsClient({
+      serverUrl: 'http://[::1]:3000',
+      projectId: 'proj-1',
+      apiKey: 'key',
+    });
+
+    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(ConfigError);
+    const err = await client.pushKey('k', 'de', 'v').catch((e: unknown) => e);
+    expect((err as ConfigError).message).toContain(
+      'TMS server URL must use HTTPS'
+    );
+    expect((err as ConfigError).message).toContain('http://[::1]:3000');
+    expect((err as ConfigError).suggestion).toContain('http://localhost');
+    expect((err as ConfigError).suggestion).toContain('127.0.0.1');
+  });
+
+  it('says the same for a host that is not loopback at all', async () => {
+    const client = new TmsClient({
+      serverUrl: 'http://tms.internal:3000',
+      projectId: 'proj-1',
+      apiKey: 'key',
+    });
+
+    const err = await client.pushKey('k', 'de', 'v').catch((e: unknown) => e);
+    expect((err as ConfigError).message).toContain('http://tms.internal:3000');
+    expect((err as ConfigError).suggestion).toContain('http://localhost');
+  });
+
+  // Over-rejection guard: the waiver is not widened by the message change. The
+  // URL parser normalizes these three to 127.0.0.1, so they were always accepted.
+  it.each([
+    'http://0x7f.0.0.1:3000',
+    'http://127.1:3000',
+    'http://2130706433:3000',
+  ])('still accepts %s, which normalizes to 127.0.0.1', async (serverUrl) => {
+    const client = new TmsClient({
+      serverUrl,
+      projectId: 'proj-1',
+      apiKey: 'key',
+    });
+    mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
+    await expect(client.pushKey('k', 'de', 'v')).resolves.toBeUndefined();
+  });
+
+  it('still refuses http://0.0.0.0, which is not a loopback address', async () => {
+    const client = new TmsClient({
+      serverUrl: 'http://0.0.0.0:3000',
+      projectId: 'proj-1',
+      apiKey: 'key',
+    });
+
+    await expect(client.pushKey('k', 'de', 'v')).rejects.toThrow(ConfigError);
+  });
 });
 
 describe('TmsClient URL construction', () => {

From a30c573624e9d0b76319a32cbf2b546b045eedb4 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 22:36:16 +0200
Subject: [PATCH 171/256] fix(sync): report an unreachable TMS as a network
 failure, not an unclassified one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`fetch` rejects with a bare `TypeError: fetch failed` and puts the errno on
`cause`, and the request loop threw that rejection as it stood. So a TMS that was
simply not running ended the run at `Error: fetch failed` — no host, no port, no
code, no remediation — and at exit 1, which docs/API.md tells CI to read as "the
CLI crashed, investigate", rather than at the retriable code it documents for
exactly this.

Measured with the built CLI on three shapes: a refused connection to a released
port and an unresolvable hostname both exited 1, while a server that accepted and
never answered exited 5 with the method, the URL and a suggestion. Same condition,
differently timed, reported two ways. All three now read `TMS request failed: PUT
https://…/api/projects/p/keys/greeting: ECONNREFUSED` at exit 5.

No code allowlist is involved: everything the request loop catches is a transport
failure by construction, since fetchOnce only awaits the fetch implementation and
every response-level outcome — status, body, shape — is judged after it returns.
An error that is already a NetworkError keeps its own message, so the timeout
keeps its `timeout_ms` remediation.

THE REPLAY POLICY IS UNCHANGED. Retry eligibility is decided before the error is
classified, and both counts are asserted: a refusal is still retried to
tms.retry.max_attempts (3 calls), an unresolvable name still fails on the first
(1 call). A push is billable at the far end, so this is not the place to start
replaying one.

Note for anyone re-measuring: `http://127.0.0.1:1` is not a repro. fetch refuses
port 1 as a blocked port, with `cause.message: "bad port"` and no code, before any
connection is attempted — which is also why the fallback chain ends at the cause's
message rather than assuming an errno is present.

Refs cli-8kr2.64
---
 CHANGELOG.md                       |   4 +
 docs/API.md                        |   2 +
 docs/SYNC.md                       |   2 +
 src/sync/tms-client.ts             |  46 ++++++++-
 tests/unit/sync/tms-client.test.ts | 147 +++++++++++++++++++++++++++++
 5 files changed, 200 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c5143195..d00e526b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,6 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **watch**: **a `deepl watch` session now exits 12 rather than 0 when it recorded a failure.** Ctrl+C used to end every session at exit 0 with failed translations and failed auto-commits only logged, so a script wrapping `deepl watch` could not tell a clean run from one that lost work. A session that recorded any translation error or any `--auto-commit` failure now exits **12** (`PartialFailure`), and the auto-commit failure count is printed beside the translation total. A session with no failures still exits 0. See Fixed.
 
+- **sync**: **`deepl sync push` / `pull` exit 5 where they exited 1 when the TMS could not be reached.** A pipeline branching on exit 1 as "the CLI crashed" stops seeing an unreachable TMS there and starts seeing it under the documented retriable code, alongside the timeout it already handled. Request counts are unchanged. See Fixed.
+
 - **sync**: **`deepl sync` exits 12 where it exited 0 on a locale whose target file it cannot read**, and writes nothing for it rather than rebuilding the file from the source. Automation that treated exit 0 as "the locale is up to date" will start failing on a project whose target file is unparseable or unreadable — which is the point: the alternative was re-billing the locale and overwriting the only copy of its translations. `deepl sync pull` reports the same condition as a new `unusable_target` skip reason in its `(N skipped: …)` summary and in `--format json`, at its existing exit code, matching how a colliding target file is already handled. See Fixed.
 
 - **sync**: **`deepl sync` exits 12 where it exited 0 on a key it could not write into the target file.** Any automation treating that command's exit 0 as "the locale is up to date" will start failing on a project it was already shipping incomplete — which is the point: the alternative was a lockfile entry claiming a translation the file does not contain. `sync --frozen` exits 10 and `sync status` counts the key against the locale for the same reason. See Fixed.
@@ -137,6 +139,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a TMS that cannot be reached is a network failure (exit 5), not an unclassified one (exit 1).** `fetch` rejects with a bare `TypeError: fetch failed` and puts the errno on `cause`, and the request loop threw that rejection as it stood, so the run ended at `Error: fetch failed` — no host, no port, no code, no remediation — and at the exit code `docs/API.md` tells CI to read as "the CLI crashed, investigate". Measured with the built CLI on three shapes: a refused connection to a port with nothing listening and an unresolvable hostname both exited **1**, while a server that accepted the connection and never answered exited **5** with `TMS request timed out after 1500ms: PUT http://127.0.0.1:60423/…` and a suggestion — the same condition, differently timed, reported two different ways. All three now exit 5 and name the request: `TMS request failed: PUT https://tms.example.com/api/projects/p/keys/greeting: ECONNREFUSED`, plus a line pointing at the `server:` URL in the `tms:` block. Everything the request loop catches is a transport failure by construction — the fetch call is all it awaits, and every response-level outcome is judged after it returns — so the classification needs no code allowlist; an error that is already a `NetworkError` keeps its own message, and a 401, a 500 and a timeout each keep theirs, with a guard apiece. **The replay policy is deliberately unchanged**: retry eligibility is decided before the error is classified, and both counts are asserted — a refusal is still retried to `tms.retry.max_attempts` (3 calls), an unresolvable name still fails on the first (1 call). While measuring this, note that `http://127.0.0.1:1` is not a usable repro: `fetch` refuses port 1 as a blocked port with `cause.message: "bad port"` and no code, before any connection is attempted.
+
 - **sync**: **`TMS server URL must use HTTPS` now says which spellings are waived and how to reach a local TMS.** Plain `http://` is accepted for `http://localhost` and `http://127.0.0.1` only — the same pair the DeepL API base URL waives — so a developer whose `.deepl-sync.yaml` named `http://[::1]:3000` got a one-line refusal at exit 7 with no way to act on it. The rule is unchanged; the error now echoes the URL and points at `http://localhost`, which was measured to reach a server bound to `::1` only (HTTP 200 through the CLI, the `::1`-bound server logging the `PUT`) as well as one bound to `0.0.0.0` or `127.0.0.1`, so it covers every local bind rather than being a partial answer. The waiver was deliberately **not** widened: it would make this rule more permissive than the one for `--api-url`, `0.0.0.0` is not a loopback address, and `127.0.0.2` is not bindable at all without aliasing the loopback interface (`EADDRNOTAVAIL` on macOS). `http://0x7f.0.0.1`, `http://127.1` and `http://2130706433` were already accepted, contrary to the finding: the URL parser normalizes all three to `127.0.0.1`, which four new tests pin so the change cannot widen the gate. The destination-trust gate still does not exempt loopback at all, and answers a different question.
 
 - **sync**: **a target file that cannot be read is left alone instead of being re-translated and overwritten.** The pre-read of each locale's target file swallowed every failure into "this locale has no existing translations", which cannot tell a locale that has never been synced — nothing to lose — from one whose file is on disk and unreadable, which holds the only copy of its translations, since the lock file records hashes rather than translated text. Measured end to end against a mock endpoint, on a healthy two-key JSON project whose `locales/es.json` was then given a flat `"menu.save"` beside a nested `"menu": {"save": …}`, the `.`-separator collision a bad merge produces and the JSON parser refuses: `deepl sync --yes` printed `✓ es: 2/2 keys` and `Sync complete: 2 current` at **exit 0**, made 1 billable translate request where a healthy repeat run makes 0, and rewrote the file as `{"greeting": "Hola", "added": "Traduceme"}` — both hand-reviewed translations replaced by fresh machine output and the file's two other keys deleted — with nothing in the output naming the file. The same happened with the source changed as well (2 requests, exit 0), so this was not an artefact of the `unwritten` repair path added earlier in this release, and the same happened to a file present but unreadable (`chmod 000`), which was rebuilt from the source template and kept its mode, so the damage was not even visible afterwards. The reach is wider than one format: of the parsers that can refuse a file, `json`, `laravel_php` and `android_xml` each have a `reconstruct` that accepts a template its own `extract` rejects and rebuilds it silently, while `po` and a JSON syntax error happened to fail loudly in `reconstruct` — but only after the whole locale had been re-billed. `ENOENT` is now the only read failure that means "absent". Any other errno, and any parse failure, marks that locale unusable for that file **before any translation is requested**: the run prints `Sync failed for locale "es" on "locales/en.json": target file locales/es.json is on disk but could not be read (<reason>) — it holds the only copy of this locale's translations, so it was left as it stands rather than rebuilt from the source. Fix it, then run `deepl sync` again.`, reports `✗ es: 0/2 keys`, exits **12**, bills **0** characters, and leaves the file byte-identical. A key the source has just gained is recorded `failed` rather than `translated`, so the next run retries it once the file is fixed. `deepl sync pull` had the same conflation with a carve-out for one cause (a key collision, added earlier in this release) and now routes every unreadable target to the same outcome: measured on a target file holding git conflict markers, pull printed `Pulled 1 translations` at exit 0 having replaced it with `{"greeting": "TMS-Hola"}`, discarding the local-only key the export does not carry; it now leaves the file byte-identical and records a new `unusable_target` skip reason. `deepl sync push` needed no change — it already propagates every error but `ENOENT`, which is the distinction this fix generalizes. One reader (`readTargetFile`) now answers absent / usable / unusable for all four call sites, and costs no extra I/O: it replaces a read that was already being made.
diff --git a/docs/API.md b/docs/API.md
index 5a477242..66d51b86 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3380,6 +3380,8 @@ A response the endpoint cuts off mid-body is exit 5 as well, even though the sta
 
 A document upload response whose `document_id` is not a document identifier is rejected here as well. That value is interpolated into the path of every follow-up request (`POST /v2/document/{id}`, `POST /v2/document/{id}/result`), so an ID containing `..` or `/` would send this client's own requests to a different route on the endpoint. Anything outside `[A-Za-z0-9_-]+` is refused before the next request is sent, the ID is quoted back in the message, and no output file is written.
 
+A TMS that cannot be reached is exit 5 too, however it fails to answer. `deepl sync push` / `pull` used to report a refused connection or an unresolvable hostname as `Error: fetch failed` at exit 1 — the unclassified code — because `fetch` rejects with a bare `TypeError` and puts the errno on `cause`. Both now name the request and the code (`TMS request failed: PUT https://tms.example.com/api/projects/p/keys/greeting: ECONNREFUSED`), matching the client-side timeout, which was already exit 5. **The replay policy is unchanged by this**: retry eligibility is decided before the error is classified, so a refusal is still retried up to `tms.retry.max_attempts` and an unresolvable name still fails on the first attempt.
+
 Remediation: check connectivity and `HTTPS_PROXY` / `HTTP_PROXY` env vars, then retry.
 
 #### 6 — InvalidInput
diff --git a/docs/SYNC.md b/docs/SYNC.md
index ac2fd671..d1792122 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -468,6 +468,8 @@ The gate does not apply to a credential inlined as `api_key` / `token` in this f
 
 Each TMS HTTP request is bounded by `tms.timeout_ms` (default 30000 ms) using an `AbortController`. If the configured timeout elapses before the server responds, the client raises a `TmsTimeoutError` rather than hanging indefinitely.
 
+A TMS that never answers at all is reported the same way: a refused connection, an unresolvable hostname or any other failure of the request itself exits **5** (`NetworkError`) with the method, the URL and the underlying code (`TMS request failed: PUT https://tms.example.com/api/projects/p/keys/greeting: ECONNREFUSED`). Which of those failures is retried is unchanged by that, and is listed below.
+
 `429 Too Many Requests` and `503 Service Unavailable` responses, along with transient network errors (`ECONNRESET`, `ETIMEDOUT`, `ECONNREFUSED`, `EAI_AGAIN`) and timeouts, are retried up to 3 attempts total with jittered exponential backoff starting at ~500 ms, doubling each attempt, and capped at ~10 s (±25% jitter). All other `4xx` responses (including `401`/`403` auth failures) are not retried. When a non-2xx response is finally surfaced to the caller, up to 1 KB of the response body is appended to the error message so operators can diagnose the failure without reproducing it under `curl`.
 
 `deepl sync push` issues per-key `PUT` requests concurrently, bounded by `tms.push_concurrency` (default 10). A 5000-key × 10-locale project at ~100 ms round-trip completes in minutes instead of hours. Pushes abort on first failure — a partial push is confusing and operators re-run after fixing the underlying cause — so the overall semantic (fail-fast, caller retries) is unchanged from the previous serial behavior.
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index 0fc03f84..15b4c5ee 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -124,6 +124,45 @@ function isAbortError(err: unknown): boolean {
   return err instanceof Error && err.name === 'AbortError';
 }
 
+/**
+ * Restate a rejection from the fetch call as a network failure that names the
+ * request.
+ *
+ * Everything the request loop catches is a transport failure by construction:
+ * `fetchOnce` only awaits the fetch implementation, and every response-level
+ * outcome — a status, a body, a shape — is judged after it returns. `fetch`
+ * rejects with `TypeError: fetch failed` and puts the errno on `cause`, so the
+ * raw rejection names neither the host nor the code, and exits as an
+ * unclassified failure rather than as the retriable network error it is. An
+ * error that is already a NetworkError (the client-side timeout) keeps its own
+ * message.
+ */
+function asTransportFailure(
+  err: unknown,
+  method: string,
+  url: string
+): unknown {
+  if (err instanceof NetworkError || !(err instanceof Error)) return err;
+  const cause = (err as { cause?: unknown }).cause;
+  const causeCode =
+    cause && typeof cause === 'object'
+      ? (cause as { code?: unknown }).code
+      : undefined;
+  const causeMessage =
+    cause instanceof Error && cause.message ? cause.message : undefined;
+  const detail =
+    (typeof (err as NodeJS.ErrnoException).code === 'string'
+      ? (err as NodeJS.ErrnoException).code
+      : undefined) ??
+    (typeof causeCode === 'string' ? causeCode : undefined) ??
+    causeMessage ??
+    err.message;
+  return new NetworkError(
+    `TMS request failed: ${method} ${sanitizeUrl(url)}: ${detail}`,
+    'Check that the TMS server is running and reachable at the server: URL in the tms: block of .deepl-sync.yaml.'
+  );
+}
+
 function computeBackoffDelay(
   attempt: number,
   baseDelayMs: number,
@@ -312,7 +351,12 @@ export class TmsClient {
         lastError = err;
         const retriable =
           err instanceof TmsTimeoutError || isRetriableNetworkError(err);
-        if (!retriable || attempt === this.retry.maxAttempts - 1) throw err;
+        // Retry eligibility is decided first and independently of how the error
+        // is classified, so naming the failure cannot change how often a
+        // billable push is replayed.
+        if (!retriable || attempt === this.retry.maxAttempts - 1) {
+          throw asTransportFailure(err, method, url);
+        }
         const delay = computeBackoffDelay(
           attempt,
           this.retry.baseDelayMs,
diff --git a/tests/unit/sync/tms-client.test.ts b/tests/unit/sync/tms-client.test.ts
index 8e83a645..38b33682 100644
--- a/tests/unit/sync/tms-client.test.ts
+++ b/tests/unit/sync/tms-client.test.ts
@@ -546,6 +546,153 @@ describe('TmsClient retry', () => {
   });
 });
 
+/**
+ * A TMS that cannot be reached is a network failure whichever way it fails.
+ * `fetch` rejects with `TypeError: fetch failed` and puts the errno on `cause`,
+ * so the raw rejection carried neither the host, the port nor the code: the run
+ * ended at `Error: fetch failed` and the unclassified exit code, while the
+ * client-side timeout — the same condition, differently timed — exited 5 with a
+ * full message.
+ */
+describe('TmsClient transport failures', () => {
+  beforeEach(() => mockFetch.mockReset());
+
+  function transportError(causeCode?: string, causeMessage?: string): Error {
+    const err = new TypeError('fetch failed');
+    (err as { cause?: unknown }).cause = Object.assign(
+      new Error(causeMessage ?? 'connect failed'),
+      causeCode ? { code: causeCode } : {}
+    );
+    return err;
+  }
+
+  function clientWith(stubFetch: jest.Mock, maxAttempts = 1): TmsClient {
+    return new TmsClient({
+      serverUrl: 'https://tms.example.com',
+      projectId: 'p',
+      apiKey: 'k',
+      fetch: stubFetch,
+      retry: { maxAttempts, baseDelayMs: 1, maxDelayMs: 2, jitter: false },
+    });
+  }
+
+  it('classifies a refused connection as a network error naming the request', async () => {
+    const stubFetch = jest
+      .fn()
+      .mockRejectedValue(
+        transportError('ECONNREFUSED', 'connect ECONNREFUSED 127.0.0.1:60550')
+      );
+
+    const err = await clientWith(stubFetch)
+      .pushKey('k', 'de', 'v')
+      .catch((e: unknown) => e);
+
+    expect(exitCodeForError(err)).toBe(ExitCode.NetworkError);
+    expect((err as Error).message).toContain('PUT');
+    expect((err as Error).message).toContain('https://tms.example.com');
+    expect((err as Error).message).toContain('ECONNREFUSED');
+  });
+
+  it('classifies a name that does not resolve the same way', async () => {
+    const stubFetch = jest
+      .fn()
+      .mockRejectedValue(
+        transportError('ENOTFOUND', 'getaddrinfo ENOTFOUND tms.example.com')
+      );
+
+    const err = await clientWith(stubFetch)
+      .pullKeys('de')
+      .catch((e: unknown) => e);
+
+    expect(exitCodeForError(err)).toBe(ExitCode.NetworkError);
+    expect((err as Error).message).toContain('ENOTFOUND');
+  });
+
+  it('falls back to the underlying message when there is no errno', async () => {
+    // `fetch` refuses a blocked port before connecting, with no code at all.
+    const stubFetch = jest
+      .fn()
+      .mockRejectedValue(transportError(undefined, 'bad port'));
+
+    const err = await clientWith(stubFetch)
+      .pushKey('k', 'de', 'v')
+      .catch((e: unknown) => e);
+
+    expect(exitCodeForError(err)).toBe(ExitCode.NetworkError);
+    expect((err as Error).message).toContain('bad port');
+  });
+
+  // The replay policy is unchanged: classification and retry eligibility are
+  // separate decisions, and a push is billable at the far end.
+  it('retries a refused connection exactly as before and no more', async () => {
+    const stubFetch = jest
+      .fn()
+      .mockRejectedValue(transportError('ECONNREFUSED'));
+
+    await expect(
+      clientWith(stubFetch, 3).pushKey('k', 'de', 'v')
+    ).rejects.toThrow();
+
+    expect(stubFetch).toHaveBeenCalledTimes(3);
+  });
+
+  it('still does not retry a name that does not resolve', async () => {
+    const stubFetch = jest.fn().mockRejectedValue(transportError('ENOTFOUND'));
+
+    await expect(
+      clientWith(stubFetch, 3).pushKey('k', 'de', 'v')
+    ).rejects.toThrow();
+
+    expect(stubFetch).toHaveBeenCalledTimes(1);
+  });
+
+  // Over-rejection guards: nothing that is not a transport failure is relabelled.
+  it('leaves a 401 as a ConfigError', async () => {
+    const stubFetch = jest.fn().mockResolvedValue({
+      ok: false,
+      status: 401,
+      statusText: 'Unauthorized',
+      text: async () => '',
+    });
+
+    const err = await clientWith(stubFetch)
+      .pushKey('k', 'de', 'v')
+      .catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(ConfigError);
+    expect(exitCodeForError(err)).not.toBe(ExitCode.NetworkError);
+  });
+
+  it('leaves a 500 naming the status', async () => {
+    const stubFetch = jest.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+      statusText: 'Internal Server Error',
+      text: async () => '',
+    });
+
+    const err = await clientWith(stubFetch)
+      .pushKey('k', 'de', 'v')
+      .catch((e: unknown) => e);
+
+    expect((err as Error).message).toContain('TMS API error: 500');
+  });
+
+  it('keeps the timeout message and its remediation', async () => {
+    const abort = Object.assign(new Error('The operation was aborted'), {
+      name: 'AbortError',
+    });
+    const stubFetch = jest.fn().mockRejectedValue(abort);
+
+    const err = await clientWith(stubFetch)
+      .pushKey('k', 'de', 'v')
+      .catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(TmsTimeoutError);
+    expect((err as Error).message).toContain('timed out after');
+  });
+});
+
 describe('TmsClient error body', () => {
   beforeEach(() => mockFetch.mockReset());
 

From e03938975f2447f2d55013fd5ba2e09562ba1796 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 23:09:32 +0200
Subject: [PATCH 172/256] test(e2e): parse machine-readable output from a
 stream that carries only it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three e2e tests JSON.parsed a stream that also carries diagnostics, so any line
the Node runtime writes to stderr broke them. Reported from an environment where
`node:sqlite` is still flagged experimental: all three failed with
`SyntaxError: Unexpected token '(', "(node:7016"... is not valid JSON`.

Reproduced by putting a `node` shim on PATH that emits the same
ExperimentalWarning — NODE_OPTIONS could not be used, because the glob-bomb suite
overrides it with --max-old-space-size. With the shim the three named suites fail
exactly as reported; with it removed they pass. Both directions are now verified
against the fix.

cli-hooks and cli-sync merged stderr into stdout with `2>&1` and parsed the lot.
Their `run()` / `runSyncAll()` helpers stay as they are — several tests rely on
seeing warnings — and the two JSON assertions move to new `runJson` /
`runSyncJson` helpers that read stdout alone. That is the product's actual
contract: JSON on stdout, diagnostics on stderr.

cli-sync-glob-bomb cannot do the same, because the JSON error envelope is written
to stderr by design (sync-options.ts). It now takes the envelope line out of
stderr instead of assuming the stream holds nothing else. `sanitizeMessage` strips
control characters from the message, newline included, so the envelope is always
one line.

Not a product defect on the stdout paths: the CLI's own streams were correct
throughout. The stderr envelope sharing a stream with warnings is a real exposure
for a consumer piping stderr into a parser, and is filed as cli-6lqs rather than
changed here.

Two sibling suites turned up in a grep for `2>&1` plus `JSON.parse`
(cli-sync-tms, cli-structured-file) and are NOT affected: both parse a written
file, not CLI output. Measured under the shim, 21/21 green.
---
 tests/e2e/cli-hooks.e2e.test.ts          | 26 ++++++++++++++++++++++-
 tests/e2e/cli-sync-glob-bomb.e2e.test.ts | 27 ++++++++++++++++++++----
 tests/e2e/cli-sync.e2e.test.ts           | 24 +++++++++++++++++++--
 3 files changed, 70 insertions(+), 7 deletions(-)

diff --git a/tests/e2e/cli-hooks.e2e.test.ts b/tests/e2e/cli-hooks.e2e.test.ts
index 56d8a255..018bbf3c 100644
--- a/tests/e2e/cli-hooks.e2e.test.ts
+++ b/tests/e2e/cli-hooks.e2e.test.ts
@@ -15,6 +15,28 @@ describe('Hooks Command E2E', () => {
   const testConfig = createTestConfigDir('e2e-hooks');
   let tmpDir: string;
 
+  /**
+   * Machine-readable output only, taken from stdout alone.
+   *
+   * `run()` merges stderr into stdout so its callers can assert on warnings, but
+   * a JSON parse cannot survive anything else written to that stream: one
+   * `ExperimentalWarning` from the Node runtime is enough to turn the output into
+   * `(node:1234) ...{...}` and fail at the first token.
+   */
+  function runJson<T>(args: string): T {
+    const stdout = execSync(`node ${CLI_PATH} ${args}`, {
+      encoding: 'utf-8',
+      cwd: tmpDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: {
+        ...process.env,
+        DEEPL_CONFIG_DIR: testConfig.path,
+        NO_COLOR: '1',
+      },
+    });
+    return JSON.parse(stdout) as T;
+  }
+
   function run(args: string): string {
     return execSync(`node ${CLI_PATH} ${args} 2>&1`, {
       encoding: 'utf-8',
@@ -123,7 +145,9 @@ describe('Hooks Command E2E', () => {
     });
 
     it('should report the state rather than a bare boolean in JSON', () => {
-      const parsed = JSON.parse(run('hooks list --format json'));
+      const parsed = runJson<Record<string, string>>(
+        'hooks list --format json'
+      );
 
       expect(parsed['pre-commit']).toBe('modified');
       expect(parsed['pre-push']).toBe('not-installed');
diff --git a/tests/e2e/cli-sync-glob-bomb.e2e.test.ts b/tests/e2e/cli-sync-glob-bomb.e2e.test.ts
index 10fee648..ff6d60a3 100644
--- a/tests/e2e/cli-sync-glob-bomb.e2e.test.ts
+++ b/tests/e2e/cli-sync-glob-bomb.e2e.test.ts
@@ -31,6 +31,28 @@ describe('CLI sync glob bomb containment', () => {
     stderr: string;
   }
 
+  /**
+   * The JSON error envelope goes to stderr, which is also where the CLI's own
+   * warnings and the Node runtime's go — an `ExperimentalWarning` ahead of it is
+   * enough to fail a parse of the whole stream. Take the envelope line instead of
+   * assuming stderr holds nothing else. `sanitizeMessage` strips control
+   * characters from the message, newline included, so the envelope is always one
+   * line.
+   */
+  function parseErrorEnvelope(stderr: string): {
+    ok: boolean;
+    error: { message: string };
+  } {
+    const line = stderr
+      .split('\n')
+      .filter((l) => l.trimStart().startsWith('{'))
+      .pop();
+    if (!line) {
+      throw new Error(`no JSON envelope on stderr, got: ${stderr}`);
+    }
+    return JSON.parse(line) as { ok: boolean; error: { message: string } };
+  }
+
   function runCli(args: string[]): Run {
     const result: SpawnSyncReturns<string> = spawnSync(
       'node',
@@ -138,10 +160,7 @@ describe('CLI sync glob bomb containment', () => {
 
     expect(result.signal).toBeNull();
     expect(result.status).toBe(CONFIG_EXIT_CODE);
-    const envelope = JSON.parse(result.stderr) as {
-      ok: boolean;
-      error: { message: string };
-    };
+    const envelope = parseErrorEnvelope(result.stderr);
     expect(envelope.ok).toBe(false);
     expect(envelope.error.message).toMatch(/expands to more than/i);
   });
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 2789ea10..6dc9316a 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -152,6 +152,26 @@ describe('CLI Sync E2E', () => {
     });
   }
 
+  /**
+   * Machine-readable output only, taken from stdout alone.
+   *
+   * `runSyncAll` merges stderr so its callers can assert on warnings, but a JSON
+   * parse cannot survive anything else written to that stream: one
+   * `ExperimentalWarning` from the Node runtime is enough to turn the output into
+   * `(node:1234) ...{...}` and fail at the first token.
+   */
+  function runSyncJson<T>(args: string = ''): T {
+    const stdout = execSync(`node ${CLI_PATH} sync ${args}`, {
+      encoding: 'utf-8',
+      shell: '/bin/sh',
+      cwd: testFiles.path,
+      env: buildEnv(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 15000,
+    });
+    return JSON.parse(stdout) as T;
+  }
+
   function runSyncExpectError(args: string = ''): {
     status: number;
     output: string;
@@ -582,10 +602,10 @@ describe('CLI Sync E2E', () => {
       it('carries the count in --format json', () => {
         damageTarget();
 
-        const parsed = JSON.parse(runSyncAll('status --format json')) as {
+        const parsed = runSyncJson<{
           locales: { locale: string; unwritten: number; complete: number }[];
           unwrittenByLocale: { locale: string; file: string; keys: string[] }[];
-        };
+        }>('status --format json');
 
         expect(parsed.locales[0]?.unwritten).toBe(1);
         expect(parsed.unwrittenByLocale).toEqual([

From 3308c5aa6978b7754eabbfb1f556f68a9523f03e Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 23:34:14 +0200
Subject: [PATCH 173/256] fix(sync): arbitrate a whole translation when one
 side has no timestamp

`sync resolve` merged a conflicting translation field by field whenever one
side was missing `translated_at`, producing an entry that existed on neither
branch. Measured over a real `git merge` of real serializer output:

  ours    hash=human_hash    review_status=human_reviewed      (no translated_at)
  theirs  hash=machine_hash  review_status=machine_translated  translated_at=2026-08-03
  merged  hash=human_hash    review_status=human_reviewed      translated_at=2026-08-03

Reported as three per-field decisions, exit 0. That is the fabrication the
one-line lockfile format exists to prevent, performed by the resolver after
git had correctly raised the conflict.

The predicate was the cause. It recognised a translation by `translated_at`
and, failing that, by `source_hash` -- which belongs to the entry AROUND a
translation, not to the translation. A translation whose only remaining
identifying field was `hash` was therefore not recognised, and the pair fell
through to the generic member-by-member merge. Nothing validates the field on
read (repairEntryShape accepts any object as a translation), so the shape
survives a lockfile round trip untouched, and `human_reviewed` is only ever
set by hand -- a hand-edited entry is the reachable path.

A translation leaf is now identified by `hash` as well, and ONE SIDE BEING
ONE IS ENOUGH: the pair is arbitrated whole whenever either side looks like a
translation, so no field combination can be invented however degraded the
other side is. The container check runs first, so an entry carrying a
`translations` map is still merged one locale at a time.

Two decision reasons also stated things that were not true. Equal timestamps
reported `kept ours: newer translated_at <stamp>` when neither side was
newer; and a pair where OURS had a timestamp and theirs did not fell to the
terminal branch and reported `kept ours: neither side had translated_at`.
All four cases -- both dated, equal, one dated, neither -- are now explicit
and named accurately. A `translated_at` that is not a string counts as absent
rather than being compared against an ISO timestamp.

The bead's own premises did not survive measurement: it said the tie-break
never fires because isTranslationEntry matches on `source_hash`, and that git
conflicts the lockfile at leaf-field level. Both were true before af1818e put
each translation on one line; at HEAD the tie-break fires in both directions
over a real git merge. What is left of the finding is the undated shape above.

Refs cli-8kr2.65
---
 CHANGELOG.md                         |   2 +
 docs/SYNC.md                         |  11 +++
 src/sync/sync-resolve.ts             |  60 ++++++++++----
 tests/unit/sync/sync-resolve.test.ts | 117 +++++++++++++++++++++++++++
 4 files changed, 176 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d00e526b..f6cda5c7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -139,6 +139,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`sync resolve` no longer merges a translation field by field when one side is missing `translated_at`, which produced an entry that existed on neither branch.** Measured over a real `git merge` of real serializer output: ours held `{"hash": "human_hash", "review_status": "human_reviewed", "status": "translated"}` and theirs `{"hash": "machine_hash", "review_status": "machine_translated", "translated_at": "2026-08-03T15:00:00.000Z"}`; the resolver wrote `{"hash": "human_hash", "review_status": "human_reviewed", "status": "translated", "translated_at": "2026-08-03T15:00:00.000Z"}` — ours' hash and review status carrying theirs' timestamp — reported as three per-field decisions and exit 0. That is precisely the fabrication the one-line lockfile format exists to prevent, performed by the resolver after git had correctly raised the conflict. The cause was the translation predicate: it recognised a leaf by `translated_at`, or failing that by `source_hash`, which belongs to the *entry* around a translation and not to the translation itself, so a translation whose only remaining identifying field was `hash` was not recognised and fell through to the generic member-by-member merge. Nothing validates `translated_at` on read — the shape survives a lockfile round trip untouched — and `human_reviewed` is only ever set by hand, so a hand-edited entry is the reachable path. A translation leaf is now identified by `hash` as well, and **one side being one is enough**: a pair is arbitrated whole whenever either side looks like a translation, so no field combination can be invented regardless of how degraded the other side is. **Two decision reasons also stated things that were not true.** Equal timestamps reported `kept ours: newer translated_at 2026-08-04T10:00:00.000Z` when neither side was newer — now `kept ours: same translated_at <stamp> on both sides`. And a pair where *ours* had a timestamp and theirs did not fell to the terminal branch and reported `kept ours: neither side had translated_at` — now `kept ours: theirs had no translated_at`, with the mirrored case worded to match. A `translated_at` that is not a string now counts as absent rather than being compared against an ISO timestamp, so a lockfile committed by another tool cannot steer the tie-break with a non-comparable value.
+
 - **sync**: **a TMS that cannot be reached is a network failure (exit 5), not an unclassified one (exit 1).** `fetch` rejects with a bare `TypeError: fetch failed` and puts the errno on `cause`, and the request loop threw that rejection as it stood, so the run ended at `Error: fetch failed` — no host, no port, no code, no remediation — and at the exit code `docs/API.md` tells CI to read as "the CLI crashed, investigate". Measured with the built CLI on three shapes: a refused connection to a port with nothing listening and an unresolvable hostname both exited **1**, while a server that accepted the connection and never answered exited **5** with `TMS request timed out after 1500ms: PUT http://127.0.0.1:60423/…` and a suggestion — the same condition, differently timed, reported two different ways. All three now exit 5 and name the request: `TMS request failed: PUT https://tms.example.com/api/projects/p/keys/greeting: ECONNREFUSED`, plus a line pointing at the `server:` URL in the `tms:` block. Everything the request loop catches is a transport failure by construction — the fetch call is all it awaits, and every response-level outcome is judged after it returns — so the classification needs no code allowlist; an error that is already a `NetworkError` keeps its own message, and a 401, a 500 and a timeout each keep theirs, with a guard apiece. **The replay policy is deliberately unchanged**: retry eligibility is decided before the error is classified, and both counts are asserted — a refusal is still retried to `tms.retry.max_attempts` (3 calls), an unresolvable name still fails on the first (1 call). While measuring this, note that `http://127.0.0.1:1` is not a usable repro: `fetch` refuses port 1 as a blocked port with `cause.message: "bad port"` and no code, before any connection is attempted.
 
 - **sync**: **`TMS server URL must use HTTPS` now says which spellings are waived and how to reach a local TMS.** Plain `http://` is accepted for `http://localhost` and `http://127.0.0.1` only — the same pair the DeepL API base URL waives — so a developer whose `.deepl-sync.yaml` named `http://[::1]:3000` got a one-line refusal at exit 7 with no way to act on it. The rule is unchanged; the error now echoes the URL and points at `http://localhost`, which was measured to reach a server bound to `::1` only (HTTP 200 through the CLI, the `::1`-bound server logging the `PUT`) as well as one bound to `0.0.0.0` or `127.0.0.1`, so it covers every local bind rather than being a partial answer. The waiver was deliberately **not** widened: it would make this rule more permissive than the one for `--api-url`, `0.0.0.0` is not a loopback address, and `127.0.0.2` is not bindable at all without aliasing the loopback interface (`EADDRNOTAVAIL` on macOS). `http://0x7f.0.0.1`, `http://127.1` and `http://2130706433` were already accepted, contrary to the finding: the URL parser normalizes all three to `127.0.0.1`, which four new tests pin so the change cannot widen the gate. The destination-trust gate still does not exempt loopback at all, and answers a different question.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index d1792122..32662f44 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -874,6 +874,17 @@ WARN  locales/de/app.json:<conflict-region> — parse-error fallback used, JSON.
 Resolved 3 conflicts (1 theirs, 1 ours, 1 length-heuristic). Run "deepl sync" to fill any gaps.
 ```
 
+**The tie-break arbitrates a whole translation, never its fields.** A conflicting pair is arbitrated as one unit whenever *either* side looks like a translation, so the resolver cannot emit a translation whose fields come from both sides — the failure the one-line format described under [`.deepl-sync.lock`](#deepl-sync-lock) exists to prevent. That matters because `translated_at` is not guaranteed to be there: nothing validates it on read, and `human_reviewed` is only ever set by hand, so a hand-edited entry can be missing it. Each case is decided explicitly and named in the report:
+
+| Both sides | Kept | Reported as |
+|------------|------|-------------|
+| Different `translated_at` | The later one | `kept ours/theirs: newer translated_at <stamp>` |
+| The same `translated_at` | Ours | `kept ours: same translated_at <stamp> on both sides` |
+| Only one has `translated_at` | The side that has it | `kept ours/theirs: <other side> had no translated_at` |
+| Neither has one | Ours | `kept ours: neither side had translated_at` |
+
+A `translated_at` that is not a string counts as absent rather than being compared against an ISO timestamp.
+
 **Region terminators.** A conflict region that sits inside an object is a sequence of members, and unless it is the last one it ends with a comma joining it to the member that follows. The resolver takes that comma off before parsing the region and puts it back afterwards — without this, every region but the last failed to parse and fell to the length heuristic below, so the documented `translated_at` tie-break never ran. When the two sides *disagree* on whether the region ends a member list — one side deleted what the other modified — no terminator can be correct for both, so the region falls to the heuristic rather than risk emitting invalid JSON.
 
 **Canonical output.** Resolving rebuilds each merged region, so the resolved lockfile is written back in the canonical format described under [`.deepl-sync.lock`](#deepl-sync-lock) rather than with the resolver's own indentation. Committing a resolved lockfile therefore cannot leave translations expanded across lines for the next merge to recombine.
diff --git a/src/sync/sync-resolve.ts b/src/sync/sync-resolve.ts
index 7a953f4d..11f49825 100644
--- a/src/sync/sync-resolve.ts
+++ b/src/sync/sync-resolve.ts
@@ -213,15 +213,22 @@ function deepMergeWithDecisions(
       continue;
     }
 
-    if (isTranslationEntry(ourValue) && isTranslationEntry(theirValue)) {
-      const ourDate = (ourValue as Record<string, unknown>)['translated_at'] as
-        string | undefined;
-      const theirDate = (theirValue as Record<string, unknown>)[
-        'translated_at'
-      ] as string | undefined;
-      if (ourDate && theirDate) {
-        if (ourDate >= theirDate) {
-          merged[key] = ourValue;
+    // One side is enough: a translation is only meaningful whole, so a pair
+    // where either side is one is arbitrated whole. Merging it member by member
+    // would emit a translation that existed on neither side — one side's hash
+    // and review status carrying the other side's timestamp.
+    if (isTranslationEntry(ourValue) || isTranslationEntry(theirValue)) {
+      const ourDate = translatedAt(ourValue);
+      const theirDate = translatedAt(theirValue);
+      if (ourDate !== undefined && theirDate !== undefined) {
+        if (ourDate === theirDate) {
+          decisions.push({
+            file,
+            key: childPath,
+            source: 'ours',
+            reason: `kept ours: same translated_at ${ourDate} on both sides`,
+          });
+        } else if (ourDate > theirDate) {
           decisions.push({
             file,
             key: childPath,
@@ -237,13 +244,20 @@ function deepMergeWithDecisions(
             reason: `kept theirs: newer translated_at ${theirDate}`,
           });
         }
-      } else if (theirDate) {
+      } else if (theirDate !== undefined) {
         merged[key] = theirValue;
         decisions.push({
           file,
           key: childPath,
           source: 'theirs',
-          reason: `kept theirs: ours lacked translated_at`,
+          reason: 'kept theirs: ours had no translated_at',
+        });
+      } else if (ourDate !== undefined) {
+        decisions.push({
+          file,
+          key: childPath,
+          source: 'ours',
+          reason: 'kept ours: theirs had no translated_at',
         });
       } else {
         decisions.push({
@@ -290,12 +304,30 @@ function deepMergeWithDecisions(
 function isTranslationEntry(obj: unknown): boolean {
   if (typeof obj !== 'object' || obj === null) return false;
   const record = obj as Record<string, unknown>;
-  if ('translated_at' in record) return true;
   // An object holding a `translations` map is a container, not a leaf: its
   // timestamps belong to the locales inside it, so it has to be merged one
-  // locale at a time rather than compared at this level.
+  // locale at a time rather than compared at this level. Checked before the
+  // fields below, since a container carries some of them too.
   if ('translations' in record) return false;
-  return 'source_hash' in record;
+  // `hash` is a translation's own field; `source_hash` belongs to the entry
+  // around it and identifies one that has lost its translations map. Nothing
+  // validates `translated_at` on read, so a translation missing it still has to
+  // be recognised as one.
+  return (
+    'translated_at' in record || 'hash' in record || 'source_hash' in record
+  );
+}
+
+/**
+ * The comparable timestamp of a translation, or `undefined` when it carries
+ * nothing a comparison can order. A lock file is read from the repository, so
+ * the field is untrusted: a non-string cannot be compared against an ISO
+ * timestamp and counts as absent rather than steering the tie-break.
+ */
+function translatedAt(value: unknown): string | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const stamp = (value as Record<string, unknown>)['translated_at'];
+  return typeof stamp === 'string' && stamp !== '' ? stamp : undefined;
 }
 
 export async function resolveLockFile(
diff --git a/tests/unit/sync/sync-resolve.test.ts b/tests/unit/sync/sync-resolve.test.ts
index cc9b8eb5..2d8b836a 100644
--- a/tests/unit/sync/sync-resolve.test.ts
+++ b/tests/unit/sync/sync-resolve.test.ts
@@ -284,6 +284,15 @@ describe('resolveConflicts()', () => {
       return `{"hash": "${hash}", "review_status": "${review}", "status": "translated", "translated_at": "${stamp}"}`;
     }
 
+    /**
+     * A translation carrying no timestamp. Nothing validates the field on read,
+     * so a hand-edited lockfile — the only way `human_reviewed` is ever set —
+     * can commit this shape.
+     */
+    function undatedTranslation(hash: string, review: string): string {
+      return `{"hash": "${hash}", "review_status": "${review}", "status": "translated"}`;
+    }
+
     function surviving(resolved: string): Record<string, unknown> {
       const parsed = JSON.parse(resolved) as {
         entries: Record<
@@ -383,6 +392,114 @@ describe('resolveConflicts()', () => {
         review: winner['review_status'],
       });
     });
+
+    it('should keep one whole side when only ours carries a timestamp', () => {
+      const { resolved } = resolveConflicts(
+        conflictedLock(
+          translation('ours_hash', '2026-02-01T00:00:00.000Z'),
+          undatedTranslation('them_hash', 'human_reviewed')
+        )
+      );
+
+      const winner = surviving(resolved);
+      expect([
+        { hash: 'ours_hash', review: 'machine_translated' },
+        { hash: 'them_hash', review: 'human_reviewed' },
+      ]).toContainEqual({
+        hash: winner['hash'],
+        review: winner['review_status'],
+      });
+    });
+
+    it('should keep one whole side when only theirs carries a timestamp', () => {
+      const { resolved } = resolveConflicts(
+        conflictedLock(
+          undatedTranslation('ours_hash', 'human_reviewed'),
+          translation('them_hash', '2026-03-01T00:00:00.000Z')
+        )
+      );
+
+      const winner = surviving(resolved);
+      expect([
+        { hash: 'ours_hash', review: 'human_reviewed' },
+        { hash: 'them_hash', review: 'machine_translated' },
+      ]).toContainEqual({
+        hash: winner['hash'],
+        review: winner['review_status'],
+      });
+    });
+
+    it('should not pair an undated side field by field', () => {
+      const { decisions } = resolveConflicts(
+        conflictedLock(
+          undatedTranslation('ours_hash', 'human_reviewed'),
+          translation('them_hash', '2026-03-01T00:00:00.000Z')
+        )
+      );
+
+      expect(decisions.map((d) => d.key)).toEqual(['de']);
+    });
+
+    it('should not carry the other side timestamp onto the kept translation', () => {
+      const { resolved } = resolveConflicts(
+        conflictedLock(
+          undatedTranslation('ours_hash', 'human_reviewed'),
+          translation('them_hash', '2026-03-01T00:00:00.000Z')
+        )
+      );
+
+      const winner = surviving(resolved);
+      if (winner['hash'] === 'ours_hash') {
+        expect(winner['translated_at']).toBeUndefined();
+      } else {
+        expect(winner['translated_at']).toBe('2026-03-01T00:00:00.000Z');
+      }
+    });
+
+    it('should not claim a timestamp is newer when both sides match', () => {
+      const stamp = '2026-01-01T00:00:00.000Z';
+      const { decisions } = resolveConflicts(
+        conflictedLock(
+          translation('machine_hash', stamp, 'machine_translated'),
+          translation('human_hash', stamp, 'human_reviewed')
+        )
+      );
+
+      expect(decisions.map((d) => d.reason)).toEqual([
+        `kept ours: same translated_at ${stamp} on both sides`,
+      ]);
+    });
+
+    it('should keep ours whole when neither side carries a timestamp', () => {
+      const { resolved, decisions } = resolveConflicts(
+        conflictedLock(
+          undatedTranslation('ours_hash', 'human_reviewed'),
+          undatedTranslation('them_hash', 'machine_translated')
+        )
+      );
+
+      expect(surviving(resolved)).toEqual({
+        hash: 'ours_hash',
+        review_status: 'human_reviewed',
+        status: 'translated',
+      });
+      expect(decisions.map((d) => d.reason)).toEqual([
+        'kept ours: neither side had translated_at',
+      ]);
+    });
+
+    it('should not claim neither side had a timestamp when ours did', () => {
+      const { decisions } = resolveConflicts(
+        conflictedLock(
+          translation('ours_hash', '2026-02-01T00:00:00.000Z'),
+          undatedTranslation('them_hash', 'human_reviewed')
+        )
+      );
+
+      expect(decisions.map((d) => d.reason)).toEqual([
+        'kept ours: theirs had no translated_at',
+      ]);
+    });
   });
 
   describe('sides that disagree on the region terminator', () => {

From b2165f0a823f32c153a563c81fe087927db0ec50 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sat, 8 Aug 2026 23:37:24 +0200
Subject: [PATCH 174/256] fix(sync): stop sync resolve warning about data loss
 on every lockfile merge

The lockfile's own metadata was the one part of the file where git could
produce a conflict region that is not a whole anything. Keys are sorted, so
`stats` sits two context lines below `generated_at`, and every write changes
both -- git therefore joined them into one region, which with `stats` expanded
over five lines OPENED INSIDE `stats` AND CLOSED OUTSIDE IT:

  <<<<<<< HEAD
    "generated_at": "2026-08-02T10:00:00.000Z",
    "source_locale": "en",
    "stats": {
      "last_sync": "2026-08-02T10:00:00.000Z",
  =======

That is not a member list, so JSON.parse('{' + region + '}') failed, the
region fell to the length-heuristic fallback, and resolve printed

  WARN  .deepl-sync.lock:<conflict-region> - parse-error fallback used,
  JSON.parse failed on ""generate...

then picked a side by byte length. Measured over a real `git merge` of real
serializer output: it fired in every case where both branches had run a sync,
including the most common one of all -- two branches translating DIFFERENT
keys, where git merges the entries map perfectly and nothing is in conflict at
all -- which reported `Resolved 1 conflict (0 theirs, 0 ours, 1
length-heuristic)`. The docs tell the reader a length-heuristic decision is a
data-loss risk to inspect by hand, so the one signal that exists to make
silent data loss auditable fired spuriously on every resolve, and a warning
about a region that really did carry a translation was indistinguishable from
the routine noise.

`stats` is now serialized on one line, like a translation and for the
neighbouring reason: its counts and `last_sync` describe one sync run. The
region stays a member list and merges normally -- the same fixtures now report
`generated_at` and `stats.last_sync` as ordinary per-member decisions with no
warning. Fixing the shape rather than the message keeps the loud fallback
meaningful for a genuinely mangled region.

Nothing was being lost while the fallback picked sides, as it happens:
`total_keys` and `total_translations` are recomputed from `entries` on every
read and `generated_at` is overwritten on every write, so the block it
arbitrated carries no information -- which is precisely why warning about it
was wrong.

The fixture is built with real git through the real serializer, in a new
integration suite, because the region boundaries are git's to choose and a
hand-authored conflict file picks them by guesswork. It also pins the
translated_at tie-break over a real merge, which is the behaviour the bead
claimed never fires.

Upgrading reformats every existing lockfile on the next write; five lines
become one and no entry's content changes.

Residual, not fixed here: `glossary_ids` is still an expanded container
between `generated_at` and `stats`, so a merge that changes both it and
`generated_at` can still straddle its opening brace. It only changes when
glossary configuration does, and inlining it would make two branches adding
different locales' glossary ids resolve whole-side instead of per-locale.

Refs cli-8kr2.65
---
 CHANGELOG.md                                  |   2 +
 docs/SYNC.md                                  |   8 +
 src/sync/sync-lock.ts                         |  38 ++-
 ...sync-resolve-git-merge.integration.test.ts | 240 ++++++++++++++++++
 tests/unit/sync/sync-lock.test.ts             |  31 +++
 5 files changed, 311 insertions(+), 8 deletions(-)
 create mode 100644 tests/integration/sync-resolve-git-merge.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6cda5c7..b04ece6c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -139,6 +139,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`sync resolve` no longer warns about possible data loss on every ordinary lockfile merge.** The lockfile's own metadata was the one part of the file where git could produce a conflict region that is not a whole anything. `stats` sits two context lines below `generated_at`, and every write changes both, so git joined them into a single region — which, with `stats` expanded over five lines, opened inside `stats` and closed outside it. That is not a member list, so `JSON.parse('{' + region + '}')` failed, the region fell to the length-heuristic fallback, and the resolver emitted `WARN .deepl-sync.lock:<conflict-region> — parse-error fallback used, JSON.parse failed on ""generate…"` and picked a side by byte length. Measured over a real `git merge` of real serializer output: it fired in every case where both branches had run a sync, including the most common one of all — two branches translating **different** keys, where git merges the entries map perfectly and there is no real conflict at anything — which reported `Resolved 1 conflict (0 theirs, 0 ours, 1 length-heuristic)`. Since the docs tell the reader a `length-heuristic` decision is a data-loss risk to inspect by hand, the one signal that exists to make silent data loss auditable fired spuriously on every single resolve, and a warning about a region that really did carry a translation was indistinguishable from the routine noise. **`stats` is now written on one line**, like a translation and for the neighbouring reason — its counts and `last_sync` describe one sync run — so the region stays a member list and merges normally: the same fixtures now report `generated_at` and `stats.last_sync` as ordinary per-member decisions with no warning at all. Nothing was lost while the fallback was picking sides, as it happens: `total_keys` and `total_translations` are recomputed from `entries` on every read and `generated_at` is overwritten on every write, so the block it was arbitrating carries no information — which is exactly why warning about it was wrong. Upgrading reformats every existing lockfile on the next write; it is formatting only, five lines becoming one, and no entry's content changes.
+
 - **sync**: **`sync resolve` no longer merges a translation field by field when one side is missing `translated_at`, which produced an entry that existed on neither branch.** Measured over a real `git merge` of real serializer output: ours held `{"hash": "human_hash", "review_status": "human_reviewed", "status": "translated"}` and theirs `{"hash": "machine_hash", "review_status": "machine_translated", "translated_at": "2026-08-03T15:00:00.000Z"}`; the resolver wrote `{"hash": "human_hash", "review_status": "human_reviewed", "status": "translated", "translated_at": "2026-08-03T15:00:00.000Z"}` — ours' hash and review status carrying theirs' timestamp — reported as three per-field decisions and exit 0. That is precisely the fabrication the one-line lockfile format exists to prevent, performed by the resolver after git had correctly raised the conflict. The cause was the translation predicate: it recognised a leaf by `translated_at`, or failing that by `source_hash`, which belongs to the *entry* around a translation and not to the translation itself, so a translation whose only remaining identifying field was `hash` was not recognised and fell through to the generic member-by-member merge. Nothing validates `translated_at` on read — the shape survives a lockfile round trip untouched — and `human_reviewed` is only ever set by hand, so a hand-edited entry is the reachable path. A translation leaf is now identified by `hash` as well, and **one side being one is enough**: a pair is arbitrated whole whenever either side looks like a translation, so no field combination can be invented regardless of how degraded the other side is. **Two decision reasons also stated things that were not true.** Equal timestamps reported `kept ours: newer translated_at 2026-08-04T10:00:00.000Z` when neither side was newer — now `kept ours: same translated_at <stamp> on both sides`. And a pair where *ours* had a timestamp and theirs did not fell to the terminal branch and reported `kept ours: neither side had translated_at` — now `kept ours: theirs had no translated_at`, with the mirrored case worded to match. A `translated_at` that is not a string now counts as absent rather than being compared against an ISO timestamp, so a lockfile committed by another tool cannot steer the tie-break with a non-comparable value.
 
 - **sync**: **a TMS that cannot be reached is a network failure (exit 5), not an unclassified one (exit 1).** `fetch` rejects with a bare `TypeError: fetch failed` and puts the errno on `cause`, and the request loop threw that rejection as it stood, so the run ended at `Error: fetch failed` — no host, no port, no code, no remediation — and at the exit code `docs/API.md` tells CI to read as "the CLI crashed, investigate". Measured with the built CLI on three shapes: a refused connection to a port with nothing listening and an unresolvable hostname both exited **1**, while a server that accepted the connection and never answered exited **5** with `TMS request timed out after 1500ms: PUT http://127.0.0.1:60423/…` and a suggestion — the same condition, differently timed, reported two different ways. All three now exit 5 and name the request: `TMS request failed: PUT https://tms.example.com/api/projects/p/keys/greeting: ECONNREFUSED`, plus a line pointing at the `server:` URL in the `tms:` block. Everything the request loop catches is a transport failure by construction — the fetch call is all it awaits, and every response-level outcome is judged after it returns — so the classification needs no code allowlist; an error that is already a `NetworkError` keeps its own message, and a 401, a 500 and a timeout each keep theirs, with a guard apiece. **The replay policy is deliberately unchanged**: retry eligibility is decided before the error is classified, and both counts are asserted — a refusal is still retried to `tms.retry.max_attempts` (3 calls), an unresolvable name still fails on the first (1 call). While measuring this, note that `http://127.0.0.1:1` is not a usable repro: `fetch` refuses port 1 as a blocked port with `cause.message: "bad port"` and no code, before any connection is attempted.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 32662f44..2455740d 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -525,6 +525,14 @@ Each translation entry in the lockfile records:
 
 This is a merge-safety property, not a style choice. A translation is only meaningful whole — its hash, timestamp and review status all describe one act of translating. With one field per line, `git merge` treats those fields as independently mergeable units: a branch that changed only `review_status` and a branch that changed only `translated_at` merge **with no conflict at all** into an entry that existed on neither branch, labelling machine output `human_reviewed` while carrying a timestamp from the other branch. One line per entry makes the smallest region git can produce a whole entry, so such an overlap conflicts and reaches [`deepl sync resolve`](#deepl-sync-resolve) instead of being silently combined. Keys are sorted, so the diff for a changed translation is a single line.
 
+The `stats` block is written on one line for a neighbouring reason:
+
+```json
+"stats": {"last_sync": "2026-04-20T08:12:03Z", "total_keys": 412, "total_translations": 1236}
+```
+
+`stats` sits two lines below `generated_at`, and every write changes both, so git joins the two into a single conflict region. Expanded over five lines, that region opens inside `stats` and closes outside it — not a member list any parser can read, so `sync resolve` could not merge it and fell back to picking a side by byte length, warning about possible data loss on **every** ordinary lockfile merge. On one line the region stays a member list the resolver merges normally, and a `length-heuristic` warning again means what it says.
+
 Upgrading from an earlier release reformats every existing lockfile on the next write, which produces one large diff. It is a formatting change only — no entry's content changes.
 
 ### Multiple Buckets
diff --git a/src/sync/sync-lock.ts b/src/sync/sync-lock.ts
index e78fb1bd..6a884e75 100644
--- a/src/sync/sync-lock.ts
+++ b/src/sync/sync-lock.ts
@@ -87,6 +87,14 @@ function isTranslation(path: readonly string[]): boolean {
   );
 }
 
+/**
+ * The top-level `stats` object, matched on the path so an i18n key or source
+ * file of that name is not compacted with it.
+ */
+function isStats(path: readonly string[]): boolean {
+  return path.length === 1 && path[0] === 'stats';
+}
+
 /**
  * Own, enumerable, serializable members in key order. Enumerated as pairs rather
  * than read back by key: an i18n key named `__proto__` is a real own property,
@@ -118,7 +126,12 @@ function serializeInline(value: unknown): string {
 // one node per translation per key, and a fresh array at each would allocate
 // once for every one of them.
 function serializeNode(value: unknown, indent: string, path: string[]): string {
-  if (isTranslation(path) || value === null || typeof value !== 'object') {
+  if (
+    isTranslation(path) ||
+    isStats(path) ||
+    value === null ||
+    typeof value !== 'object'
+  ) {
     return serializeInline(value);
   }
   const childIndent = `${indent}  `;
@@ -146,13 +159,22 @@ function serializeNode(value: unknown, indent: string, path: string[]): string {
 /**
  * The canonical on-disk form of a lock file, including its trailing newline.
  *
- * Every container is expanded one key per line, but each translation is emitted
- * on a single line. A translation is only meaningful whole — its hash, timestamp
- * and review status all describe one act of translating — and one field per line
- * makes those fields independently mergeable units, so `git merge` can combine
- * one side's hash with the other's review status and produce a translation that
- * existed on neither branch, with no conflict raised. One line per translation
- * makes the smallest region git can produce a whole entry.
+ * Every container is expanded one key per line, but each translation and the
+ * `stats` object are emitted on a single line. A translation is only meaningful
+ * whole — its hash, timestamp and review status all describe one act of
+ * translating — and one field per line makes those fields independently
+ * mergeable units, so `git merge` can combine one side's hash with the other's
+ * review status and produce a translation that existed on neither branch, with
+ * no conflict raised. One line per translation makes the smallest region git can
+ * produce a whole entry.
+ *
+ * `stats` is compacted for the neighbouring reason. Its counts and `last_sync`
+ * describe one sync run, and it sits two context lines below `generated_at`,
+ * which every write also changes — so git joins the two into one conflict
+ * region. Expanded, that region opens inside `stats` and closes outside it,
+ * which is not a member list `sync resolve` can parse, and the resolver falls
+ * back to picking a side by byte length. On one line the region stays a member
+ * list the resolver can merge.
  */
 export function serializeLockFile(lockFile: SyncLockFile): string {
   return `${serializeNode(lockFile, '', [])}\n`;
diff --git a/tests/integration/sync-resolve-git-merge.integration.test.ts b/tests/integration/sync-resolve-git-merge.integration.test.ts
new file mode 100644
index 00000000..7365580b
--- /dev/null
+++ b/tests/integration/sync-resolve-git-merge.integration.test.ts
@@ -0,0 +1,240 @@
+/**
+ * `deepl sync resolve` over conflicts produced by a real `git merge`.
+ *
+ * The resolver reads whatever git left in the working tree, so the shape that
+ * reaches it is decided by the canonical serializer and by git's own region
+ * boundaries. Hand-authoring a conflicted lockfile picks those boundaries by
+ * guesswork and hides the regions git actually produces, so these fixtures are
+ * built by committing serializer output on two branches and merging them.
+ */
+
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+jest.unmock('child_process');
+
+import { serializeLockFile } from '../../src/sync/sync-lock';
+import { resolveLockFile } from '../../src/sync/sync-resolve';
+import type {
+  ResolveDecision,
+  ResolveResult,
+} from '../../src/sync/sync-resolve';
+import { LOCK_FILE_NAME } from '../../src/sync/types';
+import type { SyncLockFile, SyncLockTranslation } from '../../src/sync/types';
+
+function gitAvailable(): boolean {
+  try {
+    execFileSync('git', ['--version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function git(cwd: string, args: string[]): void {
+  execFileSync('git', args, { cwd, stdio: 'ignore' });
+}
+
+function translation(
+  hash: string,
+  stamp: string,
+  review: SyncLockTranslation['review_status'] = 'machine_translated'
+): SyncLockTranslation {
+  return {
+    hash,
+    translated_at: stamp,
+    status: 'translated',
+    review_status: review,
+    character_count: 11,
+  };
+}
+
+const BASE_STAMP = '2026-08-01T00:00:00.000Z';
+
+function lockFile(
+  stamp: string,
+  edits: Record<string, SyncLockTranslation> = {}
+): SyncLockFile {
+  const entry = (
+    hash: string,
+    text: string,
+    key: string
+  ): [string, SyncLockFile['entries'][string][string]] => [
+    key,
+    {
+      source_hash: hash,
+      source_text: text,
+      translations: {
+        de: edits[key] ?? translation(`base-${key}`, BASE_STAMP),
+      },
+    },
+  ];
+
+  return {
+    _comment: 'DeepL sync lock file',
+    version: 1,
+    generated_at: stamp,
+    source_locale: 'en',
+    entries: {
+      'locales/en.json': Object.fromEntries([
+        entry('h-cancel', 'Cancel', 'button.cancel'),
+        entry('h-delete', 'Delete', 'button.delete'),
+        entry('h-save', 'Save', 'button.save'),
+      ]),
+    },
+    stats: { total_keys: 3, total_translations: 3, last_sync: stamp },
+  };
+}
+
+interface MergedFixture {
+  lockPath: string;
+  content: string;
+}
+
+/**
+ * Commits `theirs` on a side branch and `ours` on main, then merges. Returns the
+ * conflicted lockfile git produced.
+ */
+function mergeBranches(
+  dir: string,
+  ours: SyncLockFile,
+  theirs: SyncLockFile
+): MergedFixture {
+  const lockPath = path.join(dir, LOCK_FILE_NAME);
+  git(dir, ['init', '-q', '-b', 'main']);
+  git(dir, ['config', 'user.email', 'test@example.com']);
+  git(dir, ['config', 'user.name', 'Test User']);
+  git(dir, ['config', 'commit.gpgsign', 'false']);
+
+  fs.writeFileSync(lockPath, serializeLockFile(lockFile(BASE_STAMP)), 'utf-8');
+  git(dir, ['add', '-A']);
+  git(dir, ['commit', '-qm', 'base']);
+
+  git(dir, ['checkout', '-q', '-b', 'other']);
+  fs.writeFileSync(lockPath, serializeLockFile(theirs), 'utf-8');
+  git(dir, ['commit', '-qam', 'theirs']);
+
+  git(dir, ['checkout', '-q', 'main']);
+  fs.writeFileSync(lockPath, serializeLockFile(ours), 'utf-8');
+  git(dir, ['commit', '-qam', 'ours']);
+
+  try {
+    git(dir, ['merge', 'other']);
+  } catch {
+    // A conflicting merge exits non-zero; the conflicted tree is the fixture.
+  }
+
+  return { lockPath, content: fs.readFileSync(lockPath, 'utf-8') };
+}
+
+function translationsOf(
+  lockPath: string
+): Record<string, Record<string, unknown>> {
+  const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf-8')) as SyncLockFile;
+  const entries = parsed.entries['locales/en.json']!;
+  return Object.fromEntries(
+    Object.entries(entries).map(([key, entry]) => [
+      key,
+      entry.translations['de'] as unknown as Record<string, unknown>,
+    ])
+  );
+}
+
+const describeGit = gitAvailable() ? describe : describe.skip;
+
+describeGit('sync resolve over a real git merge', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(
+      path.join(fs.realpathSync(os.tmpdir()), 'resolve-git-')
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  describe('two branches translating different keys', () => {
+    let fixture: MergedFixture;
+    let result: ResolveResult;
+
+    beforeEach(async () => {
+      fixture = mergeBranches(
+        dir,
+        lockFile('2026-08-02T10:00:00.000Z', {
+          'button.cancel': translation(
+            'ours-cancel',
+            '2026-08-02T10:00:00.000Z'
+          ),
+        }),
+        lockFile('2026-08-03T15:00:00.000Z', {
+          'button.save': translation('theirs-save', '2026-08-03T15:00:00.000Z'),
+        })
+      );
+      result = await resolveLockFile(fixture.lockPath);
+    });
+
+    it('conflicts only outside the entries map', () => {
+      const conflicted = fixture.content.split('\n');
+      const markerAt = conflicted.findIndex((line) =>
+        line.startsWith('<<<<<<<')
+      );
+      expect(markerAt).toBeGreaterThan(-1);
+      expect(conflicted.slice(0, markerAt).join('\n')).toContain('ours-cancel');
+      expect(conflicted.slice(0, markerAt).join('\n')).toContain('theirs-save');
+    });
+
+    it('resolves without falling back to the length heuristic', () => {
+      const fallbacks = (result.decisions ?? []).filter(
+        (d: ResolveDecision) => d.source === 'length-heuristic'
+      );
+      expect(fallbacks).toEqual([]);
+    });
+
+    it('keeps both branches translations', () => {
+      const translations = translationsOf(fixture.lockPath);
+      expect(translations['button.cancel']!['hash']).toBe('ours-cancel');
+      expect(translations['button.save']!['hash']).toBe('theirs-save');
+    });
+  });
+
+  describe('two branches translating the same key', () => {
+    let fixture: MergedFixture;
+    let result: ResolveResult;
+
+    beforeEach(async () => {
+      fixture = mergeBranches(
+        dir,
+        lockFile('2026-08-02T10:00:00.000Z', {
+          'button.delete': translation(
+            'ours-delete',
+            '2026-08-02T10:00:00.000Z'
+          ),
+        }),
+        lockFile('2026-08-03T15:00:00.000Z', {
+          'button.delete': translation(
+            'theirs-delete',
+            '2026-08-03T15:00:00.000Z'
+          ),
+        })
+      );
+      result = await resolveLockFile(fixture.lockPath);
+    });
+
+    it('applies the translated_at tie-break to the newer side', () => {
+      expect(translationsOf(fixture.lockPath)['button.delete']!['hash']).toBe(
+        'theirs-delete'
+      );
+    });
+
+    it('resolves without falling back to the length heuristic', () => {
+      const fallbacks = (result.decisions ?? []).filter(
+        (d: ResolveDecision) => d.source === 'length-heuristic'
+      );
+      expect(fallbacks).toEqual([]);
+    });
+  });
+});
diff --git a/tests/unit/sync/sync-lock.test.ts b/tests/unit/sync/sync-lock.test.ts
index 07c9a882..18f08019 100644
--- a/tests/unit/sync/sync-lock.test.ts
+++ b/tests/unit/sync/sync-lock.test.ts
@@ -141,6 +141,37 @@ describe('serializeLockFile()', () => {
     expect(line).toContain('"review_status": "machine_translated"');
   });
 
+  // `stats` sits two context lines below `generated_at`, and every write changes
+  // both, so git joins them into one conflict region. Expanded over five lines
+  // that region starts inside `stats` and ends outside it, which is not a member
+  // list any parser can read — `sync resolve` cannot merge it and falls back to
+  // picking a side by byte length. On one line the region stays a member list.
+  it('should put stats on one line', () => {
+    const lines = serializeLockFile(lockWith({ de }))
+      .split('\n')
+      .filter((line) => /^\s*"stats":/.test(line));
+
+    expect(lines).toHaveLength(1);
+    expect(lines[0]!.trimEnd().replace(/,$/, '')).toMatch(/\}$/);
+  });
+
+  it('should keep every field of stats on that one line', () => {
+    const lockFile = lockWith({ de });
+    lockFile.stats = {
+      total_keys: 7,
+      total_translations: 9,
+      last_sync: '2026-01-03T00:00:00.000Z',
+    };
+
+    const [line] = serializeLockFile(lockFile)
+      .split('\n')
+      .filter((l) => /^\s*"stats":/.test(l));
+
+    expect(line).toContain('"total_keys": 7');
+    expect(line).toContain('"total_translations": 9');
+    expect(line).toContain('"last_sync": "2026-01-03T00:00:00.000Z"');
+  });
+
   it('should still expand the containers above a translation', () => {
     const serialized = serializeLockFile(lockWith({ de }));
 

From e97d8356b2562abeaa8cc3ae19b86ade657ba4f0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 00:11:59 +0200
Subject: [PATCH 175/256] fix(watch): anchor git on the watched files, not on
 the CLI's own directory

Every git invocation behind --auto-commit and --git-staged ran with no cwd,
so both flags acted on whatever repository the terminal happened to be in.

Measured with the built CLI over two real repositories: with the terminal in
an unrelated repository, git add refused every translation as "outside
repository", one counted failure per file and exit 12 with the output left
untracked; nested inside another repository, git add silently did nothing and
the commit failed with "pathspec did not match"; with the cwd in no
repository, the session claimed "Not a git repository, skipping auto-commit"
about a watched path that was one, and exited 0 having committed nothing. No
case committed into the wrong history, because git refuses a pathspec outside
its own working tree.

--git-staged failed silently inside a single repository: git diff --cached
names its files relative to the repository root and the result was resolved
against process.cwd(), so a session started from any subdirectory reported its
staged count, watched, and then matched nothing for the rest of the run.

The commit now goes to the repository holding the output directory, which is
the only one git can put those files in, and the staged snapshot comes from
the repository holding the watched path. Output paths are resolved to absolute
before the working directory changes, so a relative --output still commits the
file it wrote.

--auto-commit with an output directory in no repository now exits 6 at
startup, where it used to bill a translation and then warn once per file,
matching how a glossary without a source language is refused at launch.

Refs cli-8kr2.66
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   6 +-
 src/cli/commands/watch.ts                     | 122 +++++++++----
 tests/e2e/cli-watch-auto-commit.e2e.test.ts   | 126 +++++++++++++-
 .../watch-auto-commit.integration.test.ts     | 161 ++++++++++--------
 .../watch-service.integration.test.ts         |  56 +++++-
 tests/unit/watch-command.test.ts              |  84 ++++++++-
 7 files changed, 439 insertions(+), 120 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b04ece6c..bf239f7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **watch**: **`deepl watch --auto-commit` now exits 6 at startup when the output directory is in no git repository.** It previously started the watcher, translated, and printed `⚠️  Not a git repository, skipping auto-commit` once per translated file while exiting 0, so a session that could never commit anything still billed every translation. The refusal names the directory and comes before the first translation, matching how a `--glossary` without a source language is refused at launch rather than once per file change. Automation that relied on the translations still being written in that case has to drop `--auto-commit`. See Fixed.
+
 - **watch**: **a `deepl watch` session now exits 12 rather than 0 when it recorded a failure.** Ctrl+C used to end every session at exit 0 with failed translations and failed auto-commits only logged, so a script wrapping `deepl watch` could not tell a clean run from one that lost work. A session that recorded any translation error or any `--auto-commit` failure now exits **12** (`PartialFailure`), and the auto-commit failure count is printed beside the translation total. A session with no failures still exits 0. See Fixed.
 
 - **sync**: **`deepl sync push` / `pull` exit 5 where they exited 1 when the TMS could not be reached.** A pipeline branching on exit 1 as "the CLI crashed" stops seeing an unreachable TMS there and starts seeing it under the documented retriable code, alongside the timeout it already handled. Request counts are unchanged. See Fixed.
@@ -139,6 +141,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **`--auto-commit` and `--git-staged` now act on the repository holding the files they name, not on the directory the CLI was started in.** Every git invocation behind both flags ran with no working directory of its own, so watching a path outside the current repository handed one repository's pathspecs to another's index. Measured with the built CLI over two real repositories and a real endpoint. With the terminal in an unrelated repository, every translation failed to commit with `fatal: .../repoA/out/doc.de.md: '.../repoA/out/doc.de.md' is outside repository at '/private/.../repoB'` — one counted auto-commit failure per translated file, the session exiting 12, and the translation left untracked. With the watched repository nested inside the one holding the working directory, `git add` silently did nothing at all, because git does not descend into another repository, and the commit then failed with `error: pathspec '.../out/doc.de.md' did not match any file(s) known to git`. With the working directory in no repository, the session printed `⚠️  Not a git repository, skipping auto-commit` — untrue, the watched path was one — and **exited 0** having committed nothing, which is the silent half. No case committed into the wrong repository's history: git refuses a pathspec outside its own working tree, so the defect was that the flag could never work rather than that it worked somewhere else. **`--git-staged` was the more reachable half, and failed silently inside a single repository with no unusual layout at all.** `git diff --cached --name-only` names its files relative to the repository root, and the result was resolved against the process working directory, so `deepl watch ./docs --git-staged` started from any subdirectory reported `Git-staged files: 1`, printed `Watching for changes...`, and then matched nothing for the rest of the session: every edit to the staged file ignored, no translation, no output, exit 0. Started from another repository it read that repository's index instead and stopped at `No git-staged files found. Nothing to watch.` Both flags now resolve their repository from the path they act on — `git rev-parse --show-toplevel` anchored on the output directory for the commit, and on the watched path for the staged snapshot, with every staged name resolved against that repository's root. Output paths are made absolute before the working directory changes, so a relative `--output` still commits the file it wrote: `deepl watch ../repoA/src --output ../repoA/out --auto-commit` run from a sibling repository now commits `out/doc.de.md` into repoA at exit 0 and leaves the CLI's own repository untouched, as does the same session run with absolute paths, from a non-repository directory, or over a nested repository.
+
 - **sync**: **`sync resolve` no longer warns about possible data loss on every ordinary lockfile merge.** The lockfile's own metadata was the one part of the file where git could produce a conflict region that is not a whole anything. `stats` sits two context lines below `generated_at`, and every write changes both, so git joined them into a single region — which, with `stats` expanded over five lines, opened inside `stats` and closed outside it. That is not a member list, so `JSON.parse('{' + region + '}')` failed, the region fell to the length-heuristic fallback, and the resolver emitted `WARN .deepl-sync.lock:<conflict-region> — parse-error fallback used, JSON.parse failed on ""generate…"` and picked a side by byte length. Measured over a real `git merge` of real serializer output: it fired in every case where both branches had run a sync, including the most common one of all — two branches translating **different** keys, where git merges the entries map perfectly and there is no real conflict at anything — which reported `Resolved 1 conflict (0 theirs, 0 ours, 1 length-heuristic)`. Since the docs tell the reader a `length-heuristic` decision is a data-loss risk to inspect by hand, the one signal that exists to make silent data loss auditable fired spuriously on every single resolve, and a warning about a region that really did carry a translation was indistinguishable from the routine noise. **`stats` is now written on one line**, like a translation and for the neighbouring reason — its counts and `last_sync` describe one sync run — so the region stays a member list and merges normally: the same fixtures now report `generated_at` and `stats.last_sync` as ordinary per-member decisions with no warning at all. Nothing was lost while the fallback was picking sides, as it happens: `total_keys` and `total_translations` are recomputed from `entries` on every read and `generated_at` is overwritten on every write, so the block it was arbitrating carries no information — which is exactly why warning about it was wrong. Upgrading reformats every existing lockfile on the next write; it is formatting only, five lines becoming one, and no entry's content changes.
 
 - **sync**: **`sync resolve` no longer merges a translation field by field when one side is missing `translated_at`, which produced an entry that existed on neither branch.** Measured over a real `git merge` of real serializer output: ours held `{"hash": "human_hash", "review_status": "human_reviewed", "status": "translated"}` and theirs `{"hash": "machine_hash", "review_status": "machine_translated", "translated_at": "2026-08-03T15:00:00.000Z"}`; the resolver wrote `{"hash": "human_hash", "review_status": "human_reviewed", "status": "translated", "translated_at": "2026-08-03T15:00:00.000Z"}` — ours' hash and review status carrying theirs' timestamp — reported as three per-field decisions and exit 0. That is precisely the fabrication the one-line lockfile format exists to prevent, performed by the resolver after git had correctly raised the conflict. The cause was the translation predicate: it recognised a leaf by `translated_at`, or failing that by `source_hash`, which belongs to the *entry* around a translation and not to the translation itself, so a translation whose only remaining identifying field was `hash` was not recognised and fell through to the generic member-by-member merge. Nothing validates `translated_at` on read — the shape survives a lockfile round trip untouched — and `human_reviewed` is only ever set by hand, so a hand-edited entry is the reachable path. A translation leaf is now identified by `hash` as well, and **one side being one is enough**: a pair is arbitrated whole whenever either side looks like a translation, so no field combination can be invented regardless of how degraded the other side is. **Two decision reasons also stated things that were not true.** Equal timestamps reported `kept ours: newer translated_at 2026-08-04T10:00:00.000Z` when neither side was newer — now `kept ours: same translated_at <stamp> on both sides`. And a pair where *ours* had a timestamp and theirs did not fell to the terminal branch and reported `kept ours: neither side had translated_at` — now `kept ours: theirs had no translated_at`, with the mirrored case worded to match. A `translated_at` that is not a string now counts as absent rather than being compared against an ISO timestamp, so a lockfile committed by another tool cannot steer the tie-break with a non-comparable value.
diff --git a/docs/API.md b/docs/API.md
index 66d51b86..392c942f 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1136,8 +1136,8 @@ Monitor files or directories for changes and automatically translate them. Suppo
 
 **Git Integration:**
 
-- `--auto-commit` - Auto-commit translations to git after each change. One commit per translated source file, queued one at a time: git holds `.git/index.lock` for the duration of an `add` or a `commit`, so parallel translations cannot commit in parallel. A failed commit is reported and counted, and the session exits 12 rather than 0 (see below)
-- `--git-staged` - Only watch git-staged files (snapshot taken once at startup)
+- `--auto-commit` - Auto-commit translations to git after each change. One commit per translated source file, queued one at a time: git holds `.git/index.lock` for the duration of an `add` or a `commit`, so parallel translations cannot commit in parallel. A failed commit is reported and counted, and the session exits 12 rather than 0 (see below). The commit goes to the repository holding the **output directory**, whatever directory the CLI was started in — git can only commit files inside its own working tree, so that is the only repository the translations can reach. When the output directory is in no repository at all, the command exits 6 before the watcher starts rather than warning once per translated file
+- `--git-staged` - Only watch git-staged files (snapshot taken once at startup). The index read is the one belonging to the **watched path**'s repository, so the CLI need not be started from its root
 - `--dry-run` - Show what would be watched without starting the watcher
 
 #### Examples
@@ -1189,7 +1189,7 @@ git add docs/guide.md docs/faq.md
 deepl watch docs/ --to de,ja --git-staged --auto-commit
 ```
 
-> **Note:** `--git-staged` takes a one-time snapshot of staged files at startup. Files staged after the watcher starts are not included. Requires a git repository — exits with an error otherwise.
+> **Note:** `--git-staged` takes a one-time snapshot of staged files at startup. Files staged after the watcher starts are not included. The watched path must be inside a git repository — the command exits with an error otherwise — and it is that repository's index that is read, not the one belonging to the directory the CLI was started in.
 
 ---
 
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index b03ddbcf..d534f831 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -40,6 +40,16 @@ interface WatchOptions {
   gitStaged?: boolean;
 }
 
+/**
+ * The directory a git command about `target` must run in: the watched path
+ * itself when it is a directory, and its parent when it is a single file.
+ */
+function watchedDirectory(target: string): string {
+  const isDirectory =
+    fs.existsSync(target) && fs.statSync(target).isDirectory();
+  return isDirectory ? target : path.dirname(target);
+}
+
 export class WatchCommand {
   private fileTranslationService: FileTranslationService;
   private glossaryService: GlossaryService;
@@ -79,32 +89,61 @@ export class WatchCommand {
   }
 
   /**
-   * Get the set of git-staged file paths (absolute).
-   * SECURITY: Uses execFile instead of exec to prevent command injection
+   * The working tree root of the repository containing `anchorDir`, or null
+   * when that directory is not inside one.
+   *
+   * git resolves a relative pathspec against its own working directory and
+   * refuses one that lies outside its working tree, so every git invocation is
+   * anchored on the files it acts on rather than on the directory the CLI
+   * happens to have been started in.
    */
-  async getStagedFiles(): Promise<Set<string>> {
+  private async gitWorktreeRoot(anchorDir: string): Promise<string | null> {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
 
-    // Verify we're in a git repo
     try {
-      await execFileAsync('git', ['rev-parse', '--git-dir']);
+      const { stdout } = await execFileAsync(
+        'git',
+        ['rev-parse', '--show-toplevel'],
+        { cwd: anchorDir }
+      );
+      const root = stdout.trim();
+      return root.length > 0 ? root : null;
     } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get the set of git-staged file paths (absolute).
+   *
+   * The index that matters is the one belonging to the path being watched, and
+   * `git diff --cached` names its files relative to that repository's root, so
+   * both the query and the paths it returns are anchored there.
+   *
+   * SECURITY: Uses execFile instead of exec to prevent command injection
+   */
+  async getStagedFiles(pathToWatch: string): Promise<Set<string>> {
+    const root = await this.gitWorktreeRoot(watchedDirectory(pathToWatch));
+    if (root === null) {
       throw new ValidationError('--git-staged requires a git repository');
     }
 
-    const { stdout } = await execFileAsync('git', [
-      'diff',
-      '--cached',
-      '--name-only',
-      '--diff-filter=ACM',
-    ]);
+    const { execFile } = await import('child_process');
+    const { promisify } = await import('util');
+    const execFileAsync = promisify(execFile);
+
+    const { stdout } = await execFileAsync(
+      'git',
+      ['diff', '--cached', '--name-only', '--diff-filter=ACM'],
+      { cwd: root }
+    );
     const files = stdout
       .trim()
       .split('\n')
       .filter((f) => f.length > 0);
-    return new Set(files.map((f) => path.resolve(f)));
+    return new Set(files.map((f) => path.resolve(root, f)));
   }
 
   /**
@@ -145,7 +184,7 @@ export class WatchCommand {
     // Get git-staged files if requested
     let stagedFiles: Set<string> | undefined;
     if (options.gitStaged) {
-      stagedFiles = await this.getStagedFiles();
+      stagedFiles = await this.getStagedFiles(pathToWatch);
       if (stagedFiles.size === 0) {
         Logger.warn(
           chalk.yellow('No git-staged files found. Nothing to watch.')
@@ -189,6 +228,20 @@ export class WatchCommand {
       fs.mkdirSync(outputDir, { recursive: true });
     }
 
+    // git can only commit files inside its own working tree, so --auto-commit
+    // is answerable only by the repository holding the output directory. Asked
+    // here, before the first translation is billed, so a session that could
+    // never commit anything says so once instead of once per translated file.
+    if (options.autoCommit) {
+      const repoRoot = await this.gitWorktreeRoot(outputDir);
+      if (repoRoot === null) {
+        throw new ValidationError(
+          `--auto-commit needs a git repository, but the output directory "${outputDir}" is not inside one.`,
+          'Point --output at a path inside the repository the translations belong to, or drop --auto-commit.'
+        );
+      }
+    }
+
     // Create watch service with optional debounce and concurrency
     const watchServiceOptions: {
       debounceMs?: number;
@@ -326,36 +379,38 @@ export class WatchCommand {
       const { promisify } = await import('util');
       const execFileAsync = promisify(execFile);
 
-      // Check if in a git repository
-      try {
-        await execFileAsync('git', ['rev-parse', '--git-dir']);
-      } catch {
-        Logger.warn(
-          chalk.yellow('⚠️  Not a git repository, skipping auto-commit')
-        );
-        return;
-      }
-
-      // Collect output files
+      // Collect output files. Resolved here, while the process working
+      // directory is still the one they were written relative to.
       const outputFiles: string[] = [];
       if (Array.isArray(result)) {
         result.forEach((r: FileTranslationResult) => {
           if (r.outputPath) {
-            outputFiles.push(r.outputPath);
+            outputFiles.push(path.resolve(r.outputPath));
           }
         });
       } else if (result.outputPath) {
-        outputFiles.push(result.outputPath);
+        outputFiles.push(path.resolve(result.outputPath));
       }
 
       if (outputFiles.length === 0) {
         return;
       }
 
+      // The translations decide which repository receives them: git can only
+      // commit files inside its own working tree, so the commit belongs to the
+      // repository holding the output directory.
+      const cwd = await this.gitWorktreeRoot(path.dirname(outputFiles[0]!));
+      if (cwd === null) {
+        Logger.warn(
+          chalk.yellow('⚠️  Not a git repository, skipping auto-commit')
+        );
+        return;
+      }
+
       // `--` stops git reading an output path that begins with a dash as an
       // option: execFile prevents shell injection, not git's own option parsing.
       for (const file of outputFiles) {
-        await execFileAsync('git', ['add', '--', file]);
+        await execFileAsync('git', ['add', '--', file], { cwd });
       }
 
       // Create commit message
@@ -367,14 +422,11 @@ export class WatchCommand {
 
       // --only restricts the commit to the translated outputs, so anything else
       // already staged in the index is not swept into an i18n commit.
-      await execFileAsync('git', [
-        'commit',
-        '--only',
-        '-m',
-        commitMsg,
-        '--',
-        ...outputFiles,
-      ]);
+      await execFileAsync(
+        'git',
+        ['commit', '--only', '-m', commitMsg, '--', ...outputFiles],
+        { cwd }
+      );
 
       Logger.success(chalk.green('✓ Auto-committed translations'));
     } catch (error) {
diff --git a/tests/e2e/cli-watch-auto-commit.e2e.test.ts b/tests/e2e/cli-watch-auto-commit.e2e.test.ts
index 8a97212a..a259978b 100644
--- a/tests/e2e/cli-watch-auto-commit.e2e.test.ts
+++ b/tests/e2e/cli-watch-auto-commit.e2e.test.ts
@@ -62,11 +62,17 @@ describe('deepl watch --auto-commit exit status (subprocess)', () => {
     });
   }
 
-  function git(args: string[]): void {
-    execFileSync('git', args, { cwd: tmpDir, stdio: 'ignore' });
+  function git(args: string[], cwd: string = tmpDir): void {
+    execFileSync('git', args, { cwd, stdio: 'ignore' });
   }
 
-  async function startWatch(port: number): Promise<void> {
+  function initRepo(dir: string): void {
+    git(['init', '-q'], dir);
+    git(['config', 'user.email', 'test@test.com'], dir);
+    git(['config', 'user.name', 'Test'], dir);
+  }
+
+  async function startWatch(port: number, runFrom = tmpDir): Promise<void> {
     fs.writeFileSync(
       path.join(configDir, 'config.json'),
       JSON.stringify({
@@ -96,7 +102,7 @@ describe('deepl watch --auto-commit exit status (subprocess)', () => {
         outDir,
         '--auto-commit',
       ],
-      { cwd: tmpDir, env, stdio: ['ignore', 'pipe', 'pipe'] }
+      { cwd: runFrom, env, stdio: ['ignore', 'pipe', 'pipe'] }
     );
     const collect = (chunk: Buffer): void => {
       cliOutput += chunk.toString();
@@ -129,17 +135,19 @@ describe('deepl watch --auto-commit exit status (subprocess)', () => {
   }
 
   beforeEach(() => {
-    configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ac-cfg-'));
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ac-'));
+    configDir = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ac-cfg-'))
+    );
+    tmpDir = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ac-'))
+    );
     srcDir = path.join(tmpDir, 'src');
     outDir = path.join(tmpDir, 'out');
     fs.mkdirSync(srcDir, { recursive: true });
     fs.mkdirSync(outDir, { recursive: true });
     cliOutput = '';
 
-    git(['init', '-q']);
-    git(['config', 'user.email', 'test@test.com']);
-    git(['config', 'user.name', 'Test']);
+    initRepo(tmpDir);
     fs.writeFileSync(path.join(srcDir, 'doc.md'), 'BASE\n');
     git(['add', '-A']);
     git(['commit', '-qm', 'init']);
@@ -180,6 +188,106 @@ describe('deepl watch --auto-commit exit status (subprocess)', () => {
     expect(code).toBe(12);
   }, 90000);
 
+  it('commits into the watched repository when started from another one', async () => {
+    // The terminal sits in an unrelated repository; the translations belong to
+    // the watched one.
+    const otherRepo = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ac-other-'))
+    );
+    initRepo(otherRepo);
+    fs.writeFileSync(path.join(otherRepo, 'README.md'), 'other\n');
+    git(['add', '-A'], otherRepo);
+    git(['commit', '-qm', 'init'], otherRepo);
+
+    try {
+      const port = await startServer();
+      await startWatch(port, otherRepo);
+      expect(await editUntilTranslated(path.join(srcDir, 'doc.md'))).toBe(true);
+      expect(
+        await waitUntil(() => /Auto-committed/.test(cliOutput), 15000)
+      ).toBe(true);
+
+      const code = await stopAndWait();
+
+      expect(cliOutput).not.toContain('Auto-commit failed');
+      expect(code).toBe(0);
+
+      const watchedLog = execFileSync(
+        'git',
+        ['log', '--oneline', '--name-only'],
+        { cwd: tmpDir, encoding: 'utf-8' }
+      );
+      expect(watchedLog).toContain('auto-translate');
+      expect(watchedLog).toContain('out/doc.de.md');
+
+      const otherLog = execFileSync('git', ['log', '--oneline'], {
+        cwd: otherRepo,
+        encoding: 'utf-8',
+      });
+      expect(otherLog).not.toContain('auto-translate');
+    } finally {
+      fs.rmSync(otherRepo, { recursive: true, force: true });
+    }
+  }, 90000);
+
+  it('refuses before translating when the output directory is in no repository', async () => {
+    const plainOut = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-ac-plain-'))
+    );
+    outDir = plainOut;
+
+    try {
+      const port = await startServer();
+      const configPath = path.join(configDir, 'config.json');
+      fs.writeFileSync(
+        configPath,
+        JSON.stringify({
+          auth: { apiKey: 'mock-api-key-for-testing:fx' },
+          api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+          cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+          output: { format: 'text', verbose: false, color: false },
+        })
+      );
+      const env: NodeJS.ProcessEnv = {
+        ...process.env,
+        DEEPL_CONFIG_DIR: configDir,
+        NO_COLOR: '1',
+      };
+      delete env['DEEPL_API_KEY'];
+
+      child = spawn(
+        'node',
+        [
+          CLI_PATH,
+          'watch',
+          srcDir,
+          '--to',
+          'de',
+          '--output',
+          plainOut,
+          '--auto-commit',
+        ],
+        { cwd: tmpDir, env, stdio: ['ignore', 'pipe', 'pipe'] }
+      );
+      const collect = (chunk: Buffer): void => {
+        cliOutput += chunk.toString();
+      };
+      child.stdout?.on('data', collect);
+      child.stderr?.on('data', collect);
+
+      const code = await new Promise<number | null>((resolve) => {
+        child?.once('exit', (exitCode) => resolve(exitCode));
+      });
+
+      expect(code).toBe(6);
+      expect(cliOutput).toContain('--auto-commit needs a git repository');
+      expect(cliOutput).not.toContain('Watching for changes');
+      expect(fs.readdirSync(plainOut)).toEqual([]);
+    } finally {
+      fs.rmSync(plainOut, { recursive: true, force: true });
+    }
+  }, 60000);
+
   it('exits 0 when every auto-commit succeeded', async () => {
     const port = await startServer();
     await startWatch(port);
diff --git a/tests/integration/watch-auto-commit.integration.test.ts b/tests/integration/watch-auto-commit.integration.test.ts
index af8540f6..cf8c1c16 100644
--- a/tests/integration/watch-auto-commit.integration.test.ts
+++ b/tests/integration/watch-auto-commit.integration.test.ts
@@ -50,7 +50,9 @@ describe('Watch auto-commit integration', () => {
 
   beforeEach(() => {
     jest.clearAllMocks();
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-autocommit-'));
+    tmpDir = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-autocommit-'))
+    );
 
     // Init a real git repo
     execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
@@ -88,18 +90,11 @@ describe('Watch auto-commit integration', () => {
     const outFile = path.join(tmpDir, 'file.es.md');
     fs.writeFileSync(outFile, 'Hola mundo');
 
-    // Run autoCommit from within the repo directory
-    const origCwd = process.cwd();
-    process.chdir(tmpDir);
-    try {
-      await callAutoCommit('file.md', {
-        targetLang: 'es',
-        text: 'Hola mundo',
-        outputPath: outFile,
-      });
-    } finally {
-      process.chdir(origCwd);
-    }
+    await callAutoCommit('file.md', {
+      targetLang: 'es',
+      text: 'Hola mundo',
+      outputPath: outFile,
+    });
 
     // Verify git log shows the commit
     const log = execSync('git log --oneline -1', {
@@ -118,16 +113,10 @@ describe('Watch auto-commit integration', () => {
     fs.writeFileSync(esFile, 'Hola');
     fs.writeFileSync(frFile, 'Bonjour');
 
-    const origCwd = process.cwd();
-    process.chdir(tmpDir);
-    try {
-      await callAutoCommit('file.md', [
-        { targetLang: 'es', text: 'Hola', outputPath: esFile },
-        { targetLang: 'fr', text: 'Bonjour', outputPath: frFile },
-      ]);
-    } finally {
-      process.chdir(origCwd);
-    }
+    await callAutoCommit('file.md', [
+      { targetLang: 'es', text: 'Hola', outputPath: esFile },
+      { targetLang: 'fr', text: 'Bonjour', outputPath: frFile },
+    ]);
 
     const log = execSync('git log --oneline -1', {
       cwd: tmpDir,
@@ -149,17 +138,11 @@ describe('Watch auto-commit integration', () => {
     const outFile = path.join(nonGitDir, 'file.es.md');
     fs.writeFileSync(outFile, 'Hola');
 
-    const origCwd = process.cwd();
-    process.chdir(nonGitDir);
-    try {
-      await callAutoCommit('file.md', {
-        targetLang: 'es',
-        text: 'Hola',
-        outputPath: outFile,
-      });
-    } finally {
-      process.chdir(origCwd);
-    }
+    await callAutoCommit('file.md', {
+      targetLang: 'es',
+      text: 'Hola',
+      outputPath: outFile,
+    });
 
     expect(Logger.warn as jest.Mock).toHaveBeenCalledWith(
       expect.stringContaining('Not a git repository')
@@ -169,17 +152,11 @@ describe('Watch auto-commit integration', () => {
   });
 
   it('should return early when result has no output files', async () => {
-    const origCwd = process.cwd();
-    process.chdir(tmpDir);
-    try {
-      await callAutoCommit('file.md', {
-        targetLang: 'es',
-        text: 'Hola',
-        // no outputPath
-      });
-    } finally {
-      process.chdir(origCwd);
-    }
+    await callAutoCommit('file.md', {
+      targetLang: 'es',
+      text: 'Hola',
+      // no outputPath
+    });
 
     // Should only have the initial commit
     const count = execSync('git rev-list --count HEAD', {
@@ -190,23 +167,79 @@ describe('Watch auto-commit integration', () => {
   });
 
   it('should handle commit failure gracefully', async () => {
-    // Stage nothing — git commit will fail with "nothing to commit"
+    // git refuses to add an ignored path, so the add fails inside a real repo.
+    fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'file.es.md\n');
+    execSync('git add .gitignore && git commit -m "ignore"', {
+      cwd: tmpDir,
+      stdio: 'ignore',
+    });
+    fs.writeFileSync(path.join(tmpDir, 'file.es.md'), 'Hola');
+
+    await callAutoCommit('file.md', {
+      targetLang: 'es',
+      text: 'Hola',
+      outputPath: path.join(tmpDir, 'file.es.md'),
+    });
+
+    expect(Logger.error as jest.Mock).toHaveBeenCalledWith(
+      expect.stringContaining('Auto-commit failed'),
+      expect.any(String)
+    );
+  });
+
+  it('commits into the repository holding the output file, not the process cwd', async () => {
+    // A second repository stands in for the directory the CLI was started in.
+    const otherRepo = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-other-repo-'))
+    );
+    execSync('git init', { cwd: otherRepo, stdio: 'ignore' });
+    execSync('git config user.email "test@test.com"', {
+      cwd: otherRepo,
+      stdio: 'ignore',
+    });
+    execSync('git config user.name "Test"', {
+      cwd: otherRepo,
+      stdio: 'ignore',
+    });
+    fs.writeFileSync(path.join(otherRepo, 'README.md'), 'init');
+    execSync('git add . && git commit -m "init"', {
+      cwd: otherRepo,
+      stdio: 'ignore',
+    });
+
+    const outFile = path.join(tmpDir, 'file.es.md');
+    fs.writeFileSync(outFile, 'Hola mundo');
+
     const origCwd = process.cwd();
-    process.chdir(tmpDir);
+    process.chdir(otherRepo);
     try {
       await callAutoCommit('file.md', {
         targetLang: 'es',
-        text: 'Hola',
-        outputPath: '/nonexistent/file.es.md',
+        text: 'Hola mundo',
+        outputPath: outFile,
       });
     } finally {
       process.chdir(origCwd);
     }
 
-    expect(Logger.error as jest.Mock).toHaveBeenCalledWith(
-      expect.stringContaining('Auto-commit failed'),
-      expect.any(String)
+    const failures = (Logger.error as jest.Mock).mock.calls.filter((call) =>
+      String(call[0]).includes('Auto-commit failed')
+    );
+    expect(failures).toEqual([]);
+
+    const committed = execSync(
+      'git diff-tree --no-commit-id --name-only -r HEAD',
+      { cwd: tmpDir, encoding: 'utf-8' }
     );
+    expect(committed).toContain('file.es.md');
+
+    const otherLog = execSync('git log --oneline', {
+      cwd: otherRepo,
+      encoding: 'utf-8',
+    });
+    expect(otherLog).not.toContain('auto-translate');
+
+    fs.rmSync(otherRepo, { recursive: true, force: true });
   });
 
   it('serializes concurrent auto-commits so every translation lands', async () => {
@@ -215,21 +248,15 @@ describe('Watch auto-commit integration', () => {
       fs.writeFileSync(path.join(tmpDir, `${name}.es.md`), `Hola ${name}`);
     }
 
-    const origCwd = process.cwd();
-    process.chdir(tmpDir);
-    try {
-      await Promise.all(
-        files.map((name) =>
-          callAutoCommit(`${name}.md`, {
-            targetLang: 'es',
-            text: `Hola ${name}`,
-            outputPath: path.join(tmpDir, `${name}.es.md`),
-          })
-        )
-      );
-    } finally {
-      process.chdir(origCwd);
-    }
+    await Promise.all(
+      files.map((name) =>
+        callAutoCommit(`${name}.md`, {
+          targetLang: 'es',
+          text: `Hola ${name}`,
+          outputPath: path.join(tmpDir, `${name}.es.md`),
+        })
+      )
+    );
 
     const failures = (Logger.error as jest.Mock).mock.calls.filter((call) =>
       String(call[0]).includes('Auto-commit failed')
diff --git a/tests/integration/watch-service.integration.test.ts b/tests/integration/watch-service.integration.test.ts
index edfc6035..8069b52c 100644
--- a/tests/integration/watch-service.integration.test.ts
+++ b/tests/integration/watch-service.integration.test.ts
@@ -583,7 +583,7 @@ ${body}
       const output = runScript(
         gitDir,
         `
-const result = await cmd.getStagedFiles();
+const result = await cmd.getStagedFiles(${JSON.stringify('.')});
 console.log(JSON.stringify({ size: result.size, files: [...result] }));
 `
       );
@@ -595,13 +595,63 @@ console.log(JSON.stringify({ size: result.size, files: [...result] }));
       );
     });
 
+    it('resolves staged paths against the watched repository, not the process cwd', () => {
+      const watchedDir = path.join(gitDir, 'docs');
+      fs.mkdirSync(watchedDir);
+      fs.writeFileSync(path.join(watchedDir, 'guide.md'), 'Hello');
+      execSyncChild('git add docs/guide.md', { cwd: gitDir, stdio: 'ignore' });
+
+      // The CLI is started from a sibling subdirectory of the same repository.
+      const runFrom = path.join(gitDir, 'tools');
+      fs.mkdirSync(runFrom);
+
+      const output = runScript(
+        runFrom,
+        `
+const result = await cmd.getStagedFiles(${JSON.stringify(watchedDir)});
+console.log(JSON.stringify({ files: [...result] }));
+`
+      );
+
+      const parsed = JSON.parse(output.trim());
+      expect(parsed.files).toEqual([
+        path.join(fs.realpathSync(gitDir), 'docs', 'guide.md'),
+      ]);
+    });
+
+    it('reads the index of the watched repository, not the one holding the cwd', () => {
+      const otherRepo = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-git-staged-other-')
+      );
+      execSyncChild('git init', { cwd: otherRepo, stdio: 'ignore' });
+      fs.writeFileSync(path.join(gitDir, 'file1.txt'), 'Hello');
+      execSyncChild('git add file1.txt', { cwd: gitDir, stdio: 'ignore' });
+
+      try {
+        const output = runScript(
+          otherRepo,
+          `
+const result = await cmd.getStagedFiles(${JSON.stringify(gitDir)});
+console.log(JSON.stringify({ files: [...result] }));
+`
+        );
+
+        const parsed = JSON.parse(output.trim());
+        expect(parsed.files).toEqual([
+          path.join(fs.realpathSync(gitDir), 'file1.txt'),
+        ]);
+      } finally {
+        fs.rmSync(otherRepo, { recursive: true, force: true });
+      }
+    });
+
     it('should return empty set when no files are staged', () => {
       fs.writeFileSync(path.join(gitDir, 'file1.txt'), 'Hello');
 
       const output = runScript(
         gitDir,
         `
-const result = await cmd.getStagedFiles();
+const result = await cmd.getStagedFiles(${JSON.stringify('.')});
 console.log(JSON.stringify({ size: result.size }));
 `
       );
@@ -619,7 +669,7 @@ console.log(JSON.stringify({ size: result.size }));
         runScript(
           nonGitDir,
           `
-await cmd.getStagedFiles();
+await cmd.getStagedFiles(${JSON.stringify('.')});
 `
         );
         fail('Should have thrown');
diff --git a/tests/unit/watch-command.test.ts b/tests/unit/watch-command.test.ts
index 6d80b8bb..2a9095dd 100644
--- a/tests/unit/watch-command.test.ts
+++ b/tests/unit/watch-command.test.ts
@@ -55,6 +55,13 @@ jest.mock('fs');
 jest.mock('../../src/services/watch');
 jest.mock('../../src/services/file-translation');
 
+interface PrivateWatchCommand {
+  gitWorktreeRoot: (anchorDir: string) => Promise<string | null>;
+}
+
+const asPrivate = (command: WatchCommand): PrivateWatchCommand =>
+  command as unknown as PrivateWatchCommand;
+
 describe('WatchCommand', () => {
   let mockTranslationService: jest.Mocked<TranslationService>;
   let mockFileTranslationService: jest.Mocked<FileTranslationService>;
@@ -687,6 +694,9 @@ describe('WatchCommand', () => {
     it('should display initial watch message with all options', async () => {
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+      jest
+        .spyOn(asPrivate(watchCommand), 'gitWorktreeRoot')
+        .mockResolvedValue('/some');
 
       // Mock the watch service watch method to return a resolved promise
       mockWatchService.watch.mockReturnValue(undefined);
@@ -761,6 +771,9 @@ describe('WatchCommand', () => {
 
       (fs.existsSync as jest.Mock).mockReturnValue(true);
       (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => false });
+      jest
+        .spyOn(asPrivate(watchCommand), 'gitWorktreeRoot')
+        .mockResolvedValue('/some');
     });
 
     it('should auto-commit translations when autoCommit is enabled for multiple languages', async () => {
@@ -830,11 +843,15 @@ describe('WatchCommand', () => {
       expect(mockLogger.success).toHaveBeenCalled();
     });
 
-    it('should handle auto-commit when not in git repository', async () => {
+    it('should warn and skip the commit when the output directory stops being a repository', async () => {
       expect.assertions(1);
       mockWatchService.watch.mockImplementation(() => {
         throw new Error('Test complete');
       });
+      jest
+        .spyOn(asPrivate(watchCommand), 'gitWorktreeRoot')
+        .mockResolvedValueOnce('/some')
+        .mockResolvedValue(null);
 
       try {
         await watchCommand.watch('/some/file.md', {
@@ -854,8 +871,9 @@ describe('WatchCommand', () => {
         outputPath: '/test/file.es.md',
       });
 
-      // Should not throw, just log warning
-      expect(mockLogger.success).toHaveBeenCalled();
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Not a git repository')
+      );
     });
 
     it('should handle auto-commit with no output files', async () => {
@@ -914,6 +932,66 @@ describe('WatchCommand', () => {
     });
   });
 
+  describe('watch() with autoCommit', () => {
+    beforeEach(() => {
+      (fs.existsSync as jest.Mock).mockReturnValue(true);
+      (fs.statSync as jest.Mock).mockReturnValue({ isDirectory: () => true });
+      jest.spyOn(process, 'on').mockImplementation(() => process);
+      mockWatchService.watch.mockImplementation(() => {
+        throw new Error('Test complete');
+      });
+    });
+
+    it('refuses before the watcher starts when the output directory is not in a repository', async () => {
+      expect.assertions(2);
+      jest
+        .spyOn(asPrivate(watchCommand), 'gitWorktreeRoot')
+        .mockResolvedValue(null);
+
+      await expect(
+        watchCommand.watch('/some/dir', {
+          to: 'es',
+          output: '/not/a/repo',
+          autoCommit: true,
+        })
+      ).rejects.toThrow('--auto-commit');
+
+      expect(mockWatchService.watch).not.toHaveBeenCalled();
+    });
+
+    it('starts the watcher when the output directory is in a repository', async () => {
+      expect.assertions(1);
+      jest
+        .spyOn(asPrivate(watchCommand), 'gitWorktreeRoot')
+        .mockResolvedValue('/repo');
+
+      try {
+        await watchCommand.watch('/repo/docs', {
+          to: 'es',
+          output: '/repo/out',
+          autoCommit: true,
+        });
+      } catch {
+        // Expected: the watcher is stubbed to throw once reached
+      }
+
+      expect(mockWatchService.watch).toHaveBeenCalled();
+    });
+
+    it('does not check for a repository when autoCommit is off', async () => {
+      expect.assertions(1);
+      const probe = jest.spyOn(asPrivate(watchCommand), 'gitWorktreeRoot');
+
+      try {
+        await watchCommand.watch('/some/dir', { to: 'es' });
+      } catch {
+        // Expected: the watcher is stubbed to throw once reached
+      }
+
+      expect(probe).not.toHaveBeenCalled();
+    });
+  });
+
   describe('watch() with gitStaged', () => {
     beforeEach(() => {
       (fs.existsSync as jest.Mock).mockReturnValue(true);

From 6072307114068a53d9f4a17cc54760d15f85d225 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 00:38:41 +0200
Subject: [PATCH 176/256] fix(watch): compare path spellings through their
 symlinked ancestors

--git-staged built its set from git, which names files under the
repository's real path, and compared that set against the path the user
typed, so a watched path reaching the repository through a symlink
matched nothing: "Git-staged files: 1", then every edit ignored, no
translation, empty output, exit 0. The loop guard's warn-once
bookkeeping compared the same two spellings, and warned about a file the
CLI had just written itself, naming two spellings of one directory.

Both sites now key on a canonical path with symlinked ancestors resolved
and the final component left alone: a staged file that is itself a
symlink is the file git tracks, not its target. Messages still show the
path as the user spelled it.

Refs cli-8kr2.71
---
 CHANGELOG.md                                  |  2 +
 src/cli/commands/watch.ts                     |  3 +-
 src/services/watch.ts                         | 19 ++--
 src/utils/paths.ts                            | 18 ++++
 .../watch-output-guard.integration.test.ts    | 54 ++++++++++++
 .../watch-service.integration.test.ts         | 28 ++++++
 tests/unit/services/watch.test.ts             | 87 ++++++++++++++++++-
 7 files changed, 200 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bf239f7a..1e6074c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -141,6 +141,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **`--git-staged` now matches its files when the watched path reaches the repository through a symlink.** Two spellings of one path were compared: the staged set is built from `git rev-parse --show-toplevel`, and git always answers with the repository's **real** path, while the watcher compared the path the user typed. Where those differed by a symlinked ancestor, no watched file was ever in the staged set. Measured with the built CLI at e97d835 against a real endpoint, started from the repository root so the working-directory fix above does not apply: `deepl watch /tmp/link/src --to de --git-staged` over a symlink to a repository with one staged file reported `Git-staged files: 1`, printed `Watching for changes...`, and then ignored every edit for the rest of the run — no `Change detected`, **0 translate requests**, empty output directory, **exit 0** — where the same session watching the real path translated the file and wrote `a.de.md`. macOS reaches this with no symlink of the user's own, since `os.tmpdir()` is `/var/folders/…` symlinked to `/private/var/folders/…`, as does any project under a symlinked checkout root. The same two-spellings defect had a **second, independently measured site**: the loop guard's warn-once bookkeeping also compared unresolved paths, so a session whose output directory is reached through a symlink warned `Skipping …/link/src/translations/a.de.md: it is inside the output directory and named like a translated output … Move it outside …/repoA/src/translations to have it translated` about a file **the CLI had just written itself** — a message naming two different spellings of one directory, telling the user to move their own output. Both sites now compare a canonical key with symlinked ancestors resolved and the final path component left alone: a staged file that is itself a symlink is the file git tracks, not its target, so resolving the last component would have broken a case that worked. Messages still show the path as the user spelled it; only the comparison keys are canonical. After the fix the same symlinked session reports `Change detected`, issues 1 translate request and writes `a.de.md`, and the mirror case writes its output with no warning at all.
+
 - **watch**: **`--auto-commit` and `--git-staged` now act on the repository holding the files they name, not on the directory the CLI was started in.** Every git invocation behind both flags ran with no working directory of its own, so watching a path outside the current repository handed one repository's pathspecs to another's index. Measured with the built CLI over two real repositories and a real endpoint. With the terminal in an unrelated repository, every translation failed to commit with `fatal: .../repoA/out/doc.de.md: '.../repoA/out/doc.de.md' is outside repository at '/private/.../repoB'` — one counted auto-commit failure per translated file, the session exiting 12, and the translation left untracked. With the watched repository nested inside the one holding the working directory, `git add` silently did nothing at all, because git does not descend into another repository, and the commit then failed with `error: pathspec '.../out/doc.de.md' did not match any file(s) known to git`. With the working directory in no repository, the session printed `⚠️  Not a git repository, skipping auto-commit` — untrue, the watched path was one — and **exited 0** having committed nothing, which is the silent half. No case committed into the wrong repository's history: git refuses a pathspec outside its own working tree, so the defect was that the flag could never work rather than that it worked somewhere else. **`--git-staged` was the more reachable half, and failed silently inside a single repository with no unusual layout at all.** `git diff --cached --name-only` names its files relative to the repository root, and the result was resolved against the process working directory, so `deepl watch ./docs --git-staged` started from any subdirectory reported `Git-staged files: 1`, printed `Watching for changes...`, and then matched nothing for the rest of the session: every edit to the staged file ignored, no translation, no output, exit 0. Started from another repository it read that repository's index instead and stopped at `No git-staged files found. Nothing to watch.` Both flags now resolve their repository from the path they act on — `git rev-parse --show-toplevel` anchored on the output directory for the commit, and on the watched path for the staged snapshot, with every staged name resolved against that repository's root. Output paths are made absolute before the working directory changes, so a relative `--output` still commits the file it wrote: `deepl watch ../repoA/src --output ../repoA/out --auto-commit` run from a sibling repository now commits `out/doc.de.md` into repoA at exit 0 and leaves the CLI's own repository untouched, as does the same session run with absolute paths, from a non-repository directory, or over a nested repository.
 
 - **sync**: **`sync resolve` no longer warns about possible data loss on every ordinary lockfile merge.** The lockfile's own metadata was the one part of the file where git could produce a conflict region that is not a whole anything. `stats` sits two context lines below `generated_at`, and every write changes both, so git joined them into a single region — which, with `stats` expanded over five lines, opened inside `stats` and closed outside it. That is not a member list, so `JSON.parse('{' + region + '}')` failed, the region fell to the length-heuristic fallback, and the resolver emitted `WARN .deepl-sync.lock:<conflict-region> — parse-error fallback used, JSON.parse failed on ""generate…"` and picked a side by byte length. Measured over a real `git merge` of real serializer output: it fired in every case where both branches had run a sync, including the most common one of all — two branches translating **different** keys, where git merges the entries map perfectly and there is no real conflict at anything — which reported `Resolved 1 conflict (0 theirs, 0 ours, 1 length-heuristic)`. Since the docs tell the reader a `length-heuristic` decision is a data-loss risk to inspect by hand, the one signal that exists to make silent data loss auditable fired spuriously on every single resolve, and a warning about a region that really did carry a translation was indistinguishable from the routine noise. **`stats` is now written on one line**, like a translation and for the neighbouring reason — its counts and `last_sync` describe one sync run — so the region stays a member list and merges normally: the same fixtures now report `generated_at` and `stats.last_sync` as ordinary per-member decisions with no warning at all. Nothing was lost while the fallback was picking sides, as it happens: `total_keys` and `total_translations` are recomputed from `entries` on every read and `generated_at` is overwritten on every write, so the block it was arbitrating carries no information — which is exactly why warning about it was wrong. Upgrading reformats every existing lockfile on the next write; it is formatting only, five lines becoming one, and no entry's content changes.
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index d534f831..05403fb4 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -18,6 +18,7 @@ import {
 } from '../../services/watch.js';
 import { Logger } from '../../utils/logger.js';
 import { ValidationError } from '../../utils/errors.js';
+import { canonicalPathKey } from '../../utils/paths.js';
 import {
   applyGlossarySourceLang,
   hasGlossarySelection,
@@ -143,7 +144,7 @@ export class WatchCommand {
       .trim()
       .split('\n')
       .filter((f) => f.length > 0);
-    return new Set(files.map((f) => path.resolve(root, f)));
+    return new Set(files.map((f) => canonicalPathKey(path.resolve(root, f))));
   }
 
   /**
diff --git a/src/services/watch.ts b/src/services/watch.ts
index 382f681d..452ee5ab 100644
--- a/src/services/watch.ts
+++ b/src/services/watch.ts
@@ -13,7 +13,7 @@ import { Language, TranslationOptions } from '../types/index.js';
 import { Logger } from '../utils/logger.js';
 import { ValidationError } from '../utils/errors.js';
 import { errorMessage } from '../utils/error-message.js';
-import { isWithinDirectory } from '../utils/paths.js';
+import { canonicalPathKey, isWithinDirectory } from '../utils/paths.js';
 
 export interface FileTranslationResult {
   targetLang: Language;
@@ -229,10 +229,13 @@ export class WatchService {
       return;
     }
 
-    // Check if file is in the git-staged set
+    // Check if file is in the git-staged set. Both sides are keyed through
+    // their symlinked ancestors: the set comes from git, which reports the
+    // repository's real path, while a watched path is spelled the way the user
+    // gave it.
     if (
       this.options.stagedFiles &&
-      !this.options.stagedFiles.has(path.resolve(filePath))
+      !this.options.stagedFiles.has(canonicalPathKey(filePath))
     ) {
       return;
     }
@@ -358,11 +361,11 @@ export class WatchService {
    * without a word is indistinguishable from the watcher not seeing it.
    */
   private warnOnceAboutSkippedOutput(filePath: string): void {
-    const resolved = path.resolve(filePath);
-    if (this.writtenOutputs.has(resolved) || this.warnedOutputs.has(resolved)) {
+    const key = canonicalPathKey(filePath);
+    if (this.writtenOutputs.has(key) || this.warnedOutputs.has(key)) {
       return;
     }
-    this.warnedOutputs.add(resolved);
+    this.warnedOutputs.add(key);
     Logger.warn(
       `Skipping ${filePath}: it is inside the output directory and named like a translated output, so it is read as a translation rather than a source. Move it outside ${this.watchOptions?.outputDir ?? 'the output directory'} to have it translated.`
     );
@@ -419,7 +422,7 @@ export class WatchService {
         { preserveCode }
       );
 
-      this.writtenOutputs.add(path.resolve(outputPath));
+      this.writtenOutputs.add(canonicalPathKey(outputPath));
       this.stats.translationsCount++;
 
       if (this.watchOptions.onTranslate) {
@@ -439,7 +442,7 @@ export class WatchService {
 
       for (const result of results) {
         if (result.outputPath) {
-          this.writtenOutputs.add(path.resolve(result.outputPath));
+          this.writtenOutputs.add(canonicalPathKey(result.outputPath));
         }
       }
       this.stats.translationsCount += results.length;
diff --git a/src/utils/paths.ts b/src/utils/paths.ts
index 2b150952..51254d33 100644
--- a/src/utils/paths.ts
+++ b/src/utils/paths.ts
@@ -38,6 +38,24 @@ export function realpathOrAncestor(absPath: string): string {
   }
 }
 
+/**
+ * A comparison key for a file path: symlinked ancestors resolved, the final
+ * component left exactly as given.
+ *
+ * Two spellings of one file — the path a user typed and the path a tool such as
+ * git reports — must compare equal, which requires resolving the directories
+ * they reach the file through. The last component is deliberately not resolved:
+ * a symlink that is itself the tracked file is a different file from its
+ * target, and resolving it would make the two stop matching.
+ */
+export function canonicalPathKey(absPath: string): string {
+  const resolved = path.resolve(absPath);
+  return path.join(
+    realpathOrAncestor(path.dirname(resolved)),
+    path.basename(resolved)
+  );
+}
+
 /**
  * Whether `target` is `root` itself or lies beneath it, with both sides
  * resolved through their symlinks first — so a symlink inside `root` that
diff --git a/tests/integration/watch-output-guard.integration.test.ts b/tests/integration/watch-output-guard.integration.test.ts
index a48f13c7..b34bcfd9 100644
--- a/tests/integration/watch-output-guard.integration.test.ts
+++ b/tests/integration/watch-output-guard.integration.test.ts
@@ -96,6 +96,60 @@ describe('Watch output-file guard integration', () => {
     expect(warnings).toEqual([]);
   });
 
+  // The output directory is deliberately outside the watched directory in the
+  // two tests below, so every handleFileChange call is the test's own and no
+  // chokidar event can add one.
+  const symlinkedOutputLayout = (): {
+    src: string;
+    out: string;
+    link: string;
+  } => {
+    const realDir = fs.realpathSync(tmpDir);
+    const src = path.join(realDir, 'src');
+    const out = path.join(realDir, 'out');
+    fs.mkdirSync(src);
+    fs.mkdirSync(out);
+    const link = path.join(realDir, 'link');
+    fs.symlinkSync(out, link);
+    return { src, out, link };
+  };
+
+  it('stays silent about a file it wrote that is reported through a symlinked ancestor', async () => {
+    const { src, out, link } = symlinkedOutputLayout();
+    const source = path.join(src, 'doc.md');
+    fs.writeFileSync(source, 'Hello\n');
+
+    watchService.watch(src, { targetLangs: ['es'], outputDir: out });
+    watchService.handleFileChange(source);
+    await sleep(DEBOUNCE_MS * 5);
+
+    expect(fs.readFileSync(path.join(out, 'doc.es.md'), 'utf-8')).toBe(
+      'es:Hello\n'
+    );
+
+    // The same output file, spelled the way a session whose output directory is
+    // reached through a symlink sees it.
+    watchService.handleFileChange(path.join(link, 'doc.es.md'));
+    await sleep(DEBOUNCE_MS * 5);
+
+    expect(translationService.translate).toHaveBeenCalledTimes(1);
+    expect(warnings).toEqual([]);
+  });
+
+  it('still says once why it skips a user file reached through a symlinked ancestor', async () => {
+    const { src, out, link } = symlinkedOutputLayout();
+    fs.writeFileSync(path.join(out, 'pricing.es.md'), 'Precios\n');
+
+    watchService.watch(src, { targetLangs: ['es'], outputDir: out });
+    watchService.handleFileChange(path.join(link, 'pricing.es.md'));
+    watchService.handleFileChange(path.join(out, 'pricing.es.md'));
+    await sleep(DEBOUNCE_MS * 5);
+
+    expect(translationService.translate).not.toHaveBeenCalled();
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('pricing.es.md');
+  });
+
   it('says once why it skips a user file sitting in the output directory', async () => {
     const source = path.join(tmpDir, 'pricing.es.md');
     fs.writeFileSync(source, 'Precios\n');
diff --git a/tests/integration/watch-service.integration.test.ts b/tests/integration/watch-service.integration.test.ts
index 8069b52c..6101aecb 100644
--- a/tests/integration/watch-service.integration.test.ts
+++ b/tests/integration/watch-service.integration.test.ts
@@ -645,6 +645,34 @@ console.log(JSON.stringify({ files: [...result] }));
       }
     });
 
+    it('names staged files under the repository real path when the watched path reaches it through a symlink', () => {
+      fs.writeFileSync(path.join(gitDir, 'file1.txt'), 'Hello');
+      execSyncChild('git add file1.txt', { cwd: gitDir, stdio: 'ignore' });
+
+      const linkParent = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'deepl-git-staged-link-')
+      );
+      const link = path.join(linkParent, 'link');
+      fs.symlinkSync(gitDir, link);
+
+      try {
+        const output = runScript(
+          gitDir,
+          `
+const result = await cmd.getStagedFiles(${JSON.stringify(link)});
+console.log(JSON.stringify({ files: [...result] }));
+`
+        );
+
+        const parsed = JSON.parse(output.trim());
+        expect(parsed.files).toEqual([
+          path.join(fs.realpathSync(gitDir), 'file1.txt'),
+        ]);
+      } finally {
+        fs.rmSync(linkParent, { recursive: true, force: true });
+      }
+    });
+
     it('should return empty set when no files are staged', () => {
       fs.writeFileSync(path.join(gitDir, 'file1.txt'), 'Hello');
 
diff --git a/tests/unit/services/watch.test.ts b/tests/unit/services/watch.test.ts
index 7453b3c7..b2d625cc 100644
--- a/tests/unit/services/watch.test.ts
+++ b/tests/unit/services/watch.test.ts
@@ -965,6 +965,14 @@ describe('WatchService', () => {
   });
 
   describe('stagedFiles filtering', () => {
+    // git reports its files under the repository's real path, so a staged set
+    // is spelled with every symlinked ancestor resolved.
+    const stagedEntry = (filePath: string): string =>
+      path.join(
+        fs.realpathSync(path.dirname(filePath)),
+        path.basename(filePath)
+      );
+
     it('should skip files not in stagedFiles set', async () => {
       const testFile = path.join(testDir, 'unstaged.txt');
       fs.writeFileSync(testFile, 'Hello');
@@ -991,7 +999,7 @@ describe('WatchService', () => {
       fs.writeFileSync(testFile, 'Hello');
 
       const stagedService = new WatchService(mockFileTranslationService, {
-        stagedFiles: new Set([path.resolve(testFile)]),
+        stagedFiles: new Set([stagedEntry(testFile)]),
       });
 
       const onChange = jest.fn();
@@ -1013,7 +1021,7 @@ describe('WatchService', () => {
 
       // File is staged but doesn't match pattern *.md
       const stagedService = new WatchService(mockFileTranslationService, {
-        stagedFiles: new Set([path.resolve(testFile)]),
+        stagedFiles: new Set([stagedEntry(testFile)]),
         pattern: '*.md',
       });
 
@@ -1033,6 +1041,81 @@ describe('WatchService', () => {
       expect(onChange).toHaveBeenCalledWith(testFile);
     });
 
+    it('should process a staged file whose path reaches it through a symlinked ancestor', () => {
+      // git names its files under the repository's real path; chokidar reports
+      // whatever spelling the session was started with.
+      const realDir = fs.realpathSync(testDir);
+      const workDir = path.join(realDir, 'work');
+      fs.mkdirSync(workDir);
+      const linkDir = path.join(realDir, 'link');
+      fs.symlinkSync(workDir, linkDir);
+      fs.writeFileSync(path.join(workDir, 'staged.txt'), 'Hello');
+
+      const stagedService = new WatchService(mockFileTranslationService, {
+        stagedFiles: new Set([path.join(workDir, 'staged.txt')]),
+      });
+
+      const onChange = jest.fn();
+      const watchedFile = path.join(linkDir, 'staged.txt');
+      stagedService.watch(linkDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+        onChange,
+      });
+      stagedService.handleFileChange(watchedFile);
+
+      expect(onChange).toHaveBeenCalledWith(watchedFile);
+    });
+
+    it('should still skip an unstaged file reached through a symlinked ancestor', () => {
+      const realDir = fs.realpathSync(testDir);
+      const workDir = path.join(realDir, 'work');
+      fs.mkdirSync(workDir);
+      const linkDir = path.join(realDir, 'link');
+      fs.symlinkSync(workDir, linkDir);
+      fs.writeFileSync(path.join(workDir, 'unstaged.txt'), 'Hello');
+
+      const stagedService = new WatchService(mockFileTranslationService, {
+        stagedFiles: new Set([path.join(workDir, 'staged.txt')]),
+      });
+
+      const onChange = jest.fn();
+      stagedService.watch(linkDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+        onChange,
+      });
+      stagedService.handleFileChange(path.join(linkDir, 'unstaged.txt'));
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('should process a staged file that is itself a symlink to a file outside the tree', () => {
+      // git stages the link, not its target, so the comparison must leave the
+      // final path component alone.
+      const realDir = fs.realpathSync(testDir);
+      const workDir = path.join(realDir, 'work');
+      fs.mkdirSync(workDir);
+      const outside = path.join(realDir, 'outside.txt');
+      fs.writeFileSync(outside, 'Hello');
+      const linkedFile = path.join(workDir, 'linked.txt');
+      fs.symlinkSync(outside, linkedFile);
+
+      const stagedService = new WatchService(mockFileTranslationService, {
+        stagedFiles: new Set([linkedFile]),
+      });
+
+      const onChange = jest.fn();
+      stagedService.watch(workDir, {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+        onChange,
+      });
+      stagedService.handleFileChange(linkedFile);
+
+      expect(onChange).toHaveBeenCalledWith(linkedFile);
+    });
+
     it('should not filter when stagedFiles is undefined', async () => {
       const testFile = path.join(testDir, 'any.txt');
       fs.writeFileSync(testFile, 'Hello');

From 57754a8320350db0ccee74b5f3bd319d4ba7e2ae Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 07:35:10 +0200
Subject: [PATCH 177/256] fix(sync): make --dry-run and the cost cap price the
 run, not the lockfile

The dry-run branch returned before the two target-file checks the real run
makes, so its estimate came from the lockfile alone and was wrong in both
directions: a key the lockfile calls translated that the target file no
longer holds was absent from the estimate though the run re-translates and
re-bills it, and a locale whose target file is unreadable was estimated as
translatable though the run refuses it, bills nothing and exits 12.

Both now come from one findTargetGaps call per source file, which returns
the missing keys and the unreadable reason from the same read: repair keys
join the estimate and are reported as unwrittenKeys, and a refused locale
is excluded and named in a warning written in the preview's own voice. The
max_characters cap quotes from the same function, since it under-counted
the same work and let a run bill twice its cap. Memoising that audit also
stops --frozen reading every target file twice.

--dry-run still writes nothing and still exits 0.

Refs cli-8kr2.68
---
 CHANGELOG.md                                  |   8 +
 docs/API.md                                   |   2 +
 docs/SYNC.md                                  |  31 +++-
 src/cli/commands/sync-command.ts              |  12 ++
 src/sync/sync-process-bucket.ts               | 157 ++++++++++++------
 src/sync/sync-target-read.ts                  |  19 +++
 .../sync-target-drift.integration.test.ts     |  44 +++++
 .../sync-unusable-target.integration.test.ts  |  78 +++++++++
 tests/integration/sync.integration.test.ts    |  11 +-
 tests/unit/sync/sync-command.test.ts          |  42 +++++
 10 files changed, 351 insertions(+), 53 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e6074c5..c2933c84 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **a project that sets `sync.max_characters` can now be refused where it previously ran**, and `deepl sync --dry-run` can now report a larger character estimate than before for the same input. Both follow from the cap and the preview finally counting repair work — keys the lockfile calls translated that the target file no longer holds — which a real run translates and bills. A pipeline whose cap was tuned against the old under-count will need it raised to the number `--dry-run` now reports, which is the number that run actually spends. `--dry-run` still exits 0 and still writes nothing. See Fixed.
+
 - **watch**: **`deepl watch --auto-commit` now exits 6 at startup when the output directory is in no git repository.** It previously started the watcher, translated, and printed `⚠️  Not a git repository, skipping auto-commit` once per translated file while exiting 0, so a session that could never commit anything still billed every translation. The refusal names the directory and comes before the first translation, matching how a `--glossary` without a source language is refused at launch rather than once per file change. Automation that relied on the translations still being written in that case has to drop `--auto-commit`. See Fixed.
 
 - **watch**: **a `deepl watch` session now exits 12 rather than 0 when it recorded a failure.** Ctrl+C used to end every session at exit 0 with failed translations and failed auto-commits only logged, so a script wrapping `deepl watch` could not tell a clean run from one that lost work. A session that recorded any translation error or any `--auto-commit` failure now exits **12** (`PartialFailure`), and the auto-commit failure count is printed beside the translation total. A session with no failures still exits 0. See Fixed.
@@ -141,6 +143,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`--dry-run` now previews the run rather than the lockfile, in both directions it was wrong.** The dry-run branch returned before the two target-file checks the real run makes, so the estimate came from the lockfile alone. Measured against a real endpoint on a JSON project with one damaged locale. **Under-reporting:** with a key the lockfile calls translated deleted from the target file, `deepl sync --dry-run` reported `Sync complete: 2 current`, `estimatedCharacters: 0` and no cost line at all, while the very next real run translated it — `✓ es: 1/1 keys`. **Over-reporting:** with a new source key added and the target file left unreadable, dry-run reported `estimatedCharacters: 12` and `ok: true` at exit 0, and said nothing about the file; the real run refused the locale, billed **0**, reported `failed: 3` and exited **12**. So the one command whose job is deciding whether to spend money under-quoted repair work and over-quoted work that was never going to happen. Both halves now come from one `findTargetGaps` call per source file — the machinery `--frozen` already uses, which returns the missing keys and the unreadable reason from the same read: keys the target no longer holds are added to the estimate and reported as `unwrittenKeys`, and a locale whose target file is unreadable is left out of the estimate and named in its own warning ending `It is left out of the estimate below. Fix it before running \`deepl sync\`.` A dry run still writes nothing — no target file, no lockfile, no backup — and still exits 0, since it reports what a run would do rather than standing in for its exit code, which is what `--frozen` is for. Because the summary counts a repair key as `current`, the run now also says `1 key is recorded as translated in the lock file but could not be confirmed in the target file, so a real run would translate it again`, so the character estimate is not a number with nothing behind it. **The bead's suggested cheap option was based on a wrong premise**: warning about an unreadable target "without paying for a full audit" costs exactly the same reads, because a file cannot be known to be unreadable without opening it, and the gap keys fall out of that same read for free. **Cost, measured** on a 20,000-key, 6-locale JSON project (2.83 MiB source, 17.3 MiB of targets, 24 MiB lockfile): `--dry-run` 0.44 s → 0.75 s, against 0.77 s for `sync status` and 0.79 s for `sync --frozen`; peak RSS 283 MiB → 370 MiB. A locale the lockfile claims nothing for is not read at all, so a project mid-first-sync pays nothing.
+
+- **sync**: **the `sync.max_characters` cost cap no longer under-counts the work it is meant to cap.** Its preflight estimate came from the same lockfile-only arithmetic as `--dry-run`, so repair work was invisible to it: on a fixture whose lockfile claimed ten translated keys for a locale with no target file at all, plus a newly added locale, the cap computed **500** characters for a run that bills **1,000** — a cap set at 500 let it through. The cap and `--dry-run` now quote from one function, so a run the preview prices above the cap is a run the cap refuses. This costs one pass over the target files before the cap decides, where it previously decided without reading anything: measured on the fixture above, a translating run went from 1.54 s to 1.91 s against a local mock, where no network latency dilutes the fraction. Projects that do not set `max_characters` are unaffected.
+
+- **sync**: **`--frozen` no longer reads every target file twice.** On a project with no drift the target-versus-lockfile comparison ran once for the drift check and again for the "nothing left to do" check, since each call started a fresh audit. The answer is now computed once per source file and reused, which took `sync --frozen` from 1.13 s to 0.79 s on the 20,000-key, 6-locale fixture above and cut its peak RSS from 469 MiB to 382 MiB. No output changes.
+
 - **watch**: **`--git-staged` now matches its files when the watched path reaches the repository through a symlink.** Two spellings of one path were compared: the staged set is built from `git rev-parse --show-toplevel`, and git always answers with the repository's **real** path, while the watcher compared the path the user typed. Where those differed by a symlinked ancestor, no watched file was ever in the staged set. Measured with the built CLI at e97d835 against a real endpoint, started from the repository root so the working-directory fix above does not apply: `deepl watch /tmp/link/src --to de --git-staged` over a symlink to a repository with one staged file reported `Git-staged files: 1`, printed `Watching for changes...`, and then ignored every edit for the rest of the run — no `Change detected`, **0 translate requests**, empty output directory, **exit 0** — where the same session watching the real path translated the file and wrote `a.de.md`. macOS reaches this with no symlink of the user's own, since `os.tmpdir()` is `/var/folders/…` symlinked to `/private/var/folders/…`, as does any project under a symlinked checkout root. The same two-spellings defect had a **second, independently measured site**: the loop guard's warn-once bookkeeping also compared unresolved paths, so a session whose output directory is reached through a symlink warned `Skipping …/link/src/translations/a.de.md: it is inside the output directory and named like a translated output … Move it outside …/repoA/src/translations to have it translated` about a file **the CLI had just written itself** — a message naming two different spellings of one directory, telling the user to move their own output. Both sites now compare a canonical key with symlinked ancestors resolved and the final path component left alone: a staged file that is itself a symlink is the file git tracks, not its target, so resolving the last component would have broken a case that worked. Messages still show the path as the user spelled it; only the comparison keys are canonical. After the fix the same symlinked session reports `Change detected`, issues 1 translate request and writes `a.de.md`, and the mirror case writes its output with no warning at all.
 
 - **watch**: **`--auto-commit` and `--git-staged` now act on the repository holding the files they name, not on the directory the CLI was started in.** Every git invocation behind both flags ran with no working directory of its own, so watching a path outside the current repository handed one repository's pathspecs to another's index. Measured with the built CLI over two real repositories and a real endpoint. With the terminal in an unrelated repository, every translation failed to commit with `fatal: .../repoA/out/doc.de.md: '.../repoA/out/doc.de.md' is outside repository at '/private/.../repoB'` — one counted auto-commit failure per translated file, the session exiting 12, and the translation left untracked. With the watched repository nested inside the one holding the working directory, `git add` silently did nothing at all, because git does not descend into another repository, and the commit then failed with `error: pathspec '.../out/doc.de.md' did not match any file(s) known to git`. With the working directory in no repository, the session printed `⚠️  Not a git repository, skipping auto-commit` — untrue, the watched path was one — and **exited 0** having committed nothing, which is the silent half. No case committed into the wrong repository's history: git refuses a pathspec outside its own working tree, so the defect was that the flag could never work rather than that it worked somewhere else. **`--git-staged` was the more reachable half, and failed silently inside a single repository with no unusual layout at all.** `git diff --cached --name-only` names its files relative to the repository root, and the result was resolved against the process working directory, so `deepl watch ./docs --git-staged` started from any subdirectory reported `Git-staged files: 1`, printed `Watching for changes...`, and then matched nothing for the rest of the session: every edit to the staged file ignored, no translation, no output, exit 0. Started from another repository it read that repository's index instead and stopped at `No git-staged files found. Nothing to watch.` Both flags now resolve their repository from the path they act on — `git rev-parse --show-toplevel` anchored on the output directory for the commit, and on the watched path for the staged snapshot, with every staged name resolved against that repository's root. Output paths are made absolute before the working directory changes, so a relative `--output` still commits the file it wrote: `deepl watch ../repoA/src --output ../repoA/out --auto-commit` run from a sibling repository now commits `out/doc.de.md` into repoA at exit 0 and leaves the CLI's own repository untouched, as does the same session run with absolute paths, from a non-repository directory, or over a nested repository.
diff --git a/docs/API.md b/docs/API.md
index 392c942f..90e16068 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1607,6 +1607,8 @@ No other fields appear in the output. Fields not listed above are internal and m
 #### Notes
 
 - The `--frozen` flag makes no API calls. It compares the lockfile against source files, and each target file against what the lockfile claims about it, and exits with code 10 if any translations are missing, outdated, or recorded as translated while absent from the target file. This is the recommended mode for CI/CD pipelines.
+- The `--dry-run` flag makes no API calls and writes nothing — no target file, no lockfile, no backup. It reads each target file the lockfile claims translations for, so its estimate covers the same work the real run does: keys the lockfile calls translated that the target file no longer holds are **included** (the run re-translates and re-bills them, and `unwrittenKeys` reports the count), and a locale whose target file is on disk and unreadable is **excluded** and named in a warning, because the run refuses that locale, bills nothing for it and exits 12. Reading the target files is what makes the estimate faithful and is the flag's main cost: measured on a 20,000-key, 6-locale project (2.83 MiB source, 17.3 MiB of target files, 24 MiB lockfile), `--dry-run` went from 0.44 s to 0.75 s, alongside 0.77 s for `sync status` and 0.79 s for `sync --frozen`. The read is skipped entirely for a locale the lockfile claims nothing for, so a project mid-first-sync pays nothing.
+- The `sync.max_characters` cost cap quotes from the same estimate as `--dry-run`, so a run the preview prices above the cap is a run the cap refuses. That costs one pass over the target files before the cap decides: on the fixture above, a translating run took 1.54 s with no cap configured and 1.91 s with one. The cap is unaffected for projects that do not set it.
 - The lockfile (`.deepl-sync.lock`) should be committed to version control. It enables incremental sync by tracking content hashes.
 - The `push` and `pull` subcommands require a TMS that implements the REST contract documented in [docs/SYNC.md](./SYNC.md#tms-rest-contract). All other commands work with the standard DeepL Translation API.
 - By default, keys with extracted context are grouped by i18n section and translated in section batches. Use `--no-batch` to force individual per-key context translation. Use `--batch` to force all keys into plain batch calls (no context).
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 2455740d..ca3eb3bf 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -165,7 +165,9 @@ In `--format json` the locale's entry in `unwrittenByLocale` carries an extra `u
 
 Two deliberate exemptions. A key whose **source value is empty** is never reported: an empty source can only produce an empty translation, and PO and XLIFF read an empty translation side as untranslated on purpose (see [Bilingual formats](#bilingual-formats-po-and-xliff)), so such a key is legitimately absent from a bilingual target. A key the lock file records as `failed`, or against an older source hash, is already reported as outdated and is not counted twice.
 
-The cost is one read and parse of each target file per locale, and it is only paid where the answer would otherwise come from the lock file alone: `sync status`, `sync --frozen`, and a `sync` run that has nothing else to do. A run with translating to do reads those files anyway. Measured on a 2.8 MiB XLIFF source with 20,316 keys across 6 locales (52 MiB of files): `sync status` 410 ms → 660 ms, `sync --frozen` 465 ms → 970 ms. A locale with no keys claimed by the lock file is not read at all.
+The cost is one read and parse of each target file per locale, and it is only paid where the answer would otherwise come from the lock file alone: `sync status`, `sync --frozen`, `sync --dry-run`, the `sync.max_characters` cost cap, and a `sync` run that has nothing else to do. A run with translating to do reads those files anyway. Measured on a 2.8 MiB XLIFF source with 20,316 keys across 6 locales (52 MiB of files): `sync status` 410 ms → 660 ms, `sync --frozen` 465 ms → 970 ms. A locale with no keys claimed by the lock file is not read at all, so a project mid-first-sync pays nothing.
+
+Within one source file the answer is computed once and reused, so no command reads a target file twice for it. On a 20,000-key, 6-locale JSON project (2.83 MiB source, 17.3 MiB of target files) that took `sync --frozen` from 1.13 s to 0.79 s, because a healthy project made it ask twice — once for the drift check and again for the "nothing to do" check.
 
 ### A target file that cannot be read
 
@@ -194,6 +196,20 @@ Sync complete: 2 current (2 translations failed)
 
 Exit **12** (`PartialFailure`), 0 characters billed, and the file is byte-identical. Other locales of the same file, and other files, are unaffected. A key the source has just gained is recorded `failed` rather than `translated`, so the next run retries it once the file is fixed. `deepl sync status` reports the file under its own sentence (see above) and `--frozen` exits 10.
 
+`deepl sync --dry-run` says so before you get there, rather than leaving the exit 12 to the real run:
+
+```
+$ deepl sync --dry-run
+es: target file locales/es.json is on disk but could not be read (JSON:
+'menu.save' is the key of two different strings. …) — it holds the only copy of
+this locale's translations, so a real run would leave it as it stands, translate
+nothing for this locale and exit 12. It is left out of the estimate below. Fix it
+before running `deepl sync`.
+[dry-run] No translations performed.
+```
+
+The locale is left out of the character estimate because the run bills nothing for it. Dry run itself still exits **0** and writes nothing: it reports what a run would do rather than standing in for its exit code, which is what `--frozen` is for.
+
 `deepl sync pull` skips the locale under the `unusable_target` skip reason — or `key_collision` when that is the cause, which has its own remediation (see below) — and leaves the file exactly as it stands. `deepl sync push` reports a file that is not there under `target_missing` and surfaces every other failure, since it only reads.
 
 The distinction is deliberately strict: an errno the CLI does not recognise refuses the file rather than admitting it. A file that is genuinely absent produces `ENOENT` and nothing else.
@@ -649,7 +665,7 @@ Sync complete: 200 new (150 translations failed)
 
 The count totals every locale, so a run failing 4 keys in `de` and 3 in `fr` reports `7 translations failed`. Exit code is 12 (partial failure).
 
-In `--dry-run` mode, the output includes estimated characters and cost (computed from source string lengths × target locales, no API calls):
+In `--dry-run` mode, the output includes estimated characters and cost (computed from source string lengths × the target locales the run would actually translate, no API calls):
 
 ```
 [dry-run] No translations performed.
@@ -657,6 +673,17 @@ Sync complete: 12 new, 3 updated across 5 languages
 This sync: ~4,500 chars, ~$0.11 (Pro tier estimate)
 ```
 
+The estimate covers repair work as well as new work. A key the lock file calls translated that its target file no longer holds is counted `current` in the summary — it is current as far as the lock file goes — so the run says why the estimate is not zero:
+
+```
+[dry-run] No translations performed.
+Sync complete: 2 current across 1 language
+1 key is recorded as translated in the lock file but could not be confirmed in
+the target file, so a real run would translate it again. Run `deepl sync status`
+to see which keys, in which file, and why.
+This sync: ~12 chars, <$0.01 (Pro tier estimate)
+```
+
 Cost estimates use the DeepL Pro rate ($25 per 1 million characters). If you are on the Free tier or a different plan, your actual cost will differ. Check your account tier at [deepl.com](https://deepl.com) to determine the applicable rate.
 
 With `--format json`, the result includes `estimatedCharacters`, `targetLocaleCount`, `estimatedCost`, and `rateAssumption: "pro"` (indicating the estimate is based on Pro-tier pricing). A `perLocale` array provides per-file per-locale breakdowns.
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index 8bff0e39..ed206b80 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -785,6 +785,18 @@ export class SyncCommand {
       }
     }
 
+    // The summary counts such a key as `current`, which it is as far as the lock
+    // file goes, so the estimate below would otherwise quote characters for work
+    // nothing in the report accounts for.
+    if (result.dryRun && result.unwrittenKeys > 0) {
+      const one = result.unwrittenKeys === 1;
+      Logger.info(
+        `${result.unwrittenKeys.toLocaleString()} ${one ? 'key is' : 'keys are'} recorded as translated in the lock file ` +
+          `but could not be confirmed in the target file, so a real run would translate ${one ? 'it' : 'them'} again. ` +
+          'Run `deepl sync status` to see which keys, in which file, and why.'
+      );
+    }
+
     if (result.dryRun && result.estimatedCharacters > 0) {
       Logger.info(
         `This sync: ~${result.estimatedCharacters.toLocaleString()} chars, ${formatCostEstimate(result.estimatedCharacters)} (Pro tier estimate)`
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index a5f67e50..0fc64af7 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -16,8 +16,12 @@ import {
   extractExistingTranslations,
   type WalkedBucketFile,
 } from './sync-bucket-walker.js';
-import { findTargetGaps } from './sync-target-audit.js';
-import { readTargetFile, unusableTargetMessage } from './sync-target-read.js';
+import { findTargetGaps, type TargetGaps } from './sync-target-audit.js';
+import {
+  readTargetFile,
+  unusableTargetMessage,
+  unusableTargetPreviewMessage,
+} from './sync-target-read.js';
 import type { LocaleTranslator } from './sync-locale-translator.js';
 import type { SyncFileResult, SyncOptions } from './sync-service.js';
 
@@ -156,21 +160,89 @@ export async function processBucket(
    * target unrepaired for as long as no other key needed work. A run that has
    * translating to do reads every target file a few lines further down anyway.
    */
+  let gapsCache: TargetGaps | undefined;
+  const targetGaps = async (): Promise<TargetGaps> => {
+    if (gapsCache === undefined) {
+      const effective = options?.localeFilter?.length
+        ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
+        : config.target_locales;
+      gapsCache = await findTargetGaps(
+        config,
+        walked,
+        fileLockEntries,
+        effective
+      );
+    }
+    return gapsCache;
+  };
+
   const unwrittenTargetKeys = async (): Promise<number> => {
-    const effective = options?.localeFilter?.length
-      ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
-      : config.target_locales;
-    const gaps = await findTargetGaps(
-      config,
-      walked,
-      fileLockEntries,
-      effective
-    );
+    const gaps = await targetGaps();
     let count = 0;
     for (const gap of gaps.values()) count += gap.keys.size;
     return count;
   };
 
+  /**
+   * Characters a real run would bill for this bucket, and the locales it would
+   * refuse.
+   *
+   * Counted: new and stale keys for every locale that will be translated,
+   * current keys for a locale that holds none of them yet, and keys the lockfile
+   * calls translated that the target file does not hold — the run translates
+   * those again. Not counted: a locale whose target file is on disk and
+   * unreadable, which the run refuses in full and bills nothing for.
+   *
+   * `--dry-run` and the `max_characters` cap both quote from here, so the number
+   * a preview shows is the number the cap enforces.
+   */
+  const estimateCharacters = async (
+    candidateLocales: readonly string[]
+  ): Promise<{
+    chars: number;
+    refused: ReadonlySet<string>;
+    gaps: TargetGaps;
+  }> => {
+    const gaps = await targetGaps();
+    const refused = new Set<string>();
+    for (const [locale, gap] of gaps) {
+      if (gap.unusable !== undefined) refused.add(locale);
+    }
+    const billable = candidateLocales.filter((locale) => !refused.has(locale));
+
+    let chars =
+      toTranslate.reduce((sum, d) => sum + (d.value?.length ?? 0), 0) *
+      billable.length;
+
+    if (hasNewLocale) {
+      const currentChars = diffs
+        .filter((d) => d.status === 'current')
+        .reduce((sum, d) => sum + (d.value?.length ?? 0), 0);
+      const newLocaleCount = billable.filter((locale) =>
+        diffs.some(
+          (d) =>
+            d.status === 'current' &&
+            !getOwnMember(fileLockEntries, d.key)?.translations[locale]
+        )
+      ).length;
+      chars += currentChars * newLocaleCount;
+    }
+
+    // Under `--force` every key is already counted above.
+    if (!options?.force) {
+      const sourceValues = new Map(entries.map((e) => [e.key, e.value]));
+      for (const locale of billable) {
+        const gap = gaps.get(locale);
+        if (gap === undefined) continue;
+        for (const key of gap.keys) {
+          chars += sourceValues.get(key)?.length ?? 0;
+        }
+      }
+    }
+
+    return { chars, refused, gaps };
+  };
+
   if (options?.frozen) {
     const failMissing = config.validation?.fail_on_missing !== false;
     const failStale = config.validation?.fail_on_stale !== false;
@@ -199,30 +271,36 @@ export async function processBucket(
       ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
       : config.target_locales;
 
-    // Estimate characters for new/stale keys across all effective locales
-    out.estimatedCharactersDelta +=
-      toTranslate.reduce((sum, d) => sum + (d.value?.length ?? 0), 0) *
-      effectiveLocales.length;
+    // The same target-file checks the real run makes, so the preview is of that
+    // run rather than of the lockfile.
+    const { chars, refused, gaps } = await estimateCharacters(effectiveLocales);
+    out.estimatedCharactersDelta += chars;
 
     if (hasNewLocale) {
       // Count current keys needing translation for new locales
-      const currentDiffs = diffs.filter((d) => d.status === 'current');
-      out.newKeysDelta += currentDiffs.length;
+      out.newKeysDelta += diffs.filter((d) => d.status === 'current').length;
+    }
 
-      // Estimate characters for current keys needing translation for new locales only
-      const currentChars = currentDiffs.reduce(
-        (sum, d) => sum + (d.value?.length ?? 0),
-        0
-      );
-      const newLocaleCount = effectiveLocales.filter((locale) =>
-        diffs.some(
-          (d) =>
-            d.status === 'current' &&
-            !getOwnMember(fileLockEntries, d.key)?.translations[locale]
+    for (const gap of gaps.values()) out.unwrittenKeysDelta += gap.keys.size;
+
+    for (const locale of refused) {
+      const targetRelPath = walked.isMultiLocale
+        ? relPath
+        : resolveTargetPath(
+            relPath,
+            config.source_locale,
+            locale,
+            bucketConfig.target_path_pattern
+          );
+      Logger.warn(
+        unusableTargetPreviewMessage(
+          locale,
+          targetRelPath,
+          gaps.get(locale)!.unusable!
         )
-      ).length;
-      out.estimatedCharactersDelta += currentChars * newLocaleCount;
+      );
     }
+
     return out;
   }
 
@@ -265,24 +343,9 @@ export async function processBucket(
       MULTI_TARGET_CONCURRENCY);
 
   if (config.sync?.max_characters !== undefined && !options?.force) {
-    let estimatedChars =
-      toTranslate.reduce((sum, d) => sum + (d.value?.length ?? 0), 0) *
-      locales.length;
-    if (hasNewLocale) {
-      const currentDiffs = diffs.filter((d) => d.status === 'current');
-      const currentChars = currentDiffs.reduce(
-        (sum, d) => sum + (d.value?.length ?? 0),
-        0
-      );
-      const newLocaleCount = locales.filter((locale) =>
-        diffs.some(
-          (d) =>
-            d.status === 'current' &&
-            !getOwnMember(fileLockEntries, d.key)?.translations[locale]
-        )
-      ).length;
-      estimatedChars += currentChars * newLocaleCount;
-    }
+    // Quoted from the same place `--dry-run` quotes, so a run the preview priced
+    // above the cap is a run the cap refuses.
+    const { chars: estimatedChars } = await estimateCharacters(locales);
     if (
       currentTotalCharsBilled + out.totalCharsBilledDelta + estimatedChars >
       config.sync.max_characters
diff --git a/src/sync/sync-target-read.ts b/src/sync/sync-target-read.ts
index 9c3bbc53..7ee34e36 100644
--- a/src/sync/sync-target-read.ts
+++ b/src/sync/sync-target-read.ts
@@ -66,3 +66,22 @@ export function unusableTargetMessage(relPath: string, reason: string): string {
     'stands rather than rebuilt from the source. Fix it, then run `deepl sync` again.'
   );
 }
+
+/**
+ * The same condition as `unusableTargetMessage`, in the voice a preview needs:
+ * `--dry-run` has not left the file anywhere yet, and saying that it had would
+ * contradict the report it appears in.
+ */
+export function unusableTargetPreviewMessage(
+  locale: string,
+  relPath: string,
+  reason: string
+): string {
+  return (
+    `${locale}: target file ${relPath} is on disk but could not be read ` +
+    `(${reason}) — it holds the only copy of this locale's translations, so a ` +
+    'real run would leave it as it stands, translate nothing for this locale ' +
+    'and exit 12. It is left out of the estimate below. Fix it before running ' +
+    '`deepl sync`.'
+  );
+}
diff --git a/tests/integration/sync-target-drift.integration.test.ts b/tests/integration/sync-target-drift.integration.test.ts
index 944472ec..f3ca0c9e 100644
--- a/tests/integration/sync-target-drift.integration.test.ts
+++ b/tests/integration/sync-target-drift.integration.test.ts
@@ -121,6 +121,37 @@ describe('a target file missing translations the lockfile claims', () => {
     );
   });
 
+  it('is carried by the --dry-run estimate, which the real run charges for', async () => {
+    await damage();
+
+    const dry = await harness.syncService.sync(await loadSyncConfig(tmpDir), {
+      dryRun: true,
+    });
+
+    // 'Translate me' is the source of the key the target lost, and repairing it
+    // is what the next real run spends.
+    expect(dry.estimatedCharacters).toBe('Translate me'.length);
+    expect(dry.unwrittenKeys).toBe(1);
+  });
+
+  it('writes nothing while estimating the repair', async () => {
+    await damage();
+    const before = fs.readFileSync(targetPath(), 'utf-8');
+    const lockBefore = fs.readFileSync(
+      path.join(tmpDir, '.deepl-sync.lock'),
+      'utf-8'
+    );
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir), {
+      dryRun: true,
+    });
+
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toBe(before);
+    expect(
+      fs.readFileSync(path.join(tmpDir, '.deepl-sync.lock'), 'utf-8')
+    ).toBe(lockBefore);
+  });
+
   it('reports a target file that was deleted outright', async () => {
     await damage();
     fs.unlinkSync(targetPath());
@@ -165,6 +196,19 @@ describe('a target file missing translations the lockfile claims', () => {
     expect(es.coverage).toBe(0);
   });
 
+  it('leaves a healthy project --dry-run estimate at zero', async () => {
+    replyTranslating();
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    const dry = await harness.syncService.sync(await loadSyncConfig(tmpDir), {
+      dryRun: true,
+    });
+
+    expect(dry.estimatedCharacters).toBe(0);
+    expect(dry.unwrittenKeys).toBe(0);
+    expect(dry.currentKeys).toBe(2);
+  });
+
   it('leaves a healthy project alone on --frozen', async () => {
     replyTranslating();
     await harness.syncService.sync(await loadSyncConfig(tmpDir));
diff --git a/tests/integration/sync-unusable-target.integration.test.ts b/tests/integration/sync-unusable-target.integration.test.ts
index 393d2e7a..92e32514 100644
--- a/tests/integration/sync-unusable-target.integration.test.ts
+++ b/tests/integration/sync-unusable-target.integration.test.ts
@@ -42,6 +42,7 @@ describe('sync over a target file that cannot be read', () => {
   let tmpDir: string;
   let harness: ReturnType<typeof createSyncHarness>;
   let errors: string[];
+  let warnings: string[];
 
   beforeEach(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-unusable-'));
@@ -54,9 +55,13 @@ describe('sync over a target file that cannot be read', () => {
     fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
     fs.writeFileSync(sourcePath, SOURCE, 'utf-8');
     errors = [];
+    warnings = [];
     jest.spyOn(Logger, 'error').mockImplementation((...args: unknown[]) => {
       errors.push(args.join(' '));
     });
+    jest.spyOn(Logger, 'warn').mockImplementation((...args: unknown[]) => {
+      warnings.push(args.join(' '));
+    });
   });
 
   afterEach(() => {
@@ -170,8 +175,81 @@ describe('sync over a target file that cannot be read', () => {
     expect(scope.isDone()).toBe(false);
   });
 
+  it('is left out of the --dry-run estimate, which the real run bills nothing for', async () => {
+    await damage();
+    // A key the source has just gained, so there is work to estimate.
+    fs.writeFileSync(
+      path.join(tmpDir, 'locales', 'en.json'),
+      JSON.stringify(
+        { greeting: 'Hello', added: 'Translate me', fresh: 'Good morning' },
+        null,
+        2
+      ) + '\n',
+      'utf-8'
+    );
+
+    const dry = await harness.syncService.sync(await loadSyncConfig(tmpDir), {
+      dryRun: true,
+    });
+
+    // es is the only locale, and the real run refuses it and bills 0.
+    expect(dry.estimatedCharacters).toBe(0);
+  });
+
+  it('is named by --dry-run rather than left for the real run to discover', async () => {
+    await damage();
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir), {
+      dryRun: true,
+    });
+
+    const said = warnings.join('\n');
+    expect(said).toContain('locales/es.json');
+    expect(said).toContain("'menu.save' is the key of two different strings");
+  });
+
+  it('writes nothing while reporting the unreadable target', async () => {
+    await damage();
+    const before = fs.readFileSync(targetPath(), 'utf-8');
+    const lockBefore = fs.readFileSync(
+      path.join(tmpDir, '.deepl-sync.lock'),
+      'utf-8'
+    );
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir), {
+      dryRun: true,
+    });
+
+    expect(fs.readFileSync(targetPath(), 'utf-8')).toBe(before);
+    expect(
+      fs.readFileSync(path.join(tmpDir, '.deepl-sync.lock'), 'utf-8')
+    ).toBe(lockBefore);
+  });
+
   // Over-rejection guards: absent is not unusable, and a file that reads fine is
   // still repaired.
+  it('leaves a healthy project --dry-run estimate and output alone', async () => {
+    replyTranslating();
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+    fs.writeFileSync(
+      path.join(tmpDir, 'locales', 'en.json'),
+      JSON.stringify(
+        { greeting: 'Hello', added: 'Translate me', fresh: 'Good morning' },
+        null,
+        2
+      ) + '\n',
+      'utf-8'
+    );
+
+    const dry = await harness.syncService.sync(await loadSyncConfig(tmpDir), {
+      dryRun: true,
+    });
+
+    expect(dry.estimatedCharacters).toBe('Good morning'.length);
+    expect(dry.unwrittenKeys).toBe(0);
+    expect(warnings).toEqual([]);
+  });
+
   it('still writes a locale that has never been synced', async () => {
     replyTranslating();
 
diff --git a/tests/integration/sync.integration.test.ts b/tests/integration/sync.integration.test.ts
index f8f7b0ef..84dead53 100644
--- a/tests/integration/sync.integration.test.ts
+++ b/tests/integration/sync.integration.test.ts
@@ -1746,12 +1746,15 @@ buckets:
       const config = await loadSyncConfig(tmpDir);
       const dryResult = await syncService.sync(config, { dryRun: true });
 
-      // dry-run must estimate currentChars * newLocaleCount (10 keys * 50 chars * 1 new locale = 500)
-      expect(dryResult.estimatedCharacters).toBe(500);
+      // 10 keys * 50 chars for the added locale, plus the same again for `de`:
+      // the seeded lockfile calls every key translated for `de` and no `de`
+      // target file exists, so the run repairs all ten and bills for them too.
+      expect(dryResult.estimatedCharacters).toBe(1000);
+      expect(dryResult.unwrittenKeys).toBe(10);
 
       // The live path preflight must compute the same estimate; verify by setting cap just below it
       const configAtCap = await loadSyncConfig(tmpDir);
-      (configAtCap as any).sync = { ...configAtCap.sync, max_characters: 499 };
+      (configAtCap as any).sync = { ...configAtCap.sync, max_characters: 999 };
       await expect(syncService.sync(configAtCap)).rejects.toThrow(
         ValidationError
       );
@@ -1759,7 +1762,7 @@ buckets:
       const configAboveCap = await loadSyncConfig(tmpDir);
       (configAboveCap as any).sync = {
         ...configAboveCap.sync,
-        max_characters: 500,
+        max_characters: 1000,
       };
       nock(DEEPL_FREE_API_URL)
         .post('/v2/translate')
diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index ecdbbae6..304a14ca 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -261,6 +261,48 @@ describe('SyncCommand', () => {
       expect(infoOutput).toContain('Pro tier estimate');
     });
 
+    it('should say why a dry-run estimate covers keys the summary calls current', async () => {
+      const result = makeResult({
+        dryRun: true,
+        estimatedCharacters: 12,
+        unwrittenKeys: 1,
+        currentKeys: 2,
+        totalCharactersBilled: 0,
+      });
+      const mockService = createMockSyncService(result);
+      const command = new SyncCommand(mockService);
+
+      await command.run({ dryRun: true });
+
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
+      expect(infoOutput).toContain(
+        '1 key is recorded as translated in the lock file'
+      );
+      expect(infoOutput).toContain('would translate it again');
+    });
+
+    it('should say nothing about unwritten keys when a dry run finds none', async () => {
+      const result = makeResult({
+        dryRun: true,
+        estimatedCharacters: 12,
+        unwrittenKeys: 0,
+        totalCharactersBilled: 0,
+      });
+      const mockService = createMockSyncService(result);
+      const command = new SyncCommand(mockService);
+
+      await command.run({ dryRun: true });
+
+      const infoOutput = logInfoSpy.mock.calls
+        .map((c) => String(c[0]))
+        .join('\n');
+      expect(infoOutput).not.toContain(
+        'recorded as translated in the lock file'
+      );
+    });
+
     it('should include estimatedCost in JSON output', async () => {
       const result = makeResult({ totalCharactersBilled: 1_000_000 });
       const mockService = createMockSyncService(result);

From e7d0426db6f5ce53a03d67ca89fb347a51305f1d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 07:54:03 +0200
Subject: [PATCH 178/256] fix(sync): stop counting a fuzzy PO translation as a
 finished one

gettext marks an entry fuzzy to mean "needs review, do not use", and
msgfmt leaves it out of the compiled catalog, so the string every read
path here counted as done is one the application does not display. On a
two-key catalog with one entry flagged and its source unchanged, msgfmt
reported "1 translated message, 1 fuzzy translation" while sync status
reported 100%, dry-run reported 2 current, sync made no requests and
validate passed.

Such a key is now its own needsReview category in sync status, and sync
push skips it under a needs_review reason instead of uploading a draft as
approved. Nothing is re-translated and no file is rewritten: the value
belongs to whoever flagged it, so reading it as untranslated would replace
a human's in-progress work with machine output and re-bill every fuzzy
entry. --frozen still passes, since a fuzzy entry is a normal transient
state only a review clears.

XLIFF's needs-review states are the same idea in the other bilingual
format and are tracked separately: no bundled tool arbitrates which of
them mean "will not ship".

Refs cli-8kr2.67
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   2 +
 docs/SYNC.md                                  |  10 +-
 src/cli/commands/sync/register-sync-status.ts |  16 +-
 src/formats/format.ts                         |  14 ++
 src/formats/po.ts                             |  30 +++
 src/sync/sync-review-flags.ts                 |  58 ++++++
 src/sync/sync-status.ts                       |  36 +++-
 src/sync/sync-tms.ts                          |  22 +-
 .../e2e/cli-sync-bilingual-target.e2e.test.ts |  42 ++++
 .../sync-bilingual-target.integration.test.ts | 191 ++++++++++++++++++
 tests/unit/formats/po.test.ts                 |  72 +++++++
 12 files changed, 491 insertions(+), 6 deletions(-)
 create mode 100644 src/sync/sync-review-flags.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c2933c84..2c995fdc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **`deepl sync status` reports a lower coverage percentage for a PO project holding `#, fuzzy` entries**, and each locale in `--format json` gains a `needsReview` count. A dashboard or CI check reading `coverage` or `complete` out of that command will see a project it called 100% drop to whatever share of its keys are actually shippable — which is what `msgfmt` has been reporting all along. `deepl sync push` reports a new `needs_review` skip reason, so its pushed count falls by the number of fuzzy entries. Nothing is re-translated, rewritten or re-billed, and `sync --frozen` still passes. See Fixed.
+
 - **sync**: **a project that sets `sync.max_characters` can now be refused where it previously ran**, and `deepl sync --dry-run` can now report a larger character estimate than before for the same input. Both follow from the cap and the preview finally counting repair work — keys the lockfile calls translated that the target file no longer holds — which a real run translates and bills. A pipeline whose cap was tuned against the old under-count will need it raised to the number `--dry-run` now reports, which is the number that run actually spends. `--dry-run` still exits 0 and still writes nothing. See Fixed.
 
 - **watch**: **`deepl watch --auto-commit` now exits 6 at startup when the output directory is in no git repository.** It previously started the watcher, translated, and printed `⚠️  Not a git repository, skipping auto-commit` once per translated file while exiting 0, so a session that could never commit anything still billed every translation. The refusal names the directory and comes before the first translation, matching how a `--glossary` without a source language is refused at launch rather than once per file change. Automation that relied on the translations still being written in that case has to drop `--auto-commit`. See Fixed.
@@ -143,6 +145,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a gettext `#, fuzzy` translation is no longer counted as complete.** Every read path treated the msgstr of a fuzzy entry as a finished translation, but `fuzzy` is gettext's way of saying "needs review, do not use": `msgfmt` leaves the entry out of the compiled catalog, so the string the CLI called done is one the application does not display. Measured against that oracle on a two-key PO catalog with one entry flagged and its source unchanged — `msgfmt --statistics` said `1 translated message, 1 fuzzy translation` while `deepl sync status` said `100% (0 missing, 0 outdated)`, `complete: 2`, `unwritten: 0`, `sync --dry-run` said `2 current`, `deepl sync` made **0 requests**, and `sync validate` said `All translations passed validation`. So a project shipping an untranslated string reported as finished, indefinitely. Such a key is now its own **`needsReview`** category in `sync status` (text suffix `, 1 needs review` plus a line explaining the flag and both ways out; `needsReview` on each locale in `--format json`), and the same catalog now reports `50%`, agreeing with `msgfmt`. `deepl sync push` skips it under a new **`needs_review`** skip reason instead of uploading a reviewer's draft as an approved translation. **Nothing is re-translated and nothing is rewritten**: the value belongs to whoever flagged it, so reading it as untranslated would have replaced a human's in-progress work with machine output and re-billed every fuzzy entry in the project — the one outcome worse than an overstated percentage. Both documented remedies were measured end to end: removing the flag returns the key to `complete` (`msgfmt`: `2 translated messages`), and clearing the msgstr has the next `deepl sync` translate it afresh. `sync --frozen` deliberately still passes, since a fuzzy entry is a normal transient state in a gettext workflow that only a human review clears. XLIFF's `state="needs-review-translation"` is the same idea in the other bilingual format and is tracked separately: its states differ between 1.2 and 2.0 and no external tool arbitrates which of them mean "will not ship", where `msgfmt` settles it for PO.
+
 - **sync**: **`--dry-run` now previews the run rather than the lockfile, in both directions it was wrong.** The dry-run branch returned before the two target-file checks the real run makes, so the estimate came from the lockfile alone. Measured against a real endpoint on a JSON project with one damaged locale. **Under-reporting:** with a key the lockfile calls translated deleted from the target file, `deepl sync --dry-run` reported `Sync complete: 2 current`, `estimatedCharacters: 0` and no cost line at all, while the very next real run translated it — `✓ es: 1/1 keys`. **Over-reporting:** with a new source key added and the target file left unreadable, dry-run reported `estimatedCharacters: 12` and `ok: true` at exit 0, and said nothing about the file; the real run refused the locale, billed **0**, reported `failed: 3` and exited **12**. So the one command whose job is deciding whether to spend money under-quoted repair work and over-quoted work that was never going to happen. Both halves now come from one `findTargetGaps` call per source file — the machinery `--frozen` already uses, which returns the missing keys and the unreadable reason from the same read: keys the target no longer holds are added to the estimate and reported as `unwrittenKeys`, and a locale whose target file is unreadable is left out of the estimate and named in its own warning ending `It is left out of the estimate below. Fix it before running \`deepl sync\`.` A dry run still writes nothing — no target file, no lockfile, no backup — and still exits 0, since it reports what a run would do rather than standing in for its exit code, which is what `--frozen` is for. Because the summary counts a repair key as `current`, the run now also says `1 key is recorded as translated in the lock file but could not be confirmed in the target file, so a real run would translate it again`, so the character estimate is not a number with nothing behind it. **The bead's suggested cheap option was based on a wrong premise**: warning about an unreadable target "without paying for a full audit" costs exactly the same reads, because a file cannot be known to be unreadable without opening it, and the gap keys fall out of that same read for free. **Cost, measured** on a 20,000-key, 6-locale JSON project (2.83 MiB source, 17.3 MiB of targets, 24 MiB lockfile): `--dry-run` 0.44 s → 0.75 s, against 0.77 s for `sync status` and 0.79 s for `sync --frozen`; peak RSS 283 MiB → 370 MiB. A locale the lockfile claims nothing for is not read at all, so a project mid-first-sync pays nothing.
 
 - **sync**: **the `sync.max_characters` cost cap no longer under-counts the work it is meant to cap.** Its preflight estimate came from the same lockfile-only arithmetic as `--dry-run`, so repair work was invisible to it: on a fixture whose lockfile claimed ten translated keys for a locale with no target file at all, plus a newly added locale, the cap computed **500** characters for a run that bills **1,000** — a cap set at 500 let it through. The cap and `--dry-run` now quote from one function, so a run the preview prices above the cap is a run the cap refuses. This costs one pass over the target files before the cap decides, where it previously decided without reading anything: measured on the fixture above, a translating run went from 1.54 s to 1.91 s against a local mock, where no network latency dilutes the fraction. Projects that do not set `max_characters` are unaffected.
diff --git a/docs/API.md b/docs/API.md
index 90e16068..472a6464 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1391,6 +1391,8 @@ Source: en (142 keys)
   ja  [##################..]  91%  (12 missing, 0 outdated)
 ```
 
+A locale also reports **`needsReview`** keys — a translation is present but its format marks it as not ready to ship, which today means a gettext `#, fuzzy` msgstr. `msgfmt` leaves such an entry out of the compiled catalog, so the application shows the source string; counting it complete would report a project as done while it ships untranslated text. Such a key is never re-translated and the file is never rewritten for it — the value is a reviewer's draft — so the count is a report, not a repair, and nothing is billed. The suffix `, N needs review` and its explanatory line appear only when the count is non-zero, and `--format json` always carries `needsReview` on each locale. `deepl sync push` skips such a key under a `needs_review` skip reason rather than uploading it as an approved translation. `sync --frozen` deliberately does **not** treat it as drift: a fuzzy entry is a normal, transient state in a gettext workflow that only a human review clears, and nothing the CLI did caused it.
+
 A locale also reports **`unwritten`** keys — recorded as translated in `.deepl-sync.lock` but not in that locale's target file — when there are any, followed by a line naming the file and the keys. The suffix is omitted when the count is zero, so the line above is unchanged for a healthy project. `--format json` always carries `unwritten` on each locale plus a top-level `unwrittenByLocale` array of `{locale, file, keys}`, each entry gaining an `unusable` field when the target file could not be read or parsed at all. See [docs/SYNC.md](./SYNC.md#a-string-added-after-the-first-sync) for what is and is not counted.
 
 ##### `validate`
diff --git a/docs/SYNC.md b/docs/SYNC.md
index ca3eb3bf..68f2858e 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -231,13 +231,19 @@ Nine of the eleven formats are monolingual -- a target file holds translations a
 | Path | What it reads from a PO / XLIFF target |
 |------|----------------------------------------|
 | `deepl sync` | The existing `msgstr` / `<target>` is carried forward for a key the lockfile calls up to date, so a reviewed translation survives a run that rewrites the file because a *sibling* key changed |
-| `deepl sync push` | The `msgstr` / `<target>` is what gets uploaded |
+| `deepl sync push` | The `msgstr` / `<target>` is what gets uploaded, unless it is flagged `fuzzy` |
 | `deepl sync validate` | Placeholder and structure checks compare the `msgstr` against the `msgid` |
 | `deepl sync pull` | For a key the export does not carry, the existing `msgstr` is kept |
 | `deepl sync audit` | Terminology consistency is measured across translations |
 
 **An empty translation side means untranslated, not empty.** A `msgstr ""`, a `<trans-unit>` with no `<target>`, and an empty `<target></target>` all read as "this key has no translation yet": `sync` translates the key rather than pinning the empty string, and `push` skips it (see below). This differs from the monolingual formats, where an empty value is a deliberate translation and is preserved.
 
+**A `#, fuzzy` msgstr is a translation the catalog will not ship.** Gettext marks an entry `fuzzy` to mean "there is a translation here, but it needs review" — `msgmerge` writes it when a source string changes and it matched an old translation, and reviewers set it by hand. `msgfmt` leaves such an entry out of the compiled `.mo`, so the application shows the **msgid**. The CLI therefore counts it as its own `needsReview` category rather than as complete, and its numbers now agree with the oracle's: on a two-key catalog with one entry flagged, `msgfmt --statistics` says `1 translated message, 1 fuzzy translation` and `deepl sync status` says `50% (0 missing, 0 outdated, 1 needs review)` where it used to say `100%`.
+
+What the CLI does **not** do is act on it. The msgstr is a reviewer's draft and the lockfile records that key as translated against an unchanged source, so `deepl sync` carries the value and the flag forward untouched, re-translates nothing and bills nothing — reading it as untranslated would replace a human's in-progress work with machine output, which is the one outcome worse than an overstated percentage. `deepl sync push` skips the key under the `needs_review` reason rather than uploading a draft as approved. `sync --frozen` does not treat it as drift, because a fuzzy entry is a normal, transient state that only a human review clears. Two ways out, both measured: **remove the flag** and the key counts complete again (`msgfmt`: `2 translated messages`), or **clear the msgstr** and the next `deepl sync` translates it afresh (`msgfmt`: `1 translated, 1 untranslated`, then `2 translated messages`).
+
+XLIFF's `state="needs-review-translation"` and its siblings are the same idea in the other bilingual format and are **not** covered: XLIFF 1.2 and 2.0 spell the states differently, several values arguably qualify, and there is no external tool to arbitrate which — unlike gettext, where `msgfmt` decides. It is tracked separately.
+
 **PO entries need no blank line between them.** The blank-line separator is a convention `msgfmt -c` does not require, and a catalog written without it — after the header or between messages — is read and written entry by entry all the same. An entry ends at the first line that is not a continuation of its translation: a comment, a `msgctxt`, or the next `msgid`. Layout is preserved either way, so a catalog that arrived without the separators keeps that shape on the way out.
 
 ## Configuration
@@ -1019,7 +1025,7 @@ deepl sync push [OPTIONS]
 | `--format <fmt>` | Output format: `text` (default), `json` |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 
-**A key with no translation yet is not pushed.** Push reads each target file and uploads the translation it holds. A bilingual target file (see [Bilingual formats: PO and XLIFF](#bilingual-formats-po-and-xliff)) lists every key the source has, translated or not, so pushing such a key would upload its source text as the locale's translation and make the TMS the authority for it -- a later `pull` would then write English into the target file. Those keys are skipped and reported under the `untranslated` reason, with the pushed count reflecting only what was actually sent. For a monolingual format nothing is skipped on this account: every key the target file lists has a value.
+**A key with no translation yet is not pushed.** Push reads each target file and uploads the translation it holds. A bilingual target file (see [Bilingual formats: PO and XLIFF](#bilingual-formats-po-and-xliff)) lists every key the source has, translated or not, so pushing such a key would upload its source text as the locale's translation and make the TMS the authority for it -- a later `pull` would then write English into the target file. Those keys are skipped and reported under the `untranslated` reason, with the pushed count reflecting only what was actually sent. A PO entry flagged `#, fuzzy` is skipped too, under `needs_review`: it has a translation, but one its own toolchain will not ship (see [Bilingual formats](#bilingual-formats-po-and-xliff)). For a monolingual format nothing is skipped on this account: every key the target file lists has a value.
 
 ### `deepl sync pull`
 
diff --git a/src/cli/commands/sync/register-sync-status.ts b/src/cli/commands/sync/register-sync-status.ts
index 57cc38cb..00bad898 100644
--- a/src/cli/commands/sync/register-sync-status.ts
+++ b/src/cli/commands/sync/register-sync-status.ts
@@ -75,8 +75,10 @@ async function handleSyncStatus(
         )}`;
         const unwrittenSuffix =
           locale.unwritten > 0 ? `, ${locale.unwritten} unwritten` : '';
+        const needsReviewSuffix =
+          locale.needsReview > 0 ? `, ${locale.needsReview} needs review` : '';
         Logger.output(
-          `  ${locale.locale}  [${bar}] ${locale.coverage}%  (${locale.missing} missing, ${locale.outdated} outdated${unwrittenSuffix})`
+          `  ${locale.locale}  [${bar}] ${locale.coverage}%  (${locale.missing} missing, ${locale.outdated} outdated${unwrittenSuffix}${needsReviewSuffix})`
         );
       }
       const unwritten = status.unwrittenByLocale.filter(
@@ -88,6 +90,18 @@ async function handleSyncStatus(
         Logger.output('');
         Logger.warn(targetGapsWarning(unwritten));
       }
+      const needingReview = locales.reduce((sum, l) => sum + l.needsReview, 0);
+      if (needingReview > 0) {
+        const one = needingReview === 1;
+        Logger.output('');
+        Logger.warn(
+          `${needingReview} ${one ? 'key holds' : 'keys hold'} a translation marked as needing review — a gettext ` +
+            '`#, fuzzy` msgstr, which `msgfmt` leaves out of the compiled catalog, so the ' +
+            `application shows the source string instead. \`deepl sync\` carries ${one ? 'it' : 'them'} forward ` +
+            `untouched and never re-translates ${one ? 'it' : 'them'}: remove the flag once the translation ` +
+            `has been checked, or clear the msgstr to have ${one ? 'it' : 'them'} translated again.`
+        );
+      }
     }
   } catch (error) {
     if (options.format === 'json') {
diff --git a/src/formats/format.ts b/src/formats/format.ts
index 824be8a8..2794428f 100644
--- a/src/formats/format.ts
+++ b/src/formats/format.ts
@@ -48,6 +48,20 @@ export interface FormatParser {
    * target read already is the translation.
    */
   extractTranslations?(content: string, locale?: string): Map<string, string>;
+  /**
+   * Optional: keys whose translation is present but marked as needing review, so
+   * the format's own toolchain will not ship it.
+   *
+   * Gettext is the case this exists for: `msgfmt` leaves a `#, fuzzy` entry out
+   * of the compiled catalog, so a translation this CLI counted as done is one the
+   * application does not display. The value is still a translation and is
+   * deliberately still returned by `extractTranslations` — a run must carry it
+   * forward rather than overwrite a reviewer's draft — so the two answers travel
+   * separately.
+   *
+   * A format with no such concept leaves it undefined.
+   */
+  extractNeedsReview?(content: string, locale?: string): Set<string>;
   /**
    * Optional: a copy of this parser bounded to `maxDepth` levels of nesting.
    * Parsers that walk their tree recursively implement it so `sync` can apply
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 0901e4ce..197c8222 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -400,6 +400,36 @@ export class PoFormatParser implements FormatParser {
    * which is enough to report the entry as translated. The per-form values
    * travel separately in `metadata.plural_forms`.
    */
+  /**
+   * Keys carrying gettext's `fuzzy` flag with a translation to go with it.
+   *
+   * `msgfmt` leaves such an entry out of the compiled catalog, so the string the
+   * application shows is the msgid — a key this CLI would otherwise report as
+   * complete. A fuzzy entry with an empty msgstr is left out here: it has no
+   * translation at all, which every reader already reports as missing.
+   */
+  extractNeedsReview(content: string): Set<string> {
+    const flagged = new Set<string>();
+    if (!content.trim()) {
+      return flagged;
+    }
+
+    for (const pe of parseEntries(content)) {
+      if (isHeaderEntry(pe)) continue;
+      if (!pe.flags.includes('fuzzy')) continue;
+
+      const singular = pe.msgstr[0];
+      const hasTranslation =
+        (singular !== undefined && singular !== '') ||
+        [...pe.msgstrPlural.values()].some((v) => v !== '');
+      if (hasTranslation) {
+        flagged.add(makeKey(pe));
+      }
+    }
+
+    return flagged;
+  }
+
   extractTranslations(content: string): Map<string, string> {
     const translations = new Map<string, string>();
     if (!content.trim()) {
diff --git a/src/sync/sync-review-flags.ts b/src/sync/sync-review-flags.ts
new file mode 100644
index 00000000..cc160b3c
--- /dev/null
+++ b/src/sync/sync-review-flags.ts
@@ -0,0 +1,58 @@
+import * as path from 'path';
+import type { ResolvedSyncConfig } from './sync-config.js';
+import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
+import type { WalkedBucketFile } from './sync-bucket-walker.js';
+import { readTargetFile } from './sync-target-read.js';
+
+/**
+ * Keys whose translation is present but marked as needing review, keyed by
+ * locale. A locale with nothing flagged is absent from the map.
+ */
+export type NeedsReviewKeys = Map<string, Set<string>>;
+
+/**
+ * Ask each locale's target file which of its translations its own toolchain
+ * would refuse to ship.
+ *
+ * Only bilingual formats carry the concept — gettext's `#, fuzzy`, which
+ * `msgfmt` leaves out of the compiled catalog — so a parser without
+ * `extractNeedsReview` short-circuits before any file is opened and the nine
+ * monolingual formats cost nothing.
+ *
+ * A file that is absent or unreadable yields nothing rather than an error: the
+ * caller already reports an unreadable target through `findTargetGaps`, and
+ * reporting it twice under two names would say one file is two problems. The
+ * read having succeeded is also why the extraction below cannot fail — it walks
+ * the same entries `readTargetFile` has already parsed.
+ */
+export async function findNeedsReview(
+  config: ResolvedSyncConfig,
+  walked: WalkedBucketFile,
+  locales: readonly string[]
+): Promise<NeedsReviewKeys> {
+  const flagged: NeedsReviewKeys = new Map();
+  const extractNeedsReview = walked.parser.extractNeedsReview;
+  if (extractNeedsReview === undefined) {
+    return flagged;
+  }
+
+  for (const locale of locales) {
+    const targetRelPath = resolveTargetPath(
+      walked.relPath,
+      config.source_locale,
+      locale,
+      walked.bucketConfig.target_path_pattern
+    );
+    const targetAbsPath = path.join(config.projectRoot, targetRelPath);
+    assertPathWithinRoot(targetAbsPath, config.projectRoot);
+    const read = await readTargetFile(walked.parser, targetAbsPath, locale);
+    if (read.state !== 'usable') continue;
+
+    const keys = extractNeedsReview.call(walked.parser, read.content, locale);
+    if (keys.size > 0) {
+      flagged.set(locale, keys);
+    }
+  }
+
+  return flagged;
+}
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index 9b573d2f..1c9ccba1 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -7,6 +7,7 @@ import type { ResolvedSyncConfig } from './sync-config.js';
 import { LOCK_FILE_NAME } from './types.js';
 import { walkBuckets } from './sync-bucket-walker.js';
 import { findTargetGaps } from './sync-target-audit.js';
+import { findNeedsReview } from './sync-review-flags.js';
 import { resolveTargetPath } from './sync-utils.js';
 
 export interface LocaleStatus {
@@ -21,6 +22,14 @@ export interface LocaleStatus {
    * counted as `complete`.
    */
   unwritten: number;
+  /**
+   * Keys whose target translation is present but marked as needing review, so
+   * the format's own toolchain will not ship it — a gettext `#, fuzzy` msgstr,
+   * which `msgfmt` leaves out of the compiled catalog. Never counted as
+   * `complete`, and never re-translated: the value is a reviewer's, not this
+   * tool's, so a run carries it forward untouched and reports it instead.
+   */
+  needsReview: number;
   coverage: number;
 }
 
@@ -66,7 +75,13 @@ export async function computeSyncStatus(
   const unwrittenByLocale: UnwrittenTargetKeys[] = [];
   const localeStats = new Map<
     string,
-    { complete: number; missing: number; outdated: number; unwritten: number }
+    {
+      complete: number;
+      missing: number;
+      outdated: number;
+      unwritten: number;
+      needsReview: number;
+    }
   >();
 
   for (const locale of config.target_locales) {
@@ -75,6 +90,7 @@ export async function computeSyncStatus(
       missing: 0,
       outdated: 0,
       unwritten: 0,
+      needsReview: 0,
     });
   }
 
@@ -93,6 +109,15 @@ export async function computeSyncStatus(
       fileLockEntries,
       config.target_locales
     );
+    // Keys whose target translation the format's own toolchain will not ship.
+    // Only asked of a parser that has the concept, so the nine monolingual
+    // formats cost nothing and no extra file is opened for them.
+    const needsReviewByLocale = await findNeedsReview(
+      config,
+      walked,
+      config.target_locales
+    );
+
     for (const [locale, gap] of gaps) {
       unwrittenByLocale.push({
         locale,
@@ -131,6 +156,8 @@ export async function computeSyncStatus(
           stats.outdated++;
         } else if (gaps.get(locale)?.keys.has(diff.key)) {
           stats.unwritten++;
+        } else if (needsReviewByLocale.get(locale)?.has(diff.key)) {
+          stats.needsReview++;
         } else {
           stats.complete++;
         }
@@ -144,9 +171,14 @@ export async function computeSyncStatus(
       missing: 0,
       outdated: 0,
       unwritten: 0,
+      needsReview: 0,
     };
     const total =
-      stats.complete + stats.missing + stats.outdated + stats.unwritten;
+      stats.complete +
+      stats.missing +
+      stats.outdated +
+      stats.unwritten +
+      stats.needsReview;
     const coverage = total > 0 ? Math.round((stats.complete / total) * 100) : 0;
     return { locale, ...stats, coverage };
   });
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index a881df00..47b96128 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -41,7 +41,8 @@ export type SkipReason =
   | 'pipe_pluralization'
   | 'key_collision'
   | 'unusable_target'
-  | 'untranslated';
+  | 'untranslated'
+  | 'needs_review';
 
 export interface SkippedRecord {
   file: string;
@@ -68,6 +69,7 @@ const SKIP_REASON_LABELS: Record<SkipReason, string> = {
   key_collision: 'target file keys collide (left untouched)',
   unusable_target: 'target file could not be read (left untouched)',
   untranslated: 'no translation in the target file',
+  needs_review: 'translation marked as needing review (not pushed)',
 };
 
 /**
@@ -121,6 +123,12 @@ export async function pushTranslations(
         let entries: ExtractedEntry[];
         let skippedEntries: ExtractedEntry[];
         let translations: Map<string, string>;
+        /**
+         * Keys whose translation the format's own toolchain will not ship — a
+         * `#, fuzzy` msgstr is the case. Uploading one would make the TMS the
+         * authority for a string a reviewer has marked as not ready.
+         */
+        let needsReview: Set<string>;
         if (isMultiLocale) {
           ({ entries, skippedEntries } = partitionEntries(
             parser.extract(sourceContent, locale)
@@ -130,6 +138,8 @@ export async function pushTranslations(
             sourceContent,
             locale
           );
+          needsReview =
+            parser.extractNeedsReview?.(sourceContent, locale) ?? new Set();
         } else {
           const targetPath = resolveTargetPath(
             relPath,
@@ -144,6 +154,7 @@ export async function pushTranslations(
             parser.extract(content)
           ));
           translations = extractExistingTranslations(parser, content);
+          needsReview = parser.extractNeedsReview?.(content) ?? new Set();
         }
         for (const skippedEntry of skippedEntries) {
           skipped.push({
@@ -169,6 +180,15 @@ export async function pushTranslations(
             });
             continue;
           }
+          if (needsReview.has(entry.key)) {
+            skipped.push({
+              file: relPath,
+              locale,
+              reason: 'needs_review',
+              key: entry.key,
+            });
+            continue;
+          }
           pushable.push({ entry, translation });
         }
         await mapWithConcurrency(
diff --git a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
index 27d97518..0ba7567c 100644
--- a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
+++ b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
@@ -188,4 +188,46 @@ describe('CLI sync with a bilingual target file', () => {
     expect(xlf).toContain('<target>REVIEWED-XLF</target>');
     expect(xlf).not.toContain('<target>Hello</target>');
   }, 120000);
+
+  it('reports a fuzzy msgstr as needing review rather than as complete', () => {
+    // Runs after the test above, so the lockfile calls both PO keys translated.
+    fs.writeFileSync(
+      poTarget(),
+      fs
+        .readFileSync(poTarget(), 'utf-8')
+        .replace('msgid "Translate me"', '#, fuzzy\nmsgid "Translate me"')
+    );
+
+    const { CI: _ci, DEEPL_API_KEY: _key, ...rest } = process.env;
+    const status = spawnSync(
+      'node',
+      [CLI_PATH, 'sync', 'status', '--format', 'json'],
+      {
+        encoding: 'utf-8',
+        cwd: testFiles.path,
+        env: { ...rest, DEEPL_CONFIG_DIR: testConfig.path, NO_COLOR: '1' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 60000,
+      }
+    );
+
+    expect(status.status).toBe(0);
+    const parsed = JSON.parse(status.stdout) as {
+      locales: { locale: string; needsReview: number; coverage: number }[];
+    };
+    const es = parsed.locales.find((l) => l.locale === 'es')!;
+    expect(es.needsReview).toBe(1);
+    expect(es.coverage).toBeLessThan(100);
+
+    const text = spawnSync('node', [CLI_PATH, 'sync', 'status'], {
+      encoding: 'utf-8',
+      cwd: testFiles.path,
+      env: { ...rest, DEEPL_CONFIG_DIR: testConfig.path, NO_COLOR: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60000,
+    });
+    const output = (text.stdout ?? '') + (text.stderr ?? '');
+    expect(output).toContain('1 needs review');
+    expect(output).toContain('msgfmt');
+  }, 120000);
 });
diff --git a/tests/integration/sync-bilingual-target.integration.test.ts b/tests/integration/sync-bilingual-target.integration.test.ts
index 3c9a8e37..d9989dcd 100644
--- a/tests/integration/sync-bilingual-target.integration.test.ts
+++ b/tests/integration/sync-bilingual-target.integration.test.ts
@@ -26,9 +26,11 @@ import nock from 'nock';
 import { createTmsClient } from '../../src/sync/tms-client';
 import { pushTranslations, pullTranslations } from '../../src/sync/sync-tms';
 import { validateTranslations } from '../../src/sync/sync-validate';
+import { computeSyncStatus } from '../../src/sync/sync-status';
 import { loadSyncConfig } from '../../src/sync/sync-config';
 
 import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
 import {
   TMS_BASE,
   TMS_PROJECT,
@@ -194,6 +196,89 @@ describe('sync paths that read a bilingual target file', () => {
         },
       ]);
     });
+
+    it('skips a fuzzy translation rather than uploading it as approved', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        tms: tmsConfig(),
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hello"\nmsgstr ""\n\nmsgid "Bye"\nmsgstr ""\n'
+      );
+      write(
+        tmpDir,
+        'locales/es/app.po',
+        PO_HEADER +
+          'msgid "Hello"\nmsgstr "Hola"\n\n#, fuzzy\nmsgid "Bye"\nmsgstr "Adios"\n'
+      );
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+      const sent: Record<string, string> = {};
+      nock(TMS_BASE)
+        .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
+        .times(2)
+        .reply(200, function reply(uri: string, body: unknown) {
+          sent[decodeURIComponent(uri.split('/keys/')[1]!)] = (
+            body as { value: string }
+          ).value;
+          return {};
+        });
+
+      const result = await pushTranslations(config, client, harness.registry);
+
+      expect(Object.keys(sent)).toEqual(['Hello']);
+      expect(result.pushed).toBe(1);
+      expect(result.skipped).toEqual([
+        {
+          file: 'locales/en/app.po',
+          locale: 'es',
+          reason: 'needs_review',
+          key: 'Bye',
+        },
+      ]);
+    });
+
+    it('still pushes a translation whose only flag is not fuzzy', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        tms: tmsConfig(),
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hi %s"\nmsgstr ""\n'
+      );
+      write(
+        tmpDir,
+        'locales/es/app.po',
+        PO_HEADER + '#, python-format\nmsgid "Hi %s"\nmsgstr "Hola %s"\n'
+      );
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+      const sent: Record<string, string> = {};
+      nock(TMS_BASE)
+        .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
+        .reply(200, function reply(uri: string, body: unknown) {
+          sent[decodeURIComponent(uri.split('/keys/')[1]!)] = (
+            body as { value: string }
+          ).value;
+          return {};
+        });
+
+      const result = await pushTranslations(config, client, harness.registry);
+
+      expect(result.pushed).toBe(1);
+      expect(sent['Hi %s']).toBe('Hola %s');
+      expect(result.skipped).toEqual([]);
+    });
   });
 
   describe('validate', () => {
@@ -286,4 +371,110 @@ describe('sync paths that read a bilingual target file', () => {
       expect(written).not.toContain('msgstr "Hello"');
     });
   });
+
+  describe('status', () => {
+    /** A synced project, then one entry marked fuzzy with the source unchanged. */
+    async function syncedThenFlagged(): Promise<void> {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hello"\nmsgstr ""\n\nmsgid "Bye"\nmsgstr ""\n'
+      );
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .times(4)
+        .reply(200, (_uri, body) => {
+          const parsed = new URLSearchParams(body as string);
+          return {
+            translations: parsed.getAll('text').map((t) => ({
+              text: `[es]${t}`,
+              detected_source_language: 'EN',
+              billed_characters: t.length,
+            })),
+          };
+        });
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+      const target = path.join(tmpDir, 'locales/es/app.po');
+      fs.writeFileSync(
+        target,
+        fs
+          .readFileSync(target, 'utf-8')
+          .replace('msgid "Bye"', '#, fuzzy\nmsgid "Bye"'),
+        'utf-8'
+      );
+    }
+
+    it('does not count a fuzzy msgstr as complete, the way msgfmt does not', async () => {
+      await syncedThenFlagged();
+
+      const status = await computeSyncStatus(
+        await loadSyncConfig(tmpDir),
+        harness.registry
+      );
+
+      const es = status.locales.find((l) => l.locale === 'es')!;
+      expect(es.needsReview).toBe(1);
+      expect(es.complete).toBe(1);
+      expect(es.coverage).toBe(50);
+      expect(es.missing).toBe(0);
+      expect(es.unwritten).toBe(0);
+    });
+
+    it('leaves the reviewer draft on disk and bills nothing to report it', async () => {
+      await syncedThenFlagged();
+      const before = fs.readFileSync(
+        path.join(tmpDir, 'locales/es/app.po'),
+        'utf-8'
+      );
+
+      const result = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(result.totalCharactersBilled).toBe(0);
+      expect(
+        fs.readFileSync(path.join(tmpDir, 'locales/es/app.po'), 'utf-8')
+      ).toBe(before);
+    });
+
+    it('reports a project with no flags exactly as before', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER + 'msgid "Hello"\nmsgstr ""\n\nmsgid "Bye"\nmsgstr ""\n'
+      );
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .times(4)
+        .reply(200, (_uri, body) => {
+          const parsed = new URLSearchParams(body as string);
+          return {
+            translations: parsed.getAll('text').map((t) => ({
+              text: `[es]${t}`,
+              detected_source_language: 'EN',
+              billed_characters: t.length,
+            })),
+          };
+        });
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      const status = await computeSyncStatus(
+        await loadSyncConfig(tmpDir),
+        harness.registry
+      );
+
+      const es = status.locales.find((l) => l.locale === 'es')!;
+      expect(es.needsReview).toBe(0);
+      expect(es.complete).toBe(2);
+      expect(es.coverage).toBe(100);
+    });
+  });
 });
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index 84ae071d..b8457764 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -480,6 +480,78 @@ describe('PoFormatParser — entries with no blank line between them', () => {
     ]);
   });
 
+  describe('extractNeedsReview', () => {
+    it('names a key whose translation is flagged fuzzy', () => {
+      const po = [
+        HEADER,
+        'msgid "Hello"',
+        'msgstr "Hola"',
+        '',
+        '#, fuzzy',
+        'msgid "Good morning"',
+        'msgstr "Buenas"',
+        '',
+      ].join('\n');
+
+      expect([...parser.extractNeedsReview(po)]).toEqual(['Good morning']);
+    });
+
+    it('still returns the flagged translation from extractTranslations', () => {
+      // A run must carry a reviewer's draft forward, not overwrite it.
+      const po = [
+        HEADER,
+        '#, fuzzy',
+        'msgid "Good morning"',
+        'msgstr "Buenas"',
+        '',
+      ].join('\n');
+
+      expect(parser.extractTranslations(po).get('Good morning')).toBe('Buenas');
+    });
+
+    it('leaves a fuzzy entry with no translation out, since it is simply missing', () => {
+      const po = [
+        HEADER,
+        '#, fuzzy',
+        'msgid "Good morning"',
+        'msgstr ""',
+        '',
+      ].join('\n');
+
+      expect([...parser.extractNeedsReview(po)]).toEqual([]);
+    });
+
+    it('keeps a key whose other flags do not mean needs-review', () => {
+      const po = [
+        HEADER,
+        '#, python-format',
+        'msgid "Hi %s"',
+        'msgstr "Hola %s"',
+        '',
+      ].join('\n');
+
+      expect([...parser.extractNeedsReview(po)]).toEqual([]);
+    });
+
+    it('names a flagged key that carries other flags too', () => {
+      const po = [
+        HEADER,
+        '#, fuzzy, python-format',
+        'msgid "Hi %s"',
+        'msgstr "Hola %s"',
+        '',
+      ].join('\n');
+
+      expect([...parser.extractNeedsReview(po)]).toEqual(['Hi %s']);
+    });
+
+    it('says nothing about a catalog with no flags at all', () => {
+      const po = [HEADER, 'msgid "Hello"', 'msgstr "Hola"', ''].join('\n');
+
+      expect([...parser.extractNeedsReview(po)]).toEqual([]);
+    });
+  });
+
   it('keeps the header and its charset when the first message follows it directly', () => {
     const po = [HEADER, 'msgid "Hello"', 'msgstr "REVIEWED"', ''].join('\n');
 

From 2bb3e277de284c54b5be871e4d728bc8de14b424 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 08:07:55 +0200
Subject: [PATCH 179/256] fix(watch,sync): ignore in-flight atomic-write temps;
 call a failed key missing

Two cosmetic residuals from the verdict pass over the ten recorded in earlier
close reasons. The other eight ended as wontfix or were promoted to their own
beads.

atomicWriteFile renames from a <target>.tmp.<pid>.<random> sibling, which
must sit beside its target for the rename to be atomic, so a watcher on the
output directory sees it. Its name carries the output file's, so the
output-file check matched it and the session advised the user to move a file
this process had already renamed away. Such a path is now recognised as an
in-flight write and ignored before that check.

sync status counted a failed translation as outdated, which is documented as
"recorded against an older source". A failed attempt is recorded against the
current source and produced no translation at all, so missing is the honest
word. --frozen computes its gating from the source diff and is unaffected.

Refs cli-8kr2.69
---
 CHANGELOG.md                        |  4 ++
 docs/SYNC.md                        |  2 +-
 src/services/watch.ts               |  8 ++++
 src/sync/sync-status.ts             | 13 +++---
 src/utils/atomic-write.ts           | 18 ++++++++
 tests/unit/services/watch.test.ts   | 38 +++++++++++++++++
 tests/unit/sync/sync-status.test.ts | 66 +++++++++++++++++++++++++++++
 7 files changed, 143 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c995fdc..854a1141 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -145,6 +145,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **the loop guard no longer warns about the temp file the CLI is writing through.** `atomicWriteFile` renames from a `<target>.tmp.<pid>.<random>` sibling, which has to sit beside its target because a rename is only atomic within one filesystem — so a watcher on the output directory sees it appear and vanish. Its name carries the output file's, so the output-file check matched it and the session printed `Skipping …/doc.es.md.tmp.4242.a1b2c3: it is inside the output directory and named like a translated output … Move it outside …` about a file that this process had already renamed away, telling the user to move something that no longer exists. Such a path is now recognised as an in-flight write and ignored, before the output-file check. A real output-looking file the user put there still gets its one warning.
+
+- **sync**: **`sync status` counts a failed translation as `missing` rather than `outdated`.** `outdated` is documented as "recorded against an older source"; a failed attempt is recorded against the **current** source and produced no translation at all, so the count named the wrong problem — a reader chasing an outdated string would go looking for a source change that never happened. `missing` and `outdated` therefore both move for a project with failed translations in its lockfile. Nothing else changes: `--frozen` computes its own gating from the source diff and is unaffected, and a genuinely stale hash is still `outdated`.
+
 - **sync**: **a gettext `#, fuzzy` translation is no longer counted as complete.** Every read path treated the msgstr of a fuzzy entry as a finished translation, but `fuzzy` is gettext's way of saying "needs review, do not use": `msgfmt` leaves the entry out of the compiled catalog, so the string the CLI called done is one the application does not display. Measured against that oracle on a two-key PO catalog with one entry flagged and its source unchanged — `msgfmt --statistics` said `1 translated message, 1 fuzzy translation` while `deepl sync status` said `100% (0 missing, 0 outdated)`, `complete: 2`, `unwritten: 0`, `sync --dry-run` said `2 current`, `deepl sync` made **0 requests**, and `sync validate` said `All translations passed validation`. So a project shipping an untranslated string reported as finished, indefinitely. Such a key is now its own **`needsReview`** category in `sync status` (text suffix `, 1 needs review` plus a line explaining the flag and both ways out; `needsReview` on each locale in `--format json`), and the same catalog now reports `50%`, agreeing with `msgfmt`. `deepl sync push` skips it under a new **`needs_review`** skip reason instead of uploading a reviewer's draft as an approved translation. **Nothing is re-translated and nothing is rewritten**: the value belongs to whoever flagged it, so reading it as untranslated would have replaced a human's in-progress work with machine output and re-billed every fuzzy entry in the project — the one outcome worse than an overstated percentage. Both documented remedies were measured end to end: removing the flag returns the key to `complete` (`msgfmt`: `2 translated messages`), and clearing the msgstr has the next `deepl sync` translate it afresh. `sync --frozen` deliberately still passes, since a fuzzy entry is a normal transient state in a gettext workflow that only a human review clears. XLIFF's `state="needs-review-translation"` is the same idea in the other bilingual format and is tracked separately: its states differ between 1.2 and 2.0 and no external tool arbitrates which of them mean "will not ship", where `msgfmt` settles it for PO.
 
 - **sync**: **`--dry-run` now previews the run rather than the lockfile, in both directions it was wrong.** The dry-run branch returned before the two target-file checks the real run makes, so the estimate came from the lockfile alone. Measured against a real endpoint on a JSON project with one damaged locale. **Under-reporting:** with a key the lockfile calls translated deleted from the target file, `deepl sync --dry-run` reported `Sync complete: 2 current`, `estimatedCharacters: 0` and no cost line at all, while the very next real run translated it — `✓ es: 1/1 keys`. **Over-reporting:** with a new source key added and the target file left unreadable, dry-run reported `estimatedCharacters: 12` and `ok: true` at exit 0, and said nothing about the file; the real run refused the locale, billed **0**, reported `failed: 3` and exited **12**. So the one command whose job is deciding whether to spend money under-quoted repair work and over-quoted work that was never going to happen. Both halves now come from one `findTargetGaps` call per source file — the machinery `--frozen` already uses, which returns the missing keys and the unreadable reason from the same read: keys the target no longer holds are added to the estimate and reported as `unwrittenKeys`, and a locale whose target file is unreadable is left out of the estimate and named in its own warning ending `It is left out of the estimate below. Fix it before running \`deepl sync\`.` A dry run still writes nothing — no target file, no lockfile, no backup — and still exits 0, since it reports what a run would do rather than standing in for its exit code, which is what `--frozen` is for. Because the summary counts a repair key as `current`, the run now also says `1 key is recorded as translated in the lock file but could not be confirmed in the target file, so a real run would translate it again`, so the character estimate is not a number with nothing behind it. **The bead's suggested cheap option was based on a wrong premise**: warning about an unreadable target "without paying for a full audit" costs exactly the same reads, because a file cannot be known to be unreadable without opening it, and the gap keys fall out of that same read for free. **Cost, measured** on a 20,000-key, 6-locale JSON project (2.83 MiB source, 17.3 MiB of targets, 24 MiB lockfile): `--dry-run` 0.44 s → 0.75 s, against 0.77 s for `sync status` and 0.79 s for `sync --frozen`; peak RSS 283 MiB → 370 MiB. A locale the lockfile claims nothing for is not read at all, so a project mid-first-sync pays nothing.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 68f2858e..e7c16e3c 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -134,7 +134,7 @@ Two cases are deliberately left out, because writing them would mean inventing s
 
 Whatever the reason a key does not land, the run says so rather than recording it as translated. Every key is read back out of the content just written before the lockfile is updated, so a key the file does not hold is recorded `failed`: the run warns naming the file, the locale and the key, reports `✗ es: 0/1 keys` and exits **12** (`PartialFailure`), `deepl sync status` counts it against the locale, and `deepl sync --frozen` exits **10**. The next sync retries it.
 
-**A target file is also checked against what the lock file claims about it.** For every key the lock file records as `translated` against the current source text, `deepl sync status` and `deepl sync --frozen` open the locale's target file and check that the translation is in it. A key it does not hold is counted **`unwritten`** — a category of its own, distinct from `missing` (absent from the lock file) and `outdated` (recorded against an older source), and never counted as complete:
+**A target file is also checked against what the lock file claims about it.** For every key the lock file records as `translated` against the current source text, `deepl sync status` and `deepl sync --frozen` open the locale's target file and check that the translation is in it. A key it does not hold is counted **`unwritten`** — a category of its own, distinct from `missing` (absent from the lock file, or recorded as a failed attempt) and `outdated` (recorded against an older source), and never counted as complete:
 
 ```
 $ deepl sync status
diff --git a/src/services/watch.ts b/src/services/watch.ts
index 452ee5ab..0551fd8a 100644
--- a/src/services/watch.ts
+++ b/src/services/watch.ts
@@ -14,6 +14,7 @@ import { Logger } from '../utils/logger.js';
 import { ValidationError } from '../utils/errors.js';
 import { errorMessage } from '../utils/error-message.js';
 import { canonicalPathKey, isWithinDirectory } from '../utils/paths.js';
+import { isAtomicWriteTempPath } from '../utils/atomic-write.js';
 
 export interface FileTranslationResult {
   targetLang: Language;
@@ -218,6 +219,13 @@ export class WatchService {
       return;
     }
 
+    // A temp sibling of an in-flight atomic write is this process mid-write. It
+    // carries the output file's name plus a suffix, so the output-file check
+    // below would match it and warn about a file that is already gone.
+    if (isAtomicWriteTempPath(filePath)) {
+      return;
+    }
+
     // Check if file is a translated output file to prevent infinite loops
     if (this.isTranslatedOutputFile(filePath)) {
       this.warnOnceAboutSkippedOutput(filePath);
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index 1c9ccba1..3b6ebbd6 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -142,15 +142,18 @@ export async function computeSyncStatus(
         const translation = lockEntry?.translations[locale];
         const hasTranslation = translation !== undefined;
         // Judge staleness for THIS locale rather than inheriting the shared
-        // source-level status: a locale whose stored hash lags behind, or whose
-        // last attempt failed, is outdated even when the source is unchanged.
+        // source-level status: a locale whose stored hash lags behind is
+        // outdated even when the source is unchanged.
         const localeOutdated =
           lockEntry !== undefined &&
           translation !== undefined &&
-          (translation.status === 'failed' ||
-            translation.hash !== lockEntry.source_hash);
+          translation.hash !== lockEntry.source_hash;
+        // A failed attempt is recorded against the CURRENT source and produced
+        // no translation at all, so `outdated` — documented as recorded against
+        // an older source — would describe the wrong problem.
+        const localeFailed = translation?.status === 'failed';
 
-        if (diff.status === 'new' || !hasTranslation) {
+        if (diff.status === 'new' || !hasTranslation || localeFailed) {
           stats.missing++;
         } else if (diff.status === 'stale' || localeOutdated) {
           stats.outdated++;
diff --git a/src/utils/atomic-write.ts b/src/utils/atomic-write.ts
index b77447e5..39c4bd50 100644
--- a/src/utils/atomic-write.ts
+++ b/src/utils/atomic-write.ts
@@ -73,6 +73,24 @@ export function __getInFlightTmpCount(): number {
   return inFlightTmpPaths.size;
 }
 
+/**
+ * The `.tmp.<pid>.<random>` sibling `atomicWriteFile` renames from. It has to sit
+ * beside its target, since a rename is only atomic within one filesystem, which
+ * means anything watching the target's directory sees it appear and vanish.
+ */
+const TMP_SIBLING_PATTERN = /\.tmp\.\d+\.[a-z0-9]+$/;
+
+/**
+ * Whether `filePath` is a temp sibling of an in-flight atomic write.
+ *
+ * A watcher observing an output directory needs this: such a file is this
+ * process mid-write, not a document, so it is neither something to translate nor
+ * something to tell the user about.
+ */
+export function isAtomicWriteTempPath(filePath: string): boolean {
+  return TMP_SIBLING_PATTERN.test(filePath);
+}
+
 /**
  * Write a file atomically by writing to a temp file then renaming.
  * Prevents partial writes from corrupting output files. An existing
diff --git a/tests/unit/services/watch.test.ts b/tests/unit/services/watch.test.ts
index b2d625cc..25bb2462 100644
--- a/tests/unit/services/watch.test.ts
+++ b/tests/unit/services/watch.test.ts
@@ -1134,6 +1134,44 @@ describe('WatchService', () => {
     });
   });
 
+  describe('atomic-write temp files', () => {
+    it('says nothing about the temp file it is writing through', () => {
+      const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+      const outputDir = path.join(testDir, 'output');
+      fs.mkdirSync(outputDir, { recursive: true });
+
+      const onChange = jest.fn();
+      watchService.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir,
+        onChange,
+      });
+      // The shape atomicWriteFile writes through: <target>.tmp.<pid>.<rand>
+      watchService.handleFileChange(
+        path.join(outputDir, 'doc.es.md.tmp.4242.a1b2c3')
+      );
+
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(onChange).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+
+    it('still says why it skips a real output-looking file', () => {
+      const warnSpy = jest.spyOn(Logger, 'warn').mockImplementation(() => {});
+      const outputDir = path.join(testDir, 'output');
+      fs.mkdirSync(outputDir, { recursive: true });
+
+      watchService.watch(testDir, {
+        targetLangs: ['es' as const],
+        outputDir,
+      });
+      watchService.handleFileChange(path.join(outputDir, 'doc.es.md'));
+
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      warnSpy.mockRestore();
+    });
+  });
+
   describe('translated output file filtering', () => {
     it('should ignore files that match translated output pattern (e.g. test.es.txt)', async () => {
       const testFile = path.join(testDir, 'test.es.txt');
diff --git a/tests/unit/sync/sync-status.test.ts b/tests/unit/sync/sync-status.test.ts
index 80d18601..e843cf73 100644
--- a/tests/unit/sync/sync-status.test.ts
+++ b/tests/unit/sync/sync-status.test.ts
@@ -157,6 +157,72 @@ describe('computeSyncStatus', () => {
     expect(result.locales[1]!.locale).toBe('fr');
   });
 
+  it('counts a failed translation as missing rather than outdated', async () => {
+    // `outdated` is documented as "recorded against an older source". A failed
+    // attempt is recorded against the CURRENT source and produced no
+    // translation at all, so the honest word for it is missing.
+    mockComputeDiff.mockReturnValue([
+      { key: 'greeting', status: 'current', value: 'Hello' },
+    ]);
+    (SyncLockManager as jest.Mock).mockImplementation(() => ({
+      read: jest.fn().mockResolvedValue({
+        entries: {
+          'locales/en.json': {
+            greeting: {
+              source_hash: 'a',
+              source_text: 'Hello',
+              translations: {
+                de: { hash: 'a', translated_at: '', status: 'failed' },
+              },
+            },
+          },
+        },
+        source_locale: 'en',
+        version: 1,
+        _comment: '',
+        generated_at: '',
+        stats: { total_keys: 1, total_translations: 0, last_sync: '' },
+      }),
+    }));
+    const parser = makeParser();
+    const result = await computeSyncStatus(makeConfig(), makeRegistry(parser));
+    const deStats = result.locales[0]!;
+    expect(deStats.missing).toBe(1);
+    expect(deStats.outdated).toBe(0);
+    expect(deStats.complete).toBe(0);
+  });
+
+  it('still counts a stale hash as outdated', async () => {
+    mockComputeDiff.mockReturnValue([
+      { key: 'greeting', status: 'current', value: 'Hello' },
+    ]);
+    (SyncLockManager as jest.Mock).mockImplementation(() => ({
+      read: jest.fn().mockResolvedValue({
+        entries: {
+          'locales/en.json': {
+            greeting: {
+              source_hash: 'NEW',
+              source_text: 'Hello',
+              translations: {
+                de: { hash: 'OLD', translated_at: '', status: 'translated' },
+              },
+            },
+          },
+        },
+        source_locale: 'en',
+        version: 1,
+        _comment: '',
+        generated_at: '',
+        stats: { total_keys: 1, total_translations: 1, last_sync: '' },
+      }),
+    }));
+    const parser = makeParser();
+    const result = await computeSyncStatus(makeConfig(), makeRegistry(parser));
+    const deStats = result.locales[0]!;
+    expect(deStats.outdated).toBe(1);
+    expect(deStats.missing).toBe(0);
+  });
+
   it('should not count deleted diffs in coverage stats', async () => {
     mockComputeDiff.mockReturnValue([
       { key: 'greeting', status: 'current', value: 'Hello' },

From 0df2a9b0b8c2271c9fa6d78bd0d9fac86b65cc19 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 08:36:08 +0200
Subject: [PATCH 180/256] fix(watch): give each watched source its own output
 directory

The output path was built from the source's basename alone, so every doc.md
under a watched tree mapped to one <output>/doc.es.md and the last translation
to finish silently replaced the ones before it, at exit 0 with the summary
still counting both. The output now carries the source's directory relative to
the watched path, which is the layout deepl translate <dir> --output <dir>
already produced.

Three call sites flattened, not the one: the single-target path built the name
itself, and the multi-target path handed a bare output directory to
FileTranslationService.translateFileToMultiple for text files and to
StructuredFileTranslationService for JSON and YAML, each of which applied the
same rule. A path outside the watched root has no directory to mirror and
stays at the top.

Refs cli-8kr2.74
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   1 +
 src/services/watch.ts                         |  34 ++-
 .../watch-output-layout.integration.test.ts   | 240 ++++++++++++++++++
 tests/unit/services/watch.test.ts             | 122 +++++++++
 5 files changed, 399 insertions(+), 2 deletions(-)
 create mode 100644 tests/integration/watch-output-layout.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 854a1141..ba6b1668 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **watch**: **`deepl watch` writes a nested source file to a nested output path.** Watching `docs/` with `--output out`, `docs/guide/intro.md` now lands at `out/guide/intro.es.md` where it used to land at `out/intro.es.md`. Anything reading a watch session's output by flat basename — a publish step, a `.gitignore` entry, an `--auto-commit` diff — has to follow the directory it now sits in. A file at the top of the watched directory, and a watched path that is a single file, are unchanged, so a single-directory or single-file session sees no difference. The layout is the one `deepl translate <dir> --output <dir>` has always produced. See Fixed.
+
 - **sync**: **`deepl sync status` reports a lower coverage percentage for a PO project holding `#, fuzzy` entries**, and each locale in `--format json` gains a `needsReview` count. A dashboard or CI check reading `coverage` or `complete` out of that command will see a project it called 100% drop to whatever share of its keys are actually shippable — which is what `msgfmt` has been reporting all along. `deepl sync push` reports a new `needs_review` skip reason, so its pushed count falls by the number of fuzzy entries. Nothing is re-translated, rewritten or re-billed, and `sync --frozen` still passes. See Fixed.
 
 - **sync**: **a project that sets `sync.max_characters` can now be refused where it previously ran**, and `deepl sync --dry-run` can now report a larger character estimate than before for the same input. Both follow from the cap and the preview finally counting repair work — keys the lockfile calls translated that the target file no longer holds — which a real run translates and bills. A pipeline whose cap was tuned against the old under-count will need it raised to the number `--dry-run` now reports, which is the number that run actually spends. `--dry-run` still exits 0 and still writes nothing. See Fixed.
@@ -145,6 +147,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **two watched files with the same name no longer write one translation on top of the other.** The output path was built from the source's basename alone, so every `doc.md` under the watched tree mapped to one `<output>/doc.es.md` and the last translation to finish silently replaced the ones before it — the whole of the losing file's translated output gone, at exit 0, with no warning and nothing in the summary to notice: the count still read `Translations: 2`. Measured on a watched tree holding `a/doc.md` ("Hello") and `b/doc.md` ("Good morning") with `--to es`: `translateFile` was called twice with the same `out/doc.es.md`, `out/` held one file, and its contents were `b/doc.md`'s translation. The output now carries the source's directory relative to the watched path, so those two write `out/a/doc.es.md` and `out/b/doc.es.md` — both texts, at 2 API calls, unchanged from before. The same flattening ran on **three** paths, not the one: the single-target path built the name itself, and the multi-target path (`--to es,fr`) handed a bare output directory to `FileTranslationService.translateFileToMultiple` for text files and to `StructuredFileTranslationService` for JSON and YAML, each of which then applied the same basename rule. All three now take the per-source directory. Verified end to end through the CLI against a mock API with the **default** output directory (`<watched>/translations`, which sits inside the watched tree): both translations landed under their own subdirectory, `translateCalls` settled at 2 with no further activity, so the loop guard still recognises a nested output as the CLI's own work and does not re-translate it. The layout is what `deepl translate <dir> --output <dir>` already produced — measured on the same fixture, which wrote `out/a/doc.es.md` and `out/b/doc.es.md` — so watch was the one command flattening. See Changed for the paths that move.
+
 - **watch**: **the loop guard no longer warns about the temp file the CLI is writing through.** `atomicWriteFile` renames from a `<target>.tmp.<pid>.<random>` sibling, which has to sit beside its target because a rename is only atomic within one filesystem — so a watcher on the output directory sees it appear and vanish. Its name carries the output file's, so the output-file check matched it and the session printed `Skipping …/doc.es.md.tmp.4242.a1b2c3: it is inside the output directory and named like a translated output … Move it outside …` about a file that this process had already renamed away, telling the user to move something that no longer exists. Such a path is now recognised as an in-flight write and ignored, before the output-file check. A real output-looking file the user put there still gets its one warning.
 
 - **sync**: **`sync status` counts a failed translation as `missing` rather than `outdated`.** `outdated` is documented as "recorded against an older source"; a failed attempt is recorded against the **current** source and produced no translation at all, so the count named the wrong problem — a reader chasing an outdated string would go looking for a source change that never happened. `missing` and `outdated` therefore both move for a project with failed translations in its lockfile. Nothing else changes: `--frozen` computes its own gating from the source diff and is unaffected, and a genuinely stale hash is still `outdated`.
diff --git a/docs/API.md b/docs/API.md
index 472a6464..e0c10aa7 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1115,6 +1115,7 @@ Monitor files or directories for changes and automatically translate them. Suppo
 - Debounces rapid changes to avoid duplicate translations
 - Translates one version of a file at a time. An edit arriving while a file's translation is still running queues exactly one re-translation, which starts after the running one has written. Two translations of the same file never overlap, so a slower translation of older content cannot overwrite a newer one, and an edit storm costs two translations rather than one per event
 - Skips files inside the output directory whose name carries a target-language segment (`doc.es.md` with `--to es`), so the CLI's own output does not re-trigger the watcher. The check is limited to the output directory, so a *source* file named that way — `pricing.es.md` translated to `es` — is translated normally as long as it lives outside it. When such a file is skipped and the CLI did not write it, the reason is printed once per file
+- Mirrors each source file's directory under the output directory, relative to the watched path: watching `docs/` writes `docs/a/index.md` to `<output>/a/index.es.md` and `docs/b/index.md` to `<output>/b/index.es.md`. This is the same layout `deepl translate <dir> --output <dir>` produces, and it is what keeps two same-named files in different directories from writing one output path. A file at the top of the watched directory, and a watched path that is a single file, write straight into the output directory as before
 
 #### Options
 
diff --git a/src/services/watch.ts b/src/services/watch.ts
index 0551fd8a..5b562873 100644
--- a/src/services/watch.ts
+++ b/src/services/watch.ts
@@ -80,6 +80,7 @@ export class WatchService {
   private watcher: FSWatcher | null = null;
   private options: WatchServiceOptions;
   private watchOptions: WatchOptions | null = null;
+  private watchRoot = '';
   private debounceTimers: Map<string, NodeJS.Timeout> = new Map();
   private activeTranslations: Set<string> = new Set();
   private pendingTranslations: Set<string> = new Set();
@@ -115,6 +116,13 @@ export class WatchService {
     }
 
     this.watchOptions = options;
+    // The root every source path is made relative to when its output directory
+    // is built. A watched file has no tree of its own, so its directory is the
+    // root and its output stays at the top of the output directory.
+    const resolvedWatchPath = path.resolve(watchPath);
+    this.watchRoot = fs.statSync(resolvedWatchPath).isDirectory()
+      ? resolvedWatchPath
+      : path.dirname(resolvedWatchPath);
 
     // Create watcher
     const watcherOptions: {
@@ -379,6 +387,26 @@ export class WatchService {
     );
   }
 
+  /**
+   * Output directory for one source file.
+   *
+   * Every translation a session writes lands under the one output directory, so
+   * the source's directory relative to the watched root is carried over: named
+   * by basename alone, two same-named files in different directories write the
+   * same output path and the second translation replaces the first. This is the
+   * layout `deepl translate <dir> --output <dir>` already produces. A path
+   * outside the watched root has no directory to mirror, so it stays at the top.
+   */
+  private outputDirFor(filePath: string, outputDir: string): string {
+    const relativeDir = path.dirname(
+      path.relative(this.watchRoot, path.resolve(filePath))
+    );
+    if (relativeDir === '.' || relativeDir.startsWith('..')) {
+      return outputDir;
+    }
+    return path.join(outputDir, relativeDir);
+  }
+
   /**
    * Translate a file with the configured options
    */
@@ -414,12 +442,13 @@ export class WatchService {
     // Determine output path(s)
     const fileName = path.basename(filePath, path.extname(filePath));
     const ext = path.extname(filePath);
+    const fileOutputDir = this.outputDirFor(filePath, outputDir);
 
     if (targetLangs.length === 1) {
       // Single target language (length === 1 guarantees targetLangs[0] exists)
       const targetLang = targetLangs[0]!;
       const outputPath = path.join(
-        outputDir,
+        fileOutputDir,
         `${fileName}.${targetLang}${ext}`
       );
 
@@ -445,7 +474,7 @@ export class WatchService {
       const results = await this.fileTranslationService.translateFileToMultiple(
         filePath,
         targetLangs as Language[],
-        { ...baseOptions, outputDir, preserveCode }
+        { ...baseOptions, outputDir: fileOutputDir, preserveCode }
       );
 
       for (const result of results) {
@@ -467,6 +496,7 @@ export class WatchService {
   async stop(): Promise<void> {
     this.stats.isWatching = false;
     this.watchOptions = null;
+    this.watchRoot = '';
 
     for (const timer of this.debounceTimers.values()) {
       clearTimeout(timer);
diff --git a/tests/integration/watch-output-layout.integration.test.ts b/tests/integration/watch-output-layout.integration.test.ts
new file mode 100644
index 00000000..0296db43
--- /dev/null
+++ b/tests/integration/watch-output-layout.integration.test.ts
@@ -0,0 +1,240 @@
+/**
+ * Integration tests for the watch output layout.
+ *
+ * Every translation a watch session writes lands under one output directory, so
+ * the output path has to carry the source's directory as well as its name:
+ * flattening to the basename made two same-named sources in different
+ * directories write the same file. The layout mirrors what
+ * `deepl translate <dir> --output <dir>` already produces. Real files and a
+ * real write path; only the translation call is stubbed.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.mock('p-limit', () => ({
+  __esModule: true,
+  default: (_concurrency: number) => {
+    return (fn: () => Promise<unknown>) => fn();
+  },
+}));
+
+import { WatchService } from '../../src/services/watch.js';
+import { FileTranslationService } from '../../src/services/file-translation.js';
+import { TranslationService } from '../../src/services/translation.js';
+import type { Language } from '../../src/types/index.js';
+import { createMockTranslationService } from '../helpers/mock-factories';
+
+const DEBOUNCE_MS = 20;
+
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+const filesUnder = (dir: string): string[] => {
+  const found: string[] = [];
+  const walk = (current: string, relative: string): void => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const child = path.join(current, entry.name);
+      const childRelative = path.join(relative, entry.name);
+      if (entry.isDirectory()) {
+        walk(child, childRelative);
+      } else {
+        found.push(childRelative);
+      }
+    }
+  };
+  walk(dir, '');
+  return found.sort();
+};
+
+/**
+ * Waits for the writes to land rather than sleeping a fixed span: the
+ * structured-format path imports its service on first use, which under a full
+ * suite run takes longer than any debounce multiple worth hard-coding. Returns
+ * whatever is on disk when the count is reached or the bound expires, so the
+ * assertion still reports the real listing on a genuine failure.
+ */
+const waitForFiles = async (dir: string, count: number): Promise<string[]> => {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const found = filesUnder(dir);
+    if (found.length >= count) {
+      return found;
+    }
+    await sleep(DEBOUNCE_MS);
+  }
+  return filesUnder(dir);
+};
+
+describe('Watch output layout integration', () => {
+  let tmpDir: string;
+  let sourceDir: string;
+  let outDir: string;
+  let watchService: WatchService;
+  let translationService: jest.Mocked<TranslationService>;
+
+  beforeEach(() => {
+    // Realpath because the CLI is handed the spelling below while a comparison
+    // against a path produced elsewhere would see /private/var on macOS.
+    tmpDir = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-layout-'))
+    );
+    sourceDir = path.join(tmpDir, 'src');
+    outDir = path.join(tmpDir, 'out');
+    fs.mkdirSync(sourceDir, { recursive: true });
+    fs.mkdirSync(outDir, { recursive: true });
+
+    translationService = createMockTranslationService();
+    const DEFAULT_LANG = 'es' as Language;
+    translationService.translate.mockImplementation(
+      async (text: string, options?: { targetLang?: Language }) => ({
+        text: `${options?.targetLang ?? DEFAULT_LANG}:${text}`,
+        detectedSourceLang: 'en' as Language,
+        targetLang: options?.targetLang ?? DEFAULT_LANG,
+        billedCharacters: text.length,
+      })
+    );
+    translationService.translateBatch.mockImplementation(
+      async (texts: string[], options: { targetLang: Language }) =>
+        texts.map((text) => ({
+          text: `${options.targetLang}:${text}`,
+          detectedSourceLang: 'en',
+          targetLang: options.targetLang,
+          billedCharacters: text.length,
+        }))
+    );
+    translationService.translateToMultiple.mockImplementation(
+      async (text: string, targetLangs: readonly Language[]) =>
+        targetLangs.map((targetLang) => ({
+          text: `${targetLang}:${text}`,
+          detectedSourceLang: 'en',
+          targetLang,
+          billedCharacters: text.length,
+        }))
+    );
+
+    watchService = new WatchService(
+      new FileTranslationService(translationService),
+      { debounceMs: DEBOUNCE_MS }
+    );
+  });
+
+  afterEach(async () => {
+    await watchService.stop();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const write = (relative: string, contents: string): string => {
+    const full = path.join(sourceDir, relative);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, contents);
+    return full;
+  };
+
+  it('keeps both translations when two sources share a basename', async () => {
+    const a = write(path.join('a', 'doc.md'), 'Hello\n');
+    const b = write(path.join('b', 'doc.md'), 'Good morning\n');
+
+    watchService.watch(sourceDir, { targetLangs: ['es'], outputDir: outDir });
+    watchService.handleFileChange(a);
+    watchService.handleFileChange(b);
+
+    expect(await waitForFiles(outDir, 2)).toEqual([
+      path.join('a', 'doc.es.md'),
+      path.join('b', 'doc.es.md'),
+    ]);
+    expect(fs.readFileSync(path.join(outDir, 'a', 'doc.es.md'), 'utf-8')).toBe(
+      'es:Hello\n'
+    );
+    expect(fs.readFileSync(path.join(outDir, 'b', 'doc.es.md'), 'utf-8')).toBe(
+      'es:Good morning\n'
+    );
+  });
+
+  it('keeps both translations for every target when two sources share a basename', async () => {
+    const a = write(path.join('a', 'doc.md'), 'Hello\n');
+    const b = write(path.join('b', 'doc.md'), 'Good morning\n');
+
+    watchService.watch(sourceDir, {
+      targetLangs: ['es', 'fr'],
+      outputDir: outDir,
+    });
+    watchService.handleFileChange(a);
+    watchService.handleFileChange(b);
+
+    expect(await waitForFiles(outDir, 4)).toEqual([
+      path.join('a', 'doc.es.md'),
+      path.join('a', 'doc.fr.md'),
+      path.join('b', 'doc.es.md'),
+      path.join('b', 'doc.fr.md'),
+    ]);
+    expect(fs.readFileSync(path.join(outDir, 'a', 'doc.fr.md'), 'utf-8')).toBe(
+      'fr:Hello\n'
+    );
+    expect(fs.readFileSync(path.join(outDir, 'b', 'doc.fr.md'), 'utf-8')).toBe(
+      'fr:Good morning\n'
+    );
+  });
+
+  it('keeps a structured file per source directory', async () => {
+    const a = write(path.join('a', 'app.json'), '{"greeting":"Hello"}');
+    const b = write(path.join('b', 'app.json'), '{"greeting":"Good morning"}');
+
+    watchService.watch(sourceDir, {
+      targetLangs: ['es', 'fr'],
+      outputDir: outDir,
+    });
+    watchService.handleFileChange(a);
+    watchService.handleFileChange(b);
+
+    expect(await waitForFiles(outDir, 4)).toEqual([
+      path.join('a', 'app.es.json'),
+      path.join('a', 'app.fr.json'),
+      path.join('b', 'app.es.json'),
+      path.join('b', 'app.fr.json'),
+    ]);
+    expect(
+      JSON.parse(
+        fs.readFileSync(path.join(outDir, 'b', 'app.es.json'), 'utf-8')
+      )
+    ).toEqual({ greeting: 'es:Good morning' });
+  });
+
+  it('translates each source once per target and no more', async () => {
+    const a = write(path.join('a', 'doc.md'), 'Hello\n');
+    const b = write(path.join('b', 'doc.md'), 'Good morning\n');
+
+    watchService.watch(sourceDir, { targetLangs: ['es'], outputDir: outDir });
+    watchService.handleFileChange(a);
+    watchService.handleFileChange(b);
+    await waitForFiles(outDir, 2);
+    // A settling span on top, so a third call would have arrived by now.
+    await sleep(DEBOUNCE_MS * 8);
+
+    expect(translationService.translate).toHaveBeenCalledTimes(2);
+    expect(
+      translationService.translate.mock.calls.map((call) => call[0]).sort()
+    ).toEqual(['Good morning\n', 'Hello\n']);
+  });
+
+  it('leaves a source at the top of the watched directory flat', async () => {
+    const doc = write('doc.md', 'Hello\n');
+
+    watchService.watch(sourceDir, { targetLangs: ['es'], outputDir: outDir });
+    watchService.handleFileChange(doc);
+
+    expect(await waitForFiles(outDir, 1)).toEqual(['doc.es.md']);
+    expect(fs.readFileSync(path.join(outDir, 'doc.es.md'), 'utf-8')).toBe(
+      'es:Hello\n'
+    );
+  });
+
+  it('leaves the output flat when the watched path is a single nested file', async () => {
+    const doc = write(path.join('a', 'doc.md'), 'Hello\n');
+
+    watchService.watch(doc, { targetLangs: ['es'], outputDir: outDir });
+    watchService.handleFileChange(doc);
+
+    expect(await waitForFiles(outDir, 1)).toEqual(['doc.es.md']);
+  });
+});
diff --git a/tests/unit/services/watch.test.ts b/tests/unit/services/watch.test.ts
index 25bb2462..8c1e8ebf 100644
--- a/tests/unit/services/watch.test.ts
+++ b/tests/unit/services/watch.test.ts
@@ -2040,4 +2040,126 @@ describe('WatchService', () => {
       await service.stop();
     });
   });
+
+  describe('output layout', () => {
+    const DEBOUNCE_MS = 5;
+    const settle = () =>
+      new Promise<void>((resolve) => setTimeout(resolve, DEBOUNCE_MS * 4));
+
+    let outputDir: string;
+    let service: WatchService;
+
+    beforeEach(() => {
+      outputDir = path.join(testDir, 'out');
+      fs.mkdirSync(outputDir, { recursive: true });
+      service = new WatchService(mockFileTranslationService, {
+        debounceMs: DEBOUNCE_MS,
+      });
+      mockFileTranslationService.translateFile.mockResolvedValue(undefined);
+      mockFileTranslationService.translateFileToMultiple.mockResolvedValue([]);
+    });
+
+    afterEach(async () => {
+      await service.stop();
+    });
+
+    const outputPathsOf = (): string[] =>
+      mockFileTranslationService.translateFile.mock.calls.map(
+        (call) => call[1]
+      );
+
+    it('gives two sources sharing a basename two different output paths', async () => {
+      const a = path.join(testDir, 'a', 'doc.md');
+      const b = path.join(testDir, 'b', 'doc.md');
+      fs.mkdirSync(path.dirname(a), { recursive: true });
+      fs.mkdirSync(path.dirname(b), { recursive: true });
+      fs.writeFileSync(a, 'Hello');
+      fs.writeFileSync(b, 'Good morning');
+
+      service.watch(testDir, { targetLangs: ['es'], outputDir });
+      service.handleFileChange(a);
+      service.handleFileChange(b);
+      await settle();
+
+      expect(outputPathsOf()).toEqual([
+        path.join(outputDir, 'a', 'doc.es.md'),
+        path.join(outputDir, 'b', 'doc.es.md'),
+      ]);
+    });
+
+    it('gives the multiple-target path a per-source output directory', async () => {
+      const a = path.join(testDir, 'a', 'doc.md');
+      fs.mkdirSync(path.dirname(a), { recursive: true });
+      fs.writeFileSync(a, 'Hello');
+
+      service.watch(testDir, { targetLangs: ['es', 'fr'], outputDir });
+      service.handleFileChange(a);
+      await settle();
+
+      expect(
+        mockFileTranslationService.translateFileToMultiple
+      ).toHaveBeenCalledWith(
+        a,
+        ['es', 'fr'],
+        expect.objectContaining({ outputDir: path.join(outputDir, 'a') })
+      );
+    });
+
+    it('leaves a source at the top of the watched directory flat', async () => {
+      const doc = path.join(testDir, 'doc.md');
+      fs.writeFileSync(doc, 'Hello');
+
+      service.watch(testDir, { targetLangs: ['es'], outputDir });
+      service.handleFileChange(doc);
+      await settle();
+
+      expect(outputPathsOf()).toEqual([path.join(outputDir, 'doc.es.md')]);
+    });
+
+    it('mirrors each nested source directory even when the basenames differ', async () => {
+      const a = path.join(testDir, 'a', 'one.md');
+      const b = path.join(testDir, 'b', 'two.md');
+      fs.mkdirSync(path.dirname(a), { recursive: true });
+      fs.mkdirSync(path.dirname(b), { recursive: true });
+      fs.writeFileSync(a, 'Hello');
+      fs.writeFileSync(b, 'Good morning');
+
+      service.watch(testDir, { targetLangs: ['es'], outputDir });
+      service.handleFileChange(a);
+      service.handleFileChange(b);
+      await settle();
+
+      expect(outputPathsOf()).toEqual([
+        path.join(outputDir, 'a', 'one.es.md'),
+        path.join(outputDir, 'b', 'two.es.md'),
+      ]);
+    });
+
+    it('leaves the output flat when the watched path is a single file', async () => {
+      const doc = path.join(testDir, 'a', 'doc.md');
+      fs.mkdirSync(path.dirname(doc), { recursive: true });
+      fs.writeFileSync(doc, 'Hello');
+
+      service.watch(doc, { targetLangs: ['es'], outputDir });
+      service.handleFileChange(doc);
+      await settle();
+
+      expect(outputPathsOf()).toEqual([path.join(outputDir, 'doc.es.md')]);
+    });
+
+    it('leaves the output flat for a path outside the watched root', async () => {
+      const outside = path.join(testDir, 'outside');
+      const doc = path.join(outside, 'doc.md');
+      const watched = path.join(testDir, 'watched');
+      fs.mkdirSync(outside, { recursive: true });
+      fs.mkdirSync(watched, { recursive: true });
+      fs.writeFileSync(doc, 'Hello');
+
+      service.watch(watched, { targetLangs: ['es'], outputDir });
+      service.handleFileChange(doc);
+      await settle();
+
+      expect(outputPathsOf()).toEqual([path.join(outputDir, 'doc.es.md')]);
+    });
+  });
 });

From 2fdd5d1bb76bd07ceba171fdae526b8cf736822a Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 08:59:53 +0200
Subject: [PATCH 181/256] test(watch): wait for the named outputs, not for a
 file count

The output-layout suite waited until the output directory held N files, and
under a full coverage run the Nth was the `.tmp.<pid>.<rand>` sibling an atomic
write renames from, so the assertion read a write that was still in flight. It
now waits for the paths it is about to assert on, and the listing ignores an
in-flight temp through isAtomicWriteTempPath.

Refs cli-8kr2.74
---
 .../watch-output-layout.integration.test.ts   | 50 ++++++++++++-------
 1 file changed, 31 insertions(+), 19 deletions(-)

diff --git a/tests/integration/watch-output-layout.integration.test.ts b/tests/integration/watch-output-layout.integration.test.ts
index 0296db43..3afd5359 100644
--- a/tests/integration/watch-output-layout.integration.test.ts
+++ b/tests/integration/watch-output-layout.integration.test.ts
@@ -24,6 +24,7 @@ import { WatchService } from '../../src/services/watch.js';
 import { FileTranslationService } from '../../src/services/file-translation.js';
 import { TranslationService } from '../../src/services/translation.js';
 import type { Language } from '../../src/types/index.js';
+import { isAtomicWriteTempPath } from '../../src/utils/atomic-write.js';
 import { createMockTranslationService } from '../helpers/mock-factories';
 
 const DEBOUNCE_MS = 20;
@@ -31,6 +32,11 @@ const DEBOUNCE_MS = 20;
 const sleep = (ms: number) =>
   new Promise<void>((resolve) => setTimeout(resolve, ms));
 
+/**
+ * The output files on disk, ignoring the temp sibling an atomic write renames
+ * from: it appears and vanishes under the output directory, so counting it would
+ * report a write as finished while it is still in flight.
+ */
 const filesUnder = (dir: string): string[] => {
   const found: string[] = [];
   const walk = (current: string, relative: string): void => {
@@ -39,7 +45,7 @@ const filesUnder = (dir: string): string[] => {
       const childRelative = path.join(relative, entry.name);
       if (entry.isDirectory()) {
         walk(child, childRelative);
-      } else {
+      } else if (!isAtomicWriteTempPath(child)) {
         found.push(childRelative);
       }
     }
@@ -49,16 +55,19 @@ const filesUnder = (dir: string): string[] => {
 };
 
 /**
- * Waits for the writes to land rather than sleeping a fixed span: the
- * structured-format path imports its service on first use, which under a full
- * suite run takes longer than any debounce multiple worth hard-coding. Returns
- * whatever is on disk when the count is reached or the bound expires, so the
- * assertion still reports the real listing on a genuine failure.
+ * Waits for named files rather than sleeping a fixed span: the structured-format
+ * path imports its service on first use, which under a full suite run takes
+ * longer than any debounce multiple worth hard-coding. Returns whatever is on
+ * disk once every expected path is there or the bound expires, so the assertion
+ * still reports the real listing on a genuine failure.
  */
-const waitForFiles = async (dir: string, count: number): Promise<string[]> => {
+const waitForFiles = async (
+  dir: string,
+  expected: readonly string[]
+): Promise<string[]> => {
   for (let attempt = 0; attempt < 100; attempt++) {
     const found = filesUnder(dir);
-    if (found.length >= count) {
+    if (expected.every((relative) => found.includes(relative))) {
       return found;
     }
     await sleep(DEBOUNCE_MS);
@@ -139,10 +148,8 @@ describe('Watch output layout integration', () => {
     watchService.handleFileChange(a);
     watchService.handleFileChange(b);
 
-    expect(await waitForFiles(outDir, 2)).toEqual([
-      path.join('a', 'doc.es.md'),
-      path.join('b', 'doc.es.md'),
-    ]);
+    const expected = [path.join('a', 'doc.es.md'), path.join('b', 'doc.es.md')];
+    expect(await waitForFiles(outDir, expected)).toEqual(expected);
     expect(fs.readFileSync(path.join(outDir, 'a', 'doc.es.md'), 'utf-8')).toBe(
       'es:Hello\n'
     );
@@ -162,12 +169,13 @@ describe('Watch output layout integration', () => {
     watchService.handleFileChange(a);
     watchService.handleFileChange(b);
 
-    expect(await waitForFiles(outDir, 4)).toEqual([
+    const expected = [
       path.join('a', 'doc.es.md'),
       path.join('a', 'doc.fr.md'),
       path.join('b', 'doc.es.md'),
       path.join('b', 'doc.fr.md'),
-    ]);
+    ];
+    expect(await waitForFiles(outDir, expected)).toEqual(expected);
     expect(fs.readFileSync(path.join(outDir, 'a', 'doc.fr.md'), 'utf-8')).toBe(
       'fr:Hello\n'
     );
@@ -187,12 +195,13 @@ describe('Watch output layout integration', () => {
     watchService.handleFileChange(a);
     watchService.handleFileChange(b);
 
-    expect(await waitForFiles(outDir, 4)).toEqual([
+    const expected = [
       path.join('a', 'app.es.json'),
       path.join('a', 'app.fr.json'),
       path.join('b', 'app.es.json'),
       path.join('b', 'app.fr.json'),
-    ]);
+    ];
+    expect(await waitForFiles(outDir, expected)).toEqual(expected);
     expect(
       JSON.parse(
         fs.readFileSync(path.join(outDir, 'b', 'app.es.json'), 'utf-8')
@@ -207,7 +216,10 @@ describe('Watch output layout integration', () => {
     watchService.watch(sourceDir, { targetLangs: ['es'], outputDir: outDir });
     watchService.handleFileChange(a);
     watchService.handleFileChange(b);
-    await waitForFiles(outDir, 2);
+    await waitForFiles(outDir, [
+      path.join('a', 'doc.es.md'),
+      path.join('b', 'doc.es.md'),
+    ]);
     // A settling span on top, so a third call would have arrived by now.
     await sleep(DEBOUNCE_MS * 8);
 
@@ -223,7 +235,7 @@ describe('Watch output layout integration', () => {
     watchService.watch(sourceDir, { targetLangs: ['es'], outputDir: outDir });
     watchService.handleFileChange(doc);
 
-    expect(await waitForFiles(outDir, 1)).toEqual(['doc.es.md']);
+    expect(await waitForFiles(outDir, ['doc.es.md'])).toEqual(['doc.es.md']);
     expect(fs.readFileSync(path.join(outDir, 'doc.es.md'), 'utf-8')).toBe(
       'es:Hello\n'
     );
@@ -235,6 +247,6 @@ describe('Watch output layout integration', () => {
     watchService.watch(doc, { targetLangs: ['es'], outputDir: outDir });
     watchService.handleFileChange(doc);
 
-    expect(await waitForFiles(outDir, 1)).toEqual(['doc.es.md']);
+    expect(await waitForFiles(outDir, ['doc.es.md'])).toEqual(['doc.es.md']);
   });
 });

From 75d46fa2e5fe6a11d28df66151157ad260fddc7e Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 09:00:11 +0200
Subject: [PATCH 182/256] fix(sync): stop counting an XLIFF needs-review state
 as a finished translation

A `<target state="needs-review-translation">` in 1.2, and a
`<segment state="initial">` in 2.0, say a translation exists but is not
approved. Every read path took the target at face value, so a project shipping
unapproved strings reported 100% coverage and pushed those strings to the TMS as
approved. XliffFormatParser now implements extractNeedsReview, which both
consumers already drive. Only an explicit claim counts: an absent attribute, and
a value outside the version's set, stay complete, so an existing project's
coverage does not move.

Reading the state is only correct if the file's own state is honest, and it was
not: reconstruct preserved whatever it found, so a source exported with
`<target state="needs-translation"></target>` placeholders yielded a target
whose every unit said it still needed translating about a string the CLI had
just translated. A state on an element whose content this reconstruct replaces
now becomes `translated`; one on an unchanged translation is left alone, which
is what keeps a reviewer's flag alive through a run that translates a sibling
key.

`sync status`'s explanation of the count described gettext alone -- `#, fuzzy`,
`msgfmt`, "clear the msgstr" -- to a user whose format has none of those.

Refs cli-8kr2.73
---
 CHANGELOG.md                                  |   6 +
 docs/API.md                                   |   2 +-
 docs/SYNC.md                                  |  17 +-
 src/cli/commands/sync/register-sync-status.ts |  12 +-
 src/formats/xliff.ts                          | 150 ++++++++++++++--
 .../e2e/cli-sync-bilingual-target.e2e.test.ts |  34 ++++
 .../sync-bilingual-target.integration.test.ts | 167 ++++++++++++++++++
 tests/unit/formats/bilingual-target.test.ts   | 111 ++++++++++++
 tests/unit/formats/xliff-attributes.test.ts   |  79 ++++++++-
 9 files changed, 552 insertions(+), 26 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ba6b1668..daf42448 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **`deepl sync status` reports a lower coverage percentage for an XLIFF project whose targets carry a review `state`, and `deepl sync` writes `state="translated"` where it used to leave the old value.** A dashboard or CI check reading `coverage` or `complete` out of that command will see an XLIFF project it called 100% drop to whatever share of its units are actually approved, and `deepl sync push` reports a lower pushed count by the same number. The written bytes change only for a target that already carried a `state` and whose translation this run replaced; a target with no `state` is written exactly as before. The `sync status` explanation of the `needsReview` count no longer describes gettext alone — it named `#, fuzzy`, `msgfmt` and "clear the msgstr" to users of a format that has none of those. `sync --frozen` still passes. See Fixed.
+
 - **watch**: **`deepl watch` writes a nested source file to a nested output path.** Watching `docs/` with `--output out`, `docs/guide/intro.md` now lands at `out/guide/intro.es.md` where it used to land at `out/intro.es.md`. Anything reading a watch session's output by flat basename — a publish step, a `.gitignore` entry, an `--auto-commit` diff — has to follow the directory it now sits in. A file at the top of the watched directory, and a watched path that is a single file, are unchanged, so a single-directory or single-file session sees no difference. The layout is the one `deepl translate <dir> --output <dir>` has always produced. See Fixed.
 
 - **sync**: **`deepl sync status` reports a lower coverage percentage for a PO project holding `#, fuzzy` entries**, and each locale in `--format json` gains a `needsReview` count. A dashboard or CI check reading `coverage` or `complete` out of that command will see a project it called 100% drop to whatever share of its keys are actually shippable — which is what `msgfmt` has been reporting all along. `deepl sync push` reports a new `needs_review` skip reason, so its pushed count falls by the number of fuzzy entries. Nothing is re-translated, rewritten or re-billed, and `sync --frozen` still passes. See Fixed.
@@ -147,6 +149,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **an XLIFF review `state` is no longer counted as a finished translation.** `<target state="needs-review-translation">` in 1.2 and `<segment state="initial">` in 2.0 mean a translation exists but is not approved; every read path took the `<target>` at face value, so a project shipping unapproved strings reported itself done. Measured end to end on a two-unit project through the CLI, in both versions: after flagging one unit with its source unchanged, `deepl sync status` said `100% (0 missing, 0 outdated)`, `--format json` said `needsReview: 0` and `complete: 2`, `sync validate` said `All translations passed validation` and `sync --dry-run` said `2 current`. The same project now reports `50% (0 missing, 0 outdated, 1 needs review)`. `deepl sync push` skips such a unit under the existing `needs_review` reason instead of uploading it as approved. The states are read as an explicit claim only: 1.2's `new` and `needs-*` values and 2.0's `initial` count, `translated` / `signed-off` / `final` / `reviewed` do not, and an **absent** attribute or a value outside those sets counts as complete — which is why an existing project's coverage does not move. In particular 2.0's documented `initial` default is deliberately not applied to a segment that carries no `state`, since that is the shape the CLI itself writes. `state-qualifier` (1.2) and `subState` (2.0) are different attributes and are not read. Nothing is re-translated, rewritten or re-billed; both ways out were measured — changing the state to `translated` returns the key to `complete` with **no API call**, and emptying the `<target>` has the next `deepl sync` translate it afresh.
+
+- **sync**: **a `state` attribute on an XLIFF target the CLI has just written now describes what the CLI wrote.** A source XLIFF exported with `<target state="needs-translation"></target>` placeholders — what most CAT tools produce — yielded a target file whose every unit claimed it still needed translating about a string the CLI had just translated, in both versions (2.0 kept `<segment state="initial">` around a filled-in target). The file contradicted itself, any consumer reading `state` would ignore or re-request work already paid for, and with the counting above every one of those keys would have reported as needing review forever. Such a state now becomes `translated` when reconstruct replaces the target's content, and a `signed-off` state the CLI writes over is downgraded the same way rather than claiming human approval for machine output. An element carrying no `state` still gains none, and a `state` on a unit whose translation is **unchanged** is never touched — which is what keeps a reviewer's `needs-review-translation` alive through a run that translates a sibling key, verified on the real write path.
+
 - **watch**: **two watched files with the same name no longer write one translation on top of the other.** The output path was built from the source's basename alone, so every `doc.md` under the watched tree mapped to one `<output>/doc.es.md` and the last translation to finish silently replaced the ones before it — the whole of the losing file's translated output gone, at exit 0, with no warning and nothing in the summary to notice: the count still read `Translations: 2`. Measured on a watched tree holding `a/doc.md` ("Hello") and `b/doc.md` ("Good morning") with `--to es`: `translateFile` was called twice with the same `out/doc.es.md`, `out/` held one file, and its contents were `b/doc.md`'s translation. The output now carries the source's directory relative to the watched path, so those two write `out/a/doc.es.md` and `out/b/doc.es.md` — both texts, at 2 API calls, unchanged from before. The same flattening ran on **three** paths, not the one: the single-target path built the name itself, and the multi-target path (`--to es,fr`) handed a bare output directory to `FileTranslationService.translateFileToMultiple` for text files and to `StructuredFileTranslationService` for JSON and YAML, each of which then applied the same basename rule. All three now take the per-source directory. Verified end to end through the CLI against a mock API with the **default** output directory (`<watched>/translations`, which sits inside the watched tree): both translations landed under their own subdirectory, `translateCalls` settled at 2 with no further activity, so the loop guard still recognises a nested output as the CLI's own work and does not re-translate it. The layout is what `deepl translate <dir> --output <dir>` already produced — measured on the same fixture, which wrote `out/a/doc.es.md` and `out/b/doc.es.md` — so watch was the one command flattening. See Changed for the paths that move.
 
 - **watch**: **the loop guard no longer warns about the temp file the CLI is writing through.** `atomicWriteFile` renames from a `<target>.tmp.<pid>.<random>` sibling, which has to sit beside its target because a rename is only atomic within one filesystem — so a watcher on the output directory sees it appear and vanish. Its name carries the output file's, so the output-file check matched it and the session printed `Skipping …/doc.es.md.tmp.4242.a1b2c3: it is inside the output directory and named like a translated output … Move it outside …` about a file that this process had already renamed away, telling the user to move something that no longer exists. Such a path is now recognised as an in-flight write and ignored, before the output-file check. A real output-looking file the user put there still gets its one warning.
diff --git a/docs/API.md b/docs/API.md
index e0c10aa7..f4d7a72e 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1392,7 +1392,7 @@ Source: en (142 keys)
   ja  [##################..]  91%  (12 missing, 0 outdated)
 ```
 
-A locale also reports **`needsReview`** keys — a translation is present but its format marks it as not ready to ship, which today means a gettext `#, fuzzy` msgstr. `msgfmt` leaves such an entry out of the compiled catalog, so the application shows the source string; counting it complete would report a project as done while it ships untranslated text. Such a key is never re-translated and the file is never rewritten for it — the value is a reviewer's draft — so the count is a report, not a repair, and nothing is billed. The suffix `, N needs review` and its explanatory line appear only when the count is non-zero, and `--format json` always carries `needsReview` on each locale. `deepl sync push` skips such a key under a `needs_review` skip reason rather than uploading it as an approved translation. `sync --frozen` deliberately does **not** treat it as drift: a fuzzy entry is a normal, transient state in a gettext workflow that only a human review clears, and nothing the CLI did caused it.
+A locale also reports **`needsReview`** keys — a translation is present but its format marks it as not ready to ship, which means a gettext `#, fuzzy` msgstr or an XLIFF review `state` such as `needs-review-translation` (1.2) or `initial` (2.0). `msgfmt` leaves a fuzzy entry out of the compiled catalog, so the application shows the source string; counting such a key complete would report a project as done while it ships untranslated text. An XLIFF unit with no `state` attribute, or one carrying a value outside the recognised sets, counts as complete — see docs/SYNC.md for the two tables. Such a key is never re-translated and the file is never rewritten for it — the value is a reviewer's draft — so the count is a report, not a repair, and nothing is billed. The suffix `, N needs review` and its explanatory line appear only when the count is non-zero, and `--format json` always carries `needsReview` on each locale. `deepl sync push` skips such a key under a `needs_review` skip reason rather than uploading it as an approved translation. `sync --frozen` deliberately does **not** treat it as drift: such a marker is a normal, transient state in a review workflow that only a human clears, and nothing the CLI did caused it.
 
 A locale also reports **`unwritten`** keys — recorded as translated in `.deepl-sync.lock` but not in that locale's target file — when there are any, followed by a line naming the file and the keys. The suffix is omitted when the count is zero, so the line above is unchanged for a healthy project. `--format json` always carries `unwritten` on each locale plus a top-level `unwrittenByLocale` array of `{locale, file, keys}`, each entry gaining an `unusable` field when the target file could not be read or parsed at all. See [docs/SYNC.md](./SYNC.md#a-string-added-after-the-first-sync) for what is and is not counted.
 
diff --git a/docs/SYNC.md b/docs/SYNC.md
index e7c16e3c..49abe8a8 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -231,7 +231,7 @@ Nine of the eleven formats are monolingual -- a target file holds translations a
 | Path | What it reads from a PO / XLIFF target |
 |------|----------------------------------------|
 | `deepl sync` | The existing `msgstr` / `<target>` is carried forward for a key the lockfile calls up to date, so a reviewed translation survives a run that rewrites the file because a *sibling* key changed |
-| `deepl sync push` | The `msgstr` / `<target>` is what gets uploaded, unless it is flagged `fuzzy` |
+| `deepl sync push` | The `msgstr` / `<target>` is what gets uploaded, unless it is flagged `fuzzy` or carries a review `state` |
 | `deepl sync validate` | Placeholder and structure checks compare the `msgstr` against the `msgid` |
 | `deepl sync pull` | For a key the export does not carry, the existing `msgstr` is kept |
 | `deepl sync audit` | Terminology consistency is measured across translations |
@@ -242,7 +242,18 @@ Nine of the eleven formats are monolingual -- a target file holds translations a
 
 What the CLI does **not** do is act on it. The msgstr is a reviewer's draft and the lockfile records that key as translated against an unchanged source, so `deepl sync` carries the value and the flag forward untouched, re-translates nothing and bills nothing — reading it as untranslated would replace a human's in-progress work with machine output, which is the one outcome worse than an overstated percentage. `deepl sync push` skips the key under the `needs_review` reason rather than uploading a draft as approved. `sync --frozen` does not treat it as drift, because a fuzzy entry is a normal, transient state that only a human review clears. Two ways out, both measured: **remove the flag** and the key counts complete again (`msgfmt`: `2 translated messages`), or **clear the msgstr** and the next `deepl sync` translates it afresh (`msgfmt`: `1 translated, 1 untranslated`, then `2 translated messages`).
 
-XLIFF's `state="needs-review-translation"` and its siblings are the same idea in the other bilingual format and are **not** covered: XLIFF 1.2 and 2.0 spell the states differently, several values arguably qualify, and there is no external tool to arbitrate which — unlike gettext, where `msgfmt` decides. It is tracked separately.
+**An XLIFF review `state` says the same thing, and is read the same way.** XLIFF 1.2 records it on `<target>`, 2.0 on `<segment>`, and the CLI counts a unit whose translation is present as `needsReview` when that attribute makes an explicit claim that the translation is not finished:
+
+| Version | Where | Counted as needing review | Counted as complete |
+|---------|-------|---------------------------|---------------------|
+| 1.2 | `<target state="...">` | `new`, `needs-translation`, `needs-l10n`, `needs-adaptation`, `needs-review-translation`, `needs-review-l10n`, `needs-review-adaptation` | `translated`, `signed-off`, `final` |
+| 2.0 | `<segment state="...">` | `initial` | `translated`, `reviewed`, `final` |
+
+An **absent** attribute counts as complete in both versions, and so does a value neither list names. That is deliberate, and it is why an existing project's coverage does not move: absence is what the CLI itself writes and what a file from a toolchain with no review workflow carries, so reading it as unfinished would report every such project as needing review. It means the CLI does **not** apply 2.0's documented `initial` default to a segment with no `state` — only an explicit claim counts. `state-qualifier` (1.2) and `subState` (2.0) are different attributes with their own vocabularies and are not read. There is no `msgfmt` equivalent to arbitrate this, so unlike the PO numbers above these are the CLI's policy rather than an oracle's.
+
+Everything else matches the PO case: the `<target>` is carried forward untouched, nothing is re-translated or re-billed, `push` skips the key under `needs_review`, and `sync --frozen` does not treat it as drift. Two ways out, both measured: **change the state** to `translated` and the key counts complete again with **no API call**, or **empty the `<target>`** and the next `deepl sync` translates it afresh.
+
+**A state the CLI writes over describes what the CLI wrote.** When `reconstruct` replaces a `<target>`'s content, a `state` attribute already on that element (1.2) or on its `<segment>` (2.0) becomes `translated`. Otherwise the file would contradict itself: a source XLIFF exported with `<target state="needs-translation"></target>` placeholders — a common CAT-tool shape — produced a target file whose every unit said it still needed translating about a string the CLI had just translated, and every one of those keys would then be reported as needing review forever. An element carrying no `state` gains none. A `state` on a unit whose translation is **unchanged** is never touched, which is what keeps a reviewer's `needs-review-translation` alive through a run that translates a *sibling* key.
 
 **PO entries need no blank line between them.** The blank-line separator is a convention `msgfmt -c` does not require, and a catalog written without it — after the header or between messages — is read and written entry by entry all the same. An entry ends at the first line that is not a continuation of its translation: a comment, a `msgctxt`, or the next `msgid`. Layout is preserved either way, so a catalog that arrived without the separators keeps that shape on the way out.
 
@@ -1025,7 +1036,7 @@ deepl sync push [OPTIONS]
 | `--format <fmt>` | Output format: `text` (default), `json` |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 
-**A key with no translation yet is not pushed.** Push reads each target file and uploads the translation it holds. A bilingual target file (see [Bilingual formats: PO and XLIFF](#bilingual-formats-po-and-xliff)) lists every key the source has, translated or not, so pushing such a key would upload its source text as the locale's translation and make the TMS the authority for it -- a later `pull` would then write English into the target file. Those keys are skipped and reported under the `untranslated` reason, with the pushed count reflecting only what was actually sent. A PO entry flagged `#, fuzzy` is skipped too, under `needs_review`: it has a translation, but one its own toolchain will not ship (see [Bilingual formats](#bilingual-formats-po-and-xliff)). For a monolingual format nothing is skipped on this account: every key the target file lists has a value.
+**A key with no translation yet is not pushed.** Push reads each target file and uploads the translation it holds. A bilingual target file (see [Bilingual formats: PO and XLIFF](#bilingual-formats-po-and-xliff)) lists every key the source has, translated or not, so pushing such a key would upload its source text as the locale's translation and make the TMS the authority for it -- a later `pull` would then write English into the target file. Those keys are skipped and reported under the `untranslated` reason, with the pushed count reflecting only what was actually sent. A PO entry flagged `#, fuzzy`, and an XLIFF unit whose review `state` says the translation is not finished, are skipped too, under `needs_review`: they have a translation, but one their own toolchain will not ship (see [Bilingual formats](#bilingual-formats-po-and-xliff)). For a monolingual format nothing is skipped on this account: every key the target file lists has a value.
 
 ### `deepl sync pull`
 
diff --git a/src/cli/commands/sync/register-sync-status.ts b/src/cli/commands/sync/register-sync-status.ts
index 00bad898..2b760d9c 100644
--- a/src/cli/commands/sync/register-sync-status.ts
+++ b/src/cli/commands/sync/register-sync-status.ts
@@ -95,11 +95,13 @@ async function handleSyncStatus(
         const one = needingReview === 1;
         Logger.output('');
         Logger.warn(
-          `${needingReview} ${one ? 'key holds' : 'keys hold'} a translation marked as needing review — a gettext ` +
-            '`#, fuzzy` msgstr, which `msgfmt` leaves out of the compiled catalog, so the ' +
-            `application shows the source string instead. \`deepl sync\` carries ${one ? 'it' : 'them'} forward ` +
-            `untouched and never re-translates ${one ? 'it' : 'them'}: remove the flag once the translation ` +
-            `has been checked, or clear the msgstr to have ${one ? 'it' : 'them'} translated again.`
+          `${needingReview} ${one ? 'key holds' : 'keys hold'} a translation its target file marks as needing ` +
+            'review — a gettext `#, fuzzy` msgstr, which `msgfmt` leaves out of the compiled ' +
+            'catalog so the application shows the source string instead, or an XLIFF review ' +
+            '`state` such as `needs-review-translation`. ' +
+            `\`deepl sync\` carries ${one ? 'it' : 'them'} forward untouched and never re-translates ` +
+            `${one ? 'it' : 'them'}: clear the marker once the translation has been checked, or empty the ` +
+            `translation to have ${one ? 'it' : 'them'} made again.`
         );
       }
     }
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index 8b5c641c..58bc31d6 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -72,6 +72,56 @@ const TRANSLATABLE_EL: ElementPattern = {
   close: /<\/(?:\w+:)?(?:source|target)>/iy,
 };
 
+// Matches only the `state` attribute: `state-qualifier` (1.2) and `subState`
+// (2.0) are different attributes carrying different vocabularies.
+const STATE_ATTR_RE = /(\sstate\s*=\s*["'])([^"'<]*)(["'])/i;
+
+/** The value written for a target this reconstruct has just filled in. */
+const TRANSLATED_STATE = 'translated';
+
+/**
+ * XLIFF states saying a translation is present but not ready to ship. 1.2 keeps
+ * `state` on `<target>`; 2.0 keeps it on `<segment>` with a four-value
+ * vocabulary.
+ *
+ * An ABSENT attribute is deliberately NOT read as 2.0's documented `initial`
+ * default: absent is what this parser writes and what a file from a toolchain
+ * with no review workflow carries, so reading it as unfinished would report
+ * every such project as needing review. Only an explicit claim counts, and an
+ * unrecognised value counts as shippable for the same reason — a string this
+ * list does not know is not evidence that the translation is unfinished.
+ */
+const UNFINISHED_STATES_V12: ReadonlySet<string> = new Set([
+  'new',
+  'needs-translation',
+  'needs-l10n',
+  'needs-adaptation',
+  'needs-review-translation',
+  'needs-review-l10n',
+  'needs-review-adaptation',
+]);
+
+const UNFINISHED_STATES_V2: ReadonlySet<string> = new Set(['initial']);
+
+function stateOf(attrs: string): string | undefined {
+  return STATE_ATTR_RE.exec(attrs)?.[2];
+}
+
+/**
+ * Say the element holds a translation, on an element whose translation this
+ * reconstruct has just replaced. Whatever the previous value claimed — that the
+ * string still needed translating, or that a human had signed the old one off —
+ * it does not describe the text now in the element. An element carrying no
+ * `state` gains none: absence is this parser's own output shape.
+ */
+function withTranslatedState(attrs: string): string {
+  return attrs.replace(
+    STATE_ATTR_RE,
+    (_match, open: string, _value: string, close: string) =>
+      `${open}${TRANSLATED_STATE}${close}`
+  );
+}
+
 const NAMED_ENTITIES: Record<string, string> = {
   amp: '&',
   lt: '<',
@@ -164,15 +214,32 @@ function rewriteInner(element: ScannedElement, inner: string): string {
   return `${element.openTag}${inner}${element.closeTag}`;
 }
 
+/**
+ * True when the block's `<target>` already holds exactly this translation, so
+ * rewriting the element changes nothing it says. Compared in the terms
+ * `extractTranslations` reports, since that is where the translation being
+ * written back came from.
+ */
+function targetHolds(block: string, translation: string): boolean {
+  const target = findElement(block, TARGET_EL);
+  return target !== undefined && unescapeXml(target.inner) === translation;
+}
+
 /**
  * Replace the first `<target>` in a block, or insert one after `<source>`
  * when the block has none.
  */
-function applyTarget(block: string, escaped: string): string {
+function applyTarget(
+  block: string,
+  translation: string,
+  markTranslated: boolean
+): string {
+  const escaped = escapeXml(translation);
   const target = findElement(block, TARGET_EL);
   if (target) {
     const ns = target.groups[0] ?? '';
-    const attrs = target.groups[1] ?? '';
+    const existing = target.groups[1] ?? '';
+    const attrs = markTranslated ? withTranslatedState(existing) : existing;
     return (
       block.slice(0, target.start) +
       `<${ns}target${attrs}>${escaped}</${ns}target>` +
@@ -218,28 +285,76 @@ export class XliffFormatParser implements FormatParser {
    */
   extractTranslations(content: string): Map<string, string> {
     assertNoCdataInTranslatable(content);
-    const isV2 = detectVersion(content) === '2.0';
     const translations = new Map<string, string>();
 
+    for (const unit of this.translatedUnits(content)) {
+      translations.set(unit.key, unit.translation);
+    }
+
+    return translations;
+  }
+
+  /**
+   * Keys whose `<target>` holds a translation the file's own state attribute
+   * says is not ready to ship. The translation itself stays in
+   * `extractTranslations`: it belongs to whoever set that state, and a run has
+   * to carry it forward rather than replace it.
+   */
+  extractNeedsReview(content: string): Set<string> {
+    assertNoCdataInTranslatable(content);
+    const unfinished =
+      detectVersion(content) === '2.0'
+        ? UNFINISHED_STATES_V2
+        : UNFINISHED_STATES_V12;
+    const flagged = new Set<string>();
+
+    for (const unit of this.translatedUnits(content)) {
+      const state = stateOf(unit.stateAttrs);
+      if (state !== undefined && unfinished.has(state)) {
+        flagged.add(unit.key);
+      }
+    }
+
+    return flagged;
+  }
+
+  /**
+   * Every unit holding a translation, with the attributes of the element this
+   * XLIFF version records a review state on — `<target>` in 1.2, `<segment>` in
+   * 2.0. One walk, so the two readers above cannot disagree about which units
+   * count as translated. A unit with no `<target>`, or an empty one, is
+   * untranslated and is left out so a caller re-translates it. The element is
+   * located exactly as `applyTarget` locates the one it overwrites, so what is
+   * reported is what a write would replace.
+   */
+  private *translatedUnits(content: string): Generator<{
+    key: string;
+    translation: string;
+    stateAttrs: string;
+  }> {
+    const isV2 = detectVersion(content) === '2.0';
+
     for (const element of scanElements(
       content,
       isV2 ? UNIT_EL : TRANS_UNIT_EL
     )) {
       const scope = isV2
-        ? findElement(element.inner, SEGMENT_EL)?.inner
-        : element.inner;
+        ? findElement(element.inner, SEGMENT_EL)
+        : { inner: element.inner, openTag: element.openTag };
       if (scope === undefined) continue;
-      if (!findElement(scope, SOURCE_EL)) continue;
+      if (!findElement(scope.inner, SOURCE_EL)) continue;
 
-      const target = findElement(scope, TARGET_EL);
+      const target = findElement(scope.inner, TARGET_EL);
       if (!target) continue;
       const translation = unescapeXml(target.inner);
       if (translation === '') continue;
 
-      translations.set(element.groups[0]!, translation);
+      yield {
+        key: element.groups[0]!,
+        translation,
+        stateAttrs: isV2 ? scope.openTag : (target.groups[1] ?? ''),
+      };
     }
-
-    return translations;
   }
 
   reconstruct(content: string, entries: TranslatedEntry[]): string {
@@ -375,9 +490,10 @@ export class XliffFormatParser implements FormatParser {
       const translation = translations.get(element.groups[0]!);
       if (translation === undefined) return '';
       assertNoControlChars(element.groups[0]!, translation);
+      const changed = !targetHolds(element.inner, translation);
       return rewriteInner(
         element,
-        applyTarget(element.inner, escapeXml(translation))
+        applyTarget(element.inner, translation, changed)
       );
     });
     return result.replace(/\n{3,}/g, '\n\n');
@@ -397,12 +513,16 @@ export class XliffFormatParser implements FormatParser {
       const segment = findElement(element.inner, SEGMENT_EL);
       if (!segment) return element.text;
 
+      // 2.0 records the review state on the segment rather than the target.
+      const changed = !targetHolds(segment.inner, translation);
+      const openTag = changed
+        ? withTranslatedState(segment.openTag)
+        : segment.openTag;
       const inner =
         element.inner.slice(0, segment.start) +
-        rewriteInner(
-          segment,
-          applyTarget(segment.inner, escapeXml(translation))
-        ) +
+        openTag +
+        applyTarget(segment.inner, translation, changed) +
+        segment.closeTag +
         element.inner.slice(segment.end);
       return rewriteInner(element, inner);
     });
diff --git a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
index 0ba7567c..e1329e44 100644
--- a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
+++ b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
@@ -230,4 +230,38 @@ describe('CLI sync with a bilingual target file', () => {
     expect(output).toContain('1 needs review');
     expect(output).toContain('msgfmt');
   }, 120000);
+
+  it('reports an XLIFF needs-review state as needing review too', () => {
+    // Runs after the two tests above, so the PO key is still flagged fuzzy and
+    // the lockfile calls every key translated.
+    fs.writeFileSync(
+      xlfTarget(),
+      fs
+        .readFileSync(xlfTarget(), 'utf-8')
+        .replace('<target>', '<target state="needs-review-translation">')
+    );
+
+    const { CI: _ci, DEEPL_API_KEY: _key, ...rest } = process.env;
+    const run = (args: string[]): string => {
+      const result = spawnSync('node', [CLI_PATH, ...args], {
+        encoding: 'utf-8',
+        cwd: testFiles.path,
+        env: { ...rest, DEEPL_CONFIG_DIR: testConfig.path, NO_COLOR: '1' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 60000,
+      });
+      expect(result.status).toBe(0);
+      return (result.stdout ?? '') + (result.stderr ?? '');
+    };
+
+    const parsed = JSON.parse(run(['sync', 'status', '--format', 'json'])) as {
+      locales: { locale: string; needsReview: number }[];
+    };
+    // The flagged PO key plus the flagged XLIFF unit.
+    expect(parsed.locales.find((l) => l.locale === 'es')!.needsReview).toBe(2);
+
+    const text = run(['sync', 'status']);
+    expect(text).toContain('2 needs review');
+    expect(text).toContain('needs-review-translation');
+  }, 120000);
 });
diff --git a/tests/integration/sync-bilingual-target.integration.test.ts b/tests/integration/sync-bilingual-target.integration.test.ts
index d9989dcd..d03d5a6f 100644
--- a/tests/integration/sync-bilingual-target.integration.test.ts
+++ b/tests/integration/sync-bilingual-target.integration.test.ts
@@ -477,4 +477,171 @@ describe('sync paths that read a bilingual target file', () => {
       expect(es.coverage).toBe(100);
     });
   });
+
+  describe('XLIFF review states', () => {
+    const XLIFF_SOURCE = (units: string): string =>
+      [
+        '<?xml version="1.0"?>',
+        '<xliff version="1.2"><file source-language="en" target-language="es" datatype="plaintext" original="app">',
+        '<body>',
+        units,
+        '</body></file></xliff>',
+        '',
+      ].join('\n');
+
+    const unit = (id: string, source: string): string =>
+      `<trans-unit id="${id}"><source>${source}</source></trans-unit>`;
+
+    const TWO_UNITS = XLIFF_SOURCE(
+      [unit('greeting', 'Hello'), unit('farewell', 'Bye')].join('\n')
+    );
+
+    function mockTranslate(times: number): void {
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .times(times)
+        .reply(200, (_uri, body) => {
+          const parsed = new URLSearchParams(body as string);
+          return {
+            translations: parsed.getAll('text').map((t) => ({
+              text: `[es]${t}`,
+              detected_source_language: 'EN',
+              billed_characters: t.length,
+            })),
+          };
+        });
+    }
+
+    /** A synced project, then one unit marked needs-review with the source unchanged. */
+    async function syncedThenFlagged(): Promise<string> {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        tms: tmsConfig(),
+        buckets: { xliff: { include: ['locales/en/app.xlf'] } },
+      });
+      write(tmpDir, 'locales/en/app.xlf', TWO_UNITS);
+      mockTranslate(4);
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      const target = path.join(tmpDir, 'locales/es/app.xlf');
+      fs.writeFileSync(
+        target,
+        fs
+          .readFileSync(target, 'utf-8')
+          .replace('<target>', '<target state="needs-review-translation">'),
+        'utf-8'
+      );
+      return target;
+    }
+
+    it('does not count a needs-review target as complete', async () => {
+      await syncedThenFlagged();
+
+      const status = await computeSyncStatus(
+        await loadSyncConfig(tmpDir),
+        harness.registry
+      );
+
+      const es = status.locales.find((l) => l.locale === 'es')!;
+      expect(es.needsReview).toBe(1);
+      expect(es.complete).toBe(1);
+      expect(es.coverage).toBe(50);
+      expect(es.missing).toBe(0);
+      expect(es.unwritten).toBe(0);
+    });
+
+    it('skips a needs-review target rather than pushing it as approved', async () => {
+      await syncedThenFlagged();
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+      const sent: string[] = [];
+      nock(TMS_BASE)
+        .put(new RegExp(`/api/projects/${TMS_PROJECT}/keys/.+`))
+        .times(2)
+        .reply(200, function reply(uri: string) {
+          sent.push(decodeURIComponent(uri.split('/keys/')[1]!));
+          return {};
+        });
+
+      const result = await pushTranslations(config, client, harness.registry);
+
+      expect(sent).toEqual(['farewell']);
+      expect(result.pushed).toBe(1);
+      expect(result.skipped).toEqual([
+        {
+          file: 'locales/en/app.xlf',
+          locale: 'es',
+          reason: 'needs_review',
+          key: 'greeting',
+        },
+      ]);
+    });
+
+    it('leaves the reviewer state on disk and bills nothing to report it', async () => {
+      const target = await syncedThenFlagged();
+      const before = fs.readFileSync(target, 'utf-8');
+
+      const result = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(result.totalCharactersBilled).toBe(0);
+      expect(fs.readFileSync(target, 'utf-8')).toBe(before);
+    });
+
+    it('keeps the reviewer state on a carried-forward key while translating a new one', async () => {
+      const target = await syncedThenFlagged();
+      write(
+        tmpDir,
+        'locales/en/app.xlf',
+        XLIFF_SOURCE(
+          [
+            unit('greeting', 'Hello'),
+            unit('farewell', 'Bye'),
+            unit('welcome', 'Welcome'),
+          ].join('\n')
+        )
+      );
+      mockTranslate(2);
+
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      const written = fs.readFileSync(target, 'utf-8');
+      expect(written).toContain('state="needs-review-translation"');
+      expect(written).toContain('[es]Welcome');
+
+      const status = await computeSyncStatus(
+        await loadSyncConfig(tmpDir),
+        harness.registry
+      );
+      expect(status.locales.find((l) => l.locale === 'es')!.needsReview).toBe(
+        1
+      );
+    });
+
+    it('reports a project with no state attributes exactly as before', async () => {
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { xliff: { include: ['locales/en/app.xlf'] } },
+      });
+      write(tmpDir, 'locales/en/app.xlf', TWO_UNITS);
+      mockTranslate(4);
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      const status = await computeSyncStatus(
+        await loadSyncConfig(tmpDir),
+        harness.registry
+      );
+
+      const es = status.locales.find((l) => l.locale === 'es')!;
+      expect(es.needsReview).toBe(0);
+      expect(es.complete).toBe(2);
+      expect(es.coverage).toBe(100);
+      expect(
+        fs.readFileSync(path.join(tmpDir, 'locales/es/app.xlf'), 'utf-8')
+      ).not.toContain('state=');
+    });
+  });
 });
diff --git a/tests/unit/formats/bilingual-target.test.ts b/tests/unit/formats/bilingual-target.test.ts
index 104501dd..c1c9efb2 100644
--- a/tests/unit/formats/bilingual-target.test.ts
+++ b/tests/unit/formats/bilingual-target.test.ts
@@ -347,6 +347,117 @@ describe('XliffFormatParser.extractTranslations', () => {
   });
 });
 
+describe('XliffFormatParser.extractNeedsReview', () => {
+  const parser = new XliffFormatParser();
+
+  const v12 = (targetTag: string): string =>
+    XLIFF_12_SOURCE.replace(
+      '<source>Hello</source>',
+      `<source>Hello</source>${targetTag}`
+    );
+
+  const v20 = (segmentAttrs: string, targetTag = '<target>Hola</target>') =>
+    XLIFF_20_SOURCE.replace(
+      '<segment><source>Hello</source></segment>',
+      `<segment${segmentAttrs}><source>Hello</source>${targetTag}</segment>`
+    );
+
+  describe('1.2, where the state is on the target', () => {
+    const UNFINISHED = [
+      'new',
+      'needs-translation',
+      'needs-l10n',
+      'needs-adaptation',
+      'needs-review-translation',
+      'needs-review-l10n',
+      'needs-review-adaptation',
+    ];
+
+    it.each(UNFINISHED)('names a key whose state is %s', (state) => {
+      const content = v12(`<target state="${state}">Hola</target>`);
+
+      expect([...parser.extractNeedsReview(content)]).toEqual(['greeting']);
+    });
+
+    it.each(['translated', 'signed-off', 'final'])(
+      'says nothing about a key whose state is %s',
+      (state) => {
+        const content = v12(`<target state="${state}">Hola</target>`);
+
+        expect([...parser.extractNeedsReview(content)]).toEqual([]);
+      }
+    );
+
+    it('says nothing about a target with no state attribute', () => {
+      expect([
+        ...parser.extractNeedsReview(v12('<target>Hola</target>')),
+      ]).toEqual([]);
+    });
+
+    it('says nothing about a state value XLIFF does not define', () => {
+      const content = v12('<target state="x-vendor-thing">Hola</target>');
+
+      expect([...parser.extractNeedsReview(content)]).toEqual([]);
+    });
+
+    it('leaves an empty target out, since it is simply untranslated', () => {
+      const content = v12('<target state="needs-translation"></target>');
+
+      expect([...parser.extractNeedsReview(content)]).toEqual([]);
+    });
+
+    it('does not read state-qualifier as the state', () => {
+      const content = v12(
+        '<target state-qualifier="fuzzy-match">Hola</target>'
+      );
+
+      expect([...parser.extractNeedsReview(content)]).toEqual([]);
+    });
+
+    it('still returns the flagged translation from extractTranslations', () => {
+      // A run must carry a reviewer's draft forward, not overwrite it.
+      const content = v12(
+        '<target state="needs-review-translation">Hola</target>'
+      );
+
+      expect(parser.extractTranslations(content).get('greeting')).toBe('Hola');
+    });
+  });
+
+  describe('2.0, where the state is on the segment', () => {
+    it('names a key whose segment state is initial', () => {
+      expect([...parser.extractNeedsReview(v20(' state="initial"'))]).toEqual([
+        'greeting',
+      ]);
+    });
+
+    it.each(['translated', 'reviewed', 'final'])(
+      'says nothing about a key whose segment state is %s',
+      (state) => {
+        expect([
+          ...parser.extractNeedsReview(v20(` state="${state}"`)),
+        ]).toEqual([]);
+      }
+    );
+
+    it('says nothing about a segment with no state attribute', () => {
+      expect([...parser.extractNeedsReview(v20(''))]).toEqual([]);
+    });
+
+    it('does not read subState as the state', () => {
+      const content = v20(' subState="vendor:draft"');
+
+      expect([...parser.extractNeedsReview(content)]).toEqual([]);
+    });
+
+    it('leaves an empty target out, since it is simply untranslated', () => {
+      const content = v20(' state="initial"', '<target></target>');
+
+      expect([...parser.extractNeedsReview(content)]).toEqual([]);
+    });
+  });
+});
+
 describe('monolingual parsers leave the read alone', () => {
   const MONOLINGUAL: Array<[string, FormatParser]> = [
     ['JSON', new JsonFormatParser()],
diff --git a/tests/unit/formats/xliff-attributes.test.ts b/tests/unit/formats/xliff-attributes.test.ts
index 6ea2977f..f84408a1 100644
--- a/tests/unit/formats/xliff-attributes.test.ts
+++ b/tests/unit/formats/xliff-attributes.test.ts
@@ -62,7 +62,7 @@ describe('XLIFF elements with attributes', () => {
       expect(parser.extract(out).map((e) => e.key)).toEqual(['greeting']);
     });
 
-    it('should preserve the segment state attribute', () => {
+    it('should say the segment is translated once it holds a new translation', () => {
       const parser = new XliffFormatParser();
       const entries = parser.extract(V20_WITH_STATE);
 
@@ -71,6 +71,19 @@ describe('XLIFF elements with attributes', () => {
         entries.map((e) => ({ ...e, translation: 'Guten Tag' }))
       );
 
+      expect(out).toContain('state="translated"');
+      expect(out).not.toContain('state="initial"');
+    });
+
+    it('should leave the segment state alone when the translation is unchanged', () => {
+      const parser = new XliffFormatParser();
+      const entries = parser.extract(V20_WITH_STATE);
+
+      const out = parser.reconstruct(
+        V20_WITH_STATE,
+        entries.map((e) => ({ ...e, translation: 'Hallo alt' }))
+      );
+
       expect(out).toContain('state="initial"');
     });
   });
@@ -91,7 +104,7 @@ describe('XLIFF elements with attributes', () => {
       expect(out).not.toContain('Hallo alt');
     });
 
-    it('should preserve the target state attribute', () => {
+    it('should say the target is translated once it holds a new translation', () => {
       const parser = new XliffFormatParser();
       const entries = parser.extract(V12_WITH_STATE);
 
@@ -100,7 +113,69 @@ describe('XLIFF elements with attributes', () => {
         entries.map((e) => ({ ...e, translation: 'Guten Tag' }))
       );
 
+      expect(out).toContain('<target state="translated">Guten Tag</target>');
+      expect(out).not.toContain('needs-translation');
+    });
+
+    it('should leave the target state alone when the translation is unchanged', () => {
+      const parser = new XliffFormatParser();
+      const entries = parser.extract(V12_WITH_STATE);
+
+      const out = parser.reconstruct(
+        V12_WITH_STATE,
+        entries.map((e) => ({ ...e, translation: 'Hallo alt' }))
+      );
+
       expect(out).toContain('state="needs-translation"');
     });
+
+    it('should replace a signed-off state it has just written over', () => {
+      const parser = new XliffFormatParser();
+      const signedOff = V12_WITH_STATE.replace(
+        'needs-translation',
+        'signed-off'
+      );
+      const entries = parser.extract(signedOff);
+
+      const out = parser.reconstruct(
+        signedOff,
+        entries.map((e) => ({ ...e, translation: 'Guten Tag' }))
+      );
+
+      expect(out).toContain('state="translated"');
+      expect(out).not.toContain('signed-off');
+    });
+
+    it('should add no state attribute to a target that carries none', () => {
+      const parser = new XliffFormatParser();
+      const bare = V12_WITH_STATE.replace(' state="needs-translation"', '');
+      const entries = parser.extract(bare);
+
+      const out = parser.reconstruct(
+        bare,
+        entries.map((e) => ({ ...e, translation: 'Guten Tag' }))
+      );
+
+      expect(out).toContain('<target>Guten Tag</target>');
+      expect(out).not.toContain('state=');
+    });
+
+    it('should keep the attributes that are not the state', () => {
+      const parser = new XliffFormatParser();
+      const withMore = V12_WITH_STATE.replace(
+        '<target state="needs-translation">',
+        '<target xml:lang="de" state="needs-translation" approved="no">'
+      );
+      const entries = parser.extract(withMore);
+
+      const out = parser.reconstruct(
+        withMore,
+        entries.map((e) => ({ ...e, translation: 'Guten Tag' }))
+      );
+
+      expect(out).toContain(
+        '<target xml:lang="de" state="translated" approved="no">Guten Tag</target>'
+      );
+    });
   });
 });

From defbd14cf889e183850d3e7cf6ff9fa5fae0b75d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 09:45:15 +0200
Subject: [PATCH 183/256] fix(sync): keep a carried-forward plural entry's
 forms instead of the source's
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A carried-forward entry was handed to reconstruct with the SOURCE diff's
plural payloads — empty msgstr[N] for gettext, source-language <item>s for
Android XML — and reconstruct rebuilds plural content from exactly those
payloads. Any run with other work to do therefore emptied a PO plural
entry's translated forms (misreported as "the target file has no element to
hold it", re-billed on the next sync) or silently reverted an Android
<plurals> entry to English, at exit 0. The same shape fired on the
validation-withholding carry and on every sync pull that rewrote the file.

The carry-forward sites and the pull merge now omit the plural payloads
(withoutPluralForms in sync-utils), so the parsers keep the target file's
own forms; android-xml's reconstruct keeps a <plurals> element verbatim for
an entry handed over without per-form translations, while a key absent from
the entry list is still deleted. A plural entry whose source changed is
still re-translated with fresh forms.

sync pull additionally stops applying an exported value to a plural entry —
one exported string cannot fill its forms. Such a key is reported under a
new plural_entry skip reason, is not counted as pulled or replaced, and no
lockfile entry is recorded for it.

Two existing unit stubs mocked sync-utils away wholesale and one test
asserted the source-language payload had to survive the withheld carry;
they now model the real module and the kept-forms contract.

Refs cli-8kr2.77
---
 CHANGELOG.md                                  |   4 +
 docs/SYNC.md                                  |   8 +
 src/formats/android-xml.ts                    |   5 +-
 src/sync/sync-locale-translator.ts            |  13 +-
 src/sync/sync-tms.ts                          |  35 +-
 src/sync/sync-utils.ts                        |  43 +-
 ...c-plural-carry-forward.integration.test.ts | 407 ++++++++++++++++++
 tests/unit/formats/android-xml.test.ts        |  15 +
 .../unit/sync/sync-locale-translator.test.ts  |  13 +-
 .../sync/sync-source-as-translation.test.ts   |   1 +
 tests/unit/sync/sync-utils.test.ts            |  73 ++++
 11 files changed, 601 insertions(+), 16 deletions(-)
 create mode 100644 tests/integration/sync-plural-carry-forward.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index daf42448..a7b402c0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **`deepl sync pull` no longer applies an exported value to a plural entry, and its counts move.** The export carries one string per key, which cannot fill a plural entry's forms; that value used to be applied nowhere while the entry's forms were emptied and the key was still counted as pulled and replaced. Such a key is now reported under a new `plural_entry` skip reason in the `(N skipped: …)` summary and in `--format json`, is not counted in `pulled` or `replaced`, and no lockfile entry is recorded for it. A consumer reconciling pull counts against the export's key list will see the difference; the export itself is requested exactly as before. See Fixed.
+
 - **sync**: **`deepl sync status` reports a lower coverage percentage for an XLIFF project whose targets carry a review `state`, and `deepl sync` writes `state="translated"` where it used to leave the old value.** A dashboard or CI check reading `coverage` or `complete` out of that command will see an XLIFF project it called 100% drop to whatever share of its units are actually approved, and `deepl sync push` reports a lower pushed count by the same number. The written bytes change only for a target that already carried a `state` and whose translation this run replaced; a target with no `state` is written exactly as before. The `sync status` explanation of the `needsReview` count no longer describes gettext alone — it named `#, fuzzy`, `msgfmt` and "clear the msgstr" to users of a format that has none of those. `sync --frozen` still passes. See Fixed.
 
 - **watch**: **`deepl watch` writes a nested source file to a nested output path.** Watching `docs/` with `--output out`, `docs/guide/intro.md` now lands at `out/guide/intro.es.md` where it used to land at `out/intro.es.md`. Anything reading a watch session's output by flat basename — a publish step, a `.gitignore` entry, an `--auto-commit` diff — has to follow the directory it now sits in. A file at the top of the watched directory, and a watched path that is a single file, are unchanged, so a single-directory or single-file session sees no difference. The layout is the one `deepl translate <dir> --output <dir>` has always produced. See Fixed.
@@ -149,6 +151,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a plural entry a run carries forward keeps its plural forms.** A carried-forward entry was handed to the file writer with the **source** file's plural payloads — empty `msgstr[N]` for gettext, source-language `<item>`s for Android XML — and plural content is rebuilt from exactly those payloads, so any run with other work to do destroyed the target's plural translations at exit 0. Measured through the CLI against a mock engine on three paths. **Translate**: a PO project holding a translated plural entry had `msgstr[0]` / `msgstr[1]` emptied by a sync whose only work was one new sibling key — `msgfmt --statistics` went from `3 translated messages` to `3 translated, 1 untranslated` — with the run misreporting its own destruction as `could not be given 1 translated key … the target file has no element to hold it` and the next sync re-translating and **re-billing** the entry. Android XML was worse: reviewer-corrected items (`Un archivo` / `Muchos archivos`) were silently reverted to the English source (`One file` / `Many files`) with no warning at all, because the reverted values are non-empty and the write-verification saw the key as present. **Validation withholding**: a stale plural entry whose fresh translation failed validation was supposed to keep what the file holds and emptied its forms instead. **Pull**: any `deepl sync pull` that rewrote a PO file emptied plural forms whether or not the export carried the plural key. The carry-forward sites and the pull merge now omit the plural payloads from what they hand the writer, so the parsers keep the file's own forms, and Android's writer keeps a `<plurals>` element verbatim for an entry handed over without per-form translations — a key absent from the entry list is still deleted. A plural entry whose source text actually changed is still re-translated with fresh forms. See docs/SYNC.md "A plural entry carried forward".
+
 - **sync**: **an XLIFF review `state` is no longer counted as a finished translation.** `<target state="needs-review-translation">` in 1.2 and `<segment state="initial">` in 2.0 mean a translation exists but is not approved; every read path took the `<target>` at face value, so a project shipping unapproved strings reported itself done. Measured end to end on a two-unit project through the CLI, in both versions: after flagging one unit with its source unchanged, `deepl sync status` said `100% (0 missing, 0 outdated)`, `--format json` said `needsReview: 0` and `complete: 2`, `sync validate` said `All translations passed validation` and `sync --dry-run` said `2 current`. The same project now reports `50% (0 missing, 0 outdated, 1 needs review)`. `deepl sync push` skips such a unit under the existing `needs_review` reason instead of uploading it as approved. The states are read as an explicit claim only: 1.2's `new` and `needs-*` values and 2.0's `initial` count, `translated` / `signed-off` / `final` / `reviewed` do not, and an **absent** attribute or a value outside those sets counts as complete — which is why an existing project's coverage does not move. In particular 2.0's documented `initial` default is deliberately not applied to a segment that carries no `state`, since that is the shape the CLI itself writes. `state-qualifier` (1.2) and `subState` (2.0) are different attributes and are not read. Nothing is re-translated, rewritten or re-billed; both ways out were measured — changing the state to `translated` returns the key to `complete` with **no API call**, and emptying the `<target>` has the next `deepl sync` translate it afresh.
 
 - **sync**: **a `state` attribute on an XLIFF target the CLI has just written now describes what the CLI wrote.** A source XLIFF exported with `<target state="needs-translation"></target>` placeholders — what most CAT tools produce — yielded a target file whose every unit claimed it still needed translating about a string the CLI had just translated, in both versions (2.0 kept `<segment state="initial">` around a filled-in target). The file contradicted itself, any consumer reading `state` would ignore or re-request work already paid for, and with the counting above every one of those keys would have reported as needing review forever. Such a state now becomes `translated` when reconstruct replaces the target's content, and a `signed-off` state the CLI writes over is downgraded the same way rather than claiming human approval for machine output. An element carrying no `state` still gains none, and a `state` on a unit whose translation is **unchanged** is never touched — which is what keeps a reviewer's `needs-review-translation` alive through a run that translates a sibling key, verified on the real write path.
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 49abe8a8..f7bfc191 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -169,6 +169,12 @@ The cost is one read and parse of each target file per locale, and it is only pa
 
 Within one source file the answer is computed once and reused, so no command reads a target file twice for it. On a 20,000-key, 6-locale JSON project (2.83 MiB source, 17.3 MiB of target files) that took `sync --frozen` from 1.13 s to 0.79 s, because a healthy project made it ask twice — once for the drift check and again for the "nothing to do" check.
 
+### A plural entry carried forward
+
+A run rewrites a whole target file even when only one key changed — that is how the file stays consistent — so every entry the run is *not* translating is carried forward. For an entry with plural forms (gettext `msgstr[N]`, an Android `<plurals>` element's items) the forms the target file holds are kept exactly as they stand: on a sync triggered by a sibling key, when a re-translation was withheld by validation, and on `deepl sync pull`. Only translating the entry itself — its source text changed, or it is new to the locale — rewrites the forms.
+
+A TMS export carries one string per key, which cannot fill a plural entry's forms, so `deepl sync pull` never applies an exported value to one: the key is reported under the `plural_entry` skip reason in the `(N skipped: …)` summary and in `--format json`, is not counted as pulled or replaced, and no lockfile entry is recorded for it. The entry stays exactly as the target file holds it; review plural strings in the local file, or empty the forms to have the next `deepl sync` translate them afresh.
+
 ### A target file that cannot be read
 
 Every command that opens a locale's target file distinguishes three answers, and only the first two let it write:
@@ -1063,6 +1069,8 @@ Each target locale's approved dictionary is fetched exactly once per `sync pull`
 
 **Pull does not claim human review.** The export endpoint returns `{ "key": "value" }` with no per-entry review flag, so pulled entries are recorded with `status: translated` and **no** `review_status`, meaning "unknown". Earlier releases stamped `review_status: human_reviewed` on every pulled key, asserting a review the CLI had not verified and the response did not describe.
 
+**A plural entry is left as it stands.** The export carries one string per key, which cannot fill a plural entry's forms (gettext `msgstr[N]`, an Android `<plurals>` element). Such a key is skipped under the `plural_entry` reason, is not counted as pulled or replaced, and no lockfile entry is recorded for it — see [A plural entry carried forward](#a-plural-entry-carried-forward).
+
 **A target file that cannot be read is left untouched.** Pull reads the existing target file so it can keep translations the export does not carry. If that file cannot be opened, cannot be parsed, or cannot be keyed unambiguously, the locale is skipped with a warning naming the file and the reason, and the file is not written — under the `key_collision` reason when keys collide (see [Key separators and colliding keys](#key-separators-and-colliding-keys)), which has its own remediation, and `unusable_target` otherwise. Pull deliberately does not fall back to reconstructing it from the source file in either case: that would replace the whole file with just the keys the export happened to carry. Only a file that is genuinely not there yet takes that fallback. See [A target file that cannot be read](#a-target-file-that-cannot-be-read).
 
 **Key-count limit:** The pull response is capped at **50,000 keys** (`MAX_PULL_KEY_COUNT`). Responses exceeding this limit are rejected with a `ValidationError` before any data is written. If your TMS project exceeds this threshold, partition the export by locale or paginate the pull on the TMS side before invoking `deepl sync pull`.
diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index 5278cb6a..361fc9af 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -257,7 +257,10 @@ export class AndroidXmlFormatParser implements FormatParser {
     result = replaceElements(result, PLURALS_EL, (el) => {
       const quantityMap = pluralTranslations.get(el.groups[0]!);
       if (!quantityMap) {
-        return null;
+        // An entry handed over without per-form translations is one whose
+        // plural forms this run did not translate: the element keeps the items
+        // it already holds. Only a key absent from the entry list is removed.
+        return translations.has(el.groups[0]!) ? el.text : null;
       }
       const inner = replaceElements(el.inner, PLURAL_ITEM_EL, (item) => {
         const translation = quantityMap.get(item.groups[0]!);
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 0b93fce3..f2ace911 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -22,7 +22,11 @@ import {
 } from './translation-validator.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
-import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
+import {
+  resolveTargetPath,
+  assertPathWithinRoot,
+  withoutPluralForms,
+} from './sync-utils.js';
 import { extractExistingTranslations } from './sync-bucket-walker.js';
 import { BACKUP_SUFFIX } from './sync-bak-cleanup.js';
 import { Logger } from '../utils/logger.js';
@@ -763,7 +767,7 @@ export class LocaleTranslator {
         key: rejected.key,
         value: rejected.source,
         translation: previous,
-        metadata: diff?.metadata,
+        metadata: withoutPluralForms(diff?.metadata),
       });
     }
     const currentDiffs = diffs.filter((d) => d.status === 'current');
@@ -777,12 +781,13 @@ export class LocaleTranslator {
         lockEntry?.translations[locale] !== undefined;
       if (existingTranslation !== undefined) {
         // Present in the target file — including a deliberately empty string,
-        // which must be preserved rather than treated as missing.
+        // which must be preserved rather than treated as missing. The same
+        // goes for its plural forms, which this run is not translating.
         allTranslatedEntries.push({
           key: cd.key,
           value: cd.value,
           translation: existingTranslation,
-          metadata: cd.metadata,
+          metadata: withoutPluralForms(cd.metadata),
         });
       } else {
         // No translation in the target file. Translate it, even when the
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index 47b96128..f576c121 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -17,6 +17,7 @@ import {
   resolveTargetPath,
   assertPathWithinRoot,
   mergePulledTranslations,
+  hasPluralForms,
 } from './sync-utils.js';
 import { LOCK_FILE_NAME } from './types.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
@@ -42,7 +43,8 @@ export type SkipReason =
   | 'key_collision'
   | 'unusable_target'
   | 'untranslated'
-  | 'needs_review';
+  | 'needs_review'
+  | 'plural_entry';
 
 export interface SkippedRecord {
   file: string;
@@ -70,6 +72,8 @@ const SKIP_REASON_LABELS: Record<SkipReason, string> = {
   unusable_target: 'target file could not be read (left untouched)',
   untranslated: 'no translation in the target file',
   needs_review: 'translation marked as needing review (not pushed)',
+  plural_entry:
+    'plural entry (one exported string cannot fill its forms; left as it stands)',
 };
 
 /**
@@ -301,23 +305,44 @@ export async function pullTranslations(
       const existingTargetEntries =
         read.state === 'usable' ? read.translations : new Map<string, string>();
 
+      // The export is one string per key, which cannot fill a plural entry's
+      // forms — gettext's msgstr[N], Android's <plurals> items. Applying it
+      // would replace the file's own forms with the source's, so such a key is
+      // reported skipped and the entry is carried forward as it stands.
+      const pluralEntries = sourceEntries.filter(
+        (entry) =>
+          keys[entry.key] !== undefined && hasPluralForms(entry.metadata)
+      );
+      const applicableKeys = { ...keys };
+      for (const entry of pluralEntries) {
+        skipped.push({
+          file: relPath,
+          locale,
+          reason: 'plural_entry',
+          key: entry.key,
+        });
+        delete applicableKeys[entry.key];
+      }
+
       const pulledEntries = sourceEntries
-        .filter((entry) => keys[entry.key] !== undefined)
+        .filter((entry) => applicableKeys[entry.key] !== undefined)
         .map((entry) => ({
           key: entry.key,
           value: entry.value,
-          translation: keys[entry.key]!,
+          translation: applicableKeys[entry.key]!,
           metadata: entry.metadata,
         }));
 
       if (pulledEntries.length === 0) {
-        skipped.push({ file: relPath, locale, reason: 'no_matches' });
+        if (pluralEntries.length === 0) {
+          skipped.push({ file: relPath, locale, reason: 'no_matches' });
+        }
         continue;
       }
 
       const translatedEntries = mergePulledTranslations(
         sourceEntries,
-        keys,
+        applicableKeys,
         existingTargetEntries
       );
 
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index c0e2d8f6..8031a33b 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -17,6 +17,45 @@ export function getParserForBucket(
   return formatRegistry.getParserByFormatKey(formatKey);
 }
 
+/**
+ * The metadata payloads a parser rebuilds an entry's plural content from:
+ * gettext's `plural_forms` (`msgstr[N]`) and Android XML's `plurals` items.
+ */
+const PLURAL_FORM_METADATA_KEYS = ['plural_forms', 'plurals'] as const;
+
+/**
+ * True when `reconstruct` would rebuild this entry's plural forms from its
+ * metadata rather than keep the ones the target file holds.
+ */
+export function hasPluralForms(
+  metadata: Record<string, unknown> | undefined
+): boolean {
+  return (
+    metadata !== undefined &&
+    PLURAL_FORM_METADATA_KEYS.some((key) => key in metadata)
+  );
+}
+
+/**
+ * An entry's metadata with the plural-form payloads left out.
+ *
+ * In a source entry's metadata those payloads hold the source file's own
+ * forms — empty `msgstr[N]` for gettext, source-language items for Android —
+ * so handing them to `reconstruct` for an entry whose plural forms this run
+ * did not translate replaces the target's translated forms with them. Without
+ * the payloads the parsers keep the target file's own plural lines.
+ */
+export function withoutPluralForms(
+  metadata: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  if (!hasPluralForms(metadata)) return metadata;
+  const rest = { ...metadata };
+  for (const key of PLURAL_FORM_METADATA_KEYS) {
+    delete rest[key];
+  }
+  return rest;
+}
+
 /**
  * Merge a TMS pull response over whatever the target file already holds: the
  * pulled value wins, an existing target value is kept when the response omits
@@ -43,7 +82,9 @@ export function mergePulledTranslations(
       key: entry.key,
       value: entry.value,
       context: entry.context,
-      metadata: entry.metadata,
+      // A pull never carries per-form plural translations — the export is one
+      // string per key — so the target file's own forms must survive the write.
+      metadata: withoutPluralForms(entry.metadata),
       translation,
     });
   }
diff --git a/tests/integration/sync-plural-carry-forward.integration.test.ts b/tests/integration/sync-plural-carry-forward.integration.test.ts
new file mode 100644
index 00000000..6355c749
--- /dev/null
+++ b/tests/integration/sync-plural-carry-forward.integration.test.ts
@@ -0,0 +1,407 @@
+/**
+ * Integration tests for plural entries a sync run carries forward.
+ *
+ * A carried-forward entry's `TranslatedEntry` is built from the SOURCE diff's
+ * metadata, and the plural payloads in that metadata are the source file's
+ * own — empty `msgstr[N]` for gettext, source-language `<item>`s for Android.
+ * `reconstruct` rebuilds plural content from exactly that metadata, so a run
+ * with any other work to do emptied a PO plural entry's forms, or reverted an
+ * Android `<plurals>` entry to source text, at exit 0. The forms a target file
+ * already holds must survive every path that rewrites the file for a sibling
+ * key: translate, validation withholding, and TMS pull.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { pullTranslations } from '../../src/sync/sync-tms';
+import { createTmsClient } from '../../src/sync/tms-client';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import {
+  TMS_BASE,
+  TMS_PROJECT,
+  tmsConfig,
+  approvedTmsTrust,
+} from '../helpers/tms-nock';
+import type { SyncLockFile } from '../../src/sync/types';
+
+const PO_HEADER = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '',
+  '',
+].join('\n');
+
+const PO_V1 =
+  PO_HEADER +
+  [
+    'msgid "Hello"',
+    'msgstr ""',
+    '',
+    'msgid "One %d file"',
+    'msgid_plural "%d files"',
+    'msgstr[0] ""',
+    'msgstr[1] ""',
+    '',
+  ].join('\n');
+
+const PO_V2 = PO_V1 + ['msgid "Bye"', 'msgstr ""', ''].join('\n');
+
+const ANDROID_V1 = [
+  '<?xml version="1.0" encoding="utf-8"?>',
+  '<resources>',
+  '    <string name="greeting">Hello</string>',
+  '    <plurals name="file_count">',
+  '        <item quantity="one">One %d file</item>',
+  '        <item quantity="other">Many files</item>',
+  '    </plurals>',
+  '</resources>',
+  '',
+].join('\n');
+
+const ANDROID_V2 = ANDROID_V1.replace(
+  '</resources>',
+  '    <string name="bye">Bye</string>\n</resources>'
+);
+
+/** Echo `[ES] <text>` per text, recording every text the engine was sent. */
+function replyEchoing(sent: string[]): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .persist()
+    .post('/v2/translate')
+    .reply(200, (_uri, body) => {
+      const texts = new URLSearchParams(body as string).getAll('text');
+      sent.push(...texts);
+      return {
+        translations: texts.map((t) => ({
+          text: `[ES] ${t}`,
+          detected_source_language: 'EN',
+          billed_characters: t.length,
+        })),
+      };
+    });
+}
+
+describe('sync with a plural entry carried forward', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  describe('PO', () => {
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-plural-'));
+      harness = createSyncHarness({ parsers: ['po'] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+    });
+
+    const sourcePath = () => path.join(tmpDir, 'locales', 'en', 'app.po');
+    const targetPath = () => path.join(tmpDir, 'locales', 'es', 'app.po');
+
+    async function establishProject(): Promise<void> {
+      fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+      fs.writeFileSync(sourcePath(), PO_V1, 'utf-8');
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const first = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+      expect(first.success).toBe(true);
+      nock.cleanAll();
+
+      const reviewed = fs
+        .readFileSync(targetPath(), 'utf-8')
+        .replace('msgstr[0] "[ES] One %d file"', 'msgstr[0] "Un archivo"')
+        .replace('msgstr[1] "[ES] %d files"', 'msgstr[1] "%d archivos"');
+      expect(reviewed).toContain('msgstr[0] "Un archivo"');
+      expect(reviewed).toContain('msgstr[1] "%d archivos"');
+      fs.writeFileSync(targetPath(), reviewed, 'utf-8');
+    }
+
+    it('keeps the reviewed msgstr[N] while translating a new sibling key', async () => {
+      await establishProject();
+
+      fs.writeFileSync(sourcePath(), PO_V2, 'utf-8');
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const second = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(second.success).toBe(true);
+      expect(second.newKeys).toBe(1);
+      expect(second.unwrittenKeys).toBe(0);
+      expect(second.fileResults.map((r) => r.failed)).toEqual([0]);
+      // The plural entry is carried, not re-translated: only the new key bills.
+      expect(sent).toEqual(['Bye']);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr[0] "Un archivo"');
+      expect(written).toContain('msgstr[1] "%d archivos"');
+      expect(written).toContain('msgstr "[ES] Bye"');
+    });
+
+    it('still rewrites the forms when the plural source itself changed', async () => {
+      await establishProject();
+
+      fs.writeFileSync(
+        sourcePath(),
+        PO_V1.replace('msgid_plural "%d files"', 'msgid_plural "%d documents"'),
+        'utf-8'
+      );
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const second = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(second.success).toBe(true);
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr[0] "[ES] One %d file"');
+      expect(written).toContain('msgstr[1] "[ES] %d documents"');
+      expect(written).not.toContain('Un archivo');
+    });
+
+    it('keeps the reviewed msgstr[N] when a re-translation is withheld', async () => {
+      await establishProject();
+
+      // The plural source gains a placeholder-carrying text and the engine
+      // starts dropping the substituted tokens, so the fresh translation is
+      // withheld and the entry falls back to what the target already holds.
+      fs.writeFileSync(
+        sourcePath(),
+        PO_V1.replace('msgid_plural "%d files"', 'msgid_plural "%d file(s)"'),
+        'utf-8'
+      );
+      nock(DEEPL_FREE_API_URL)
+        .persist()
+        .post('/v2/translate')
+        .reply(200, (_uri, body) => {
+          const texts = new URLSearchParams(body as string).getAll('text');
+          return {
+            translations: texts.map((t) => ({
+              text: `[ES] ${t.replace(/__VAR_\d+__/g, '').trim()}`,
+              detected_source_language: 'EN',
+              billed_characters: t.length,
+            })),
+          };
+        });
+      const second = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(second.fileResults.map((r) => r.failed)).toEqual([1]);
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr[0] "Un archivo"');
+      expect(written).toContain('msgstr[1] "%d archivos"');
+    });
+  });
+
+  describe('Android XML', () => {
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-plural-'));
+      harness = createSyncHarness({ parsers: ['android_xml'] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: {
+          android_xml: {
+            include: ['res/values/strings.xml'],
+            target_path_pattern: 'res/values-{locale}/strings.xml',
+          },
+        },
+      });
+    });
+
+    const sourcePath = () => path.join(tmpDir, 'res', 'values', 'strings.xml');
+    const targetPath = () =>
+      path.join(tmpDir, 'res', 'values-es', 'strings.xml');
+
+    async function establishProject(): Promise<void> {
+      fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+      fs.writeFileSync(sourcePath(), ANDROID_V1, 'utf-8');
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const first = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+      expect(first.success).toBe(true);
+      nock.cleanAll();
+
+      const reviewed = fs
+        .readFileSync(targetPath(), 'utf-8')
+        .replace('[ES] One %d file', 'Un archivo')
+        .replace('[ES] Many files', 'Muchos archivos');
+      expect(reviewed).toContain('Un archivo');
+      fs.writeFileSync(targetPath(), reviewed, 'utf-8');
+    }
+
+    it('keeps the reviewed <plurals> items while translating a new sibling key', async () => {
+      await establishProject();
+
+      fs.writeFileSync(sourcePath(), ANDROID_V2, 'utf-8');
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const second = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(second.success).toBe(true);
+      expect(second.newKeys).toBe(1);
+      expect(sent).toEqual(['Bye']);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('<item quantity="one">Un archivo</item>');
+      expect(written).toContain(
+        '<item quantity="other">Muchos archivos</item>'
+      );
+      expect(written).not.toContain('One %d file');
+      expect(written).toContain('[ES] Bye');
+    });
+
+    it('still rewrites the items when the plural source itself changed', async () => {
+      await establishProject();
+
+      fs.writeFileSync(
+        sourcePath(),
+        ANDROID_V1.replace('Many files', 'Many documents'),
+        'utf-8'
+      );
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const second = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(second.success).toBe(true);
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('<item quantity="one">[ES] One %d file</item>');
+      expect(written).toContain(
+        '<item quantity="other">[ES] Many documents</item>'
+      );
+      expect(written).not.toContain('Un archivo');
+    });
+  });
+
+  describe('TMS pull', () => {
+    let envSnapshot: NodeJS.ProcessEnv;
+
+    beforeEach(() => {
+      envSnapshot = { ...process.env };
+      process.env['TMS_API_KEY'] = 'env-key';
+      delete process.env['TMS_TOKEN'];
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-sync-plural-'));
+      harness = createSyncHarness({ parsers: ['po'] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        tms: tmsConfig(),
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+    });
+
+    afterEach(() => {
+      process.env = envSnapshot;
+    });
+
+    const sourcePath = () => path.join(tmpDir, 'locales', 'en', 'app.po');
+    const targetPath = () => path.join(tmpDir, 'locales', 'es', 'app.po');
+
+    function establishFiles(): void {
+      fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+      fs.writeFileSync(sourcePath(), PO_V1, 'utf-8');
+      fs.mkdirSync(path.dirname(targetPath()), { recursive: true });
+      fs.writeFileSync(
+        targetPath(),
+        PO_HEADER +
+          [
+            'msgid "Hello"',
+            'msgstr "Hola"',
+            '',
+            'msgid "One %d file"',
+            'msgid_plural "%d files"',
+            'msgstr[0] "Un archivo"',
+            'msgstr[1] "%d archivos"',
+            '',
+          ].join('\n'),
+        'utf-8'
+      );
+    }
+
+    function mockExport(keys: Record<string, string>): void {
+      nock(TMS_BASE)
+        .get(new RegExp(`/api/projects/${TMS_PROJECT}/keys/export`))
+        .query(true)
+        .reply(200, keys);
+    }
+
+    it('keeps the msgstr[N] of a plural entry the export does not carry', async () => {
+      establishFiles();
+      mockExport({ Hello: 'Hola TMS' });
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+      const result = await pullTranslations(config, client, harness.registry);
+
+      expect(result.pulled).toBe(1);
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr "Hola TMS"');
+      expect(written).toContain('msgstr[0] "Un archivo"');
+      expect(written).toContain('msgstr[1] "%d archivos"');
+    });
+
+    it('skips a plural entry the export does carry, with a per-key reason', async () => {
+      establishFiles();
+      mockExport({ Hello: 'Hola TMS', 'One %d file': 'Un archivo TMS' });
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+      const result = await pullTranslations(config, client, harness.registry);
+
+      // A TMS export carries one string per key, which cannot fill a plural
+      // entry's forms — the file keeps its own and the key is reported skipped,
+      // not counted as pulled or replaced.
+      expect(result.pulled).toBe(1);
+      expect(result.replaced).toBe(1);
+      expect(result.skipped).toEqual([
+        {
+          file: 'locales/en/app.po',
+          locale: 'es',
+          reason: 'plural_entry',
+          key: 'One %d file',
+        },
+      ]);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr[0] "Un archivo"');
+      expect(written).toContain('msgstr[1] "%d archivos"');
+      expect(written).not.toContain('Un archivo TMS');
+
+      // The lockfile records only what was applied: no pulled entry for the
+      // plural key.
+      const lock = JSON.parse(
+        fs.readFileSync(path.join(tmpDir, '.deepl-sync.lock'), 'utf-8')
+      ) as SyncLockFile;
+      const fileEntries = lock.entries['locales/en/app.po'] ?? {};
+      expect(fileEntries['One %d file']).toBeUndefined();
+      expect(fileEntries['Hello']?.translations['es']?.status).toBe(
+        'translated'
+      );
+    });
+  });
+});
diff --git a/tests/unit/formats/android-xml.test.ts b/tests/unit/formats/android-xml.test.ts
index a9a68d3f..a3d7d7d9 100644
--- a/tests/unit/formats/android-xml.test.ts
+++ b/tests/unit/formats/android-xml.test.ts
@@ -238,6 +238,21 @@ describe('android-xml parser', () => {
       expect(result).not.toContain('Goodbye');
     });
 
+    it('should keep a plurals element verbatim for an entry handed over without per-form translations', () => {
+      const xml = `<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <plurals name="items">
+        <item quantity="one">Un elemento</item>
+        <item quantity="other">%d elementos</item>
+    </plurals>
+</resources>`;
+      const translated: TranslatedEntry[] = [
+        { key: 'items', value: '%d items', translation: 'Un elemento' },
+      ];
+      const result = parser.reconstruct(xml, translated);
+      expect(result).toBe(xml);
+    });
+
     it('should remove plural elements not present in entries', () => {
       const xml = `<?xml version="1.0" encoding="utf-8"?>
 <resources>
diff --git a/tests/unit/sync/sync-locale-translator.test.ts b/tests/unit/sync/sync-locale-translator.test.ts
index 28cd2d0a..e7699ac1 100644
--- a/tests/unit/sync/sync-locale-translator.test.ts
+++ b/tests/unit/sync/sync-locale-translator.test.ts
@@ -37,6 +37,7 @@ jest.mock('../../../src/utils/logger', () => ({
 }));
 
 jest.mock('../../../src/sync/sync-utils', () => ({
+  ...jest.requireActual('../../../src/sync/sync-utils'),
   resolveTargetPath: jest.fn(),
   assertPathWithinRoot: jest.fn(),
 }));
@@ -1864,7 +1865,7 @@ describe('LocaleTranslator', () => {
       expect(warnings).toContain('check_placeholders');
     });
 
-    it('should reconstruct a withheld entry from the plural forms it was extracted with', async () => {
+    it('should hand a withheld entry over without plural forms so the target keeps its own', async () => {
       mockValidateBatch.mockReturnValueOnce([
         {
           key: 'items',
@@ -1908,13 +1909,15 @@ describe('LocaleTranslator', () => {
       const entries = (parser.reconstruct as jest.Mock).mock
         .calls[0]![1] as Array<{
         key: string;
+        translation: string;
         metadata?: Record<string, unknown>;
       }>;
       expect(entries).toHaveLength(1);
-      expect(entries[0]!.metadata?.['plurals']).toEqual([
-        { quantity: 'one', value: '1 item' },
-        { quantity: 'other', value: '%d items' },
-      ]);
+      // The extracted payload holds the source-language items, and the fresh
+      // translation was withheld — handing either over would replace the
+      // target's own forms. Without the payload the parser keeps them.
+      expect(entries[0]!.metadata?.['plurals']).toBeUndefined();
+      expect(entries[0]!.translation).toBe('1 Element (vorher)');
     });
 
     it('should validate the new-locale backfill batch and withhold its errors', async () => {
diff --git a/tests/unit/sync/sync-source-as-translation.test.ts b/tests/unit/sync/sync-source-as-translation.test.ts
index d80354a0..920321a8 100644
--- a/tests/unit/sync/sync-source-as-translation.test.ts
+++ b/tests/unit/sync/sync-source-as-translation.test.ts
@@ -44,6 +44,7 @@ jest.mock('../../../src/utils/logger', () => ({
 }));
 
 jest.mock('../../../src/sync/sync-utils', () => ({
+  ...jest.requireActual('../../../src/sync/sync-utils'),
   resolveTargetPath: jest.fn(),
   assertPathWithinRoot: jest.fn(),
 }));
diff --git a/tests/unit/sync/sync-utils.test.ts b/tests/unit/sync/sync-utils.test.ts
index 876e3dbe..07ac5556 100644
--- a/tests/unit/sync/sync-utils.test.ts
+++ b/tests/unit/sync/sync-utils.test.ts
@@ -6,6 +6,8 @@ import {
   assertPathWithinRoot,
   getParserForBucket,
   mergePulledTranslations,
+  hasPluralForms,
+  withoutPluralForms,
 } from '../../../src/sync/sync-utils';
 import { createDefaultRegistry } from '../../../src/formats';
 import { ValidationError } from '../../../src/utils/errors';
@@ -422,4 +424,75 @@ describe('mergePulledTranslations()', () => {
       )
     ).toEqual([]);
   });
+
+  it('should strip the plural-form payloads so the target file keeps its own forms', () => {
+    const merged = mergePulledTranslations(
+      [
+        {
+          key: 'One %d file',
+          value: 'One %d file',
+          metadata: {
+            msgid_plural: '%d files',
+            plural_forms: { 'msgstr[0]': '', 'msgstr[1]': '' },
+          },
+        },
+        {
+          key: 'file_count',
+          value: 'One file',
+          metadata: {
+            plurals: [{ quantity: 'one', value: 'One file' }],
+          },
+        },
+      ],
+      {},
+      new Map([
+        ['One %d file', 'Un archivo'],
+        ['file_count', 'Un archivo'],
+      ])
+    );
+
+    expect(merged).toEqual([
+      {
+        key: 'One %d file',
+        value: 'One %d file',
+        translation: 'Un archivo',
+        context: undefined,
+        metadata: { msgid_plural: '%d files' },
+      },
+      {
+        key: 'file_count',
+        value: 'One file',
+        translation: 'Un archivo',
+        context: undefined,
+        metadata: {},
+      },
+    ]);
+  });
+});
+
+describe('hasPluralForms() / withoutPluralForms()', () => {
+  it('recognises gettext and Android plural payloads', () => {
+    expect(hasPluralForms({ plural_forms: {} })).toBe(true);
+    expect(hasPluralForms({ plurals: [] })).toBe(true);
+    expect(hasPluralForms({ msgid_plural: '%d files' })).toBe(false);
+    expect(hasPluralForms({ flags: ['fuzzy'] })).toBe(false);
+    expect(hasPluralForms(undefined)).toBe(false);
+  });
+
+  it('strips only the plural payloads and keeps everything else', () => {
+    expect(
+      withoutPluralForms({
+        flags: ['fuzzy'],
+        msgid_plural: '%d files',
+        plural_forms: { 'msgstr[0]': '' },
+        plurals: [{ quantity: 'one', value: 'One file' }],
+      })
+    ).toEqual({ flags: ['fuzzy'], msgid_plural: '%d files' });
+  });
+
+  it('returns metadata without plural payloads unchanged, same reference', () => {
+    const metadata = { flags: ['fuzzy'] };
+    expect(withoutPluralForms(metadata)).toBe(metadata);
+    expect(withoutPluralForms(undefined)).toBeUndefined();
+  });
 });

From 39c640bdf1576540b38eae71f2b1a14b2fcc7854 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 09:51:17 +0200
Subject: [PATCH 184/256] fix(sync): keep a PO #, fuzzy flag on an entry whose
 content the run does not change
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

reconstruct's comment replay filtered 'fuzzy' out of every #, line it
emitted, and a run hands it every key the file should keep, so any sync
with other work to do removed a reviewer's do-not-ship marker from
carried-forward entries — after which sync status reported the project
complete again and msgfmt compiled the questioned translation.

The strip is now gated on the same content test the XLIFF writer applies
to its review state: the flag goes only when this run writes a different
msgstr (or a different msgstr[N]) over the entry. A carried-forward
entry's comment lines are kept byte-for-byte — a multi-flag line is no
longer re-joined either — measured with a byte diff across a sync whose
only work was a sibling key: the appended new entry is the file's only
change. A re-translation that produces different content still clears
the flag.

Refs cli-8kr2.76
---
 CHANGELOG.md                                  |   2 +
 src/formats/po.ts                             |  37 +++++-
 .../sync-bilingual-target.integration.test.ts |  40 ++++++
 tests/unit/formats/po.test.ts                 | 120 ++++++++++++++++++
 4 files changed, 193 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7b402c0..29bf9ada 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -151,6 +151,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a `#, fuzzy` flag on a carried-forward PO entry survives a run that rewrites the file for a sibling key.** The comment replay in the PO writer stripped `fuzzy` from every entry it emitted, and a run is handed every key the file should keep, so any sync with other work to do silently removed a reviewer's "do not ship" marker — after which `sync status` reported the project 100% complete again and `msgfmt` compiled the questioned translation into the catalog. Measured through the CLI: flag one synced key by hand (`sync status`: `50% (1 needs review)`, the behavior the needsReview counting was built on), add one new source key, `deepl sync --yes` — the flag was gone and `status` said `100%`, at exit 0. The flag is now stripped only when the run writes **different content** over the entry — the same test the XLIFF writer applies to its review `state` — comparing the msgstr and every `msgstr[N]` against what this run writes. A carried-forward entry now keeps its comment lines byte-for-byte (a `#, fuzzy, python-format` line is no longer re-joined either), verified with a byte diff across a sync whose only work was a sibling key: the only change in the file is the appended new entry. A re-translation that produces different content still clears the flag, and `msgfmt --statistics` confirms both directions.
+
 - **sync**: **a plural entry a run carries forward keeps its plural forms.** A carried-forward entry was handed to the file writer with the **source** file's plural payloads — empty `msgstr[N]` for gettext, source-language `<item>`s for Android XML — and plural content is rebuilt from exactly those payloads, so any run with other work to do destroyed the target's plural translations at exit 0. Measured through the CLI against a mock engine on three paths. **Translate**: a PO project holding a translated plural entry had `msgstr[0]` / `msgstr[1]` emptied by a sync whose only work was one new sibling key — `msgfmt --statistics` went from `3 translated messages` to `3 translated, 1 untranslated` — with the run misreporting its own destruction as `could not be given 1 translated key … the target file has no element to hold it` and the next sync re-translating and **re-billing** the entry. Android XML was worse: reviewer-corrected items (`Un archivo` / `Muchos archivos`) were silently reverted to the English source (`One file` / `Many files`) with no warning at all, because the reverted values are non-empty and the write-verification saw the key as present. **Validation withholding**: a stale plural entry whose fresh translation failed validation was supposed to keep what the file holds and emptied its forms instead. **Pull**: any `deepl sync pull` that rewrote a PO file emptied plural forms whether or not the export carried the plural key. The carry-forward sites and the pull merge now omit the plural payloads from what they hand the writer, so the parsers keep the file's own forms, and Android's writer keeps a `<plurals>` element verbatim for an entry handed over without per-form translations — a key absent from the entry list is still deleted. A plural entry whose source text actually changed is still re-translated with fresh forms. See docs/SYNC.md "A plural entry carried forward".
 
 - **sync**: **an XLIFF review `state` is no longer counted as a finished translation.** `<target state="needs-review-translation">` in 1.2 and `<segment state="initial">` in 2.0 mean a translation exists but is not approved; every read path took the `<target>` at face value, so a project shipping unapproved strings reported itself done. Measured end to end on a two-unit project through the CLI, in both versions: after flagging one unit with its source unchanged, `deepl sync status` said `100% (0 missing, 0 outdated)`, `--format json` said `needsReview: 0` and `complete: 2`, `sync validate` said `All translations passed validation` and `sync --dry-run` said `2 current`. The same project now reports `50% (0 missing, 0 outdated, 1 needs review)`. `deepl sync push` skips such a unit under the existing `needs_review` reason instead of uploading it as approved. The states are read as an explicit claim only: 1.2's `new` and `needs-*` values and 2.0's `initial` count, `translated` / `signed-off` / `final` / `reviewed` do not, and an **absent** attribute or a value outside those sets counts as complete — which is why an existing project's coverage does not move. In particular 2.0's documented `initial` default is deliberately not applied to a segment that carries no `state`, since that is the shape the CLI itself writes. `state-qualifier` (1.2) and `subState` (2.0) are different attributes and are not read. Nothing is re-translated, rewritten or re-billed; both ways out were measured — changing the state to `translated` returns the key to `complete` with **no API call**, and emptying the `<target>` has the next `deepl sync` translate it afresh.
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 197c8222..9f2bfb8e 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -495,6 +495,8 @@ export class PoFormatParser implements FormatParser {
       const entryLines: string[] = [];
       let entryMsgctxt: string | undefined;
       let entryMsgid = '';
+      let entryMsgstr: string | undefined;
+      const entryMsgstrPlural = new Map<number, string>();
       let target: ParseTarget | undefined;
 
       let backtrack = result.length - 1;
@@ -544,13 +546,16 @@ export class PoFormatParser implements FormatParser {
 
         const strPluralM = /^msgstr\[(\d+)]\s+(.*)$/.exec(el);
         if (strPluralM?.[1] && strPluralM[2] !== undefined) {
-          target = `msgstr[${parseInt(strPluralM[1], 10)}]`;
+          const idx = parseInt(strPluralM[1], 10);
+          entryMsgstrPlural.set(idx, unquote(strPluralM[2]));
+          target = `msgstr[${idx}]`;
           i++;
           continue;
         }
 
         const strM = /^msgstr\s+(.*)$/.exec(el);
         if (strM?.[1]) {
+          entryMsgstr = unquote(strM[1]);
           target = 'msgstr';
           i++;
           continue;
@@ -562,6 +567,14 @@ export class PoFormatParser implements FormatParser {
             entryMsgctxt = (entryMsgctxt ?? '') + continued;
           } else if (target === 'msgid') {
             entryMsgid += continued;
+          } else if (target === 'msgstr') {
+            entryMsgstr = (entryMsgstr ?? '') + continued;
+          } else if (target.startsWith('msgstr[')) {
+            const idx = parseInt(target.slice('msgstr['.length), 10);
+            entryMsgstrPlural.set(
+              idx,
+              (entryMsgstrPlural.get(idx) ?? '') + continued
+            );
           }
           i++;
           continue;
@@ -604,10 +617,26 @@ export class PoFormatParser implements FormatParser {
 
       emittedKeys.add(key);
 
+      const translation = translatedEntry.translation;
+      const pluralTranslations = translatedEntry.metadata?.['plural_forms'] as
+        Record<string, string> | undefined;
+
+      // The fuzzy flag describes the translation the entry holds, so it is
+      // stripped only when this run writes different content over it — the
+      // same content test XLIFF applies to its review `state`. An entry
+      // rewritten only because a sibling key changed keeps its comment lines
+      // byte-for-byte, reviewer markers included.
+      const writesChange =
+        (entryMsgstr !== undefined && translation !== entryMsgstr) ||
+        [...entryMsgstrPlural].some(([idx, existing]) => {
+          const pluralVal = pluralTranslations?.[`msgstr[${idx}]`];
+          return pluralVal !== undefined && pluralVal !== existing;
+        });
+
       const commentStart = result.length - commentLines.length;
       result.splice(commentStart, commentLines.length);
       for (const cl of commentLines) {
-        if (/^#,/.test(cl)) {
+        if (writesChange && /^#,/.test(cl)) {
           const flags = cl
             .slice(2)
             .trim()
@@ -621,10 +650,6 @@ export class PoFormatParser implements FormatParser {
         }
       }
 
-      const translation = translatedEntry.translation;
-      const pluralTranslations = translatedEntry.metadata?.['plural_forms'] as
-        Record<string, string> | undefined;
-
       let inMsgstr = false;
       let inMsgstrPlural = false;
 
diff --git a/tests/integration/sync-bilingual-target.integration.test.ts b/tests/integration/sync-bilingual-target.integration.test.ts
index d03d5a6f..e45e6144 100644
--- a/tests/integration/sync-bilingual-target.integration.test.ts
+++ b/tests/integration/sync-bilingual-target.integration.test.ts
@@ -441,6 +441,46 @@ describe('sync paths that read a bilingual target file', () => {
       ).toBe(before);
     });
 
+    it('keeps the reviewer flag on a carried-forward key while translating a new one', async () => {
+      await syncedThenFlagged();
+      write(
+        tmpDir,
+        'locales/en/app.po',
+        PO_HEADER +
+          'msgid "Hello"\nmsgstr ""\n\nmsgid "Bye"\nmsgstr ""\n\nmsgid "Welcome"\nmsgstr ""\n'
+      );
+      nock(DEEPL_FREE_API_URL)
+        .post('/v2/translate')
+        .times(2)
+        .reply(200, (_uri, body) => {
+          const parsed = new URLSearchParams(body as string);
+          return {
+            translations: parsed.getAll('text').map((t) => ({
+              text: `[es]${t}`,
+              detected_source_language: 'EN',
+              billed_characters: t.length,
+            })),
+          };
+        });
+
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      const written = fs.readFileSync(
+        path.join(tmpDir, 'locales/es/app.po'),
+        'utf-8'
+      );
+      expect(written).toContain('#, fuzzy\nmsgid "Bye"');
+      expect(written).toContain('msgstr "[es]Welcome"');
+
+      const status = await computeSyncStatus(
+        await loadSyncConfig(tmpDir),
+        harness.registry
+      );
+      expect(status.locales.find((l) => l.locale === 'es')!.needsReview).toBe(
+        1
+      );
+    });
+
     it('reports a project with no flags exactly as before', async () => {
       writeSyncConfig(tmpDir, {
         targetLocales: ['es'],
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index b8457764..150b8b4c 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -190,6 +190,126 @@ describe('PoFormatParser reconstruct', () => {
     expect(result).toContain('msgstr "Hallo"');
   });
 
+  it('should keep the fuzzy flag on an entry whose msgstr this run does not change', () => {
+    const template = ['#, fuzzy', 'msgid "greeting"', 'msgstr "Hallo"'].join(
+      '\n'
+    );
+
+    const entries: TranslatedEntry[] = [
+      { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+    ];
+
+    const result = parser.reconstruct(template, entries);
+
+    expect(result).toContain('#, fuzzy');
+    expect(result).toContain('msgstr "Hallo"');
+  });
+
+  it('should keep a multi-flag comment line verbatim when the msgstr is unchanged', () => {
+    const template = [
+      '#, fuzzy, python-format',
+      'msgid "count: %d"',
+      'msgstr "Anzahl: %d"',
+    ].join('\n');
+
+    const entries: TranslatedEntry[] = [
+      { key: 'count: %d', value: 'count: %d', translation: 'Anzahl: %d' },
+    ];
+
+    const result = parser.reconstruct(template, entries);
+
+    expect(result).toContain('#, fuzzy, python-format');
+  });
+
+  it('should keep the fuzzy flag when the unchanged msgstr is wrapped across continuation lines', () => {
+    const template = [
+      '#, fuzzy',
+      'msgid "greeting"',
+      'msgstr ""',
+      '"Hallo "',
+      '"Welt"',
+    ].join('\n');
+
+    const entries: TranslatedEntry[] = [
+      { key: 'greeting', value: 'Hello world', translation: 'Hallo Welt' },
+    ];
+
+    const result = parser.reconstruct(template, entries);
+
+    expect(result).toContain('#, fuzzy');
+    expect(result).toContain('msgstr "Hallo Welt"');
+  });
+
+  it('should keep the fuzzy flag on a plural entry whose forms are carried forward', () => {
+    const template = [
+      '#, fuzzy',
+      'msgid "One file"',
+      'msgid_plural "%d files"',
+      'msgstr[0] "Un archivo"',
+      'msgstr[1] "%d archivos"',
+    ].join('\n');
+
+    // A carried-forward entry travels without plural payloads, so the forms
+    // in the file are kept and the flag with them.
+    const entries: TranslatedEntry[] = [
+      { key: 'One file', value: 'One file', translation: 'Un archivo' },
+    ];
+
+    const result = parser.reconstruct(template, entries);
+
+    expect(result).toContain('#, fuzzy');
+    expect(result).toContain('msgstr[0] "Un archivo"');
+    expect(result).toContain('msgstr[1] "%d archivos"');
+  });
+
+  it('should strip the fuzzy flag from a plural entry rewritten with fresh forms', () => {
+    const template = [
+      '#, fuzzy',
+      'msgid "One file"',
+      'msgid_plural "%d files"',
+      'msgstr[0] "Un archivo"',
+      'msgstr[1] "%d archivos"',
+    ].join('\n');
+
+    const entries: TranslatedEntry[] = [
+      {
+        key: 'One file',
+        value: 'One file',
+        translation: 'Una ficha',
+        metadata: {
+          plural_forms: {
+            'msgstr[0]': 'Una ficha',
+            'msgstr[1]': '%d fichas',
+          },
+        },
+      },
+    ];
+
+    const result = parser.reconstruct(template, entries);
+
+    expect(result).not.toContain('fuzzy');
+    expect(result).toContain('msgstr[0] "Una ficha"');
+    expect(result).toContain('msgstr[1] "%d fichas"');
+  });
+
+  it('should write a catalog with no flags byte-identically when nothing changes', () => {
+    const template =
+      [
+        'msgid "greeting"',
+        'msgstr "Hallo"',
+        '',
+        'msgid "farewell"',
+        'msgstr "Tschuess"',
+      ].join('\n') + '\n';
+
+    const entries: TranslatedEntry[] = [
+      { key: 'greeting', value: 'Hello', translation: 'Hallo' },
+      { key: 'farewell', value: 'Bye', translation: 'Tschuess' },
+    ];
+
+    expect(parser.reconstruct(template, entries)).toBe(template);
+  });
+
   it('should use continuation line format for long msgstr with newlines', () => {
     const template = ['msgid "long_message"', 'msgstr ""'].join('\n');
 

From f4a3fdbb6aeaf925249534ef74aa0678dde00109 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 10:00:16 +0200
Subject: [PATCH 185/256] fix(translate): restore nested preservation tokens
 instead of refusing the translation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The preservation passes run in sequence over already-substituted text, so
a span preserved later can wrap an earlier pass's token: a fence token
inside an inline code span, a code token inside a brace-shaped variable.
Restore and the loss check both walked the map in insertion order, so the
inner token was processed before the outer span re-introduced it —
translate --preserve-code refused such input at exit 5 blaming the
endpoint for a placeholder the CLI had nested itself, and the round-trip
property failed (three lines expected, one received).

restorePlaceholders now expands tokens in reverse insertion order — a
stored value can only contain tokens preserved before it, so one pass
unfolds every level — and unresolvedPlaceholders counts a token as
surviving when it sits inside a later span that itself survived. Pinned
the fast-check counterexample byte for byte, plus the brace-wrapping
sibling shape and a genuine-loss guard; four consecutive random-seed
property runs green.

Refs cli-8kr2.72
---
 CHANGELOG.md                         |  2 ++
 src/utils/text-preservation.ts       | 27 ++++++++++++---
 tests/unit/text-preservation.test.ts | 49 ++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 29bf9ada..809d74c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -151,6 +151,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **translate**: **code preservation survives a fenced block overlapping an inline code span.** The preservation passes run in sequence over already-substituted text, so a span preserved later can wrap an earlier pass's token — `` ` ``` ``…``` ` `` makes the inline pass preserve `` ` __CODE_0__ ` `` as `__CODE_1__`, and a brace-shaped span can wrap a code token the same way (`{`x`}`). Both the restore and the loss check walked the map in insertion order, so the inner token was expanded after its own pass had already run — `deepl translate --preserve-code` on that input refused the translation at exit 5 with `The translation lost the placeholder …`, blaming the endpoint for a token the CLI had nested itself, and the round-trip law (`preserve → identity-translate → restore` is the identity) failed under fast-check seed 2139537717 with three lines expected and one received. Restore now expands tokens in reverse insertion order — a stored value can only contain tokens preserved before it, so one pass unfolds every level — and the loss check counts a token as surviving when it sits inside a later span that itself survived, in the sync validator as well as the translate-path assert. The same input now translates at exit 0 with every line restored verbatim, the pinned seed replays green, and four consecutive random-seed property runs stay green.
+
 - **sync**: **a `#, fuzzy` flag on a carried-forward PO entry survives a run that rewrites the file for a sibling key.** The comment replay in the PO writer stripped `fuzzy` from every entry it emitted, and a run is handed every key the file should keep, so any sync with other work to do silently removed a reviewer's "do not ship" marker — after which `sync status` reported the project 100% complete again and `msgfmt` compiled the questioned translation into the catalog. Measured through the CLI: flag one synced key by hand (`sync status`: `50% (1 needs review)`, the behavior the needsReview counting was built on), add one new source key, `deepl sync --yes` — the flag was gone and `status` said `100%`, at exit 0. The flag is now stripped only when the run writes **different content** over the entry — the same test the XLIFF writer applies to its review `state` — comparing the msgstr and every `msgstr[N]` against what this run writes. A carried-forward entry now keeps its comment lines byte-for-byte (a `#, fuzzy, python-format` line is no longer re-joined either), verified with a byte diff across a sync whose only work was a sibling key: the only change in the file is the appended new entry. A re-translation that produces different content still clears the flag, and `msgfmt --statistics` confirms both directions.
 
 - **sync**: **a plural entry a run carries forward keeps its plural forms.** A carried-forward entry was handed to the file writer with the **source** file's plural payloads — empty `msgstr[N]` for gettext, source-language `<item>`s for Android XML — and plural content is rebuilt from exactly those payloads, so any run with other work to do destroyed the target's plural translations at exit 0. Measured through the CLI against a mock engine on three paths. **Translate**: a PO project holding a translated plural entry had `msgstr[0]` / `msgstr[1]` emptied by a sync whose only work was one new sibling key — `msgfmt --statistics` went from `3 translated messages` to `3 translated, 1 untranslated` — with the run misreporting its own destruction as `could not be given 1 translated key … the target file has no element to hold it` and the next sync re-translating and **re-billing** the entry. Android XML was worse: reviewer-corrected items (`Un archivo` / `Muchos archivos`) were silently reverted to the English source (`One file` / `Many files`) with no warning at all, because the reverted values are non-empty and the write-verification saw the key as present. **Validation withholding**: a stale plural entry whose fresh translation failed validation was supposed to keep what the file holds and emptied its forms instead. **Pull**: any `deepl sync pull` that rewrote a PO file emptied plural forms whether or not the export carried the plural key. The carry-forward sites and the pull merge now omit the plural payloads from what they hand the writer, so the parsers keep the file's own forms, and Android's writer keeps a `<plurals>` element verbatim for an entry handed over without per-form translations — a key absent from the entry list is still deleted. A plural entry whose source text actually changed is still re-translated with fresh forms. See docs/SYNC.md "A plural entry carried forward".
diff --git a/src/utils/text-preservation.ts b/src/utils/text-preservation.ts
index 4aab54d9..b270e3a1 100644
--- a/src/utils/text-preservation.ts
+++ b/src/utils/text-preservation.ts
@@ -70,13 +70,26 @@ export function unresolvedPlaceholders(
   text: string,
   preservationMap: Map<string, string>
 ): string[] {
+  // The preservation passes run in sequence over already-substituted text, so
+  // a span preserved later can hold an earlier pass's token (a fence token
+  // inside an inline code span, a code token inside a brace-shaped variable).
+  // Such an earlier token is legitimately absent from the engine's output: it
+  // survives inside the stored value of the later token. Scanning in reverse
+  // insertion order lets each token count the values already found intact.
   const missing: string[] = [];
-  for (const [placeholder, original] of preservationMap.entries()) {
-    if (!text.includes(placeholder)) {
+  const survivingValues: string[] = [];
+  const entries = [...preservationMap.entries()].reverse();
+  for (const [placeholder, original] of entries) {
+    if (
+      text.includes(placeholder) ||
+      survivingValues.some((value) => value.includes(placeholder))
+    ) {
+      survivingValues.push(original);
+    } else {
       missing.push(original);
     }
   }
-  return missing;
+  return missing.reverse();
 }
 
 /**
@@ -121,7 +134,13 @@ export function restorePlaceholders(
   preservationMap: Map<string, string>
 ): string {
   let restored = text;
-  for (const [placeholder, original] of preservationMap.entries()) {
+  // Reverse insertion order: a span preserved later can hold an earlier
+  // token, so the later token must be expanded first for the earlier one to
+  // be visible at all. A stored value can only contain tokens preserved
+  // before it — the value was captured from text as it stood then — so one
+  // pass in this order expands every level of nesting.
+  const entries = [...preservationMap.entries()].reverse();
+  for (const [placeholder, original] of entries) {
     // Single pass per placeholder: `original` may itself contain the
     // placeholder token (a locale value shaped like `{__VAR_0__}`), so any
     // loop that re-scans the output would never terminate.
diff --git a/tests/unit/text-preservation.test.ts b/tests/unit/text-preservation.test.ts
index b1d3a33b..e2edf98d 100644
--- a/tests/unit/text-preservation.test.ts
+++ b/tests/unit/text-preservation.test.ts
@@ -2,6 +2,7 @@ import {
   preserveCodeBlocks,
   preserveVariables,
   restorePlaceholders,
+  unresolvedPlaceholders,
 } from '../../src/utils/text-preservation.js';
 
 describe('text-preservation', () => {
@@ -216,4 +217,52 @@ describe('text-preservation', () => {
       expect(restored).toBe(original);
     });
   });
+
+  describe('nested preservation (a later span wrapping an earlier token)', () => {
+    // FC_SEED=2139537717 FC_PATH="383:2:3:10:15:15:14" counterexample: the
+    // fence pass substitutes __CODE_0__, then the inline pass preserves
+    // "` __CODE_0__ `" as __CODE_1__, so __CODE_1__'s stored value carries an
+    // earlier token.
+    const OVERLAP = '` ```\nfenced block\n``` `inline code`';
+
+    it('round-trips a fence overlapping an inline code span byte for byte', () => {
+      const map = new Map<string, string>();
+      const processed = preserveVariables(
+        preserveCodeBlocks(OVERLAP, map),
+        map
+      );
+
+      expect(restorePlaceholders(processed, map)).toBe(OVERLAP);
+    });
+
+    it('round-trips a variable-shaped span wrapping a preserved code token', () => {
+      const original = 'set {`x`} here';
+      const map = new Map<string, string>();
+      const processed = preserveVariables(
+        preserveCodeBlocks(original, map),
+        map
+      );
+
+      expect(restorePlaceholders(processed, map)).toBe(original);
+    });
+
+    it('does not report a token that survives inside a later resolved span', () => {
+      const map = new Map<string, string>();
+      const processed = preserveVariables(
+        preserveCodeBlocks(OVERLAP, map),
+        map
+      );
+
+      expect(unresolvedPlaceholders(processed, map)).toEqual([]);
+    });
+
+    it('reports both spans lost when the outer token is gone', () => {
+      const map = new Map<string, string>();
+      preserveVariables(preserveCodeBlocks(OVERLAP, map), map);
+
+      const missing = unresolvedPlaceholders('the engine ate it all', map);
+
+      expect(missing).toEqual(['```\nfenced block\n```', '` __CODE_0__ `']);
+    });
+  });
 });

From c206d9a2cf1e4dabbdd39afeab0a4b4ca540a622 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 10:13:18 +0200
Subject: [PATCH 186/256] fix(sync): report an unreadable target as a validate
 issue instead of ending the command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A target-file parse failure propagated out of sync validate's walk and
ended the whole command at exit 1 with a raw parser message, so a project
with fifty locales and one corrupt file was told about the corrupt file
and nothing about the other forty-nine. Every other path already refuses
one file loudly and carries on.

validate now reads targets through readTargetFile like the rest of the
pipeline: an absent file still skips the locale silently, and an
unreadable one becomes an error-severity issue under an unusable_target
check — counting toward exit 8, phrased for the command that only reads —
while every other locale and file is validated and reported beside it.
Deliberately not a warn-and-skip, which would let CI go green over a
locale nobody validated. totalChecked and passed keep counting only pairs
actually compared.

sync audit needed no change: measured on the same fixture, it already
excludes such a locale from the comparison and reports it under
missingTargets at its normal exit code. sync export reads no target
files at all.

Refs cli-8kr2.75
---
 CHANGELOG.md                                  |  4 +
 docs/API.md                                   |  2 +-
 docs/SYNC.md                                  |  2 +
 src/sync/sync-target-read.ts                  | 16 ++++
 src/sync/sync-validate.ts                     | 46 +++++++---
 tests/e2e/cli-sync.e2e.test.ts                | 23 +++++
 .../sync-unusable-target.integration.test.ts  | 90 +++++++++++++++++++
 tests/unit/sync/sync-validate.test.ts         |  7 +-
 8 files changed, 176 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 809d74c4..8487ba6b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **`deepl sync validate` exits 8 where it exited 1 on a project whose target file cannot be read, and its `--format json` issues list gains a new check kind.** A consumer that treated exit 1 as "the CLI crashed" starts seeing the documented check-failure code with a full report attached, and a JSON consumer iterating `issues` will meet entries whose `check` is `unusable_target`, whose `key` and `file` are both the target path, and whose `source`/`translation` are empty. See Fixed.
+
 - **sync**: **`deepl sync pull` no longer applies an exported value to a plural entry, and its counts move.** The export carries one string per key, which cannot fill a plural entry's forms; that value used to be applied nowhere while the entry's forms were emptied and the key was still counted as pulled and replaced. Such a key is now reported under a new `plural_entry` skip reason in the `(N skipped: …)` summary and in `--format json`, is not counted in `pulled` or `replaced`, and no lockfile entry is recorded for it. A consumer reconciling pull counts against the export's key list will see the difference; the export itself is requested exactly as before. See Fixed.
 
 - **sync**: **`deepl sync status` reports a lower coverage percentage for an XLIFF project whose targets carry a review `state`, and `deepl sync` writes `state="translated"` where it used to leave the old value.** A dashboard or CI check reading `coverage` or `complete` out of that command will see an XLIFF project it called 100% drop to whatever share of its units are actually approved, and `deepl sync push` reports a lower pushed count by the same number. The written bytes change only for a target that already carried a `state` and whose translation this run replaced; a target with no `state` is written exactly as before. The `sync status` explanation of the `needsReview` count no longer describes gettext alone — it named `#, fuzzy`, `msgfmt` and "clear the msgstr" to users of a format that has none of those. `sync --frozen` still passes. See Fixed.
@@ -151,6 +153,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`deepl sync validate` validates the rest of the project when one target file cannot be read.** A target-file parse failure propagated out of the walk and ended the whole command at exit 1 with a raw parser message (`Error: Expected double-quoted property name in JSON at position 32`, `UnknownError` in the JSON envelope) — a project with fifty locales and one corrupt file was told about the corrupt file and nothing about the other forty-nine, which is the opposite of what a validation command is for. Every other path already refuses one file and carries on. The unreadable file is now an `error`-severity issue like any other — reported under an `unusable_target` check with the file, the locale and the parser's reason, counting toward exit **8** — and every other locale and file is validated and reported alongside it. Deliberately **not** a warn-and-skip: validate exiting 0 over a file it never validated would turn CI green on an unvalidated locale, which is strictly worse than dying. A locale with no target file at all is still skipped silently, `totalChecked`/`passed` keep counting only pairs actually compared, and a healthy project's output is byte-identical. `deepl sync audit` needed no change — measured on the same fixture, it already excludes such a locale from the comparison and reports it under `missingTargets` at its normal exit code.
+
 - **translate**: **code preservation survives a fenced block overlapping an inline code span.** The preservation passes run in sequence over already-substituted text, so a span preserved later can wrap an earlier pass's token — `` ` ``` ``…``` ` `` makes the inline pass preserve `` ` __CODE_0__ ` `` as `__CODE_1__`, and a brace-shaped span can wrap a code token the same way (`{`x`}`). Both the restore and the loss check walked the map in insertion order, so the inner token was expanded after its own pass had already run — `deepl translate --preserve-code` on that input refused the translation at exit 5 with `The translation lost the placeholder …`, blaming the endpoint for a token the CLI had nested itself, and the round-trip law (`preserve → identity-translate → restore` is the identity) failed under fast-check seed 2139537717 with three lines expected and one received. Restore now expands tokens in reverse insertion order — a stored value can only contain tokens preserved before it, so one pass unfolds every level — and the loss check counts a token as surviving when it sits inside a later span that itself survived, in the sync validator as well as the translate-path assert. The same input now translates at exit 0 with every line restored verbatim, the pinned seed replays green, and four consecutive random-seed property runs stay green.
 
 - **sync**: **a `#, fuzzy` flag on a carried-forward PO entry survives a run that rewrites the file for a sibling key.** The comment replay in the PO writer stripped `fuzzy` from every entry it emitted, and a run is handed every key the file should keep, so any sync with other work to do silently removed a reviewer's "do not ship" marker — after which `sync status` reported the project 100% complete again and `msgfmt` compiled the questioned translation into the catalog. Measured through the CLI: flag one synced key by hand (`sync status`: `50% (1 needs review)`, the behavior the needsReview counting was built on), add one new source key, `deepl sync --yes` — the flag was gone and `status` said `100%`, at exit 0. The flag is now stripped only when the run writes **different content** over the entry — the same test the XLIFF writer applies to its review `state` — comparing the msgstr and every `msgstr[N]` against what this run writes. A carried-forward entry now keeps its comment lines byte-for-byte (a `#, fuzzy, python-format` line is no longer re-joined either), verified with a byte diff across a sync whose only work was a sibling key: the only change in the file is the appended new entry. A re-translation that produces different content still clears the flag, and `msgfmt --statistics` confirms both directions.
diff --git a/docs/API.md b/docs/API.md
index f4d7a72e..6d77b5a7 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3421,7 +3421,7 @@ Remediation: run `deepl config get` to inspect the current config, or edit the f
 A check-style command ran successfully but found actionable issues. Exit is *soft* — `process.exitCode` is set so cleanup still runs. Emitted by:
 
 - `deepl write --check <text|file>` when the Write API would suggest changes (`needsImprovement === true`)
-- `deepl sync validate` when validation surfaces one or more `error`-severity issues (missing placeholders, format-string mismatches, unbalanced HTML tags)
+- `deepl sync validate` when validation surfaces one or more `error`-severity issues (missing placeholders, format-string mismatches, unbalanced HTML tags, or a target file on disk that could not be read — reported under an `unusable_target` check while every other locale is still validated)
 
 This code is specifically designed for CI use: a `check` step can block a merge without requiring try/catch wrappers in the calling script. It does **not** indicate a CLI failure.
 
diff --git a/docs/SYNC.md b/docs/SYNC.md
index f7bfc191..0595f7fe 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -218,6 +218,8 @@ The locale is left out of the character estimate because the run bills nothing f
 
 `deepl sync pull` skips the locale under the `unusable_target` skip reason — or `key_collision` when that is the cause, which has its own remediation (see below) — and leaves the file exactly as it stands. `deepl sync push` reports a file that is not there under `target_missing` and surfaces every other failure, since it only reads.
 
+`deepl sync validate` reports the file as an error-severity issue under an `unusable_target` check and goes on to validate every other locale and file. A file nobody could read holds translations nobody validated, so skipping it with a warning would let the command exit 0 — CI green — over an unvalidated locale; the issue counts toward exit **8** like any other error. In `--format json` it appears in `issues` with the target path as its `key` and `file`, an empty `source`/`translation`, and the reason in its message; such a file's keys are not counted in `totalChecked` or `passed`, which keep meaning "pairs actually compared". A locale with no target file at all is still skipped silently — never having been synced is not a validation failure. `deepl sync audit` excludes the locale from the comparison and lists it under `missingTargets` at its normal exit code: audit is a report, not a gate.
+
 The distinction is deliberately strict: an errno the CLI does not recognise refuses the file rather than admitting it. A file that is genuinely absent produces `ENOENT` and nothing else.
 
 ### Key separators and colliding keys
diff --git a/src/sync/sync-target-read.ts b/src/sync/sync-target-read.ts
index 7ee34e36..af9a3a34 100644
--- a/src/sync/sync-target-read.ts
+++ b/src/sync/sync-target-read.ts
@@ -67,6 +67,22 @@ export function unusableTargetMessage(relPath: string, reason: string): string {
   );
 }
 
+/**
+ * The same condition for `deepl sync validate`, which only reads: nothing was
+ * left unwritten, but nothing was checked either, and a pass that stayed
+ * silent about that would let CI go green over a file it never looked at.
+ */
+export function unvalidatedTargetMessage(
+  relPath: string,
+  reason: string
+): string {
+  return (
+    `target file ${relPath} is on disk but could not be read (${reason}) — ` +
+    'its translations were not validated. Fix the file, then run ' +
+    '`deepl sync validate` again.'
+  );
+}
+
 /**
  * The same condition as `unusableTargetMessage`, in the voice a preview needs:
  * `--dry-run` has not left the file anywhere yet, and saying that it had would
diff --git a/src/sync/sync-validate.ts b/src/sync/sync-validate.ts
index 4ee482fa..f502ba66 100644
--- a/src/sync/sync-validate.ts
+++ b/src/sync/sync-validate.ts
@@ -1,4 +1,3 @@
-import * as fs from 'fs';
 import * as path from 'path';
 import type { FormatRegistry } from '../formats/index.js';
 import {
@@ -11,6 +10,10 @@ import {
   extractExistingTranslations,
   walkBuckets,
 } from './sync-bucket-walker.js';
+import {
+  readTargetFile,
+  unvalidatedTargetMessage,
+} from './sync-target-read.js';
 
 export interface ValidateIssue extends ValidationResult {
   locale: string;
@@ -31,6 +34,10 @@ export async function validateTranslations(
 ): Promise<ValidateResult> {
   const allIssues: ValidateIssue[] = [];
   let totalChecked = 0;
+  // File-level issues: an unreadable target holds translations nobody checked.
+  // They count toward `errors` (exit 8) but not toward `totalChecked`, so
+  // `passed` keeps meaning "checked pairs with no issue".
+  let unreadableTargets = 0;
 
   for await (const walked of walkBuckets(config, formatRegistry)) {
     const {
@@ -59,17 +66,34 @@ export async function validateTranslations(
         const targetAbsPath = path.join(config.projectRoot, targetRelPath);
         assertPathWithinRoot(targetAbsPath, config.projectRoot);
 
-        try {
-          await fs.promises.access(targetAbsPath);
-        } catch {
+        const read = await readTargetFile(parser, targetAbsPath);
+        if (read.state === 'absent') {
+          // A locale that has never been synced has nothing to validate.
           continue;
         }
-
-        const targetContent = await fs.promises.readFile(
-          targetAbsPath,
-          'utf-8'
-        );
-        targetMap = extractExistingTranslations(parser, targetContent);
+        if (read.state === 'unusable') {
+          // Skipping with a warning would let the command exit 0 over a file
+          // it never validated; dying on it would leave every other locale
+          // unreported. It is an error-severity issue like any other.
+          unreadableTargets++;
+          allIssues.push({
+            key: targetRelPath,
+            source: '',
+            translation: '',
+            severity: 'error',
+            issues: [
+              {
+                check: 'unusable_target',
+                severity: 'error',
+                message: unvalidatedTargetMessage(targetRelPath, read.reason),
+              },
+            ],
+            locale,
+            file: targetRelPath,
+          });
+          continue;
+        }
+        targetMap = read.translations;
       }
 
       const pairs = sourceEntries
@@ -91,7 +115,7 @@ export async function validateTranslations(
 
   const warnings = allIssues.filter((i) => i.severity === 'warn').length;
   const errors = allIssues.filter((i) => i.severity === 'error').length;
-  const passed = totalChecked - allIssues.length;
+  const passed = totalChecked - (allIssues.length - unreadableTargets);
 
   return { totalChecked, passed, warnings, errors, issues: allIssues };
 }
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 6dc9316a..84f20025 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -1070,6 +1070,29 @@ describe('CLI Sync E2E', () => {
       expect(result.output.toLowerCase()).toMatch(/placeholder|welcome/);
     });
 
+    it('exits with CheckFailed (8) on an unreadable target file, after validating the rest', () => {
+      writeSyncConfig(testFiles.path, ['de', 'fr']);
+      const dir = path.join(testFiles.path, 'locales');
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'en.json'),
+        JSON.stringify({ welcome: 'Hello {name}' }, null, 2) + '\n'
+      );
+      fs.writeFileSync(
+        path.join(dir, 'de.json'),
+        JSON.stringify({ welcome: 'Hallo {name}' }, null, 2) + '\n'
+      );
+      fs.writeFileSync(path.join(dir, 'fr.json'), '{ not json at all');
+
+      const result = runSyncExpectError('validate');
+      expect(result.status).toBe(8);
+      // The healthy locale was still validated, and the unreadable file is
+      // reported as the issue rather than ending the command.
+      expect(result.output).toMatch(/Checked 1 translation/);
+      expect(result.output).toContain('fr.json');
+      expect(result.output).toMatch(/could not be read/);
+    });
+
     it('does not emit raw terminal control characters from a hostile i18n key', () => {
       writeSyncConfig(testFiles.path, ['de']);
       const dir = path.join(testFiles.path, 'locales');
diff --git a/tests/integration/sync-unusable-target.integration.test.ts b/tests/integration/sync-unusable-target.integration.test.ts
index 92e32514..11559c29 100644
--- a/tests/integration/sync-unusable-target.integration.test.ts
+++ b/tests/integration/sync-unusable-target.integration.test.ts
@@ -18,6 +18,7 @@ jest.unmock('fast-glob');
 import nock from 'nock';
 
 import { loadSyncConfig } from '../../src/sync/sync-config';
+import { validateTranslations } from '../../src/sync/sync-validate';
 import { Logger } from '../../src/utils/logger';
 import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
 import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
@@ -274,3 +275,92 @@ describe('sync over a target file that cannot be read', () => {
     });
   });
 });
+
+describe('sync validate over a target file that cannot be read', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-validate-unusable-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es', 'fr'],
+      buckets: { json: { include: ['locales/en.json'] } },
+    });
+    const dir = path.join(tmpDir, 'locales');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, 'en.json'),
+      JSON.stringify({ greeting: 'Hello {name}' }, null, 2) + '\n',
+      'utf-8'
+    );
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  function write(locale: string, content: string): void {
+    fs.writeFileSync(path.join(tmpDir, 'locales', `${locale}.json`), content);
+  }
+
+  it('reports the unreadable file as an error and still validates the other locale', async () => {
+    // es drops the placeholder, so a validated es proves the walk went on.
+    write('es', JSON.stringify({ greeting: 'Hola' }, null, 2) + '\n');
+    write('fr', '{ "greeting": "Bonjour {name}", %%% not json');
+
+    const result = await validateTranslations(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const frIssue = result.issues.find((i) => i.locale === 'fr');
+    expect(frIssue).toBeDefined();
+    expect(frIssue!.severity).toBe('error');
+    expect(frIssue!.issues[0]!.check).toBe('unusable_target');
+    expect(frIssue!.issues[0]!.message).toContain('locales/fr.json');
+    expect(frIssue!.issues[0]!.message).toContain('not validated');
+
+    const esIssue = result.issues.find((i) => i.locale === 'es');
+    expect(esIssue).toBeDefined();
+    expect(esIssue!.issues[0]!.message).toContain('{name}');
+
+    expect(result.totalChecked).toBe(1);
+    expect(result.passed).toBe(0);
+    expect(result.errors).toBe(2);
+  });
+
+  it('still skips a locale with no target file at all', async () => {
+    write('es', JSON.stringify({ greeting: 'Hola {name}' }, null, 2) + '\n');
+
+    const result = await validateTranslations(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    expect(result.issues).toEqual([]);
+    expect(result.totalChecked).toBe(1);
+    expect(result.passed).toBe(1);
+  });
+
+  it('leaves a healthy project result unchanged', async () => {
+    write('es', JSON.stringify({ greeting: 'Hola {name}' }, null, 2) + '\n');
+    write('fr', JSON.stringify({ greeting: 'Bonjour {name}' }, null, 2) + '\n');
+
+    const result = await validateTranslations(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    expect(result).toEqual({
+      totalChecked: 2,
+      passed: 2,
+      warnings: 0,
+      errors: 0,
+      issues: [],
+    });
+  });
+});
diff --git a/tests/unit/sync/sync-validate.test.ts b/tests/unit/sync/sync-validate.test.ts
index 41602ae4..c91c5903 100644
--- a/tests/unit/sync/sync-validate.test.ts
+++ b/tests/unit/sync/sync-validate.test.ts
@@ -133,8 +133,11 @@ describe('validateTranslations', () => {
 
   it('should skip missing target file gracefully', async () => {
     const source = [{ key: 'greeting', value: 'Hello' }] as ExtractedEntry[];
-    mockReadFile.mockResolvedValueOnce('source');
-    mockAccess.mockRejectedValueOnce(new Error('ENOENT'));
+    mockReadFile
+      .mockResolvedValueOnce('source')
+      .mockRejectedValueOnce(
+        Object.assign(new Error('ENOENT: no such file'), { code: 'ENOENT' })
+      );
     const parser: FormatParser = {
       name: 'JSON',
       configKey: 'json',

From 7e841b2567af315fd1ef4bb9b0e833fa9dd83fc5 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 10:25:36 +0200
Subject: [PATCH 187/256] fix(sync): write the --format json error envelope to
 stdout, the machine stream
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The envelope went to stderr, which is also where every diagnostic goes —
the CLI's own warnings and anything the Node runtime emits — so a
consumer capturing stderr got valid JSON only when nothing else happened
to be said, and the failure path was the one case sharing a stream.
Measured: sync validate --format json with a group-readable config file
interleaved the mode-tightening warning and the envelope on stderr, with
stdout empty.

The envelope is the command's result in the failure case, so it now lands
where the success payload already does, for every sync subcommand at once
(init's inline config-already-exists envelope goes through the shared
emitter and moves with it). Exit codes are unchanged and remain the
failure signal; warnings stay on stderr, where they can no longer break
the parse — asserted end to end with the CLI's own warning firing beside
a JSON.parse of the whole of stdout.

Refs cli-6lqs
---
 CHANGELOG.md                                  |  4 ++
 docs/API.md                                   |  6 +--
 docs/SYNC.md                                  |  6 +--
 examples/24-sync-live-validation.sh           |  4 +-
 src/cli/commands/sync/register-sync-init.ts   | 18 +++------
 src/cli/commands/sync/sync-options.ts         | 11 +++++-
 tests/e2e/cli-sync-error-envelope.e2e.test.ts | 37 +++++++++++++++----
 tests/e2e/cli-sync-glob-bomb.e2e.test.ts      | 18 ++++-----
 tests/e2e/cli-sync-init.e2e.test.ts           |  2 +-
 tests/e2e/cli-sync-option-routing.e2e.test.ts |  2 +-
 tests/e2e/cli-sync-push-pull.e2e.test.ts      |  8 ++--
 tests/e2e/cli-sync.e2e.test.ts                |  4 +-
 tests/helpers/assert-error-envelope.ts        | 18 ++++-----
 13 files changed, 82 insertions(+), 56 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8487ba6b..c3a5a745 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **the `--format json` error envelope moves from stderr to stdout, for every sync subcommand at once.** A consumer that read the failure reason off stderr stops finding it there: `deepl sync … --format json 2>err.json` now captures only human-facing warnings, and the envelope arrives where `> out.json` already captured the success payload, so one redirection handles both cases. Exit codes are unchanged and remain the failure signal. Anything branching on *the presence of* stderr output still works — warnings still go there — but anything *parsing* stderr must switch to stdout. See Fixed.
+
 - **sync**: **`deepl sync validate` exits 8 where it exited 1 on a project whose target file cannot be read, and its `--format json` issues list gains a new check kind.** A consumer that treated exit 1 as "the CLI crashed" starts seeing the documented check-failure code with a full report attached, and a JSON consumer iterating `issues` will meet entries whose `check` is `unusable_target`, whose `key` and `file` are both the target path, and whose `source`/`translation` are empty. See Fixed.
 
 - **sync**: **`deepl sync pull` no longer applies an exported value to a plural entry, and its counts move.** The export carries one string per key, which cannot fill a plural entry's forms; that value used to be applied nowhere while the entry's forms were emptied and the key was still counted as pulled and replaced. Such a key is now reported under a new `plural_entry` skip reason in the `(N skipped: …)` summary and in `--format json`, is not counted in `pulled` or `replaced`, and no lockfile entry is recorded for it. A consumer reconciling pull counts against the export's key list will see the difference; the export itself is requested exactly as before. See Fixed.
@@ -153,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **the `--format json` error envelope is machine-readable again: it moves to stdout, the stream nothing else writes to.** The envelope went to stderr, which is also where every diagnostic goes — the CLI's own warnings (the world-readable-config notice, the non-DeepL-endpoint key warning, every `Logger.warn` in a run) and anything the Node runtime emits (`(node:7016) ExperimentalWarning: SQLite is an experimental feature…`, which is exactly how three e2e tests broke on 2026-08-08: `JSON.parse(stderr)` failed at the opening `(`). A consumer capturing stderr got valid JSON only when nothing else happened to be said, and the failure path — the one case a script most needs to parse — was the one case sharing a stream. Measured before the fix: `deepl sync validate --format json` in a directory with no `.deepl-sync.yaml` and a group-readable config file wrote the mode-tightening warning **and** the envelope interleaved on stderr, with stdout empty. The envelope is the command's *result* in the failure case, so it now lands where the success payload already does; the non-zero exit code remains the failure signal, and warnings stay on stderr where they can no longer break the parse — asserted end to end with the CLI's own warning firing alongside a `JSON.parse` of the whole of stdout. `sync init`'s config-already-exists envelope, previously built inline, goes through the shared emitter and moves with it. See Changed for the migration note.
+
 - **sync**: **`deepl sync validate` validates the rest of the project when one target file cannot be read.** A target-file parse failure propagated out of the walk and ended the whole command at exit 1 with a raw parser message (`Error: Expected double-quoted property name in JSON at position 32`, `UnknownError` in the JSON envelope) — a project with fifty locales and one corrupt file was told about the corrupt file and nothing about the other forty-nine, which is the opposite of what a validation command is for. Every other path already refuses one file and carries on. The unreadable file is now an `error`-severity issue like any other — reported under an `unusable_target` check with the file, the locale and the parser's reason, counting toward exit **8** — and every other locale and file is validated and reported alongside it. Deliberately **not** a warn-and-skip: validate exiting 0 over a file it never validated would turn CI green on an unvalidated locale, which is strictly worse than dying. A locale with no target file at all is still skipped silently, `totalChecked`/`passed` keep counting only pairs actually compared, and a healthy project's output is byte-identical. `deepl sync audit` needed no change — measured on the same fixture, it already excludes such a locale from the comparison and reports it under `missingTargets` at its normal exit code.
 
 - **translate**: **code preservation survives a fenced block overlapping an inline code span.** The preservation passes run in sequence over already-substituted text, so a span preserved later can wrap an earlier pass's token — `` ` ``` ``…``` ` `` makes the inline pass preserve `` ` __CODE_0__ ` `` as `__CODE_1__`, and a brace-shaped span can wrap a code token the same way (`{`x`}`). Both the restore and the loss check walked the map in insertion order, so the inner token was expanded after its own pass had already run — `deepl translate --preserve-code` on that input refused the translation at exit 5 with `The translation lost the placeholder …`, blaming the endpoint for a token the CLI had nested itself, and the round-trip law (`preserve → identity-translate → restore` is the identity) failed under fast-check seed 2139537717 with three lines expected and one received. Restore now expands tokens in reverse insertion order — a stored value can only contain tokens preserved before it, so one pass unfolds every level — and the loss check counts a token as surviving when it sits inside a later span that itself survived, in the sync validator as well as the translate-path assert. The same input now translates at exit 0 with every line restored verbatim, the pinned seed replays green, and four consecutive random-seed property runs stay green.
diff --git a/docs/API.md b/docs/API.md
index 6d77b5a7..117a457a 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1338,9 +1338,9 @@ Show translation coverage for all target locales.
 
 `skippedKeys` counts entries the parser tagged as untranslatable and excluded from the translation batch — currently only Laravel pipe-pluralization values (`|{n}`, `|[n,m]`, `|[n,*]`). Included in `totalKeys`.
 
-**stdout/stderr split (stable contract):** The success JSON payload is written to **stdout**, so `deepl sync status --format json > status.json` produces a parseable file. Diagnostic/progress logs stay on **stderr**. The same stdout/stderr split applies to `deepl sync --format json`, `deepl sync validate --format json`, and `deepl sync audit --format json`.
+**stdout/stderr split (stable contract):** The JSON payload — the success result, or the error envelope below when the command fails — is written to **stdout**, so `deepl sync status --format json > status.json` produces a parseable file in both cases. Diagnostic/progress logs and warnings stay on **stderr**, which means stdout parses even when the CLI or the Node runtime had something to say. The same stdout/stderr split applies to `deepl sync --format json`, `deepl sync validate --format json`, and `deepl sync audit --format json`.
 
-**Error envelope (shared across every `sync` subcommand):** On failure, `--format json` emits the following JSON envelope to **stderr** and exits with the typed exit code:
+**Error envelope (shared across every `sync` subcommand):** On failure, `--format json` emits the following JSON envelope to **stdout** — the envelope is the command's result in the failure case; the non-zero exit code is the failure signal — and exits with the typed exit code:
 
 ```json
 {
@@ -1468,7 +1468,7 @@ Export source strings to XLIFF 1.2 for CAT tool handoff.
 - `--locale LANGS` - Filter by locale (comma-separated)
 - `--output PATH` - Write to file instead of stdout. Path must stay within the project root; intermediate directories are created automatically
 - `--overwrite` - Required to overwrite an existing `--output` file. Without it, an existing file causes a non-zero exit and no write occurs
-- `--format FORMAT` - Output format: `text` (default), `json`. Success output is always XLIFF 1.2 regardless of format; `json` affects the **error** envelope on stderr (matching other sync subcommands) so script consumers can parse failure shape uniformly
+- `--format FORMAT` - Output format: `text` (default), `json`. Success output is always XLIFF 1.2 regardless of format; `json` affects the **error** envelope on stdout (matching other sync subcommands) so script consumers can parse failure shape uniformly
 - `--sync-config PATH` - Path to `.deepl-sync.yaml`
 
 **Examples:**
diff --git a/docs/SYNC.md b/docs/SYNC.md
index 0595f7fe..a1eb8666 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -713,7 +713,7 @@ Cost estimates use the DeepL Pro rate ($25 per 1 million characters). If you are
 
 With `--format json`, the result includes `estimatedCharacters`, `targetLocaleCount`, `estimatedCost`, and `rateAssumption: "pro"` (indicating the estimate is based on Pro-tier pricing). A `perLocale` array provides per-file per-locale breakdowns.
 
-**stdout/stderr split (stable contract).** The final success JSON payload is written to **stdout**, so `deepl sync --format json > out.json` captures the result in a parseable file. Progress events (both `key-translated` and `locale-complete`) are streamed to **stderr** as JSON lines during the sync, enabling programmatic progress monitoring without polluting the consumer contract on stdout. On failure, `--format json` emits the nested error envelope `{"ok":false,"error":{"code":"...","message":"...","suggestion":"..."},"exitCode":N}` to **stderr** and exits non-zero; the `error.code` field matches the error class name (e.g. `ConfigError`).
+**stdout/stderr split (stable contract).** The final JSON payload — the success result, or the error envelope when the command fails — is written to **stdout**, so `deepl sync --format json > out.json` captures a parseable file in both cases. Progress events (both `key-translated` and `locale-complete`) are streamed to **stderr** as JSON lines during the sync, enabling programmatic progress monitoring without polluting the consumer contract on stdout. On failure, `--format json` emits the nested error envelope `{"ok":false,"error":{"code":"...","message":"...","suggestion":"..."},"exitCode":N}` to **stdout** and exits non-zero; the `error.code` field matches the error class name (e.g. `ConfigError`). Warnings — the CLI's own and the Node runtime's — go to stderr, so they can never break a consumer parsing stdout.
 
 ### `deepl sync init`
 
@@ -838,7 +838,7 @@ deepl sync status --format json
 
 **`skippedKeys`** counts entries the parser tagged as untranslatable and excluded from the translation batch — currently only Laravel pipe-pluralization values (`|{n}`, `|[n,m]`, `|[n,*]`). Included in `totalKeys`; round-trip byte-verbatim via reconstruct.
 
-**JSON output contract.** The field set above is stable within a major version. `coverage` is an integer 0-100. The success payload is written to **stdout** so `deepl sync status --format json > status.json` captures it in a parseable file; diagnostic logs remain on stderr. On failure, `--format json` emits the nested error envelope `{"ok":false,"error":{"code":"...","message":"...","suggestion":"..."},"exitCode":N}` to **stderr** and exits non-zero; `error.code` matches the error class name (e.g. `ConfigError`). The same stdout/stderr split applies to `deepl sync validate --format json` and `deepl sync audit --format json`.
+**JSON output contract.** The field set above is stable within a major version. `coverage` is an integer 0-100. The success payload is written to **stdout** so `deepl sync status --format json > status.json` captures it in a parseable file; diagnostic logs remain on stderr. On failure, `--format json` emits the nested error envelope `{"ok":false,"error":{"code":"...","message":"...","suggestion":"..."},"exitCode":N}` to **stdout** as well — the envelope is the command's result in the failure case, and the non-zero exit code is the failure signal — so a consumer parses one stream in both cases. `error.code` matches the error class name (e.g. `ConfigError`). The same stdout/stderr split applies to `deepl sync validate --format json` and `deepl sync audit --format json`.
 
 **Casing.** CLI JSON output uses `camelCase`. The on-disk lockfile and config use `snake_case`. This split is deliberate — JSON is a consumer contract, files are authored configuration.
 
@@ -900,7 +900,7 @@ deepl sync export [OPTIONS]
 | `--locale <langs>` | Export for specific locales only |
 | `--output <path>` | Write to file instead of stdout |
 | `--overwrite` | Overwrite `--output` if it already exists (default: refuse to clobber) |
-| `--format <fmt>` | Output format: `text` (default), `json`. Success output is always XLIFF 1.2; `json` affects the **error** envelope on stderr so script consumers can parse failure shape uniformly with other sync subcommands |
+| `--format <fmt>` | Output format: `text` (default), `json`. Success output is always XLIFF 1.2; `json` affects the **error** envelope on stdout so script consumers can parse failure shape uniformly with other sync subcommands |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 
 Without `--overwrite`, `deepl sync export --output` refuses to write over an existing file and exits 6 (ValidationError). Pass `--overwrite` to re-export:
diff --git a/examples/24-sync-live-validation.sh b/examples/24-sync-live-validation.sh
index 9c0aa498..b7b2de3e 100755
--- a/examples/24-sync-live-validation.sh
+++ b/examples/24-sync-live-validation.sh
@@ -208,7 +208,9 @@ echo "Phase 5: Status + Validate"
 deepl sync status 2>&1 | head -10
 assert_exit_code "status exits 0" 0 deepl sync status
 
-STATUS_JSON=$(deepl sync status --format json 2>&1)
+# stdout only: the JSON payload lands there in both the success and the
+# failure case, and merging stderr would splice warnings into the capture.
+STATUS_JSON=$(deepl sync status --format json)
 # Wrap pipelines inside helper functions so the assert helper runs them
 # atomically. Otherwise `assert "desc" echo $X | python3 ...` parses the
 # pipe at the assert call level — assert sees only `echo $X` (always 0)
diff --git a/src/cli/commands/sync/register-sync-init.ts b/src/cli/commands/sync/register-sync-init.ts
index e8b079c5..f0361383 100644
--- a/src/cli/commands/sync/register-sync-init.ts
+++ b/src/cli/commands/sync/register-sync-init.ts
@@ -103,18 +103,12 @@ async function handleSyncInit(
       if (options.format === 'json') {
         // Already-present config is not an error per se, but scripted
         // bootstrap flows need a non-ok envelope to branch on.
-        const envelope = {
-          ok: false,
-          error: {
-            code: 'ConfigError',
-            message: `Config file ${displayPath} already exists.`,
-            suggestion:
-              'Remove or rename the existing config file, or edit it directly.',
-          },
-          exitCode: ExitCode.ConfigError,
-        };
-        process.stderr.write(JSON.stringify(envelope) + '\n');
-        process.exit(ExitCode.ConfigError);
+        emitJsonErrorAndExit(
+          new ConfigError(
+            `Config file ${displayPath} already exists.`,
+            'Remove or rename the existing config file, or edit it directly.'
+          )
+        );
       }
       Logger.warn(chalk.yellow(`Config file ${displayPath} already exists.`));
       return;
diff --git a/src/cli/commands/sync/sync-options.ts b/src/cli/commands/sync/sync-options.ts
index 1264ffaa..e61189c2 100644
--- a/src/cli/commands/sync/sync-options.ts
+++ b/src/cli/commands/sync/sync-options.ts
@@ -101,9 +101,16 @@ function sanitizeMessage(message: string): string {
 }
 
 /**
- * Serialize an error to the canonical envelope on stderr and exit with the
+ * Serialize an error to the canonical envelope on stdout and exit with the
  * error's typed exit code. Shared by every subcommand that honors
  * --format json for machine-readable failures.
+ *
+ * stdout, not stderr: the envelope is the command's result in the failure
+ * case, and stderr is where every warning — the CLI's own and the Node
+ * runtime's — already goes, so an envelope there parses only when nothing
+ * else happened to be said. The non-zero exit code remains the failure
+ * signal; a consumer reads the reason off the same stream as the success
+ * payload.
  */
 export function emitJsonErrorAndExit(
   error: unknown,
@@ -125,7 +132,7 @@ export function emitJsonErrorAndExit(
     },
     exitCode,
   };
-  process.stderr.write(JSON.stringify(envelope) + '\n');
+  process.stdout.write(JSON.stringify(envelope) + '\n');
   process.exit(exitCode);
 }
 
diff --git a/tests/e2e/cli-sync-error-envelope.e2e.test.ts b/tests/e2e/cli-sync-error-envelope.e2e.test.ts
index e681c1c0..41200114 100644
--- a/tests/e2e/cli-sync-error-envelope.e2e.test.ts
+++ b/tests/e2e/cli-sync-error-envelope.e2e.test.ts
@@ -1,7 +1,9 @@
 /**
  * E2E tests for the shared JSON error envelope across every `deepl sync`
  * subcommand. When --format json is set and a command fails, every
- * subcommand must emit the canonical envelope to stderr:
+ * subcommand must emit the canonical envelope to stdout — the envelope is
+ * the command's result in the failure case, and stdout is the one stream
+ * warnings and runtime diagnostics never share:
  *
  *   { ok: false, error: { code, message, suggestion? }, exitCode }
  *
@@ -146,7 +148,7 @@ describe('CLI sync --format json error envelope', () => {
       it(`deepl sync ${sub} --format json → envelope ConfigError/7`, () => {
         const run = runCli(['sync', sub, '--format', 'json']);
         expect(run.status).toBe(7);
-        assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+        assertErrorEnvelope(run.stdout, 'ConfigError', 7);
       });
     }
   });
@@ -158,7 +160,7 @@ describe('CLI sync --format json error envelope', () => {
 
       const run = runCli(['sync', 'push', '--format', 'json']);
       expect(run.status).toBe(7);
-      const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+      const envelope = assertErrorEnvelope(run.stdout, 'ConfigError', 7);
       expect(envelope.error.message).toMatch(/TMS integration not configured/);
       expect(envelope.error.suggestion).toMatch(/tms:/);
     });
@@ -169,7 +171,7 @@ describe('CLI sync --format json error envelope', () => {
 
       const run = runCli(['sync', 'pull', '--format', 'json']);
       expect(run.status).toBe(7);
-      assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+      assertErrorEnvelope(run.stdout, 'ConfigError', 7);
     });
   });
 
@@ -185,7 +187,7 @@ describe('CLI sync --format json error envelope', () => {
         'en',
       ]);
       expect(run.status).toBe(6);
-      const envelope = assertErrorEnvelope(run.stderr, 'ValidationError', 6);
+      const envelope = assertErrorEnvelope(run.stdout, 'ValidationError', 6);
       expect(envelope.error.message).toMatch(/All four flags/);
     });
   });
@@ -239,7 +241,7 @@ describe('CLI sync --format json error envelope', () => {
       ]);
 
       expect(run.status).toBe(7);
-      const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+      const envelope = assertErrorEnvelope(run.stdout, 'ConfigError', 7);
       expect(envelope.error.message).toMatch(/already exists/);
     });
   });
@@ -275,7 +277,7 @@ describe('CLI sync --format json error envelope', () => {
 
       const run = runCli(['sync', 'resolve', '--format', 'json']);
       expect(run.status).toBe(11);
-      const envelope = assertErrorEnvelope(run.stderr, 'SyncConflict', 11);
+      const envelope = assertErrorEnvelope(run.stdout, 'SyncConflict', 11);
       expect(envelope.error.suggestion).toMatch(/conflict markers manually/);
     });
   });
@@ -287,9 +289,28 @@ describe('CLI sync --format json error envelope', () => {
     it('ConfigError envelope does not contain raw control chars in message', () => {
       const run = runCli(['sync', 'export', '--format', 'json']);
       expect(run.status).toBe(7);
-      const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+      const envelope = assertErrorEnvelope(run.stdout, 'ConfigError', 7);
       // eslint-disable-next-line no-control-regex -- intentional: assert sanitation
       expect(envelope.error.message).not.toMatch(/[\u0000-\u001F]/);
     });
   });
+
+  describe('a warning on stderr cannot break a consumer parsing the envelope', () => {
+    it('emits the envelope as the whole of stdout while the CLI warns on stderr', () => {
+      // A world-readable config file makes the CLI itself write a warning to
+      // stderr before anything else runs -- the same stream pollution as a
+      // Node runtime ExperimentalWarning, produced without shimming node.
+      const configPath = path.join(testConfig.path, 'config.json');
+      fs.chmodSync(configPath, 0o644);
+
+      const run = runCli(['sync', 'validate', '--format', 'json']);
+
+      expect(run.status).toBe(7);
+      expect(run.stderr).toContain('Warning');
+      // The whole stream parses -- no trailing-line extraction required.
+      const envelope = JSON.parse(run.stdout) as { ok: boolean };
+      expect(envelope.ok).toBe(false);
+      assertErrorEnvelope(run.stdout, 'ConfigError', 7);
+    });
+  });
 });
diff --git a/tests/e2e/cli-sync-glob-bomb.e2e.test.ts b/tests/e2e/cli-sync-glob-bomb.e2e.test.ts
index ff6d60a3..d1a59dac 100644
--- a/tests/e2e/cli-sync-glob-bomb.e2e.test.ts
+++ b/tests/e2e/cli-sync-glob-bomb.e2e.test.ts
@@ -32,23 +32,21 @@ describe('CLI sync glob bomb containment', () => {
   }
 
   /**
-   * The JSON error envelope goes to stderr, which is also where the CLI's own
-   * warnings and the Node runtime's go — an `ExperimentalWarning` ahead of it is
-   * enough to fail a parse of the whole stream. Take the envelope line instead of
-   * assuming stderr holds nothing else. `sanitizeMessage` strips control
-   * characters from the message, newline included, so the envelope is always one
-   * line.
+   * The JSON error envelope is the whole of stdout — warnings and runtime
+   * diagnostics go to stderr, so the machine stream parses as-is.
+   * `sanitizeMessage` strips control characters from the message, newline
+   * included, so the envelope is always one line.
    */
-  function parseErrorEnvelope(stderr: string): {
+  function parseErrorEnvelope(stdout: string): {
     ok: boolean;
     error: { message: string };
   } {
-    const line = stderr
+    const line = stdout
       .split('\n')
       .filter((l) => l.trimStart().startsWith('{'))
       .pop();
     if (!line) {
-      throw new Error(`no JSON envelope on stderr, got: ${stderr}`);
+      throw new Error(`no JSON envelope on stdout, got: ${stdout}`);
     }
     return JSON.parse(line) as { ok: boolean; error: { message: string } };
   }
@@ -160,7 +158,7 @@ describe('CLI sync glob bomb containment', () => {
 
     expect(result.signal).toBeNull();
     expect(result.status).toBe(CONFIG_EXIT_CODE);
-    const envelope = parseErrorEnvelope(result.stderr);
+    const envelope = parseErrorEnvelope(result.stdout);
     expect(envelope.ok).toBe(false);
     expect(envelope.error.message).toMatch(/expands to more than/i);
   });
diff --git a/tests/e2e/cli-sync-init.e2e.test.ts b/tests/e2e/cli-sync-init.e2e.test.ts
index 6369b796..53403187 100644
--- a/tests/e2e/cli-sync-init.e2e.test.ts
+++ b/tests/e2e/cli-sync-init.e2e.test.ts
@@ -110,7 +110,7 @@ describe('deepl sync init — no i18n files detected', () => {
     const run = runCli(['sync', 'init', '--format', 'json']);
 
     expect(run.status).toBe(7);
-    const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+    const envelope = assertErrorEnvelope(run.stdout, 'ConfigError', 7);
     expect(envelope.error.message).toMatch(/No i18n files detected/);
 
     const configPath = path.join(testFiles.path, '.deepl-sync.yaml');
diff --git a/tests/e2e/cli-sync-option-routing.e2e.test.ts b/tests/e2e/cli-sync-option-routing.e2e.test.ts
index 185b0a20..fcd90063 100644
--- a/tests/e2e/cli-sync-option-routing.e2e.test.ts
+++ b/tests/e2e/cli-sync-option-routing.e2e.test.ts
@@ -251,7 +251,7 @@ describe('CLI sync option routing E2E', () => {
       ]);
 
       expect(run.status).toBe(7);
-      const envelope = JSON.parse(run.stderr.trim()) as {
+      const envelope = JSON.parse(run.stdout.trim()) as {
         ok: boolean;
         error: { code: string };
         exitCode: number;
diff --git a/tests/e2e/cli-sync-push-pull.e2e.test.ts b/tests/e2e/cli-sync-push-pull.e2e.test.ts
index 53e53c67..c41c191b 100644
--- a/tests/e2e/cli-sync-push-pull.e2e.test.ts
+++ b/tests/e2e/cli-sync-push-pull.e2e.test.ts
@@ -366,7 +366,7 @@ describe('CLI sync push/pull dispatch E2E', () => {
       });
 
       expect(run.status).toBe(7);
-      const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+      const envelope = assertErrorEnvelope(run.stdout, 'ConfigError', 7);
       expect(envelope.error.message).toContain('localhost');
       expect(envelope.error.suggestion).toContain(
         'deepl config set tms.allowedServers'
@@ -658,7 +658,7 @@ describe('CLI sync push/pull dispatch E2E', () => {
         });
 
         expect(run.status).toBe(7);
-        const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+        const envelope = assertErrorEnvelope(run.stdout, 'ConfigError', 7);
         expect(envelope.error.message).toBe(
           `tms.${field} was never implemented and has been removed`
         );
@@ -672,7 +672,7 @@ describe('CLI sync push/pull dispatch E2E', () => {
       const run = runCli(['sync', 'push', '--format', 'json']);
 
       expect(run.status).toBe(7);
-      const envelope = assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+      const envelope = assertErrorEnvelope(run.stdout, 'ConfigError', 7);
       expect(envelope.error.message).toMatch(/TMS integration not configured/);
       expect(envelope.error.suggestion).toMatch(/tms:/);
     });
@@ -684,7 +684,7 @@ describe('CLI sync push/pull dispatch E2E', () => {
       const run = runCli(['sync', 'pull', '--format', 'json']);
 
       expect(run.status).toBe(7);
-      assertErrorEnvelope(run.stderr, 'ConfigError', 7);
+      assertErrorEnvelope(run.stdout, 'ConfigError', 7);
     });
   });
 });
diff --git a/tests/e2e/cli-sync.e2e.test.ts b/tests/e2e/cli-sync.e2e.test.ts
index 84f20025..62730dc6 100644
--- a/tests/e2e/cli-sync.e2e.test.ts
+++ b/tests/e2e/cli-sync.e2e.test.ts
@@ -510,7 +510,7 @@ describe('CLI Sync E2E', () => {
       );
     });
 
-    it('emits a parseable JSON error envelope to stderr when --format json and config is missing', () => {
+    it('emits a parseable JSON error envelope when --format json and config is missing', () => {
       const result = runSyncExpectError('--format json');
 
       expect(result.status).toBe(7);
@@ -1584,7 +1584,7 @@ describe('CLI Sync E2E', () => {
       expect(Number.isInteger(first['coverage'])).toBe(true);
     });
 
-    it('emits a parseable JSON error envelope to stderr when config is missing', () => {
+    it('emits a parseable JSON error envelope when config is missing', () => {
       // No .deepl-sync.yaml in testFiles.path (beforeEach cleans it up).
       const result = runSyncExpectError('status --format json');
 
diff --git a/tests/helpers/assert-error-envelope.ts b/tests/helpers/assert-error-envelope.ts
index 84692bff..ce0c42d0 100644
--- a/tests/helpers/assert-error-envelope.ts
+++ b/tests/helpers/assert-error-envelope.ts
@@ -1,5 +1,5 @@
 /**
- * Test helper: validates the JSON error envelope emitted on stderr by
+ * Test helper: validates the JSON error envelope emitted on stdout by
  * `deepl sync <subcommand> --format json` when a command fails.
  *
  * The envelope shape is shared by every subcommand (push/pull/resolve/export/
@@ -86,20 +86,20 @@ const validateError = ajv.compile(ERROR_ENVELOPE_SCHEMA);
 const validateInitSuccess = ajv.compile(INIT_SUCCESS_ENVELOPE_SCHEMA);
 
 /**
- * Extract the last JSON object from `stderr` and assert it matches the
- * error envelope schema. Parent-process progress lines (e.g. "Detecting
- * i18n files...") can land on stderr before the envelope, so we match the
- * final `{...}` block rather than parsing all of stderr.
+ * Extract the last JSON object from the machine-readable stream (stdout, or a
+ * merged capture) and assert it matches the error envelope schema. Callers
+ * that merge streams can carry warning lines before the envelope, so we match
+ * the final `{...}` block rather than parsing the whole capture.
  */
 export function assertErrorEnvelope(
-  stderr: string,
+  output: string,
   expectedCode: string,
   expectedExitCode: number
 ): SyncJsonErrorEnvelope {
-  const match = stderr.trim().match(/\{[\s\S]*\}\s*$/);
+  const match = output.trim().match(/\{[\s\S]*\}\s*$/);
   if (!match) {
     throw new Error(
-      `No trailing JSON object found in stderr. stderr was:\n${stderr}`
+      `No trailing JSON object found in the capture. It was:\n${output}`
     );
   }
 
@@ -108,7 +108,7 @@ export function assertErrorEnvelope(
     parsed = JSON.parse(match[0]);
   } catch (err) {
     throw new Error(
-      `stderr trailing JSON is not parseable: ${(err as Error).message}\nPayload: ${match[0]}`,
+      `Trailing JSON is not parseable: ${(err as Error).message}\nPayload: ${match[0]}`,
       { cause: err }
     );
   }

From 24dcfe1d503e0d3874eebdb4b16f3eac222a53dd Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 12:15:25 +0200
Subject: [PATCH 188/256] fix(sync): stop deepl sync pull reading an inherited
 prototype member as a translation

sanitizePullKeysResponse returns a null-prototype object so a source key
named toString/constructor/valueOf cannot resolve to a function through
keys[key] !== undefined, but pullTranslations had begun spreading it into
a plain object literal for the plural_entry skip, re-exposing
Object.prototype. On a monolingual bucket a source key with such a name,
against an export that omits it, read the inherited function as an
approved value, reported Pulled/Replaced and deleted the reviewed local
translation; on PO it crashed value is not iterable.

The spread now preserves the null prototype via Object.assign over
Object.create(null), and mergePulledTranslations tests membership with
Object.hasOwn so it is immune to whatever object shape a caller passes.

Regression introduced this session by defbd14 (cli-8kr2.77); never shipped
in a tagged release. Found by the cli-8kr2.70 independent red-team pass.

Refs cli-8zn5.2
---
 CHANGELOG.md                                  |  2 +
 src/sync/sync-tms.ts                          |  8 +++-
 src/sync/sync-utils.ts                        |  9 +++-
 ...c-plural-carry-forward.integration.test.ts | 46 +++++++++++++++++++
 tests/unit/sync/sync-utils.test.ts            | 45 ++++++++++++++++++
 5 files changed, 107 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c3a5a745..b0111384 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -513,6 +513,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **config**: `config delete` and the config read paths can no longer walk or mutate the prototype chain — `__proto__`/`constructor`/`prototype` segments are rejected, completing the `config set` hardening.
 
+- **sync**: `deepl sync pull` no longer reads an inherited `Object.prototype` member as a pulled translation. `sanitizePullKeysResponse` returns a null-prototype object precisely so a source key named `toString`/`constructor`/`valueOf` cannot resolve to a function through `keys[key] !== undefined`, but the pull path had begun spreading it into a plain object literal (`{ ...keys }`), re-exposing the prototype — so on a monolingual bucket a source key with such a name, against a TMS export that omits it, read the inherited function as an approved value, reported `Pulled`/`Replaced`, and deleted the reviewed local translation (on a PO bucket it crashed `value is not iterable`). The spread now preserves the null prototype, and `mergePulledTranslations` tests membership with `Object.hasOwn` so it is immune to the shape of whatever object a caller hands it. All within unreleased work; no tagged release shipped it.
+
 - **perf**: `sync audit` registration no longer loads fast-glob on every CLI invocation (lazy import, matching its sibling subcommands).
 
 ### Security
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index f576c121..78c2ca38 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -313,7 +313,13 @@ export async function pullTranslations(
         (entry) =>
           keys[entry.key] !== undefined && hasPluralForms(entry.metadata)
       );
-      const applicableKeys = { ...keys };
+      // Preserve the null prototype `sanitizePullKeysResponse` gave `keys`: a
+      // plain-object spread would re-expose Object.prototype, so a source key
+      // named `toString`/`constructor` would read as an approved translation.
+      const applicableKeys: Record<string, string> = Object.assign(
+        Object.create(null) as Record<string, string>,
+        keys
+      );
       for (const entry of pluralEntries) {
         skipped.push({
           file: relPath,
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index 8031a33b..29558539 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -75,8 +75,13 @@ export function mergePulledTranslations(
 ): TranslatedEntry[] {
   const merged: TranslatedEntry[] = [];
   for (const entry of sourceEntries) {
-    const translation =
-      pulledKeys[entry.key] ?? existingTargetEntries.get(entry.key);
+    // Own-key only: a source key named after a prototype member (`toString`,
+    // `constructor`) must not resolve to an inherited function when the pull
+    // response is a plain object that does not own it. `Object.hasOwn` is safe
+    // on a null-prototype response too.
+    const translation = Object.hasOwn(pulledKeys, entry.key)
+      ? pulledKeys[entry.key]
+      : existingTargetEntries.get(entry.key);
     if (translation === undefined) continue;
     merged.push({
       key: entry.key,
diff --git a/tests/integration/sync-plural-carry-forward.integration.test.ts b/tests/integration/sync-plural-carry-forward.integration.test.ts
index 6355c749..ceaa9b24 100644
--- a/tests/integration/sync-plural-carry-forward.integration.test.ts
+++ b/tests/integration/sync-plural-carry-forward.integration.test.ts
@@ -403,5 +403,51 @@ describe('sync with a plural entry carried forward', () => {
         'translated'
       );
     });
+
+    it('does not treat a source key named toString as pulled when the export omits it', async () => {
+      // A source key named after an Object.prototype member, an export that
+      // does not carry it, and a reviewed local translation. The membership
+      // test must be own-key only, or `toString` resolves to the inherited
+      // function and the reviewed value is destroyed.
+      fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+      fs.writeFileSync(
+        sourcePath(),
+        PO_HEADER +
+          [
+            'msgid "Hello"',
+            'msgstr ""',
+            '',
+            'msgid "toString"',
+            'msgstr ""',
+          ].join('\n'),
+        'utf-8'
+      );
+      fs.mkdirSync(path.dirname(targetPath()), { recursive: true });
+      fs.writeFileSync(
+        targetPath(),
+        PO_HEADER +
+          [
+            'msgid "Hello"',
+            'msgstr "Hola"',
+            '',
+            'msgid "toString"',
+            'msgstr "Convertir en texto"',
+          ].join('\n'),
+        'utf-8'
+      );
+      mockExport({ Hello: 'Hola TMS' });
+
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+      const result = await pullTranslations(config, client, harness.registry);
+
+      // Only Hello is applied; toString is neither pulled nor replaced, and the
+      // reviewed local msgstr survives.
+      expect(result.pulled).toBe(1);
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr "Hola TMS"');
+      expect(written).toContain('msgstr "Convertir en texto"');
+      expect(written).not.toMatch(/function toString/);
+    });
   });
 });
diff --git a/tests/unit/sync/sync-utils.test.ts b/tests/unit/sync/sync-utils.test.ts
index 07ac5556..f8a18bf0 100644
--- a/tests/unit/sync/sync-utils.test.ts
+++ b/tests/unit/sync/sync-utils.test.ts
@@ -425,6 +425,51 @@ describe('mergePulledTranslations()', () => {
     ).toEqual([]);
   });
 
+  it('does not read an inherited Object.prototype member as a pulled translation', () => {
+    // A source key named after a prototype member, with a plain-object pull
+    // response that does NOT own that key. Membership must be own-key only, or
+    // `toString` resolves to the inherited function and destroys the reviewed
+    // value the target file holds.
+    const merged = mergePulledTranslations(
+      [
+        { key: 'toString', value: 'Convert to text' },
+        { key: 'constructor', value: 'Builder' },
+      ],
+      {},
+      new Map([
+        ['toString', 'In Text umwandeln'],
+        ['constructor', 'Erbauer'],
+      ])
+    );
+
+    expect(merged).toEqual([
+      {
+        key: 'toString',
+        value: 'Convert to text',
+        translation: 'In Text umwandeln',
+        context: undefined,
+        metadata: undefined,
+      },
+      {
+        key: 'constructor',
+        value: 'Builder',
+        translation: 'Erbauer',
+        context: undefined,
+        metadata: undefined,
+      },
+    ]);
+    expect(typeof merged[0]!.translation).toBe('string');
+    expect(typeof merged[1]!.translation).toBe('string');
+  });
+
+  it('omits a prototype-named key the pull response and target both lack, rather than inheriting one', () => {
+    const merged = mergePulledTranslations(
+      [{ key: 'toString', value: 'Convert to text' }],
+      {}
+    );
+    expect(merged).toEqual([]);
+  });
+
   it('should strip the plural-form payloads so the target file keeps its own forms', () => {
     const merged = mergePulledTranslations(
       [

From f66d5cbb5d241b23171b12339fdee8d0180c5afb Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 12:18:59 +0200
Subject: [PATCH 189/256] fix(sync): pin the TMS request origin to the approved
 server origin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

buildUrl resolved new URL(projectPath + path, parsedUrl) where projectPath
begins with the server pathname. A tms.server whose path starts with // is
a protocol-relative reference: https://approved.example.com//evil.example.com
(or http://localhost//169.254.169.254) parses with hostname approved/localhost
— what ensureTmsServerApproved approves and what the HTTPS/localhost waiver
keys off — but the resolved request host becomes evil/169.254.169.254, so
TMS_API_KEY/TMS_TOKEN and every translated string were sent there.

buildUrl now requires the resolved URL's origin to equal the approved
parsedUrl.origin and throws ConfigError naming the redirected origin
otherwise. A legitimate base path (https://tms.example.com/tms) is
unaffected.

Threat: a maliciously-contributed .deepl-sync.yaml in a repo whose
maintainer runs deepl sync push/pull. Found by the cli-8kr2.70 independent
red-team pass.

Refs cli-8zn5.1
---
 CHANGELOG.md                       |  2 ++
 src/sync/tms-client.ts             | 15 ++++++++++++++-
 tests/unit/sync/tms-client.test.ts | 29 +++++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b0111384..ac02a672 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -513,6 +513,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **config**: `config delete` and the config read paths can no longer walk or mutate the prototype chain — `__proto__`/`constructor`/`prototype` segments are rejected, completing the `config set` hardening.
 
+- **sync**: `deepl sync push`/`pull` no longer send the TMS credential and translated strings to a host the destination-trust gate never approved. A `tms.server` whose path begins with `//` — `https://approved.example.com//evil.example.com`, or `http://localhost//169.254.169.254` — parses with `hostname = approved.example.com`/`localhost`, which is what `ensureTmsServerApproved` approves and what the HTTPS/localhost checks key off, but `buildUrl`'s `new URL(projectPath + path, parsedUrl)` then resolved the *request* to `evil.example.com`/`169.254.169.254` (a protocol-relative reference), delivering `TMS_API_KEY`/`TMS_TOKEN` and every translated string there. `buildUrl` now pins the resolved request origin to the approved `parsedUrl.origin` and throws `ConfigError` naming the redirected origin otherwise; a legitimate base path (`https://tms.example.com/tms`) is unaffected. The threat is a maliciously-contributed `.deepl-sync.yaml` in a repo whose maintainer runs `deepl sync push`. CWE-918. Found by the cli-8kr2.70 independent red-team pass.
+
 - **sync**: `deepl sync pull` no longer reads an inherited `Object.prototype` member as a pulled translation. `sanitizePullKeysResponse` returns a null-prototype object precisely so a source key named `toString`/`constructor`/`valueOf` cannot resolve to a function through `keys[key] !== undefined`, but the pull path had begun spreading it into a plain object literal (`{ ...keys }`), re-exposing the prototype — so on a monolingual bucket a source key with such a name, against a TMS export that omits it, read the inherited function as an approved value, reported `Pulled`/`Replaced`, and deleted the reviewed local translation (on a PO bucket it crashed `value is not iterable`). The spread now preserves the null prototype, and `mergePulledTranslations` tests membership with `Object.hasOwn` so it is immune to the shape of whatever object a caller hands it. All within unreleased work; no tagged release shipped it.
 
 - **perf**: `sync audit` registration no longer loads fast-glob on every CLI invocation (lazy import, matching its sibling subcommands).
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index 15b4c5ee..64450619 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -332,7 +332,20 @@ export class TmsClient {
 
     const basePath = parsedUrl.pathname.replace(/\/+$/, '');
     const projectPath = `${basePath}/api/projects/${encodeURIComponent(this.options.projectId)}`;
-    return new URL(`${projectPath}${path}`, parsedUrl).toString();
+    const resolved = new URL(`${projectPath}${path}`, parsedUrl);
+    // A server pathname beginning with `//` is a protocol-relative reference:
+    // `new URL('//evil/…', https://approved)` resolves the request to `evil`,
+    // even though `parsedUrl.hostname` — what the destination-trust gate
+    // approved and what the https/localhost checks keyed off — is still
+    // `approved`. Pin the resolved origin to the approved one so the API key
+    // and every translated string cannot be redirected to another host.
+    if (resolved.origin !== parsedUrl.origin) {
+      throw new ConfigError(
+        `TMS server URL resolves requests to a different origin (${sanitizeUrl(resolved.origin)}) than the configured server (${sanitizeUrl(parsedUrl.origin)})`,
+        'Set server: to a bare origin with an optional base path; a path beginning with "//" is a protocol-relative reference that redirects the host.'
+      );
+    }
+    return resolved.toString();
   }
 
   private async request(
diff --git a/tests/unit/sync/tms-client.test.ts b/tests/unit/sync/tms-client.test.ts
index 38b33682..228406be 100644
--- a/tests/unit/sync/tms-client.test.ts
+++ b/tests/unit/sync/tms-client.test.ts
@@ -285,6 +285,35 @@ describe('TmsClient URL construction', () => {
       expect.anything()
     );
   });
+
+  it('should refuse a server URL whose path resolves the request to a different host', async () => {
+    // `https://approved//evil` parses with hostname=approved, which the trust
+    // gate approves and the https/localhost checks key off — but the base
+    // path `//evil…` is a protocol-relative reference, so the resolved request
+    // host becomes evil. The credential and every translated string would go
+    // there. Refuse before any request.
+    await expect(
+      clientFor('https://tms.example.com//evil.example.com').pullKeys('de')
+    ).rejects.toThrow(ConfigError);
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('should refuse a localhost server URL whose path redirects to another host', async () => {
+    await expect(
+      clientFor('http://localhost//169.254.169.254').pullKeys('de')
+    ).rejects.toThrow(ConfigError);
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('should still accept a legitimate base path that keeps the approved host', async () => {
+    mockFetch.mockResolvedValue({ ok: true, json: async () => ({}) });
+    await clientFor('https://tms.example.com/tms').pullKeys('de');
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://tms.example.com/tms/api/projects/proj-1/keys/export?format=json&locale=de',
+      expect.anything()
+    );
+  });
 });
 
 describe('TmsClient error message redaction', () => {

From cbbac45d5ad329b496727c02d852f8435baf2a4f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 12:58:55 +0200
Subject: [PATCH 190/256] test(sync): parse sync status --format json from
 stdout alone, not merged streams
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The XLIFF-needs-review e2e built its parse input from stdout + stderr and
JSON.parsed the concatenation, so any diagnostic sharing stderr — the
config-mode-tightening notice, a node:sqlite ExperimentalWarning — broke
it with "Unexpected non-whitespace character after JSON". The --format
json payload is a stdout-only contract; the test now parses stdout alone
(matching the sibling fuzzy test in the same file) and keeps the merged
streams only for the text-mode substring assertions.

Reproduced by forcing the config-mode warning: stdout parses clean while
stdout+stderr fails at the same position the report showed. Latent since
the test landed in 75d46fa; surfaces on any environment that emits a
startup diagnostic to stderr.
---
 tests/e2e/cli-sync-bilingual-target.e2e.test.ts | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
index e1329e44..997eef0a 100644
--- a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
+++ b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
@@ -242,7 +242,7 @@ describe('CLI sync with a bilingual target file', () => {
     );
 
     const { CI: _ci, DEEPL_API_KEY: _key, ...rest } = process.env;
-    const run = (args: string[]): string => {
+    const run = (args: string[]): { stdout: string; combined: string } => {
       const result = spawnSync('node', [CLI_PATH, ...args], {
         encoding: 'utf-8',
         cwd: testFiles.path,
@@ -251,16 +251,22 @@ describe('CLI sync with a bilingual target file', () => {
         timeout: 60000,
       });
       expect(result.status).toBe(0);
-      return (result.stdout ?? '') + (result.stderr ?? '');
+      const stdout = result.stdout ?? '';
+      return { stdout, combined: stdout + (result.stderr ?? '') };
     };
 
-    const parsed = JSON.parse(run(['sync', 'status', '--format', 'json'])) as {
+    // `--format json` is a stdout-only contract; a diagnostic can share stderr
+    // (a config-mode-tightening notice, a node:sqlite ExperimentalWarning), so
+    // parse stdout alone rather than the merged streams.
+    const parsed = JSON.parse(
+      run(['sync', 'status', '--format', 'json']).stdout
+    ) as {
       locales: { locale: string; needsReview: number }[];
     };
     // The flagged PO key plus the flagged XLIFF unit.
     expect(parsed.locales.find((l) => l.locale === 'es')!.needsReview).toBe(2);
 
-    const text = run(['sync', 'status']);
+    const text = run(['sync', 'status']).combined;
     expect(text).toContain('2 needs review');
     expect(text).toContain('needs-review-translation');
   }, 120000);

From 48bf5af6d6f496d31ecaadc4b65b12f0e2672ca3 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:21:15 +0200
Subject: [PATCH 191/256] fix(sync): carry a reviewer translation forward on
 the new-key path

The carry-forward that keeps a human translation from being replaced by
machine output was wired into the `current`-key path only, and a key is
`current` only once the lockfile mentions it. With no `.deepl-sync.lock`
-- first adoption, or a CI checkout where the lockfile is gitignored --
every key of a fully translated catalog arrives as `new`, so every key
was re-translated and written over, dropping the review markers the
formats carry, at exit 0 and with no backup surviving the run.

A `new` key whose target file already holds a translation is now carried
forward and recorded in the lockfile, so it is neither re-translated nor
re-billed, and its marker survives because the entry is rewritten with
the bytes it already had.

Not carried: a target value equal to the source, or an empty one. A
locale file copied from the source is untranslated text, and carrying it
would record it as translated -- what the new-locale path already
refuses to do. `--force` re-translates regardless.

sync-interrupt's fixtures relied on the defect to make the run rewrite a
human target; they now hold a reviewed value for one key and lack
another, so each test's subject (backup, SIGINT restore, stale-backup
retention) is exercised by real work. The withheld-key unit test moves
to a `stale` diff, the only status from which a re-translation -- and so
a withholding -- is now reachable for a key the target already has.

Refs cli-8zn5.3
---
 CHANGELOG.md                                  |   2 +
 src/sync/sync-locale-translator.ts            |  58 ++++-
 src/sync/sync-service.ts                      |   3 +-
 .../sync-first-adoption.integration.test.ts   | 209 ++++++++++++++++++
 .../sync-interrupt.integration.test.ts        |  13 +-
 .../unit/sync/sync-locale-translator.test.ts  |  15 +-
 .../sync/sync-source-as-translation.test.ts   |   3 +
 7 files changed, 289 insertions(+), 14 deletions(-)
 create mode 100644 tests/integration/sync-first-adoption.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ac02a672..670f3303 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **the first `deepl sync` over an already-translated project no longer overwrites every reviewer translation with machine output.** The carry-forward that protects a reviewed translation was wired into the `current`-key path only, and a key is `current` only once the lockfile mentions it. With no `.deepl-sync.lock` — first adoption of the tool, or any CI checkout where the lockfile is gitignored — *every* key of a fully human-translated catalog arrives as `new`, so every key was re-translated, re-billed, and written over, dropping the review markers the formats carry (gettext `#, fuzzy`, XLIFF `state`) at **exit 0**, with no `.bak` surviving the successful run. Measured on a two-entry PO catalog with one `#, fuzzy` entry and no lockfile: both `msgid`s went to the engine and both reviewed `msgstr`s came back as machine output. A `new` key whose target file already holds a translation is now carried forward untouched and recorded in the lockfile, so it is neither re-translated nor re-billed, and the marker survives because the entry is rewritten with the same bytes it already had. Two things are deliberately **not** carried: a target value equal to the source (a locale file copied from the source is untranslated text, and carrying it would freeze the source language into the locale — the same reasoning the new-locale path already applies) and an empty one; both are still translated. `--force` re-translates everything as before, since asking for re-translation is what it means. `sync status` already reported and refused to re-translate these keys — the invariant is now enforced on the path that writes, not only the one that reports.
+
 - **sync**: **the `--format json` error envelope is machine-readable again: it moves to stdout, the stream nothing else writes to.** The envelope went to stderr, which is also where every diagnostic goes — the CLI's own warnings (the world-readable-config notice, the non-DeepL-endpoint key warning, every `Logger.warn` in a run) and anything the Node runtime emits (`(node:7016) ExperimentalWarning: SQLite is an experimental feature…`, which is exactly how three e2e tests broke on 2026-08-08: `JSON.parse(stderr)` failed at the opening `(`). A consumer capturing stderr got valid JSON only when nothing else happened to be said, and the failure path — the one case a script most needs to parse — was the one case sharing a stream. Measured before the fix: `deepl sync validate --format json` in a directory with no `.deepl-sync.yaml` and a group-readable config file wrote the mode-tightening warning **and** the envelope interleaved on stderr, with stdout empty. The envelope is the command's *result* in the failure case, so it now lands where the success payload already does; the non-zero exit code remains the failure signal, and warnings stay on stderr where they can no longer break the parse — asserted end to end with the CLI's own warning firing alongside a `JSON.parse` of the whole of stdout. `sync init`'s config-already-exists envelope, previously built inline, goes through the shared emitter and moves with it. See Changed for the migration note.
 
 - **sync**: **`deepl sync validate` validates the rest of the project when one target file cannot be read.** A target-file parse failure propagated out of the walk and ended the whole command at exit 1 with a raw parser message (`Error: Expected double-quoted property name in JSON at position 32`, `UnknownError` in the JSON envelope) — a project with fifty locales and one corrupt file was told about the corrupt file and nothing about the other forty-nine, which is the opposite of what a validation command is for. Every other path already refuses one file and carries on. The unreadable file is now an `error`-severity issue like any other — reported under an `unusable_target` check with the file, the locale and the parser's reason, counting toward exit **8** — and every other locale and file is validated and reported alongside it. Deliberately **not** a warn-and-skip: validate exiting 0 over a file it never validated would turn CI green on an unvalidated locale, which is strictly worse than dying. A locale with no target file at all is still skipped silently, `totalChecked`/`passed` keep counting only pairs actually compared, and a healthy project's output is byte-identical. `deepl sync audit` needed no change — measured on the same fixture, it already excludes such a locale from the comparison and reports it under `missingTargets` at its normal exit code.
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index f2ace911..05a2ba8d 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -221,7 +221,10 @@ export class LocaleTranslator {
     private readonly resolvedGlossaryId: string | undefined,
     private readonly resolvedTmId: string | undefined,
     private readonly forceBatch: boolean | undefined,
-    private readonly onProgress: ((e: SyncProgressEvent) => void) | undefined
+    private readonly onProgress: ((e: SyncProgressEvent) => void) | undefined,
+    // `--force`: every key arrives as `new`, and re-translation is the point, so
+    // the carry-forward below does not apply.
+    private readonly force: boolean | undefined
   ) {}
 
   async translate(
@@ -265,8 +268,40 @@ export class LocaleTranslator {
       showBilledCharacters: true,
     };
 
+    const existingTranslations =
+      existingTargetEntries.get(locale) ?? new Map<string, string>();
+
+    // A `new` key the target file already holds a translation for is not new to
+    // the translator, only to the lockfile: first adoption of the tool, or a CI
+    // checkout whose `.deepl-sync.lock` is gitignored, presents every key of an
+    // already-translated catalog as `new`. Translating those would replace the
+    // reviewer's text with machine output and drop the review markers the
+    // formats carry, so carry the existing value forward exactly as a `current`
+    // key's is below.
+    //
+    // A target value equal to the source is NOT a translation — a locale file
+    // copied from the source starts out that way — and neither is an empty one.
+    // Carrying either forward would record untranslated text as `translated`,
+    // which no later run would correct. `--force` asks for re-translation of
+    // every key by definition, so it skips the carry entirely.
+    const carriedForward: SyncDiff[] = [];
+    const needsTranslation = toTranslate.filter((d) => {
+      if (this.force || d.status !== 'new') return true;
+      const existing = existingTranslations.get(d.key);
+      if (existing === undefined || existing === '' || existing === d.value) {
+        return true;
+      }
+      carriedForward.push(d);
+      return false;
+    });
+    if (carriedForward.length > 0) {
+      Logger.verbose(
+        `[verbose] ${locale}: ${carriedForward.length} key(s) absent from the lockfile already have a translation in the target file — carrying it forward rather than re-translating`
+      );
+    }
+
     // Deep-clone metadata per locale to prevent concurrent mutation
-    const localeDiffs = toTranslate.map((d) => ({
+    const localeDiffs = needsTranslation.map((d) => ({
       ...d,
       metadata: d.metadata
         ? (JSON.parse(JSON.stringify(d.metadata)) as Record<string, unknown>)
@@ -750,11 +785,22 @@ export class LocaleTranslator {
 
     const successfulKeys: string[] = translatedEntries.map((te) => te.key);
 
-    // Use target file translations for current keys
-    const existingTranslations =
-      existingTargetEntries.get(locale) ?? new Map<string, string>();
     const allTranslatedEntries: TranslatedEntry[] = [...translatedEntries];
 
+    // Carried-forward keys count as successful so the lockfile records the
+    // translation the target file holds. Left out, they would come back `new` on
+    // every run — re-read, re-carried, and reported missing by `sync status`
+    // forever.
+    for (const diff of carriedForward) {
+      allTranslatedEntries.push({
+        key: diff.key,
+        value: diff.value!,
+        translation: existingTranslations.get(diff.key)!,
+        metadata: withoutPluralForms(diff.metadata),
+      });
+      successfulKeys.push(diff.key);
+    }
+
     // A withheld key still needs an entry: the list is the complete desired key
     // set, so leaving it out deletes the key from the target file rather than
     // leaving it alone. Carry the value the target file already had — the same
@@ -978,7 +1024,7 @@ export class LocaleTranslator {
         file: targetRelPath,
         locale,
         translated,
-        skipped: currentDiffs.length,
+        skipped: currentDiffs.length + carriedForward.length,
         failed,
         written: true,
       },
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index 33d22622..de80e97c 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -429,7 +429,8 @@ export class SyncService {
       resolvedGlossaryId,
       resolvedTmId,
       options?.batch ?? config.sync?.batch,
-      options?.onProgress
+      options?.onProgress,
+      options?.force
     );
     const allContextSentKeys = new Set<string>();
     const allInstructionSentKeys = new Set<string>();
diff --git a/tests/integration/sync-first-adoption.integration.test.ts b/tests/integration/sync-first-adoption.integration.test.ts
new file mode 100644
index 00000000..556d1931
--- /dev/null
+++ b/tests/integration/sync-first-adoption.integration.test.ts
@@ -0,0 +1,209 @@
+/**
+ * Integration tests for the first sync over an already-translated catalog.
+ *
+ * With no lockfile every key is `new`, and the `new`-key path used to translate
+ * and write unconditionally — so adopting the tool on a human-translated
+ * project (or a CI checkout with a gitignored `.deepl-sync.lock`) replaced every
+ * reviewer translation with machine output and dropped the review markers, at
+ * exit 0. The carry-forward the `current`-key path performs has to hold here
+ * too. What must NOT be carried is a target that merely copies the source: that
+ * is untranslated text, and recording it as translated would freeze the source
+ * language into the locale file.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import { LOCK_FILE_NAME } from '../../src/sync/types';
+
+const PO_HEADER = [
+  'msgid ""',
+  'msgstr ""',
+  '"Content-Type: text/plain; charset=UTF-8\\n"',
+  '',
+  '',
+].join('\n');
+
+const PO_SOURCE =
+  PO_HEADER +
+  ['msgid "Hello"', 'msgstr ""', '', 'msgid "Goodbye"', 'msgstr ""', ''].join(
+    '\n'
+  );
+
+/** A human-translated catalog, one entry flagged for review. */
+const PO_REVIEWED =
+  PO_HEADER +
+  [
+    'msgid "Hello"',
+    'msgstr "Hola"',
+    '',
+    '#, fuzzy',
+    'msgid "Goodbye"',
+    'msgstr "Adios"',
+    '',
+  ].join('\n');
+
+/** A target that is a byte copy of the source: nothing is translated yet. */
+const PO_UNTRANSLATED_COPY =
+  PO_HEADER +
+  [
+    'msgid "Hello"',
+    'msgstr "Hello"',
+    '',
+    'msgid "Goodbye"',
+    'msgstr "Goodbye"',
+    '',
+  ].join('\n');
+
+/** Echo `[ES] <text>` per text, recording every text the engine was sent. */
+function replyEchoing(sent: string[]): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .persist()
+    .post('/v2/translate')
+    .reply(200, (_uri, body) => {
+      const texts = new URLSearchParams(body as string).getAll('text');
+      sent.push(...texts);
+      return {
+        translations: texts.map((t) => ({
+          text: `[ES] ${t}`,
+          detected_source_language: 'EN',
+          billed_characters: t.length,
+        })),
+      };
+    });
+}
+
+describe('first sync over an already-translated catalog', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  describe('PO', () => {
+    const sourcePath = () => path.join(tmpDir, 'locales', 'en', 'app.po');
+    const targetPath = () => path.join(tmpDir, 'locales', 'es', 'app.po');
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-first-adopt-'));
+      harness = createSyncHarness({ parsers: ['po'] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+      fs.mkdirSync(path.dirname(targetPath()), { recursive: true });
+      fs.writeFileSync(sourcePath(), PO_SOURCE, 'utf-8');
+    });
+
+    it('carries the reviewer translations forward instead of re-translating them', async () => {
+      fs.writeFileSync(targetPath(), PO_REVIEWED, 'utf-8');
+      expect(fs.existsSync(path.join(tmpDir, LOCK_FILE_NAME))).toBe(false);
+
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const result = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(result.success).toBe(true);
+      expect(sent).toEqual([]);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr "Hola"');
+      expect(written).toContain('msgstr "Adios"');
+      expect(written).toContain('#, fuzzy');
+      expect(written).not.toContain('[ES]');
+    });
+
+    it('still translates a target whose msgstr merely copies the msgid', async () => {
+      fs.writeFileSync(targetPath(), PO_UNTRANSLATED_COPY, 'utf-8');
+
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const result = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(result.success).toBe(true);
+      expect(sent.sort()).toEqual(['Goodbye', 'Hello']);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr "[ES] Hello"');
+      expect(written).toContain('msgstr "[ES] Goodbye"');
+    });
+
+    it('re-translates under --force even when the target holds translations', async () => {
+      fs.writeFileSync(targetPath(), PO_REVIEWED, 'utf-8');
+
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const result = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir),
+        { force: true }
+      );
+
+      expect(result.success).toBe(true);
+      expect(sent.sort()).toEqual(['Goodbye', 'Hello']);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr "[ES] Hello"');
+    });
+  });
+
+  describe('JSON', () => {
+    const sourcePath = () => path.join(tmpDir, 'locales', 'en.json');
+    const targetPath = () => path.join(tmpDir, 'locales', 'es.json');
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-first-adopt-'));
+      harness = createSyncHarness({ parsers: ['json'] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { json: { include: ['locales/en.json'] } },
+      });
+      fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+      fs.writeFileSync(
+        sourcePath(),
+        JSON.stringify({ hello: 'Hello', bye: 'Goodbye' }, null, 2),
+        'utf-8'
+      );
+    });
+
+    it('carries existing translations forward and translates only the gaps', async () => {
+      fs.writeFileSync(
+        targetPath(),
+        JSON.stringify({ hello: 'Hola' }, null, 2),
+        'utf-8'
+      );
+
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const result = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(result.success).toBe(true);
+      expect(sent).toEqual(['Goodbye']);
+
+      const written = JSON.parse(
+        fs.readFileSync(targetPath(), 'utf-8')
+      ) as Record<string, string>;
+      expect(written['hello']).toBe('Hola');
+      expect(written['bye']).toBe('[ES] Goodbye');
+    });
+  });
+});
diff --git a/tests/integration/sync-interrupt.integration.test.ts b/tests/integration/sync-interrupt.integration.test.ts
index 106e2cd3..360479ce 100644
--- a/tests/integration/sync-interrupt.integration.test.ts
+++ b/tests/integration/sync-interrupt.integration.test.ts
@@ -37,10 +37,11 @@ buckets:
 `;
 
 const SOURCE = JSON.stringify({ a: 'Alpha', b: 'Beta' }, null, 2) + '\n';
-const HUMAN_DE =
-  JSON.stringify({ a: 'HUMAN-DE-Alpha', b: 'HUMAN-DE-Beta' }, null, 2) + '\n';
-const HUMAN_FR =
-  JSON.stringify({ a: 'HUMAN-FR-Alpha', b: 'HUMAN-FR-Beta' }, null, 2) + '\n';
+// Each target holds a reviewed translation for `a` and is missing `b`, so every
+// run below has one key to translate and rewrites the file — while `a` shows
+// whether the reviewed text survived.
+const HUMAN_DE = JSON.stringify({ a: 'HUMAN-DE-Alpha' }, null, 2) + '\n';
+const HUMAN_FR = JSON.stringify({ a: 'HUMAN-FR-Alpha' }, null, 2) + '\n';
 
 function createServices(): { client: DeepLClient; syncService: SyncService } {
   const client = new DeepLClient(TEST_API_KEY, { maxRetries: 0 });
@@ -195,7 +196,9 @@ describe('sync interruption and crash recovery', () => {
     const result = await syncService.sync(config);
 
     expect(result.success).toBe(true);
-    expect(fs.readFileSync(dePath(), 'utf-8')).toContain('MT Alpha');
+    const written = fs.readFileSync(dePath(), 'utf-8');
+    expect(written).toContain('MT Beta');
+    expect(written).toContain('HUMAN-DE-Alpha');
     expect(fs.existsSync(deBakPath())).toBe(false);
   });
 });
diff --git a/tests/unit/sync/sync-locale-translator.test.ts b/tests/unit/sync/sync-locale-translator.test.ts
index e7699ac1..80e4d3a8 100644
--- a/tests/unit/sync/sync-locale-translator.test.ts
+++ b/tests/unit/sync/sync-locale-translator.test.ts
@@ -153,7 +153,10 @@ function makeCtx(
     content: '{}',
     parser: makeParser(),
     diffs,
-    toTranslate: diffs.filter((d) => d.status === 'new'),
+    // The same filter processBucket applies.
+    toTranslate: diffs.filter(
+      (d) => d.status === 'new' || d.status === 'stale'
+    ),
     fileLockEntries: {},
     existingTargetEntries: new Map(),
     keyContexts,
@@ -206,6 +209,7 @@ function makeTranslator(
     undefined,
     undefined,
     forceBatch,
+    undefined,
     undefined
   );
 }
@@ -651,6 +655,7 @@ describe('LocaleTranslator', () => {
         undefined,
         TM_ID,
         undefined,
+        undefined,
         undefined
       );
 
@@ -674,6 +679,7 @@ describe('LocaleTranslator', () => {
         GLOSSARY_ID,
         undefined,
         undefined,
+        undefined,
         undefined
       );
 
@@ -1777,7 +1783,12 @@ describe('LocaleTranslator', () => {
         },
       ]);
 
-      const diffs = [makeDiff('b', 'Beta {name}')];
+      // Stale, not new: a key the target already has a translation for is only
+      // re-translated when its source changed, so that is the status from which
+      // a withholding is reachable.
+      const diffs: SyncDiff[] = [
+        { key: 'b', value: 'Beta {name}', status: 'stale' },
+      ];
       const { mock } = captureTranslateBatch(['B']);
       const parser = makeParser();
 
diff --git a/tests/unit/sync/sync-source-as-translation.test.ts b/tests/unit/sync/sync-source-as-translation.test.ts
index 920321a8..9cdfe73b 100644
--- a/tests/unit/sync/sync-source-as-translation.test.ts
+++ b/tests/unit/sync/sync-source-as-translation.test.ts
@@ -178,6 +178,7 @@ describe('source text as translation', () => {
       undefined,
       undefined,
       undefined,
+      undefined,
       undefined
     );
 
@@ -203,6 +204,7 @@ describe('source text as translation', () => {
       undefined,
       undefined,
       undefined,
+      undefined,
       undefined
     );
 
@@ -226,6 +228,7 @@ describe('source text as translation', () => {
       undefined,
       undefined,
       undefined,
+      undefined,
       undefined
     );
 

From 7dde7d3860b7395905622190319da387f55e3ed7 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:27:08 +0200
Subject: [PATCH 192/256] fix(sync): keep a failed batch's existing
 translations instead of deleting them

translateBatch chunks at 50 texts and deliberately continues when one
chunk's request fails, returning empty slots for its texts. Those slots
fell into a bare `failed++` with no carry-forward -- unlike the
validation-withheld path, which keeps what the target already held -- and
because reconstruct treats the entry list as the complete desired key
set, the failed chunk's keys were removed from the target file. Already
shipped translations were erased by a run whose only interest in them was
re-translating them, with the .bak unlinked because the run succeeded.

For PO the entry disappears rather than emptying, so `msgfmt
--statistics` reports the catalog fully translated while strings are
missing.

The existing translation is now carried forward, and deliberately not
counted as a success: the lockfile records `failed` so the next run
retries the key.

Refs cli-8zn5.4
---
 CHANGELOG.md                                  |   2 +
 src/sync/sync-locale-translator.ts            |  25 ++-
 .../sync-failed-batch.integration.test.ts     | 175 ++++++++++++++++++
 3 files changed, 201 insertions(+), 1 deletion(-)
 create mode 100644 tests/integration/sync-failed-batch.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 670f3303..3afa7196 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **one failed translate batch no longer deletes that batch's existing translations.** `translateBatch` chunks at 50 texts and deliberately keeps going when one chunk's request fails, returning empty slots for its texts. Those slots fell into a bare `failed++` with no carry-forward — unlike the validation-withheld path, which keeps whatever the target already held — and since `reconstruct` treats the entry list as the complete desired key set, the failed chunk's keys were **removed from the target file**. Translations that had already shipped were erased by a run that touched them only to re-translate them, and the run's `.bak` was unlinked because the run itself succeeded. Needs more than 50 changed strings in one file, so a single-chunk failure was always safe; for PO the whole entry disappeared, which is worse than an empty `msgstr` because `msgfmt --statistics` then reports the catalog fully translated while strings are missing. Measured on a 60-key JSON file with every value changed and the second chunk answering 500: 60 keys before, 50 after, `k51`–`k60` gone. A key the target already holds a translation for now keeps it, and — unlike the first-adoption carry above — is deliberately **not** counted as a success, so the lockfile records `failed` and the next run retries it.
+
 - **sync**: **the first `deepl sync` over an already-translated project no longer overwrites every reviewer translation with machine output.** The carry-forward that protects a reviewed translation was wired into the `current`-key path only, and a key is `current` only once the lockfile mentions it. With no `.deepl-sync.lock` — first adoption of the tool, or any CI checkout where the lockfile is gitignored — *every* key of a fully human-translated catalog arrives as `new`, so every key was re-translated, re-billed, and written over, dropping the review markers the formats carry (gettext `#, fuzzy`, XLIFF `state`) at **exit 0**, with no `.bak` surviving the successful run. Measured on a two-entry PO catalog with one `#, fuzzy` entry and no lockfile: both `msgid`s went to the engine and both reviewed `msgstr`s came back as machine output. A `new` key whose target file already holds a translation is now carried forward untouched and recorded in the lockfile, so it is neither re-translated nor re-billed, and the marker survives because the entry is rewritten with the same bytes it already had. Two things are deliberately **not** carried: a target value equal to the source (a locale file copied from the source is untranslated text, and carrying it would freeze the source language into the locale — the same reasoning the new-locale path already applies) and an empty one; both are still translated. `--force` re-translates everything as before, since asking for re-translation is what it means. `sync status` already reported and refused to re-translate these keys — the invariant is now enforced on the path that writes, not only the one that reports.
 
 - **sync**: **the `--format json` error envelope is machine-readable again: it moves to stdout, the stream nothing else writes to.** The envelope went to stderr, which is also where every diagnostic goes — the CLI's own warnings (the world-readable-config notice, the non-DeepL-endpoint key warning, every `Logger.warn` in a run) and anything the Node runtime emits (`(node:7016) ExperimentalWarning: SQLite is an experimental feature…`, which is exactly how three e2e tests broke on 2026-08-08: `JSON.parse(stderr)` failed at the opening `(`). A consumer capturing stderr got valid JSON only when nothing else happened to be said, and the failure path — the one case a script most needs to parse — was the one case sharing a stream. Measured before the fix: `deepl sync validate --format json` in a directory with no `.deepl-sync.yaml` and a group-readable config file wrote the mode-tightening warning **and** the envelope interleaved on stderr, with stdout empty. The envelope is the command's *result* in the failure case, so it now lands where the success payload already does; the non-zero exit code remains the failure signal, and warnings stay on stderr where they can no longer break the parse — asserted end to end with the CLI's own warning firing alongside a `JSON.parse` of the whole of stdout. `sync init`'s config-already-exists envelope, previously built inline, goes through the shared emitter and moves with it. See Changed for the migration note.
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 05a2ba8d..e2296712 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -746,6 +746,17 @@ export class LocaleTranslator {
     }
 
     const translatedEntries: TranslatedEntry[] = [];
+    /**
+     * Existing translations of keys this run could not translate.
+     *
+     * `translateBatch` chunks at 50 texts and carries on when one chunk's
+     * request fails, so those texts come back as empty slots. The entry list is
+     * the complete desired key set, so omitting such a key deletes the
+     * translation the target already shipped — for a key the run touched only to
+     * re-translate it. Kept out of `successfulKeys` on purpose: the lockfile has
+     * to record `failed` so the next run retries.
+     */
+    const failedCarryEntries: TranslatedEntry[] = [];
     let translated = 0;
     let failed = 0;
     let localeBilled = 0;
@@ -774,6 +785,15 @@ export class LocaleTranslator {
         translated++;
       } else {
         failed++;
+        const previous = existingTranslations.get(diff.key);
+        if (previous !== undefined && diff.value !== undefined) {
+          failedCarryEntries.push({
+            key: diff.key,
+            value: diff.value,
+            translation: previous,
+            metadata: withoutPluralForms(diff.metadata),
+          });
+        }
       }
     }
 
@@ -785,7 +805,10 @@ export class LocaleTranslator {
 
     const successfulKeys: string[] = translatedEntries.map((te) => te.key);
 
-    const allTranslatedEntries: TranslatedEntry[] = [...translatedEntries];
+    const allTranslatedEntries: TranslatedEntry[] = [
+      ...translatedEntries,
+      ...failedCarryEntries,
+    ];
 
     // Carried-forward keys count as successful so the lockfile records the
     // translation the target file holds. Left out, they would come back `new` on
diff --git a/tests/integration/sync-failed-batch.integration.test.ts b/tests/integration/sync-failed-batch.integration.test.ts
new file mode 100644
index 00000000..0d786072
--- /dev/null
+++ b/tests/integration/sync-failed-batch.integration.test.ts
@@ -0,0 +1,175 @@
+/**
+ * Integration tests for what a partially failed translate leaves in the target.
+ *
+ * `translateBatch` chunks at 50 texts and keeps going when one chunk's request
+ * fails, returning empty slots for that chunk's texts. Those slots used to fall
+ * into a bare `failed++` with no carry-forward, and because `reconstruct` treats
+ * the entry list as the complete desired key set, the keys of the failed chunk
+ * were deleted from the target file — translations that had already shipped,
+ * erased by a run that touched them only to re-translate them. The lockfile must
+ * still record them `failed` so the next run retries.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import { LOCK_FILE_NAME } from '../../src/sync/types';
+import type { SyncLockFile } from '../../src/sync/types';
+
+/** 60 keys: two chunks of 50 + 10 at the 50-text batch size. */
+const KEY_COUNT = 60;
+const FIRST_CHUNK = 50;
+
+function keyName(i: number): string {
+  return `k${String(i + 1).padStart(2, '0')}`;
+}
+
+function sourceObject(revision: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < KEY_COUNT; i++) {
+    out[keyName(i)] = `${revision} text ${i + 1}`;
+  }
+  return out;
+}
+
+/** Echo `[ES] <text>`, recording the texts of every request. */
+function replyEchoing(): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .persist()
+    .post('/v2/translate')
+    .reply(200, (_uri, body) => {
+      const texts = new URLSearchParams(body as string).getAll('text');
+      return {
+        translations: texts.map((t) => ({
+          text: `[ES] ${t}`,
+          detected_source_language: 'EN',
+          billed_characters: t.length,
+        })),
+      };
+    });
+}
+
+describe('sync with one translate batch failing', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  const sourcePath = () => path.join(tmpDir, 'locales', 'en.json');
+  const targetPath = () => path.join(tmpDir, 'locales', 'es.json');
+  const readTarget = (): Record<string, string> =>
+    JSON.parse(fs.readFileSync(targetPath(), 'utf-8')) as Record<
+      string,
+      string
+    >;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-failed-batch-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es'],
+      buckets: { json: { include: ['locales/en.json'] } },
+    });
+    fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+    fs.writeFileSync(
+      sourcePath(),
+      JSON.stringify(sourceObject('v1'), null, 2),
+      'utf-8'
+    );
+  });
+
+  /** A project whose 60 keys are all translated and recorded in the lockfile. */
+  async function establishProject(): Promise<void> {
+    replyEchoing();
+    const first = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+    expect(first.success).toBe(true);
+    expect(Object.keys(readTarget())).toHaveLength(KEY_COUNT);
+    nock.cleanAll();
+  }
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  /** Every source value changes, so all 60 keys are stale and re-translated. */
+  function bumpSourceAndFailSecondChunk(): void {
+    fs.writeFileSync(
+      sourcePath(),
+      JSON.stringify(sourceObject('v2'), null, 2),
+      'utf-8'
+    );
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => {
+        const texts = new URLSearchParams(body as string).getAll('text');
+        return {
+          translations: texts.map((t) => ({
+            text: `[ES] ${t}`,
+            detected_source_language: 'EN',
+            billed_characters: t.length,
+          })),
+        };
+      });
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .reply(500, { message: 'Internal server error' });
+  }
+
+  it('keeps the failed chunk’s existing translations in the target', async () => {
+    await establishProject();
+    bumpSourceAndFailSecondChunk();
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    const written = readTarget();
+    expect(Object.keys(written)).toHaveLength(KEY_COUNT);
+
+    // The chunk that succeeded holds fresh translations of the new source.
+    expect(written[keyName(0)]).toBe('[ES] v2 text 1');
+    // The chunk that failed keeps what it already had, rather than vanishing.
+    for (let i = FIRST_CHUNK; i < KEY_COUNT; i++) {
+      expect(written[keyName(i)]).toBe(`[ES] v1 text ${i + 1}`);
+    }
+
+    expect(result.fileResults.map((r) => r.failed)).toEqual([
+      KEY_COUNT - FIRST_CHUNK,
+    ]);
+  });
+
+  it('records the failed chunk as failed so the next run retries it', async () => {
+    await establishProject();
+    bumpSourceAndFailSecondChunk();
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    const lock = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, LOCK_FILE_NAME), 'utf-8')
+    ) as SyncLockFile;
+    const entries = lock.entries['locales/en.json']!;
+    expect(entries[keyName(0)]!.translations['es']!.status).toBe('translated');
+    expect(entries[keyName(FIRST_CHUNK)]!.translations['es']!.status).toBe(
+      'failed'
+    );
+
+    // The retry: with the engine healthy again, the carried keys translate.
+    nock.cleanAll();
+    replyEchoing();
+    const retry = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(retry.success).toBe(true);
+    const written = readTarget();
+    for (let i = FIRST_CHUNK; i < KEY_COUNT; i++) {
+      expect(written[keyName(i)]).toBe(`[ES] v2 text ${i + 1}`);
+    }
+  });
+});

From a2e63abbd097115427c6f25c1a129d5c8e1a39e8 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:30:58 +0200
Subject: [PATCH 193/256] fix(sync): guard the audit read against lockfile keys
 that escape the root

`deepl sync audit` is the only sync read driven by .deepl-sync.lock keys
rather than by globbed source paths, and it joined resolveTargetPath's
output to the project root and read it with a bare fs.readFile -- the
single bypass of a guard whose docstring claims it cannot be bypassed by
a caller that forgets.

A lockfile arrives with a clone like any other committed file, so its
keys are untrusted input. A key of `../secretplace/en.json` read a file
outside the root and `--format json` printed its string values in
inconsistencies[].translations, at exit 0.

assertPathWithinRoot now runs before the read. A violation ends the
command rather than skipping the locale, matching how a sync run treats
one. A lockfile entry whose path merely fails to resolve for a locale is
still skipped, so a stale lockfile does not become a hard failure.

Refs cli-8zn5.8
---
 CHANGELOG.md                                  |   2 +
 src/cli/commands/sync/register-sync-audit.ts  |  21 +-
 .../e2e/cli-sync-audit-traversal.e2e.test.ts  | 201 ++++++++++++++++++
 3 files changed, 221 insertions(+), 3 deletions(-)
 create mode 100644 tests/e2e/cli-sync-audit-traversal.e2e.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3afa7196..ccde2db7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`deepl sync audit` no longer reads files outside the project root.** Audit is the one sync read driven by `.deepl-sync.lock` keys rather than by globbed source paths, and it joined `resolveTargetPath`'s output to the project root and read it with a bare `fs.readFile`, never calling `assertPathWithinRoot` — the single bypass of a guard whose own docstring claims it "cannot be bypassed by a caller that forgets". A lockfile arrives with a clone like any other committed file, so its keys are untrusted input: a key of `../secretplace/en.json` read a file outside the root and `--format json` printed that file's string values in `inconsistencies[].translations`, at exit 0. Measured on a project with two lockfile entries sharing one `source_text`, one of them escaping the root: the report carried the out-of-root file's contents verbatim. The guard now runs before the read, and a violation ends the command at exit 6 rather than skipping the locale, matching how a sync run treats a containment violation — it is a problem with the project, not with one locale. A lockfile entry whose path merely fails to resolve for a locale is still skipped as before, so a stale lockfile does not become a hard failure.
+
 - **sync**: **one failed translate batch no longer deletes that batch's existing translations.** `translateBatch` chunks at 50 texts and deliberately keeps going when one chunk's request fails, returning empty slots for its texts. Those slots fell into a bare `failed++` with no carry-forward — unlike the validation-withheld path, which keeps whatever the target already held — and since `reconstruct` treats the entry list as the complete desired key set, the failed chunk's keys were **removed from the target file**. Translations that had already shipped were erased by a run that touched them only to re-translate them, and the run's `.bak` was unlinked because the run itself succeeded. Needs more than 50 changed strings in one file, so a single-chunk failure was always safe; for PO the whole entry disappeared, which is worse than an empty `msgstr` because `msgfmt --statistics` then reports the catalog fully translated while strings are missing. Measured on a 60-key JSON file with every value changed and the second chunk answering 500: 60 keys before, 50 after, `k51`–`k60` gone. A key the target already holds a translation for now keeps it, and — unlike the first-adoption carry above — is deliberately **not** counted as a success, so the lockfile records `failed` and the next run retries it.
 
 - **sync**: **the first `deepl sync` over an already-translated project no longer overwrites every reviewer translation with machine output.** The carry-forward that protects a reviewed translation was wired into the `current`-key path only, and a key is `current` only once the lockfile mentions it. With no `.deepl-sync.lock` — first adoption of the tool, or any CI checkout where the lockfile is gitignored — *every* key of a fully human-translated catalog arrives as `new`, so every key was re-translated, re-billed, and written over, dropping the review markers the formats carry (gettext `#, fuzzy`, XLIFF `state`) at **exit 0**, with no `.bak` surviving the successful run. Measured on a two-entry PO catalog with one `#, fuzzy` entry and no lockfile: both `msgid`s went to the engine and both reviewed `msgstr`s came back as machine output. A `new` key whose target file already holds a translation is now carried forward untouched and recorded in the lockfile, so it is neither re-translated nor re-billed, and the marker survives because the entry is rewritten with the same bytes it already had. Two things are deliberately **not** carried: a target value equal to the source (a locale file copied from the source is untranslated text, and carrying it would freeze the source language into the locale — the same reasoning the new-locale path already applies) and an empty one; both are still translated. `--force` re-translates everything as before, since asking for re-translation is what it means. `sync status` already reported and refused to re-translate these keys — the invariant is now enforced on the path that writes, not only the one that reports.
diff --git a/src/cli/commands/sync/register-sync-audit.ts b/src/cli/commands/sync/register-sync-audit.ts
index e552bfc7..18d05abc 100644
--- a/src/cli/commands/sync/register-sync-audit.ts
+++ b/src/cli/commands/sync/register-sync-audit.ts
@@ -71,7 +71,8 @@ async function handleSyncAudit(
     const { extractExistingTranslations } =
       await import('../../../sync/sync-bucket-walker.js');
     const { createDefaultRegistry } = await import('../../../formats/index.js');
-    const { resolveTargetPath } = await import('../../../sync/sync-utils.js');
+    const { resolveTargetPath, assertPathWithinRoot } =
+      await import('../../../sync/sync-utils.js');
     const pathMod = await import('path');
     const fsMod = await import('fs');
 
@@ -90,6 +91,7 @@ async function handleSyncAudit(
       for (const relPath of Object.keys(lockFile.entries)) {
         const fileLocaleMap = new Map<string, Map<string, string>>();
         for (const locale of config.target_locales) {
+          let targetAbs: string;
           try {
             const targetRel = resolveTargetPath(
               relPath,
@@ -97,8 +99,21 @@ async function handleSyncAudit(
               locale,
               bucketConfig.target_path_pattern
             );
-            const targetAbs = pathMod.join(config.projectRoot, targetRel);
-            if (!fsMod.existsSync(targetAbs)) continue;
+            targetAbs = pathMod.join(config.projectRoot, targetRel);
+          } catch {
+            // A lockfile entry whose path no longer resolves for this locale.
+            continue;
+          }
+          // Audit is the only sync read driven by lockfile keys rather than
+          // globbed source paths, and a lockfile arrives with a clone like any
+          // other committed file — so its keys are untrusted input. A key of
+          // `../secret/en.json` otherwise read a file outside the project root
+          // and printed its string values in the report. Thrown rather than
+          // skipped, matching how a sync run treats a containment violation: it
+          // is a problem with the project, not with one locale.
+          assertPathWithinRoot(targetAbs, config.projectRoot);
+          if (!fsMod.existsSync(targetAbs)) continue;
+          try {
             const content = await fsMod.promises.readFile(targetAbs, 'utf-8');
             fileLocaleMap.set(
               locale,
diff --git a/tests/e2e/cli-sync-audit-traversal.e2e.test.ts b/tests/e2e/cli-sync-audit-traversal.e2e.test.ts
new file mode 100644
index 00000000..f8eeccee
--- /dev/null
+++ b/tests/e2e/cli-sync-audit-traversal.e2e.test.ts
@@ -0,0 +1,201 @@
+/**
+ * E2E regression for the containment gap in `deepl sync audit`.
+ *
+ * Audit is the one sync read that walks `.deepl-sync.lock` keys rather than
+ * globbed source files, and it joined `resolveTargetPath`'s output to the
+ * project root and read it with a bare `fs.readFile` — no
+ * `assertPathWithinRoot`. A committed lockfile key of `../secretplace/en.json`
+ * therefore read a file outside the project root, and `--format json` printed
+ * that file's string values in `inconsistencies[].translations`: a
+ * content-exfiltration primitive driven by a file that arrives with a clone.
+ */
+
+import { spawnSync, SpawnSyncReturns } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createTestConfigDir } from '../helpers';
+import { LOCK_FILE_VERSION, LOCK_FILE_COMMENT } from '../../src/sync/types';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const VALIDATION_EXIT_CODE = 6;
+const SECRET = 'TOP-SECRET-EXFIL-abc123';
+
+describe('CLI sync audit path containment', () => {
+  const testConfig = createTestConfigDir('e2e-audit-traversal');
+  let rootDir: string;
+  let projectDir: string;
+
+  interface Run {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+  }
+
+  function runCli(args: string[]): Run {
+    const env: Record<string, string | undefined> = {
+      ...process.env,
+      DEEPL_CONFIG_DIR: testConfig.path,
+      NO_COLOR: '1',
+    };
+    // A real key in the ambient environment would send this run at the live API.
+    delete env['DEEPL_API_KEY'];
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        cwd: projectDir,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 30000,
+      }
+    );
+    return {
+      status: result.status,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  beforeAll(() => {
+    fs.writeFileSync(
+      path.join(testConfig.path, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: 'http://127.0.0.1:1/', usePro: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        proxy: {},
+      }),
+      'utf-8'
+    );
+  });
+
+  afterAll(() => {
+    testConfig.cleanup();
+  });
+
+  beforeEach(() => {
+    rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-audit-traversal-'));
+    projectDir = path.join(rootDir, 'project');
+    const secretDir = path.join(rootDir, 'secretplace');
+    fs.mkdirSync(path.join(projectDir, 'locales'), { recursive: true });
+    fs.mkdirSync(secretDir, { recursive: true });
+
+    // Outside the project root: the file the lockfile key reaches for.
+    fs.writeFileSync(
+      path.join(secretDir, 'de.json'),
+      JSON.stringify({ greeting: SECRET }),
+      'utf-8'
+    );
+
+    fs.writeFileSync(
+      path.join(projectDir, '.deepl-sync.yaml'),
+      [
+        'version: 1',
+        'source_locale: en',
+        'target_locales:',
+        '  - de',
+        'buckets:',
+        '  json:',
+        '    include:',
+        '      - "locales/en.json"',
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+    fs.writeFileSync(
+      path.join(projectDir, 'locales', 'en.json'),
+      JSON.stringify({ greeting: 'Hello' }, null, 2),
+      'utf-8'
+    );
+    fs.writeFileSync(
+      path.join(projectDir, 'locales', 'de.json'),
+      JSON.stringify({ greeting: 'Hallo' }, null, 2),
+      'utf-8'
+    );
+
+    // Two lockfile entries share one source_text, so a second, differing
+    // translation lands in `inconsistencies[].translations` — the field that
+    // carried the out-of-root file's content. The second key escapes the root.
+    const entry = {
+      source_hash: 'h1',
+      source_text: 'Hello',
+      translations: {
+        de: {
+          hash: 'h1',
+          translated_at: new Date(0).toISOString(),
+          status: 'translated' as const,
+        },
+      },
+    };
+    fs.writeFileSync(
+      path.join(projectDir, '.deepl-sync.lock'),
+      JSON.stringify(
+        {
+          _comment: LOCK_FILE_COMMENT,
+          version: LOCK_FILE_VERSION,
+          generated_at: new Date(0).toISOString(),
+          source_locale: 'en',
+          entries: {
+            'locales/en.json': { greeting: entry },
+            '../secretplace/en.json': { greeting: entry },
+          },
+          stats: {
+            total_keys: 2,
+            total_translations: 2,
+            last_sync: new Date(0).toISOString(),
+          },
+        },
+        null,
+        2
+      ) + '\n',
+      'utf-8'
+    );
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(rootDir)) {
+      fs.rmSync(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses a lockfile key that escapes the project root', () => {
+    const run = runCli(['sync', 'audit', '--format', 'json']);
+
+    expect(run.status).toBe(VALIDATION_EXIT_CODE);
+    expect(run.stdout + run.stderr).toMatch(/escapes project root/i);
+  });
+
+  it('never prints content from outside the project root', () => {
+    const run = runCli(['sync', 'audit', '--format', 'json']);
+
+    expect(run.stdout).not.toContain(SECRET);
+    expect(run.stderr).not.toContain(SECRET);
+  });
+
+  it('still audits a project whose lockfile keys are all inside the root', () => {
+    const lockPath = path.join(projectDir, '.deepl-sync.lock');
+    const lock = JSON.parse(fs.readFileSync(lockPath, 'utf-8')) as {
+      entries: Record<string, unknown>;
+    };
+    delete lock.entries['../secretplace/en.json'];
+    fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf-8');
+
+    const run = runCli(['sync', 'audit', '--format', 'json']);
+
+    expect(run.status).toBe(0);
+    const report = JSON.parse(run.stdout) as {
+      totalTerms: number;
+      inconsistencies: unknown[];
+    };
+    expect(report.totalTerms).toBe(1);
+    expect(report.inconsistencies).toEqual([]);
+  });
+});

From b0e6f526bdecd6ad42893abee8eb32f0375a1b0f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:34:04 +0200
Subject: [PATCH 194/256] fix(sync): stop sync pull deleting tab, LF and CR
 from pulled translations

The pull value sanitizer stripped /[\x00-\x1f\x7f]/g, a range that
includes the three C0 bytes isForbiddenControlChar exempts because every
format either escapes them or legally emits them. An approved multi-line
or tabbed translation had them deleted rather than escaped, fusing
adjacent words at exit 0 with `Pulled N`. Any correct TMS returning a
multi-line string hit this.

Tab, LF and CR now reach the per-format writer, which escapes them.
Every other C0 byte and DEL is still stripped: a raw ESC in a locale
file renders as a live terminal command in git diff and CI logs.

The unit test covering this asserted the fused output under a name
claiming it preserved tabs and newlines; it now asserts what its name
says.

Refs cli-8zn5.10
---
 CHANGELOG.md                                  |  2 ++
 src/sync/tms-client.ts                        | 18 +++++++++++--
 .../integration/sync-tms.integration.test.ts  | 27 +++++++++++++++++++
 tests/unit/sync/tms-client.test.ts            | 13 +++++----
 4 files changed, 51 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ccde2db7..70a34431 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **`deepl sync pull` keeps the tabs and newlines of a multi-line translation instead of deleting them.** The pull value sanitizer ran `/[\x00-\x1f\x7f]/g` over every value returned by the TMS — a range that includes 0x09, 0x0a and 0x0d, the three C0 bytes this project's own `isForbiddenControlChar` exempts because every format either escapes them or legally emits them. A human-approved multi-line or tabbed translation had those bytes **deleted rather than escaped**, fusing the adjacent words (`"Zeile eins\nZeile zwei"` → `"Zeile einsZeile zwei"`), reported as `Pulled N` at exit 0. This fired on any correct TMS returning a multi-line string, not only a hostile one, and the unit test covering it asserted the fused output under a name that claimed the opposite. Tab, LF and CR now survive to the per-format writer, which escapes them; every other C0 byte and DEL is still stripped, because a raw ESC reaching a locale file renders as a live terminal command in `git diff` and CI log viewers. Verified end to end: a pulled `"Zeile eins\nZeile zwei\tmit Tab\x1b[31m"` lands in `de.json` with the newline and tab intact and the ESC removed.
+
 - **sync**: **`deepl sync audit` no longer reads files outside the project root.** Audit is the one sync read driven by `.deepl-sync.lock` keys rather than by globbed source paths, and it joined `resolveTargetPath`'s output to the project root and read it with a bare `fs.readFile`, never calling `assertPathWithinRoot` — the single bypass of a guard whose own docstring claims it "cannot be bypassed by a caller that forgets". A lockfile arrives with a clone like any other committed file, so its keys are untrusted input: a key of `../secretplace/en.json` read a file outside the root and `--format json` printed that file's string values in `inconsistencies[].translations`, at exit 0. Measured on a project with two lockfile entries sharing one `source_text`, one of them escaping the root: the report carried the out-of-root file's contents verbatim. The guard now runs before the read, and a violation ends the command at exit 6 rather than skipping the locale, matching how a sync run treats a containment violation — it is a problem with the project, not with one locale. A lockfile entry whose path merely fails to resolve for a locale is still skipped as before, so a stale lockfile does not become a hard failure.
 
 - **sync**: **one failed translate batch no longer deletes that batch's existing translations.** `translateBatch` chunks at 50 texts and deliberately keeps going when one chunk's request fails, returning empty slots for its texts. Those slots fell into a bare `failed++` with no carry-forward — unlike the validation-withheld path, which keeps whatever the target already held — and since `reconstruct` treats the entry list as the complete desired key set, the failed chunk's keys were **removed from the target file**. Translations that had already shipped were erased by a run that touched them only to re-translate them, and the run's `.bak` was unlinked because the run itself succeeded. Needs more than 50 changed strings in one file, so a single-chunk failure was always safe; for PO the whole entry disappeared, which is worse than an empty `msgstr` because `msgfmt --statistics` then reports the catalog fully translated while strings are missing. Measured on a 60-key JSON file with every value changed and the second chunk answering 500: 60 keys before, 50 after, `k51`–`k60` gone. A key the target already holds a translation for now keeps it, and — unlike the first-adoption carry above — is deliberately **not** counted as a success, so the lockfile records `failed` and the next run retries it.
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index 64450619..f0d62395 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -15,8 +15,22 @@ export const MAX_PULL_KEY_COUNT = 50000;
 export const MAX_PULL_BODY_BYTES = 32 * 1024 * 1024;
 // eslint-disable-next-line no-control-regex -- intentional: checking for control chars in untrusted TMS-returned keys
 const KEY_FORBIDDEN_CHARS = /[\x00-\x1f\x7f/\\]/;
-// eslint-disable-next-line no-control-regex -- intentional: strip control chars from untrusted TMS-returned values before they reach the filesystem
+// eslint-disable-next-line no-control-regex -- intentional: matching control chars in untrusted TMS-returned text before quoting it into an error message
 const VALUE_CONTROL_CHARS = /[\x00-\x1f\x7f]/g;
+/**
+ * Control characters stripped from an accepted pull value: C0 and DEL, minus
+ * tab, LF and CR.
+ *
+ * Those three are the set `isForbiddenControlChar` exempts — the C0 bytes every
+ * format either escapes or legally emits — and a multi-line or tabbed
+ * translation is ordinary human content, not a hostile payload. Deleting them
+ * (rather than letting the per-format writer escape them) fused adjacent words
+ * of an approved translation at exit 0. Everything else is still removed here,
+ * because a raw ESC reaching a locale file renders as a live terminal command in
+ * `git diff` and CI logs.
+ */
+// eslint-disable-next-line no-control-regex -- intentional: strip format-breaking control chars from untrusted TMS-returned values before they reach the filesystem
+const VALUE_FORBIDDEN_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
 
 export function sanitizePullKeysResponse(raw: unknown): Record<string, string> {
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
@@ -59,7 +73,7 @@ export function sanitizePullKeysResponse(raw: unknown): Record<string, string> {
         'Split oversized translations into smaller keys, or raise the issue with your TMS administrator.'
       );
     }
-    result[key] = value.replace(VALUE_CONTROL_CHARS, '');
+    result[key] = value.replace(VALUE_FORBIDDEN_CHARS, '');
   }
   return result;
 }
diff --git a/tests/integration/sync-tms.integration.test.ts b/tests/integration/sync-tms.integration.test.ts
index 9ea5aadf..e1a363d6 100644
--- a/tests/integration/sync-tms.integration.test.ts
+++ b/tests/integration/sync-tms.integration.test.ts
@@ -93,6 +93,33 @@ describe('sync push/pull (TMS integration)', () => {
     }
   });
 
+  it('pull: keeps a multi-line translation intact rather than fusing its lines', async () => {
+    writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
+    writeJson(tmpDir, 'locales/en.json', { notice: 'Line one\nLine two' });
+    writeJson(tmpDir, 'locales/de.json', { notice: 'OLD' });
+
+    process.env['TMS_API_KEY'] = 'env-key';
+
+    const config = await loadSyncConfig(tmpDir);
+    const client = await createTmsClient(config.tms!, approvedTmsTrust);
+
+    // A control byte that is never legitimate content is still removed, so the
+    // value-stripping is narrowed rather than abandoned.
+    expectTmsPull(
+      'de',
+      { notice: 'Zeile eins\nZeile zwei\tmit Tab\x1b[31m' },
+      { auth: { apiKey: 'env-key' } }
+    );
+
+    const result = await pullTranslations(config, client, harness.registry);
+    expect(result.pulled).toBe(1);
+
+    const targetContent = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'locales/de.json'), 'utf-8')
+    ) as Record<string, string>;
+    expect(targetContent['notice']).toBe('Zeile eins\nZeile zwei\tmit Tab[31m');
+  });
+
   // ---- Case 2: pull happy path ----
   it('pull: fetches translations, writes target file, and does not claim human review', async () => {
     writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });
diff --git a/tests/unit/sync/tms-client.test.ts b/tests/unit/sync/tms-client.test.ts
index 228406be..896c5092 100644
--- a/tests/unit/sync/tms-client.test.ts
+++ b/tests/unit/sync/tms-client.test.ts
@@ -1133,17 +1133,16 @@ describe('TmsClient.pullKeys response validation', () => {
     expect(result['greeting']).toBe('HalloWorld');
   });
 
-  it('should preserve printable content including tabs and newlines-as-content when stripping', async () => {
-    // Tabs (\x09), line feeds (\x0a), carriage returns (\x0d) are control chars
-    // per the spec but common in translation values; stripping them is the
-    // documented behavior (fail-closed on format-breaking bytes).
+  it('should keep tab, LF and CR, which are legitimate translation content', async () => {
+    // The three C0 bytes every format either escapes or legally emits, and the
+    // three this project's own rule exempts. Deleting them fused adjacent words
+    // of a human-approved multi-line translation.
     mockFetch.mockResolvedValue({
       ok: true,
-      json: async () => ({ greeting: 'line1\nline2\tend' }),
+      json: async () => ({ greeting: 'line1\nline2\tend\r\ntail' }),
     });
     const result = await client.pullKeys('de');
-    // The regex [\x00-\x1f\x7f] matches \n and \t. Expect both stripped.
-    expect(result['greeting']).toBe('line1line2end');
+    expect(result['greeting']).toBe('line1\nline2\tend\r\ntail');
   });
 
   it('should pass through normal payloads unchanged', async () => {

From 6d7ac8a5f277ee6d6178063e725af96eb77a03fa Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:39:58 +0200
Subject: [PATCH 195/256] fix(xliff): read a unit id containing the
 non-delimiting quote character

The id scanner captured id=["']([^"'<]+)["'], excluding both quote
characters from the value. Only the delimiter in use needs escaping
inside an XML attribute, so id="label.don't" truncated to `label.don`.
Two units whose ids differ only after the apostrophe collapsed onto one
key and both received the same translation -- one unit shipping another
string's text under its own id, unreported because XLIFF is exempt from
assertDistinctKeys.

The delimiter is now captured and the value excludes only that
delimiter, in both the 1.2 trans-unit and the 2.0 unit scanner. The id
moves to the second capture group, read through a `unitId` accessor
rather than groups[0] at each of the eight unit sites.

Refs cli-8zn5.9
---
 CHANGELOG.md                     |  2 +
 src/formats/xliff.ts             | 41 ++++++++------
 tests/unit/formats/xliff.test.ts | 91 ++++++++++++++++++++++++++++++++
 3 files changed, 118 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 70a34431..aac67a16 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **xliff**: **a `trans-unit` id containing an apostrophe is read in full, so two units no longer collapse onto one key.** The id scanner captured `id=["']([^"'<]+)["']`, excluding *both* quote characters from the value — but only the delimiter actually in use needs escaping inside an XML attribute, so `id="label.don't"` truncated to `label.don`. Two units whose ids differ only after the apostrophe therefore became one key, and the single fetched translation was written into **both** units, shipping one string's translation under another string's id. XLIFF is exempt from `assertDistinctKeys`, so nothing reported the collision and the lockfile recorded the truncated key. Measured on a v1.2 file with `label.don't` and `label.don'x`: both extracted as `label.don`, and both units received the same translation. The delimiter is now captured and the value excludes only that delimiter, in both the 1.2 `trans-unit` and 2.0 `unit` scanners; a single-quoted id keeps a double quote inside it for the same reason, and a following attribute (`xml:space="preserve"`) is still not swallowed into the id.
+
 - **sync**: **`deepl sync pull` keeps the tabs and newlines of a multi-line translation instead of deleting them.** The pull value sanitizer ran `/[\x00-\x1f\x7f]/g` over every value returned by the TMS — a range that includes 0x09, 0x0a and 0x0d, the three C0 bytes this project's own `isForbiddenControlChar` exempts because every format either escapes them or legally emits them. A human-approved multi-line or tabbed translation had those bytes **deleted rather than escaped**, fusing the adjacent words (`"Zeile eins\nZeile zwei"` → `"Zeile einsZeile zwei"`), reported as `Pulled N` at exit 0. This fired on any correct TMS returning a multi-line string, not only a hostile one, and the unit test covering it asserted the fused output under a name that claimed the opposite. Tab, LF and CR now survive to the per-format writer, which escapes them; every other C0 byte and DEL is still stripped, because a raw ESC reaching a locale file renders as a live terminal command in `git diff` and CI log viewers. Verified end to end: a pulled `"Zeile eins\nZeile zwei\tmit Tab\x1b[31m"` lands in `de.json` with the newline and tab intact and the ESC removed.
 
 - **sync**: **`deepl sync audit` no longer reads files outside the project root.** Audit is the one sync read driven by `.deepl-sync.lock` keys rather than by globbed source paths, and it joined `resolveTargetPath`'s output to the project root and read it with a bare `fs.readFile`, never calling `assertPathWithinRoot` — the single bypass of a guard whose own docstring claims it "cannot be bypassed by a caller that forgets". A lockfile arrives with a clone like any other committed file, so its keys are untrusted input: a key of `../secretplace/en.json` read a file outside the root and `--format json` printed that file's string values in `inconsistencies[].translations`, at exit 0. Measured on a project with two lockfile entries sharing one `source_text`, one of them escaping the root: the report carried the out-of-root file's contents verbatim. The guard now runs before the read, and a violation ends the command at exit 6 rather than skipping the locale, matching how a sync run treats a containment violation — it is a problem with the project, not with one locale. A lockfile entry whose path merely fails to resolve for a locale is still skipped as before, so a stale lockfile does not become a hard failure.
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index 58bc31d6..3366a73b 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -20,16 +20,27 @@ import {
 
 const VERSION_RE = /<(?:\w+:)?xliff[^>]*version=["'](\d+\.\d+)["']/i;
 
+// The quote delimiter is captured so the value can exclude only the delimiter
+// actually in use. Excluding both quote characters truncated `id="label.don't"`
+// at the apostrophe — well-formed XML, and only the delimiter needs escaping
+// inside a value — so two ids differing after an apostrophe collapsed onto one
+// key. XLIFF is exempt from `assertDistinctKeys`, so nothing reported the
+// collision and one unit shipped the other's translation.
 const TRANS_UNIT_EL: ElementPattern = {
-  open: /<(?:\w+:)?trans-unit\s+id=["']([^"'<]+)["'][^><]*>/iy,
+  open: /<(?:\w+:)?trans-unit\s+id=(["'])((?:(?!\1)[^<])+)\1[^><]*>/iy,
   close: /<\/(?:\w+:)?trans-unit>/iy,
 };
 
 const UNIT_EL: ElementPattern = {
-  open: /<(?:\w+:)?unit\s+id=["']([^"'<]+)["'][^><]*>/iy,
+  open: /<(?:\w+:)?unit\s+id=(["'])((?:(?!\1)[^<])+)\1[^><]*>/iy,
   close: /<\/(?:\w+:)?unit>/iy,
 };
 
+/** The `id` of a scanned `trans-unit`/`unit`; group 0 is the quote delimiter. */
+function unitId(element: ScannedElement): string {
+  return element.groups[1]!;
+}
+
 const SOURCE_EL: ElementPattern = {
   open: /<(\w+:)?source>/iy,
   close: /<\/(?:\w+:)?source>/iy,
@@ -350,7 +361,7 @@ export class XliffFormatParser implements FormatParser {
       if (translation === '') continue;
 
       yield {
-        key: element.groups[0]!,
+        key: unitId(element),
         translation,
         stateAttrs: isV2 ? scope.openTag : (target.groups[1] ?? ''),
       };
@@ -376,7 +387,7 @@ export class XliffFormatParser implements FormatParser {
     const unit = detectVersion(content) === '2.0' ? UNIT_EL : TRANS_UNIT_EL;
 
     for (const element of scanElements(content, unit)) {
-      if (element.groups[0] !== key) continue;
+      if (unitId(element) !== key) continue;
       const note = findElement(element.inner, NOTE_EL);
       return note ? unescapeXml(note.inner) : undefined;
     }
@@ -387,9 +398,7 @@ export class XliffFormatParser implements FormatParser {
     for (const element of scanElements(content, TRANS_UNIT_EL)) {
       const source = findElement(element.inner, SOURCE_EL);
       if (!source) continue;
-      entries.push(
-        this.toEntry(element.groups[0]!, source.inner, element.inner)
-      );
+      entries.push(this.toEntry(unitId(element), source.inner, element.inner));
     }
   }
 
@@ -400,9 +409,7 @@ export class XliffFormatParser implements FormatParser {
 
       const source = findElement(segment.inner, SOURCE_EL);
       if (!source) continue;
-      entries.push(
-        this.toEntry(element.groups[0]!, source.inner, element.inner)
-      );
+      entries.push(this.toEntry(unitId(element), source.inner, element.inner));
     }
   }
 
@@ -486,10 +493,11 @@ export class XliffFormatParser implements FormatParser {
     slotted: Set<string>
   ): string {
     const result = replaceElements(content, TRANS_UNIT_EL, (element) => {
-      slotted.add(element.groups[0]!);
-      const translation = translations.get(element.groups[0]!);
+      const id = unitId(element);
+      slotted.add(id);
+      const translation = translations.get(id);
       if (translation === undefined) return '';
-      assertNoControlChars(element.groups[0]!, translation);
+      assertNoControlChars(id, translation);
       const changed = !targetHolds(element.inner, translation);
       return rewriteInner(
         element,
@@ -505,10 +513,11 @@ export class XliffFormatParser implements FormatParser {
     slotted: Set<string>
   ): string {
     const result = replaceElements(content, UNIT_EL, (element) => {
-      slotted.add(element.groups[0]!);
-      const translation = translations.get(element.groups[0]!);
+      const id = unitId(element);
+      slotted.add(id);
+      const translation = translations.get(id);
       if (translation === undefined) return '';
-      assertNoControlChars(element.groups[0]!, translation);
+      assertNoControlChars(id, translation);
 
       const segment = findElement(element.inner, SEGMENT_EL);
       if (!segment) return element.text;
diff --git a/tests/unit/formats/xliff.test.ts b/tests/unit/formats/xliff.test.ts
index 7221940c..5e1f5d20 100644
--- a/tests/unit/formats/xliff.test.ts
+++ b/tests/unit/formats/xliff.test.ts
@@ -575,3 +575,94 @@ describe('xliff parser', () => {
     });
   });
 });
+
+describe('unit ids containing a quote character', () => {
+  // The id scanner excluded BOTH quote characters from the value, so a
+  // double-quoted id truncated at its first apostrophe. Two ids differing only
+  // after the apostrophe collapsed to one key, and XLIFF is exempt from
+  // assertDistinctKeys, so the single fetched translation was written into both
+  // units with nothing reported.
+  const V12 = `<?xml version="1.0" encoding="UTF-8"?>
+<xliff version="1.2">
+  <file source-language="en" target-language="es">
+    <body>
+      <trans-unit id="label.don't">
+        <source>Good morning</source>
+      </trans-unit>
+      <trans-unit id="label.don'x">
+        <source>Good evening</source>
+      </trans-unit>
+    </body>
+  </file>
+</xliff>`;
+
+  const V2 = `<?xml version="1.0" encoding="UTF-8"?>
+<xliff version="2.0" srcLang="en" trgLang="es">
+  <file id="f1">
+    <unit id="label.don't">
+      <segment>
+        <source>Good morning</source>
+      </segment>
+    </unit>
+    <unit id="label.don'x">
+      <segment>
+        <source>Good evening</source>
+      </segment>
+    </unit>
+  </file>
+</xliff>`;
+
+  it('keeps an apostrophe in a double-quoted v1.2 trans-unit id', () => {
+    const entries = parser.extract(V12);
+    expect(entries.map((e) => e.key)).toEqual(["label.don't", "label.don'x"]);
+    expect(entries.map((e) => e.value)).toEqual([
+      'Good morning',
+      'Good evening',
+    ]);
+  });
+
+  it('keeps an apostrophe in a double-quoted v2.0 unit id', () => {
+    const entries = parser.extract(V2);
+    expect(entries.map((e) => e.key)).toEqual(["label.don't", "label.don'x"]);
+  });
+
+  it('writes each translation into its own unit rather than into both', () => {
+    const written = parser.reconstruct(V12, [
+      { key: "label.don't", value: 'Good morning', translation: 'Buenos días' },
+      {
+        key: "label.don'x",
+        value: 'Good evening',
+        translation: 'Buenas tardes',
+      },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('<target>Buenos días</target>');
+    expect(written).toContain('<target>Buenas tardes</target>');
+    // Round-trips: re-reading finds both ids and both translations.
+    const back = [...parser.extractTranslations(written).entries()];
+    expect(back).toEqual([
+      ["label.don't", 'Buenos días'],
+      ["label.don'x", 'Buenas tardes'],
+    ]);
+  });
+
+  it('still reads a single-quoted id, and keeps a double quote inside it', () => {
+    const singleQuoted = V12.replace(
+      `id="label.don't"`,
+      `id='label.say"hi'`
+    ).replace(`id="label.don'x"`, `id='plain'`);
+
+    const entries = parser.extract(singleQuoted);
+    expect(entries.map((e) => e.key)).toEqual(['label.say"hi', 'plain']);
+  });
+
+  it('does not swallow a following attribute into the id', () => {
+    const withAttrs = V12.replace(
+      `id="label.don't"`,
+      `id="label.don't" xml:space="preserve"`
+    );
+
+    const entries = parser.extract(withAttrs);
+    expect(entries.map((e) => e.key)).toEqual(["label.don't", "label.don'x"]);
+  });
+});

From 8ff4dea0f9ae6f8a20ce8f6765d0db9c09f58790 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:45:00 +0200
Subject: [PATCH 196/256] fix(po): keep the continuation lines of a plural form
 being carried forward

gettext writes any msgstr[N] over 74 characters as `msgstr[N] ""` plus
continuation lines. reconstruct re-emitted the first line of a form it
was KEEPING and then swallowed the continuations -- correct only for a
form it has just replaced, where quoteLong has already re-emitted the
whole value.

A carried plural entry supplies no plural_forms metadata by design, so
the file's own forms stand; the reviewed translation therefore collapsed
to the empty first line. Adding one unrelated source key erased a
reviewed long plural form, and the entry then became permanently
unwritable.

msgfmt --statistics does not reveal this: it reports the catalog fully
translated before and after, since a plural message with a non-empty
msgstr[0] counts as translated. The evidence is the emitted bytes and a
re-extraction, which is what the tests assert.

Refs cli-8zn5.7
---
 CHANGELOG.md                                  |  2 +
 src/formats/po.ts                             |  9 +-
 ...c-plural-carry-forward.integration.test.ts | 32 ++++++++
 tests/unit/formats/po.test.ts                 | 82 +++++++++++++++++++
 4 files changed, 124 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aac67a16..a0246a44 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **po**: **a wrapped (continuation-line) plural form survives a run that only rewrites its entry for a sibling key.** gettext writes any `msgstr[N]` longer than 74 characters as `msgstr[N] ""` followed by continuation lines. `reconstruct` re-emitted the first line of a form it was *keeping* and then swallowed the continuations — the same branch that correctly swallows them for a form it has just replaced, where the whole value has already been re-emitted. Because a carried plural entry deliberately supplies no `plural_forms` metadata (so the file's own forms stand), the reviewed translation collapsed to the empty first line: adding one unrelated key to the source erased a reviewed long plural form, and the entry then became permanently unwritable. Note that `msgfmt --statistics` does **not** reveal this — it reports the catalog as fully translated before and after, because a plural message with a non-empty `msgstr[0]` counts as translated — so the loss is silent even to the format's own tool; the evidence is the emitted bytes and a re-extraction. Continuation lines are now kept for a form being carried and still dropped for a form being replaced.
+
 - **xliff**: **a `trans-unit` id containing an apostrophe is read in full, so two units no longer collapse onto one key.** The id scanner captured `id=["']([^"'<]+)["']`, excluding *both* quote characters from the value — but only the delimiter actually in use needs escaping inside an XML attribute, so `id="label.don't"` truncated to `label.don`. Two units whose ids differ only after the apostrophe therefore became one key, and the single fetched translation was written into **both** units, shipping one string's translation under another string's id. XLIFF is exempt from `assertDistinctKeys`, so nothing reported the collision and the lockfile recorded the truncated key. Measured on a v1.2 file with `label.don't` and `label.don'x`: both extracted as `label.don`, and both units received the same translation. The delimiter is now captured and the value excludes only that delimiter, in both the 1.2 `trans-unit` and 2.0 `unit` scanners; a single-quoted id keeps a double quote inside it for the same reason, and a following attribute (`xml:space="preserve"`) is still not swallowed into the id.
 
 - **sync**: **`deepl sync pull` keeps the tabs and newlines of a multi-line translation instead of deleting them.** The pull value sanitizer ran `/[\x00-\x1f\x7f]/g` over every value returned by the TMS — a range that includes 0x09, 0x0a and 0x0d, the three C0 bytes this project's own `isForbiddenControlChar` exempts because every format either escapes them or legally emits them. A human-approved multi-line or tabbed translation had those bytes **deleted rather than escaped**, fusing the adjacent words (`"Zeile eins\nZeile zwei"` → `"Zeile einsZeile zwei"`), reported as `Pulled N` at exit 0. This fired on any correct TMS returning a multi-line string, not only a hostile one, and the unit test covering it asserted the fused output under a name that claimed the opposite. Tab, LF and CR now survive to the per-format writer, which escapes them; every other C0 byte and DEL is still stripped, because a raw ESC reaching a locale file renders as a live terminal command in `git diff` and CI log viewers. Verified end to end: a pulled `"Zeile eins\nZeile zwei\tmit Tab\x1b[31m"` lands in `de.json` with the newline and tab intact and the ESC removed.
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 9f2bfb8e..0afb4416 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -665,7 +665,14 @@ export class PoFormatParser implements FormatParser {
             result.push(el);
           }
           inMsgstr = false;
-          inMsgstrPlural = true;
+          // Only a form this run is REPLACING swallows its continuation lines,
+          // because `quoteLong` has just re-emitted the whole value. A form
+          // being kept — a carried plural entry supplies no `plural_forms`, so
+          // the file's own forms stand — must keep its continuations too:
+          // gettext writes any form over 74 characters as `msgstr[N] ""` plus
+          // continuations, so dropping them left the empty first line as the
+          // whole translation.
+          inMsgstrPlural = pluralVal !== undefined;
           continue;
         }
 
diff --git a/tests/integration/sync-plural-carry-forward.integration.test.ts b/tests/integration/sync-plural-carry-forward.integration.test.ts
index ceaa9b24..12da5fce 100644
--- a/tests/integration/sync-plural-carry-forward.integration.test.ts
+++ b/tests/integration/sync-plural-carry-forward.integration.test.ts
@@ -158,6 +158,38 @@ describe('sync with a plural entry carried forward', () => {
       expect(written).toContain('msgstr "[ES] Bye"');
     });
 
+    it('keeps a wrapped (continuation-line) reviewed form while translating a sibling', async () => {
+      await establishProject();
+
+      // gettext writes any msgstr[N] over 74 characters as `msgstr[N] ""` plus
+      // continuation lines. reconstruct re-emitted only the first of those
+      // lines for a form it was keeping, so the reviewed text became "".
+      const long =
+        'Esta es una traduccion deliberadamente larga para que gettext la envuelva.';
+      fs.writeFileSync(
+        targetPath(),
+        fs
+          .readFileSync(targetPath(), 'utf-8')
+          .replace('msgstr[1] "%d archivos"', `msgstr[1] ""\n"${long}"`),
+        'utf-8'
+      );
+
+      fs.writeFileSync(sourcePath(), PO_V2, 'utf-8');
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const second = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(second.success).toBe(true);
+      expect(sent).toEqual(['Bye']);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain(long);
+      expect(written).toContain('msgstr[0] "Un archivo"');
+      expect(written).not.toMatch(/msgstr\[1] ""\s*\n\s*(?:msgid|$)/);
+    });
+
     it('still rewrites the forms when the plural source itself changed', async () => {
       await establishProject();
 
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index 150b8b4c..e18d7dee 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -803,3 +803,85 @@ describe('PoFormatParser — entries with no blank line between them', () => {
     ]);
   });
 });
+
+describe('PoFormatParser — carrying a wrapped plural form forward', () => {
+  // gettext writes any msgstr[N] over 74 characters as `msgstr[N] ""` plus
+  // continuation lines. A carried plural entry supplies no `plural_forms`
+  // metadata, so reconstruct must keep the form the file already holds — but it
+  // re-emitted only the FIRST line and swallowed the continuations, leaving
+  // `msgstr[N] ""`. The reviewed translation was erased by a run whose only
+  // reason to rewrite the entry was a sibling key.
+  const LONG_ES =
+    'Esta es una traduccion deliberadamente larga para que gettext la envuelva en varias lineas.';
+
+  const CATALOG = [
+    'msgid ""',
+    'msgstr ""',
+    '"Content-Type: text/plain; charset=UTF-8\\n"',
+    '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"',
+    '',
+    'msgid "One %d file"',
+    'msgid_plural "%d files"',
+    'msgstr[0] "Un archivo"',
+    'msgstr[1] ""',
+    `"${LONG_ES}"`,
+    '',
+    'msgid "Hello"',
+    'msgstr "Hola"',
+    '',
+  ].join('\n');
+
+  const parser = new PoFormatParser();
+
+  it('reads the wrapped form as its full value', () => {
+    const entries = parser.extract(CATALOG);
+    const plural = entries.find((e) => e.key === 'One %d file');
+    expect(
+      (plural?.metadata?.['plural_forms'] as Record<string, string>)?.[
+        'msgstr[1]'
+      ]
+    ).toBe(LONG_ES);
+  });
+
+  it('keeps every continuation line when the entry is carried, not retranslated', () => {
+    // The carry shape: the plural entry arrives with its plural_forms stripped
+    // (what `withoutPluralForms` produces), so the file's own forms must stand.
+    const written = parser.reconstruct(CATALOG, [
+      {
+        key: 'One %d file',
+        value: 'One %d file',
+        translation: 'Un archivo',
+        metadata: { msgid_plural: '%d files' },
+      },
+      { key: 'Hello', value: 'Hello', translation: 'Hola' },
+    ]);
+
+    expect(written).toContain(LONG_ES);
+    const reread = parser.extract(written);
+    const plural = reread.find((e) => e.key === 'One %d file');
+    expect(
+      (plural?.metadata?.['plural_forms'] as Record<string, string>)?.[
+        'msgstr[1]'
+      ]
+    ).toBe(LONG_ES);
+  });
+
+  it('still replaces a wrapped form when this run has a new translation for it', () => {
+    const fresh = 'Traduccion nueva y tambien bastante larga para envolverse.';
+    const written = parser.reconstruct(CATALOG, [
+      {
+        key: 'One %d file',
+        value: 'One %d file',
+        translation: 'Un archivo',
+        metadata: {
+          msgid_plural: '%d files',
+          plural_forms: { 'msgstr[0]': 'Un archivo', 'msgstr[1]': fresh },
+        },
+      },
+      { key: 'Hello', value: 'Hello', translation: 'Hola' },
+    ]);
+
+    expect(written).toContain(fresh);
+    expect(written).not.toContain(LONG_ES);
+  });
+});

From f6b0894e929b6483e3fb0b7210703794c3e2dc1e Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:50:36 +0200
Subject: [PATCH 197/256] fix(sync): identify a plural form by quantity, not by
 matching its value

expandPlurals skipped every Android <item> whose value equalled the
entry's own, so two coinciding forms were both skipped and only one was
ever translated. The primary write-back then used
find(p => p.value === diff.value), which returns whichever form comes
first rather than the `other` form the extractor published as
entry.value. English invariant nouns (fish, sheep) and copy-pasted items
make this ordinary input: `one` got the translation and `other` shipped
the English source, recorded translated.

The PO half mirrored it -- msgid_plural was expanded only when it
differed from msgid, so an invariant-noun entry left msgstr[1] empty and
still recorded the key translated.

Both sites now use one primaryPluralItem rule keyed on quantity (`other`,
else the first item), which android-xml's extractor also uses so the
three cannot drift apart. msgid_plural is always expanded; identical
texts deduplicate inside translateBatch, so this bills nothing extra.

Refs cli-8zn5.6
---
 CHANGELOG.md                                  |   2 +
 src/formats/android-xml.ts                    |   4 +-
 src/formats/util/plurals.ts                   |  25 +++
 src/sync/sync-locale-translator.ts            |   3 +-
 src/sync/sync-message-preprocess.ts           |  13 +-
 ...lural-coinciding-forms.integration.test.ts | 205 ++++++++++++++++++
 6 files changed, 247 insertions(+), 5 deletions(-)
 create mode 100644 src/formats/util/plurals.ts
 create mode 100644 tests/integration/sync-plural-coinciding-forms.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a0246a44..0e2c1ded 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a plural key whose source forms coincide no longer keeps source-language text in one of them.** The plural pipeline identified forms by value equality rather than by quantity: `expandPlurals` skipped every Android `<item>` whose value equalled the entry's own — so with two coinciding forms *neither* was expanded and only one was ever translated — and the primary write-back then used `find(p => p.value === diff.value)`, which returns whichever form comes first rather than the `other` form the extractor actually published as `entry.value`. English invariant nouns (fish, sheep, series) and copy-pasted `<item>`s make this ordinary input. Measured on `<item quantity="one">%d fish</item><item quantity="other">%d fish</item>`: `one` got the translation and **`other` shipped the English source**, recorded `translated`. The PO half had the mirror problem — `msgid_plural` was expanded only when it differed from `msgid`, so an invariant-noun entry left `msgstr[1]` untouched (`msgstr[1] ""`, silently untranslated but recorded translated). Both sites now use one shared `primaryPluralItem` rule keyed on quantity (`other`, else the first item), which the Android extractor also uses so the three cannot drift apart, and `msgid_plural` is always expanded — identical texts deduplicate inside `translateBatch`, so this bills nothing extra.
+
 - **po**: **a wrapped (continuation-line) plural form survives a run that only rewrites its entry for a sibling key.** gettext writes any `msgstr[N]` longer than 74 characters as `msgstr[N] ""` followed by continuation lines. `reconstruct` re-emitted the first line of a form it was *keeping* and then swallowed the continuations — the same branch that correctly swallows them for a form it has just replaced, where the whole value has already been re-emitted. Because a carried plural entry deliberately supplies no `plural_forms` metadata (so the file's own forms stand), the reviewed translation collapsed to the empty first line: adding one unrelated key to the source erased a reviewed long plural form, and the entry then became permanently unwritable. Note that `msgfmt --statistics` does **not** reveal this — it reports the catalog as fully translated before and after, because a plural message with a non-empty `msgstr[0]` counts as translated — so the loss is silent even to the format's own tool; the evidence is the emitted bytes and a re-extraction. Continuation lines are now kept for a form being carried and still dropped for a form being replaced.
 
 - **xliff**: **a `trans-unit` id containing an apostrophe is read in full, so two units no longer collapse onto one key.** The id scanner captured `id=["']([^"'<]+)["']`, excluding *both* quote characters from the value — but only the delimiter actually in use needs escaping inside an XML attribute, so `id="label.don't"` truncated to `label.don`. Two units whose ids differ only after the apostrophe therefore became one key, and the single fetched translation was written into **both** units, shipping one string's translation under another string's id. XLIFF is exempt from `assertDistinctKeys`, so nothing reported the collision and the lockfile recorded the truncated key. Measured on a v1.2 file with `label.don't` and `label.don'x`: both extracted as `label.don`, and both units received the same translation. The delimiter is now captured and the value excludes only that delimiter, in both the 1.2 `trans-unit` and 2.0 `unit` scanners; a single-quoted id keeps a double quote inside it for the same reason, and a following attribute (`xml:space="preserve"`) is still not swallowed into the id.
diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index 361fc9af..e6babfc2 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -18,6 +18,7 @@ import {
   type ElementPattern,
   type ScannedElement,
 } from './xml-scan.js';
+import { primaryPluralItem } from './util/plurals.js';
 
 interface PluralItem {
   quantity: string;
@@ -387,8 +388,7 @@ export class AndroidXmlFormatParser implements FormatParser {
         })
       );
 
-      const defaultItem =
-        plurals.find((p) => p.quantity === 'other') ?? plurals[0];
+      const defaultItem = primaryPluralItem(plurals);
       entries.push({
         key: el.groups[0]!,
         value: defaultItem?.value ?? '',
diff --git a/src/formats/util/plurals.ts b/src/formats/util/plurals.ts
new file mode 100644
index 00000000..28f76aed
--- /dev/null
+++ b/src/formats/util/plurals.ts
@@ -0,0 +1,25 @@
+/** One `<item quantity=…>` of an Android `<plurals>` element. */
+export interface PluralItemLike {
+  quantity: string;
+  value: string;
+}
+
+/**
+ * The plural form whose translation comes from the entry's own `value` rather
+ * than from a separately translated slot.
+ *
+ * `other` is the form Android requires every `<plurals>` to declare, and it is
+ * the one the extractor publishes as `entry.value`; the first item stands in for
+ * a non-conforming element that declares no `other`.
+ *
+ * Chosen by quantity, never by matching `value`: English invariant nouns (fish,
+ * sheep, series) and copy-pasted items make two forms carry the same source
+ * text, and a value match then returned whichever came first — so the real
+ * primary kept its source-language text, which was written to the target and
+ * recorded as translated.
+ */
+export function primaryPluralItem<T extends PluralItemLike>(
+  plurals: readonly T[]
+): T | undefined {
+  return plurals.find((p) => p.quantity === 'other') ?? plurals[0];
+}
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index e2296712..ba6c21a5 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -28,6 +28,7 @@ import {
   withoutPluralForms,
 } from './sync-utils.js';
 import { extractExistingTranslations } from './sync-bucket-walker.js';
+import { primaryPluralItem } from '../formats/util/plurals.js';
 import { BACKUP_SUFFIX } from './sync-bak-cleanup.js';
 import { Logger } from '../utils/logger.js';
 import {
@@ -740,7 +741,7 @@ export class LocaleTranslator {
       const androidPlurals = diff.metadata['plurals'] as
         Array<{ quantity: string; value: string }> | undefined;
       if (androidPlurals) {
-        const primary = androidPlurals.find((p) => p.value === diff.value);
+        const primary = primaryPluralItem(androidPlurals);
         if (primary) primary.value = result.text;
       }
     }
diff --git a/src/sync/sync-message-preprocess.ts b/src/sync/sync-message-preprocess.ts
index 0803cb77..8580d1d5 100644
--- a/src/sync/sync-message-preprocess.ts
+++ b/src/sync/sync-message-preprocess.ts
@@ -21,6 +21,7 @@ import type { TranslationService } from '../services/translation.js';
 import type { TranslationOptions } from '../types/api.js';
 import type { TranslationResult } from '../api/translation-client.js';
 import type { SyncDiff } from './types.js';
+import { primaryPluralItem } from '../formats/util/plurals.js';
 
 export interface PluralSlot {
   diffIndex: number;
@@ -48,8 +49,12 @@ export function expandPlurals(
     const androidPlurals = diff.metadata['plurals'] as
       Array<{ quantity: string; value: string }> | undefined;
     if (androidPlurals) {
+      // Reference identity against the primary form, not value equality: with
+      // coinciding source forms a value test skipped every matching form, so
+      // only one of them was ever translated.
+      const primary = primaryPluralItem(androidPlurals);
       for (const p of androidPlurals) {
-        if (p.value === diff.value) continue;
+        if (p === primary) continue;
         pluralSlots.push({
           diffIndex: di,
           format: 'android',
@@ -61,7 +66,11 @@ export function expandPlurals(
     }
 
     const msgidPlural = diff.metadata['msgid_plural'] as string | undefined;
-    if (msgidPlural && msgidPlural !== diff.value) {
+    // Expanded even when it equals `msgid`: `msgstr[1]` is a different form that
+    // needs its own translation, and a target language may distinguish the two
+    // where English does not. Identical texts deduplicate inside translateBatch,
+    // so this costs no extra characters.
+    if (msgidPlural) {
       pluralSlots.push({
         diffIndex: di,
         format: 'po',
diff --git a/tests/integration/sync-plural-coinciding-forms.integration.test.ts b/tests/integration/sync-plural-coinciding-forms.integration.test.ts
new file mode 100644
index 00000000..aa1246e9
--- /dev/null
+++ b/tests/integration/sync-plural-coinciding-forms.integration.test.ts
@@ -0,0 +1,205 @@
+/**
+ * Integration tests for plural entries whose SOURCE forms coincide.
+ *
+ * English has invariant nouns (fish, sheep, series), and copy-pasted `<item>`s
+ * are common, so two plural forms of one key often carry the same source text.
+ * Both halves of the plural pipeline identified a form by value equality rather
+ * than by quantity/index: `expandPlurals` skipped every form whose value equals
+ * the entry's own, and the primary write-back picked the FIRST form matching by
+ * value. With coinciding forms that left one form holding source-language text,
+ * written to the target and recorded `translated`.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+
+/** Echo `[ES] <text>`, recording every text the engine was sent. */
+function replyEchoing(sent: string[]): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .persist()
+    .post('/v2/translate')
+    .reply(200, (_uri, body) => {
+      const texts = new URLSearchParams(body as string).getAll('text');
+      sent.push(...texts);
+      return {
+        translations: texts.map((t) => ({
+          text: `[ES] ${t}`,
+          detected_source_language: 'EN',
+          billed_characters: t.length,
+        })),
+      };
+    });
+}
+
+describe('sync of a plural key whose source forms coincide', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  describe('Android <plurals>', () => {
+    const sourcePath = () => path.join(tmpDir, 'res', 'values', 'strings.xml');
+    const targetPath = () =>
+      path.join(tmpDir, 'res', 'values-es', 'strings.xml');
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-plural-same-'));
+      harness = createSyncHarness({ parsers: ['android_xml'] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: {
+          android_xml: {
+            include: ['res/values/strings.xml'],
+            target_path_pattern: 'res/values-{locale}/strings.xml',
+          },
+        },
+      });
+      fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+    });
+
+    it('translates every form when one and other share the source text', async () => {
+      fs.writeFileSync(
+        sourcePath(),
+        [
+          '<?xml version="1.0" encoding="utf-8"?>',
+          '<resources>',
+          '    <plurals name="fish_count">',
+          '        <item quantity="one">%d fish</item>',
+          '        <item quantity="other">%d fish</item>',
+          '    </plurals>',
+          '</resources>',
+          '',
+        ].join('\n'),
+        'utf-8'
+      );
+
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const result = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(result.success).toBe(true);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('<item quantity="one">[ES] %d fish</item>');
+      // The form that kept the English source: `other` is the primary the
+      // extractor chose, but the value-equality find matched `one` first.
+      expect(written).toContain('<item quantity="other">[ES] %d fish</item>');
+    });
+
+    it('still translates each form separately when the forms differ', async () => {
+      fs.writeFileSync(
+        sourcePath(),
+        [
+          '<?xml version="1.0" encoding="utf-8"?>',
+          '<resources>',
+          '    <plurals name="file_count">',
+          '        <item quantity="one">One file</item>',
+          '        <item quantity="other">%d files</item>',
+          '    </plurals>',
+          '</resources>',
+          '',
+        ].join('\n'),
+        'utf-8'
+      );
+
+      const sent: string[] = [];
+      replyEchoing(sent);
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('<item quantity="one">[ES] One file</item>');
+      expect(written).toContain('<item quantity="other">[ES] %d files</item>');
+    });
+  });
+
+  describe('PO plural', () => {
+    const sourcePath = () => path.join(tmpDir, 'locales', 'en', 'app.po');
+    const targetPath = () => path.join(tmpDir, 'locales', 'es', 'app.po');
+
+    const header = [
+      'msgid ""',
+      'msgstr ""',
+      '"Content-Type: text/plain; charset=UTF-8\\n"',
+      '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"',
+      '',
+      '',
+    ].join('\n');
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-plural-same-'));
+      harness = createSyncHarness({ parsers: ['po'] });
+      writeSyncConfig(tmpDir, {
+        targetLocales: ['es'],
+        buckets: { po: { include: ['locales/en/app.po'] } },
+      });
+      fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+    });
+
+    it('translates msgstr[1] when msgid_plural equals msgid', async () => {
+      fs.writeFileSync(
+        sourcePath(),
+        header +
+          [
+            'msgid "%d fish"',
+            'msgid_plural "%d fish"',
+            'msgstr[0] ""',
+            'msgstr[1] ""',
+            '',
+          ].join('\n'),
+        'utf-8'
+      );
+
+      const sent: string[] = [];
+      replyEchoing(sent);
+      const result = await harness.syncService.sync(
+        await loadSyncConfig(tmpDir)
+      );
+
+      expect(result.success).toBe(true);
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr[0] "[ES] %d fish"');
+      expect(written).toContain('msgstr[1] "[ES] %d fish"');
+    });
+
+    it('still translates both forms when msgid_plural differs from msgid', async () => {
+      fs.writeFileSync(
+        sourcePath(),
+        header +
+          [
+            'msgid "One file"',
+            'msgid_plural "%d files"',
+            'msgstr[0] ""',
+            'msgstr[1] ""',
+            '',
+          ].join('\n'),
+        'utf-8'
+      );
+
+      const sent: string[] = [];
+      replyEchoing(sent);
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+      const written = fs.readFileSync(targetPath(), 'utf-8');
+      expect(written).toContain('msgstr[0] "[ES] One file"');
+      expect(written).toContain('msgstr[1] "[ES] %d files"');
+    });
+  });
+});

From 123529349e956c03e7bbdd372f863d3317b1e57c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:55:45 +0200
Subject: [PATCH 198/256] fix(sync): refuse a bucket whose source files share
 one target path

target_path_pattern need not contain {basename}, so out/{locale}.json
made every source file in a bucket claim one target, and nothing checked
for it. Each file's reconstruct is handed only its own keys and treats
that list as the complete key set, so the files deleted each other's
translations; unwrittenKeys inspects only the string the current file
produced, so the loser was still recorded translated.

Measured across three syncs of a bucket globbing modA/en.json and
modB/en.json: the target alternated between {b1,b2} and {a1,a2}, two more
texts billed per run, success at exit 0 every time.

The collision is now detected at the bucket walk, before any translation
request, and refused with an error naming both files, the shared target
and the locale. Checked against every configured locale, since the
collision is a property of the configuration rather than of one run.

The suggestion does not offer {basename}: it interpolates the source
filename, so it does not separate two files both called en.json in
different directories. Omitting the pattern, or splitting the bucket, are
the remedies that work -- and a test pins that the message says so.

Multi-locale buckets are exempt: each file is its own target.

Refs cli-8zn5.5
---
 CHANGELOG.md                                  |   2 +
 src/sync/sync-bucket-walker.ts                |  72 ++++++-
 ...-target-path-collision.integration.test.ts | 200 ++++++++++++++++++
 3 files changed, 273 insertions(+), 1 deletion(-)
 create mode 100644 tests/integration/sync-target-path-collision.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0e2c1ded..19880b97 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a bucket whose source files resolve to the same target path is refused instead of billing forever for translations it destroys.** `target_path_pattern` need not contain `{basename}`, so `out/{locale}.json` made every source file in a bucket claim one target, and nothing checked for it. Each file's `reconstruct` is handed only its own keys and treats that list as the complete key set, so the files deleted each other's translations; `unwrittenKeys` inspects only the string the current file just produced, so the loser was still recorded `translated`. Measured across three consecutive syncs of a bucket globbing `modA/en.json` and `modB/en.json`: the single target alternated between `{b1,b2}` and `{a1,a2}`, two more texts were billed on every run, and every run reported success at **exit 0** — an unbounded billing loop against a target that can never be complete, which `sync status` and `--frozen` report while prescribing a cure that cannot work. The collision is now detected at the bucket walk, before any translation request, and refused with an error naming both source files, the shared target and the locale. The suggestion deliberately does **not** offer `{basename}` as the fix: it interpolates the source *filename*, so it does not separate two files both called `en.json` in different directories — omitting `target_path_pattern` (per-file locale substitution) or splitting the sources into separate buckets are the remedies that work. Multi-locale (bilingual) buckets are exempt, since each file is its own target.
+
 - **sync**: **a plural key whose source forms coincide no longer keeps source-language text in one of them.** The plural pipeline identified forms by value equality rather than by quantity: `expandPlurals` skipped every Android `<item>` whose value equalled the entry's own — so with two coinciding forms *neither* was expanded and only one was ever translated — and the primary write-back then used `find(p => p.value === diff.value)`, which returns whichever form comes first rather than the `other` form the extractor actually published as `entry.value`. English invariant nouns (fish, sheep, series) and copy-pasted `<item>`s make this ordinary input. Measured on `<item quantity="one">%d fish</item><item quantity="other">%d fish</item>`: `one` got the translation and **`other` shipped the English source**, recorded `translated`. The PO half had the mirror problem — `msgid_plural` was expanded only when it differed from `msgid`, so an invariant-noun entry left `msgstr[1]` untouched (`msgstr[1] ""`, silently untranslated but recorded translated). Both sites now use one shared `primaryPluralItem` rule keyed on quantity (`other`, else the first item), which the Android extractor also uses so the three cannot drift apart, and `msgid_plural` is always expanded — identical texts deduplicate inside `translateBatch`, so this bills nothing extra.
 
 - **po**: **a wrapped (continuation-line) plural form survives a run that only rewrites its entry for a sibling key.** gettext writes any `msgstr[N]` longer than 74 characters as `msgstr[N] ""` followed by continuation lines. `reconstruct` re-emitted the first line of a form it was *keeping* and then swallowed the continuations — the same branch that correctly swallows them for a form it has just replaced, where the whole value has already been re-emitted. Because a carried plural entry deliberately supplies no `plural_forms` metadata (so the file's own forms stand), the reviewed translation collapsed to the empty first line: adding one unrelated key to the source erased a reviewed long plural form, and the entry then became permanently unwritable. Note that `msgfmt --statistics` does **not** reveal this — it reports the catalog as fully translated before and after, because a plural message with a non-empty `msgstr[0]` counts as translated — so the loss is silent even to the format's own tool; the evidence is the emitted bytes and a re-extraction. Continuation lines are now kept for a form being carried and still dropped for a form being replaced.
diff --git a/src/sync/sync-bucket-walker.ts b/src/sync/sync-bucket-walker.ts
index 129cf074..988e6fde 100644
--- a/src/sync/sync-bucket-walker.ts
+++ b/src/sync/sync-bucket-walker.ts
@@ -11,7 +11,7 @@ import {
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncBucketConfig } from './types.js';
 import { resolveSyncLimits } from './types.js';
-import { assertPathWithinRoot } from './sync-utils.js';
+import { assertPathWithinRoot, resolveTargetPath } from './sync-utils.js';
 import { Logger } from '../utils/logger.js';
 import { ValidationError } from '../utils/errors.js';
 
@@ -121,6 +121,67 @@ export interface WalkBucketsOptions {
   fileCache?: BucketFileCache;
 }
 
+/**
+ * Refuse a bucket in which two source files resolve to the same target path.
+ *
+ * `target_path_pattern` need not contain `{basename}`, so `out/{locale}.json`
+ * makes every source file in the bucket claim one target. Each file's
+ * `reconstruct` is handed only its own keys and treats that list as the complete
+ * key set, so the files delete each other's translations; `unwrittenKeys`
+ * inspects only the string the current file produced, so the loser is still
+ * recorded `translated`. Every later run re-translates, re-bills and re-loses the
+ * same keys against a target that can never be complete — measured as a target
+ * alternating between the two files' keys and two more texts billed per run, at
+ * exit 0 throughout. `sync status` and `--frozen` report the incompleteness but
+ * prescribe a cure that cannot succeed.
+ *
+ * Checked against every configured locale, not just the ones a filtered run
+ * would touch: the collision is a property of the configuration. A file whose
+ * target path does not resolve for a locale is left to the run's own
+ * per-locale reporting rather than being turned into a config error here.
+ *
+ * Multi-locale (bilingual) parsers are exempt: they write back to the source
+ * file, so each file is its own target and a collision cannot arise.
+ */
+function assertDistinctTargetPaths(
+  bucket: string,
+  sourceFiles: readonly string[],
+  config: ResolvedSyncConfig,
+  targetPathPattern: string | undefined
+): void {
+  if (sourceFiles.length < 2) return;
+
+  for (const locale of config.target_locales) {
+    const owners = new Map<string, string>();
+    for (const sourceFile of sourceFiles) {
+      const relPath = path.relative(config.projectRoot, sourceFile);
+      let targetRelPath: string;
+      try {
+        targetRelPath = resolveTargetPath(
+          relPath,
+          config.source_locale,
+          locale,
+          targetPathPattern
+        );
+      } catch {
+        continue;
+      }
+      const previous = owners.get(targetRelPath);
+      if (previous !== undefined) {
+        throw new ValidationError(
+          `Bucket "${bucket}": source files "${previous}" and "${relPath}" both resolve to the target path ` +
+            `"${targetRelPath}" for locale "${locale}". Each would overwrite the other's translations, and ` +
+            `every later sync would re-translate and re-bill the keys it had just lost.`,
+          `Remove target_path_pattern so each source file's own path is used ("${previous}" -> its own ` +
+            `${locale} sibling), or split these sources into separate buckets. Note that {basename} is the ` +
+            `source file's name only, so it does not separate files that share a name in different directories.`
+        );
+      }
+      owners.set(targetRelPath, relPath);
+    }
+  }
+}
+
 export async function* walkBuckets(
   config: ResolvedSyncConfig,
   registry: FormatRegistry,
@@ -172,6 +233,15 @@ export async function* walkBuckets(
 
     const isMultiLocale = !!parser.multiLocale;
 
+    if (!isMultiLocale) {
+      assertDistinctTargetPaths(
+        bucket,
+        sourceFiles,
+        config,
+        bucketConfig.target_path_pattern
+      );
+    }
+
     for (const sourceFile of sourceFiles) {
       assertPathWithinRoot(sourceFile, config.projectRoot);
       const cached = opts.fileCache?.get(sourceFile);
diff --git a/tests/integration/sync-target-path-collision.integration.test.ts b/tests/integration/sync-target-path-collision.integration.test.ts
new file mode 100644
index 00000000..302b2ba3
--- /dev/null
+++ b/tests/integration/sync-target-path-collision.integration.test.ts
@@ -0,0 +1,200 @@
+/**
+ * Integration tests for two source files in one bucket that resolve to the same
+ * target path.
+ *
+ * `target_path_pattern` need not contain `{basename}`, so `out/{locale}.json`
+ * makes every source file in a bucket claim one target. Each file's
+ * `reconstruct` is handed only its own keys and treats that list as the complete
+ * key set, so the files delete each other's translations — and `unwrittenKeys`
+ * inspects only the string the current file just produced, so the loser is still
+ * recorded `translated`. Every later run then re-translates, re-bills and
+ * re-loses the same keys against a target that can never be complete.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import { ValidationError } from '../../src/utils/errors';
+
+function replyEchoing(sent: string[]): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .persist()
+    .post('/v2/translate')
+    .reply(200, (_uri, body) => {
+      const texts = new URLSearchParams(body as string).getAll('text');
+      sent.push(...texts);
+      return {
+        translations: texts.map((t) => ({
+          text: `[ES] ${t}`,
+          detected_source_language: 'EN',
+          billed_characters: t.length,
+        })),
+      };
+    });
+}
+
+describe('sync with two source files resolving to one target path', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-target-collide-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    for (const mod of ['modA', 'modB']) {
+      fs.mkdirSync(path.join(tmpDir, mod), { recursive: true });
+    }
+    fs.writeFileSync(
+      path.join(tmpDir, 'modA', 'en.json'),
+      JSON.stringify({ a1: 'Alpha one', a2: 'Alpha two' }, null, 2),
+      'utf-8'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'modB', 'en.json'),
+      JSON.stringify({ b1: 'Beta one', b2: 'Beta two' }, null, 2),
+      'utf-8'
+    );
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  /** A pattern with no `{basename}`: both source files claim `out/es.json`. */
+  function writeCollidingConfig(): void {
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es'],
+      buckets: {
+        json: {
+          include: ['mod*/en.json'],
+          target_path_pattern: 'out/{locale}.json',
+        },
+      },
+    });
+  }
+
+  it('refuses the bucket instead of letting the files overwrite each other', async () => {
+    writeCollidingConfig();
+    const sent: string[] = [];
+    replyEchoing(sent);
+
+    await expect(
+      harness.syncService.sync(await loadSyncConfig(tmpDir))
+    ).rejects.toThrow(ValidationError);
+
+    // Refused before any translation is requested, so nothing is billed and no
+    // half-written target is left behind.
+    expect(sent).toEqual([]);
+    expect(fs.existsSync(path.join(tmpDir, 'out', 'es.json'))).toBe(false);
+  });
+
+  it('names both files, the shared target and a remedy that works', async () => {
+    expect.assertions(5);
+    writeCollidingConfig();
+    replyEchoing([]);
+
+    try {
+      await harness.syncService.sync(await loadSyncConfig(tmpDir));
+    } catch (err) {
+      const error = err as ValidationError;
+      expect(error.message).toContain('modA/en.json');
+      expect(error.message).toContain('modB/en.json');
+      expect(error.message).toContain('out/es.json');
+      expect(error.suggestion).toMatch(/target_path_pattern/);
+      // {basename} is the source filename, so it does NOT separate two files
+      // called en.json in different directories — the message must not offer it
+      // as the fix.
+      expect(error.suggestion).toMatch(/does not separate/);
+    }
+  });
+
+  it('accepts the same sources with no pattern, where each keeps its own path', async () => {
+    // The remedy the error names: locale substitution is per file, so
+    // modA/en.json -> modA/es.json and modB/en.json -> modB/es.json.
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es'],
+      buckets: { json: { include: ['mod*/en.json'] } },
+    });
+    const sent: string[] = [];
+    replyEchoing(sent);
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.success).toBe(true);
+    expect(sent.sort()).toEqual([
+      'Alpha one',
+      'Alpha two',
+      'Beta one',
+      'Beta two',
+    ]);
+
+    const a = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'modA', 'es.json'), 'utf-8')
+    ) as Record<string, string>;
+    const b = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'modB', 'es.json'), 'utf-8')
+    ) as Record<string, string>;
+    expect(Object.keys(a).sort()).toEqual(['a1', 'a2']);
+    expect(Object.keys(b).sort()).toEqual(['b1', 'b2']);
+  });
+
+  it('accepts a pattern where {basename} really does separate the targets', async () => {
+    fs.mkdirSync(path.join(tmpDir, 'src'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'a.en.json'),
+      JSON.stringify({ a1: 'Alpha one' }),
+      'utf-8'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'b.en.json'),
+      JSON.stringify({ b1: 'Beta one' }),
+      'utf-8'
+    );
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['es'],
+      buckets: {
+        json: {
+          include: ['src/*.en.json'],
+          target_path_pattern: 'out/{locale}/{basename}',
+        },
+      },
+    });
+    replyEchoing([]);
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.success).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, 'out', 'es', 'a.en.json'))).toBe(
+      true
+    );
+    expect(fs.existsSync(path.join(tmpDir, 'out', 'es', 'b.en.json'))).toBe(
+      true
+    );
+  });
+
+  it('accepts a single-file bucket whose pattern has no {basename}', async () => {
+    fs.rmSync(path.join(tmpDir, 'modB'), { recursive: true, force: true });
+    writeCollidingConfig();
+    const sent: string[] = [];
+    replyEchoing(sent);
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.success).toBe(true);
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'out', 'es.json'), 'utf-8')
+    ) as Record<string, string>;
+    expect(Object.keys(written).sort()).toEqual(['a1', 'a2']);
+  });
+});

From 4069bf7d6dd2b660b63d6385266889978825561c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 13:59:50 +0200
Subject: [PATCH 199/256] fix(watch): restore an aborted pass's targets rather
 than deleting their backups

SyncService.sync skips its restore-on-signal path for a watch run because
watch mode owns the backup tracker -- but WatchController only ever
unlinked what the tracker held, from both the per-pass finally and
shutdown().

A pass that completes unlinks its own backups and clears the tracker
inside sync, so anything still in the tracker belongs to a pass that
threw, was cancelled, or hit drift, none of which write a lockfile.
Measured with es translating and fr answered 403: es.json was left
holding MT output, its .deepl.bak deleted and no lockfile written, at
exit 0 -- the state COPYFILE_EXCL and the stale sweep exist to prevent.

The tracked backups are now restored, matching plain sync. Each file is
copied back before its backup is removed, so an interrupt mid-restore
leaves the backup rather than nothing, and a backup that cannot be
restored is kept with a warning naming it. Synchronous fs calls because
the shutdown path only guarantees synchronous work.

Refs cli-8zn5.11
---
 CHANGELOG.md                                  |   2 +
 src/cli/commands/sync-command.ts              |  36 +++-
 ...ync-watch-aborted-pass.integration.test.ts | 165 ++++++++++++++++++
 3 files changed, 201 insertions(+), 2 deletions(-)
 create mode 100644 tests/integration/sync-watch-aborted-pass.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 19880b97..852c81ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **a watch pass that fails or is interrupted restores the targets it had already rewritten, instead of deleting their backups.** `SyncService.sync` skips its restore-on-signal path for a watch run, because watch mode owns the backup tracker — but `WatchController` only ever *unlinked* what the tracker held, from both the per-pass `finally` and `shutdown()`. A pass that completes unlinks its own backups and clears the tracker inside `sync`, so anything still in the tracker belongs to a pass that threw, was cancelled, or hit drift, none of which write a lockfile. Measured on a two-locale project where es translated and fr was answered 403: es.json was left holding `MT Beta`, its `.deepl.bak` deleted, no lockfile written, at **exit 0** — the reviewed content gone with no record and no recovery path, which is exactly the state the `COPYFILE_EXCL` guard and the stale-backup sweep were added to prevent. Plain `deepl sync` restores in the same situation, and now so does a watch pass: each file is copied back before its backup is removed, so an interrupt mid-restore leaves the backup rather than nothing, and a backup that cannot be restored is kept with a warning naming it. A pass that completes still removes its backups as before.
+
 - **sync**: **a bucket whose source files resolve to the same target path is refused instead of billing forever for translations it destroys.** `target_path_pattern` need not contain `{basename}`, so `out/{locale}.json` made every source file in a bucket claim one target, and nothing checked for it. Each file's `reconstruct` is handed only its own keys and treats that list as the complete key set, so the files deleted each other's translations; `unwrittenKeys` inspects only the string the current file just produced, so the loser was still recorded `translated`. Measured across three consecutive syncs of a bucket globbing `modA/en.json` and `modB/en.json`: the single target alternated between `{b1,b2}` and `{a1,a2}`, two more texts were billed on every run, and every run reported success at **exit 0** — an unbounded billing loop against a target that can never be complete, which `sync status` and `--frozen` report while prescribing a cure that cannot work. The collision is now detected at the bucket walk, before any translation request, and refused with an error naming both source files, the shared target and the locale. The suggestion deliberately does **not** offer `{basename}` as the fix: it interpolates the source *filename*, so it does not separate two files both called `en.json` in different directories — omitting `target_path_pattern` (per-file locale substitution) or splitting the sources into separate buckets are the remedies that work. Multi-locale (bilingual) buckets are exempt, since each file is its own target.
 
 - **sync**: **a plural key whose source forms coincide no longer keeps source-language text in one of them.** The plural pipeline identified forms by value equality rather than by quantity: `expandPlurals` skipped every Android `<item>` whose value equalled the entry's own — so with two coinciding forms *neither* was expanded and only one was ever translated — and the primary write-back then used `find(p => p.value === diff.value)`, which returns whichever form comes first rather than the `other` form the extractor actually published as `entry.value`. English invariant nouns (fish, sheep, series) and copy-pasted `<item>`s make this ordinary input. Measured on `<item quantity="one">%d fish</item><item quantity="other">%d fish</item>`: `one` got the translation and **`other` shipped the English source**, recorded `translated`. The PO half had the mirror problem — `msgid_plural` was expanded only when it differed from `msgid`, so an invariant-noun entry left `msgstr[1]` untouched (`msgstr[1] ""`, silently untranslated but recorded translated). Both sites now use one shared `primaryPluralItem` rule keyed on quantity (`other`, else the first item), which the Android extractor also uses so the three cannot drift apart, and `msgid_plural` is always expanded — identical texts deduplicate inside `translateBatch`, so this bills nothing extra.
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index ed206b80..050306a2 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -1,4 +1,5 @@
 import * as fsSync from 'fs';
+import * as path from 'path';
 import {
   SyncService,
   type SyncResult,
@@ -17,6 +18,7 @@ import { ExitCode } from '../../utils/exit-codes.js';
 import { LOCK_FILE_NAME } from '../../sync/types.js';
 import {
   sweepStaleBackups as sweepStaleBackupsImpl,
+  BACKUP_SUFFIX,
   DEFAULT_BAK_SWEEP_MAX_AGE_SECONDS,
 } from '../../sync/sync-bak-cleanup.js';
 import { claimGracefulShutdown } from '../../utils/signal-exit.js';
@@ -132,21 +134,51 @@ export function createWatchController(
   const cancellationSignal: CancellationSignal = { cancelled: false };
   const activeBackups = new Set<string>();
 
+  /**
+   * Put back what a pass that did not finish had already overwritten.
+   *
+   * A pass that completes unlinks its own backups inside `SyncService.sync` and
+   * clears this tracker, so anything still here belongs to a pass that threw,
+   * was cancelled, or hit drift — none of which wrote a lockfile. Unlinking
+   * those deleted the only remaining copy of the user's translations and left
+   * the target holding machine output that nothing recorded, at exit 0: a loop
+   * pass that rewrote es.json and then aborted on fr destroyed es.json's
+   * reviewed content. Plain `deepl sync` restores from the signal path for the
+   * same reason; a watch pass is skipped there because it owns this tracker, so
+   * the restore has to happen here.
+   *
+   * Synchronous fs calls on purpose: reached from the shutdown path, where the
+   * deferred exit only guarantees work done synchronously in the handler. Each
+   * file is copied back before its backup is removed, so an interrupt mid-restore
+   * leaves the backup rather than nothing.
+   */
   async function cleanupTrackedBackups(): Promise<void> {
     if (activeBackups.size === 0) return;
+    const restored: string[] = [];
     for (const bakPath of activeBackups) {
+      const targetPath = bakPath.slice(0, -BACKUP_SUFFIX.length);
       try {
-        await fsSync.promises.unlink(bakPath);
+        fsSync.copyFileSync(bakPath, targetPath);
+        fsSync.unlinkSync(bakPath);
+        restored.push(path.relative(deps.projectRoot, targetPath));
       } catch (err) {
         const code = (err as NodeJS.ErrnoException).code;
         if (code !== 'ENOENT') {
+          // Left in place deliberately: it may be the only copy left.
           Logger.warn(
-            `Failed to remove backup ${bakPath}: ${err instanceof Error ? err.message : String(err)}`
+            `Could not restore ${targetPath} from its backup: ${err instanceof Error ? err.message : String(err)}. ` +
+              `${bakPath} holds the content from before this pass.`
           );
         }
       }
     }
     activeBackups.clear();
+    if (restored.length > 0) {
+      Logger.warn(
+        `Pass did not complete — restored ${restored.length} file(s) from backup: ${restored.join(', ')}. ` +
+          'No lockfile was written, so nothing was recorded; the next change re-translates.'
+      );
+    }
   }
 
   async function runOnce(): Promise<void> {
diff --git a/tests/integration/sync-watch-aborted-pass.integration.test.ts b/tests/integration/sync-watch-aborted-pass.integration.test.ts
new file mode 100644
index 00000000..d14c4976
--- /dev/null
+++ b/tests/integration/sync-watch-aborted-pass.integration.test.ts
@@ -0,0 +1,165 @@
+/**
+ * Integration tests for the backups of a watch pass that does not finish.
+ *
+ * A pass that completes unlinks its own backups inside `SyncService.sync` and
+ * clears the tracker, so anything still in the tracker afterwards belongs to a
+ * pass that threw, was cancelled, or hit drift — none of which wrote a lockfile.
+ * `WatchController` unlinked those anyway, so a loop pass that rewrote es.json
+ * and then aborted on fr left es.json holding machine output that nothing
+ * recorded, with the only pre-run copy deleted, at exit 0 — the exact state the
+ * COPYFILE_EXCL guard and the stale-backup sweep exist to prevent. Plain
+ * `deepl sync` restores in the same situation; watch has to as well.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { createWatchController } from '../../src/cli/commands/sync-command';
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { BACKUP_SUFFIX } from '../../src/sync/sync-bak-cleanup';
+import { LOCK_FILE_NAME } from '../../src/sync/types';
+import { createSyncHarness } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+
+const SOURCE = JSON.stringify({ a: 'Alpha', b: 'Beta' }, null, 2) + '\n';
+// A reviewed translation for `a`, and no `b`: the pass has real work to do, so
+// it rewrites the file and takes a backup, while `a` shows what survived.
+const HUMAN_ES = JSON.stringify({ a: 'HUMAN-ES-Alpha' }, null, 2) + '\n';
+const HUMAN_FR = JSON.stringify({ a: 'HUMAN-FR-Alpha' }, null, 2) + '\n';
+
+const CONFIG_YAML = [
+  'version: 1',
+  'source_locale: en',
+  'target_locales:',
+  '  - es',
+  '  - fr',
+  'sync:',
+  '  concurrency: 1',
+  'buckets:',
+  '  json:',
+  '    include:',
+  '      - "locales/en.json"',
+  '',
+].join('\n');
+
+function createStubWatcher(): { close: () => Promise<void> } {
+  return { close: async () => {} };
+}
+
+describe('watch pass that aborts after rewriting a target', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  const esPath = () => path.join(tmpDir, 'locales', 'es.json');
+  const frPath = () => path.join(tmpDir, 'locales', 'fr.json');
+  const esBak = () => esPath() + BACKUP_SUFFIX;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-abort-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    fs.mkdirSync(path.join(tmpDir, 'locales'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, '.deepl-sync.yaml'),
+      CONFIG_YAML,
+      'utf-8'
+    );
+    fs.writeFileSync(path.join(tmpDir, 'locales', 'en.json'), SOURCE, 'utf-8');
+    fs.writeFileSync(esPath(), HUMAN_ES, 'utf-8');
+    fs.writeFileSync(frPath(), HUMAN_FR, 'utf-8');
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  /**
+   * es translates, then fr is answered 403. An auth failure is rethrown out of
+   * the per-locale handler, so `SyncService.sync` rejects and the pass is
+   * abandoned with es.json already rewritten and no lockfile written.
+   */
+  function replyThenFailSecondLocale(): void {
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => {
+        const texts = new URLSearchParams(body as string).getAll('text');
+        return {
+          translations: texts.map((t) => ({
+            text: `MT ${t}`,
+            detected_source_language: 'EN',
+          })),
+        };
+      });
+    nock(DEEPL_FREE_API_URL)
+      .post('/v2/translate')
+      .reply(403, { message: 'Authorization failed' });
+  }
+
+  function makeController(): ReturnType<typeof createWatchController> {
+    return createWatchController({
+      watcher: createStubWatcher(),
+      projectRoot: tmpDir,
+      staleBackupAgeMs: 5 * 60_000,
+      runSync: async (signal, backupTracker) => {
+        await harness.syncService.sync(await loadSyncConfig(tmpDir), {
+          cancellationSignal: signal,
+          backupTracker,
+        });
+      },
+    });
+  }
+
+  it('restores the already-rewritten target instead of deleting its backup', async () => {
+    replyThenFailSecondLocale();
+
+    await makeController().runOnce();
+
+    // Nothing was recorded, so the machine output must not be left in place.
+    expect(fs.existsSync(path.join(tmpDir, LOCK_FILE_NAME))).toBe(false);
+    expect(fs.readFileSync(esPath(), 'utf-8')).toBe(HUMAN_ES);
+    expect(fs.readFileSync(frPath(), 'utf-8')).toBe(HUMAN_FR);
+  });
+
+  it('does not leave the target holding unrecorded output with no backup', async () => {
+    replyThenFailSecondLocale();
+
+    await makeController().runOnce();
+
+    const es = fs.readFileSync(esPath(), 'utf-8');
+    const strandedOutput = es.includes('MT Beta') && !fs.existsSync(esBak());
+    expect(strandedOutput).toBe(false);
+  });
+
+  it('still removes the backups of a pass that completes', async () => {
+    nock(DEEPL_FREE_API_URL)
+      .persist()
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => {
+        const texts = new URLSearchParams(body as string).getAll('text');
+        return {
+          translations: texts.map((t) => ({
+            text: `MT ${t}`,
+            detected_source_language: 'EN',
+          })),
+        };
+      });
+
+    await makeController().runOnce();
+
+    expect(fs.existsSync(esBak())).toBe(false);
+    expect(fs.existsSync(frPath() + BACKUP_SUFFIX)).toBe(false);
+    const es = fs.readFileSync(esPath(), 'utf-8');
+    expect(es).toContain('MT Beta');
+    // The reviewed translation is carried, not overwritten.
+    expect(es).toContain('HUMAN-ES-Alpha');
+    expect(fs.existsSync(path.join(tmpDir, LOCK_FILE_NAME))).toBe(true);
+  });
+});

From a0c2f73cd4a4a36f4478c1de19a207118a9ac30f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:03:13 +0200
Subject: [PATCH 200/256] fix(android): read a single-quoted name or quantity
 attribute
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<string name='greeting'> is well-formed XML, and ATTRS already accepted
either quote for every other attribute, but the name/quantity capture
required a double quote. Such an element was never extracted, never
translated and never reported, so sync status read 100% while the string
shipped in the source language.

All four scanners (<string>, <plurals>, <item quantity=…>,
<string-array>) now capture the delimiter and exclude only the delimiter
in use, so a single-quoted name may also contain a double quote. The
value and attrs groups shift by one, read through attrValue/otherAttrs
accessors rather than positional indices at fifteen sites.

The Android mirror of the XLIFF id gap in 6d7ac8a.

Refs cli-8zn5.18
---
 CHANGELOG.md                           |  2 +
 src/formats/android-xml.ts             | 73 ++++++++++++++------
 tests/unit/formats/android-xml.test.ts | 95 ++++++++++++++++++++++++++
 3 files changed, 149 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 852c81ce..30043840 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **android**: **a single-quoted `name` or `quantity` attribute is no longer invisible.** `<string name='greeting'>` is well-formed XML, and the scanners already accepted either quote for every *other* attribute, but the `name`/`quantity` capture required a double quote. Such an element was never extracted, never translated and never reported — so `sync status` read 100% complete while the string shipped in the source language, with nothing anywhere saying so. All four scanners (`<string>`, `<plurals>`, `<item quantity=…>`, `<string-array>`) now capture the delimiter and exclude only the delimiter in use, which also means a single-quoted name may contain a double quote. The quoting style of each element is preserved on rewrite, and a following attribute (`translatable="true"`) is still not swallowed into the name. This is the Android mirror of the XLIFF `trans-unit id` gap fixed above.
+
 - **watch**: **a watch pass that fails or is interrupted restores the targets it had already rewritten, instead of deleting their backups.** `SyncService.sync` skips its restore-on-signal path for a watch run, because watch mode owns the backup tracker — but `WatchController` only ever *unlinked* what the tracker held, from both the per-pass `finally` and `shutdown()`. A pass that completes unlinks its own backups and clears the tracker inside `sync`, so anything still in the tracker belongs to a pass that threw, was cancelled, or hit drift, none of which write a lockfile. Measured on a two-locale project where es translated and fr was answered 403: es.json was left holding `MT Beta`, its `.deepl.bak` deleted, no lockfile written, at **exit 0** — the reviewed content gone with no record and no recovery path, which is exactly the state the `COPYFILE_EXCL` guard and the stale-backup sweep were added to prevent. Plain `deepl sync` restores in the same situation, and now so does a watch pass: each file is copied back before its backup is removed, so an interrupt mid-restore leaves the backup rather than nothing, and a backup that cannot be restored is kept with a warning naming it. A pass that completes still removes its backups as before.
 
 - **sync**: **a bucket whose source files resolve to the same target path is refused instead of billing forever for translations it destroys.** `target_path_pattern` need not contain `{basename}`, so `out/{locale}.json` made every source file in a bucket claim one target, and nothing checked for it. Each file's `reconstruct` is handed only its own keys and treats that list as the complete key set, so the files deleted each other's translations; `unwrittenKeys` inspects only the string the current file just produced, so the loser was still recorded `translated`. Measured across three consecutive syncs of a bucket globbing `modA/en.json` and `modB/en.json`: the single target alternated between `{b1,b2}` and `{a1,a2}`, two more texts were billed on every run, and every run reported success at **exit 0** — an unbounded billing loop against a target that can never be complete, which `sync status` and `--frozen` report while prescribing a cure that cannot work. The collision is now detected at the bucket walk, before any translation request, and refused with an error naming both source files, the shared target and the locale. The suggestion deliberately does **not** offer `{basename}` as the fix: it interpolates the source *filename*, so it does not separate two files both called `en.json` in different directories — omitting `target_path_pattern` (per-file locale substitution) or splitting the sources into separate buckets are the remedies that work. Multi-locale (bilingual) buckets are exempt, since each file is its own target.
diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index e6babfc2..bd7c1687 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -28,22 +28,34 @@ interface PluralItem {
 const ATTRS = String.raw`((?:\s+[a-zA-Z_:][a-zA-Z0-9_:.-]*=(?:"[^"<]*"|'[^'<]*'))*)`;
 
 const STRING_EL: ElementPattern = {
-  open: new RegExp(String.raw`<string\s+name="([^"<]+)"${ATTRS}>`, 'y'),
+  open: new RegExp(
+    String.raw`<string\s+name=(["\'])((?:(?!\1)[^<])+)\1${ATTRS}>`,
+    'y'
+  ),
   close: /<\/string>/y,
 };
 
 const PLURALS_EL: ElementPattern = {
-  open: new RegExp(String.raw`<plurals\s+name="([^"<]+)"${ATTRS}>`, 'y'),
+  open: new RegExp(
+    String.raw`<plurals\s+name=(["\'])((?:(?!\1)[^<])+)\1${ATTRS}>`,
+    'y'
+  ),
   close: /<\/plurals>/y,
 };
 
 const PLURAL_ITEM_EL: ElementPattern = {
-  open: new RegExp(String.raw`<item\s+quantity="([^"<]+)"${ATTRS}>`, 'y'),
+  open: new RegExp(
+    String.raw`<item\s+quantity=(["\'])((?:(?!\1)[^<])+)\1${ATTRS}>`,
+    'y'
+  ),
   close: /<\/item>/y,
 };
 
 const STRING_ARRAY_EL: ElementPattern = {
-  open: new RegExp(String.raw`<string-array\s+name="([^"<]+)"${ATTRS}>`, 'y'),
+  open: new RegExp(
+    String.raw`<string-array\s+name=(["\'])((?:(?!\1)[^<])+)\1${ATTRS}>`,
+    'y'
+  ),
   close: /<\/string-array>/y,
 };
 
@@ -57,6 +69,25 @@ const RESOURCES_EL: ElementPattern = {
   close: /<\/resources>/y,
 };
 
+/**
+ * The `name` / `quantity` of a scanned element.
+ *
+ * Group 0 is the quote delimiter, captured so the value can exclude only the
+ * delimiter actually in use. Requiring a double quote made
+ * `<string name='greeting'>` — well-formed XML, and already accepted for every
+ * other attribute by ATTRS — invisible: never extracted, never translated and
+ * never reported, so `sync status` read 100% while the string shipped in the
+ * source language.
+ */
+function attrValue(element: ScannedElement): string {
+  return element.groups[1]!;
+}
+
+/** The element's remaining attributes, preserved verbatim on rewrite. */
+function otherAttrs(element: ScannedElement): string {
+  return element.groups[2] ?? '';
+}
+
 const INDENT_STEP = '    ';
 
 // A `<string-array>` element's entries are keyed `<name>.<index>`, so a key
@@ -222,8 +253,8 @@ export class AndroidXmlFormatParser implements FormatParser {
         const arrayName = entry.key.substring(0, lastDot);
         const index = parseInt(entry.key.substring(lastDot + 1), 10);
         arrayNames ??= new Set(
-          scanElements(originalContent, STRING_ARRAY_EL).map(
-            (el) => el.groups[0]!
+          scanElements(originalContent, STRING_ARRAY_EL).map((el) =>
+            attrValue(el)
           )
         );
 
@@ -241,43 +272,43 @@ export class AndroidXmlFormatParser implements FormatParser {
     }
 
     let result = replaceElements(originalContent, STRING_EL, (el) => {
-      const attrs = el.groups[1] ?? '';
+      const attrs = otherAttrs(el);
       if (TRANSLATABLE_FALSE_RE.test(attrs)) {
         return el.text;
       }
-      const translation = translations.get(el.groups[0]!);
+      const translation = translations.get(attrValue(el));
       if (translation === undefined) {
         return null;
       }
       return this.rewriteInner(
         el,
-        this.escapeForReconstruct(el.groups[0]!, el.inner, translation)
+        this.escapeForReconstruct(attrValue(el), el.inner, translation)
       );
     });
 
     result = replaceElements(result, PLURALS_EL, (el) => {
-      const quantityMap = pluralTranslations.get(el.groups[0]!);
+      const quantityMap = pluralTranslations.get(attrValue(el));
       if (!quantityMap) {
         // An entry handed over without per-form translations is one whose
         // plural forms this run did not translate: the element keeps the items
         // it already holds. Only a key absent from the entry list is removed.
-        return translations.has(el.groups[0]!) ? el.text : null;
+        return translations.has(attrValue(el)) ? el.text : null;
       }
       const inner = replaceElements(el.inner, PLURAL_ITEM_EL, (item) => {
-        const translation = quantityMap.get(item.groups[0]!);
+        const translation = quantityMap.get(attrValue(item));
         if (translation === undefined) {
           return item.text;
         }
         return this.rewriteInner(
           item,
-          this.escapeForReconstruct(el.groups[0]!, item.inner, translation)
+          this.escapeForReconstruct(attrValue(el), item.inner, translation)
         );
       });
       return this.rewriteInner(el, inner);
     });
 
     result = replaceElements(result, STRING_ARRAY_EL, (el) => {
-      const indexMap = arrayTranslations.get(el.groups[0]!);
+      const indexMap = arrayTranslations.get(attrValue(el));
       if (!indexMap) {
         return null;
       }
@@ -290,7 +321,7 @@ export class AndroidXmlFormatParser implements FormatParser {
         }
         return this.rewriteInner(
           item,
-          this.escapeForReconstruct(el.groups[0]!, item.inner, translation)
+          this.escapeForReconstruct(attrValue(el), item.inner, translation)
         );
       });
       return this.rewriteInner(el, inner);
@@ -317,7 +348,7 @@ export class AndroidXmlFormatParser implements FormatParser {
     const plurals = scanElements(content, PLURALS_EL);
     const arrays = scanElements(content, STRING_ARRAY_EL);
     const slotted = new Set(
-      [...strings, ...plurals, ...arrays].map((el) => el.groups[0]!)
+      [...strings, ...plurals, ...arrays].map((el) => attrValue(el))
     );
 
     const missingStrings = [...translations].filter(
@@ -372,10 +403,10 @@ export class AndroidXmlFormatParser implements FormatParser {
 
   private extractStrings(content: string, entries: ExtractedEntry[]): void {
     for (const el of scanElements(content, STRING_EL)) {
-      if (TRANSLATABLE_FALSE_RE.test(el.groups[1] ?? '')) {
+      if (TRANSLATABLE_FALSE_RE.test(otherAttrs(el))) {
         continue;
       }
-      entries.push({ key: el.groups[0]!, value: this.decodeValue(el.inner) });
+      entries.push({ key: attrValue(el), value: this.decodeValue(el.inner) });
     }
   }
 
@@ -383,14 +414,14 @@ export class AndroidXmlFormatParser implements FormatParser {
     for (const el of scanElements(content, PLURALS_EL)) {
       const plurals: PluralItem[] = scanElements(el.inner, PLURAL_ITEM_EL).map(
         (item) => ({
-          quantity: item.groups[0]!,
+          quantity: attrValue(item),
           value: this.decodeValue(item.inner),
         })
       );
 
       const defaultItem = primaryPluralItem(plurals);
       entries.push({
-        key: el.groups[0]!,
+        key: attrValue(el),
         value: defaultItem?.value ?? '',
         metadata: { plurals },
       });
@@ -402,7 +433,7 @@ export class AndroidXmlFormatParser implements FormatParser {
     entries: ExtractedEntry[]
   ): void {
     for (const el of scanElements(content, STRING_ARRAY_EL)) {
-      const name = el.groups[0]!;
+      const name = attrValue(el);
       let index = 0;
       for (const item of scanElements(el.inner, ARRAY_ITEM_EL)) {
         entries.push({
diff --git a/tests/unit/formats/android-xml.test.ts b/tests/unit/formats/android-xml.test.ts
index a3d7d7d9..2f139947 100644
--- a/tests/unit/formats/android-xml.test.ts
+++ b/tests/unit/formats/android-xml.test.ts
@@ -513,3 +513,98 @@ describe('android-xml parser', () => {
     });
   });
 });
+
+describe('single-quoted name and quantity attributes', () => {
+  // `<string name='greeting'>` is well-formed XML, and the scanners already
+  // accept either quote for every OTHER attribute — but the name/quantity
+  // capture required a double quote, so such an element was never extracted,
+  // never translated and never reported: `sync status` read 100% while the
+  // string shipped in the source language.
+  const SINGLE_QUOTED = [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    '<resources>',
+    "    <string name='greeting'>Hello</string>",
+    '    <string name="farewell">Goodbye</string>',
+    "    <plurals name='file_count'>",
+    "        <item quantity='one'>One file</item>",
+    '        <item quantity="other">%d files</item>',
+    '    </plurals>',
+    "    <string-array name='menu'>",
+    '        <item>First</item>',
+    '    </string-array>',
+    '</resources>',
+    '',
+  ].join('\n');
+
+  it('extracts a single-quoted string name', () => {
+    const keys = parser.extract(SINGLE_QUOTED).map((e) => e.key);
+    expect(keys).toContain('greeting');
+    expect(keys).toContain('farewell');
+  });
+
+  it('extracts a single-quoted plurals name and its single-quoted quantity', () => {
+    const plural = parser
+      .extract(SINGLE_QUOTED)
+      .find((e) => e.key === 'file_count');
+    expect(plural).toBeDefined();
+    const forms = plural!.metadata?.['plurals'] as Array<{
+      quantity: string;
+      value: string;
+    }>;
+    expect(forms.map((f) => f.quantity)).toEqual(['one', 'other']);
+  });
+
+  it('extracts a single-quoted string-array name', () => {
+    const keys = parser.extract(SINGLE_QUOTED).map((e) => e.key);
+    expect(keys).toContain('menu.0');
+  });
+
+  it('writes a translation back into a single-quoted element', () => {
+    const written = parser.reconstruct(SINGLE_QUOTED, [
+      { key: 'greeting', value: 'Hello', translation: 'Hola' },
+      { key: 'farewell', value: 'Goodbye', translation: 'Adios' },
+      {
+        key: 'file_count',
+        value: '%d files',
+        translation: '%d archivos',
+        metadata: {
+          plurals: [
+            { quantity: 'one', value: 'Un archivo' },
+            { quantity: 'other', value: '%d archivos' },
+          ],
+        },
+      },
+      { key: 'menu.0', value: 'First', translation: 'Primero' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain("<string name='greeting'>Hola</string>");
+    expect(written).toContain('<string name="farewell">Adios</string>');
+    expect(written).toContain("<item quantity='one'>Un archivo</item>");
+    expect(written).toContain('<item quantity="other">%d archivos</item>');
+    expect(written).toContain('<item>Primero</item>');
+  });
+
+  it('keeps a double quote inside a single-quoted name', () => {
+    const keys = parser
+      .extract(
+        [
+          '<resources>',
+          `    <string name='say"hi'>Hello</string>`,
+          '</resources>',
+        ].join('\n')
+      )
+      .map((e) => e.key);
+    expect(keys).toEqual(['say"hi']);
+  });
+
+  it('does not swallow a following attribute into the name', () => {
+    const entries = parser.extract(
+      [
+        '<resources>',
+        '    <string name="greeting" translatable="true">Hello</string>',
+        '</resources>',
+      ].join('\n')
+    );
+    expect(entries.map((e) => e.key)).toEqual(['greeting']);
+  });
+});

From 9ed6b2b01252c344ffa6495b4ce01e0f09970255 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:06:24 +0200
Subject: [PATCH 201/256] fix(toml): quote a new key that is not a bare key

New-key insertion emitted `${leaf} = value` and `[${section}]` unquoted,
so a source key outside TOML's bare-key set produced a document
smol-toml refuses on its next read ("only letter, numbers, dashes and
underscores are allowed in keys"). The unusable-target guard then pins
that locale permanently unreadable -- the run that wrote the file is the
run that broke it, so every later sync refuses the locale it just
created.

Leaf keys and each component of a section header now go through
encodeTomlKey: bare where the character set allows, a quoted key with
basic-string escaping otherwise. A bare key is still written unquoted, so
existing files are unchanged.

Refs cli-8zn5.14
---
 CHANGELOG.md                    |  2 ++
 src/formats/toml.ts             | 28 +++++++++++++++++--
 tests/unit/formats/toml.test.ts | 49 +++++++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 30043840..14a2a297 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **toml**: **a new key outside TOML's bare-key character set is written as a quoted key instead of invalid TOML.** New-key insertion emitted `${leaf} = value` and `[${section}]` with no quoting, so a source key such as `with space` (or one containing a quote) produced a document `smol-toml` refuses on its next read — *"only letter, numbers, dashes and underscores are allowed in keys"*. The unusable-target guard then pins that locale as permanently unreadable, and because the run that wrote the file is the run that broke it, every later sync refuses the locale it just created. Leaf keys and each component of a section header are now emitted bare where the character set allows and as quoted keys (basic-string escaping) otherwise; a bare key is still written unquoted, so existing files are untouched.
+
 - **android**: **a single-quoted `name` or `quantity` attribute is no longer invisible.** `<string name='greeting'>` is well-formed XML, and the scanners already accepted either quote for every *other* attribute, but the `name`/`quantity` capture required a double quote. Such an element was never extracted, never translated and never reported — so `sync status` read 100% complete while the string shipped in the source language, with nothing anywhere saying so. All four scanners (`<string>`, `<plurals>`, `<item quantity=…>`, `<string-array>`) now capture the delimiter and exclude only the delimiter in use, which also means a single-quoted name may contain a double quote. The quoting style of each element is preserved on rewrite, and a following attribute (`translatable="true"`) is still not swallowed into the name. This is the Android mirror of the XLIFF `trans-unit id` gap fixed above.
 
 - **watch**: **a watch pass that fails or is interrupted restores the targets it had already rewritten, instead of deleting their backups.** `SyncService.sync` skips its restore-on-signal path for a watch run, because watch mode owns the backup tracker — but `WatchController` only ever *unlinked* what the tracker held, from both the per-pass `finally` and `shutdown()`. A pass that completes unlinks its own backups and clears the tracker inside `sync`, so anything still in the tracker belongs to a pass that threw, was cancelled, or hit drift, none of which write a lockfile. Measured on a two-locale project where es translated and fr was answered 403: es.json was left holding `MT Beta`, its `.deepl.bak` deleted, no lockfile written, at **exit 0** — the reviewed content gone with no record and no recovery path, which is exactly the state the `COPYFILE_EXCL` guard and the stale-backup sweep were added to prevent. Plain `deepl sync` restores in the same situation, and now so does a watch pass: each file is copied back before its backup is removed, so an interrupt mid-restore leaves the backup rather than nothing, and a backup that cannot be restored is kept with a warning naming it. A pass that completes still removes its backups as before.
diff --git a/src/formats/toml.ts b/src/formats/toml.ts
index 47e53b25..a6d5dd2f 100644
--- a/src/formats/toml.ts
+++ b/src/formats/toml.ts
@@ -229,7 +229,7 @@ export class TomlFormatParser implements FormatParser {
         0,
         ...group.map(
           ({ leaf, entry }) =>
-            `${leaf} = ${encodeTomlString(entry.translation, true)}`
+            `${encodeTomlKey(leaf)} = ${encodeTomlString(entry.translation, true)}`
         )
       );
     }
@@ -238,9 +238,11 @@ export class TomlFormatParser implements FormatParser {
     for (const [section, group] of bySection) {
       if (sectionEnd.has(section)) continue;
       if (out.length > 0 && out[out.length - 1] !== '') out.push('');
-      out.push(`[${section}]`);
+      out.push(`[${encodeTomlSection(section)}]`);
       for (const { leaf, entry } of group) {
-        out.push(`${leaf} = ${encodeTomlString(entry.translation, true)}`);
+        out.push(
+          `${encodeTomlKey(leaf)} = ${encodeTomlString(entry.translation, true)}`
+        );
       }
     }
   }
@@ -275,6 +277,26 @@ function tomlUnicodeEscape(code: number): string {
   return '\\u' + code.toString(16).padStart(4, '0');
 }
 
+const BARE_KEY_RE = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * A key spelled the way TOML requires: bare where the character set allows,
+ * otherwise a quoted key.
+ *
+ * Writing an unquoted `with space` produced a document smol-toml refuses on its
+ * next read, and the unusable-target guard then pins the locale permanently
+ * unreadable — the run that wrote the file is the run that broke it. Quoted keys
+ * take the same escaping as a basic string.
+ */
+function encodeTomlKey(key: string): string {
+  return BARE_KEY_RE.test(key) ? key : encodeTomlString(key, true);
+}
+
+/** A dotted section path with each component quoted as TOML requires. */
+function encodeTomlSection(section: string): string {
+  return section.split('.').map(encodeTomlKey).join('.');
+}
+
 function encodeTomlString(value: string, useDoubleQuote: boolean): string {
   if (!useDoubleQuote) {
     // Literal strings (single-quoted) are raw — no escapes, cannot contain `'`
diff --git a/tests/unit/formats/toml.test.ts b/tests/unit/formats/toml.test.ts
index 8b35b938..714fb401 100644
--- a/tests/unit/formats/toml.test.ts
+++ b/tests/unit/formats/toml.test.ts
@@ -321,3 +321,52 @@ describe('TomlFormatParser', () => {
     });
   });
 });
+
+describe('TomlFormatParser — quoting a new key that is not a bare key', () => {
+  // The new-key insertion wrote `${leaf} = value` with no quoting, so a source
+  // key outside TOML's bare-key set (`with space`, `a.b` as one literal key, a
+  // key holding a quote) produced a file smol-toml refuses on the next read.
+  // The unusable-target guard then pins the locale permanently unreadable: the
+  // run that wrote the file is the run that broke it.
+  const TEMPLATE = ['[greeting]', 'hello = "Hola"', ''].join('\n');
+
+  function roundTrip(key: string, translation: string): string {
+    return parser.reconstruct(TEMPLATE, [
+      { key: 'greeting.hello', value: 'Hello', translation: 'Hola' },
+      { key, value: 'Source', translation },
+    ] as TranslatedEntry[]);
+  }
+
+  it('quotes a leaf key containing a space', () => {
+    const written = roundTrip('greeting.with space', 'Con espacio');
+    expect(() => parser.extract(written)).not.toThrow();
+    expect(parser.extract(written).map((e) => e.key)).toContain(
+      'greeting.with space'
+    );
+  });
+
+  it('quotes a leaf key containing a double quote', () => {
+    const written = roundTrip('greeting.say"hi', 'Hola');
+    expect(() => parser.extract(written)).not.toThrow();
+    const keys = parser.extract(written).map((e) => e.key);
+    expect(keys).toContain('greeting.say"hi');
+  });
+
+  it('quotes a section name that is not a bare key', () => {
+    const written = parser.reconstruct(TEMPLATE, [
+      { key: 'greeting.hello', value: 'Hello', translation: 'Hola' },
+      { key: 'my section.item', value: 'Source', translation: 'Destino' },
+    ] as TranslatedEntry[]);
+
+    expect(() => parser.extract(written)).not.toThrow();
+    expect(parser.extract(written).map((e) => e.key)).toContain(
+      'my section.item'
+    );
+  });
+
+  it('leaves a bare key unquoted', () => {
+    const written = roundTrip('greeting.farewell-2', 'Adios');
+    expect(written).toContain('farewell-2 = ');
+    expect(written).not.toContain('"farewell-2"');
+  });
+});

From 03cdaeed798c8c60060b5b6f92ce66858a003872 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:12:48 +0200
Subject: [PATCH 202/256] fix(toml): translate a quoted key containing a dot in
 place

`"greeting.formal" = "Good day"` is one flat key whose name contains a
dot. extract surfaced it, since TOML.parse yields a property literally
called `greeting.formal`, but ENTRY_LINE_RE excluded quoted keys -- so
reconstruct passed the line through untranslated and appended a new
[greeting] table with a `formal` key. The source's own key kept its
English while the lockfile recorded the key translated and status read
100%.

Quoted key segments are now matched, with the logical dot-path derived
through TOML.parse itself so it agrees with extract by construction
rather than by a second hand-rolled unquoting. The key is rewritten in
place, keeping its original quoting style.

For a key the target does not yet hold, extract records the segment path
so insertion writes the flat quoted key instead of inventing a table.
That metadata is attached only where a segment carries a literal dot:
adding it unconditionally would change computeSourceHash for every TOML
key and mark whole catalogues stale.

TOML also joins JSON, Android XML and Laravel PHP in calling
assertDistinctKeys, so a file holding both `"a.b"` and `[a] b` is refused
rather than having one translation written over the other.

Refs cli-8zn5.15
---
 CHANGELOG.md                    |   2 +
 src/formats/toml.ts             | 105 ++++++++++++++++++++++-----
 tests/unit/formats/toml.test.ts | 124 ++++++++++++++++++++++++++++++++
 3 files changed, 212 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 14a2a297..8786d638 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **toml**: **a quoted key containing a dot is translated in place instead of being turned into a nested table.** `"greeting.formal" = "Good day"` is *one* flat key whose name contains a dot. `extract` surfaced it — `TOML.parse` yields a property literally called `greeting.formal` — but the entry-line regex deliberately excluded quoted keys, so the two halves of the parser disagreed: `reconstruct` passed the line through untranslated and *appended a new `[greeting]` table with a `formal` key*. The source's own key kept its English while the lockfile recorded the key translated and `sync status` read 100%. Quoted key segments (basic and literal strings) are now matched, with the logical dot-path derived through `TOML.parse` itself so it agrees with `extract` by construction rather than by a second hand-rolled unquoting; the key is rewritten in place, keeping its original quoting style. For a key the target file does not yet have, `extract` records the segment path so insertion writes `"greeting.formal" = …` (or `"a.b" = …` inside its real table) rather than inventing a table — attached **only** where a segment carries a literal dot, so `computeSourceHash` and therefore staleness are unchanged for every other TOML key. Finally, TOML now uses `assertDistinctKeys` like JSON, Android XML and Laravel PHP: a file holding both `"a.b" = …` and `[a] b = …` is one key for two strings, and is refused rather than having one translation written over the other.
+
 - **toml**: **a new key outside TOML's bare-key character set is written as a quoted key instead of invalid TOML.** New-key insertion emitted `${leaf} = value` and `[${section}]` with no quoting, so a source key such as `with space` (or one containing a quote) produced a document `smol-toml` refuses on its next read — *"only letter, numbers, dashes and underscores are allowed in keys"*. The unusable-target guard then pins that locale as permanently unreadable, and because the run that wrote the file is the run that broke it, every later sync refuses the locale it just created. Leaf keys and each component of a section header are now emitted bare where the character set allows and as quoted keys (basic-string escaping) otherwise; a bare key is still written unquoted, so existing files are untouched.
 
 - **android**: **a single-quoted `name` or `quantity` attribute is no longer invisible.** `<string name='greeting'>` is well-formed XML, and the scanners already accepted either quote for every *other* attribute, but the `name`/`quantity` capture required a double quote. Such an element was never extracted, never translated and never reported — so `sync status` read 100% complete while the string shipped in the source language, with nothing anywhere saying so. All four scanners (`<string>`, `<plurals>`, `<item quantity=…>`, `<string-array>`) now capture the delimiter and exclude only the delimiter in use, which also means a single-quoted name may contain a double quote. The quoting style of each element is preserved on rewrite, and a following attribute (`translatable="true"`) is still not swallowed into the name. This is the Android mirror of the XLIFF `trans-unit id` gap fixed above.
diff --git a/src/formats/toml.ts b/src/formats/toml.ts
index a6d5dd2f..ba8c4ed8 100644
--- a/src/formats/toml.ts
+++ b/src/formats/toml.ts
@@ -1,8 +1,9 @@
 import * as TOML from 'smol-toml';
-import type {
-  ExtractedEntry,
-  FormatParser,
-  TranslatedEntry,
+import {
+  assertDistinctKeys,
+  type ExtractedEntry,
+  type FormatParser,
+  type TranslatedEntry,
 } from './format.js';
 import { PendingCommentBuffer } from './pending-comment-buffer.js';
 import {
@@ -20,14 +21,52 @@ const SECTION_RE = /^\[([^[\]]+)\]\s*(?:#.*)?$/;
 // anyway, so no surgery is needed).
 const ARRAY_OF_TABLES_RE = /^\[\[([^[\]]+)\]\]\s*(?:#.*)?$/;
 
+// One segment of a key: bare, a basic string, or a literal string.
+const KEY_SEGMENT = String.raw`(?:[A-Za-z0-9_-]+|"(?:[^"\\]|\\.)*"|'[^']*')`;
+
 // `key = value[...]` — captures:
 //   1 indent
-//   2 key (bare or dotted bare; quoted keys deliberately excluded — they are
-//     rare in i18n TOML and would require careful dot-path round-tripping)
+//   2 key (dotted, each segment bare or quoted)
 //   3 `=` + surrounding whitespace
 //   4 rest of line (value + optional trailing whitespace + optional `#`)
-const ENTRY_LINE_RE =
-  /^(\s*)([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)(\s*=\s*)(.*)$/;
+//
+// Quoted key segments are included because `extract` surfaces them: TOML.parse
+// turns `"greeting.formal" = "…"` into a property literally called
+// `greeting.formal`, so the sync pipeline treats it as translatable. Excluding
+// them here made the two halves disagree — reconstruct passed the line through
+// untranslated and then appended a NEW nested `[greeting] formal` entry, so the
+// key the source actually has kept its source-language text while the lockfile
+// recorded it translated.
+const ENTRY_LINE_RE = new RegExp(
+  String.raw`^(\s*)(${KEY_SEGMENT}(?:\s*\.\s*${KEY_SEGMENT})*)(\s*=\s*)(.*)$`
+);
+
+/**
+ * The logical dot-path a written key denotes, with quoted segments decoded.
+ *
+ * Derived through `TOML.parse` for a key that contains a quote, so it agrees
+ * with `extract` — which reads the same document through the same parser — by
+ * construction rather than by a second hand-rolled unquoting. A key with no
+ * quote is its own path, which keeps the common case off the parser.
+ */
+function logicalKeyPath(keyPart: string): string {
+  if (!keyPart.includes('"') && !keyPart.includes("'")) {
+    return keyPart.replace(/\s*\.\s*/g, '.');
+  }
+  try {
+    const path: string[] = [];
+    let node: unknown = TOML.parse(`${keyPart} = 0`);
+    while (node !== null && typeof node === 'object' && !Array.isArray(node)) {
+      const names = Object.keys(node);
+      if (names.length !== 1) break;
+      path.push(names[0]!);
+      node = (node as Record<string, unknown>)[names[0]!];
+    }
+    return path.join('.');
+  } catch {
+    return keyPart;
+  }
+}
 
 // String-literal prefix of an entry's RHS. Captures:
 //   1 the quoted literal (including quotes)
@@ -48,7 +87,11 @@ export class TomlFormatParser implements FormatParser {
     if (!content.trim()) return [];
     const data = TOML.parse(content);
     const entries: ExtractedEntry[] = [];
-    this.walk(data, '', entries);
+    this.walk(data, '', entries, []);
+    // A literal '.' inside a key is indistinguishable from the separator between
+    // levels, so `"a.b" = …` and `[a] b = …` produce one key for two strings and
+    // one translation would be written over the other.
+    assertDistinctKeys(entries, 'TOML', '.');
     return entries;
   }
 
@@ -120,15 +163,15 @@ export class TomlFormatParser implements FormatParser {
             }
           }
           const multilineKey = currentSection
-            ? `${currentSection}.${keyPart}`
-            : keyPart;
+            ? `${currentSection}.${logicalKeyPath(keyPart)}`
+            : logicalKeyPath(keyPart);
           usedKeys.add(multilineKey);
           continue;
         }
 
         const fullKey = currentSection
-          ? `${currentSection}.${keyPart}`
-          : keyPart;
+          ? `${currentSection}.${logicalKeyPath(keyPart)}`
+          : logicalKeyPath(keyPart);
         const stringMatch = valuePart.match(STRING_VALUE_RE);
 
         if (stringMatch) {
@@ -209,9 +252,21 @@ export class TomlFormatParser implements FormatParser {
       { leaf: string; entry: TranslatedEntry }[]
     >();
     for (const entry of newEntries) {
-      const lastDot = entry.key.lastIndexOf('.');
-      const section = lastDot === -1 ? '' : entry.key.slice(0, lastDot);
-      const leaf = lastDot === -1 ? entry.key : entry.key.slice(lastDot + 1);
+      const recordedPath = entry.metadata?.['toml_key_path'];
+      let section: string;
+      let leaf: string;
+      if (Array.isArray(recordedPath) && recordedPath.length > 0) {
+        const segments = recordedPath as string[];
+        section = segments
+          .slice(0, -1)
+          .map((segment) => encodeTomlKey(segment))
+          .join('.');
+        leaf = segments[segments.length - 1]!;
+      } else {
+        const lastDot = entry.key.lastIndexOf('.');
+        section = lastDot === -1 ? '' : entry.key.slice(0, lastDot);
+        leaf = lastDot === -1 ? entry.key : entry.key.slice(lastDot + 1);
+      }
       const group = bySection.get(section);
       if (group) group.push({ leaf, entry });
       else bySection.set(section, [{ leaf, entry }]);
@@ -250,19 +305,31 @@ export class TomlFormatParser implements FormatParser {
   private walk(
     obj: Record<string, unknown>,
     prefix: string,
-    entries: ExtractedEntry[]
+    entries: ExtractedEntry[],
+    path: readonly string[]
   ): void {
     for (const [prop, val] of Object.entries(obj)) {
       const key = prefix ? `${prefix}.${prop}` : prop;
+      const propPath = [...path, prop];
       if (typeof val === 'string') {
-        entries.push({ key, value: val });
+        // `toml_key_path` is attached ONLY when a segment carries a literal dot,
+        // where the key string alone cannot say which dots are structural. New-key
+        // insertion needs that to write `"greeting.formal" = …` rather than
+        // inventing a `[greeting] formal` table the source does not have. Adding
+        // it unconditionally would change `computeSourceHash` for every TOML key
+        // and mark whole catalogues stale.
+        entries.push(
+          propPath.some((segment) => segment.includes('.'))
+            ? { key, value: val, metadata: { toml_key_path: propPath } }
+            : { key, value: val }
+        );
       } else if (
         typeof val === 'object' &&
         val !== null &&
         !Array.isArray(val) &&
         !(val instanceof Date)
       ) {
-        this.walk(val as Record<string, unknown>, key, entries);
+        this.walk(val as Record<string, unknown>, key, entries, propPath);
       }
     }
   }
diff --git a/tests/unit/formats/toml.test.ts b/tests/unit/formats/toml.test.ts
index 714fb401..12e135a6 100644
--- a/tests/unit/formats/toml.test.ts
+++ b/tests/unit/formats/toml.test.ts
@@ -370,3 +370,127 @@ describe('TomlFormatParser — quoting a new key that is not a bare key', () =>
     expect(written).not.toContain('"farewell-2"');
   });
 });
+
+describe('TomlFormatParser — a quoted key containing a dot', () => {
+  // `"greeting.formal" = "Good day"` is ONE flat key whose name contains a dot.
+  // `extract` surfaced it (TOML.parse yields a property called `greeting.formal`)
+  // but ENTRY_LINE_RE excluded quoted keys, so reconstruct passed the line
+  // through untouched and instead wrote a NEW nested `[greeting] formal` entry.
+  // The source's own key kept its English while the lockfile recorded the key
+  // translated and status read 100%.
+  const FLAT = ['"greeting.formal" = "Good day"', ''].join('\n');
+
+  it('extracts the flat key, recording that its dot is literal', () => {
+    expect(parser.extract(FLAT)).toEqual([
+      {
+        key: 'greeting.formal',
+        value: 'Good day',
+        metadata: { toml_key_path: ['greeting.formal'] },
+      },
+    ]);
+  });
+
+  it('writes the translation into the quoted key itself', () => {
+    const written = parser.reconstruct(FLAT, [
+      { key: 'greeting.formal', value: 'Good day', translation: 'Buen día' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('"greeting.formal" = "Buen día"');
+    expect(written).not.toContain('[greeting]');
+    const reread = parser.extract(written);
+    expect(reread.map((e) => [e.key, e.value])).toEqual([
+      ['greeting.formal', 'Buen día'],
+    ]);
+  });
+
+  it('leaves a genuinely nested key nested', () => {
+    const nested = ['[greeting]', 'formal = "Good day"', ''].join('\n');
+    const written = parser.reconstruct(nested, [
+      { key: 'greeting.formal', value: 'Good day', translation: 'Buen día' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('[greeting]');
+    expect(written).toContain('formal = "Buen día"');
+  });
+
+  it('refuses a file where a flat quoted key collides with a nested one', () => {
+    const ambiguous = [
+      '"greeting.formal" = "Good day"',
+      '[greeting]',
+      'formal = "Hello"',
+      '',
+    ].join('\n');
+
+    expect(() => parser.extract(ambiguous)).toThrow(
+      /two different strings|key of two/i
+    );
+  });
+
+  it('handles a single-quoted (literal) key containing a dot', () => {
+    const literal = ['\'greeting.casual\' = "Hi"', ''].join('\n');
+    const written = parser.reconstruct(literal, [
+      { key: 'greeting.casual', value: 'Hi', translation: 'Hola' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('\'greeting.casual\' = "Hola"');
+  });
+});
+
+describe('TomlFormatParser — inserting a NEW key whose dot is literal', () => {
+  // The template has no line for the key, so the insertion path runs. Splitting
+  // at the last dot would invent a `[greeting]` table and leave the source's
+  // own `"greeting.formal"` key absent from the target.
+  it('writes a new flat quoted key at the top level', () => {
+    const template = ['other = "Otro"', ''].join('\n');
+    const written = parser.reconstruct(template, [
+      { key: 'other', value: 'Other', translation: 'Otro' },
+      {
+        key: 'greeting.formal',
+        value: 'Good day',
+        translation: 'Buen día',
+        metadata: { toml_key_path: ['greeting.formal'] },
+      },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('"greeting.formal" = "Buen día"');
+    expect(written).not.toContain('[greeting]');
+    expect(
+      parser
+        .extract(written)
+        .map((e) => e.key)
+        .sort()
+    ).toEqual(['greeting.formal', 'other']);
+  });
+
+  it('writes a new flat key inside its real table', () => {
+    const template = ['[greeting]', 'hello = "Hola"', ''].join('\n');
+    const written = parser.reconstruct(template, [
+      { key: 'greeting.hello', value: 'Hello', translation: 'Hola' },
+      {
+        key: 'greeting.a.b',
+        value: 'Source',
+        translation: 'Destino',
+        metadata: { toml_key_path: ['greeting', 'a.b'] },
+      },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('"a.b" = "Destino"');
+    expect(
+      parser
+        .extract(written)
+        .map((e) => e.key)
+        .sort()
+    ).toEqual(['greeting.a.b', 'greeting.hello']);
+  });
+
+  it('still nests a new key whose dots are structural', () => {
+    const template = ['other = "Otro"', ''].join('\n');
+    const written = parser.reconstruct(template, [
+      { key: 'other', value: 'Other', translation: 'Otro' },
+      { key: 'greeting.formal', value: 'Good day', translation: 'Buen día' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('[greeting]');
+    expect(written).toContain('formal = "Buen día"');
+  });
+});

From c02c5c1d83b8ea2f140bb25c8c99a8f1f75d8b4e Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:15:53 +0200
Subject: [PATCH 203/256] fix(po): decode an escaped carriage return

quote escaped CR to \r, but unquote's escape set was \\ " n t with no r
case, so reading a catalog back turned \r into a literal backslash + 'r'.
The next run escaped that backslash in turn, so a carried entry's CR
became \\r, then \\\\r, gaining a backslash on every run. msgfmt flags
neither spelling.

unquote now decodes \r, making the two halves symmetric. A test
reconstructs twice and requires the second output to be byte-identical to
the first, so the asymmetry cannot come back unnoticed.

Refs cli-8zn5.16
---
 CHANGELOG.md                  |  2 ++
 src/formats/po.ts             | 40 +++++++++++++++++------------
 tests/unit/formats/po.test.ts | 48 +++++++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8786d638..ac5d2598 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **po**: **an escaped carriage return survives a round trip instead of growing a backslash on every run.** `quote` escaped CR to `\r`, but `unquote`'s escape set was `\\ " n t` with no `r` case — so reading a catalog back turned `\r` into a literal backslash followed by `r`. The next run then escaped *that* backslash, so a carried entry's CR became `\\r`, then `\\\\r`, gaining a backslash indefinitely. `msgfmt` flags neither spelling, so nothing reported it. `unquote` now decodes `\r`, which makes the two halves symmetric and the round trip idempotent — asserted by reconstructing twice and requiring the second output to be byte-identical to the first.
+
 - **toml**: **a quoted key containing a dot is translated in place instead of being turned into a nested table.** `"greeting.formal" = "Good day"` is *one* flat key whose name contains a dot. `extract` surfaced it — `TOML.parse` yields a property literally called `greeting.formal` — but the entry-line regex deliberately excluded quoted keys, so the two halves of the parser disagreed: `reconstruct` passed the line through untranslated and *appended a new `[greeting]` table with a `formal` key*. The source's own key kept its English while the lockfile recorded the key translated and `sync status` read 100%. Quoted key segments (basic and literal strings) are now matched, with the logical dot-path derived through `TOML.parse` itself so it agrees with `extract` by construction rather than by a second hand-rolled unquoting; the key is rewritten in place, keeping its original quoting style. For a key the target file does not yet have, `extract` records the segment path so insertion writes `"greeting.formal" = …` (or `"a.b" = …` inside its real table) rather than inventing a table — attached **only** where a segment carries a literal dot, so `computeSourceHash` and therefore staleness are unchanged for every other TOML key. Finally, TOML now uses `assertDistinctKeys` like JSON, Android XML and Laravel PHP: a file holding both `"a.b" = …` and `[a] b = …` is one key for two strings, and is refused rather than having one translation written over the other.
 
 - **toml**: **a new key outside TOML's bare-key character set is written as a quoted key instead of invalid TOML.** New-key insertion emitted `${leaf} = value` and `[${section}]` with no quoting, so a source key such as `with space` (or one containing a quote) produced a document `smol-toml` refuses on its next read — *"only letter, numbers, dashes and underscores are allowed in keys"*. The unusable-target guard then pins that locale as permanently unreadable, and because the run that wrote the file is the run that broke it, every later sync refuses the locale it just created. Leaf keys and each component of a section header are now emitted bare where the character set allows and as quoted keys (basic-string escaping) otherwise; a bare key is still written unquoted, so existing files are untouched.
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 0afb4416..2d6c8f40 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -30,22 +30,30 @@ type ParseTarget =
 function unquote(line: string): string {
   const trimmed = line.trim();
   if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
-    return trimmed
-      .slice(1, -1)
-      .replace(/\\(\\|"|n|t)/g, (_match, ch: string) => {
-        switch (ch) {
-          case '\\':
-            return '\\';
-          case '"':
-            return '"';
-          case 'n':
-            return '\n';
-          case 't':
-            return '\t';
-          default:
-            return ch;
-        }
-      });
+    return (
+      trimmed
+        .slice(1, -1)
+        // `r` is here because `quote` writes it: without it an escaped CR read
+        // back as a literal backslash + 'r', whose backslash the next `quote`
+        // escaped in turn, so a carried entry grew a backslash on every run.
+        // msgfmt flags neither spelling.
+        .replace(/\\(\\|"|n|t|r)/g, (_match, ch: string) => {
+          switch (ch) {
+            case '\\':
+              return '\\';
+            case '"':
+              return '"';
+            case 'n':
+              return '\n';
+            case 't':
+              return '\t';
+            case 'r':
+              return '\r';
+            default:
+              return ch;
+          }
+        })
+    );
   }
   return trimmed;
 }
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index e18d7dee..05f7e469 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -885,3 +885,51 @@ describe('PoFormatParser — carrying a wrapped plural form forward', () => {
     expect(written).not.toContain(LONG_ES);
   });
 });
+
+describe('PoFormatParser — carriage returns round-trip', () => {
+  // `quote` escapes CR to `\r`, but `unquote` had no `r` case, so reading the
+  // file back produced a literal backslash + 'r'. The next run then escaped that
+  // backslash, so a carried entry's CR became `\\r` and grew a backslash on
+  // every subsequent run. msgfmt cannot flag it: both spellings are valid.
+  const parser = new PoFormatParser();
+  const HEADER = [
+    'msgid ""',
+    'msgstr ""',
+    '"Content-Type: text/plain; charset=UTF-8\\n"',
+    '',
+    '',
+  ].join('\n');
+
+  const WITH_CR = HEADER + ['msgid "Hi"', 'msgstr "a\\rb"', ''].join('\n');
+
+  it('decodes an escaped CR back to a carriage return', () => {
+    expect(parser.extractTranslations(WITH_CR).get('Hi')).toBe('a\rb');
+  });
+
+  it('is idempotent across runs rather than growing a backslash', () => {
+    const first = parser.reconstruct(WITH_CR, [
+      {
+        key: 'Hi',
+        value: 'Hi',
+        translation: parser.extractTranslations(WITH_CR).get('Hi')!,
+      },
+    ]);
+    expect(first).toContain('msgstr "a\\rb"');
+
+    const second = parser.reconstruct(first, [
+      {
+        key: 'Hi',
+        value: 'Hi',
+        translation: parser.extractTranslations(first).get('Hi')!,
+      },
+    ]);
+    expect(second).toBe(first);
+    expect(parser.extractTranslations(second).get('Hi')).toBe('a\rb');
+  });
+
+  it('still decodes the escapes it already handled', () => {
+    const mixed =
+      HEADER + ['msgid "K"', 'msgstr "n\\nt\\tq\\"b\\\\end"', ''].join('\n');
+    expect(parser.extractTranslations(mixed).get('K')).toBe('n\nt\tq"b\\end');
+  });
+});

From 58164006fe2f45f7f4ca2afb161c76fd2033fda9 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:18:32 +0200
Subject: [PATCH 204/256] fix(po): concatenate adjacent string literals on one
 line

`msgstr "Hola " "mundo"` is valid gettext for `Hola mundo` -- literals
join C-style. unquote tested only that the value started and ended with a
quote and sliced, so it read the inner `" "` as content, and the next
write escaped those quotes: the translation became `Hola \" \"mundo`
permanently. msgfmt -c accepts both forms, so nothing flagged it.

Values are now read as a run of literals. Cross-checked against gettext:
msgunfmt reports `Hola mundo` for the same catalog, and so does the
parser now. Applies to msgid and msgctxt as well as msgstr.

A quote that is genuinely content still decodes as content, a plain
single literal is unchanged, and a malformed value (unterminated quote) is
returned untouched rather than mangled.

Refs cli-8zn5.20
---
 CHANGELOG.md                  |  2 +
 src/formats/po.ts             | 91 +++++++++++++++++++++++++----------
 tests/unit/formats/po.test.ts | 57 ++++++++++++++++++++++
 3 files changed, 124 insertions(+), 26 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ac5d2598..a3f7be4f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **po**: **adjacent string literals on one line are concatenated, as gettext defines them.** `msgstr "Hola " "mundo"` is valid gettext for the string `Hola mundo` — literals join C-style. `unquote` tested only that the value started and ended with a quote and then sliced, so it read the inner `" "` as *content*; the next write escaped those quotes, turning the translation into `Hola \" \"mundo` permanently. `msgfmt -c` accepts both forms, so nothing flagged it. Values are now read as a run of literals, matching `msgunfmt`'s own answer for the same catalog (verified: `msgunfmt` reports `Hola mundo`, and so does the parser). Applies to `msgid` and `msgctxt` as well as `msgstr`. A quote that is genuinely part of the string (`"say \" here"`) still decodes as content, a plain single literal is unaffected, and a malformed value (unterminated quote) is returned untouched rather than mangled.
+
 - **po**: **an escaped carriage return survives a round trip instead of growing a backslash on every run.** `quote` escaped CR to `\r`, but `unquote`'s escape set was `\\ " n t` with no `r` case — so reading a catalog back turned `\r` into a literal backslash followed by `r`. The next run then escaped *that* backslash, so a carried entry's CR became `\\r`, then `\\\\r`, gaining a backslash indefinitely. `msgfmt` flags neither spelling, so nothing reported it. `unquote` now decodes `\r`, which makes the two halves symmetric and the round trip idempotent — asserted by reconstructing twice and requiring the second output to be byte-identical to the first.
 
 - **toml**: **a quoted key containing a dot is translated in place instead of being turned into a nested table.** `"greeting.formal" = "Good day"` is *one* flat key whose name contains a dot. `extract` surfaced it — `TOML.parse` yields a property literally called `greeting.formal` — but the entry-line regex deliberately excluded quoted keys, so the two halves of the parser disagreed: `reconstruct` passed the line through untranslated and *appended a new `[greeting]` table with a `formal` key*. The source's own key kept its English while the lockfile recorded the key translated and `sync status` read 100%. Quoted key segments (basic and literal strings) are now matched, with the logical dot-path derived through `TOML.parse` itself so it agrees with `extract` by construction rather than by a second hand-rolled unquoting; the key is rewritten in place, keeping its original quoting style. For a key the target file does not yet have, `extract` records the segment path so insertion writes `"greeting.formal" = …` (or `"a.b" = …` inside its real table) rather than inventing a table — attached **only** where a segment carries a literal dot, so `computeSourceHash` and therefore staleness are unchanged for every other TOML key. Finally, TOML now uses `assertDistinctKeys` like JSON, Android XML and Laravel PHP: a file holding both `"a.b" = …` and `[a] b = …` is one key for two strings, and is refused rather than having one translation written over the other.
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 2d6c8f40..869a6375 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -27,35 +27,74 @@ interface PoEntry {
 type ParseTarget =
   'msgctxt' | 'msgid' | 'msgid_plural' | 'msgstr' | `msgstr[${number}]`;
 
+/**
+ * One PO escape sequence, decoded.
+ *
+ * `r` is in the set because `quote` writes it: without it an escaped CR read
+ * back as a literal backslash + 'r', whose backslash the next `quote` escaped in
+ * turn, so a carried entry grew a backslash on every run. msgfmt flags neither
+ * spelling.
+ */
+function unescapePoChar(ch: string): string {
+  switch (ch) {
+    case '\\':
+      return '\\';
+    case '"':
+      return '"';
+    case 'n':
+      return '\n';
+    case 't':
+      return '\t';
+    case 'r':
+      return '\r';
+    default:
+      return ch;
+  }
+}
+
+/**
+ * The string a PO value expresses, decoding escapes and concatenating adjacent
+ * literals.
+ *
+ * gettext joins adjacent string literals C-style, so `msgstr "Hola " "mundo"` is
+ * `Hola mundo`. Testing only that the value starts and ends with a quote and
+ * slicing read the inner `" "` as content, and the next write escaped those
+ * quotes — corrupting the string permanently, with `msgfmt -c` unable to flag it
+ * because both forms are well-formed.
+ *
+ * A value that is not a well-formed run of literals (an unterminated quote, or
+ * anything else between literals) is returned trimmed and untouched, which is
+ * what the previous single-literal test did for input it did not recognise.
+ */
 function unquote(line: string): string {
   const trimmed = line.trim();
-  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
-    return (
-      trimmed
-        .slice(1, -1)
-        // `r` is here because `quote` writes it: without it an escaped CR read
-        // back as a literal backslash + 'r', whose backslash the next `quote`
-        // escaped in turn, so a carried entry grew a backslash on every run.
-        // msgfmt flags neither spelling.
-        .replace(/\\(\\|"|n|t|r)/g, (_match, ch: string) => {
-          switch (ch) {
-            case '\\':
-              return '\\';
-            case '"':
-              return '"';
-            case 'n':
-              return '\n';
-            case 't':
-              return '\t';
-            case 'r':
-              return '\r';
-            default:
-              return ch;
-          }
-        })
-    );
+  if (!trimmed.startsWith('"')) return trimmed;
+
+  let result = '';
+  let i = 0;
+  while (i < trimmed.length) {
+    if (trimmed[i] !== '"') return trimmed;
+    i++;
+    let closed = false;
+    while (i < trimmed.length) {
+      const ch = trimmed[i]!;
+      if (ch === '\\' && i + 1 < trimmed.length) {
+        result += unescapePoChar(trimmed[i + 1]!);
+        i += 2;
+        continue;
+      }
+      if (ch === '"') {
+        closed = true;
+        i++;
+        break;
+      }
+      result += ch;
+      i++;
+    }
+    if (!closed) return trimmed;
+    while (i < trimmed.length && /\s/.test(trimmed[i]!)) i++;
   }
-  return trimmed;
+  return result;
 }
 
 function quote(value: string): string {
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index 05f7e469..a9dd1351 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -933,3 +933,60 @@ describe('PoFormatParser — carriage returns round-trip', () => {
     expect(parser.extractTranslations(mixed).get('K')).toBe('n\nt\tq"b\\end');
   });
 });
+
+describe('PoFormatParser — adjacent string literals on one line', () => {
+  // gettext concatenates adjacent literals C-style, so `msgstr "Hola " "mundo"`
+  // is the string `Hola mundo`. unquote tested only that the value starts and
+  // ends with a quote and sliced, reading the inner `" "` as content — then
+  // rewrote it with the quotes escaped, so the string became `Hola \" \"mundo`
+  // permanently. msgfmt -c cannot flag it: both forms are well-formed.
+  const parser = new PoFormatParser();
+  const HEADER = [
+    'msgid ""',
+    'msgstr ""',
+    '"Content-Type: text/plain; charset=UTF-8\\n"',
+    '',
+    '',
+  ].join('\n');
+
+  it('concatenates adjacent literals in a msgstr', () => {
+    const po =
+      HEADER + ['msgid "Hello"', 'msgstr "Hola " "mundo"', ''].join('\n');
+    expect(parser.extractTranslations(po).get('Hello')).toBe('Hola mundo');
+  });
+
+  it('concatenates adjacent literals in a msgid', () => {
+    const po =
+      HEADER + ['msgid "Good " "day"', 'msgstr "Buen día"', ''].join('\n');
+    expect(parser.extract(po).map((e) => e.key)).toEqual(['Good day']);
+  });
+
+  it('does not re-escape the joint when rewriting the entry', () => {
+    const po =
+      HEADER + ['msgid "Hello"', 'msgstr "Hola " "mundo"', ''].join('\n');
+    const written = parser.reconstruct(po, [
+      {
+        key: 'Hello',
+        value: 'Hello',
+        translation: parser.extractTranslations(po).get('Hello')!,
+      },
+    ]);
+    expect(written).toContain('msgstr "Hola mundo"');
+    expect(written).not.toContain('\\"');
+  });
+
+  it('keeps a quote that is genuinely part of the string', () => {
+    const po = HEADER + ['msgid "Q"', 'msgstr "say \\" here"', ''].join('\n');
+    expect(parser.extractTranslations(po).get('Q')).toBe('say " here');
+  });
+
+  it('still reads a plain single literal', () => {
+    const po = HEADER + ['msgid "Hello"', 'msgstr "Hola"', ''].join('\n');
+    expect(parser.extractTranslations(po).get('Hello')).toBe('Hola');
+  });
+
+  it('leaves an unterminated literal alone rather than mangling it', () => {
+    const po = HEADER + ['msgid "Hello"', 'msgstr "Hola', ''].join('\n');
+    expect(() => parser.extractTranslations(po)).not.toThrow();
+  });
+});

From 7093cd3f811536cc7bb576f39453cfe2a3558433 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:21:29 +0200
Subject: [PATCH 205/256] fix(po): write msgid_plural and msgstr[N] when
 appending a new plural entry

The new-key append path wrote msgid + a bare msgstr, the singular entry
shape. A plural key added to the source after the target file existed
therefore arrived with no msgid_plural and no plural forms, so ngettext
returned the English source for every count while the lockfile recorded
the key translated. The existing new-key-insertion test missed it because
its PO case carried no plural metadata.

The append path now emits msgid_plural and one msgstr[N] per recorded
form in index order, with index 0 falling back to the entry's
translation and an unrecorded form written empty -- which gettext reads as
untranslated rather than as source text.

Verified with gettext: msgfmt -c accepts the appended catalog at exit 0,
msgfmt --statistics counts the entry translated, msgunfmt reads both
forms back.

Refs cli-8zn5.12
---
 CHANGELOG.md                  |  2 +
 src/formats/po.ts             | 30 ++++++++++++++-
 tests/unit/formats/po.test.ts | 69 +++++++++++++++++++++++++++++++++++
 3 files changed, 100 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a3f7be4f..ee3de301 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **po**: **a plural key appended to an existing catalog keeps its `msgid_plural` and every `msgstr[N]`.** The new-key append path wrote `msgid` + a bare `msgstr`, which is the singular entry shape. A plural key added to the source *after* the target file existed therefore arrived in the catalog with no `msgid_plural` and no plural forms, so `ngettext` returned the English source for every count while the lockfile recorded the key translated — and the existing new-key-insertion test missed it because its PO case carried no plural metadata. The append path now emits `msgid_plural` and one `msgstr[N]` per recorded form, in index order, with index 0 falling back to the entry's translation. Verified with gettext itself: `msgfmt -c` accepts the appended catalog at exit 0, `msgfmt --statistics` counts the entry as translated, and `msgunfmt` reads both forms back.
+
 - **po**: **adjacent string literals on one line are concatenated, as gettext defines them.** `msgstr "Hola " "mundo"` is valid gettext for the string `Hola mundo` — literals join C-style. `unquote` tested only that the value started and ended with a quote and then sliced, so it read the inner `" "` as *content*; the next write escaped those quotes, turning the translation into `Hola \" \"mundo` permanently. `msgfmt -c` accepts both forms, so nothing flagged it. Values are now read as a run of literals, matching `msgunfmt`'s own answer for the same catalog (verified: `msgunfmt` reports `Hola mundo`, and so does the parser). Applies to `msgid` and `msgctxt` as well as `msgstr`. A quote that is genuinely part of the string (`"say \" here"`) still decodes as content, a plain single literal is unaffected, and a malformed value (unterminated quote) is returned untouched rather than mangled.
 
 - **po**: **an escaped carriage return survives a round trip instead of growing a backslash on every run.** `quote` escaped CR to `\r`, but `unquote`'s escape set was `\\ " n t` with no `r` case — so reading a catalog back turned `\r` into a literal backslash followed by `r`. The next run then escaped *that* backslash, so a carried entry's CR became `\\r`, then `\\\\r`, gaining a backslash indefinitely. `msgfmt` flags neither spelling, so nothing reported it. `unquote` now decodes `\r`, which makes the two halves symmetric and the round trip idempotent — asserted by reconstructing twice and requiring the second output to be byte-identical to the first.
diff --git a/src/formats/po.ts b/src/formats/po.ts
index 869a6375..bffce882 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -759,7 +759,35 @@ export class PoFormatParser implements FormatParser {
       } else {
         result.push(`msgid ${quote(entry.key)}`);
       }
-      result.push(`msgstr ${quoteLong(entry.translation)}`);
+
+      // A plural entry is `msgid_plural` + one `msgstr[N]` per form, never a bare
+      // `msgstr`. Writing only the singular shape lost the plural forms of a key
+      // added to the source after the target file existed, so ngettext returned
+      // the English source for every count while the lockfile called the key
+      // translated.
+      const msgidPlural = entry.metadata?.['msgid_plural'];
+      if (typeof msgidPlural === 'string') {
+        result.push(`msgid_plural ${quote(msgidPlural)}`);
+        const forms =
+          (entry.metadata?.['plural_forms'] as
+            Record<string, string> | undefined) ?? {};
+        const indices = new Set<number>([0, 1]);
+        for (const name of Object.keys(forms)) {
+          const match = /^msgstr\[(\d+)]$/.exec(name);
+          if (match?.[1] !== undefined) indices.add(Number(match[1]));
+        }
+        for (const index of [...indices].sort((a, b) => a - b)) {
+          // Index 0 falls back to `translation`, which is the same string the
+          // singular form would have carried; a form with no recorded value is
+          // written empty, which gettext and `msgfmt --statistics` both read as
+          // untranslated rather than as the source text.
+          const value =
+            forms[`msgstr[${index}]`] ?? (index === 0 ? entry.translation : '');
+          result.push(`msgstr[${index}] ${quoteLong(value)}`);
+        }
+      } else {
+        result.push(`msgstr ${quoteLong(entry.translation)}`);
+      }
     }
 
     return result.join('\n');
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index a9dd1351..e9335b3b 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -990,3 +990,72 @@ describe('PoFormatParser — adjacent string literals on one line', () => {
     expect(() => parser.extractTranslations(po)).not.toThrow();
   });
 });
+
+describe('PoFormatParser — appending a NEW plural entry', () => {
+  // The append path wrote `msgid` + `msgstr` only. A plural key added to the
+  // source after the target file existed therefore lost its `msgid_plural` and
+  // every `msgstr[N]`, so ngettext returned the English source for every count
+  // while the lockfile recorded the key translated.
+  const parser = new PoFormatParser();
+  const TARGET = [
+    'msgid ""',
+    'msgstr ""',
+    '"Content-Type: text/plain; charset=UTF-8\\n"',
+    '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"',
+    '',
+    'msgid "Hello"',
+    'msgstr "Hola"',
+    '',
+  ].join('\n');
+
+  const NEW_PLURAL = {
+    key: 'One file',
+    value: 'One file',
+    translation: 'Un archivo',
+    metadata: {
+      msgid_plural: '%d files',
+      plural_forms: {
+        'msgstr[0]': 'Un archivo',
+        'msgstr[1]': '%d archivos',
+      },
+    },
+  };
+
+  it('writes msgid_plural and every msgstr[N]', () => {
+    const written = parser.reconstruct(TARGET, [
+      { key: 'Hello', value: 'Hello', translation: 'Hola' },
+      NEW_PLURAL,
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('msgid_plural "%d files"');
+    expect(written).toContain('msgstr[0] "Un archivo"');
+    expect(written).toContain('msgstr[1] "%d archivos"');
+    // A plural entry has no bare `msgstr` line.
+    expect(written).not.toMatch(/^msgstr "Un archivo"$/m);
+  });
+
+  it('round-trips the appended plural entry', () => {
+    const written = parser.reconstruct(TARGET, [
+      { key: 'Hello', value: 'Hello', translation: 'Hola' },
+      NEW_PLURAL,
+    ] as TranslatedEntry[]);
+
+    const reread = parser.extract(written).find((e) => e.key === 'One file');
+    expect(reread?.metadata?.['msgid_plural']).toBe('%d files');
+    expect(reread?.metadata?.['plural_forms']).toEqual({
+      'msgstr[0]': 'Un archivo',
+      'msgstr[1]': '%d archivos',
+    });
+  });
+
+  it('still appends a non-plural entry as msgid + msgstr', () => {
+    const written = parser.reconstruct(TARGET, [
+      { key: 'Hello', value: 'Hello', translation: 'Hola' },
+      { key: 'Bye', value: 'Bye', translation: 'Adios' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('msgid "Bye"');
+    expect(written).toContain('msgstr "Adios"');
+    expect(written).not.toContain('msgid_plural');
+  });
+});

From fa28773d485f18cb61c8bfff9a11b33d5a6340af Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:25:47 +0200
Subject: [PATCH 206/256] fix(android,xliff): guard and escape an appended
 resource's key

Both new-resource append paths ran assertNoControlChars on the
translation and then interpolated the key straight into
<string name="..."> / <trans-unit id="...">. A control byte in a source
key produced a file no XML consumer can read -- XML 1.0 cannot represent a
C0 byte in any form, not even as a numeric character reference -- plus a
live terminal escape sequence in git diff and CI logs. A key containing
&, < or " broke the attribute outright, and a " is now legitimately
reachable because a single-quoted id/name may contain one.

The key is now control-checked (as are Android plural quantity values)
and escaped for an attribute context. extract entity-decodes attribute
values so such a key round-trips instead of coming back as a&amp;b.

Refs cli-8zn5.13
---
 CHANGELOG.md                           |  2 ++
 src/formats/android-xml.ts             | 40 ++++++++++++++++-----
 src/formats/xliff.ts                   | 28 +++++++++++++--
 tests/unit/formats/android-xml.test.ts | 49 ++++++++++++++++++++++++++
 tests/unit/formats/xliff.test.ts       | 43 ++++++++++++++++++++++
 5 files changed, 151 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ee3de301..c3599dc2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **android, xliff**: **the key of an appended resource is guarded and escaped, not just its translation.** Both new-resource append paths ran `assertNoControlChars` on the *translation* and then interpolated the key straight into `<string name="…">` / `<trans-unit id="…">`. A control byte in a source key therefore produced a file no XML consumer can read — XML 1.0 has no representation for a C0 byte in any form, not even a numeric character reference — plus a live terminal escape sequence in `git diff` and CI logs. A key containing `&`, `<` or `"` broke the attribute outright, and a `"` is now legitimately reachable since a single-quoted `id`/`name` may contain one. The key is now checked for control bytes (as are Android plural `quantity` values) and escaped for an attribute context, and `extract` entity-decodes attributes so such a key round-trips instead of coming back as `a&amp;b`.
+
 - **po**: **a plural key appended to an existing catalog keeps its `msgid_plural` and every `msgstr[N]`.** The new-key append path wrote `msgid` + a bare `msgstr`, which is the singular entry shape. A plural key added to the source *after* the target file existed therefore arrived in the catalog with no `msgid_plural` and no plural forms, so `ngettext` returned the English source for every count while the lockfile recorded the key translated — and the existing new-key-insertion test missed it because its PO case carried no plural metadata. The append path now emits `msgid_plural` and one `msgstr[N]` per recorded form, in index order, with index 0 falling back to the entry's translation. Verified with gettext itself: `msgfmt -c` accepts the appended catalog at exit 0, `msgfmt --statistics` counts the entry as translated, and `msgunfmt` reads both forms back.
 
 - **po**: **adjacent string literals on one line are concatenated, as gettext defines them.** `msgstr "Hola " "mundo"` is valid gettext for the string `Hola mundo` — literals join C-style. `unquote` tested only that the value started and ended with a quote and then sliced, so it read the inner `" "` as *content*; the next write escaped those quotes, turning the translation into `Hola \" \"mundo` permanently. `msgfmt -c` accepts both forms, so nothing flagged it. Values are now read as a run of literals, matching `msgunfmt`'s own answer for the same catalog (verified: `msgunfmt` reports `Hola mundo`, and so does the parser). Applies to `msgid` and `msgctxt` as well as `msgstr`. A quote that is genuinely part of the string (`"say \" here"`) still decodes as content, a plain single literal is unaffected, and a malformed value (unterminated quote) is returned untouched rather than mangled.
diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index bd7c1687..7e2b251d 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -80,7 +80,10 @@ const RESOURCES_EL: ElementPattern = {
  * source language.
  */
 function attrValue(element: ScannedElement): string {
-  return element.groups[1]!;
+  // Entity-decoded, because the writer escapes `&`/`"` when it interpolates a
+  // key into the attribute. Without decoding here the key would not round-trip:
+  // extract would report `a&amp;b` for the key the writer was given as `a&b`.
+  return decodeXmlEntities(element.groups[1]!);
 }
 
 /** The element's remaining attributes, preserved verbatim on rewrite. */
@@ -168,6 +171,20 @@ function unescapeAndroid(value: string): string {
   return decodeXmlEntities(withoutBackslashEscapes);
 }
 
+/**
+ * A value written inside a double-quoted XML attribute.
+ *
+ * `name` / `quantity` used to be interpolated raw, so a key holding `&` or `"`
+ * produced an element no XML consumer can read.
+ */
+function escapeXmlAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
 function escapeAndroid(value: string): string {
   return (
     value
@@ -379,19 +396,26 @@ export class AndroidXmlFormatParser implements FormatParser {
 
     const blocks = [
       ...missingStrings.map(([name, translation]) => {
+        // The KEY is checked as well as the translation: it is interpolated into
+        // the `name` attribute, and XML 1.0 has no representation for a C0 byte
+        // in any form, so a control byte in a source key produced a file no
+        // consumer reads and a live terminal sequence in `git diff`.
+        assertNoControlChars(name, name);
         assertNoControlChars(name, translation);
-        return `<string name="${name}">${escapeAndroid(translation)}</string>`;
+        return `<string name="${escapeXmlAttr(name)}">${escapeAndroid(translation)}</string>`;
       }),
-      ...missingPlurals.map(([name, quantities]) =>
-        [
-          `<plurals name="${name}">`,
+      ...missingPlurals.map(([name, quantities]) => {
+        assertNoControlChars(name, name);
+        return [
+          `<plurals name="${escapeXmlAttr(name)}">`,
           ...[...quantities].map(([quantity, value]) => {
+            assertNoControlChars(name, quantity);
             assertNoControlChars(name, value);
-            return `${indent}${INDENT_STEP}<item quantity="${quantity}">${escapeAndroid(value)}</item>`;
+            return `${indent}${INDENT_STEP}<item quantity="${escapeXmlAttr(quantity)}">${escapeAndroid(value)}</item>`;
           }),
           `${indent}</plurals>`,
-        ].join('\n')
-      ),
+        ].join('\n');
+      }),
     ];
 
     return insertBlocksAt(content, at, indent, blocks);
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index 3366a73b..50cce56d 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -38,7 +38,11 @@ const UNIT_EL: ElementPattern = {
 
 /** The `id` of a scanned `trans-unit`/`unit`; group 0 is the quote delimiter. */
 function unitId(element: ScannedElement): string {
-  return element.groups[1]!;
+  // Entity-decoded, because the writer escapes `&`/`"`/`<` when it interpolates
+  // a key into the `id` attribute. Without decoding here the key would not round
+  // trip: extract would report `a&amp;b` for the key the writer was given as
+  // `a&b`.
+  return unescapeXml(element.groups[1]!);
 }
 
 const SOURCE_EL: ElementPattern = {
@@ -216,6 +220,18 @@ function escapeXml(value: string): string {
     .replace(/>/g, '&gt;');
 }
 
+/**
+ * A value written inside a double-quoted attribute, where `"` also has to be
+ * escaped.
+ *
+ * The unit id used to be interpolated raw, so a key holding `"` or `&` produced
+ * an element no XML consumer can read — and the key can hold `"` legitimately,
+ * since a single-quoted `id` may contain one.
+ */
+function escapeXmlAttr(value: string): string {
+  return escapeXml(value).replace(/"/g, '&quot;');
+}
+
 function detectVersion(content: string): string {
   const match = VERSION_RE.exec(content);
   return match?.[1] ?? '1.2';
@@ -460,6 +476,12 @@ export class XliffFormatParser implements FormatParser {
       (anchor ? /^<(\w+:)/.exec(anchor.openTag)?.[1] : undefined) ?? '';
 
     const blocks = missing.map((entry) => {
+      // The KEY is checked as well as the translation: it is interpolated into
+      // the `id` attribute, and XML 1.0 has no representation for a C0 byte in
+      // any form — not even a numeric character reference — so a control byte in
+      // a source key produced a file no consumer reads and a live terminal
+      // sequence in `git diff`.
+      assertNoControlChars(entry.key, entry.key);
       assertNoControlChars(entry.key, entry.translation);
       const inner = isV2
         ? indent + INDENT_STEP.repeat(2)
@@ -470,13 +492,13 @@ export class XliffFormatParser implements FormatParser {
       ];
       if (!isV2) {
         return [
-          `<${ns}trans-unit id="${entry.key}">`,
+          `<${ns}trans-unit id="${escapeXmlAttr(entry.key)}">`,
           ...body,
           `${indent}</${ns}trans-unit>`,
         ].join('\n');
       }
       return [
-        `<${ns}unit id="${entry.key}">`,
+        `<${ns}unit id="${escapeXmlAttr(entry.key)}">`,
         `${indent}${INDENT_STEP}<${ns}segment>`,
         ...body,
         `${indent}${INDENT_STEP}</${ns}segment>`,
diff --git a/tests/unit/formats/android-xml.test.ts b/tests/unit/formats/android-xml.test.ts
index 2f139947..1413e15e 100644
--- a/tests/unit/formats/android-xml.test.ts
+++ b/tests/unit/formats/android-xml.test.ts
@@ -608,3 +608,52 @@ describe('single-quoted name and quantity attributes', () => {
     expect(entries.map((e) => e.key)).toEqual(['greeting']);
   });
 });
+
+describe('appending a resource whose KEY needs guarding', () => {
+  const EMPTY = [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    '<resources>',
+    '</resources>',
+  ].join('\n');
+
+  it('refuses a key carrying a control byte XML cannot represent', () => {
+    expect(() =>
+      parser.reconstruct(EMPTY, [
+        { key: 'bad\x1bkey', value: 'Hello', translation: 'Hola' },
+      ] as TranslatedEntry[])
+    ).toThrow(/U\+001B|control/i);
+  });
+
+  it('escapes a key containing XML markup characters', () => {
+    const written = parser.reconstruct(EMPTY, [
+      { key: 'a&b"c"', value: 'Hello', translation: 'Hola' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('&amp;');
+    expect(written).toContain('&quot;');
+    expect(written).not.toContain('name="a&b');
+    expect(parser.extract(written).map((e) => e.key)).toEqual(['a&b"c"']);
+  });
+
+  it('refuses a control byte in a plurals key too', () => {
+    expect(() =>
+      parser.reconstruct(EMPTY, [
+        {
+          key: 'bad\x00name',
+          value: '%d files',
+          translation: '%d archivos',
+          metadata: {
+            plurals: [{ quantity: 'other', value: '%d archivos' }],
+          },
+        },
+      ] as TranslatedEntry[])
+    ).toThrow(/U\+0000|control/i);
+  });
+
+  it('still appends an ordinary key unescaped', () => {
+    const written = parser.reconstruct(EMPTY, [
+      { key: 'greeting', value: 'Hello', translation: 'Hola' },
+    ] as TranslatedEntry[]);
+    expect(written).toContain('<string name="greeting">Hola</string>');
+  });
+});
diff --git a/tests/unit/formats/xliff.test.ts b/tests/unit/formats/xliff.test.ts
index 5e1f5d20..009f8ee5 100644
--- a/tests/unit/formats/xliff.test.ts
+++ b/tests/unit/formats/xliff.test.ts
@@ -666,3 +666,46 @@ describe('unit ids containing a quote character', () => {
     expect(entries.map((e) => e.key)).toEqual(["label.don't", "label.don'x"]);
   });
 });
+
+describe('appending a unit whose KEY needs guarding', () => {
+  // Both append paths ran assertNoControlChars on the TRANSLATION and then
+  // interpolated the key raw into `id="..."`. A control byte in a source key
+  // produced a file no XML consumer reads and a live terminal sequence in
+  // `git diff`; a quote or ampersand broke the attribute outright.
+  const EMPTY_V12 = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<xliff version="1.2">',
+    '  <file source-language="en" target-language="es">',
+    '    <body>',
+    '    </body>',
+    '  </file>',
+    '</xliff>',
+  ].join('\n');
+
+  it('refuses a key carrying a control byte XML cannot represent', () => {
+    expect(() =>
+      parser.reconstruct(EMPTY_V12, [
+        { key: 'bad\x1bkey', value: 'Hello', translation: 'Hola' },
+      ] as TranslatedEntry[])
+    ).toThrow(/U\+001B|control/i);
+  });
+
+  it('escapes a key containing XML markup characters', () => {
+    const written = parser.reconstruct(EMPTY_V12, [
+      { key: 'a&b<c>"d"', value: 'Hello', translation: 'Hola' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('&amp;');
+    expect(written).toContain('&quot;');
+    expect(written).not.toContain('id="a&b');
+    // The key round-trips: the escaped attribute decodes back to the original.
+    expect(parser.extract(written).map((e) => e.key)).toEqual(['a&b<c>"d"']);
+  });
+
+  it('still appends an ordinary key unescaped', () => {
+    const written = parser.reconstruct(EMPTY_V12, [
+      { key: 'greeting', value: 'Hello', translation: 'Hola' },
+    ] as TranslatedEntry[]);
+    expect(written).toContain('<trans-unit id="greeting">');
+  });
+});

From a5eac94e9015010d203c4210fb2cdf7116274b8e Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:29:19 +0200
Subject: [PATCH 207/256] fix(properties): read a key whose separator is
 escaped

escapeKey escapes =, :, space and backslash when writing a key, but
ENTRY_RE's key part excluded = and : outright with no notion of a
backslash escape -- so the parser could not read back a key it had just
written. `greeting:formal`, written `greeting\:formal`, split at the
escaped colon: key `greeting\`, value `formal=Hello`. Half the key went
to the engine as the value and the real key never reached the target.

The rewrite path carried a second copy of the same pattern, which
truncated the key when replacing a value. Both now share one KEY_CHARS
fragment treating \X as a single key character.

An ordinary key still splits at its first separator (a.b=x=y keeps the
value x=y), and a key's own bytes are preserved verbatim when its value is
rewritten.

Refs cli-8zn5.17
---
 CHANGELOG.md                          |  2 ++
 src/formats/properties.ts             | 17 ++++++++--
 tests/unit/formats/properties.test.ts | 48 +++++++++++++++++++++++++++
 3 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c3599dc2..8f023a6e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **properties**: **a key containing an escaped `=` or `:` is read back correctly, so the parser can read its own output.** `escapeKey` escapes `=`, `:`, space and backslash when writing a key — but the entry regex's key part excluded `=` and `:` outright, with no notion of a backslash escape. A key like `greeting:formal`, written as `greeting\:formal`, was therefore split at the escaped colon on the next read: the key became `greeting\` and the value `formal=Hello`, so **half the key was sent to the engine as the value** and the real key never reached the target file. The rewrite path carried a second copy of the same pattern, which truncated the key when replacing a value. Both now share one fragment that treats `\X` as a single key character; a key's own bytes are preserved verbatim when its value is rewritten, and an ordinary key still splits at its first separator (`a.b=x=y` → value `x=y`).
+
 - **android, xliff**: **the key of an appended resource is guarded and escaped, not just its translation.** Both new-resource append paths ran `assertNoControlChars` on the *translation* and then interpolated the key straight into `<string name="…">` / `<trans-unit id="…">`. A control byte in a source key therefore produced a file no XML consumer can read — XML 1.0 has no representation for a C0 byte in any form, not even a numeric character reference — plus a live terminal escape sequence in `git diff` and CI logs. A key containing `&`, `<` or `"` broke the attribute outright, and a `"` is now legitimately reachable since a single-quoted `id`/`name` may contain one. The key is now checked for control bytes (as are Android plural `quantity` values) and escaped for an attribute context, and `extract` entity-decodes attributes so such a key round-trips instead of coming back as `a&amp;b`.
 
 - **po**: **a plural key appended to an existing catalog keeps its `msgid_plural` and every `msgstr[N]`.** The new-key append path wrote `msgid` + a bare `msgstr`, which is the singular entry shape. A plural key added to the source *after* the target file existed therefore arrived in the catalog with no `msgid_plural` and no plural forms, so `ngettext` returned the English source for every count while the lockfile recorded the key translated — and the existing new-key-insertion test missed it because its PO case carried no plural metadata. The append path now emits `msgid_plural` and one `msgstr[N]` per recorded form, in index order, with index 0 falling back to the entry's translation. Verified with gettext itself: `msgfmt -c` accepts the appended catalog at exit 0, `msgfmt --statistics` counts the entry as translated, and `msgunfmt` reads both forms back.
diff --git a/src/formats/properties.ts b/src/formats/properties.ts
index 72cff890..673f64e2 100644
--- a/src/formats/properties.ts
+++ b/src/formats/properties.ts
@@ -7,7 +7,20 @@ import { PendingCommentBuffer } from './pending-comment-buffer.js';
 import { appendEntryLines } from './util/append-lines.js';
 import { isForbiddenControlChar } from './util/control-chars.js';
 
-const ENTRY_RE = /^([^=:#!\s][^=:]*?)\s*[=:]\s*(.*)/;
+// A key, treating `\X` as one unit so an escaped separator belongs to the key
+// rather than ending it. Without that the parser could not read back a key it
+// had just written: `escapeKey` escapes `=`, `:`, space and backslash, so
+// `greeting:formal` is written `greeting\:formal` and was then split at the
+// escaped colon — key `greeting\`, value `formal=Hello`. Half the key went out
+// for translation as the value, and the real key never reached the target file.
+const KEY_CHARS = String.raw`(?:[^=:#!\s\\]|\\.)(?:[^=:\\]|\\.)*?`;
+
+// `key = value` / `key: value`.
+const ENTRY_RE = new RegExp(String.raw`^(${KEY_CHARS})\s*[=:]\s*(.*)`);
+
+// The key and its separator, byte for byte, so rewriting a value preserves the
+// author's spelling of the line (`:` versus `=`, and the spacing around it).
+const KEY_SEPARATOR_RE = new RegExp(String.raw`^(${KEY_CHARS}\s*[=:]\s*)`);
 const COMMENT_RE = /^\s*[#!]/;
 
 /**
@@ -112,7 +125,7 @@ export class PropertiesFormatParser implements FormatParser {
           pending.flushToOutput(result);
           const escapedValue = this.escapeValue(translation);
           const originalLine = lines[startLine]!;
-          const sepMatch = /^([^=:#!\s][^=:]*?\s*[=:]\s*)/.exec(originalLine);
+          const sepMatch = KEY_SEPARATOR_RE.exec(originalLine);
           if (sepMatch) {
             result.push(sepMatch[1] + escapedValue);
           } else {
diff --git a/tests/unit/formats/properties.test.ts b/tests/unit/formats/properties.test.ts
index 60e9fae4..d8eacdf5 100644
--- a/tests/unit/formats/properties.test.ts
+++ b/tests/unit/formats/properties.test.ts
@@ -432,3 +432,51 @@ describe('PropertiesFormatParser', () => {
     });
   });
 });
+
+describe('PropertiesFormatParser — a key containing an escaped separator', () => {
+  // `escapeKey` escapes `=`, `:`, space and backslash when writing a key, but
+  // ENTRY_RE's key part excluded `=` and `:` outright — so the parser could not
+  // read back a key it had just written. `greeting\:formal=Hello` split at the
+  // escaped colon, making the key `greeting\` and the value `formal=Hello`: half
+  // the key was sent for translation as the value, and the real key never
+  // reached the target file.
+  it('reads a key whose colon is escaped', () => {
+    const entries = parser.extract('greeting\\:formal=Hello\n');
+    expect(entries).toEqual([{ key: 'greeting:formal', value: 'Hello' }]);
+  });
+
+  it('reads a key whose equals sign is escaped', () => {
+    const entries = parser.extract('a\\=b=Hello\n');
+    expect(entries).toEqual([{ key: 'a=b', value: 'Hello' }]);
+  });
+
+  it('reads a key whose space is escaped', () => {
+    const entries = parser.extract('with\\ space=Hello\n');
+    expect(entries).toEqual([{ key: 'with space', value: 'Hello' }]);
+  });
+
+  it('round-trips a key containing a separator character', () => {
+    const written = parser.reconstruct('', [
+      { key: 'greeting:formal', value: 'Hello', translation: 'Buenos días' },
+    ]);
+    expect(parser.extract(written)).toEqual([
+      { key: 'greeting:formal', value: 'Buenos días' },
+    ]);
+  });
+
+  it('rewrites the translation of an escaped-separator key in place', () => {
+    const written = parser.reconstruct('greeting\\:formal=Hello\n', [
+      { key: 'greeting:formal', value: 'Hello', translation: 'Buenos dias' },
+    ]);
+    // The key keeps its own bytes; only the value is replaced.
+    expect(written).toContain('greeting\\:formal=Buenos dias');
+    expect(parser.extract(written)).toEqual([
+      { key: 'greeting:formal', value: 'Buenos dias' },
+    ]);
+  });
+
+  it('still splits an ordinary key at its first separator', () => {
+    expect(parser.extract('a.b=x=y\n')).toEqual([{ key: 'a.b', value: 'x=y' }]);
+    expect(parser.extract('a.b:x:y\n')).toEqual([{ key: 'a.b', value: 'x:y' }]);
+  });
+});

From d6313228dcdc5c444715351571092f9e4c4a9455 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:34:03 +0200
Subject: [PATCH 208/256] fix(xliff): locate the review state by attribute, not
 by first regex match

`state` was found with one unanchored, non-global regex, so it returned
the first state=... anywhere in the attribute run -- including one inside
another attribute's value, e.g. note="compare state='final' with the old
one". extractNeedsReview then read the decoy and missed the real
needs-review-translation, and the rewrite corrupted the decoy's value
while leaving the real state alone: a needs-review marker stayed attached
to text the run had just replaced with machine output.

Attributes are now walked as whole name="value" pairs, so a value's
contents cannot shadow a real attribute and an attribute merely ending in
`state` (xstate=) is not mistaken for it.

Two sibling markers go with it, since neither can describe replaced text:
approved="yes" becomes approved="no", and state-qualifier (1.2) /
subState (2.0) are dropped rather than rewritten -- their vocabularies
have no "this is machine output now" value.

Markers are still left untouched when the run writes the text it found.

Refs cli-8zn5.22
---
 CHANGELOG.md                     |  2 +
 src/formats/xliff.ts             | 86 ++++++++++++++++++++++++++++----
 tests/unit/formats/xliff.test.ts | 78 +++++++++++++++++++++++++++++
 3 files changed, 157 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f023a6e..196d4d84 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **xliff**: **the review state of a rewritten element is read and updated on the real attribute, not on a `state=` sequence inside another attribute's value.** `state` was located with a single unanchored, non-global regex, so it returned the *first* `state=…` anywhere in the attribute run — including one sitting inside another attribute's value, such as `note="compare state='final' with the old one"`. The consequences compounded: `extractNeedsReview` read the decoy and so missed the real `needs-review-translation`, and the rewrite corrupted the decoy's value while leaving the real state untouched — so a needs-review marker stayed attached to text this run had just replaced with machine output. Attributes are now walked as whole `name="value"` pairs, which also means an attribute merely *ending* in `state` (`xstate=`) is no longer mistaken for it. Two sibling markers are handled at the same time, since neither can describe text the run has just replaced: `approved="yes"` becomes `approved="no"`, and `state-qualifier` (1.2) / `subState` (2.0) are removed rather than rewritten, their vocabularies having no "this is machine output now" value. Every marker is left untouched when the run writes the same text it found, which is the existing `targetHolds` behaviour.
+
 - **properties**: **a key containing an escaped `=` or `:` is read back correctly, so the parser can read its own output.** `escapeKey` escapes `=`, `:`, space and backslash when writing a key — but the entry regex's key part excluded `=` and `:` outright, with no notion of a backslash escape. A key like `greeting:formal`, written as `greeting\:formal`, was therefore split at the escaped colon on the next read: the key became `greeting\` and the value `formal=Hello`, so **half the key was sent to the engine as the value** and the real key never reached the target file. The rewrite path carried a second copy of the same pattern, which truncated the key when replacing a value. Both now share one fragment that treats `\X` as a single key character; a key's own bytes are preserved verbatim when its value is rewritten, and an ordinary key still splits at its first separator (`a.b=x=y` → value `x=y`).
 
 - **android, xliff**: **the key of an appended resource is guarded and escaped, not just its translation.** Both new-resource append paths ran `assertNoControlChars` on the *translation* and then interpolated the key straight into `<string name="…">` / `<trans-unit id="…">`. A control byte in a source key therefore produced a file no XML consumer can read — XML 1.0 has no representation for a C0 byte in any form, not even a numeric character reference — plus a live terminal escape sequence in `git diff` and CI logs. A key containing `&`, `<` or `"` broke the attribute outright, and a `"` is now legitimately reachable since a single-quoted `id`/`name` may contain one. The key is now checked for control bytes (as are Android plural `quantity` values) and escaped for an attribute context, and `extract` entity-decodes attributes so such a key round-trips instead of coming back as `a&amp;b`.
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index 50cce56d..2aafa9ef 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -87,9 +87,51 @@ const TRANSLATABLE_EL: ElementPattern = {
   close: /<\/(?:\w+:)?(?:source|target)>/iy,
 };
 
-// Matches only the `state` attribute: `state-qualifier` (1.2) and `subState`
-// (2.0) are different attributes carrying different vocabularies.
-const STATE_ATTR_RE = /(\sstate\s*=\s*["'])([^"'<]*)(["'])/i;
+// One `name="value"` pair. Scanned globally from the start of the attribute run
+// so pairs are consumed whole, which is what keeps a `state='…'` sequence sitting
+// INSIDE another attribute's value from being read as the element's state.
+const ATTR_PAIR_RE = /([a-zA-Z_:][\w:.-]*)\s*=\s*(["'])([\s\S]*?)\2/g;
+
+interface AttrMatch {
+  /** Offset of the value within the attribute run. */
+  valueStart: number;
+  valueEnd: number;
+  value: string;
+  /** Offsets of the whole `name="value"` pair, including any leading space. */
+  pairStart: number;
+  pairEnd: number;
+}
+
+/**
+ * Find an attribute by name in an element's attribute run.
+ *
+ * Attributes are walked as whole pairs rather than searched for with a single
+ * unanchored regex. The old `state` pattern returned the FIRST `state=…` in the
+ * string, so a `state='…'` sequence inside another attribute's value shadowed the
+ * real one: the review state was neither read (`extractNeedsReview` missed it)
+ * nor rewritten (the decoy was corrupted instead), leaving a
+ * `needs-review-translation` marker attached to freshly machine-translated text.
+ * Comparing the captured name in full also means `xstate=` is not a `state`.
+ */
+function findAttr(attrs: string, name: string): AttrMatch | undefined {
+  ATTR_PAIR_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = ATTR_PAIR_RE.exec(attrs)) !== null) {
+    if (match[1]!.toLowerCase() !== name) continue;
+    const value = match[3]!;
+    const valueEnd = match.index + match[0].length - 1;
+    let pairStart = match.index;
+    while (pairStart > 0 && /\s/.test(attrs[pairStart - 1]!)) pairStart--;
+    return {
+      valueStart: valueEnd - value.length,
+      valueEnd,
+      value,
+      pairStart,
+      pairEnd: match.index + match[0].length,
+    };
+  }
+  return undefined;
+}
 
 /** The value written for a target this reconstruct has just filled in. */
 const TRANSLATED_STATE = 'translated';
@@ -119,7 +161,7 @@ const UNFINISHED_STATES_V12: ReadonlySet<string> = new Set([
 const UNFINISHED_STATES_V2: ReadonlySet<string> = new Set(['initial']);
 
 function stateOf(attrs: string): string | undefined {
-  return STATE_ATTR_RE.exec(attrs)?.[2];
+  return findAttr(attrs, 'state')?.value;
 }
 
 /**
@@ -130,11 +172,37 @@ function stateOf(attrs: string): string | undefined {
  * `state` gains none: absence is this parser's own output shape.
  */
 function withTranslatedState(attrs: string): string {
-  return attrs.replace(
-    STATE_ATTR_RE,
-    (_match, open: string, _value: string, close: string) =>
-      `${open}${TRANSLATED_STATE}${close}`
-  );
+  let result = attrs;
+
+  // `state-qualifier` (1.2) and `subState` (2.0) qualify a state that no longer
+  // describes this element's text, so they are dropped rather than rewritten:
+  // their vocabularies have no "this is machine output now" value. Removed before
+  // `state` and `approved` are rewritten, so those offsets are still valid.
+  for (const name of ['state-qualifier', 'substate']) {
+    const found = findAttr(result, name);
+    if (found) {
+      result = result.slice(0, found.pairStart) + result.slice(found.pairEnd);
+    }
+  }
+
+  // `approved="yes"` is 1.2's other claim that a human signed this text off. It
+  // cannot describe text this run has just replaced.
+  const approved = findAttr(result, 'approved');
+  if (approved?.value.toLowerCase() === 'yes') {
+    result =
+      result.slice(0, approved.valueStart) +
+      'no' +
+      result.slice(approved.valueEnd);
+  }
+
+  const state = findAttr(result, 'state');
+  if (state) {
+    result =
+      result.slice(0, state.valueStart) +
+      TRANSLATED_STATE +
+      result.slice(state.valueEnd);
+  }
+  return result;
 }
 
 const NAMED_ENTITIES: Record<string, string> = {
diff --git a/tests/unit/formats/xliff.test.ts b/tests/unit/formats/xliff.test.ts
index 009f8ee5..8f2292f8 100644
--- a/tests/unit/formats/xliff.test.ts
+++ b/tests/unit/formats/xliff.test.ts
@@ -709,3 +709,81 @@ describe('appending a unit whose KEY needs guarding', () => {
     expect(written).toContain('<trans-unit id="greeting">');
   });
 });
+
+describe('review-state attributes on an element the run rewrites', () => {
+  // STATE_ATTR_RE was one unanchored, non-global regex, so it returned the FIRST
+  // `state=...` in the attribute string -- including one sitting inside ANOTHER
+  // attribute's value. The real review state was then neither read (needsReview
+  // missed it) nor rewritten (the decoy was corrupted instead), so a
+  // `needs-review-translation` marker stayed attached to freshly machine
+  // translated text.
+  const withDecoy = (targetAttrs: string): string =>
+    [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<xliff version="1.2">',
+      '  <file source-language="en" target-language="es">',
+      '    <body>',
+      '      <trans-unit id="greeting">',
+      '        <source>Hello</source>',
+      `        <target${targetAttrs}>Viejo</target>`,
+      '      </trans-unit>',
+      '    </body>',
+      '  </file>',
+      '</xliff>',
+    ].join('\n');
+
+  const DECOY_ATTRS = ` note="compare state='final' with the old one" state="needs-review-translation"`;
+
+  it('reads the real state, not a state= sequence inside another value', () => {
+    const flagged = parser.extractNeedsReview(withDecoy(DECOY_ATTRS));
+    expect([...flagged]).toEqual(['greeting']);
+  });
+
+  it('rewrites the real state and leaves the decoy value alone', () => {
+    const written = parser.reconstruct(withDecoy(DECOY_ATTRS), [
+      { key: 'greeting', value: 'Hello', translation: 'Hola' },
+    ]);
+
+    expect(written).toContain('state="translated"');
+    expect(written).not.toContain('state="needs-review-translation"');
+    // The other attribute's value is content, not a marker to rewrite.
+    expect(written).toContain(`note="compare state='final' with the old one"`);
+  });
+
+  it('does not treat an attribute merely ending in "state" as the state', () => {
+    const written = parser.reconstruct(
+      withDecoy(' xstate="needs-review-translation" state="new"'),
+      [{ key: 'greeting', value: 'Hello', translation: 'Hola' }]
+    );
+    expect(written).toContain('xstate="needs-review-translation"');
+    expect(written).toContain('state="translated"');
+  });
+
+  it('withdraws approved="yes" from text this run replaced', () => {
+    const written = parser.reconstruct(withDecoy(' approved="yes"'), [
+      { key: 'greeting', value: 'Hello', translation: 'Hola' },
+    ]);
+    expect(written).toContain('approved="no"');
+    expect(written).not.toContain('approved="yes"');
+  });
+
+  it('drops a state-qualifier that no longer describes the text', () => {
+    const written = parser.reconstruct(
+      withDecoy(
+        ' state="needs-review-translation" state-qualifier="mt-suggestion"'
+      ),
+      [{ key: 'greeting', value: 'Hello', translation: 'Hola' }]
+    );
+    expect(written).toContain('state="translated"');
+    expect(written).not.toContain('state-qualifier');
+  });
+
+  it('leaves every marker alone when the run writes the same text', () => {
+    const unchanged = withDecoy(' approved="yes" state="signed-off"');
+    const written = parser.reconstruct(unchanged, [
+      { key: 'greeting', value: 'Hello', translation: 'Viejo' },
+    ]);
+    expect(written).toContain('approved="yes"');
+    expect(written).toContain('state="signed-off"');
+  });
+});

From e4a81f19a9474ff9295bf38538e1a3a9767f3e3c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:40:23 +0200
Subject: [PATCH 209/256] fix(sync): judge staleness per locale, not from the
 whole lock entry

Three places decided a per-locale property from the whole entry.

processBucket scoped staleness to every configured locale rather than to
the --locale filter, so `sync --locale de` re-translated, re-billed and
overwrote de's reviewed translation because es had failed -- a locale the
run was not asked to look at.

sync status called computeDiff with no locales, triggering its
whole-entry "some locale failed" fallback, and then inherited the
key-level `stale` verdict -- which conflates "the source changed" (every
locale is out of date) with "one locale's own record lags" (only that one
is). The report now separates the two by re-checking the source hash.

The duplicated locale-filter expression is computed once and reused.

The locale that genuinely failed is still re-translated and still
reported as needing work.

Refs cli-8zn5.23
---
 CHANGELOG.md                                  |   2 +
 src/sync/sync-process-bucket.ts               |  43 +++--
 src/sync/sync-status.ts                       |  33 +++-
 ...cross-locale-staleness.integration.test.ts | 163 ++++++++++++++++++
 4 files changed, 216 insertions(+), 25 deletions(-)
 create mode 100644 tests/integration/sync-cross-locale-staleness.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 196d4d84..d40ccbb2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **one locale's failure no longer makes a key stale for every locale.** Staleness is recorded per target locale in the lockfile, but three places decided it from the whole entry. `deepl sync --locale de` scoped staleness to *all* configured locales rather than to the `--locale` filter, so a key that had failed for **es** was re-translated, re-billed and written over de's reviewed translation — a locale the run was not asked to look at. `sync status` called `computeDiff` with no locales at all, which triggers its whole-entry "some locale failed" fallback and reported a complete locale as `outdated`; and even with locales passed, the report inherited the key-level `stale` verdict, which conflates *the source changed* (every locale is out of date) with *one locale's own record lags* (only that locale is). The run now judges staleness against the locales it will actually touch, the status report distinguishes the two `stale` cases by re-checking the source hash, and the duplicated locale-filter expression is computed once. The locale that genuinely failed is still re-translated and still reported as needing work.
+
 - **xliff**: **the review state of a rewritten element is read and updated on the real attribute, not on a `state=` sequence inside another attribute's value.** `state` was located with a single unanchored, non-global regex, so it returned the *first* `state=…` anywhere in the attribute run — including one sitting inside another attribute's value, such as `note="compare state='final' with the old one"`. The consequences compounded: `extractNeedsReview` read the decoy and so missed the real `needs-review-translation`, and the rewrite corrupted the decoy's value while leaving the real state untouched — so a needs-review marker stayed attached to text this run had just replaced with machine output. Attributes are now walked as whole `name="value"` pairs, which also means an attribute merely *ending* in `state` (`xstate=`) is no longer mistaken for it. Two sibling markers are handled at the same time, since neither can describe text the run has just replaced: `approved="yes"` becomes `approved="no"`, and `state-qualifier` (1.2) / `subState` (2.0) are removed rather than rewritten, their vocabularies having no "this is machine output now" value. Every marker is left untouched when the run writes the same text it found, which is the existing `targetHolds` behaviour.
 
 - **properties**: **a key containing an escaped `=` or `:` is read back correctly, so the parser can read its own output.** `escapeKey` escapes `=`, `:`, space and backslash when writing a key — but the entry regex's key part excluded `=` and `:` outright, with no notion of a backslash escape. A key like `greeting:formal`, written as `greeting\:formal`, was therefore split at the escaped colon on the next read: the key became `greeting\` and the value `formal=Hello`, so **half the key was sent to the engine as the value** and the real key never reached the target file. The rewrite path carried a second copy of the same pattern, which truncated the key when replacing a value. Both now share one fragment that treats `\X` as a single key character; a key's own bytes are preserved verbatim when its value is rewritten, and an ordinary key still splits at its first separator (`a.b=x=y` → value `x=y`).
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index 0fc64af7..145decc6 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -107,10 +107,20 @@ export async function processBucket(
   const out: BucketContribution = { ...EMPTY, fileResults: [] };
 
   const fileLockEntries = getOwnMember(lockFile.entries, relPath) ?? {};
-  // Pass the configured locales so staleness is judged per locale: a key whose
-  // source is unchanged still needs work if any target locale's stored hash
-  // lags behind, or if that locale previously failed.
-  let diffs = computeDiff(fileLockEntries, entries, config.target_locales);
+  /**
+   * The locales this run will actually touch.
+   *
+   * Staleness is judged against these rather than against every configured
+   * locale: a key that failed for es is not stale for de, so `sync --locale de`
+   * used to re-translate, re-bill and overwrite de's reviewed keys because of a
+   * locale the run was not even asked to look at.
+   */
+  const effectiveLocales = options?.localeFilter?.length
+    ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
+    : config.target_locales;
+  // Per-locale staleness: a key whose source is unchanged still needs work if a
+  // locale in scope has a stale stored hash, or previously failed.
+  let diffs = computeDiff(fileLockEntries, entries, effectiveLocales);
 
   if (options?.force) {
     diffs = diffs.map((d) => ({ ...d, status: 'new' as const }));
@@ -162,17 +172,12 @@ export async function processBucket(
    */
   let gapsCache: TargetGaps | undefined;
   const targetGaps = async (): Promise<TargetGaps> => {
-    if (gapsCache === undefined) {
-      const effective = options?.localeFilter?.length
-        ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
-        : config.target_locales;
-      gapsCache = await findTargetGaps(
-        config,
-        walked,
-        fileLockEntries,
-        effective
-      );
-    }
+    gapsCache ??= await findTargetGaps(
+      config,
+      walked,
+      fileLockEntries,
+      effectiveLocales
+    );
     return gapsCache;
   };
 
@@ -267,10 +272,6 @@ export async function processBucket(
   }
 
   if (options?.dryRun) {
-    const effectiveLocales = options?.localeFilter?.length
-      ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
-      : config.target_locales;
-
     // The same target-file checks the real run makes, so the preview is of that
     // run rather than of the lockfile.
     const { chars, refused, gaps } = await estimateCharacters(effectiveLocales);
@@ -326,9 +327,7 @@ export async function processBucket(
     return out;
   }
 
-  const locales = options?.localeFilter?.length
-    ? config.target_locales.filter((l) => options.localeFilter!.includes(l))
-    : config.target_locales;
+  const locales = effectiveLocales;
 
   if (options?.localeFilter?.length && locales.length === 0) {
     Logger.warn(
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index 3b6ebbd6..e67769e7 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -1,6 +1,6 @@
 import * as path from 'path';
 import type { FormatRegistry } from '../formats/index.js';
-import { SyncLockManager } from './sync-lock.js';
+import { SyncLockManager, computeSourceHash } from './sync-lock.js';
 import { getOwnMember } from '../utils/own-members.js';
 import { computeDiff } from './sync-differ.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
@@ -100,7 +100,11 @@ export async function computeSyncStatus(
     skippedKeys += skippedEntries.length;
 
     const fileLockEntries = getOwnMember(lockFile.entries, relPath) ?? {};
-    const diffs = computeDiff(fileLockEntries, entries);
+    // Scoped to the configured locales, so staleness is judged per locale. With
+    // no locales computeDiff falls back to a whole-entry "some locale failed"
+    // test, which reported a complete locale as outdated because a DIFFERENT
+    // locale had failed.
+    const diffs = computeDiff(fileLockEntries, entries, config.target_locales);
     // The lockfile alone cannot answer "is this locale complete": it records
     // what a run intended, not what its target file ended up holding.
     const gaps = await findTargetGaps(
@@ -132,6 +136,29 @@ export async function computeSyncStatus(
       });
     }
 
+    /**
+     * Keys whose SOURCE changed, as opposed to keys the differ called `stale`
+     * because one locale's own record lags behind.
+     *
+     * `stale` covers both, and only the first can speak for every locale: a key
+     * that failed for es is not outdated for de. Deciding from `diff.status`
+     * alone reported a complete locale as outdated because a different locale
+     * had failed.
+     */
+    const sourceChangedKeys = new Set(
+      diffs
+        .filter((diff) => {
+          if (diff.status !== 'stale' || diff.value === undefined) return false;
+          const lockEntry = getOwnMember(fileLockEntries, diff.key);
+          return (
+            lockEntry !== undefined &&
+            computeSourceHash(diff.value, diff.metadata) !==
+              lockEntry.source_hash
+          );
+        })
+        .map((diff) => diff.key)
+    );
+
     for (const locale of config.target_locales) {
       const stats = localeStats.get(locale);
       if (!stats) continue;
@@ -155,7 +182,7 @@ export async function computeSyncStatus(
 
         if (diff.status === 'new' || !hasTranslation || localeFailed) {
           stats.missing++;
-        } else if (diff.status === 'stale' || localeOutdated) {
+        } else if (sourceChangedKeys.has(diff.key) || localeOutdated) {
           stats.outdated++;
         } else if (gaps.get(locale)?.keys.has(diff.key)) {
           stats.unwritten++;
diff --git a/tests/integration/sync-cross-locale-staleness.integration.test.ts b/tests/integration/sync-cross-locale-staleness.integration.test.ts
new file mode 100644
index 00000000..a29773d9
--- /dev/null
+++ b/tests/integration/sync-cross-locale-staleness.integration.test.ts
@@ -0,0 +1,163 @@
+/**
+ * Integration tests for staleness being judged per locale.
+ *
+ * A lockfile records a status per target locale. Judging a key's staleness from
+ * the whole entry — "some locale failed" — makes one locale's failure speak for
+ * every locale: `sync --locale de` re-translated, re-billed and overwrote de's
+ * reviewed keys because *es* had failed, `sync status` reported a complete locale
+ * as outdated, and `--frozen` failed a locale that was up to date.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { computeSyncStatus } from '../../src/sync/sync-status';
+import type { LocaleStatus } from '../../src/sync/sync-status';
+import {
+  createSyncHarness,
+  writeSyncConfig,
+  seedLockFile,
+} from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import { computeSourceHash } from '../../src/sync/sync-lock';
+
+function replyEchoing(sent: string[]): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .persist()
+    .post('/v2/translate')
+    .reply(200, (_uri, body) => {
+      const texts = new URLSearchParams(body as string).getAll('text');
+      sent.push(...texts);
+      return {
+        translations: texts.map((t) => ({
+          text: `[MT] ${t}`,
+          detected_source_language: 'EN',
+          billed_characters: t.length,
+        })),
+      };
+    });
+}
+
+describe('staleness when one locale has failed', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  const sourcePath = () => path.join(tmpDir, 'locales', 'en.json');
+  const dePath = () => path.join(tmpDir, 'locales', 'de.json');
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-cross-locale-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['de', 'es'],
+      buckets: { json: { include: ['locales/en.json'] } },
+    });
+    fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+    fs.writeFileSync(
+      sourcePath(),
+      JSON.stringify({ greeting: 'Hello' }, null, 2),
+      'utf-8'
+    );
+    fs.writeFileSync(
+      dePath(),
+      JSON.stringify({ greeting: 'REVIEWED-DE' }, null, 2),
+      'utf-8'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'locales', 'es.json'),
+      JSON.stringify({}, null, 2),
+      'utf-8'
+    );
+
+    // de is translated against the current source; es failed.
+    const hash = computeSourceHash('Hello', undefined);
+    seedLockFile(tmpDir, {
+      entries: {
+        'locales/en.json': {
+          greeting: {
+            source_hash: hash,
+            source_text: 'Hello',
+            translations: {
+              de: {
+                hash,
+                translated_at: new Date(0).toISOString(),
+                status: 'translated',
+              },
+              es: {
+                hash,
+                translated_at: new Date(0).toISOString(),
+                status: 'failed',
+              },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  afterEach(() => {
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  it('does not re-translate de because es failed', async () => {
+    const sent: string[] = [];
+    replyEchoing(sent);
+
+    const result = await harness.syncService.sync(
+      await loadSyncConfig(tmpDir),
+      { localeFilter: ['de'] }
+    );
+
+    expect(result.success).toBe(true);
+    expect(sent).toEqual([]);
+    expect(
+      (
+        JSON.parse(fs.readFileSync(dePath(), 'utf-8')) as Record<string, string>
+      )['greeting']
+    ).toBe('REVIEWED-DE');
+  });
+
+  it('does not report de as outdated in sync status', async () => {
+    const status = await computeSyncStatus(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const de = status.locales.find((l: LocaleStatus) => l.locale === 'de')!;
+    expect(de.outdated).toBe(0);
+    expect(de.complete).toBe(1);
+  });
+
+  it('still re-translates es, which is the locale that failed', async () => {
+    const sent: string[] = [];
+    replyEchoing(sent);
+
+    const result = await harness.syncService.sync(
+      await loadSyncConfig(tmpDir),
+      { localeFilter: ['es'] }
+    );
+
+    expect(result.success).toBe(true);
+    expect(sent).toEqual(['Hello']);
+  });
+
+  it('still reports es as needing work in sync status', async () => {
+    const status = await computeSyncStatus(
+      await loadSyncConfig(tmpDir),
+      harness.registry
+    );
+
+    const es = status.locales.find((l: LocaleStatus) => l.locale === 'es')!;
+    expect(es.complete).toBe(0);
+  });
+});

From 4b8caa1e15b9b0b01add5fc19ff76f350c205659 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:50:33 +0200
Subject: [PATCH 210/256] fix(sync): refuse a glob whose extglob repetition
 wraps an unbounded wildcard

The glob guard bounded brace expansion and raw length but said nothing
about extglobs, and a pattern can carry no brace at all. *(...) and +(...)
compile to a repetition, so a wildcard inside one hands picomatch a
nested quantifier.

Measured: against a 40-character directory name the six-character pattern
`+(a*)b` takes ~50 seconds; six such groups took 53 seconds in the first
probe and longer patterns do not finish. The bead reported N=22/~45s, so
the reachable threshold is far lower than filed -- one group is enough.

Both the pattern and the directory names it runs against come from the
checkout, so this is reachable from a merge request, and it wedges sync,
--dry-run, validate and watch alike.

Such a group is now rejected at config load (0.16 ms) with an error
naming the construct and pointing at @(...), which matches one
alternative without the repetition. Measured and deliberately untouched:
@(...), ?(...) and !(...) are not repetitions and stayed flat, so
@(en|de)/*.json, !(node_modules)/**/*.json, +(en|de)/messages.json and
res/values-*/strings.xml all still load.

Refs cli-8zn5.26
---
 CHANGELOG.md                         |  2 +
 src/utils/glob-safety.ts             | 62 +++++++++++++++++++++++++++-
 tests/unit/utils/glob-safety.test.ts | 51 +++++++++++++++++++++++
 zz-redos2.mjs                        | 10 +++++
 zz-redos3.mjs                        |  7 ++++
 5 files changed, 130 insertions(+), 2 deletions(-)
 create mode 100644 zz-redos2.mjs
 create mode 100644 zz-redos3.mjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d40ccbb2..856f9efe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **an `include`/`exclude` pattern with a nested-quantifier extglob is refused instead of wedging the process for minutes.** The glob guard bounded brace expansion and raw pattern length, but said nothing about extglobs — and a pattern can carry no brace at all. `*(…)` and `+(…)` compile to a *repetition*, so an unbounded wildcard inside one hands picomatch a nested quantifier: measured against a 40-character directory name, the **six-character** pattern `+(a*)b` takes about **50 seconds**, and a longer one never finishes. Both the pattern and the directory names it runs against come from the checkout, so this is reachable from a merge request rather than only from a hand-edited config; it wedges `sync`, `--dry-run`, `validate` and `watch` alike. Such a group is now rejected at config load (in 0.16 ms) with an error naming the offending construct and pointing at `@(…)`, which matches one alternative without the repetition. Measured and left alone: `@(…)`, `?(…)` and `!(…)` are not repetitions and stay flat, so ordinary patterns — `@(en|de)/*.json`, `!(node_modules)/**/*.json`, `+(en|de)/messages.json`, `res/values-*/strings.xml` — are unaffected.
+
 - **sync**: **one locale's failure no longer makes a key stale for every locale.** Staleness is recorded per target locale in the lockfile, but three places decided it from the whole entry. `deepl sync --locale de` scoped staleness to *all* configured locales rather than to the `--locale` filter, so a key that had failed for **es** was re-translated, re-billed and written over de's reviewed translation — a locale the run was not asked to look at. `sync status` called `computeDiff` with no locales at all, which triggers its whole-entry "some locale failed" fallback and reported a complete locale as `outdated`; and even with locales passed, the report inherited the key-level `stale` verdict, which conflates *the source changed* (every locale is out of date) with *one locale's own record lags* (only that locale is). The run now judges staleness against the locales it will actually touch, the status report distinguishes the two `stale` cases by re-checking the source hash, and the duplicated locale-filter expression is computed once. The locale that genuinely failed is still re-translated and still reported as needing work.
 
 - **xliff**: **the review state of a rewritten element is read and updated on the real attribute, not on a `state=` sequence inside another attribute's value.** `state` was located with a single unanchored, non-global regex, so it returned the *first* `state=…` anywhere in the attribute run — including one sitting inside another attribute's value, such as `note="compare state='final' with the old one"`. The consequences compounded: `extractNeedsReview` read the decoy and so missed the real `needs-review-translation`, and the rewrite corrupted the decoy's value while leaving the real state untouched — so a needs-review marker stayed attached to text this run had just replaced with machine output. Attributes are now walked as whole `name="value"` pairs, which also means an attribute merely *ending* in `state` (`xstate=`) is no longer mistaken for it. Two sibling markers are handled at the same time, since neither can describe text the run has just replaced: `approved="yes"` becomes `approved="no"`, and `state-qualifier` (1.2) / `subState` (2.0) are removed rather than rewritten, their vocabularies having no "this is machine output now" value. Every marker is left untouched when the run writes the same text it found, which is the existing `targetHolds` behaviour.
diff --git a/src/utils/glob-safety.ts b/src/utils/glob-safety.ts
index e609b305..441a9acc 100644
--- a/src/utils/glob-safety.ts
+++ b/src/utils/glob-safety.ts
@@ -139,13 +139,71 @@ export function countGlobExpansion(pattern: string): number {
 }
 
 /**
- * Reject a glob pattern whose brace expansion or raw length could wedge the
- * process inside fast-glob. `field` names the config path for the error.
+ * The first `*(…)` / `+(…)` extglob group whose body holds an unbounded
+ * wildcard, or undefined.
+ *
+ * Those two operators are repetitions, so a `*` or `+` inside one gives picomatch
+ * a nested quantifier and exponential backtracking. Measured against a
+ * 40-character directory name, the six-character pattern `+(a*)b` takes about 50
+ * SECONDS — and the expansion bound above never sees it, because a pattern can
+ * carry no brace at all. `@(…)`, `?(…)` and `!(…)` are not repetitions and stayed
+ * flat under the same measurement, so they are left alone.
+ *
+ * Both the pattern and the directory names it is matched against come from the
+ * checkout, so this is reachable from a merge request rather than only from a
+ * hand-edited config.
+ */
+function findNestedQuantifierExtglob(pattern: string): string | undefined {
+  for (let i = 0; i < pattern.length; i += 1) {
+    if (pattern[i] === '\\') {
+      i += 1;
+      continue;
+    }
+    const op = pattern[i];
+    if ((op !== '*' && op !== '+') || pattern[i + 1] !== '(') continue;
+
+    let depth = 1;
+    let body = '';
+    let j = i + 2;
+    for (; j < pattern.length; j += 1) {
+      const ch = pattern[j]!;
+      if (ch === '\\') {
+        body += ch + (pattern[j + 1] ?? '');
+        j += 1;
+        continue;
+      }
+      if (ch === '(') depth += 1;
+      if (ch === ')') {
+        depth -= 1;
+        if (depth === 0) break;
+      }
+      body += ch;
+    }
+    if (/[*+]/.test(body)) {
+      return pattern.slice(i, Math.min(j + 1, pattern.length));
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Reject a glob pattern whose brace expansion, raw length or extglob nesting
+ * could wedge the process inside fast-glob. `field` names the config path for
+ * the error.
  */
 export function assertBoundedGlobExpansion(
   pattern: string,
   field: string
 ): void {
+  const nested = findNestedQuantifierExtglob(pattern);
+  if (nested !== undefined) {
+    throw new ConfigError(
+      `${field} entry contains the extglob group "${sanitizeForTerminal(nested)}", whose repetition wraps an unbounded wildcard. ` +
+        `That compiles to a regular expression with nested quantifiers, which can take minutes on a single directory name.`,
+      `Remove the "*" or "+" from inside the group in ${field} — "@(...)" matches one alternative without the repetition.`
+    );
+  }
+
   if (pattern.length > MAX_GLOB_PATTERN_LENGTH) {
     throw new ConfigError(
       `${field} entry is ${pattern.length} characters long, exceeding the ${MAX_GLOB_PATTERN_LENGTH}-character limit for a glob pattern`,
diff --git a/tests/unit/utils/glob-safety.test.ts b/tests/unit/utils/glob-safety.test.ts
index 973db7b7..05ec51d8 100644
--- a/tests/unit/utils/glob-safety.test.ts
+++ b/tests/unit/utils/glob-safety.test.ts
@@ -134,3 +134,54 @@ describe('assertBoundedGlobExpansion', () => {
     ).toThrow(ConfigError);
   });
 });
+
+describe('extglob nested-quantifier rejection', () => {
+  // The brace-count guard says nothing about extglobs, and `*(...)` / `+(...)`
+  // compile to a repetition — so an unbounded wildcard inside one hands picomatch
+  // a nested quantifier. Measured against a 40-character directory name, the
+  // six-character pattern `+(a*)b` takes ~50 SECONDS, wedging sync, validate,
+  // dry-run and watch alike. `@(...)`, `?(...)` and `!(...)` are not repetitions
+  // and stay flat, so they are left alone.
+  const field = 'buckets.json.include';
+
+  it.each([
+    ['+(a*)b'],
+    ['*(a*)b'],
+    ['locales/+(a*)/en.json'],
+    ['+(a+)b'],
+    ['*(*)'],
+    ['+(@(a*))b'],
+  ])('rejects %s', (pattern) => {
+    expect(() => assertBoundedGlobExpansion(pattern, field)).toThrow(
+      /extglob|backtrack/i
+    );
+  });
+
+  it.each([
+    ['locales/en.json'],
+    ['locales/**/*.json'],
+    ['locales/@(en|de)/*.json'],
+    ['?(a)b'],
+    ['!(node_modules)/**/*.json'],
+    ['+(en|de)/messages.json'],
+    ['res/values-*/strings.xml'],
+  ])('accepts %s', (pattern) => {
+    expect(() => assertBoundedGlobExpansion(pattern, field)).not.toThrow();
+  });
+
+  it('names the offending construct in the error', () => {
+    expect.assertions(2);
+    try {
+      assertBoundedGlobExpansion('locales/+(a*)/en.json', field);
+    } catch (err) {
+      expect((err as Error).message).toContain('+(a*)');
+      expect((err as Error).message).toContain(field);
+    }
+  });
+
+  it('does not treat an escaped extglob opener as one', () => {
+    expect(() =>
+      assertBoundedGlobExpansion('locales/\\+(a*)/en.json', field)
+    ).not.toThrow();
+  });
+});
diff --git a/zz-redos2.mjs b/zz-redos2.mjs
new file mode 100644
index 00000000..fd1cbcb2
--- /dev/null
+++ b/zz-redos2.mjs
@@ -0,0 +1,10 @@
+import picomatch from 'picomatch';
+const decoy = 'a'.repeat(40);
+for (const n of [1, 2, 3, 4, 5]) {
+  const pattern = '+(a*)'.repeat(n) + 'b';
+  const isMatch = picomatch(pattern);
+  const t0 = process.hrtime.bigint();
+  isMatch(decoy);
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+  console.log(`N=${n} -> ${ms.toFixed(2)} ms`);
+}
diff --git a/zz-redos3.mjs b/zz-redos3.mjs
new file mode 100644
index 00000000..5cf5d8a2
--- /dev/null
+++ b/zz-redos3.mjs
@@ -0,0 +1,7 @@
+import picomatch from 'picomatch';
+const decoy = 'a'.repeat(40);
+const n = Number(process.argv[2]);
+const pattern = '+(a*)'.repeat(n) + 'b';
+const t0 = process.hrtime.bigint();
+picomatch(pattern)(decoy);
+console.log(`N=${n} -> ${(Number(process.hrtime.bigint() - t0) / 1e6).toFixed(2)} ms`);

From 89e5f7a372101073840c92f8302713b6e7b7bd7c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 14:54:58 +0200
Subject: [PATCH 211/256] fix(sync): name the target-only keys a rewrite
 removes

Every run that rewrites a locale drops whatever the target holds that is
not in the desired key set, because reconstruct is handed that set whole.
For a key the lockfile recorded, that is the intended prune of a key the
source no longer defines. For a key neither the source nor the lockfile
accounts for -- one a translator added by hand -- it is someone else's
data being deleted, and it happened with no mention in the run output,
sync status or sync validate, while the .deepl.bak was unlinked on
success.

Such keys are now named in a warning pointing at both remedies: add them
to the source, or recover them from the backup before the next run. The
prune itself is unchanged, since emitting exactly the keys the source
defines is what makes deleting a removed key work -- the finding was the
silence, not the pruning.

The distinction cannot be drawn from the lockfile at that point:
processBucket removes deleted keys' lock entries before the locale loop,
which makes them indistinguishable there from keys it never recorded. It
is drawn from the `deleted` diffs instead.

Refs cli-8zn5.25
---
 CHANGELOG.md                                  |   2 +
 src/sync/sync-locale-translator.ts            |  59 +++++++
 .../sync-target-only-keys.integration.test.ts | 162 ++++++++++++++++++
 3 files changed, 223 insertions(+)
 create mode 100644 tests/integration/sync-target-only-keys.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 856f9efe..83608bf1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a run that removes a hand-added key from a locale file now says so.** `reconstruct` is handed the complete desired key set, so every run that rewrites a locale drops whatever the target holds that is not in that set. For a key the lockfile recorded, that is the intended prune of a key the source no longer defines. For a key **neither the source nor the lockfile accounts for** — one a translator added to the locale file by hand — it is someone else's data being deleted, and it happened with no mention in the run output, `sync status` or `sync validate`, while the `.deepl.bak` was unlinked on success: nothing said anything was lost and nothing was left to recover it from. Such keys are now named in a warning that points at both remedies (add them to the source, or recover them from the backup before the next run). The prune itself is deliberately unchanged — emitting exactly the keys the source defines is what makes deleting a removed key work — so this makes the behaviour visible rather than altering it. Note the distinction cannot be drawn from the lockfile at that point, because the run removes deleted keys' lock entries before the locale loop; it is drawn from the `deleted` diffs instead.
+
 - **sync**: **an `include`/`exclude` pattern with a nested-quantifier extglob is refused instead of wedging the process for minutes.** The glob guard bounded brace expansion and raw pattern length, but said nothing about extglobs — and a pattern can carry no brace at all. `*(…)` and `+(…)` compile to a *repetition*, so an unbounded wildcard inside one hands picomatch a nested quantifier: measured against a 40-character directory name, the **six-character** pattern `+(a*)b` takes about **50 seconds**, and a longer one never finishes. Both the pattern and the directory names it runs against come from the checkout, so this is reachable from a merge request rather than only from a hand-edited config; it wedges `sync`, `--dry-run`, `validate` and `watch` alike. Such a group is now rejected at config load (in 0.16 ms) with an error naming the offending construct and pointing at `@(…)`, which matches one alternative without the repetition. Measured and left alone: `@(…)`, `?(…)` and `!(…)` are not repetitions and stay flat, so ordinary patterns — `@(en|de)/*.json`, `!(node_modules)/**/*.json`, `+(en|de)/messages.json`, `res/values-*/strings.xml` — are unaffected.
 
 - **sync**: **one locale's failure no longer makes a key stale for every locale.** Staleness is recorded per target locale in the lockfile, but three places decided it from the whole entry. `deepl sync --locale de` scoped staleness to *all* configured locales rather than to the `--locale` filter, so a key that had failed for **es** was re-translated, re-billed and written over de's reviewed translation — a locale the run was not asked to look at. `sync status` called `computeDiff` with no locales at all, which triggers its whole-entry "some locale failed" fallback and reported a complete locale as `outdated`; and even with locales passed, the report inherited the key-level `stale` verdict, which conflates *the source changed* (every locale is out of date) with *one locale's own record lags* (only that locale is). The run now judges staleness against the locales it will actually touch, the status report distinguishes the two `stale` cases by re-checking the source hash, and the duplicated locale-filter expression is computed once. The locale that genuinely failed is still re-translated and still reported as needing work.
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index ba6c21a5..cc20f030 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -197,6 +197,54 @@ function withheldKeysWarning(
   );
 }
 
+/**
+ * Keys the target file holds that this rewrite will not write back, and that
+ * neither the source file nor the lockfile accounts for.
+ *
+ * `reconstruct` is handed the complete desired key set, so anything absent from
+ * it is removed from the file. For a key the lockfile records, that is the
+ * intended prune of a key the source no longer has. A key the lockfile has never
+ * heard of was not put there by this tool — a translator added it by hand — so
+ * deleting it is outside what the run was asked to do. The prune itself is left
+ * alone; what was undefensible is that it happened with no mention in the run
+ * output, `sync status` or `sync validate`, and with the backup unlinked on
+ * success, so nothing was recoverable and nothing said anything was lost.
+ */
+function droppedTargetOnlyKeys(
+  existingTranslations: ReadonlyMap<string, string>,
+  written: readonly TranslatedEntry[],
+  diffs: readonly SyncDiff[]
+): string[] {
+  const writtenKeys = new Set(written.map((entry) => entry.key));
+  // A `deleted` diff is a key the lockfile recorded that the source no longer
+  // has, so pruning it is the point. The lockfile itself cannot answer this:
+  // processBucket removes those entries before the locale loop runs, which makes
+  // them indistinguishable there from a key it never recorded.
+  const prunedKeys = new Set(
+    diffs.filter((diff) => diff.status === 'deleted').map((diff) => diff.key)
+  );
+  return [...existingTranslations.keys()].filter(
+    (key) => !writtenKeys.has(key) && !prunedKeys.has(key)
+  );
+}
+
+function droppedTargetOnlyWarning(
+  locale: string,
+  targetRelPath: string,
+  dropped: readonly string[]
+): string {
+  const shown = dropped.slice(0, 3).map((key) => `"${key}"`);
+  const more = dropped.length > shown.length ? ', …' : '';
+  const one = dropped.length === 1;
+  return (
+    `${locale}: ${targetRelPath} holds ${dropped.length} ${one ? 'key' : 'keys'} that the source file ` +
+    `and .deepl-sync.lock both lack: ${shown.join(', ')}${more}. ` +
+    `${one ? 'It has' : 'They have'} been removed, because a rewrite emits exactly the keys the source defines. ` +
+    `If ${one ? 'it was' : 'they were'} added to the locale file on purpose, add ${one ? 'it' : 'them'} to the source ` +
+    `file as well — or recover ${one ? 'it' : 'them'} from ${targetRelPath}${BACKUP_SUFFIX} before the next run.`
+  );
+}
+
 export interface TranslateLocaleResult {
   fileResult: SyncFileResult;
   successfulKeys: string[];
@@ -1013,6 +1061,17 @@ export class LocaleTranslator {
       }
     }
 
+    const droppedTargetOnly = droppedTargetOnlyKeys(
+      existingTranslations,
+      allTranslatedEntries,
+      diffs
+    );
+    if (droppedTargetOnly.length > 0) {
+      Logger.warn(
+        droppedTargetOnlyWarning(locale, targetRelPath, droppedTargetOnly)
+      );
+    }
+
     const reconstructed = isMultiLocale
       ? parser.reconstruct(templateContent, allTranslatedEntries, locale)
       : parser.reconstruct(templateContent, allTranslatedEntries);
diff --git a/tests/integration/sync-target-only-keys.integration.test.ts b/tests/integration/sync-target-only-keys.integration.test.ts
new file mode 100644
index 00000000..6ba9d370
--- /dev/null
+++ b/tests/integration/sync-target-only-keys.integration.test.ts
@@ -0,0 +1,162 @@
+/**
+ * Integration test for keys that exist only in a target file.
+ *
+ * `reconstruct` is handed the complete desired key set, so any run that rewrites
+ * a locale drops whatever the target holds that is not in that set. For a key
+ * the lockfile records, that is the intended prune of a key the source no longer
+ * has. For a key the lockfile has NEVER recorded — one a translator added by
+ * hand — it is someone else's data being deleted, and it happened with no
+ * mention in the run output, `sync status` or `sync validate`, with the backup
+ * unlinked on success. The prune stays; the silence does not.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import {
+  createSyncHarness,
+  writeSyncConfig,
+  seedLockFile,
+} from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import { computeSourceHash } from '../../src/sync/sync-lock';
+import { Logger } from '../../src/utils/logger';
+
+function replyEchoing(): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .persist()
+    .post('/v2/translate')
+    .reply(200, (_uri, body) => {
+      const texts = new URLSearchParams(body as string).getAll('text');
+      return {
+        translations: texts.map((t) => ({
+          text: `[MT] ${t}`,
+          detected_source_language: 'EN',
+          billed_characters: t.length,
+        })),
+      };
+    });
+}
+
+describe('a key present only in the target file', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+  let warnings: string[];
+  let warnSpy: jest.SpyInstance;
+
+  const sourcePath = () => path.join(tmpDir, 'locales', 'en.json');
+  const dePath = () => path.join(tmpDir, 'locales', 'de.json');
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-target-only-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    warnings = [];
+    warnSpy = jest
+      .spyOn(Logger, 'warn')
+      .mockImplementation((...args: unknown[]) => {
+        warnings.push(args.map(String).join(' '));
+      });
+
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['de'],
+      buckets: { json: { include: ['locales/en.json'] } },
+    });
+    fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+    fs.writeFileSync(
+      sourcePath(),
+      JSON.stringify({ greeting: 'Hello v2' }, null, 2),
+      'utf-8'
+    );
+    fs.writeFileSync(
+      dePath(),
+      JSON.stringify(
+        { greeting: 'Hallo', handAdded: 'VON HAND', pruned: 'ALT' },
+        null,
+        2
+      ),
+      'utf-8'
+    );
+
+    // The lockfile knows `greeting` (against an older source, so the run has
+    // work) and `pruned` (a key the source has since dropped). It has never
+    // heard of `handAdded`.
+    seedLockFile(tmpDir, {
+      entries: {
+        'locales/en.json': {
+          greeting: {
+            source_hash: computeSourceHash('Hello', undefined),
+            source_text: 'Hello',
+            translations: {
+              de: {
+                hash: computeSourceHash('Hello', undefined),
+                translated_at: new Date(0).toISOString(),
+                status: 'translated',
+              },
+            },
+          },
+          pruned: {
+            source_hash: computeSourceHash('Old', undefined),
+            source_text: 'Old',
+            translations: {
+              de: {
+                hash: computeSourceHash('Old', undefined),
+                translated_at: new Date(0).toISOString(),
+                status: 'translated',
+              },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  it('warns, naming the key the lockfile never recorded', async () => {
+    replyEchoing();
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+    expect(result.success).toBe(true);
+
+    const about = warnings.filter((w) => w.includes('handAdded'));
+    expect(about).toHaveLength(1);
+    expect(about[0]).toContain('locales/de.json');
+    expect(about[0]).toMatch(/de:/);
+  });
+
+  it('does not warn about a key the lockfile recorded and the source dropped', async () => {
+    replyEchoing();
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    // `pruned` is this tool's own key, removed because the source no longer has
+    // it — the documented prune, not a surprise.
+    expect(warnings.filter((w) => w.includes('pruned'))).toEqual([]);
+  });
+
+  it('says nothing when the target holds no key of its own', async () => {
+    fs.writeFileSync(
+      dePath(),
+      JSON.stringify({ greeting: 'Hallo' }, null, 2),
+      'utf-8'
+    );
+    replyEchoing();
+
+    await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(warnings.filter((w) => /only in|hand/i.test(w))).toEqual([]);
+  });
+});

From bdbdbee65b467bfa359373b1fb3fbc56b8adbe06 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 15:26:14 +0200
Subject: [PATCH 212/256] fix(sync): read the reconstruct template through the
 guarded target read

The pre-read went through readTargetFile, which separates an absent file
from one on disk that could not be opened and refuses the locale in the
second case. The write-time re-read that produces the template was a bare
fs.readFile whose catch fell back to the SOURCE, so a file that became
unreadable in the window was reclassified as absent: no backup was taken,
and a source-derived file was written over the target the run had just
failed to read. sync pull already gets this right with one guarded read.

Measured by revoking read permission from inside the engine reply -- the
one hook that runs between the two reads: the target gained the machine
translation and lost its own state at exit 0. It is now left untouched
and the locale is reported failed, matching the pre-read's handling.

readTargetFile now classifies whitespace-only content as present-but-empty
rather than unusable. It has no translations to lose, and parsing it fails
for most formats, which would otherwise refuse a locale over an empty file
-- the over-rejection this change surfaced in an existing test.

A sync-validate test stubbed only the first of two reads, leaving the
target read resolving to undefined, which fs.readFile cannot return; it
now stubs both.

Refs cli-8zn5.24
---
 CHANGELOG.md                                  |   2 +
 src/sync/sync-locale-translator.ts            |  36 +++-
 src/sync/sync-target-read.ts                  |   9 +
 ...template-reread-toctou.integration.test.ts | 155 ++++++++++++++++++
 tests/unit/sync/sync-validate.test.ts         |   7 +-
 5 files changed, 199 insertions(+), 10 deletions(-)
 create mode 100644 tests/integration/sync-template-reread-toctou.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 83608bf1..43730772 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: **a target file that becomes unreadable mid-run is left alone, not overwritten from the source.** The pre-read went through `readTargetFile`, which separates *nothing is there* from *something is there this run could not open* and refuses the locale in the second case — but the write-time re-read that produces the reconstruct template was a bare `fs.readFile` whose `catch` fell back to the **source** as the template. A file that became unreadable in the window between the two was therefore reclassified as absent: no backup was taken (`targetExists` stayed false) and a source-derived file was written over the very target the run had just failed to read. Measured by revoking read permission on `de.json` from inside the engine reply, which is the one hook that runs between the two reads: the target gained the machine translation and lost its own state, at exit 0. The template now comes from the same guarded read, and an unreadable target aborts that locale exactly as the pre-read would — reported, with the file untouched. As part of this, a target holding only whitespace is now classified as present-but-empty rather than unusable: it has no translations to lose, and parsing it would fail (`JSON.parse('  ')` throws), which would otherwise refuse a locale over an empty file.
+
 - **sync**: **a run that removes a hand-added key from a locale file now says so.** `reconstruct` is handed the complete desired key set, so every run that rewrites a locale drops whatever the target holds that is not in that set. For a key the lockfile recorded, that is the intended prune of a key the source no longer defines. For a key **neither the source nor the lockfile accounts for** — one a translator added to the locale file by hand — it is someone else's data being deleted, and it happened with no mention in the run output, `sync status` or `sync validate`, while the `.deepl.bak` was unlinked on success: nothing said anything was lost and nothing was left to recover it from. Such keys are now named in a warning that points at both remedies (add them to the source, or recover them from the backup before the next run). The prune itself is deliberately unchanged — emitting exactly the keys the source defines is what makes deleting a removed key work — so this makes the behaviour visible rather than altering it. Note the distinction cannot be drawn from the lockfile at that point, because the run removes deleted keys' lock entries before the locale loop; it is drawn from the `deleted` diffs instead.
 
 - **sync**: **an `include`/`exclude` pattern with a nested-quantifier extglob is refused instead of wedging the process for minutes.** The glob guard bounded brace expansion and raw pattern length, but said nothing about extglobs — and a pattern can carry no brace at all. `*(…)` and `+(…)` compile to a *repetition*, so an unbounded wildcard inside one hands picomatch a nested quantifier: measured against a 40-character directory name, the **six-character** pattern `+(a*)b` takes about **50 seconds**, and a longer one never finishes. Both the pattern and the directory names it runs against come from the checkout, so this is reachable from a merge request rather than only from a hand-edited config; it wedges `sync`, `--dry-run`, `validate` and `watch` alike. Such a group is now rejected at config load (in 0.16 ms) with an error naming the offending construct and pointing at `@(…)`, which matches one alternative without the repetition. Measured and left alone: `@(…)`, `?(…)` and `!(…)` are not repetitions and stay flat, so ordinary patterns — `@(en|de)/*.json`, `!(node_modules)/**/*.json`, `+(en|de)/messages.json`, `res/values-*/strings.xml` — are unaffected.
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index cc20f030..45952ec1 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -28,6 +28,7 @@ import {
   withoutPluralForms,
 } from './sync-utils.js';
 import { extractExistingTranslations } from './sync-bucket-walker.js';
+import { readTargetFile, unusableTargetMessage } from './sync-target-read.js';
 import { primaryPluralItem } from '../formats/util/plurals.js';
 import { BACKUP_SUFFIX } from './sync-bak-cleanup.js';
 import { Logger } from '../utils/logger.js';
@@ -1010,19 +1011,36 @@ export class LocaleTranslator {
       Logger.warn(withheldKeysWarning(locale, targetRelPath, withheld));
     }
 
+    // The same guarded read the pre-read pass uses, rather than a bare readFile
+    // whose catch cannot tell an absent file from one that is on disk and could
+    // not be opened. A target that became unreadable in the window between the
+    // two was reclassified as absent: the template fell back to the SOURCE,
+    // no backup was taken because `targetExists` stayed false, and a
+    // source-derived file was written over the very target the run had just
+    // failed to read. `deepl sync pull` gets this right with one guarded read.
+    //
+    // Thrown rather than warned, matching how the pre-read treats the same
+    // condition: processBucket catches it per locale, records the locale failed
+    // and leaves the file alone.
     let templateContent = content;
     let targetExists = false;
-    try {
-      const existingTargetContent = await fs.promises.readFile(
-        targetAbsPath,
-        'utf-8'
+    const templateRead = await readTargetFile(
+      parser,
+      targetAbsPath,
+      isMultiLocale ? locale : undefined
+    );
+    if (templateRead.state === 'unusable') {
+      throw new Error(
+        unusableTargetMessage(targetRelPath, templateRead.reason)
       );
-      if (existingTargetContent.trim()) {
-        templateContent = existingTargetContent;
-      }
+    }
+    if (templateRead.state === 'usable') {
       targetExists = true;
-    } catch {
-      templateContent = content;
+      // An empty file is a target that exists — so it is backed up — but holds no
+      // template, so the source's structure is used.
+      if (templateRead.content.trim()) {
+        templateContent = templateRead.content;
+      }
     }
 
     if (
diff --git a/src/sync/sync-target-read.ts b/src/sync/sync-target-read.ts
index af9a3a34..f3c04cf9 100644
--- a/src/sync/sync-target-read.ts
+++ b/src/sync/sync-target-read.ts
@@ -41,6 +41,15 @@ export async function readTargetFile(
     }
     return { state: 'unusable', reason: describe(err), error: err };
   }
+  // A file holding only whitespace has no translations to lose, so `unusable` —
+  // whose whole point is that the file holds the only copy of this locale's work
+  // — does not describe it. Parsing it would fail for most formats
+  // (`JSON.parse('  ')` throws), which would refuse the locale over an empty
+  // file; the callers treat a blank template as "use the source's structure".
+  if (content.trim() === '') {
+    return { state: 'usable', content, translations: new Map() };
+  }
+
   try {
     return {
       state: 'usable',
diff --git a/tests/integration/sync-template-reread-toctou.integration.test.ts b/tests/integration/sync-template-reread-toctou.integration.test.ts
new file mode 100644
index 00000000..db5020a1
--- /dev/null
+++ b/tests/integration/sync-template-reread-toctou.integration.test.ts
@@ -0,0 +1,155 @@
+/**
+ * Integration test for the window between the guarded pre-read of a target file
+ * and the write-time re-read that produces the reconstruct template.
+ *
+ * The pre-read went through `readTargetFile`, which separates "nothing is there"
+ * from "something is there that this run could not open" and refuses the locale
+ * in the second case. The write-time re-read was a bare `fs.readFile` whose catch
+ * fell back to the SOURCE as the template — so a file that became unreadable in
+ * the window was reclassified as "no target": no backup was taken, and a
+ * source-derived file was written over the very target the run could not read.
+ * `deepl sync pull` gets this right with a single guarded read.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { createSyncHarness, writeSyncConfig } from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import { BACKUP_SUFFIX } from '../../src/sync/sync-bak-cleanup';
+
+// A reviewed translation for `a` and no `b`, so the run has one key to translate
+// -- which is what gets the engine called, and the engine reply is the only hook
+// that runs between the pre-read and the write.
+const HUMAN_DE = JSON.stringify({ a: 'HUMAN-A' }, null, 2) + '\n';
+
+// Root ignores the permission bits, so the read the test needs to fail would
+// succeed and the race could not be staged at all.
+const describeIfNotRoot =
+  typeof process.getuid === 'function' && process.getuid() === 0
+    ? describe.skip
+    : describe;
+
+describeIfNotRoot('target file that becomes unreadable mid-run', () => {
+  let tmpDir: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+
+  const sourcePath = () => path.join(tmpDir, 'locales', 'en.json');
+  const dePath = () => path.join(tmpDir, 'locales', 'de.json');
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-toctou-'));
+    harness = createSyncHarness({ parsers: ['json'] });
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['de'],
+      buckets: { json: { include: ['locales/en.json'] } },
+    });
+    fs.mkdirSync(path.dirname(sourcePath()), { recursive: true });
+    fs.writeFileSync(
+      sourcePath(),
+      JSON.stringify({ a: 'Alpha', b: 'Beta' }, null, 2),
+      'utf-8'
+    );
+    fs.writeFileSync(dePath(), HUMAN_DE, 'utf-8');
+  });
+
+  afterEach(() => {
+    try {
+      fs.chmodSync(dePath(), 0o644);
+    } catch {
+      /* already gone */
+    }
+    harness.cleanup();
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    nock.cleanAll();
+  });
+
+  /**
+   * The engine reply is the one point that runs after the pre-read and before the
+   * write, so it is where the file is made unreadable.
+   */
+  function replyAndRevokeRead(): void {
+    nock(DEEPL_FREE_API_URL)
+      .persist()
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => {
+        fs.chmodSync(dePath(), 0o000);
+        const texts = new URLSearchParams(body as string).getAll('text');
+        return {
+          translations: texts.map((t) => ({
+            text: `[MT] ${t}`,
+            detected_source_language: 'EN',
+            billed_characters: t.length,
+          })),
+        };
+      });
+  }
+
+  it('refuses the locale instead of writing a source-derived file over it', async () => {
+    // Guard the premise: the revocation must really make the read fail here.
+    fs.chmodSync(dePath(), 0o000);
+    let readable = true;
+    try {
+      fs.readFileSync(dePath(), 'utf-8');
+    } catch {
+      readable = false;
+    }
+    fs.chmodSync(dePath(), 0o644);
+    if (readable) {
+      // Filesystem does not enforce the bits; the race cannot be staged.
+      return;
+    }
+
+    replyAndRevokeRead();
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    fs.chmodSync(dePath(), 0o644);
+    const after = fs.readFileSync(dePath(), 'utf-8');
+
+    // Byte-identical: the file the run could not read is left exactly as it
+    // stands, rather than rebuilt from a source-derived template.
+    expect(after).toBe(HUMAN_DE);
+    expect(after).not.toContain('[MT]');
+    // Reported, not silent.
+    expect(result.fileResults.every((r) => r.written)).toBe(false);
+  });
+
+  it('still writes normally when the target stays readable', async () => {
+    nock(DEEPL_FREE_API_URL)
+      .persist()
+      .post('/v2/translate')
+      .reply(200, (_uri, body) => {
+        const texts = new URLSearchParams(body as string).getAll('text');
+        return {
+          translations: texts.map((t) => ({
+            text: `[MT] ${t}`,
+            detected_source_language: 'EN',
+            billed_characters: t.length,
+          })),
+        };
+      });
+
+    // Give the run something to do: b is missing from the target.
+    fs.writeFileSync(
+      dePath(),
+      JSON.stringify({ a: 'HUMAN-A' }, null, 2) + '\n',
+      'utf-8'
+    );
+
+    const result = await harness.syncService.sync(await loadSyncConfig(tmpDir));
+
+    expect(result.success).toBe(true);
+    const after = fs.readFileSync(dePath(), 'utf-8');
+    expect(after).toContain('HUMAN-A');
+    expect(after).toContain('[MT] Beta');
+    expect(fs.existsSync(dePath() + BACKUP_SUFFIX)).toBe(false);
+  });
+});
diff --git a/tests/unit/sync/sync-validate.test.ts b/tests/unit/sync/sync-validate.test.ts
index c91c5903..695371ef 100644
--- a/tests/unit/sync/sync-validate.test.ts
+++ b/tests/unit/sync/sync-validate.test.ts
@@ -153,7 +153,12 @@ describe('validateTranslations', () => {
   });
 
   it('should return empty result for empty source', async () => {
-    mockReadFile.mockResolvedValueOnce('source');
+    // Both reads are stubbed: the source file and then the target file. Stubbing
+    // only the first left the target read resolving to `undefined`, which is not
+    // something `fs.readFile` can return.
+    mockReadFile
+      .mockResolvedValueOnce('source')
+      .mockResolvedValueOnce('target');
     const parser = makeParser([], []);
     const result = await validateTranslations(
       makeConfig(),

From 41d764cb5c5f0a1bd3764da01490baa0a9cea67d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 15:34:48 +0200
Subject: [PATCH 213/256] fix(watch): key a path by inode so two spellings of
 one file compare equal

The comparison key resolved symlinked ancestors and nothing else, but
fs.realpathSync does not case-fold on a case-insensitive volume -- measured
on APFS, it returns `Docs` for `Docs` even when the directory is stored as
`docs` -- and does not unify NFC with NFD. Two spellings reaching the same
inode produced different keys, so `watch --git-staged` translated nothing
when the index spelled a directory differently from the watcher, silently
at exit 0.

Where the file exists the key is now its device+inode pair, which is its
identity. Verified on APFS that docs/en.md and Docs/en.md, and the NFC and
NFD spellings of one name, all reach the same inode. No platform guesswork
is needed in either direction: on a case-sensitive volume the other
spelling does not exist, so the paths keep distinct keys. lstat rather
than stat keeps a symlink distinct from its target, and a path with no
file yet falls back to the resolved string.

Three test sites hand-rolled the old key format or seeded staged sets with
raw paths getStagedFiles never produces, which is what let the format
change slip past them; they now build keys with canonicalPathKey and
assert which file was identified rather than how the key is spelled.

Refs cli-8zn5.21
---
 CHANGELOG.md                                  |   2 +
 src/utils/paths.ts                            |  31 ++++-
 .../watch-service.integration.test.ts         |  19 ++-
 tests/unit/services/watch.test.ts             |  18 +--
 tests/unit/utils/canonical-path-key.test.ts   | 127 ++++++++++++++++++
 5 files changed, 179 insertions(+), 18 deletions(-)
 create mode 100644 tests/unit/utils/canonical-path-key.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43730772..0a3f9223 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: **`--git-staged` recognises a staged file when git and the watcher spell its path differently.** The path comparison key resolved symlinked ancestors but nothing else, and `fs.realpathSync` **does not** case-fold on a case-insensitive volume — measured on APFS, `realpathSync` returns `Docs` for `Docs` even when the directory is stored as `docs` — nor does it unify NFC with NFD. Two spellings reaching the very same inode therefore produced different keys, so `watch --git-staged` translated **nothing** when the index spelled a directory one way and the watcher saw another: silently, at exit 0. Where the file exists, the key is now its device + inode pair, which is its identity — verified on APFS that `docs/en.md` and `Docs/en.md`, and the NFC and NFD spellings of one name, all reach the same inode. This needs no platform guesswork in either direction: on a case-sensitive volume the other spelling does not exist, so the two paths keep distinct keys. `lstat` rather than `stat`, so a symlink stays a different file from its target; a path with no file yet falls back to the resolved string as before.
+
 - **sync**: **a target file that becomes unreadable mid-run is left alone, not overwritten from the source.** The pre-read went through `readTargetFile`, which separates *nothing is there* from *something is there this run could not open* and refuses the locale in the second case — but the write-time re-read that produces the reconstruct template was a bare `fs.readFile` whose `catch` fell back to the **source** as the template. A file that became unreadable in the window between the two was therefore reclassified as absent: no backup was taken (`targetExists` stayed false) and a source-derived file was written over the very target the run had just failed to read. Measured by revoking read permission on `de.json` from inside the engine reply, which is the one hook that runs between the two reads: the target gained the machine translation and lost its own state, at exit 0. The template now comes from the same guarded read, and an unreadable target aborts that locale exactly as the pre-read would — reported, with the file untouched. As part of this, a target holding only whitespace is now classified as present-but-empty rather than unusable: it has no translations to lose, and parsing it would fail (`JSON.parse('  ')` throws), which would otherwise refuse a locale over an empty file.
 
 - **sync**: **a run that removes a hand-added key from a locale file now says so.** `reconstruct` is handed the complete desired key set, so every run that rewrites a locale drops whatever the target holds that is not in that set. For a key the lockfile recorded, that is the intended prune of a key the source no longer defines. For a key **neither the source nor the lockfile accounts for** — one a translator added to the locale file by hand — it is someone else's data being deleted, and it happened with no mention in the run output, `sync status` or `sync validate`, while the `.deepl.bak` was unlinked on success: nothing said anything was lost and nothing was left to recover it from. Such keys are now named in a warning that points at both remedies (add them to the source, or recover them from the backup before the next run). The prune itself is deliberately unchanged — emitting exactly the keys the source defines is what makes deleting a removed key work — so this makes the behaviour visible rather than altering it. Note the distinction cannot be drawn from the lockfile at that point, because the run removes deleted keys' lock entries before the locale loop; it is drawn from the `deleted` diffs instead.
diff --git a/src/utils/paths.ts b/src/utils/paths.ts
index 51254d33..c60dd1d6 100644
--- a/src/utils/paths.ts
+++ b/src/utils/paths.ts
@@ -50,10 +50,33 @@ export function realpathOrAncestor(absPath: string): string {
  */
 export function canonicalPathKey(absPath: string): string {
   const resolved = path.resolve(absPath);
-  return path.join(
-    realpathOrAncestor(path.dirname(resolved)),
-    path.basename(resolved)
-  );
+
+  // Where the file exists, its device + inode pair IS its identity, and that is
+  // what makes two spellings of one file compare equal. The string form cannot:
+  // `fs.realpathSync` does not case-fold on a case-insensitive volume (APFS
+  // returns `Docs` for `Docs` even when the directory is stored as `docs`) and
+  // does not unify NFC with NFD. Both were measured on APFS as reaching the same
+  // inode while producing different strings, which made `watch --git-staged`
+  // translate nothing when git spelled a directory differently from the watcher —
+  // silently, at exit 0.
+  //
+  // `lstat`, not `stat`: a symlink has its own inode, which keeps the rule below
+  // that a symlink is a different file from its target. On a case-SENSITIVE
+  // volume the other spelling simply does not exist, so the two paths keep
+  // distinct keys — no platform guesswork in either direction.
+  //
+  // Callers only ever compare these keys with each other (`Set.has`, map keys),
+  // never treat one as a path, so an opaque key is safe. A path with no file yet
+  // has no inode and falls back to the resolved string.
+  try {
+    const stat = fs.lstatSync(resolved);
+    return `inode:${stat.dev}:${stat.ino}`;
+  } catch {
+    return path.join(
+      realpathOrAncestor(path.dirname(resolved)),
+      path.basename(resolved)
+    );
+  }
 }
 
 /**
diff --git a/tests/integration/watch-service.integration.test.ts b/tests/integration/watch-service.integration.test.ts
index 6101aecb..cb0ac9a1 100644
--- a/tests/integration/watch-service.integration.test.ts
+++ b/tests/integration/watch-service.integration.test.ts
@@ -4,6 +4,7 @@
  */
 
 import * as fs from 'fs';
+import { canonicalPathKey } from '../../src/utils/paths';
 import * as path from 'path';
 import * as os from 'os';
 
@@ -575,7 +576,7 @@ ${body}
       }
     };
 
-    it('should return staged file paths as absolute paths', () => {
+    it('identifies the staged file, and only it', () => {
       fs.writeFileSync(path.join(gitDir, 'file1.txt'), 'Hello');
       fs.writeFileSync(path.join(gitDir, 'file2.txt'), 'World');
       execSyncChild('git add file1.txt', { cwd: gitDir, stdio: 'ignore' });
@@ -588,10 +589,16 @@ console.log(JSON.stringify({ size: result.size, files: [...result] }));
 `
       );
 
+      // The set holds comparison keys, which are inode-based for a file that
+      // exists — so the assertion is which FILE was identified, computed the same
+      // way the watcher will compute it when a change arrives.
       const parsed = JSON.parse(output.trim());
       expect(parsed.size).toBe(1);
       expect(parsed.files[0]).toBe(
-        path.resolve(fs.realpathSync(gitDir), 'file1.txt')
+        canonicalPathKey(path.resolve(fs.realpathSync(gitDir), 'file1.txt'))
+      );
+      expect(parsed.files[0]).not.toBe(
+        canonicalPathKey(path.resolve(fs.realpathSync(gitDir), 'file2.txt'))
       );
     });
 
@@ -615,7 +622,9 @@ console.log(JSON.stringify({ files: [...result] }));
 
       const parsed = JSON.parse(output.trim());
       expect(parsed.files).toEqual([
-        path.join(fs.realpathSync(gitDir), 'docs', 'guide.md'),
+        canonicalPathKey(
+          path.join(fs.realpathSync(gitDir), 'docs', 'guide.md')
+        ),
       ]);
     });
 
@@ -638,7 +647,7 @@ console.log(JSON.stringify({ files: [...result] }));
 
         const parsed = JSON.parse(output.trim());
         expect(parsed.files).toEqual([
-          path.join(fs.realpathSync(gitDir), 'file1.txt'),
+          canonicalPathKey(path.join(fs.realpathSync(gitDir), 'file1.txt')),
         ]);
       } finally {
         fs.rmSync(otherRepo, { recursive: true, force: true });
@@ -666,7 +675,7 @@ console.log(JSON.stringify({ files: [...result] }));
 
         const parsed = JSON.parse(output.trim());
         expect(parsed.files).toEqual([
-          path.join(fs.realpathSync(gitDir), 'file1.txt'),
+          canonicalPathKey(path.join(fs.realpathSync(gitDir), 'file1.txt')),
         ]);
       } finally {
         fs.rmSync(linkParent, { recursive: true, force: true });
diff --git a/tests/unit/services/watch.test.ts b/tests/unit/services/watch.test.ts
index 8c1e8ebf..b03773f2 100644
--- a/tests/unit/services/watch.test.ts
+++ b/tests/unit/services/watch.test.ts
@@ -3,6 +3,7 @@
  */
 
 import * as fs from 'fs';
+import { canonicalPathKey } from '../../../src/utils/paths';
 import * as path from 'path';
 import * as os from 'os';
 import * as chokidar from 'chokidar';
@@ -965,13 +966,12 @@ describe('WatchService', () => {
   });
 
   describe('stagedFiles filtering', () => {
-    // git reports its files under the repository's real path, so a staged set
-    // is spelled with every symlinked ancestor resolved.
+    // The staged set holds the same comparison keys the watcher computes for an
+    // incoming change, so it is built with the same function rather than a
+    // hand-rolled copy of it — a copy is exactly what let a change to the key
+    // format go unnoticed here.
     const stagedEntry = (filePath: string): string =>
-      path.join(
-        fs.realpathSync(path.dirname(filePath)),
-        path.basename(filePath)
-      );
+      canonicalPathKey(filePath);
 
     it('should skip files not in stagedFiles set', async () => {
       const testFile = path.join(testDir, 'unstaged.txt');
@@ -1052,7 +1052,7 @@ describe('WatchService', () => {
       fs.writeFileSync(path.join(workDir, 'staged.txt'), 'Hello');
 
       const stagedService = new WatchService(mockFileTranslationService, {
-        stagedFiles: new Set([path.join(workDir, 'staged.txt')]),
+        stagedFiles: new Set([stagedEntry(path.join(workDir, 'staged.txt'))]),
       });
 
       const onChange = jest.fn();
@@ -1076,7 +1076,7 @@ describe('WatchService', () => {
       fs.writeFileSync(path.join(workDir, 'unstaged.txt'), 'Hello');
 
       const stagedService = new WatchService(mockFileTranslationService, {
-        stagedFiles: new Set([path.join(workDir, 'staged.txt')]),
+        stagedFiles: new Set([stagedEntry(path.join(workDir, 'staged.txt'))]),
       });
 
       const onChange = jest.fn();
@@ -1102,7 +1102,7 @@ describe('WatchService', () => {
       fs.symlinkSync(outside, linkedFile);
 
       const stagedService = new WatchService(mockFileTranslationService, {
-        stagedFiles: new Set([linkedFile]),
+        stagedFiles: new Set([stagedEntry(linkedFile)]),
       });
 
       const onChange = jest.fn();
diff --git a/tests/unit/utils/canonical-path-key.test.ts b/tests/unit/utils/canonical-path-key.test.ts
new file mode 100644
index 00000000..4024f9b2
--- /dev/null
+++ b/tests/unit/utils/canonical-path-key.test.ts
@@ -0,0 +1,127 @@
+/**
+ * Unit tests for `canonicalPathKey`, the comparison key that decides whether two
+ * spellings of a path denote the same file.
+ *
+ * `fs.realpathSync` does not case-fold on a case-insensitive volume — APFS
+ * returns `Docs` for `Docs` even when the directory is stored as `docs` — and
+ * does not unify NFC with NFD. Two spellings reaching the same inode therefore
+ * produced different keys, and `watch --git-staged` translated nothing when git
+ * spelled a directory differently from the watcher: silently, at exit 0.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { canonicalPathKey } from '../../../src/utils/paths';
+
+describe('canonicalPathKey', () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'canonical-key-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  /** Whether this filesystem reaches one file through two casings. */
+  function sameFileThroughBothCasings(a: string, b: string): boolean {
+    try {
+      const sa = fs.lstatSync(a);
+      const sb = fs.lstatSync(b);
+      return sa.ino === sb.ino && sa.dev === sb.dev;
+    } catch {
+      return false;
+    }
+  }
+
+  it('gives one key to two casings that reach the same file', () => {
+    fs.mkdirSync(path.join(root, 'docs'));
+    const lower = path.join(root, 'docs', 'en.md');
+    fs.writeFileSync(lower, 'hi');
+    const upper = path.join(root, 'Docs', 'en.md');
+
+    if (!sameFileThroughBothCasings(lower, upper)) {
+      // Case-sensitive volume: the two really are different paths, and the keys
+      // below are supposed to differ. Nothing to assert.
+      return;
+    }
+    expect(canonicalPathKey(lower)).toBe(canonicalPathKey(upper));
+  });
+
+  it('gives one key to the NFC and NFD spellings of a name', () => {
+    fs.mkdirSync(path.join(root, 'docs'));
+    const nfc = path.join(root, 'docs', 'café.md');
+    const nfd = path.join(root, 'docs', 'café.md');
+    fs.writeFileSync(nfc, 'hi');
+
+    if (!sameFileThroughBothCasings(nfc, nfd)) {
+      return;
+    }
+    expect(canonicalPathKey(nfc)).toBe(canonicalPathKey(nfd));
+  });
+
+  it('keeps different files apart', () => {
+    const a = path.join(root, 'a.md');
+    const b = path.join(root, 'b.md');
+    fs.writeFileSync(a, 'a');
+    fs.writeFileSync(b, 'b');
+
+    expect(canonicalPathKey(a)).not.toBe(canonicalPathKey(b));
+  });
+
+  it('keeps two files with identical content apart', () => {
+    const a = path.join(root, 'a.md');
+    const b = path.join(root, 'b.md');
+    fs.writeFileSync(a, 'same');
+    fs.writeFileSync(b, 'same');
+
+    expect(canonicalPathKey(a)).not.toBe(canonicalPathKey(b));
+  });
+
+  it('treats a symlink as a different file from its target', () => {
+    const target = path.join(root, 'target.md');
+    const link = path.join(root, 'link.md');
+    fs.writeFileSync(target, 'hi');
+    fs.symlinkSync(target, link);
+
+    expect(canonicalPathKey(link)).not.toBe(canonicalPathKey(target));
+  });
+
+  it('resolves a symlinked ancestor so both routes to a file agree', () => {
+    const real = path.join(root, 'real');
+    fs.mkdirSync(real);
+    fs.writeFileSync(path.join(real, 'en.md'), 'hi');
+    const linkDir = path.join(root, 'via');
+    fs.symlinkSync(real, linkDir);
+
+    expect(canonicalPathKey(path.join(linkDir, 'en.md'))).toBe(
+      canonicalPathKey(path.join(real, 'en.md'))
+    );
+  });
+
+  it('is stable for a path that does not exist yet', () => {
+    const missing = path.join(root, 'not-written-yet.md');
+    expect(canonicalPathKey(missing)).toBe(canonicalPathKey(missing));
+  });
+
+  it('separates two paths that do not exist yet', () => {
+    expect(canonicalPathKey(path.join(root, 'x.md'))).not.toBe(
+      canonicalPathKey(path.join(root, 'y.md'))
+    );
+  });
+
+  it('agrees with itself across a relative and an absolute spelling', () => {
+    const file = path.join(root, 'en.md');
+    fs.writeFileSync(file, 'hi');
+    const cwd = process.cwd();
+    try {
+      process.chdir(root);
+      expect(canonicalPathKey('en.md')).toBe(canonicalPathKey(file));
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+});

From 45a54ea4b7b14ca0b86087399ab20d7b3aedc2b9 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 15:42:07 +0200
Subject: [PATCH 214/256] perf(po,sync): make the comment backtrack linear and
 cap the target read

Two defects filed together.

reconstruct collected the run of comment lines above an entry by walking
backwards and unshifting each line, and unshift re-indexes the whole array
per call -- so the cost grew with the square of the run's length. Measured
28 ms at 20k comment lines, 109 ms at 40k, 437 ms at 80k: four times the
time for twice the input, extrapolating to the ~47 s reported. The run is
now taken with one slice: 80k lines take 11 ms and growth is linear.

max_file_bytes was enforced on source files only, so a target -- the file a
hostile or corrupt checkout actually controls -- was parsed and rebuilt at
any size. readTargetFile now takes an optional cap, wired from
resolveSyncLimits at all six call sites, and reports an oversized target
`unusable` so the locale is refused rather than treated as empty,
re-translated in full and overwritten.

The size is checked on the content read rather than through a separate
stat: the cap exists to bound the parse, reconstruct and comparison work
that follows, and a second syscall broke 119 tests that mock readFile
alone. Node's own string-length ceiling bounds the read and surfaces as a
catchable error.

Refs cli-8zn5.27
---
 CHANGELOG.md                                 |  4 +
 src/formats/po.ts                            |  9 ++-
 src/sync/sync-locale-translator.ts           |  4 +-
 src/sync/sync-process-bucket.ts              |  8 +-
 src/sync/sync-review-flags.ts                |  8 +-
 src/sync/sync-target-audit.ts                |  8 +-
 src/sync/sync-target-read.ts                 | 21 ++++-
 src/sync/sync-tms.ts                         |  8 +-
 src/sync/sync-validate.ts                    |  8 +-
 tests/unit/sync/sync-target-read-cap.test.ts | 81 ++++++++++++++++++++
 10 files changed, 150 insertions(+), 9 deletions(-)
 create mode 100644 tests/unit/sync/sync-target-read-cap.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0a3f9223..d458e6e9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **po**: **rebuilding a catalog is linear in the length of a comment block again, instead of quadratic.** `reconstruct` collected the run of comment lines above an entry by walking backwards and `unshift`ing each line onto an array — and `unshift` re-indexes the whole array on every call, so the cost grew with the square of the run's length. Measured: 20k comment lines took 28 ms, 40k took 109 ms and 80k took 437 ms — four times the time for twice the input — which extrapolates to the ~47 seconds reported for a large catalog. The run is now taken with a single slice: the same 80k lines take **11 ms**, and the growth is linear.
+
+- **sync**: **`sync.limits.max_file_bytes` now applies to target files, not only source files.** A target is the file a hostile or corrupt checkout actually controls, and it was parsed and rebuilt at any size. An oversized target is now reported `unusable` — refused, with the reason naming the limit — rather than treated as empty, which is what would otherwise re-translate the locale in full and then overwrite the file. The size is checked on the content that was read rather than through a separate `stat`, because the cap's purpose is to bound the parse, reconstruct and comparison work that follows; Node's own string-length ceiling bounds the read itself and surfaces as a catchable error.
+
 - **watch**: **`--git-staged` recognises a staged file when git and the watcher spell its path differently.** The path comparison key resolved symlinked ancestors but nothing else, and `fs.realpathSync` **does not** case-fold on a case-insensitive volume — measured on APFS, `realpathSync` returns `Docs` for `Docs` even when the directory is stored as `docs` — nor does it unify NFC with NFD. Two spellings reaching the very same inode therefore produced different keys, so `watch --git-staged` translated **nothing** when the index spelled a directory one way and the watcher saw another: silently, at exit 0. Where the file exists, the key is now its device + inode pair, which is its identity — verified on APFS that `docs/en.md` and `Docs/en.md`, and the NFC and NFD spellings of one name, all reach the same inode. This needs no platform guesswork in either direction: on a case-sensitive volume the other spelling does not exist, so the two paths keep distinct keys. `lstat` rather than `stat`, so a symlink stays a different file from its target; a path with no file yet falls back to the resolved string as before.
 
 - **sync**: **a target file that becomes unreadable mid-run is left alone, not overwritten from the source.** The pre-read went through `readTargetFile`, which separates *nothing is there* from *something is there this run could not open* and refuses the locale in the second case — but the write-time re-read that produces the reconstruct template was a bare `fs.readFile` whose `catch` fell back to the **source** as the template. A file that became unreadable in the window between the two was therefore reclassified as absent: no backup was taken (`targetExists` stayed false) and a source-derived file was written over the very target the run had just failed to read. Measured by revoking read permission on `de.json` from inside the engine reply, which is the one hook that runs between the two reads: the target gained the machine translation and lost its own state, at exit 0. The template now comes from the same guarded read, and an unreadable target aborts that locale exactly as the pre-read would — reported, with the file untouched. As part of this, a target holding only whitespace is now classified as present-but-empty rather than unusable: it has no translations to lose, and parsing it would fail (`JSON.parse('  ')` throws), which would otherwise refuse a locale over an empty file.
diff --git a/src/formats/po.ts b/src/formats/po.ts
index bffce882..8993f263 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -538,7 +538,6 @@ export class PoFormatParser implements FormatParser {
         continue;
       }
 
-      const commentLines: string[] = [];
       const entryLines: string[] = [];
       let entryMsgctxt: string | undefined;
       let entryMsgid = '';
@@ -546,11 +545,17 @@ export class PoFormatParser implements FormatParser {
       const entryMsgstrPlural = new Map<number, string>();
       let target: ParseTarget | undefined;
 
+      // The run of comment lines immediately above the entry, taken with one
+      // slice. Walking backwards and `unshift`ing each line made this quadratic
+      // in the length of the run — `unshift` re-indexes the whole array every
+      // call — so a target file carrying one long comment block cost minutes:
+      // measured 28 ms at 20k comment lines, 109 ms at 40k and 437 ms at 80k,
+      // which is 4x the time for 2x the input.
       let backtrack = result.length - 1;
       while (backtrack >= 0 && result[backtrack]!.startsWith('#')) {
-        commentLines.unshift(result[backtrack]!);
         backtrack--;
       }
+      const commentLines: string[] = result.slice(backtrack + 1);
 
       while (i < lines.length) {
         const el = lines[i];
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 45952ec1..5f25b7a5 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -7,6 +7,7 @@ import type { TranslationResult } from '../api/translation-client.js';
 import type { Language } from '../types/common.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncBucketConfig, SyncDiff, SyncLockEntry } from './types.js';
+import { resolveSyncLimits } from './types.js';
 import type { KeyContext } from './sync-context.js';
 import { sectionContextKey, sectionToContext } from './sync-context.js';
 import {
@@ -1027,7 +1028,8 @@ export class LocaleTranslator {
     const templateRead = await readTargetFile(
       parser,
       targetAbsPath,
-      isMultiLocale ? locale : undefined
+      isMultiLocale ? locale : undefined,
+      resolveSyncLimits(config).max_file_bytes
     );
     if (templateRead.state === 'unusable') {
       throw new Error(
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index 145decc6..b71dafc4 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -1,4 +1,5 @@
 import * as path from 'path';
+import { resolveSyncLimits } from './types.js';
 import { computeDiff } from './sync-differ.js';
 import {
   mapWithConcurrency,
@@ -380,7 +381,12 @@ export async function processBucket(
       );
       const targetAbsPath = path.join(config.projectRoot, targetRelPath);
       assertPathWithinRoot(targetAbsPath, config.projectRoot);
-      const read = await readTargetFile(parser, targetAbsPath);
+      const read = await readTargetFile(
+        parser,
+        targetAbsPath,
+        undefined,
+        resolveSyncLimits(config).max_file_bytes
+      );
       if (read.state === 'unusable') {
         unusableTargets.set(
           locale,
diff --git a/src/sync/sync-review-flags.ts b/src/sync/sync-review-flags.ts
index cc160b3c..14533476 100644
--- a/src/sync/sync-review-flags.ts
+++ b/src/sync/sync-review-flags.ts
@@ -1,4 +1,5 @@
 import * as path from 'path';
+import { resolveSyncLimits } from './types.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
 import type { WalkedBucketFile } from './sync-bucket-walker.js';
@@ -45,7 +46,12 @@ export async function findNeedsReview(
     );
     const targetAbsPath = path.join(config.projectRoot, targetRelPath);
     assertPathWithinRoot(targetAbsPath, config.projectRoot);
-    const read = await readTargetFile(walked.parser, targetAbsPath, locale);
+    const read = await readTargetFile(
+      walked.parser,
+      targetAbsPath,
+      locale,
+      resolveSyncLimits(config).max_file_bytes
+    );
     if (read.state !== 'usable') continue;
 
     const keys = extractNeedsReview.call(walked.parser, read.content, locale);
diff --git a/src/sync/sync-target-audit.ts b/src/sync/sync-target-audit.ts
index 8aceeb1e..44f7576a 100644
--- a/src/sync/sync-target-audit.ts
+++ b/src/sync/sync-target-audit.ts
@@ -1,4 +1,5 @@
 import * as path from 'path';
+import { resolveSyncLimits } from './types.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncLockEntry } from './types.js';
 import { getOwnMember } from '../utils/own-members.js';
@@ -104,7 +105,12 @@ export async function findTargetGaps(
       );
       const targetAbsPath = path.join(config.projectRoot, targetRelPath);
       assertPathWithinRoot(targetAbsPath, config.projectRoot);
-      const read = await readTargetFile(walked.parser, targetAbsPath);
+      const read = await readTargetFile(
+        walked.parser,
+        targetAbsPath,
+        undefined,
+        resolveSyncLimits(config).max_file_bytes
+      );
       if (read.state === 'usable') held = read.translations;
       if (read.state === 'unusable') unusable = read.reason;
     }
diff --git a/src/sync/sync-target-read.ts b/src/sync/sync-target-read.ts
index f3c04cf9..b1e0342b 100644
--- a/src/sync/sync-target-read.ts
+++ b/src/sync/sync-target-read.ts
@@ -27,7 +27,8 @@ export type TargetFileRead =
 export async function readTargetFile(
   parser: FormatParser,
   absPath: string,
-  locale?: string
+  locale?: string,
+  maxBytes?: number
 ): Promise<TargetFileRead> {
   let content: string;
   try {
@@ -41,6 +42,24 @@ export async function readTargetFile(
     }
     return { state: 'unusable', reason: describe(err), error: err };
   }
+  // `max_file_bytes` was enforced on SOURCE files only, so a target — the file a
+  // hostile or corrupt checkout actually controls — was parsed and rebuilt at any
+  // size. Reported as `unusable` rather than skipped, so the locale is refused
+  // instead of being treated as empty, re-translated in full and overwritten.
+  //
+  // Checked on the content rather than through a separate `stat`: the cap's
+  // purpose is to bound the parse, the reconstruct and the comparison work that
+  // follow, which is where the cost was (a target with one long comment block
+  // took 47 seconds). Node's own string-length ceiling bounds the read itself,
+  // and it surfaces as a catchable error above.
+  if (maxBytes !== undefined && Buffer.byteLength(content, 'utf8') > maxBytes) {
+    return {
+      state: 'unusable',
+      reason: `file size ${Buffer.byteLength(content, 'utf8')} bytes exceeds sync.limits.max_file_bytes (${maxBytes})`,
+      error: undefined,
+    };
+  }
+
   // A file holding only whitespace has no translations to lose, so `unusable` —
   // whose whole point is that the file holds the only copy of this locale's work
   // — does not describe it. Parsing it would fail for most formats
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index 78c2ca38..c0e613fe 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -1,4 +1,5 @@
 import * as fs from 'fs';
+import { resolveSyncLimits } from './types.js';
 import * as path from 'path';
 import {
   FormatKeyCollisionError,
@@ -287,7 +288,12 @@ export async function pullTranslations(
       // source template, which would rebuild it from source text and discard
       // every local translation the export does not carry. Only a file that is
       // genuinely not there yet takes that fallback.
-      const read = await readTargetFile(parser, targetAbsPath, locale);
+      const read = await readTargetFile(
+        parser,
+        targetAbsPath,
+        locale,
+        resolveSyncLimits(config).max_file_bytes
+      );
       if (read.state === 'unusable') {
         Logger.warn(`Skipping ${targetRelPath}: ${read.reason}`);
         skipped.push({
diff --git a/src/sync/sync-validate.ts b/src/sync/sync-validate.ts
index f502ba66..ee50425d 100644
--- a/src/sync/sync-validate.ts
+++ b/src/sync/sync-validate.ts
@@ -1,4 +1,5 @@
 import * as path from 'path';
+import { resolveSyncLimits } from './types.js';
 import type { FormatRegistry } from '../formats/index.js';
 import {
   validateBatch,
@@ -66,7 +67,12 @@ export async function validateTranslations(
         const targetAbsPath = path.join(config.projectRoot, targetRelPath);
         assertPathWithinRoot(targetAbsPath, config.projectRoot);
 
-        const read = await readTargetFile(parser, targetAbsPath);
+        const read = await readTargetFile(
+          parser,
+          targetAbsPath,
+          undefined,
+          resolveSyncLimits(config).max_file_bytes
+        );
         if (read.state === 'absent') {
           // A locale that has never been synced has nothing to validate.
           continue;
diff --git a/tests/unit/sync/sync-target-read-cap.test.ts b/tests/unit/sync/sync-target-read-cap.test.ts
new file mode 100644
index 00000000..895d0d71
--- /dev/null
+++ b/tests/unit/sync/sync-target-read-cap.test.ts
@@ -0,0 +1,81 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { readTargetFile } from '../../../src/sync/sync-target-read';
+import { JsonFormatParser } from '../../../src/formats/json';
+
+/**
+ * Unit tests for the target-file read cap.
+ */
+
+describe('oversized target file', () => {
+  // `max_file_bytes` was enforced on source files only, so a target — the file a
+  // hostile or corrupt checkout actually controls — was parsed and rebuilt at any
+  // size. It is refused rather than treated as empty, which is what would
+  // otherwise re-translate the locale in full and overwrite the file.
+  it('is refused rather than read as empty', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-target-cap-'));
+    try {
+      const target = path.join(dir, 'de.json');
+      fs.writeFileSync(
+        target,
+        JSON.stringify({ greeting: 'x'.repeat(5000) }),
+        'utf-8'
+      );
+
+      const read = await readTargetFile(
+        new JsonFormatParser(),
+        target,
+        undefined,
+        1024
+      );
+
+      expect(read.state).toBe('unusable');
+      if (read.state === 'unusable') {
+        expect(read.reason).toMatch(/max_file_bytes/);
+      }
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('reads a target inside the cap normally', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-target-cap-'));
+    try {
+      const target = path.join(dir, 'de.json');
+      fs.writeFileSync(target, JSON.stringify({ greeting: 'Hallo' }), 'utf-8');
+
+      const read = await readTargetFile(
+        new JsonFormatParser(),
+        target,
+        undefined,
+        1024
+      );
+
+      expect(read.state).toBe('usable');
+      if (read.state === 'usable') {
+        expect(read.translations.get('greeting')).toBe('Hallo');
+      }
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('applies no cap when none is given', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-target-cap-'));
+    try {
+      const target = path.join(dir, 'de.json');
+      fs.writeFileSync(
+        target,
+        JSON.stringify({ greeting: 'x'.repeat(5000) }),
+        'utf-8'
+      );
+
+      const read = await readTargetFile(new JsonFormatParser(), target);
+      expect(read.state).toBe('usable');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

From ab8e95516b886f5f1937f70178196d759799e882 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 15:48:29 +0200
Subject: [PATCH 215/256] fix(translate): choose placeholder tokens the source
 does not already contain

Preservation tokens came from a plain counter, so text carrying a literal
__VAR_0__ -- ordinary content, not a variable -- could be handed the same
token as a real {name}. Two occurrences went to the engine and
restorePlaceholders uses replaceAll, so the literal copy came back as
{name} as well: 'literal __VAR_0__ and {name}' round-tripped to
'literal {name} and {name}'.

The same collision made unresolvedPlaceholders accept the literal copy as
evidence the substituted token had survived, so an engine that mangled the
real token had a genuine loss reported as intact.

Tokens are now picked to avoid anything the source text already carries,
for both the __VAR_ and __CODE_ families, compared against the original
text so tokens this pass created are not skipped. The low numbers are
still used when the source carries none.

A property test had been documenting the corruption as its expected
output; it now asserts the round trip.

Refs cli-8zn5.19
---
 CHANGELOG.md                                  |  2 +
 src/utils/text-preservation.ts                | 37 +++++++++++--
 .../text-preservation.property.test.ts        | 12 ++---
 tests/unit/text-preservation.test.ts          | 52 +++++++++++++++++++
 4 files changed, 92 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d458e6e9..17457211 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **translate**: **a source string that literally contains the CLI's own placeholder token is no longer corrupted, and a genuinely lost token is no longer reported as intact.** Preservation tokens came from a plain counter, so text carrying a literal `__VAR_0__` — ordinary content, not a variable — could be handed the *same* token as a real `{name}`. Two occurrences then went to the engine, and `restorePlaceholders` uses `replaceAll`, so the literal copy came back as `{name}` too: `'literal __VAR_0__ and {name}'` round-tripped to `'literal {name} and {name}'`. The same collision made the loss check accept the literal copy as evidence that the substituted token had survived, so an engine that mangled the real token had a genuine loss reported as intact. Tokens are now chosen to avoid any that the source text already contains, for both the `__VAR_` and `__CODE_` families, and the low numbers are still used when the source carries none. A property test that had been *documenting* the corruption as expected output now asserts the round trip.
+
 - **po**: **rebuilding a catalog is linear in the length of a comment block again, instead of quadratic.** `reconstruct` collected the run of comment lines above an entry by walking backwards and `unshift`ing each line onto an array — and `unshift` re-indexes the whole array on every call, so the cost grew with the square of the run's length. Measured: 20k comment lines took 28 ms, 40k took 109 ms and 80k took 437 ms — four times the time for twice the input — which extrapolates to the ~47 seconds reported for a large catalog. The run is now taken with a single slice: the same 80k lines take **11 ms**, and the growth is linear.
 
 - **sync**: **`sync.limits.max_file_bytes` now applies to target files, not only source files.** A target is the file a hostile or corrupt checkout actually controls, and it was parsed and rebuilt at any size. An oversized target is now reported `unusable` — refused, with the reason naming the limit — rather than treated as empty, which is what would otherwise re-translate the locale in full and then overwrite the file. The size is checked on the content that was read rather than through a separate `stat`, because the cap's purpose is to bound the parse, reconstruct and comparison work that follows; Node's own string-length ceiling bounds the read itself and surfaces as a catchable error.
diff --git a/src/utils/text-preservation.ts b/src/utils/text-preservation.ts
index b270e3a1..064a42a8 100644
--- a/src/utils/text-preservation.ts
+++ b/src/utils/text-preservation.ts
@@ -5,23 +5,50 @@
 
 import { NetworkError } from './errors.js';
 
+/**
+ * The next placeholder token that does not already occur in `text`.
+ *
+ * The tokens are generated from a counter, so a source string carrying a literal
+ * `__VAR_0__` — which is ordinary text, not a variable — could be handed the same
+ * token as a real variable. Two occurrences then went to the engine and
+ * `restorePlaceholders` uses `replaceAll`, so the literal copy was rewritten into
+ * the preserved value. The same collision made `unresolvedPlaceholders` accept
+ * the literal copy as proof the substituted token had survived, reporting a
+ * genuine loss as intact.
+ *
+ * Compared against the ORIGINAL text, never the partly-substituted text: tokens
+ * this pass has already created are absent from the original, so they are not
+ * skipped, while anything the caller's own content carries is.
+ */
+function nextFreeToken(
+  prefix: string,
+  counter: { next: number },
+  text: string
+): string {
+  let token = `__${prefix}_${counter.next++}__`;
+  while (text.includes(token)) {
+    token = `__${prefix}_${counter.next++}__`;
+  }
+  return token;
+}
+
 export function preserveCodeBlocks(
   text: string,
   preservationMap: Map<string, string>
 ): string {
   let processed = text;
-  let counter = 0;
+  const counter = { next: 0 };
 
   // Preserve multi-line code blocks (```)
   processed = processed.replace(/```[\s\S]*?```/g, (match) => {
-    const placeholder = `__CODE_${counter++}__`;
+    const placeholder = nextFreeToken('CODE', counter, text);
     preservationMap.set(placeholder, match);
     return placeholder;
   });
 
   // Preserve inline code blocks (`)
   processed = processed.replace(/`[^`]+`/g, (match) => {
-    const placeholder = `__CODE_${counter++}__`;
+    const placeholder = nextFreeToken('CODE', counter, text);
     preservationMap.set(placeholder, match);
     return placeholder;
   });
@@ -34,7 +61,7 @@ export function preserveVariables(
   preservationMap: Map<string, string>
 ): string {
   let processed = text;
-  let counter = 0;
+  const counter = { next: 0 };
 
   // Preserve various variable formats (order matters - longest match first)
   const patterns = [
@@ -47,7 +74,7 @@ export function preserveVariables(
 
   for (const pattern of patterns) {
     processed = processed.replace(pattern, (match) => {
-      const placeholder = `__VAR_${counter++}__`;
+      const placeholder = nextFreeToken('VAR', counter, text);
       preservationMap.set(placeholder, match);
       return placeholder;
     });
diff --git a/tests/property/text-preservation.property.test.ts b/tests/property/text-preservation.property.test.ts
index 3a8ea0f2..62d7bd55 100644
--- a/tests/property/text-preservation.property.test.ts
+++ b/tests/property/text-preservation.property.test.ts
@@ -83,13 +83,13 @@ describe('text preservation properties', () => {
   });
 
   describe('directed: literal placeholder tokens in input', () => {
-    it('documents the collision: a literal __VAR_0__ in the source is rewritten on restore', () => {
+    it('round-trips a literal __VAR_0__ in the source', () => {
+      // A token shape appearing in the source is ordinary text. Handing the same
+      // token to a real variable put two occurrences in the request, and
+      // restorePlaceholders replaces all of them — so the literal copy became
+      // `{name}`. Tokens are now chosen to avoid whatever the source carries.
       const text = 'literal __VAR_0__ and {name}';
-      const result = roundTrip(text);
-      // Intended behavior would be result === text. Recording the actual
-      // (corrupting) behavior so the failure mode is pinned with a repro.
-      expect(result).toBe('literal {name} and {name}');
-      expect(result).not.toBe(text);
+      expect(roundTrip(text)).toBe(text);
     });
   });
 });
diff --git a/tests/unit/text-preservation.test.ts b/tests/unit/text-preservation.test.ts
index e2edf98d..b905e0bb 100644
--- a/tests/unit/text-preservation.test.ts
+++ b/tests/unit/text-preservation.test.ts
@@ -266,3 +266,55 @@ describe('text-preservation', () => {
     });
   });
 });
+
+describe("a source that literally contains the CLI's own token shape", () => {
+  // The tokens are generated by a plain counter, so a source string carrying a
+  // literal `__VAR_0__` could be handed the SAME token for a real variable. Two
+  // occurrences then went to the engine, and restorePlaceholders uses replaceAll
+  // — so the literal copy was rewritten into the preserved value. It also made
+  // the loss check accept the literal copy as proof the substituted token
+  // survived, reporting a genuine loss as intact.
+  it('round-trips a literal __VAR_0__ alongside a real variable', () => {
+    const map = new Map<string, string>();
+    const source = 'Hi {name}, the token __VAR_0__ is literal text';
+    const restored = restorePlaceholders(preserveVariables(source, map), map);
+    expect(restored).toBe(source);
+  });
+
+  it('does not give a real variable a token the source already contains', () => {
+    const map = new Map<string, string>();
+    preserveVariables('__VAR_0__ and {name}', map);
+    expect([...map.keys()]).not.toContain('__VAR_0__');
+    expect(map.size).toBe(1);
+  });
+
+  it('skips a whole run of tokens the source contains', () => {
+    const map = new Map<string, string>();
+    const source = '__VAR_0__ __VAR_1__ __VAR_2__ {a} {b}';
+    const restored = restorePlaceholders(preserveVariables(source, map), map);
+    expect(restored).toBe(source);
+    expect(map.size).toBe(2);
+  });
+
+  it('reports a dropped token even when a literal copy survives', () => {
+    const map = new Map<string, string>();
+    const processed = preserveVariables('__VAR_0__ and {name}', map);
+    const token = [...map.keys()][0]!;
+    // The engine mangles the substituted token but leaves the literal text.
+    const mangled = processed.replace(token, '__ Var_x __');
+    expect(unresolvedPlaceholders(mangled, map)).toEqual(['{name}']);
+  });
+
+  it('round-trips a literal __CODE_0__ alongside a real code span', () => {
+    const map = new Map<string, string>();
+    const source = 'see `code` and the literal __CODE_0__ token';
+    const restored = restorePlaceholders(preserveCodeBlocks(source, map), map);
+    expect(restored).toBe(source);
+  });
+
+  it('still uses the low token numbers when the source contains none', () => {
+    const map = new Map<string, string>();
+    preserveVariables('{a} {b}', map);
+    expect([...map.keys()]).toEqual(['__VAR_0__', '__VAR_1__']);
+  });
+});

From f0d61d46a03c2763fe6aefca5b2be2d6eaf78e45 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 16:36:19 +0200
Subject: [PATCH 216/256] fix(sync): treat msgid_plural alone as a plural entry
 on pull

`plural_forms` metadata only appears once an entry HAS msgstr[N] lines, so
a freshly extracted gettext plural entry carries msgid_plural on its own.
Judging plurality from the payload made `sync pull` treat such an entry as
an ordinary key: one exported string cannot fill a plural entry's forms,
so the pull recorded a translation it had not applied.

A new isPluralEntry predicate adds msgid_plural to the test.
PLURAL_FORM_METADATA_KEYS is deliberately left alone, because that list is
what withoutPluralForms STRIPS -- stripping msgid_plural would tell
reconstruct the entry is not plural, which is how the carry-forward and the
new-entry append both know to emit msgid_plural and its msgstr[N] forms.

Refs cli-8zn5.28 (L7)
---
 src/sync/sync-tms.ts                          |  4 +-
 src/sync/sync-utils.ts                        | 31 +++++++++++
 .../integration/sync-tms.integration.test.ts  | 51 +++++++++++++++++++
 3 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index c0e613fe..109d2442 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -18,7 +18,7 @@ import {
   resolveTargetPath,
   assertPathWithinRoot,
   mergePulledTranslations,
-  hasPluralForms,
+  isPluralEntry,
 } from './sync-utils.js';
 import { LOCK_FILE_NAME } from './types.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
@@ -317,7 +317,7 @@ export async function pullTranslations(
       // reported skipped and the entry is carried forward as it stands.
       const pluralEntries = sourceEntries.filter(
         (entry) =>
-          keys[entry.key] !== undefined && hasPluralForms(entry.metadata)
+          keys[entry.key] !== undefined && isPluralEntry(entry.metadata)
       );
       // Preserve the null prototype `sanitizePullKeysResponse` gave `keys`: a
       // plain-object spread would re-expose Object.prototype, so a source key
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index 29558539..b764254b 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -23,6 +23,37 @@ export function getParserForBucket(
  */
 const PLURAL_FORM_METADATA_KEYS = ['plural_forms', 'plurals'] as const;
 
+/**
+ * The metadata that makes an entry a plural entry at all, whether or not it
+ * currently carries the forms.
+ *
+ * A gettext entry declares `msgid_plural` even when it has no `msgstr[N]` lines
+ * yet — a freshly extracted catalog is exactly that shape, since `plural_forms`
+ * only appears once forms exist. Judging plurality from the payload alone let
+ * `deepl sync pull` treat such an entry as ordinary: one exported string cannot
+ * fill a plural entry's forms, so the pull recorded a translation it had not
+ * applied.
+ *
+ * Kept separate from `PLURAL_FORM_METADATA_KEYS`, which lists the payloads to
+ * STRIP. Stripping `msgid_plural` would tell `reconstruct` the entry is not
+ * plural at all, and that is how both the carry-forward and the new-entry append
+ * know to emit `msgid_plural` and one `msgstr[N]` per form.
+ */
+const PLURAL_ENTRY_METADATA_KEYS = [
+  ...PLURAL_FORM_METADATA_KEYS,
+  'msgid_plural',
+] as const;
+
+/** True when the entry is a plural entry in its format's terms. */
+export function isPluralEntry(
+  metadata: Record<string, unknown> | undefined
+): boolean {
+  return (
+    metadata !== undefined &&
+    PLURAL_ENTRY_METADATA_KEYS.some((key) => key in metadata)
+  );
+}
+
 /**
  * True when `reconstruct` would rebuild this entry's plural forms from its
  * metadata rather than keep the ones the target file holds.
diff --git a/tests/integration/sync-tms.integration.test.ts b/tests/integration/sync-tms.integration.test.ts
index e1a363d6..c2f5b726 100644
--- a/tests/integration/sync-tms.integration.test.ts
+++ b/tests/integration/sync-tms.integration.test.ts
@@ -120,6 +120,57 @@ describe('sync push/pull (TMS integration)', () => {
     expect(targetContent['notice']).toBe('Zeile eins\nZeile zwei\tmit Tab[31m');
   });
 
+  it('pull: skips a plural entry that declares msgid_plural but holds no msgstr[N]', async () => {
+    // `plural_forms` metadata only appears once an entry HAS msgstr[N] lines, so a
+    // freshly extracted plural entry carries `msgid_plural` alone. Judging
+    // plurality from the payload made pull treat it as an ordinary key: one
+    // exported string cannot fill a plural entry's forms, so the pull reported a
+    // translation it had not applied.
+    writeSyncConfig(tmpDir, {
+      targetLocales: ['de'],
+      tms: tmsConfig(),
+      buckets: { po: { include: ['locales/en/app.po'] } },
+    });
+    const poHarness = createSyncHarness({ parsers: ['po'] });
+    try {
+      const source = path.join(tmpDir, 'locales', 'en', 'app.po');
+      fs.mkdirSync(path.dirname(source), { recursive: true });
+      fs.writeFileSync(
+        source,
+        [
+          'msgid ""',
+          'msgstr ""',
+          '"Content-Type: text/plain; charset=UTF-8\\n"',
+          '"Plural-Forms: nplurals=2; plural=(n != 1);\\n"',
+          '',
+          'msgid "One file"',
+          'msgid_plural "%d files"',
+          '',
+        ].join('\n'),
+        'utf-8'
+      );
+      const target = path.join(tmpDir, 'locales', 'de', 'app.po');
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(source, target);
+
+      process.env['TMS_API_KEY'] = 'env-key';
+      const config = await loadSyncConfig(tmpDir);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+      expectTmsPull(
+        'de',
+        { 'One file': 'Eine Datei' },
+        { auth: { apiKey: 'env-key' } }
+      );
+
+      const result = await pullTranslations(config, client, poHarness.registry);
+
+      expect(result.pulled).toBe(0);
+      expect(result.skipped.map((s) => s.reason)).toEqual(['plural_entry']);
+    } finally {
+      poHarness.cleanup();
+    }
+  });
+
   // ---- Case 2: pull happy path ----
   it('pull: fetches translations, writes target file, and does not claim human review', async () => {
     writeSyncConfig(tmpDir, { targetLocales: ['de'], tms: tmsConfig() });

From 52e11d63ead63d3361245030be0ae7c760a7a25b Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 17:02:05 +0200
Subject: [PATCH 217/256] fix(po): read a value containing U+2028 or U+2029

JS `.` excludes the line separators, so a msgstr carrying either did not
match its own line pattern at all: the line was invisible to both
scanners, the key was reported unwritten -- honestly, at exit 12 -- but
under a remediation about adding a containing group, and no later run
could converge.

The value-capturing line patterns now carry the `s` flag.

Deliberately NOT the remedy the report suggested. It proposed escaping
these the way toml.ts does, but the PO escape set has no \uXXXX, so an
escape would round-trip back as the literal text `u2028`. gettext accepts
the byte raw -- verified, `msgfmt -c` exits 0 on such a catalog -- so the
file was valid and it was this parser that could not read it.

Refs cli-8zn5.28 (L5)
---
 src/formats/po.ts             | 38 +++++++++++++++---------
 tests/unit/formats/po.test.ts | 54 +++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+), 13 deletions(-)

diff --git a/src/formats/po.ts b/src/formats/po.ts
index 8993f263..9c3417b1 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -218,6 +218,18 @@ function startsNextEntry(
   );
 }
 
+/**
+ * The value-capturing line patterns below all carry the `s` flag.
+ *
+ * Without it `.` excludes U+2028 and U+2029, so a `msgstr` carrying either did
+ * not match its own pattern at all: the line was invisible to both scanners, the
+ * key was reported unwritten — honestly, at exit 12 — but under a remediation
+ * about adding a containing group, and no later run could converge. gettext
+ * itself accepts the byte raw (`msgfmt -c` exits 0 on such a catalog), so the
+ * file is valid and it was this parser that could not read it. Escaping is not an
+ * option the way it is for TOML: the PO escape set has no `\uXXXX`, so an escape
+ * would round-trip back as the literal text.
+ */
 function parseEntries(content: string): PoEntry[] {
   const lines = content.split(/\r?\n/);
   const entries: PoEntry[] = [];
@@ -273,7 +285,7 @@ function parseEntries(content: string): PoEntry[] {
       continue;
     }
 
-    const msgctxtMatch = /^msgctxt\s+(.*)$/.exec(line);
+    const msgctxtMatch = /^msgctxt\s+(.*)$/s.exec(line);
     if (msgctxtMatch?.[1]) {
       current.msgctxt = unquote(msgctxtMatch[1]);
       target = 'msgctxt';
@@ -281,7 +293,7 @@ function parseEntries(content: string): PoEntry[] {
       continue;
     }
 
-    const msgidPluralMatch = /^msgid_plural\s+(.*)$/.exec(line);
+    const msgidPluralMatch = /^msgid_plural\s+(.*)$/s.exec(line);
     if (msgidPluralMatch?.[1]) {
       current.msgidPlural = unquote(msgidPluralMatch[1]);
       target = 'msgid_plural';
@@ -289,7 +301,7 @@ function parseEntries(content: string): PoEntry[] {
       continue;
     }
 
-    const msgidMatch = /^msgid\s+(.*)$/.exec(line);
+    const msgidMatch = /^msgid\s+(.*)$/s.exec(line);
     if (msgidMatch?.[1]) {
       current.msgid = unquote(msgidMatch[1]);
       target = 'msgid';
@@ -297,7 +309,7 @@ function parseEntries(content: string): PoEntry[] {
       continue;
     }
 
-    const msgstrPluralMatch = /^msgstr\[(\d+)]\s+(.*)$/.exec(line);
+    const msgstrPluralMatch = /^msgstr\[(\d+)]\s+(.*)$/s.exec(line);
     if (msgstrPluralMatch?.[1] && msgstrPluralMatch[2] !== undefined) {
       const idx = parseInt(msgstrPluralMatch[1], 10);
       current.msgstrPlural.set(idx, unquote(msgstrPluralMatch[2]));
@@ -306,7 +318,7 @@ function parseEntries(content: string): PoEntry[] {
       continue;
     }
 
-    const msgstrMatch = /^msgstr\s+(.*)$/.exec(line);
+    const msgstrMatch = /^msgstr\s+(.*)$/s.exec(line);
     if (msgstrMatch?.[1]) {
       current.msgstr = [unquote(msgstrMatch[1])];
       target = 'msgstr';
@@ -573,7 +585,7 @@ export class PoFormatParser implements FormatParser {
         }
         entryLines.push(el);
 
-        const ctxtM = /^msgctxt\s+(.*)$/.exec(el);
+        const ctxtM = /^msgctxt\s+(.*)$/s.exec(el);
         if (ctxtM?.[1]) {
           entryMsgctxt = unquote(ctxtM[1]);
           target = 'msgctxt';
@@ -581,14 +593,14 @@ export class PoFormatParser implements FormatParser {
           continue;
         }
 
-        const idPluralM = /^msgid_plural\s+(.*)$/.exec(el);
+        const idPluralM = /^msgid_plural\s+(.*)$/s.exec(el);
         if (idPluralM?.[1]) {
           target = 'msgid_plural';
           i++;
           continue;
         }
 
-        const idM = /^msgid\s+(.*)$/.exec(el);
+        const idM = /^msgid\s+(.*)$/s.exec(el);
         if (idM?.[1]) {
           entryMsgid = unquote(idM[1]);
           target = 'msgid';
@@ -596,7 +608,7 @@ export class PoFormatParser implements FormatParser {
           continue;
         }
 
-        const strPluralM = /^msgstr\[(\d+)]\s+(.*)$/.exec(el);
+        const strPluralM = /^msgstr\[(\d+)]\s+(.*)$/s.exec(el);
         if (strPluralM?.[1] && strPluralM[2] !== undefined) {
           const idx = parseInt(strPluralM[1], 10);
           entryMsgstrPlural.set(idx, unquote(strPluralM[2]));
@@ -605,7 +617,7 @@ export class PoFormatParser implements FormatParser {
           continue;
         }
 
-        const strM = /^msgstr\s+(.*)$/.exec(el);
+        const strM = /^msgstr\s+(.*)$/s.exec(el);
         if (strM?.[1]) {
           entryMsgstr = unquote(strM[1]);
           target = 'msgstr';
@@ -706,7 +718,7 @@ export class PoFormatParser implements FormatParser {
       let inMsgstrPlural = false;
 
       for (const el of entryLines) {
-        const strPluralM = /^msgstr\[(\d+)]\s+(.*)$/.exec(el);
+        const strPluralM = /^msgstr\[(\d+)]\s+(.*)$/s.exec(el);
         if (strPluralM?.[1] && strPluralM[2] !== undefined) {
           const idx = parseInt(strPluralM[1], 10);
           const pluralKey = `msgstr[${idx}]`;
@@ -728,7 +740,7 @@ export class PoFormatParser implements FormatParser {
           continue;
         }
 
-        const strM = /^msgstr\s+(.*)$/.exec(el);
+        const strM = /^msgstr\s+(.*)$/s.exec(el);
         if (strM?.[1]) {
           result.push(`msgstr ${quoteLong(translation)}`);
           inMsgstr = true;
@@ -805,7 +817,7 @@ function isHeaderMsgidFromLines(msgid: string, entryLines: string[]): boolean {
   }
   let foundMsgstr = false;
   for (const line of entryLines) {
-    const strM = /^msgstr\s+(.*)$/.exec(line);
+    const strM = /^msgstr\s+(.*)$/s.exec(line);
     if (strM?.[1]) {
       const val = unquote(strM[1]);
       if (val !== '') {
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index e9335b3b..ee3107a2 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -1059,3 +1059,57 @@ describe('PoFormatParser — appending a NEW plural entry', () => {
     expect(written).not.toContain('msgid_plural');
   });
 });
+
+describe('PoFormatParser — U+2028 / U+2029 in a value', () => {
+  // JS `.` excludes the line separators, so a msgstr carrying one did not match
+  // its own line pattern: the line was invisible to both scanners, the key was
+  // reported unwritten (honest, exit 12) but under a remediation about adding a
+  // containing group, and no later run converged. gettext accepts the byte raw --
+  // `msgfmt -c` exits 0 on such a catalog -- so the file is valid and it was this
+  // parser that could not read it. Escaping is not the remedy TOML uses here: the
+  // PO escape set has no \\uXXXX, so an escape would round-trip as literal text.
+  const parser = new PoFormatParser();
+  const HEADER = [
+    'msgid ""',
+    'msgstr ""',
+    '"Content-Type: text/plain; charset=UTF-8\\n"',
+    '',
+    '',
+  ].join('\n');
+
+  it.each([
+    ['U+2028', '\u2028'],
+    ['U+2029', '\u2029'],
+  ])('reads a msgstr containing %s', (_name, sep) => {
+    const po =
+      HEADER + ['msgid "K"', `msgstr "line1${sep}line2"`, ''].join('\n');
+    expect(parser.extractTranslations(po).get('K')).toBe(`line1${sep}line2`);
+  });
+
+  it.each([
+    ['U+2028', '\u2028'],
+    ['U+2029', '\u2029'],
+  ])('writes and re-reads a translation containing %s', (_name, sep) => {
+    const template = HEADER + ['msgid "K"', 'msgstr ""', ''].join('\n');
+    const written = parser.reconstruct(template, [
+      { key: 'K', value: 'K', translation: `line1${sep}line2` },
+    ]);
+    expect(parser.extractTranslations(written).get('K')).toBe(
+      `line1${sep}line2`
+    );
+  });
+
+  it('reads a msgid containing U+2028 as its key', () => {
+    const po =
+      HEADER + ['msgid "a\u2028b"', 'msgstr "translated"', ''].join('\n');
+    expect(parser.extract(po).map((e) => e.key)).toEqual(['a\u2028b']);
+  });
+
+  it('still round-trips an ordinary newline', () => {
+    const template = HEADER + ['msgid "K"', 'msgstr ""', ''].join('\n');
+    const written = parser.reconstruct(template, [
+      { key: 'K', value: 'K', translation: 'line1\nline2' },
+    ]);
+    expect(parser.extractTranslations(written).get('K')).toBe('line1\nline2');
+  });
+});

From ca338ea097c6849c6199103ca69675fff2c2bc64 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 17:05:52 +0200
Subject: [PATCH 218/256] fix(watch): recognise a temp sibling by membership,
 not by its name alone

isAtomicWriteTempPath pattern-matched the name, though its own docstring
promised "a temp sibling of an in-flight atomic write" and the in-flight
set was right there. Any real document named `*.tmp.<digits>.<lc-alnum>`
was therefore dropped from watch -- and dropped before the warn-once
branch, so nothing said it had been skipped.

It is now a membership test against the in-flight set, with paths resolved
on both sides. The name pattern is still honoured for a path that does not
exist, which is what a temp sibling looks like once its rename completed
but the watcher's event is only now being delivered: there is nothing
there to treat as a document either way.

Refs cli-8zn5.28 (L1)
---
 src/utils/atomic-write.ts       | 15 +++++++--
 tests/unit/atomic-write.test.ts | 56 +++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/src/utils/atomic-write.ts b/src/utils/atomic-write.ts
index 39c4bd50..e09c503e 100644
--- a/src/utils/atomic-write.ts
+++ b/src/utils/atomic-write.ts
@@ -1,4 +1,5 @@
 import * as fs from 'fs';
+import * as path from 'path';
 
 /**
  * In-flight `.tmp` sibling files created by atomicWriteFile / atomicWriteFileSync.
@@ -47,12 +48,12 @@ function maybeDetachSignalHandlers(): void {
 }
 
 function registerTmp(tmpPath: string): void {
-  inFlightTmpPaths.add(tmpPath);
+  inFlightTmpPaths.add(path.resolve(tmpPath));
   ensureSignalHandlers();
 }
 
 function unregisterTmp(tmpPath: string): void {
-  inFlightTmpPaths.delete(tmpPath);
+  inFlightTmpPaths.delete(path.resolve(tmpPath));
   maybeDetachSignalHandlers();
 }
 
@@ -88,7 +89,15 @@ const TMP_SIBLING_PATTERN = /\.tmp\.\d+\.[a-z0-9]+$/;
  * something to tell the user about.
  */
 export function isAtomicWriteTempPath(filePath: string): boolean {
-  return TMP_SIBLING_PATTERN.test(filePath);
+  const resolved = path.resolve(filePath);
+  if (inFlightTmpPaths.has(resolved)) return true;
+  // Not one of ours. The name pattern alone used to be the whole test, which
+  // silently dropped any real document named `*.tmp.<digits>.<lc-alnum>` from
+  // watch — before the warn-once branch, so nothing said the file had been
+  // skipped. It is still honoured for a path that does not exist, which is what a
+  // temp sibling looks like once its rename has completed but the watcher's event
+  // is only now being delivered: there is nothing there to treat as a document.
+  return TMP_SIBLING_PATTERN.test(resolved) && !fs.existsSync(resolved);
 }
 
 /**
diff --git a/tests/unit/atomic-write.test.ts b/tests/unit/atomic-write.test.ts
index 362beee4..d0046bb8 100644
--- a/tests/unit/atomic-write.test.ts
+++ b/tests/unit/atomic-write.test.ts
@@ -6,6 +6,7 @@ import {
   atomicWriteFileSync,
   __cleanupInFlightTmpFiles,
   __getInFlightTmpCount,
+  isAtomicWriteTempPath,
 } from '../../src/utils/atomic-write';
 
 describe('atomicWriteFile', () => {
@@ -263,3 +264,58 @@ describe('atomic-write crash cleanup', () => {
     expect(process.listenerCount('SIGTERM')).toBe(sigtermBase);
   });
 });
+
+describe('isAtomicWriteTempPath', () => {
+  // The check was a name pattern rather than a membership test against the
+  // in-flight set, so a real document named `*.tmp.<digits>.<lc-alnum>` was
+  // silently dropped from watch -- before the warn-once branch, so nothing said
+  // it had been skipped.
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'atomic-tmp-name-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('does not claim a real file that merely looks like a temp sibling', () => {
+    const real = path.join(dir, 'report.tmp.12345.abc');
+    fs.writeFileSync(real, 'a genuine document');
+
+    expect(isAtomicWriteTempPath(real)).toBe(false);
+  });
+
+  it('claims a temp sibling while its write is in flight', async () => {
+    const target = path.join(dir, 'out.txt');
+    let seen: string | undefined;
+    const original = fs.promises.rename;
+    const spy = jest
+      .spyOn(fs.promises, 'rename')
+      .mockImplementation(async (from, to) => {
+        seen = String(from);
+        expect(isAtomicWriteTempPath(String(from))).toBe(true);
+        return original(from, to);
+      });
+    try {
+      await atomicWriteFile(target, 'content', 'utf-8');
+    } finally {
+      spy.mockRestore();
+    }
+    expect(seen).toBeDefined();
+    // Drained once the rename completed.
+    expect(isAtomicWriteTempPath(seen!)).toBe(true); // no longer on disk
+    expect(fs.existsSync(seen!)).toBe(false);
+  });
+
+  it('still claims a temp-shaped path that no longer exists', () => {
+    expect(isAtomicWriteTempPath(path.join(dir, 'gone.tmp.999.zz'))).toBe(true);
+  });
+
+  it('does not claim an ordinary file name', () => {
+    const plain = path.join(dir, 'notes.txt');
+    fs.writeFileSync(plain, 'x');
+    expect(isAtomicWriteTempPath(plain)).toBe(false);
+  });
+});

From da2896086b019727b44d1b64573ad8c03ef7ce8a Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 17:09:57 +0200
Subject: [PATCH 219/256] fix(watch): a no-op auto-commit is not a session
 failure

A re-save whose bytes are unchanged stages nothing, and `git commit
--only` then exits non-zero. The undifferentiated catch counted that as an
auto-commit failure, and sessionExitCode() reports 12 when any occurred --
so a session in which nothing went wrong exited 12. The catch also logged
only `error.message`, which carries the exit status; git's own diagnosis
lives in `stderr` and was discarded.

The staged state is now asked as `git diff --cached --quiet` rather than by
matching git's "nothing to commit" wording, which is translated in a
localized git, and a genuine failure is reported with git's stderr.

Not a defect, found while testing: a non-repository output directory is
already handled by an explicit early return with a warning, so it is not
counted as a failure either.

Refs cli-8zn5.28 (L3)
---
 src/cli/commands/watch.ts                     |  42 +++++++-
 .../watch-auto-commit.integration.test.ts     | 101 ++++++++++++++++++
 2 files changed, 139 insertions(+), 4 deletions(-)

diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index 05403fb4..e385a513 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -51,6 +51,22 @@ function watchedDirectory(target: string): string {
   return isDirectory ? target : path.dirname(target);
 }
 
+/**
+ * What git said, rather than only that a command failed.
+ *
+ * `execFile` puts the exit status in `message` and the diagnosis in `stderr`, so
+ * reporting `message` alone discarded the one part that tells the user what to
+ * fix.
+ */
+function gitFailureDetail(error: unknown): string {
+  if (typeof error === 'object' && error !== null) {
+    const stderr = (error as { stderr?: unknown }).stderr;
+    const text = typeof stderr === 'string' ? stderr.trim() : '';
+    if (text) return text;
+  }
+  return error instanceof Error ? error.message : 'Unknown error';
+}
+
 export class WatchCommand {
   private fileTranslationService: FileTranslationService;
   private glossaryService: GlossaryService;
@@ -421,6 +437,27 @@ export class WatchCommand {
 
       const commitMsg = `chore(i18n): auto-translate ${sourceFile} to ${langs}`;
 
+      // A re-save whose bytes are unchanged stages nothing, and `git commit`
+      // then exits non-zero. That is not a failure — nothing needed committing —
+      // but the catch below counted it as one, which made `sessionExitCode()`
+      // report 12 for a session in which nothing had gone wrong. Asked as a
+      // diff rather than by matching git's "nothing to commit" wording, which is
+      // translated in a localized git.
+      const nothingStaged = await execFileAsync(
+        'git',
+        ['diff', '--cached', '--quiet', '--', ...outputFiles],
+        { cwd }
+      ).then(
+        () => true,
+        () => false
+      );
+      if (nothingStaged) {
+        Logger.info(
+          'Auto-commit: translated output unchanged, nothing to commit'
+        );
+        return;
+      }
+
       // --only restricts the commit to the translated outputs, so anything else
       // already staged in the index is not swept into an i18n commit.
       await execFileAsync(
@@ -432,10 +469,7 @@ export class WatchCommand {
       Logger.success(chalk.green('✓ Auto-committed translations'));
     } catch (error) {
       this.autoCommitFailures++;
-      Logger.error(
-        chalk.red('✗ Auto-commit failed:'),
-        error instanceof Error ? error.message : 'Unknown error'
-      );
+      Logger.error(chalk.red('✗ Auto-commit failed:'), gitFailureDetail(error));
     }
   }
 
diff --git a/tests/integration/watch-auto-commit.integration.test.ts b/tests/integration/watch-auto-commit.integration.test.ts
index cf8c1c16..bf82eb5f 100644
--- a/tests/integration/watch-auto-commit.integration.test.ts
+++ b/tests/integration/watch-auto-commit.integration.test.ts
@@ -277,3 +277,104 @@ describe('Watch auto-commit integration', () => {
     expect(status.trim()).toBe('');
   }, 60000);
 });
+
+describe('Watch auto-commit: a re-save with unchanged bytes', () => {
+  // A `git commit --only` with nothing staged exits non-zero, and the
+  // undifferentiated catch counted that as an auto-commit failure -- which makes
+  // sessionExitCode() report 12 for a session in which nothing went wrong. The
+  // catch also discarded git's stderr, so the log said only "Auto-commit failed".
+  let tmpDir: string;
+  let watchCommand: WatchCommand;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    tmpDir = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-autocommit-noop-'))
+    );
+    execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.email "test@test.com"', {
+      cwd: tmpDir,
+      stdio: 'ignore',
+    });
+    execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'ignore' });
+    fs.writeFileSync(path.join(tmpDir, 'README.md'), 'init');
+    execSync('git add . && git commit -m "init"', {
+      cwd: tmpDir,
+      stdio: 'ignore',
+    });
+    watchCommand = new WatchCommand(
+      createMockTranslationService(),
+      createMockGlossaryService()
+    );
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  function callAutoCommit(sourceFile: string, result: unknown): Promise<void> {
+    return (
+      watchCommand as unknown as {
+        autoCommit: (s: string, r: unknown) => Promise<void>;
+      }
+    ).autoCommit(sourceFile, result);
+  }
+
+  function failures(): number {
+    return (watchCommand as unknown as { autoCommitFailures: number })
+      .autoCommitFailures;
+  }
+
+  it('is not counted as an auto-commit failure', async () => {
+    const outFile = path.join(tmpDir, 'file.es.md');
+    fs.writeFileSync(outFile, 'Hola mundo');
+    const result = {
+      targetLang: 'es',
+      text: 'Hola mundo',
+      outputPath: outFile,
+    };
+
+    // First save commits normally.
+    await callAutoCommit('file.md', result);
+    expect(failures()).toBe(0);
+
+    // Re-save with identical bytes: there is nothing to commit.
+    fs.writeFileSync(outFile, 'Hola mundo');
+    await callAutoCommit('file.md', result);
+
+    expect(failures()).toBe(0);
+    expect(Logger.error as jest.Mock).not.toHaveBeenCalled();
+    // Exactly one commit exists for that message.
+    const log = execSync('git log --oneline', {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    });
+    expect(
+      log.split('\n').filter((l) => l.includes('auto-translate file.md')).length
+    ).toBe(1);
+  });
+
+  it("still reports a genuine failure, quoting git's own message", async () => {
+    const outFile = path.join(tmpDir, 'file.es.md');
+    fs.writeFileSync(outFile, 'Hola');
+    // A held index lock is a real git failure with a specific diagnosis, which
+    // the report has to carry: `execFile` puts the exit status in `message` and
+    // the diagnosis in `stderr`, and only `message` used to be logged.
+    fs.writeFileSync(path.join(tmpDir, '.git', 'index.lock'), '');
+
+    await callAutoCommit('file.md', {
+      targetLang: 'es',
+      text: 'Hola',
+      outputPath: outFile,
+    });
+
+    expect(failures()).toBe(1);
+    const logged = (Logger.error as jest.Mock).mock.calls
+      .flat()
+      .map(String)
+      .join(' ');
+    expect(logged).toMatch(/index\.lock/);
+  });
+});

From 50298653a324e0c2322bb66c8629543623a98cef Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 17:12:11 +0200
Subject: [PATCH 220/256] fix(android): route an entry by the element it names,
 not by its key shape

reconstruct decided what an entry was from the shape of its key: a dot made
it a <string-array> item. A plurals entry named `x.0` -- alongside a sibling
<string-array name="x">, and with its plural metadata stripped, which is
exactly what the carry-forward does -- was therefore routed into the array
branch. Nothing then claimed the element, and the PLURALS_EL pass deleted
it.

A key that names a <plurals> element in the file is that element, whatever
shape the name has. Ordinary array items still route by index.

Refs cli-8zn5.28 (L6)
---
 src/formats/android-xml.ts             | 16 +++++++-
 tests/unit/formats/android-xml.test.ts | 55 ++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index 7e2b251d..b2b7121c 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -256,6 +256,7 @@ export class AndroidXmlFormatParser implements FormatParser {
     const pluralTranslations = new Map<string, Map<string, string>>();
     const arrayTranslations = new Map<string, Map<number, string>>();
     let arrayNames: Set<string> | undefined;
+    let pluralsNames: Set<string> | undefined;
 
     for (const entry of entries) {
       if (entry.metadata?.['plurals']) {
@@ -274,8 +275,21 @@ export class AndroidXmlFormatParser implements FormatParser {
             attrValue(el)
           )
         );
+        // A key that NAMES a <plurals> element is that element, whatever shape it
+        // has. Routing on the key's shape alone sent a plurals entry called `x.0`
+        // into the string-array branch whenever a `<string-array name="x">` was
+        // present — so with the entry's plural metadata stripped, which is exactly
+        // what the carry-forward does, nothing claimed the element and the
+        // PLURALS_EL pass deleted it.
+        pluralsNames ??= new Set(
+          scanElements(originalContent, PLURALS_EL).map((el) => attrValue(el))
+        );
 
-        if (!isNaN(index) && arrayNames.has(arrayName)) {
+        if (
+          !isNaN(index) &&
+          arrayNames.has(arrayName) &&
+          !pluralsNames.has(entry.key)
+        ) {
           if (!arrayTranslations.has(arrayName)) {
             arrayTranslations.set(arrayName, new Map());
           }
diff --git a/tests/unit/formats/android-xml.test.ts b/tests/unit/formats/android-xml.test.ts
index 1413e15e..c327eae8 100644
--- a/tests/unit/formats/android-xml.test.ts
+++ b/tests/unit/formats/android-xml.test.ts
@@ -657,3 +657,58 @@ describe('appending a resource whose KEY needs guarding', () => {
     expect(written).toContain('<string name="greeting">Hola</string>');
   });
 });
+
+describe('a <plurals> element whose name looks like an array index', () => {
+  // Reconstruct routed an entry by the SHAPE of its key: a dot made it a
+  // `<string-array>` item. A plurals entry whose metadata was stripped -- which is
+  // exactly what the carry-forward does -- and whose name is `x.0`, alongside a
+  // sibling `<string-array name="x">`, was therefore routed into the array branch
+  // and its element deleted.
+  const XML = [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    '<resources>',
+    '    <string-array name="x">',
+    '        <item>First</item>',
+    '    </string-array>',
+    '    <plurals name="x.0">',
+    '        <item quantity="one">One file</item>',
+    '        <item quantity="other">%d files</item>',
+    '    </plurals>',
+    '</resources>',
+    '',
+  ].join('\n');
+
+  it('keeps the element when the carried entry has no plural metadata', () => {
+    const written = parser.reconstruct(XML, [
+      { key: 'x.0', value: '%d files', translation: '%d archivos' },
+      { key: 'x.0', value: 'First', translation: 'Primero' },
+    ] as TranslatedEntry[]);
+
+    expect(written).toContain('<plurals name="x.0">');
+    expect(written).toContain('<item quantity="one">One file</item>');
+    expect(written).toContain('<item quantity="other">%d files</item>');
+  });
+
+  it('still fills a string-array item whose name is not a plurals element', () => {
+    const written = parser.reconstruct(XML, [
+      { key: 'x.0', value: 'First', translation: 'Primero' },
+    ] as TranslatedEntry[]);
+    // `x.0` names the <plurals>, so the array item is left as it stands rather
+    // than being fed the plurals entry's translation.
+    expect(written).toContain('<plurals name="x.0">');
+  });
+
+  it('still routes an ordinary array item by index', () => {
+    const arrayOnly = [
+      '<resources>',
+      '    <string-array name="menu">',
+      '        <item>First</item>',
+      '    </string-array>',
+      '</resources>',
+    ].join('\n');
+    const written = parser.reconstruct(arrayOnly, [
+      { key: 'menu.0', value: 'First', translation: 'Primero' },
+    ] as TranslatedEntry[]);
+    expect(written).toContain('<item>Primero</item>');
+  });
+});

From fdf4bf159d669e6b2df55a03dd084a3e6d7e6d97 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 17:14:49 +0200
Subject: [PATCH 221/256] fix(po): do not claim an obsolete #~ block as the
 next entry's comments

The comment backtrack walked every preceding line starting with `#`, and
`#~` starts with `#`. gettext's retired-work region is an obsolete entry of
its own, not the following entry's comments, so dropping an entry -- a key
the source no longer has -- deleted the `#~` block above it as well.

The backtrack now stops at a `#~` line. An entry's own `#.`/`#:`/`#,`
comments are still dropped with it, and msgfmt accepts the result.

Reproducing this needs the `#~` block adjacent to the next entry's
comments: with a blank line between them the backtrack already stopped, so
the fixture has to omit it.

Refs cli-8zn5.28 (L8)
---
 src/formats/po.ts             | 10 ++++++-
 tests/unit/formats/po.test.ts | 56 +++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/src/formats/po.ts b/src/formats/po.ts
index 9c3417b1..dfaf222b 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -564,7 +564,15 @@ export class PoFormatParser implements FormatParser {
       // measured 28 ms at 20k comment lines, 109 ms at 40k and 437 ms at 80k,
       // which is 4x the time for 2x the input.
       let backtrack = result.length - 1;
-      while (backtrack >= 0 && result[backtrack]!.startsWith('#')) {
+      while (
+        backtrack >= 0 &&
+        result[backtrack]!.startsWith('#') &&
+        // `#~` marks gettext's retired-work region: those lines are an obsolete
+        // entry of their own, not this entry's comments. Claiming them meant that
+        // dropping an entry — a key the source no longer has — deleted the
+        // obsolete block sitting above it as well.
+        !result[backtrack]!.startsWith('#~')
+      ) {
         backtrack--;
       }
       const commentLines: string[] = result.slice(backtrack + 1);
diff --git a/tests/unit/formats/po.test.ts b/tests/unit/formats/po.test.ts
index ee3107a2..ccd2ed67 100644
--- a/tests/unit/formats/po.test.ts
+++ b/tests/unit/formats/po.test.ts
@@ -1113,3 +1113,59 @@ describe('PoFormatParser — U+2028 / U+2029 in a value', () => {
     expect(parser.extractTranslations(written).get('K')).toBe('line1\nline2');
   });
 });
+
+describe('PoFormatParser — an obsolete #~ block above an entry', () => {
+  // reconstruct's comment backtrack claims every preceding line starting with `#`
+  // as the entry's comments, and `#~` starts with `#`. Dropping the entry (a key
+  // the source no longer has) therefore took the retired-work block with it, even
+  // though `#~` lines belong to no live entry at all.
+  const parser = new PoFormatParser();
+  const CATALOG = [
+    'msgid ""',
+    'msgstr ""',
+    '"Content-Type: text/plain; charset=UTF-8\\n"',
+    '',
+    '#~ msgid "Retired"',
+    '#~ msgstr "Retirado"',
+    '#. a real comment',
+    'msgid "Gone"',
+    'msgstr "Ido"',
+    '',
+    'msgid "Kept"',
+    'msgstr "Guardado"',
+    '',
+  ].join('\n');
+
+  it('keeps the #~ block when the entry below it is dropped', () => {
+    const written = parser.reconstruct(CATALOG, [
+      { key: 'Kept', value: 'Kept', translation: 'Guardado' },
+    ]);
+
+    expect(written).toContain('#~ msgid "Retired"');
+    expect(written).toContain('#~ msgstr "Retirado"');
+    // The dropped entry and its own comment are gone.
+    expect(written).not.toContain('msgid "Gone"');
+    expect(written).not.toContain('a real comment');
+  });
+
+  it("still drops the entry's own comments with it", () => {
+    const simple = [
+      'msgid ""',
+      'msgstr ""',
+      '"Content-Type: text/plain; charset=UTF-8\\n"',
+      '',
+      '#. belongs to Gone',
+      'msgid "Gone"',
+      'msgstr "Ido"',
+      '',
+      'msgid "Kept"',
+      'msgstr "Guardado"',
+      '',
+    ].join('\n');
+    const written = parser.reconstruct(simple, [
+      { key: 'Kept', value: 'Kept', translation: 'Guardado' },
+    ]);
+    expect(written).not.toContain('belongs to Gone');
+    expect(written).toContain('msgid "Kept"');
+  });
+});

From 7ff8421ee6681805b5d30a72b875c70f3fa23f62 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 17:16:09 +0200
Subject: [PATCH 222/256] docs(changelog): record the low-severity guard
 red-team fixes

Covers the six lows fixed under cli-8zn5.28: the atomic-write temp-sibling
name test, the no-op auto-commit exit code, PO line separators, the PO #~
block, the pull plural-entry test, and the Android plurals routing.

Refs cli-8zn5.28
---
 CHANGELOG.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17457211..a0d80d81 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -155,6 +155,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **watch**: a real document named like an atomic-write temp sibling (`*.tmp.<digits>.<letters>`) is no longer skipped. The check pattern-matched the file **name**, though its own docstring promised "a temp sibling of an in-flight atomic write" and the in-flight set was already there; the skip also happened before the warn-once branch, so nothing said the file had been passed over. It is now a membership test against that set, with the name pattern still honoured for a path that no longer exists — a temp sibling whose rename completed before the watcher's event arrived.
+
+- **watch**: `--auto-commit` no longer reports a session failure when there was nothing to commit. Re-saving a file whose translated bytes are unchanged stages nothing, `git commit --only` then exits non-zero, and the undifferentiated `catch` counted that as an auto-commit failure — which makes the session exit **12** although nothing went wrong. The staged state is now asked as `git diff --cached --quiet` rather than by matching git's "nothing to commit" wording, which a localized git translates. A genuine failure is now reported with git's own `stderr`, which was previously discarded in favour of the bare exit-status message.
+
+- **po**: a `msgstr` containing U+2028 or U+2029 is readable. JS `.` excludes the line separators, so such a line did not match its own pattern at all: it was invisible to both scanners, and the key was reported unwritten — honestly, at exit 12 — but under a remediation about adding a containing group, so no later run could converge. gettext accepts the byte raw (verified: `msgfmt -c` exits 0 on such a catalog), so the file was valid and it was this parser that could not read it. Note that escaping — the remedy TOML uses — is *not* available here: the PO escape set has no `\uXXXX`, so an escape would round-trip back as the literal text.
+
+- **po**: an obsolete `#~` block is no longer deleted along with the entry beneath it. The comment backtrack claimed every preceding line starting with `#`, and `#~` starts with `#` — but gettext's retired-work region is an obsolete entry in its own right, not the following entry's comments. An entry's own `#.`/`#:`/`#,` comments are still dropped with it.
+
+- **sync**: `deepl sync pull` recognises a gettext plural entry that declares `msgid_plural` without yet holding any `msgstr[N]`. `plural_forms` metadata only appears once forms exist, so judging plurality from that payload made pull treat such an entry as an ordinary key — and one exported string cannot fill a plural entry's forms, so the pull recorded a translation it had not applied.
+
+- **android**: a `<plurals>` element whose name looks like an array index (`x.0`, beside a `<string-array name="x">`) is no longer deleted. `reconstruct` decided what an entry was from the shape of its key, so with the entry's plural metadata stripped — which is exactly what the carry-forward does — nothing claimed the element. A key that names a `<plurals>` element in the file is now treated as that element whatever shape its name has.
+
 - **translate**: **a source string that literally contains the CLI's own placeholder token is no longer corrupted, and a genuinely lost token is no longer reported as intact.** Preservation tokens came from a plain counter, so text carrying a literal `__VAR_0__` — ordinary content, not a variable — could be handed the *same* token as a real `{name}`. Two occurrences then went to the engine, and `restorePlaceholders` uses `replaceAll`, so the literal copy came back as `{name}` too: `'literal __VAR_0__ and {name}'` round-tripped to `'literal {name} and {name}'`. The same collision made the loss check accept the literal copy as evidence that the substituted token had survived, so an engine that mangled the real token had a genuine loss reported as intact. Tokens are now chosen to avoid any that the source text already contains, for both the `__VAR_` and `__CODE_` families, and the low numbers are still used when the source carries none. A property test that had been *documenting* the corruption as expected output now asserts the round trip.
 
 - **po**: **rebuilding a catalog is linear in the length of a comment block again, instead of quadratic.** `reconstruct` collected the run of comment lines above an entry by walking backwards and `unshift`ing each line onto an array — and `unshift` re-indexes the whole array on every call, so the cost grew with the square of the run's length. Measured: 20k comment lines took 28 ms, 40k took 109 ms and 80k took 437 ms — four times the time for twice the input — which extrapolates to the ~47 seconds reported for a large catalog. The run is now taken with a single slice: the same 80k lines take **11 ms**, and the growth is linear.

From ee44dba37c7d1795234ed601525eab934209d860 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 19:41:44 +0200
Subject: [PATCH 223/256] chore: remove two throwaway ReDoS measurement
 harnesses

zz-redos2.mjs and zz-redos3.mjs were picomatch timing loops used to measure
the extglob backtracking in 4b8caa1. They were swept into that commit by
`git add -A` because the cleanup `rm` never ran -- the command they were
part of timed out. Investigation harnesses do not belong in the tree.

Removed forward rather than by rewriting 4b8caa1: the bead close reasons
across this epic quote commit SHAs, and a rewrite would invalidate them.
---
 zz-redos2.mjs | 10 ----------
 zz-redos3.mjs |  7 -------
 2 files changed, 17 deletions(-)
 delete mode 100644 zz-redos2.mjs
 delete mode 100644 zz-redos3.mjs

diff --git a/zz-redos2.mjs b/zz-redos2.mjs
deleted file mode 100644
index fd1cbcb2..00000000
--- a/zz-redos2.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-import picomatch from 'picomatch';
-const decoy = 'a'.repeat(40);
-for (const n of [1, 2, 3, 4, 5]) {
-  const pattern = '+(a*)'.repeat(n) + 'b';
-  const isMatch = picomatch(pattern);
-  const t0 = process.hrtime.bigint();
-  isMatch(decoy);
-  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
-  console.log(`N=${n} -> ${ms.toFixed(2)} ms`);
-}
diff --git a/zz-redos3.mjs b/zz-redos3.mjs
deleted file mode 100644
index 5cf5d8a2..00000000
--- a/zz-redos3.mjs
+++ /dev/null
@@ -1,7 +0,0 @@
-import picomatch from 'picomatch';
-const decoy = 'a'.repeat(40);
-const n = Number(process.argv[2]);
-const pattern = '+(a*)'.repeat(n) + 'b';
-const t0 = process.hrtime.bigint();
-picomatch(pattern)(decoy);
-console.log(`N=${n} -> ${(Number(process.hrtime.bigint() - t0) / 1e6).toFixed(2)} ms`);

From 12d2149bec6170fda5c9c65a9cd8bcc4a3d1efed Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 20:06:21 +0200
Subject: [PATCH 224/256] fix(sync): age out a lock holder this user cannot
 signal, and add --break-lock

kill(pid, 0) answers EPERM for a PID that exists but belongs to another
user, which is equally what a PID recycled by an unrelated process or one
from a container's PID namespace looks like. That was read as "alive" with
no upper bound, and the startedAt the pidfile has always recorded was never
consulted, so such a pidfile refused every later sync indefinitely: a
pidfile naming PID 1 with a 30-day-old start time held exit 7 forever.

An unownable holder is now trusted only while its recorded start time is
within 24 hours and readable as a date; the distance is absolute, so a time
impossibly far ahead of this clock counts against it too. A holder the probe
reports as genuinely running is never aged out, however old the lock, since
taking the lock from a live sync is the concurrent-writer hazard the lock
exists to prevent. That case gets --break-lock instead, on every command
that takes the lock (sync, sync pull, sync resolve), resolved across parent
and subcommand scopes like the other shared sync flags and honoured on the
first acquisition attempt only. Watch mode resets it per pass so a session
does not stop arbitrating after its first cycle.

Refs cli-8zn5.30
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   4 +
 docs/SYNC.md                                  |  10 +
 src/cli/commands/sync-command.ts              |   6 +
 src/cli/commands/sync/register-sync-pull.ts   |  11 +-
 .../commands/sync/register-sync-resolve.ts    |  10 +-
 src/cli/commands/sync/register-sync-root.ts   |   4 +
 src/cli/commands/sync/sync-options.ts         |  14 ++
 src/sync/sync-process-lock.ts                 |  96 ++++++--
 src/sync/sync-service.ts                      |  10 +-
 tests/e2e/cli-sync-break-lock.e2e.test.ts     | 215 ++++++++++++++++++
 .../register-sync.commander-snapshot.test.ts  |  35 ++-
 tests/unit/sync/sync-command.test.ts          |  58 +++++
 tests/unit/sync/sync-process-lock.test.ts     | 175 +++++++++++++-
 14 files changed, 629 insertions(+), 23 deletions(-)
 create mode 100644 tests/e2e/cli-sync-break-lock.e2e.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a0d80d81..58d7424a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- **sync**: `--break-lock` on `deepl sync`, `deepl sync pull` and `deepl sync resolve` takes the process lock even when `.deepl-sync.lock.pidfile` names a holder that looks alive, printing the PID and start time it removed. It is the operator's escape from a lock whose holder cannot be disproved — a PID recycled by one of this user's own processes — and it applies to the run it is passed to only, so a `--watch` session breaks the lock for its first pass and then arbitrates normally for the rest of the session. Unsafe if that sync really is running, and the warning says so: two concurrent runs write the same target files and then overwrite each other's lockfile.
+
 ### Added
 
 - **sync**: `deepl sync pull --dry-run` previews a pull without writing anything — no target file, no `.deepl-sync.lock`. It reports how many translations would be pulled and how many existing local translations would be replaced, and `--verbose` names each key and file whose TMS value differs from the local one. `--format json` carries `replaced` and `dryRun` alongside `pulled`. Pull is the one sync command that replaces hand edits with content the CLI has no way to date, and it was the only writing sync command with no preview mode; `sync` itself and `sync resolve` both have one. The flag is also accepted on the parent (`deepl sync --dry-run pull`), matching how `sync resolve` reads it.
@@ -155,6 +157,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: a pidfile naming a process this user cannot signal no longer refuses every later sync indefinitely. `kill(pid, 0)` answers EPERM for a PID that exists but belongs to another user — which is equally what a PID recycled by an unrelated process, or one from a container's PID namespace, looks like — and that was read as "alive" with no upper bound, while the `startedAt` the pidfile has always recorded was never consulted. Measured through the CLI: a pidfile naming PID 1 with a start time 30 days old refused `deepl sync` with exit 7 on every attempt. Such a holder is now trusted only while its recorded start time is within 24 hours and readable as a date (a time impossibly far in the future counts against it too), after which the lock is reclaimed with a warning naming the PID and the reason. A holder the probe reports as **genuinely running** is never aged out, however old the lock — taking the lock from a live sync is the concurrent-writer hazard the lock exists to prevent — so that case gets `--break-lock` instead (see Added). The refusal message now names the flag.
+
 - **watch**: a real document named like an atomic-write temp sibling (`*.tmp.<digits>.<letters>`) is no longer skipped. The check pattern-matched the file **name**, though its own docstring promised "a temp sibling of an in-flight atomic write" and the in-flight set was already there; the skip also happened before the warn-once branch, so nothing said the file had been passed over. It is now a membership test against that set, with the name pattern still honoured for a path that no longer exists — a temp sibling whose rename completed before the watcher's event arrived.
 
 - **watch**: `--auto-commit` no longer reports a session failure when there was nothing to commit. Re-saving a file whose translated bytes are unchanged stages nothing, `git commit --only` then exits non-zero, and the undifferentiated `catch` counted that as an auto-commit failure — which makes the session exit **12** although nothing went wrong. The staged state is now asked as `git diff --cached --quiet` rather than by matching git's "nothing to commit" wording, which a localized git translates. A genuine failure is now reported with git's own `stderr`, which was previously discarded in favour of the bare exit-status message.
diff --git a/docs/API.md b/docs/API.md
index 117a457a..ef3bdc06 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1244,6 +1244,7 @@ Scan, translate, and sync i18n resource files. The sync engine reads `.deepl-syn
   - Anywhere else the prompt cannot be shown — a git hook, cron job, `make` target, container entrypoint, `deepl sync --force < /dev/null`, or `--no-input` — `--force` is **refused** with exit 6 rather than assumed to be confirmed. `--yes` is the only way to run it unattended. `--force` overwrites every target file, including translations edited by hand, and no `.deepl.bak` survives a successful run, so there is nothing to recover from afterwards.
 
 - `--yes, -y` - Skip the `--force` confirmation prompt (required when `CI=true`, and whenever there is no terminal to prompt on)
+- `--break-lock` - Take the sync lock even when `.deepl-sync.lock.pidfile` names a process that looks alive, reporting the holder it removed. Also accepted by `sync pull` and `sync resolve`, which take the same lock. Use it only when that run is definitely not running: two concurrent syncs write the same target files and the same lockfile. Not carried into `--watch` cycles — it applies to the run you asked for, then the lock arbitrates normally again. See [Concurrent sync](SYNC.md#concurrent-sync)
 
 **Filtering:**
 
@@ -1496,6 +1497,7 @@ Resolve git merge conflicts in `.deepl-sync.lock`.
 - `--format FORMAT` - Output format: `text` (default), `json`
 - `--dry-run` - Preview conflict decisions without writing the lockfile
 - `--sync-config PATH` - Path to `.deepl-sync.yaml`
+- `--break-lock` - Take the sync lock even when `.deepl-sync.lock.pidfile` names a process that looks alive
 
 **JSON success envelope (stable within a major version):** `{ "ok": true, "resolved": <n>, "decisions": [...] }`
 
@@ -1532,6 +1534,8 @@ Pull approved translations from a TMS back into local files.
 - `--locale LANGS` - Pull specific locales only
 - `--format FORMAT` - Output format: `text` (default), `json`
 - `--sync-config PATH` - Path to `.deepl-sync.yaml`
+- `--dry-run` - Preview what the pull would change without writing any file
+- `--break-lock` - Take the sync lock even when `.deepl-sync.lock.pidfile` names a process that looks alive
 
 **Requires TMS integration.** Add a `tms:` block to `.deepl-sync.yaml` (at minimum `enabled: true`, `server`, `project_id`) and supply credentials via the `TMS_API_KEY` or `TMS_TOKEN` environment variable. Running `pull` without a configured `tms:` block exits 7 (ConfigError). See [docs/SYNC.md#tms-rest-contract](./SYNC.md#tms-rest-contract) for the full field reference and REST contract.
 
diff --git a/docs/SYNC.md b/docs/SYNC.md
index a1eb8666..f3a5f36b 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -60,6 +60,16 @@ Sync also refuses to read or write any path resolving into `.git/` or `.github/`
 
 Only one `deepl sync` run is supported at a time per project directory. At startup, sync writes a `.deepl-sync.lock.pidfile` containing its PID; a second invocation that sees an existing pidfile whose PID is still alive exits with `ConfigError` (exit code 7). If the PID is dead (e.g., a previous run crashed), sync removes the stale pidfile with a warning and proceeds. The pidfile is deleted automatically on normal completion and on SIGINT/SIGTERM.
 
+Three verdicts are possible for the PID a pidfile names, because `kill(pid, 0)` has three answers. A PID that is running holds the lock. A PID that does not exist is stale, and sync removes the pidfile with a warning and proceeds. A PID that exists but belongs to **another user** cannot be probed any further — and that is also what a PID recycled by an unrelated process looks like — so it is trusted only while the start time recorded in the pidfile keeps it plausible: a holder this user cannot signal whose recorded start is more than 24 hours old (or is not a readable date, or is impossibly far in the future) is treated as stale and reclaimed with a warning naming it. A holder that *is* running is never aged out, however old the lock: taking the lock from a live sync is the concurrent-writer hazard the lock exists to prevent.
+
+For that last case — a lock you know is dead but the machine still reports as alive, typically a recycled PID belonging to you — pass `--break-lock`:
+
+```bash
+deepl sync --break-lock          # also on `sync pull` and `sync resolve`
+```
+
+It removes the pidfile whatever its holder looks like, prints the PID and start time it removed, and takes the lock. Removing `.deepl-sync.lock.pidfile` by hand does the same thing. Both are unsafe if that sync really is running: two concurrent runs write the same target files and then overwrite each other's lockfile. `--break-lock` applies to the run you pass it to only — a `--watch` session breaks the lock for its first pass and then arbitrates normally for the rest of the session.
+
 Every command that writes `.deepl-sync.lock` takes the lock: `deepl sync`, `deepl sync pull` and `deepl sync resolve`, the last of these including `--dry-run`. A run reads the lockfile when it starts and writes its whole in-memory copy when it finishes, so anything written in between would be replaced. Read-only commands (`sync status`, `sync validate`, `sync audit`, `sync export`) do not take it.
 
 If the lockfile changes on disk between a run's read and its write anyway — a hand edit, a `git merge` or another tool, none of which take the lock — the run says so and still writes what it recorded:
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index 050306a2..6835828a 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -44,6 +44,7 @@ export interface CliSyncOptions {
   debounce?: number;
   flagForReview?: boolean;
   autoCommit?: boolean;
+  breakLock?: boolean;
 }
 
 /**
@@ -341,6 +342,7 @@ export class SyncCommand {
       localeFilter: overrides.localeFilter,
       concurrency: options.concurrency,
       batch: options.batch,
+      breakLock: options.breakLock,
       onProgress: (event) => this.renderProgress(event, format),
     };
 
@@ -474,6 +476,10 @@ export class SyncCommand {
         Logger.info(`[${timestamp}] Change detected, syncing...`);
         const result = await this.syncService.sync(activeConfig, {
           ...syncOptions,
+          // --break-lock applies to the run the operator asked for. Carrying it
+          // into every later pass would leave the whole watch session unable to
+          // arbitrate against another sync in the same directory.
+          breakLock: false,
           cancellationSignal: signal,
           backupTracker,
         });
diff --git a/src/cli/commands/sync/register-sync-pull.ts b/src/cli/commands/sync/register-sync-pull.ts
index cf711db6..790df5d5 100644
--- a/src/cli/commands/sync/register-sync-pull.ts
+++ b/src/cli/commands/sync/register-sync-pull.ts
@@ -5,6 +5,7 @@ import type { ServiceDeps } from '../service-factory.js';
 import {
   emitJsonErrorAndExit,
   parseLocaleFilter,
+  resolveBreakLock,
   resolveFormat,
   resolveLocale,
   resolveSyncConfig,
@@ -15,6 +16,7 @@ interface PullOptions {
   syncConfig?: string;
   format?: string;
   dryRun?: boolean;
+  breakLock?: boolean;
 }
 
 export function registerSyncPull(
@@ -35,6 +37,10 @@ export function registerSyncPull(
       '--dry-run',
       'Preview what the pull would change without writing any file'
     )
+    .option(
+      '--break-lock',
+      'Take the sync lock even when .deepl-sync.lock.pidfile names a process that looks alive'
+    )
     .addHelpText(
       'after',
       `
@@ -54,6 +60,7 @@ full field list and REST contract.
       options.format = resolveFormat(options, command);
       options.locale = resolveLocale(options, command);
       options.syncConfig = resolveSyncConfig(options, command);
+      options.breakLock = resolveBreakLock(options, command);
       // Commander routes --dry-run on the invocation line to the parent `sync`
       // command (which also defines --dry-run). Fall back to the parent's value.
       const parentDryRun = command.parent?.opts()['dryRun'] as
@@ -92,7 +99,9 @@ export async function handleSyncPull(
       );
     }
 
-    const processLock = acquireSyncProcessLock(config.projectRoot);
+    const processLock = acquireSyncProcessLock(config.projectRoot, {
+      breakLock: options.breakLock,
+    });
     try {
       const client = await createTmsClient(config.tms);
       const { tmsServerOrigin } =
diff --git a/src/cli/commands/sync/register-sync-resolve.ts b/src/cli/commands/sync/register-sync-resolve.ts
index 6def2430..dcf0ce20 100644
--- a/src/cli/commands/sync/register-sync-resolve.ts
+++ b/src/cli/commands/sync/register-sync-resolve.ts
@@ -4,6 +4,7 @@ import { SyncConflictError } from '../../../utils/errors.js';
 import type { ServiceDeps } from '../service-factory.js';
 import {
   emitJsonErrorAndExit,
+  resolveBreakLock,
   resolveFormat,
   resolveSyncConfig,
 } from './sync-options.js';
@@ -12,6 +13,7 @@ interface ResolveOptions {
   syncConfig?: string;
   dryRun?: boolean;
   format?: string;
+  breakLock?: boolean;
 }
 
 export function registerSyncResolve(
@@ -31,6 +33,10 @@ export function registerSyncResolve(
       '--dry-run',
       'Preview the decision report without writing the lockfile'
     )
+    .option(
+      '--break-lock',
+      'Take the sync lock even when .deepl-sync.lock.pidfile names a process that looks alive'
+    )
     .action((options: ResolveOptions, command: Command) =>
       handleSyncResolve(options, command, deps)
     );
@@ -62,7 +68,9 @@ async function handleSyncResolve(
     // copy when it finishes, so a resolve landing in between is erased by the
     // sync's own write. Held for a dry run too, matching `sync pull`: the file
     // the report describes is about to be rewritten.
-    const processLock = acquireSyncProcessLock(config.projectRoot);
+    const processLock = acquireSyncProcessLock(config.projectRoot, {
+      breakLock: resolveBreakLock(options, command),
+    });
     try {
       const result = await resolveLockFile(lockPath, { dryRun });
 
diff --git a/src/cli/commands/sync/register-sync-root.ts b/src/cli/commands/sync/register-sync-root.ts
index cbdb7e7e..1a1b036d 100644
--- a/src/cli/commands/sync/register-sync-root.ts
+++ b/src/cli/commands/sync/register-sync-root.ts
@@ -86,6 +86,10 @@ export function registerSyncRoot(program: Command, deps: ServiceDeps): Command {
       '-y, --yes',
       'Skip --force confirmation prompt (required when CI=true)'
     )
+    .option(
+      '--break-lock',
+      'Take the sync lock even when .deepl-sync.lock.pidfile names a process that looks alive. Use only when that sync is definitely not running: two concurrent syncs overwrite the same target files.'
+    )
     .optionsGroup('Output:')
     .addOption(
       new Option('--format <format>', 'Output format')
diff --git a/src/cli/commands/sync/sync-options.ts b/src/cli/commands/sync/sync-options.ts
index e61189c2..ad19a62b 100644
--- a/src/cli/commands/sync/sync-options.ts
+++ b/src/cli/commands/sync/sync-options.ts
@@ -50,6 +50,20 @@ export function resolveSyncConfig(
   return command.parent?.opts()['syncConfig'] as string | undefined;
 }
 
+/**
+ * Resolve --break-lock across parent (`sync`) and subcommand scopes. Same
+ * parent/child binding rule as {@link resolveLocale}: the parent `sync`
+ * command also declares the flag, so a subcommand that reads only its own
+ * store would silently keep respecting a lock the operator asked it to break.
+ */
+export function resolveBreakLock(
+  opts: { breakLock?: boolean },
+  command: Command
+): boolean {
+  if (opts.breakLock !== undefined) return opts.breakLock;
+  return (command.parent?.opts()['breakLock'] as boolean | undefined) ?? false;
+}
+
 /**
  * Split a resolved --locale value into the comma-separated filter list that
  * `loadSyncConfig` validates against `target_locales`.
diff --git a/src/sync/sync-process-lock.ts b/src/sync/sync-process-lock.ts
index 57f0663a..6742d0f3 100644
--- a/src/sync/sync-process-lock.ts
+++ b/src/sync/sync-process-lock.ts
@@ -7,6 +7,14 @@ export const PROCESS_LOCK_FILE_NAME = '.deepl-sync.lock.pidfile';
 
 const MAX_ACQUIRE_ATTEMPTS = 5;
 
+/**
+ * How long a pidfile whose holder this user cannot probe is trusted, measured
+ * from the start time the holder recorded. Generous on purpose: the lock is
+ * held for one sync pass (watch mode retakes it per change), so a day is far
+ * beyond any run, while still bounding a pidfile nothing can disprove.
+ */
+export const UNOWNED_HOLDER_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
 interface PidFilePayload {
   pid: number;
   startedAt: string;
@@ -23,20 +31,49 @@ function isPidFilePayload(value: unknown): value is PidFilePayload {
   );
 }
 
-function isProcessAlive(pid: number): boolean {
+/** `unowned`: the PID exists but belongs to a user this process cannot signal. */
+type ProcessLiveness = 'alive' | 'dead' | 'unowned';
+
+function probeProcess(pid: number): ProcessLiveness {
   try {
     process.kill(pid, 0);
-    return true;
+    return 'alive';
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;
-    if (code === 'ESRCH') {
-      return false;
-    }
-    // EPERM means the PID exists but we don't own it — still alive.
-    return code === 'EPERM';
+    return code === 'EPERM' ? 'unowned' : 'dead';
   }
 }
 
+function isCredibleStartTime(startedAt: string): boolean {
+  const started = Date.parse(startedAt);
+  if (Number.isNaN(started)) return false;
+  // Absolute distance, so a start time far enough ahead of this clock to be
+  // impossible counts against the holder just as an ancient one does, while
+  // ordinary skew between two machines' clocks does not.
+  return Math.abs(Date.now() - started) <= UNOWNED_HOLDER_MAX_AGE_MS;
+}
+
+/**
+ * Describes why a recorded holder does not hold the lock, or null when it must
+ * be treated as still running.
+ *
+ * A probe that succeeds is conclusive and is never overridden: taking the lock
+ * from a process known to be running is the concurrent-writer hazard the lock
+ * exists to prevent. EPERM is not conclusive — it is equally what a PID
+ * recycled by an unrelated process looks like — so it is trusted only while the
+ * holder's own recorded start time keeps it plausible.
+ */
+function staleHolderReason(payload: PidFilePayload): string | null {
+  const liveness = probeProcess(payload.pid);
+  if (liveness === 'alive') return null;
+  if (liveness === 'dead') return `PID=${payload.pid} is not alive`;
+  if (isCredibleStartTime(payload.startedAt)) return null;
+  return (
+    `PID=${payload.pid} belongs to another user and its recorded start time ` +
+    `${payload.startedAt} is not one a running sync could have`
+  );
+}
+
 interface PidFileInspection {
   /** null when the file holds content no sync wrote, which counts as stale. */
   payload: PidFilePayload | null;
@@ -173,7 +210,25 @@ export interface ProcessLockHandle {
   release(): void;
 }
 
-export function acquireSyncProcessLock(projectRoot: string): ProcessLockHandle {
+export interface SyncProcessLockOptions {
+  /**
+   * Removes an existing pidfile whatever its holder looks like. The operator's
+   * escape hatch for a lock whose holder cannot be disproved — a PID recycled
+   * by this user's own process, or one reported by a container's PID namespace.
+   */
+  breakLock?: boolean;
+}
+
+function holderLabel(inspection: PidFileInspection): string {
+  return inspection.payload
+    ? ` held by PID=${inspection.payload.pid} (started ${inspection.payload.startedAt})`
+    : '';
+}
+
+export function acquireSyncProcessLock(
+  projectRoot: string,
+  options?: SyncProcessLockOptions
+): ProcessLockHandle {
   const pidFilePath = path.join(projectRoot, PROCESS_LOCK_FILE_NAME);
 
   // Every acquisition goes through the same O_EXCL create, including the one
@@ -190,10 +245,26 @@ export function acquireSyncProcessLock(projectRoot: string): ProcessLockHandle {
     }
 
     const existing = inspectPidFile(pidFilePath);
-    if (existing?.payload && isProcessAlive(existing.payload.pid)) {
+
+    // Honoured on the first attempt only: it breaks the lock the operator saw,
+    // not whichever sync happens to take the freed slot afterwards.
+    if (existing !== null && attempt === 1 && options?.breakLock) {
+      if (reclaimStalePidFile(pidFilePath, existing)) {
+        Logger.warn(
+          `--break-lock: removed ${PROCESS_LOCK_FILE_NAME}${holderLabel(existing)}. ` +
+            'If that sync is still running, both runs can now write the same files concurrently.'
+        );
+      }
+      continue;
+    }
+
+    const staleReason = existing?.payload
+      ? staleHolderReason(existing.payload)
+      : null;
+    if (existing?.payload && staleReason === null) {
       throw new ConfigError(
         `Another \`deepl sync\` process is running in this directory (PID=${existing.payload.pid}, started ${existing.payload.startedAt}). Wait for it to finish or kill it before retrying.`,
-        `If the process is definitely not running, remove ${PROCESS_LOCK_FILE_NAME} manually and retry.`
+        `If the process is definitely not running, retry with --break-lock, or remove ${PROCESS_LOCK_FILE_NAME} manually.`
       );
     }
 
@@ -207,11 +278,8 @@ export function acquireSyncProcessLock(projectRoot: string): ProcessLockHandle {
     // A pidfile that vanished between the failed create and the read needs no
     // reclaim; retry the create directly.
     if (existing !== null && reclaimStalePidFile(pidFilePath, existing)) {
-      const stalePidLabel = existing.payload
-        ? `PID=${existing.payload.pid}`
-        : 'unknown PID';
       Logger.warn(
-        `Removed stale ${PROCESS_LOCK_FILE_NAME} (${stalePidLabel} is not alive); reclaiming lock.`
+        `Removed stale ${PROCESS_LOCK_FILE_NAME} (${staleReason ?? 'unknown PID is not alive'}); reclaiming lock.`
       );
     }
   }
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index de80e97c..904b0c14 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -79,6 +79,12 @@ export interface SyncOptions {
    * throws or is cancelled before its own successful-completion cleanup runs.
    */
   backupTracker?: Set<string>;
+  /**
+   * Removes an existing process-lock pidfile whatever its holder looks like.
+   * Operator-driven and per run: watch mode must not carry it into later
+   * passes, or the lock stops arbitrating for the rest of the session.
+   */
+  breakLock?: boolean;
 }
 
 export interface SyncFileResult {
@@ -138,7 +144,9 @@ export class SyncService {
     config: ResolvedSyncConfig,
     options?: SyncOptions
   ): Promise<SyncResult> {
-    const processLock = acquireSyncProcessLock(config.projectRoot);
+    const processLock = acquireSyncProcessLock(config.projectRoot, {
+      breakLock: options?.breakLock,
+    });
     // Watch mode owns its own sweep + backup cleanup via `backupTracker`;
     // only the non-watch runs (single `deepl sync`, `sync push/pull/export`,
     // etc.) need the startup sweep and per-run signal cleanup wired up here.
diff --git a/tests/e2e/cli-sync-break-lock.e2e.test.ts b/tests/e2e/cli-sync-break-lock.e2e.test.ts
new file mode 100644
index 00000000..5e90f686
--- /dev/null
+++ b/tests/e2e/cli-sync-break-lock.e2e.test.ts
@@ -0,0 +1,215 @@
+/**
+ * E2E tests for recovery from a `deepl sync` pidfile whose holder cannot be
+ * disproved.
+ *
+ * Two escapes exist and both are exercised through the real CLI: a holder this
+ * user cannot signal ages out of credibility, and `--break-lock` removes any
+ * pidfile on the operator's word. Every command that takes the lock —
+ * `sync`, `sync resolve`, `sync pull` — must offer the flag.
+ */
+
+import { spawnSync, SpawnSyncReturns } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+const PIDFILE_NAME = '.deepl-sync.lock.pidfile';
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * True when this user cannot signal PID 1, which is the case the ageing rule
+ * exists for. A test process running as root can signal it and would see a
+ * genuinely live holder instead.
+ */
+const CANNOT_SIGNAL_INIT = ((): boolean => {
+  try {
+    process.kill(1, 0);
+    return false;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM';
+  }
+})();
+
+function makeTmpProject(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-break-lock-'));
+  const configDir = path.join(dir, 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(configDir, 'config.json'),
+    JSON.stringify({
+      auth: { apiKey: 'test-key:fx' },
+      api: { baseUrl: 'http://127.0.0.1:1', usePro: false },
+      cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+      output: { format: 'text', verbose: false, color: false },
+      defaults: {
+        targetLangs: [],
+        formality: 'default',
+        preserveFormatting: true,
+      },
+    }),
+    { mode: 0o600 }
+  );
+  const localesDir = path.join(dir, 'locales');
+  fs.mkdirSync(localesDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(localesDir, 'en.json'),
+    JSON.stringify({ greeting: 'Hello' }, null, 2) + '\n'
+  );
+  fs.writeFileSync(
+    path.join(dir, '.deepl-sync.yaml'),
+    [
+      'version: 1',
+      'source_locale: en',
+      'target_locales:',
+      '  - de',
+      'buckets:',
+      '  json:',
+      '    include:',
+      '      - "locales/en.json"',
+      'tms:',
+      '  enabled: true',
+      '  server: http://127.0.0.1:1',
+      '  project_id: proj-test',
+      '',
+    ].join('\n')
+  );
+  return dir;
+}
+
+interface RunResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+  combined: string;
+}
+
+function run(args: string[], cwd: string): RunResult {
+  const result: SpawnSyncReturns<string> = spawnSync(
+    'node',
+    [CLI_PATH, ...args],
+    {
+      encoding: 'utf-8',
+      cwd,
+      env: {
+        ...process.env,
+        DEEPL_CONFIG_DIR: path.join(cwd, 'config'),
+        DEEPL_API_KEY: 'test-key:fx',
+        TMS_API_KEY: 'tms-test-key',
+        NO_COLOR: '1',
+      },
+      timeout: 20000,
+    }
+  );
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+  return {
+    status: result.status ?? 1,
+    stdout,
+    stderr,
+    combined: stdout + stderr,
+  };
+}
+
+describe('deepl sync lock recovery', () => {
+  let tmpDir: string;
+  let pidFile: string;
+
+  beforeEach(() => {
+    tmpDir = makeTmpProject();
+    pidFile = path.join(tmpDir, PIDFILE_NAME);
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tmpDir))
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function plantHolder(pid: number, ageMs: number): void {
+    fs.writeFileSync(
+      pidFile,
+      JSON.stringify({
+        pid,
+        startedAt: new Date(Date.now() - ageMs).toISOString(),
+      })
+    );
+  }
+
+  describe('a holder that is genuinely running', () => {
+    it('refuses the sync and names --break-lock as the way out', () => {
+      plantHolder(process.pid, 60_000);
+
+      const result = run(['sync', '--dry-run'], tmpDir);
+
+      expect(result.status).toBe(7);
+      expect(result.combined).toContain(`PID=${process.pid}`);
+      expect(result.combined).toContain('--break-lock');
+      expect(fs.existsSync(pidFile)).toBe(true);
+    });
+
+    it('proceeds with --break-lock, reporting the holder it removed', () => {
+      plantHolder(process.pid, 60_000);
+
+      const result = run(['sync', '--dry-run', '--break-lock'], tmpDir);
+
+      expect(result.status).toBe(0);
+      expect(result.combined).toContain('--break-lock');
+      expect(result.combined).toContain(`PID=${process.pid}`);
+      expect(fs.existsSync(pidFile)).toBe(false);
+    });
+
+    it('offers --break-lock on sync resolve, which takes the same lock', () => {
+      plantHolder(process.pid, 60_000);
+
+      const refused = run(['sync', 'resolve'], tmpDir);
+      expect(refused.status).toBe(7);
+
+      const broken = run(['sync', 'resolve', '--break-lock'], tmpDir);
+      expect(broken.status).toBe(0);
+      expect(broken.combined).toMatch(/No merge conflicts/i);
+    });
+
+    it('offers --break-lock on sync pull, which takes the same lock', () => {
+      plantHolder(process.pid, 60_000);
+
+      const refused = run(['sync', 'pull'], tmpDir);
+      expect(refused.status).toBe(7);
+      expect(refused.combined).toMatch(/Another `deepl sync` process/);
+
+      // The pull then stops at the TMS destination-trust gate, which is the
+      // next guard in its path and not the lock's business; what matters here
+      // is that the lock is gone and the run got past it.
+      const broken = run(['sync', 'pull', '--break-lock'], tmpDir);
+      expect(broken.combined).toContain('--break-lock: removed');
+      expect(broken.combined).not.toMatch(/Another `deepl sync` process/);
+      expect(fs.existsSync(pidFile)).toBe(false);
+    });
+  });
+
+  // Skipped wholesale rather than asserted loosely when this process can
+  // signal PID 1: as root the holder is genuinely alive, which is a different
+  // case with a different correct answer.
+  (CANNOT_SIGNAL_INIT ? describe : describe.skip)(
+    'a holder this user cannot signal',
+    () => {
+      it('reclaims the lock once the recorded start time is too old for a sync', () => {
+        plantHolder(1, 30 * DAY_MS);
+
+        const result = run(['sync', '--dry-run'], tmpDir);
+
+        expect(result.status).toBe(0);
+        expect(result.combined).toMatch(/stale/i);
+        expect(result.combined).toContain('PID=1');
+      });
+
+      it('still refuses one that started moments ago', () => {
+        plantHolder(1, 60_000);
+
+        const result = run(['sync', '--dry-run'], tmpDir);
+
+        expect(result.status).toBe(7);
+        expect(fs.existsSync(pidFile)).toBe(true);
+      });
+    }
+  );
+});
diff --git a/tests/unit/cli/register-sync.commander-snapshot.test.ts b/tests/unit/cli/register-sync.commander-snapshot.test.ts
index a0b74430..6dfe73b8 100644
--- a/tests/unit/cli/register-sync.commander-snapshot.test.ts
+++ b/tests/unit/cli/register-sync.commander-snapshot.test.ts
@@ -171,6 +171,19 @@ const PULL_DRY_RUN: OptionSnapshot = {
   mandatory: false,
 };
 
+const SUBCOMMAND_BREAK_LOCK: OptionSnapshot = {
+  flags: '--break-lock',
+  description:
+    'Take the sync lock even when .deepl-sync.lock.pidfile names a process that looks alive',
+  defaultValue: undefined,
+  negate: false,
+  choices: undefined,
+  required: false,
+  optional: false,
+  variadic: false,
+  mandatory: false,
+};
+
 const PARENT_SYNC_CONFIG_OPT: OptionSnapshot = {
   flags: '--sync-config <path>',
   description: 'Path to .deepl-sync.yaml (default: auto-detect)',
@@ -246,6 +259,18 @@ const EXPECTED: CommandSnapshot = {
         variadic: false,
         mandatory: false,
       },
+      {
+        flags: '--break-lock',
+        description:
+          'Take the sync lock even when .deepl-sync.lock.pidfile names a process that looks alive. Use only when that sync is definitely not running: two concurrent syncs overwrite the same target files.',
+        defaultValue: undefined,
+        negate: false,
+        choices: undefined,
+        required: false,
+        optional: false,
+        variadic: false,
+        mandatory: false,
+      },
       {
         flags: '--ci',
         description: 'Alias for --frozen',
@@ -566,6 +591,7 @@ const EXPECTED: CommandSnapshot = {
         FORMAT_OPT,
         LOCALE_FILTER_OPT,
         PULL_DRY_RUN,
+        SUBCOMMAND_BREAK_LOCK,
         SYNC_CONFIG_OPT,
       ].sort((a, b) => a.flags.localeCompare(b.flags)),
       subcommands: [],
@@ -581,9 +607,12 @@ const EXPECTED: CommandSnapshot = {
     {
       name: 'resolve',
       description: 'Resolve git merge conflicts in .deepl-sync.lock',
-      options: [FORMAT_OPT, RESOLVE_DRY_RUN, SYNC_CONFIG_OPT].sort((a, b) =>
-        a.flags.localeCompare(b.flags)
-      ),
+      options: [
+        FORMAT_OPT,
+        RESOLVE_DRY_RUN,
+        SUBCOMMAND_BREAK_LOCK,
+        SYNC_CONFIG_OPT,
+      ].sort((a, b) => a.flags.localeCompare(b.flags)),
       subcommands: [],
     },
     {
diff --git a/tests/unit/sync/sync-command.test.ts b/tests/unit/sync/sync-command.test.ts
index 304a14ca..11342e38 100644
--- a/tests/unit/sync/sync-command.test.ts
+++ b/tests/unit/sync/sync-command.test.ts
@@ -1521,6 +1521,64 @@ describe('SyncCommand', () => {
       processOnSpy.mockRestore();
     });
 
+    /**
+     * --break-lock removes a pidfile whose holder looks alive. Repeating it on
+     * every watch cycle would leave the session unable to arbitrate against
+     * another sync in the same directory for as long as it runs.
+     */
+    it('applies --break-lock to the initial sync only, not to later watch cycles', async () => {
+      const registeredHandlers: Array<(p?: string) => void> = [];
+      mockWatcherOn.mockImplementation(
+        (event: string, handler: (p?: string) => void) => {
+          if (event === 'change' || event === 'add') {
+            registeredHandlers.push(handler);
+          }
+          return mockWatcher;
+        }
+      );
+
+      const mockService = createMockSyncService(makeResult());
+      const command = new SyncCommand(mockService);
+
+      const sigintListeners: Array<() => void> = [];
+      const processOnSpy = jest.spyOn(process, 'on').mockImplementation(((
+        event: string,
+        listener: () => void
+      ) => {
+        if (event === 'SIGINT') sigintListeners.push(listener);
+        return process;
+      }) as unknown as ProcessOn);
+
+      const runPromise = command.run({
+        watch: true,
+        debounce: 50,
+        breakLock: true,
+      });
+
+      await flushWatchSetup();
+
+      expect(mockService.sync).toHaveBeenCalledTimes(1);
+      expect(mockService.sync.mock.calls[0]![1]).toMatchObject({
+        breakLock: true,
+      });
+
+      expect(registeredHandlers.length).toBeGreaterThan(0);
+      registeredHandlers[0]!();
+      await jest.advanceTimersByTimeAsync(60);
+      await flushUntil(
+        () => mockService.sync.mock.calls.length >= 2,
+        'second sync from watch cycle'
+      );
+
+      expect(mockService.sync.mock.calls[1]![1]).toMatchObject({
+        breakLock: false,
+      });
+
+      for (const listener of sigintListeners) listener();
+      await runPromise;
+      processOnSpy.mockRestore();
+    });
+
     it('returns SIGINT/SIGTERM listener counts to their baseline after shutdown', async () => {
       const result = makeResult();
       const mockService = createMockSyncService(result);
diff --git a/tests/unit/sync/sync-process-lock.test.ts b/tests/unit/sync/sync-process-lock.test.ts
index 87e93a65..30e3d232 100644
--- a/tests/unit/sync/sync-process-lock.test.ts
+++ b/tests/unit/sync/sync-process-lock.test.ts
@@ -24,6 +24,7 @@ jest.mock('../../../src/utils/logger', () => ({
 import {
   acquireSyncProcessLock,
   PROCESS_LOCK_FILE_NAME,
+  UNOWNED_HOLDER_MAX_AGE_MS,
 } from '../../../src/sync/sync-process-lock';
 import { Logger } from '../../../src/utils/logger';
 import { ConfigError } from '../../../src/utils/errors';
@@ -40,6 +41,11 @@ function errnoError(code: string): NodeJS.ErrnoException {
   return error;
 }
 
+/** A start time the given number of milliseconds in the past, as a holder records it. */
+function startedMsAgo(ageMs: number): string {
+  return new Date(Date.now() - ageMs).toISOString();
+}
+
 describe('acquireSyncProcessLock', () => {
   let projectRoot: string;
   let pidFilePath: string;
@@ -130,7 +136,7 @@ describe('acquireSyncProcessLock', () => {
     });
 
     it('refuses the lock when the probe reports EPERM, which means a process this user does not own', () => {
-      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      plantPidFile({ pid: 4242, startedAt: startedMsAgo(60_000) });
       jest.spyOn(process, 'kill').mockImplementation(() => {
         throw errnoError('EPERM');
       });
@@ -139,16 +145,30 @@ describe('acquireSyncProcessLock', () => {
     });
 
     it('names the holding PID and its start time when refusing', () => {
-      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      const startedAt = startedMsAgo(60_000);
+      plantPidFile({ pid: 4242, startedAt });
       jest.spyOn(process, 'kill').mockImplementation(() => {
         throw errnoError('EPERM');
       });
 
       expect(() => acquireSyncProcessLock(projectRoot)).toThrow(
-        /PID=4242, started 2026-01-01T00:00:00\.000Z/
+        new RegExp(`PID=4242, started ${startedAt.replace(/\./g, '\\.')}`)
       );
     });
 
+    it('tells the operator how to break a lock it refuses', () => {
+      plantPidFile({ pid: process.pid, startedAt: startedMsAgo(60_000) });
+
+      let caught: unknown;
+      try {
+        acquireSyncProcessLock(projectRoot);
+      } catch (error) {
+        caught = error;
+      }
+
+      expect((caught as ConfigError).suggestion).toMatch(/--break-lock/);
+    });
+
     it('reclaims the lock when the probe reports ESRCH', () => {
       plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
       jest.spyOn(process, 'kill').mockImplementation(() => {
@@ -177,6 +197,155 @@ describe('acquireSyncProcessLock', () => {
     });
   });
 
+  /**
+   * EPERM says the PID exists and belongs to someone else, which is equally
+   * what a PID recycled by an unrelated process looks like. Without an upper
+   * bound on the recorded start time such a pidfile refuses every later sync
+   * for as long as it exists.
+   */
+  describe('a holder this user cannot probe', () => {
+    function plantUnownedHolder(startedAt: unknown): void {
+      plantPidFile({ pid: 4242, startedAt });
+      jest.spyOn(process, 'kill').mockImplementation((pid: number) => {
+        if (pid === 4242) throw errnoError('EPERM');
+        return true;
+      });
+    }
+
+    it('reclaims the lock when the recorded start time is older than any sync can run', () => {
+      plantUnownedHolder(startedMsAgo(30 * UNOWNED_HOLDER_MAX_AGE_MS));
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(ownerPid()).toBe(process.pid);
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('PID=4242')
+      );
+      handle.release();
+    });
+
+    it('says why it distrusted the holder when it reclaims', () => {
+      plantUnownedHolder(startedMsAgo(30 * UNOWNED_HOLDER_MAX_AGE_MS));
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(Logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('another user')
+      );
+      handle.release();
+    });
+
+    it('reclaims the lock when the recorded start time is not a date', () => {
+      plantUnownedHolder('halfway through last tuesday');
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(ownerPid()).toBe(process.pid);
+      handle.release();
+    });
+
+    it('reclaims the lock when the recorded start time is impossibly far ahead of this clock', () => {
+      plantUnownedHolder(startedMsAgo(-30 * UNOWNED_HOLDER_MAX_AGE_MS));
+
+      const handle = acquireSyncProcessLock(projectRoot);
+
+      expect(ownerPid()).toBe(process.pid);
+      handle.release();
+    });
+
+    it('refuses a holder that started moments ago', () => {
+      plantUnownedHolder(startedMsAgo(1_000));
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+      expect(ownerPid()).toBe(4242);
+    });
+
+    it('refuses a holder still inside the age ceiling', () => {
+      plantUnownedHolder(startedMsAgo(UNOWNED_HOLDER_MAX_AGE_MS - 60_000));
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+      expect(ownerPid()).toBe(4242);
+    });
+
+    it('refuses a holder whose clock runs a little ahead of this one', () => {
+      plantUnownedHolder(startedMsAgo(-60_000));
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+      expect(ownerPid()).toBe(4242);
+    });
+
+    /**
+     * Ageing exists to escape a verdict nothing can disprove. A probe that
+     * succeeds is not that: taking the lock from a process known to be running
+     * is the concurrent-writer hazard the lock exists to prevent.
+     */
+    it('never ages out a holder the probe reports as genuinely running', () => {
+      plantPidFile({
+        pid: process.pid,
+        startedAt: startedMsAgo(365 * UNOWNED_HOLDER_MAX_AGE_MS),
+      });
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+      expect(ownerPid()).toBe(process.pid);
+    });
+  });
+
+  describe('breakLock', () => {
+    it('takes the lock from a holder that is genuinely running', () => {
+      plantPidFile({ pid: 4242, startedAt: startedMsAgo(60_000) });
+      jest.spyOn(process, 'kill').mockImplementation(() => true);
+
+      const handle = acquireSyncProcessLock(projectRoot, { breakLock: true });
+
+      expect(ownerPid()).toBe(process.pid);
+      handle.release();
+    });
+
+    it('names the holder it broke and warns what that permits', () => {
+      const startedAt = startedMsAgo(60_000);
+      plantPidFile({ pid: 4242, startedAt });
+      jest.spyOn(process, 'kill').mockImplementation(() => true);
+
+      const handle = acquireSyncProcessLock(projectRoot, { breakLock: true });
+
+      const warnings = jest
+        .mocked(Logger.warn)
+        .mock.calls.map((args) => String(args[0]))
+        .join('\n');
+      expect(warnings).toContain('PID=4242');
+      expect(warnings).toContain(startedAt);
+      expect(warnings).toMatch(/concurrent|same files/i);
+      handle.release();
+    });
+
+    it('is silent when there was no lock to break', () => {
+      const handle = acquireSyncProcessLock(projectRoot, { breakLock: true });
+
+      expect(ownerPid()).toBe(process.pid);
+      expect(Logger.warn).not.toHaveBeenCalled();
+      handle.release();
+    });
+
+    it('reports the running sync rather than breaking twice when a new holder takes the freed slot', () => {
+      plantPidFile({ pid: 4242, startedAt: startedMsAgo(60_000) });
+      jest.spyOn(process, 'kill').mockImplementation(() => true);
+      const realRename = fsModule.renameSync;
+      let broken = false;
+      jest.spyOn(fsModule, 'renameSync').mockImplementation((from, to) => {
+        realRename(from, to);
+        if (!broken) {
+          broken = true;
+          plantPidFile({ pid: 5555, startedAt: startedMsAgo(1_000) });
+        }
+      });
+
+      expect(() =>
+        acquireSyncProcessLock(projectRoot, { breakLock: true })
+      ).toThrow(/PID=5555/);
+      expect(ownerPid()).toBe(5555);
+    });
+  });
+
   describe('unreadable pidfile contents', () => {
     it.each([
       ['content that is not JSON', 'not json at all'],

From 77c1f90f463c7f6e5a4abd335838cd9b7133210b Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 20:27:50 +0200
Subject: [PATCH 225/256] fix(sync): refuse to rewrite a target another sync
 configuration writes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A rewrite emits exactly the keys its own configuration defines, so a target
file has one owner. The existing guard refuses that collision only within one
bucket; across two configurations nothing saw it, because each has its own
project root, its own lockfile and — the process lock being keyed on the
project root — its own pidfile.

Measured through the CLI on nested roots (a repository-level config and a
package-level one whose target_path_pattern resolved into the same directory):
the file held whichever ran last, both runs reported success at exit 0, and
each later run deleted the other's keys and re-billed its own. That flip-flop
needs no concurrency at all, which is why re-keying the lock was never the
fix: serialising the two runs would not stop them destroying each other.

A run about to delete keys from a target now looks for another configuration
that accounts for them, with that configuration's lockfile as the evidence: a
configuration writes only inside its own project root, so one that also writes
this file is rooted at an ancestor directory of it, and a match requires that
lockfile to record those exact keys for the same locale. Judged in the
pre-read, before anything is translated, so a refusal costs nothing.

`deepl sync` then fails that locale through the landing site the unusable
target already uses — file untouched, keys recorded failed for the next run,
exit 12 — and `deepl sync pull`, which rebuilds the same file from its own
source keys and had the same defect, skips it under a new `shared_target`
reason. Keys added to a locale file by hand are unaffected: no lockfile
accounts for them, so they are still pruned with the usual warning.

Refs cli-8zn5.29
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |   2 +
 docs/SYNC.md                                  |  14 +
 src/sync/sync-foreign-owner.ts                | 135 ++++++
 src/sync/sync-process-bucket.ts               |  38 +-
 src/sync/sync-tms.ts                          |  37 +-
 ...red-target-two-configs.integration.test.ts | 395 ++++++++++++++++++
 tests/unit/sync/sync-foreign-owner.test.ts    | 199 +++++++++
 8 files changed, 822 insertions(+), 2 deletions(-)
 create mode 100644 src/sync/sync-foreign-owner.ts
 create mode 100644 tests/integration/sync-shared-target-two-configs.integration.test.ts
 create mode 100644 tests/unit/sync/sync-foreign-owner.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58d7424a..102cb189 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,6 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **sync**: **`deepl sync pull --format json` can now carry a `shared_target` entry in `skipped`.** A consumer iterating `skipped` will meet a reason it has not seen before, for a target file another sync configuration's lockfile accounts for keys in; such a locale is not counted in `pulled` or `replaced` and no lockfile entry is recorded for it. Every other reason, count and field is unchanged. See Fixed.
+
 - **sync**: **the `--format json` error envelope moves from stderr to stdout, for every sync subcommand at once.** A consumer that read the failure reason off stderr stops finding it there: `deepl sync … --format json 2>err.json` now captures only human-facing warnings, and the envelope arrives where `> out.json` already captured the success payload, so one redirection handles both cases. Exit codes are unchanged and remain the failure signal. Anything branching on *the presence of* stderr output still works — warnings still go there — but anything *parsing* stderr must switch to stdout. See Fixed.
 
 - **sync**: **`deepl sync validate` exits 8 where it exited 1 on a project whose target file cannot be read, and its `--format json` issues list gains a new check kind.** A consumer that treated exit 1 as "the CLI crashed" starts seeing the documented check-failure code with a full report attached, and a JSON consumer iterating `issues` will meet entries whose `check` is `unusable_target`, whose `key` and `file` are both the target path, and whose `source`/`translation` are empty. See Fixed.
@@ -157,6 +159,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: `deepl sync` and `deepl sync pull` no longer delete another sync configuration's translations from a target file both configurations write. A rewrite emits exactly the keys its own configuration defines, and the existing guard refuses that collision only *within* one bucket (two source files in one bucket resolving to one target); across two configurations nothing saw it, because each has its own project root, its own `.deepl-sync.lock` and — the process lock being keyed on the project root — its own pidfile. Measured through the CLI on nested roots (a repository-level config and a package-level one whose `target_path_pattern` resolved into the same directory): the file ended up holding whichever ran last, both runs reported success at exit 0, and each later run deleted the other's keys and re-billed its own — a flip-flop with no concurrency needed, which is why the lock's key was never the fix. A run that is about to delete keys from a target now looks for another configuration that accounts for them, using that configuration's lockfile as the evidence: a configuration writes only inside its own project root, so one that also writes this file is rooted at an ancestor directory of it, and a match requires that lockfile to record those exact keys for the same locale. When it does, the file is left exactly as it stands — `deepl sync` fails that locale (nothing written, nothing billed for it, keys recorded `failed` so the next run retries them, exit 12) and `deepl sync pull` skips it under a new `shared_target` reason. Both name the other lockfile, the shared keys and the remedy. Keys added to a locale file by hand are unaffected: no lockfile accounts for them, so they are still pruned with the usual warning.
+
 - **sync**: a pidfile naming a process this user cannot signal no longer refuses every later sync indefinitely. `kill(pid, 0)` answers EPERM for a PID that exists but belongs to another user — which is equally what a PID recycled by an unrelated process, or one from a container's PID namespace, looks like — and that was read as "alive" with no upper bound, while the `startedAt` the pidfile has always recorded was never consulted. Measured through the CLI: a pidfile naming PID 1 with a start time 30 days old refused `deepl sync` with exit 7 on every attempt. Such a holder is now trusted only while its recorded start time is within 24 hours and readable as a date (a time impossibly far in the future counts against it too), after which the lock is reclaimed with a warning naming the PID and the reason. A holder the probe reports as **genuinely running** is never aged out, however old the lock — taking the lock from a live sync is the concurrent-writer hazard the lock exists to prevent — so that case gets `--break-lock` instead (see Added). The refusal message now names the flag.
 
 - **watch**: a real document named like an atomic-write temp sibling (`*.tmp.<digits>.<letters>`) is no longer skipped. The check pattern-matched the file **name**, though its own docstring promised "a temp sibling of an in-flight atomic write" and the in-flight set was already there; the skip also happened before the warn-once branch, so nothing said the file had been passed over. It is now a membership test against that set, with the name pattern still honoured for a path that no longer exists — a temp sibling whose rename completed before the watcher's event arrived.
diff --git a/docs/API.md b/docs/API.md
index ef3bdc06..017d5532 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1551,6 +1551,8 @@ Both commands print the resolved destination origin on success, in text and JSON
 
 **JSON success envelope (stable within a major version):** `{ "ok": true, "pulled": <n>, "skipped": [...], "server": "<origin>" }`
 
+Each `skipped` entry carries a `reason`: `target_missing`, `no_matches`, `pipe_pluralization`, `key_collision`, `unusable_target`, `plural_entry`, or `shared_target` — the last for a target file another sync configuration's `.deepl-sync.lock` accounts for keys in, which is left untouched rather than rebuilt from this configuration's keys alone. See [docs/SYNC.md#two-configurations-writing-one-file](./SYNC.md#two-configurations-writing-one-file).
+
 #### Examples
 
 **Basic sync:**
diff --git a/docs/SYNC.md b/docs/SYNC.md
index f3a5f36b..cbd1e7e6 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -81,6 +81,18 @@ Check the file into git before re-running if another tool or a merge wrote it.
 
 It warns rather than refusing because by that point the target files are written and their translations billed; declining to record them would leave the next run to translate and bill all of them again.
 
+### Two configurations writing one file
+
+A rewrite emits exactly the keys its own configuration defines, so a target file has one owner. Two configurations can end up sharing one anyway when their project roots nest — a repository-level `.deepl-sync.yaml` and a package-level one whose `target_path_pattern` resolves into the same directory, or two config files in one directory used with `--sync-config`. Nothing about the process lock helps here: it is keyed on the project root, so nested configurations take different pidfiles, and even run strictly one after another they would delete each other's keys and re-translate them on every run — measured as a target alternating between the two key sets, at exit 0 throughout, with each run reporting success.
+
+A run that is about to delete keys from a target now looks for another sync configuration that accounts for them. The evidence is the other `.deepl-sync.lock`: a configuration writes only inside its own project root, so one that also writes this file is rooted at one of the file's ancestor directories, and a match requires that its lockfile record those exact keys for the same locale. When it does, the file is left exactly as it stands:
+
+- `deepl sync` fails that locale — nothing written, nothing billed for it, the keys recorded `failed` so the next run retries them — and the run ends with exit code 12.
+- `deepl sync pull` skips that locale under the `shared_target` reason.
+
+Both name the other lockfile, the shared keys and the remedy: give each configuration its own target file, or merge them into one. Keys someone added to a locale file by hand are unaffected — no lockfile accounts for them, so they are still pruned with the usual warning. If the lockfile named is left over from a configuration that no longer writes the file, remove it.
+
+
 ## Supported File Formats
 
 | Format | Extensions | Used By |
@@ -1083,6 +1095,8 @@ Each target locale's approved dictionary is fetched exactly once per `sync pull`
 
 **A plural entry is left as it stands.** The export carries one string per key, which cannot fill a plural entry's forms (gettext `msgstr[N]`, an Android `<plurals>` element). Such a key is skipped under the `plural_entry` reason, is not counted as pulled or replaced, and no lockfile entry is recorded for it — see [A plural entry carried forward](#a-plural-entry-carried-forward).
 
+**A target file another sync configuration also writes is left untouched.** A pull rebuilds the target from this configuration's own source keys, so it would delete any key the file holds that this configuration does not account for. When a `.deepl-sync.lock` above that file — belonging to another configuration — records those keys for the same locale, the locale is skipped under the `shared_target` reason with a warning naming that lockfile, nothing is written and nothing is recorded. See [Two configurations writing one file](#two-configurations-writing-one-file).
+
 **A target file that cannot be read is left untouched.** Pull reads the existing target file so it can keep translations the export does not carry. If that file cannot be opened, cannot be parsed, or cannot be keyed unambiguously, the locale is skipped with a warning naming the file and the reason, and the file is not written — under the `key_collision` reason when keys collide (see [Key separators and colliding keys](#key-separators-and-colliding-keys)), which has its own remediation, and `unusable_target` otherwise. Pull deliberately does not fall back to reconstructing it from the source file in either case: that would replace the whole file with just the keys the export happened to carry. Only a file that is genuinely not there yet takes that fallback. See [A target file that cannot be read](#a-target-file-that-cannot-be-read).
 
 **Key-count limit:** The pull response is capped at **50,000 keys** (`MAX_PULL_KEY_COUNT`). Responses exceeding this limit are rejected with a `ValidationError` before any data is written. If your TMS project exceeds this threshold, partition the export by locale or paginate the pull on the TMS side before invoking `deepl sync pull`.
diff --git a/src/sync/sync-foreign-owner.ts b/src/sync/sync-foreign-owner.ts
new file mode 100644
index 00000000..0b795122
--- /dev/null
+++ b/src/sync/sync-foreign-owner.ts
@@ -0,0 +1,135 @@
+import * as path from 'path';
+import { safeReadFile } from '../utils/safe-read-file.js';
+import { LOCK_FILE_NAME } from './types.js';
+
+/** Another sync configuration's lockfile, and the keys it accounts for. */
+export interface ForeignKeyOwner {
+  /** Absolute path of the other configuration's lockfile. */
+  lockPath: string;
+  /** The queried keys that lockfile records for the locale, sorted. */
+  keys: string[];
+}
+
+export interface FindForeignKeyOwnerParams {
+  /** Absolute path of the target file holding the keys. */
+  targetAbsPath: string;
+  /** Absolute path of this run's own lockfile, which never counts as foreign. */
+  ownLockPath: string;
+  locale: string;
+  /** Keys the target holds that this configuration does not account for. */
+  keys: readonly string[];
+}
+
+/**
+ * A lockfile is only read up to this size. A sync lockfile is JSON proportional
+ * to the project's key count; anything larger than this is not one, and this
+ * walk reads files outside the project root, which no other read here does.
+ */
+const MAX_LOCK_FILE_BYTES = 64 * 1024 * 1024;
+
+function recordedKeysForLocale(parsed: unknown, locale: string): Set<string> {
+  const found = new Set<string>();
+  const entries = (parsed as { entries?: unknown }).entries;
+  if (typeof entries !== 'object' || entries === null) return found;
+  // Own enumerable properties only, at both levels: a lockfile is untrusted
+  // input, and an indexed lookup would resolve `constructor` or `toString`
+  // against Object.prototype and report them as recorded.
+  for (const perFile of Object.values(entries)) {
+    if (typeof perFile !== 'object' || perFile === null) continue;
+    for (const [key, entry] of Object.entries(perFile)) {
+      if (typeof entry !== 'object' || entry === null) continue;
+      const translations = (entry as { translations?: unknown }).translations;
+      if (typeof translations !== 'object' || translations === null) continue;
+      if (Object.hasOwn(translations, locale)) found.add(key);
+    }
+  }
+  return found;
+}
+
+/**
+ * Find another sync configuration that accounts for keys this run's target file
+ * holds but its own source and lockfile do not.
+ *
+ * A configuration writes only inside its own project root, so one that also
+ * writes this target must be rooted at one of the target's ancestor
+ * directories — which makes the search a walk up from the file rather than a
+ * scan of the tree. The walk continues above this run's own project root,
+ * because the other configuration is as likely to be the outer one as the inner
+ * one.
+ *
+ * The lockfile is the evidence, not the mere presence of another configuration:
+ * a match requires that it record these exact keys for this locale. That keeps a
+ * neighbouring configuration which happens to sit above the file from being
+ * blamed for keys someone added by hand.
+ */
+export async function findForeignKeyOwner(
+  params: FindForeignKeyOwnerParams
+): Promise<ForeignKeyOwner | null> {
+  if (params.keys.length === 0) return null;
+  const wanted = new Set(params.keys);
+
+  let dir = path.dirname(params.targetAbsPath);
+  for (;;) {
+    const lockPath = path.join(dir, LOCK_FILE_NAME);
+    if (lockPath !== params.ownLockPath) {
+      const recorded = await readRecordedKeys(lockPath, params.locale);
+      const shared = [...wanted].filter((key) => recorded.has(key));
+      if (shared.length > 0) {
+        return { lockPath, keys: shared.sort() };
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Why a target another configuration also writes was left alone.
+ *
+ * Phrased to follow the per-locale prefix its landing sites add, and to say what
+ * the run did NOT do: the other configuration's translations are still on disk,
+ * and nothing was recorded for this locale, so the next run retries it.
+ */
+export function sharedTargetMessage(
+  targetRelPath: string,
+  locale: string,
+  owner: ForeignKeyOwner,
+  retryCommand = 'deepl sync'
+): string {
+  const shown = owner.keys.slice(0, 3).map((key) => `"${key}"`);
+  const more = owner.keys.length > shown.length ? ', …' : '';
+  const one = owner.keys.length === 1;
+  return (
+    `${targetRelPath} is also written by another sync configuration: ` +
+    `${owner.lockPath} records ${owner.keys.length} of the ${one ? 'key' : 'keys'} this file ` +
+    `holds (${shown.join(', ')}${more}) for ${locale}. Rewriting it here emits only this ` +
+    `configuration's keys, which would delete ${one ? 'that one' : 'those'} — and the other ` +
+    "configuration's next run would delete this one's, so the two destroy each other's " +
+    'translations and re-translate them on every run. The file was left as it stands and ' +
+    'nothing was recorded for this locale. Give each configuration its own target file, or ' +
+    `merge them into one configuration, then run \`${retryCommand}\` again. If that lockfile ` +
+    'is left over from a configuration that no longer writes this file, remove it.'
+  );
+}
+
+async function readRecordedKeys(
+  lockPath: string,
+  locale: string
+): Promise<Set<string>> {
+  let raw: string;
+  try {
+    // A lockfile that cannot be read, is a symlink, or is not the JSON this tool
+    // writes is no evidence either way, and this walk must never be the thing
+    // that fails a sync.
+    raw = await safeReadFile(lockPath, 'utf-8');
+  } catch {
+    return new Set();
+  }
+  if (raw.length > MAX_LOCK_FILE_BYTES) return new Set();
+  try {
+    return recordedKeysForLocale(JSON.parse(raw), locale);
+  } catch {
+    return new Set();
+  }
+}
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index b71dafc4..0440c87e 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -1,5 +1,5 @@
 import * as path from 'path';
-import { resolveSyncLimits } from './types.js';
+import { LOCK_FILE_NAME, resolveSyncLimits } from './types.js';
 import { computeDiff } from './sync-differ.js';
 import {
   mapWithConcurrency,
@@ -8,6 +8,10 @@ import {
 import { ValidationError } from '../utils/errors.js';
 import { resolveTargetPath, assertPathWithinRoot } from './sync-utils.js';
 import { computeSourceHash, ensureFileEntries } from './sync-lock.js';
+import {
+  findForeignKeyOwner,
+  sharedTargetMessage,
+} from './sync-foreign-owner.js';
 import { getOwnMember, setOwnMember } from '../utils/own-members.js';
 import type { ResolvedSyncConfig } from './sync-config.js';
 import type { SyncLockFile, SyncLockTranslation } from './types.js';
@@ -366,6 +370,19 @@ export async function processBucket(
    * result over the copy nobody managed to read.
    */
   const unusableTargets = new Map<string, string>();
+  /**
+   * Locales whose target file holds keys another sync configuration's lockfile
+   * accounts for, with the explanation. Rewriting such a file emits only this
+   * configuration's keys, so the other configuration's translations would be
+   * deleted — and its next run would delete this one's.
+   *
+   * Judged before anything is translated, so a refusal costs nothing. Only
+   * single-locale targets can collide this way: a multi-locale (bilingual)
+   * parser writes back to the source file, which is this configuration's own.
+   */
+  const sharedTargets = new Map<string, string>();
+  const accountedKeys = new Set(diffs.map((diff) => diff.key));
+  const ownLockPath = path.join(config.projectRoot, LOCK_FILE_NAME);
   for (const locale of locales) {
     if (isMultiLocale) {
       existingTargetEntries.set(
@@ -398,6 +415,23 @@ export async function processBucket(
         locale,
         read.state === 'usable' ? read.translations : new Map()
       );
+      if (read.state === 'usable') {
+        const unaccountedFor = [...read.translations.keys()].filter(
+          (key) => !accountedKeys.has(key)
+        );
+        const owner = await findForeignKeyOwner({
+          targetAbsPath,
+          ownLockPath,
+          locale,
+          keys: unaccountedFor,
+        });
+        if (owner) {
+          sharedTargets.set(
+            locale,
+            sharedTargetMessage(targetRelPath, locale, owner)
+          );
+        }
+      }
     }
   }
 
@@ -428,6 +462,8 @@ export async function processBucket(
       try {
         const unusable = unusableTargets.get(locale);
         if (unusable) throw new Error(unusable);
+        const shared = sharedTargets.get(locale);
+        if (shared) throw new Error(shared);
         const result = await localeTranslator.translate({
           locale,
           relPath,
diff --git a/src/sync/sync-tms.ts b/src/sync/sync-tms.ts
index 109d2442..82fdb42c 100644
--- a/src/sync/sync-tms.ts
+++ b/src/sync/sync-tms.ts
@@ -21,6 +21,10 @@ import {
   isPluralEntry,
 } from './sync-utils.js';
 import { LOCK_FILE_NAME } from './types.js';
+import {
+  findForeignKeyOwner,
+  sharedTargetMessage,
+} from './sync-foreign-owner.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { mapWithConcurrency, PUSH_CONCURRENCY } from '../utils/concurrency.js';
 import {
@@ -45,7 +49,8 @@ export type SkipReason =
   | 'unusable_target'
   | 'untranslated'
   | 'needs_review'
-  | 'plural_entry';
+  | 'plural_entry'
+  | 'shared_target';
 
 export interface SkippedRecord {
   file: string;
@@ -75,6 +80,8 @@ const SKIP_REASON_LABELS: Record<SkipReason, string> = {
   needs_review: 'translation marked as needing review (not pushed)',
   plural_entry:
     'plural entry (one exported string cannot fill its forms; left as it stands)',
+  shared_target:
+    'target file also written by another sync configuration (left untouched)',
 };
 
 /**
@@ -311,6 +318,34 @@ export async function pullTranslations(
       const existingTargetEntries =
         read.state === 'usable' ? read.translations : new Map<string, string>();
 
+      // A pull rebuilds the file from this configuration's own source keys, so a
+      // target another configuration also writes loses that configuration's keys
+      // here exactly as `deepl sync` would. Judged from its lockfile, which is
+      // the only record of what it accounts for.
+      if (read.state === 'usable' && !isMultiLocale) {
+        const accounted = new Set(sourceEntries.map((entry) => entry.key));
+        for (const key of Object.keys(
+          getOwnMember(lockFile.entries, relPath) ?? {}
+        )) {
+          accounted.add(key);
+        }
+        const owner = await findForeignKeyOwner({
+          targetAbsPath,
+          ownLockPath: lockPath,
+          locale,
+          keys: [...existingTargetEntries.keys()].filter(
+            (key) => !accounted.has(key)
+          ),
+        });
+        if (owner) {
+          Logger.warn(
+            `Skipping ${targetRelPath}: ${sharedTargetMessage(targetRelPath, locale, owner, 'deepl sync pull')}`
+          );
+          skipped.push({ file: relPath, locale, reason: 'shared_target' });
+          continue;
+        }
+      }
+
       // The export is one string per key, which cannot fill a plural entry's
       // forms — gettext's msgstr[N], Android's <plurals> items. Applying it
       // would replace the file's own forms with the source's, so such a key is
diff --git a/tests/integration/sync-shared-target-two-configs.integration.test.ts b/tests/integration/sync-shared-target-two-configs.integration.test.ts
new file mode 100644
index 00000000..e1e1019f
--- /dev/null
+++ b/tests/integration/sync-shared-target-two-configs.integration.test.ts
@@ -0,0 +1,395 @@
+/**
+ * Integration tests for two sync configurations in nested project roots whose
+ * buckets resolve to one target file.
+ *
+ * Two source files inside ONE bucket that claim one target are refused by the
+ * bucket walker. Across two configurations nothing saw it: each has its own project root, its
+ * own `.deepl-sync.lock` and — because the process lock is keyed on the project
+ * root — its own pidfile, so the two neither exclude nor notice each other.
+ * Measured through the CLI before this guard: the file ends up holding whichever
+ * configuration wrote last, each later run deletes the other's keys and re-bills
+ * them, and every run reports success at exit 0.
+ *
+ * A run that would delete keys another configuration's lockfile accounts for now
+ * leaves that target alone and fails the locale instead.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+jest.unmock('fast-glob');
+
+import nock from 'nock';
+
+import { loadSyncConfig } from '../../src/sync/sync-config';
+import { pullTranslations } from '../../src/sync/sync-tms';
+import { createTmsClient } from '../../src/sync/tms-client';
+import {
+  expectTmsPull,
+  tmsConfig,
+  approvedTmsTrust,
+} from '../helpers/tms-nock';
+import {
+  createSyncHarness,
+  writeSyncConfig,
+  seedLockFile,
+} from '../helpers/sync-harness';
+import { DEEPL_FREE_API_URL } from '../helpers/nock-setup';
+import { LOCK_FILE_NAME } from '../../src/sync/types';
+import type { SyncLockEntry } from '../../src/sync/types';
+
+function replyEchoing(sent: string[]): nock.Scope {
+  return nock(DEEPL_FREE_API_URL)
+    .persist()
+    .post('/v2/translate')
+    .reply(200, (_uri, body) => {
+      const texts = new URLSearchParams(body as string).getAll('text');
+      sent.push(...texts);
+      return {
+        translations: texts.map((t) => ({
+          text: `[DE] ${t}`,
+          detected_source_language: 'EN',
+          billed_characters: t.length,
+        })),
+      };
+    });
+}
+
+function translatedEntry(sourceText: string, locale: string): SyncLockEntry {
+  return {
+    source_hash: `hash-of-${sourceText}`,
+    source_text: sourceText,
+    translations: {
+      [locale]: {
+        hash: `hash-of-${sourceText}`,
+        translated_at: '2026-08-01T00:00:00.000Z',
+        status: 'translated',
+        review_status: 'machine_translated',
+      },
+    },
+  };
+}
+
+describe('two sync configurations writing one target file', () => {
+  let base: string;
+  let pkg: string;
+  let sharedTarget: string;
+  let harness: ReturnType<typeof createSyncHarness>;
+  let errorSpy: jest.SpyInstance;
+  let warnSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    base = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-two-configs-'))
+    );
+    pkg = path.join(base, 'pkg');
+    fs.mkdirSync(path.join(pkg, 'locales'), { recursive: true });
+    fs.mkdirSync(path.join(pkg, 'strings'), { recursive: true });
+    sharedTarget = path.join(pkg, 'locales', 'de.json');
+
+    // The outer configuration, rooted at `base`, translates pkg/locales/en.json
+    // to its `de` sibling — pkg/locales/de.json.
+    fs.writeFileSync(
+      path.join(pkg, 'locales', 'en.json'),
+      JSON.stringify({ 'outer.one': 'Outer one', 'outer.two': 'Outer two' }),
+      'utf-8'
+    );
+    writeSyncConfig(base, {
+      targetLocales: ['de'],
+      buckets: { json: { include: ['pkg/locales/en.json'] } },
+    });
+
+    // The inner configuration, rooted at `pkg`, translates strings/en.json into
+    // the same file via its target_path_pattern.
+    fs.writeFileSync(
+      path.join(pkg, 'strings', 'en.json'),
+      JSON.stringify({ 'inner.one': 'Inner one', 'inner.two': 'Inner two' }),
+      'utf-8'
+    );
+    writeSyncConfig(pkg, {
+      targetLocales: ['de'],
+      buckets: {
+        json: {
+          include: ['strings/en.json'],
+          target_path_pattern: 'locales/{locale}.json',
+        },
+      },
+    });
+
+    harness = createSyncHarness({ parsers: ['json'] });
+    errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    errorSpy.mockRestore();
+    warnSpy.mockRestore();
+    harness.cleanup();
+    if (fs.existsSync(base)) fs.rmSync(base, { recursive: true, force: true });
+    nock.cleanAll();
+  });
+
+  function diagnostics(): string {
+    return [...errorSpy.mock.calls, ...warnSpy.mock.calls]
+      .map((args: unknown[]) => args.map((a) => String(a)).join(' '))
+      .join('\n');
+  }
+
+  /** The inner configuration has already run: its keys are in the shared file. */
+  function seedInnerRun(): void {
+    fs.writeFileSync(
+      sharedTarget,
+      JSON.stringify(
+        { 'inner.one': '[DE] Inner one', 'inner.two': '[DE] Inner two' },
+        null,
+        2
+      ) + '\n',
+      'utf-8'
+    );
+    seedLockFile(pkg, {
+      entries: {
+        'strings/en.json': {
+          'inner.one': translatedEntry('Inner one', 'de'),
+          'inner.two': translatedEntry('Inner two', 'de'),
+        },
+      },
+    });
+  }
+
+  /** The outer configuration has already run: its keys are in the shared file. */
+  function seedOuterRun(): void {
+    fs.writeFileSync(
+      sharedTarget,
+      JSON.stringify(
+        { 'outer.one': '[DE] Outer one', 'outer.two': '[DE] Outer two' },
+        null,
+        2
+      ) + '\n',
+      'utf-8'
+    );
+    seedLockFile(base, {
+      entries: {
+        'pkg/locales/en.json': {
+          'outer.one': translatedEntry('Outer one', 'de'),
+          'outer.two': translatedEntry('Outer two', 'de'),
+        },
+      },
+    });
+  }
+
+  it('leaves the other configuration translations in place rather than deleting them', async () => {
+    seedInnerRun();
+    const before = fs.readFileSync(sharedTarget, 'utf-8');
+    const sent: string[] = [];
+    replyEchoing(sent);
+
+    const result = await harness.syncService.sync(await loadSyncConfig(base));
+
+    expect(result.success).toBe(false);
+    expect(fs.readFileSync(sharedTarget, 'utf-8')).toBe(before);
+  });
+
+  it('spends nothing on a locale it is going to refuse', async () => {
+    seedInnerRun();
+    const sent: string[] = [];
+    replyEchoing(sent);
+
+    const result = await harness.syncService.sync(await loadSyncConfig(base));
+
+    expect(sent).toEqual([]);
+    expect(result.totalCharactersBilled).toBe(0);
+  });
+
+  it('names the other lockfile, the keys and a remedy', async () => {
+    seedInnerRun();
+    replyEchoing([]);
+
+    await harness.syncService.sync(await loadSyncConfig(base));
+
+    const output = diagnostics();
+    expect(output).toContain(path.join(pkg, LOCK_FILE_NAME));
+    expect(output).toContain('inner.one');
+    expect(output).toContain('inner.two');
+    expect(output).toMatch(/own target file|separate/i);
+  });
+
+  it('refuses in the other direction too, where the outer configuration wrote first', async () => {
+    seedOuterRun();
+    const before = fs.readFileSync(sharedTarget, 'utf-8');
+    const sent: string[] = [];
+    replyEchoing(sent);
+
+    const result = await harness.syncService.sync(await loadSyncConfig(pkg));
+
+    expect(result.success).toBe(false);
+    expect(sent).toEqual([]);
+    expect(fs.readFileSync(sharedTarget, 'utf-8')).toBe(before);
+    expect(diagnostics()).toContain(path.join(base, LOCK_FILE_NAME));
+  });
+
+  it('records the refused locale as failed, never as translated, so the next run retries it', async () => {
+    seedInnerRun();
+    replyEchoing([]);
+
+    await harness.syncService.sync(await loadSyncConfig(base));
+
+    const lock = JSON.parse(
+      fs.readFileSync(path.join(base, LOCK_FILE_NAME), 'utf-8')
+    ) as {
+      entries: Record<
+        string,
+        Record<string, { translations: Record<string, { status: string }> }>
+      >;
+    };
+    const statuses = Object.values(lock.entries)
+      .flatMap((perFile) => Object.values(perFile))
+      .map((entry) => entry.translations['de']?.status);
+    expect(statuses).toEqual(['failed', 'failed']);
+  });
+
+  describe('healthy cases the guard must not touch', () => {
+    it('still prunes hand-added keys no other configuration accounts for', async () => {
+      fs.writeFileSync(
+        sharedTarget,
+        JSON.stringify({ 'hand.added': 'Von Hand' }, null, 2) + '\n',
+        'utf-8'
+      );
+      const sent: string[] = [];
+      replyEchoing(sent);
+
+      const result = await harness.syncService.sync(await loadSyncConfig(base));
+
+      expect(result.success).toBe(true);
+      const written = JSON.parse(
+        fs.readFileSync(sharedTarget, 'utf-8')
+      ) as Record<string, string>;
+      expect(Object.keys(written).sort()).toEqual(['outer.one', 'outer.two']);
+      expect(diagnostics()).toContain('hand.added');
+    });
+
+    it('proceeds when the other lockfile accounts for those keys in another locale only', async () => {
+      fs.writeFileSync(
+        sharedTarget,
+        JSON.stringify({ 'inner.one': '[DE] Inner one' }, null, 2) + '\n',
+        'utf-8'
+      );
+      seedLockFile(pkg, {
+        entries: {
+          'strings/en.json': {
+            'inner.one': translatedEntry('Inner one', 'fr'),
+          },
+        },
+      });
+      replyEchoing([]);
+
+      const result = await harness.syncService.sync(await loadSyncConfig(base));
+
+      expect(result.success).toBe(true);
+    });
+
+    it('syncs both configurations once each has its own target file', async () => {
+      // The remedy the refusal names.
+      writeSyncConfig(pkg, {
+        targetLocales: ['de'],
+        buckets: {
+          json: {
+            include: ['strings/en.json'],
+            target_path_pattern: 'strings/{locale}.json',
+          },
+        },
+      });
+      const sent: string[] = [];
+      replyEchoing(sent);
+
+      const outer = await harness.syncService.sync(await loadSyncConfig(base));
+      const inner = await harness.syncService.sync(await loadSyncConfig(pkg));
+
+      expect(outer.success).toBe(true);
+      expect(inner.success).toBe(true);
+      expect(sent.sort()).toEqual([
+        'Inner one',
+        'Inner two',
+        'Outer one',
+        'Outer two',
+      ]);
+      const outerTarget = JSON.parse(
+        fs.readFileSync(sharedTarget, 'utf-8')
+      ) as Record<string, string>;
+      const innerTarget = JSON.parse(
+        fs.readFileSync(path.join(pkg, 'strings', 'de.json'), 'utf-8')
+      ) as Record<string, string>;
+      expect(Object.keys(outerTarget).sort()).toEqual([
+        'outer.one',
+        'outer.two',
+      ]);
+      expect(Object.keys(innerTarget).sort()).toEqual([
+        'inner.one',
+        'inner.two',
+      ]);
+    });
+  });
+  /**
+   * `deepl sync pull` rebuilds the same target from its own source key set, so it
+   * deletes another configuration's keys exactly as `deepl sync` did.
+   */
+  describe('sync pull over the same shared target', () => {
+    beforeEach(() => {
+      writeSyncConfig(base, {
+        targetLocales: ['de'],
+        buckets: { json: { include: ['pkg/locales/en.json'] } },
+        tms: tmsConfig(),
+      });
+      process.env['TMS_API_KEY'] = 'env-key';
+    });
+
+    afterEach(() => {
+      delete process.env['TMS_API_KEY'];
+    });
+
+    it('leaves the other configuration keys alone and reports the file skipped', async () => {
+      seedInnerRun();
+      const before = fs.readFileSync(sharedTarget, 'utf-8');
+      expectTmsPull(
+        'de',
+        { 'outer.one': 'Von der TMS', 'outer.two': 'Auch von der TMS' },
+        { auth: { apiKey: 'env-key' } }
+      );
+
+      const config = await loadSyncConfig(base);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+      const result = await pullTranslations(config, client, harness.registry);
+
+      expect(fs.readFileSync(sharedTarget, 'utf-8')).toBe(before);
+      expect(result.pulled).toBe(0);
+      expect(result.skipped).toEqual([
+        { file: 'pkg/locales/en.json', locale: 'de', reason: 'shared_target' },
+      ]);
+      expect(diagnostics()).toContain(path.join(pkg, LOCK_FILE_NAME));
+    });
+
+    it('still pulls into a target no other configuration accounts for', async () => {
+      fs.writeFileSync(
+        sharedTarget,
+        JSON.stringify({ 'outer.one': 'Alt' }, null, 2) + '\n',
+        'utf-8'
+      );
+      expectTmsPull(
+        'de',
+        { 'outer.one': 'Neu' },
+        { auth: { apiKey: 'env-key' } }
+      );
+
+      const config = await loadSyncConfig(base);
+      const client = await createTmsClient(config.tms!, approvedTmsTrust);
+      const result = await pullTranslations(config, client, harness.registry);
+
+      expect(result.pulled).toBe(1);
+      expect(result.skipped).toEqual([]);
+      const written = JSON.parse(
+        fs.readFileSync(sharedTarget, 'utf-8')
+      ) as Record<string, string>;
+      expect(written['outer.one']).toBe('Neu');
+    });
+  });
+});
diff --git a/tests/unit/sync/sync-foreign-owner.test.ts b/tests/unit/sync/sync-foreign-owner.test.ts
new file mode 100644
index 00000000..c57a75c5
--- /dev/null
+++ b/tests/unit/sync/sync-foreign-owner.test.ts
@@ -0,0 +1,199 @@
+/**
+ * Unit tests for locating another sync configuration that accounts for keys
+ * this run's target file holds.
+ *
+ * A configuration can only write files inside its own project root, so any
+ * configuration that also writes a given target must live in one of that
+ * target's ancestor directories. Its lockfile is the evidence: if it records
+ * the keys for the same locale, the file has two owners.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { findForeignKeyOwner } from '../../../src/sync/sync-foreign-owner';
+import { LOCK_FILE_NAME } from '../../../src/sync/types';
+import type { SyncLockEntry, SyncLockFile } from '../../../src/sync/types';
+
+function lockFileWith(
+  entries: Record<string, Record<string, string[]>>
+): SyncLockFile {
+  const built: SyncLockFile['entries'] = {};
+  for (const [sourceFile, keys] of Object.entries(entries)) {
+    const perFile: Record<string, SyncLockEntry> = {};
+    built[sourceFile] = perFile;
+    for (const [key, locales] of Object.entries(keys)) {
+      perFile[key] = {
+        source_hash: 'h',
+        source_text: 'Source text',
+        translations: Object.fromEntries(
+          locales.map((l) => [
+            l,
+            {
+              hash: 'h',
+              translated_at: '2026-08-01T00:00:00.000Z',
+              status: 'translated' as const,
+            },
+          ])
+        ),
+      };
+    }
+  }
+  return {
+    _comment: 'test',
+    version: 1,
+    generated_at: '2026-08-01T00:00:00.000Z',
+    source_locale: 'en',
+    entries: built,
+    stats: { total_keys: 0, total_translations: 0, last_sync: '' },
+  };
+}
+
+describe('findForeignKeyOwner', () => {
+  let root: string;
+  let ownRoot: string;
+  let targetPath: string;
+  let ownLockPath: string;
+
+  beforeEach(() => {
+    root = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-foreign-owner-'))
+    );
+    ownRoot = path.join(root, 'pkg');
+    fs.mkdirSync(path.join(ownRoot, 'locales'), { recursive: true });
+    targetPath = path.join(ownRoot, 'locales', 'de.json');
+    fs.writeFileSync(targetPath, '{}', 'utf-8');
+    ownLockPath = path.join(ownRoot, LOCK_FILE_NAME);
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  function writeLock(dir: string, lock: unknown): string {
+    const lockPath = path.join(dir, LOCK_FILE_NAME);
+    fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2), 'utf-8');
+    return lockPath;
+  }
+
+  const find = (keys: string[], locale = 'de') =>
+    findForeignKeyOwner({
+      targetAbsPath: targetPath,
+      ownLockPath,
+      locale,
+      keys,
+    });
+
+  it('returns null when no other lockfile sits above the target', async () => {
+    await expect(find(['outer.one'])).resolves.toBeNull();
+  });
+
+  it('returns null when the only lockfile above the target is this run own', async () => {
+    writeLock(
+      ownRoot,
+      lockFileWith({ 'strings/en.json': { 'outer.one': ['de'] } })
+    );
+
+    await expect(find(['outer.one'])).resolves.toBeNull();
+  });
+
+  it('finds a lockfile in a directory above this run project root', async () => {
+    const lockPath = writeLock(
+      root,
+      lockFileWith({ 'pkg/locales/en.json': { 'outer.one': ['de'] } })
+    );
+
+    await expect(find(['outer.one'])).resolves.toEqual({
+      lockPath,
+      keys: ['outer.one'],
+    });
+  });
+
+  it('finds a lockfile sitting in the target own directory', async () => {
+    const lockPath = writeLock(
+      path.join(ownRoot, 'locales'),
+      lockFileWith({ 'en.json': { 'outer.one': ['de'] } })
+    );
+
+    await expect(find(['outer.one'])).resolves.toMatchObject({ lockPath });
+  });
+
+  it('reports only the queried keys that lockfile accounts for', async () => {
+    writeLock(
+      root,
+      lockFileWith({
+        'pkg/locales/en.json': {
+          'outer.one': ['de'],
+          'outer.two': ['de'],
+          'unrelated.key': ['de'],
+        },
+      })
+    );
+
+    const owner = await find(['outer.one', 'outer.two', 'hand.added']);
+
+    expect(owner?.keys).toEqual(['outer.one', 'outer.two']);
+  });
+
+  it('returns null when the other lockfile records those keys for another locale only', async () => {
+    writeLock(
+      root,
+      lockFileWith({ 'pkg/locales/en.json': { 'outer.one': ['fr'] } })
+    );
+
+    await expect(find(['outer.one'])).resolves.toBeNull();
+  });
+
+  it('returns null when the other lockfile records different keys', async () => {
+    writeLock(
+      root,
+      lockFileWith({ 'pkg/locales/en.json': { 'something.else': ['de'] } })
+    );
+
+    await expect(find(['outer.one'])).resolves.toBeNull();
+  });
+
+  it('treats a lockfile it cannot parse as no evidence', async () => {
+    fs.writeFileSync(path.join(root, LOCK_FILE_NAME), 'not json', 'utf-8');
+
+    await expect(find(['outer.one'])).resolves.toBeNull();
+  });
+
+  it('treats a lockfile that is a symlink as no evidence', async () => {
+    const real = path.join(root, 'real-lock.json');
+    fs.writeFileSync(
+      real,
+      JSON.stringify(
+        lockFileWith({ 'pkg/locales/en.json': { 'outer.one': ['de'] } })
+      ),
+      'utf-8'
+    );
+    fs.symlinkSync(real, path.join(root, LOCK_FILE_NAME));
+
+    await expect(find(['outer.one'])).resolves.toBeNull();
+  });
+
+  it('does not read inherited object members as recorded translations', async () => {
+    writeLock(
+      root,
+      lockFileWith({ 'pkg/locales/en.json': { 'outer.one': ['de'] } })
+    );
+
+    // `constructor` and `toString` resolve on Object.prototype for both the
+    // entry map and the translations map, so a lookup that does not test own
+    // membership would report them as owned keys.
+    const owner = await find(['constructor', 'toString', 'outer.one']);
+
+    expect(owner?.keys).toEqual(['outer.one']);
+  });
+
+  it('returns null when there are no keys to account for', async () => {
+    writeLock(
+      root,
+      lockFileWith({ 'pkg/locales/en.json': { 'outer.one': ['de'] } })
+    );
+
+    await expect(find([])).resolves.toBeNull();
+  });
+});

From 35159035a797a6b851128dce68fdca29480ef39c Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 20:46:01 +0200
Subject: [PATCH 226/256] fix(cli): emit the JSON error envelope from every
 command with a JSON mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Only the sync subcommands emitted a machine-readable failure. Every other
command that accepts --format json routed failures through the global
handler, which printed prose on stderr and left stdout empty — measured
through the real CLI for translate, usage, languages, detect, glossary, tm,
write, correct, style-rules, admin and voice. A script that selected
--format json had nothing to parse in exactly the failure case and had to
carry a second strategy: scraping sentences off stderr.

handleError now consults the output format of the command commander is
about to run, captured in the preAction hook from the action command's own
options — so the envelope appears only where the flag exists and resolves
to json, and the format is read from commander rather than threaded through
every command's catch. The writer moves to src/cli/json-error-envelope.ts
and the sync surface re-exports it, keeping one emitter for both.

Unchanged: exit codes, text and table modes, commands with no --format
flag, and results that are not errors — write --check and correct --check
still exit 8 with no envelope. Commander's own parse errors still print on
stderr and exit 6; the envelope covers command failures, not parse
failures. One e2e assertion that read the reason off stderr for a
--format json translate is updated to the contract, as the sync suites were
when the envelope first moved to stdout.

Refs cli-53lo
---
 CHANGELOG.md                                  |   4 +
 docs/API.md                                   |  11 +-
 src/cli/commands/sync/sync-options.ts         |  60 +-----
 src/cli/index.ts                              |  25 ++-
 src/cli/json-error-envelope.ts                |  60 ++++++
 tests/e2e/cli-json-error-envelope.e2e.test.ts | 184 ++++++++++++++++++
 tests/e2e/cli-workflow.e2e.test.ts            |   5 +-
 7 files changed, 291 insertions(+), 58 deletions(-)
 create mode 100644 src/cli/json-error-envelope.ts
 create mode 100644 tests/e2e/cli-json-error-envelope.e2e.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 102cb189..c033cb98 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,6 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **cli**: **a failing command with `--format json` now writes its error to stdout instead of stderr, for every command that has a JSON mode.** A consumer that captured the reason with `2>err.txt` on `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` or `style-rules` stops finding it there; `> out.json` now captures both the success payload and the failure envelope, so one redirection handles both. Prose on stderr is replaced by the envelope's `message`/`suggestion` fields — a human reading `--format json` output sees JSON where they saw a sentence. Exit codes are the unchanged failure signal, and text/table modes are byte-identical. `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed. See Fixed.
+
 - **sync**: **`deepl sync pull --format json` can now carry a `shared_target` entry in `skipped`.** A consumer iterating `skipped` will meet a reason it has not seen before, for a target file another sync configuration's lockfile accounts for keys in; such a locale is not counted in `pulled` or `replaced` and no lockfile entry is recorded for it. Every other reason, count and field is unchanged. See Fixed.
 
 - **sync**: **the `--format json` error envelope moves from stderr to stdout, for every sync subcommand at once.** A consumer that read the failure reason off stderr stops finding it there: `deepl sync … --format json 2>err.json` now captures only human-facing warnings, and the envelope arrives where `> out.json` already captured the success payload, so one redirection handles both cases. Exit codes are unchanged and remain the failure signal. Anything branching on *the presence of* stderr output still works — warnings still go there — but anything *parsing* stderr must switch to stdout. See Fixed.
@@ -159,6 +161,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **cli**: every command with a JSON mode now emits the machine-readable error envelope, not only the `sync` subcommands. `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` and `style-rules` routed their failures through the global handler, which printed `Error:` (and `Suggestion:`) as prose on stderr and left stdout empty — measured through the real CLI for eleven of them, so a script that selected `--format json` had nothing to parse in exactly the failure case, and had to implement two error-handling strategies, the second of which was scraping prose off stderr. Failures now emit the same `{ ok: false, error: { code, message, suggestion? }, exitCode }` envelope on stdout that `deepl sync` has emitted since the envelope was recognised as the command's result in the failure case, from one shared writer. Exit codes are unchanged. Text and table modes are untouched, a command with no `--format` flag is untouched, and a result that is not an error keeps its own shape — `write --check` / `correct --check` still exit 8 with no envelope. A malformed invocation that commander rejects before the command runs still prints commander's message on stderr and exits 6: the envelope covers command failures, not parse failures.
+
 - **sync**: `deepl sync` and `deepl sync pull` no longer delete another sync configuration's translations from a target file both configurations write. A rewrite emits exactly the keys its own configuration defines, and the existing guard refuses that collision only *within* one bucket (two source files in one bucket resolving to one target); across two configurations nothing saw it, because each has its own project root, its own `.deepl-sync.lock` and — the process lock being keyed on the project root — its own pidfile. Measured through the CLI on nested roots (a repository-level config and a package-level one whose `target_path_pattern` resolved into the same directory): the file ended up holding whichever ran last, both runs reported success at exit 0, and each later run deleted the other's keys and re-billed its own — a flip-flop with no concurrency needed, which is why the lock's key was never the fix. A run that is about to delete keys from a target now looks for another configuration that accounts for them, using that configuration's lockfile as the evidence: a configuration writes only inside its own project root, so one that also writes this file is rooted at an ancestor directory of it, and a match requires that lockfile to record those exact keys for the same locale. When it does, the file is left exactly as it stands — `deepl sync` fails that locale (nothing written, nothing billed for it, keys recorded `failed` so the next run retries them, exit 12) and `deepl sync pull` skips it under a new `shared_target` reason. Both name the other lockfile, the shared keys and the remedy. Keys added to a locale file by hand are unaffected: no lockfile accounts for them, so they are still pruned with the usual warning.
 
 - **sync**: a pidfile naming a process this user cannot signal no longer refuses every later sync indefinitely. `kill(pid, 0)` answers EPERM for a PID that exists but belongs to another user — which is equally what a PID recycled by an unrelated process, or one from a container's PID namespace, looks like — and that was read as "alive" with no upper bound, while the `startedAt` the pidfile has always recorded was never consulted. Measured through the CLI: a pidfile naming PID 1 with a start time 30 days old refused `deepl sync` with exit 7 on every attempt. Such a holder is now trusted only while its recorded start time is within 24 hours and readable as a date (a time impossibly far in the future counts against it too), after which the lock is reclaimed with a warning naming the PID and the reason. A holder the probe reports as **genuinely running** is never aged out, however old the lock — taking the lock from a live sync is the concurrent-writer hazard the lock exists to prevent — so that case gets `--break-lock` instead (see Added). The refusal message now names the flag.
diff --git a/docs/API.md b/docs/API.md
index 017d5532..4f831271 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1341,7 +1341,7 @@ Show translation coverage for all target locales.
 
 **stdout/stderr split (stable contract):** The JSON payload — the success result, or the error envelope below when the command fails — is written to **stdout**, so `deepl sync status --format json > status.json` produces a parseable file in both cases. Diagnostic/progress logs and warnings stay on **stderr**, which means stdout parses even when the CLI or the Node runtime had something to say. The same stdout/stderr split applies to `deepl sync --format json`, `deepl sync validate --format json`, and `deepl sync audit --format json`.
 
-**Error envelope (shared across every `sync` subcommand):** On failure, `--format json` emits the following JSON envelope to **stdout** — the envelope is the command's result in the failure case; the non-zero exit code is the failure signal — and exits with the typed exit code:
+**Error envelope (shared across every command with a JSON mode):** On failure, `--format json` emits the following JSON envelope to **stdout** — the envelope is the command's result in the failure case; the non-zero exit code is the failure signal — and exits with the typed exit code:
 
 ```json
 {
@@ -1355,7 +1355,14 @@ Show translation coverage for all target locales.
 }
 ```
 
-The `error.code` field matches the error class name (`ConfigError`, `ValidationError`, `SyncConflict`, `AuthError`, etc.). `error.suggestion` is present when the underlying `DeepLCLIError` carries one. `exitCode` matches the process exit code, so a caller can branch on either field. The envelope shape is identical for `deepl sync`, `sync push`, `sync pull`, `sync resolve`, `sync export`, `sync validate`, `sync audit`, `sync init`, and `sync status`.
+The `error.code` field matches the error class name (`ConfigError`, `ValidationError`, `SyncConflict`, `AuthError`, etc.). `error.suggestion` is present when the underlying `DeepLCLIError` carries one. `exitCode` matches the process exit code, so a caller can branch on either field.
+
+**Which commands emit it:** every command whose effective `--format` is `json` — the nine `sync` subcommands plus `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, and those subcommands of `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` and `style-rules` that declare the flag. The shape and the stream are identical everywhere, so a script wrapping several `deepl` commands needs one failure path. Notes on the edges:
+
+- A command with no `--format` flag, and any run in `text` or `table` mode, is unchanged: `Error:` / `Suggestion:` prose on stderr.
+- `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed.
+- A result that is not an error keeps its own shape: `write --check` / `correct --check` exit `8` to report that text needs changes, and no envelope is emitted for it.
+- A malformed invocation commander rejects before the command runs (`unknown option`, a missing argument) still prints commander's own message on stderr and exits `6`. The envelope covers command failures, not parse failures.
 
 **`sync init --format json` success envelope:** For scripted project bootstrap, `deepl sync init --format json` emits a success envelope on **stdout** instead of the plain text confirmation:
 
diff --git a/src/cli/commands/sync/sync-options.ts b/src/cli/commands/sync/sync-options.ts
index ad19a62b..90c2d179 100644
--- a/src/cli/commands/sync/sync-options.ts
+++ b/src/cli/commands/sync/sync-options.ts
@@ -1,6 +1,5 @@
 import type { Command } from 'commander';
-import { DeepLCLIError } from '../../../utils/errors.js';
-import { ExitCode, exitCodeForError } from '../../../utils/exit-codes.js';
+import { ExitCode } from '../../../utils/exit-codes.js';
 
 /**
  * Commander routes an invocation-line --format to the nearest command that
@@ -76,21 +75,13 @@ export function parseLocaleFilter(
 }
 
 /**
- * JSON error envelope shape emitted on stderr when --format json is set and
- * a command fails. Shared across every `deepl sync` subcommand so script
+ * JSON error envelope shape emitted on stdout when --format json is set and a
+ * command fails. Shared across every command that has a JSON mode so script
  * consumers can parse failures with one schema.
  *
  * @see tests/helpers/assert-error-envelope.ts for the canonical validator.
  */
-export interface SyncJsonErrorEnvelope {
-  ok: false;
-  error: {
-    code: string;
-    message: string;
-    suggestion?: string;
-  };
-  exitCode: number;
-}
+export type { JsonErrorEnvelope as SyncJsonErrorEnvelope } from '../../json-error-envelope.js';
 
 /**
  * Canonical success envelope for `sync init --format json`. Other subcommands
@@ -107,48 +98,11 @@ export interface SyncInitJsonSuccessEnvelope {
   };
 }
 
-// eslint-disable-next-line no-control-regex -- intentional: strip control chars from error messages before emitting envelope
-const CONTROL_CHAR_RE = /[\u0000-\u001F\u007F-\u009F\u200B-\u200D\uFEFF]/g;
-
-function sanitizeMessage(message: string): string {
-  return message.replace(CONTROL_CHAR_RE, '');
-}
-
 /**
- * Serialize an error to the canonical envelope on stdout and exit with the
- * error's typed exit code. Shared by every subcommand that honors
- * --format json for machine-readable failures.
- *
- * stdout, not stderr: the envelope is the command's result in the failure
- * case, and stderr is where every warning — the CLI's own and the Node
- * runtime's — already goes, so an envelope there parses only when nothing
- * else happened to be said. The non-zero exit code remains the failure
- * signal; a consumer reads the reason off the same stream as the success
- * payload.
+ * The sync surface's name for the shared envelope emitter, kept so every sync
+ * subcommand imports its machine-readable failure path from one place.
  */
-export function emitJsonErrorAndExit(
-  error: unknown,
-  overrideExitCode?: number
-): never {
-  const err = error instanceof Error ? error : new Error(String(error));
-  const code = err instanceof DeepLCLIError ? err.name : 'UnknownError';
-  const exitCode =
-    overrideExitCode ??
-    (err instanceof DeepLCLIError ? err.exitCode : exitCodeForError(err));
-  const envelope: SyncJsonErrorEnvelope = {
-    ok: false,
-    error: {
-      code,
-      message: sanitizeMessage(err.message),
-      ...(err instanceof DeepLCLIError && err.suggestion
-        ? { suggestion: sanitizeMessage(err.suggestion) }
-        : {}),
-    },
-    exitCode,
-  };
-  process.stdout.write(JSON.stringify(envelope) + '\n');
-  process.exit(exitCode);
-}
+export { emitJsonErrorAndExit } from '../../json-error-envelope.js';
 
 /**
  * Serialize the canonical success envelope for `sync init --format json` to
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 9974fd47..519343e5 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -22,6 +22,7 @@ import { AuthError, DeepLCLIError } from '../utils/errors.js';
 import { ExitCode, exitCodeForError } from '../utils/exit-codes.js';
 import { isSymlink } from '../utils/safe-read-file.js';
 import { setNoInput } from '../utils/confirm.js';
+import { emitJsonErrorAndExit } from './json-error-envelope.js';
 import { registerAuth } from './commands/register-auth.js';
 import { registerUsage } from './commands/register-usage.js';
 import { registerLanguages } from './commands/register-languages.js';
@@ -79,9 +80,25 @@ const getCacheService = createCacheServiceGetter(() =>
 );
 
 /**
- * Handle error and exit with appropriate exit code
+ * Output format of the command commander is about to run, captured by the
+ * preAction hook. Read only by `handleError`, so a failure is reported in the
+ * shape the invocation asked for.
+ */
+let activeOutputFormat: string | undefined;
+
+/**
+ * Handle error and exit with appropriate exit code.
+ *
+ * With `--format json` in effect the failure is the command's result, so it
+ * goes to stdout as the same typed envelope every `deepl sync` subcommand
+ * emits, and the prose is inside it rather than on stderr. Commands with no
+ * JSON mode, and every text-mode run, are unchanged.
  */
 function handleError(error: unknown): never {
+  if (activeOutputFormat === 'json') {
+    emitJsonErrorAndExit(error);
+  }
+
   const errorMessage = error instanceof Error ? error.message : 'Unknown error';
   const exitCode = exitCodeForError(error);
 
@@ -201,9 +218,13 @@ program
     '--max-retries <n>',
     'Maximum automatic retries for retryable requests (default: 3)'
   )
-  .hook('preAction', (thisCommand) => {
+  .hook('preAction', (thisCommand, actionCommand) => {
     const options = thisCommand.opts();
 
+    // The format lives on the command being run, not on the program, and only
+    // the commands that declare --format have one at all.
+    activeOutputFormat = actionCommand.opts()['format'] as string | undefined;
+
     // Handle --config flag - reinitialize config service with custom path
     // SECURITY: Validate path to prevent traversal attacks
     if (options['config']) {
diff --git a/src/cli/json-error-envelope.ts b/src/cli/json-error-envelope.ts
new file mode 100644
index 00000000..d9768acd
--- /dev/null
+++ b/src/cli/json-error-envelope.ts
@@ -0,0 +1,60 @@
+import { DeepLCLIError } from '../utils/errors.js';
+import { exitCodeForError } from '../utils/exit-codes.js';
+
+/**
+ * JSON error envelope emitted on stdout when a command fails with
+ * `--format json` in effect. Shared by every command that has a JSON mode so
+ * script consumers can parse failures with one schema.
+ *
+ * @see tests/helpers/assert-error-envelope.ts for the canonical validator.
+ */
+export interface JsonErrorEnvelope {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+    suggestion?: string;
+  };
+  exitCode: number;
+}
+
+// eslint-disable-next-line no-control-regex -- intentional: strip control chars from error messages before emitting envelope
+const CONTROL_CHAR_RE = /[\u0000-\u001F\u007F-\u009F\u200B-\u200D\uFEFF]/g;
+
+function sanitizeMessage(message: string): string {
+  return message.replace(CONTROL_CHAR_RE, '');
+}
+
+/**
+ * Serialize an error to the canonical envelope on stdout and exit with the
+ * error's typed exit code.
+ *
+ * stdout, not stderr: the envelope is the command's result in the failure
+ * case, and stderr is where every warning — the CLI's own and the Node
+ * runtime's — already goes, so an envelope there parses only when nothing else
+ * happened to be said. The non-zero exit code remains the failure signal; a
+ * consumer reads the reason off the same stream as the success payload.
+ */
+export function emitJsonErrorAndExit(
+  error: unknown,
+  overrideExitCode?: number
+): never {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const code = err instanceof DeepLCLIError ? err.name : 'UnknownError';
+  const exitCode =
+    overrideExitCode ??
+    (err instanceof DeepLCLIError ? err.exitCode : exitCodeForError(err));
+  const envelope: JsonErrorEnvelope = {
+    ok: false,
+    error: {
+      code,
+      message: sanitizeMessage(err.message),
+      ...(err instanceof DeepLCLIError && err.suggestion
+        ? { suggestion: sanitizeMessage(err.suggestion) }
+        : {}),
+    },
+    exitCode,
+  };
+  process.stdout.write(JSON.stringify(envelope) + '\n');
+  process.exit(exitCode);
+}
diff --git a/tests/e2e/cli-json-error-envelope.e2e.test.ts b/tests/e2e/cli-json-error-envelope.e2e.test.ts
new file mode 100644
index 00000000..a9c87c9c
--- /dev/null
+++ b/tests/e2e/cli-json-error-envelope.e2e.test.ts
@@ -0,0 +1,184 @@
+/**
+ * E2E tests for the `--format json` error envelope on the non-sync commands.
+ *
+ * The sync subcommands have emitted a typed envelope on stdout since the
+ * envelope was recognised as the command's result in the failure case. Every
+ * other command that accepts `--format json` routed its failures through the
+ * global handler instead, which printed prose on stderr and left stdout empty —
+ * so a script that chose `--format json` had nothing to parse in exactly the
+ * case it needed to. These tests hold the two surfaces to one contract.
+ */
+
+import { spawnSync, SpawnSyncReturns } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+import { assertErrorEnvelope } from '../helpers/assert-error-envelope';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+
+/** A port nothing listens on, so every API call fails as a NetworkError. */
+const DEAD_ENDPOINT = 'http://127.0.0.1:1';
+
+interface RunResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+describe('--format json error envelope (non-sync commands)', () => {
+  let configDir: string;
+
+  beforeEach(() => {
+    configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-json-err-'));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'test-key:fx' },
+        api: { baseUrl: DEAD_ENDPOINT, usePro: false },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+      }),
+      { mode: 0o600 }
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(configDir, { recursive: true, force: true });
+  });
+
+  function run(args: string[]): RunResult {
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: configDir,
+          DEEPL_API_KEY: 'test-key:fx',
+          NO_COLOR: '1',
+        },
+        timeout: 20000,
+      }
+    );
+    return {
+      status: result.status ?? 1,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  describe('an unreachable API', () => {
+    // The whole point is that one contract covers every command with the flag,
+    // so the cases are a table rather than a hand-written test each.
+    const NETWORK_CASES: Array<[label: string, args: string[]]> = [
+      ['translate', ['translate', 'Hello', '--to', 'de']],
+      ['usage', ['usage']],
+      ['languages', ['languages']],
+      ['detect', ['detect', 'Bonjour tout le monde']],
+      ['glossary list', ['glossary', 'list']],
+      ['tm list', ['tm', 'list']],
+      ['write', ['write', 'Hello there']],
+      ['correct', ['correct', 'Helo there']],
+    ];
+
+    it.each(NETWORK_CASES)(
+      '%s emits the envelope on stdout with the network exit code',
+      (_label, args) => {
+        const result = run([...args, '--format', 'json']);
+
+        expect(result.status).toBe(5);
+        const envelope = assertErrorEnvelope(result.stdout, 'NetworkError', 5);
+        expect(envelope.error.message).toMatch(/ECONNREFUSED|Network error/);
+      }
+    );
+
+    it.each(NETWORK_CASES)(
+      '%s leaves text mode reporting on stderr, with stdout empty',
+      (_label, args) => {
+        const result = run(args);
+
+        expect(result.status).toBe(5);
+        expect(result.stdout).toBe('');
+        expect(result.stderr).toContain('Error:');
+      }
+    );
+
+    it('parses as one JSON document even when the CLI warns on stderr', () => {
+      // The endpoint is not a DeepL one, so the key-destination warning fires on
+      // stderr in the same run. That is what put the envelope on stdout in the
+      // first place, and it must not reach the machine-readable stream.
+      const result = run(['usage', '--format', 'json']);
+
+      expect(result.stderr).toContain('not a DeepL API endpoint');
+      expect(() => JSON.parse(result.stdout)).not.toThrow();
+    });
+  });
+
+  describe('a local validation failure', () => {
+    it('carries the typed code and the suggestion', () => {
+      const result = run(['translate', 'Hello', '--format', 'json']);
+
+      expect(result.status).toBe(6);
+      const envelope = assertErrorEnvelope(result.stdout, 'ValidationError', 6);
+      expect(envelope.error.suggestion).toMatch(/--to/);
+    });
+
+    it('reports a missing API key as an auth failure', () => {
+      const result = spawnSync(
+        'node',
+        [CLI_PATH, 'usage', '--format', 'json'],
+        {
+          encoding: 'utf-8',
+          env: (() => {
+            const { DEEPL_API_KEY: _drop, ...rest } = process.env;
+            return {
+              ...rest,
+              DEEPL_CONFIG_DIR: fs.mkdtempSync(
+                path.join(os.tmpdir(), 'deepl-json-noauth-')
+              ),
+              NO_COLOR: '1',
+            };
+          })(),
+          timeout: 20000,
+        }
+      );
+
+      expect(result.status).toBe(2);
+      assertErrorEnvelope(result.stdout ?? '', 'AuthError', 2);
+    });
+  });
+
+  describe('healthy paths the envelope must not disturb', () => {
+    it('leaves a successful text-mode command alone', () => {
+      const result = run(['config', 'list', '--format', 'text']);
+
+      expect(result.status).toBe(0);
+      expect(() => JSON.parse(result.stdout)).toThrow();
+      expect(result.stdout).toContain('api.baseUrl');
+    });
+
+    it('leaves a successful --format json payload alone', () => {
+      const result = run(['config', 'list', '--format', 'json']);
+
+      expect(result.status).toBe(0);
+      const parsed = JSON.parse(result.stdout) as { api?: unknown };
+      expect(parsed.api).toBeDefined();
+    });
+
+    it('does not emit an envelope for --format table', () => {
+      const result = run(['usage', '--format', 'table']);
+
+      expect(result.status).toBe(5);
+      expect(result.stdout).toBe('');
+      expect(result.stderr).toContain('Error:');
+    });
+  });
+});
diff --git a/tests/e2e/cli-workflow.e2e.test.ts b/tests/e2e/cli-workflow.e2e.test.ts
index cc83a7d9..9a724c8a 100644
--- a/tests/e2e/cli-workflow.e2e.test.ts
+++ b/tests/e2e/cli-workflow.e2e.test.ts
@@ -659,7 +659,10 @@ describe('CLI Workflow E2E', () => {
           { excludeApiKey: true }
         );
       } catch (error: any) {
-        const output = error.stderr ?? error.stdout ?? error.message;
+        // Under --format json the failure is the command's result and lands on
+        // stdout as the typed envelope, so both streams are searched: what this
+        // test is about is that the flag combination parsed at all.
+        const output = `${error.stdout ?? ''}\n${error.stderr ?? ''}`;
         // Should fail on auth, not on flag parsing
         expect(output).toMatch(/API key|auth/i);
         expect(output).not.toMatch(/unknown.*option/i);

From a44781333e09914810bfeaf01fd69f62905bd964 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 21:10:26 +0200
Subject: [PATCH 227/256] fix(write): give --check a JSON result shape and stop
 --format json corrupting it

`write --check` / `correct --check` declared --format json and ignored it: the
check reported only through the human logger, so a run exited 8 with stdout
empty and one sentence on stderr. The exit code told a CI job that text needed
changes; nothing machine-readable said how many, in which file, or which command
had run. Exit 8 is a RESULT, not an error, so the error envelope deliberately
does not cover this path -- it needed a success shape, which is now
{ ok: true, mode, needsChanges, changes, file? } on stdout, with the exit code
unchanged at 0 or 8.

Measuring the path first turned up two defects the finding did not name, both
from one root cause: checkText obtained the improved text by calling improve(),
which renders a JSON document when the caller asked for one, so the word-level
diff compared the original text against that document.

  * The verdict was inverted. Against an endpoint echoing its input unchanged,
    `write --check` exited 0 and said "Text looks good" while
    `write --check --format json` exited 8 claiming 2 potential changes, for any
    input, because the JSON scaffolding was itself the diff.
  * --fix, which writes what the check computed, overwrote the file with the
    JSON document -- measured on a file needing no change at all, reported as
    "File improved / Changes: 2". --backup preserved the original; without it
    the content was lost.

WriteCommand.improvedText() now returns the unrendered text and improve()
renders on top of it, so the verdict, the count and the bytes written to disk no
longer depend on the format the report was asked for. improveWithDiff() and
improveFile() still call improve(), leaving --alternatives, --diff, --output and
--in-place byte-identical under both formats; those paths have their own missing
JSON shapes, filed as cli-ds1v because --diff needs a design decision rather
than a fix.

Refs cli-mpxl
---
 CHANGELOG.md                               |   6 +
 README.md                                  |   4 +
 docs/API.md                                |  41 ++-
 examples/13-write.sh                       |   4 +
 examples/15-correct.sh                     |   4 +
 src/cli/commands/register-write.ts         |  42 ++-
 src/cli/commands/write.ts                  |  31 +-
 tests/e2e/cli-write-check-json.e2e.test.ts | 358 +++++++++++++++++++++
 tests/e2e/write-check-server.cjs           |  53 +++
 tests/unit/register-correct.test.ts        |  33 ++
 tests/unit/register-write.test.ts          | 106 ++++++
 tests/unit/write-command.test.ts           |  85 +++++
 12 files changed, 750 insertions(+), 17 deletions(-)
 create mode 100644 tests/e2e/cli-write-check-json.e2e.test.ts
 create mode 100644 tests/e2e/write-check-server.cjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c033cb98..4a6e6133 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **write/correct**: `--check` honours `--format json`, emitting a result payload on stdout: `{ ok: true, mode: 'write'|'correct', needsChanges, changes, file? }`. The flag was declared on both commands and accepted on this path, but the check branch reported only through the human logger, so a run measured with a mock Write endpoint exited 8 with **stdout empty** and a single sentence on stderr — the exit code told a CI job *that* text needed changes and nothing machine-readable said how many, in which file, or which of the two commands had run. `ok` is `true` whichever way the check comes out, because the check ran: the verdict is `needsChanges`, which the exit code repeats as 0 or 8. That makes `ok` the discriminator against the error envelope added for genuine failures — `false` is a failure, `true` is a verdict. `file` is the absolute path and is present only for file input. The payload replaces the human report rather than joining it, so the `File: …` line and the `⚠ Text needs improvement` / `✓ Text looks good` verdict remain text-mode only; the exit code is unchanged in both modes. `original` and `improved` are deliberately omitted: `--check` answers a yes/no question and the non-check invocation is what returns the content, and fields can be added later compatibly where removing them could not.
+
 - **sync**: `deepl sync pull --dry-run` previews a pull without writing anything — no target file, no `.deepl-sync.lock`. It reports how many translations would be pulled and how many existing local translations would be replaced, and `--verbose` names each key and file whose TMS value differs from the local one. `--format json` carries `replaced` and `dryRun` alongside `pulled`. Pull is the one sync command that replaces hand edits with content the CLI has no way to date, and it was the only writing sync command with no preview mode; `sync` itself and `sync resolve` both have one. The flag is also accepted on the parent (`deepl sync --dry-run pull`), matching how `sync resolve` reads it.
 
 - **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API). It was previously accepted and then silently discarded with a "document mode does not support --glossary" warning, even though `POST /v2/document` supports glossaries. Repeating the flag works here too, with the same merge behaviour and the same API-decided conflict resolution. `--from` is required, because the API rejects a document glossary without a source language; `--translation-memory` remains unsupported for documents. Note that glossary matching is context-dependent for documents exactly as it is for text — a term applied in one sentence may be left alone in another.
@@ -39,6 +41,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **write/correct**: **`--check --format json` can now exit 0 where it always exited 8, and writes a payload to stdout.** A CI gate built on `deepl write --check --format json` was failing unconditionally — the verdict was computed against a rendered JSON document, so no input could pass it — and will start passing for text that is actually clean. A pipeline whose step was green only because a later step ignored the code, or that was quietly always red, sees its result change to the truthful one. Anything reading stdout on this path now finds a JSON object where it found nothing; text mode is byte-identical. See Fixed.
+
 - **cli**: **a failing command with `--format json` now writes its error to stdout instead of stderr, for every command that has a JSON mode.** A consumer that captured the reason with `2>err.txt` on `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` or `style-rules` stops finding it there; `> out.json` now captures both the success payload and the failure envelope, so one redirection handles both. Prose on stderr is replaced by the envelope's `message`/`suggestion` fields — a human reading `--format json` output sees JSON where they saw a sentence. Exit codes are the unchanged failure signal, and text/table modes are byte-identical. `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed. See Fixed.
 
 - **sync**: **`deepl sync pull --format json` can now carry a `shared_target` entry in `skipped`.** A consumer iterating `skipped` will meet a reason it has not seen before, for a target file another sync configuration's lockfile accounts for keys in; such a locale is not counted in `pulled` or `replaced` and no lockfile entry is recorded for it. Every other reason, count and field is unchanged. See Fixed.
@@ -161,6 +165,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **write/correct**: `--format json` no longer inverts the `--check` verdict or corrupts the file `--fix` writes. `checkText` obtained the improved text by calling `improve()`, which renders a JSON document when the caller asked for one, so the word-level diff behind the check compared the original text against that document rather than against the improvement. Measured against a mock Write endpoint that echoed its input unchanged — a genuinely clean check: `write --check 'text'` exited 0 and said `✓ Text looks good`, while `write --check 'text' --format json` exited **8** and claimed `2 potential changes`, for any input, because the JSON scaffolding was itself the diff. The same call served `--fix`, which writes what the check computed, so `write file.txt --fix --format json` **overwrote the file with the JSON document** — measured on a file needing no change at all, which was reported as `✓ File improved / Changes: 2` and left holding `{"original":…,"improved":…}`; `--backup` preserved the original, without it the content was lost. And the change count disagreed with itself across formats for the same input (2 vs the truthful 1). The improved text is now produced without the presentation formatting, which `improve()` still applies for its own output, so the verdict, the count and the bytes written to disk no longer depend on the format the report was asked for. `--alternatives`, `--diff`, `--output` and `--in-place` are byte-identical under both formats, verified by diffing a full before/after run of all four.
+
 - **cli**: every command with a JSON mode now emits the machine-readable error envelope, not only the `sync` subcommands. `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` and `style-rules` routed their failures through the global handler, which printed `Error:` (and `Suggestion:`) as prose on stderr and left stdout empty — measured through the real CLI for eleven of them, so a script that selected `--format json` had nothing to parse in exactly the failure case, and had to implement two error-handling strategies, the second of which was scraping prose off stderr. Failures now emit the same `{ ok: false, error: { code, message, suggestion? }, exitCode }` envelope on stdout that `deepl sync` has emitted since the envelope was recognised as the command's result in the failure case, from one shared writer. Exit codes are unchanged. Text and table modes are untouched, a command with no `--format` flag is untouched, and a result that is not an error keeps its own shape — `write --check` / `correct --check` still exit 8 with no envelope. A malformed invocation that commander rejects before the command runs still prints commander's message on stderr and exits 6: the envelope covers command failures, not parse failures.
 
 - **sync**: `deepl sync` and `deepl sync pull` no longer delete another sync configuration's translations from a target file both configurations write. A rewrite emits exactly the keys its own configuration defines, and the existing guard refuses that collision only *within* one bucket (two source files in one bucket resolving to one target); across two configurations nothing saw it, because each has its own project root, its own `.deepl-sync.lock` and — the process lock being keyed on the project root — its own pidfile. Measured through the CLI on nested roots (a repository-level config and a package-level one whose `target_path_pattern` resolved into the same directory): the file ended up holding whichever ran last, both runs reported success at exit 0, and each later run deleted the other's keys and re-billed its own — a flip-flop with no concurrency needed, which is why the lock's key was never the fix. A run that is about to delete keys from a target now looks for another configuration that accounts for them, using that configuration's lockfile as the evidence: a configuration writes only inside its own project root, so one that also writes this file is rooted at an ancestor directory of it, and a match requires that lockfile to record those exact keys for the same locale. When it does, the file is left exactly as it stands — `deepl sync` fails that locale (nothing written, nothing billed for it, keys recorded `failed` so the next run retries them, exit 12) and `deepl sync pull` skips it under a new `shared_target` reason. Both name the other lockfile, the shared keys and the remedy. Keys added to a locale file by hand are unaffected: no lockfile accounts for them, so they are still pruned with the usual warning.
diff --git a/README.md b/README.md
index f0088ad2..b3a39f6e 100644
--- a/README.md
+++ b/README.md
@@ -644,6 +644,10 @@ deepl write "Text to improve." --lang en-us --style business --interactive
 # Check if text needs improvement (exit code 0 if no changes needed)
 deepl write document.md --lang en-us --check
 
+# Machine-readable check result for CI (exit code unchanged)
+deepl write document.md --check --format json
+# {"ok":true,"mode":"write","needsChanges":true,"changes":3,"file":"/abs/path/document.md"}
+
 # Auto-fix files in place
 deepl write document.md --lang en-us --fix
 
diff --git a/docs/API.md b/docs/API.md
index 4f831271..8da69c1e 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -775,7 +775,7 @@ The 14 languages are generated from `GET /v3/languages?resource=write` into `src
 - `--alternatives, -a` - Show all improvement alternatives
 - `--interactive, -i` - Interactive mode: choose from multiple alternatives
 - `--diff, -d` - Show diff between original and improved text
-- `--check` - Check if text needs improvement without modifying (exits with 0 if no changes, 8 if improvements suggested)
+- `--check` - Check if text needs improvement without modifying (exits with 0 if no changes, 8 if improvements suggested). With `--format json`, emits the check result payload on stdout
 - `--fix` - Auto-fix files in place
 - `--output, -o FILE` - Write output to file
 - `--in-place` - Edit file in place
@@ -876,6 +876,30 @@ deepl write "Text to improve." --lang en-us --interactive
 deepl write document.md --lang en-us --check
 ```
 
+`--check` reports a result rather than an error, so `--format json` gives it a
+success shape rather than the error envelope:
+
+```bash
+deepl write document.md --check --format json
+# {"ok":true,"mode":"write","needsChanges":true,"changes":3,"file":"/abs/path/document.md"}
+
+deepl write "This is fine." --check --format json
+# {"ok":true,"mode":"write","needsChanges":false,"changes":0}
+```
+
+| Field         | Meaning                                                              |
+| ------------- | -------------------------------------------------------------------- |
+| `ok`          | Always `true` — the check ran. A failure emits the error envelope.    |
+| `mode`        | `write` or `correct`, so one parser serves both commands.             |
+| `needsChanges`| The verdict, repeated by the exit code (`0` clean, `8` needs changes).|
+| `changes`     | Number of word-level changes the API would make.                     |
+| `file`        | Absolute path of the checked file; absent when the input was text.    |
+
+The payload goes to **stdout** and replaces the human report — the `File: …` line
+and the `⚠ Text needs improvement` / `✓ Text looks good` verdict stay on stderr in
+text mode only. The exit code is unchanged either way, so a CI job may branch on
+the code, the payload, or both.
+
 **Diff view:**
 
 ```bash
@@ -936,7 +960,7 @@ Fixes spelling and grammar only, avoiding the broader rewording that `deepl writ
 
 **Fix Operations:**
 
-- `--check` - Check if text needs correction (exit 0 if clean, exit 8 if corrections needed)
+- `--check` - Check if text needs correction (exit 0 if clean, exit 8 if corrections needed). With `--format json`, emits the check result payload on stdout
 - `--fix` - Automatically fix file in place
 - `--backup, -b` - Create backup file before fixing (use with `--fix`)
 
@@ -963,6 +987,15 @@ deepl c "Their going too the store."
 deepl correct README.md --check
 ```
 
+With `--format json` the check emits the same result payload `write --check`
+does, with `mode` set to `correct` (the field table is under `write`'s **Check
+mode** above):
+
+```bash
+deepl correct README.md --check --format json
+# {"ok":true,"mode":"correct","needsChanges":true,"changes":2,"file":"/abs/path/README.md"}
+```
+
 **Fix a file in place with a backup:**
 
 ```bash
@@ -1361,7 +1394,7 @@ The `error.code` field matches the error class name (`ConfigError`, `ValidationE
 
 - A command with no `--format` flag, and any run in `text` or `table` mode, is unchanged: `Error:` / `Suggestion:` prose on stderr.
 - `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed.
-- A result that is not an error keeps its own shape: `write --check` / `correct --check` exit `8` to report that text needs changes, and no envelope is emitted for it.
+- A result that is not an error keeps its own shape: `write --check` / `correct --check` exit `8` to report that text needs changes, and emit their own `ok: true` result payload rather than an envelope. Discriminate on `ok`: `false` is a failure, `true` is a verdict whose detail is in the payload.
 - A malformed invocation commander rejects before the command runs (`unknown option`, a missing argument) still prints commander's own message on stderr and exits `6`. The envelope covers command failures, not parse failures.
 
 **`sync init --format json` success envelope:** For scripted project bootstrap, `deepl sync init --format json` emits a success envelope on **stdout** instead of the plain text confirmation:
@@ -3433,7 +3466,7 @@ Remediation: run `deepl config get` to inspect the current config, or edit the f
 
 A check-style command ran successfully but found actionable issues. Exit is *soft* — `process.exitCode` is set so cleanup still runs. Emitted by:
 
-- `deepl write --check <text|file>` when the Write API would suggest changes (`needsImprovement === true`)
+- `deepl write --check <text|file>` and `deepl correct --check <text|file>` when the Write API would suggest changes (`needsImprovement === true`). Under `--format json` the same run also emits the `ok: true` check result payload on stdout, so the count and the file are readable without parsing prose
 - `deepl sync validate` when validation surfaces one or more `error`-severity issues (missing placeholders, format-string mismatches, unbalanced HTML tags, or a target file on disk that could not be read — reported under an `unusable_target` check while every other locale is still validated)
 
 This code is specifically designed for CI use: a `check` step can block a merge without requiring try/catch wrappers in the calling script. It does **not** indicate a CLI failure.
diff --git a/examples/13-write.sh b/examples/13-write.sh
index ca873cad..7edb56ec 100755
--- a/examples/13-write.sh
+++ b/examples/13-write.sh
@@ -118,6 +118,10 @@ echo "19. Check a file for improvements:"
 deepl write "$DEMO_FILE" --check --lang en-us || true
 echo
 
+echo "19b. Machine-readable check result for a CI gate:"
+deepl write "$DEMO_FILE" --check --lang en-us --format json || true
+echo
+
 echo "20. Auto-fix a file in place:"
 echo "Their going to the store tommorow." > "$DEMO_FILE"
 deepl write "$DEMO_FILE" --fix
diff --git a/examples/15-correct.sh b/examples/15-correct.sh
index 048ffa38..12236711 100755
--- a/examples/15-correct.sh
+++ b/examples/15-correct.sh
@@ -51,6 +51,10 @@ else
 fi
 echo
 
+echo "5b. Check mode as a machine-readable result (ok stays true; the verdict is needsChanges)"
+deepl correct "$TEST_DIR/draft.txt" --check --format json || true
+echo
+
 echo "6. Fix a file in place with a backup"
 deepl correct "$TEST_DIR/draft.txt" --fix --backup
 echo "Fixed content:"
diff --git a/src/cli/commands/register-write.ts b/src/cli/commands/register-write.ts
index 9dfaad04..d897090d 100644
--- a/src/cli/commands/register-write.ts
+++ b/src/cli/commands/register-write.ts
@@ -60,6 +60,23 @@ export type WriteDeps = Pick<
   'createDeepLClient' | 'getConfigService' | 'getCacheService' | 'handleError'
 >;
 
+/**
+ * Result payload for `write --check` / `correct --check` under `--format json`.
+ *
+ * `ok` is true whichever way the check comes out: the command did its job, and
+ * the verdict is `needsChanges` — which the exit code repeats as 0 or 8. A
+ * failure on this path emits the error envelope instead, so a consumer
+ * discriminates the two on `ok`.
+ */
+export interface WriteCheckJsonResult {
+  ok: true;
+  mode: 'write' | 'correct';
+  needsChanges: boolean;
+  changes: number;
+  /** Absolute path, present only when the input was a file. */
+  file?: string;
+}
+
 interface WriteActionOptions {
   lang?: string;
   to?: string;
@@ -188,30 +205,49 @@ export function createWriteAction(
       };
 
       if (options.check) {
+        const asJson = options.format === 'json';
         let needsImprovement: boolean;
         let changes = 0;
+        let checkedFile: string | undefined;
 
         if (existsSync(text)) {
           const result = await writeCommand.checkFile(text, writeOptions);
           needsImprovement = result.needsImprovement;
           changes = result.changes;
-          Logger.info(chalk.gray(`File: ${text}`));
+          checkedFile = result.filePath;
+          if (!asJson) {
+            Logger.info(chalk.gray(`File: ${text}`));
+          }
         } else {
           const result = await writeCommand.checkText(text, writeOptions);
           needsImprovement = result.needsImprovement;
           changes = result.changes;
         }
 
-        if (needsImprovement) {
+        // The payload replaces the human report rather than joining it: it
+        // carries the file path and the count the prose would have said.
+        if (asJson) {
+          const payload: WriteCheckJsonResult = {
+            ok: true,
+            mode,
+            needsChanges: needsImprovement,
+            changes,
+            ...(checkedFile ? { file: checkedFile } : {}),
+          };
+          process.stdout.write(JSON.stringify(payload) + '\n');
+        } else if (needsImprovement) {
           Logger.warn(
             chalk.yellow(
               `⚠ Text ${needsChangesLabel} (${changes} potential changes)`
             )
           );
-          process.exitCode = ExitCode.CheckFailed;
         } else {
           Logger.success(chalk.green('✓ Text looks good'));
         }
+
+        if (needsImprovement) {
+          process.exitCode = ExitCode.CheckFailed;
+        }
         return;
       }
 
diff --git a/src/cli/commands/write.ts b/src/cli/commands/write.ts
index 64507d5b..b7af91a2 100644
--- a/src/cli/commands/write.ts
+++ b/src/cli/commands/write.ts
@@ -43,6 +43,26 @@ export class WriteCommand {
    * (rephrase by default; spelling/grammar correction when options.correct is set)
    */
   async improve(text: string, options: WriteOptions): Promise<string> {
+    const improved = await this.improvedText(text, options);
+
+    // Format output based on format option. The alternatives listing is its own
+    // presentation and has no JSON form, so it is returned as produced.
+    if (options.showAlternatives || options.format !== 'json') {
+      return improved;
+    }
+
+    return formatWriteJson(text, improved, options.lang ?? 'auto-detected');
+  }
+
+  /**
+   * The improvement as plain text, without the presentation formatting
+   * `improve()` applies. The check and fix workflows diff this text and write it
+   * to disk, so they need the text itself rather than a rendered document.
+   */
+  private async improvedText(
+    text: string,
+    options: WriteOptions
+  ): Promise<string> {
     const serviceOptions = { skipCache: options.noCache };
 
     if (options.showAlternatives) {
@@ -60,15 +80,6 @@ export class WriteCommand {
       serviceOptions
     );
 
-    // Format output based on format option
-    if (options.format === 'json') {
-      return formatWriteJson(
-        text,
-        improvement.text,
-        options.lang ?? 'auto-detected'
-      );
-    }
-
     return improvement.text;
   }
 
@@ -231,7 +242,7 @@ export class WriteCommand {
     improved: string;
     changes: number;
   }> {
-    const improvedText = await this.improve(text, options);
+    const improvedText = await this.improvedText(text, options);
 
     // Count the number of changes using diff
     const patches = Diff.diffWords(text, improvedText);
diff --git a/tests/e2e/cli-write-check-json.e2e.test.ts b/tests/e2e/cli-write-check-json.e2e.test.ts
new file mode 100644
index 00000000..3bcf509e
--- /dev/null
+++ b/tests/e2e/cli-write-check-json.e2e.test.ts
@@ -0,0 +1,358 @@
+/**
+ * E2E tests for `write --check` / `correct --check` under `--format json`.
+ *
+ * `--check` reports a RESULT, not an error: exit 0 when the text is clean and
+ * exit 8 when it needs changes. The exit code is the primary signal and the
+ * JSON payload carries the detail behind it — how many changes, which file, and
+ * which of the two commands ran — so a CI job can act on the verdict without
+ * scraping prose off stderr. The error envelope covers the failure case only,
+ * which is why this path needs a success shape of its own.
+ */
+
+import {
+  spawn,
+  spawnSync,
+  ChildProcess,
+  SpawnSyncReturns,
+} from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+
+/** Comes back from the mock unchanged, so the check is clean. */
+const CLEAN_TEXT = 'This sentence is already polished';
+/** Comes back with one word appended, so the check reports one change. */
+const DIRTY_TEXT = 'Their going to the store';
+
+interface RunResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+interface CheckPayload {
+  ok: true;
+  mode: 'write' | 'correct';
+  needsChanges: boolean;
+  changes: number;
+  file?: string;
+}
+
+describe('write/correct --check under --format json', () => {
+  let mockServer: ChildProcess;
+  let baseUrl: string;
+  let configDir: string;
+  let workDir: string;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const script = path.join(__dirname, 'write-check-server.cjs');
+      const child = spawn('node', [script], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      mockServer = child;
+
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = output.match(/PORT=(\d+)/);
+        if (match) {
+          resolve(parseInt(match[1]!, 10));
+        }
+      });
+      child.stderr.on('data', (data: Buffer) => {
+        process.stderr.write(`[write-check-server] ${data.toString()}`);
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  beforeAll(async () => {
+    const port = await startMockServer();
+    baseUrl = `http://127.0.0.1:${port}`;
+
+    configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-check-json-cfg-'));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl, usePro: false },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+      }),
+      { mode: 0o600 }
+    );
+  }, 30000);
+
+  beforeEach(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-check-json-work-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  afterAll(() => {
+    if (mockServer) {
+      mockServer.kill('SIGTERM');
+    }
+    fs.rmSync(configDir, { recursive: true, force: true });
+  });
+
+  function run(args: string[]): RunResult {
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        cwd: workDir,
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: configDir,
+          DEEPL_API_KEY: 'mock-api-key-for-testing:fx',
+          NO_COLOR: '1',
+        },
+        timeout: 20000,
+      }
+    );
+    return {
+      status: result.status ?? 1,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  /**
+   * Parses the payload off stdout alone. The CLI warns on stderr in the same run
+   * (the mock is not a DeepL endpoint), so a merged stream would not parse.
+   */
+  function parsePayload(stdout: string): CheckPayload {
+    const payload = JSON.parse(stdout) as CheckPayload;
+    expect(payload.ok).toBe(true);
+    return payload;
+  }
+
+  const COMMANDS: Array<{
+    label: string;
+    command: string;
+    mode: 'write' | 'correct';
+    needsLabel: string;
+  }> = [
+    {
+      label: 'write',
+      command: 'write',
+      mode: 'write',
+      needsLabel: 'needs improvement',
+    },
+    {
+      label: 'correct',
+      command: 'correct',
+      mode: 'correct',
+      needsLabel: 'needs correction',
+    },
+  ];
+
+  describe.each(COMMANDS)('$label --check --format json', (subject) => {
+    it('emits the result payload on stdout and exits 8 when changes are needed', () => {
+      const result = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--check',
+        '--format',
+        'json',
+      ]);
+
+      expect(result.status).toBe(8);
+      const payload = parsePayload(result.stdout);
+      expect(payload).toEqual({
+        ok: true,
+        mode: subject.mode,
+        needsChanges: true,
+        changes: 1,
+      });
+    });
+
+    it('emits the result payload on stdout and exits 0 when the text is clean', () => {
+      const result = run([
+        subject.command,
+        CLEAN_TEXT,
+        '--check',
+        '--format',
+        'json',
+      ]);
+
+      expect(result.status).toBe(0);
+      const payload = parsePayload(result.stdout);
+      expect(payload).toEqual({
+        ok: true,
+        mode: subject.mode,
+        needsChanges: false,
+        changes: 0,
+      });
+    });
+
+    it('names the checked file when the input is a path', () => {
+      const filePath = path.join(workDir, 'draft.txt');
+      fs.writeFileSync(filePath, DIRTY_TEXT, 'utf-8');
+
+      const result = run([
+        subject.command,
+        'draft.txt',
+        '--check',
+        '--format',
+        'json',
+      ]);
+
+      expect(result.status).toBe(8);
+      const payload = parsePayload(result.stdout);
+      expect(payload.needsChanges).toBe(true);
+      expect(payload.file).toBe(fs.realpathSync(filePath));
+    });
+
+    it('omits the file key when the input is text', () => {
+      const result = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--check',
+        '--format',
+        'json',
+      ]);
+
+      expect(Object.keys(parsePayload(result.stdout))).not.toContain('file');
+    });
+
+    it('counts the same changes the text-mode report counts', () => {
+      const jsonResult = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--check',
+        '--format',
+        'json',
+      ]);
+      const textResult = run([subject.command, DIRTY_TEXT, '--check']);
+
+      expect(jsonResult.status).toBe(textResult.status);
+      expect(parsePayload(jsonResult.stdout).changes).toBe(1);
+      expect(textResult.stderr).toContain('(1 potential changes)');
+    });
+  });
+
+  // Over-rejection guards: the paths that already worked must not move.
+  describe.each(COMMANDS)(
+    '$label --check text mode is unchanged',
+    (subject) => {
+      it('reports the verdict on stderr with stdout empty when changes are needed', () => {
+        const result = run([subject.command, DIRTY_TEXT, '--check']);
+
+        expect(result.status).toBe(8);
+        expect(result.stdout).toBe('');
+        expect(result.stderr).toContain(
+          `⚠ Text ${subject.needsLabel} (1 potential changes)`
+        );
+      });
+
+      it('reports a clean verdict on stderr with stdout empty', () => {
+        const result = run([subject.command, CLEAN_TEXT, '--check']);
+
+        expect(result.status).toBe(0);
+        expect(result.stdout).toBe('');
+        expect(result.stderr).toContain('✓ Text looks good');
+      });
+
+      it('still names the file on stderr for file input', () => {
+        fs.writeFileSync(path.join(workDir, 'draft.txt'), DIRTY_TEXT, 'utf-8');
+
+        const result = run([subject.command, 'draft.txt', '--check']);
+
+        expect(result.status).toBe(8);
+        expect(result.stdout).toBe('');
+        expect(result.stderr).toContain('File: draft.txt');
+      });
+    }
+  );
+
+  describe.each(COMMANDS)('$label without --check is unchanged', (subject) => {
+    it('keeps the non-check JSON payload shape', () => {
+      const result = run([subject.command, DIRTY_TEXT, '--format', 'json']);
+
+      expect(result.status).toBe(0);
+      expect(JSON.parse(result.stdout)).toEqual({
+        original: DIRTY_TEXT,
+        improved: `${DIRTY_TEXT} (improved)`,
+        changes: 1,
+        language: 'auto-detected',
+      });
+    });
+
+    it('keeps the plain-text output', () => {
+      const result = run([subject.command, DIRTY_TEXT]);
+
+      expect(result.status).toBe(0);
+      expect(result.stdout.trim()).toBe(`${DIRTY_TEXT} (improved)`);
+    });
+  });
+
+  // --fix shares the check computation, so it shares the defect: the text it
+  // writes to the file must be the improved text under either format.
+  describe.each(COMMANDS)(
+    '$label --fix writes text, not a payload',
+    (subject) => {
+      it('writes the improved text with --format json', () => {
+        const filePath = path.join(workDir, 'fixme.txt');
+        fs.writeFileSync(filePath, DIRTY_TEXT, 'utf-8');
+
+        const result = run([
+          subject.command,
+          'fixme.txt',
+          '--fix',
+          '--format',
+          'json',
+        ]);
+
+        expect(result.status).toBe(0);
+        expect(fs.readFileSync(filePath, 'utf-8')).toBe(
+          `${DIRTY_TEXT} (improved)`
+        );
+      });
+
+      it('writes the improved text in text mode', () => {
+        const filePath = path.join(workDir, 'fixme.txt');
+        fs.writeFileSync(filePath, DIRTY_TEXT, 'utf-8');
+
+        const result = run([subject.command, 'fixme.txt', '--fix']);
+
+        expect(result.status).toBe(0);
+        expect(fs.readFileSync(filePath, 'utf-8')).toBe(
+          `${DIRTY_TEXT} (improved)`
+        );
+      });
+
+      it('leaves a clean file untouched with --format json', () => {
+        const filePath = path.join(workDir, 'clean.txt');
+        fs.writeFileSync(filePath, CLEAN_TEXT, 'utf-8');
+
+        const result = run([
+          subject.command,
+          'clean.txt',
+          '--fix',
+          '--format',
+          'json',
+        ]);
+
+        expect(result.status).toBe(0);
+        expect(fs.readFileSync(filePath, 'utf-8')).toBe(CLEAN_TEXT);
+      });
+    }
+  );
+});
diff --git a/tests/e2e/write-check-server.cjs b/tests/e2e/write-check-server.cjs
new file mode 100644
index 00000000..75116606
--- /dev/null
+++ b/tests/e2e/write-check-server.cjs
@@ -0,0 +1,53 @@
+/**
+ * A Write API mock that can answer either outcome the `--check` workflow has to
+ * distinguish, keyed on the TEXT rather than on the request index so a test does
+ * not depend on how many calls preceded it.
+ *
+ * Text containing the word `polished` comes back unchanged, which is what a
+ * clean check looks like; anything else comes back with ` (improved)` appended,
+ * which is a one-word change. Both `/v2/write/rephrase` and `/v2/write/correct`
+ * answer, so `write` and `correct` share the server.
+ *
+ * Prints `PORT=<port>` on stdout once listening. Runs in its own process because
+ * the test driver blocks its own event loop on spawnSync and would otherwise
+ * never accept the connection.
+ *
+ * Usage: node tests/e2e/write-check-server.cjs
+ */
+
+const http = require('http');
+
+const server = http.createServer((req, res) => {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk;
+  });
+  req.on('end', () => {
+    res.setHeader('Content-Type', 'application/json');
+
+    if (
+      req.method === 'POST' &&
+      (req.url === '/v2/write/rephrase' || req.url === '/v2/write/correct')
+    ) {
+      const params = new URLSearchParams(body);
+      const improvements = params.getAll('text').map((text) => ({
+        text: text.includes('polished') ? text : text + ' (improved)',
+        target_language: params.get('target_lang') || 'en-US',
+        detected_source_language: 'EN',
+      }));
+
+      res.writeHead(200);
+      res.end(JSON.stringify({ improvements }));
+      return;
+    }
+
+    res.writeHead(404);
+    res.end(
+      JSON.stringify({ message: 'no route: ' + req.method + ' ' + req.url })
+    );
+  });
+});
+
+server.listen(0, '127.0.0.1', () => {
+  process.stdout.write('PORT=' + server.address().port + '\n');
+});
diff --git a/tests/unit/register-correct.test.ts b/tests/unit/register-correct.test.ts
index b9157fb8..3fde2f8f 100644
--- a/tests/unit/register-correct.test.ts
+++ b/tests/unit/register-correct.test.ts
@@ -255,6 +255,39 @@ describe('registerCorrect', () => {
       );
       expect(process.exitCode).toBeUndefined();
     });
+
+    it('emits the result payload under --format json with mode correct', async () => {
+      const stdout: string[] = [];
+      const stdoutSpy = jest
+        .spyOn(process.stdout, 'write')
+        .mockImplementation((chunk: unknown) => {
+          stdout.push(String(chunk));
+          return true;
+        });
+      mockWriteCommand.checkText.mockResolvedValue({
+        needsImprovement: true,
+        changes: 2,
+      });
+
+      await program.parseAsync([
+        'node',
+        'test',
+        'correct',
+        'This is an test.',
+        '--check',
+        '--format',
+        'json',
+      ]);
+
+      expect(JSON.parse(stdout.join(''))).toEqual({
+        ok: true,
+        mode: 'correct',
+        needsChanges: true,
+        changes: 2,
+      });
+      expect(process.exitCode).toBe(8);
+      stdoutSpy.mockRestore();
+    });
   });
 
   describe('--fix', () => {
diff --git a/tests/unit/register-write.test.ts b/tests/unit/register-write.test.ts
index 58e419cf..45928227 100644
--- a/tests/unit/register-write.test.ts
+++ b/tests/unit/register-write.test.ts
@@ -647,6 +647,112 @@ describe('registerWrite', () => {
       expect(exitSpy).not.toHaveBeenCalled();
       exitSpy.mockRestore();
     });
+
+    describe('--format json', () => {
+      let stdout: string[];
+      let stdoutSpy: jest.SpyInstance;
+
+      beforeEach(() => {
+        stdout = [];
+        stdoutSpy = jest
+          .spyOn(process.stdout, 'write')
+          .mockImplementation((chunk: unknown) => {
+            stdout.push(String(chunk));
+            return true;
+          });
+      });
+
+      afterEach(() => {
+        stdoutSpy.mockRestore();
+      });
+
+      it('should emit the result payload and keep exitCode 8', async () => {
+        mockWriteCommand.checkText.mockResolvedValue({
+          needsImprovement: true,
+          changes: 3,
+        });
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'bad text',
+          '--check',
+          '--format',
+          'json',
+        ]);
+
+        expect(JSON.parse(stdout.join(''))).toEqual({
+          ok: true,
+          mode: 'write',
+          needsChanges: true,
+          changes: 3,
+        });
+        expect(process.exitCode).toBe(8);
+      });
+
+      it('should emit the result payload and leave exitCode unset when clean', async () => {
+        mockWriteCommand.checkText.mockResolvedValue({
+          needsImprovement: false,
+          changes: 0,
+        });
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'good text',
+          '--check',
+          '--format',
+          'json',
+        ]);
+
+        expect(JSON.parse(stdout.join(''))).toEqual({
+          ok: true,
+          mode: 'write',
+          needsChanges: false,
+          changes: 0,
+        });
+        expect(process.exitCode).toBeUndefined();
+      });
+
+      it('should name the checked file and replace the human report', async () => {
+        mockExistsSync.mockReturnValue(true);
+        mockWriteCommand.checkFile.mockResolvedValue({
+          needsImprovement: true,
+          changes: 2,
+          filePath: '/abs/file.txt',
+        });
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'file.txt',
+          '--check',
+          '--format',
+          'json',
+        ]);
+
+        expect(JSON.parse(stdout.join(''))).toEqual({
+          ok: true,
+          mode: 'write',
+          needsChanges: true,
+          changes: 2,
+          file: '/abs/file.txt',
+        });
+        expect(Logger.info).not.toHaveBeenCalled();
+        expect(Logger.warn).not.toHaveBeenCalled();
+      });
+
+      it('should not emit a payload in text mode', async () => {
+        mockWriteCommand.checkText.mockResolvedValue({
+          needsImprovement: true,
+          changes: 1,
+        });
+        await program.parseAsync(['node', 'test', 'write', 'text', '--check']);
+
+        expect(stdout.join('')).toBe('');
+        expect(Logger.warn).toHaveBeenCalled();
+      });
+    });
   });
 
   describe('--fix mode', () => {
diff --git a/tests/unit/write-command.test.ts b/tests/unit/write-command.test.ts
index 8d496cce..6c0e0f3b 100644
--- a/tests/unit/write-command.test.ts
+++ b/tests/unit/write-command.test.ts
@@ -694,6 +694,47 @@ describe('WriteCommand', () => {
       expect(result.needsImprovement).toBe(true);
       expect(result.changes).toBeGreaterThan(0);
     });
+
+    // `improve()` renders a JSON document when the caller asked for one, but the
+    // check compares and counts text, so the presentation format must not reach
+    // the comparison.
+    describe('with format json', () => {
+      it('should compare against the improved text, not a rendered document', async () => {
+        mockWriteService.getBestImprovement.mockResolvedValue({
+          text: 'Improved text.',
+          targetLanguage: 'en-US',
+        });
+
+        const withJson = await writeCommand.checkText('Original text.', {
+          lang: 'en-us',
+          format: 'json',
+        });
+        const withText = await writeCommand.checkText('Original text.', {
+          lang: 'en-us',
+          format: 'text',
+        });
+
+        expect(withJson.improved).toBe('Improved text.');
+        expect(withJson.changes).toBe(withText.changes);
+      });
+
+      it('should report clean text as clean', async () => {
+        const text = 'Perfect text.';
+        mockWriteService.getBestImprovement.mockResolvedValue({
+          text,
+          targetLanguage: 'en-US',
+        });
+
+        const result = await writeCommand.checkText(text, {
+          lang: 'en-us',
+          format: 'json',
+        });
+
+        expect(result.needsImprovement).toBe(false);
+        expect(result.changes).toBe(0);
+        expect(result.improved).toBe(text);
+      });
+    });
   });
 
   describe('checkFile()', () => {
@@ -829,6 +870,50 @@ describe('WriteCommand', () => {
         })
       ).rejects.toThrow('File not found');
     });
+
+    // --fix writes the improved text to the user's file, so what it writes must
+    // not depend on the output format the report was asked for.
+    describe('with format json', () => {
+      it('should write the improved text to the file', async () => {
+        await fs.mkdir(testDir, { recursive: true });
+        const testFile = join(testDir, 'test.txt');
+        await fs.writeFile(testFile, 'Original content', 'utf-8');
+
+        mockWriteService.getBestImprovement.mockResolvedValue({
+          text: 'Improved content.',
+          targetLanguage: 'en-US',
+        });
+
+        const result = await writeCommand.autoFixFile(testFile, {
+          lang: 'en-us',
+          format: 'json',
+        });
+
+        expect(result.fixed).toBe(true);
+        expect(await fs.readFile(testFile, 'utf-8')).toBe('Improved content.');
+      });
+
+      it('should leave a file needing no changes untouched', async () => {
+        await fs.mkdir(testDir, { recursive: true });
+        const testFile = join(testDir, 'perfect.txt');
+        const content = 'Perfect content.';
+        await fs.writeFile(testFile, content, 'utf-8');
+
+        mockWriteService.getBestImprovement.mockResolvedValue({
+          text: content,
+          targetLanguage: 'en-US',
+        });
+
+        const result = await writeCommand.autoFixFile(testFile, {
+          lang: 'en-us',
+          format: 'json',
+        });
+
+        expect(result.fixed).toBe(false);
+        expect(result.changes).toBe(0);
+        expect(await fs.readFile(testFile, 'utf-8')).toBe(content);
+      });
+    });
   });
 
   describe('improveInteractive()', () => {

From ce346387c27685097c6f9be8ec30df42ddf62c5f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 21:31:51 +0200
Subject: [PATCH 228/256] feat(write): give --diff and --alternatives JSON
 payloads under --format json

Both flags were declared alongside --format json on `write` and `correct` and
neither consulted it. Measured against a mock Write endpoint:

  * --alternatives --format json returned the numbered TEXT list
    ("1. Hello there (improved)"), leaving a consumer to parse prose by line
    number. It now emits { ok: true, original, alternatives: [...] }.
  * --diff --format json printed the human three-block report in which the block
    headed "Improved:" held a rendered JSON document, so the unified diff below
    described JSON scaffolding rather than wording -- it read
    `+  "original": "Hello there",` where the changed sentence belonged. It now
    emits { ok: true, original, improved, diff }.

improveWithDiff takes its improved text from improvedText() rather than
improve(), the same seam that fixed --check and --fix, so the "Improved:" text is
the improvement in both modes. The payload's diff comes from a new
generatePatch(), the uncoloured patch generateDiff() already built on, because a
colour escape is meaningless in a machine-readable field -- asserted under
FORCE_COLOR=3, where the payload stays escape-free.

Both payloads carry ok: true so a consumer discriminates a result from the
ok: false error envelope, matching the --check payload. The plain improvement
payload keeps its { original, improved, changes, language } shape and its absent
ok, since it predates the envelope; that inconsistency is documented rather than
fixed, as changing it would break existing consumers.

--output/--in-place still receive whatever the improvement renders to, which
under --format json is the payload. That was already true of the plain payload
and is now also true of --alternatives, where the file previously got the
numbered list; recorded as a Changed entry. --in-place writing JSON at all is
left as it stands, deliberately.

Refs cli-ds1v
---
 CHANGELOG.md                                  |   6 +
 README.md                                     |   8 +
 docs/API.md                                   |  40 +-
 examples/13-write.sh                          |   8 +
 examples/15-correct.sh                        |   4 +
 src/cli/commands/register-write.ts            |  25 ++
 src/cli/commands/write.ts                     |  66 ++--
 src/utils/formatters.ts                       |  29 ++
 .../cli-write-output-modes-json.e2e.test.ts   | 366 ++++++++++++++++++
 tests/e2e/write-check-server.cjs              |  27 +-
 tests/unit/register-write.test.ts             |  72 ++++
 tests/unit/write-command.test.ts              |  62 +++
 12 files changed, 676 insertions(+), 37 deletions(-)
 create mode 100644 tests/e2e/cli-write-output-modes-json.e2e.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a6e6133..ac71ba5e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **write/correct**: `--diff` and `--alternatives` honour `--format json`, each with a payload of its own. `--diff` emits `{ ok: true, original, improved, diff }`, where `diff` is the unified patch with **no colour escapes** whatever the terminal reports -- the text report colours the same patch for a human and that colouring never reaches the payload. `--alternatives` emits `{ ok: true, original, alternatives: [...] }`, an array rather than the numbered list a consumer would otherwise have had to parse by line number. Both flags were declared alongside `--format json` and neither consulted it: `--alternatives` returned the numbered text list whatever the format, and `--diff` printed the human three-block report. Each carries `ok: true` so a consumer discriminates a result from the `ok: false` error envelope, matching `--check`; the plain improvement payload keeps its existing `{ original, improved, changes, language }` shape and its absent `ok`, since it predates the envelope. One API call per invocation either way, unchanged.
+
 - **write/correct**: `--check` honours `--format json`, emitting a result payload on stdout: `{ ok: true, mode: 'write'|'correct', needsChanges, changes, file? }`. The flag was declared on both commands and accepted on this path, but the check branch reported only through the human logger, so a run measured with a mock Write endpoint exited 8 with **stdout empty** and a single sentence on stderr — the exit code told a CI job *that* text needed changes and nothing machine-readable said how many, in which file, or which of the two commands had run. `ok` is `true` whichever way the check comes out, because the check ran: the verdict is `needsChanges`, which the exit code repeats as 0 or 8. That makes `ok` the discriminator against the error envelope added for genuine failures — `false` is a failure, `true` is a verdict. `file` is the absolute path and is present only for file input. The payload replaces the human report rather than joining it, so the `File: …` line and the `⚠ Text needs improvement` / `✓ Text looks good` verdict remain text-mode only; the exit code is unchanged in both modes. `original` and `improved` are deliberately omitted: `--check` answers a yes/no question and the non-check invocation is what returns the content, and fields can be added later compatibly where removing them could not.
 
 - **sync**: `deepl sync pull --dry-run` previews a pull without writing anything — no target file, no `.deepl-sync.lock`. It reports how many translations would be pulled and how many existing local translations would be replaced, and `--verbose` names each key and file whose TMS value differs from the local one. `--format json` carries `replaced` and `dryRun` alongside `pulled`. Pull is the one sync command that replaces hand edits with content the CLI has no way to date, and it was the only writing sync command with no preview mode; `sync` itself and `sync resolve` both have one. The flag is also accepted on the parent (`deepl sync --dry-run pull`), matching how `sync resolve` reads it.
@@ -41,6 +43,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **write/correct**: **`--alternatives --format json --output <file>` writes a JSON payload where it wrote the numbered text list.** `--output` and `--in-place` receive whatever the improvement renders to, which under `--format json` is now the alternatives payload rather than `1. ...\n\n2. ...` prose -- the plain improvement payload has behaved that way all along, and `--alternatives` was the odd one out. Anything consuming such a file as prose has to parse it as JSON or drop `--format json`; to put improved text in a file, leave `--format` at its default. Text mode is unchanged. See Added.
+
 - **write/correct**: **`--check --format json` can now exit 0 where it always exited 8, and writes a payload to stdout.** A CI gate built on `deepl write --check --format json` was failing unconditionally — the verdict was computed against a rendered JSON document, so no input could pass it — and will start passing for text that is actually clean. A pipeline whose step was green only because a later step ignored the code, or that was quietly always red, sees its result change to the truthful one. Anything reading stdout on this path now finds a JSON object where it found nothing; text mode is byte-identical. See Fixed.
 
 - **cli**: **a failing command with `--format json` now writes its error to stdout instead of stderr, for every command that has a JSON mode.** A consumer that captured the reason with `2>err.txt` on `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` or `style-rules` stops finding it there; `> out.json` now captures both the success payload and the failure envelope, so one redirection handles both. Prose on stderr is replaced by the envelope's `message`/`suggestion` fields — a human reading `--format json` output sees JSON where they saw a sentence. Exit codes are the unchanged failure signal, and text/table modes are byte-identical. `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed. See Fixed.
@@ -165,6 +169,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **write/correct**: `write --diff --format json` no longer labels a rendered JSON document as the improved text. `improveWithDiff` took its improved text from `improve()`, which renders a JSON document when the caller asked for one, so the block headed `Improved:` held that document and the unified diff below it described JSON scaffolding rather than wording -- measured against a mock Write endpoint, the diff read `+  "original": "Hello there",` where it should have read the changed sentence. It now takes the unrendered text, the same seam that fixed `--check` and `--fix`. Text mode is byte-identical.
+
 - **write/correct**: `--format json` no longer inverts the `--check` verdict or corrupts the file `--fix` writes. `checkText` obtained the improved text by calling `improve()`, which renders a JSON document when the caller asked for one, so the word-level diff behind the check compared the original text against that document rather than against the improvement. Measured against a mock Write endpoint that echoed its input unchanged — a genuinely clean check: `write --check 'text'` exited 0 and said `✓ Text looks good`, while `write --check 'text' --format json` exited **8** and claimed `2 potential changes`, for any input, because the JSON scaffolding was itself the diff. The same call served `--fix`, which writes what the check computed, so `write file.txt --fix --format json` **overwrote the file with the JSON document** — measured on a file needing no change at all, which was reported as `✓ File improved / Changes: 2` and left holding `{"original":…,"improved":…}`; `--backup` preserved the original, without it the content was lost. And the change count disagreed with itself across formats for the same input (2 vs the truthful 1). The improved text is now produced without the presentation formatting, which `improve()` still applies for its own output, so the verdict, the count and the bytes written to disk no longer depend on the format the report was asked for. `--alternatives`, `--diff`, `--output` and `--in-place` are byte-identical under both formats, verified by diffing a full before/after run of all four.
 
 - **cli**: every command with a JSON mode now emits the machine-readable error envelope, not only the `sync` subcommands. `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` and `style-rules` routed their failures through the global handler, which printed `Error:` (and `Suggestion:`) as prose on stderr and left stdout empty — measured through the real CLI for eleven of them, so a script that selected `--format json` had nothing to parse in exactly the failure case, and had to implement two error-handling strategies, the second of which was scraping prose off stderr. Failures now emit the same `{ ok: false, error: { code, message, suggestion? }, exitCode }` envelope on stdout that `deepl sync` has emitted since the envelope was recognised as the command's result in the failure case, from one shared writer. Exit codes are unchanged. Text and table modes are untouched, a command with no `--format` flag is untouched, and a result that is not an error keeps its own shape — `write --check` / `correct --check` still exit 8 with no envelope. A malformed invocation that commander rejects before the command runs still prints commander's message on stderr and exits 6: the envelope covers command failures, not parse failures.
diff --git a/README.md b/README.md
index b3a39f6e..354d06a0 100644
--- a/README.md
+++ b/README.md
@@ -660,6 +660,14 @@ deepl write file.txt --lang en-us --diff
 # Show diff for plain text
 deepl write "This text could be better." --lang en-us --diff
 
+# Machine-readable diff (uncoloured patch)
+deepl write file.txt --diff --format json
+# {"ok":true,"original":"...","improved":"...","diff":"Index: text\n===...\n"}
+
+# Every alternative the API offered, as an array
+deepl write "This is good." --alternatives --format json
+# {"ok":true,"original":"This is good.","alternatives":["This is fine.","This works."]}
+
 # Bypass cache for this request
 deepl write "Fresh improvement please." --lang en-us --no-cache
 ```
diff --git a/docs/API.md b/docs/API.md
index 8da69c1e..a9749949 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -772,9 +772,9 @@ The 14 languages are generated from `GET /v3/languages?resource=write` into `src
 
 **Output Options:**
 
-- `--alternatives, -a` - Show all improvement alternatives
+- `--alternatives, -a` - Show all improvement alternatives. With `--format json`, emits them as an array
 - `--interactive, -i` - Interactive mode: choose from multiple alternatives
-- `--diff, -d` - Show diff between original and improved text
+- `--diff, -d` - Show diff between original and improved text. With `--format json`, emits the diff payload with an uncoloured patch
 - `--check` - Check if text needs improvement without modifying (exits with 0 if no changes, 8 if improvements suggested). With `--format json`, emits the check result payload on stdout
 - `--fix` - Auto-fix files in place
 - `--output, -o FILE` - Write output to file
@@ -915,6 +915,32 @@ deepl write "This are good." --lang en-us --format json
 # {"original":"This are good.","improved":"This is good.","changes":1,"language":"en-us"}
 ```
 
+Each output mode has its own JSON shape, because each answers a different
+question. `--check` and the two below carry `ok: true`, marking them as results
+rather than the `ok: false` error envelope; the plain improvement payload above
+predates the envelope and keeps its shape, so it has no `ok` field.
+
+```bash
+# --diff: the same three things the text report shows, with an uncoloured patch
+deepl write "This are good." --diff --format json
+# {"ok":true,"original":"This are good.","improved":"This is good.",
+#  "diff":"Index: text\n===...\n-This are good.\n+This is good.\n"}
+
+# --alternatives: every improvement the API offered, as an array
+deepl write "This are good." --alternatives --format json
+# {"ok":true,"original":"This are good.","alternatives":["This is good.","These are good."]}
+```
+
+`--diff`'s `diff` field is the unified patch with no colour escapes, whatever the
+terminal — the text report colours the same patch for a human, and that colouring
+never reaches the payload. `--diff` ignores `--output`/`--in-place`, so its payload
+only ever goes to stdout.
+
+`--output <file>` and `--in-place` receive whatever the improvement renders to, so
+under `--format json` they write the payload rather than the improved text — that
+is true of the plain payload and of `--alternatives` alike. To put improved *text*
+in a file, leave `--format` at its default.
+
 **Bypass cache:**
 
 ```bash
@@ -952,11 +978,11 @@ Fixes spelling and grammar only, avoiding the broader rewording that `deepl writ
 
 **Output Modes:**
 
-- `--alternatives, -a` - Show all alternative corrections
+- `--alternatives, -a` - Show all alternative corrections. With `--format json`, emits them as an array
 - `--output, -o FILE` - Write corrected text to file
 - `--in-place` - Edit file in place (use with file input)
 - `--interactive, -i` - Review the correction before accepting
-- `--diff, -d` - Show diff between original and corrected text
+- `--diff, -d` - Show diff between original and corrected text. With `--format json`, emits the diff payload with an uncoloured patch
 
 **Fix Operations:**
 
@@ -1021,6 +1047,10 @@ deepl correct "Their going too the store." --format json
 # {"original":"Their going too the store.","improved":"They're going to the store.","changes":1,"language":"auto-detected"}
 ```
 
+`--check`, `--diff` and `--alternatives` each carry their own payload, identical to
+`write`'s (see **JSON output** under `write` above); only `--check`'s differs, in
+that its `mode` reads `correct`.
+
 ---
 
 ### voice
@@ -1394,7 +1424,7 @@ The `error.code` field matches the error class name (`ConfigError`, `ValidationE
 
 - A command with no `--format` flag, and any run in `text` or `table` mode, is unchanged: `Error:` / `Suggestion:` prose on stderr.
 - `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed.
-- A result that is not an error keeps its own shape: `write --check` / `correct --check` exit `8` to report that text needs changes, and emit their own `ok: true` result payload rather than an envelope. Discriminate on `ok`: `false` is a failure, `true` is a verdict whose detail is in the payload.
+- A result that is not an error keeps its own shape: `write --check` / `correct --check` exit `8` to report that text needs changes, and emit their own `ok: true` result payload rather than an envelope; `--diff` and `--alternatives` carry `ok: true` payloads of their own too. Discriminate on `ok`: `false` is a failure, `true` is a result whose detail is in the payload. The one exception is `write`/`correct`'s plain improvement payload (`{original, improved, changes, language}`), which predates the envelope and carries no `ok` field.
 - A malformed invocation commander rejects before the command runs (`unknown option`, a missing argument) still prints commander's own message on stderr and exits `6`. The envelope covers command failures, not parse failures.
 
 **`sync init --format json` success envelope:** For scripted project bootstrap, `deepl sync init --format json` emits a success envelope on **stdout** instead of the plain text confirmation:
diff --git a/examples/13-write.sh b/examples/13-write.sh
index 7edb56ec..a1f64434 100755
--- a/examples/13-write.sh
+++ b/examples/13-write.sh
@@ -143,6 +143,14 @@ echo "22. Show diff between original and improved text:"
 deepl write "Their going to the store tommorow." --diff --lang en-us
 echo
 
+echo "22b. Machine-readable diff (uncoloured patch in the payload):"
+deepl write "Their going to the store tommorow." --diff --lang en-us --format json
+echo
+
+echo "22c. Every alternative as a JSON array:"
+deepl write "This is a test." --lang en-us --alternatives --format json
+echo
+
 echo "23. Edit file in place:"
 echo "This text could be more better." > "$DEMO_FILE"
 deepl write "$DEMO_FILE" --in-place --lang en-us
diff --git a/examples/15-correct.sh b/examples/15-correct.sh
index 12236711..739c2ca2 100755
--- a/examples/15-correct.sh
+++ b/examples/15-correct.sh
@@ -37,6 +37,10 @@ echo "4. Diff view"
 deepl correct "This are a example sentence." --lang en-us --diff
 echo
 
+echo "4b. Diff view as a machine-readable payload"
+deepl correct "This are a example sentence." --lang en-us --diff --format json
+echo
+
 echo "5. Check mode (exit 8 would mean corrections needed)"
 echo "A sentence with an mistake." > "$TEST_DIR/draft.txt"
 if deepl correct "$TEST_DIR/draft.txt" --check; then
diff --git a/src/cli/commands/register-write.ts b/src/cli/commands/register-write.ts
index d897090d..eaaa51bc 100644
--- a/src/cli/commands/register-write.ts
+++ b/src/cli/commands/register-write.ts
@@ -77,6 +77,20 @@ export interface WriteCheckJsonResult {
   file?: string;
 }
 
+/**
+ * Result payload for `write --diff` / `correct --diff` under `--format json`.
+ *
+ * `diff` is the uncoloured unified patch between `original` and `improved`, so a
+ * consumer gets the same three things the text report shows, without the colour
+ * escapes that report writes for a terminal.
+ */
+export interface WriteDiffJsonResult {
+  ok: true;
+  original: string;
+  improved: string;
+  diff: string;
+}
+
 interface WriteActionOptions {
   lang?: string;
   to?: string;
@@ -285,6 +299,17 @@ export function createWriteAction(
           result = await writeCommand.improveWithDiff(text, writeOptions);
         }
 
+        if (options.format === 'json') {
+          const payload: WriteDiffJsonResult = {
+            ok: true,
+            original: result.original,
+            improved: result.improved,
+            diff: writeCommand.generatePatch(result.original, result.improved),
+          };
+          process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+          return;
+        }
+
         Logger.output(chalk.bold('Original:'));
         Logger.output(result.original);
         Logger.output();
diff --git a/src/cli/commands/write.ts b/src/cli/commands/write.ts
index b7af91a2..a0ffaa14 100644
--- a/src/cli/commands/write.ts
+++ b/src/cli/commands/write.ts
@@ -11,7 +11,10 @@ import { resolve, dirname } from 'path';
 import * as Diff from 'diff';
 import chalk from 'chalk';
 
-import { formatWriteJson } from '../../utils/formatters.js';
+import {
+  formatWriteAlternativesJson,
+  formatWriteJson,
+} from '../../utils/formatters.js';
 import { safeReadFile } from '../../utils/safe-read-file.js';
 import { Logger } from '../../utils/logger.js';
 import { sanitizeForTerminal } from '../../utils/control-chars.js';
@@ -43,11 +46,18 @@ export class WriteCommand {
    * (rephrase by default; spelling/grammar correction when options.correct is set)
    */
   async improve(text: string, options: WriteOptions): Promise<string> {
+    // Format output based on format option. The alternatives listing is a set of
+    // results rather than one, so it has a payload of its own.
+    if (options.showAlternatives) {
+      const alternatives = await this.alternativeTexts(text, options);
+      return options.format === 'json'
+        ? formatWriteAlternativesJson(text, alternatives)
+        : this.formatAlternatives(alternatives);
+    }
+
     const improved = await this.improvedText(text, options);
 
-    // Format output based on format option. The alternatives listing is its own
-    // presentation and has no JSON form, so it is returned as produced.
-    if (options.showAlternatives || options.format !== 'json') {
+    if (options.format !== 'json') {
       return improved;
     }
 
@@ -63,26 +73,32 @@ export class WriteCommand {
     text: string,
     options: WriteOptions
   ): Promise<string> {
-    const serviceOptions = { skipCache: options.noCache };
-
     if (options.showAlternatives) {
-      const improvements = await this.fetchImprovements(
-        text,
-        options,
-        serviceOptions
+      return this.formatAlternatives(
+        await this.alternativeTexts(text, options)
       );
-      return this.formatAlternatives(improvements.map((i) => i.text));
     }
 
-    const improvement = await this.fetchBestImprovement(
-      text,
-      options,
-      serviceOptions
-    );
+    const improvement = await this.fetchBestImprovement(text, options, {
+      skipCache: options.noCache,
+    });
 
     return improvement.text;
   }
 
+  /**
+   * Every improvement the API offered, in the order it offered them.
+   */
+  private async alternativeTexts(
+    text: string,
+    options: WriteOptions
+  ): Promise<string[]> {
+    const improvements = await this.fetchImprovements(text, options, {
+      skipCache: options.noCache,
+    });
+    return improvements.map((i) => i.text);
+  }
+
   /**
    * Dispatch to the rephrase or correct endpoint based on options.correct
    */
@@ -169,17 +185,19 @@ export class WriteCommand {
     return improvedText;
   }
 
+  /**
+   * The unified patch between original and improved text, uncoloured — what a
+   * machine-readable diff carries, since a colour escape is meaningless there.
+   */
+  generatePatch(original: string, improved: string): string {
+    return Diff.createPatch('text', original, improved, 'original', 'improved');
+  }
+
   /**
    * Generate a unified diff between original and improved text
    */
   generateDiff(original: string, improved: string): string {
-    const patch = Diff.createPatch(
-      'text',
-      original,
-      improved,
-      'original',
-      'improved'
-    );
+    const patch = this.generatePatch(original, improved);
 
     // Color the diff output
     const lines = patch.split('\n');
@@ -204,7 +222,7 @@ export class WriteCommand {
     text: string,
     options: WriteOptions
   ): Promise<{ original: string; improved: string; diff: string }> {
-    const improvedText = await this.improve(text, options);
+    const improvedText = await this.improvedText(text, options);
     const diff = this.generateDiff(text, improvedText);
 
     return {
diff --git a/src/utils/formatters.ts b/src/utils/formatters.ts
index 206d9eac..11d3e202 100644
--- a/src/utils/formatters.ts
+++ b/src/utils/formatters.ts
@@ -48,6 +48,19 @@ export interface WriteJsonOutput {
   language: string;
 }
 
+/**
+ * `write --alternatives` / `correct --alternatives` under `--format json`.
+ *
+ * `ok` marks it as a result rather than the `ok: false` error envelope, the same
+ * discrimination the `--check` payload offers. `WriteJsonOutput` predates the
+ * envelope and keeps its shape.
+ */
+export interface WriteAlternativesJsonOutput {
+  ok: true;
+  original: string;
+  alternatives: string[];
+}
+
 export interface MultiTranslateJsonOutput {
   translations: Array<{
     targetLang: Language;
@@ -130,6 +143,22 @@ export function formatWriteJson(
   return JSON.stringify(output, null, 2);
 }
 
+/**
+ * Format every alternative the Write API offered as JSON
+ */
+export function formatWriteAlternativesJson(
+  original: string,
+  alternatives: string[]
+): string {
+  const output: WriteAlternativesJsonOutput = {
+    ok: true,
+    original,
+    alternatives,
+  };
+
+  return JSON.stringify(output, null, 2);
+}
+
 /**
  * Format multiple translation results as table
  */
diff --git a/tests/e2e/cli-write-output-modes-json.e2e.test.ts b/tests/e2e/cli-write-output-modes-json.e2e.test.ts
new file mode 100644
index 00000000..8ceb42f5
--- /dev/null
+++ b/tests/e2e/cli-write-output-modes-json.e2e.test.ts
@@ -0,0 +1,366 @@
+/**
+ * E2E tests for `write`/`correct` `--diff` and `--alternatives` under
+ * `--format json`.
+ *
+ * Both modes declared the flag and ignored it: `--alternatives` returned the
+ * numbered text list whatever the format, and `--diff` printed the human
+ * three-block report in which the block labelled `Improved:` held a rendered
+ * JSON document, so the unified diff described JSON scaffolding rather than
+ * wording. Each now has a payload of its own, carrying `ok: true` so a consumer
+ * discriminates it from the `ok: false` error envelope the same way the
+ * `--check` result payload is discriminated.
+ */
+
+import {
+  spawn,
+  spawnSync,
+  ChildProcess,
+  SpawnSyncReturns,
+} from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const CLI_PATH = path.join(process.cwd(), 'dist/cli/index.js');
+
+/** Comes back from the mock with one word appended. */
+const DIRTY_TEXT = 'Their going to the store';
+/** Comes back from the mock as three improvements. */
+const VARIANTS_TEXT = 'Please offer variants of this';
+
+/** Built from the code point so the source carries no control byte. */
+const ESC = String.fromCharCode(0x1b);
+
+interface RunResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+describe('write/correct output modes under --format json', () => {
+  let mockServer: ChildProcess;
+  let configDir: string;
+  let workDir: string;
+
+  function startMockServer(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const script = path.join(__dirname, 'write-check-server.cjs');
+      const child = spawn('node', [script], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      mockServer = child;
+
+      let output = '';
+      child.stdout.on('data', (data: Buffer) => {
+        output += data.toString();
+        const match = output.match(/PORT=(\d+)/);
+        if (match) {
+          resolve(parseInt(match[1]!, 10));
+        }
+      });
+      child.stderr.on('data', (data: Buffer) => {
+        process.stderr.write(`[write-check-server] ${data.toString()}`);
+      });
+      child.on('error', reject);
+      setTimeout(
+        () => reject(new Error('mock server did not start within 15s')),
+        15000
+      );
+    });
+  }
+
+  beforeAll(async () => {
+    const port = await startMockServer();
+
+    configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-modes-json-cfg-'));
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify({
+        auth: { apiKey: 'mock-api-key-for-testing:fx' },
+        api: { baseUrl: `http://127.0.0.1:${port}`, usePro: false },
+        cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
+        output: { format: 'text', verbose: false, color: false },
+        defaults: {
+          targetLangs: [],
+          formality: 'default',
+          preserveFormatting: true,
+        },
+      }),
+      { mode: 0o600 }
+    );
+  }, 30000);
+
+  beforeEach(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-modes-json-work-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  afterAll(() => {
+    if (mockServer) {
+      mockServer.kill('SIGTERM');
+    }
+    fs.rmSync(configDir, { recursive: true, force: true });
+  });
+
+  function run(args: string[], colored = false): RunResult {
+    const result: SpawnSyncReturns<string> = spawnSync(
+      'node',
+      [CLI_PATH, ...args],
+      {
+        encoding: 'utf-8',
+        cwd: workDir,
+        env: {
+          ...process.env,
+          DEEPL_CONFIG_DIR: configDir,
+          DEEPL_API_KEY: 'mock-api-key-for-testing:fx',
+          ...(colored ? { FORCE_COLOR: '3' } : { NO_COLOR: '1' }),
+        },
+        timeout: 20000,
+      }
+    );
+    return {
+      status: result.status ?? 1,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  const COMMANDS = [
+    { label: 'write', command: 'write', improvedHeading: 'Improved:' },
+    { label: 'correct', command: 'correct', improvedHeading: 'Corrected:' },
+  ];
+
+  describe.each(COMMANDS)('$label --diff --format json', (subject) => {
+    it('emits the diff payload with the improved text, not a rendered document', () => {
+      const result = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--diff',
+        '--format',
+        'json',
+      ]);
+
+      expect(result.status).toBe(0);
+      const payload = JSON.parse(result.stdout) as {
+        ok: boolean;
+        original: string;
+        improved: string;
+        diff: string;
+      };
+      expect(payload.ok).toBe(true);
+      expect(payload.original).toBe(DIRTY_TEXT);
+      expect(payload.improved).toBe(`${DIRTY_TEXT} (improved)`);
+      expect(Object.keys(payload).sort()).toEqual([
+        'diff',
+        'improved',
+        'ok',
+        'original',
+      ]);
+    });
+
+    it('carries a unified patch of the text, free of JSON scaffolding', () => {
+      const result = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--diff',
+        '--format',
+        'json',
+      ]);
+
+      const { diff } = JSON.parse(result.stdout) as { diff: string };
+      expect(diff).toContain(`-${DIRTY_TEXT}`);
+      expect(diff).toContain(`+${DIRTY_TEXT} (improved)`);
+      expect(diff).not.toContain('"improved":');
+      expect(diff).not.toContain('"language":');
+    });
+
+    it('leaves no colour escapes in the payload even when colour is forced', () => {
+      const result = run(
+        [subject.command, DIRTY_TEXT, '--diff', '--format', 'json'],
+        true
+      );
+
+      expect(result.stdout).not.toContain(ESC);
+      const { diff } = JSON.parse(result.stdout) as { diff: string };
+      expect(diff).not.toContain(ESC);
+    });
+
+    it('reads a file input as the original', () => {
+      fs.writeFileSync(path.join(workDir, 'draft.txt'), DIRTY_TEXT, 'utf-8');
+
+      const result = run([
+        subject.command,
+        'draft.txt',
+        '--diff',
+        '--format',
+        'json',
+      ]);
+
+      expect(result.status).toBe(0);
+      const payload = JSON.parse(result.stdout) as { original: string };
+      expect(payload.original).toBe(DIRTY_TEXT);
+    });
+  });
+
+  describe.each(COMMANDS)('$label --alternatives --format json', (subject) => {
+    it('emits the alternatives as an array', () => {
+      const result = run([
+        subject.command,
+        VARIANTS_TEXT,
+        '--alternatives',
+        '--format',
+        'json',
+      ]);
+
+      expect(result.status).toBe(0);
+      expect(JSON.parse(result.stdout)).toEqual({
+        ok: true,
+        original: VARIANTS_TEXT,
+        alternatives: [
+          `${VARIANTS_TEXT} (simple)`,
+          `${VARIANTS_TEXT} (business)`,
+          `${VARIANTS_TEXT} (casual)`,
+        ],
+      });
+    });
+
+    it('emits a single-element array when the API offers one improvement', () => {
+      const result = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--alternatives',
+        '--format',
+        'json',
+      ]);
+
+      expect(JSON.parse(result.stdout)).toEqual({
+        ok: true,
+        original: DIRTY_TEXT,
+        alternatives: [`${DIRTY_TEXT} (improved)`],
+      });
+    });
+  });
+
+  // Over-rejection guards: every path that already worked must not move.
+  describe.each(COMMANDS)('$label text mode is unchanged', (subject) => {
+    it('prints the three-block diff report', () => {
+      const result = run([subject.command, DIRTY_TEXT, '--diff']);
+
+      expect(result.status).toBe(0);
+      expect(result.stdout).toContain('Original:');
+      expect(result.stdout).toContain(subject.improvedHeading);
+      expect(result.stdout).toContain('Diff:');
+      expect(result.stdout).toContain(`+${DIRTY_TEXT} (improved)`);
+      expect(() => JSON.parse(result.stdout)).toThrow();
+    });
+
+    it('prints the numbered alternatives list', () => {
+      const result = run([subject.command, VARIANTS_TEXT, '--alternatives']);
+
+      expect(result.status).toBe(0);
+      expect(result.stdout).toContain(`1. ${VARIANTS_TEXT} (simple)`);
+      expect(result.stdout).toContain(`2. ${VARIANTS_TEXT} (business)`);
+      expect(result.stdout).toContain(`3. ${VARIANTS_TEXT} (casual)`);
+    });
+  });
+
+  describe.each(COMMANDS)(
+    '$label other JSON payloads are unchanged',
+    (subject) => {
+      it('keeps the plain improvement payload, which carries no ok field', () => {
+        const result = run([subject.command, DIRTY_TEXT, '--format', 'json']);
+
+        expect(result.status).toBe(0);
+        expect(JSON.parse(result.stdout)).toEqual({
+          original: DIRTY_TEXT,
+          improved: `${DIRTY_TEXT} (improved)`,
+          changes: 1,
+          language: 'auto-detected',
+        });
+      });
+
+      it('keeps the --check result payload', () => {
+        const result = run([
+          subject.command,
+          DIRTY_TEXT,
+          '--check',
+          '--format',
+          'json',
+        ]);
+
+        expect(result.status).toBe(8);
+        expect(JSON.parse(result.stdout)).toEqual({
+          ok: true,
+          mode: subject.command,
+          needsChanges: true,
+          changes: 1,
+        });
+      });
+    }
+  );
+
+  // --output and --in-place receive whatever the improvement renders to, which
+  // under --format json is the payload. That predates this change for the plain
+  // path and is deliberately left as it stands.
+  describe.each(COMMANDS)('$label --output under --format json', (subject) => {
+    it('writes the plain improvement payload', () => {
+      const result = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--format',
+        'json',
+        '--output',
+        'out.json',
+      ]);
+
+      expect(result.status).toBe(0);
+      expect(
+        JSON.parse(fs.readFileSync(path.join(workDir, 'out.json'), 'utf-8'))
+      ).toEqual({
+        original: DIRTY_TEXT,
+        improved: `${DIRTY_TEXT} (improved)`,
+        changes: 1,
+        language: 'auto-detected',
+      });
+    });
+
+    it('writes the alternatives payload with --alternatives', () => {
+      const result = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--alternatives',
+        '--format',
+        'json',
+        '--output',
+        'alts.json',
+      ]);
+
+      expect(result.status).toBe(0);
+      expect(
+        JSON.parse(fs.readFileSync(path.join(workDir, 'alts.json'), 'utf-8'))
+      ).toEqual({
+        ok: true,
+        original: DIRTY_TEXT,
+        alternatives: [`${DIRTY_TEXT} (improved)`],
+      });
+    });
+
+    it('writes the numbered list with --alternatives in text mode', () => {
+      const result = run([
+        subject.command,
+        DIRTY_TEXT,
+        '--alternatives',
+        '--output',
+        'alts.txt',
+      ]);
+
+      expect(result.status).toBe(0);
+      expect(fs.readFileSync(path.join(workDir, 'alts.txt'), 'utf-8')).toBe(
+        `1. ${DIRTY_TEXT} (improved)`
+      );
+    });
+  });
+});
diff --git a/tests/e2e/write-check-server.cjs b/tests/e2e/write-check-server.cjs
index 75116606..1b852024 100644
--- a/tests/e2e/write-check-server.cjs
+++ b/tests/e2e/write-check-server.cjs
@@ -4,9 +4,11 @@
  * not depend on how many calls preceded it.
  *
  * Text containing the word `polished` comes back unchanged, which is what a
- * clean check looks like; anything else comes back with ` (improved)` appended,
- * which is a one-word change. Both `/v2/write/rephrase` and `/v2/write/correct`
- * answer, so `write` and `correct` share the server.
+ * clean check looks like; text containing `variants` comes back as three
+ * improvements, which is what `--alternatives` has to render; anything else comes
+ * back with ` (improved)` appended, which is a one-word change. Both
+ * `/v2/write/rephrase` and `/v2/write/correct` answer, so `write` and `correct`
+ * share the server.
  *
  * Prints `PORT=<port>` on stdout once listening. Runs in its own process because
  * the test driver blocks its own event loop on spawnSync and would otherwise
@@ -30,11 +32,20 @@ const server = http.createServer((req, res) => {
       (req.url === '/v2/write/rephrase' || req.url === '/v2/write/correct')
     ) {
       const params = new URLSearchParams(body);
-      const improvements = params.getAll('text').map((text) => ({
-        text: text.includes('polished') ? text : text + ' (improved)',
-        target_language: params.get('target_lang') || 'en-US',
-        detected_source_language: 'EN',
-      }));
+      const targetLanguage = params.get('target_lang') || 'en-US';
+      const improvements = [];
+      for (const text of params.getAll('text')) {
+        const variants = text.includes('variants')
+          ? [text + ' (simple)', text + ' (business)', text + ' (casual)']
+          : [text.includes('polished') ? text : text + ' (improved)'];
+        for (const variant of variants) {
+          improvements.push({
+            text: variant,
+            target_language: targetLanguage,
+            detected_source_language: 'EN',
+          });
+        }
+      }
 
       res.writeHead(200);
       res.end(JSON.stringify({ improvements }));
diff --git a/tests/unit/register-write.test.ts b/tests/unit/register-write.test.ts
index 45928227..73bf76b1 100644
--- a/tests/unit/register-write.test.ts
+++ b/tests/unit/register-write.test.ts
@@ -43,6 +43,7 @@ const mockWriteCommand = {
   checkFile: jest.fn(),
   autoFixFile: jest.fn(),
   improveWithDiff: jest.fn(),
+  generatePatch: jest.fn(),
   improveFileWithDiff: jest.fn(),
   improveInteractive: jest.fn(),
   improveFileInteractive: jest.fn(),
@@ -860,6 +861,77 @@ describe('registerWrite', () => {
         expect.any(Object)
       );
     });
+
+    describe('--format json', () => {
+      let stdout: string[];
+      let stdoutSpy: jest.SpyInstance;
+
+      beforeEach(() => {
+        stdout = [];
+        stdoutSpy = jest
+          .spyOn(process.stdout, 'write')
+          .mockImplementation((chunk: unknown) => {
+            stdout.push(String(chunk));
+            return true;
+          });
+      });
+
+      afterEach(() => {
+        stdoutSpy.mockRestore();
+      });
+
+      it('should emit the diff payload with the uncoloured patch', async () => {
+        mockWriteCommand.improveWithDiff.mockResolvedValue({
+          original: 'old',
+          improved: 'new',
+          diff: 'coloured diff',
+        });
+        mockWriteCommand.generatePatch.mockReturnValue('-old\n+new');
+
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'some text',
+          '--diff',
+          '--format',
+          'json',
+        ]);
+
+        expect(mockWriteCommand.generatePatch).toHaveBeenCalledWith(
+          'old',
+          'new'
+        );
+        expect(JSON.parse(stdout.join(''))).toEqual({
+          ok: true,
+          original: 'old',
+          improved: 'new',
+          diff: '-old\n+new',
+        });
+        expect(Logger.output).not.toHaveBeenCalled();
+      });
+
+      it('should print the human report in text mode', async () => {
+        mockWriteCommand.improveWithDiff.mockResolvedValue({
+          original: 'old',
+          improved: 'new',
+          diff: 'coloured diff',
+        });
+
+        await program.parseAsync([
+          'node',
+          'test',
+          'write',
+          'some text',
+          '--diff',
+        ]);
+
+        expect(stdout.join('')).toBe('');
+        expect(Logger.output).toHaveBeenCalledWith(
+          expect.stringContaining('Original')
+        );
+      });
+    });
   });
 
   describe('--interactive mode', () => {
diff --git a/tests/unit/write-command.test.ts b/tests/unit/write-command.test.ts
index 6c0e0f3b..5dd44410 100644
--- a/tests/unit/write-command.test.ts
+++ b/tests/unit/write-command.test.ts
@@ -335,6 +335,40 @@ describe('WriteCommand', () => {
         expect(result).toMatch(/1\./);
         expect(result).toMatch(/2\./);
       });
+
+      it('should return the alternatives payload under format json', async () => {
+        mockWriteService.improve.mockResolvedValue([
+          { text: 'Option one.', targetLanguage: 'en-US' },
+          { text: 'Option two.', targetLanguage: 'en-US' },
+        ]);
+
+        const result = await writeCommand.improve('Test', {
+          lang: 'en-us',
+          showAlternatives: true,
+          format: 'json',
+        });
+
+        expect(JSON.parse(result)).toEqual({
+          ok: true,
+          original: 'Test',
+          alternatives: ['Option one.', 'Option two.'],
+        });
+      });
+
+      it('should call the API once for the alternatives payload', async () => {
+        mockWriteService.improve.mockResolvedValue([
+          { text: 'Option one.', targetLanguage: 'en-US' },
+        ]);
+
+        await writeCommand.improve('Test', {
+          lang: 'en-us',
+          showAlternatives: true,
+          format: 'json',
+        });
+
+        expect(mockWriteService.improve).toHaveBeenCalledTimes(1);
+        expect(mockWriteService.getBestImprovement).not.toHaveBeenCalled();
+      });
     });
 
     describe('parameter constraints', () => {
@@ -599,6 +633,34 @@ describe('WriteCommand', () => {
     });
   });
 
+  describe('generatePatch()', () => {
+    it('should produce the unified patch the coloured diff is built from', () => {
+      const patch = writeCommand.generatePatch('Original.', 'Improved.');
+
+      expect(patch).toContain('-Original.');
+      expect(patch).toContain('+Improved.');
+      expect(patch).toContain('@@');
+    });
+  });
+
+  describe('improveWithDiff() with format json', () => {
+    it('should report the improved text, not a rendered document', async () => {
+      mockWriteService.getBestImprovement.mockResolvedValue({
+        text: 'Improved text.',
+        targetLanguage: 'en-US',
+      });
+
+      const result = await writeCommand.improveWithDiff('Original text.', {
+        lang: 'en-us',
+        format: 'json',
+      });
+
+      expect(result.original).toBe('Original text.');
+      expect(result.improved).toBe('Improved text.');
+      expect(result.diff).toContain('+Improved text.');
+    });
+  });
+
   describe('improveWithDiff()', () => {
     it('should return improved text with diff view', async () => {
       const original = 'Original text.';

From db00c03175632bd9061c83f90bd25b33873813ac Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 22:42:19 +0200
Subject: [PATCH 229/256] refactor(comments): trim narration from the api,
 storage and types layers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comments-only. The invariants a reader cannot recover from the code stay --
why POST is excluded from the replay set, why an empty Retry-After needs its
own check when Number('') is 0, why classification is idempotent, why the
XDG path priority is what it is -- while the story of the defect each guard
was written against goes, since the commit log and CHANGELOG already hold it.

Two docblocks were attached to the wrong declaration: the GET /v3/languages
contract sat above the private `translateLanguages` field with a second
docblock beneath it, and is now on `getSupportedLanguages`.

Also drops a crop of pure restatement in cache.ts and config.ts
(`/** Get cache statistics */`, `/** Enable cache */`, `// Validate boolean
fields`) that repeats the signature on the next line.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/api/http-client.ts        | 28 ++++++++----------------
 src/api/response-shape.ts     | 16 ++++++--------
 src/api/translation-client.ts | 12 +++++------
 src/data/language-registry.ts |  3 +--
 src/storage/cache.ts          | 40 +++++++----------------------------
 src/storage/config.ts         | 37 ++++++--------------------------
 src/types/glossary.ts         |  3 ---
 7 files changed, 36 insertions(+), 103 deletions(-)

diff --git a/src/api/http-client.ts b/src/api/http-client.ts
index 55353a76..bee4f457 100644
--- a/src/api/http-client.ts
+++ b/src/api/http-client.ts
@@ -141,8 +141,6 @@ function isResponseTooLarge(error: AxiosError): boolean {
  * recommended variant for retry-storm dampening: it removes the fixed
  * lower bound of "equal jitter" entirely, so concurrent clients that
  * all 429 simultaneously see maximum decorrelation on the next attempt.
- * Exported for unit testing; the caller pulls the randomized value
- * and passes it straight to `sleep()`.
  */
 export function computeBackoffWithJitter(attempt: number): number {
   const cap = Math.min(
@@ -171,8 +169,7 @@ export class HttpClient {
 
   /**
    * Standard NO_PROXY matching: `*` bypasses everything, a leading dot or `*.`
-   * matches subdomains, and an entry may carry a port. Without this a corporate
-   * HTTPS_PROXY was applied even to a localhost endpoint.
+   * matches subdomains, and an entry may carry a port.
    */
   private static isProxyBypassed(targetUrl: string): boolean {
     const noProxy = process.env['NO_PROXY'] ?? process.env['no_proxy'];
@@ -314,13 +311,11 @@ export class HttpClient {
     const proxyConfig = options.proxy ?? HttpClient.parseProxyFromEnv(baseURL);
 
     if (proxyConfig) {
-      // SECURITY: a plain-http proxy sitting in front of an https: API
-      // endpoint is a MITM footgun. axios tunnels via CONNECT so TLS is
-      // nominally end-to-end, but a misconfigured or compromised proxy
-      // env var routes every DeepL call — including the Authorization
-      // header — through attacker infrastructure. Warn loud at startup;
-      // don't refuse the connection (users with legitimate corporate
-      // http-only proxies need the escape hatch).
+      // SECURITY: axios tunnels via CONNECT so TLS is nominally end-to-end,
+      // but a plain-http proxy in front of an https: endpoint is a MITM
+      // footgun — a compromised one that terminates TLS sees every DeepL call,
+      // Authorization header included. Warn rather than refuse: users with
+      // legitimate corporate http-only proxies need the escape hatch.
       if (proxyConfig.protocol === 'http' && baseURL.startsWith('https:')) {
         Logger.warn(
           `Warning: routing HTTPS traffic to ${baseURL} via HTTP proxy ${proxyConfig.host}:${proxyConfig.port}. ` +
@@ -604,8 +599,6 @@ export class HttpClient {
       // user-facing error strings. Defense-in-depth against a malicious or
       // buggy server scribbling ANSI escape codes / control chars on the
       // user's terminal, matching the sanitization in tms-client.ts.
-      // Coalesce to '' before sanitizing — some axios error shapes have no
-      // `.message` field, and sanitizeForTerminal expects a string.
       const message = sanitizeForTerminal(
         responseData?.message ?? error.message ?? ''
       );
@@ -651,12 +644,9 @@ export class HttpClient {
           // body was read — cut off mid-body, or a body the transport could
           // not decode. The status is what decides it: the axios code varies
           // with how the peer failed (ERR_BAD_RESPONSE for an aborted stream,
-          // a socket or zlib code otherwise), while the mere presence of a
-          // response used to send all of these to `ValidationError`, telling
-          // the operator to check input that was never the problem and
-          // charging them exit 6 for a transport failure. Deadline aborts are
-          // restated before classification (see `makeRequest`), so what
-          // arrives here is the peer's doing.
+          // a socket or zlib code otherwise). Deadline aborts are restated
+          // before classification (see `makeRequest`), so what arrives here is
+          // the peer's doing.
           if (status !== undefined && status >= 200 && status < 300) {
             return new NetworkError(
               `Network error: the API answered HTTP ${status} but its response body did not arrive intact: ${message}${traceIdSuffix}`
diff --git a/src/api/response-shape.ts b/src/api/response-shape.ts
index 243f6200..d86dd5ba 100644
--- a/src/api/response-shape.ts
+++ b/src/api/response-shape.ts
@@ -6,13 +6,10 @@ import { NetworkError } from '../utils/errors.js';
  * A response body is untrusted input: the endpoint can be redirected by
  * `--api-url`, an `api.baseUrl` in the config, or a proxy, and a redirected host
  * can return well-formed JSON of any shape. Declaring a TypeScript interface for
- * the body asserts nothing at runtime, so without these checks a wrong-shaped
- * value is carried all the way into terminal output, a written file, or an i18n
- * bucket.
+ * the body asserts nothing at runtime.
  *
- * Follows the contract `sanitizePullKeysResponse` sets for the TMS: reject
- * rather than coerce, and name the offending type so the endpoint is
- * diagnosable.
+ * The policy matches `sanitizePullKeysResponse`: reject rather than coerce, and
+ * name the offending type so the endpoint is diagnosable.
  */
 
 function describe(value: unknown): string {
@@ -24,10 +21,9 @@ function describe(value: unknown): string {
 /**
  * Require `body` to be `{ [field]: Array<object> }` and return that array.
  *
- * The string case is the one that mattered most in practice: a string has a
- * truthy `.length`, so a `!body[field]` guard followed by a length comparison
- * passed, `[0]` yielded `undefined`, and `undefined` was printed as the
- * translation at exit 0.
+ * A string is the case a truthiness-plus-length guard cannot catch: it has a
+ * truthy `.length` but indexing it yields characters rather than items, so the
+ * array-ness has to be tested explicitly.
  */
 export function requireItemArray(
   body: unknown,
diff --git a/src/api/translation-client.ts b/src/api/translation-client.ts
index cf73b833..4b2294aa 100644
--- a/src/api/translation-client.ts
+++ b/src/api/translation-client.ts
@@ -368,12 +368,6 @@ export class TranslationClient extends HttpClient {
     }
   }
 
-  /**
-   * Lists languages via GET /v3/languages (v2 is deprecated). One response
-   * carries both roles as usable_as_source/usable_as_target flags, filtered
-   * here to preserve the per-type contract. Formality support comes from the
-   * per-language features matrix, which is what v2's supports_formality became.
-   */
   /**
    * The raw translate_text language list, fetched at most once per client. The
    * request does not vary by role and both roles are filtered out of the one
@@ -394,6 +388,12 @@ export class TranslationClient extends HttpClient {
     return this.translateLanguages;
   }
 
+  /**
+   * Lists languages via GET /v3/languages (v2 is deprecated). One response
+   * carries both roles as usable_as_source/usable_as_target flags, filtered
+   * here to preserve the per-type contract. Formality support comes from the
+   * per-language features matrix, which is what v2's supports_formality became.
+   */
   async getSupportedLanguages(
     type: 'source' | 'target'
   ): Promise<LanguageInfo[]> {
diff --git a/src/data/language-registry.ts b/src/data/language-registry.ts
index 1594a14c..cf3300b0 100644
--- a/src/data/language-registry.ts
+++ b/src/data/language-registry.ts
@@ -45,8 +45,7 @@ export interface LanguageEntry {
  *
  * `LanguageEntry`'s fields are `readonly` because the accessors below hand out
  * these very objects: a caller mutating one would change the registry for the
- * whole process, which the generated `as const` tuple forbids but a widened
- * element type would have silently permitted.
+ * whole process.
  */
 const ENTRIES: readonly LanguageEntry[] = GENERATED_ENTRIES;
 
diff --git a/src/storage/cache.ts b/src/storage/cache.ts
index 3f772334..de2fb9f6 100644
--- a/src/storage/cache.ts
+++ b/src/storage/cache.ts
@@ -71,11 +71,11 @@ function isCorruptionError(error: unknown): boolean {
  * `PRAGMA user_version` on fresh DBs and checked on every open. Bumping
  * this number means "future callers will read a DB laid out differently."
  *
- * Version 2 marks a change in how translation cache keys are computed. Version 3
- * adds the resolved API endpoint to the translation, write, and correct keys, so
- * all three namespaces changed. Opening an older DB drops the rows whose keys can
- * no longer be reached and leaves every other namespace in place. The table layout
- * is identical in all versions, so nothing is migrated.
+ * The bumps so far changed how the translation, write and correct cache keys are
+ * computed — version 3 adds the resolved API endpoint to all three. Opening an
+ * older DB drops the rows whose keys can no longer be reached and leaves every
+ * other namespace in place. The table layout is identical in all versions, so
+ * nothing is migrated.
  */
 const CACHE_SCHEMA_VERSION = 3;
 
@@ -185,8 +185,8 @@ export class CacheService {
   private openDatabase(dbPath: string): void {
     const dir = path.dirname(dbPath);
     // Unconditional: a recursive mkdir does not fail on a directory that already
-    // exists, and the existsSync it replaces left a window for one to appear
-    // between the check and the create.
+    // exists, and an existence check first would leave a window for one to
+    // appear between the check and the create.
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     warnOnWritableDirectory(dir);
     this.db = new DatabaseSync(dbPath);
@@ -262,8 +262,7 @@ export class CacheService {
       // size budget and `cache stats` until its TTL expires. Dropping them is
       // also the point: a row poisoned by a run against a custom endpoint must
       // not survive the upgrade that stops it happening again. Other namespaces
-      // (glossary listings, language lists) are unaffected and stay. A fresh DB
-      // has no rows, so this is a no-op on first open.
+      // (glossary listings, language lists) are unaffected and stay.
       this.db.exec(
         "DELETE FROM cache WHERE key LIKE 'translation:%' OR key LIKE 'write:%' OR key LIKE 'correct:%'"
       );
@@ -284,9 +283,6 @@ export class CacheService {
     return row.total;
   }
 
-  /**
-   * Get value from cache
-   */
   get(key: string): unknown;
   get<T>(key: string, guard: (data: unknown) => data is T): T | null;
   get<T>(key: string, guard?: (data: unknown) => data is T): T | null {
@@ -294,7 +290,6 @@ export class CacheService {
       return null;
     }
 
-    // Clean up expired entries first
     this.cleanupExpired();
 
     const stmt = this.db.prepare(
@@ -306,9 +301,7 @@ export class CacheService {
       return null;
     }
 
-    // Check if entry is expired
     if (this.ttl > 0 && Date.now() - row.timestamp > this.ttl) {
-      // Delete expired entry
       this.db.prepare('DELETE FROM cache WHERE key = ?').run(key);
       return null;
     }
@@ -358,10 +351,8 @@ export class CacheService {
       return;
     }
 
-    // Clean up expired entries
     this.cleanupExpired();
 
-    // Check if key already exists and get its size
     const existingStmt = this.db.prepare(
       'SELECT size FROM cache WHERE key = ?'
     );
@@ -382,9 +373,6 @@ export class CacheService {
     this.db.exec('DELETE FROM cache');
   }
 
-  /**
-   * Get cache statistics
-   */
   stats(): CacheStats {
     const stmt = this.db.prepare(`
       SELECT COUNT(*) as count, COALESCE(SUM(size), 0) as total
@@ -400,23 +388,14 @@ export class CacheService {
     };
   }
 
-  /**
-   * Enable cache
-   */
   enable(): void {
     this.enabled = true;
   }
 
-  /**
-   * Disable cache
-   */
   disable(): void {
     this.enabled = false;
   }
 
-  /**
-   * Set maximum cache size
-   */
   setMaxSize(maxSize: number): void {
     if (maxSize < 0) {
       throw new ConfigError('Max size must be positive');
@@ -424,9 +403,6 @@ export class CacheService {
     this.maxSize = maxSize;
   }
 
-  /**
-   * Close database connection
-   */
   close(): void {
     if (!this.isClosed) {
       this.db.close();
diff --git a/src/storage/config.ts b/src/storage/config.ts
index dafdbb34..12cdb717 100644
--- a/src/storage/config.ts
+++ b/src/storage/config.ts
@@ -145,11 +145,10 @@ export class ConfigService {
   }
 
   /**
-   * Get the entire configuration
-   * Returns a readonly reference to prevent accidental mutations
+   * A readonly reference to the live configuration.
    *
-   * IMPORTANT: Do not mutate the returned config object.
-   * If you need to modify the config, use set() method instead.
+   * IMPORTANT: Do not mutate the returned object. To change a setting, use
+   * `set()`, which validates the value and persists it.
    */
   get(): Readonly<DeepLConfig> {
     return this.config;
@@ -208,9 +207,6 @@ export class ConfigService {
     return current as T;
   }
 
-  /**
-   * Check if a configuration key exists
-   */
   has(key: string): boolean {
     const keys = key.split('.');
     let current: unknown = this.config;
@@ -231,9 +227,6 @@ export class ConfigService {
     return current !== undefined;
   }
 
-  /**
-   * Delete a configuration value
-   */
   delete(key: string): void {
     const keys = key.split('.');
     this.validateSegments(keys);
@@ -272,9 +265,6 @@ export class ConfigService {
     }
   }
 
-  /**
-   * Get default configuration
-   */
   static getDefaults(): DeepLConfig {
     return {
       auth: {
@@ -311,9 +301,6 @@ export class ConfigService {
     };
   }
 
-  /**
-   * Load configuration from disk
-   */
   private load(): DeepLConfig {
     try {
       if (fs.existsSync(this.configPath)) {
@@ -383,9 +370,6 @@ export class ConfigService {
     }
   }
 
-  /**
-   * Save configuration to disk
-   */
   private save(): void {
     // Unpredictable name, exclusive create. This file holds the API key in
     // plaintext, and at a guessable path a planted symlink would redirect the
@@ -394,8 +378,8 @@ export class ConfigService {
     const tmpPath = `${this.configPath}.tmp.${process.pid}.${randomBytes(6).toString('hex')}`;
     try {
       // Unconditional: a recursive mkdir does not fail on a directory that
-      // already exists, and the existsSync it replaces left a window for one to
-      // appear between the check and the create.
+      // already exists, and an existence check first would leave a window for
+      // one to appear between the check and the create.
       fs.mkdirSync(path.dirname(this.configPath), {
         recursive: true,
         mode: 0o700,
@@ -477,7 +461,6 @@ export class ConfigService {
 
     const path = keys.join('.');
 
-    // Validate specific paths
     if (path === 'defaults.sourceLang' && value !== undefined) {
       this.validateLanguage(value as string, path, true);
     }
@@ -519,7 +502,6 @@ export class ConfigService {
       }
     }
 
-    // Validate boolean fields
     if (
       BOOLEAN_CONFIG_PATHS.includes(
         path as (typeof BOOLEAN_CONFIG_PATHS)[number]
@@ -536,8 +518,7 @@ export class ConfigService {
    * Validate language code. Codes the bundled snapshot does not list are
    * accepted when they are shaped like a language tag, because GET /v3/languages
    * is the authority on which languages exist and the snapshot can lag it.
-   */
-  /**
+   *
    * @param announceUnknown - warn when the code is well-formed but absent from
    *   the bundled snapshot. Only the write path announces: every command loads
    *   the config, and a note on each invocation is noise, not guidance.
@@ -568,9 +549,6 @@ export class ConfigService {
     }
   }
 
-  /**
-   * Validate formality value
-   */
   private validateFormality(formality: string, key?: string): void {
     if (!VALID_FORMALITY.includes(formality as Formality)) {
       const context = key ? ` for "${key}"` : '';
@@ -580,9 +558,6 @@ export class ConfigService {
     }
   }
 
-  /**
-   * Validate output format
-   */
   private validateOutputFormat(format: string, key?: string): void {
     if (!VALID_OUTPUT_FORMATS.includes(format as OutputFormat)) {
       const context = key ? ` for "${key}"` : '';
diff --git a/src/types/glossary.ts b/src/types/glossary.ts
index aab1e817..dce91db3 100644
--- a/src/types/glossary.ts
+++ b/src/types/glossary.ts
@@ -8,7 +8,6 @@ import { ValidationError } from '../utils/errors.js';
 
 /**
  * Raw API response from DeepL v3 glossary endpoints
- * This matches the actual API response structure
  */
 export interface GlossaryApiResponse {
   glossary_id: string;
@@ -48,7 +47,6 @@ export function normalizeGlossaryInfo(
   options: { warnOnEmpty?: boolean } = {}
 ): GlossaryInfo {
   const { warnOnEmpty = true } = options;
-  // Extract unique source and target languages from dictionaries
   const sourceLangs = new Set<Language>();
   const targetLangs = new Set<Language>();
 
@@ -100,7 +98,6 @@ export function getTargetLang(
   glossary: GlossaryInfo,
   targetLang?: Language
 ): Language {
-  // If specified, validate it exists
   if (targetLang) {
     if (!glossary.target_langs.includes(targetLang)) {
       throw new ValidationError(

From 63a68c1dec74db5fa31fc574b8cfafa7cc698c31 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 22:42:31 +0200
Subject: [PATCH 230/256] refactor(comments): state the format-parser
 invariants as rules, not histories
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comments-only. The format quirks a reader cannot deduce from the code all stay,
rewritten in the present tense: why `r` must remain in the PO escape set, why
adjacent PO string literals cannot be read as one, why a blank line is only a
convention between entries, why U+2028 cannot be escaped the way TOML escapes
it, why `#~` blocks belong to no entry, and why a dotted TOML key must not be
excluded from the entry pattern.

Two things the task called out are now marked explicitly rather than left to
inference:

  * `PoEntry.rawLines` is written for every line and never read back. It is
    left in place on purpose, and now says so, because removing it looks like
    cleanup.
  * the second entry scanner in `reconstruct` must stay separate from
    `parseEntries` -- one yields decoded entries, the other rewrites the file
    line by line so untouched lines survive byte-for-byte.

`extractTranslations`' docblock also now states the half that was implicit: an
empty msgstr means "not translated yet", the opposite of what an empty value
means in a monolingual format. It, and the CDATA-breakout docblock in
android-xml.ts, were sitting above the wrong function behind a second docblock.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/formats/android-xml.ts  | 39 +++++++--------
 src/formats/ios-strings.ts  |  1 -
 src/formats/po.ts           | 98 ++++++++++++++++++-------------------
 src/formats/properties.ts   | 14 ++----
 src/formats/toml.ts         | 14 +++---
 src/formats/util/plurals.ts |  4 +-
 src/formats/xcstrings.ts    |  6 +--
 src/formats/xliff.ts        | 27 +++++-----
 8 files changed, 93 insertions(+), 110 deletions(-)

diff --git a/src/formats/android-xml.ts b/src/formats/android-xml.ts
index b2b7121c..01206394 100644
--- a/src/formats/android-xml.ts
+++ b/src/formats/android-xml.ts
@@ -73,11 +73,10 @@ const RESOURCES_EL: ElementPattern = {
  * The `name` / `quantity` of a scanned element.
  *
  * Group 0 is the quote delimiter, captured so the value can exclude only the
- * delimiter actually in use. Requiring a double quote made
+ * delimiter actually in use. Requiring a double quote would make
  * `<string name='greeting'>` — well-formed XML, and already accepted for every
- * other attribute by ATTRS — invisible: never extracted, never translated and
- * never reported, so `sync status` read 100% while the string shipped in the
- * source language.
+ * other attribute by ATTRS — invisible to the scan, so the string would be
+ * neither extracted nor reported while shipping in the source language.
  */
 function attrValue(element: ScannedElement): string {
   // Entity-decoded, because the writer escapes `&`/`"` when it interpolates a
@@ -172,10 +171,9 @@ function unescapeAndroid(value: string): string {
 }
 
 /**
- * A value written inside a double-quoted XML attribute.
- *
- * `name` / `quantity` used to be interpolated raw, so a key holding `&` or `"`
- * produced an element no XML consumer can read.
+ * A value written inside a double-quoted XML attribute. `name` and `quantity`
+ * are interpolated from keys, which may hold `&` or `"` — raw, either produces
+ * an element no XML consumer can read.
  */
 function escapeXmlAttr(value: string): string {
   return value
@@ -200,13 +198,6 @@ function escapeAndroid(value: string): string {
   );
 }
 
-/**
- * Refuse a value that would close the CDATA section it is written into.
- * Nothing inside a CDATA body is entity-escaped, so the text after a "]]>"
- * would be parsed as XML — an injected element in a generated resource file.
- * Fail fast rather than rewrite the value into something the round-trip
- * cannot reproduce, matching the XLIFF parser's stance on CDATA.
- */
 /**
  * Refuse a value XML 1.0 cannot carry. Every C0 byte except tab, LF and CR is
  * outside the `Char` production, so there is no escape and no numeric character
@@ -225,6 +216,13 @@ function assertNoControlChars(name: string, value: string): void {
   }
 }
 
+/**
+ * Refuse a value that would close the CDATA section it is written into.
+ * Nothing inside a CDATA body is entity-escaped, so the text after a "]]>"
+ * would be parsed as XML — an injected element in a generated resource file.
+ * Fail fast rather than rewrite the value into something the round-trip
+ * cannot reproduce, matching the XLIFF parser's stance on CDATA.
+ */
 function assertNoCdataBreakout(value: string): void {
   if (value.includes(']]>')) {
     throw new ValidationError(
@@ -276,11 +274,10 @@ export class AndroidXmlFormatParser implements FormatParser {
           )
         );
         // A key that NAMES a <plurals> element is that element, whatever shape it
-        // has. Routing on the key's shape alone sent a plurals entry called `x.0`
-        // into the string-array branch whenever a `<string-array name="x">` was
-        // present — so with the entry's plural metadata stripped, which is exactly
-        // what the carry-forward does, nothing claimed the element and the
-        // PLURALS_EL pass deleted it.
+        // has: a plurals key like `x.0` also reads as an item of
+        // `<string-array name="x">`, and a carried-forward entry arrives with its
+        // plural metadata stripped. Routing on the key's shape alone would leave
+        // the element unclaimed, for the PLURALS_EL pass to delete.
         pluralsNames ??= new Set(
           scanElements(originalContent, PLURALS_EL).map((el) => attrValue(el))
         );
@@ -412,7 +409,7 @@ export class AndroidXmlFormatParser implements FormatParser {
       ...missingStrings.map(([name, translation]) => {
         // The KEY is checked as well as the translation: it is interpolated into
         // the `name` attribute, and XML 1.0 has no representation for a C0 byte
-        // in any form, so a control byte in a source key produced a file no
+        // in any form, so a control byte in a source key yields a file no
         // consumer reads and a live terminal sequence in `git diff`.
         assertNoControlChars(name, name);
         assertNoControlChars(name, translation);
diff --git a/src/formats/ios-strings.ts b/src/formats/ios-strings.ts
index a7ff1de4..6d7a7963 100644
--- a/src/formats/ios-strings.ts
+++ b/src/formats/ios-strings.ts
@@ -39,7 +39,6 @@ export class IosStringsFormatParser implements FormatParser {
         continue;
       }
 
-      // Handle multi-line block comments
       if (trimmed.startsWith('/*') && !trimmed.endsWith('*/')) {
         let commentBody = trimmed;
         while (i + 1 < lines.length) {
diff --git a/src/formats/po.ts b/src/formats/po.ts
index dfaf222b..5b6e357c 100644
--- a/src/formats/po.ts
+++ b/src/formats/po.ts
@@ -21,6 +21,10 @@ interface PoEntry {
   msgidPlural: string | undefined;
   msgstr: string[];
   msgstrPlural: Map<number, string>;
+  /**
+   * Written for every parsed line and never read back. Left in place on
+   * purpose — removing it is not the cleanup it looks like.
+   */
   rawLines: string[];
 }
 
@@ -30,10 +34,10 @@ type ParseTarget =
 /**
  * One PO escape sequence, decoded.
  *
- * `r` is in the set because `quote` writes it: without it an escaped CR read
- * back as a literal backslash + 'r', whose backslash the next `quote` escaped in
- * turn, so a carried entry grew a backslash on every run. msgfmt flags neither
- * spelling.
+ * `r` must stay in the set because `quote` writes it: an escape this decoder
+ * does not know reads back as a literal backslash, which the next `quote`
+ * escapes in turn, so the value grows a backslash on every round trip. msgfmt
+ * flags neither spelling.
  */
 function unescapePoChar(ch: string): string {
   switch (ch) {
@@ -57,14 +61,12 @@ function unescapePoChar(ch: string): string {
  * literals.
  *
  * gettext joins adjacent string literals C-style, so `msgstr "Hola " "mundo"` is
- * `Hola mundo`. Testing only that the value starts and ends with a quote and
- * slicing read the inner `" "` as content, and the next write escaped those
- * quotes — corrupting the string permanently, with `msgfmt -c` unable to flag it
- * because both forms are well-formed.
+ * `Hola mundo`. Treating the value as one literal instead would read the inner
+ * `" "` as content and the next write would escape those quotes — corruption
+ * `msgfmt -c` cannot flag, because both forms are well-formed.
  *
  * A value that is not a well-formed run of literals (an unterminated quote, or
- * anything else between literals) is returned trimmed and untouched, which is
- * what the previous single-literal test did for input it did not recognise.
+ * anything else between literals) is returned trimmed and untouched.
  */
 function unquote(line: string): string {
   const trimmed = line.trim();
@@ -194,12 +196,9 @@ function makeKey(entry: PoEntry): string {
  * Whether `line` can only be the start of the next entry.
  *
  * gettext ends an entry at the first line that is not a continuation of its
- * translation; the blank line convention is a convention, and `msgfmt -c`
- * accepts a catalog with none. Treating a blank line as the only terminator
- * collapsed such a catalog into a single entry, which cost the reader every
- * key but the last and made the writer put one translation into every `msgstr`
- * it walked past — the header's included, deleting the charset and
- * `Plural-Forms` lines with it.
+ * translation; the blank line between entries is a convention only, and
+ * `msgfmt -c` accepts a catalog with none. A blank-line-only terminator would
+ * read such a catalog as a single entry.
  *
  * Only a msgstr-ish `target` can be interrupted this way. Before that the
  * entry is still assembling its `msgctxt`/`msgid`, where a second `msgid` line
@@ -221,14 +220,12 @@ function startsNextEntry(
 /**
  * The value-capturing line patterns below all carry the `s` flag.
  *
- * Without it `.` excludes U+2028 and U+2029, so a `msgstr` carrying either did
- * not match its own pattern at all: the line was invisible to both scanners, the
- * key was reported unwritten — honestly, at exit 12 — but under a remediation
- * about adding a containing group, and no later run could converge. gettext
- * itself accepts the byte raw (`msgfmt -c` exits 0 on such a catalog), so the
- * file is valid and it was this parser that could not read it. Escaping is not an
- * option the way it is for TOML: the PO escape set has no `\uXXXX`, so an escape
- * would round-trip back as the literal text.
+ * Without it `.` excludes U+2028 and U+2029, so a `msgstr` carrying either
+ * matches no pattern at all and the line is invisible to both scanners. gettext
+ * accepts the byte raw (`msgfmt -c` exits 0 on such a catalog), so the file is
+ * valid and it is this parser that cannot read it. Escaping is not an option the
+ * way it is for TOML: the PO escape set has no `\uXXXX`, so an escape would
+ * round-trip back as the literal text.
  */
 function parseEntries(content: string): PoEntry[] {
   const lines = content.split(/\r?\n/);
@@ -449,16 +446,6 @@ export class PoFormatParser implements FormatParser {
     return entries;
   }
 
-  /**
-   * PO is bilingual, so `extract().value` is the msgid even when the file being
-   * read is a target. The translation is the msgstr, and an empty msgstr is
-   * gettext's spelling of "not translated yet" — such a key is left out so a
-   * caller re-translates it rather than pinning the empty string.
-   *
-   * A plural entry has no bare msgstr; its first non-empty msgstr[n] stands in,
-   * which is enough to report the entry as translated. The per-form values
-   * travel separately in `metadata.plural_forms`.
-   */
   /**
    * Keys carrying gettext's `fuzzy` flag with a translation to go with it.
    *
@@ -489,6 +476,18 @@ export class PoFormatParser implements FormatParser {
     return flagged;
   }
 
+  /**
+   * PO is bilingual, so `extract().value` is the msgid even when the file being
+   * read is a target. The translation is the msgstr, and an empty msgstr is
+   * gettext's spelling of "not translated yet" — the opposite of what an empty
+   * value means in a monolingual format, where it is the translation. Such a key
+   * is left out so a caller re-translates it rather than pinning the empty
+   * string.
+   *
+   * A plural entry has no bare msgstr; its first non-empty msgstr[n] stands in,
+   * which is enough to report the entry as translated. The per-form values
+   * travel separately in `metadata.plural_forms`.
+   */
   extractTranslations(content: string): Map<string, string> {
     const translations = new Map<string, string>();
     if (!content.trim()) {
@@ -515,8 +514,12 @@ export class PoFormatParser implements FormatParser {
     return translations;
   }
 
-  // Comment bookkeeping is local rather than via PendingCommentBuffer: po
-  // backtracks into `result` at entry-start to slice trailing contiguous
+  // This walk is a second entry scanner alongside `parseEntries`, and the two
+  // must stay separate: `parseEntries` yields decoded entries, while this one
+  // rewrites the file line by line so untouched lines survive byte-for-byte.
+  //
+  // Comment bookkeeping is likewise local rather than via PendingCommentBuffer:
+  // po backtracks into `result` at entry-start to slice trailing contiguous
   // `#`-runs into `commentLines`, for pop-on-delete or splice-with-fuzzy-strip
   // on keep. That is incompatible with the buffer's forward-only flush/drop
   // semantics.
@@ -558,19 +561,17 @@ export class PoFormatParser implements FormatParser {
       let target: ParseTarget | undefined;
 
       // The run of comment lines immediately above the entry, taken with one
-      // slice. Walking backwards and `unshift`ing each line made this quadratic
-      // in the length of the run — `unshift` re-indexes the whole array every
-      // call — so a target file carrying one long comment block cost minutes:
-      // measured 28 ms at 20k comment lines, 109 ms at 40k and 437 ms at 80k,
-      // which is 4x the time for 2x the input.
+      // slice. Walking backwards and `unshift`ing each line is quadratic in the
+      // length of the run — `unshift` re-indexes the whole array every call —
+      // which costs minutes on a file carrying one long comment block.
       let backtrack = result.length - 1;
       while (
         backtrack >= 0 &&
         result[backtrack]!.startsWith('#') &&
         // `#~` marks gettext's retired-work region: those lines are an obsolete
-        // entry of their own, not this entry's comments. Claiming them meant that
-        // dropping an entry — a key the source no longer has — deleted the
-        // obsolete block sitting above it as well.
+        // entry of their own, not this entry's comments, so dropping an entry —
+        // a key the source no longer has — must not take the obsolete block
+        // above it along with it.
         !result[backtrack]!.startsWith('#~')
       ) {
         backtrack--;
@@ -742,8 +743,7 @@ export class PoFormatParser implements FormatParser {
           // being kept — a carried plural entry supplies no `plural_forms`, so
           // the file's own forms stand — must keep its continuations too:
           // gettext writes any form over 74 characters as `msgstr[N] ""` plus
-          // continuations, so dropping them left the empty first line as the
-          // whole translation.
+          // continuations, so its first line alone carries none of the text.
           inMsgstrPlural = pluralVal !== undefined;
           continue;
         }
@@ -786,10 +786,8 @@ export class PoFormatParser implements FormatParser {
       }
 
       // A plural entry is `msgid_plural` + one `msgstr[N]` per form, never a bare
-      // `msgstr`. Writing only the singular shape lost the plural forms of a key
-      // added to the source after the target file existed, so ngettext returned
-      // the English source for every count while the lockfile called the key
-      // translated.
+      // `msgstr`: written in the singular shape, ngettext falls back to the source
+      // string for every count.
       const msgidPlural = entry.metadata?.['msgid_plural'];
       if (typeof msgidPlural === 'string') {
         result.push(`msgid_plural ${quote(msgidPlural)}`);
diff --git a/src/formats/properties.ts b/src/formats/properties.ts
index 673f64e2..d13a10ac 100644
--- a/src/formats/properties.ts
+++ b/src/formats/properties.ts
@@ -8,11 +8,10 @@ import { appendEntryLines } from './util/append-lines.js';
 import { isForbiddenControlChar } from './util/control-chars.js';
 
 // A key, treating `\X` as one unit so an escaped separator belongs to the key
-// rather than ending it. Without that the parser could not read back a key it
-// had just written: `escapeKey` escapes `=`, `:`, space and backslash, so
-// `greeting:formal` is written `greeting\:formal` and was then split at the
-// escaped colon — key `greeting\`, value `formal=Hello`. Half the key went out
-// for translation as the value, and the real key never reached the target file.
+// rather than ending it — without that the parser cannot read back a key it has
+// just written. `escapeKey` escapes `=`, `:`, space and backslash, so
+// `greeting:formal` is written `greeting\:formal`; split at that escaped colon
+// it would read as key `greeting\` with value `formal=Hello`.
 const KEY_CHARS = String.raw`(?:[^=:#!\s\\]|\\.)(?:[^=:\\]|\\.)*?`;
 
 // `key = value` / `key: value`.
@@ -27,8 +26,7 @@ const COMMENT_RE = /^\s*[#!]/;
  * A trailing backslash continues the line only when the run of backslashes
  * ending it is odd; an even run is one or more escaped literal backslashes,
  * which is exactly what escapeValue emits for a value ending in `\`. Testing
- * `endsWith('\\')` instead consumed the following entry and appended its raw
- * `key=value` text to the previous value.
+ * `endsWith('\\')` instead would consume the entry on the following line.
  */
 function continuesOnNextLine(line: string): boolean {
   let backslashes = 0;
@@ -62,7 +60,6 @@ export class PropertiesFormatParser implements FormatParser {
         continue;
       }
 
-      // Handle line continuations (trailing backslash)
       while (continuesOnNextLine(line) && i + 1 < lines.length) {
         i++;
         line = line.slice(0, -1) + lines[i]!.trimStart();
@@ -109,7 +106,6 @@ export class PropertiesFormatParser implements FormatParser {
         continue;
       }
 
-      // Handle line continuations
       const startLine = i;
       while (continuesOnNextLine(line) && i + 1 < lines.length) {
         i++;
diff --git a/src/formats/toml.ts b/src/formats/toml.ts
index ba8c4ed8..7bc198e1 100644
--- a/src/formats/toml.ts
+++ b/src/formats/toml.ts
@@ -33,10 +33,8 @@ const KEY_SEGMENT = String.raw`(?:[A-Za-z0-9_-]+|"(?:[^"\\]|\\.)*"|'[^']*')`;
 // Quoted key segments are included because `extract` surfaces them: TOML.parse
 // turns `"greeting.formal" = "…"` into a property literally called
 // `greeting.formal`, so the sync pipeline treats it as translatable. Excluding
-// them here made the two halves disagree — reconstruct passed the line through
-// untranslated and then appended a NEW nested `[greeting] formal` entry, so the
-// key the source actually has kept its source-language text while the lockfile
-// recorded it translated.
+// them here would make the two halves disagree: reconstruct would pass the line
+// through untranslated and then append a NEW nested `[greeting] formal` entry.
 const ENTRY_LINE_RE = new RegExp(
   String.raw`^(\s*)(${KEY_SEGMENT}(?:\s*\.\s*${KEY_SEGMENT})*)(\s*=\s*)(.*)$`
 );
@@ -350,10 +348,10 @@ const BARE_KEY_RE = /^[A-Za-z0-9_-]+$/;
  * A key spelled the way TOML requires: bare where the character set allows,
  * otherwise a quoted key.
  *
- * Writing an unquoted `with space` produced a document smol-toml refuses on its
- * next read, and the unusable-target guard then pins the locale permanently
- * unreadable — the run that wrote the file is the run that broke it. Quoted keys
- * take the same escaping as a basic string.
+ * An unquoted `with space` produces a document smol-toml refuses on its next
+ * read, and the unusable-target guard then pins the locale permanently
+ * unreadable — the run that writes the file is the run that breaks it. Quoted
+ * keys take the same escaping as a basic string.
  */
 function encodeTomlKey(key: string): string {
   return BARE_KEY_RE.test(key) ? key : encodeTomlString(key, true);
diff --git a/src/formats/util/plurals.ts b/src/formats/util/plurals.ts
index 28f76aed..4e1fed07 100644
--- a/src/formats/util/plurals.ts
+++ b/src/formats/util/plurals.ts
@@ -14,9 +14,7 @@ export interface PluralItemLike {
  *
  * Chosen by quantity, never by matching `value`: English invariant nouns (fish,
  * sheep, series) and copy-pasted items make two forms carry the same source
- * text, and a value match then returned whichever came first — so the real
- * primary kept its source-language text, which was written to the target and
- * recorded as translated.
+ * text, so a value match would return whichever came first.
  */
 export function primaryPluralItem<T extends PluralItemLike>(
   plurals: readonly T[]
diff --git a/src/formats/xcstrings.ts b/src/formats/xcstrings.ts
index 9cca9d3f..0ec367a5 100644
--- a/src/formats/xcstrings.ts
+++ b/src/formats/xcstrings.ts
@@ -72,9 +72,9 @@ export class XcstringsFormatParser implements FormatParser {
       const def = (data.strings[entry.key] ??= {} as StringDefinition);
       def.localizations ??= {};
       const existing = def.localizations[locale];
-      // Replacing the whole localization discarded plural `variations`, which
-      // carry per-category translations this parser does not surface as
-      // entries — so they could never be restored.
+      // Merged rather than replaced: `variations` carry per-category
+      // translations this parser does not surface as entries, so nothing could
+      // restore them once discarded.
       if (existing?.variations) {
         def.localizations[locale] = {
           ...existing,
diff --git a/src/formats/xliff.ts b/src/formats/xliff.ts
index 2aafa9ef..f2e238f6 100644
--- a/src/formats/xliff.ts
+++ b/src/formats/xliff.ts
@@ -21,11 +21,10 @@ import {
 const VERSION_RE = /<(?:\w+:)?xliff[^>]*version=["'](\d+\.\d+)["']/i;
 
 // The quote delimiter is captured so the value can exclude only the delimiter
-// actually in use. Excluding both quote characters truncated `id="label.don't"`
-// at the apostrophe — well-formed XML, and only the delimiter needs escaping
-// inside a value — so two ids differing after an apostrophe collapsed onto one
-// key. XLIFF is exempt from `assertDistinctKeys`, so nothing reported the
-// collision and one unit shipped the other's translation.
+// actually in use: only the delimiter needs escaping inside a value, so
+// `id="label.don't"` is well-formed and must not be truncated at the apostrophe.
+// Two ids differing only after one would otherwise collapse onto a single key,
+// and XLIFF is exempt from `assertDistinctKeys`, so nothing would report it.
 const TRANS_UNIT_EL: ElementPattern = {
   open: /<(?:\w+:)?trans-unit\s+id=(["'])((?:(?!\1)[^<])+)\1[^><]*>/iy,
   close: /<\/(?:\w+:)?trans-unit>/iy,
@@ -106,12 +105,10 @@ interface AttrMatch {
  * Find an attribute by name in an element's attribute run.
  *
  * Attributes are walked as whole pairs rather than searched for with a single
- * unanchored regex. The old `state` pattern returned the FIRST `state=…` in the
- * string, so a `state='…'` sequence inside another attribute's value shadowed the
- * real one: the review state was neither read (`extractNeedsReview` missed it)
- * nor rewritten (the decoy was corrupted instead), leaving a
- * `needs-review-translation` marker attached to freshly machine-translated text.
- * Comparing the captured name in full also means `xstate=` is not a `state`.
+ * unanchored regex, so a `state='…'` sequence sitting inside another attribute's
+ * value cannot shadow the real one — which would leave the review state neither
+ * read nor rewritten. Comparing the captured name in full also means `xstate=`
+ * is not a `state`.
  */
 function findAttr(attrs: string, name: string): AttrMatch | undefined {
   ATTR_PAIR_RE.lastIndex = 0;
@@ -292,9 +289,9 @@ function escapeXml(value: string): string {
  * A value written inside a double-quoted attribute, where `"` also has to be
  * escaped.
  *
- * The unit id used to be interpolated raw, so a key holding `"` or `&` produced
- * an element no XML consumer can read — and the key can hold `"` legitimately,
- * since a single-quoted `id` may contain one.
+ * The unit id is interpolated into the `id` attribute, and a key can hold `"`
+ * legitimately, since a single-quoted `id` may contain one. Written raw, that or
+ * an `&` produces an element no XML consumer can read.
  */
 function escapeXmlAttr(value: string): string {
   return escapeXml(value).replace(/"/g, '&quot;');
@@ -547,7 +544,7 @@ export class XliffFormatParser implements FormatParser {
       // The KEY is checked as well as the translation: it is interpolated into
       // the `id` attribute, and XML 1.0 has no representation for a C0 byte in
       // any form — not even a numeric character reference — so a control byte in
-      // a source key produced a file no consumer reads and a live terminal
+      // a source key yields a file no consumer reads and a live terminal
       // sequence in `git diff`.
       assertNoControlChars(entry.key, entry.key);
       assertNoControlChars(entry.key, entry.translation);

From eeb21c44c3bd3bfcab9fa37fa92dbf2061856f09 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 22:42:43 +0200
Subject: [PATCH 231/256] refactor(comments): keep the sync invariants, drop
 the defect narration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comments-only, and the largest share of it: every guard in the sync engine
arrived with a paragraph about the failure it prevents, and most of those
paragraphs outlived their moment.

Kept, because the code cannot show them: why ENOENT alone means absent and a
two-step exists-then-read cannot; why a size comparison precedes a content
comparison; why the target read is capped when only the source used to be; why
staleness is judged per locale rather than from the whole lock entry; why a
backup is left on disk when a run did not finish, and why deleting it on age
alone would destroy the copy a recovery run needs; why the destination-trust
gate exempts no loopback address; why a glossary term is normalized the way the
TSV round trip normalizes it.

Two corrections rather than trims:

  * acquireSyncProcessLock's comment described an "O_EXCL create". The pidfile
    is staged at a private path and linked into place -- `fs.linkSync`, as the
    docblock 60 lines above it explains -- so the comment named a mechanism the
    code does not use.
  * a `// Fix SPEC-02:` marker is gone. A ticket reference belongs in the commit
    message.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/sync/sync-bak-cleanup.ts        |  24 +++++++++----------
 src/sync/sync-bucket-walker.ts      |   5 +---
 src/sync/sync-config.ts             |   8 +++----
 src/sync/sync-differ.ts             |   6 ++---
 src/sync/sync-foreign-owner.ts      |   7 ++----
 src/sync/sync-glossary-report.ts    | Bin 3150 -> 3146 bytes
 src/sync/sync-glossary.ts           |   4 ++--
 src/sync/sync-locale-translator.ts  |  36 ++++++++++------------------
 src/sync/sync-message-preprocess.ts |  10 ++++----
 src/sync/sync-process-bucket.ts     |   9 ++++---
 src/sync/sync-process-lock.ts       |   8 +++----
 src/sync/sync-service.ts            |  20 +++++++---------
 src/sync/sync-status.ts             |   8 +++----
 src/sync/sync-target-audit.ts       |  10 ++++----
 src/sync/sync-target-read.ts        |  13 +++++-----
 src/sync/sync-utils.ts              |   6 ++---
 src/sync/tms-client.ts              |  10 ++++----
 17 files changed, 77 insertions(+), 107 deletions(-)

diff --git a/src/sync/sync-bak-cleanup.ts b/src/sync/sync-bak-cleanup.ts
index 695da67e..ccb73a4e 100644
--- a/src/sync/sync-bak-cleanup.ts
+++ b/src/sync/sync-bak-cleanup.ts
@@ -25,10 +25,9 @@ let _warnedNoScope = false;
  * of each glob (i.e. everything before the first `*`, `?`, `{`, or `[`).
  *
  * A glob that starts with a wildcard has no literal prefix and contributes no
- * root. Falling back to `projectRoot` there defeated the scoping this function
- * exists to provide: `**\/en.json` handed the sweep the entire project tree,
- * walked recursively. The cost is that such a bucket gets no stale-backup
- * cleanup, which leaves inert `.deepl.bak` files on disk.
+ * root, because falling back to `projectRoot` there would hand the sweep the
+ * entire project tree to walk recursively. The cost is that such a bucket gets
+ * no stale-backup cleanup, which leaves inert `.deepl.bak` files on disk.
  */
 export function bucketSweepRoots(
   projectRoot: string,
@@ -77,19 +76,18 @@ export function bucketSweepRoots(
  * Age alone is not a safe test. A run that reaches its end unlinks its own
  * backups, so a backup still on disk is from a run that did not — and there it
  * holds the only surviving copy of whatever that run had already overwritten.
- * Deleting it on age made the natural recovery action (re-run `deepl sync`)
- * destroy the user's translations at exit 0 once the crash was more than
- * `bak_sweep_max_age_seconds` old, because the recovery run's
- * `COPYFILE_EXCL` guard has nothing left to collide with. A backup whose
+ * Deleting it on age alone would let the natural recovery action (re-run
+ * `deepl sync`) destroy those translations at exit 0, because the recovery
+ * run's `COPYFILE_EXCL` guard has nothing left to collide with. A backup whose
  * target holds the same bytes is the litter this sweep exists for; one whose
  * target does not is kept indefinitely and reported. Retention is bounded at
  * one file per target, since the backup name is derived from the target's.
  *
- * It used to restore a zero-length sibling from its backup first. Because
- * every target write goes through `atomicWriteFile`, which renames a
- * fully-written temp file into place, a crash cannot leave a zero-length
- * target — so that branch had no legitimate trigger, and a hostile checkout
- * could use it to write chosen bytes into any empty file within a sweep root.
+ * There is deliberately no step that restores a zero-length sibling from its
+ * backup: every target write goes through `atomicWriteFile`, which renames a
+ * fully-written temp file into place, so a crash cannot leave a zero-length
+ * target, and such a branch would let a hostile checkout write chosen bytes
+ * into any empty file within a sweep root.
  *
  * When `buckets` is provided the sweep is scoped to the directories implied by
  * each bucket's `include` globs instead of the entire project tree, keeping
diff --git a/src/sync/sync-bucket-walker.ts b/src/sync/sync-bucket-walker.ts
index 988e6fde..1e95ff6e 100644
--- a/src/sync/sync-bucket-walker.ts
+++ b/src/sync/sync-bucket-walker.ts
@@ -130,10 +130,7 @@ export interface WalkBucketsOptions {
  * key set, so the files delete each other's translations; `unwrittenKeys`
  * inspects only the string the current file produced, so the loser is still
  * recorded `translated`. Every later run re-translates, re-bills and re-loses the
- * same keys against a target that can never be complete — measured as a target
- * alternating between the two files' keys and two more texts billed per run, at
- * exit 0 throughout. `sync status` and `--frozen` report the incompleteness but
- * prescribe a cure that cannot succeed.
+ * same keys against a target that can never be complete.
  *
  * Checked against every configured locale, not just the ones a filtered run
  * would touch: the collision is a property of the configuration. A file whose
diff --git a/src/sync/sync-config.ts b/src/sync/sync-config.ts
index 4e3f566c..e798db92 100644
--- a/src/sync/sync-config.ts
+++ b/src/sync/sync-config.ts
@@ -174,11 +174,9 @@ const KNOWN_TMS_KEYS: readonly string[] = [
 
 /**
  * `tms:` fields the schema once accepted, and documented, without any code
- * reading them. Membership in `KNOWN_TMS_KEYS` was the whole reason they were
- * tolerated, so a review gate a user configured did nothing and said nothing.
- * They are rejected by name rather than as unknown fields, because "unknown"
- * reads as a typo and sends the reader looking for the correct spelling of
- * something that never existed.
+ * reading them. They are rejected by name rather than as unknown fields,
+ * because "unknown" reads as a typo and sends the reader looking for the
+ * correct spelling of something that never existed.
  */
 const RETIRED_TMS_KEYS: Readonly<Record<string, string>> = {
   auto_push:
diff --git a/src/sync/sync-differ.ts b/src/sync/sync-differ.ts
index d4af3fc3..36d8de92 100644
--- a/src/sync/sync-differ.ts
+++ b/src/sync/sync-differ.ts
@@ -51,9 +51,9 @@ export function computeDiff(
       computeSourceHash(entry.value, entry.metadata) === lockEntry.source_hash
     ) {
       // Scope the check to the configured target locales when they are known: a
-      // whole-entry `some(failed)` check would mark the key stale for EVERY
-      // locale as soon as one had failed, re-translating locales that are already
-      // fine and overwriting human-edited files.
+      // whole-entry `some(failed)` check marks the key stale for EVERY locale as
+      // soon as one has failed, re-translating locales that are already fine and
+      // overwriting human-edited files.
       const needsWork = targetLocales
         ? hasOutdatedLocale(lockEntry, lockEntry.source_hash, targetLocales)
         : Object.values(lockEntry.translations).some(
diff --git a/src/sync/sync-foreign-owner.ts b/src/sync/sync-foreign-owner.ts
index 0b795122..05d8f5f9 100644
--- a/src/sync/sync-foreign-owner.ts
+++ b/src/sync/sync-foreign-owner.ts
@@ -85,11 +85,8 @@ export async function findForeignKeyOwner(
 }
 
 /**
- * Why a target another configuration also writes was left alone.
- *
- * Phrased to follow the per-locale prefix its landing sites add, and to say what
- * the run did NOT do: the other configuration's translations are still on disk,
- * and nothing was recorded for this locale, so the next run retries it.
+ * Why a target another configuration also writes was left alone. Phrased to
+ * follow the per-locale prefix its landing sites add.
  */
 export function sharedTargetMessage(
   targetRelPath: string,
diff --git a/src/sync/sync-glossary-report.ts b/src/sync/sync-glossary-report.ts
index ca79f1e88666e925ef465a05f06ceaeb27b5d553..212a914c9680f0a7baab7d686c991359964069cc 100644
GIT binary patch
delta 55
zcmX>naY|xCGqaYJLS~6Vd46e5ib6(aN~%IpYGRH;N@iJVQF>}#a;idNUW!6yURi2h
K$>xpBb2$JuXB2n<

delta 59
zcmX>laZX}GGqaw;qlPI8rNx<f=?a-83K^Lx3Pq`jISMJ6WvNB!sd>q%3W<3s3YmFj
Psd*)-DVx_a&*cCBu(1}i

diff --git a/src/sync/sync-glossary.ts b/src/sync/sync-glossary.ts
index 1f2c17aa..e5380e4b 100644
--- a/src/sync/sync-glossary.ts
+++ b/src/sync/sync-glossary.ts
@@ -24,8 +24,8 @@ function isUnusableTerm(text: string): boolean {
 
 /**
  * Normalize the way the glossary TSV round trip does — the API returns entries
- * parsed back out of TSV, which trims each field. Comparing raw local terms
- * against that could never be equal, so every sync re-uploaded the dictionary.
+ * parsed back out of TSV, which trims each field. Raw local terms never compare
+ * equal to that, so every sync would re-upload the dictionary.
  */
 function normalizeForComparison(
   entries: Record<string, string>
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 5f25b7a5..3b801aac 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -125,11 +125,11 @@ function screenTranslations(
  * The keys `reconstruct` did not put into the content it returned.
  *
  * A run records a key as translated on the strength of the translation call, so
- * without this a parser that cannot place an entry — one added to the source
- * since the target file was written, and so with no slot in the template — lost
- * the string at exit 0, with the lockfile calling it translated and every gate
- * reading that as complete. Verifying the write is what keeps the lockfile a
- * record of the file rather than of the API call.
+ * the write itself has to be checked: a parser that cannot place an entry — one
+ * added to the source since the target file was written, and so with no slot in
+ * the template — drops it silently, and every gate reads the lockfile as
+ * complete. Verifying the write is what keeps the lockfile a record of the file
+ * rather than of the API call.
  *
  * Presence is the test, not equality: whether a written value round-trips
  * byte-for-byte is the escaping contract, checked per parser. A translation that
@@ -207,10 +207,9 @@ function withheldKeysWarning(
  * it is removed from the file. For a key the lockfile records, that is the
  * intended prune of a key the source no longer has. A key the lockfile has never
  * heard of was not put there by this tool — a translator added it by hand — so
- * deleting it is outside what the run was asked to do. The prune itself is left
- * alone; what was undefensible is that it happened with no mention in the run
- * output, `sync status` or `sync validate`, and with the backup unlinked on
- * success, so nothing was recoverable and nothing said anything was lost.
+ * deleting it is outside what the run was asked to do. The prune itself stands;
+ * this only names the keys, so a hand-added one is not lost without a word in
+ * the run output.
  */
 function droppedTargetOnlyKeys(
   existingTranslations: ReadonlyMap<string, string>,
@@ -261,10 +260,6 @@ export interface TranslateLocaleResult {
 }
 
 export class LocaleTranslator {
-  // tmCache remains instance-level on SyncService. The orchestrator resolves
-  // TM IDs before calling LocaleTranslator.translate and passes the resolved
-  // per-locale Map through the context; LocaleTranslator itself does not
-  // resolve TM IDs.
   constructor(
     private readonly translationService: TranslationService,
     private readonly backupPaths: Set<string>,
@@ -387,7 +382,6 @@ export class LocaleTranslator {
     const instructionGroupCounts = new Map<string, number>();
 
     if (forceBatch === true || localeDiffs.length <= 1) {
-      // --batch mode or single key: use existing batch behavior
       const contextForSingle =
         localeDiffs.length === 1
           ? (config.context?.overrides?.[localeDiffs[0]?.key ?? ''] ??
@@ -417,7 +411,6 @@ export class LocaleTranslator {
         });
       }
     } else {
-      // Three-way partitioning: context (per-key) vs. element instruction (batched) vs. plain batch
       const localeSupportsInstructions = supportsCustomInstructions(locale);
       const contextIndices: number[] = [];
       const instructionGroups = new Map<string, number[]>(); // elementType → indices
@@ -1014,11 +1007,9 @@ export class LocaleTranslator {
 
     // The same guarded read the pre-read pass uses, rather than a bare readFile
     // whose catch cannot tell an absent file from one that is on disk and could
-    // not be opened. A target that became unreadable in the window between the
-    // two was reclassified as absent: the template fell back to the SOURCE,
-    // no backup was taken because `targetExists` stayed false, and a
-    // source-derived file was written over the very target the run had just
-    // failed to read. `deepl sync pull` gets this right with one guarded read.
+    // not be opened. A target misread as absent takes its template from the
+    // SOURCE and leaves `targetExists` false, so no backup is taken and a
+    // source-derived file goes over the very target the run just failed to read.
     //
     // Thrown rather than warned, matching how the pre-read treats the same
     // condition: processBucket catches it per locale, records the locale failed
@@ -1055,9 +1046,8 @@ export class LocaleTranslator {
         // COPYFILE_EXCL, because a backup already on disk is not ours to
         // replace. The guard above is per-process, so after a crash — where the
         // lockfile was never written and the backup holds the only surviving
-        // copy of the user's file — the natural recovery action of re-running
-        // sync used to overwrite that copy with machine output and then unlink
-        // it on success, destroying the data at exit 0.
+        // copy of the user's file — re-running sync must not overwrite that copy
+        // with machine output and then unlink it on success.
         await fs.promises.copyFile(
           targetAbsPath,
           bakPath,
diff --git a/src/sync/sync-message-preprocess.ts b/src/sync/sync-message-preprocess.ts
index 8580d1d5..9e1db7e4 100644
--- a/src/sync/sync-message-preprocess.ts
+++ b/src/sync/sync-message-preprocess.ts
@@ -50,8 +50,8 @@ export function expandPlurals(
       Array<{ quantity: string; value: string }> | undefined;
     if (androidPlurals) {
       // Reference identity against the primary form, not value equality: with
-      // coinciding source forms a value test skipped every matching form, so
-      // only one of them was ever translated.
+      // coinciding source forms a value test skips every matching form, so only
+      // one of them gets translated.
       const primary = primaryPluralItem(androidPlurals);
       for (const p of androidPlurals) {
         if (p === primary) continue;
@@ -96,8 +96,8 @@ export function detectIcu(extendedTexts: string[]): {
     if (icuResult.isIcu && icuResult.segments.length > 0) {
       icuMappings.push({ textIndex: ti, icuResult });
       // ICU strings skip the main batch and get translated segment-by-segment,
-      // so the slot holds nothing to translate. A marker token here was itself
-      // submitted as a text, billed, and cached under its own key.
+      // so the slot holds nothing to translate. A marker token here would itself
+      // be submitted as a text, billed, and cached under its own key.
       // `reassembleIcu` overwrites every mapped index, so the blank never
       // reaches a target file.
       out[ti] = '';
@@ -137,7 +137,7 @@ export async function reassembleIcu(
     // one would emit a part-source message reported as successfully translated,
     // so leave the result unset — the message is marked failed and retried.
     // An empty branch (`one {}`) translates to an empty string, which is a
-    // result: treating it as a failure lost the whole message permanently.
+    // result: treating it as a failure would lose the whole message permanently.
     const anySegmentFailed =
       segResults.length !== segTexts.length ||
       segResults.some((sr) => typeof sr?.text !== 'string');
diff --git a/src/sync/sync-process-bucket.ts b/src/sync/sync-process-bucket.ts
index 0440c87e..9e069899 100644
--- a/src/sync/sync-process-bucket.ts
+++ b/src/sync/sync-process-bucket.ts
@@ -117,7 +117,7 @@ export async function processBucket(
    *
    * Staleness is judged against these rather than against every configured
    * locale: a key that failed for es is not stale for de, so `sync --locale de`
-   * used to re-translate, re-bill and overwrite de's reviewed keys because of a
+   * must not re-translate, re-bill and overwrite de's reviewed keys because of a
    * locale the run was not even asked to look at.
    */
   const effectiveLocales = options?.localeFilter?.length
@@ -171,9 +171,9 @@ export async function processBucket(
    *
    * Computed lazily, and only where a decision would otherwise be made on the
    * lockfile alone: `--frozen`, whose whole purpose is catching a locale that is
-   * not up to date, and the early return below, which used to leave a damaged
-   * target unrepaired for as long as no other key needed work. A run that has
-   * translating to do reads every target file a few lines further down anyway.
+   * not up to date, and the early return below, which would otherwise leave a
+   * damaged target unrepaired for as long as no other key needed work. A run
+   * that has translating to do reads every target file a few lines below anyway.
    */
   let gapsCache: TargetGaps | undefined;
   const targetGaps = async (): Promise<TargetGaps> => {
@@ -283,7 +283,6 @@ export async function processBucket(
     out.estimatedCharactersDelta += chars;
 
     if (hasNewLocale) {
-      // Count current keys needing translation for new locales
       out.newKeysDelta += diffs.filter((d) => d.status === 'current').length;
     }
 
diff --git a/src/sync/sync-process-lock.ts b/src/sync/sync-process-lock.ts
index 6742d0f3..0c8a0b74 100644
--- a/src/sync/sync-process-lock.ts
+++ b/src/sync/sync-process-lock.ts
@@ -231,10 +231,10 @@ export function acquireSyncProcessLock(
 ): ProcessLockHandle {
   const pidFilePath = path.join(projectRoot, PROCESS_LOCK_FILE_NAME);
 
-  // Every acquisition goes through the same O_EXCL create, including the one
-  // after a stale file is cleared: taking the lock is the only step that may
-  // decide the winner, so a create that loses reports another running sync
-  // rather than crashing with a raw EEXIST.
+  // Every acquisition goes through the same exclusive link(2) create, including
+  // the one after a stale file is cleared: taking the lock is the only step
+  // that may decide the winner, so a create that loses reports another running
+  // sync rather than crashing with a raw EEXIST.
   for (let attempt = 1; ; attempt++) {
     try {
       writePidFile(pidFilePath);
diff --git a/src/sync/sync-service.ts b/src/sync/sync-service.ts
index 904b0c14..da0c7b61 100644
--- a/src/sync/sync-service.ts
+++ b/src/sync/sync-service.ts
@@ -157,12 +157,9 @@ export class SyncService {
      * Undo the writes this run has already made. Reached only from the signal
      * path, where the run is abandoned partway through: the lockfile is written
      * once at the end, so an interrupted run records nothing, and the targets it
-     * has rewritten hold machine output that nothing accounts for.
-     *
-     * This used to unlink the backups instead, which is right for a run that
-     * finished and wrong for one that did not — it deleted the only remaining
-     * copy of content the run had already overwritten, at which point the user's
-     * translations were gone with no record and no recovery path.
+     * has rewritten hold machine output that nothing accounts for. Unlinking the
+     * backups here instead — right for a run that finished — would delete the
+     * only remaining copy of content this run has already overwritten.
      *
      * Synchronous on purpose: `installSignalExit` defers the exit by one
      * `setImmediate`, so only work done synchronously in a handler is guaranteed
@@ -314,11 +311,11 @@ export class SyncService {
       );
     }
 
-    // Per-locale overrides are resolved here rather than inside the bucket loop,
-    // which repeated the work for every file: an override that does not cover its
-    // own locale has to fail before anything is translated, not after earlier
-    // files have already been written. `auto` names no glossary to resolve — it
-    // is managed by the auto-glossary pass after translation.
+    // Per-locale overrides are resolved once here rather than inside the bucket
+    // loop: an override that does not cover its own locale has to fail before
+    // anything is translated, not after earlier files have already been written.
+    // `auto` names no glossary to resolve — it is managed by the auto-glossary
+    // pass after translation.
     const localeGlossaryIds = new Map<string, string>();
     const localeTmIds = new Map<string, string>();
     for (const locale of effectiveLocales) {
@@ -480,7 +477,6 @@ export class SyncService {
       if (contribution.lockDirty) lockDirty = true;
     }
 
-    // Fix SPEC-02: Wire auto-glossary sync
     if (
       config.translation?.glossary === 'auto' &&
       !options?.dryRun &&
diff --git a/src/sync/sync-status.ts b/src/sync/sync-status.ts
index e67769e7..7e61bcab 100644
--- a/src/sync/sync-status.ts
+++ b/src/sync/sync-status.ts
@@ -102,8 +102,8 @@ export async function computeSyncStatus(
     const fileLockEntries = getOwnMember(lockFile.entries, relPath) ?? {};
     // Scoped to the configured locales, so staleness is judged per locale. With
     // no locales computeDiff falls back to a whole-entry "some locale failed"
-    // test, which reported a complete locale as outdated because a DIFFERENT
-    // locale had failed.
+    // test, which reports a complete locale as outdated when a DIFFERENT locale
+    // has failed.
     const diffs = computeDiff(fileLockEntries, entries, config.target_locales);
     // The lockfile alone cannot answer "is this locale complete": it records
     // what a run intended, not what its target file ended up holding.
@@ -141,9 +141,7 @@ export async function computeSyncStatus(
      * because one locale's own record lags behind.
      *
      * `stale` covers both, and only the first can speak for every locale: a key
-     * that failed for es is not outdated for de. Deciding from `diff.status`
-     * alone reported a complete locale as outdated because a different locale
-     * had failed.
+     * that failed for es is not outdated for de.
      */
     const sourceChangedKeys = new Set(
       diffs
diff --git a/src/sync/sync-target-audit.ts b/src/sync/sync-target-audit.ts
index 44f7576a..207a7f59 100644
--- a/src/sync/sync-target-audit.ts
+++ b/src/sync/sync-target-audit.ts
@@ -59,12 +59,10 @@ function claimedKeys(
 /**
  * Compare a target file against what the lockfile claims about it.
  *
- * Nothing used to: `sync status` and `sync --frozen` both diffed the source
- * file against `.deepl-sync.lock` and never opened the target, so a locale
- * whose file had lost translations the lockfile calls translated — by an
- * earlier version of this tool dropping them, a bad merge, a partial checkout,
- * a hand deletion — reported 100% complete at exit 0 indefinitely, and `sync`
- * itself returned early without repairing it.
+ * A source-to-lockfile diff cannot see this: a locale whose file has lost
+ * translations the lockfile calls translated — a bad merge, a partial checkout,
+ * a hand deletion — would report 100% complete at exit 0 indefinitely, and
+ * `sync` itself would return early without repairing it.
  *
  * A file that cannot be read or cannot be parsed yields every claimed key: a
  * file whose contents are unavailable cannot be shown to hold anything.
diff --git a/src/sync/sync-target-read.ts b/src/sync/sync-target-read.ts
index b1e0342b..8c996e23 100644
--- a/src/sync/sync-target-read.ts
+++ b/src/sync/sync-target-read.ts
@@ -42,16 +42,15 @@ export async function readTargetFile(
     }
     return { state: 'unusable', reason: describe(err), error: err };
   }
-  // `max_file_bytes` was enforced on SOURCE files only, so a target — the file a
-  // hostile or corrupt checkout actually controls — was parsed and rebuilt at any
-  // size. Reported as `unusable` rather than skipped, so the locale is refused
-  // instead of being treated as empty, re-translated in full and overwritten.
+  // `max_file_bytes` caps targets as well as source files: a target is the file a
+  // hostile or corrupt checkout actually controls. An oversized one is `unusable`
+  // rather than skipped, so the locale is refused instead of being treated as
+  // empty, re-translated in full and overwritten.
   //
   // Checked on the content rather than through a separate `stat`: the cap's
   // purpose is to bound the parse, the reconstruct and the comparison work that
-  // follow, which is where the cost was (a target with one long comment block
-  // took 47 seconds). Node's own string-length ceiling bounds the read itself,
-  // and it surfaces as a catchable error above.
+  // follow, which is where the cost is. Node's own string-length ceiling bounds
+  // the read itself, and it surfaces as a catchable error above.
   if (maxBytes !== undefined && Buffer.byteLength(content, 'utf8') > maxBytes) {
     return {
       state: 'unusable',
diff --git a/src/sync/sync-utils.ts b/src/sync/sync-utils.ts
index b764254b..acc203c9 100644
--- a/src/sync/sync-utils.ts
+++ b/src/sync/sync-utils.ts
@@ -29,9 +29,9 @@ const PLURAL_FORM_METADATA_KEYS = ['plural_forms', 'plurals'] as const;
  *
  * A gettext entry declares `msgid_plural` even when it has no `msgstr[N]` lines
  * yet — a freshly extracted catalog is exactly that shape, since `plural_forms`
- * only appears once forms exist. Judging plurality from the payload alone let
+ * only appears once forms exist. Judging plurality from the payload alone makes
  * `deepl sync pull` treat such an entry as ordinary: one exported string cannot
- * fill a plural entry's forms, so the pull recorded a translation it had not
+ * fill a plural entry's forms, so the pull records a translation it has not
  * applied.
  *
  * Kept separate from `PLURAL_FORM_METADATA_KEYS`, which lists the payloads to
@@ -206,7 +206,7 @@ function assertNotDashLeading(targetPath: string): string {
  * under a symlinked directory (the common macOS case where `/tmp` is a
  * symlink to `/private/tmp`) would reject paths the user typed in their
  * unresolved form. Symlink-based escapes (a symlink inside the project
- * pointing outside) are now also caught.
+ * pointing outside) are caught by the same resolution.
  *
  * The forbidden-segment check belongs on the resolved path rather than on
  * `target_path_pattern` alone: the default locale-substitution branch of
diff --git a/src/sync/tms-client.ts b/src/sync/tms-client.ts
index f0d62395..eca37b6b 100644
--- a/src/sync/tms-client.ts
+++ b/src/sync/tms-client.ts
@@ -23,11 +23,11 @@ const VALUE_CONTROL_CHARS = /[\x00-\x1f\x7f]/g;
  *
  * Those three are the set `isForbiddenControlChar` exempts — the C0 bytes every
  * format either escapes or legally emits — and a multi-line or tabbed
- * translation is ordinary human content, not a hostile payload. Deleting them
- * (rather than letting the per-format writer escape them) fused adjacent words
- * of an approved translation at exit 0. Everything else is still removed here,
- * because a raw ESC reaching a locale file renders as a live terminal command in
- * `git diff` and CI logs.
+ * translation is ordinary human content, not a hostile payload, so deleting
+ * them (rather than letting the per-format writer escape them) would fuse
+ * adjacent words of an approved translation. Everything else is still removed
+ * here, because a raw ESC reaching a locale file renders as a live terminal
+ * command in `git diff` and CI logs.
  */
 // eslint-disable-next-line no-control-regex -- intentional: strip format-breaking control chars from untrusted TMS-returned values before they reach the filesystem
 const VALUE_FORBIDDEN_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;

From 46a471f70dbd37fb60d36b6f11c6a35e976d27f0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 22:42:54 +0200
Subject: [PATCH 232/256] refactor(comments): cut step-by-step narration from
 the service layer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comments-only. The bulk of this is a long tail of comments that label the next
statement rather than explain it -- `// Validate input`, `// Upload document`,
`// Poll for completion`, `// Start watching`, `// Add the last field` -- which a
reader gets from the call itself.

What stays is the reasoning: why an empty source value is filled in without a
request and must not leave a null slot; why each deduplicated index gets its own
result copy; why the cacheData property order is fixed; why the cache key must
carry the resolved endpoint; why a debounce timer is dropped only while it is
still the current one; why at most one translation per path may be in flight.

Two comments were replaced by what they were gesturing at: the symlink note now
says `safeReadFile` rejects a symlinked input rather than "(with symlink
security check)", and the file-size note says the document is sized before the
read so an oversize one is never resident.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/services/batch-translation.ts    | 12 -----
 src/services/document-translation.ts | 18 +------
 src/services/file-translation.ts     | 16 +-----
 src/services/git-hooks.ts            |  7 ---
 src/services/glossary.ts             | 23 ++-------
 src/services/translation-memory.ts   | 14 +++---
 src/services/translation.ts          | 74 ++++++----------------------
 src/services/watch.ts                | 53 +++++++-------------
 src/services/write.ts                |  2 +-
 9 files changed, 49 insertions(+), 170 deletions(-)

diff --git a/src/services/batch-translation.ts b/src/services/batch-translation.ts
index ef3995d9..c6bb37fc 100644
--- a/src/services/batch-translation.ts
+++ b/src/services/batch-translation.ts
@@ -93,7 +93,6 @@ export class BatchTranslationService {
     this.fileTranslationService = fileTranslationService;
     this.translationService = options.translationService ?? null;
 
-    // Validate concurrency parameter
     const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
     if (concurrency < 1) {
       throw new ValidationError('Concurrency must be at least 1');
@@ -130,7 +129,6 @@ export class BatchTranslationService {
       return result;
     }
 
-    // Partition files into plain text (batchable) vs others (per-file)
     const plainTextFiles: string[] = [];
     const perFileFiles: string[] = [];
 
@@ -147,7 +145,6 @@ export class BatchTranslationService {
     const totalFiles = files.length;
     let completed = result.skipped.length;
 
-    // Report progress for skipped files
     for (const entry of result.skipped) {
       batchOptions.onProgress?.({
         completed,
@@ -156,7 +153,6 @@ export class BatchTranslationService {
       });
     }
 
-    // Batch-translate plain text files
     if (plainTextFiles.length > 0) {
       const batchResult = await this.translatePlainTextFilesBatched(
         plainTextFiles,
@@ -176,7 +172,6 @@ export class BatchTranslationService {
         batchResult.skipped.length;
     }
 
-    // Per-file translation for structured/other files
     if (perFileFiles.length > 0) {
       const limit = pLimit(this.concurrency);
       // Same reasoning as the batched path: an unsupported target_lang is a
@@ -334,7 +329,6 @@ export class BatchTranslationService {
         );
 
         if (results.length !== batch.length) {
-          // Result count mismatch — mark entire batch as failed
           for (const entry of batch) {
             failed.push({
               file: entry.file,
@@ -463,7 +457,6 @@ export class BatchTranslationService {
     translationOptions: TranslationOptions,
     batchOptions: Partial<BatchOptions> = {}
   ): Promise<BatchResult> {
-    // Check if directory exists
     if (!fs.existsSync(inputDir)) {
       throw new ValidationError(`Directory not found: ${inputDir}`);
     }
@@ -473,7 +466,6 @@ export class BatchTranslationService {
       throw new ValidationError(`Not a directory: ${inputDir}`);
     }
 
-    // Build glob pattern
     const pattern = batchOptions.pattern ?? '*';
     const depth = batchOptions.recursive === false ? 1 : undefined;
     const globPattern =
@@ -481,7 +473,6 @@ export class BatchTranslationService {
         ? path.join(inputDir, pattern)
         : path.join(inputDir, '**', pattern);
 
-    // Find all files
     const files = await fg(globPattern, {
       onlyFiles: true,
       absolute: true,
@@ -490,12 +481,10 @@ export class BatchTranslationService {
       followSymbolicLinks: false,
     });
 
-    // Filter to only supported files
     const supportedFiles = files.filter((file) =>
       this.fileTranslationService.isSupportedFile(file)
     );
 
-    // Translate files with preserved directory structure
     return this.translateFiles(supportedFiles, translationOptions, {
       ...batchOptions,
       outputDir: batchOptions.outputDir ?? inputDir,
@@ -528,7 +517,6 @@ export class BatchTranslationService {
     const ext = path.extname(inputPath);
     const basename = path.basename(inputPath, ext);
 
-    // Apply custom pattern if provided
     if (options.outputPattern) {
       const outputFilename = options.outputPattern
         .replace('{name}', basename)
diff --git a/src/services/document-translation.ts b/src/services/document-translation.ts
index 899a678b..c2122e0a 100644
--- a/src/services/document-translation.ts
+++ b/src/services/document-translation.ts
@@ -81,7 +81,6 @@ export class DocumentTranslationService {
     progressCallback?: ProgressCallback,
     serviceOptions?: TranslateDocumentOptions
   ): Promise<DocumentTranslationResult> {
-    // Validate document minification is only used with PPTX/DOCX
     if (options.enableDocumentMinification) {
       const ext = path.extname(inputPath).toLowerCase();
       if (ext !== '.pptx' && ext !== '.docx') {
@@ -91,7 +90,7 @@ export class DocumentTranslationService {
       }
     }
 
-    // Validate file size before reading into memory (eliminates TOCTOU race)
+    // Sized before the read, so an oversize document is never resident.
     let fileStat: fs.Stats;
     try {
       fileStat = await fs.promises.stat(inputPath);
@@ -112,38 +111,32 @@ export class DocumentTranslationService {
       );
     }
 
-    // Read input file (with symlink security check)
+    // safeReadFile rejects a symlinked input rather than following it.
     const fileBuffer = await safeReadFile(inputPath);
     const filename = path.basename(inputPath);
 
-    // Upload document
     const handle = await this.client.uploadDocument(fileBuffer, {
       ...options,
       filename,
     });
 
-    // Poll for completion
     const finalStatus = await this.pollDocumentStatus(
       handle,
       progressCallback,
       serviceOptions?.abortSignal
     );
 
-    // Check for errors
     if (finalStatus.status === 'error') {
       throw new NetworkError(
         `Document translation failed: ${finalStatus.errorMessage ?? 'Unknown error'}`
       );
     }
 
-    // Download translated document
     const translatedBuffer = await this.client.downloadDocument(handle);
 
-    // Create output directory if needed
     const outputDir = path.dirname(outputPath);
     await fs.promises.mkdir(outputDir, { recursive: true });
 
-    // Write translated document to output path
     await atomicWriteFile(outputPath, translatedBuffer);
 
     return {
@@ -171,7 +164,6 @@ export class DocumentTranslationService {
     while (attempts < this.MAX_POLL_ATTEMPTS) {
       attempts++;
 
-      // Check if total timeout exceeded
       const elapsed = Date.now() - startTime;
       if (elapsed > this.TOTAL_TIMEOUT_MS) {
         throw new ValidationError(
@@ -179,14 +171,12 @@ export class DocumentTranslationService {
         );
       }
 
-      // Check if operation was cancelled
       if (abortSignal?.aborted) {
         throw new ValidationError('Document translation cancelled');
       }
 
       status = await this.client.getDocumentStatus(handle);
 
-      // Call progress callback if provided
       if (progressCallback) {
         progressCallback({
           status: status.status,
@@ -196,7 +186,6 @@ export class DocumentTranslationService {
         });
       }
 
-      // Check if translation is complete
       if (status.status === 'done' || status.status === 'error') {
         return status;
       }
@@ -213,7 +202,6 @@ export class DocumentTranslationService {
       );
     }
 
-    // Exceeded maximum attempts
     const totalMinutes = Math.round((Date.now() - startTime) / 1000 / 60);
     throw new ValidationError(
       `Document translation timed out after ~${totalMinutes} minutes. The document may still be processing on DeepL servers.`
@@ -241,7 +229,6 @@ export class DocumentTranslationService {
    */
   private sleep(ms: number, abortSignal?: AbortSignal): Promise<void> {
     return new Promise((resolve, reject) => {
-      // Check if already aborted
       if (abortSignal?.aborted) {
         reject(new ValidationError('Document translation cancelled'));
         return;
@@ -257,7 +244,6 @@ export class DocumentTranslationService {
         resolve();
       }, ms);
 
-      // Listen for abort event
       const abortHandler = () => {
         if (!isSettled) {
           isSettled = true;
diff --git a/src/services/file-translation.ts b/src/services/file-translation.ts
index f798b7c6..153cb499 100644
--- a/src/services/file-translation.ts
+++ b/src/services/file-translation.ts
@@ -64,7 +64,6 @@ export class FileTranslationService {
     options: TranslationOptions,
     fileOptions: FileTranslationOptions = {}
   ): Promise<void> {
-    // Check file type is supported
     if (!this.isSupportedFile(inputPath)) {
       throw new ValidationError(
         `Unsupported file type: ${path.extname(inputPath)}`,
@@ -72,13 +71,12 @@ export class FileTranslationService {
       );
     }
 
-    // Delegate structured files (JSON/YAML) to StructuredFileTranslationService
     if (this.isStructuredExt(inputPath)) {
       const svc = await this.getStructuredService();
       return svc.translateFile(inputPath, outputPath, options, fileOptions);
     }
 
-    // Read file content using safeReadFile (rejects symlinks for security)
+    // safeReadFile rejects a symlinked input rather than following it.
     let content: string;
     try {
       content = await safeReadFile(inputPath, 'utf-8');
@@ -90,12 +88,10 @@ export class FileTranslationService {
       throw err;
     }
 
-    // Check for empty files
     if (!content || content.trim() === '') {
       throw new ValidationError('Cannot translate empty file');
     }
 
-    // Translate content
     const result = await this.translationService.translate(
       content,
       options,
@@ -108,11 +104,9 @@ export class FileTranslationService {
       return;
     }
 
-    // Create output directory if needed
     const outputDir = path.dirname(outputPath);
     await fs.promises.mkdir(outputDir, { recursive: true });
 
-    // Write translated content
     await atomicWriteFile(outputPath, result.text, 'utf-8');
   }
 
@@ -132,7 +126,6 @@ export class FileTranslationService {
       );
     }
 
-    // Delegate structured files (JSON/YAML) to StructuredFileTranslationService
     if (this.isStructuredExt(inputPath)) {
       const svc = await this.getStructuredService();
       return svc.translateFileToMultiple(
@@ -143,7 +136,7 @@ export class FileTranslationService {
       );
     }
 
-    // Read file content using safeReadFile (rejects symlinks for security)
+    // safeReadFile rejects a symlinked input rather than following it.
     let content: string;
     try {
       content = await safeReadFile(inputPath, 'utf-8');
@@ -159,20 +152,17 @@ export class FileTranslationService {
       throw new ValidationError('Cannot translate empty file');
     }
 
-    // Translate to multiple languages
     const translationResults =
       await this.translationService.translateToMultiple(content, targetLangs, {
         ...options,
         skipCache: fileOptions.skipCache,
       });
 
-    // Convert to FileMultiTargetResult
     const results: FileMultiTargetResult[] = translationResults.map((r) => ({
       targetLang: r.targetLang,
       text: r.text,
     }));
 
-    // If outputDir is specified, write files
     if (options.outputDir) {
       const outputDir = options.outputDir;
       await fs.promises.mkdir(outputDir, { recursive: true });
@@ -217,9 +207,7 @@ export class FileTranslationService {
       return true;
     }
 
-    // For existing files, perform security checks
     try {
-      // Resolve symlinks to get real path
       const realPath = fs.realpathSync(filePath);
       const realExt = path.extname(realPath).toLowerCase();
 
diff --git a/src/services/git-hooks.ts b/src/services/git-hooks.ts
index a99e6f30..58fc6577 100644
--- a/src/services/git-hooks.ts
+++ b/src/services/git-hooks.ts
@@ -198,12 +198,10 @@ export class GitHooksService {
     const hookPath = this.getHookPath(hookType);
     const hookContent = this.generateHookContent(hookType);
 
-    // Create hooks directory if it doesn't exist
     if (!fs.existsSync(this.hooksDir)) {
       fs.mkdirSync(this.hooksDir, { recursive: true });
     }
 
-    // Backup existing hook if it exists and is not a DeepL hook
     let backupPath: string | null = null;
     if (fs.existsSync(hookPath)) {
       const existingContent = fs.readFileSync(hookPath, 'utf-8');
@@ -213,10 +211,8 @@ export class GitHooksService {
       }
     }
 
-    // Write the hook file
     fs.writeFileSync(hookPath, hookContent, 'utf-8');
 
-    // Make it executable
     fs.chmodSync(hookPath, 0o755);
 
     return { hookPath, backupPath };
@@ -255,7 +251,6 @@ export class GitHooksService {
       return;
     }
 
-    // Verify it's a DeepL hook before removing
     const content = fs.readFileSync(hookPath, 'utf-8');
     if (!this.isDeepLHook(content)) {
       throw new ValidationError(
@@ -265,7 +260,6 @@ export class GitHooksService {
 
     fs.unlinkSync(hookPath);
 
-    // Restore backup if it exists
     const backupPath = hookPath + '.backup';
     if (fs.existsSync(backupPath)) {
       fs.copyFileSync(backupPath, hookPath);
@@ -342,7 +336,6 @@ export class GitHooksService {
     // which never equals path.parse().root and loops forever.
     let currentPath = path.resolve(startPath ?? process.cwd());
 
-    // Traverse up the directory tree
     while (currentPath !== path.parse(currentPath).root) {
       const gitPath = path.join(currentPath, '.git');
       if (fs.existsSync(gitPath)) {
diff --git a/src/services/glossary.ts b/src/services/glossary.ts
index 528af06d..0f716140 100644
--- a/src/services/glossary.ts
+++ b/src/services/glossary.ts
@@ -90,7 +90,6 @@ export class GlossaryService {
     targetLangs: Language[],
     entries: Record<string, string>
   ): Promise<GlossaryInfo> {
-    // Validate inputs
     if (!name || name.trim() === '') {
       throw new ValidationError('Glossary name is required');
     }
@@ -103,10 +102,8 @@ export class GlossaryService {
       throw new ValidationError('Glossary entries cannot be empty');
     }
 
-    // Convert entries to TSV format
     const tsv = GlossaryService.entriesToTSV(entries);
 
-    // Create glossary via API
     const result = await this.client.createGlossary(
       name,
       sourceLang,
@@ -515,24 +512,20 @@ export class GlossaryService {
     sourceLang: Language,
     targetLang: Language
   ): Promise<void> {
-    // Get glossary info to validate it's multilingual
     const glossary = await this.client.getGlossary(glossaryId);
 
-    // Check if glossary has multiple dictionaries
     if (!isMultilingual(glossary)) {
       throw new ValidationError(
         'Cannot delete dictionary from single-language glossary. Delete the entire glossary instead.'
       );
     }
 
-    // Check if this would be the last dictionary
     if (glossary.dictionaries.length === 1) {
       throw new ValidationError(
         'Cannot delete last dictionary from glossary. Delete the entire glossary instead.'
       );
     }
 
-    // Validate the dictionary exists
     const dictionaryExists = glossary.dictionaries.some(
       (dict) =>
         dict.source_lang.toUpperCase() === sourceLang.toUpperCase() &&
@@ -545,7 +538,6 @@ export class GlossaryService {
       );
     }
 
-    // Delete the dictionary using v3 DELETE endpoint
     await this.client.deleteGlossaryDictionary(
       glossaryId,
       sourceLang,
@@ -594,7 +586,6 @@ export class GlossaryService {
       lineNumber++;
       const trimmed = line.trim();
 
-      // Skip empty lines
       if (!trimmed) {
         continue;
       }
@@ -604,17 +595,14 @@ export class GlossaryService {
       if (isTabSeparated) {
         parts = trimmed.split('\t');
       } else if (trimmed.includes(',')) {
-        // Use proper CSV parsing for comma-separated values (handles quoted fields)
         parts = GlossaryService.parseCsvLine(trimmed);
       } else {
-        // Line has no separator - skip it
         Logger.warn(
           `Line ${lineNumber}: No tab or comma separator found, skipping`
         );
         continue;
       }
 
-      // Validate we have at least 2 columns
       if (parts.length < 2) {
         Logger.warn(
           `Line ${lineNumber}: Expected 2 columns, found ${parts.length}, skipping`
@@ -622,7 +610,7 @@ export class GlossaryService {
         continue;
       }
 
-      // Warn if more than 2 columns (extra data will be ignored)
+      // Columns past the second are ignored.
       if (parts.length > 2) {
         Logger.warn(
           `Line ${lineNumber}: Found ${parts.length} columns, expected 2. Using first 2 columns.`
@@ -632,7 +620,6 @@ export class GlossaryService {
       const source = parts[0]?.trim();
       const target = parts[1]?.trim();
 
-      // Validate both source and target are non-empty
       if (!source || !target) {
         Logger.warn(`Line ${lineNumber}: Empty source or target, skipping`);
         continue;
@@ -648,7 +635,7 @@ export class GlossaryService {
         continue;
       }
 
-      // Add to entries (duplicates will overwrite earlier entries)
+      // A repeated source term overwrites the earlier entry.
       if (Object.hasOwn(entries, source)) {
         Logger.warn(
           `Line ${lineNumber}: Duplicate source "${source}", overwriting previous entry`
@@ -673,27 +660,23 @@ export class GlossaryService {
 
       if (char === '"') {
         if (inQuotes && nextChar === '"') {
-          // Escaped quote (two consecutive quotes = one quote character)
+          // Two consecutive quotes inside a quoted field are one quote.
           currentField += '"';
           i += 2;
         } else {
-          // Toggle quote state (entering or leaving quoted field)
           inQuotes = !inQuotes;
           i++;
         }
       } else if (char === ',' && !inQuotes) {
-        // Field separator (only when not inside quotes)
         fields.push(currentField);
         currentField = '';
         i++;
       } else {
-        // Regular character
         currentField += char;
         i++;
       }
     }
 
-    // Add the last field
     fields.push(currentField);
 
     return fields;
diff --git a/src/services/translation-memory.ts b/src/services/translation-memory.ts
index 409de988..b30bbc9e 100644
--- a/src/services/translation-memory.ts
+++ b/src/services/translation-memory.ts
@@ -15,19 +15,17 @@ export function sanitizeForError(input: string): string {
   return input.replace(/[\x00-\x1f\x7f]/g, '').slice(0, 80);
 }
 
-// Filter API-returned TM entries whose name contains suspicious codepoints
-// (ASCII control chars or zero-width chars) before name matching. Defense-
-// in-depth against server-side name pollution where an attacker-controlled
-// entry would otherwise participate in the find() candidate pool. Silent
-// skip — real TMs created via the DeepL dashboard cannot contain these.
+// Keeps an API-returned TM whose name carries ASCII control or zero-width
+// characters out of the name-matching candidate pool. Skipped in silence,
+// because a TM created through the DeepL dashboard cannot contain these.
 function hasSuspiciousChars(name: string): boolean {
   // eslint-disable-next-line no-control-regex -- intentional: checking for control chars in untrusted API-returned strings
   return /[\x00-\x1f\x7f\u200B-\u200D\uFEFF]/.test(name);
 }
 
-// Takes the expected pair ({from, targets}) and returns only the ID, so
-// language-pair validation is centralized here and text + file handlers
-// cannot drift. The UUID path trusts the caller and skips the check.
+// Language-pair validation lives here rather than in the callers, so the text
+// and file handlers cannot drift. The UUID path trusts the caller and skips the
+// check.
 export async function resolveTranslationMemoryId(
   client: TranslationMemoryLister,
   nameOrId: string,
diff --git a/src/services/translation.ts b/src/services/translation.ts
index 1a24d959..dcc5a692 100644
--- a/src/services/translation.ts
+++ b/src/services/translation.ts
@@ -92,7 +92,7 @@ export class TranslationService {
   /**
    * The cache state is a property of the run, not of one request, so repeat it
    * no more than once. A file of more than `TRANSLATE_BATCH_SIZE` strings needs
-   * several requests, and one notice per request buried the output.
+   * several requests, and one notice per request would bury the output.
    */
   private announceCacheMode(cacheEnabled: boolean, skipCache: boolean): void {
     const notice = !cacheEnabled
@@ -114,7 +114,6 @@ export class TranslationService {
     options: TranslationOptions,
     serviceOptions: TranslateServiceOptions = {}
   ): Promise<TranslationResult> {
-    // Validate inputs
     if (!text || text.trim() === '') {
       throw new ValidationError('Text cannot be empty');
     }
@@ -131,11 +130,9 @@ export class TranslationService {
       );
     }
 
-    // Get defaults from config
     const configData = this.config.get();
     const defaults = configData.defaults;
 
-    // Merge options with defaults
     const translationOptions: TranslationOptions = {
       ...options,
       sourceLang: options.sourceLang ?? defaults.sourceLang,
@@ -144,7 +141,6 @@ export class TranslationService {
         options.preserveFormatting ?? defaults.preserveFormatting,
     };
 
-    // Preserve code blocks if requested
     let processedText = text;
     const preservationMap: Map<string, string> = new Map();
 
@@ -152,10 +148,8 @@ export class TranslationService {
       processedText = preserveCodeBlocks(text, preservationMap);
     }
 
-    // Always preserve variables
     processedText = preserveVariables(processedText, preservationMap);
 
-    // Check cache (only if cache is enabled AND skipCache is not set)
     const cacheEnabled = this.config.getValue<boolean>('cache.enabled') ?? true;
     const shouldUseCache = cacheEnabled && !serviceOptions.skipCache;
 
@@ -177,7 +171,6 @@ export class TranslationService {
       Logger.verbose('[verbose] Cache miss');
     }
 
-    // Translate via API
     const startTime = Date.now();
     const result = await this.client.translate(
       processedText,
@@ -190,7 +183,6 @@ export class TranslationService {
     // not become a cache entry that reproduces the same output offline.
     assertPlaceholdersSurvived(result.text, preservationMap);
 
-    // Store in cache
     if (shouldUseCache) {
       this.cache?.set(cacheKey, result);
     }
@@ -210,9 +202,8 @@ export class TranslationService {
    * @param texts - Array of texts to translate
    * @param options - Translation options
    * @param serviceOptions - `skipCache` bypasses both the cache read and the
-   *   cache write, matching `translate()`. Without it, `--no-cache` was a
-   *   silent no-op for every structured i18n format, so a corrupt translation
-   *   could not be re-fetched and the natural remedy did nothing.
+   *   cache write, matching `translate()`. Every structured i18n format goes
+   *   through this path, so it is what makes `--no-cache` reach them.
    * @returns One slot per input text, in input order. A slot is `null` when the
    *   request carrying that text failed; the surviving batches are still
    *   returned so callers that track failure per item can retry only those.
@@ -242,7 +233,6 @@ export class TranslationService {
       }
     }
 
-    // Get config defaults
     const configData = this.config.get();
     const defaults = configData.defaults;
     const cacheEnabled = this.config.getValue<boolean>('cache.enabled') ?? true;
@@ -250,7 +240,6 @@ export class TranslationService {
 
     this.announceCacheMode(cacheEnabled, serviceOptions.skipCache === true);
 
-    // Merge options with defaults
     const translationOptions: TranslationOptions = {
       ...options,
       sourceLang: options.sourceLang ?? defaults.sourceLang,
@@ -259,8 +248,6 @@ export class TranslationService {
         options.preserveFormatting ?? defaults.preserveFormatting,
     };
 
-    // Check cache and separate cached vs non-cached texts
-    // Use Set for deduplication and Map to track all indices for each text
     const textsToTranslateSet = new Set<string>();
     const textIndexMap = new Map<string, number[]>(); // Maps text to ALL original indices
     const results: (TranslationResult | null)[] =
@@ -269,10 +256,9 @@ export class TranslationService {
     for (let i = 0; i < texts.length; i++) {
       const text = texts[i];
       if (!text) {
-        // An empty source value has an empty translation. Sending it would be
-        // billed for nothing, and leaving the slot null made a text that was
-        // never sent indistinguishable from a request that failed — which
-        // crashed file translation and cost sync the key outright.
+        // An empty source value has an empty translation, filled in without a
+        // request: sending it is billed for nothing, and a null slot would be
+        // indistinguishable from a request that failed.
         results[i] = { text: '', billedCharacters: 0 };
         continue;
       }
@@ -287,35 +273,26 @@ export class TranslationService {
         }
       }
 
-      // Not cached, need to translate
-      // Track this text for translation (deduplicated via Set)
       textsToTranslateSet.add(text);
 
-      // Track ALL indices for this text (handles duplicates)
       if (!textIndexMap.has(text)) {
         textIndexMap.set(text, []);
       }
       textIndexMap.get(text)!.push(i);
     }
 
-    // Convert Set to Array for batch translation
     const textsToTranslate = Array.from(textsToTranslateSet);
 
-    // If all texts were cached, return results preserving positional correspondence
     if (textsToTranslate.length === 0) {
       return results;
     }
 
-    // Use batch API to translate all non-cached texts in a single request
-    // DeepL API supports up to TRANSLATE_BATCH_SIZE texts per request, so chunk if needed
     const BATCH_SIZE = TRANSLATE_BATCH_SIZE;
     const batches: string[][] = [];
     for (let i = 0; i < textsToTranslate.length; i += BATCH_SIZE) {
       batches.push(textsToTranslate.slice(i, i + BATCH_SIZE));
     }
 
-    // Process all batches and track failures
-    // Use a Map to correctly track which text maps to which result
     const textToResultMap = new Map<string, TranslationResult>();
     let lastError: Error | null = null;
 
@@ -326,7 +303,6 @@ export class TranslationService {
           translationOptions
         );
 
-        // Map each result to its corresponding text
         for (let i = 0; i < batch.length; i++) {
           const text = batch[i];
           const result = batchResults[i];
@@ -337,38 +313,31 @@ export class TranslationService {
       } catch (error) {
         lastError = error as Error;
         Logger.error(`Batch translation failed: ${errorMessage(error)}`);
-        // Mark all texts in this batch as processed (but failed)
-        // Continue with other batches rather than failing completely
+        // The other batches still run; only a run where every batch failed
+        // rejects.
       }
     }
 
-    // If all batches failed, throw the last error
     if (textToResultMap.size === 0 && lastError) {
       throw lastError;
     }
 
-    // Store results in cache and map back to ALL original indices
     for (const text of textsToTranslate) {
       const result = textToResultMap.get(text);
 
       if (!result) {
-        // Translation failed for this text
         continue;
       }
 
       const originalIndices = textIndexMap.get(text);
       if (originalIndices) {
-        // Assign result to ALL indices where this text appeared (handles
-        // duplicates). Each index gets its own copy: the returned array is
-        // typed as one result per index, and a caller editing results[i] in
-        // place was silently editing every other index whose text deduplicated
-        // to the same request item — which wrote one key's placeholder into
-        // another key's translation.
+        // Each of the indices this text deduplicated to gets its own copy: the
+        // returned array is typed as one result per index, so a caller editing
+        // results[i] in place must not reach any other index.
         for (const index of originalIndices) {
           results[index] = { ...result };
         }
 
-        // Cache the result (only once per unique text)
         if (shouldUseCache) {
           const cacheKey = this.generateCacheKey(text, translationOptions);
           this.cache?.set(cacheKey, result);
@@ -376,7 +345,6 @@ export class TranslationService {
       }
     }
 
-    // Calculate actual failures
     const actualFailures = results.filter((r) => r === null).length;
     if (actualFailures > 0) {
       Logger.warn(
@@ -451,19 +419,15 @@ export class TranslationService {
   async getSupportedLanguages(
     type: 'source' | 'target'
   ): Promise<LanguageInfo[]> {
-    // Check cache first
     const cached = this.languageCache.get(type);
     const now = Date.now();
 
-    // Return cached data if it exists and hasn't expired
     if (cached && now - cached.timestamp < this.LANGUAGE_CACHE_TTL) {
       return cached.data;
     }
 
-    // Fetch from API
     const languages = await this.client.getSupportedLanguages(type);
 
-    // Cache result with timestamp
     this.languageCache.set(type, { data: languages, timestamp: now });
 
     return languages;
@@ -472,13 +436,10 @@ export class TranslationService {
   /**
    * Generate cache key from text and options
    *
-   * IMPORTANT: This method creates a new object with properties in a FIXED order
-   * to ensure deterministic cache keys. Two translation requests with identical
-   * parameters must generate the same cache key, regardless of the order in which
-   * properties were specified in the input options object.
-   *
-   * The property order in `cacheData` is intentional and must not be changed,
-   * as it directly affects cache key generation via JSON.stringify().
+   * IMPORTANT: the property order in `cacheData` is fixed and must not be
+   * changed, because the key is a hash of its `JSON.stringify` output: two
+   * requests with identical parameters must produce the same key whatever order
+   * the caller specified those parameters in.
    *
    * The text is hashed byte-exact, with no Unicode normalization: NFC and NFD
    * encodings of the same visible string produce distinct cache keys. This is
@@ -508,7 +469,7 @@ export class TranslationService {
    * `endpoint` is not a request parameter but decides who answers the request,
    * and one cache DB is shared by every endpoint a config dir has ever talked
    * to. Without it, a single run against `--api-url http://localhost:1234`
-   * served its answers back for api.deepl.com for the full 30-day TTL, with no
+   * serves its answers back for api.deepl.com for the full 30-day TTL, with no
    * network involved. Custom endpoints are a supported feature — proxies,
    * regional endpoints — so this needs no misuse to reach.
    */
@@ -517,8 +478,6 @@ export class TranslationService {
     // naming one glossary share a key and an empty selection keys as no glossary
     const glossary = resolveGlossaryWireParams(options);
 
-    // Create a stable representation with deterministic property order
-    // Property order matters because JSON.stringify() preserves insertion order
     const cacheData = {
       text, // 1. Text to translate
       targetLang: options.targetLang, // 2. Target language
@@ -549,7 +508,6 @@ export class TranslationService {
       endpoint: this.client.resolvedBaseUrl, // 21. Who answered the request
     };
 
-    // Generate SHA-256 hash of the stable representation
     const hash = crypto
       .createHash('sha256')
       .update(JSON.stringify(cacheData))
diff --git a/src/services/watch.ts b/src/services/watch.ts
index 5b562873..de224d31 100644
--- a/src/services/watch.ts
+++ b/src/services/watch.ts
@@ -48,7 +48,7 @@ export interface WatchOptions {
    * Called once a file's translations are on disk. A promise returned here is
    * awaited before the path is considered done, so follow-up work such as
    * `--auto-commit` runs inside the translation's slot and its failure is
-   * reported instead of being dropped.
+   * reported.
    */
   onTranslate?: (
     filePath: string,
@@ -110,7 +110,6 @@ export class WatchService {
    * Start watching a file or directory
    */
   watch(watchPath: string, options: WatchOptions): void {
-    // Validate path exists
     if (!fs.existsSync(watchPath)) {
       throw new ValidationError(`Path not found: ${watchPath}`);
     }
@@ -124,7 +123,6 @@ export class WatchService {
       ? resolvedWatchPath
       : path.dirname(resolvedWatchPath);
 
-    // Create watcher
     const watcherOptions: {
       persistent: boolean;
       ignoreInitial: boolean;
@@ -212,17 +210,14 @@ export class WatchService {
 
   /**
    * Handle file change event
-   * Uses isWatching flag to prevent race conditions with stop()
    */
   handleFileChange(filePath: string): void {
-    // Check if watch has been started at least once
     if (!this.watchOptions) {
       throw new ValidationError('Watch not started');
     }
 
-    // Early check: Don't schedule new timers if watch is being stopped or has stopped
-    // This prevents race conditions where stop() is called between the check above
-    // and scheduling the timer below
+    // Checked before the timer is scheduled below, so a stop() that lands
+    // between the two never leaves a timer behind.
     if (!this.stats.isWatching) {
       return;
     }
@@ -240,15 +235,13 @@ export class WatchService {
       return;
     }
 
-    // Check if file is supported
     if (!this.fileTranslationService.isSupportedFile(filePath)) {
       return;
     }
 
-    // Check if file is in the git-staged set. Both sides are keyed through
-    // their symlinked ancestors: the set comes from git, which reports the
-    // repository's real path, while a watched path is spelled the way the user
-    // gave it.
+    // Both sides of the git-staged check are keyed through their symlinked
+    // ancestors: the set comes from git, which reports the repository's real
+    // path, while a watched path is spelled the way the user gave it.
     if (
       this.options.stagedFiles &&
       !this.options.stagedFiles.has(canonicalPathKey(filePath))
@@ -256,27 +249,23 @@ export class WatchService {
       return;
     }
 
-    // Call onChange callback
     if (this.watchOptions.onChange) {
       this.watchOptions.onChange(filePath);
     }
 
-    // Debounce file changes
     const existingTimer = this.debounceTimers.get(filePath);
     if (existingTimer) {
       clearTimeout(existingTimer);
     }
 
     const timer = setTimeout(() => {
-      // Drop the bookkeeping as soon as the timer fires, not after the
-      // translation finishes, and only if this timer is still the current one.
-      // Deleting unconditionally later would drop a NEWER pending timer for the
-      // same file, making it uncancellable and letting two translations race to
-      // write the same output path.
+      // Drop the bookkeeping as soon as the timer fires, and only while this
+      // timer is still the current one: deleting unconditionally would drop a
+      // newer pending timer for the same file, making it uncancellable and
+      // letting two translations race to write the same output path.
       if (this.debounceTimers.get(filePath) === timer) {
         this.debounceTimers.delete(filePath);
       }
-      // Wrap async code to handle Promise properly (void operator tells TypeScript we intentionally ignore the Promise)
       void this.runTranslation(filePath);
     }, this.options.debounceMs);
 
@@ -287,11 +276,11 @@ export class WatchService {
    * Translate one path, reporting any failure through onError.
    *
    * At most one translation per path is in flight. A change arriving while one
-   * runs records a single re-run instead of starting a second translation:
-   * two concurrent runs write the same output path in API-completion order, so
-   * a slower translation of older content would overwrite a newer one and the
-   * output would stay stale until the next edit. Coalescing also collapses an
-   * edit storm into one re-translation rather than one per event.
+   * runs records a single re-run instead of starting a second translation: two
+   * concurrent runs write the same output path in API-completion order, so a
+   * slower translation of older content can overwrite a newer one. Coalescing
+   * also collapses an edit storm into one re-translation rather than one per
+   * event.
    *
    * The re-run is dispatched from `finally` so a failed translation still picks
    * up the edit that arrived while it was running.
@@ -337,9 +326,8 @@ export class WatchService {
    * Detects patterns like name.{langCode}.ext where langCode matches a
    * configured target language, and only inside the output directory — every
    * file this service writes lands there, so requiring containment keeps the
-   * loop guard complete while letting a source file that merely carries a
-   * target-language segment in its name (pricing.es.md with --to es) be
-   * translated instead of skipped for the lifetime of the session.
+   * loop guard complete while still translating a source file that merely
+   * carries a target-language segment in its name (pricing.es.md with --to es).
    */
   private isTranslatedOutputFile(filePath: string): boolean {
     if (!this.watchOptions) {
@@ -358,7 +346,6 @@ export class WatchService {
     }
 
     const targetLangs = this.watchOptions.targetLangs;
-    // Check any segment between the first and last could be a target language code
     for (let i = 1; i < parts.length - 1; i++) {
       const segment = parts[i]!.toLowerCase();
       if (targetLangs.some((lang) => lang.toLowerCase() === segment)) {
@@ -424,7 +411,7 @@ export class WatchService {
       preserveCode,
     } = this.watchOptions;
 
-    // Build translation options base (targetLang will be set per operation)
+    // targetLang is set per operation below.
     const baseOptions: Partial<TranslationOptions> = {};
 
     if (sourceLang) {
@@ -439,13 +426,12 @@ export class WatchService {
       baseOptions.glossaryId = glossaryId;
     }
 
-    // Determine output path(s)
     const fileName = path.basename(filePath, path.extname(filePath));
     const ext = path.extname(filePath);
     const fileOutputDir = this.outputDirFor(filePath, outputDir);
 
     if (targetLangs.length === 1) {
-      // Single target language (length === 1 guarantees targetLangs[0] exists)
+      // length === 1 guarantees targetLangs[0] exists
       const targetLang = targetLangs[0]!;
       const outputPath = path.join(
         fileOutputDir,
@@ -470,7 +456,6 @@ export class WatchService {
         });
       }
     } else {
-      // Multiple target languages
       const results = await this.fileTranslationService.translateFileToMultiple(
         filePath,
         targetLangs as Language[],
diff --git a/src/services/write.ts b/src/services/write.ts
index 8c067acf..89719610 100644
--- a/src/services/write.ts
+++ b/src/services/write.ts
@@ -169,7 +169,7 @@ export class WriteService {
    *
    * `endpoint` is not a request parameter but decides who answers the request,
    * and one cache DB is shared by every endpoint a config dir has ever talked
-   * to. Without it, a run against a custom `--api-url` served its answers back
+   * to. Without it, a run against a custom `--api-url` serves its answers back
    * for api.deepl.com for the full TTL.
    */
   private generateCacheKey(

From 48f5109cb3c06992d1900eec3117440f90c7cb5f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 22:43:06 +0200
Subject: [PATCH 233/256] refactor(comments): trim the CLI layer to the
 comments that carry a reason
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comments-only. Two kinds went. The first is restatement, thickest in the
commander wiring and the command classes: `// Get __dirname equivalent in ESM`,
`// Save to config`, `// Create abort controller for cancellation`,
`/** Truncate text for preview */`, and a `// Get target language (will throw
...)` repeated verbatim above four identical calls.

The second is the defect story attached to a guard. The rules those guards
enforce stay: that the JSON error envelope goes to stdout because stderr already
carries warnings from the CLI and from Node itself; that a lockfile arrives with
a clone and its keys are untrusted input; that an auto-commit staging nothing is
not a session failure, asked as a diff rather than by matching git's wording,
which a localized git translates; that `--frozen` must read the target and not
only the lockfile.

Also drops a `docs/API.md:2939` line-number citation, which rots on the next
edit to that file, in favour of naming the document.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/cli/commands/auth.ts                      | 11 +---
 src/cli/commands/config.ts                    | 12 -----
 src/cli/commands/glossary.ts                  |  7 ---
 src/cli/commands/hooks.ts                     |  4 --
 src/cli/commands/languages.ts                 |  7 ++-
 src/cli/commands/parse-int-option.ts          |  5 +-
 src/cli/commands/sync-command.ts              | 38 ++++++-------
 src/cli/commands/sync/register-sync-audit.ts  | 10 ++--
 src/cli/commands/sync/register-sync-root.ts   |  2 +-
 src/cli/commands/sync/sync-options.ts         | 11 +---
 .../translate/document-translation-handler.ts |  2 +-
 .../translate/file-translation-handler.ts     |  4 +-
 src/cli/commands/translate/translate-utils.ts |  6 +--
 .../translate/translation-options-factory.ts  | 21 ++++----
 src/cli/commands/voice.ts                     |  4 +-
 src/cli/commands/watch.ts                     | 53 ++++++-------------
 src/cli/commands/write.ts                     | 35 ++----------
 src/cli/index.ts                              | 23 +++-----
 src/cli/json-error-envelope.ts                |  9 ++--
 19 files changed, 75 insertions(+), 189 deletions(-)

diff --git a/src/cli/commands/auth.ts b/src/cli/commands/auth.ts
index 90337113..cdf45bd8 100644
--- a/src/cli/commands/auth.ts
+++ b/src/cli/commands/auth.ts
@@ -29,7 +29,6 @@ export class AuthCommand {
     apiKey: string,
     options: { verify?: boolean } = {}
   ): Promise<void> {
-    // Validate input
     if (!apiKey || apiKey.trim() === '') {
       throw new ValidationError('API key cannot be empty');
     }
@@ -39,11 +38,9 @@ export class AuthCommand {
       return;
     }
 
-    // Validate with DeepL API by making a test request
-    // Note: No format validation - let the API determine if the key is valid
-    // This supports production keys (:fx suffix), free keys, and test keys
+    // No local format check: the API decides, which keeps production (`:fx`),
+    // free and test keys all usable.
     try {
-      // Use configured API endpoint for validation
       const configBaseUrl = this.config.getValue<string>('api.baseUrl');
       const usePro = this.config.getValue<boolean>('api.usePro');
       const baseUrl = resolveEndpoint({ apiKey, configBaseUrl, usePro });
@@ -70,7 +67,6 @@ export class AuthCommand {
       throw new AuthError('Failed to validate API key');
     }
 
-    // Save to config
     this.config.set('auth.apiKey', apiKey);
   }
 
@@ -78,13 +74,10 @@ export class AuthCommand {
    * Get API key from config or environment
    */
   async getKey(): Promise<string | undefined> {
-    // Check environment variable first (for CI/CD)
     const envKey = process.env['DEEPL_API_KEY'];
 
-    // Check config
     const configKey = this.config.getValue<string>('auth.apiKey');
 
-    // Prefer config over environment
     return configKey ?? envKey;
   }
 
diff --git a/src/cli/commands/config.ts b/src/cli/commands/config.ts
index 66660126..2ac0894a 100644
--- a/src/cli/commands/config.ts
+++ b/src/cli/commands/config.ts
@@ -51,7 +51,6 @@ export class ConfigCommand {
    * Set config value
    */
   async set(key: string, value: string): Promise<void> {
-    // Parse value based on type
     const parsedValue = this.parseValue(key, value);
     this.config.set(key, parsedValue);
   }
@@ -62,7 +61,6 @@ export class ConfigCommand {
   async list(): Promise<Record<string, unknown>> {
     const config = this.config.get();
 
-    // Mask sensitive values
     return this.maskSensitiveValues(config);
   }
 
@@ -114,11 +112,7 @@ export class ConfigCommand {
     }
   }
 
-  /**
-   * Parse value based on key
-   */
   private parseValue(key: string, value: string): unknown {
-    // Handle array values (comma-separated)
     if (
       ARRAY_KEYS.includes(key) ||
       key.includes('targetLangs') ||
@@ -127,13 +121,11 @@ export class ConfigCommand {
       return value.split(',').map((v) => v.trim());
     }
 
-    // Auto-coerce string values to booleans for known boolean config keys
     if (BOOLEAN_KEYS.includes(key)) {
       if (value === 'true') return true;
       if (value === 'false') return false;
     }
 
-    // Auto-coerce string values to numbers for known numeric config keys
     if (NUMERIC_KEYS.includes(key)) {
       const num = parseInt(value, 10);
       if (!isNaN(num)) return num;
@@ -142,9 +134,6 @@ export class ConfigCommand {
     return value;
   }
 
-  /**
-   * Mask sensitive values like API keys
-   */
   private maskSensitiveValues(
     config: Record<string, unknown>
   ): Record<string, unknown> {
@@ -153,7 +142,6 @@ export class ConfigCommand {
       unknown
     >;
 
-    // Mask API key
     if (masked['auth'] && typeof masked['auth'] === 'object') {
       const auth = masked['auth'] as Record<string, unknown>;
       if (auth['apiKey'] && typeof auth['apiKey'] === 'string') {
diff --git a/src/cli/commands/glossary.ts b/src/cli/commands/glossary.ts
index d487acf5..28fe9d3b 100644
--- a/src/cli/commands/glossary.ts
+++ b/src/cli/commands/glossary.ts
@@ -57,11 +57,9 @@ export class GlossaryCommand {
    * Show glossary details
    */
   async show(nameOrId: string): Promise<GlossaryInfo> {
-    // Try to get by ID first
     try {
       return await this.glossaryService.getGlossary(nameOrId);
     } catch {
-      // If failed, try by name
       const glossary = await this.glossaryService.getGlossaryByName(nameOrId);
       if (!glossary) {
         throw new ConfigError(`Glossary not found: ${nameOrId}`);
@@ -74,7 +72,6 @@ export class GlossaryCommand {
    * Delete glossary
    */
   async delete(nameOrId: string): Promise<void> {
-    // Try to get glossary first to find ID
     const glossary = await this.show(nameOrId);
     await this.glossaryService.deleteGlossary(glossary.glossary_id);
   }
@@ -87,7 +84,6 @@ export class GlossaryCommand {
     targetLang?: Language
   ): Promise<Record<string, string>> {
     const glossary = await this.show(nameOrId);
-    // Get target language (will throw if glossary is multilingual and targetLang not provided)
     const target = getTargetLang(glossary, targetLang);
     return this.glossaryService.getGlossaryEntries(
       glossary.glossary_id,
@@ -113,7 +109,6 @@ export class GlossaryCommand {
     targetLang?: Language
   ): Promise<void> {
     const glossary = await this.show(nameOrId);
-    // Get target language (will throw if glossary is multilingual and targetLang not provided)
     const target = getTargetLang(glossary, targetLang);
     await this.glossaryService.addEntry(
       glossary.glossary_id,
@@ -134,7 +129,6 @@ export class GlossaryCommand {
     targetLang?: Language
   ): Promise<void> {
     const glossary = await this.show(nameOrId);
-    // Get target language (will throw if glossary is multilingual and targetLang not provided)
     const target = getTargetLang(glossary, targetLang);
     await this.glossaryService.updateEntry(
       glossary.glossary_id,
@@ -154,7 +148,6 @@ export class GlossaryCommand {
     targetLang?: Language
   ): Promise<void> {
     const glossary = await this.show(nameOrId);
-    // Get target language (will throw if glossary is multilingual and targetLang not provided)
     const target = getTargetLang(glossary, targetLang);
     await this.glossaryService.removeEntry(
       glossary.glossary_id,
diff --git a/src/cli/commands/hooks.ts b/src/cli/commands/hooks.ts
index 79b27ef4..f5e1f827 100644
--- a/src/cli/commands/hooks.ts
+++ b/src/cli/commands/hooks.ts
@@ -48,7 +48,6 @@ export class HooksCommand {
   private gitHooksService: GitHooksService | null = null;
 
   constructor(gitDir?: string) {
-    // Find git directory if not provided
     const gitDirectory = gitDir ?? GitHooksService.findGitRoot();
 
     if (!gitDirectory) {
@@ -58,9 +57,6 @@ export class HooksCommand {
     }
   }
 
-  /**
-   * Install a git hook
-   */
   /**
    * The `core.hooksPath` this repository uses to send hooks outside the working
    * tree, or null. The CLI asks before writing there; `install` refuses on its
diff --git a/src/cli/commands/languages.ts b/src/cli/commands/languages.ts
index fab78eaf..8d64a6fa 100644
--- a/src/cli/commands/languages.ts
+++ b/src/cli/commands/languages.ts
@@ -200,10 +200,9 @@ export class LanguagesCommand {
   /**
    * Merge API languages with the bundled snapshot. API names take precedence.
    *
-   * The row set is the union of both: iterating only the snapshot meant a
-   * language the API offers but the snapshot predates was silently dropped from
-   * the listing, so `deepl languages` could not show what `translate` accepted.
-   * Snapshot entries the API omits are kept, so a partial response never makes
+   * The row set is the union of both: a language the API offers but the snapshot
+   * predates is listed, so `deepl languages` shows what `translate` accepts, and
+   * snapshot entries the API omits are kept, so a partial response never makes
    * languages disappear.
    */
   mergeWithRegistry(
diff --git a/src/cli/commands/parse-int-option.ts b/src/cli/commands/parse-int-option.ts
index 493de9a1..2853c4e5 100644
--- a/src/cli/commands/parse-int-option.ts
+++ b/src/cli/commands/parse-int-option.ts
@@ -4,9 +4,8 @@ import { InvalidArgumentError } from 'commander';
  * Commander option parser for a bounded positive integer.
  *
  * A bare `parseInt` yields NaN for a non-numeric value, and NaN survives the
- * `??` default chains used downstream — so an invalid `--concurrency` reached
- * the worker-pool sizing and silently produced zero workers. Rejecting at the
- * boundary means the user is told instead.
+ * `??` default chains used downstream, so an invalid `--concurrency` would reach
+ * worker-pool sizing unnoticed. Rejecting at the boundary tells the user instead.
  */
 export function parsePositiveIntOption(
   value: string,
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index 6835828a..4be2fa8a 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -121,8 +121,7 @@ export interface WatchControllerDeps {
   buckets?: Record<string, { include: string[] }>;
   /**
    * Optional hook invoked at the start of `shutdown()` so the outer loop can
-   * cancel any pending debounce timer. Lets us guarantee that a "Change
-   * detected" log line cannot print after "Stopping watch".
+   * cancel any pending debounce timer.
    */
   clearPendingDebounce?: () => void;
 }
@@ -140,13 +139,10 @@ export function createWatchController(
    *
    * A pass that completes unlinks its own backups inside `SyncService.sync` and
    * clears this tracker, so anything still here belongs to a pass that threw,
-   * was cancelled, or hit drift — none of which wrote a lockfile. Unlinking
-   * those deleted the only remaining copy of the user's translations and left
-   * the target holding machine output that nothing recorded, at exit 0: a loop
-   * pass that rewrote es.json and then aborted on fr destroyed es.json's
-   * reviewed content. Plain `deepl sync` restores from the signal path for the
-   * same reason; a watch pass is skipped there because it owns this tracker, so
-   * the restore has to happen here.
+   * was cancelled, or hit drift — none of which wrote a lockfile, which makes a
+   * backup the only remaining copy of the user's translations. Plain
+   * `deepl sync` restores from the signal path for the same reason; a watch pass
+   * is skipped there because it owns this tracker, so the restore happens here.
    *
    * Synchronous fs calls on purpose: reached from the shutdown path, where the
    * deferred exit only guarantees work done synchronously in the handler. Each
@@ -407,18 +403,14 @@ export class SyncCommand {
       followSymlinks: false,
     });
 
-    // Configurable stale-bak sweep age. Falls back to the hardcoded
-    // STALE_BACKUP_AGE_MS when .deepl-sync.yaml doesn't set it.
     const configuredSweepSeconds = config.sync?.bak_sweep_max_age_seconds;
     const configuredSweepMs =
       configuredSweepSeconds !== undefined && configuredSweepSeconds > 0
         ? configuredSweepSeconds * 1000
         : STALE_BACKUP_AGE_MS;
 
-    // Cache the validated config for the watch session. loadSyncConfig +
-    // validateSyncConfig is ~O(file-read + YAML.parse + ajv-like checks);
-    // running it on every debounced tick is wasted work since config rarely
-    // changes during a watch session. The cache invalidates on SIGHUP or when
+    // The validated config is cached for the watch session rather than reloaded
+    // on every debounced tick. The cache invalidates on SIGHUP or when
     // .deepl-sync.yaml itself is one of the changed files.
     let cachedConfig: ResolvedSyncConfig = config;
     const configFileName = path.basename(configPathResolved);
@@ -740,8 +732,8 @@ export class SyncCommand {
         result.totalCharactersBilled || result.estimatedCharacters;
       const estimatedCost =
         charSource > 0 ? formatCostEstimate(charSource) : undefined;
-      // Success JSON payload routed to stdout so `deepl sync --format json > out.json`
-      // captures the final result. Progress events remain on stderr via Logger.info.
+      // The JSON payload goes to stdout so `deepl sync --format json > out.json`
+      // captures it; progress events stay on stderr via Logger.
       process.stdout.write(
         JSON.stringify(projectToPublicShape(result, estimatedCost), null, 2) +
           '\n'
@@ -783,9 +775,9 @@ export class SyncCommand {
     if (result.deletedKeys > 0) parts.push(`${result.deletedKeys} deleted`);
 
     const summary = parts.length > 0 ? parts.join(', ') : 'no changes';
-    // The key counts above describe the diff, not what landed, so on a partial
-    // failure the line would otherwise read as if every diffed key had been
-    // translated — contradicting the per-locale progress lines above it.
+    // The key counts above describe the diff, not what landed, so a partial
+    // failure has to be named for the summary line to match the per-locale
+    // progress lines above it.
     const failedTranslations = result.fileResults.reduce(
       (total, fileResult) => total + fileResult.failed,
       0
@@ -823,9 +815,9 @@ export class SyncCommand {
       }
     }
 
-    // The summary counts such a key as `current`, which it is as far as the lock
-    // file goes, so the estimate below would otherwise quote characters for work
-    // nothing in the report accounts for.
+    // The summary counts an unwritten key as `current`, which it is as far as
+    // the lock file goes; saying so here keeps the estimate below from quoting
+    // characters for work nothing else in the report accounts for.
     if (result.dryRun && result.unwrittenKeys > 0) {
       const one = result.unwrittenKeys === 1;
       Logger.info(
diff --git a/src/cli/commands/sync/register-sync-audit.ts b/src/cli/commands/sync/register-sync-audit.ts
index 18d05abc..2eb341f6 100644
--- a/src/cli/commands/sync/register-sync-audit.ts
+++ b/src/cli/commands/sync/register-sync-audit.ts
@@ -106,11 +106,11 @@ async function handleSyncAudit(
           }
           // Audit is the only sync read driven by lockfile keys rather than
           // globbed source paths, and a lockfile arrives with a clone like any
-          // other committed file — so its keys are untrusted input. A key of
-          // `../secret/en.json` otherwise read a file outside the project root
-          // and printed its string values in the report. Thrown rather than
-          // skipped, matching how a sync run treats a containment violation: it
-          // is a problem with the project, not with one locale.
+          // other committed file — so its keys are untrusted input, and a key
+          // like `../secret/en.json` would otherwise have its string values
+          // printed in the report. Thrown rather than skipped, matching how a
+          // sync run treats a containment violation: it is a problem with the
+          // project, not with one locale.
           assertPathWithinRoot(targetAbs, config.projectRoot);
           if (!fsMod.existsSync(targetAbs)) continue;
           try {
diff --git a/src/cli/commands/sync/register-sync-root.ts b/src/cli/commands/sync/register-sync-root.ts
index 1a1b036d..ee57a2de 100644
--- a/src/cli/commands/sync/register-sync-root.ts
+++ b/src/cli/commands/sync/register-sync-root.ts
@@ -191,7 +191,7 @@ async function handleSyncRoot(
     if (result.driftDetected) {
       // Soft exit — set exitCode and return so in-flight writes / auto-commit
       // steps / the --watch event loop drain cleanly instead of being killed
-      // mid-cycle. docs/API.md:2939 has promised this shape since 1.1.0.
+      // mid-cycle. docs/API.md documents this exit shape.
       process.exitCode = ExitCode.SyncDrift;
       return;
     }
diff --git a/src/cli/commands/sync/sync-options.ts b/src/cli/commands/sync/sync-options.ts
index 90c2d179..6f2c03bb 100644
--- a/src/cli/commands/sync/sync-options.ts
+++ b/src/cli/commands/sync/sync-options.ts
@@ -75,11 +75,8 @@ export function parseLocaleFilter(
 }
 
 /**
- * JSON error envelope shape emitted on stdout when --format json is set and a
- * command fails. Shared across every command that has a JSON mode so script
- * consumers can parse failures with one schema.
- *
- * @see tests/helpers/assert-error-envelope.ts for the canonical validator.
+ * Sync's alias for the shared failure envelope emitted on stdout when
+ * --format json is set.
  */
 export type { JsonErrorEnvelope as SyncJsonErrorEnvelope } from '../../json-error-envelope.js';
 
@@ -98,10 +95,6 @@ export interface SyncInitJsonSuccessEnvelope {
   };
 }
 
-/**
- * The sync surface's name for the shared envelope emitter, kept so every sync
- * subcommand imports its machine-readable failure path from one place.
- */
 export { emitJsonErrorAndExit } from '../../json-error-envelope.js';
 
 /**
diff --git a/src/cli/commands/translate/document-translation-handler.ts b/src/cli/commands/translate/document-translation-handler.ts
index 9952db9f..b0f21284 100644
--- a/src/cli/commands/translate/document-translation-handler.ts
+++ b/src/cli/commands/translate/document-translation-handler.ts
@@ -35,7 +35,7 @@ export class DocumentTranslationHandler {
       'enableMinification',
     ]);
     warnIgnoredOptions('document', options, supported);
-    // Actually ignored, not just announced: leaving them set let shared
+    // Actually ignored, not just announced: left set, they let shared
     // validation reject a command over a flag this mode has just said it would
     // disregard.
     const {
diff --git a/src/cli/commands/translate/file-translation-handler.ts b/src/cli/commands/translate/file-translation-handler.ts
index d6445da2..d3069cce 100644
--- a/src/cli/commands/translate/file-translation-handler.ts
+++ b/src/cli/commands/translate/file-translation-handler.ts
@@ -126,8 +126,8 @@ export class FileTranslationHandler {
       this.ctx.documentTranslationService.isDocumentSupported(filePath);
 
     // Resolved once, ahead of every branch below: each of them writes to
-    // options.output, so deciding this per branch is what let a directory
-    // destination reach the write unnoticed.
+    // options.output, so a directory destination has to be turned into a file
+    // name before the branch is picked.
     const outputPath = resolveFileOutputPath(
       filePath,
       requestedOutput,
diff --git a/src/cli/commands/translate/translate-utils.ts b/src/cli/commands/translate/translate-utils.ts
index 66b76ac0..3839dfdf 100644
--- a/src/cli/commands/translate/translate-utils.ts
+++ b/src/cli/commands/translate/translate-utils.ts
@@ -159,9 +159,9 @@ export interface TranslationLanguageConstraints extends ExtendedLanguageConstrai
 }
 
 /**
- * The language gate for every translate input mode. One entry point because a
- * mode that checked codes without the extended-tier arms accepted, and sent,
- * commands its siblings rejected locally.
+ * The language gate for every translate input mode. One entry point so no mode
+ * can check codes without also applying the extended-tier arms and send a
+ * command its siblings reject locally.
  */
 export function validateTranslationLanguages(
   targets: string[],
diff --git a/src/cli/commands/translate/translation-options-factory.ts b/src/cli/commands/translate/translation-options-factory.ts
index 4e266ae6..a33e12b7 100644
--- a/src/cli/commands/translate/translation-options-factory.ts
+++ b/src/cli/commands/translate/translation-options-factory.ts
@@ -9,9 +9,9 @@ import {
 } from './translate-utils.js';
 
 /**
- * Single source of truth for the *base* TranslateOptions mapping from CLI
- * flags — the shape all translate handlers (text, file, directory, document)
- * agreed on. Produces the same field set regardless of handler.
+ * Single source of truth for the *base* TranslateOptions mapping of CLI flags,
+ * producing the same field set for every translate handler (text, file,
+ * directory, document).
  *
  * Shared downstream shaping lives in `applySharedTmAndGlossary`; handlers
  * keep only handler-specific shaping (custom instructions, style id, XML tag
@@ -35,10 +35,9 @@ export function buildBaseTranslationOptions(
 
 /**
  * Resolve `--glossary` values to IDs and place them on `base`. One glossary is
- * assigned to `glossaryId` so the request keeps the shape — and cache key — it
- * had before multiple glossaries were supported; several go to `glossaryIds`,
- * in the order given, because the API applies the last glossary that defines a
- * conflicting term.
+ * assigned to `glossaryId`, keeping the single-glossary wire shape and its
+ * cache key; several go to `glossaryIds`, in the order given, because the API
+ * applies the last glossary that defines a conflicting term.
  *
  * Separate from `applySharedTmAndGlossary` because document translation
  * supports glossaries but not translation memories.
@@ -107,10 +106,10 @@ export interface SharedTmAndGlossaryDeps {
  * default onto a base `TranslationParams`-compatible object. Mutates `base`
  * in place so handlers can compose additional downstream shaping.
  *
- * Shared by the text + file handlers. All
- * validation (required `--from`, TM-requires-quality_optimized, extended-lang
- * constraints) remains in the caller so per-handler error messages are
- * preserved; this helper is called only after validation passes.
+ * Shared by the text + file handlers. All validation (required `--from`,
+ * TM-requires-quality_optimized, extended-lang constraints) remains in the
+ * caller so per-handler error messages are preserved; this helper is called
+ * only after validation passes.
  *
  * The generic `T` lets callers pass a `TranslationParams` (text handler), a
  * `TranslationParams & { outputDir: string }` (file multi-target), or the
diff --git a/src/cli/commands/voice.ts b/src/cli/commands/voice.ts
index 1bd00dd2..122b6a02 100644
--- a/src/cli/commands/voice.ts
+++ b/src/cli/commands/voice.ts
@@ -360,7 +360,6 @@ export class VoiceCommand {
       // Move cursor up to overwrite previous output
       readline.moveCursor(process.stdout, 0, -lineCount);
 
-      // Render source line
       const src = state['source']!;
       readline.clearLine(process.stdout, 0);
       readline.cursorTo(process.stdout, 0);
@@ -368,7 +367,6 @@ export class VoiceCommand {
         `${chalk.bold('[source]')} ${src.concluded}${chalk.gray(src.tentative)}\n`
       );
 
-      // Render each target language
       for (const lang of targetLangs) {
         const tgt = state[lang]!;
         readline.clearLine(process.stdout, 0);
@@ -390,7 +388,7 @@ export class VoiceCommand {
       }
     };
 
-    // Print initial blank lines
+    // Reserve the lines `render` moves back over and overwrites.
     for (let i = 0; i < lineCount; i++) {
       process.stdout.write('\n');
     }
diff --git a/src/cli/commands/watch.ts b/src/cli/commands/watch.ts
index e385a513..156ec8af 100644
--- a/src/cli/commands/watch.ts
+++ b/src/cli/commands/watch.ts
@@ -55,8 +55,7 @@ function watchedDirectory(target: string): string {
  * What git said, rather than only that a command failed.
  *
  * `execFile` puts the exit status in `message` and the diagnosis in `stderr`, so
- * reporting `message` alone discarded the one part that tells the user what to
- * fix.
+ * `stderr` is the part that tells the user what to fix.
  */
 function gitFailureDetail(error: unknown): string {
   if (typeof error === 'object' && error !== null) {
@@ -167,12 +166,10 @@ export class WatchCommand {
    * Start watching a file or directory
    */
   async watch(pathToWatch: string, options: WatchOptions): Promise<void> {
-    // Validate path exists
     if (!fs.existsSync(pathToWatch)) {
       throw new ValidationError(`Path not found: ${pathToWatch}`);
     }
 
-    // Parse target languages
     const targetLangs = options.to
       .split(',')
       .map((lang) => lang.trim())
@@ -186,10 +183,9 @@ export class WatchCommand {
     }
 
     // The API rejects any translation naming a glossary without source_lang, so
-    // an unguarded watch session fails once per file change instead of at launch.
-    // Settled from `defaults.sourceLang` when the flag is absent, the same way
-    // every other command does it, so a direct call and the CLI agree on what is
-    // runnable.
+    // the requirement is settled at launch, using the configured
+    // `defaults.sourceLang` when the flag is absent, rather than failing once
+    // per file change.
     if (hasGlossarySelection(options)) {
       applyGlossarySourceLang(
         options,
@@ -198,7 +194,6 @@ export class WatchCommand {
       );
     }
 
-    // Get git-staged files if requested
     let stagedFiles: Set<string> | undefined;
     if (options.gitStaged) {
       stagedFiles = await this.getStagedFiles(pathToWatch);
@@ -211,8 +206,8 @@ export class WatchCommand {
       Logger.info(chalk.gray(`Git-staged files: ${stagedFiles.size}`));
     }
 
-    // Resolve glossary ID if provided. The pair is known at launch, so the
-    // coverage check happens here rather than once per file change.
+    // The language pair is known at launch, so the glossary coverage check
+    // happens here rather than once per file change.
     let glossaryId: string | undefined;
     if (options.glossary) {
       glossaryId = await this.resolveGlossaryId(
@@ -223,12 +218,10 @@ export class WatchCommand {
       );
     }
 
-    // Determine output directory
     let outputDir: string;
     if (options.output) {
       outputDir = options.output;
     } else {
-      // Default: create translations/ subdirectory
       const isDirectory = fs.statSync(pathToWatch).isDirectory();
       if (isDirectory) {
         outputDir = `${pathToWatch}/translations`;
@@ -240,7 +233,6 @@ export class WatchCommand {
       }
     }
 
-    // Create output directory if it doesn't exist
     if (!fs.existsSync(outputDir)) {
       fs.mkdirSync(outputDir, { recursive: true });
     }
@@ -248,7 +240,7 @@ export class WatchCommand {
     // git can only commit files inside its own working tree, so --auto-commit
     // is answerable only by the repository holding the output directory. Asked
     // here, before the first translation is billed, so a session that could
-    // never commit anything says so once instead of once per translated file.
+    // never commit anything says so once.
     if (options.autoCommit) {
       const repoRoot = await this.gitWorktreeRoot(outputDir);
       if (repoRoot === null) {
@@ -259,7 +251,6 @@ export class WatchCommand {
       }
     }
 
-    // Create watch service with optional debounce and concurrency
     const watchServiceOptions: {
       debounceMs?: number;
       concurrency?: number;
@@ -267,9 +258,8 @@ export class WatchCommand {
       stagedFiles?: Set<string>;
     } = { pattern: options.pattern, stagedFiles };
 
-    // The default is applied here rather than left to WatchService so that the
-    // documented value holds and `watch.debounceMs` takes effect: the flag wins,
-    // then configuration, then the documented default.
+    // Applied here rather than left to WatchService so that `watch.debounceMs`
+    // takes effect and the documented default holds.
     watchServiceOptions.debounceMs =
       options.debounce ??
       this.config?.getValue<number>('watch.debounceMs') ??
@@ -283,10 +273,8 @@ export class WatchCommand {
       watchServiceOptions
     );
 
-    // Create abort controller for cancellation
     const controller = new AbortController();
 
-    // Build watch options
     const watchOpts = {
       targetLangs,
       outputDir,
@@ -301,7 +289,6 @@ export class WatchCommand {
       },
       onTranslate: async (filePath: string, result: WatchTranslationResult) => {
         if (Array.isArray(result)) {
-          // Multiple languages
           Logger.success(
             chalk.green(
               `✓ Translated ${filePath} to ${result.length} languages`
@@ -311,12 +298,10 @@ export class WatchCommand {
             Logger.info(chalk.gray(`  → [${r.targetLang}] ${r.outputPath}`));
           });
         } else {
-          // Single language
           Logger.success(chalk.green(`✓ Translated ${filePath}`));
           Logger.info(chalk.gray(`  → ${result.outputPath}`));
         }
 
-        // Auto-commit if enabled
         if (options.autoCommit) {
           await this.autoCommit(filePath, result);
         }
@@ -329,10 +314,8 @@ export class WatchCommand {
       },
     };
 
-    // Start watching
     this.watchService.watch(pathToWatch, watchOpts);
 
-    // Display initial message
     Logger.success(chalk.green('👀 Watching for changes...'));
     Logger.info(chalk.gray(`Path: ${pathToWatch}`));
     Logger.info(chalk.gray(`Targets: ${targetLangs.join(', ')}`));
@@ -348,7 +331,6 @@ export class WatchCommand {
     }
     Logger.info(chalk.gray('Press Ctrl+C to stop\n'));
 
-    // Handle graceful shutdown
     const cleanup = async () => {
       Logger.warn(chalk.yellow('\n\n🛑 Stopping watch...'));
       controller.abort();
@@ -370,7 +352,6 @@ export class WatchCommand {
     process.on('SIGINT', () => void cleanup());
     process.on('SIGTERM', () => void cleanup());
 
-    // Keep process alive
     await new Promise(() => {
       // Intentionally never resolves - will exit via signal handlers
     });
@@ -396,8 +377,8 @@ export class WatchCommand {
       const { promisify } = await import('util');
       const execFileAsync = promisify(execFile);
 
-      // Collect output files. Resolved here, while the process working
-      // directory is still the one they were written relative to.
+      // Resolved here, while the process working directory is still the one
+      // they were written relative to.
       const outputFiles: string[] = [];
       if (Array.isArray(result)) {
         result.forEach((r: FileTranslationResult) => {
@@ -430,7 +411,6 @@ export class WatchCommand {
         await execFileAsync('git', ['add', '--', file], { cwd });
       }
 
-      // Create commit message
       const langs = Array.isArray(result)
         ? result.map((r: FileTranslationResult) => r.targetLang).join(', ')
         : result.targetLang;
@@ -438,11 +418,9 @@ export class WatchCommand {
       const commitMsg = `chore(i18n): auto-translate ${sourceFile} to ${langs}`;
 
       // A re-save whose bytes are unchanged stages nothing, and `git commit`
-      // then exits non-zero. That is not a failure — nothing needed committing —
-      // but the catch below counted it as one, which made `sessionExitCode()`
-      // report 12 for a session in which nothing had gone wrong. Asked as a
-      // diff rather than by matching git's "nothing to commit" wording, which is
-      // translated in a localized git.
+      // then exits non-zero — which is not a failure, since nothing needed
+      // committing. Asked as a diff rather than by matching git's "nothing to
+      // commit" wording, which a localized git translates.
       const nothingStaged = await execFileAsync(
         'git',
         ['diff', '--cached', '--quiet', '--', ...outputFiles],
@@ -476,8 +454,7 @@ export class WatchCommand {
   /**
    * Exit code for a watch session ending on SIGINT/SIGTERM. A translation or an
    * auto-commit that failed during the session is a partial failure, not a
-   * clean run: the session used to report exit 0 with the failures only logged,
-   * so a script driving `deepl watch` had no way to notice.
+   * clean run, so a script driving `deepl watch` can notice it.
    */
   private sessionExitCode(): number {
     const errors = this.watchService?.getStats().errorsCount ?? 0;
diff --git a/src/cli/commands/write.ts b/src/cli/commands/write.ts
index a0ffaa14..57511c25 100644
--- a/src/cli/commands/write.ts
+++ b/src/cli/commands/write.ts
@@ -46,8 +46,8 @@ export class WriteCommand {
    * (rephrase by default; spelling/grammar correction when options.correct is set)
    */
   async improve(text: string, options: WriteOptions): Promise<string> {
-    // Format output based on format option. The alternatives listing is a set of
-    // results rather than one, so it has a payload of its own.
+    // The alternatives listing is a set of results rather than one, so it has a
+    // payload of its own.
     if (options.showAlternatives) {
       const alternatives = await this.alternativeTexts(text, options);
       return options.format === 'json'
@@ -99,9 +99,6 @@ export class WriteCommand {
     return improvements.map((i) => i.text);
   }
 
-  /**
-   * Dispatch to the rephrase or correct endpoint based on options.correct
-   */
   private fetchImprovements(
     text: string,
     options: WriteOptions,
@@ -169,13 +166,10 @@ export class WriteCommand {
     const absolutePath = resolve(filePath);
     const content = await this.readFileContent(filePath);
 
-    // Improve the content
     const improvedText = await this.improve(content, options);
 
-    // Handle output
     if (options.outputFile) {
       const outputPath = resolve(options.outputFile);
-      // Ensure output directory exists
       await fs.mkdir(dirname(outputPath), { recursive: true });
       await atomicWriteFile(outputPath, improvedText, 'utf-8');
     } else if (options.inPlace) {
@@ -199,7 +193,6 @@ export class WriteCommand {
   generateDiff(original: string, improved: string): string {
     const patch = this.generatePatch(original, improved);
 
-    // Color the diff output
     const lines = patch.split('\n');
     const coloredLines = lines.map((line) => {
       if (line.startsWith('+') && !line.startsWith('+++')) {
@@ -262,7 +255,6 @@ export class WriteCommand {
   }> {
     const improvedText = await this.improvedText(text, options);
 
-    // Count the number of changes using diff
     const patches = Diff.diffWords(text, improvedText);
     const changes = patches.filter((p) => p.added || p.removed).length;
 
@@ -321,7 +313,6 @@ export class WriteCommand {
     const absolutePath = resolve(filePath);
     const content = await this.readFileContent(filePath);
 
-    // Check if improvements are needed
     const checkResult = await this.checkText(content, options);
 
     if (!checkResult.needsImprovement) {
@@ -332,14 +323,12 @@ export class WriteCommand {
       };
     }
 
-    // Create backup if requested
     let backupPath: string | undefined;
     if (options.createBackup) {
       backupPath = `${absolutePath}.bak`;
       await fs.writeFile(backupPath, content, 'utf-8');
     }
 
-    // Write improved content
     await atomicWriteFile(absolutePath, checkResult.improved, 'utf-8');
 
     return {
@@ -399,11 +388,9 @@ export class WriteCommand {
       return selection === -1 ? text : improvements[0]!.text;
     }
 
-    // Generate multiple alternatives by calling API with different styles
     const styles: WritingStyle[] = ['simple', 'business', 'academic', 'casual'];
     const allImprovements: Array<{ text: string; label: string }> = [];
 
-    // Call API for each style
     for (const style of styles) {
       try {
         const improvements = await this.writeService.improve(
@@ -436,7 +423,6 @@ export class WriteCommand {
         index === self.findIndex((t) => t.text === improvement.text)
     );
 
-    // Create choices with style labels
     const maxLen = this.getPreviewWidth();
     const originalPreview = sanitizeForTerminal(text);
     const choices = [
@@ -455,15 +441,13 @@ export class WriteCommand {
       }),
     ];
 
-    // Prompt user to select
     const selection = await select({
       message: `Choose an improvement (${uniqueImprovements.length} alternatives):`,
       choices,
     });
 
-    // Return selected text
     if (selection === -1) {
-      return text; // Keep original
+      return text;
     }
 
     return uniqueImprovements[selection]!.text;
@@ -491,7 +475,6 @@ export class WriteCommand {
     });
     const alternatives = improvements.map((i) => i.text);
 
-    // Interactive selection
     const selected = await this.improveInteractive(content, options);
 
     return {
@@ -520,16 +503,10 @@ export class WriteCommand {
     }
   }
 
-  /**
-   * Calculate preview width based on terminal columns
-   */
   private getPreviewWidth(): number {
     return Math.max(40, (process.stdout.columns || 80) - 25);
   }
 
-  /**
-   * Truncate text for preview
-   */
   private truncate(text: string, maxLength: number): string {
     if (text.length <= maxLength) {
       return text;
@@ -537,16 +514,10 @@ export class WriteCommand {
     return text.substring(0, maxLength - 3) + '...';
   }
 
-  /**
-   * Capitalize first letter of string
-   */
   private capitalizeFirst(str: string): string {
     return str.charAt(0).toUpperCase() + str.slice(1);
   }
 
-  /**
-   * Format alternatives with numbering
-   */
   private formatAlternatives(alternatives: string[]): string {
     return alternatives
       .map((alt, index) => `${index + 1}. ${alt}`)
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 519343e5..ad8b1d6e 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -54,21 +54,18 @@ import { assertSupportedNodeVersion } from './node-version-check.js';
 
 assertSupportedNodeVersion();
 
-// Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Read version from package.json
 const packageJsonPath = join(__dirname, '../../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as {
   version: string;
 };
 const { version } = packageJson;
 
-// Initialize services
 const paths = resolvePaths();
 
-// Create config service - can be overridden by --config flag
+// Reassigned by the preAction hook when --config names another file.
 let configService = new ConfigService(paths.configFile);
 
 // HTTP transport overrides from --timeout / --max-retries, applied to every
@@ -91,8 +88,7 @@ let activeOutputFormat: string | undefined;
  *
  * With `--format json` in effect the failure is the command's result, so it
  * goes to stdout as the same typed envelope every `deepl sync` subcommand
- * emits, and the prose is inside it rather than on stderr. Commands with no
- * JSON mode, and every text-mode run, are unchanged.
+ * emits, and the prose is inside it rather than on stderr.
  */
 function handleError(error: unknown): never {
   if (activeOutputFormat === 'json') {
@@ -187,7 +183,6 @@ async function createDeepLClient(
   return new Client(key, { baseUrl, usePro, ...httpOptions });
 }
 
-// Create program
 const program = new Command();
 program.showSuggestionAfterError(true);
 
@@ -225,13 +220,11 @@ program
     // the commands that declare --format have one at all.
     activeOutputFormat = actionCommand.opts()['format'] as string | undefined;
 
-    // Handle --config flag - reinitialize config service with custom path
     // SECURITY: Validate path to prevent traversal attacks
     if (options['config']) {
       const customConfigPath = options['config'] as string;
 
-      // Resolve to absolute path (handles both relative and absolute paths)
-      // resolve() automatically normalizes and resolves '..' sequences safely
+      // resolve() normalizes and resolves '..' sequences safely.
       const safePath = isAbsolute(customConfigPath)
         ? resolve(customConfigPath)
         : resolve(process.cwd(), customConfigPath);
@@ -253,7 +246,6 @@ program
       configService = new ConfigService(safePath);
     }
 
-    // Set quiet mode before any command runs
     if (options['quiet']) {
       Logger.setQuiet(true);
     }
@@ -277,7 +269,6 @@ program
       chalk.level = 0;
     }
 
-    // Set non-interactive mode
     if (options['input'] === false) {
       setNoInput(true);
     }
@@ -467,16 +458,14 @@ program.on('command:*', (operands: string[]) => {
 // call process.exit() and thereby preempt the others.
 installSignalExit();
 
-// Show help and exit 0 if no arguments provided
 if (!process.argv.slice(2).length) {
   program.outputHelp();
   process.exit(0);
 }
 
-// Parse arguments. Commander propagates non-CommanderError throws from option
-// coercers (e.g. --tm-threshold) uncaught, so route DeepLCLIError subclasses
-// through handleError here — otherwise pre-handler validation crashes with a
-// stack trace instead of the documented exit code.
+// Commander propagates non-CommanderError throws from option coercers (e.g.
+// --tm-threshold) uncaught, so pre-handler validation has to be routed through
+// handleError here to reach its documented exit code.
 try {
   await program.parseAsync(process.argv);
 } catch (error) {
diff --git a/src/cli/json-error-envelope.ts b/src/cli/json-error-envelope.ts
index d9768acd..32ce352a 100644
--- a/src/cli/json-error-envelope.ts
+++ b/src/cli/json-error-envelope.ts
@@ -29,11 +29,10 @@ function sanitizeMessage(message: string): string {
  * Serialize an error to the canonical envelope on stdout and exit with the
  * error's typed exit code.
  *
- * stdout, not stderr: the envelope is the command's result in the failure
- * case, and stderr is where every warning — the CLI's own and the Node
- * runtime's — already goes, so an envelope there parses only when nothing else
- * happened to be said. The non-zero exit code remains the failure signal; a
- * consumer reads the reason off the same stream as the success payload.
+ * stdout, not stderr: the envelope is the command's result in the failure case,
+ * and stderr already carries warnings from both the CLI and the Node runtime,
+ * which would break a parse there. The non-zero exit code remains the failure
+ * signal.
  */
 export function emitJsonErrorAndExit(
   error: unknown,

From 339ad093f17baefff54fd657261d4b295403a733 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 22:43:18 +0200
Subject: [PATCH 234/256] refactor(comments): keep the adversarial-input rules
 in utils, drop the measurements
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comments-only. These modules encode rules about hostile or awkward input, and
the rules stay: that an extglob repetition wrapping an unbounded wildcard gives
picomatch a nested quantifier; that a V8 out-of-memory abort is not catchable so
a pattern must be bounded before fast-glob sees it; that the redaction floor
exists because the match has no token boundary; that terminal control sequences
are neutralized only for a TTY, because redirected stdout is data; that a temp
sibling cannot be recognised by its name alone.

What went with them is the bench data from the session that found each one --
"~600MB at 20 groups", "28 ms at 20k comment lines, 109 ms at 40k", "about 50
SECONDS". The cap values they justify are documented where they are declared:
MAX_GLOB_EXPANSION still explains that it sits at the `braces` range limit.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/utils/atomic-write.ts      | 11 +++++------
 src/utils/formatters.ts        |  1 -
 src/utils/glob-safety.ts       | 20 ++++++++++----------
 src/utils/icu-preservation.ts  | 20 ++++++++------------
 src/utils/logger.ts            | 34 +++++++++-------------------------
 src/utils/paths.ts             |  6 ++----
 src/utils/private-mode.ts      |  8 ++++----
 src/utils/text-preservation.ts | 14 +++++++-------
 8 files changed, 45 insertions(+), 69 deletions(-)

diff --git a/src/utils/atomic-write.ts b/src/utils/atomic-write.ts
index e09c503e..0fc9bda8 100644
--- a/src/utils/atomic-write.ts
+++ b/src/utils/atomic-write.ts
@@ -91,12 +91,11 @@ const TMP_SIBLING_PATTERN = /\.tmp\.\d+\.[a-z0-9]+$/;
 export function isAtomicWriteTempPath(filePath: string): boolean {
   const resolved = path.resolve(filePath);
   if (inFlightTmpPaths.has(resolved)) return true;
-  // Not one of ours. The name pattern alone used to be the whole test, which
-  // silently dropped any real document named `*.tmp.<digits>.<lc-alnum>` from
-  // watch — before the warn-once branch, so nothing said the file had been
-  // skipped. It is still honoured for a path that does not exist, which is what a
-  // temp sibling looks like once its rename has completed but the watcher's event
-  // is only now being delivered: there is nothing there to treat as a document.
+  // Not one of ours. The name pattern alone cannot be the whole test: it would
+  // drop a real document named `*.tmp.<digits>.<lc-alnum>` from watch. It is
+  // honoured only for a path that does not exist, which is what a temp sibling
+  // looks like once its rename has completed but the watcher's event is only now
+  // being delivered: there is nothing there to treat as a document.
   return TMP_SIBLING_PATTERN.test(resolved) && !fs.existsSync(resolved);
 }
 
diff --git a/src/utils/formatters.ts b/src/utils/formatters.ts
index 11d3e202..c4106146 100644
--- a/src/utils/formatters.ts
+++ b/src/utils/formatters.ts
@@ -170,7 +170,6 @@ export function formatMultiTranslationTable(
     billedCharacters?: number;
   }>
 ): string {
-  // Check if any result has billedCharacters - if so, show the Characters column
   const showCharacters = results.some((r) => r.billedCharacters !== undefined);
   const colorDisabled = !isColorEnabled();
 
diff --git a/src/utils/glob-safety.ts b/src/utils/glob-safety.ts
index 441a9acc..981271ef 100644
--- a/src/utils/glob-safety.ts
+++ b/src/utils/glob-safety.ts
@@ -4,11 +4,11 @@ import { sanitizeForTerminal } from './control-chars.js';
 /**
  * fast-glob expands brace groups through `braces`, which bounds only its INPUT
  * length (10000 characters) and places no bound on the expansion it produces —
- * unlike `brace-expansion`, whose similar name hides a very different set of
- * caps. The expansion is the product of every group's alternatives, so 20
- * `{a,b}` groups fit in 107 characters and allocate ~600MB, and 22 groups end
- * the process with a V8 out-of-memory abort. An abort is not a catchable
- * exception, so patterns must be bounded before they reach fast-glob at all.
+ * unlike the similarly named `brace-expansion`, whose caps are different. The
+ * expansion is the product of every group's alternatives, so a pattern barely
+ * 100 characters long can exhaust the heap. A V8 out-of-memory abort is not a
+ * catchable exception, so patterns must be bounded before they reach fast-glob
+ * at all.
  *
  * The cap sits at or below the `braces` range limit (1000) so that a range
  * wider than the limit is rejected here rather than surfacing as a raw
@@ -143,11 +143,11 @@ export function countGlobExpansion(pattern: string): number {
  * wildcard, or undefined.
  *
  * Those two operators are repetitions, so a `*` or `+` inside one gives picomatch
- * a nested quantifier and exponential backtracking. Measured against a
- * 40-character directory name, the six-character pattern `+(a*)b` takes about 50
- * SECONDS — and the expansion bound above never sees it, because a pattern can
- * carry no brace at all. `@(…)`, `?(…)` and `!(…)` are not repetitions and stayed
- * flat under the same measurement, so they are left alone.
+ * a nested quantifier and exponential backtracking: a pattern as short as
+ * `+(a*)b` takes tens of seconds against a single 40-character directory name,
+ * and the expansion bound above never sees it, because such a pattern need carry
+ * no brace at all. `@(…)`, `?(…)` and `!(…)` are not repetitions, stay flat, and
+ * are left alone.
  *
  * Both the pattern and the directory names it is matched against come from the
  * checkout, so this is reachable from a merge request rather than only from a
diff --git a/src/utils/icu-preservation.ts b/src/utils/icu-preservation.ts
index e80dd645..8873f74d 100644
--- a/src/utils/icu-preservation.ts
+++ b/src/utils/icu-preservation.ts
@@ -44,9 +44,8 @@ export function parseIcu(text: string): IcuParseResult {
     let template = '';
     let pos = 0;
 
-    // Every block is protected, not just the first. Pushing the whole suffix as
-    // one prose segment submitted the remaining blocks' syntax to the engine,
-    // which translates the keyword and the selectors.
+    // Every block is protected, not just the first: a block left inside a prose
+    // segment would reach the engine as raw ICU syntax.
     for (;;) {
       const match = ICU_DETECT_RE.exec(text.slice(pos));
       if (!match) break;
@@ -59,8 +58,7 @@ export function parseIcu(text: string): IcuParseResult {
         return { isIcu: false, segments: [], reassemble: () => text };
       }
 
-      // Text between blocks is ordinary prose and must be translated too —
-      // dropping it from the template silently deleted it.
+      // Text between blocks is ordinary prose and must be translated too.
       const prose = text.slice(pos, blockStart);
       if (prose !== '') {
         template += `__ICU_LEAF_${segments.length}__`;
@@ -90,8 +88,8 @@ export function parseIcu(text: string): IcuParseResult {
       segments,
       reassemble: (translations: string[]) => {
         if (translations.length !== segments.length) {
-          // Filling missing values with '' produced empty plural branches,
-          // which render nothing for that category.
+          // Filling the missing values with '' would produce empty plural
+          // branches, which render nothing for that category.
           throw new Error(
             `ICU reassemble expected ${segments.length} translations, received ${translations.length}`
           );
@@ -240,11 +238,9 @@ function tryParseNestedContent(
   inPluralContext: boolean,
   segments: IcuSegment[]
 ): { template: string } | null {
-  // Check if content contains a nested ICU block
-  // e.g., "{gender, select, male {He has # items} female {She has # items}}"
-  // Content might be mixed: "text before {var, plural, ...} text after"
-
-  // For MVP: only handle content that IS a full ICU block (starts with {var, keyword, ...})
+  // Only content that IS a full ICU block nests, e.g.
+  // "{gender, select, male {He has # items} female {She has # items}}".
+  // Mixed content — "text before {var, plural, ...} text after" — stays a leaf.
   const trimmed = content.trim();
   if (!ICU_DETECT_RE.test(trimmed)) return null;
 
diff --git a/src/utils/logger.ts b/src/utils/logger.ts
index 7587dac3..7d7fe4d0 100644
--- a/src/utils/logger.ts
+++ b/src/utils/logger.ts
@@ -8,9 +8,8 @@ import { neutralizeTerminalControls } from './control-chars.js';
 /**
  * Shortest credential value redacted by literal substring match. A DeepL key is
  * UUID-shaped and TMS credentials are longer still, so nothing real is below
- * this; anything that is would corrupt ordinary prose instead, because the
- * match has no token boundary — a one-character key turns every "Check" in
- * every diagnostic into "Chec[REDACTED]".
+ * this; anything shorter would corrupt ordinary prose instead, because the match
+ * has no token boundary.
  */
 const MIN_REDACTABLE_SECRET_LENGTH = 8;
 
@@ -36,30 +35,18 @@ class LoggerClass {
     this.registeredSecrets.clear();
   }
 
-  /**
-   * Enable or disable quiet mode
-   */
   setQuiet(enabled: boolean): void {
     this.quiet = enabled;
   }
 
-  /**
-   * Check if quiet mode is enabled
-   */
   isQuiet(): boolean {
     return this.quiet;
   }
 
-  /**
-   * Enable or disable verbose mode
-   */
   setVerbose(enabled: boolean): void {
     this.verboseMode = enabled;
   }
 
-  /**
-   * Check if verbose mode is enabled
-   */
   isVerbose(): boolean {
     return this.verboseMode;
   }
@@ -147,7 +134,6 @@ class LoggerClass {
     // Every remaining object — a plain one, an axios AxiosHeaders, a
     // ClientRequest — is rebuilt property by property on its own prototype, so
     // util.inspect still names the class but never sees the live original.
-    // Handing a redactor's caller the untouched instance is the wrong default.
     // Properties are defined rather than assigned so a key named `__proto__`
     // becomes an own property of the copy instead of reaching the setter.
     const copy = Object.create(
@@ -263,12 +249,11 @@ class LoggerClass {
    * Log essential output (ALWAYS shown, even in quiet mode)
    * Use this for translation results, command output, etc.
    *
-   * Terminal control sequences are neutralized only when stdout is a TTY.
-   * Redirected stdout is data — `deepl translate ... > out.txt` and command
-   * substitution must reproduce the translation byte for byte — and a control
-   * sequence can only act on a terminal that interprets it. Untrusted values
-   * interpolated into report lines are sanitized at their call site instead,
-   * so those stay safe whether or not stdout is a terminal.
+   * Terminal control sequences are neutralized only when stdout is a TTY:
+   * redirected stdout is data — `deepl translate ... > out.txt` and command
+   * substitution must reproduce the translation byte for byte. Untrusted values
+   * interpolated into report lines are sanitized at their call site instead, so
+   * those stay safe whether or not stdout is a terminal.
    */
   output(...args: unknown[]): void {
     if (process.stdout.isTTY) {
@@ -282,13 +267,12 @@ class LoggerClass {
    * Check if spinners should be shown.
    * Returns false in quiet mode or when stderr is not a TTY — ora writes to
    * stderr by default, so a non-TTY stderr means spinners would either no-op
-   * silently inside ora or (on older ora versions) leak ANSI escapes into CI
-   * logs. Gating at this single chokepoint covers every `ora(...)` callsite.
+   * inside ora or leak ANSI escapes into CI logs. Gating at this single
+   * chokepoint covers every `ora(...)` callsite.
    */
   shouldShowSpinner(): boolean {
     return !this.quiet && !!process.stderr.isTTY;
   }
 }
 
-// Export singleton instance
 export const Logger = new LoggerClass();
diff --git a/src/utils/paths.ts b/src/utils/paths.ts
index c60dd1d6..79f1df71 100644
--- a/src/utils/paths.ts
+++ b/src/utils/paths.ts
@@ -55,10 +55,8 @@ export function canonicalPathKey(absPath: string): string {
   // what makes two spellings of one file compare equal. The string form cannot:
   // `fs.realpathSync` does not case-fold on a case-insensitive volume (APFS
   // returns `Docs` for `Docs` even when the directory is stored as `docs`) and
-  // does not unify NFC with NFD. Both were measured on APFS as reaching the same
-  // inode while producing different strings, which made `watch --git-staged`
-  // translate nothing when git spelled a directory differently from the watcher —
-  // silently, at exit 0.
+  // does not unify NFC with NFD, so on APFS two paths reaching the same inode can
+  // still produce different strings.
   //
   // `lstat`, not `stat`: a symlink has its own inode, which keeps the rule below
   // that a symlink is a different file from its target. On a case-SENSITIVE
diff --git a/src/utils/private-mode.ts b/src/utils/private-mode.ts
index 3fdcb088..1af82c3c 100644
--- a/src/utils/private-mode.ts
+++ b/src/utils/private-mode.ts
@@ -1,10 +1,10 @@
 /**
  * Permission enforcement for the files the CLI keeps private.
  *
- * The 0600 file mode and 0700 directory mode are applied when the CLI creates
- * them and were never checked again, so a config file restored from a backup,
- * copied by another tool, or written by hand kept whatever mode it arrived
- * with — and `config.json` holds the API key in plaintext.
+ * The 0600 file mode and 0700 directory mode applied when the CLI creates them
+ * are not enough on their own: a config file restored from a backup, copied by
+ * another tool, or written by hand carries whatever mode it arrived with — and
+ * `config.json` holds the API key in plaintext.
  */
 
 import * as fs from 'fs';
diff --git a/src/utils/text-preservation.ts b/src/utils/text-preservation.ts
index 064a42a8..f0e25589 100644
--- a/src/utils/text-preservation.ts
+++ b/src/utils/text-preservation.ts
@@ -8,13 +8,13 @@ import { NetworkError } from './errors.js';
 /**
  * The next placeholder token that does not already occur in `text`.
  *
- * The tokens are generated from a counter, so a source string carrying a literal
- * `__VAR_0__` — which is ordinary text, not a variable — could be handed the same
- * token as a real variable. Two occurrences then went to the engine and
- * `restorePlaceholders` uses `replaceAll`, so the literal copy was rewritten into
- * the preserved value. The same collision made `unresolvedPlaceholders` accept
- * the literal copy as proof the substituted token had survived, reporting a
- * genuine loss as intact.
+ * The tokens are generated by a counter, so a source string carrying a literal
+ * `__VAR_0__` — which is ordinary text, not a variable — could otherwise be
+ * handed the same token as a real variable. Two occurrences would then reach the
+ * engine: `restorePlaceholders` uses `replaceAll`, so the literal copy would be
+ * rewritten into the preserved value, and `unresolvedPlaceholders` would accept
+ * that copy as proof the substituted token had survived, reporting a genuine loss
+ * as intact.
  *
  * Compared against the ORIGINAL text, never the partly-substituted text: tokens
  * this pass has already created are absent from the original, so they are not

From 771af523fc795a93789e1b0dc8b6b319819d9ad9 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Sun, 9 Aug 2026 22:43:30 +0200
Subject: [PATCH 235/256] docs(comments): correct the test header docblocks
 that misdescribe their suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Header docblocks only -- no test body, title or assertion is touched. This repo
uses them deliberately to say what a suite is about, so length was not the test;
accuracy was. Of the 245 suites carrying one, 30 changed and the rest were read
and left alone.

Three carried a bead ID (`cli-8kr2.59`, `.60`, `.42`) and one carried `sync-qsn`.
Those now name the behaviour the suite pins, which is what a reader needed from
the reference.

Four made a claim the suite contradicts:

  * voice-stream-session said it covers "SIGINT handling"; the suite asserts the
    session registers no SIGINT listener at all.
  * cli-document-translation and cli-structured-file-translate each claimed CLI-
    level coverage. Neither spawns a subprocess; both point at the e2e suite that
    does.
  * cli-sync-init said the JSON error envelope goes to stderr. It goes to stdout.

The rest had a past-session defect story where the invariant belonged.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../e2e/cli-sync-bilingual-target.e2e.test.ts | 14 ++++++-------
 tests/e2e/cli-sync-control-chars.e2e.test.ts  |  3 ++-
 tests/e2e/cli-sync-init.e2e.test.ts           |  7 ++++---
 tests/e2e/cli-sync-new-source-key.e2e.test.ts |  3 ++-
 tests/helpers/sync-harness.ts                 |  3 ---
 ...i-document-translation.integration.test.ts |  3 ++-
 ...uctured-file-translate.integration.test.ts |  4 +++-
 .../cli-translate.integration.test.ts         |  7 +++++--
 .../integration/sync-init.integration.test.ts |  4 +++-
 tests/unit/cache-loader.test.ts               |  3 ++-
 tests/unit/cli-no-args-exit.test.ts           |  3 ++-
 tests/unit/concurrency-limiting.test.ts       | 12 ++++++-----
 tests/unit/dry-run.test.ts                    |  3 ++-
 tests/unit/errors.test.ts                     |  9 +++++---
 tests/unit/formats/roundtrip.test.ts          |  5 +++--
 tests/unit/formats/toml-sections.test.ts      |  8 +++----
 tests/unit/formats/xcstrings-arb.test.ts      | 11 +++++-----
 tests/unit/formats/xliff-attributes.test.ts   | 14 ++++++-------
 tests/unit/http-retry-policy.test.ts          |  4 ++--
 tests/unit/icu-multiple-blocks.test.ts        |  9 ++++----
 tests/unit/placeholder-postcondition.test.ts  | 16 +++++++-------
 tests/unit/retry-after-blank.test.ts          | 12 ++++++-----
 .../unit/services/cache-key-endpoint.test.ts  | 10 ++++-----
 .../translate-batch-skip-cache.test.ts        | 17 +++++++--------
 .../translate-batch-sparse-contract.test.ts   | 16 +++++++-------
 .../sync-forbidden-target-segments.test.ts    | 12 +++++------
 tests/unit/sync/sync-tms.test.ts              |  3 ++-
 tests/unit/text-preservation-loop.test.ts     | 21 ++++++++++---------
 tests/unit/utils/canonical-path-key.test.ts   |  6 +++---
 tests/unit/voice-stream-session.test.ts       |  9 ++++++--
 tests/unit/write-client.test.ts               |  4 +++-
 31 files changed, 142 insertions(+), 113 deletions(-)

diff --git a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
index 997eef0a..ce7d4c4d 100644
--- a/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
+++ b/tests/e2e/cli-sync-bilingual-target.e2e.test.ts
@@ -1,13 +1,13 @@
 /**
- * E2E regression for cli-8kr2.59.
+ * E2E cover for the translations `deepl sync` reads back out of a bilingual
+ * target file.
  *
  * PO and XLIFF carry both the source and the translation in one file, and their
- * `extract().value` is the source. `sync` built its "translations the target
- * file already has" map from that value, so on any run that rewrote the file —
- * one where a sibling key is new — a `current` key had the msgid carried
- * forward into its own msgstr. A reviewed translation became English, silently,
- * at exit 0, and the lockfile still called the key translated so no later run
- * corrected it.
+ * `extract().value` is the source, not the translation. A run that rewrites the
+ * file because a sibling key is new must therefore not take its "translations
+ * the target already has" map from that value: doing so carries the msgid
+ * forward into its own msgstr, replacing a reviewed translation with English at
+ * exit 0 while the lockfile still calls the key translated.
  */
 
 import { spawn, spawnSync, ChildProcess } from 'child_process';
diff --git a/tests/e2e/cli-sync-control-chars.e2e.test.ts b/tests/e2e/cli-sync-control-chars.e2e.test.ts
index 4b7f45ba..53a79ff3 100644
--- a/tests/e2e/cli-sync-control-chars.e2e.test.ts
+++ b/tests/e2e/cli-sync-control-chars.e2e.test.ts
@@ -1,5 +1,6 @@
 /**
- * E2E regression for the TOML self-DoS in cli-8kr2.42.
+ * E2E regression for the TOML self-DoS a control character in a committed
+ * target value causes.
  *
  * A contributor can commit a *valid* `locales/app.de.toml` holding
  * `greeting = "Hola"` — TOML basic strings legally carry `\uXXXX`, and
diff --git a/tests/e2e/cli-sync-init.e2e.test.ts b/tests/e2e/cli-sync-init.e2e.test.ts
index 53403187..0280775d 100644
--- a/tests/e2e/cli-sync-init.e2e.test.ts
+++ b/tests/e2e/cli-sync-init.e2e.test.ts
@@ -4,10 +4,11 @@
  * When the detector finds zero i18n files the command must:
  *   - exit 7 (ConfigError) — not 0
  *   - print a remediation hint naming all four required flags
- *   - in --format json mode emit the canonical error envelope to stderr
+ *   - in --format json mode emit the canonical error envelope to stdout, the
+ *     one stream a consumer can parse whole
  *
- * Regression guard: successful interactive-equivalent path (all four flags
- * supplied, stdin not a TTY) must still exit 0.
+ * The successful interactive-equivalent path (all four flags supplied, stdin
+ * not a TTY) must still exit 0.
  */
 
 import { spawnSync } from 'child_process';
diff --git a/tests/e2e/cli-sync-new-source-key.e2e.test.ts b/tests/e2e/cli-sync-new-source-key.e2e.test.ts
index 183c6d06..c9021945 100644
--- a/tests/e2e/cli-sync-new-source-key.e2e.test.ts
+++ b/tests/e2e/cli-sync-new-source-key.e2e.test.ts
@@ -1,5 +1,6 @@
 /**
- * E2E regression for cli-8kr2.60.
+ * E2E regression for a key added to the source catalog after the first sync
+ * run.
  *
  * `deepl sync` uses an existing target file as the reconstruct template, so a
  * key added to the source after the first run has no slot in it. Five parsers
diff --git a/tests/helpers/sync-harness.ts b/tests/helpers/sync-harness.ts
index d6cd2e5e..ad6fbc1e 100644
--- a/tests/helpers/sync-harness.ts
+++ b/tests/helpers/sync-harness.ts
@@ -5,9 +5,6 @@
  *   - createSyncHarness()   -> wires up SyncService with the real deps and mock config/cache
  *   - buildSyncConfigYaml() -> serializes a .deepl-sync.yaml document from a plain object
  *   - seedLockFile()        -> writes a valid .deepl-sync.lock to a test project root
- *
- * These replace ad-hoc template strings and duplicated service-wiring code that
- * accumulated across the sync integration tests.
  */
 
 import * as fs from 'fs';
diff --git a/tests/integration/cli-document-translation.integration.test.ts b/tests/integration/cli-document-translation.integration.test.ts
index 81239e34..bdab7513 100644
--- a/tests/integration/cli-document-translation.integration.test.ts
+++ b/tests/integration/cli-document-translation.integration.test.ts
@@ -1,7 +1,8 @@
 /**
  * Integration Tests for Document Translation Workflow
  * Tests the multi-step upload -> poll -> download flow with nock HTTP mocking.
- * Validates API interaction contracts at both service and CLI levels.
+ * Every case is service-level; CLI flag and exit-code behavior lives in
+ * tests/e2e/cli-document-translation.e2e.test.ts.
  */
 
 import nock from 'nock';
diff --git a/tests/integration/cli-structured-file-translate.integration.test.ts b/tests/integration/cli-structured-file-translate.integration.test.ts
index 027dcf24..f3c6b761 100644
--- a/tests/integration/cli-structured-file-translate.integration.test.ts
+++ b/tests/integration/cli-structured-file-translate.integration.test.ts
@@ -1,6 +1,8 @@
 /**
  * Integration Tests for Structured File (JSON/YAML) Translation
- * Tests both CLI argument validation (via subprocess) and service-level integration (in-process)
+ * Drives FileTranslationService in-process against nock. CLI argument
+ * validation and the exit codes of the built binary live in
+ * tests/e2e/cli-structured-file.e2e.test.ts.
  */
 
 import * as fs from 'fs';
diff --git a/tests/integration/cli-translate.integration.test.ts b/tests/integration/cli-translate.integration.test.ts
index 89fe7751..c6051527 100644
--- a/tests/integration/cli-translate.integration.test.ts
+++ b/tests/integration/cli-translate.integration.test.ts
@@ -1,6 +1,9 @@
 /**
- * Integration Tests for Translation Memory wiring on `deepl translate`
- * Drives handler -> resolver -> service -> HTTP in-process against nock.
+ * Integration Tests for Translation Memory and glossary wiring on
+ * `deepl translate`
+ * Drives handler -> resolver -> service -> HTTP in-process against nock, so the
+ * assertions are on the request body — including the order several glossaries
+ * are sent in, since that order decides which one wins.
  * CLI flag handling lives in tests/e2e/cli-translate-flags.e2e.test.ts.
  */
 
diff --git a/tests/integration/sync-init.integration.test.ts b/tests/integration/sync-init.integration.test.ts
index 2033ea72..4e199034 100644
--- a/tests/integration/sync-init.integration.test.ts
+++ b/tests/integration/sync-init.integration.test.ts
@@ -3,7 +3,9 @@
  *
  * Uses REAL fast-glob (not mocked) against real filesystem structures
  * to verify that detectI18nFiles() produces include patterns that
- * actually match source files — the exact bug that sync-qsn reported.
+ * actually match source files: a pattern that is syntactically plausible but
+ * matches nothing yields a config that detects an i18n project and then syncs
+ * no keys at all.
  */
 
 jest.unmock('fast-glob');
diff --git a/tests/unit/cache-loader.test.ts b/tests/unit/cache-loader.test.ts
index 04b4ffb6..821633cd 100644
--- a/tests/unit/cache-loader.test.ts
+++ b/tests/unit/cache-loader.test.ts
@@ -1,5 +1,6 @@
 /**
- * Tests for the lazy cache-service getter used by the CLI entry point.
+ * Tests for the cache wiring used by the CLI entry point: the translation of
+ * config values into cache-service options, and the lazy getter around them.
  * A cache backend that cannot load must degrade to "no cache" with a
  * single warning, not crash the command or retry on every call.
  */
diff --git a/tests/unit/cli-no-args-exit.test.ts b/tests/unit/cli-no-args-exit.test.ts
index 6883cdef..b4d0047c 100644
--- a/tests/unit/cli-no-args-exit.test.ts
+++ b/tests/unit/cli-no-args-exit.test.ts
@@ -1,7 +1,8 @@
 /**
  * Tests for CLI exit code when no arguments provided.
  *
- * Validates that running 'deepl' with no arguments exits with code 0.
+ * Validates that running 'deepl' with no arguments prints help and exits
+ * with code 0.
  */
 
 import { execSync } from 'child_process';
diff --git a/tests/unit/concurrency-limiting.test.ts b/tests/unit/concurrency-limiting.test.ts
index d33dbb50..ae0778b4 100644
--- a/tests/unit/concurrency-limiting.test.ts
+++ b/tests/unit/concurrency-limiting.test.ts
@@ -1,10 +1,12 @@
 /**
- * Tests that concurrency is genuinely bounded.
+ * Tests that concurrency is genuinely bounded, and that mapWithConcurrency
+ * processes every item without exceeding the requested limit.
  *
- * These deliberately do NOT mock p-limit. A manual mock under
- * tests/__mocks__/p-limit.ts is auto-applied repo-wide, which would leave
- * real concurrency limits unexercised everywhere. The first test here fails
- * if such a mock is ever introduced.
+ * These deliberately do NOT mock p-limit or fast-glob. A manual mock placed
+ * under tests/__mocks__/ is auto-applied repo-wide, so one for either package
+ * would leave real concurrency limits and every glob-walking path unexercised
+ * everywhere. The first test in each of those two blocks fails if such a mock
+ * is ever introduced.
  */
 
 import pLimit from 'p-limit';
diff --git a/tests/unit/dry-run.test.ts b/tests/unit/dry-run.test.ts
index 41202731..538a8aa3 100644
--- a/tests/unit/dry-run.test.ts
+++ b/tests/unit/dry-run.test.ts
@@ -1,6 +1,7 @@
 /**
  * Tests for --dry-run flag across CLI commands
- * Tests translate (file/directory), glossary delete, cache clear, and watch commands
+ * Tests translate (text/file/directory), glossary delete, cache clear, and
+ * watch commands
  */
 
 import { Command } from 'commander';
diff --git a/tests/unit/errors.test.ts b/tests/unit/errors.test.ts
index 8554df47..9598ae7d 100644
--- a/tests/unit/errors.test.ts
+++ b/tests/unit/errors.test.ts
@@ -1,7 +1,10 @@
 /**
- * Typed DeepLCLIError subclasses — symmetry checks across the error
- * taxonomy. The classifier tests live in tests/unit/exit-codes.test.ts;
- * this file asserts the class contracts that exit-code dispatch leans on.
+ * The sync-specific DeepLCLIError subclasses (SyncConflictError,
+ * SyncDriftError, SyncPartialFailureError) — symmetry checks across that
+ * corner of the error taxonomy: exit code, instanceof, the `name` the JSON
+ * error envelope publishes, and the default vs custom suggestion. The
+ * classifier itself is tested in tests/unit/exit-codes.test.ts; this file
+ * asserts the class contracts that exit-code dispatch leans on.
  */
 
 import {
diff --git a/tests/unit/formats/roundtrip.test.ts b/tests/unit/formats/roundtrip.test.ts
index 6724d824..d24e56b7 100644
--- a/tests/unit/formats/roundtrip.test.ts
+++ b/tests/unit/formats/roundtrip.test.ts
@@ -1,8 +1,9 @@
 /**
  * Round-trip stability tests: extract -> reconstruct -> extract must be a
  * fixed point. A parser that is not idempotent corrupts a little more on
- * every `deepl sync` run, which is how entity double-escaping went
- * unnoticed — a single run looks almost right.
+ * every `deepl sync` run, and a single run looks almost right, so drift of
+ * this kind — entity double-escaping above all — is easy to miss without a
+ * test that syncs the same content repeatedly.
  */
 
 import { AndroidXmlFormatParser } from '../../../src/formats/android-xml';
diff --git a/tests/unit/formats/toml-sections.test.ts b/tests/unit/formats/toml-sections.test.ts
index bc4968fb..66924265 100644
--- a/tests/unit/formats/toml-sections.test.ts
+++ b/tests/unit/formats/toml-sections.test.ts
@@ -1,10 +1,10 @@
 /**
  * Tests that new TOML keys land in the right section.
  *
- * New keys were appended at end of file using their full dotted path while
- * the last `[section]` header was still in scope, so `messages.newkey`
- * parsed back as `messages.messages.newkey`. Because the intended key was
- * then still missing, it was re-appended on every subsequent sync run.
+ * A key appended at end of file carries its full dotted path while the last
+ * `[section]` header is still in scope, so `messages.newkey` parses back as
+ * `messages.messages.newkey` — and because the intended key is then still
+ * missing, every subsequent sync run appends it again.
  */
 
 import { TomlFormatParser } from '../../../src/formats/toml';
diff --git a/tests/unit/formats/xcstrings-arb.test.ts b/tests/unit/formats/xcstrings-arb.test.ts
index 732ba198..284394c8 100644
--- a/tests/unit/formats/xcstrings-arb.test.ts
+++ b/tests/unit/formats/xcstrings-arb.test.ts
@@ -1,9 +1,10 @@
 /**
- * Tests for two localized-resource defects:
- *  - Xcode String Catalogs: reconstruct replaced a locale's entire
- *    localization object, destroying pre-existing plural `variations`.
- *  - ARB: a UTF-8 BOM made JSON.parse throw, so a BOM-prefixed Flutter
- *    resource file could not be read at all.
+ * Tests for two localized-resource invariants:
+ *  - Xcode String Catalogs: writing one locale's translation leaves the rest
+ *    of that key's localization object intact — plural `variations` above all
+ *    — and leaves the other locales alone.
+ *  - ARB: a UTF-8 BOM does not stop a Flutter resource file being extracted or
+ *    reconstructed, and yields the same entries as the same file without one.
  */
 
 import { XcstringsFormatParser } from '../../../src/formats/xcstrings';
diff --git a/tests/unit/formats/xliff-attributes.test.ts b/tests/unit/formats/xliff-attributes.test.ts
index f84408a1..78a2d304 100644
--- a/tests/unit/formats/xliff-attributes.test.ts
+++ b/tests/unit/formats/xliff-attributes.test.ts
@@ -1,13 +1,13 @@
 /**
  * Tests that XLIFF elements carrying attributes are handled.
  *
- * `state` is a standard XLIFF attribute that every CAT tool writes, but
- * SEGMENT_RE and TARGET_RE required bare `<segment>` / `<target>` tags. The
- * consequences were severe and silent: for XLIFF 2.0, extract returned no
- * entries and reconstruct then deleted every `<unit>`; for XLIFF 1.2, an
- * existing `<target state="...">` was treated as absent and a second
- * `<target>` was injected, producing schema-invalid output that retained
- * the stale translation.
+ * `state` is a standard XLIFF attribute that every CAT tool writes, so
+ * SEGMENT_RE and TARGET_RE have to match a tag carrying attributes and not
+ * only a bare `<segment>` / `<target>`. The failures otherwise are severe and
+ * silent: for XLIFF 2.0, extract returns no entries and reconstruct then
+ * deletes every `<unit>`; for XLIFF 1.2, an existing `<target state="...">`
+ * reads as absent and a second `<target>` is injected, producing
+ * schema-invalid output that retains the stale translation.
  */
 
 import { XliffFormatParser } from '../../../src/formats/xliff';
diff --git a/tests/unit/http-retry-policy.test.ts b/tests/unit/http-retry-policy.test.ts
index 63508caa..4a6b4c38 100644
--- a/tests/unit/http-retry-policy.test.ts
+++ b/tests/unit/http-retry-policy.test.ts
@@ -1,8 +1,8 @@
 /**
  * Retry-policy and transport-error classification tests for HttpClient.
  *
- * Every assertion here counts SERVER-SIDE requests: a replay of a
- * non-idempotent request is only observable from the server's side, so
+ * The retry assertions count SERVER-SIDE requests: a replay of a
+ * non-idempotent request is only observable on the server's side, so
  * `.rejects.toThrow()` alone cannot catch it.
  */
 
diff --git a/tests/unit/icu-multiple-blocks.test.ts b/tests/unit/icu-multiple-blocks.test.ts
index ae90117a..cab94357 100644
--- a/tests/unit/icu-multiple-blocks.test.ts
+++ b/tests/unit/icu-multiple-blocks.test.ts
@@ -1,10 +1,11 @@
 /**
  * A string may contain more than one ICU block.
  *
- * Detection found one block and pushed the whole remaining suffix as a single
- * prose segment, so every block after the first was submitted to the MT engine
- * as translatable text — the exact exposure the module exists to prevent. The
- * engine translates the keyword and the selectors:
+ * Detection must find all of them rather than stopping at the first and
+ * pushing the remaining suffix on as a single prose segment: that submits
+ * every later block to the MT engine as translatable text — the exact exposure
+ * the module exists to prevent. The engine translates the keyword and the
+ * selectors:
  *
  *   in  You have {n, plural, one {# item} other {# items}} and
  *       {m, plural, one {# gift} other {# gifts}} waiting.
diff --git a/tests/unit/placeholder-postcondition.test.ts b/tests/unit/placeholder-postcondition.test.ts
index a5fed1d3..9c8845f4 100644
--- a/tests/unit/placeholder-postcondition.test.ts
+++ b/tests/unit/placeholder-postcondition.test.ts
@@ -1,13 +1,13 @@
 /**
- * `restorePlaceholders` replaced the placeholders it could find and silently
- * left the rest alone, with nothing verifying that the tokens the CLI injected
- * came back intact. Re-casing or re-spacing an unknown token is ordinary MT
- * behaviour, so `__VAR_0__` returning as `__ Var_0 __` wrote the CLI's own
- * internal scaffolding into the user's file — or printed it to stdout — at
- * exit 0 with no warning.
+ * Every translate path must check that the placeholder tokens the CLI injected
+ * came back intact. `restorePlaceholders` replaces the ones it can find and
+ * leaves the rest alone, and re-casing or re-spacing an unknown token is
+ * ordinary MT behaviour — so without the check, `__VAR_0__` returning as
+ * `__ Var_0 __` writes the CLI's own internal scaffolding into the user's file,
+ * or prints it to stdout, at exit 0 with no warning.
  *
- * The sync path already catches this in the placeholder validator. The three
- * translate paths had no validator at all.
+ * The sync path has its own placeholder validator; these are the three
+ * translate paths.
  */
 
 import {
diff --git a/tests/unit/retry-after-blank.test.ts b/tests/unit/retry-after-blank.test.ts
index 5a0d3336..b62fc27e 100644
--- a/tests/unit/retry-after-blank.test.ts
+++ b/tests/unit/retry-after-blank.test.ts
@@ -1,10 +1,12 @@
 /**
- * Tests Retry-After parsing for blank headers.
+ * Tests Retry-After parsing.
  *
- * `Number('')` is 0, which passed the finite check and produced a 0 ms delay.
- * Because 0 is a real number, the `retryAfterDelay ?? computeBackoffWithJitter`
- * fallback never engaged, so every 429 retry fired back-to-back against an
- * endpoint that was already rate-limiting the client.
+ * A blank header must read as absent, not as a delay. `Number('')` is 0, which
+ * satisfies a bare finite check, and because 0 is a real number the
+ * `retryAfterDelay ?? computeBackoffWithJitter` fallback would not engage —
+ * every 429 retry would then fire back-to-back against an endpoint already
+ * rate-limiting the client. A literal `0` is still honoured, so absent and zero
+ * have to stay distinguishable.
  */
 
 import { HttpClient } from '../../src/api/http-client';
diff --git a/tests/unit/services/cache-key-endpoint.test.ts b/tests/unit/services/cache-key-endpoint.test.ts
index 6c0faf5e..8f18d52e 100644
--- a/tests/unit/services/cache-key-endpoint.test.ts
+++ b/tests/unit/services/cache-key-endpoint.test.ts
@@ -1,11 +1,11 @@
 /**
  * The translation and write cache keys hash the request parameters, but the
  * resolved API endpoint is not a request parameter — and one cache DB is shared
- * by every endpoint a config dir has ever talked to. A single run against
- * `--api-url http://127.0.0.1:18111` therefore served its answers back for
- * api.deepl.com for the full 30-day TTL, with no network reachable at all.
- * Custom endpoints are a supported feature (proxies, regional endpoints), so
- * this needed no misuse to reach.
+ * by every endpoint a config dir has ever talked to. Unless the key carries the
+ * endpoint, a single run against `--api-url http://127.0.0.1:18111` has its
+ * answers served back for api.deepl.com for the full 30-day TTL, with no
+ * network reachable at all. Custom endpoints are a supported feature (proxies,
+ * regional endpoints), so this needs no misuse to reach.
  */
 
 import { TranslationService } from '../../../src/services/translation';
diff --git a/tests/unit/services/translate-batch-skip-cache.test.ts b/tests/unit/services/translate-batch-skip-cache.test.ts
index 581cce39..bd77886d 100644
--- a/tests/unit/services/translate-batch-skip-cache.test.ts
+++ b/tests/unit/services/translate-batch-skip-cache.test.ts
@@ -1,14 +1,13 @@
 /**
- * `--no-cache` was a silent no-op for all 11 structured i18n formats.
+ * `TranslationService.translateBatch()` takes its cache decision from the
+ * caller's `skipCache`, not from `cache.enabled` in persisted config alone.
  *
- * In one function 30 lines apart, the plain-text branch of the translate
- * command passed `skipCache: !options.cache` and the structured branch passed
- * only `{ preserveCode }` — because `TranslationService.translateBatch()` had
- * no service-options parameter at all and read `cache.enabled` from persisted
- * config alone. So a corrupt translation was permanent: re-running the
- * identical command with `--no-cache` against a different endpoint sent zero
- * requests and reproduced the poisoned output byte for byte, defeating the one
- * remedy a user would reach for.
+ * Every structured i18n format translates through this method, so without that
+ * parameter `--no-cache` is a silent no-op for all 11 of them — and a corrupt
+ * translation then becomes permanent: re-running the identical command with
+ * `--no-cache` against a different endpoint sends zero requests and reproduces
+ * the poisoned output byte for byte, defeating the one remedy a user would
+ * reach for.
  */
 
 import { TranslationService } from '../../../src/services/translation';
diff --git a/tests/unit/services/translate-batch-sparse-contract.test.ts b/tests/unit/services/translate-batch-sparse-contract.test.ts
index fa656ce1..829266a2 100644
--- a/tests/unit/services/translate-batch-sparse-contract.test.ts
+++ b/tests/unit/services/translate-batch-sparse-contract.test.ts
@@ -1,13 +1,13 @@
 /**
- * `translateBatch` returns one slot per input text, but leaves a slot `null`
- * both when a chunk request failed and when the input text was empty and
- * therefore never sent. Its declared return type was `TranslationResult[]`,
- * so no consumer was forced to handle either case: an empty i18n value crashed
- * structured file translation with a TypeError before any output was written,
- * and reached sync as a permanent per-key failure.
+ * `translateBatch` returns one slot per input text, and that array is sparse: a
+ * slot is `null` where the chunk request failed. An empty input text is not
+ * such a case — it is never sent, and round-trips as an empty translation, a
+ * result rather than a failure — so the null that remains means failure, and it
+ * is in the declared return type, which forces consumers to handle it. Left
+ * out of the type, an empty i18n value crashes structured file translation with
+ * a TypeError before any output is written, and reaches sync as a permanent
+ * per-key failure.
  *
- * An empty input now round-trips as an empty translation — a result, not a
- * failure — and the remaining null case is in the type.
  */
 
 import { StructuredFileTranslationService } from '../../../src/services/structured-file-translation';
diff --git a/tests/unit/sync/sync-forbidden-target-segments.test.ts b/tests/unit/sync/sync-forbidden-target-segments.test.ts
index 016d1d7c..dbed37b9 100644
--- a/tests/unit/sync/sync-forbidden-target-segments.test.ts
+++ b/tests/unit/sync/sync-forbidden-target-segments.test.ts
@@ -1,15 +1,15 @@
 /**
  * `FORBIDDEN_TARGET_SEGMENTS` exists so a translated-locale name can never
- * become VCS metadata or CI workflow code. It had exactly one enforcement
- * site — inside the `if (target_path_pattern !== undefined)` branch of config
- * validation — so a bucket that simply omitted `target_path_pattern` reached
- * the default locale-substitution path with no check at all:
+ * become VCS metadata or CI workflow code. Enforcing it only inside the
+ * `if (target_path_pattern !== undefined)` branch of config validation is not
+ * enough: a bucket that simply omits `target_path_pattern` reaches the default
+ * locale-substitution path, where nothing would check it:
  *
  *   buckets.yaml.include: ['.github/workflows/en.yml']
  *   -> sync writes .github/workflows/de.yml from API-returned bytes
  *
- * `assertPathWithinRoot` accepted it, because the path never leaves the
- * project root. The guard now lives on the resolved path at that shared
+ * `assertPathWithinRoot` accepts that, because the path never leaves the
+ * project root. The guard therefore lives on the resolved path at that shared
  * boundary, so every read and write in the sync pipeline inherits it —
  * including the multi-locale branch, which writes back to the source path and
  * never calls `resolveTargetPath` at all.
diff --git a/tests/unit/sync/sync-tms.test.ts b/tests/unit/sync/sync-tms.test.ts
index 3d276433..c06d29b5 100644
--- a/tests/unit/sync/sync-tms.test.ts
+++ b/tests/unit/sync/sync-tms.test.ts
@@ -8,7 +8,8 @@
  * must re-apply that partition, or skipped pipe-plural values reach
  * `TmsClient.pushKey(...)` and the pull-merge translation set. These tests
  * lock the invariant in at each inline extract point plus the runtime guard on
- * `TmsClient.pushEntry(...)`.
+ * `TmsClient.pushEntry(...)`, and cover the per-reason summary a run prints for
+ * what it skipped.
  */
 import * as path from 'path';
 
diff --git a/tests/unit/text-preservation-loop.test.ts b/tests/unit/text-preservation-loop.test.ts
index 457172a9..10d1452d 100644
--- a/tests/unit/text-preservation-loop.test.ts
+++ b/tests/unit/text-preservation-loop.test.ts
@@ -1,16 +1,17 @@
 /**
- * Tests that placeholder restoration terminates.
+ * Tests that placeholder restoration terminates, and still restores every
+ * ordinary placeholder while it does.
  *
- * restorePlaceholders looped `while (restored.includes(placeholder))`,
- * re-running a single `replace` each pass. When the preserved original itself
- * contained the placeholder token, every pass re-inserted it: the guard never
- * went false and the string grew by the original's length forever.
+ * restorePlaceholders must not loop on `restored.includes(placeholder)` while
+ * re-running a single `replace` each pass: when the preserved original itself
+ * contains the placeholder token, every pass re-inserts it, so the guard never
+ * goes false and the string grows by the original's length forever.
  *
- * `preserveVariables`' pattern is `/\{[\p{L}\p{N}_]+\}/u`, which matches
- * `{__VAR_0__}` because underscores and digits are in the class — so a locale
- * file containing a token of that shape triggers it, and because variable
- * preservation runs unconditionally and restoration also runs on cached
- * results, it hangs with no API call at all.
+ * That input is reachable. `preserveVariables`' pattern is
+ * `/\{[\p{L}\p{N}_]+\}/u`, which matches `{__VAR_0__}` because underscores and
+ * digits are in the class — so a locale file containing a token of that shape
+ * triggers it, and because variable preservation runs unconditionally and
+ * restoration also runs on cached results, the hang needs no API call at all.
  */
 
 import {
diff --git a/tests/unit/utils/canonical-path-key.test.ts b/tests/unit/utils/canonical-path-key.test.ts
index 4024f9b2..d5a8a008 100644
--- a/tests/unit/utils/canonical-path-key.test.ts
+++ b/tests/unit/utils/canonical-path-key.test.ts
@@ -4,9 +4,9 @@
  *
  * `fs.realpathSync` does not case-fold on a case-insensitive volume — APFS
  * returns `Docs` for `Docs` even when the directory is stored as `docs` — and
- * does not unify NFC with NFD. Two spellings reaching the same inode therefore
- * produced different keys, and `watch --git-staged` translated nothing when git
- * spelled a directory differently from the watcher: silently, at exit 0.
+ * does not unify NFC with NFD. Two spellings reaching the same inode still have
+ * to produce one key, or `watch --git-staged` translates nothing when git
+ * spells a directory differently from the watcher: silently, at exit 0.
  */
 
 import * as fs from 'fs';
diff --git a/tests/unit/voice-stream-session.test.ts b/tests/unit/voice-stream-session.test.ts
index 84f0e84e..f0e9001d 100644
--- a/tests/unit/voice-stream-session.test.ts
+++ b/tests/unit/voice-stream-session.test.ts
@@ -1,7 +1,12 @@
 /**
  * Tests for VoiceStreamSession
- * Covers WebSocket lifecycle, reconnection, SIGINT handling, chunk streaming,
- * and transcript accumulation directly on the extracted class.
+ * Covers WebSocket lifecycle, reconnection, chunk streaming, transcript
+ * accumulation, callback proxying, and rejection of a stream that transcribed
+ * source audio but produced no text for a target — all directly on the
+ * extracted class.
+ *
+ * The session deliberately registers no SIGINT listener of its own; whichever
+ * caller owns the signal stops it through cancel().
  */
 
 import {
diff --git a/tests/unit/write-client.test.ts b/tests/unit/write-client.test.ts
index 8b6577a0..23fd0648 100644
--- a/tests/unit/write-client.test.ts
+++ b/tests/unit/write-client.test.ts
@@ -1,6 +1,8 @@
 /**
  * Tests for WriteClient
- * Covers improveText with success/error cases
+ * Covers improveText and correctText with their success and error cases,
+ * including the documentation hint appended to a 400 only when a writing style
+ * or tone was sent.
  */
 
 import { WriteClient } from '../../src/api/write-client.js';

From a9b5218a8858b87568a12ae2277f87c96814fbe3 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 00:20:00 +0200
Subject: [PATCH 236/256] docs(migration): add a v2 migration guide and link it
 from the README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`grep -in 'breaking|migrat'` over README.md, docs/API.md, docs/SYNC.md and
docs/TROUBLESHOOTING.md returned zero hits against a release with five BREAKING
changes and 53 Changed entries. The CHANGELOG has all of it, but nobody reads a
changelog to find out why their script broke.

docs/MIGRATION.md is organised by what breaks in a caller's setup rather than by
command: requirements, removed flags and config keys, exit codes that moved,
machine-readable output moving to stdout, output that scripts parse, files written
to disk, tagged output, and the published TypeScript types. Each item has a
before/after, and the checklist at the end is the short version. Linked from the
README's Documentation list, its table of contents, and a short "Upgrading from
1.x" section under Installation, which is where someone upgrading actually lands.

Two corrections came out of verifying the claims by execution rather than trusting
the CHANGELOG:

  * an unknown option exits **6**, not 1. The BREAKING entry for the removed
    `sync init --source-lang` / `--target-langs` aliases predates the parse-error
    remapping later in this same release, which moved subcommand parse errors from
    1 to 6; that entry is corrected here too.
  * language codes are lowercase for `glossary` as well. An earlier entry says
    `glossary create`/`show` render them uppercase, which d15bc89 superseded --
    glossary.ts lowercases at display time -- so the guide documents the sweep and
    not the exception.

Also verified by execution: a retired `tms.*` key exits 7 with the replacement in
its suggestion, and `sync --force` without `--yes` exits 6 on closed stdin. The
Language union went 121 -> 125 with nothing removed (`de-ch`, `de-de`, `fr-ca`,
`fr-fr` added), while `WriteLanguage` did lose members to lowercasing, which is why
the guide calls the type change out.

docs/MIGRATION.md is deliberately absent from the documented-surface test's DOCS
list: it is the one document that must name flags this CLI no longer accepts, so
those checks would fail it by design. The DOCS array now says so.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                               |   2 +-
 README.md                                  |  10 +
 docs/MIGRATION.md                          | 296 +++++++++++++++++++++
 tests/unit/docs/documented-surface.test.ts |   5 +
 4 files changed, 312 insertions(+), 1 deletion(-)
 create mode 100644 docs/MIGRATION.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ac71ba5e..f3edca58 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -165,7 +165,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **deps**: `better-sqlite3` and `@types/better-sqlite3`. The production dependency tree no longer contains any native addon, removing the entire class of ABI-mismatch failures (`ERR_DLOPEN_FAILED` / `NODE_MODULE_VERSION` errors after a Node major upgrade, e.g. via `brew upgrade node`), a 1.9 MB platform-specific binary, and the C++ compilation-toolchain requirement for installs from source. The cacheless-degradation safety net remains: a runtime whose `node:sqlite` is missing (Node < 22.5.0) warns once and runs uncached rather than crashing, and never touches the cache database.
 
-- **BREAKING — sync**: `deepl sync init --source-lang` and `--target-langs`, the deprecated aliases introduced in 1.x, are removed and now fail with `unknown option` (exit 1). Use `--source-locale` and `--target-locales`. This is the documented removal of 1.x aliases at the 2.0 cut. `deepl translate --target-lang` is unaffected — it is the API's wire name, not a deprecated alias.
+- **BREAKING — sync**: `deepl sync init --source-lang` and `--target-langs`, the deprecated aliases introduced in 1.x, are removed and now fail with `error: unknown option` (exit 6, per the subcommand parse-error mapping also in this release). Use `--source-locale` and `--target-locales`. This is the documented removal of 1.x aliases at the 2.0 cut. `deepl translate --target-lang` is unaffected — it is the API's wire name, not a deprecated alias.
 
 ### Fixed
 
diff --git a/README.md b/README.md
index 354d06a0..1fad9aa1 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,7 @@ For security policy and vulnerability reporting, see [SECURITY.md](SECURITY.md).
 ## 📋 Table of Contents
 
 - [Installation](#-installation)
+- [Upgrading from 1.x](#-upgrading-from-1x)
 - [Quick Start](#-quick-start)
 - [Global Options](#-global-options)
   - [Verbose Mode](#verbose-mode)
@@ -101,6 +102,14 @@ npm link
 deepl --version
 ```
 
+## 🔀 Upgrading from 1.x
+
+2.0.0 requires Node 24, renames the package to `@deepl/cli`, removes several
+deprecated flags, and changes a number of exit codes and output shapes that scripts
+read. If you have a pipeline built on 1.x, read
+**[docs/MIGRATION.md](./docs/MIGRATION.md)** before upgrading — it lists every
+change that needs action, with a before/after for each.
+
 ## 🚀 Quick Start
 
 ### 1. Get Your DeepL API Key
@@ -1668,6 +1677,7 @@ npm run examples:fast
 ## 📚 Documentation
 
 - **[API Reference](./docs/API.md)** - Complete API reference with all commands, flags, and options
+- **[Migrating from 1.x](./docs/MIGRATION.md)** - Removed flags, changed exit codes, and output that scripts parse
 - **[Sync Guide](./docs/SYNC.md)** - Continuous localization: `.deepl-sync.yaml` configuration, lockfile model, CI/CD recipes, TMS integration
 - **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues, solutions, and exit codes reference
 - **[Examples](./examples/README.md)** - Practical usage examples for every feature
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
new file mode 100644
index 00000000..7ca52aef
--- /dev/null
+++ b/docs/MIGRATION.md
@@ -0,0 +1,296 @@
+# Migrating from 1.x to 2.0.0
+
+This release removes deprecated flags, changes several exit codes, and moves
+machine-readable output from stderr to stdout. Nothing here is a silent change of
+meaning: every item below either fails loudly or changes a value you can see.
+
+**If you only read one section, read [Exit codes that moved](#exit-codes-that-moved).**
+It is the change most likely to alter what your CI pipeline decides, and unlike a
+removed flag it does not announce itself.
+
+## Contents
+
+- [Requirements](#requirements)
+- [Removed flags and config keys](#removed-flags-and-config-keys)
+- [Exit codes that moved](#exit-codes-that-moved)
+- [Machine-readable output moved to stdout](#machine-readable-output-moved-to-stdout)
+- [Output that scripts parse](#output-that-scripts-parse)
+- [Files written to disk](#files-written-to-disk)
+- [Tagged translation output](#tagged-translation-output)
+- [TypeScript consumers](#typescript-consumers)
+- [Upgrade checklist](#upgrade-checklist)
+
+## Requirements
+
+**Node.js 24 or later** — up from 20. The cache now uses Node's built-in
+`node:sqlite` instead of the `better-sqlite3` native addon, so there is no
+compilation step and no `ERR_DLOPEN_FAILED` after a Node upgrade, but the runtime
+floor is higher. Running under an older Node fails fast with a one-line error and
+exit 6 rather than crashing later.
+
+**The package is published as `@deepl/cli`.** The command is still `deepl`.
+
+```bash
+# 1.x
+npm install -g deepl-cli
+
+# 2.0.0
+npm install -g @deepl/cli
+```
+
+Your cache and config are untouched by the rename. The cache database is upgraded
+in place on first open: rows whose keys can no longer be reached are dropped and
+every other namespace is left alone, so the first translation after upgrading may
+be a miss where it used to be a hit.
+
+## Removed flags and config keys
+
+All of these fail immediately, so nothing here can pass silently.
+
+| Removed | Replacement | Symptom |
+| --- | --- | --- |
+| `translate --enable-beta-languages` | Delete it — beta languages are part of the regular language set | `error: unknown option`, exit 6 |
+| `sync init --source-lang` | `--source-locale` | `error: unknown option`, exit 6 |
+| `sync init --target-langs` | `--target-locales` | `error: unknown option`, exit 6 |
+| `tms.auto_push` | Run `deepl sync push` after `deepl sync` | `ConfigError`, exit 7 |
+| `tms.auto_pull` | Run `deepl sync pull` before `deepl sync` | `ConfigError`, exit 7 |
+| `tms.require_review` | Preview with `deepl sync pull --dry-run` | `ConfigError`, exit 7 |
+
+```bash
+# 1.x
+deepl sync init --source-lang en --target-langs es,fr
+
+# 2.0.0
+deepl sync init --source-locale en --target-locales es,fr
+```
+
+The three `tms:` keys were on the config allowlist and in the documentation but no
+code ever read them, so a review gate you configured was doing nothing. They are
+rejected by name — with the replacement in the error's suggestion — rather than as
+unknown fields, so the message cannot be mistaken for a typo.
+
+```yaml
+# 1.x — accepted and ignored
+tms:
+  enabled: true
+  server: https://tms.example.com
+  auto_push: true
+  require_review: true
+
+# 2.0.0 — remove both; push explicitly instead
+tms:
+  enabled: true
+  server: https://tms.example.com
+```
+
+Also gone: the `usage` command's "Speech-to-Text Usage" section and
+`speechToTextMilliseconds*` fields, following the API's deprecation of
+`speech_to_text_milliseconds_count`/`_limit`.
+
+## Exit codes that moved
+
+Most of these are conditions that used to exit 0 while losing or skipping work,
+saying so only in a log line. A few move the other way, where 1.x failed on input it
+should have accepted. In both directions the old code was the wrong answer.
+
+| Command | Condition | 1.x | 2.0.0 |
+| --- | --- | --- | --- |
+| `sync` | Target file unreadable or unparseable | 0 | 12 |
+| `sync` | Key could not be written into the target | 0 | 12 |
+| `sync` | Validation error on a translation | 0 | 12 |
+| `sync` | File containing an empty string value | 12, every run | 0 |
+| `sync validate` | Target file cannot be read | 1 | 8 |
+| `sync validate` | PO/XLIFF project with untranslated keys | 0 | 8 |
+| `sync push` / `pull` | TMS unreachable | 1 | 5 |
+| `sync --force` | Cannot prompt (piped stdin, cron, hook, `--no-input`) | 0 | 6 |
+| `watch` | Session recorded any failure | 0 | 12 |
+| `watch --auto-commit` | Output directory in no git repository | 0 | 6, at startup |
+| `translate` | Translation lost one of your placeholders | 0, with output | 5 |
+| `translate <file>` | File containing an empty string value | 1 | 0 |
+| `translate <file>` | Rate limit part-way through a structured file | 1 | 3 |
+| `write --check --format json` | Text needs no changes | 8, always | 0 |
+
+Three of these deserve a note:
+
+- **`sync --force` now needs `--yes` anywhere it cannot prompt**, not only under
+  `CI=true`. Add `--yes` to any invocation from a git hook, cron job, `make`
+  target or container entrypoint.
+- **`write --check --format json` could never pass in 1.x** — the verdict was
+  computed against a rendered JSON document. A gate built on it was either
+  unconditionally red or green only because a later step ignored the code. It now
+  returns the truthful answer, which means it will start passing.
+- **`translate` with a lost placeholder now writes nothing and exits 5.** In 1.x
+  it wrote output containing the CLI's own internal token, such as `__ Var_0 __`.
+
+Exit 3 and 5 are retriable; 12 is a partial failure with some locales succeeded.
+The full table is in [API.md](./API.md#exit-codes).
+
+## Machine-readable output moved to stdout
+
+**Under `--format json`, a failing command writes its error envelope to stdout.**
+This applies to every command with a JSON mode — `translate`, `write`, `correct`,
+`voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`,
+`hooks`, `admin`, `style-rules` — and to every `sync` subcommand.
+
+```bash
+# 1.x — reason on stderr, payload on stdout, two redirections
+deepl translate "hi" --to es --format json > out.json 2> err.txt
+
+# 2.0.0 — one stream carries both
+deepl translate "hi" --to es --format json > out.json
+```
+
+The exit code is still the failure signal. Warnings stay on stderr, so a check for
+*the presence of* stderr output still works; anything **parsing** stderr for the
+reason must switch to stdout. A human reading `--format json` output will see the
+envelope's `message` and `suggestion` fields where a prose sentence used to be.
+
+`config get` and `config list` default to `json`, so their failures carry the
+envelope with no flag passed.
+
+Separately, the human-readable reports of `sync status`, `sync validate`,
+`sync audit`, `sync init` and `auth show` now print to stdout, so `> report.txt`
+captures them.
+
+## Output that scripts parse
+
+**Language codes are lowercase everywhere.** 1.x mixed three casings: `languages`
+printed lowercase, `glossary show` and `tm list` uppercased at display time,
+`translate --format table` uppercased the target, and `write`/`correct` used BCP-47
+(`en-GB`, `zh-Hans`). Anything comparing codes scraped from output needs to fold
+case or expect lowercase:
+
+| Command | 1.x | 2.0.0 |
+| --- | --- | --- |
+| `glossary show` | `Source language: EN` | `Source language: en` |
+| `glossary show` | `EN → ES: 5 entries` | `en → es: 5 entries` |
+| `tm list` | `brand-terms (EN → DE, FR)` | `brand-terms (en → de, fr)` |
+| `translate --format table` | row labelled `DE` | row labelled `de` |
+| `write --format json` | `"language": "en-US"` | `"language": "en-us"` |
+
+**No command line has to change** — input is case-insensitive everywhere. `voice`
+previously demanded the exact mixed-case spelling of a regional code (`--to zh-HANS`)
+and rejected the lowercase form the rest of the CLI prints; it now accepts both.
+
+Wire parameters that are not display output are untouched: `translate` and the
+glossary create endpoint still send uppercase `source_lang`/`target_lang`, as those
+endpoints document.
+
+`glossary create` also prints its success line to stdout and renders the creation
+timestamp as a locale-independent ISO string rather than a locale-dependent date on
+stderr.
+
+**`hooks list --format json` reports a state string, not a boolean.** The values are
+`installed`, `modified`, `unverified` and `not-installed`. A truthiness test now
+passes for every state including `not-installed`, so it must be replaced:
+
+```js
+// 1.x
+if (hook.installed) { /* ... */ }
+
+// 2.0.0
+if (hook.state === 'installed') { /* ... */ }
+```
+
+A hook you edited by hand reports `modified` from then on, since its body no longer
+matches the hash recorded at install.
+
+**`write --alternatives --format json --output <file>` writes JSON.** It wrote the
+numbered prose list in 1.x. To keep prose in the file, drop `--format json`.
+
+**Ten language display names changed** to match the API, a consequence of
+generating the language list rather than hand-writing it.
+
+**`sync` JSON shapes gained fields and skip reasons.** A consumer iterating
+`skipped` will meet reasons it has not seen: `shared_target`, `plural_entry`,
+`unusable_target`, `untranslated` and `needs_review`. Each locale in
+`sync status --format json` gains a `needsReview` count, and pulled keys no longer
+carry `review_status`.
+
+**Coverage numbers drop for PO and XLIFF projects.** `sync status` now counts a
+`#, fuzzy` PO entry and an XLIFF `needs-review-translation` target as needing
+review rather than as complete — which is what `msgfmt` has reported all along. A
+project reported at 100% will drop to the share actually shippable, and
+`sync push` reports a correspondingly lower pushed count. Nothing is re-translated
+or re-billed, and `sync --frozen` still passes.
+
+`sync --dry-run` may also report a **larger** character estimate than 1.x, because
+it now counts repair work — keys the lockfile calls translated that the target file
+no longer holds — which a real run bills. If you tuned `sync.max_characters`
+against the old under-count, raise it to the number `--dry-run` now reports.
+
+## Files written to disk
+
+**Backups are `<file>.deepl.bak`, not `<file>.bak`.** The stale-backup sweep only
+considers the new suffix, so any `.bak` files left by 1.x stay on disk untouched —
+delete them yourself once you no longer need them.
+
+**`watch` writes a nested source file to a nested output path.** Watching `docs/`
+with `--output out`, the file `docs/guide/intro.md` now lands at
+`out/guide/intro.es.md` where it used to land at `out/intro.es.md`. This matches
+what `deepl translate <dir> --output <dir>` has always produced. A file at the top
+of the watched directory, and a watched path that is a single file, are unchanged.
+
+**`sync` writes `state="translated"` on XLIFF targets** whose translation it
+replaced, where it used to leave the old value. A target that carried no `state` is
+written exactly as before.
+
+## Tagged translation output
+
+**`--tag-handling` now pins `tag_handling_version=v2`** instead of letting the API
+choose. Tagged output may differ from 1.x. To restore the old behaviour:
+
+```bash
+deepl translate input.html --to es --tag-handling html --tag-handling-version v1
+```
+
+## TypeScript consumers
+
+If you import this package's types, two published shapes changed. The `Language`
+union grew from 121 to 125 members with nothing removed, so it needs no action —
+but `WriteLanguage` did lose members.
+
+**`WriteLanguage` members are lowercase.** Four regional codes were re-spelled:
+
+| 1.x | 2.0.0 |
+| --- | --- |
+| `'en-GB'` | `'en-gb'` |
+| `'en-US'` | `'en-us'` |
+| `'pt-BR'` | `'pt-br'` |
+| `'pt-PT'` | `'pt-pt'` |
+| `'zh-Hans'` | `'zh-hans'` |
+
+Code that passed a literal in the old casing no longer compiles:
+
+```ts
+// 1.x
+const target: WriteLanguage = 'en-GB';
+
+// 2.0.0
+const target: WriteLanguage = 'en-gb';
+```
+
+**`WriteImprovement.targetLanguage` widened from `WriteLanguage` to `string`.** The
+API echoes this field in its own casing (`en-GB`, `zh-Hans`), which the narrower
+type claimed it would not. Assignments *from* the field still compile; code that
+assigned it *to* a `WriteLanguage` variable needs a check or a cast.
+
+## Upgrade checklist
+
+1. Move to Node 24 and reinstall from `@deepl/cli`.
+2. Remove `--enable-beta-languages`; rename `sync init --source-lang`/`--target-langs`.
+3. Delete `tms.auto_push`, `tms.auto_pull` and `tms.require_review` from `.deepl-sync.yaml`.
+4. Add `--yes` to any non-interactive `deepl sync --force`.
+5. Re-check every exit-code branch in CI against the table above — especially any
+   step treating `sync` or `watch` exit 0 as "complete".
+6. Point JSON error parsing at stdout instead of stderr.
+7. Fold case when comparing language codes from output; replace
+   `hook.installed` with `hook.state === 'installed'`.
+8. Expect lower `sync status` coverage for PO and XLIFF projects, and re-tune
+   `sync.max_characters` against the new `--dry-run` estimate.
+9. Follow `watch --output` into its new nested layout, and clean up leftover
+   `.bak` files.
+10. If you import the types, lowercase your `WriteLanguage` literals.
+
+The complete list of changes, including everything fixed that does not require
+action, is in [CHANGELOG.md](../CHANGELOG.md).
diff --git a/tests/unit/docs/documented-surface.test.ts b/tests/unit/docs/documented-surface.test.ts
index 52d14455..3ff4f972 100644
--- a/tests/unit/docs/documented-surface.test.ts
+++ b/tests/unit/docs/documented-surface.test.ts
@@ -136,6 +136,11 @@ const OPTION_CHOICES: Record<string, string[]> = {
 
 const ROOT = path.join(__dirname, '..', '..', '..');
 const CLI_ENTRY = path.join(ROOT, 'dist', 'cli', 'index.js');
+/**
+ * docs/MIGRATION.md is deliberately absent: it documents the 1.x surface a reader
+ * is migrating off, so it names flags this CLI no longer accepts and codes in the
+ * casing it no longer prints. Adding it here fails these checks by design.
+ */
 const DOCS = [
   'README.md',
   'docs/API.md',

From c54b01333ea686d1606d3d3b4d67cd4ab18613b0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 00:24:13 +0200
Subject: [PATCH 237/256] docs(changelog): stop the glossary entry
 contradicting the lowercase sweep
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two Unreleased entries disagreed about the same output. The `create`/`show` entry
claimed both commands render language codes uppercase; the later sweep entry states
codes are lowercase everywhere and names `glossary show` among the three casings it
replaced. The sweep is what ships -- verified against the code, not the log:
`normalizeGlossaryInfo` lowercases `source_lang`/`target_langs`, and
`formatGlossaryInfo` lowercases each dictionary pair -- so the uppercase clause is
what has to go.

The entry keeps its two accurate claims, both re-checked: the timestamp is rendered
through `toISOString()`, and the create success line goes through `Logger.output`,
which is stdout. It now defers to the sweep on casing rather than restating it.

The intermediate state is deliberately not described. Nothing in this release has
shipped, so no user ever saw codes rendered uppercase, and a changelog entry about a
casing that existed only between two unreleased commits is development narration.

`de-CH`/`de-DE`/`fr-CA`/`fr-FR` are left mixed-case in the unusable-languages entry:
that entry is about codes the API accepts and returns, which the sweep explicitly
exempts from the display rule, and input is case-insensitive either way.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f3edca58..acdd7977 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -145,7 +145,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **cli**: The primary human-readable reports of `sync status`, `sync validate`, `sync audit`, `sync init`, and `auth show` print to stdout, so `deepl sync status > report.txt` and `deepl auth show > key.txt` capture output instead of producing empty files. Diagnostics, warnings, and progress stay on stderr, and `--format json` stdout purity is unchanged.
 
-- **glossary**: `create` and `show` render language codes uppercase and the creation timestamp as a locale-independent ISO string, and the create success line prints to stdout — matching the documented output instead of a locale-dependent date on stderr.
+- **glossary**: `create` and `show` render the creation timestamp as a locale-independent ISO string, and the create success line prints to stdout — matching the documented output instead of a locale-dependent date on stderr. Their language codes are covered by the lowercase sweep above.
 
 - **hooks**: The installed pre-commit hook now actually validates translations — when a `.deepl-sync.yaml` exists and the CLI is on PATH it runs `deepl sync validate` and blocks the commit on validation errors (with a `--no-verify` hint). It was previously a no-op that grepped staged files and always exited 0.
 

From 8e7044e2950cb8dc54d27e5a87cfc00a8da13733 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:25:26 +0200
Subject: [PATCH 238/256] docs(changelog): condense the v2 changeset and date
 the 2.0.0 release
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Unreleased section had grown to 692 lines and 322 KB -- entries running 150-400
words that carried the defect narrative, the rationale for the chosen fix, live-API
verification notes, measurements, rejected alternatives and reassurances about what
did not change. That is a commit message, not a changelog entry. The already-released
1.1.0 and 1.2.0 sections are one to three sentences per entry; this restores that.

Now 291 lines and 137 KB: a 65% reduction in bytes, with 340 bullets merged to 206.
Every distinct user-facing fact survives -- flag names, config keys, JSON field names,
skip reasons, exit codes, renamed things, changed defaults. What went is the narrative
around them. Verified mechanically rather than by eye: of 374 distinct backticked
identifiers in the original, the only three absent are `totalChecked`, `no_matches` and
`pipe_pluralization`, all pre-existing surfaces that did not change in 2.0.0 and were
documented gaps instead (now fixed in SYNC.md and API.md).

Breaking changes are clustered at the top of Changed and prefixed `BREAKING -- scope`,
ordered by blast radius. For a MAJOR release the exit-code and stdout/stderr moves are
the headline, and they were buried mid-way through a 100-line list.

Two structural defects fixed. The `--break-lock` entry sat above `### Added` in no
category at all; it is now under Added. And the six test-infrastructure entries are
compressed to the two with user-visible effect -- the property suite and the credential
isolation -- since a changelog is for users of the CLI. Verified there are now zero
bullets outside a category and zero non-standard categories anywhere in the file.

Corrected one claim rather than carrying it over: `sync validate` was said to exit 8 on
a PO or XLIFF project holding untranslated keys. Measured, such a project checks zero
pairs and exits 0 -- an empty msgstr is not a source/translation pair. The real change
is that validate reads the real msgstr/<target> instead of comparing the source against
itself, so a translation carrying a dropped placeholder now exits 8 where it passed.

Also dropped the "Node < 22.5.0 degrades to running uncached" reassurance from the
better-sqlite3 entry: in a release that hard-floors the CLI at Node 24 and exits 6
below it, naming 22.5.0 reads as though Node 22 works.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md | 933 +++++++++++++++------------------------------------
 1 file changed, 267 insertions(+), 666 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index acdd7977..0bb37853 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,694 +7,295 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- **sync**: `--break-lock` on `deepl sync`, `deepl sync pull` and `deepl sync resolve` takes the process lock even when `.deepl-sync.lock.pidfile` names a holder that looks alive, printing the PID and start time it removed. It is the operator's escape from a lock whose holder cannot be disproved — a PID recycled by one of this user's own processes — and it applies to the run it is passed to only, so a `--watch` session breaks the lock for its first pass and then arbitrates normally for the rest of the session. Unsafe if that sync really is running, and the warning says so: two concurrent runs write the same target files and then overwrite each other's lockfile.
+## [2.0.0] - 2026-08-09
 
-### Added
-
-- **write/correct**: `--diff` and `--alternatives` honour `--format json`, each with a payload of its own. `--diff` emits `{ ok: true, original, improved, diff }`, where `diff` is the unified patch with **no colour escapes** whatever the terminal reports -- the text report colours the same patch for a human and that colouring never reaches the payload. `--alternatives` emits `{ ok: true, original, alternatives: [...] }`, an array rather than the numbered list a consumer would otherwise have had to parse by line number. Both flags were declared alongside `--format json` and neither consulted it: `--alternatives` returned the numbered text list whatever the format, and `--diff` printed the human three-block report. Each carries `ok: true` so a consumer discriminates a result from the `ok: false` error envelope, matching `--check`; the plain improvement payload keeps its existing `{ original, improved, changes, language }` shape and its absent `ok`, since it predates the envelope. One API call per invocation either way, unchanged.
-
-- **write/correct**: `--check` honours `--format json`, emitting a result payload on stdout: `{ ok: true, mode: 'write'|'correct', needsChanges, changes, file? }`. The flag was declared on both commands and accepted on this path, but the check branch reported only through the human logger, so a run measured with a mock Write endpoint exited 8 with **stdout empty** and a single sentence on stderr — the exit code told a CI job *that* text needed changes and nothing machine-readable said how many, in which file, or which of the two commands had run. `ok` is `true` whichever way the check comes out, because the check ran: the verdict is `needsChanges`, which the exit code repeats as 0 or 8. That makes `ok` the discriminator against the error envelope added for genuine failures — `false` is a failure, `true` is a verdict. `file` is the absolute path and is present only for file input. The payload replaces the human report rather than joining it, so the `File: …` line and the `⚠ Text needs improvement` / `✓ Text looks good` verdict remain text-mode only; the exit code is unchanged in both modes. `original` and `improved` are deliberately omitted: `--check` answers a yes/no question and the non-check invocation is what returns the content, and fields can be added later compatibly where removing them could not.
-
-- **sync**: `deepl sync pull --dry-run` previews a pull without writing anything — no target file, no `.deepl-sync.lock`. It reports how many translations would be pulled and how many existing local translations would be replaced, and `--verbose` names each key and file whose TMS value differs from the local one. `--format json` carries `replaced` and `dryRun` alongside `pulled`. Pull is the one sync command that replaces hand edits with content the CLI has no way to date, and it was the only writing sync command with no preview mode; `sync` itself and `sync resolve` both have one. The flag is also accepted on the parent (`deepl sync --dry-run pull`), matching how `sync resolve` reads it.
-
-- **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API). It was previously accepted and then silently discarded with a "document mode does not support --glossary" warning, even though `POST /v2/document` supports glossaries. Repeating the flag works here too, with the same merge behaviour and the same API-decided conflict resolution. `--from` is required, because the API rejects a document glossary without a source language; `--translation-memory` remains unsupported for documents. Note that glossary matching is context-dependent for documents exactly as it is for text — a term applied in one sentence may be left alone in another.
-
-- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged, so terms unique to each glossary all apply. When several glossaries define the same source term, **which mapping wins is the API's choice and does not follow flag order** — verified live with two glossaries defining the same term, where the same one won in both orderings in five of six trials and the first-listed one won in the sixth, so position is not a way to override a term. The order is still sent as given and never sorted, because it is part of the cache key: reordering the flags is a different request with its own cache entry. Names and UUIDs may be mixed and are resolved independently. A single `--glossary` still goes out as `glossary_id`, leaving existing commands and their cache keys untouched; the new field is appended last in the cache key for the same reason. A 6th `--glossary` exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration. Verified against the live API: `POST /v2/translate` accepts `glossary_ids` as repeated form fields and resolves them in order, rejects a sixth with `A maximum of 5 glossaries can be specified per request.`, and rejects `glossary_id` and `glossary_ids` together with `Specify either glossary_id or glossary_ids, not both.` -- which is why the CLI collapses a single glossary to `glossary_id` rather than sending both. The multipart `POST /v2/document` takes one comma-joined value, since multipart does not parse repeated fields as a list. Both halves of that are now confirmed against the live API with two real single-entry glossaries: a comma-joined `glossary_ids` applies the terms from both, while sending the same two IDs as repeated multipart fields applies only the first and reports no error, so the comma-joining is required rather than merely sufficient.
-
-- **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`, which the CLI previously discarded. Support no longer has to be discovered by making a request and reading the error. Which features get a column is derived from the response rather than a fixed list: a feature appears when its support differs across the languages listed, and one supported by all of them is reported once as `All listed languages also support: ...` instead of being repeated on every row (`All languages with reported features also support: ...` when the listing also carries languages the response did not describe, since the note must not speak for those). A language the response omitted reads as `no feature data` rather than as supporting nothing, and does not count towards whether a feature varies. That makes the columns differ between listings — `auto detection` appears under `--target`, where target-only variants lack it, but is uniform under `--source` — and means a newly reported feature shows up without a code change. Support is signalled by the API reporting a feature at all; `status` describes maturity, so anything short of generally available renders verbatim (`glossary (beta)`) rather than collapsing to `yes`. Works with `--format table` (one column per feature) and `--format json` (the raw matrix including each status, present only when `--features` is passed, so existing JSON consumers are unaffected). The `supportsFormality` field is unchanged for every language `GET /v3/languages` describes, which is all of them today; it now comes from the matrix rather than v2's `supports_formality` boolean, and is **omitted rather than reported as `false`** for a target the response says nothing about, since silence is not evidence that formality is absent. `--features` supersedes the `[F]` shorthand and replaces it when given. It needs an API key; without one the command warns and falls back to the registry, which carries no feature data. Note that the matrix is finer-grained than the core/regional/extended tiers: some extended languages support style rules and translation memory even though they support neither formality nor glossary.
-
-- **cli**: `deepl correct` command (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`), but not `--style`/`--tone`, which the correct endpoint does not accept. Results are cached under a separate `correct:` namespace so corrections and rephrasings of the same text never collide.
-
-- **http**: `NO_PROXY` / `no_proxy` are honoured, with the standard semantics — `*` for everything, a leading dot or `*.` for subdomains, and an optional `host:port` that must agree. A corporate `HTTPS_PROXY` was previously applied to every request, including one aimed at localhost.
-
-- **auth**: `deepl auth set-key --no-verify` stores a key without validating it against the API. Validation ran before persisting, so on a network without proxy configuration both documented setup paths — `auth set-key` and `init` — failed and discarded the key; an unreachable API now also names `DEEPL_API_KEY` as the zero-network alternative.
-
-- **ci**: `npm run check-deps` fails the build when a package imported by `src/` is missing from `dependencies`, including one declared only under `devDependencies`. It runs in CI and in the publish job, and matches package names as quoted strings so indirect loads such as `requireModule('php-parser')` count as references.
-
-- **cli**: `t` and `w` command aliases for `translate` and `write` ([#12](https://github.com/DeepL/deepl-cli/issues/12)). The aliases appear in `--help` output and in bash/zsh/fish shell completions. `w` is deliberately assigned to `write` rather than `watch` — write is a primary API feature, watch a workflow helper.
+**Breaking:** the package is published as **`@deepl/cli`** and requires **Node.js 24 or later**. Several exit codes moved, and under `--format json` a failing command now writes its error envelope to stdout. Every breaking change is covered with before/after examples in **[docs/MIGRATION.md](docs/MIGRATION.md)** — read it before upgrading, starting with [Exit codes that moved](docs/MIGRATION.md#exit-codes-that-moved).
 
-- **ci**: Pushing a `v*` tag now creates a GitHub Release, with notes extracted from that version's CHANGELOG section and generated notes as a fallback when the section is missing. This is why the repo has 17 tags and zero Releases. The workflow does **not** publish to npm: releases are published from GitLab, which is the source of truth and mirrors to GitHub, matching the other DeepL client libraries. The tag is checked against `package.json` first, so a mislabelled tag cannot mint a Release whose title disagrees with the version it contains.
+### Added
 
+- **cli**: `deepl correct` (alias `c`) — spelling and grammar correction without rewording, via the Write API's `/v2/write/correct` endpoint. Supports the same input handling and workflow flags as `write` (`--check` with exit code 8, `--fix`/`--backup`, `--diff`, `--interactive`, `--output`/`--in-place`, `--format json`, `--no-cache`) but not `--style`/`--tone`, which the endpoint does not accept. Results are cached under a separate `correct:` namespace.
+- **translate**: `--glossary` is repeatable, applying up to 5 glossaries to one request via the API's `glossary_ids` parameter. Entries are merged; when several glossaries define the same source term, **which mapping wins is the API's choice and does not follow flag order**. Names and UUIDs may be mixed, order is sent as given and is part of the cache key, a single `--glossary` still goes out as `glossary_id`, and a 6th exits 6 (ValidationError) before any API call. `watch` and `sync` keep their single-glossary configuration.
+- **translate**: `--glossary` now applies to document translation (PDF, DOCX, PPTX, XLSX, images, and text-based files routed to the document API), where it was previously accepted and then discarded with a warning. `--from` is required, since the API rejects a document glossary without a source language, and `--translation-memory` remains unsupported for documents. Glossary matching is context-dependent for documents exactly as it is for text.
+- **languages**: `deepl languages --features` shows which features each language supports — formality, glossary, style rules, translation memory, tag handling and auto-detection — from the `features` matrix on `GET /v3/languages`. Which features get a column is derived from the response: a feature supported by every listed language is reported once as a footer note instead of a column, a language the response omitted reads as `no feature data` rather than as supporting nothing, and anything short of generally available renders verbatim (`glossary (beta)`). Works with `--format table` (one column per feature) and `--format json` (the raw matrix, present only when `--features` is passed), supersedes the `[F]` shorthand, and needs an API key — without one it warns and falls back to the bundled registry, which carries no feature data.
+- **write/correct**: `--check`, `--diff` and `--alternatives` honour `--format json`, each with a payload of its own on stdout: `{ ok: true, mode: 'write'|'correct', needsChanges, changes, file? }`, `{ ok: true, original, improved, diff }` (the unified patch, never colour-escaped whatever the terminal reports), and `{ ok: true, original, alternatives: [...] }` as an array rather than a numbered list to parse by line. `ok: true` discriminates a result from the `ok: false` error envelope, `file` is the absolute path and present only for file input, and `--check` deliberately omits `original`/`improved`. Each payload replaces the human report rather than joining it; the plain improvement payload keeps its existing `{ original, improved, changes, language }` shape and its absent `ok`, and exit codes are unchanged in both modes.
+- **sync**: `deepl sync pull --dry-run` previews a pull without writing anything — no target file, no `.deepl-sync.lock`. It reports how many translations would be pulled and how many existing local translations would be replaced, `--verbose` names each key and file whose TMS value differs from the local one, and `--format json` carries `replaced` and `dryRun` alongside `pulled`. Also accepted on the parent (`deepl sync --dry-run pull`).
+- **sync**: `--break-lock` on `deepl sync`, `deepl sync pull` and `deepl sync resolve` takes the process lock even when `.deepl-sync.lock.pidfile` names a holder that looks alive, printing the PID and start time it removed. It applies only to the run it is passed to, so a `--watch` session breaks the lock for its first pass and then arbitrates normally. It is unsafe if that sync really is running — two concurrent runs write the same target files and overwrite each other's lockfile — and the warning says so.
 - **cli**: Global `--timeout <ms>` and `--max-retries <n>` options override the HTTP transport defaults (30000 ms, 3 retries) for a single invocation. Neither was previously configurable from the CLI.
-
 - **translate**: `--format json` output now includes the documented `cached` boolean, so scripts can distinguish cache hits from fresh API calls.
-
-- **cli**: Running under Node.js < 24 now fails fast with a clear one-line error (exit 6) instead of surfacing a raw `node:sqlite` ExperimentalWarning or crashing later.
+- **http**: `NO_PROXY` / `no_proxy` are honoured with the standard semantics — `*` for everything, a leading dot or `*.` for subdomains, and an optional `host:port` that must agree — so a corporate `HTTPS_PROXY` is no longer applied to a request aimed at localhost.
+- **auth**: `deepl auth set-key --no-verify` stores a key without validating it against the API. Validation ran before persisting, so on a network without proxy configuration both documented setup paths (`auth set-key` and `init`) failed and discarded the key; an unreachable API now also names `DEEPL_API_KEY` as the zero-network alternative.
+- **cli**: `t` and `w` command aliases for `translate` and `write` ([#12](https://github.com/DeepL/deepl-cli/issues/12)), shown in `--help` output and in bash/zsh/fish completions. `w` is deliberately assigned to `write` rather than `watch`.
+- **ci**: Pushing a `v*` tag creates a GitHub Release, with notes extracted from that version's CHANGELOG section and generated notes as a fallback. The tag is checked against `package.json` first, so a mislabelled tag cannot mint a Release whose title disagrees with the version it contains. The workflow does **not** publish to npm — releases are published from GitLab, which mirrors to GitHub.
+- **ci**: `npm run check-deps` fails the build when a package imported by `src/` is missing from `dependencies`, including one declared only under `devDependencies`. It runs in CI and in the publish job, and matches package names as quoted strings so indirect loads such as `requireModule('php-parser')` count as references.
 
 ### Changed
 
-- **write/correct**: **`--alternatives --format json --output <file>` writes a JSON payload where it wrote the numbered text list.** `--output` and `--in-place` receive whatever the improvement renders to, which under `--format json` is now the alternatives payload rather than `1. ...\n\n2. ...` prose -- the plain improvement payload has behaved that way all along, and `--alternatives` was the odd one out. Anything consuming such a file as prose has to parse it as JSON or drop `--format json`; to put improved text in a file, leave `--format` at its default. Text mode is unchanged. See Added.
-
-- **write/correct**: **`--check --format json` can now exit 0 where it always exited 8, and writes a payload to stdout.** A CI gate built on `deepl write --check --format json` was failing unconditionally — the verdict was computed against a rendered JSON document, so no input could pass it — and will start passing for text that is actually clean. A pipeline whose step was green only because a later step ignored the code, or that was quietly always red, sees its result change to the truthful one. Anything reading stdout on this path now finds a JSON object where it found nothing; text mode is byte-identical. See Fixed.
-
-- **cli**: **a failing command with `--format json` now writes its error to stdout instead of stderr, for every command that has a JSON mode.** A consumer that captured the reason with `2>err.txt` on `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` or `style-rules` stops finding it there; `> out.json` now captures both the success payload and the failure envelope, so one redirection handles both. Prose on stderr is replaced by the envelope's `message`/`suggestion` fields — a human reading `--format json` output sees JSON where they saw a sentence. Exit codes are the unchanged failure signal, and text/table modes are byte-identical. `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed. See Fixed.
-
-- **sync**: **`deepl sync pull --format json` can now carry a `shared_target` entry in `skipped`.** A consumer iterating `skipped` will meet a reason it has not seen before, for a target file another sync configuration's lockfile accounts for keys in; such a locale is not counted in `pulled` or `replaced` and no lockfile entry is recorded for it. Every other reason, count and field is unchanged. See Fixed.
-
-- **sync**: **the `--format json` error envelope moves from stderr to stdout, for every sync subcommand at once.** A consumer that read the failure reason off stderr stops finding it there: `deepl sync … --format json 2>err.json` now captures only human-facing warnings, and the envelope arrives where `> out.json` already captured the success payload, so one redirection handles both cases. Exit codes are unchanged and remain the failure signal. Anything branching on *the presence of* stderr output still works — warnings still go there — but anything *parsing* stderr must switch to stdout. See Fixed.
-
-- **sync**: **`deepl sync validate` exits 8 where it exited 1 on a project whose target file cannot be read, and its `--format json` issues list gains a new check kind.** A consumer that treated exit 1 as "the CLI crashed" starts seeing the documented check-failure code with a full report attached, and a JSON consumer iterating `issues` will meet entries whose `check` is `unusable_target`, whose `key` and `file` are both the target path, and whose `source`/`translation` are empty. See Fixed.
-
-- **sync**: **`deepl sync pull` no longer applies an exported value to a plural entry, and its counts move.** The export carries one string per key, which cannot fill a plural entry's forms; that value used to be applied nowhere while the entry's forms were emptied and the key was still counted as pulled and replaced. Such a key is now reported under a new `plural_entry` skip reason in the `(N skipped: …)` summary and in `--format json`, is not counted in `pulled` or `replaced`, and no lockfile entry is recorded for it. A consumer reconciling pull counts against the export's key list will see the difference; the export itself is requested exactly as before. See Fixed.
-
-- **sync**: **`deepl sync status` reports a lower coverage percentage for an XLIFF project whose targets carry a review `state`, and `deepl sync` writes `state="translated"` where it used to leave the old value.** A dashboard or CI check reading `coverage` or `complete` out of that command will see an XLIFF project it called 100% drop to whatever share of its units are actually approved, and `deepl sync push` reports a lower pushed count by the same number. The written bytes change only for a target that already carried a `state` and whose translation this run replaced; a target with no `state` is written exactly as before. The `sync status` explanation of the `needsReview` count no longer describes gettext alone — it named `#, fuzzy`, `msgfmt` and "clear the msgstr" to users of a format that has none of those. `sync --frozen` still passes. See Fixed.
-
-- **watch**: **`deepl watch` writes a nested source file to a nested output path.** Watching `docs/` with `--output out`, `docs/guide/intro.md` now lands at `out/guide/intro.es.md` where it used to land at `out/intro.es.md`. Anything reading a watch session's output by flat basename — a publish step, a `.gitignore` entry, an `--auto-commit` diff — has to follow the directory it now sits in. A file at the top of the watched directory, and a watched path that is a single file, are unchanged, so a single-directory or single-file session sees no difference. The layout is the one `deepl translate <dir> --output <dir>` has always produced. See Fixed.
-
-- **sync**: **`deepl sync status` reports a lower coverage percentage for a PO project holding `#, fuzzy` entries**, and each locale in `--format json` gains a `needsReview` count. A dashboard or CI check reading `coverage` or `complete` out of that command will see a project it called 100% drop to whatever share of its keys are actually shippable — which is what `msgfmt` has been reporting all along. `deepl sync push` reports a new `needs_review` skip reason, so its pushed count falls by the number of fuzzy entries. Nothing is re-translated, rewritten or re-billed, and `sync --frozen` still passes. See Fixed.
-
-- **sync**: **a project that sets `sync.max_characters` can now be refused where it previously ran**, and `deepl sync --dry-run` can now report a larger character estimate than before for the same input. Both follow from the cap and the preview finally counting repair work — keys the lockfile calls translated that the target file no longer holds — which a real run translates and bills. A pipeline whose cap was tuned against the old under-count will need it raised to the number `--dry-run` now reports, which is the number that run actually spends. `--dry-run` still exits 0 and still writes nothing. See Fixed.
-
-- **watch**: **`deepl watch --auto-commit` now exits 6 at startup when the output directory is in no git repository.** It previously started the watcher, translated, and printed `⚠️  Not a git repository, skipping auto-commit` once per translated file while exiting 0, so a session that could never commit anything still billed every translation. The refusal names the directory and comes before the first translation, matching how a `--glossary` without a source language is refused at launch rather than once per file change. Automation that relied on the translations still being written in that case has to drop `--auto-commit`. See Fixed.
-
-- **watch**: **a `deepl watch` session now exits 12 rather than 0 when it recorded a failure.** Ctrl+C used to end every session at exit 0 with failed translations and failed auto-commits only logged, so a script wrapping `deepl watch` could not tell a clean run from one that lost work. A session that recorded any translation error or any `--auto-commit` failure now exits **12** (`PartialFailure`), and the auto-commit failure count is printed beside the translation total. A session with no failures still exits 0. See Fixed.
-
-- **sync**: **`deepl sync push` / `pull` exit 5 where they exited 1 when the TMS could not be reached.** A pipeline branching on exit 1 as "the CLI crashed" stops seeing an unreachable TMS there and starts seeing it under the documented retriable code, alongside the timeout it already handled. Request counts are unchanged. See Fixed.
-
-- **sync**: **`deepl sync` exits 12 where it exited 0 on a locale whose target file it cannot read**, and writes nothing for it rather than rebuilding the file from the source. Automation that treated exit 0 as "the locale is up to date" will start failing on a project whose target file is unparseable or unreadable — which is the point: the alternative was re-billing the locale and overwriting the only copy of its translations. `deepl sync pull` reports the same condition as a new `unusable_target` skip reason in its `(N skipped: …)` summary and in `--format json`, at its existing exit code, matching how a colliding target file is already handled. See Fixed.
-
-- **sync**: **`deepl sync` exits 12 where it exited 0 on a key it could not write into the target file.** Any automation treating that command's exit 0 as "the locale is up to date" will start failing on a project it was already shipping incomplete — which is the point: the alternative was a lockfile entry claiming a translation the file does not contain. `sync --frozen` exits 10 and `sync status` counts the key against the locale for the same reason. See Fixed.
-
-- **sync**: **a project already missing strings from this defect recovers on its next sync that has any work to do, and re-bills them.** Measured on a `properties` project whose target file was missing a key the lockfile called `translated`: the next `deepl sync` that had a further key to translate reported `es: 2/2 keys` — the new key plus the recovered one — and wrote both. A run with nothing else to do reported `2 current`, wrote nothing, and `sync status` still said `100% (0 missing)`, because `status` and `--frozen` compare the source against the **lockfile** and never read the target file. So a project where nothing has changed since is not repaired by upgrading alone: add a string and sync, or delete the target file to have it rebuilt. See Fixed for the defect itself.
-
-- **sync**: **two output shapes change for PO and XLIFF buckets.** `deepl sync validate` now **exits 8** on a project it previously passed at exit 0, because the check finally reads the translation (see Security) — a CI job treating that command's exit 0 as "translations are sound" will start failing on input it was already shipping broken. And `deepl sync push` now reports a lower pushed count on any PO or XLIFF bucket with keys not yet translated: those keys are skipped rather than uploaded as their own source text (see Fixed), under a new `untranslated` skip reason that appears in the `(N skipped: ...)` summary line and in `--format json`. Monolingual buckets are unaffected on both counts.
-
-- **sync**: **`sync pull`'s lockfile and output shapes both change.** Pulled keys no longer carry `review_status` at all (see Security), so anything reading `review_status === "human_reviewed"` out of `.deepl-sync.lock` to find reviewed strings stops matching pulled entries — an absent field means "unknown", which is all the export response supports. A key with no translation in the export and none in the target file is now **absent** from the written target file rather than present holding the source string (see Fixed). `sync pull --format json` gains `replaced` and `dryRun` fields, and the text output gains a second line naming the replaced count when it is non-zero.
-
-- **translate**: **a translation that lost one of your placeholders is now a failure rather than output.** `deepl translate` exits 5 and writes nothing where it previously printed or wrote the CLI's internal `__ Var_0 __` scaffolding at exit 0, and a directory run reports those files as failed. Anything scraping `translate` output was already receiving unusable text in this case; it now sees a non-zero exit instead. See Fixed.
-
-- **translate/sync**: **two exit codes move for files containing an empty string value.** `deepl translate <file>` exits 0 and writes its output where it used to crash with exit 1, and `deepl sync` exits 0 where it used to exit 12 on every run forever. A rate limit part-way through a large structured file now exits 3 rather than 1, so a CI wrapper that treats 3 as retryable starts retrying it. See Fixed for the measurements.
-
-- **sync**: **`deepl sync --force` without `--yes` now exits 6 wherever it cannot prompt**, not just under `CI=true`. Any automation that runs it from a git hook, cron job, `make` target or container entrypoint — anything with piped or closed stdin, plus `--no-input` — has to add `--yes`. See Security for why it was doing the opposite and what that cost.
-
-- **sync**: **a validation error now fails the run.** `deepl sync` previously exited 0 with a one-line `N validation error(s)` warning while writing the corrupt translation; the key is now withheld and counted as failed, so the run exits 12 (`PartialFailure`) — or 6 with `validation.fail_on_error: true`, as before. CI that treats `deepl sync` exit 0 as "translations are complete and correct" gets the right answer for the first time; CI that ignored the warning line starts failing on input it was already mistranslating. `SyncResult.success` is `false` for the same runs. See Fixed for the measurements and for why the `fail_on_error` default was left alone.
-
-- **hooks**: **`deepl hooks list --format json` reports a state string per hook instead of a boolean** — `"installed"`, `"modified"`, `"unverified"` or `"not-installed"` (see Security for why a boolean could not tell the truth). Scripts must gate on `state === "installed"`; a truthiness test now passes for every state, `"not-installed"` included, so it has to be replaced rather than left alone. The text output gains the same distinction, and a hook you customized by hand — which the README invites — reports `!` from then on, since its body no longer matches the hash recorded at install. `GitHooksService.list()` returns those states as well; `isInstalled()` still answers the narrower "a DeepL marker is present" question and is unchanged.
-
-- **translate**: **`--tag-handling` requests now pin `tag_handling_version=v2`** instead of letting the API pick. The CLI previously sent the parameter only when `--tag-handling-version` was passed, so everyone else inherited the server default — which DeepL documents as moving from v1 (deprecation-bound) to v2 at an unannounced date. That flip would have changed tag-handling output with no CLI change to point at, and worse, would have gone unnoticed by the cache: a request that omits the version hashes identically before and after, so cached v1 output would have kept being served after the API started returning v2. Adopting v2 now makes that one output shift deliberate and dated, and DeepL's own docs recommend v2 for structure handling. **`--tag-handling xml`/`html` output may differ from previous releases**; pass `--tag-handling-version v1` to keep the old behaviour, which is still honoured and always wins over the default. Requests without `--tag-handling` send no version. Cached translations from earlier versions are retired on first open regardless — see the cache entry under Fixed — so no tag-handling entry can be served stale.
-
-- **translate**: **A glossary referenced by name is checked against the requested language pair before any translation request.** Previously only translation memories did this; a glossary whose dictionaries did not cover the pair reached the API and came back as `No dictionary found for language pair EN-DE in glossary <uuid>`, naming a UUID the user never typed. It now fails locally, exit 7, naming what the glossary actually covers: `Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.` This costs no extra request, because the glossary list is already fetched to resolve the name. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr is not treated as covering en→fr, and when translating to several targets at once every one of them must be covered. Both sides are compared on their **base** language, because glossary dictionaries only ever name base languages while `--to` accepts regional variants: a de→en glossary covers `--to en-us`, which the API accepts, and demanding an exact match would have made glossaries unusable for every regional target — `en-us`, `en-gb`, `pt-br`, `pt-pt`, `zh-hans`, `es-419`, `fr-ca` — including the ones DeepL steers users towards over bare `en`/`pt`. The check is therefore deliberately permissive at the edges: a pair it lets through is still the API's to reject, which is much the cheaper mistake. Two deliberate exemptions: a glossary passed as a **UUID** is trusted and left to the API, matching how translation-memory resolution already behaves and giving an escape hatch if the check is ever wrong; and a glossary the API reports with no dictionaries is left alone, since that says nothing about coverage.
-
-- **write**: **The Write API's 14 target languages are generated rather than hand-maintained**, closing the last hand-kept language list. The list and the `WriteLanguage` type were two separate hand-edited copies of the same set, either of which could fall behind `GET /v3/languages?resource=write` — the same way the translation list silently went four codes stale. `npm run generate:languages` now emits both language lists and `npm run check:languages` reports which one drifted; the type is derived from the generated list, so a language added upstream widens it on regenerate instead of needing a second edit. The generated list is byte-identical to what was there. `write`/`correct` still check the code locally and name every valid option, because at 14 of 125 languages an enumerated error beats a round trip -- but a code that is *shaped* like a language tag and simply is not in the snapshot is now sent to the API with that list as a warning, rather than refused. Nothing in CI regenerates the snapshot, so refusing outright made a language DeepL had added unreachable until someone ran the generator, with no flag to get past it. Malformed input is still rejected locally. Note the documented style/tone support table is unchanged and still maintained by hand, because it records what the API accepts rather than what its metadata claims: `resource=write` omits `writing_style` for `en`, but `--style` with `--lang en` works.
-
-- **languages**: **The DeepL API is now the authority on which languages exist, not the CLI's bundled list.** That list was hand-maintained, so it could silently fall behind the API and make languages the API accepts unusable — which is exactly what happened to `de-CH`, `de-DE`, `fr-CA` and `fr-FR` (see Fixed). Three changes remove the failure mode rather than just correcting the data. **Validation defers to the API:** a well-formed language code the bundled list does not contain is sent to the API, which accepts or rejects it authoritatively, instead of being rejected locally. Input that is not shaped like a language tag is still rejected immediately with a pointer to `deepl languages`, so typos like `--to grman` still fail fast without a request. This covers `translate`, `sync` and language values in the config file. **The listing is API-driven:** `deepl languages` renders the union of the API response and the bundled list, so a language DeepL offers can no longer be missing from the output. **The list is generated:** `npm run generate:languages` rewrites it from `GET /v3/languages` and `npm run check:languages` fails on drift, so it is a build artifact of the API rather than something maintained by hand. The core/regional/extended tiers are derived in the same pass — glossary support separates extended from the rest, source usability separates core from regional — which reproduces the previously hand-assigned tiers exactly, so the tiers can no longer disagree with the API either. No command line changes; `--to de` and every other existing code behave as before.
-
-- **types**: **The published `Language` union is derived from the generated language snapshot** instead of being written out by hand. It was a fourth copy of the same list and had already fallen four codes behind the snapshot it describes — `de-ch`, `de-de`, `fr-ca`, `fr-fr`, the very codes the /v3 migration added — so `const lang: Language = 'de-de'` was a compile error in the published typings while `deepl config set defaults.targetLangs de-de` succeeded at runtime and wrote a config `DeepLConfig` could not type. Neither `generate:languages` nor `check:languages` touched it. `ENTRIES` is now generated `as const satisfies readonly LanguageEntry[]` and the union derives from its codes, exactly as `WriteLanguage` already derived from `WRITE_TARGET_LANGUAGES`, so regenerating the snapshot widens both. The union only ever gains codes here, so nothing that compiled before stops compiling; runtime validation still defers to the API, which means the union describes what the CLI can name offline rather than what works.
-
-- **languages**: **Ten display names changed to match the API**, a consequence of generating the language list rather than hand-writing it: `ckb` Central Kurdish → Kurdish (Sorani), `es-419` Spanish (Latin America) → Spanish (Latin American), `gom` Goan Konkani → Konkani, `kmr` Northern Kurdish → Kurdish (Kurmanji), `my` Myanmar (Burmese) → Burmese, `nb` Norwegian Bokmål → Norwegian (bokmål), `pam` Pampanga → Kapampangan, `st` Southern Sotho → Sesotho, `zh-hans` Chinese (Simplified) → Chinese (simplified), `zh-hant` Chinese (Traditional) → Chinese (traditional). **Only offline output changes**: with an API key configured, `deepl languages` already took names from the API and was therefore already showing these, so this makes the no-API-key output consistent with the keyed output rather than changing what keyed users saw. Language codes are unaffected, so nothing that selects a language by code has to change; only output that scrapes display names.
-
-- **cli**: **Language codes are displayed in lowercase everywhere.** Output previously mixed three casings: `deepl languages` printed lowercase from the registry, `glossary show` and `tm list` uppercased at display time, `translate`'s table uppercased the target language, and `write`/`correct` used BCP-47 (`en-GB`, `zh-Hans`). Lowercase matches the CLI's own normalized form, the registry, what `deepl languages` teaches users to type, and the wire format `/v3/languages` moved to; uppercase followed a v2-era docs convention that v3 abandons. **Scripts scraping these values will see a casing change** — `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"`. Input is case-insensitive everywhere, so no command line has to change -- `voice` included, which previously demanded the exact mixed-case spelling of a regional code (`--to zh-HANS`) and rejected the lowercase form the rest of the CLI prints. `write`/`correct` also send the lowercase code as `target_lang`: the Write API accepts any casing and canonicalizes server-side (verified live on `/v2/write/rephrase` and `/v2/write/correct` — `en-gb`, `zh-hans`, and `zh-HANS` all return 200 and echo back `en-GB` / `zh-Hans`). Wire parameters that are not display are untouched: `translate` and the glossary create endpoint still send uppercase `target_lang`/`source_lang` as those endpoints document.
-
-- **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` endpoints to `GET /v3/languages` (`resource=translate_text` / `resource=glossary`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers come from the per-language `features` matrix, which is what v2's `supports_formality` boolean became (see the Fixed entry on `pt`). A language whose features the response does not describe is left unmarked rather than marked unsupported, so the `[F]` legend cannot appear with no `[F]` beneath it.
-
-- **tests**: A fast-check property suite (`tests/property/`) now enforces round-trip laws across all 11 format parsers — translated values survive reconstruct/extract intact, re-applying the same translations never changes the file, and an identity sync is a fixed point — plus preservation laws for the placeholder and ICU utilities. Runs are seeded-random with 200 cases per law by default (`FC_NUM_RUNS` overrides; `FC_SEED`/`FC_PATH` replay a recorded counterexample). The suite found the U+2028 TOML corruption and the `.properties` leading-space loss fixed in this release; example tests document decisions, properties enforce laws.
-
-- **tests**: Tests that assert only inside a `catch` block now declare their assertion count, so they fail instead of passing with zero assertions when the command under test unexpectedly succeeds — the failure they exist to detect was the one they could not see. Sites that already assert on the success path are unchanged. `npm test` also refuses to run against a **stale** `dist/`, not just a missing one: the suites execute the built CLI, so a stale build reported results that did not describe the current source. A new suite checks every documented `deepl …` invocation in the README and docs against the CLI's real surface, so a command or flag that drifts out of existence fails CI rather than waiting for a reader to find it.
-
-- **docs**: The README leads with the npm install path and marks Homebrew as pending until the tap exists. Install instructions target `@deepl/cli` (10 occurrences across `docs/SYNC.md`, four example scripts, `examples/README.md`, and the git-hook template in `src/services/git-hooks.ts`). The README installation section documents three install paths — npm (`npm install -g @deepl/cli`), from source, and Homebrew (`brew install deepl/tap/deepl`, marked pending until the tap ships) — with an explicit Node.js 24 prerequisite, replacing the `better-sqlite3` native-compilation caveat (Xcode CLT / python3-make-gcc), which no longer applies. The `TROUBLESHOOTING.md` `NODE_MODULE_VERSION` / `npm rebuild better-sqlite3` entry is replaced by accurate guidance for the one remaining cache-degradation cause (running on Node < 24). Six stale `DeepLcom` GitHub URLs now point at the `DeepL` org directly. `CONTRIBUTING.md` states the Node 24 development prerequisite, and `SECURITY.md`'s supported-versions table reflects that only 2.x is a published, supported line.
-
-- **tests**: Removed the global manual mocks for `p-limit` and `fast-glob` (`tests/__mocks__/`). Because a manual mock for a node module is auto-applied to every suite, and `resetMocks: true` strips its implementation, `pLimit(n)` resolved to `undefined` and `fg(...)` resolved to `undefined` in all 236 suites — so no test exercised a real concurrency limit or a real glob walk, and two concurrency defects reached a release candidate undetected. The suites that need these mocked declare them explicitly with their own implementations, so nothing depended on the global versions. Added `tests/unit/concurrency-limiting.test.ts`, which asserts that `p-limit` rejects a non-positive concurrency, that peak overlap never exceeds the limit, and that `fast-glob` returns real paths — it fails if either global mock is reintroduced.
-
-- **tests**: Suites that shell out to the bare `deepl` command now run this tree's built CLI via a PATH shim installed in jest `globalSetup`, instead of whatever `deepl` happens to be globally installed. 23 suites (392 tests) previously required a global install — absent one they all failed with `command not found`, and present one they silently tested the installed version rather than the working tree. The shim lives in the real environment before jest workers spawn (a `setupFilesAfterEnv` hook cannot do this: test code sees a copied `process.env` that child processes never inherit). CI's now-redundant `npm link` step is removed, and a new unit suite pins that `deepl` resolves to the shim and reports the tree's version.
-
-- **tests**: `npm test` now fails fast with an actionable message when `dist/cli/index.js` is missing. `dist/` is gitignored and `npm test` does not build, yet all three test tiers execute the built CLI, so a fresh checkout previously failed hundreds of tests with errors that never mentioned the missing build.
-
-- **tests**: Jest's haste map no longer indexes `.claude/` (via `modulePathIgnorePatterns`). A leftover agent worktree under `.claude/worktrees/` duplicated the manual mocks in `tests/__mocks__/` and made every jest run emit a `jest-haste-map: duplicate manual mock found` warning; test files in worktrees were already excluded, but module indexing was not. Verified warning-free with a worktree present.
-
-- **BREAKING — package**: The package is now published as the scoped **`@deepl/cli`** (previously the unpublished working name `deepl-cli`). Scoped packages default to restricted visibility, so `publishConfig.access: "public"` is set explicitly — without it the publish fails. The `bin` name is unchanged: the command is still `deepl`, and scoping changes only the install string (`npm install -g @deepl/cli`). Repository, bugs, and homepage metadata now point at `github.com/DeepL/deepl-cli` directly instead of relying on the redirect from the legacy `DeepLcom` org name.
-
-- **BREAKING — cache/runtime**: The translation cache now uses Node's built-in `node:sqlite` module instead of the `better-sqlite3` native addon, and the CLI consequently requires **Node.js >= 24** (`engines.node` is now `>=24.0.0`). Node 24 is the first release where `node:sqlite` is non-experimental; Node 18/20 lack the module entirely and Node 22 would both warn on every invocation and downgrade the bundled SQLite (3.50.4 vs 3.53.1). Existing cache databases are read in place with no migration — the on-disk format is unchanged (SQLite 3.53.2-written files verified readable, WAL mode and `user_version` stamp included). **Migration**: upgrade to Node 24 (current LTS), e.g. `nvm install 24`; no other action is needed, and the cache keeps its contents.
-
-- **ci**: `.nvmrc` now pins Node 24, matching the CI matrix. It still read `20`, so `nvm use` handed local developers a runtime that cannot load `node:sqlite` and does not satisfy `commander`'s `engines.node >=22.12.0`.
-
-- **build**: `npm run build` now runs a `clean` step first, removing `dist/` and `tsconfig.tsbuildinfo` before compiling. Without it, `tsc` leaves output for sources that no longer exist, so a file rename could ship stale artifacts — verified reproducible: planting a stale module under `dist/sync/` and rebuilding left both files in `npm pack` output. Removing the build-info file is required too; deleting only `dist/` makes the incremental compiler report the output as up to date and emit nothing.
-
-- **tests**: Raised the timeout for the `watchAndSync` test block to 30s and replaced its fixed-round setup flush with a wait on an observable readiness signal. These tests intermittently exceeded the 10s default on CI runners — always as timeouts, never assertions — failing unrelated dependency PRs. Suite duration was measured to be flat across 250/25/5 flush rounds, so the historical 20 → 50 → 250 escalation could not have addressed it; the cost is runner CPU starvation (1.8s locally vs 10.8s observed on CI). The flush now also fails with the pending state rather than a bare timeout if setup genuinely stalls.
-
-- **deps**: `commander` 14.0.3 → 15.0.0. commander 15 is ESM-only (`"type": "module"`) and requires Node >=22.12.0, so it was unmergeable until the Node 24 baseline landed. Jest's `transformIgnorePatterns` allowlist gains `commander` so ts-jest transforms it under CommonJS test execution; without that, 28 suites fail to load with `SyntaxError: Cannot use import statement outside a module`.
-
-- **ci**: Test matrix, release workflow, and security workflow now target Node 24 (previously Node 20 and 22). Node 20 reached end-of-life in April 2026, and Node 24 is the current LTS. This aligns CI with the runtime the project is moving to; the `engines.node` range is unchanged in this entry and is bumped separately.
-
-- **perf**: CLI startup no longer eagerly loads the HTTP client (axios) or the format-parser stack (yaml, smol-toml): the API URL constants moved to a dependency-free module, and `sync init`'s `--file-format` choices are filled lazily via a commander `preSubcommand` hook. Measured on `--version`: ~144 ms → ~80 ms median, 358 → 137 modules loaded. Help output and invalid-value errors are unchanged.
-
-- **perf**: YAML reconstruction now indexes every string slot in a single document walk instead of calling `setIn`/`deleteIn` per key, scaling roughly linearly with file size — measured ~3.6 s → ~170 ms for a 16,000-key file. Batched deletion also fixes a correctness bug where removing several items from one sequence shifted indices mid-iteration and deleted the wrong entries.
-
-- **batch**: Plain-text batch translation now reads, translates, and writes one API batch at a time instead of loading every file into memory up front, so memory stays proportional to a single batch rather than the whole tree. Batch grouping also measures the form-encoded body size (what the API's 128 KiB limit actually applies to) instead of raw UTF-8 bytes, so CJK-heavy batches whose percent-encoding inflates ~3x are split correctly instead of being rejected server-side.
-
-- **sync**: Backups are written as `<file>.deepl.bak` instead of `<file>.bak`, and the stale-backup sweep considers only the `.deepl.bak` suffix — a user's own `*.bak` files are never touched again. The sweep also no longer re-creates a target file that was deleted, nor restores one over an existing file: it only ever deletes (see the Security entry below). **Migration**: `.bak` files from earlier versions are no longer swept or restored — delete leftover `<target>.bak` files manually if desired.
-
-- **cli**: The primary human-readable reports of `sync status`, `sync validate`, `sync audit`, `sync init`, and `auth show` print to stdout, so `deepl sync status > report.txt` and `deepl auth show > key.txt` capture output instead of producing empty files. Diagnostics, warnings, and progress stay on stderr, and `--format json` stdout purity is unchanged.
-
-- **glossary**: `create` and `show` render the creation timestamp as a locale-independent ISO string, and the create success line prints to stdout — matching the documented output instead of a locale-dependent date on stderr. Their language codes are covered by the lowercase sweep above.
-
-- **hooks**: The installed pre-commit hook now actually validates translations — when a `.deepl-sync.yaml` exists and the CLI is on PATH it runs `deepl sync validate` and blocks the commit on validation errors (with a `--no-verify` hint). It was previously a no-op that grepped staged files and always exited 0.
+- **BREAKING — package**: The package is now published as the scoped **`@deepl/cli`** (previously the unpublished working name `deepl-cli`), with `publishConfig.access: "public"` set explicitly. The `bin` name is unchanged — the command is still `deepl` — so scoping changes only the install string (`npm install -g @deepl/cli`). Repository, bugs and homepage metadata now point at `github.com/DeepL/deepl-cli` directly.
+- **BREAKING — cache/runtime**: The translation cache now uses Node's built-in `node:sqlite` instead of the `better-sqlite3` native addon, and the CLI consequently requires **Node.js >= 24** (`engines.node` is now `>=24.0.0`) — Node 24 is the first release where `node:sqlite` is non-experimental. Running under an older Node fails fast with a clear one-line error (exit 6) instead of surfacing a raw `ExperimentalWarning` or crashing later. Existing cache databases are read in place with no migration; the on-disk format is unchanged. **Migration**: upgrade to Node 24, e.g. `nvm install 24`.
+- **BREAKING — cli**: A failing command with `--format json` now writes its `{ ok: false, error: { code, message, suggestion? }, exitCode }` envelope to **stdout** instead of prose on stderr, for every command that has a JSON mode — `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin`, `style-rules` — and for every `sync` subcommand at once, from one shared writer. `> out.json` now captures both the success payload and the failure envelope, and a human reading `--format json` output sees the envelope's `message`/`suggestion` fields where a prose sentence used to be. `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed. Warnings stay on stderr, exit codes remain the failure signal, and text/table modes are byte-identical. A malformed invocation that commander rejects before the command runs still prints commander's message on stderr at exit 6.
+- **BREAKING — cli**: Language codes are displayed in lowercase everywhere, replacing three mixed casings. `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"` — so **scripts scraping these values see a casing change**. Input is case-insensitive everywhere, so no command line has to change; `voice` included, which previously demanded the exact mixed-case spelling of a regional code (`--to zh-HANS`) and rejected the lowercase form the rest of the CLI prints. `write`/`correct` also send the lowercase code as `target_lang`, which the Write API canonicalizes server-side. Wire parameters that are not display output are untouched: `translate` and the glossary create endpoint still send uppercase `source_lang`/`target_lang`.
+- **BREAKING — sync**: `deepl sync` now exits **12** where it exited 0 in three cases: a locale whose target file it cannot read or parse (nothing is written for it rather than rebuilding it from the source), a key it could not write into the target file, and a translation that fails validation (the key is withheld and counted failed rather than written corrupt). `sync --frozen` exits 10 and `sync status` counts such keys against the locale; `validation.fail_on_error: true` still promotes a validation error to exit 6, and `SyncResult.success` is `false` for these runs. `deepl sync pull` reports an unreadable target as a new `unusable_target` skip reason at its existing exit code.
+- **BREAKING — sync**: `deepl sync validate` exits **8** where it exited 1 on a project whose target file cannot be read — reported in `--format json` under a new `unusable_target` check kind, with `key` and `file` both the target path and empty `source`/`translation`, while every other locale is still validated — and exits 8 where it exited 0 on a PO or XLIFF project whose translations carry an error the check could not previously see, because it now reads the real `msgstr` / `<target>` instead of comparing the source against itself. An untranslated entry (empty `msgstr`, no `<target>`) is not a source/translation pair and is still not validated at all.
+- **BREAKING — sync**: `deepl sync push` / `deepl sync pull` exit **5** (the documented retriable code) where they exited 1 when the TMS could not be reached. Request counts are unchanged.
+- **BREAKING — sync**: `deepl sync --force` without `--yes` now exits **6** wherever it cannot prompt — piped or closed stdin, a git hook, a cron job, a `make` target, a container entrypoint, `--no-input` — not just under `CI=true`. See Security for why it was doing the opposite.
+- **BREAKING — watch**: A `deepl watch` session now exits **12** rather than 0 when it recorded any translation error or any `--auto-commit` failure, and the auto-commit failure count is printed beside the translation total; a session with no failures still exits 0. `deepl watch --auto-commit` also exits **6** at startup, naming the directory, when the output directory is in no git repository, instead of translating every file and skipping the commit each time. Automation that relied on the translations still being written in that case has to drop `--auto-commit`.
+- **BREAKING — watch**: `deepl watch` writes a nested source file to a nested output path: watching `docs/` with `--output out`, `docs/guide/intro.md` now lands at `out/guide/intro.es.md` where it used to land at `out/intro.es.md`, matching what `deepl translate <dir> --output <dir>` has always produced. Anything reading a session's output by flat basename — a publish step, a `.gitignore` entry, an `--auto-commit` diff — has to follow the directory it now sits in. A file at the top of the watched directory, and a watched path that is a single file, are unchanged.
+- **BREAKING — translate**: A translation that lost one of your placeholders is a failure rather than output: `deepl translate` exits **5** and writes nothing where it previously printed or wrote the CLI's internal `__ Var_0 __` scaffolding at exit 0, and a directory run reports those files as failed.
+- **BREAKING — translate**: `--tag-handling` now pins `tag_handling_version=v2` instead of letting the API pick, so **`--tag-handling xml`/`html` output may differ from previous releases**; pass `--tag-handling-version v1` to keep the old behaviour, which always wins over the default. Requests without `--tag-handling` send no version, and cached translations from earlier versions are retired on first open, so no tag-handling entry can be served stale.
+- **BREAKING — translate/sync**: Two exit codes move for files containing an empty string value: `deepl translate <file>` exits **0** and writes its output where it used to crash with exit 1, and `deepl sync` exits **0** where it used to exit 12 on every run forever. A rate limit part-way through a large structured file now exits **3** rather than 1, so a CI wrapper that treats 3 as retryable starts retrying it.
+- **BREAKING — write/correct**: `--check --format json` can now exit **0** where it always exited 8, and writes a payload to stdout. The verdict was computed against a rendered JSON document, so no input could pass it — a gate built on it was either unconditionally red or green only because a later step ignored the code, and it now returns the truthful answer. Anything reading stdout on this path finds a JSON object where it found nothing; text mode is unchanged.
+- **BREAKING — write/correct**: `--alternatives --format json --output <file>` writes the alternatives JSON payload where it wrote the numbered text list. To put improved prose in a file, leave `--format` at its default. Text mode is unchanged.
+- **BREAKING — hooks**: `deepl hooks list --format json` reports a state string per hook — `"installed"`, `"modified"`, `"unverified"`, `"not-installed"` — instead of a boolean, so a truthiness test now passes for every state and must be replaced with `state === "installed"`. The text output gains the same distinction, a hook you customized by hand reports `!` from then on since its body no longer matches the hash recorded at install, and `GitHooksService.list()` returns those states while `isInstalled()` is unchanged. See Security.
+- **BREAKING — types**: `WriteLanguage` members are lowercase — `'en-gb'`, `'en-us'`, `'pt-br'`, `'pt-pt'`, `'zh-hans'` — so a literal in the old casing no longer compiles, and `WriteImprovement.targetLanguage` widens from `WriteLanguage` to `string` because the API echoes that field in its own casing. `SyncTmsConfig` drops the three removed `tms` keys, so a consumer setting them stops compiling rather than being ignored at runtime. See [docs/MIGRATION.md](docs/MIGRATION.md#typescript-consumers).
+- **sync**: `--format json` gains skip reasons and fields. `sync pull` can report `shared_target` (a target another sync configuration's lockfile accounts for), `plural_entry` (one exported string cannot fill a plural entry's forms), `unusable_target` and `key_collision`; `sync push` can report `untranslated` (a PO or XLIFF key not yet translated, previously uploaded as its own source text) and `needs_review`. All of these also appear in the `(N skipped: …)` summary line, are excluded from `pulled`/`replaced`, and get no lockfile entry. `sync pull --format json` gains `replaced` and `dryRun`, its text output gains a line naming a non-zero replaced count, and each locale in `sync status --format json` gains a `needsReview` count.
+- **sync**: Pulled keys no longer carry `review_status` in `.deepl-sync.lock` at all, so anything reading `review_status === "human_reviewed"` to find reviewed strings stops matching pulled entries — an absent field means "unknown", which is all the export response supports. See Security.
+- **sync**: `sync status` reports lower coverage for PO and XLIFF projects. A `#, fuzzy` PO entry and an XLIFF review `state` now count as needing review rather than complete, so a project reported at 100% drops to the share actually shippable — which is what `msgfmt` has reported all along — and `sync push` reports a correspondingly lower pushed count. `deepl sync` also writes `state="translated"` on an XLIFF target whose translation it replaced, where it used to leave the old value; a target that carried no `state` is written exactly as before. Nothing is re-translated or re-billed and `sync --frozen` still passes. The `needsReview` explanation no longer describes gettext alone to users of a format that has no `#, fuzzy`.
+- **sync**: A project that sets `sync.max_characters` can be refused where it previously ran, and `deepl sync --dry-run` can report a larger character estimate for the same input, because both now count repair work — keys the lockfile calls translated that the target file no longer holds, which a real run translates and bills. Raise a cap that was tuned against the old under-count to the number `--dry-run` now reports. `--dry-run` still writes nothing and still exits 0.
+- **sync**: Backups are written as `<file>.deepl.bak` instead of `<file>.bak`, and the stale-backup sweep considers only the `.deepl.bak` suffix, so a user's own `*.bak` files are never touched. The sweep also no longer re-creates a deleted target file nor restores one over an existing file — it only ever deletes. **Migration**: `.bak` files from earlier versions are no longer swept or restored; delete leftover `<target>.bak` files manually if desired.
+- **translate**: A glossary referenced by name is checked against the requested language pair before any translation request, failing locally at exit 7 with what the glossary actually covers (`Glossary "my-terms" does not support the requested language pair` / `Glossary covers en→es; requested en→de.`) instead of reaching the API as a UUID the user never typed. This costs no extra request. Matching is per dictionary, so a multilingual glossary holding en→es and de→fr does not cover en→fr, and every target of a multi-target run must be covered; both sides are compared on their **base** language, so a de→en glossary covers `--to en-us`. A glossary passed as a UUID, or one the API reports with no dictionaries, is left to the API.
+- **languages**: The DeepL API is now the authority on which languages exist, not the CLI's bundled list. **Validation defers to the API**: a well-formed language code the bundled list does not contain is sent to the API rather than refused locally, across `translate`, `sync` and language values in the config file, while input that is not shaped like a language tag still fails fast with a pointer to `deepl languages`. **The listing is API-driven**: `deepl languages` renders the union of the API response and the bundled list. **The list is generated**: `npm run generate:languages` rewrites it from `GET /v3/languages` and `npm run check:languages` fails on drift, and the core/regional/extended tiers are derived in the same pass (glossary support separates extended from the rest, source usability separates core from regional), reproducing the previously hand-assigned tiers exactly. No command line changes.
+- **write**: The Write API's 14 target languages are generated rather than hand-maintained, closing the last hand-kept language list, and the `WriteLanguage` type is derived from the generated list so a language added upstream widens it on regenerate. The generated list is byte-identical to what was there. `write`/`correct` still check the code locally and name every valid option, but a code that is *shaped* like a language tag and simply is not in the snapshot is now sent to the API with that list as a warning rather than refused — nothing in CI regenerates the snapshot, so refusing outright made a newly added language unreachable. Malformed input is still rejected locally. The documented style/tone support table is unchanged and still maintained by hand, because it records what the API accepts rather than what its metadata claims.
+- **types**: The published `Language` union is derived from the generated language snapshot instead of being written out by hand, so it can no longer fall behind it (it was four codes behind: `de-ch`, `de-de`, `fr-ca`, `fr-fr`). `ENTRIES` is generated `as const satisfies readonly LanguageEntry[]` and the union derives from its codes, exactly as `WriteLanguage` derives from `WRITE_TARGET_LANGUAGES`. The union only ever gains codes, so nothing that compiled before stops compiling; runtime validation still defers to the API, so the union describes what the CLI can name offline. `LanguageEntry`'s fields are now `readonly`, so an accessor's result can no longer mutate the registry for the rest of the process.
+- **languages**: Ten display names changed to match the API, a consequence of generating the list: `ckb` → Kurdish (Sorani), `es-419` → Spanish (Latin American), `gom` → Konkani, `kmr` → Kurdish (Kurmanji), `my` → Burmese, `nb` → Norwegian (bokmål), `pam` → Kapampangan, `st` → Sesotho, `zh-hans` → Chinese (simplified), `zh-hant` → Chinese (traditional). **Only offline output changes** — with an API key configured, `deepl languages` already took names from the API. Codes are unaffected; only output that scrapes display names changes.
+- **api**: Language listings migrated from the formally deprecated `GET /v2/languages` and `GET /v2/glossary-language-pairs` to `GET /v3/languages` (`resource=translate_text` / `resource=glossary` / `resource=write`). Command output is unchanged: source/target lists derive from the v3 `usable_as_source`/`usable_as_target` flags, glossary pairs from the source×target cross-product (verified identical to the v2 pair list), and the `[F]` formality markers from the per-language `features` matrix. A language whose features the response does not describe is left unmarked rather than marked unsupported, so the `[F]` legend cannot appear with no `[F]` beneath it.
+- **cli**: The primary human-readable reports of `sync status`, `sync validate`, `sync audit`, `sync init` and `auth show` print to stdout, so `deepl sync status > report.txt` and `deepl auth show > key.txt` capture output instead of producing empty files. Diagnostics, warnings and progress stay on stderr, and `--format json` stdout purity is unchanged.
+- **glossary**: `create` and `show` render the creation timestamp as a locale-independent ISO string, and the `create` success line prints to stdout, matching the documented output instead of a locale-dependent date on stderr.
+- **hooks**: The installed pre-commit hook now actually validates translations — with a `.deepl-sync.yaml` present and the CLI on PATH it runs `deepl sync validate` and blocks the commit on validation errors, with a `--no-verify` hint. It was previously a no-op that grepped staged files and always exited 0.
+- **perf**: CLI startup no longer eagerly loads the HTTP client (axios) or the format-parser stack (yaml, smol-toml): the API URL constants moved to a dependency-free module and `sync init`'s `--file-format` choices are filled lazily. Measured on `--version`: ~144 ms → ~80 ms median. Help output and invalid-value errors are unchanged.
+- **perf**: YAML reconstruction indexes every string slot in a single document walk instead of calling `setIn`/`deleteIn` per key, scaling roughly linearly with file size (~3.6 s → ~170 ms for a 16,000-key file). Batched deletion also fixes removing several items from one sequence shifting indices mid-iteration and deleting the wrong entries.
+- **batch**: Plain-text batch translation reads, translates and writes one API batch at a time instead of loading every file into memory up front, so memory stays proportional to a single batch. Batch grouping also measures the form-encoded body size that the API's 128 KiB limit applies to, rather than raw UTF-8 bytes, so CJK-heavy batches are split correctly instead of being rejected server-side.
+- **deps**: `commander` 14.0.3 → 15.0.0, which is ESM-only and requires Node >= 22.12.0, so it was unmergeable until the Node 24 baseline landed.
+- **ci**: The test matrix, release workflow and security workflow target Node 24 (previously 20 and 22), and `.nvmrc` pins Node 24 to match — it still read `20`, so `nvm use` handed developers a runtime that cannot load `node:sqlite`.
+- **build**: `npm run build` runs a `clean` step first, removing `dist/` and `tsconfig.tsbuildinfo` before compiling, so a file rename can no longer ship stale artifacts in `npm pack` output.
+- **docs**: The README leads with the npm install path (`npm install -g @deepl/cli`) and documents three install paths — npm, from source, and Homebrew (`brew install deepl/tap/deepl`, marked pending until the tap ships) — with an explicit Node.js 24 prerequisite replacing the `better-sqlite3` native-compilation caveat. Install strings are updated across `docs/SYNC.md`, four example scripts, `examples/README.md` and the git-hook template in `src/services/git-hooks.ts`. `CONTRIBUTING.md` states the Node 24 development prerequisite, `SECURITY.md`'s supported-versions table reflects that only 2.x is a published line, and six stale `DeepLcom` GitHub URLs now point at the `DeepL` org.
+- **tests**: A fast-check property suite (`tests/property/`) enforces round-trip laws across all 11 format parsers — translated values survive reconstruct/extract intact, re-applying the same translations never changes the file, and an identity sync is a fixed point — plus preservation laws for the placeholder and ICU utilities. Runs are seeded-random with 200 cases per law (`FC_NUM_RUNS` overrides; `FC_SEED`/`FC_PATH` replay a recorded counterexample). It found the TOML U+2028 corruption and the `.properties` leading-space loss fixed in this release.
 
 ### Removed
 
-- **sync**: **BREAKING**: `tms.auto_push`, `tms.auto_pull` and `tms.require_review` are gone from the config schema. All three were on the `tms:` allowlist and in the `tms` table in docs/SYNC.md, and **no code read any of them** — the allowlist membership was the entire reason they were tolerated, since every other unknown `tms:` field throws. Measured: a `.deepl-sync.yaml` with `require_review: [de]` passed `deepl sync validate` at exit 0 and then `deepl sync pull` replaced a hand-edited German string with the mock TMS's `"Unreviewed TMS draft"` at exit 0 — a documented safety control that did nothing and said nothing. The near-miss hint made it worse: a typo'd `auto_pushh` was answered with `Did you mean "auto_push"?`, steering the reader onto the inert key. Each now fails config load with a `ConfigError` (exit 7) that says so by name — `tms.require_review was never implemented and has been removed` — rather than as a generic unknown field, because "unknown" reads as a typo and sends the reader hunting for the right spelling of something that never existed. `require_review` is not implementable from this side: the documented export contract is a flat `{ key: value }` map with no per-entry review flag, so there is nothing to gate on; use `deepl sync pull --dry-run` to preview and review a pull instead. `auto_push`/`auto_pull` are one explicit `deepl sync push` / `deepl sync pull` away, which also keeps the credential-and-destination decision on a command someone typed — implementing `auto_push` would have made a plain `deepl sync` in a checkout you do not control ship every translated string to the `tms.server` that checkout names. `SyncTmsConfig` drops the three fields too, so a TypeScript consumer setting them stops compiling rather than being ignored at runtime.
-
-- **cli**: **BREAKING**: The `--enable-beta-languages` flag on `translate` is gone. The API deprecated the underlying `enable_beta_languages` parameter with "has no effect" — beta languages are simply part of the regular language set now — so the flag had become a silent no-op. Scripts passing it will exit with an unknown-option error; remove the flag.
-
-- **usage**: The dedicated "Speech-to-Text Usage" section (text output) and "Speech-to-text" row (table output) are gone, along with the `speechToTextMilliseconds*` fields they read. The API deprecated `speech_to_text_milliseconds_count`/`_limit` on `GET /v2/usage` ("Always returns 0"), so the section could only ever display zero. Voice usage remains visible in the Product Breakdown, which reads the live per-product minutes data. The Admin API's per-key `speech_to_text_milliseconds` usage limit is a different, still-current field and is unaffected.
-
-- **repo**: The `VERSION` file and `.npmignore`. Nothing read `VERSION` — `deepl --version` reports `package.json`'s value — so it was a second, hand-edited source of truth that could only drift; use `npm version X.Y.Z --no-git-tag-version`, which updates the manifest and lockfile together. `.npmignore` was dead weight because the `files` array governs what is packed.
-
-- **build**: Source maps and declaration maps are no longer emitted. They were already excluded from the published package, so emitting them only left dangling `sourceMappingURL` comments in the shipped files, giving library consumers unresolvable stack frames and broken go-to-definition.
-
-- **deps**: `inquirer`, which no source file imported (see the `@inquirer/prompts` entry under Fixed).
-
-- **deps**: `better-sqlite3` and `@types/better-sqlite3`. The production dependency tree no longer contains any native addon, removing the entire class of ABI-mismatch failures (`ERR_DLOPEN_FAILED` / `NODE_MODULE_VERSION` errors after a Node major upgrade, e.g. via `brew upgrade node`), a 1.9 MB platform-specific binary, and the C++ compilation-toolchain requirement for installs from source. The cacheless-degradation safety net remains: a runtime whose `node:sqlite` is missing (Node < 22.5.0) warns once and runs uncached rather than crashing, and never touches the cache database.
-
-- **BREAKING — sync**: `deepl sync init --source-lang` and `--target-langs`, the deprecated aliases introduced in 1.x, are removed and now fail with `error: unknown option` (exit 6, per the subcommand parse-error mapping also in this release). Use `--source-locale` and `--target-locales`. This is the documented removal of 1.x aliases at the 2.0 cut. `deepl translate --target-lang` is unaffected — it is the API's wire name, not a deprecated alias.
+- **BREAKING — sync**: `tms.auto_push`, `tms.auto_pull` and `tms.require_review` are gone from the config schema. All three were on the `tms:` allowlist and in `docs/SYNC.md`, and **no code read any of them**, so a review gate configured through `require_review` was doing nothing. Each now fails config load with a `ConfigError` (exit 7) naming it — `tms.require_review was never implemented and has been removed` — rather than as a generic unknown field, which would read as a typo. `require_review` is not implementable from this side, since the documented export contract is a flat `{ key: value }` map with no per-entry review flag; use `deepl sync pull --dry-run` to preview a pull instead, and run `deepl sync push` / `deepl sync pull` explicitly in place of the auto flags.
+- **BREAKING — cli**: The `--enable-beta-languages` flag on `translate` is gone. The API deprecated the underlying parameter as having no effect — beta languages are part of the regular language set — so the flag had become a silent no-op. Scripts passing it exit 6 with an unknown-option error; remove the flag.
+- **BREAKING — sync**: `deepl sync init --source-lang` and `--target-langs`, the deprecated aliases introduced in 1.x, are removed and fail with `error: unknown option` (exit 6). Use `--source-locale` and `--target-locales`. `deepl translate --target-lang` is unaffected — it is the API's wire name, not a deprecated alias.
+- **usage**: The dedicated "Speech-to-Text Usage" section (text output), the "Speech-to-text" row (table output) and the `speechToTextMilliseconds*` fields they read are gone, following the API's deprecation of `speech_to_text_milliseconds_count`/`_limit` ("Always returns 0"). Voice usage remains visible in the Product Breakdown, which reads live per-product minutes; the Admin API's per-key `speech_to_text_milliseconds` usage limit is a different, still-current field and is unaffected.
+- **deps**: `better-sqlite3` and `@types/better-sqlite3`. The production dependency tree no longer contains any native addon, removing the whole class of ABI-mismatch failures (`ERR_DLOPEN_FAILED` / `NODE_MODULE_VERSION` after a Node major upgrade), a 1.9 MB platform-specific binary, and the C++ compilation-toolchain requirement for installs from source. The cacheless-degradation safety net remains: a runtime whose `node:sqlite` is unusable warns once and runs uncached rather than crashing, and never touches the cache database.
+- **deps**: `inquirer`, which no source file imported.
+- **repo**: The `VERSION` file — nothing read it, since `deepl --version` reports `package.json`'s value, so it was a second hand-edited source of truth that could only drift — and `.npmignore`, which was dead weight because the `files` array governs what is packed.
+- **build**: Source maps and declaration maps are no longer emitted. They were already excluded from the published package, so emitting them only left dangling `sourceMappingURL` comments in the shipped files, giving consumers unresolvable stack frames and broken go-to-definition.
 
 ### Fixed
 
-- **write/correct**: `write --diff --format json` no longer labels a rendered JSON document as the improved text. `improveWithDiff` took its improved text from `improve()`, which renders a JSON document when the caller asked for one, so the block headed `Improved:` held that document and the unified diff below it described JSON scaffolding rather than wording -- measured against a mock Write endpoint, the diff read `+  "original": "Hello there",` where it should have read the changed sentence. It now takes the unrendered text, the same seam that fixed `--check` and `--fix`. Text mode is byte-identical.
-
-- **write/correct**: `--format json` no longer inverts the `--check` verdict or corrupts the file `--fix` writes. `checkText` obtained the improved text by calling `improve()`, which renders a JSON document when the caller asked for one, so the word-level diff behind the check compared the original text against that document rather than against the improvement. Measured against a mock Write endpoint that echoed its input unchanged — a genuinely clean check: `write --check 'text'` exited 0 and said `✓ Text looks good`, while `write --check 'text' --format json` exited **8** and claimed `2 potential changes`, for any input, because the JSON scaffolding was itself the diff. The same call served `--fix`, which writes what the check computed, so `write file.txt --fix --format json` **overwrote the file with the JSON document** — measured on a file needing no change at all, which was reported as `✓ File improved / Changes: 2` and left holding `{"original":…,"improved":…}`; `--backup` preserved the original, without it the content was lost. And the change count disagreed with itself across formats for the same input (2 vs the truthful 1). The improved text is now produced without the presentation formatting, which `improve()` still applies for its own output, so the verdict, the count and the bytes written to disk no longer depend on the format the report was asked for. `--alternatives`, `--diff`, `--output` and `--in-place` are byte-identical under both formats, verified by diffing a full before/after run of all four.
-
-- **cli**: every command with a JSON mode now emits the machine-readable error envelope, not only the `sync` subcommands. `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin` and `style-rules` routed their failures through the global handler, which printed `Error:` (and `Suggestion:`) as prose on stderr and left stdout empty — measured through the real CLI for eleven of them, so a script that selected `--format json` had nothing to parse in exactly the failure case, and had to implement two error-handling strategies, the second of which was scraping prose off stderr. Failures now emit the same `{ ok: false, error: { code, message, suggestion? }, exitCode }` envelope on stdout that `deepl sync` has emitted since the envelope was recognised as the command's result in the failure case, from one shared writer. Exit codes are unchanged. Text and table modes are untouched, a command with no `--format` flag is untouched, and a result that is not an error keeps its own shape — `write --check` / `correct --check` still exit 8 with no envelope. A malformed invocation that commander rejects before the command runs still prints commander's message on stderr and exits 6: the envelope covers command failures, not parse failures.
-
-- **sync**: `deepl sync` and `deepl sync pull` no longer delete another sync configuration's translations from a target file both configurations write. A rewrite emits exactly the keys its own configuration defines, and the existing guard refuses that collision only *within* one bucket (two source files in one bucket resolving to one target); across two configurations nothing saw it, because each has its own project root, its own `.deepl-sync.lock` and — the process lock being keyed on the project root — its own pidfile. Measured through the CLI on nested roots (a repository-level config and a package-level one whose `target_path_pattern` resolved into the same directory): the file ended up holding whichever ran last, both runs reported success at exit 0, and each later run deleted the other's keys and re-billed its own — a flip-flop with no concurrency needed, which is why the lock's key was never the fix. A run that is about to delete keys from a target now looks for another configuration that accounts for them, using that configuration's lockfile as the evidence: a configuration writes only inside its own project root, so one that also writes this file is rooted at an ancestor directory of it, and a match requires that lockfile to record those exact keys for the same locale. When it does, the file is left exactly as it stands — `deepl sync` fails that locale (nothing written, nothing billed for it, keys recorded `failed` so the next run retries them, exit 12) and `deepl sync pull` skips it under a new `shared_target` reason. Both name the other lockfile, the shared keys and the remedy. Keys added to a locale file by hand are unaffected: no lockfile accounts for them, so they are still pruned with the usual warning.
-
-- **sync**: a pidfile naming a process this user cannot signal no longer refuses every later sync indefinitely. `kill(pid, 0)` answers EPERM for a PID that exists but belongs to another user — which is equally what a PID recycled by an unrelated process, or one from a container's PID namespace, looks like — and that was read as "alive" with no upper bound, while the `startedAt` the pidfile has always recorded was never consulted. Measured through the CLI: a pidfile naming PID 1 with a start time 30 days old refused `deepl sync` with exit 7 on every attempt. Such a holder is now trusted only while its recorded start time is within 24 hours and readable as a date (a time impossibly far in the future counts against it too), after which the lock is reclaimed with a warning naming the PID and the reason. A holder the probe reports as **genuinely running** is never aged out, however old the lock — taking the lock from a live sync is the concurrent-writer hazard the lock exists to prevent — so that case gets `--break-lock` instead (see Added). The refusal message now names the flag.
-
-- **watch**: a real document named like an atomic-write temp sibling (`*.tmp.<digits>.<letters>`) is no longer skipped. The check pattern-matched the file **name**, though its own docstring promised "a temp sibling of an in-flight atomic write" and the in-flight set was already there; the skip also happened before the warn-once branch, so nothing said the file had been passed over. It is now a membership test against that set, with the name pattern still honoured for a path that no longer exists — a temp sibling whose rename completed before the watcher's event arrived.
-
-- **watch**: `--auto-commit` no longer reports a session failure when there was nothing to commit. Re-saving a file whose translated bytes are unchanged stages nothing, `git commit --only` then exits non-zero, and the undifferentiated `catch` counted that as an auto-commit failure — which makes the session exit **12** although nothing went wrong. The staged state is now asked as `git diff --cached --quiet` rather than by matching git's "nothing to commit" wording, which a localized git translates. A genuine failure is now reported with git's own `stderr`, which was previously discarded in favour of the bare exit-status message.
-
-- **po**: a `msgstr` containing U+2028 or U+2029 is readable. JS `.` excludes the line separators, so such a line did not match its own pattern at all: it was invisible to both scanners, and the key was reported unwritten — honestly, at exit 12 — but under a remediation about adding a containing group, so no later run could converge. gettext accepts the byte raw (verified: `msgfmt -c` exits 0 on such a catalog), so the file was valid and it was this parser that could not read it. Note that escaping — the remedy TOML uses — is *not* available here: the PO escape set has no `\uXXXX`, so an escape would round-trip back as the literal text.
-
-- **po**: an obsolete `#~` block is no longer deleted along with the entry beneath it. The comment backtrack claimed every preceding line starting with `#`, and `#~` starts with `#` — but gettext's retired-work region is an obsolete entry in its own right, not the following entry's comments. An entry's own `#.`/`#:`/`#,` comments are still dropped with it.
-
-- **sync**: `deepl sync pull` recognises a gettext plural entry that declares `msgid_plural` without yet holding any `msgstr[N]`. `plural_forms` metadata only appears once forms exist, so judging plurality from that payload made pull treat such an entry as an ordinary key — and one exported string cannot fill a plural entry's forms, so the pull recorded a translation it had not applied.
-
-- **android**: a `<plurals>` element whose name looks like an array index (`x.0`, beside a `<string-array name="x">`) is no longer deleted. `reconstruct` decided what an entry was from the shape of its key, so with the entry's plural metadata stripped — which is exactly what the carry-forward does — nothing claimed the element. A key that names a `<plurals>` element in the file is now treated as that element whatever shape its name has.
-
-- **translate**: **a source string that literally contains the CLI's own placeholder token is no longer corrupted, and a genuinely lost token is no longer reported as intact.** Preservation tokens came from a plain counter, so text carrying a literal `__VAR_0__` — ordinary content, not a variable — could be handed the *same* token as a real `{name}`. Two occurrences then went to the engine, and `restorePlaceholders` uses `replaceAll`, so the literal copy came back as `{name}` too: `'literal __VAR_0__ and {name}'` round-tripped to `'literal {name} and {name}'`. The same collision made the loss check accept the literal copy as evidence that the substituted token had survived, so an engine that mangled the real token had a genuine loss reported as intact. Tokens are now chosen to avoid any that the source text already contains, for both the `__VAR_` and `__CODE_` families, and the low numbers are still used when the source carries none. A property test that had been *documenting* the corruption as expected output now asserts the round trip.
-
-- **po**: **rebuilding a catalog is linear in the length of a comment block again, instead of quadratic.** `reconstruct` collected the run of comment lines above an entry by walking backwards and `unshift`ing each line onto an array — and `unshift` re-indexes the whole array on every call, so the cost grew with the square of the run's length. Measured: 20k comment lines took 28 ms, 40k took 109 ms and 80k took 437 ms — four times the time for twice the input — which extrapolates to the ~47 seconds reported for a large catalog. The run is now taken with a single slice: the same 80k lines take **11 ms**, and the growth is linear.
-
-- **sync**: **`sync.limits.max_file_bytes` now applies to target files, not only source files.** A target is the file a hostile or corrupt checkout actually controls, and it was parsed and rebuilt at any size. An oversized target is now reported `unusable` — refused, with the reason naming the limit — rather than treated as empty, which is what would otherwise re-translate the locale in full and then overwrite the file. The size is checked on the content that was read rather than through a separate `stat`, because the cap's purpose is to bound the parse, reconstruct and comparison work that follows; Node's own string-length ceiling bounds the read itself and surfaces as a catchable error.
-
-- **watch**: **`--git-staged` recognises a staged file when git and the watcher spell its path differently.** The path comparison key resolved symlinked ancestors but nothing else, and `fs.realpathSync` **does not** case-fold on a case-insensitive volume — measured on APFS, `realpathSync` returns `Docs` for `Docs` even when the directory is stored as `docs` — nor does it unify NFC with NFD. Two spellings reaching the very same inode therefore produced different keys, so `watch --git-staged` translated **nothing** when the index spelled a directory one way and the watcher saw another: silently, at exit 0. Where the file exists, the key is now its device + inode pair, which is its identity — verified on APFS that `docs/en.md` and `Docs/en.md`, and the NFC and NFD spellings of one name, all reach the same inode. This needs no platform guesswork in either direction: on a case-sensitive volume the other spelling does not exist, so the two paths keep distinct keys. `lstat` rather than `stat`, so a symlink stays a different file from its target; a path with no file yet falls back to the resolved string as before.
-
-- **sync**: **a target file that becomes unreadable mid-run is left alone, not overwritten from the source.** The pre-read went through `readTargetFile`, which separates *nothing is there* from *something is there this run could not open* and refuses the locale in the second case — but the write-time re-read that produces the reconstruct template was a bare `fs.readFile` whose `catch` fell back to the **source** as the template. A file that became unreadable in the window between the two was therefore reclassified as absent: no backup was taken (`targetExists` stayed false) and a source-derived file was written over the very target the run had just failed to read. Measured by revoking read permission on `de.json` from inside the engine reply, which is the one hook that runs between the two reads: the target gained the machine translation and lost its own state, at exit 0. The template now comes from the same guarded read, and an unreadable target aborts that locale exactly as the pre-read would — reported, with the file untouched. As part of this, a target holding only whitespace is now classified as present-but-empty rather than unusable: it has no translations to lose, and parsing it would fail (`JSON.parse('  ')` throws), which would otherwise refuse a locale over an empty file.
-
-- **sync**: **a run that removes a hand-added key from a locale file now says so.** `reconstruct` is handed the complete desired key set, so every run that rewrites a locale drops whatever the target holds that is not in that set. For a key the lockfile recorded, that is the intended prune of a key the source no longer defines. For a key **neither the source nor the lockfile accounts for** — one a translator added to the locale file by hand — it is someone else's data being deleted, and it happened with no mention in the run output, `sync status` or `sync validate`, while the `.deepl.bak` was unlinked on success: nothing said anything was lost and nothing was left to recover it from. Such keys are now named in a warning that points at both remedies (add them to the source, or recover them from the backup before the next run). The prune itself is deliberately unchanged — emitting exactly the keys the source defines is what makes deleting a removed key work — so this makes the behaviour visible rather than altering it. Note the distinction cannot be drawn from the lockfile at that point, because the run removes deleted keys' lock entries before the locale loop; it is drawn from the `deleted` diffs instead.
-
-- **sync**: **an `include`/`exclude` pattern with a nested-quantifier extglob is refused instead of wedging the process for minutes.** The glob guard bounded brace expansion and raw pattern length, but said nothing about extglobs — and a pattern can carry no brace at all. `*(…)` and `+(…)` compile to a *repetition*, so an unbounded wildcard inside one hands picomatch a nested quantifier: measured against a 40-character directory name, the **six-character** pattern `+(a*)b` takes about **50 seconds**, and a longer one never finishes. Both the pattern and the directory names it runs against come from the checkout, so this is reachable from a merge request rather than only from a hand-edited config; it wedges `sync`, `--dry-run`, `validate` and `watch` alike. Such a group is now rejected at config load (in 0.16 ms) with an error naming the offending construct and pointing at `@(…)`, which matches one alternative without the repetition. Measured and left alone: `@(…)`, `?(…)` and `!(…)` are not repetitions and stay flat, so ordinary patterns — `@(en|de)/*.json`, `!(node_modules)/**/*.json`, `+(en|de)/messages.json`, `res/values-*/strings.xml` — are unaffected.
-
-- **sync**: **one locale's failure no longer makes a key stale for every locale.** Staleness is recorded per target locale in the lockfile, but three places decided it from the whole entry. `deepl sync --locale de` scoped staleness to *all* configured locales rather than to the `--locale` filter, so a key that had failed for **es** was re-translated, re-billed and written over de's reviewed translation — a locale the run was not asked to look at. `sync status` called `computeDiff` with no locales at all, which triggers its whole-entry "some locale failed" fallback and reported a complete locale as `outdated`; and even with locales passed, the report inherited the key-level `stale` verdict, which conflates *the source changed* (every locale is out of date) with *one locale's own record lags* (only that locale is). The run now judges staleness against the locales it will actually touch, the status report distinguishes the two `stale` cases by re-checking the source hash, and the duplicated locale-filter expression is computed once. The locale that genuinely failed is still re-translated and still reported as needing work.
-
-- **xliff**: **the review state of a rewritten element is read and updated on the real attribute, not on a `state=` sequence inside another attribute's value.** `state` was located with a single unanchored, non-global regex, so it returned the *first* `state=…` anywhere in the attribute run — including one sitting inside another attribute's value, such as `note="compare state='final' with the old one"`. The consequences compounded: `extractNeedsReview` read the decoy and so missed the real `needs-review-translation`, and the rewrite corrupted the decoy's value while leaving the real state untouched — so a needs-review marker stayed attached to text this run had just replaced with machine output. Attributes are now walked as whole `name="value"` pairs, which also means an attribute merely *ending* in `state` (`xstate=`) is no longer mistaken for it. Two sibling markers are handled at the same time, since neither can describe text the run has just replaced: `approved="yes"` becomes `approved="no"`, and `state-qualifier` (1.2) / `subState` (2.0) are removed rather than rewritten, their vocabularies having no "this is machine output now" value. Every marker is left untouched when the run writes the same text it found, which is the existing `targetHolds` behaviour.
-
-- **properties**: **a key containing an escaped `=` or `:` is read back correctly, so the parser can read its own output.** `escapeKey` escapes `=`, `:`, space and backslash when writing a key — but the entry regex's key part excluded `=` and `:` outright, with no notion of a backslash escape. A key like `greeting:formal`, written as `greeting\:formal`, was therefore split at the escaped colon on the next read: the key became `greeting\` and the value `formal=Hello`, so **half the key was sent to the engine as the value** and the real key never reached the target file. The rewrite path carried a second copy of the same pattern, which truncated the key when replacing a value. Both now share one fragment that treats `\X` as a single key character; a key's own bytes are preserved verbatim when its value is rewritten, and an ordinary key still splits at its first separator (`a.b=x=y` → value `x=y`).
-
-- **android, xliff**: **the key of an appended resource is guarded and escaped, not just its translation.** Both new-resource append paths ran `assertNoControlChars` on the *translation* and then interpolated the key straight into `<string name="…">` / `<trans-unit id="…">`. A control byte in a source key therefore produced a file no XML consumer can read — XML 1.0 has no representation for a C0 byte in any form, not even a numeric character reference — plus a live terminal escape sequence in `git diff` and CI logs. A key containing `&`, `<` or `"` broke the attribute outright, and a `"` is now legitimately reachable since a single-quoted `id`/`name` may contain one. The key is now checked for control bytes (as are Android plural `quantity` values) and escaped for an attribute context, and `extract` entity-decodes attributes so such a key round-trips instead of coming back as `a&amp;b`.
-
-- **po**: **a plural key appended to an existing catalog keeps its `msgid_plural` and every `msgstr[N]`.** The new-key append path wrote `msgid` + a bare `msgstr`, which is the singular entry shape. A plural key added to the source *after* the target file existed therefore arrived in the catalog with no `msgid_plural` and no plural forms, so `ngettext` returned the English source for every count while the lockfile recorded the key translated — and the existing new-key-insertion test missed it because its PO case carried no plural metadata. The append path now emits `msgid_plural` and one `msgstr[N]` per recorded form, in index order, with index 0 falling back to the entry's translation. Verified with gettext itself: `msgfmt -c` accepts the appended catalog at exit 0, `msgfmt --statistics` counts the entry as translated, and `msgunfmt` reads both forms back.
-
-- **po**: **adjacent string literals on one line are concatenated, as gettext defines them.** `msgstr "Hola " "mundo"` is valid gettext for the string `Hola mundo` — literals join C-style. `unquote` tested only that the value started and ended with a quote and then sliced, so it read the inner `" "` as *content*; the next write escaped those quotes, turning the translation into `Hola \" \"mundo` permanently. `msgfmt -c` accepts both forms, so nothing flagged it. Values are now read as a run of literals, matching `msgunfmt`'s own answer for the same catalog (verified: `msgunfmt` reports `Hola mundo`, and so does the parser). Applies to `msgid` and `msgctxt` as well as `msgstr`. A quote that is genuinely part of the string (`"say \" here"`) still decodes as content, a plain single literal is unaffected, and a malformed value (unterminated quote) is returned untouched rather than mangled.
-
-- **po**: **an escaped carriage return survives a round trip instead of growing a backslash on every run.** `quote` escaped CR to `\r`, but `unquote`'s escape set was `\\ " n t` with no `r` case — so reading a catalog back turned `\r` into a literal backslash followed by `r`. The next run then escaped *that* backslash, so a carried entry's CR became `\\r`, then `\\\\r`, gaining a backslash indefinitely. `msgfmt` flags neither spelling, so nothing reported it. `unquote` now decodes `\r`, which makes the two halves symmetric and the round trip idempotent — asserted by reconstructing twice and requiring the second output to be byte-identical to the first.
-
-- **toml**: **a quoted key containing a dot is translated in place instead of being turned into a nested table.** `"greeting.formal" = "Good day"` is *one* flat key whose name contains a dot. `extract` surfaced it — `TOML.parse` yields a property literally called `greeting.formal` — but the entry-line regex deliberately excluded quoted keys, so the two halves of the parser disagreed: `reconstruct` passed the line through untranslated and *appended a new `[greeting]` table with a `formal` key*. The source's own key kept its English while the lockfile recorded the key translated and `sync status` read 100%. Quoted key segments (basic and literal strings) are now matched, with the logical dot-path derived through `TOML.parse` itself so it agrees with `extract` by construction rather than by a second hand-rolled unquoting; the key is rewritten in place, keeping its original quoting style. For a key the target file does not yet have, `extract` records the segment path so insertion writes `"greeting.formal" = …` (or `"a.b" = …` inside its real table) rather than inventing a table — attached **only** where a segment carries a literal dot, so `computeSourceHash` and therefore staleness are unchanged for every other TOML key. Finally, TOML now uses `assertDistinctKeys` like JSON, Android XML and Laravel PHP: a file holding both `"a.b" = …` and `[a] b = …` is one key for two strings, and is refused rather than having one translation written over the other.
-
-- **toml**: **a new key outside TOML's bare-key character set is written as a quoted key instead of invalid TOML.** New-key insertion emitted `${leaf} = value` and `[${section}]` with no quoting, so a source key such as `with space` (or one containing a quote) produced a document `smol-toml` refuses on its next read — *"only letter, numbers, dashes and underscores are allowed in keys"*. The unusable-target guard then pins that locale as permanently unreadable, and because the run that wrote the file is the run that broke it, every later sync refuses the locale it just created. Leaf keys and each component of a section header are now emitted bare where the character set allows and as quoted keys (basic-string escaping) otherwise; a bare key is still written unquoted, so existing files are untouched.
-
-- **android**: **a single-quoted `name` or `quantity` attribute is no longer invisible.** `<string name='greeting'>` is well-formed XML, and the scanners already accepted either quote for every *other* attribute, but the `name`/`quantity` capture required a double quote. Such an element was never extracted, never translated and never reported — so `sync status` read 100% complete while the string shipped in the source language, with nothing anywhere saying so. All four scanners (`<string>`, `<plurals>`, `<item quantity=…>`, `<string-array>`) now capture the delimiter and exclude only the delimiter in use, which also means a single-quoted name may contain a double quote. The quoting style of each element is preserved on rewrite, and a following attribute (`translatable="true"`) is still not swallowed into the name. This is the Android mirror of the XLIFF `trans-unit id` gap fixed above.
-
-- **watch**: **a watch pass that fails or is interrupted restores the targets it had already rewritten, instead of deleting their backups.** `SyncService.sync` skips its restore-on-signal path for a watch run, because watch mode owns the backup tracker — but `WatchController` only ever *unlinked* what the tracker held, from both the per-pass `finally` and `shutdown()`. A pass that completes unlinks its own backups and clears the tracker inside `sync`, so anything still in the tracker belongs to a pass that threw, was cancelled, or hit drift, none of which write a lockfile. Measured on a two-locale project where es translated and fr was answered 403: es.json was left holding `MT Beta`, its `.deepl.bak` deleted, no lockfile written, at **exit 0** — the reviewed content gone with no record and no recovery path, which is exactly the state the `COPYFILE_EXCL` guard and the stale-backup sweep were added to prevent. Plain `deepl sync` restores in the same situation, and now so does a watch pass: each file is copied back before its backup is removed, so an interrupt mid-restore leaves the backup rather than nothing, and a backup that cannot be restored is kept with a warning naming it. A pass that completes still removes its backups as before.
-
-- **sync**: **a bucket whose source files resolve to the same target path is refused instead of billing forever for translations it destroys.** `target_path_pattern` need not contain `{basename}`, so `out/{locale}.json` made every source file in a bucket claim one target, and nothing checked for it. Each file's `reconstruct` is handed only its own keys and treats that list as the complete key set, so the files deleted each other's translations; `unwrittenKeys` inspects only the string the current file just produced, so the loser was still recorded `translated`. Measured across three consecutive syncs of a bucket globbing `modA/en.json` and `modB/en.json`: the single target alternated between `{b1,b2}` and `{a1,a2}`, two more texts were billed on every run, and every run reported success at **exit 0** — an unbounded billing loop against a target that can never be complete, which `sync status` and `--frozen` report while prescribing a cure that cannot work. The collision is now detected at the bucket walk, before any translation request, and refused with an error naming both source files, the shared target and the locale. The suggestion deliberately does **not** offer `{basename}` as the fix: it interpolates the source *filename*, so it does not separate two files both called `en.json` in different directories — omitting `target_path_pattern` (per-file locale substitution) or splitting the sources into separate buckets are the remedies that work. Multi-locale (bilingual) buckets are exempt, since each file is its own target.
-
-- **sync**: **a plural key whose source forms coincide no longer keeps source-language text in one of them.** The plural pipeline identified forms by value equality rather than by quantity: `expandPlurals` skipped every Android `<item>` whose value equalled the entry's own — so with two coinciding forms *neither* was expanded and only one was ever translated — and the primary write-back then used `find(p => p.value === diff.value)`, which returns whichever form comes first rather than the `other` form the extractor actually published as `entry.value`. English invariant nouns (fish, sheep, series) and copy-pasted `<item>`s make this ordinary input. Measured on `<item quantity="one">%d fish</item><item quantity="other">%d fish</item>`: `one` got the translation and **`other` shipped the English source**, recorded `translated`. The PO half had the mirror problem — `msgid_plural` was expanded only when it differed from `msgid`, so an invariant-noun entry left `msgstr[1]` untouched (`msgstr[1] ""`, silently untranslated but recorded translated). Both sites now use one shared `primaryPluralItem` rule keyed on quantity (`other`, else the first item), which the Android extractor also uses so the three cannot drift apart, and `msgid_plural` is always expanded — identical texts deduplicate inside `translateBatch`, so this bills nothing extra.
-
-- **po**: **a wrapped (continuation-line) plural form survives a run that only rewrites its entry for a sibling key.** gettext writes any `msgstr[N]` longer than 74 characters as `msgstr[N] ""` followed by continuation lines. `reconstruct` re-emitted the first line of a form it was *keeping* and then swallowed the continuations — the same branch that correctly swallows them for a form it has just replaced, where the whole value has already been re-emitted. Because a carried plural entry deliberately supplies no `plural_forms` metadata (so the file's own forms stand), the reviewed translation collapsed to the empty first line: adding one unrelated key to the source erased a reviewed long plural form, and the entry then became permanently unwritable. Note that `msgfmt --statistics` does **not** reveal this — it reports the catalog as fully translated before and after, because a plural message with a non-empty `msgstr[0]` counts as translated — so the loss is silent even to the format's own tool; the evidence is the emitted bytes and a re-extraction. Continuation lines are now kept for a form being carried and still dropped for a form being replaced.
-
-- **xliff**: **a `trans-unit` id containing an apostrophe is read in full, so two units no longer collapse onto one key.** The id scanner captured `id=["']([^"'<]+)["']`, excluding *both* quote characters from the value — but only the delimiter actually in use needs escaping inside an XML attribute, so `id="label.don't"` truncated to `label.don`. Two units whose ids differ only after the apostrophe therefore became one key, and the single fetched translation was written into **both** units, shipping one string's translation under another string's id. XLIFF is exempt from `assertDistinctKeys`, so nothing reported the collision and the lockfile recorded the truncated key. Measured on a v1.2 file with `label.don't` and `label.don'x`: both extracted as `label.don`, and both units received the same translation. The delimiter is now captured and the value excludes only that delimiter, in both the 1.2 `trans-unit` and 2.0 `unit` scanners; a single-quoted id keeps a double quote inside it for the same reason, and a following attribute (`xml:space="preserve"`) is still not swallowed into the id.
-
-- **sync**: **`deepl sync pull` keeps the tabs and newlines of a multi-line translation instead of deleting them.** The pull value sanitizer ran `/[\x00-\x1f\x7f]/g` over every value returned by the TMS — a range that includes 0x09, 0x0a and 0x0d, the three C0 bytes this project's own `isForbiddenControlChar` exempts because every format either escapes them or legally emits them. A human-approved multi-line or tabbed translation had those bytes **deleted rather than escaped**, fusing the adjacent words (`"Zeile eins\nZeile zwei"` → `"Zeile einsZeile zwei"`), reported as `Pulled N` at exit 0. This fired on any correct TMS returning a multi-line string, not only a hostile one, and the unit test covering it asserted the fused output under a name that claimed the opposite. Tab, LF and CR now survive to the per-format writer, which escapes them; every other C0 byte and DEL is still stripped, because a raw ESC reaching a locale file renders as a live terminal command in `git diff` and CI log viewers. Verified end to end: a pulled `"Zeile eins\nZeile zwei\tmit Tab\x1b[31m"` lands in `de.json` with the newline and tab intact and the ESC removed.
-
-- **sync**: **`deepl sync audit` no longer reads files outside the project root.** Audit is the one sync read driven by `.deepl-sync.lock` keys rather than by globbed source paths, and it joined `resolveTargetPath`'s output to the project root and read it with a bare `fs.readFile`, never calling `assertPathWithinRoot` — the single bypass of a guard whose own docstring claims it "cannot be bypassed by a caller that forgets". A lockfile arrives with a clone like any other committed file, so its keys are untrusted input: a key of `../secretplace/en.json` read a file outside the root and `--format json` printed that file's string values in `inconsistencies[].translations`, at exit 0. Measured on a project with two lockfile entries sharing one `source_text`, one of them escaping the root: the report carried the out-of-root file's contents verbatim. The guard now runs before the read, and a violation ends the command at exit 6 rather than skipping the locale, matching how a sync run treats a containment violation — it is a problem with the project, not with one locale. A lockfile entry whose path merely fails to resolve for a locale is still skipped as before, so a stale lockfile does not become a hard failure.
-
-- **sync**: **one failed translate batch no longer deletes that batch's existing translations.** `translateBatch` chunks at 50 texts and deliberately keeps going when one chunk's request fails, returning empty slots for its texts. Those slots fell into a bare `failed++` with no carry-forward — unlike the validation-withheld path, which keeps whatever the target already held — and since `reconstruct` treats the entry list as the complete desired key set, the failed chunk's keys were **removed from the target file**. Translations that had already shipped were erased by a run that touched them only to re-translate them, and the run's `.bak` was unlinked because the run itself succeeded. Needs more than 50 changed strings in one file, so a single-chunk failure was always safe; for PO the whole entry disappeared, which is worse than an empty `msgstr` because `msgfmt --statistics` then reports the catalog fully translated while strings are missing. Measured on a 60-key JSON file with every value changed and the second chunk answering 500: 60 keys before, 50 after, `k51`–`k60` gone. A key the target already holds a translation for now keeps it, and — unlike the first-adoption carry above — is deliberately **not** counted as a success, so the lockfile records `failed` and the next run retries it.
-
-- **sync**: **the first `deepl sync` over an already-translated project no longer overwrites every reviewer translation with machine output.** The carry-forward that protects a reviewed translation was wired into the `current`-key path only, and a key is `current` only once the lockfile mentions it. With no `.deepl-sync.lock` — first adoption of the tool, or any CI checkout where the lockfile is gitignored — *every* key of a fully human-translated catalog arrives as `new`, so every key was re-translated, re-billed, and written over, dropping the review markers the formats carry (gettext `#, fuzzy`, XLIFF `state`) at **exit 0**, with no `.bak` surviving the successful run. Measured on a two-entry PO catalog with one `#, fuzzy` entry and no lockfile: both `msgid`s went to the engine and both reviewed `msgstr`s came back as machine output. A `new` key whose target file already holds a translation is now carried forward untouched and recorded in the lockfile, so it is neither re-translated nor re-billed, and the marker survives because the entry is rewritten with the same bytes it already had. Two things are deliberately **not** carried: a target value equal to the source (a locale file copied from the source is untranslated text, and carrying it would freeze the source language into the locale — the same reasoning the new-locale path already applies) and an empty one; both are still translated. `--force` re-translates everything as before, since asking for re-translation is what it means. `sync status` already reported and refused to re-translate these keys — the invariant is now enforced on the path that writes, not only the one that reports.
-
-- **sync**: **the `--format json` error envelope is machine-readable again: it moves to stdout, the stream nothing else writes to.** The envelope went to stderr, which is also where every diagnostic goes — the CLI's own warnings (the world-readable-config notice, the non-DeepL-endpoint key warning, every `Logger.warn` in a run) and anything the Node runtime emits (`(node:7016) ExperimentalWarning: SQLite is an experimental feature…`, which is exactly how three e2e tests broke on 2026-08-08: `JSON.parse(stderr)` failed at the opening `(`). A consumer capturing stderr got valid JSON only when nothing else happened to be said, and the failure path — the one case a script most needs to parse — was the one case sharing a stream. Measured before the fix: `deepl sync validate --format json` in a directory with no `.deepl-sync.yaml` and a group-readable config file wrote the mode-tightening warning **and** the envelope interleaved on stderr, with stdout empty. The envelope is the command's *result* in the failure case, so it now lands where the success payload already does; the non-zero exit code remains the failure signal, and warnings stay on stderr where they can no longer break the parse — asserted end to end with the CLI's own warning firing alongside a `JSON.parse` of the whole of stdout. `sync init`'s config-already-exists envelope, previously built inline, goes through the shared emitter and moves with it. See Changed for the migration note.
-
-- **sync**: **`deepl sync validate` validates the rest of the project when one target file cannot be read.** A target-file parse failure propagated out of the walk and ended the whole command at exit 1 with a raw parser message (`Error: Expected double-quoted property name in JSON at position 32`, `UnknownError` in the JSON envelope) — a project with fifty locales and one corrupt file was told about the corrupt file and nothing about the other forty-nine, which is the opposite of what a validation command is for. Every other path already refuses one file and carries on. The unreadable file is now an `error`-severity issue like any other — reported under an `unusable_target` check with the file, the locale and the parser's reason, counting toward exit **8** — and every other locale and file is validated and reported alongside it. Deliberately **not** a warn-and-skip: validate exiting 0 over a file it never validated would turn CI green on an unvalidated locale, which is strictly worse than dying. A locale with no target file at all is still skipped silently, `totalChecked`/`passed` keep counting only pairs actually compared, and a healthy project's output is byte-identical. `deepl sync audit` needed no change — measured on the same fixture, it already excludes such a locale from the comparison and reports it under `missingTargets` at its normal exit code.
-
-- **translate**: **code preservation survives a fenced block overlapping an inline code span.** The preservation passes run in sequence over already-substituted text, so a span preserved later can wrap an earlier pass's token — `` ` ``` ``…``` ` `` makes the inline pass preserve `` ` __CODE_0__ ` `` as `__CODE_1__`, and a brace-shaped span can wrap a code token the same way (`{`x`}`). Both the restore and the loss check walked the map in insertion order, so the inner token was expanded after its own pass had already run — `deepl translate --preserve-code` on that input refused the translation at exit 5 with `The translation lost the placeholder …`, blaming the endpoint for a token the CLI had nested itself, and the round-trip law (`preserve → identity-translate → restore` is the identity) failed under fast-check seed 2139537717 with three lines expected and one received. Restore now expands tokens in reverse insertion order — a stored value can only contain tokens preserved before it, so one pass unfolds every level — and the loss check counts a token as surviving when it sits inside a later span that itself survived, in the sync validator as well as the translate-path assert. The same input now translates at exit 0 with every line restored verbatim, the pinned seed replays green, and four consecutive random-seed property runs stay green.
-
-- **sync**: **a `#, fuzzy` flag on a carried-forward PO entry survives a run that rewrites the file for a sibling key.** The comment replay in the PO writer stripped `fuzzy` from every entry it emitted, and a run is handed every key the file should keep, so any sync with other work to do silently removed a reviewer's "do not ship" marker — after which `sync status` reported the project 100% complete again and `msgfmt` compiled the questioned translation into the catalog. Measured through the CLI: flag one synced key by hand (`sync status`: `50% (1 needs review)`, the behavior the needsReview counting was built on), add one new source key, `deepl sync --yes` — the flag was gone and `status` said `100%`, at exit 0. The flag is now stripped only when the run writes **different content** over the entry — the same test the XLIFF writer applies to its review `state` — comparing the msgstr and every `msgstr[N]` against what this run writes. A carried-forward entry now keeps its comment lines byte-for-byte (a `#, fuzzy, python-format` line is no longer re-joined either), verified with a byte diff across a sync whose only work was a sibling key: the only change in the file is the appended new entry. A re-translation that produces different content still clears the flag, and `msgfmt --statistics` confirms both directions.
-
-- **sync**: **a plural entry a run carries forward keeps its plural forms.** A carried-forward entry was handed to the file writer with the **source** file's plural payloads — empty `msgstr[N]` for gettext, source-language `<item>`s for Android XML — and plural content is rebuilt from exactly those payloads, so any run with other work to do destroyed the target's plural translations at exit 0. Measured through the CLI against a mock engine on three paths. **Translate**: a PO project holding a translated plural entry had `msgstr[0]` / `msgstr[1]` emptied by a sync whose only work was one new sibling key — `msgfmt --statistics` went from `3 translated messages` to `3 translated, 1 untranslated` — with the run misreporting its own destruction as `could not be given 1 translated key … the target file has no element to hold it` and the next sync re-translating and **re-billing** the entry. Android XML was worse: reviewer-corrected items (`Un archivo` / `Muchos archivos`) were silently reverted to the English source (`One file` / `Many files`) with no warning at all, because the reverted values are non-empty and the write-verification saw the key as present. **Validation withholding**: a stale plural entry whose fresh translation failed validation was supposed to keep what the file holds and emptied its forms instead. **Pull**: any `deepl sync pull` that rewrote a PO file emptied plural forms whether or not the export carried the plural key. The carry-forward sites and the pull merge now omit the plural payloads from what they hand the writer, so the parsers keep the file's own forms, and Android's writer keeps a `<plurals>` element verbatim for an entry handed over without per-form translations — a key absent from the entry list is still deleted. A plural entry whose source text actually changed is still re-translated with fresh forms. See docs/SYNC.md "A plural entry carried forward".
-
-- **sync**: **an XLIFF review `state` is no longer counted as a finished translation.** `<target state="needs-review-translation">` in 1.2 and `<segment state="initial">` in 2.0 mean a translation exists but is not approved; every read path took the `<target>` at face value, so a project shipping unapproved strings reported itself done. Measured end to end on a two-unit project through the CLI, in both versions: after flagging one unit with its source unchanged, `deepl sync status` said `100% (0 missing, 0 outdated)`, `--format json` said `needsReview: 0` and `complete: 2`, `sync validate` said `All translations passed validation` and `sync --dry-run` said `2 current`. The same project now reports `50% (0 missing, 0 outdated, 1 needs review)`. `deepl sync push` skips such a unit under the existing `needs_review` reason instead of uploading it as approved. The states are read as an explicit claim only: 1.2's `new` and `needs-*` values and 2.0's `initial` count, `translated` / `signed-off` / `final` / `reviewed` do not, and an **absent** attribute or a value outside those sets counts as complete — which is why an existing project's coverage does not move. In particular 2.0's documented `initial` default is deliberately not applied to a segment that carries no `state`, since that is the shape the CLI itself writes. `state-qualifier` (1.2) and `subState` (2.0) are different attributes and are not read. Nothing is re-translated, rewritten or re-billed; both ways out were measured — changing the state to `translated` returns the key to `complete` with **no API call**, and emptying the `<target>` has the next `deepl sync` translate it afresh.
-
-- **sync**: **a `state` attribute on an XLIFF target the CLI has just written now describes what the CLI wrote.** A source XLIFF exported with `<target state="needs-translation"></target>` placeholders — what most CAT tools produce — yielded a target file whose every unit claimed it still needed translating about a string the CLI had just translated, in both versions (2.0 kept `<segment state="initial">` around a filled-in target). The file contradicted itself, any consumer reading `state` would ignore or re-request work already paid for, and with the counting above every one of those keys would have reported as needing review forever. Such a state now becomes `translated` when reconstruct replaces the target's content, and a `signed-off` state the CLI writes over is downgraded the same way rather than claiming human approval for machine output. An element carrying no `state` still gains none, and a `state` on a unit whose translation is **unchanged** is never touched — which is what keeps a reviewer's `needs-review-translation` alive through a run that translates a sibling key, verified on the real write path.
-
-- **watch**: **two watched files with the same name no longer write one translation on top of the other.** The output path was built from the source's basename alone, so every `doc.md` under the watched tree mapped to one `<output>/doc.es.md` and the last translation to finish silently replaced the ones before it — the whole of the losing file's translated output gone, at exit 0, with no warning and nothing in the summary to notice: the count still read `Translations: 2`. Measured on a watched tree holding `a/doc.md` ("Hello") and `b/doc.md` ("Good morning") with `--to es`: `translateFile` was called twice with the same `out/doc.es.md`, `out/` held one file, and its contents were `b/doc.md`'s translation. The output now carries the source's directory relative to the watched path, so those two write `out/a/doc.es.md` and `out/b/doc.es.md` — both texts, at 2 API calls, unchanged from before. The same flattening ran on **three** paths, not the one: the single-target path built the name itself, and the multi-target path (`--to es,fr`) handed a bare output directory to `FileTranslationService.translateFileToMultiple` for text files and to `StructuredFileTranslationService` for JSON and YAML, each of which then applied the same basename rule. All three now take the per-source directory. Verified end to end through the CLI against a mock API with the **default** output directory (`<watched>/translations`, which sits inside the watched tree): both translations landed under their own subdirectory, `translateCalls` settled at 2 with no further activity, so the loop guard still recognises a nested output as the CLI's own work and does not re-translate it. The layout is what `deepl translate <dir> --output <dir>` already produced — measured on the same fixture, which wrote `out/a/doc.es.md` and `out/b/doc.es.md` — so watch was the one command flattening. See Changed for the paths that move.
-
-- **watch**: **the loop guard no longer warns about the temp file the CLI is writing through.** `atomicWriteFile` renames from a `<target>.tmp.<pid>.<random>` sibling, which has to sit beside its target because a rename is only atomic within one filesystem — so a watcher on the output directory sees it appear and vanish. Its name carries the output file's, so the output-file check matched it and the session printed `Skipping …/doc.es.md.tmp.4242.a1b2c3: it is inside the output directory and named like a translated output … Move it outside …` about a file that this process had already renamed away, telling the user to move something that no longer exists. Such a path is now recognised as an in-flight write and ignored, before the output-file check. A real output-looking file the user put there still gets its one warning.
-
-- **sync**: **`sync status` counts a failed translation as `missing` rather than `outdated`.** `outdated` is documented as "recorded against an older source"; a failed attempt is recorded against the **current** source and produced no translation at all, so the count named the wrong problem — a reader chasing an outdated string would go looking for a source change that never happened. `missing` and `outdated` therefore both move for a project with failed translations in its lockfile. Nothing else changes: `--frozen` computes its own gating from the source diff and is unaffected, and a genuinely stale hash is still `outdated`.
-
-- **sync**: **a gettext `#, fuzzy` translation is no longer counted as complete.** Every read path treated the msgstr of a fuzzy entry as a finished translation, but `fuzzy` is gettext's way of saying "needs review, do not use": `msgfmt` leaves the entry out of the compiled catalog, so the string the CLI called done is one the application does not display. Measured against that oracle on a two-key PO catalog with one entry flagged and its source unchanged — `msgfmt --statistics` said `1 translated message, 1 fuzzy translation` while `deepl sync status` said `100% (0 missing, 0 outdated)`, `complete: 2`, `unwritten: 0`, `sync --dry-run` said `2 current`, `deepl sync` made **0 requests**, and `sync validate` said `All translations passed validation`. So a project shipping an untranslated string reported as finished, indefinitely. Such a key is now its own **`needsReview`** category in `sync status` (text suffix `, 1 needs review` plus a line explaining the flag and both ways out; `needsReview` on each locale in `--format json`), and the same catalog now reports `50%`, agreeing with `msgfmt`. `deepl sync push` skips it under a new **`needs_review`** skip reason instead of uploading a reviewer's draft as an approved translation. **Nothing is re-translated and nothing is rewritten**: the value belongs to whoever flagged it, so reading it as untranslated would have replaced a human's in-progress work with machine output and re-billed every fuzzy entry in the project — the one outcome worse than an overstated percentage. Both documented remedies were measured end to end: removing the flag returns the key to `complete` (`msgfmt`: `2 translated messages`), and clearing the msgstr has the next `deepl sync` translate it afresh. `sync --frozen` deliberately still passes, since a fuzzy entry is a normal transient state in a gettext workflow that only a human review clears. XLIFF's `state="needs-review-translation"` is the same idea in the other bilingual format and is tracked separately: its states differ between 1.2 and 2.0 and no external tool arbitrates which of them mean "will not ship", where `msgfmt` settles it for PO.
-
-- **sync**: **`--dry-run` now previews the run rather than the lockfile, in both directions it was wrong.** The dry-run branch returned before the two target-file checks the real run makes, so the estimate came from the lockfile alone. Measured against a real endpoint on a JSON project with one damaged locale. **Under-reporting:** with a key the lockfile calls translated deleted from the target file, `deepl sync --dry-run` reported `Sync complete: 2 current`, `estimatedCharacters: 0` and no cost line at all, while the very next real run translated it — `✓ es: 1/1 keys`. **Over-reporting:** with a new source key added and the target file left unreadable, dry-run reported `estimatedCharacters: 12` and `ok: true` at exit 0, and said nothing about the file; the real run refused the locale, billed **0**, reported `failed: 3` and exited **12**. So the one command whose job is deciding whether to spend money under-quoted repair work and over-quoted work that was never going to happen. Both halves now come from one `findTargetGaps` call per source file — the machinery `--frozen` already uses, which returns the missing keys and the unreadable reason from the same read: keys the target no longer holds are added to the estimate and reported as `unwrittenKeys`, and a locale whose target file is unreadable is left out of the estimate and named in its own warning ending `It is left out of the estimate below. Fix it before running \`deepl sync\`.` A dry run still writes nothing — no target file, no lockfile, no backup — and still exits 0, since it reports what a run would do rather than standing in for its exit code, which is what `--frozen` is for. Because the summary counts a repair key as `current`, the run now also says `1 key is recorded as translated in the lock file but could not be confirmed in the target file, so a real run would translate it again`, so the character estimate is not a number with nothing behind it. **The bead's suggested cheap option was based on a wrong premise**: warning about an unreadable target "without paying for a full audit" costs exactly the same reads, because a file cannot be known to be unreadable without opening it, and the gap keys fall out of that same read for free. **Cost, measured** on a 20,000-key, 6-locale JSON project (2.83 MiB source, 17.3 MiB of targets, 24 MiB lockfile): `--dry-run` 0.44 s → 0.75 s, against 0.77 s for `sync status` and 0.79 s for `sync --frozen`; peak RSS 283 MiB → 370 MiB. A locale the lockfile claims nothing for is not read at all, so a project mid-first-sync pays nothing.
-
-- **sync**: **the `sync.max_characters` cost cap no longer under-counts the work it is meant to cap.** Its preflight estimate came from the same lockfile-only arithmetic as `--dry-run`, so repair work was invisible to it: on a fixture whose lockfile claimed ten translated keys for a locale with no target file at all, plus a newly added locale, the cap computed **500** characters for a run that bills **1,000** — a cap set at 500 let it through. The cap and `--dry-run` now quote from one function, so a run the preview prices above the cap is a run the cap refuses. This costs one pass over the target files before the cap decides, where it previously decided without reading anything: measured on the fixture above, a translating run went from 1.54 s to 1.91 s against a local mock, where no network latency dilutes the fraction. Projects that do not set `max_characters` are unaffected.
-
-- **sync**: **`--frozen` no longer reads every target file twice.** On a project with no drift the target-versus-lockfile comparison ran once for the drift check and again for the "nothing left to do" check, since each call started a fresh audit. The answer is now computed once per source file and reused, which took `sync --frozen` from 1.13 s to 0.79 s on the 20,000-key, 6-locale fixture above and cut its peak RSS from 469 MiB to 382 MiB. No output changes.
-
-- **watch**: **`--git-staged` now matches its files when the watched path reaches the repository through a symlink.** Two spellings of one path were compared: the staged set is built from `git rev-parse --show-toplevel`, and git always answers with the repository's **real** path, while the watcher compared the path the user typed. Where those differed by a symlinked ancestor, no watched file was ever in the staged set. Measured with the built CLI at e97d835 against a real endpoint, started from the repository root so the working-directory fix above does not apply: `deepl watch /tmp/link/src --to de --git-staged` over a symlink to a repository with one staged file reported `Git-staged files: 1`, printed `Watching for changes...`, and then ignored every edit for the rest of the run — no `Change detected`, **0 translate requests**, empty output directory, **exit 0** — where the same session watching the real path translated the file and wrote `a.de.md`. macOS reaches this with no symlink of the user's own, since `os.tmpdir()` is `/var/folders/…` symlinked to `/private/var/folders/…`, as does any project under a symlinked checkout root. The same two-spellings defect had a **second, independently measured site**: the loop guard's warn-once bookkeeping also compared unresolved paths, so a session whose output directory is reached through a symlink warned `Skipping …/link/src/translations/a.de.md: it is inside the output directory and named like a translated output … Move it outside …/repoA/src/translations to have it translated` about a file **the CLI had just written itself** — a message naming two different spellings of one directory, telling the user to move their own output. Both sites now compare a canonical key with symlinked ancestors resolved and the final path component left alone: a staged file that is itself a symlink is the file git tracks, not its target, so resolving the last component would have broken a case that worked. Messages still show the path as the user spelled it; only the comparison keys are canonical. After the fix the same symlinked session reports `Change detected`, issues 1 translate request and writes `a.de.md`, and the mirror case writes its output with no warning at all.
-
-- **watch**: **`--auto-commit` and `--git-staged` now act on the repository holding the files they name, not on the directory the CLI was started in.** Every git invocation behind both flags ran with no working directory of its own, so watching a path outside the current repository handed one repository's pathspecs to another's index. Measured with the built CLI over two real repositories and a real endpoint. With the terminal in an unrelated repository, every translation failed to commit with `fatal: .../repoA/out/doc.de.md: '.../repoA/out/doc.de.md' is outside repository at '/private/.../repoB'` — one counted auto-commit failure per translated file, the session exiting 12, and the translation left untracked. With the watched repository nested inside the one holding the working directory, `git add` silently did nothing at all, because git does not descend into another repository, and the commit then failed with `error: pathspec '.../out/doc.de.md' did not match any file(s) known to git`. With the working directory in no repository, the session printed `⚠️  Not a git repository, skipping auto-commit` — untrue, the watched path was one — and **exited 0** having committed nothing, which is the silent half. No case committed into the wrong repository's history: git refuses a pathspec outside its own working tree, so the defect was that the flag could never work rather than that it worked somewhere else. **`--git-staged` was the more reachable half, and failed silently inside a single repository with no unusual layout at all.** `git diff --cached --name-only` names its files relative to the repository root, and the result was resolved against the process working directory, so `deepl watch ./docs --git-staged` started from any subdirectory reported `Git-staged files: 1`, printed `Watching for changes...`, and then matched nothing for the rest of the session: every edit to the staged file ignored, no translation, no output, exit 0. Started from another repository it read that repository's index instead and stopped at `No git-staged files found. Nothing to watch.` Both flags now resolve their repository from the path they act on — `git rev-parse --show-toplevel` anchored on the output directory for the commit, and on the watched path for the staged snapshot, with every staged name resolved against that repository's root. Output paths are made absolute before the working directory changes, so a relative `--output` still commits the file it wrote: `deepl watch ../repoA/src --output ../repoA/out --auto-commit` run from a sibling repository now commits `out/doc.de.md` into repoA at exit 0 and leaves the CLI's own repository untouched, as does the same session run with absolute paths, from a non-repository directory, or over a nested repository.
-
-- **sync**: **`sync resolve` no longer warns about possible data loss on every ordinary lockfile merge.** The lockfile's own metadata was the one part of the file where git could produce a conflict region that is not a whole anything. `stats` sits two context lines below `generated_at`, and every write changes both, so git joined them into a single region — which, with `stats` expanded over five lines, opened inside `stats` and closed outside it. That is not a member list, so `JSON.parse('{' + region + '}')` failed, the region fell to the length-heuristic fallback, and the resolver emitted `WARN .deepl-sync.lock:<conflict-region> — parse-error fallback used, JSON.parse failed on ""generate…"` and picked a side by byte length. Measured over a real `git merge` of real serializer output: it fired in every case where both branches had run a sync, including the most common one of all — two branches translating **different** keys, where git merges the entries map perfectly and there is no real conflict at anything — which reported `Resolved 1 conflict (0 theirs, 0 ours, 1 length-heuristic)`. Since the docs tell the reader a `length-heuristic` decision is a data-loss risk to inspect by hand, the one signal that exists to make silent data loss auditable fired spuriously on every single resolve, and a warning about a region that really did carry a translation was indistinguishable from the routine noise. **`stats` is now written on one line**, like a translation and for the neighbouring reason — its counts and `last_sync` describe one sync run — so the region stays a member list and merges normally: the same fixtures now report `generated_at` and `stats.last_sync` as ordinary per-member decisions with no warning at all. Nothing was lost while the fallback was picking sides, as it happens: `total_keys` and `total_translations` are recomputed from `entries` on every read and `generated_at` is overwritten on every write, so the block it was arbitrating carries no information — which is exactly why warning about it was wrong. Upgrading reformats every existing lockfile on the next write; it is formatting only, five lines becoming one, and no entry's content changes.
-
-- **sync**: **`sync resolve` no longer merges a translation field by field when one side is missing `translated_at`, which produced an entry that existed on neither branch.** Measured over a real `git merge` of real serializer output: ours held `{"hash": "human_hash", "review_status": "human_reviewed", "status": "translated"}` and theirs `{"hash": "machine_hash", "review_status": "machine_translated", "translated_at": "2026-08-03T15:00:00.000Z"}`; the resolver wrote `{"hash": "human_hash", "review_status": "human_reviewed", "status": "translated", "translated_at": "2026-08-03T15:00:00.000Z"}` — ours' hash and review status carrying theirs' timestamp — reported as three per-field decisions and exit 0. That is precisely the fabrication the one-line lockfile format exists to prevent, performed by the resolver after git had correctly raised the conflict. The cause was the translation predicate: it recognised a leaf by `translated_at`, or failing that by `source_hash`, which belongs to the *entry* around a translation and not to the translation itself, so a translation whose only remaining identifying field was `hash` was not recognised and fell through to the generic member-by-member merge. Nothing validates `translated_at` on read — the shape survives a lockfile round trip untouched — and `human_reviewed` is only ever set by hand, so a hand-edited entry is the reachable path. A translation leaf is now identified by `hash` as well, and **one side being one is enough**: a pair is arbitrated whole whenever either side looks like a translation, so no field combination can be invented regardless of how degraded the other side is. **Two decision reasons also stated things that were not true.** Equal timestamps reported `kept ours: newer translated_at 2026-08-04T10:00:00.000Z` when neither side was newer — now `kept ours: same translated_at <stamp> on both sides`. And a pair where *ours* had a timestamp and theirs did not fell to the terminal branch and reported `kept ours: neither side had translated_at` — now `kept ours: theirs had no translated_at`, with the mirrored case worded to match. A `translated_at` that is not a string now counts as absent rather than being compared against an ISO timestamp, so a lockfile committed by another tool cannot steer the tie-break with a non-comparable value.
-
-- **sync**: **a TMS that cannot be reached is a network failure (exit 5), not an unclassified one (exit 1).** `fetch` rejects with a bare `TypeError: fetch failed` and puts the errno on `cause`, and the request loop threw that rejection as it stood, so the run ended at `Error: fetch failed` — no host, no port, no code, no remediation — and at the exit code `docs/API.md` tells CI to read as "the CLI crashed, investigate". Measured with the built CLI on three shapes: a refused connection to a port with nothing listening and an unresolvable hostname both exited **1**, while a server that accepted the connection and never answered exited **5** with `TMS request timed out after 1500ms: PUT http://127.0.0.1:60423/…` and a suggestion — the same condition, differently timed, reported two different ways. All three now exit 5 and name the request: `TMS request failed: PUT https://tms.example.com/api/projects/p/keys/greeting: ECONNREFUSED`, plus a line pointing at the `server:` URL in the `tms:` block. Everything the request loop catches is a transport failure by construction — the fetch call is all it awaits, and every response-level outcome is judged after it returns — so the classification needs no code allowlist; an error that is already a `NetworkError` keeps its own message, and a 401, a 500 and a timeout each keep theirs, with a guard apiece. **The replay policy is deliberately unchanged**: retry eligibility is decided before the error is classified, and both counts are asserted — a refusal is still retried to `tms.retry.max_attempts` (3 calls), an unresolvable name still fails on the first (1 call). While measuring this, note that `http://127.0.0.1:1` is not a usable repro: `fetch` refuses port 1 as a blocked port with `cause.message: "bad port"` and no code, before any connection is attempted.
-
-- **sync**: **`TMS server URL must use HTTPS` now says which spellings are waived and how to reach a local TMS.** Plain `http://` is accepted for `http://localhost` and `http://127.0.0.1` only — the same pair the DeepL API base URL waives — so a developer whose `.deepl-sync.yaml` named `http://[::1]:3000` got a one-line refusal at exit 7 with no way to act on it. The rule is unchanged; the error now echoes the URL and points at `http://localhost`, which was measured to reach a server bound to `::1` only (HTTP 200 through the CLI, the `::1`-bound server logging the `PUT`) as well as one bound to `0.0.0.0` or `127.0.0.1`, so it covers every local bind rather than being a partial answer. The waiver was deliberately **not** widened: it would make this rule more permissive than the one for `--api-url`, `0.0.0.0` is not a loopback address, and `127.0.0.2` is not bindable at all without aliasing the loopback interface (`EADDRNOTAVAIL` on macOS). `http://0x7f.0.0.1`, `http://127.1` and `http://2130706433` were already accepted, contrary to the finding: the URL parser normalizes all three to `127.0.0.1`, which four new tests pin so the change cannot widen the gate. The destination-trust gate still does not exempt loopback at all, and answers a different question.
-
-- **sync**: **a target file that cannot be read is left alone instead of being re-translated and overwritten.** The pre-read of each locale's target file swallowed every failure into "this locale has no existing translations", which cannot tell a locale that has never been synced — nothing to lose — from one whose file is on disk and unreadable, which holds the only copy of its translations, since the lock file records hashes rather than translated text. Measured end to end against a mock endpoint, on a healthy two-key JSON project whose `locales/es.json` was then given a flat `"menu.save"` beside a nested `"menu": {"save": …}`, the `.`-separator collision a bad merge produces and the JSON parser refuses: `deepl sync --yes` printed `✓ es: 2/2 keys` and `Sync complete: 2 current` at **exit 0**, made 1 billable translate request where a healthy repeat run makes 0, and rewrote the file as `{"greeting": "Hola", "added": "Traduceme"}` — both hand-reviewed translations replaced by fresh machine output and the file's two other keys deleted — with nothing in the output naming the file. The same happened with the source changed as well (2 requests, exit 0), so this was not an artefact of the `unwritten` repair path added earlier in this release, and the same happened to a file present but unreadable (`chmod 000`), which was rebuilt from the source template and kept its mode, so the damage was not even visible afterwards. The reach is wider than one format: of the parsers that can refuse a file, `json`, `laravel_php` and `android_xml` each have a `reconstruct` that accepts a template its own `extract` rejects and rebuilds it silently, while `po` and a JSON syntax error happened to fail loudly in `reconstruct` — but only after the whole locale had been re-billed. `ENOENT` is now the only read failure that means "absent". Any other errno, and any parse failure, marks that locale unusable for that file **before any translation is requested**: the run prints `Sync failed for locale "es" on "locales/en.json": target file locales/es.json is on disk but could not be read (<reason>) — it holds the only copy of this locale's translations, so it was left as it stands rather than rebuilt from the source. Fix it, then run `deepl sync` again.`, reports `✗ es: 0/2 keys`, exits **12**, bills **0** characters, and leaves the file byte-identical. A key the source has just gained is recorded `failed` rather than `translated`, so the next run retries it once the file is fixed. `deepl sync pull` had the same conflation with a carve-out for one cause (a key collision, added earlier in this release) and now routes every unreadable target to the same outcome: measured on a target file holding git conflict markers, pull printed `Pulled 1 translations` at exit 0 having replaced it with `{"greeting": "TMS-Hola"}`, discarding the local-only key the export does not carry; it now leaves the file byte-identical and records a new `unusable_target` skip reason. `deepl sync push` needed no change — it already propagates every error but `ENOENT`, which is the distinction this fix generalizes. One reader (`readTargetFile`) now answers absent / usable / unusable for all four call sites, and costs no extra I/O: it replaces a read that was already being made.
-
-- **sync**: **`sync status` no longer says the keys of an unreadable target file "are not in the target file", nor tells you to sync again.** Both halves of that sentence are wrong for a file nobody managed to open — its contents are unknown, and `deepl sync` now refuses to rebuild it — so the advice bounced the user between a `status` that said to run `sync` and a `sync` that declined. The count is unchanged, since a file whose contents are unavailable still cannot be shown to hold what the lock file claims; only the reporting is: such a file gets its own sentence naming it and the reason (`2 keys are recorded as translated in the lock file for a target file that could not be read — es: locales/es.json (JSON: 'menu.save' is the key of two different strings. …). Fix the file: \`deepl sync\` will not overwrite it.`), and a project with both kinds of gap gets both sentences rather than one that conflates them. `--format json` carries the reason as a new `unusable` field on the locale's `unwrittenByLocale` entry, absent when the file was read and genuinely lacks the keys. The `--frozen` drift line no longer asserts a cause it has not checked either, and points at `sync status` for the detail.
-
-- **sync**: **a target file that has lost translations the lock file records as translated is no longer reported as 100% complete.** Nothing compared the two: `deepl sync status` and `deepl sync --frozen` both diffed the SOURCE file against `.deepl-sync.lock` and never opened the target file, and `deepl sync` itself returned early whenever the lock file said there was nothing to do. Measured end to end on a healthy two-key project with one key's line deleted from `locales/es.properties` by hand: `sync status` printed `es [####################] 100% (0 missing, 0 outdated)` at exit 0, `sync --frozen` printed `Sync complete: 2 current` at exit 0, and `sync --yes` printed `Sync complete: 2 current` at exit 0 having written nothing — indefinitely, on every run. This is the residual half of the key-dropping finding fixed earlier in this release: the writers no longer drop keys, but a project already damaged by the old behaviour was not repaired by upgrading, and the workaround was to add a string and sync or delete the target file. It is not specific to that, either — a bad merge, a partial checkout, a hand deletion or a `git checkout` of an older locale file all read as complete, and `--frozen` is the CI drift gate whose entire purpose is catching a locale that is not up to date. For every key the lock file records as `translated` against the current source text, the locale's target file is now read and checked. A key it does not hold is counted **`unwritten`** — its own category, distinct from `missing` (absent from the lock file) and `outdated` (recorded against an older source), never counted as complete — so the same project now reports `es [##########..........] 50% (0 missing, 0 outdated, 1 unwritten)` plus a line naming the file and the key, `--frozen` exits **10** naming the count, and `sync` translates the key again and writes it. A target file that cannot be read or cannot be parsed counts all of its claimed keys, which also closes the pre-existing hole where any target-file parse failure read as "no existing translations". Two exemptions, both deliberate: a key whose **source value is empty** is never reported, because an empty source can only produce an empty translation and PO and XLIFF read an empty translation side as untranslated on purpose; and a key already recorded `failed` or against an older hash is not counted twice. `sync` is **not** made to rewrite target files to force agreement — the narrow action is to stop reporting complete and let the existing re-translation path run. **Cost, measured before adopting** on a 2.8 MiB XLIFF source with 20,316 keys across 6 locales (52 MiB of files): `sync status` 410 ms → 660 ms and 207 → ~307 MiB peak RSS; `sync --frozen` 465 ms → 970 ms and 216 → ~365 MiB. The read is skipped entirely for a locale the lock file claims nothing for, and a run that has translating to do never triggers it, since it reads every target file a few lines later anyway. New JSON fields on `sync status`: `unwritten` per locale and a top-level `unwrittenByLocale`; new field `unwrittenKeys` on the sync result.
-
-- **sync**: **a PO catalog written without blank lines between its entries is no longer collapsed into one entry.** The blank-line separator is a gettext convention, not a requirement — `msgfmt -c` exits 0 on every fixture below — but both halves of the PO parser treated it as the only thing that ends an entry, and the damage was total. Measured on a legal five-message catalog with no separators at all: `extract` reported **one** key (`Third`, the last one), so `Hello` and `Bye` were absent from the source key set entirely, and `reconstruct` wrote that single translation into **every** `msgstr` it walked past, the header's included — `msgstr ""` plus `"Content-Type: text/plain; charset=UTF-8\n"` and `"Plural-Forms: nplurals=2; plural=(n != 1);\n"` became `msgstr "[T]Third"`, and `msgfmt -c` on the output then warned `Charset missing in header. Message conversion to user's charset will not work.` Four more shapes were measured, none of them named in the original report: a catalog whose entries carry `#:` comments silently **lost** the whole first entry from the output; an obsolete `#~` run between two messages **deleted the header outright**, at which point `msgfmt -c` failed the output with `PO file header missing or invalid` (exit 1); a plural entry lost its `Plural-Forms` rule and failed `msgfmt -c` with `header entry lacks a "plural=EXPRESSION" attribute`; and `extractTranslations` — the bilingual target read used by `sync`, `push`, `pull`, `validate` and `audit` — reported only the last entry as translated, so every other reviewed `msgstr` looked untranslated and was re-translated and re-billed on every run. An entry now ends where gettext ends it: at the first line that is not a continuation of its translation, i.e. a comment, a `msgctxt`, or the next `msgid`. **Both the reader and the writer needed it** — they scan entry blocks independently, and each was proven to be insufficient alone with its own control: with only the writer fixed the header survives but the key set is still one entry; with only the reader fixed the keys are right but the header is still destroyed. All six catalogs now pass `msgfmt -c` on both input and output, keep their charset and plural rule, and are a fixed point across three successive syncs. Layout is untouched: a catalog that arrived without separators keeps that shape. The blank-line-separated form, multi-line `msgid`/`msgstr` continuations and plural entries are all unchanged.
-
-- **http**: **a response the endpoint cuts off mid-body is reported as a network failure (exit 5), not as invalid input (exit 6).** axios attaches the 200 response to the error it raises for an aborted response stream, and `classifyError` let the mere presence of a response decide: it took the HTTP-status branch and returned `ValidationError('API error: stream has been aborted')`, telling the operator to check input that was never the problem. Reproduced against a stub that declares a `Content-Length`, writes 12 bytes of the body and destroys the socket: `deepl translate "Hello" --to es --max-retries 3` printed `Error: API error: stream has been aborted` at **exit 6**, and `deepl usage` the same. Both now exit **5** with `Network error: the API answered HTTP 200 but its response body did not arrive intact: stream has been aborted`. The test is the status, not the axios code or message: a rejection carrying a 2xx response can only have failed while the body was read, whereas the code varies with how the peer failed (`ERR_BAD_RESPONSE` for an aborted stream, a socket or zlib code otherwise) — both the `Content-Length` and the chunked truncation shapes were measured to confirm it. 3xx, 4xx and 5xx responses keep the classification they had. **The replay policy is deliberately unchanged**, contrary to the finding's framing: the request counts were measured before and after and are identical, 1 for the POST and `--max-retries + 1` for the GET. A 200 means the server accepted — and may have billed — the request, so replaying the billable POST is exactly what must not happen here; the idempotent GET was already being replayed, so the "never retried" half of the report did not hold. The client-side deadline path is untouched: it still restates its own aborts as `ETIMEDOUT` before classification, so both routes end at `NetworkError`.
-
-- **sync**: **the startup stale-backup sweep no longer deletes a crashed run's backup, so recovery is no longer limited to the five minutes after the crash.** `deepl sync` refuses to overwrite an existing `<target>.deepl.bak` (`COPYFILE_EXCL`, warn, leave it alone) precisely because after a `kill -9` that backup holds the only surviving copy of the user's translations — but the sweep runs first, at startup, and unlinked every `.deepl.bak` older than `sync.bak_sweep_max_age_seconds` (default 300) without looking at its content, which left that guard nothing to collide with. Reproduced end to end against a mock endpoint: with `locales/de.json` holding machine output, `locales/de.json.deepl.bak` holding `"HUMAN TRANSLATION"`, no lockfile, and the backup's mtime backdated ten minutes, `deepl sync --yes` reported `✓ de: 1/1 keys`, `Sync complete: 1 new`, **exit 0**, and the human translation existed nowhere in the project afterwards — the same harm the `COPYFILE_EXCL` guard was added to prevent, reached around it. The identical run with the backup dated ten **seconds** earlier kept it and warned, which is what made age the whole of the bug. A stale backup is now deleted only when the file beside it already holds the same bytes: a run that reaches its end unlinks its own backups, so one still on disk is from a run that did not, and there it is the last copy of whatever that run had already overwritten. Size is compared first and the contents only when the sizes agree, so the common case (no backup at all) costs one `readdir` as before. A backup whose target has diverged, or whose target is gone, is kept however old it is and reported once per sweep, naming the file: `Keeping 1 leftover backup file whose content is not in the file beside it: locales/de.json.deepl.bak. It is from a run that did not finish, so it may hold the only copy of translations that run overwrote.` Retention is bounded at one file per target, since the backup's name is derived from the target's, so this cannot accumulate. `bak_sweep_max_age_seconds` keeps its meaning for redundant backups and no longer sets a deadline for recovering a crashed run. The fix is in `sweepStaleBackups`, which every caller shares — `deepl sync`, `sync push`, `sync pull`, `sync export` and `sync --watch`'s startup sweep. Three tests asserted the old policy by giving a stale backup no sibling or a differing one; those fixtures now say which case they mean.
-
-- **sync**: **`sync resolve`'s merge is no longer erased by a concurrent sync, and no longer risks truncating the lockfile.** The process lock was honoured by exactly two call sites — `deepl sync` and `deepl sync pull` — and `sync resolve` took none, while writing the lockfile with a plain `fs.writeFile` rather than the rename every other lockfile writer uses. Measured through the real CLI with a slow sync holding the lock: a second `deepl sync` was correctly refused at exit 7, while `deepl sync resolve` **proceeded**, reported `Resolved 1 conflict` and wrote the merged lockfile at exit 0 — and when the sync finished (also exit 0) the merged entry was gone, because the sync had read the pre-merge lockfile at startup and wrote its whole in-memory copy at the end. Both steps reported success, so the merge-conflict recovery path lost data silently. `sync resolve` now takes the lock — `--dry-run` included, matching `sync pull` — and exits 7 with the same "Another `deepl sync` process is running" message while one is held, leaving the conflict markers in place for after the sync. Its write goes through the atomic rename, so a crash part-way through leaves the previous lockfile instead of a truncated one; a truncated lockfile reads as corrupt and is replaced with an empty one, which costs a full re-translation of the project. And because a hand edit, a `git merge` or another tool takes no lock at all, a run whose lockfile changed on disk between its read and its write now says so and still records what it did — warning rather than refusing, since by that point the target files are written and the translations billed, and declining to record them would bill every one of them again on the next run.
-
-- **watch**: **`--auto-commit` no longer loses most commits under an edit storm.** `WatchService.onTranslate` was typed `=> void` and called without `await`, so the async callback the watch command supplies — the one that awaits `autoCommit` — had its promise discarded. The git work therefore ran outside the translation's concurrency slot, unbounded and untracked, and git holds `.git/index.lock` for the duration of an `add` or a `commit`, so parallel auto-commits knocked each other out. Measured through the real CLI in a real repository, six watched files edited at once with a 300 ms stub delay: **6 translations, 2 commits, 4 auto-commit failures** (three `git add` and one `git commit`, all lock contention), three output files left untracked and a fourth left staged but uncommitted — where an unrelated later commit would have swept it in. The session still exited 0. `onTranslate` may now return a promise and it is awaited, so the callback runs inside the translation's slot and a rejection reaches `onError`; the git work is additionally queued one `add`/`commit` pair at a time. Same harness after the fix: **6 translations, 6 commits, 0 failures**, nothing left untracked or staged. Translations of different files still run in parallel — only the git step is serialized.
-
-- **watch**: **a source file whose name carries a target-language segment is translated instead of being skipped for the whole session.** The loop guard that stops the CLI's own output re-triggering the watcher matched on the *name* alone, anywhere under the watched path, so `pricing.es.md` under `--to es` was silently dropped: measured through the real CLI, no request, no output file, and not even a `📝 Change detected` line, while `plain.md` in the same directory translated normally. Every file the watcher writes lands in the output directory, so the guard now also requires the file to be *inside* it — which leaves the loop protection complete and lets any such file outside it through. Verified on the same harness: `pricing.es.md` now produces `out/pricing.es.es.md`, and pointing `--output` at the watched directory still translates `doc.md` to `doc.es.md` exactly once with no further request. In that same-directory layout a file the CLI did not write is still skipped — the name is genuinely ambiguous there — but now says so once per file instead of doing nothing, naming the file and the output directory to move it out of. The CLI's own writes are skipped in silence, since that is the guard working.
-
-- **watch**: **a slower translation of older content no longer overwrites a newer one, leaving the output permanently stale.** `deepl watch` dropped its debounce bookkeeping when the timer fired rather than when the translation finished, so an edit arriving during an in-flight translation started a *second* translation of the same file; `--concurrency` (default 5) let both run, and both wrote the same output path in API-completion order. Measured through the real CLI against a mock endpoint answering the first request after 6000 ms and the second after 200 ms: request 1 carried `VERSION-A`, request 2 carried `VERSION-B`, the newer translation was written first and the older one then overwrote it, leaving `out/doc.de.md` holding the translation of the **pre-edit** source at exit 0 with two `✓ Translated` lines and no warning. Nothing recovers from that state on its own — the file will not change again, so no further watch event ever fires. A file is now translated one version at a time: an edit arriving while its translation runs queues exactly one re-translation, which starts only after the running one has written, so the last write is always the newest source. Verified on the same harness, where request 2 is now issued after response 1 and the file ends as the translation of `VERSION-B`. Coalescing also collapses an edit storm: six edits during one slow translation cost **7 API calls before and 2 after** (the in-flight one plus one re-translation of the final content), and the final file went from the translation of the *first* edit to the translation of the last. Translations of *different* files still overlap up to `--concurrency`, which is what that option is for.
-
-- **sync**: **the lockfile now records what reached the target file, not what the API returned.** A run marked a key `translated` on the strength of the translation call, so a key `reconstruct` could not place was recorded as done and every gate read that as complete — the mechanism behind the format defect below, and one that would have hidden the next such bug just as completely. Every key is now read back out of the content just written before the lockfile is updated. A key the file does not hold is recorded `failed` instead: the run warns naming the file, the locale and the key, the file line reads `✗ es: 0/1 keys` rather than `✓ es: 1/1 keys`, and the run exits 12. Measured on the two shapes that are still deliberately not written — a new `<string-array>` item and a Laravel key whose parent array is absent from the target — where before this every surface agreed the locale was complete: run 2 now exits **12** with `status: "failed"` in `.deepl-sync.lock`, `deepl sync status` reporting 50% rather than 100%, and `deepl sync --frozen` exiting **10**. Presence is the test, not byte equality, which is the per-parser escaping contract; a translation that is deliberately the empty string is exempt, because PO and XLIFF read an empty translation side as untranslated by design. Content a parser has just produced and cannot read back counts as holding none of the keys.
-
-- **sync**: **a string added to a source file after the first sync is no longer silently dropped from five of the eleven formats.** From the second run onwards `sync` uses the existing target file as the `reconstruct` template — that is how the translations it already holds survive — so a key added to the source since has no slot in it. Six parsers appended such an entry; `properties`, `ios_strings`, `laravel_php`, `android_xml` and `xliff` discarded it, and nothing downstream could tell, because the run recorded success from the translation call rather than from the write. Measured through the real CLI against a mock endpoint, run 2 of 2 on each of the five, with `json` as a control on the same run: exit 0, `OK es: 1/1 keys`, `Sync complete: 1 new, 1 current`, the target file **without** the key, `.deepl-sync.lock` recording `added.translations.es = {status: "translated"}`, `deepl sync status` reporting `es [####] 100% (0 missing, 0 outdated)`, `deepl sync --frozen` — the CI drift gate whose whole purpose is catching a missing translation — exiting 0 with `2 current`, and `deepl sync validate` passing with `Checked 1 translations ... All passed` because it only sees keys the file actually has. The characters were billed on every affected key, and the lockfile's `translated` claim is what stopped any later run correcting it, so the string was permanently absent from the shipped locale. Each of the five now writes the entry in the file's own layout: `.properties` and `.strings` append a line keeping the trailing newline and any dangling comment in place; `laravel_php` splices an array element at the offset of the array that owns it, matching the file's quote style, indentation, one-line-or-many layout and trailing-comma style, and handling `array(...)` as well as `[...]`; `android_xml` writes a `<string>` (or a whole `<plurals>` block) before `</resources>`; XLIFF writes a `<trans-unit>` in 1.2 and a `<unit><segment>` in 2.0, carrying the namespace prefix of the unit it is written beside. **XLIFF 2.0 was affected too** and the finding only measured 1.2. Two cases are deliberately still left out, because writing them would mean inventing structure the source file already defines: a new `<string-array>` item in `android_xml` (its `name.index` key is indistinguishable from a plain resource whose name ends in a dot-integer), and a `laravel_php` key whose parent array does not exist in the target. Verified after the fix with `xmllint --noout` on both XML outputs and `plutil -lint` on the `.strings` output.
-- **sync**: **a reviewed PO or XLIFF translation is no longer replaced with source text.** Gettext PO and XLIFF are bilingual — one file carries the source in `msgid` / `<source>` and the translation in `msgstr` / `<target>` — and their `extract().value` is the *source* even when the file being read is a target. Every sync path that needed "the translation this target file already holds" built its map as `key -> extract().value`, so all of them read the source side. Measured through the real CLI against a mock endpoint, on the run that rewrites a file because a **sibling** key is new: `msgstr "REVIEWED-PO"` became `msgstr "Hello"` and `<target>REVIEWED-XLF</target>` became `<target>Hello</target>`, at exit 0, with the lockfile still recording the key as `translated` so no later run corrects it. The identical scenario on a `json` bucket correctly kept its hand-edited value, which is what made this format-specific rather than general. The finding named three call sites; there were **six**, and the two it did not name are the worse ones — see the `sync push` measurement below and the `sync validate` entry under Security. `deepl sync pull` had the same blind spot in its merge base, writing the msgid for a key the TMS export does not carry, and `deepl sync audit` measured terminology consistency across source strings rather than translations. Parsers may now override the target-side read (`FormatParser.extractTranslations`), PO and XLIFF do, and all six call sites go through one helper instead of reaching for `value`. An empty `msgstr`, a missing `<target>` and an empty `<target></target>` now read as *untranslated* rather than as a translation, so such a key is translated instead of having the source pinned into it; this differs deliberately from the monolingual formats, where an empty value is a deliberate translation and is still preserved.
-
-- **sync**: **`deepl sync push` no longer uploads English as a locale's translation.** Push reads each target file and previously sent `entry.value`, which for a PO or XLIFF target is the msgid / `<source>`. Measured against a mock TMS: a `locales/es/app.po` holding `msgstr "Hola amigo"` produced the PUT body `{"locale":"es","value":"Hello {name}"}` and a TMS store of `{"es":{"Hello {name}":"Hello {name}"}}` — the reviewed Spanish never left the machine, and the TMS became the authority for a key whose recorded translation was the English source, so the next `deepl sync pull` would write English back into the target file. `TmsClient.pushEntry` now takes the translation as a required argument rather than reading it off `entry.value`, which is why no caller can reintroduce this by omission.
-
-- **formats**: **a `.properties` value ending in a backslash no longer deletes the entry after it.** `escapeValue` correctly writes a literal trailing backslash as `\\`, but the reader's continuation test was `line.endsWith('\\')` with no parity check, so it read that escape as "this line continues", consumed the following line and appended its raw text to the previous value. Measured: a source of `greeting=Hello` / `api_key=SECRET_VALUE` / `footer=Bye` with `greeting` translated to `Hallo\` was written as `greeting=Hallo\\`, and re-extracted as `[{greeting: "Hallo api_key=SECRET_VALUE"}, {footer: "Bye"}]` — the middle entry **gone**, at exit 0. The finding called this data loss; it is also a disclosure. `sync push` extracts the target file and sends each value to the TMS, so the swallowed line left the machine under an unrelated key's name: measured, the push body for `greeting` was `Hallo api_key=SECRET_VALUE`, and `api_key` itself was never pushed at all — 2 keys sent where the file had 3. The same misread hits a *hand-written* source on its very first read, so a legitimate Windows path such as `path=C:\\` was enough on its own. Both continuation tests (extract and reconstruct) now count the trailing backslash run and continue only on an odd count, which is the rule `escapeValue` was already writing for. Round-trip is now verified for the values `x\`, `\`, `a\b\`, `C:\` and `a\\b`; the first four all previously ate the next entry.
-
-- **translate**: **`deepl translate <file.json|.yaml>` now has a size ceiling, so a huge locale file cannot exhaust memory mid-run.** The structured-file route read and fully parsed whatever it was given, while both sibling routes of the same command were already bounded — text at 100 KiB, documents at 30 MB (`MAX_DOCUMENT_FILE_SIZE`) — and `deepl sync` skips anything over `sync.limits.max_file_bytes`. Measured peak RSS against a dead endpoint, so only parse and extract are counted: 4.7 MB → 129 MB, 19.2 MB → 251 MB, 80.9 MB → 684 MB, 163.8 MB → 1178 MB, linear and unbounded. The finding did not name the multiplier: the multi-target path parses a **fresh copy per target language**, up to `MULTI_TARGET_CONCURRENCY` (5) at once, so the same 19.2 MB file peaked at 252 MB for `--to de` and **483 MB** for `--to de,fr,es,it,nl`. The ceiling is 10 MiB, matching `HARD_MAX_SYNC_LIMITS.max_file_bytes` — the value `sync` refuses to be configured above — so nothing sync can be made to accept is refused here, and the worst case stays a few hundred MB rather than gigabytes. The check is a `fs.stat` before the read, at the one function both entry points funnel through, so an oversize file is never resident: the 163.8 MB fixture now exits 6 in 0.17 s at 86 MB RSS instead of 7.8 s at 1178 MB. The message names the file, its size and the limit, and points at `deepl sync` for anything larger; a directory run fails only that file and keeps its per-file reason in the summary. A document at 25 MB is still accepted, deliberately — it is streamed to the API rather than parsed.
-
-- **sync**: **`sync pull` no longer writes source-language text into a target locale file, and no longer replaces a local translation without saying so.** The merge that applies a pull response read `pulledKeys[key] ?? existingTarget.get(key) ?? entry.value`, so a key the TMS export omits **and** the target file lacks was filled in with the source string. Measured against a mock TMS whose `de` export carried only `greeting`: a source file holding `greeting`/`farewell`/`brand_new` and a `locales/de.json` holding the first two produced a German file containing `"brand_new": "Only in source"` — English, indistinguishable from a translation to anything reading the file — at **exit 0**, with the one-line summary `Pulled 1 translations from TMS`. The final `?? entry.value` is gone; a key with a value on neither side is now omitted from the entry list, which is what `reconstruct` needs to leave it out of the file, and matches what the locale translator already does for a key it could not translate (it pushes nothing rather than the source). An empty string is a translation and is still preserved. The same change fixes the case the finding did not name: when the target file does not exist yet, the source file is used as the reconstruction template, so **every** untranslated key was written into the new locale as English; only the keys the export actually carries are written now. Separately, the pulled value has always won over the local one and always will — neither side of the documented export contract carries a timestamp, so "which is newer" is not a question that can be answered, and pull exists to bring the reviewed copy in — but the overwrite was completely silent. Pull now counts the existing local translations it replaced and names the count (`Replaced 1 existing local translation with the TMS version. Use --dry-run to preview a pull before it overwrites local edits.`), with `--verbose` naming each key and file. See Added for the preview mode.
-
-- **translate**: **the CLI's own internal placeholder tokens can no longer be written into your text.** `restorePlaceholders` substituted every `__VAR_n__` it could find and silently left the rest alone, with nothing checking that the tokens the CLI had injected came back at all. Re-casing and re-spacing an unfamiliar token is ordinary MT behaviour, so `__VAR_0__` returning as `__ Var_0 __` produced, measured against a mock endpoint that does exactly that: `deepl translate "Welcome back, {username}!" --to de` printing `XX Welcome back, __ Var_0 __!` at **exit 0** with no warning; `deepl translate a.txt --output a.de.txt` writing the same to disk at exit 0; and a directory run writing it into every file at `✓ Successful: 2`. Only `sync` caught it, because only `sync` has a placeholder validator. All three paths now check the post-condition: `translate` fails with exit 5 naming the variables it lost (`The translation lost the placeholder {username}. … Nothing was written.`) and a suggestion pointing at the endpoint, and a directory run fails only the affected files — a file with no placeholders in it is unaffected and still translated. The check runs **before** the cache write, so a response that lost a placeholder never becomes a cache entry that reproduces the same output offline; a poisoned entry from an earlier version is refused on read for the same reason. `sync` is deliberately unchanged: its validator already withholds the key, counts it failed and retries it next run, and `validation.check_placeholders: false` stays the documented way to write such a translation anyway.
-
-- **sync**: **every ICU block in a message is protected, not just the first.** `parseIcu` found one block with a single non-global match, then pushed the entire remaining suffix as one ordinary prose segment — so the second and later blocks were submitted to the MT engine as translatable text, which is the exact exposure the module exists to prevent. Measured against a mock endpoint with `You have {n, plural, one {# item} other {# items}} and {m, plural, one {# gift} other {# gifts}} waiting.`, the outbound request was `["You have ", "__VAR_HASH_0__ item", "__VAR_HASH_0__ items", " and {m, plural, one {# gift} other {# gifts}} waiting."]` — the first block's selectors and `#` correctly protected, the second block's full syntax sent as prose. A real engine translating `other` to `andere` yields a message with no `other` branch, which throws at render time. Detection now walks the whole string, emitting each run of prose between blocks as its own segment and each block through the same brace-counting parser, with leaf references reindexed into one combined segment list; the same request is now `["You have ", "__VAR_HASH_0__ item", "__VAR_HASH_0__ items", " and ", "__VAR_HASH_0__ gift", "__VAR_HASH_0__ gifts", " waiting."]`. Adjacent blocks with no prose between them, three or more blocks, and nested ICU are all covered. The documented safe fallback is unchanged and now applies to the whole message: a string holding **any** block that will not parse passes through untouched rather than half-protected.
-
-- **sync**: **the internal ICU marker is no longer submitted and billed as a text.** A string routed to segment-by-segment ICU translation had its slot in the main batch filled with `__ICU_PLACEHOLDER_<n>__`, which went to the API as an ordinary text, was billed, and was cached under its own key — measured as a whole extra request per batch containing an ICU string. The slot now holds nothing to translate, so `translateBatch` skips it (see the empty-value entry above); `reassembleIcu` overwrites every mapped index, so the blank cannot reach a target file.
-
-- **translate/sync**: **an empty string value in an i18n file is no longer mistaken for a failed translation.** `TranslationService.translateBatch` skips a text that is empty — nothing to send, nothing to bill — but left that slot `null`, the same value it uses for a text whose request failed, and declared its return type `TranslationResult[]` so nothing was forced to tell the two apart. Three separate consequences, all measured against a mock endpoint. **`deepl translate` crashed:** `{"title": "Hello world", "placeholder": "", "footer": "Goodbye"}` printed a false `⚠️  Warning: 1 of 3 translations failed` (nothing had failed) then `Error: Cannot read properties of null (reading 'text')`, **exit 1**, and no output file at all — one empty value cost the whole file. **`deepl sync` deleted the key:** the same content wrote a `de.json` containing only `title` and `footer`, recorded `placeholder` as `status: "failed"`, and every later run reported `✗ de: 0/1 keys` and **exit 12 forever**, since the retry could never succeed. It now reports `✓ de: 3/3 keys`, exit 0, writes `"placeholder": ""`, and settles in the lockfile as translated. **An ICU message with an empty plural branch was lost the same way:** `{count, plural, one {} other {# items}}` had its empty branch read as a failed segment, so the entire message was withheld and the key dropped from the target — found by looking for the same defect on a path the report did not name. Empty input now returns an empty translation with `billedCharacters: 0`, `translateBatch` is declared `(TranslationResult | null)[]` so the compiler forces the remaining failure case to be handled at each of the five call sites, and the `N of M translations failed` warning counts only real failures. `BatchTranslationService` records a missing per-index result as that one file's failure instead of dereferencing it.
-
-- **translate**: **a rate limit part-way through a large structured file now exits 3 instead of 1.** `deepl translate <file>` grouped strings for the API by byte size only (128 KB), never by count, so a file of more than 50 strings became several API requests inside one `translateBatch` call; when a later request was rejected, the surviving batches came back with holes and the caller dereferenced one. Measured on a 60-key JSON file with a 429 on the second request: `Error: Cannot read properties of null (reading 'text')` and **exit 1** — `GeneralError` — so a CI wrapper branching on `$? -eq 3` did not retry. Batches are now capped at 50 strings as well as by size, which is what `BatchTranslationService` already did, so each call is a single request and a rejection propagates with its own classified code: the same run reports `Error: Rate limit exceeded: Too many requests`, its retry suggestion, and **exit 3**, with no partial output file written. The unreachable "expected N results but got M" length guards are kept and joined by a per-index check.
-
-- **translate**: `ℹ️  Cache is disabled` and `ℹ️  Cache bypassed for this request (--no-cache)` are announced once per run rather than once per API request. The cache state is a property of the invocation, so a file needing ten requests repeated the same line ten times.
-
-- **sync**: **a translation the engine corrupted is withheld from the target file instead of being written and recorded as done.** The placeholder/ICU validator is the only defence against corrupt machine output, and it ran too late to be one: the write at `sync-locale-translator.ts` happened first, then the lockfile, then the `.deepl.bak` backups were unlinked, and only then was `validation.fail_on_error` consulted. Its results were counted, never acted on. Measured against a mock endpoint that drops the `__VAR_n__` tokens the CLI substitutes for placeholders: `"greeting": "Hello {name}, welcome back"` reported `✓ de: 2/2 keys`, `Sync complete: 2 new`, one line of `1 validation error(s)`, and **exit 0** — with `de.json` holding `"[DE] Hello , welcome back"`, the lockfile recording the key `translated`, and the next run reporting `2 current` and never retrying, so the placeholder was gone permanently. `fail_on_error: true` only changed the exit code to 6 after the same damage was done, and where the target file already existed the previous good translation had been overwritten and its backup deleted on the way out. **The new-locale backfill path was not validated at all**: adding `fr` to `target_locales` translated the already-`current` keys through a second batch that never reached `validateBatch`, so `fr.json` was written corrupt at `✓ fr: 2/2 keys`, exit 0, and **zero validation errors reported** — the bulk-translation case was the silent one. An `error`-severity result (a lost placeholder, an ICU bracket or selector rewritten) is now decided before the write, on both paths: the key is withheld, counted as failed, and recorded `status: "failed"`, so the same run reads `✗ de: 1/2 keys`, `Sync complete: 2 new (1 translations failed)`, exit 12, and the next run retries the key. Warnings still pass through and are still written. Two things the fix cannot do naively: simply leaving the entry out **deletes** the key, because the entry list is the complete desired key set a parser reconstructs from — measured, `de.json` lost `greeting` entirely and a previous `"Hallo {name}, willkommen zurueck"` with it — so a withheld key now carries whatever the target file already held, exactly as an untouched `current` key does; and the plural write-backs, which copy translated text into the metadata the PO and Android parsers reconstruct from, are skipped for withheld entries, or the forms would have gone in corrupt behind a preserved scalar. `validation.fail_on_error` keeps its `false` default rather than being flipped: a withheld key already fails the run, so the protection no longer depends on the setting, and the flag retains its documented meaning of promoting that to a hard `ValidationError`. The backups are still cleaned up on the way out — with the corrupt value never written, there is nothing to roll back to, and keeping them would make the next run report an unfinished earlier run that did not happen.
-
-- **formats**: **an `.arb` key whose name collides with an `Object.prototype` member is no longer dropped from the file it was billed for.** `arb.ts` gated new-key insertion on `key in data`, and `in` reports inherited members — so `toString`, `valueOf`, `constructor`, `hasOwnProperty`, `isPrototypeOf` and `__proto__` all read as already present and their translations were discarded. The sibling `json.ts` documents this exact defect as fixed, with the reason in a comment above the check; same repo, same class, one fixed and one not. Measured at the parser: asked to insert six keys into a target that lacked them, `arb` dropped five and `json` dropped none. **The trigger is a source file gaining a key**, not a first sync — sync seeds a new target from the source, so the keys land on the in-place path; it is the second run, inserting into a target that already exists, that loses them. Reproduced end to end against a mock endpoint: adding `hasOwnProperty` and `constructor` to `app_en.arb` reported `✓ de: 3/3 keys` and `Sync complete: 3 new`, wrote only the third key to `app_de.arb`, and exited 0. The lockfile records all three as translated, so the next run reports `6 current` and **never retries them** — the strings are lost silently and permanently rather than re-billed each run. Insertion now tests `Object.hasOwn` and writes through the shared `setOwnMember`, so a key named `__proto__` becomes an own property instead of reaching the prototype setter. `setOwnMember`/`getOwnMember` moved from `sync/sync-lock.ts` to `utils/own-members.ts` for this: `formats/` cannot import from `sync/` without inverting the dependency, and a third copy of the same `defineProperty` helper was not worth writing. No behaviour change for the five sync modules that use them.
-
-
-- **logger**: **a short credential value no longer corrupts every diagnostic message.** The redactor's last step substring-replaced the literal credential with `[REDACTED]`, with no length floor and no token boundary, so any message containing the value inside an ordinary word was mangled. With `DEEPL_API_KEY=k` — a mistyped or throwaway value — a single real CLI run against a closed port printed `Warning: sending your DeepL API [REDACTED]ey to …`, `Error: Networ[REDACTED] error: connect ECONNREFUSED`, `Suggestion: Chec[REDACTED] your internet connection and proxy settings`, and a config path rendered as `/Users/[REDACTED]wey/…`: four lines of nonsense at the moment the user most needs to read them, and the mangling was itself how this was noticed, in the harness output of two unrelated findings. A literal value is now only replaced when it is **at least 8 characters**; below that, the auth-header and `token=`/`api_key=` query-parameter patterns still apply, so nothing that is shaped like a credential in transit goes unredacted. A real DeepL key is UUID-shaped with a `:fx` or hyphenated suffix and TMS credentials are longer still, so the floor excludes nothing genuine — the shortest key in this repo's own test suites is 12 characters. The alternative of matching on a token boundary was rejected: it would silently **miss** a real key printed immediately before a word character, which is the more expensive of the two errors, where a floor can only fail to redact a value too short to be a credential.
-
-- **sync**: **the `Sync complete:` summary names how many translations failed**, instead of reading as though every diffed key had landed. The key counts in that line come from the diff, not from what was successfully translated, so a run that translated 50 of 200 keys and rate-limited on the rest printed `✗ de: 50/200 keys` and then `Sync complete: 200 new` directly beneath it — two lines flatly contradicting each other, with the accurate one being the easier to miss in a CI log. It now reads `Sync complete: 200 new (150 translations failed)`. The count totals every locale, and nothing is appended when nothing failed. Exit code 12 on partial failure is unchanged, as are the diff counts themselves, which were accurate about the diff all along.
-
-- **sync**: **the lockfile no longer lets `git merge` invent a translation that existed on neither branch, and `sync resolve` now actually applies its documented `translated_at` tie-break.** One root cause behind both: entries were serialized one field per line, making git's unit of merge a *field* rather than a *translation*. Measured with real `git merge` on real serializer output, against a stashed-old-code control. **The silent case, which never reached `sync resolve` at all:** a branch that changed only `review_status` and a branch that changed only `translated_at` are non-adjacent lines with `status` unchanged between them, so git merged both hunks cleanly and produced `review_status: human_reviewed` from one side carrying `translated_at` from the other — a combination on neither branch, marking machine output as human-approved with a timestamp that makes the staleness invisible to any later timestamp comparison, at exit 0 with no conflict reported. **The `sync resolve` case:** where git *did* conflict, the region was the entry's field list, so it parsed to three scalars and the resolver's entry-level branch was unreachable; every field took the terminal `kept ours: scalar conflict, defaulting to ours` path. Measured discarding a newer `human_reviewed` translation in favour of older machine output, reported as resolved at exit 0 — the exact opposite of the documented rule, and side-dependent, so it silently did the right thing whenever the newer edit happened to be on the local branch. **Each translation is now written on a single line**, which makes the smallest region git can produce a whole entry: the field-level overlap conflicts instead of merging, and the conflict reaches the timestamp comparison, which picks one whole coherent side. Two changes were needed to make that hold, neither of them obvious from the format change alone. A region inside an object carries a trailing comma joining it to the next member, and `JSON.parse('{' + region + '}')` fails on it — so *every* entry but the last locale in its map would have fallen straight back to the length heuristic and kept discarding the newer side; the terminator is now taken off before parsing and put back after. And because resolving rebuilds each region with its own indentation, the resolved file is now written back in canonical form, so committing it cannot leave entries expanded across lines for the next merge to recombine. Where the two sides *disagree* on the terminator — one deleted what the other modified — no terminator is correct for both and the region still falls to the length heuristic rather than risk invalid JSON. **Upgrading reformats every existing lockfile on the next write, producing one large diff; it is formatting only and no entry's content changes.** Keys are sorted within the line, so a changed translation is now a one-line diff rather than three or four.
-
-- **sync**: **`sync export` produces well-formed XLIFF for keys that contain control characters, and no longer changes a key on the way out.** `escapeXml` escaped `&`, `<`, `>` and `"` only, so a key holding a C0 control was written straight into the `id=` and `resname=` attributes — and C0 other than tab, newline and carriage return has no representation at all in XML 1.0, not even as a character reference, so the file was not well-formed and a translator's tool would reject it whole. Those characters are now replaced with `?`, which costs one odd character in one id rather than an unreadable handoff file. Separately, and independent of any hostile input: a tab, newline or carriage return inside a key was emitted literally, and every conforming XML parser **normalizes those to a space inside an attribute value** — so a multi-line key silently came back different from the key that was exported. They are now emitted as `&#9;`, `&#10;` and `&#13;`, which round-trip exactly. C1 (U+0080–U+009F) is deliberately left alone: those are valid XML 1.0 characters that round-trip unchanged, and an export is a data file, so it is mutated no further than validity requires.
-
-- **sync**: **two syncs no longer run concurrently in the same directory, which is the entire purpose of the process lock.** Measured with six processes racing over a planted stale pidfile, 100 rounds: **93 rounds had overlapping lock holders before this change — up to five at once — and 0 do after.** Two independent defects had to be fixed to get there. First, the stale-pidfile reclaim was a read/unlink/create sequence with no atomicity, so a process whose staleness verdict had already been overtaken deleted the *live* pidfile the winner had just written, after which both held what each believed was an exclusive lock; and the create that followed the unlink was the one call not wrapped in the EEXIST handling, so a lost race surfaced as an unhandled `Error: EEXIST: file already exists, open '.deepl-sync.lock.pidfile'` instead of the intended "another sync is running". A stale file is now removed only after taking possession of it with `rename(2)` — atomic, so exactly one of several racers can move a given entry aside — and confirming the captured inode is the one proven stale; a process that captures a different file puts it back rather than deleting someone's lock. Acquisition always goes through the same guarded create, so a lost race reports the running sync, and the retry loop is bounded (5 attempts) with its own error rather than spinning. Second, and the defect that actually accounted for the remaining overlap once the reclaim was atomic: the pidfile was created empty through an `O_EXCL` descriptor and filled afterwards, leaving a window in which a **live** lock read as malformed — and malformed counts as stale, so a concurrent sync deleted it and took over. No identity check downstream can catch that, because the file it inspected really is the file it removed. The payload is now written to a private staging path and `link(2)`ed into place, which publishes the name and the content in one step and doubles as the atomic acquisition. CI relevance: a runner retrying a timed-out job is exactly the double-start trigger.
-
-- **sync**: **a failed backfill for a newly added locale no longer writes the source text in as the translation.** When a current key's translation failed while bootstrapping a new target locale, the backfill path pushed `{ translation: cd.value }` — the English source — and only incremented `failed`. Because any value present in the target file counts as an existing translation, those strings were then skipped on every later run: `sync status` reported `fr 17% (50 missing, 0 outdated)` while `deepl sync` said `60 current` and refused to retranslate them, and `sync validate` rated it a warning at exit 0. The tool reported the strings as missing *and* declined to fix them, permanently, with no error anywhere. The same file's main translation path already handled this correctly, and the guard comment 60 lines up spelled out the reason: "Writing the source value here would record untranslated text as translated, which no later run would correct." The backfill path now pushes nothing, so the key stays out of the target file and the next run picks it up. Nothing is recorded in the lockfile for it either — deliberately, since a `status: 'failed'` entry would make `sync status` count the key as *outdated* when it is genuinely *missing*, and would trip the "lockfile records a translation but the target file has none" path on every retry.
-
-- **sync**: **a run that lost most of its strings no longer exits 0.** A locale counted as failed only when it translated *nothing* (`fr.translated === 0 && fr.failed > 0`), so 10 keys succeeding and 50 failing was not a failed locale: `{"ok": true, "translated": 10, "failed": 50}` at exit 0, with the 50 failed keys absent from `locales/de.json` entirely. The comment directly above the check already cited the documented contract for exit 12 and the code did not implement it. Any failure count above zero now fails the run, so `deepl sync` exits 12 and `--auto-commit` — gated on `result.success` — no longer commits a truncated locale file. A locale that translated nothing *and* failed nothing is still a success: that is a locale which is already up to date. **CI impact**: a pipeline that previously went green on a partially failed sync now sees exit 12, which is the point; branch on `$? -eq 12` and re-run with `--locale` per the retry model in `docs/API.md`. The exit-code table there described 12 as "at least one failed locale" and now says "at least one failed key", matching the prose two sections down that already defined 12 as a mixed result.
-
-- **sync**: **the progress stream no longer reports keys as translated that failed.** All five `key-translated` emission sites fired unconditionally after dispatching a batch, before any result was inspected, so a run in which every key failed still printed `translated: 60, totalKeys: 60` on the way to writing nothing. Each site now emits only when that key's `translateBatch` slot came back non-null, and the running count is a single counter over the successes rather than a loop index, so the number the stream reports agrees with the number the summary reports.
-
-- **sync**: **a backup left behind by a crashed run is no longer overwritten by the run you start to recover from it.** After a `kill -9` mid-sync the lockfile was never written and `locales/de.json.deepl.bak` held the only surviving copy of the user's file — and the natural recovery action, re-running `deepl sync`, destroyed it: the "already backed up" guard is a per-process `Set`, so the run copied the machine-translated target over the existing backup and then unlinked it on success. Reproduced end to end: after the recovery run the human content was gone at exit 0, and the already-completed translations were re-billed. The copy now uses `COPYFILE_EXCL`, and on `EEXIST` the existing backup is left alone with a warning naming it — and deliberately not tracked as this run's, so the success path does not unlink it either. The stale-backup sweep still retires it on age. A run with no pre-existing backup behaves exactly as before: back up, write, unlink on success.
-
-- **sync**: **Ctrl-C during a sync now restores the files it had already overwritten, instead of deleting their backups.** The signal handler ran the same cleanup as a successful run — unlink every `.deepl.bak` taken this run — which is right for a run that finished and catastrophic for one that did not: the backup was the only remaining copy of content the run had already replaced. Reproduced with a delaying endpoint and two locales: at the moment of the interrupt `locales/de.json` held machine output and `locales/de.json.deepl.bak` held the human translations; after `kill -INT` the backup was gone, the machine output stayed, and no lockfile had been written (it is written once at the end), so the human translations were unrecoverable and unrecorded at exit 130. Each backup is now copied back over its target before being removed — that order, so an interrupt during the restore leaves the backup rather than nothing — and the run reports what it undid: `Interrupted — restored 1 file(s) from backup: locales/de.json. No lockfile was written, so nothing was recorded; re-run to translate again.` Verified end to end: `locales/de.json` is byte-identical to its pre-run content. The restore is synchronous because `installSignalExit` defers the exit by one `setImmediate`, so only synchronous handler work is guaranteed to finish. A successful run is unaffected — it still unlinks, from its own path. `sync --watch` is unchanged: it owns its own backup tracker and cleanup.
-
-- **sync**: **a Laravel PHP lang file that overflows `php-parser` is skipped with a warning instead of ending the run.** `php-parser` has no recursion guard, and it throws from inside `parseCode` — before `php-arrays`' own `max_depth` guard, which only walks the AST once a parse has succeeded — so a 100KB file of deeply nested parentheses, well under `max_file_bytes`, arrived at the walker as a bare `RangeError` and was rethrown: `Error: Maximum call stack size exceeded`, exit 1. Verified before and after by removing the new handler and rebuilding: exit 1 with that message, versus exit 0 and `Skipping lang/en.php: nesting depth exhausted the stack while parsing (…)` with it. Covered by the same per-file boundary added for the JSON/YAML depth work below, so any parser that lets a `RangeError` escape now costs one file rather than the run.
-
-- **sync, translate**: **a deeply nested JSON or YAML file no longer ends the whole run with `Error: Maximum call stack size exceeded`.** The JSON and YAML walkers recurse once per nesting level with no depth guard, so a 16KB file of 8,000 nested arrays — far below the 4 MiB `sync.limits.max_file_bytes` default, so the pre-read size check never sees it — killed `deepl sync`, `deepl sync validate` and `deepl translate <file>` alike. In a sync it was worse than a crash: a healthy file earlier in the bucket had already been translated, billed and written, and because the run died before the lockfile was written that work was unrecorded, so the next run paid for it again. `sync.limits.max_depth` (default 32, ceiling 64) existed for exactly this and was wired only to the Laravel PHP parser, which `sync-bucket-walker.ts` documented in a comment rather than fixing. Three changes: `JsonFormatParser` takes a `maxDepth` and rejects past it with a catchable error naming the key path; the walker now applies `sync.limits.max_depth` to **any** parser that accepts one — via a new optional `withMaxDepth` on `FormatParser`, so a future recursive parser opts in rather than needing a new special case — and always, rather than only when the user overrode the default; and one file exceeding the cap is skipped with a warning while the run finishes and records what it did. Verified end to end: a bucket holding one healthy and one 8,000-deep file now completes at exit 0, writes the healthy target, writes the lockfile, and prints `Skipping deep/en.json: JSON: max nesting depth 32 exceeded at 'a.0.0.0…'`. **YAML is bounded differently, because bounding our own recursion could not have helped it:** the `yaml` library builds its tree recursively and reports the blown stack as a parse diagnostic, so it fails inside the library before any walker of ours runs — measured in both flow and block style. That diagnostic is now recognised as a depth rejection and skipped like any other, and a `RangeError` escaping any parser is caught at the same boundary as a backstop. The direct `deepl translate <file>` path has no `.deepl-sync.yaml` and so no configured limit; it gets a fixed ceiling of 100 levels, which clears any realistic i18n file by a wide margin and sits far below the ~2,000 levels at which the stack actually gives out, so its only effect is to turn an opaque stack overflow into a named error.
-
-- **sync**: **two keys whose placeholders protect to the same text no longer receive each other's variables.** `preserveVariables` replaces every variable with a positional token, so `Hello {name}` and `Hello {user}` both become `Hello __VAR_0__` — one text on the wire, and `TranslationService.translateBatch` deduplicates them, which is the point. It then assigned the *same* result object to every index the duplicate covered, and the restore loop in `sync-locale-translator.ts` edited `result.text` **in place**: the first key's restore consumed the token, so the second key found none left and was written with the first key's variable. `{alpha: 'Hello {name}', beta: 'Hello {user}'}` produced `beta: 'XX Hello {name}'`, and the far more common `%s`/`%d` pair — `{delta: 'Deleted %s files', epsilon: 'Deleted %d files'}` — produced `epsilon: 'XX Deleted %s files'`, a format specifier that no longer matches its argument. This needed no hostile input, only two strings that differ solely in their variable. The run reported `5/5 keys` at exit 0, the lockfile recorded the affected key as `translated`, and the next sync reported it `current`, so the corruption was permanent. `translateBatch` now gives each index its own copy of the result — the array is typed as one result per index, and no caller can alias two logical results any more — and both restore loops replace their entry instead of editing it. Verified end to end: every key gets its own placeholder back, and the two validation errors and two warnings the run previously emitted (advisory, exit 0, details not printed) are gone, since they were reporting exactly this. `deepl translate` was never affected; its single-text path already returned a new string.
-
-- **translate**: **`--no-cache` was accepted and silently ignored for every structured i18n format** — JSON, YAML, TOML, PO, XLIFF, Android XML, iOS `.strings`, `.xcstrings`, ARB, `.properties`, and Laravel PHP. In one function thirty lines apart, the plain-text branch passed `skipCache: !options.cache` and the structured branch passed only `{ preserveCode }`, because `TranslationService.translateBatch()` had no service-options parameter at all and consulted persisted `cache.enabled` alone. A wrong translation was therefore permanent: re-running the identical command with `--no-cache` sent **zero** requests and reproduced the previous output byte for byte, defeating the one remedy a user would reach for. `translateBatch` now takes the same `serviceOptions` shape as `translate()` and honours `skipCache` on both the cache read and the cache write, and the flag is threaded through `translateFile`, `translateFileToMultiple`, and `translateStringsInBatches` — the multi-target file path dropped it too, for plain text as well as structured files, so both single- and multi-target now behave alike rather than fixing one sibling and leaving the other bare. Verified end to end against a local stub: two identical runs without the flag make one request (second served from cache); the same pair with `--no-cache` makes two. The bypass message (`ℹ️ Cache bypassed for this request (--no-cache)`) is emitted on the batch path as well now. `sync` and `batch` do not expose `--no-cache` and are unchanged.
-
-- **translate**: **`--output <dir>` failed with `EISDIR` for a single target language, though it worked for two or more.** `--output` is documented as a file path *or* a directory, and the multi-target branch honoured that — `--to ko,ja --output dir/` wrote `dir/t.ko.md` and `dir/t.ja.md` — while the single-target branch used the destination verbatim and let the atomic rename land on the directory: `Error: EISDIR: illegal operation on a directory, rename 'dir/.tmp.59970.vmrlp5' -> 'dir/'`, exit 1. Two branches of the same command disagreed, and the one that contradicted the documentation was the common one. It affected text files, structured files (JSON/YAML) and documents alike, because each branch decided the destination at its own call site. The destination is now resolved once, ahead of every branch, and a directory names the file the way multi-target translation already does: `deepl translate t.md --to ko --output dir/` writes `dir/t.ko.md`, so two locales into one directory cannot collide. `dir` and `dir/` behave identically — the check is `statSync().isDirectory()`, not a trailing-slash test — and a trailing slash additionally creates the directory when it does not exist, matching multi-target. A converted document is named by `--output-format` (`report.pdf --to de --output-format docx --output dir/` writes `dir/report.de.docx`), since that flag decides what the bytes are. `--output -` and a non-existent path such as `--output out/new.md` are unaffected. Pre-existing, not a regression. `examples/03-batch-processing.sh` hit this in five places and hid four of them behind `2>/dev/null`, `|| true` and a `(cached or completed)` message that reported a cache hit for a call that had errored — so `npm run examples` reported 37/37 passed while this was broken; those guards are gone, and section 8's cache comparison now times calls that actually succeed.
-
-- **sync**: **`deepl sync resolve` kept the local side of every merge conflict, silently discarding a teammate's newer translations.** The documented rule — take the newer translation by `translated_at` — never fired on a real `.deepl-sync.lock`. The leaf test treated any object carrying `source_hash` as a translation to compare, and every lockfile entry carries one, so the resolver read `translated_at` on the entry, where it does not exist; the real timestamp lives on each locale inside that entry's `translations` map, and the recursion that would have reached it was never taken. Each conflict was therefore reported as `kept ours: neither side had translated_at` and resolved to ours, at exit code 0 and without the `length-heuristic` tag that exists to mark exactly this kind of unreliable decision — so the per-entry report gave no sign that anything had been dropped. An entry holding a `translations` map is now treated as a container and merged one locale at a time, which is where the timestamps are, and the report names the locale it decided (`greeting.translations.de`) rather than the entry. Fields the two sides agree on are no longer listed as conflicts. The existing tests passed throughout because their fixtures put `translated_at` directly on the entry, a shape `SyncLockManager` does not write; the suite now also drives the shape it does.
-
-- **docs**: Five documentation inaccuracies found in the pre-2.0 audit. `docs/API.md` and `README.md` still said the **last** `--glossary` wins a conflicting term, contradicting the same files, the flag's own help text, and the verified behaviour — which mapping wins is the API's choice and does not follow flag order. `docs/API.md`'s command-group table omitted `correct` while claiming to match `deepl --help`, and the README's table of contents omitted its Spelling and Grammar Correction section. `docs/API.md`'s environment-variable reference omitted `NO_PROXY`, which the HTTP client honours and the README already documented. `docs/TROUBLESHOOTING.md` attributed "Translation cache backend failed to load" to running Node.js < 24, which the startup version check now rejects earlier with its own message, so the stated cause was unreachable; that entry now describes the reachable case (a v24+ runtime with no usable `node:sqlite`) and the version error is documented under exit code 6, where it previously appeared nowhere.
-
-- **watch**: **`deepl watch` debounced at 300 ms while `--help` and every doc said 500, and `watch.debounceMs` did nothing.** The command forwarded a debounce only when `--debounce` was passed, so an omitted flag fell through to `WatchService`'s own 300 ms fallback — a third copy of a value the config schema and the flag's help text both put at 500. The configured key was accepted by `deepl config set` and listed in the documented schema, but nothing ever read it for `watch`. Resolution is now flag, then `watch.debounceMs`, then the documented 500 ms default, and that default is a single exported constant shared with the config schema so the two cannot drift again. `deepl sync --watch` was already correct at 500 and is unchanged.
-
-- **package**: **`import '@deepl/cli'` threw instead of loading.** The package is ESM, so Node requires a full specifier for every relative import, but the entry point re-exported `'./types'` — a directory — which fails with `ERR_UNSUPPORTED_DIR_IMPORT`. The whole programmatic surface was therefore unreachable, and the published typings resolved to nothing for a `nodenext` consumer, so `import type { Language } from '@deepl/cli'` was an error regardless of what the union contained. `deepl --help` never exercised this, because the `bin` entry has its own module graph. Both remaining directory specifiers now carry `/index.js`, and the manifest suite imports the built entry in a real Node ESM process and rejects any extensionless relative specifier in the emitted entry chain.
-
-- **scripts**: **The language generator wrote unescaped API response fields into TypeScript.** `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could close the literal and append arbitrary code to `src/data/language-entries.ts`, which the next `npm run build` compiles and the test suite imports. The existing guards checked the shape of the response, never the content of a field. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping; validation runs before grouping, which would otherwise drop an entry with an unrecognized category before it was checked. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
-
-- **translate**: **A directory run stopped by one request-level rejection now reports that rejection's exit code** instead of the generic `1` for "nothing succeeded". A refused `target_lang` is invalid input and exits 6, an exhausted quota exits 4, a refused key exits 2 — all cases where every file draws the same answer and the run aborts. A run where files failed for their own reasons still exits 1 with no successes, or 12 with some. Text and file modes already exited 6 for this.
-
-- **glossary**: **The language-pair preflight no longer treats two regional variants of one language as interchangeable.** Both sides were compared on their base language, so a `pt-br` dictionary satisfied a request for `pt-pt`. The relaxation is needed in one direction only — dictionaries name base languages while `--to` accepts variants — so a dictionary language now matches the requested one exactly or matches the base it reduces to. `de→en` still covers `--to en-us`, and a dictionary naming `pt-br` still matches `--to pt-br`. Not reachable through the current API, whose glossary language set is entirely base codes.
-
-- **languages**: **A language `GET /v3/languages` describes with no feature matrix is no longer filed as extended.** The tier was derived from the absence of glossary support, and an absent matrix is silence rather than a denial — the same unknown-versus-none conflation already fixed for the `--features` table. Since the extended tier is what refuses formality and glossary before a request is sent, such a language is now tiered by source usability and the API keeps the judgement. An **empty** matrix is still evidence and still means extended. The bundled snapshot is unchanged, since every language the API currently lists carries a matrix.
-
-- **languages**: An absent `usable_as_source` / `usable_as_target` flag is read as "usable" in the language and glossary-pair listings, matching how the language registry has always read it. The two disagreed, so a language whose flag was absent was dropped from `deepl languages` while the snapshot generator recorded it as core.
-
-- **types**: `LanguageEntry`'s fields are `readonly`. The accessors hand out the registry's own objects, so `getTargetLanguages()[0].code = 'x'` changed the registry for the rest of the process — something the generated `as const` snapshot forbids but the widened element type permitted.
-
-- **scripts**: `npm run generate:languages` reports a thrown fetch or an unparseable error body as its own `error:` line and exit 1, rather than as an unhandled rejection with a stack trace.
-
-- **languages**, **voice**: **Strings the API supplies are sanitized before they reach the terminal.** `deepl languages` printed the name, feature keys and feature statuses from `GET /v3/languages` verbatim, and `voice` did the same with transcript text and language labels, so a hostile or intercepted endpoint could move the cursor, clear the screen, or hide text behind a bidi override. Both now go through the same `sanitizeForTerminal` the glossary and style-rule listings already used, replacing control and zero-width characters with `?`. It matters most for `voice`, whose live display clears a fixed number of lines: a newline inside a transcript threw off the whole rendering, not just its own line. `voice --format json` keeps the text byte-for-byte, since JSON escaping already makes it inert and that is the path machines read.
-
-- **watch**: **A direct `WatchCommand.watch()` call rejected `--glossary` without `--from` even when `defaults.sourceLang` was set.** The config-aware resolution every other command uses lived only in watch's CLI registration layer, while the handler kept the older flag-only guard — so the CLI accepted a command a library caller was refused. The handler now settles the source language the same way, from `defaults.sourceLang` when the flag is absent, and `WatchCommand` takes the config service to do it. The requirement itself is unchanged: with neither a flag nor a default, the command still exits 6 before the watcher starts.
-
-- **sync**: **Per-locale glossary overrides skipped the coverage preflight, and `--dry-run` performed no resolution at all.** `locale_overrides.<locale>.glossary` was resolved without the language pair, so an override that did not cover its own locale reached the API — unlike the top-level glossary and the translation-memory override, which were already checked. Both kinds of override now resolve once at startup against their own locale, rather than being re-resolved for every file, so a bad reference fails before anything is translated instead of after earlier files have been written. `sync --dry-run` resolves and checks the same references a real run does: the command already needs an API key to reach that point, and a glossary or translation memory the config names but the account cannot use for the requested pair is exactly what a preview should report. A dry run still sends nothing to `/v2/translate`.
-
-- **voice**: **`--glossary` was resolved before the rest of the command was checked, and without the language pair.** `voice a.ogg --to bogus --glossary my-terms` spent a glossary-list round trip and only then failed locally on the target language; every local check now runs first. Resolution also passes the requested pair, so a glossary whose dictionaries do not cover it fails locally with `Glossary "my-terms" does not support the requested language pair` instead of at the API — the preflight the other commands already had. The pair is the canonical one voice sends, so `--from EN --to zh-hans` is checked as `en→zh-HANS`. Without `--from` there is no pair to check and the API still judges it.
-
-- **translate**: **File, directory and `--dry-run` runs skipped the extended-tier language checks that text runs made.** `translate "Hi" --to af --formality more` exited 6 locally, while the same flags on a file or a directory reached the network and came back as an API rejection; `--dry-run` reported both as runnable, along with `--to 'not!!a!!lang'`, which every real run refuses. Language validation was spread over eight call sites in five files and only three paired the code check with the extended-tier check, which is how the modes drifted apart. There is now one entry point that every input mode calls, so a constrained option fails before anything is sent whichever mode handles the argument. Each mode passes only the flags it actually honours, so nothing is refused over a flag its mode discards: a document run still accepts `--model-type`, which it strips after warning, and a directory run still accepts `--glossary`, which it ignores. **`--from` is validated too** — it never was, so a malformed source language went unremarked until the API answered — and is named as such: `Invalid source language code: "grman"`. The "not in the bundled language list; deferring to the API" note is now said once per code per run instead of once per call site, which had it printing twice for `--to de,ex` and four times for `--to ex,zz` on a directory. An empty repeatable `--glossary` list no longer trips the "do not support glossaries" rejection, and a dry run lowercases `--to`/`--from` the way the real run does.
-
-- **translate**: **A directory translation where every file failed exited 0.** The summary reported `✓ Successful: 0 / ✗ Failed: N` and the command still looked like success to a script or CI job. Since language validation defers unknown codes to the API, a plain `--to` typo took this path: on 1.x it exited 6 locally, and in this release it printed a failure list and exited 0. A run with no successes now exits 1, and a partial failure exits 12, matching what `sync` already does.
-
-- **translate**: **The rejected-request abort covered only plain-text batches.** `.txt` and `.md` files are grouped into batches and stopped after the first rejection, but `.json`, `.yaml`, `.html`, `.srt` and `.xliff` go through the per-file path, which still spent one round trip per file collecting the same answer. That path stops the same way now, and files that were never sent are reported as skipped rather than as failures carrying another batch's error. The classifier also checks the error class before the message: a 5xx interpolates the upstream body, so a gateway error quoting `target_lang` no longer aborts a run that is otherwise succeeding, while a refused key or an exhausted quota — as request-wide as a bad code — now do.
-
-- **voice**: **`--quiet` discarded the salvaged transcripts of a failed session.** The partial result went through the warning channel, which quiet mode suppresses, while the live display was erased regardless — so audio that had been transcribed and billed left nothing on screen. It goes through the error channel now, the display is only cleared once there is something to print in its place, and `--format json` is honoured on that path. The live display also keyed target rows by the requested spelling, so with `--to zh-HANS` a `zh-Hans` echo left the row blank for the whole session; it is matched case-insensitively, as the session already was.
-
-- **voice**: **Regional target and source codes had to be spelled in exactly the API's casing.** `--to en-gb` or `--to zh-hans` exited 6 while `--to en-GB` worked, even though `deepl languages` prints the lowercase form and every other command accepts any casing. Codes are matched case-insensitively and canonicalized to what the Voice API expects.
-
-- **glossary**: **Deduplicating repeated `--glossary` flags inverted the documented precedence.** A repeat kept its first position, so `--glossary base --glossary override --glossary base` let `override` win the terms both define, although the user put `base` last. A repeat now keeps its last position, which is the one the API applies.
-
-- **sync**: The startup glossary coverage check required the top-level glossary to cover every target locale, including locales configured with their own `locale_overrides.<locale>.glossary`. That glossary never translates those locales, so a documented configuration aborted before any file was touched.
-
-- **config**: Language normalization applied to `config set` but not to the load path, so a file written or hand-edited with uppercase codes kept them — and because `TranslationService` merges `defaults.sourceLang` verbatim, `DE` in config and an explicit `--from de` keyed two cache entries for one request. Codes are normalized on load too. The note about a code the snapshot does not list is also limited to the write path; shared with the loader it printed on every invocation, including `deepl --version`.
-
-- **translate**: Document mode warned that `--model-type` and `--tag-handling*` would be ignored and then rejected the command over them, because the shared validation still saw them. The mode now discards what it says it discards.
-
-- **usage**: A duration-billed product could render a character count as hours by scaling it, and a `null` count was reported as a genuine zero. Character counts are read only for `milliseconds` billing, where they carry the duration; anything non-finite is treated as absent.
-
-- **languages**: `--features` contradicted its own footer: a language supporting none of the discriminating features read as `none` two lines above a note crediting it with the features every described language shares. Only a language credited with nothing at all reads `none` now. `--features` also disabled the Formality column without always replacing it, so the flag could show less than the plain listing, and the `?` cell for an undescribed language had no legend.
-
-- **docs**: Three passages described behaviour that no longer exists — the `voice --glossary` row had picked up `translate`'s repeatable/`--from` semantics (voice takes one glossary and requires neither), the `write` reference still said an unknown code is rejected locally, and the `usage` reference still documented the removed Speech-to-Text section along with output showing the duplicated API-key figure.
-
-- **cache**: `write` and `correct` entries cached for the five target codes whose casing changed (`en-GB`, `en-US`, `pt-BR`, `pt-PT`, `zh-Hans`) are no longer reachable, since those keys hash the target language. They are left to expire with their 30-day TTL rather than dropped: the key is a hash, so the affected rows cannot be told apart from the ones for `de`/`en`/`es`/`fr`, which are unaffected and still serve.
-
-- **cache**: **The translation cache keyed on too little and could serve the wrong text.** `translationMemoryId`, `translationMemoryThreshold`, `--ignore-tags`, `--splitting-tags`, `--non-splitting-tags`, `--outline-detection` and `--preserve-formatting` were absent from the key, so `deepl translate "Hello" --to de` and the same command with `--translation-memory my-tm` collided: the second returned the cached non-TM translation, never consulted the memory, and reported `cached: true`. Likewise two runs differing only in `--ignore-tags` returned each other's output. `preserveFormatting` had been excluded on the grounds that it does not affect output, but `preserve_formatting` suppresses the sentence-boundary punctuation and case correction, which shows up in the text. **Every translation entry cached by an earlier version is retired**, not only the ones using these options: the service merges a `preserveFormatting` default, so it is always part of the key. The cache schema version is bumped, so those rows are dropped on first open rather than sitting unreachable until their 30-day TTL — `write` and `correct` entries key the same way they always did and are kept. The first translation of any given text after upgrading is refetched.
-
-- **translate**: **A rejected language no longer costs one API round trip per batch.** Because validation defers well-formed unknown codes to the API, a two-letter typo reaches it — and a directory translation asked the same rejected question once per batch, so `deepl translate ./docs --to ex` on 200 files made 200 failing requests to be told the same thing 200 times. An unsupported `target_lang` or `source_lang` is a property of the request, not of one batch, so the remaining batches now fail without being sent; errors specific to a batch (a rate limit, say) still let the run continue. Relatedly, local validation used to be what pointed at `deepl languages`, and deferring left users with a bare `Value for 'target_lang' not supported.` from the server: a code the bundled snapshot does not list now says so up front, before anything is sent or billed.
-
-- **usage**: **Voice usage reported the API key's own consumption as the account total.** Duration-billed products fell back to `apiKeyUnitCount` for the account figure because live `GET /v2/usage` responses omit `unit_count` for them, so `deepl usage` printed the same number in both columns — an account with 100 minutes used and 10 on this key showed 10 for both. The account-wide field the response does carry, `account_unit_count`, was neither typed nor parsed; it is now, and where no account-wide figure exists the row reads `(API key)` instead of inventing a total. This is the only place voice usage appears since the Speech-to-Text section was removed, which is why the wrong number mattered.
-
-- **glossary**: Six smaller defects around the multi-glossary work. Naming one glossary twice — or a name plus its own UUID — sent a duplicate in `glossary_ids`, which flipped the wire parameter away from `glossary_id`, minted a third cache key for an identical request, and spent two of the five slots the API allows; IDs are deduplicated after resolution. `sync` resolved its glossary without the language pair, so a glossary that did not cover it failed once per file instead of at startup, unlike the sibling translation-memory resolution. `translate --dry-run` reported a glossary command as runnable that the real run rejects for a missing `--from`, and `watch --dry-run` did the same. The document path never ran the extended-tier constraint check, newly reachable now that documents accept glossaries, so it uploaded the file and let the API refuse it while the text path said so locally. `glossary info` printed raw dictionary languages beneath a normalized summary, so one glossary could show `EN → DE` under `Source language: en`. And a coverage error listed every dictionary of a multilingual glossary on a single line.
-
-- **glossary**: `--glossary` with a source language set only in config no longer fails. `TranslationService` merges `defaults.sourceLang`, so the request carries `source_lang` whether or not `--from` was typed, but the guard tested the flag alone — so `deepl config set defaults.sourceLang en` followed by `deepl watch ./docs --to es --glossary my-terms` broke a session that had been working. The effective source language is now resolved onto the request, which also gives the document path (which merges no defaults of its own) and the glossary preflight the pair they need. An empty `--glossary` selection is no longer treated as a glossary either: `[]` is truthy, so a caller passing one got a spurious "Source language (--from) is required".
-
-- **languages**: `--features` no longer claims knowledge it does not have. The listing keeps snapshot entries the API response omitted, and every one of them was rendered as the positive claim `none` — with a response covering a handful of languages, `--features` reported over a hundred as supporting nothing. Those rows also made every feature look non-uniform, so features shared by all the described languages became columns of repeated values instead of the single footer note the flag was built around. A feature reported without a `status` rendered as the literal string `undefined` (the enum is open, and an absent status still means the feature is there), and `supportsFormality` was asserted `false` for languages whose features the response never mentioned, turning on the `[F]` legend with no `[F]` anywhere to explain it. `deepl languages` also makes one `GET /v3/languages` request instead of two identical ones — both roles are filtered out of the same payload.
-
-- **languages**: `deepl languages --format json` with no API key answered `{"source":[],"target":[]}` while the text and table formats printed all 125 from the bundled snapshot. Both read the same snapshot, so the JSON path now falls back to it too — listing languages works offline in every format.
-
-- **config**: `deepl config set defaults.sourceLang DE` was rejected while `deepl translate --from DE` works. Every translate path lowercases the flag before validating, but the config validator matched a lowercase-only pattern, so the one casing that is certainly valid was the one class of input still refused. Language values are lowercased before validation and stored normalized. A code the bundled snapshot does not list is still accepted, since the snapshot can lag the API, but now warns at the point of entry — a typo written to config otherwise failed on every later command with nothing pointing back at the config value responsible.
-
-- **translate**: `--tag-handling-version` is honoured for files and directories, not only for text. The shared option mapping carried `--tag-handling` but not the version, so with the CLI now pinning v2 whenever tag handling is on, `deepl translate page.html --tag-handling html --tag-handling-version v1` silently sent v2 — and single-file mode emits no ignored-option warning to say so. The flag is mapped in the shared mapping every handler uses, and its validation moved with it.
-
-- **scripts**: `npm run generate:languages` refuses to write a snapshot that would break the CLI. An empty write list would collapse the `WriteLanguage` union to `never`, rejecting every `--lang` while naming no valid option; a features matrix that stopped reporting `glossary` would retier all 125 languages as extended and make `--formality` and `--glossary` unusable everywhere. Both now fail the run instead. `--check` compares whole blocks rather than quoted codes, so a renamed display name is reported as real drift instead of "formatting only", and the generated file is in `.prettierignore` so `npm run format` cannot make that check fail permanently. Both resources are fetched together and their failures reported together, so a key that cannot read `resource=write` no longer blocks regenerating the translation list it can read.
-
-- **languages**: **Four target languages the API accepts were unusable.** `de-CH` (Swiss German), `de-DE`, `fr-CA` (Canadian French) and `fr-FR` are returned by `GET /v3/languages` and accepted by the translate endpoint, but the CLI's bundled language list did not contain them, so `deepl translate --to de-CH` failed locally with `Invalid target language code` before any request was made — and the `deepl languages` the error suggested did not list them either, because the listing used the bundled list as its row set rather than the API response. Swiss German and Canadian French had no workaround; `de-DE`/`fr-FR` could be spelled `de`/`fr`. The list now contains all 125 languages the API serves (32 core, 11 regional, 82 extended). See the Changed entry below for why this class of divergence can no longer make a language unusable.
-
-- **languages**: `deepl languages --target` marks Portuguese (`pt`) with `[F]`. Formality support is now read from `features.formality` on `GET /v3/languages` instead of a static table in the language registry. The v3 migration had assumed v3 stopped reporting formality, but the capability was only renamed — v2's `supports_formality` boolean became the presence of a `formality` key in the per-language features matrix — so the CLI was answering from an 11-entry snapshot of the final v2 response that had already drifted from the API. The snapshot and the registry's `supportsFormality` field are gone; the registry's `category` tiers are unaffected. Output is otherwise unchanged: the `[F]` set is identical apart from `pt`.
-
-- **watch**: `--glossary` without `--from` now exits 6 before the watcher starts, instead of starting a session that fails on every single file change with a raw server message. The API rejects any translation naming a glossary without a source language ("Use of a glossary requires the source_lang parameter to be specified"), which `translate` already guarded against up front for text, files, and documents; `watch` passed `--from` straight through. A long-running command is the worst place for this, since the operator saw the failure once per edit rather than once at launch. The check runs before the glossary name is resolved, so it costs no API call. `sync` needs no equivalent: it has no `--from` at all, taking the source language from the required `source_locale` field in `.deepl-sync.yaml`, so its requests always carry one.
-
-- **voice**: A session that ends with the audio transcribed but no translation for a requested `--to` language now fails with exit code 9 and names the languages, instead of printing an empty translation line and exiting 0. The failure **carries the transcripts that did arrive**, which the command prints to stderr before exiting: the audio is transcribed and billed before the missing translation is noticed, so with `--to de,fr,es,it,ja` one dropped target must not throw away the source transcript and four good translations and make the user re-stream to see them. Target updates are also matched **case-insensitively**, because the requested spellings include `zh-HANS` and `en-GB`: a server echoing another canonicalization had its translation silently dropped by the existing unmatched-update guard, and this check would then have reported that target as missing — turning a cosmetic mismatch into a failed session. Silent partial output was the worse failure: a script consuming `deepl voice` output saw success with the translation missing. Audio containing no speech transcribes to nothing and translates to nothing, which is legitimate and still exits 0, so the check only applies when a source transcript exists. Whitespace-only and tentative-but-never-concluded translations count as missing, since neither reaches the printed output. Investigated as an intermittent (~1 in 4) empty translated line; the leading hypothesis was disproved with frame-level traces of live sessions — the server sends `end_of_stream` strictly after `end_of_target_transcript`, and the client only tears the socket down on `end_of_stream`, so there is no client-side teardown race. Reconnect was ruled out too: a socket dropped after end-of-source cannot be resumed (the API returns `410 Gone`) and already exited non-zero. The empty line did not reproduce in 64 live runs across pacing, burst, multi-target, and concurrency variations, so the trigger appears to be server-side and transient — which is exactly why the client needs to detect it rather than report success.
-
-- **formats**: TOML reconstruction escapes U+2028/U+2029 (Unicode line/paragraph separators) in double-quoted values, and literal-string values gaining one fall back to double quotes. Written raw, these characters broke the entry-line scan on the *next* sync (JavaScript's `.` excludes line terminators), which re-appended the key as a duplicate and made the third sync fail to parse the file at all — first sync fine, second silently corrupting, third crashing. Found by the property-based round-trip suite.
-
-- **formats**: `.properties` reconstruction escapes leading spaces in values (`\ `), which the value parser otherwise strips on the next read — a translation beginning with a space silently lost it on every subsequent sync. Leading tabs, trailing spaces, and newlines were already escaped correctly. Found by the property-based round-trip suite.
-
-- **sync**: `--auto-commit` now recognises its own translation output rather than only the files a given run wrote, which fixes two related problems. A translation left on disk by an earlier refused run was classed as an unrelated modification, so auto-commit refused forever and the user had to commit it by hand; it is now committed once the genuinely unrelated changes are dealt with. And in `--watch` mode, where the same path runs once per trigger, a trigger that translated nothing skipped the checks entirely and reported success while a commit was still owed. Staging is also driven by what is actually dirty, so a rewrite that produced identical bytes no longer attempts an empty commit. Ownership is derived from the lockfile's tracked source files, with each file matched to its own bucket so one bucket's `target_path_pattern` cannot claim another's output.
-
-- **sync**: Re-running `deepl sync --auto-commit` after a refusal no longer reports success without committing. A refused run still writes its translations to disk, so the retry found nothing to translate; the preflight was skipped in that case and the command exited 0 with no commit made, the translation still uncommitted and the tree still dirty. The repo-state checks now run whenever `--auto-commit` is requested, so the refusal is reported identically on every attempt. Staging and committing are still skipped when there is nothing to commit. Two tests covered this path but could not see the defect: their assertions ran only inside a `catch` the retry never entered, which also hid an assertion that could never have matched (it looked for "detached HEAD" against a message reading "HEAD is detached").
-
-- **write**: `deepl write` now runs from a published install. `diff` is imported at the top of the write command but was declared only under `devDependencies`, which consumers do not install, so every command that loaded the module failed with `Cannot find package 'diff'` before producing output. `--help` did not surface it because the module loads lazily.
-
+- **sync**: The first `deepl sync` over an already-translated project no longer overwrites every reviewer translation with machine output. The carry-forward that protects a reviewed translation was wired into the `current`-key path only, so with no `.deepl-sync.lock` — first adoption, or any CI checkout where the lockfile is gitignored — every key arrived as `new` and was re-translated, re-billed and written over, dropping `#, fuzzy` and XLIFF `state` markers at exit 0. A `new` key whose target file already holds a translation is now carried forward untouched and recorded in the lockfile. A target value equal to the source, or an empty one, is still translated, and `--force` still re-translates everything.
+- **sync**: A reviewed PO or XLIFF translation is no longer replaced with source text. Both formats are bilingual, and every path that needed "the translation this target file already holds" read the *source* side (`msgid` / `<source>`) — six call sites, including `sync push` and `sync validate`. Parsers may now override the target-side read (`FormatParser.extractTranslations`), PO and XLIFF do, and all six sites go through one helper. An empty `msgstr`, a missing `<target>` and an empty `<target></target>` now read as *untranslated*, so such a key is translated rather than having the source pinned into it; in the monolingual formats an empty value is still a deliberate translation and is preserved. `deepl sync pull` had the same blind spot in its merge base and `deepl sync audit` measured consistency across source strings rather than translations.
+- **sync**: `deepl sync push` no longer uploads the source language as a locale's translation — a `locales/es/app.po` holding `msgstr "Hola amigo"` used to push the English msgid, making the TMS authoritative for the wrong text. `TmsClient.pushEntry` now takes the translation as a required argument rather than reading it off `entry.value`.
+- **sync**: A target file that is on disk but cannot be read or parsed is left exactly as it stands instead of being re-translated and rebuilt from the source. `ENOENT` is now the only read failure that means "absent"; any other errno and any parse failure mark that locale unusable **before any translation is requested**, so the run names the file and reason, reports `✗ es: 0/2 keys`, exits 12, bills 0 characters, and records a newly gained key `failed` for the next run to retry. `deepl sync pull` routes every unreadable target to the same outcome under a new `unusable_target` skip reason; `deepl sync push` already propagated everything but `ENOENT`. One reader (`readTargetFile`) now answers absent / usable / unusable for all four call sites at no extra I/O.
+- **sync**: A target file that becomes unreadable between the pre-read and the write-time re-read is no longer reclassified as absent and overwritten with a source-derived file, with no backup taken. The reconstruct template now comes from the same guarded read, so an unreadable target aborts that locale exactly as the pre-read would. A target holding only whitespace is now classified as present-but-empty rather than unusable, since it has no translations to lose and parsing it would fail.
+- **sync**: `deepl sync` and `deepl sync pull` no longer delete another sync configuration's translations from a target file both configurations write — a flip-flop where each run deleted the other's keys and re-billed its own, both reporting success at exit 0. A run about to delete keys now looks for another configuration whose lockfile records those exact keys for the same locale, and leaves the file exactly as it stands: `deepl sync` fails that locale (nothing written, nothing billed, keys recorded `failed`, exit 12) and `deepl sync pull` skips it under `shared_target`, both naming the other lockfile, the shared keys and the remedy. Keys added to a locale file by hand are unaffected and still pruned with the usual warning.
+- **sync**: A bucket whose source files resolve to the same target path is refused at the bucket walk, before any translation request, with an error naming both source files, the shared target and the locale. Previously each file's rewrite treated its own keys as the complete key set, so the files deleted each other's translations while every run reported success and billed again. The suggestion deliberately does not offer `{basename}`, which does not separate two files both called `en.json`; omit `target_path_pattern` or split the bucket. Multi-locale (bilingual) buckets are exempt.
+- **sync**: One failed translate batch no longer deletes that batch's existing translations from the target file. `translateBatch` chunks at 50 texts and keeps going when one chunk fails, and those empty slots used to fall through to a bare `failed++` — so, because `reconstruct` treats the entry list as the complete desired key set, the failed chunk's keys were removed from the file (and the run's `.bak` unlinked, since the run itself succeeded). A key the target already holds now keeps its translation, and is deliberately recorded `failed` rather than counted as a success so the next run retries it.
+- **sync**: The lockfile records what reached the target file, not what the API returned. Every key is now read back out of the content just written before the lockfile is updated; a key the file does not hold is recorded `failed`, warned about by file, locale and key, shown as `✗ es: 0/1 keys`, and exits 12. Presence is the test rather than byte equality, and a deliberately empty translation is exempt; content a parser has just produced and cannot read back counts as holding none of its keys.
+- **sync**: A string added to a source file after the first sync is no longer silently dropped by five of the eleven formats. From the second run on, the existing target file is the `reconstruct` template, so a newly added key has no slot in it — `properties`, `ios_strings`, `laravel_php`, `android_xml` and `xliff` discarded it while the lockfile recorded it `translated`, so no later run corrected it and the characters were billed. Each now writes the entry in the file's own layout, XLIFF 1.2 (`trans-unit`) and 2.0 (`unit`/`segment`) alike. Two cases are deliberately still not written, because doing so would mean inventing structure the source defines: a new `<string-array>` item in `android_xml`, and a `laravel_php` key whose parent array is absent from the target — both now recorded `failed` rather than `translated`.
+- **sync**: A plural entry a run carries forward keeps its plural forms. The carry-forward handed the writer the **source** file's plural payloads — empty `msgstr[N]` for gettext, source-language `<item>`s for Android XML — so any run with other work to do destroyed the target's plural translations at exit 0, on all three affected paths (translation, validation withholding, and `sync pull`). Those sites now omit the plural payloads so the parsers keep the file's own forms, and Android's writer keeps a `<plurals>` element verbatim for an entry handed over without per-form translations. A key absent from the entry list is still deleted, and a plural entry whose source text changed is still re-translated with fresh forms. See `docs/SYNC.md` "A plural entry carried forward".
+- **sync**: A `#, fuzzy` flag on a carried-forward PO entry survives a run that rewrites the file for a sibling key. The comment replay stripped `fuzzy` from every entry it emitted, so any sync with other work to do removed a reviewer's "do not ship" marker and `sync status` then reported 100% again. The flag is now stripped only when the run writes **different content** over the entry — comparing the msgstr and every `msgstr[N]` — and a carried entry keeps its comment lines byte for byte (a `#, fuzzy, python-format` line is no longer re-joined).
+- **po**: A wrapped (continuation-line) plural form survives a run that only rewrites its entry for a sibling key. `reconstruct` re-emitted the first line of a form it was *keeping* and swallowed the continuations, collapsing a reviewed long form to an empty first line and leaving the entry permanently unwritable — a loss `msgfmt --statistics` does not reveal. Continuations are now kept for a form being carried and still dropped for one being replaced.
+- **sync**: A translation the engine corrupted is withheld from the target file instead of being written and recorded as done. The placeholder/ICU validator ran after the write, the lockfile update and the backup cleanup, and its results were counted but never acted on; the new-locale backfill path was not validated at all. An `error`-severity result (a lost placeholder, a rewritten ICU bracket or selector) is now decided before the write on both paths: the key is withheld, counted failed and recorded `status: "failed"`, so the run reads `✗ de: 1/2 keys`, exits 12 and the next run retries the key. A withheld key carries whatever the target file already held rather than being deleted, plural write-backs are skipped for it, warnings still pass through and are still written, and `validation.fail_on_error` keeps its `false` default and its documented meaning.
+- **sync**: A failed backfill for a newly added locale no longer writes the source text in as the translation, which made those strings count as existing translations and be skipped on every later run — `sync status` reporting them missing while `deepl sync` refused to retranslate them, permanently. The backfill now pushes nothing, so the key stays out of the target file, and nothing is recorded in the lockfile for it either.
+- **BREAKING — sync**: Untranslated source text is never written into a target locale file and recorded as a translation. Where a key's source was unchanged, the lockfile claimed a translation and the target file supplied none — the file was deleted to force regeneration, or held an empty value — the source string was written through as the "translation" and kept its `translated` status, so no later run corrected it. Such a key is now re-translated, with a verbose message explaining why; a present-but-deliberately-empty translation is preserved. **Behaviour change**: deleting a target locale file now costs a real, billed re-translation instead of being backfilled with English.
+- **sync**: A target file that has lost translations the lockfile records as translated is no longer reported as 100% complete — `sync status`, `sync --frozen` and `sync` itself all worked from the lockfile and never opened the target file, so a bad merge, a partial checkout or a hand deletion read as complete on every run. For every key recorded `translated` against the current source, the locale's target file is now read; a key it does not hold is counted **`unwritten`**, its own category distinct from `missing` (absent from the lockfile) and `outdated` (recorded against an older source) and never counted as complete. `sync status` names the file and key, `--frozen` exits **10** naming the count, and `sync` translates the key again and writes it. New JSON fields: `unwritten` per locale and top-level `unwrittenByLocale` on `sync status`, and `unwrittenKeys` on the sync result. Two deliberate exemptions: a key whose source value is empty, and a key already recorded `failed` or against an older hash. The read is skipped for a locale the lockfile claims nothing for.
+- **sync**: `sync status` no longer says the keys of an unreadable target file "are not in the target file", nor tells you to sync again — advice that bounced the user between a `status` that said to run `sync` and a `sync` that declined. Such a file now gets its own sentence naming it and the parser's reason, a project with both kinds of gap gets both sentences, and `--format json` carries the reason as a new `unusable` field on the locale's `unwrittenByLocale` entry. The `--frozen` drift line no longer asserts a cause it has not checked and points at `sync status` for the detail.
+- **sync**: `--dry-run` previews the run rather than the lockfile, in both directions it was wrong: it under-quoted repair work (reporting `estimatedCharacters: 0` for keys the next real run translated) and over-quoted work that was never going to happen (pricing a locale whose target file the real run refuses). Both halves now come from one `findTargetGaps` call per source file: gap keys are added to the estimate and reported as `unwrittenKeys`, and a locale whose target file is unreadable is left out of the estimate and named in its own warning. The summary also states when a key recorded as translated could not be confirmed in the target file, so the estimate is not a number with nothing behind it. A dry run still writes nothing and still exits 0.
+- **sync**: The `sync.max_characters` cost cap no longer under-counts the work it is meant to cap. Its preflight used the same lockfile-only arithmetic as `--dry-run` — computing 500 characters for a run that bills 1,000 — so the two now quote from one function and a run the preview prices above the cap is a run the cap refuses. This costs one pass over the target files before the cap decides; projects that do not set `max_characters` are unaffected.
+- **sync**: `--frozen` no longer reads every target file twice — the target-versus-lockfile comparison is computed once per source file and reused. No output changes.
+- **sync**: A run that lost most of its strings, or lost one locale of several, no longer exits 0. A locale counted as failed only when it translated *nothing*, so 10 keys succeeding and 50 failing was not a failed locale and CI went green over a truncated locale file. Any failure count above zero now fails the run (exit 12); a locale that translated nothing and recorded failures fails it; a locale with nothing to do is still a success. `--auto-commit`, gated on `result.success`, no longer commits an unsuccessful sync. `docs/API.md`'s exit-code table now describes 12 as "at least one failed key".
+- **sync**: The `Sync complete:` summary names how many translations failed — `Sync complete: 200 new (150 translations failed)` — instead of reading as though every diffed key had landed, directly contradicting the `✗ de: 50/200 keys` line above it. The count totals every locale and nothing is appended when nothing failed. The progress stream's `key-translated` events also fire only when that key's `translateBatch` slot came back non-null, so the number it reports agrees with the summary.
+- **sync**: Staleness is judged per target locale. `computeDiff` compared only the entry-level `source_hash`, so once one locale was re-synced every *other* locale reported `current` forever and `--frozen` could not see it; and one locale's failure marked the key stale for **all** locales, so `deepl sync --locale de` re-translated, re-billed and overwrote de's reviewed translation because **es** had failed. A key is now stale if any locale the run will actually touch lags the source or last failed, `sync status` distinguishes "the source changed" from "this locale's record lags" by re-checking the source hash and counts a failed translation as `missing` rather than `outdated`, and locales absent from `target_locales` are ignored while a locale with no entry at all is still treated as a new-locale backfill.
+- **sync**: A gettext `#, fuzzy` entry and an XLIFF review state are no longer counted as finished translations — `msgfmt` leaves a fuzzy entry out of the compiled catalog, so the string the CLI called done is one the application does not display. Each is now its own **`needsReview`** category in `sync status` (text suffix `, 1 needs review` plus a line explaining the marker and both ways out; `needsReview` per locale in `--format json`), and `deepl sync push` skips it under a new `needs_review` skip reason instead of uploading a draft as approved. **Nothing is re-translated, rewritten or re-billed**: removing the marker returns the key to `complete` with no API call, and clearing the translation has the next sync translate it afresh. XLIFF reads its states as an explicit claim only — 1.2's `new` and `needs-*` and 2.0's `initial` count, `translated`/`signed-off`/`final`/`reviewed` do not, and an absent or unrecognised value counts as complete, so an existing project's coverage does not move. `state-qualifier` (1.2) and `subState` (2.0) are not read, and `sync --frozen` deliberately still passes.
+- **sync**: A `state` attribute on an XLIFF target the CLI has just written now describes what the CLI wrote. A source exported with `<target state="needs-translation">` placeholders — what most CAT tools produce — yielded a target file whose every unit claimed it still needed translating. Such a state becomes `translated` when reconstruct replaces the target's content, a `signed-off` state written over is downgraded the same way rather than claiming human approval for machine output, an element carrying no `state` still gains none, and a `state` on a unit whose translation is unchanged is never touched — which is what keeps a reviewer's `needs-review-translation` alive through a run that translates a sibling key.
+- **sync**: The startup stale-backup sweep no longer deletes a crashed run's backup, so recovery is no longer limited to `sync.bak_sweep_max_age_seconds` (default 300) after the crash. A stale backup is now deleted only when the file beside it already holds the same bytes (sizes compared first, contents only when they agree, so the common case still costs one `readdir`); one whose target has diverged or is gone is kept however old it is and reported once per sweep, naming the file. Retention is bounded at one file per target, and `bak_sweep_max_age_seconds` keeps its meaning for redundant backups. The fix is in `sweepStaleBackups`, which every caller shares.
+- **sync**: A backup left behind by a crashed run is no longer overwritten by the run you start to recover from it — the "already backed up" guard was a per-process `Set`, so the recovery run copied machine output over the only surviving copy of the user's file and then unlinked it on success. The copy now uses `COPYFILE_EXCL`, and on `EEXIST` the existing backup is left alone with a warning naming it and is deliberately not tracked as this run's, so the success path does not unlink it either.
+- **sync**: Ctrl-C during a sync restores the files it had already overwritten instead of deleting their backups, and reports what it undid (`Interrupted — restored 1 file(s) from backup: locales/de.json. No lockfile was written, so nothing was recorded; re-run to translate again.`). Each backup is copied back over its target before being removed, so an interrupt during the restore leaves the backup rather than nothing. The restore is synchronous, because the exit is deferred by one `setImmediate`. A successful run still unlinks from its own path.
+- **watch**: A watch pass that fails, is cancelled or hits drift now restores the targets it had already rewritten instead of deleting their backups — `WatchController` only ever *unlinked* what the backup tracker held, so a two-locale pass where the second locale was refused left the first holding machine output, its `.deepl.bak` deleted, no lockfile written, at exit 0. Each file is copied back before its backup is removed, and a backup that cannot be restored is kept with a warning naming it. A pass that completes still removes its backups as before.
+- **sync**: Two syncs can no longer run concurrently in the same directory. A stale pidfile is now removed only after taking possession of it with `rename(2)` and confirming the captured inode is the one proven stale (a process that captures a different file puts it back), acquisition always goes through one guarded create so a lost race reports the running sync instead of a raw `EEXIST`, the retry loop is bounded at 5 attempts, and the payload is written to a private path and `link(2)`ed into place so a **live** lock can no longer be read as malformed — and therefore stale — during the window it was being filled.
+- **sync**: A pidfile naming a process this user cannot signal no longer refuses every later sync indefinitely. `kill(pid, 0)` answers EPERM for a PID owned by another user, a recycled PID, or one from a container's PID namespace, and that was read as "alive" with no upper bound while the recorded `startedAt` was never consulted. Such a holder is now trusted only while its start time is within 24 hours and readable as a date (a time impossibly far in the future counts against it), after which the lock is reclaimed with a warning naming the PID and the reason. A holder the probe reports as genuinely running is never aged out — that case gets `--break-lock`, which the refusal message now names.
+- **sync**: `sync resolve` takes the process lock, `--dry-run` included, and exits 7 with the same "Another `deepl sync` process is running" message while one is held, leaving the conflict markers in place. Previously a concurrent sync silently erased its merge, both steps reporting success. Its write also goes through the atomic rename every other lockfile writer uses, so a crash part-way through leaves the previous lockfile rather than a truncated one (which reads as corrupt and costs a full re-translation), and a run whose lockfile changed on disk between its read and its write now says so while still recording what it did.
+- **sync**: Each lockfile translation is written on a single line, so the smallest region `git merge` can produce is a whole translation. Field-per-line entries let git merge two clean hunks into a translation that existed on neither branch — `review_status: human_reviewed` from one side carrying the other's `translated_at`, marking machine output as human-approved at exit 0 with no conflict reported — and made `sync resolve`'s `translated_at` tie-break unreachable, so every field took the `kept ours: scalar conflict` path and discarded newer human translations. A region's trailing comma is now removed before parsing and restored after, keys are sorted within the line, `stats` is written on one line too (its counts and `last_sync` describe one run) and is recomputed from `entries` on read. Where the two sides disagree on the terminator, the region still falls to the length heuristic rather than risk invalid JSON. **Upgrading reformats every existing lockfile on the next write; it is formatting only and no entry's content changes.**
+- **sync**: `sync resolve` no longer keeps the local side of every conflict while reporting `kept ours: neither side had translated_at`. An entry holding a `translations` map is now treated as a container and merged one locale at a time, which is where the timestamps live, and the report names the locale it decided (`greeting.translations.de`). A translation leaf is identified by `hash` as well as `translated_at`/`source_hash`, and **one side looking like a translation is enough** to arbitrate the pair whole, so no field combination can be invented however degraded the other side is; a non-string `translated_at` counts as absent so another tool cannot steer the tie-break with a non-comparable value; and fields the two sides agree on are no longer listed as conflicts. Two decision reasons that stated untruths are reworded (`kept ours: same translated_at <stamp> on both sides`, `kept ours: theirs had no translated_at`), the resolved file is written back in canonical form so committing it cannot leave entries expanded for the next merge, and each parse-error fallback warning prints once with a relative path.
+- **sync**: `sync resolve` no longer warns about possible data loss on every ordinary lockfile merge. `stats` sat two context lines below `generated_at` and both change on every write, so git joined them into one region that opened inside `stats` and closed outside it — not a member list, so `JSON.parse` failed, the length heuristic decided, and the one signal that exists to make silent data loss auditable fired on every resolve, including two branches translating different keys. Writing `stats` on one line keeps the region a member list, and the same fixtures now report `generated_at` and `stats.last_sync` as ordinary per-member decisions with no warning.
+- **sync**: A lockfile entry whose i18n key is named `__proto__` no longer vanishes on every write, and the key-sorting JSON replacer no longer drops it either. See Security for the full accessor rework.
+- **sync**: `deepl sync pull` no longer writes source-language text into a target locale file. The merge's final `?? entry.value` fallback filled a key the export omits **and** the target lacks with the source string — indistinguishable from a translation — and, when the target file did not exist yet, wrote every untranslated key into the new locale as English. Such a key is now omitted from the entry list so `reconstruct` leaves it out of the file; an empty string is a translation and is still preserved. The pulled value still wins over the local one, since neither side of the export contract carries a timestamp, but the overwrite is no longer silent: pull counts the local translations it replaced and names the count (`Replaced 1 existing local translation with the TMS version. Use --dry-run to preview a pull before it overwrites local edits.`), with `--verbose` naming each key and file.
+- **sync**: `deepl sync pull` keeps the tabs and newlines of a multi-line translation instead of deleting them and fusing the adjacent words. The sanitizer stripped the whole `[\x00-\x1f\x7f]` range, including the three C0 bytes every format either escapes or legally emits; tab, LF and CR now survive to the per-format writer, which escapes them, while every other C0 byte and DEL is still stripped so a raw ESC cannot reach a locale file.
+- **sync**: `deepl sync pull` recognises a gettext plural entry that declares `msgid_plural` before it holds any `msgstr[N]`, instead of judging plurality from metadata that only appears once forms exist — which had it treat the entry as an ordinary key and record a translation it had not applied.
+- **sync**: `deepl sync pull` no longer discards existing translations for keys named after `Object.prototype` members. `sanitizePullKeysResponse`'s accumulator now has a null prototype and keeps it through the merge, and `mergePulledTranslations` tests membership with `Object.hasOwn`, so a source key called `toString`, `constructor`, `valueOf`, `hasOwnProperty` or `__proto__` no longer resolves to an inherited function that beat the real translation and then vanished from the file while the lockfile recorded it `translated`.
+- **sync**: An unreachable TMS is reported as a network failure (exit 5) naming the request — `TMS request failed: PUT https://tms.example.com/api/projects/p/keys/greeting: ECONNREFUSED` — plus a line pointing at the `server:` URL in the `tms:` block, rather than a bare `Error: fetch failed` at exit 1 for a refused connection or an unresolvable host while a hung server exited 5. The replay policy is deliberately unchanged, and a `NetworkError`, a 401, a 500 and a timeout each keep their own message.
+- **sync**: `TMS server URL must use HTTPS` now echoes the URL and points at `http://localhost`, which reaches a server bound to `::1`, `0.0.0.0` or `127.0.0.1`. The rule is unchanged: plain `http://` is waived for `localhost` and `127.0.0.1` only, the same pair the DeepL API base URL waives.
+- **sync**: TMS request URLs are built with the URL API — a trailing slash on `server:` no longer produces a doubled separator, a base path is preserved, and a URL with a query string or fragment is rejected instead of silently truncating the API path. TMS timeouts exit 5 instead of 1, TMS error messages redact credentials embedded in the server URL, and `deepl sync pull` enforces its 32 MiB response cap while reading the body rather than after parsing it.
+- **sync**: `deepl sync audit` no longer reads files outside the project root. Audit is driven by `.deepl-sync.lock` keys rather than globbed paths, and it joined them to the project root and read them with a bare `fs.readFile`, so a lockfile key of `../secretplace/en.json` printed that file's string values in `inconsistencies[].translations` at exit 0. `assertPathWithinRoot` now runs before the read and a violation ends the command at exit 6; a lockfile entry whose path merely fails to resolve for a locale is still skipped.
+- **sync**: `deepl sync audit` no longer uses the lockfile's source hash as a stand-in for a translation, which reported divergent translations as consistent and identical ones as an inconsistency displaying a hex hash. Targets that cannot be read are listed separately in a new additive `missingTargets` field in `--format json`.
+- **sync**: `sync.limits.max_file_bytes` applies to target files, not only source files — a target is the file a hostile or corrupt checkout controls, and it was parsed and rebuilt at any size. An oversized target is now reported `unusable`, with the reason naming the limit, rather than treated as empty (which would re-translate the locale in full and overwrite the file). The size is checked on the content that was read, since the cap exists to bound the parse and comparison work.
+- **sync**: An `include`/`exclude` pattern with a nested-quantifier extglob is refused at config load, naming the offending construct and pointing at `@(…)`, instead of wedging the process for minutes. `*(…)` and `+(…)` compile to a repetition, so an unbounded wildcard inside one hands picomatch a nested quantifier — the six-character `+(a*)b` took about 50 seconds against a 40-character directory name, and both pattern and directory names come from the checkout. `@(…)`, `?(…)` and `!(…)` are not repetitions and are unaffected, so ordinary patterns still work.
+- **sync**: A run that removes a hand-added key from a locale file now says so. Every run that rewrites a locale drops whatever the target holds that is not in the desired key set; for a key **neither the source nor the lockfile accounts for** that is someone else's data, and it was deleted with no mention anywhere while the `.deepl.bak` was unlinked on success. Such keys are now named in a warning pointing at both remedies — add them to the source, or recover them from the backup before the next run. The prune itself is deliberately unchanged.
+- **sync**: An invalid `--concurrency` no longer makes a sync silently do nothing while reporting success — `--concurrency abc` produced `NaN`, which survived defaulting and started **zero** workers. `--concurrency` and `--debounce` now reject non-positive and non-numeric values at the boundary, `sync.concurrency` is validated in config, and `mapWithConcurrency` clamps to at least one worker.
+- **sync**: Subcommands honour `--locale` (`status`, `validate`, `export`, which listed or exported every configured locale when the flag trailed the subcommand name) and `--sync-config` (`status`, `validate`, `export`, `audit`, `resolve`, `push`, `pull`, which silently used the auto-detected `.deepl-sync.yaml` instead). A `--locale` value that is not in `target_locales` now exits 7 with a `ConfigError` naming the offending and configured locales, rather than exiting 0 having translated nothing. `deepl sync init --sync-config <path>` writes the config at that path and checks the already-exists guard against it, and `.deepl-sync.yaml` is written atomically.
+- **sync**: `--auto-commit` recognises its own translation output rather than only the files a given run wrote, so a translation left on disk by an earlier refused run is committed once the genuinely unrelated changes are dealt with instead of being refused forever; and in `--watch` mode a trigger that translated nothing no longer skips the checks and reports success while a commit is owed. Re-running after a refusal now reports the refusal identically instead of exiting 0 with nothing committed. Staging is driven by what is actually dirty, so a rewrite producing identical bytes no longer attempts an empty commit, and ownership is derived from the lockfile's tracked source files matched per bucket so one bucket's `target_path_pattern` cannot claim another's output.
+- **sync**: `deepl sync --frozen` reports an accurate key count when drift is caused by a newly added target locale, where it read `Sync drift detected: 0 new, 0 stale keys.`; the message also surfaces `deletedKeys` and mentions only nonzero categories. The drift exit code (10) is unchanged.
+- **sync**: Every ICU block in a message is protected, not just the first. `parseIcu` found one block and pushed the entire remaining suffix as ordinary prose, so second and later blocks were submitted to the engine as translatable text — and an engine translating `other` yields a message with no `other` branch, which throws at render time. Detection now walks the whole string, emitting each run of prose as its own segment and each block through the same brace-counting parser; adjacent blocks, three or more blocks, and nested ICU are covered. The documented safe fallback now applies to the whole message: a string holding any block that will not parse passes through untouched rather than half-protected.
+- **sync**: ICU plural/select messages with text around the block, `offset:N`, and single-quote-escaped braces (`'{'`, `'}'`, `''`, `'#'`) are recognised and preserved instead of falling back to raw machine translation, which demonstrably translates the format keyword and the selectors. Detection matches a block anywhere in the string and the prose on either side becomes a translatable segment rather than being dropped from the reassembled output. `sync validate` placeholder checking is ICU-aware, so a translated branch body no longer raises a spurious `Extra placeholders in translation`.
+- **sync**: ICU structural damage is detected instead of reported as passing — brace counts and nesting depth are identical when the engine translates the keyword, a selector or the argument name, so `fail_on_error` never tripped on a message that no longer renders. Validation now compares the parsed argument/format-type headers and the selector keyword sets, tolerating reordered selectors. A failed ICU segment is marked failed and retried rather than yielding a part-English message reported as a success, and `reassemble` throws on a translation-count mismatch instead of filling gaps with empty strings that render nothing for that category.
+- **sync**: The internal ICU marker is no longer submitted to the API and billed as a text of its own — one extra request per batch containing an ICU string. The slot now holds nothing to translate, and `reassembleIcu` overwrites every mapped index so the blank cannot reach a target file.
+- **sync**: Two keys whose placeholders protect to the same text no longer receive each other's variables. `Hello {name}` and `Hello {user}` both become `Hello __VAR_0__`, which `translateBatch` deduplicates by design — but the same result object was assigned to every index and the restore loop edited `result.text` in place, so the second key was written with the first key's variable (`Deleted %s files` / `Deleted %d files` produced a specifier that no longer matches its argument). Each index now gets its own copy of the result and both restore loops replace their entry instead of editing it. `deepl translate` was never affected.
+- **sync**: Template literals containing regex metacharacters in scanned source code (`` t(`item(${i}`) ``) no longer abort context resolution with a raw `SyntaxError` or silently mismatch keys — metacharacters are escaped before the scan pattern is compiled.
+- **po**: A catalog written without blank lines between its entries is no longer collapsed into one entry. The separator is a gettext convention, not a requirement, but both halves of the parser treated it as the only thing that ends an entry: `extract` reported a single key, `reconstruct` wrote that one translation into every `msgstr` it walked past including the header's, an entry carrying `#:` comments was lost outright, an obsolete `#~` run deleted the header, a plural entry lost its `Plural-Forms` rule, and `extractTranslations` reported only the last entry as translated so every other reviewed msgstr was re-translated and re-billed on every run. An entry now ends where gettext ends it — at the first line that is not a continuation of its translation — in both the reader and the writer, each of which was proven insufficient alone. Layout is untouched: a catalog that arrived without separators keeps that shape.
+- **po**: Adjacent string literals on one line are concatenated as gettext defines them — `msgstr "Hola " "mundo"` is the string `Hola mundo`, where the inner quotes used to be read as content and then escaped into the translation permanently. Applies to `msgid` and `msgctxt` as well; a quote genuinely part of the string still decodes as content, and a malformed value (unterminated quote) is returned untouched rather than mangled.
+- **po**: An escaped carriage return survives a round trip instead of gaining a backslash on every run — `quote` escaped CR to `\r` but `unquote` had no `r` case, so a carried entry's CR became `\\r`, then `\\\\r`, indefinitely. `unquote` now decodes `\r`, making the round trip idempotent.
+- **po**: A `msgstr` containing U+2028 or U+2029 is readable. JavaScript's `.` excludes the line separators, so such a line matched neither scanner and the key was reported unwritten under a remediation no later run could satisfy. Escaping is not available here, since the PO escape set has no `\uXXXX`.
+- **po**: An obsolete `#~` block is no longer deleted along with the entry beneath it — gettext's retired-work region is an obsolete entry in its own right, not the following entry's comments. An entry's own `#.`/`#:`/`#,` comments are still dropped with it.
+- **po**: A plural key appended to an existing catalog keeps its `msgid_plural` and every `msgstr[N]`. The append path wrote the singular entry shape, so a plural key added to the source after the target file existed had `ngettext` returning the English source for every count while the lockfile recorded it translated. The path now emits `msgid_plural` and one `msgstr[N]` per recorded form in index order, with index 0 falling back to the entry's translation.
+- **po**: Rebuilding a catalog is linear in the length of a comment block again rather than quadratic — the run of comment lines above an entry is taken with a single slice instead of `unshift`ing each line (80k comment lines: 437 ms → 11 ms).
+- **properties**: A value ending in a backslash no longer deletes the entry after it. `escapeValue` writes a literal trailing backslash as `\\`, but the reader's continuation test had no parity check, so it consumed the following line and appended its raw text to the previous value — which `sync push` then sent to the TMS under the previous key's name while the swallowed key was never pushed at all. The same misread hits a hand-written source on its first read, so a Windows path such as `path=C:\\` was enough. Both continuation tests now count the trailing backslash run and continue only on an odd count.
+- **properties**: A key containing an escaped `=` or `:` is read back correctly, so the parser can read its own output. `greeting:formal`, written as `greeting\:formal`, was split at the escaped colon so half the key was sent to the engine as the value and the real key never reached the target file; the rewrite path carried a second copy of the same pattern and truncated the key. Both now share one fragment that treats `\X` as a single key character, a key's own bytes are preserved when its value is rewritten, and an ordinary key still splits at its first separator (`a.b=x=y` → value `x=y`).
+- **properties**: Reconstruction escapes leading spaces in values (`\ `), which the value parser otherwise strips on the next read, so a translation beginning with a space no longer loses it on every sync. `escapeValue` also emits all UTF-16 code units of a character rather than only the high surrogate, so an emoji round-trips as a complete surrogate pair.
+- **toml**: A quoted key containing a dot is translated in place instead of being turned into a nested table. `"greeting.formal" = "Good day"` is one flat key, but the entry-line regex excluded quoted keys, so `reconstruct` passed the line through untranslated and appended a new `[greeting]` table — the source kept its English while the lockfile recorded the key translated and `sync status` read 100%. Quoted key segments are now matched with the logical dot-path derived through `TOML.parse` itself, the key is rewritten in place keeping its quoting style, and insertion writes `"greeting.formal" = …` rather than inventing a table (attached only where a segment carries a literal dot, so staleness is unchanged for every other key). TOML also now uses `assertDistinctKeys`, so a file holding both `"a.b" = …` and `[a] b = …` is refused rather than having one translation written over the other.
+- **toml**: A new key outside TOML's bare-key character set is written as a quoted key instead of invalid TOML. `${leaf} = value` and `[${section}]` were emitted unquoted, so a source key such as `with space` produced a document the next read refuses — and because the run that wrote the file is the run that broke it, every later sync refused the locale it had just created. Leaf keys and section-header components are now emitted bare where the character set allows and as quoted keys otherwise.
+- **toml**: Reconstruction escapes U+2028/U+2029 in double-quoted values, with a literal-string value gaining one falling back to double quotes. Written raw these broke the entry-line scan on the *next* sync, which re-appended the key as a duplicate and made the third sync fail to parse the file at all. Found by the property-based round-trip suite.
+- **toml**: Multi-line (`"""` / `'''`) values survive a sync — only the opening line was emitted verbatim, so body lines that looked like `key = "…"` were parsed as entries and deleted from the value while the never-marked key was re-appended at end of file, leaving a document that no longer parses. The whole block is now emitted verbatim and skipped, including the single-line `k = """text"""` form; multi-line values remain untranslated as documented.
+- **toml**: New keys are written into the section they belong to. They were appended at end of file using the full dotted path while a `[section]` header was still in scope, so `messages.newkey` parsed back as `messages.messages.newkey` and was re-appended on every subsequent run. Keys are now inserted inside their own section block, with a new `[section]` header added only when that section is absent.
+- **android**: A single-quoted `name` or `quantity` attribute is no longer invisible. `<string name='greeting'>` is well-formed XML and the scanners accepted either quote for every *other* attribute, so such an element was never extracted, never translated and never reported while `sync status` read 100% and the string shipped in the source language. All four scanners (`<string>`, `<plurals>`, `<item quantity=…>`, `<string-array>`) now capture the delimiter and exclude only the one in use, each element's quoting style is preserved on rewrite, and a following attribute is still not swallowed into the name.
+- **android**: A `<plurals>` element whose name looks like an array index (`x.0`, beside a `<string-array name="x">`) is no longer deleted — `reconstruct` decided what an entry was from the shape of its key, so with the entry's plural metadata stripped nothing claimed the element. A key that names a `<plurals>` element in the file is now treated as that element whatever shape its name has.
+- **android**: XML entities no longer compound on every sync run. `extract` never decoded entities and `escapeAndroid` replaced `&` last, so `Terms &amp; Conditions` became `&amp;amp;` after one run and `&amp;amp;amp;` after three. Entities are now decoded on extract via a single-pass decoder (so a literal `&amp;lt;` decodes to `&lt;`, not `<`) and `&` is escaped before `<`/`>`; a three-run identity sync is a fixed point.
+- **android**: A self-closing element (`<string name="x"/>`) is no longer deleted together with the element that follows it, a value whose CDATA body contains `</string>` is no longer truncated on extract, and plural `<item>` attributes are preserved when a translation is written back.
+- **android, xliff**: The key of an appended resource is guarded and escaped, not just its translation. Both new-resource append paths ran the control-character assertion on the translation and then interpolated the key straight into `<string name="…">` / `<trans-unit id="…">`, so a control byte produced a file no XML consumer can read plus a live terminal escape in `git diff`, and a key containing `&`, `<` or `"` broke the attribute outright. The key is now checked for control bytes (as are Android plural `quantity` values) and escaped for an attribute context, and `extract` entity-decodes attributes so such a key round-trips.
+- **xliff**: A `trans-unit` or `unit` id containing an apostrophe is read in full, so two units no longer collapse onto one key. The scanner excluded both quote characters from the value, so `id="label.don't"` truncated to `label.don` and one fetched translation was written into both units, shipping one string's translation under another's id — unreported, since XLIFF is exempt from `assertDistinctKeys`. The delimiter is now captured and the value excludes only that delimiter in both the 1.2 and 2.0 scanners.
+- **xliff**: The review state of a rewritten element is read and updated on the real attribute rather than on a `state=` sequence inside another attribute's value (`note="compare state='final' …"`), which made `extractNeedsReview` read the decoy and the rewrite corrupt it while the real state stayed attached to text the run had just replaced. Attributes are now walked as whole `name="value"` pairs, so an attribute merely *ending* in `state` (`xstate=`) is not mistaken for it either. Two sibling markers are handled at the same time: `approved="yes"` becomes `approved="no"`, and `state-qualifier` (1.2) / `subState` (2.0) are removed rather than rewritten. Every marker is left untouched when the run writes the same text it found.
+- **xliff**: Files carrying a `state` attribute are no longer mangled — the `<segment>` and `<target>` patterns required bare tags, so in 2.0 `extract` returned nothing and `reconstruct` then deleted every `<unit>`, and in 1.2 an existing `<target state="…">` was treated as absent so a second `<target>` was injected, yielding schema-invalid output holding the stale translation. Both elements now accept attributes and preserve them through a round trip. A CDATA section in a `<note>` between `<source>` and `<target>` is also no longer rejected; only CDATA inside `<source>`/`<target>` is unsupported.
+- **formats**: Android XML and XLIFF parsing is linear in file size — both matched elements with a lazy pattern, so every opening tag without a matching close rescanned the rest of the file and a 4 MiB resource file took minutes. Android reconstruct also no longer rescans the whole file once per dotted key to identify `<string-array>` members (2.7 s → 63 ms on a 3.6 MiB, 52,000-entry file).
+- **formats**: CRLF-authored resource files are no longer invisible to the tool. Line-based parsers split on `'\n'`, leaving a trailing `'\r'` that defeated their `$`-anchored patterns, so a Windows-authored `.po` extracted **zero** entries and `sync status` reported 0% coverage at exit 0 while `sync export` emitted an empty XLIFF; TOML instead appended duplicates until the file no longer parsed. PO, TOML, iOS `.strings` and Java `.properties` now all split on `/\r?\n/`.
+- **formats**: YAML files using merge keys (`<<: *anchor`) or aliases to anchored maps and sequences no longer fail at sync write-back with `Expected YAML collection` — extraction emitted paths through aliases that reconstruction could not apply. Aliased collections are translated at their anchor site and the references round-trip untouched.
+- **formats**: Translating a key in an Xcode String Catalog no longer destroys that key's plural `variations` — reconstruct replaced the locale's entire localization object with a single `stringUnit`, discarding per-category translations the parser never surfaces as entries. Existing `variations` are preserved alongside the updated `stringUnit`, and the `Localization` type declares the field.
+- **formats**: ARB (Flutter) files with a UTF-8 BOM are readable, matching the JSON parser, and an `.arb` key whose name collides with an `Object.prototype` member (`toString`, `valueOf`, `constructor`, `hasOwnProperty`, `isPrototypeOf`, `__proto__`) is no longer dropped from the file it was billed for — `key in data` reported inherited members, so on the second run those keys were discarded while the lockfile recorded them translated and no later run retried them. Insertion now tests `Object.hasOwn` and writes through the shared `setOwnMember` (moved to `utils/own-members.ts`).
+- **formats**: The JSON parser no longer pollutes `Object.prototype` via a `__proto__` key in a resource file, and round-trips prototype-named keys as ordinary data: membership is an own-property check and assignment goes through `Object.defineProperty`, so a key legitimately called `toString` translates like any other. The guard is now pinned by a test that fails if `defineProperty` is replaced with plain assignment.
+- **formats**: A Laravel PHP lang file that overflows `php-parser`'s unguarded recursion is skipped with a warning (`Skipping lang/en.php: nesting depth exhausted the stack while parsing …`) instead of ending the run with `Error: Maximum call stack size exceeded`.
+- **sync, translate**: A deeply nested JSON or YAML file no longer ends the whole run with `Maximum call stack size exceeded` — a 16 KB file of 8,000 nested arrays sits far below `sync.limits.max_file_bytes`, and in a sync the crash was worse than a crash, since work already translated and billed went unrecorded because the lockfile is written at the end. `sync.limits.max_depth` (default 32, ceiling 64) now applies to **any** parser that accepts one, via a new optional `withMaxDepth` on `FormatParser`, and always rather than only when the default was overridden; one file exceeding the cap is skipped with a warning naming the key path while the run finishes and records what it did. YAML is bounded differently, since its library blows the stack before any walker of ours runs: that parse diagnostic is recognised as a depth rejection, and a `RangeError` escaping any parser is caught at the same boundary. The direct `deepl translate <file>` path, which has no configured limit, gets a fixed ceiling of 100 levels.
+- **watch**: Two watched files with the same name no longer write one translation on top of the other. The output path was built from the basename alone, so every `doc.md` under the watched tree mapped to one `<output>/doc.es.md` and the last translation to finish silently replaced the others, at exit 0, with the count still reading `Translations: 2`. All **three** flattening paths — single-target, multi-target text, and multi-target structured (JSON/YAML) — now carry the source's directory relative to the watched path, and the loop guard still recognises a nested output directory as the CLI's own work rather than re-translating it.
+- **watch**: A slower translation of older content no longer overwrites a newer one and leaves the output permanently stale — the debounce bookkeeping was dropped when the timer fired rather than when the translation finished, so an edit arriving mid-translation started a second translation of the same file and both wrote the same path in API-completion order. Nothing recovers from that state on its own, since the file will not change again. A file is now translated one version at a time: an edit arriving during a translation queues exactly one re-translation, which starts only after the running one has written. Coalescing also collapses an edit storm (six edits during one slow translation: 7 API calls before, 2 after). Translations of *different* files still overlap up to `--concurrency`.
+- **watch**: A file changed during its own translation is no longer translated twice concurrently — the debounce entry was deleted in the translation's `finally`, removing whatever entry was current by then, usually a newer pending timer that could then not be cancelled. The entry is now cleared when the timer fires, and only if it is still the entry that timer registered.
+- **watch**: `--auto-commit` no longer loses most commits under an edit storm. `WatchService.onTranslate` was typed `=> void` and called without `await`, so the git work ran outside the translation's concurrency slot, unbounded, and parallel auto-commits fought over `.git/index.lock` — six files edited at once produced 6 translations, 2 commits and 4 auto-commit failures, with three output files left untracked and one staged but uncommitted, at exit 0. The callback may now return a promise and it is awaited, so a rejection reaches `onError`, and the git work is queued one `add`/`commit` pair at a time (same harness after: 6 translations, 6 commits, 0 failures). Translations of different files still run in parallel.
+- **watch**: `--auto-commit` and `--git-staged` act on the repository holding the files they name rather than the directory the CLI was started in. Every git invocation ran with no working directory of its own, so watching a path outside the current repository handed one repository's pathspecs to another's index: with the terminal elsewhere every commit failed with `is outside repository at …`, with the watched repository nested `git add` silently did nothing, and with the working directory in no repository the session printed `⚠️ Not a git repository, skipping auto-commit` untruthfully and exited 0. `--git-staged` failed silently inside a single repository with no unusual layout at all, since `git diff --cached --name-only` names files relative to the repository root and the result was resolved against the process working directory. Both flags now resolve their repository from the path they act on — `git rev-parse --show-toplevel` anchored on the output directory for the commit and on the watched path for the staged snapshot, with every staged name resolved against that repository's root — and output paths are made absolute before the working directory changes, so a relative `--output` still commits the file it wrote. No case ever committed into the wrong repository's history.
+- **watch**: `--git-staged` recognises a staged file when git and the watcher spell its path differently. The comparison key resolved symlinked ancestors but nothing else, so a case-insensitive volume (where `realpathSync` does not case-fold) or NFC versus NFD produced different keys for the very same inode and `watch --git-staged` translated **nothing**, silently, at exit 0. Where the file exists the key is now its device + inode pair (`lstat`, so a symlink stays a different file from its target); a path with no file yet falls back to the resolved string. The same two-spellings defect had a second site: the loop guard's warn-once bookkeeping compared unresolved paths, so a session whose output directory is reached through a symlink warned about a file the CLI had just written itself, naming two spellings of one directory. Both sites now compare a canonical key with symlinked ancestors resolved and the final component left alone; messages still show the path as the user spelled it. macOS reaches this with no symlink of the user's own, since `os.tmpdir()` is symlinked.
+- **watch**: `--auto-commit` no longer reports a session failure when there was nothing to commit — re-saving a file whose translated bytes are unchanged stages nothing, `git commit --only` then exits non-zero, and the undifferentiated `catch` counted that as a failure, exiting **12** although nothing went wrong. The staged state is now asked with `git diff --cached --quiet` rather than by matching git's "nothing to commit" wording, which a localized git translates, and a genuine failure is reported with git's own `stderr` instead of a bare exit-status message.
+- **watch**: A source file whose name carries a target-language segment is translated instead of being skipped for the whole session — `pricing.es.md` under `--to es` was dropped with no request, no output and not even a `📝 Change detected` line. The loop guard now also requires the file to be *inside* the output directory, which leaves the loop protection complete. In a same-directory layout a file the CLI did not write is still skipped, since the name is genuinely ambiguous there, but now says so once per file, naming the file and the output directory to move it out of; the CLI's own writes are skipped in silence.
+- **watch**: The loop guard no longer warns about the temp file the CLI is writing through. `atomicWriteFile` renames from a `<target>.tmp.<pid>.<random>` sibling, whose name carries the output file's, so the session told the user to move a file this process had already renamed away. Such a path is now recognised as an in-flight write and ignored before the output-file check; and, conversely, a real document named like a temp sibling is no longer skipped — the check is a membership test against the in-flight set, with the name pattern honoured only for a path that no longer exists.
+- **watch**: `deepl watch` debounces at the documented 500 ms and honours `watch.debounceMs`. The command forwarded a debounce only when `--debounce` was passed, so an omitted flag fell through to a third copy of the value at 300 ms while `--help`, the docs and the config schema all said 500, and the configured key was accepted by `deepl config set` but never read. Resolution is now flag, then `watch.debounceMs`, then a single exported default shared with the config schema. `deepl sync --watch` was already correct.
+- **watch**: `--glossary` without a source language now exits 6 before the watcher starts, instead of starting a session that fails on every file change with a raw server message — the worst place for this, since the operator saw the failure once per edit. The check runs before the glossary name is resolved, so it costs no API call, and it honours `defaults.sourceLang` as every other command does, including on a direct `WatchCommand.watch()` call, which previously refused a command the CLI accepted. `sync` needs no equivalent, taking its source language from the required `source_locale`.
+- **watch**: `filesWatched` statistics report the actual number of files under watch — seeded from the watcher's inventory once the initial scan completes and tracked on add/unlink — instead of always 0.
+- **translate**: The CLI's own internal placeholder tokens can no longer be written into your text. `restorePlaceholders` substituted every `__VAR_n__` it could find and left the rest alone, with nothing checking that the tokens the CLI injected came back — and re-casing an unfamiliar token is ordinary MT behaviour, so `__VAR_0__` returning as `__ Var_0 __` was printed, written to a file, or written into every file of a directory run, all at exit 0. All three paths now check the post-condition: `translate` exits 5 naming the variables it lost (`The translation lost the placeholder {username}. … Nothing was written.`) and a directory run fails only the affected files. The check runs **before** the cache write, and a poisoned entry from an earlier version is refused on read. `sync` is deliberately unchanged, since its validator already withholds and retries the key.
+- **translate**: A source string that literally contains the CLI's own placeholder token is no longer corrupted, and a genuinely lost token is no longer reported as intact. Tokens came from a plain counter, so text carrying a literal `__VAR_0__` could be handed the same token as a real `{name}` and `replaceAll` brought both back as `{name}` — which also made the loss check accept the literal copy as evidence the substituted token had survived. Tokens are now chosen to avoid any the source text already contains, for both the `__VAR_` and `__CODE_` families, and the low numbers are still used when the source carries none.
+- **translate**: Code preservation survives a fenced block overlapping an inline code span (`` ` ``` ``…``` ` ``), where the later pass wrapped an earlier pass's token and `--preserve-code` then refused the translation at exit 5, blaming the endpoint for a token the CLI had nested itself. Restore now expands tokens in reverse insertion order, so one pass unfolds every level, and the loss check counts a token as surviving when it sits inside a later span that itself survived — in the sync validator as well as the translate-path assert.
+- **translate/sync**: An empty string value in an i18n file is no longer mistaken for a failed translation. `translateBatch` skipped an empty text but left that slot `null`, the same value it uses for a failed request, so `deepl translate` printed a false `1 of 3 translations failed` and then crashed at exit 1 with no output file, `deepl sync` deleted the key and recorded it `failed` so every later run exited 12 forever, and an ICU message with an empty plural branch had the whole message withheld and its key dropped. Empty input now returns an empty translation with `billedCharacters: 0`, `translateBatch` is declared `(TranslationResult | null)[]` so the compiler forces the remaining failure case to be handled at each of the five call sites, `BatchTranslationService` records a missing per-index result as that file's failure, and the `N of M translations failed` warning counts only real failures.
+- **translate**: `--no-cache` is honoured for every structured i18n format — JSON, YAML, TOML, PO, XLIFF, Android XML, iOS `.strings`, `.xcstrings`, ARB, `.properties` and Laravel PHP — where it was accepted and silently ignored, so re-running the identical command with the flag sent **zero** requests and reproduced the previous output byte for byte, defeating the one remedy a user would reach for. `translateBatch` now takes the same `serviceOptions` shape as `translate()` and honours `skipCache` on both the read and the write, threaded through `translateFile`, `translateFileToMultiple` and `translateStringsInBatches` so single- and multi-target behave alike, and the bypass notice is emitted on the batch path. `sync` and `batch` expose no `--no-cache` and are unchanged.
+- **translate**: `--output <dir>` works for a single target language instead of failing with `EISDIR`, which the multi-target branch already honoured. The destination is now resolved once ahead of every branch, so `deepl translate t.md --to ko --output dir/` writes `dir/t.ko.md` for text files, structured files and documents alike; `dir` and `dir/` behave identically (the check is `statSync().isDirectory()`), a trailing slash creates the directory, a converted document is named by `--output-format`, and `--output -` and a non-existent path are unaffected.
+- **translate**: `deepl translate <file.json|.yaml>` has a size ceiling, so a huge locale file cannot exhaust memory mid-run — the structured route parsed whatever it was given while both sibling routes were already bounded (text at 100 KiB, documents at 30 MB), and the multi-target path parses a fresh copy per target language, up to `MULTI_TARGET_CONCURRENCY` (5) at once. The ceiling is 10 MiB, matching `HARD_MAX_SYNC_LIMITS.max_file_bytes`, and is checked with a `fs.stat` before the read at the one function both entry points funnel through, so an oversize file is never resident. The message names the file, its size and the limit and points at `deepl sync`; a directory run fails only that file. A 25 MB document is still accepted, since it is streamed to the API rather than parsed.
+- **translate**: A directory translation where every file failed exits 1, and a partial failure exits 12, matching `sync` — the summary reported `✓ Successful: 0 / ✗ Failed: N` and the command still looked like success. A run stopped by one request-level rejection also reports that rejection's own code: 6 for a refused `target_lang`, 4 for an exhausted quota, 2 for a refused key.
+- **translate**: A rejected language no longer costs one API round trip per batch — a two-letter typo reaches the API now that validation defers unknown codes, and a directory translation asked the same rejected question once per batch (200 files, 200 failing requests). An unsupported `target_lang`/`source_lang` is a property of the request, so the remaining batches now fail unsent, while a batch-specific error such as a rate limit still lets the run continue. The abort now also covers the per-file path (`.json`, `.yaml`, `.html`, `.srt`, `.xliff`) and not only plain-text batches, files never sent are reported as skipped rather than as failures carrying another batch's error, and the classifier checks the error class before the message so a 5xx quoting `target_lang` cannot abort a healthy run. A code the bundled snapshot does not list says so up front, before anything is sent or billed.
+- **translate**: File, directory and `--dry-run` runs make the same language checks as text runs, through one entry point rather than eight call sites in five files — `--to af --formality more` failed locally for text and reached the network for a file, and `--dry-run` reported both as runnable along with `--to 'not!!a!!lang'`. `--from` is validated too, and named as such (`Invalid source language code: "grman"`). Each mode passes only the flags it honours, so a document run still accepts `--model-type` (stripped after a warning) and a directory run still accepts `--glossary`; document mode no longer rejects the command over the flags it says it discards; the "deferring to the API" note is said once per code per run; an empty repeatable `--glossary` list no longer trips the glossary rejection; and a dry run lowercases `--to`/`--from` as a real run does.
+- **translate**: `--tag-handling-version` is honoured for files and directories, not only for text — the shared option mapping carried `--tag-handling` but not the version, so with v2 now pinned whenever tag handling is on, `deepl translate page.html --tag-handling html --tag-handling-version v1` silently sent v2.
+- **translate**: `ℹ️ Cache is disabled` and `ℹ️ Cache bypassed for this request (--no-cache)` are announced once per run rather than once per API request.
+- **translate**: The error raised for an unexpected API response points at this repository's issue tracker rather than an unrelated third-party account.
+- **write/correct**: `--format json` no longer inverts the `--check` verdict or corrupts the file `--fix` writes. `checkText` obtained the improved text by calling `improve()`, which renders a JSON document when the caller asked for one, so the diff behind the check compared the original text against that document: `write --check 'text' --format json` exited **8** claiming changes for any input, and `write file.txt --fix --format json` **overwrote the file with the JSON document** (recoverable only with `--backup`). `--diff --format json` likewise labelled a rendered JSON document as the improved text. The improved text is now produced without the presentation formatting, so the verdict, the change count and the bytes written no longer depend on the format the report was asked for; `--alternatives`, `--diff`, `--output` and `--in-place` are byte-identical under both formats.
+- **write**: `deepl write` runs from a published install — `diff` is imported at the top of the write command but was declared only under `devDependencies`, so every command that loaded the module failed with `Cannot find package 'diff'`. `--help` did not surface it, because the module loads lazily.
+- **write**: `--lang` and `--to` accept language codes in any casing and normalize them to the API's form, where they compared against a mixed-case list with an exact match and rejected the lowercase codes `deepl languages` prints and `translate --to` accepts.
+- **write**: The unsupported-style error links to the published docs URL instead of a `docs/API.md` path npm users do not have.
+- **api**: A `/v2/translate` or `/v2/write` response body of the wrong shape is refused instead of being carried into output. The bodies were typed by an interface that asserts nothing at runtime and checked only for truthiness and a length match, so `{"translations":"notarray"}` printed the literal text `undefined` into `--output`, `{"text":12345}` printed `12345`, an object printed `{ a: 1, b: [ 2, 3 ] }`, and `null` crashed at exit 1. All now exit 5 naming the field and the offending type (`Unexpected API response: "translations[0].text" must be a string, got number.`), with the bodies requested as `unknown` and the checks in a new `src/api/response-shape.ts`. `write`/`correct` had the identical hole and are fixed with it. Three distinctions: an absent or null `translations`/`improvements` field is not a type error and falls through to the callers' own "nothing came back" messages; in a batch every element is validated before any is used; and wrong-typed optional metadata (`billed_characters`, `detected_source_language`, `model_type_used`) is dropped rather than rejecting a translation that has already been billed.
+- **http**: A response the endpoint cuts off mid-body is reported as a network failure (exit 5) — `Network error: the API answered HTTP 200 but its response body did not arrive intact` — rather than as invalid input (exit 6), which told the operator to check input that was never the problem. The test is the status rather than the axios code, since a rejection carrying a 2xx response can only have failed while the body was read. 3xx, 4xx and 5xx keep their classification, the replay policy is deliberately unchanged (a 200 means the server may already have billed the request), and the client-side deadline path still restates its own aborts as `ETIMEDOUT`.
+- **api**: A client-side timeout exits 5 (network error) instead of 6 (invalid input), and an HTTP 401 maps to `AuthError` (exit 2) instead of falling through to 6 — classification substring-matched the message and missed axios's `timeout of 30000ms exceeded`, so CI that retries on 5 and hard-fails on 6 did exactly the wrong thing on a flaky network. Classification now branches on `error.code` and the absence of a response.
+- **api**: Non-idempotent POST requests are no longer re-submitted after a client-side timeout — a batch or document upload that outlived the 30 s timeout was silently re-sent up to three more times, each already accepted and billed server-side, with the worst case being duplicate admin API keys whose secret is returned only once. Automatic retry is restricted to GET, HEAD, PUT and DELETE, and a POST is replayed only on an error that proves the request never reached the server (`ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`). A 429 is still retried for every method, honouring `Retry-After`.
+- **api**: A blank or whitespace-only `Retry-After` header is treated as absent instead of collapsing 429 backoff into a tight retry loop — `Number('')` is `0`, which passed the finite check and, being a real number, kept the jitter-backoff fallback from engaging. An explicit `Retry-After: 0` is still honoured.
+- **api**: Retries run under an overall time budget rather than only a per-attempt timeout — twice the request timeout by default — so a never-responding server no longer holds a single command for two minutes. Honest `Retry-After` waits are not charged against the budget.
+- **api**: The document translation result endpoint is never retried, since the download is effectively single-use and a retry after a timeout could permanently lose an already-billed translation, and document transfers get their own larger timeout.
+- **api**: The Trace ID quoted in an error belongs to the request that failed rather than the client's last-seen response, so concurrent requests no longer cross-quote each other's. Errors already classified by the API client are no longer re-classified when a client wraps its own error handling — which could turn a validation error into a network error and drop its recovery hint — and the doubled `Network error: Network error:` prefix is gone.
+- **cache**: The translation cache keyed on too little and could serve the wrong text. `translationMemoryId`, `translationMemoryThreshold`, `--ignore-tags`, `--splitting-tags`, `--non-splitting-tags`, `--outline-detection` and `--preserve-formatting` were absent from the key, so `deepl translate "Hello" --to de` and the same command with `--translation-memory my-tm` collided — the second returned the cached non-TM translation and reported `cached: true` — and two runs differing only in `--ignore-tags` returned each other's output. `preserve_formatting` does show up in the text, since it suppresses sentence-boundary punctuation and case correction. **Every translation entry cached by an earlier version is retired** on first open via a cache schema bump rather than sitting unreachable until its 30-day TTL, so the first translation of any given text after upgrading is refetched.
+- **cache**: The size cap is actually enforced. The total is now read from `SELECT SUM(size)` rather than a process-local counter that drifted downward when an overwrite's eviction deleted the key being replaced (after which the cap stopped firing and the DB grew without bound), upward when `get()` deleted expired rows without decrementing, and negative when another process's rows were swept (disabling eviction for the process lifetime). Eviction deletes oldest rows in batches until enough space is freed instead of a one-shot estimate from the average row size, an entry larger than `maxSize` is skipped rather than wiping every other entry first, and the expired-entry sweep's throttle timer is seeded so the sweep runs on a process's first operation — it was seeded to construction time, so it never ran in any process shorter than 60 seconds. Repeated `getInstance()`/`close()` cycles no longer accumulate signal listeners until Node prints `MaxListenersExceededWarning`, and the docs now describe eviction as oldest-first, which is what the code has always done.
+- **cache**: Only genuine corruption (`SQLITE_CORRUPT` / `SQLITE_NOTADB`) triggers the rename-aside-and-recreate recovery. The constructor treated every unexpected error as corruption, so transient lock contention (`SQLITE_BUSY`) renamed a healthy cache aside and broke the other process's open transaction, and a DB written by a newer CLI version was destroyed instead of refused. Lock waits now go through `PRAGMA busy_timeout` (5 s) and anything that is not corruption propagates so the run degrades to uncached with a warning. When recovery does run, the WAL/SHM sidecars are copied before the failed handle is closed (SQLite deletes them on close) and named `<backup>-wal` / `<backup>-shm` so SQLite can actually recover the preserved data, and rename-aside backups are pruned to the most recent three.
+- **cache**: A cache backend that fails to load is no longer misclassified as database corruption and quarantined — the catch-all renamed a healthy `cache.db` aside and recreated it empty, verified on a 2,646-entry cache that passed `integrity_check`. Load failures now leave the database and its `-wal`/`-shm` sidecars untouched: `deepl translate` and `deepl write` degrade to running without a cache (one warning per process, exit 0) while `deepl cache …` subcommands, which cannot run cacheless, fail with an actionable error.
+- **cache**: `deepl cache enable` / `deepl cache disable` persist `cache.enabled` to the config file. Both reported success but only flipped an in-memory flag in a process that exited immediately, so the state reverted instantly; `deepl cache stats` likewise read a process-local flag that always initialized to enabled and now reports the persisted state.
+- **cli**: Subcommand parse errors (unknown subcommand, unknown option, invalid choice, missing argument) exit 6 as documented instead of 1 ("CLI crashed"). Top-level parse errors already did; the mapping is now uniform.
+- **cli, cache**: Interrupting a command no longer reports success or leaks the sync process lock. `CacheService`'s `SIGINT` handler called `process.exit(0)`, and because the cache singleton is constructed during service setup that handler ran before the sync engine's own — so `deepl sync` interrupted with Ctrl-C exited **0** and left `.deepl-sync.lock.pidfile` behind. The cache handler now only closes the database, and termination belongs to the CLI entry point, which defers the exit so every other listener's cleanup runs first (verified as exit 130 with the lock released). Commands that own their shutdown, such as `sync --watch`, opt out and still exit 0.
+- **cli**: The remediation for a missing API key survives `--quiet` — it was emitted as a warning, which quiet mode suppresses entirely, leaving only `Error: API key not set`, and `docs/API.md` now describes the actual behaviour. The non-TTY `--format table` fallback notice carries the documented `WARN` prefix at all six call sites, and shell completions and the did-you-mean suggester no longer offer hidden internal commands — the suggester knows aliases and prefers a prefix match (`deepl tr` → `translate`), and `--version` is no longer duplicated in the bash and zsh candidate lists.
+- **cli**: The global `--timeout` / `--max-retries` flags also apply to the API-key validation requests made by `deepl init` and `deepl auth set-key`, which always used the 30 s default.
+- **logger**: A short credential value no longer corrupts every diagnostic message. The redactor's last step substring-replaced the literal credential with no length floor or token boundary, so `DEEPL_API_KEY=k` turned four lines of a single real run into nonsense (`Warning: sending your DeepL API [REDACTED]ey to …`, `/Users/[REDACTED]wey/…`) at the moment the user most needs to read them. A literal value is now only replaced when it is at least 8 characters; below that, the auth-header and `token=`/`api_key=` query-parameter patterns still apply, so nothing shaped like a credential in transit goes unredacted. A token-boundary rule was rejected as it would *miss* a real key printed before a word character.
+- **config**: Language values are normalized on load, not only by `config set`, so a file written or hand-edited with uppercase codes no longer keys two cache entries for one request (`DE` in config plus `--from de`). `deepl config set defaults.sourceLang DE` is accepted where the validator matched a lowercase-only pattern and refused the one casing that is certainly valid; values are lowercased before validation and stored normalized. A code the bundled snapshot does not list is still accepted but now warns at the point of entry rather than failing on every later command, and that note is limited to the write path — shared with the loader it printed on every invocation, `deepl --version` included.
+- **config**: `config delete` and the config read paths can no longer walk or mutate the prototype chain — `__proto__`, `constructor` and `prototype` segments are rejected, completing the `config set` hardening.
+- **init**: `deepl init` with stdin at end-of-file exits 6 with the documented non-interactive message instead of starting to prompt and then exiting 1 with a Node `unsettled top-level await` warning. Reached by `docker run` without `-it`, CI, and piped invocations: the command checked only `--no-input`, where the sibling guard in `write --interactive` also checks whether stdin is a terminal.
 - **init/write/sync**: `@inquirer/prompts` is declared as a dependency. It is imported at runtime by `init`, `write --interactive` and `sync init` while only the unused `inquirer` was declared, so it resolved through npm's hoisting: under a strict layout (pnpm, `--install-strategy=nested`) those commands failed with `ERR_MODULE_NOT_FOUND`, and under npm the prompt that reads the API key bound to whatever major another dependent happened to hoist.
-
-- **init**: `deepl init` with stdin at end-of-file now exits 6 with the documented non-interactive message, instead of starting to prompt and then exiting 1 with a Node `unsettled top-level await` warning. Reached by `docker run` without `-it`, CI, and piped invocations. The command checked only `--no-input`, where the sibling guard in `write --interactive` also checks whether stdin is a terminal; the existing test covered only the `--no-input` variant, which already worked.
-
-- **write**: `--lang` and `--to` accept language codes in any casing and normalize them to the API's form. They previously compared against a mixed-case list with an exact match, rejecting the lowercase codes `deepl languages` prints and `translate --to` accepts — so the CLI's own discovery output was unusable with the command documented as consistent with `translate`.
-
-- **translate**: The error raised for an unexpected API response pointed at a bug tracker under an unrelated third-party account rather than this repository's.
-
-- **cli**: Shell completions and the did-you-mean suggester no longer offer hidden internal commands, and the suggester now knows about aliases and prefers a prefix match — `deepl tr` suggests `translate` rather than `tm`. `--version` is also no longer duplicated in the bash and zsh candidate lists.
-
-- **cli**: The remediation for a missing API key survives `--quiet`. It was emitted as a warning, which quiet mode suppresses entirely, leaving only `Error: API key not set`; `docs/API.md` claimed quiet mode still showed such warnings and now describes the actual behaviour.
-
-- **cache**: The size cap is now actually enforced. Size accounting previously lived in a process-local counter that drifted in both directions — downward when an overwrite's eviction deleted the very key being replaced (after which the cap stopped firing and the DB grew without bound), upward when `get()` deleted expired rows without decrementing (evicting entries that didn't need evicting), and negative when a concurrent process's rows were swept (disabling eviction for the process lifetime). The total is now always read from `SELECT SUM(size)`. Eviction now deletes oldest rows in batches until enough space is actually freed, instead of a one-shot estimate from the average row size that under-evicted whenever sizes were skewed. An entry larger than `maxSize` itself is skipped instead of stored — previously it wiped every other entry first (eviction deleted all rows and inserted the oversized one anyway), leaving a cache that re-wiped on every subsequent write. The expired-entry sweep's throttle timer is seeded so the sweep runs on a process's first operation; it was seeded to construction time, so it never ran in any process shorter than 60 seconds — essentially every CLI invocation. Repeated `getInstance()`/`close()` cycles no longer accumulate process signal listeners until Node prints `MaxListenersExceededWarning` to stderr. Docs now describe eviction as oldest-first rather than LRU, which is what the code has always done (`timestamp` is only written on `set()`).
-
-- **cache**: Only genuine corruption (`SQLITE_CORRUPT` / `SQLITE_NOTADB`) now triggers the rename-aside-and-recreate recovery. The constructor previously treated *every* unexpected error as corruption, so transient lock contention (`SQLITE_BUSY` — e.g. two concurrent invocations against a cache on a filesystem where WAL cannot be enabled) renamed a healthy cache aside, recreated it empty, and broke the other process's open transaction; and a DB written by a newer CLI version was destroyed instead of refused, defeating the schema check's stated purpose. Lock waits now go through `PRAGMA busy_timeout` (5s), and everything that isn't corruption propagates so the CLI degrades to an uncached run with a warning. When recovery does run, the backup's WAL/SHM sidecars are copied before the failed handle is closed (SQLite deletes them on close) and named `<backup>-wal` / `<backup>-shm` so SQLite can actually recover the preserved data — the old naming (`<original>-wal<suffix>`) orphaned the WAL, silently losing any rows not yet checkpointed. Rename-aside backups are pruned to the most recent three so repeated corruption cannot fill the disk.
-
-- **sync**: `deepl sync pull` no longer discards existing translations for keys named after `Object.prototype` members. `sanitizePullKeysResponse` built its result on a plain object, and callers test membership with `pulledKeys[key] !== undefined` / `??` — so for a source key called `toString`, `constructor`, `valueOf`, `hasOwnProperty`, or `__proto__`, the lookup returned an inherited *function*, which is neither `undefined` nor nullish. The entry was therefore treated as a freshly approved TMS translation and won over the real one, then vanished from the file when `JSON.stringify` dropped the function value — while the lockfile recorded it as `translated` / `human_reviewed`, so no later sync repaired it. The accumulator now has a null prototype.
-
-- **sync**: ICU plural/select messages with text around the block are now preserved. The detection pattern was anchored to the start of the string, so `You have {count, plural, one {# item} other {# items}} in your cart.` — arguably the most common real shape — was not recognised as ICU at all and the raw syntax went to the engine as prose. Confirmed against the live API: it returned `{count, Plural, ein {…} weiteres {…}}`, translating the format keyword *and* both selectors, leaving a message with no valid format type and no `other` fallback. Detection now matches an ICU block anywhere in the string, and the prose on either side becomes a translatable segment instead of being silently dropped from the reassembled output (trailing text was previously lost outright). Re-verified end to end after the fix: `plural`, `one`, `other`, and the `count` argument all survive while the surrounding prose is translated. Note this affects `deepl sync`, the only path with ICU preservation; `deepl translate` on a raw ICU string is unchanged.
-
-- **sync**: ICU structural damage is now detected instead of reported as passing. `checkIcuBrackets` compared only brace counts and nesting depth, which are identical when the engine translates the keyword, a selector, or the argument name — so `fail_on_error` never tripped on a message that no longer renders. Validation now compares the parsed argument/format-type headers and the selector keyword sets, while tolerating reordered selectors (order is not meaningful in ICU).
-
-- **sync**: A failed ICU segment no longer yields a part-English message reported as a successful translation — the message is marked failed and retried. `reassemble` also throws on a translation-count mismatch rather than filling the gaps with empty strings, which produced empty plural branches that render nothing for that category.
-
-- **sync**: A locale that failed completely now fails the run. The check used `.every()`, so a run was only unsuccessful when *every* locale failed — with two locales where one succeeded and the other failed outright, the run reported success and exited 0, leaving the failed locale's file absent while CI went green. It now matches the documented contract for exit 12 (`docs/API.md`: "completed with at least one failed locale"): a locale that translated nothing and recorded failures fails the run, while a locale that partly succeeded still reports its per-key failures in the summary without failing the run, and a locale with nothing to do is simply up to date. `--auto-commit` additionally now refuses to commit an unsuccessful sync — it previously checked only drift and dry-run, so it would happily commit a state with a missing locale file.
-
-- **sync**: Staleness is now judged per target locale, so `--frozen` can detect a locale that has fallen behind. `computeDiff` compared only the entry-level `source_hash`, so once one locale was re-synced after a source edit, the entry hash matched again and every *other* locale reported `current` **forever** — no API call was ever issued for them, `sync status` showed 100%, and the CI gate whose entire purpose is catching out-of-date translations could not see it. A key is now stale if any configured target locale's stored hash lags the source or its last attempt failed. Relatedly, the failure check was previously unscoped (`Object.values(translations).some(failed)`), so **one** locale's failure marked the key stale for **all** locales and the next run re-translated locales that were already correct — overwriting human-edited files. Locales absent from `target_locales` are ignored, so a leftover entry for a de-configured locale no longer flags a key indefinitely, and a locale with no entry at all is still treated as a new-locale backfill (counted as new keys) rather than as drift. `sync status` computes the same per-locale determination inline instead of inheriting the shared source-level status.
-
-- **BREAKING — sync**: Untranslated source text is never written into a target locale file and recorded as a translation. When a key's source was unchanged, the lockfile claimed the locale already had a translation, and the target file supplied none — because the file had been deleted to force regeneration, or held an empty value — the source string was written through as the "translation" and the lockfile kept its `translated` status, so **no later run ever corrected it**: the locale file silently retained English and the run reported success. Such a key is now re-translated, and a verbose message explains why. A translation that is present but deliberately empty is preserved rather than treated as missing. **Behaviour change to be aware of**: deleting a target locale file now causes its keys to be translated again (billed) instead of being backfilled with English — which is the point, but it does mean a deleted file costs a real re-translation. Two existing tests asserted the old fallback; neither the CHANGELOG nor `docs/SYNC.md` documented it, and both arrived inside a bulk development commit rather than as a deliberate decision, so they have been updated to the corrected contract.
-
-- **api**: A blank `Retry-After` header no longer collapses 429 backoff into a tight retry loop. `Number('')` is `0`, which passed the finite check and returned a 0 ms delay — and because `0` is a real number the jitter-backoff fallback never engaged, so all retries fired back-to-back at an endpoint that was already rate-limiting the client. A blank or whitespace-only header is now treated as absent; an explicit `Retry-After: 0` is still honoured.
-
-- **watch**: A file changed during its own translation is no longer translated twice concurrently. The debounce entry was deleted in the translation's `finally` rather than when the timer fired, so it removed whatever entry was current by then — usually a *newer* pending timer for the same file, which then could not be cancelled. A subsequent change therefore started a second translation racing to write the same output path, doubling API spend with a nondeterministic winner. The entry is now cleared when the timer fires, and only if it is still the entry that timer registered.
-
-- **sync**: An invalid `--concurrency` no longer makes a sync silently do nothing while reporting success. `--concurrency` was parsed with a bare `parseInt`, so `abc` produced `NaN`, which survives `??` defaulting; `Math.min(NaN, n)` is `NaN` and `Array.from({length: NaN})` is empty, so **zero** workers were started and `mapWithConcurrency` returned an empty result having translated nothing and thrown nothing. Verified end-to-end: with a deliberately invalid API key, `deepl sync` correctly failed with exit 2 while `--concurrency 0`, `--concurrency abc`, and `--concurrency -3` each printed `Sync complete` with exit 0 and no output file. The flag (and `--debounce`) now reject non-positive and non-numeric values at the boundary, `sync.concurrency` is validated in the config like `tms.push_concurrency` already was, and `mapWithConcurrency` clamps to at least one worker as defence in depth.
-
-- **cache/cli**: Interrupting a command no longer reports success or leaks the sync process lock. `CacheService`'s `SIGINT` handler called `process.exit(0)`, and because the cache singleton is constructed during service setup that handler ran *before* the sync engine's own — so `deepl sync` interrupted with Ctrl-C exited **0** (so `deepl sync && git commit` would commit a half-finished sync) and left `.deepl-sync.lock.pidfile` behind. The cache handler now only closes the database, and termination belongs to the CLI entry point, which defers the exit so every other listener's cleanup runs first: verified end-to-end as exit 130 with the lock released. Commands that own their shutdown — `sync --watch`, for which SIGTERM is the normal stop signal — opt out and still exit 0.
-
-- **formats**: TOML multi-line (`"""` / `'''`) values survive a sync. Only the opening line was emitted verbatim, so body lines that happened to look like `key = "…"` were parsed as entries and **deleted from the value**, and the multi-line key — never marked as used — was re-appended at end of file, leaving a document that no longer parses (`trying to redefine an already defined table or value`). The whole block is now emitted verbatim and skipped, including the single-line `k = """text"""` form. Multi-line values remain untranslated, which is the existing documented behaviour.
-
-- **formats**: Translating a key in an Xcode String Catalog no longer destroys that key's plural `variations`. Reconstruct replaced the locale's entire localization object with a single `stringUnit`, discarding per-category translations the parser never surfaces as entries — so they could not be recovered. Existing `variations` are now preserved alongside the updated `stringUnit`, and the `Localization` type declares the field so this cannot silently recur.
-
-- **formats**: ARB (Flutter) files with a UTF-8 BOM are readable. `JSON.parse` rejects a leading BOM, so a BOM-prefixed `.arb` file failed outright; the BOM is now stripped on extract and reconstruct, matching the JSON parser's existing behaviour.
-
-- **formats**: A translated Android string can no longer break out of its CDATA section. `escapeForReconstruct` wrapped the translation in `<![CDATA[…]]>` with no escaping, so a value containing `]]>` closed the section early and the remainder was parsed as XML — allowing extra `<string>` elements into a generated resource file. This was reachable without a malicious API response, because on translation failure the source string is written through verbatim and the source file is used as the template when the target locale file does not exist yet. Occurrences of `]]>` are now split across adjacent CDATA sections, which keeps the text literal, and extract concatenates adjacent sections so such values round-trip unchanged.
-
-- **formats**: New TOML keys are written into the section they belong to. They were appended at end of file using the full dotted path while a `[section]` header was still in scope, so `messages.newkey` parsed back as `messages.messages.newkey` — and because the intended key was therefore still missing, it was re-appended on every subsequent run. Keys are now inserted inside their own section block, with a new `[section]` header added only when that section is absent.
-
-- **formats**: Android XML entities no longer compound on every sync run. `extract` never decoded XML entities, and `escapeAndroid` replaced `&` *last* — so it re-escaped its own output. `Terms &amp; Conditions` became `&amp;amp;` after one run and `&amp;amp;amp;` after three, verified. Entities are now decoded on extract via a single-pass decoder (so a literal `&amp;lt;` decodes to `&lt;`, not to `<`), and `&` is escaped before `<`/`>`; a three-run identity sync is now a fixed point.
-
-- **formats**: Emoji and other astral characters survive `.properties` files. `escapeValue` iterated by code point but escaped with `charCodeAt(0)`, emitting only the high surrogate — `Hello 😀 world` was written as `Hello \ud83d world`, which cannot be decoded back. All UTF-16 code units of a character are now emitted, so an emoji round-trips as a complete surrogate pair.
-
-- **formats**: XLIFF files carrying a `state` attribute are no longer mangled. `state` is a standard attribute that every CAT tool writes, but the `<segment>` and `<target>` patterns required bare tags. For XLIFF 2.0 this meant `extract` returned nothing and `reconstruct` then **deleted every `<unit>`**; for XLIFF 1.2 an existing `<target state="…">` was treated as absent, so a second `<target>` was injected, yielding schema-invalid output that retained the stale translation. Both elements now accept attributes and preserve them through a round-trip.
-
-- **formats**: CRLF-authored resource files are no longer invisible to the tool. Line-based parsers split on `'\n'`, leaving a trailing `'\r'` that defeated their `$`-anchored patterns: a Windows-authored `.po` file extracted **zero** entries, so `deepl sync status` reported `totalKeys: 0` and 0% coverage with exit 0, and `sync export` emitted an empty XLIFF. TOML was affected differently — reconstruct failed to match existing keys and appended duplicates, producing a file that no longer parses (`trying to redefine an already defined table or value`). All line-based parsers (PO, TOML, iOS `.strings`, Java `.properties`) now split on `/\r?\n/`; the latter two already tolerated CRLF, and the change makes that explicit rather than incidental.
-
-- **glossary**: A glossary term named after an `Object.prototype` member is no longer silently dropped or misreported. `tsvToEntries` accumulated into a plain object and tested for duplicates with `entries[source] !== undefined`, so `toString` (and friends) triggered a spurious "Duplicate source" warning, and a `__proto__` term was swallowed by the prototype setter instead of being stored. Genuine duplicate detection is unchanged.
-
-- **sync**: A lockfile entry whose i18n key is named `__proto__` no longer vanishes on every write — the key-sorting JSON replacer accumulated into a plain object, where that assignment invokes the prototype setter. Auto-glossary term extraction, which is keyed by untrusted source strings, was fixed the same way.
-
-- **formats**: The JSON parser no longer pollutes `Object.prototype` via a `__proto__` key in a resource file, and now round-trips prototype-named keys as ordinary data. `hasKey` used `part in record`, which reports inherited members, and `setKeyWithParts` assigned with `current[part] = …`, where `current['__proto__'] = {}` invokes the prototype setter instead of creating a property. Membership is now an own-property check, and assignment goes through `Object.defineProperty`, so a key legitimately called `toString` translates like any other.
-
-- **hooks**: Generated git hooks no longer emit a broken install instruction. The `pre-push` hook template told users to globally install the unpublished `deepl-cli` name — which fails with `ENOVERSIONS` — and now points at `@deepl/cli`. Reported by **@maa-xx** in #70, who correctly diagnosed that the documentation instructed readers to install a package that does not resolve; their docs fix was superseded by actually publishing the package, but this source-level occurrence was the one their PR missed and is now guarded by a regression test asserting generated hook output never references an unpublished package name.
-
-- **cache**: A cache backend that fails to load (e.g. `better-sqlite3` ABI mismatch after a Node major upgrade, `ERR_DLOPEN_FAILED`) is no longer misclassified as database corruption. Previously the constructor's catch-all renamed the user's healthy `cache.db` to `cache.db.corrupt-<timestamp>` and recreated an empty database — verified to quarantine a 2,646-entry cache that passed `integrity_check`. Native-module load failures now leave the database and its `-wal`/`-shm` sidecars untouched; genuine corruption still triggers the rename-aside recovery. `deepl translate` and `deepl write` degrade to running without a cache (single warning per process, exit code 0) instead of crashing, since the cache backend is loaded lazily behind a warn-once latch; `deepl cache …` subcommands, which cannot run cacheless, fail with an actionable error suggesting a reinstall or matching Node version.
-
-- **sync**: `deepl sync --frozen` now reports an accurate key count when drift is caused by a newly-added target locale. Previously the message read `Sync drift detected: 0 new, 0 stale keys.` because the frozen branch in `processBucket` short-circuited before promoting current-status keys missing a target-locale translation into `newKeys` — even though `--dry-run` against the same state correctly reported the backfill count. The drift exit code (10) is unchanged. The drift message now also surfaces `deletedKeys` and only mentions nonzero categories, mirroring the success-path summary format.
-
-- **cache**: `deepl cache enable` / `deepl cache disable` now persist `cache.enabled` to the config file. Both reported success but only flipped an in-memory flag in a process that exited immediately, so the state reverted instantly and subsequent translations kept using the cache after it had been disabled. `deepl cache stats` likewise read a process-local flag that always initialized to enabled, so the status line could never show `disabled` — not even after `deepl config set cache.enabled false`; it now reports the persisted state.
-
-- **sync**: Subcommands now honor `--locale`. Commander bound the flag to the parent `sync` command even when it trailed the subcommand name, so `sync status --locale de` listed every configured locale and `sync export --locale de` emitted XLIFF for all of them. Affects `status`, `validate`, and `export`.
-
-- **sync**: Subcommands now honor `--sync-config`. The flag was silently ignored and the auto-detected `.deepl-sync.yaml` used instead, so `sync validate --sync-config /missing.yaml` exited 0. Affects `status`, `validate`, `export`, `audit`, `resolve`, `push`, and `pull`.
-
-- **sync**: A `--locale` value that is not in `target_locales` now exits with a `ConfigError` (exit 7) naming the offending and configured locales, as documented. Previously `sync --locale <typo>` exited 0 reporting success while translating nothing, which made a typo'd locale in CI report green.
-
-- **sync**: `deepl sync init --sync-config <path>` now writes the config at that path and checks the already-exists guard against it, instead of always using the current directory. `.deepl-sync.yaml` is also written atomically, so an interrupted run cannot leave a truncated config behind.
-
-- **formats**: Android XML and XLIFF parsing is now linear in file size. Both parsers matched elements with a lazy `([\s\S]*?)` pattern, so every opening tag without a matching close rescanned the rest of the file; a 4 MiB resource file took minutes to parse. Android reconstruct also rescanned the whole file once per dotted key to identify `<string-array>` members (2.7 s → 63 ms on a 3.6 MiB, 52,000-entry file).
-
-- **formats**: Android XML self-closing elements (`<string name="x"/>`) are no longer deleted together with the element that follows them.
-
-- **formats**: Android XML values whose CDATA body contains `</string>` are no longer truncated on extract, and plural `<item>` attributes are preserved when a translation is written back.
-
-- **formats**: XLIFF files with a CDATA section in a `<note>` between `<source>` and `<target>` are no longer rejected; only CDATA inside `<source>` / `<target>` is unsupported.
-
-- **hooks**: `deepl hooks install` now resolves the hooks directory git actually reads (`git rev-parse --git-path hooks`), so it honours `core.hooksPath` (husky) and works inside linked worktrees and submodules where `.git` is a pointer file. Previously it reported success while writing a hook git never ran, and crashed with a raw `ENOTDIR` on worktrees and submodules.
-
-- **hooks**: `deepl hooks install` no longer overwrites an existing hook backup. A repeat install writes to the next free `.backup` slot, and the install output now prints the hook path and the backup path. `findGitRoot` also no longer loops forever when given a relative start path.
-
-- **sync**: Auto-glossary sync (`translation.glossary: auto`) skips terms whose source or translation is empty or contains a tab, carriage return, or newline. Such terms were uploaded as corrupted or outright wrong glossary entries, which DeepL then applied to live translations. An unchanged dictionary is no longer re-uploaded on every run (entries were compared against a lossy TSV round trip that could never compare equal), and a glossary failure for one locale no longer ends glossary sync for the remaining locales — the warning now names the locale, glossary, and cause.
-
-- **glossary**: `deepl glossary add-entry` / `update-entry` reject terms containing a tab, carriage return, or newline instead of shifting every following column of the uploaded dictionary, and glossary import picks the TSV or CSV dialect once per file, so a quoted CSV field containing a tab is no longer split into garbage columns.
-
-- **sync**: `deepl sync audit` no longer uses the lock file's source hash as a stand-in for a translation. Divergent translations were reported as consistent and identical ones as an inconsistency displaying a hex hash. Targets that cannot be read are now listed separately as missing — a new additive `missingTargets` field in the `sync audit --format json` output.
-
-- **sync**: TMS request URLs are built with the URL API: a trailing slash on `server:` no longer produces a doubled separator, a base path is preserved, and a URL with a query string or fragment is rejected instead of silently truncating the API path. TMS timeouts now exit with the network-error code (5) instead of 1, TMS error messages redact credentials embedded in the server URL, and `deepl sync pull` enforces a 32 MiB cap on the response body while reading it, instead of after the whole payload had been parsed.
-
-- **api**: Non-idempotent POST requests are no longer re-submitted after a client-side timeout. Every failure short of a 4xx reached the retry loop for all HTTP methods, so a batch or document upload that outlived the 30 s timeout was silently re-sent up to three more times — each already accepted and billed server-side (confirmed with server-side request counts: 4 per timed-out translate and upload), with the worst case being duplicate admin API keys whose secret is returned only once. Automatic retry is now restricted to idempotent methods (GET, HEAD, PUT, DELETE); a POST is replayed only on an error that proves the request never reached the server (`ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`). A 429 is still retried for every method, honoring `Retry-After`.
-
-- **api**: A client-side timeout now exits 5 (network error) instead of 6 (invalid input), matching the documented exit-code contract. Error classification substring-matched the message and missed axios's `timeout of 30000ms exceeded` (`ECONNABORTED` and `ERR_CANCELED` were absent entirely), falling through to `ValidationError` — so CI that retries on 5 and hard-fails on 6 did exactly the wrong thing on a flaky network. Classification now branches on `error.code` and the absence of a response. An HTTP 401 is likewise mapped to `AuthError` (exit 2) instead of falling through to exit 6.
-
-- **api**: Retries run under an overall time budget rather than only a per-attempt timeout — twice the request timeout by default — so a never-responding server no longer holds a single command for two minutes (measured 125 s before). Honest `Retry-After` waits are not charged against the budget.
-
-- **api**: The Trace ID quoted in an error message now belongs to the request that failed rather than the client's last-seen response, so concurrent requests no longer cross-quote each other's Trace IDs.
-
-- **api**: Errors already classified by the API client are no longer re-classified when a client wraps its own error handling, which could turn a validation error into a network error and drop its recovery hint. Error messages also no longer print a doubled `Network error: Network error:` prefix.
-
-- **api**: The document translation result endpoint is never retried — the download is effectively single-use, so a retry after a timeout on a large file could permanently lose an already-billed translation — and document transfers get their own larger timeout.
-
-- **voice**: `deepl voice` now actually reconnects after a transport failure. The socket `error` handler marked the stream ended before the `close` event that always follows arrived, so the reconnect path (up to 3 attempts, `--reconnect` on by default) was unreachable for a real network drop — only a clean remote close ever reconnected. A reconnect that exhausts its attempts now closes the audio input instead of leaving the stream generator awaiting forever.
-
-- **formats**: YAML files using merge keys (`<<: *anchor`) or aliases to anchored maps and sequences no longer fail at sync write-back with `Expected YAML collection`. Extraction previously emitted paths through aliases that reconstruction could not apply; aliased collections are now translated at their anchor site and the references round-trip untouched.
-
-- **sync**: ICU plural messages using `offset:N` and messages with single-quote-escaped braces (`'{'`, `'}'`, `''` for a literal apostrophe, `'#'` in plural context) are now recognized and preserved instead of falling back to raw machine translation, which demonstrably corrupts ICU keywords and selectors. `sync validate` placeholder checking is also ICU-aware: plural/select branch braces are treated as structure, eliminating spurious `Extra placeholders in translation` warnings for translated branch bodies.
-
-- **sync**: Template literals containing regex metacharacters in scanned source code (e.g. `` t(`item(${i}`) ``) no longer abort context resolution with a raw `SyntaxError` or silently mismatch keys — all metacharacters are escaped before the scan pattern is compiled.
-
-- **watch**: `filesWatched` statistics now report the actual number of files under watch — seeded from the watcher's inventory once the initial scan completes and tracked live on add/unlink. It was previously never incremented and always reported 0.
-
-- **cli**: The global `--timeout`/`--max-retries` flags now also apply to the API-key validation requests made by `deepl init` and `deepl auth set-key`, which previously always used the 30 s default.
-
-- **utils**: Atomic file writes preserve the target's existing permissions instead of resetting them to the umask default — e.g. `deepl write --fix` on a `0600` secrets file no longer leaves it world-readable at `0644`.
-
-- **docs**: README translate examples no longer show a `Translation (XX):` label the CLI never emits; corrected `--model-type` (no CLI default), `--config` precedence (replaces the config file only; the cache path is unaffected), unknown-command and `deepl detect` sample output, and the nonexistent 10 MB PDF cap (the document limit is 30 MB uniformly). README now covers `deepl sync`, `deepl tm`, and all nine `style-rules` subcommands, with dead in-page anchors repaired and `docs/SYNC.md` listed under Documentation.
-
-- **docs**: TROUBLESHOOTING's exit-code table gains codes 10–12 (SyncDrift, SyncConflict, PartialFailure) and its environment-variable table gains `TMS_API_KEY`, `TMS_TOKEN`, `FORCE_COLOR`, `TERM`; sync JSON-contract stability promises are rescoped from "1.x" to "within a major version"; the GitHub Actions recipes in docs/SYNC.md pin Node 24; CONTRIBUTING no longer cites Zod (validation is commander `Option.choices()` plus hand-written validators); examples/README no longer references a nonexistent `sample-files/` directory.
-
-- **cli**: Subcommand parse errors (unknown subcommand, unknown option, invalid choice, missing argument) exit 6 (invalid input) as documented, instead of 1 ("CLI crashed"). Top-level parse errors already exited 6; the mapping is now uniform across all subcommands, so CI scripts following the documented exit-code table no longer misread a typo as a crash.
-
-- **usage**: Text and table output no longer report duration-billed products (e.g. speech-to-text minutes) as zero characters — duration billing units are recognized, rendered in h/m/s as documented, and product names print in the documented snake_case. `--format json` was already correct and is unchanged.
-
-- **admin**: An entitlement failure (valid key without admin scope) no longer suggests re-running `deepl init` / `auth set-key` — the suggestion now explains that the admin API requires an administrator API key. Exit code and classification are unchanged.
-
-- **cli**: The non-TTY `--format table` fallback notice carries the documented `WARN` prefix at all six call sites, matching `sync resolve`'s existing convention.
-
-- **glossary**: Scoped commands (`show`, `entries`, `delete`) no longer emit an unrelated org glossary's "empty dictionaries" warning during name resolution — the warning appears only when the glossary actually operated on is affected.
-
-- **sync**: `sync resolve` prints each parse-error fallback warning once (relative path) instead of twice.
-
-- **write**: The unsupported-style error links to the published docs URL instead of a `docs/API.md` path npm users don't have.
-
-- **config**: `config delete` and the config read paths can no longer walk or mutate the prototype chain — `__proto__`/`constructor`/`prototype` segments are rejected, completing the `config set` hardening.
-
-- **sync**: `deepl sync push`/`pull` no longer send the TMS credential and translated strings to a host the destination-trust gate never approved. A `tms.server` whose path begins with `//` — `https://approved.example.com//evil.example.com`, or `http://localhost//169.254.169.254` — parses with `hostname = approved.example.com`/`localhost`, which is what `ensureTmsServerApproved` approves and what the HTTPS/localhost checks key off, but `buildUrl`'s `new URL(projectPath + path, parsedUrl)` then resolved the *request* to `evil.example.com`/`169.254.169.254` (a protocol-relative reference), delivering `TMS_API_KEY`/`TMS_TOKEN` and every translated string there. `buildUrl` now pins the resolved request origin to the approved `parsedUrl.origin` and throws `ConfigError` naming the redirected origin otherwise; a legitimate base path (`https://tms.example.com/tms`) is unaffected. The threat is a maliciously-contributed `.deepl-sync.yaml` in a repo whose maintainer runs `deepl sync push`. CWE-918. Found by the cli-8kr2.70 independent red-team pass.
-
-- **sync**: `deepl sync pull` no longer reads an inherited `Object.prototype` member as a pulled translation. `sanitizePullKeysResponse` returns a null-prototype object precisely so a source key named `toString`/`constructor`/`valueOf` cannot resolve to a function through `keys[key] !== undefined`, but the pull path had begun spreading it into a plain object literal (`{ ...keys }`), re-exposing the prototype — so on a monolingual bucket a source key with such a name, against a TMS export that omits it, read the inherited function as an approved value, reported `Pulled`/`Replaced`, and deleted the reviewed local translation (on a PO bucket it crashed `value is not iterable`). The spread now preserves the null prototype, and `mergePulledTranslations` tests membership with `Object.hasOwn` so it is immune to the shape of whatever object a caller hands it. All within unreleased work; no tagged release shipped it.
-
+- **package**: `import '@deepl/cli'` loads instead of throwing. The package is ESM, so Node requires a full specifier for every relative import, but the entry point re-exported `'./types'` — a directory — which fails with `ERR_UNSUPPORTED_DIR_IMPORT`, making the whole programmatic surface unreachable and the published typings resolve to nothing for a `nodenext` consumer. `deepl --help` never exercised it, because the `bin` entry has its own module graph. Both directory specifiers now carry `/index.js`.
+- **hooks**: `deepl hooks install` resolves the hooks directory git actually reads (`git rev-parse --git-path hooks`), so it honours `core.hooksPath` (husky) and works inside linked worktrees and submodules where `.git` is a pointer file, instead of reporting success while writing a hook git never runs and crashing with a raw `ENOTDIR`. A repeat install no longer overwrites an existing hook backup (the next free `.backup` slot is used), the output prints the hook path and the backup path, and `findGitRoot` no longer loops forever when given a relative start path.
+- **hooks**: Generated git hooks no longer emit a broken install instruction — the `pre-push` template told users to globally install the unpublished `deepl-cli` name, which fails with `ENOVERSIONS`, and now points at `@deepl/cli`, guarded by a regression test asserting generated hook output never references an unpublished package name. Reported by **@maa-xx** in #70.
+- **utils**: Atomic file writes preserve the target's existing permissions instead of resetting them to the umask default, so `deepl write --fix` on a `0600` secrets file no longer leaves it world-readable at `0644`.
+- **glossary**: Deduplicating repeated `--glossary` flags no longer inverts the documented precedence — a repeat kept its first position, so `--glossary base --glossary override --glossary base` let `override` win terms both define although the user put `base` last. A repeat now keeps its last position, which is the one the API applies, and resolved IDs are deduplicated, so naming one glossary twice (or a name plus its own UUID) no longer flips the wire parameter away from `glossary_id`, mints a third cache key for an identical request, or spends two of the five slots the API allows.
+- **glossary**: `--glossary` with a source language set only in config no longer fails. `TranslationService` merges `defaults.sourceLang`, so the request carries `source_lang` whether or not `--from` was typed, but the guard tested the flag alone. The effective source language is now resolved onto the request, which also gives the document path and the glossary preflight the pair they need, and an empty `--glossary` selection is no longer treated as a glossary (`[]` is truthy, so it produced a spurious "Source language (--from) is required").
+- **glossary**: The language-pair preflight no longer treats two regional variants of one language as interchangeable — both sides were compared on their base language, so a `pt-br` dictionary satisfied a request for `pt-pt`. A dictionary language now matches the requested one exactly or matches the base it reduces to, so `de→en` still covers `--to en-us` and a dictionary naming `pt-br` still matches `--to pt-br`.
+- **glossary**: Six smaller defects around the multi-glossary work. `sync` resolved its glossary without the language pair, so a non-covering glossary failed once per file rather than at startup, unlike the sibling translation-memory resolution; `translate --dry-run` and `watch --dry-run` reported as runnable a glossary command the real run rejects for a missing `--from`; the document path never ran the extended-tier constraint check, newly reachable now that documents accept glossaries, so it uploaded the file and let the API refuse it; `glossary info` printed raw dictionary languages beneath a normalized summary, so one glossary could show `EN → DE` under `Source language: en`; and a coverage error listed every dictionary of a multilingual glossary on a single line.
+- **glossary**: `deepl glossary add-entry` / `update-entry` reject terms containing a tab, carriage return or newline instead of shifting every following column of the uploaded dictionary, and glossary import picks the TSV or CSV dialect once per file so a quoted CSV field containing a tab is not split into garbage columns. A term named after an `Object.prototype` member is no longer dropped or falsely flagged as a duplicate — `tsvToEntries` used a plain-object accumulator, so `toString` triggered a spurious "Duplicate source" warning and a `__proto__` term was swallowed by the prototype setter — while genuine duplicate detection is unchanged. Scoped commands (`show`, `entries`, `delete`) also no longer emit an unrelated org glossary's "empty dictionaries" warning during name resolution.
+- **sync**: Auto-glossary sync (`translation.glossary: auto`) skips terms whose source or translation is empty or contains a tab, carriage return or newline, which were uploaded as corrupted or outright wrong glossary entries that DeepL then applied to live translations. An unchanged dictionary is no longer re-uploaded on every run (entries were compared against a lossy TSV round trip that could never compare equal), a glossary failure for one locale no longer ends glossary sync for the remaining locales — the warning names the locale, glossary and cause — and term extraction, which is keyed by untrusted source strings, is prototype-safe.
+- **sync**: The startup glossary coverage check no longer requires the top-level glossary to cover locales that are configured with their own `locale_overrides.<locale>.glossary`, which aborted a documented configuration before any file was touched. Per-locale glossary and translation-memory overrides are now resolved and checked once at startup against their own locale rather than re-resolved per file, so a bad reference fails before anything is translated; `locale_overrides.<locale>.glossary` previously skipped the coverage preflight entirely. `sync --dry-run` resolves and checks the same references a real run does — it already needs an API key to reach that point — while still sending nothing to `/v2/translate`.
+- **voice**: `--glossary` is resolved after the command's local checks rather than before them, so `voice a.ogg --to bogus --glossary my-terms` no longer spends a glossary-list round trip to then fail locally, and resolution passes the requested language pair so a non-covering glossary fails locally instead of at the API. The pair checked is the canonical one voice sends, so `--from EN --to zh-hans` is checked as `en→zh-HANS`; without `--from` there is no pair and the API still judges it.
+- **voice**: A session that ends with the audio transcribed but no translation for a requested `--to` language now fails with exit 9 and names the languages, instead of printing an empty translation line and exiting 0. The failure **carries the transcripts that did arrive**, printed to stderr before exiting, since the audio is transcribed and billed before the missing translation is noticed. Target updates are matched case-insensitively, because the requested spellings include `zh-HANS` and `en-GB` and a differently canonicalized echo used to be dropped silently and then reported as missing. Audio containing no speech transcribes and translates to nothing, which is legitimate and still exits 0; whitespace-only and never-concluded translations count as missing.
+- **voice**: `deepl voice` reconnects after a transport failure. The socket `error` handler marked the stream ended before the `close` event that always follows, so the reconnect path (up to 3 attempts, `--reconnect` on by default) was unreachable for a real network drop and only a clean remote close ever reconnected. A reconnect that exhausts its attempts now closes the audio input instead of leaving the stream generator awaiting forever.
+- **voice**: `--quiet` no longer discards the salvaged transcripts of a failed session — the partial result went through the warning channel, which quiet mode suppresses, while the live display was erased regardless, so audio that had been transcribed and billed left nothing on screen. It goes through the error channel now, the display is cleared only once there is something to print in its place, and `--format json` is honoured on that path. The live display also keyed target rows by the requested spelling, so with `--to zh-HANS` a `zh-Hans` echo left the row blank for the whole session; it is matched case-insensitively.
+- **voice**: Regional target and source codes may be spelled in any casing — `--to en-gb` and `--to zh-hans` exited 6 while `--to en-GB` worked, even though `deepl languages` prints the lowercase form. Codes are matched case-insensitively and canonicalized to what the Voice API expects.
+- **languages**: Four target languages the API accepts were unusable: `de-CH` (Swiss German), `de-DE`, `fr-CA` (Canadian French) and `fr-FR` are returned by `GET /v3/languages` and accepted by the translate endpoint, but the bundled list did not contain them, so `deepl translate --to de-CH` failed locally with `Invalid target language code` — and the `deepl languages` the error suggested did not list them either. Swiss German and Canadian French had no workaround. The list now contains all 125 languages the API serves (32 core, 11 regional, 82 extended).
+- **languages**: `deepl languages --target` marks Portuguese (`pt`) with `[F]`. Formality support is read from `features.formality` on `GET /v3/languages` rather than a static table: the v3 migration assumed v3 stopped reporting formality, but v2's `supports_formality` boolean had only become the presence of a `formality` key in the per-language features matrix, so the CLI was answering from an 11-entry snapshot of the final v2 response. That snapshot is gone; the `[F]` set is otherwise identical and the registry's `category` tiers are unaffected.
+- **languages**: `--features` no longer claims knowledge it does not have. Snapshot entries the API response omitted were every one rendered as the positive claim `none` — with a response covering a handful of languages, over a hundred were reported as supporting nothing — and those rows also made every feature look non-uniform, so features shared by all described languages became columns of repeated values instead of the footer note the flag was built around. A feature reported without a `status` no longer renders as the literal `undefined`, `supportsFormality` is no longer asserted `false` for a language the response never mentioned (which turned on the `[F]` legend with no `[F]` to explain), only a language credited with nothing at all reads `none`, the Formality column is no longer disabled without being replaced, and the `?` cell for an undescribed language has a legend. `deepl languages` also makes one `GET /v3/languages` request instead of two identical ones.
+- **languages**: A language `GET /v3/languages` describes with no feature matrix is no longer filed as extended — the tier was derived from the absence of glossary support, and an absent matrix is silence rather than a denial. Since the extended tier is what refuses formality and glossary before a request is sent, such a language is now tiered by source usability and the API keeps the judgement; an **empty** matrix is still evidence and still means extended. An absent `usable_as_source` / `usable_as_target` flag is likewise read as "usable" in the language and glossary-pair listings, matching the registry — the two disagreed, so a language whose flag was absent was dropped from `deepl languages` while the generator recorded it as core.
+- **languages**: `deepl languages --format json` with no API key falls back to the bundled snapshot instead of answering `{"source":[],"target":[]}` while the text and table formats printed all 125, so listing languages works offline in every format.
+- **languages, voice**: Strings the API supplies are sanitized before they reach the terminal — `deepl languages` printed names, feature keys and statuses verbatim and `voice` did the same with transcript text and language labels, so a hostile or intercepted endpoint could move the cursor, clear the screen, or hide text behind a bidi override. Both now go through the same `sanitizeForTerminal` the glossary and style-rule listings used, replacing control and zero-width characters with `?`. It matters most for `voice`, whose live display clears a fixed number of lines. `voice --format json` keeps the text byte for byte.
+- **usage**: Voice usage no longer reports the API key's own consumption as the account total. Duration-billed products fell back to `apiKeyUnitCount` for the account figure, because live responses omit `unit_count` for them, so both columns showed the same number; the account-wide `account_unit_count` the response does carry was neither typed nor parsed and now is, and where no account-wide figure exists the row reads `(API key)` rather than inventing a total.
+- **usage**: Text and table output no longer report duration-billed products as zero characters — duration billing units are recognized, rendered in h/m/s as documented, and product names print in the documented snake_case (`--format json` was already correct). A character count is read only for `milliseconds` billing, where it carries the duration, so a duration-billed product can no longer render a character count as hours; anything non-finite is treated as absent rather than reported as a genuine zero.
+- **admin**: An entitlement failure (a valid key without admin scope) no longer suggests re-running `deepl init` / `auth set-key`; the suggestion explains that the admin API requires an administrator API key. Exit code and classification are unchanged.
+- **scripts**: `npm run generate:languages` refuses to write a snapshot that would break the CLI: an empty write list would collapse the `WriteLanguage` union to `never`, rejecting every `--lang` while naming no valid option, and a features matrix that stopped reporting `glossary` would retier all 125 languages as extended and make `--formality` and `--glossary` unusable everywhere. `--check` compares whole blocks rather than quoted codes, so a renamed display name is reported as real drift instead of "formatting only", and the generated file is in `.prettierignore` so `npm run format` cannot make that check fail permanently. Both resources are fetched together and their failures reported together, so a key that cannot read `resource=write` no longer blocks regenerating the translation list. A thrown fetch or unparseable error body is reported as an `error:` line at exit 1 rather than an unhandled rejection with a stack trace.
+- **scripts**: The language generator no longer writes unescaped API response fields into TypeScript. `lang` was interpolated into a single-quoted literal with no escaping and `name` escaped only quotes, so a response field containing `' }] as const;` — or merely ending in a backslash — could append arbitrary code to `src/data/language-entries.ts`, which the next build compiles and the test suite imports. Codes are now validated against the language-tag pattern, display names against a conservative character set, categories against the three tiers, and every value is quoted with escaping, with validation running before grouping. The generator's main guard also resolves `argv[1]` through `realpathSync`, because Node reports the ESM entry by its real path — under a symlinked checkout both npm scripts exited 0 without doing anything, including the release step that keeps the Write list current.
 - **perf**: `sync audit` registration no longer loads fast-glob on every CLI invocation (lazy import, matching its sibling subcommands).
+- **docs**: Documentation inaccuracies found in the pre-2.0 audit. `docs/API.md` and `README.md` said the **last** `--glossary` wins a conflicting term, contradicting the flag's own help text and the verified behaviour — which mapping wins is the API's choice and does not follow flag order. `docs/API.md`'s command-group table omitted `correct` while claiming to match `deepl --help`, its environment-variable reference omitted `NO_PROXY`, and the README's table of contents omitted its Spelling and Grammar Correction section. Three further passages described behaviour that no longer exists: the `voice --glossary` row had picked up `translate`'s repeatable/`--from` semantics (voice takes one glossary and requires neither), the `write` reference still said an unknown code is rejected locally, and the `usage` reference still documented the removed Speech-to-Text section along with output showing the duplicated API-key figure. `docs/TROUBLESHOOTING.md`'s "Translation cache backend failed to load" entry attributed the failure to running Node < 24, which the startup version check rejects earlier with its own message, so the stated cause was unreachable; that entry now describes the reachable case (a v24+ runtime with no usable `node:sqlite`) and the version error is documented under exit code 6, where it previously appeared nowhere. The `NODE_MODULE_VERSION` / `npm rebuild better-sqlite3` entry is gone with the dependency.
+- **docs**: Further corrections. The README's translate examples no longer show a `Translation (XX):` label the CLI never emits, and `--model-type` (no CLI default), `--config` precedence (replaces the config file only; the cache path is unaffected), unknown-command and `deepl detect` sample output, and the nonexistent 10 MB PDF cap (the document limit is 30 MB uniformly) are corrected; the README now covers `deepl sync`, `deepl tm` and all nine `style-rules` subcommands, with dead in-page anchors repaired and `docs/SYNC.md` listed under Documentation. `TROUBLESHOOTING.md`'s exit-code table gains codes 10–12 (SyncDrift, SyncConflict, PartialFailure) and its environment-variable table gains `TMS_API_KEY`, `TMS_TOKEN`, `FORCE_COLOR` and `TERM`; sync JSON-contract stability promises are rescoped from "1.x" to "within a major version"; the GitHub Actions recipes in `docs/SYNC.md` pin Node 24; `CONTRIBUTING.md` no longer cites Zod (validation is commander `Option.choices()` plus hand-written validators); and `examples/README.md` no longer references a nonexistent `sample-files/` directory.
+- **examples**: `examples/03-batch-processing.sh` no longer hides five `--output <dir>` failures behind `2>/dev/null`, `|| true` and a `(cached or completed)` message that reported a cache hit for a call that had errored — so `npm run examples` reported 37/37 passed while this was broken. Section 8's cache comparison now times calls that actually succeed.
 
 ### Security
 
-- **sync**: **`deepl sync validate` was inert for PO and XLIFF buckets and reported the opposite of the truth.** The gate compares each target value against its source, but for a bilingual format it read the msgid / `<source>` on both sides, so it was comparing the source against itself. Measured through the real CLI on a `locales/es/app.po` whose `msgstr "Hola amigo"` drops the `{name}` placeholder the msgid carries: `deepl sync validate` **exited 0** reporting `1 warning(s)` — and the warning was `Translation is identical to source text`, which is a false positive raised against every entry in every PO and XLIFF bucket, correct translations included. The genuinely broken translation passed. It now exits 8 with `ERROR es/Hello {name}: Missing placeholders in translation: {name}`. Anything using `deepl sync validate` as a CI gate on a PO or XLIFF project was gating on nothing: the check that was meant to catch a placeholder-dropping translation could not see the translation at all.
-
-- **formats**: **no writer emits a raw C0 control byte into a repo file any more.** Six of the nine writers escaped only their own quoting characters plus `\n`/`\r`/`\t`, so any other control byte in a translation was written through untouched; JSON, YAML and ARB were already clean because they delegate to `JSON.stringify` and the YAML emitter. That put live terminal-control sequences into source-controlled files, where `git diff`, `cat`, `less` and CI log viewers all render them — with no CLI output path involved. **No API call is needed to trigger it.** A contributor commits a *valid* `locales/app.de.toml` holding `greeting = "Hola\u001B[2J"` (TOML basic strings legally carry `\uXXXX`, and smol-toml decodes it to a raw ESC). The key is then `current`, so it is never translated and never validated: the locale translator carries the existing target value forward and the writer put the byte back out raw. Measured through the real CLI: the rewritten file contained `greeting = "Hola␛[2J"`, and `TomlFormatParser.extract` then refuses it — `Invalid TOML document: control characters are not allowed in strings`. The finding said every later run fails; **measured, it is quieter and worse than that.** `deepl sync` exits 0 and says nothing, because the target-file read is inside a catch that treats a parse failure as "no existing translations", so the file's translations simply stop being visible to sync. `deepl sync status` exits 0 reporting **`de [####] 100% (0 missing, 0 outdated)`** for a file it cannot parse. Only `deepl sync validate` fails, at the untyped exit 1. Android XML and XLIFF are worse still: every C0 byte except tab, LF and CR is outside XML 1.0's `Char` production, so there is no escape and no numeric character reference for it — expat rejects both written files as `not well-formed (invalid token)`, which means `aapt2` and every conforming CAT tool reject them too. One shared rule now lives in `src/formats/util/control-chars.ts`, and each writer applies it the way its own format allows: TOML escapes as `\uXXXX` (and forces the double-quoted form for a value a literal string could not escape, plus U+007F, which smol-toml also rejects raw — verified against the library); `.properties` extends its existing `\uXXXX` rule below U+0020; iOS Strings emits `\UXXXX`, which its own reader already decodes; PO gains the missing `\r` escape and refuses the rest with a `ValidationError` naming the entry, since its escape set cannot spell them and `unquote` could not read them back; Android XML and XLIFF refuse with a `ValidationError` naming the resource or trans-unit, matching the stance both already take on CDATA. Each message names the codepoint (`U+001B`) rather than quoting a byte that prints as nothing.
-
-- **sync**: **a source catalog can no longer smuggle one string into another string's key.** Five parsers encode hierarchical key identity in-band with no escaping: PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.`. A key component holding the separator therefore resolved to the same key as an unrelated entry, and the two control bytes **print as nothing**, so the source diff showed an ordinary string. Measured: a PO catalog carrying `msgid "menu␄Save"` beside a normal `msgctxt "menu" / msgid "Save"` pair extracted two entries with the identical key `menu␄Save`, and reconstruct wrote the smuggled entry's translation into the legitimate pair's `msgstr` — the attacker picks the source text, DeepL translates it, and the result lands in the victim key's slot in **every** locale. **The stronger case needs no collision at all**: one smuggled `msgid "menu␄Save"` in a catalog with no `msgctxt` anywhere produced `msgctxt "menu"` / `msgid "Save"` / `msgstr "ATTACKER-TEXT"` in every target `.po`, forging a context-qualified entry the source never had — so a duplicate-key check alone would have missed it. YAML behaves the same way: a source key `"a\0b"` became a genuine nested `a: { b: ATTACKER-TEXT }` via `doc.setIn`. For the `.` formats the damage is a lost or corrupt file rather than a forgery: `{"a.b":"FLAT","a":{"b":"NESTED"}}` rewrote both slots to one translation and dropped the flat key's own; the Android `<string name="items.0">` colliding with `<string-array name="items">` was **deleted** from the output; and the Laravel case emitted PHP the CLI's own parser then refuses — the repo's `11-dot-key-vs-nested.php` fixture reconstructs to `'b' => 'PWNED<NESTED>'LAT>',`, failing to re-read with `syntax error, unexpected 'LAT' (T_STRING), expecting ']'`, because `collectStringLocs` maps a key to one source offset and the two replacements splice over each other. Each parser now refuses the file: PO and YAML reject the reserved byte at both key-construction sites (extract and the target-file read inside reconstruct), quoting it back escaped as `\u0004` / `\u0000` rather than echoing a byte that prints as nothing; JSON, Laravel PHP and Android XML assert their extract output has distinct keys, which for those three is exactly equivalent to detecting a separator collision because their containers already guarantee distinct sibling keys. `sync` skips the one file with a warning naming the colliding key and finishes the rest of the run at exit 0, following the existing `FormatDepthExceededError` and `max_entries_per_file` convention — one hostile file must not discard the lockfile for work already translated, billed and written. `.properties` and XLIFF are deliberately excluded: a literally repeated key is legal in both (Java `Properties.load` is last-wins), so a blanket duplicate check would have rejected files that work today. `sync pull` reading a **target** file whose keys collide leaves it untouched and records a `key_collision` skip, rather than falling through to the source template — measured, that fallback would have rebuilt `locales/de.json` from source down to the single key the export carried, discarding a hand-written translation.
-
-- **translate**: **a document upload response can no longer choose where this client sends its own follow-up requests.** The `document_id` from `POST /v2/document` was interpolated into `POST /v2/document/{id}` and `POST /v2/document/{id}/result` with no encoding and no format check, and the endpoint supplying it is redirectable via `--api-url`, `api.baseUrl` or a proxy. Measured against a stub answering `document_id: '../../v3/glossaries%3fpwned=1'`, the client's next two request lines arrived as `POST /v3/glossaries%3fpwned=1` and `POST /v3/glossaries%3fpwned=1/result` — the traversal collapsed exactly as crafted, on a completely different route from `/v2/document/{id}` — and the run finished at **exit 0** reporting `Translated report.pdf -> out.pdf` after writing the stub's JSON body into the output file as if it were a translated PDF. `document_id` is now checked against `[A-Za-z0-9_-]+` at both interpolation sites, so a redirected first response stops the workflow at exit 5 (`NetworkError`, since nothing the user typed is wrong) with the ID quoted back, nothing further sent, and no output file written. A response with no `document_id` at all was reaching the wire as the literal path `/v2/document/undefined`; that is refused by the same check. This was the last unguarded interpolation of an untrusted value into a URL path in the API layer — `GlossaryClient` validates its ID at all 7 sites and `StyleRulesClient` encodes at all 8, and the document client was the one exception among the ten clients. The polling loop was also checked: it re-sends the original handle rather than the `document_id` echoed by each status response, so a clean first response cannot be followed by a poisoned second one.
-
-- **sync**: **`sync pull` no longer records `review_status: human_reviewed` for content it never verified was reviewed.** Every key a pull applied was stamped `human_reviewed` in `.deepl-sync.lock`, unconditionally. The documented export contract is `GET /keys/export` returning `{ "key": "translated value", … }` — a flat map with no per-entry review flag — so there was nothing in the response to base that claim on, and a TMS that exports machine-translation drafts had them recorded in a committed file as human-reviewed. Where the `tms.server` in a checkout is not one the operator chose, the endpoint controls the strings *and* the review label attached to them. Measured: a mock export returning `{"greeting":"Hallo vom TMS"}` produced `"de": {"hash":"185f8db32271","review_status":"human_reviewed","status":"translated","translated_at":"…"}`. Pulled entries now record `status: translated` with **no** `review_status`, which is the type's way of saying "unknown"; `human_reviewed` is still honoured when a person or another tool writes it, and `--flag-for-review` still writes `machine_translated`, so nothing else in the lockfile changes. Nothing in the CLI reads `review_status` today, which is exactly why a false value could sit there unnoticed until something did — including the `tms.require_review` gate the config schema advertised.
-
-- **sync**: **`--force` is refused when there is no terminal to confirm it on, instead of treating "nobody can answer" as yes.** The guard threw for `CI=true` and prompted on a TTY, and had no third branch — so in a git hook, cron job, `make` target, container entrypoint, Jenkins agent, or plain `deepl sync --force < /dev/null`, the prompt was skipped and the run **proceeded**. This inverted the convention `confirm()` exists to enforce: it returns `false` for a non-TTY, deliberately fail-closed, and the seven other destructive sites (`cache clear`, `admin`, `config`, two in `glossary`, two in `style-rules`) all inherit that auto-NO. This one site turned it into auto-YES, for the single most destructive operation the CLI has. Measured on a fully synced project whose `locales/de.json` had been hand-edited to stand in for human review: `env -u CI deepl sync --force < /dev/null` printed no prompt and no warning, reported `✓ de: 3/3 keys`, `Sync complete: 3 new`, **exit 0**, and replaced all three reviewed strings with machine output — with no `.deepl.bak` surviving, so the edits were unrecoverable. **`--no-input` was ignored on the same path**, though it documents itself as "abort instead of prompting": `deepl --no-input sync --force` destroyed the same edits at exit 0. Both now exit 6 with a message naming `--yes` as the only way to run `--force` unattended, and `--yes` still works everywhere it did. Refusing rather than aborting quietly, matching the existing `CI=true` branch and the TMS destination-trust gate: unlike `cache clear`, declining here abandons the whole sync, so exit 0 would report an up-to-date project for a run that did nothing. An interactive decline is unchanged at exit 0, and now prints `Aborted.` like its seven siblings. Verified on a real terminal through a pty: the prompt appears, `n` aborts with the edits intact, `y` proceeds. The gate is a single `canPrompt()` in `utils/confirm.ts`, which `confirm()` itself now uses, so the two cannot drift apart.
-
-- **sync**: **a lockfile is now checked member by member before sync uses it, instead of being version-checked and then cast.** `SyncLockManager.read()` validated `version` and that `entries` was an object, then cast the rest of the repository's JSON to `SyncLockFile` — so `stats`, each per-file map, each entry and each translation were dereferenced unguarded. Four shapes reproduced by execution against a mock endpoint, all from a lockfile a hostile or merge-mangled repository ships: **a missing `stats`** crashed with `Error: Cannot set properties of undefined (setting 'total_keys')` and exit 1 **after the endpoint had been hit and `de.json` written**, leaving the lockfile as the attacker's stub so the next run re-billed everything; **an entry with no `translations` container** crashed with `Cannot read properties of undefined (reading 'de')`, and the same lockfile took `sync status` — a read-only command — down with `Cannot convert undefined or null to object`; **a per-file map that is a string** crashed with `Cannot delete property '0' of [object String]`; and **`entries` as an array** was accepted silently, exit 0, with the run's results written onto named properties of that array and then discarded by the serializer, so the lockfile recorded `"entries": []` beside `total_keys: 2` and every later run re-billed the project in silence, forever. Two more shapes found while probing: **a null translation** crashed with `Cannot read properties of null (reading 'status')` — one level deeper than the shape check the finding proposed — and **`stats` as a string** crashed with `Cannot create property 'total_keys' on string`. Every one of them now exits 0 with a well-formed lockfile. **Malformed members are dropped individually, not by discarding the file**: a key that loses its entry is translated and billed again, so resetting a whole lockfile over one bad member would hand whoever wrote it a full re-translation of the project. The count is reported at WARN level and the original is copied to `.deepl-sync.lock.bak-v1-malformed-<timestamp>`. `entries` that is not a map at all has nothing to salvage and takes the existing full-sync path with its own `-entries-not-a-map` tag. **`stats` is no longer trusted at all**: it is derived from `entries` and recomputed on every write that follows a mutation, and nothing reads the on-disk values for their own sake, so read() recomputes the counts from the surviving entries rather than validating what the file claims — which also means the counts can no longer disagree with the entries they describe. The repaired `entries` is rebuilt with `setOwnMember`, so a source path or i18n key named `__proto__` is carried across as an own property. In-repo precedent for the shape of the fix: `sync/tms-client.ts` already validated an untrusted map this way for pulled keys.
-
-- **hooks**: **`deepl hooks list` no longer reports attacker-authored content as an installed DeepL hook, and the integrity check it already had is now on a path a user can reach.** Two halves of one false-assurance defect. `isDeepLHook()` was `MARKER_PATTERN.test(content) || content.includes('# DeepL CLI Hook')`, and that second test is a **bare substring match**: a file mentioning the marker anywhere, on any line, in any context, passed as a hook this CLI installed. And `verifyIntegrity()` — which parses the `# DeepL CLI Hook v1 [sha256:...]` marker, rehashes the body and compares — was referenced by nothing but its own definition and its unit tests, so no command ever called it and the recorded hash was never checked outside the test suite. Reproduced by execution: a repository shipping a tracked `.githooks/pre-commit` that carries a forged marker with an all-zero hash plus a payload, wired up with `git config core.hooksPath .githooks` (the husky pattern, commonly set by a `prepare` script), and a second file whose only claim to the marker was the sentence `# borrowed from a # DeepL CLI Hook someone posted`. Before: `✓ pre-commit installed`, `✓ pre-push installed`, and `--format json` reporting `{"pre-commit": true, "pre-push": true}` for two files this CLI had never touched. **`list` now reports one of four states per hook** rather than a boolean — `installed` (versioned marker present and the body hashes to what it records), `modified` (marker present, body does not hash to it), `unverified` (legacy pre-1.0 marker, no hash to check), `not-installed` (no file, or no marker) — so the forged hook reads `! pre-commit installed, content does not match its recorded hash` and the quoted-marker file reads `not installed`. The legacy marker is now anchored to a whole line the way the versioned one always was, which is safe because it was only ever emitted as a line of its own. **The output states plainly what the hash is and is not worth**: it detects a change made after the marker was written, and it **cannot establish authorship**, because it is unkeyed — anyone who can write the hook can compute a marker that agrees with their content. That limit is why the fix is honest reporting rather than a stronger claim, and why the marker should be read as change detection, not provenance. A mismatch also has an innocent reading the CLI cannot distinguish — the README invites customizing an installed hook by editing it — so `modified` renders in yellow and the note gives both readings instead of accusing: expected if you edited it yourself, otherwise reinstall. Tightening `isDeepLHook` also tightens two paths that consult it, both fail-safe: `uninstall` refuses to delete a file whose marker is only quoted (it would previously have removed it), and `install` backs such a file up instead of overwriting it.
-
-- **hooks**: **`deepl hooks install` no longer writes an executable outside the repository because the repository told it to.** `resolveHooksDir` asks `git rev-parse --git-path hooks`, which faithfully honours `core.hooksPath` — including an absolute path anywhere on the filesystem — and the install then did an unconditional `writeFileSync` plus `chmod 0755` with no containment check. `core.hooksPath` is repository-local git config, so it travels with a checkout rather than coming from the person running the command. Reproduced by execution: `git config core.hooksPath /outside/dir` followed by `deepl hooks install pre-commit` printed `✓ Installed pre-commit hook`, exited `0`, and left an `0755` script in `/outside/dir`, with nothing on any channel to say the write had left the project. The content written is the CLI's own static template, so this was a wrong-destination defect rather than an arbitrary-code one — but the destination was the checkout's choice. An install whose hooks directory falls outside the working tree now names the configured value and the resolved directory and asks first: declining, or having no terminal to ask on, **exits 6 and writes nothing**, and `-y, --yes` accepts it while still printing the notice to stderr so a scripted install records where the executable went. The refusal lives in `GitHooksService.install`, which needs an explicit `allowExternal` to proceed, so the gate cannot be skipped by a caller that forgets to prompt. Three scoping decisions. Only the **repository-local** setting is consulted: a global `core.hooksPath` is the user's own machine-wide choice, and reading `--local` also means a repository that sets nothing is never reported — which is what keeps **linked worktrees and submodules** quiet, since there `--git-path hooks` legitimately answers with the hooks directory of the repository that owns them, outside this working tree by design. Containment is checked **through symlinks**, so a relative `core.hooksPath` pointing at a symlink that leaves the tree is caught rather than passing a lexical check. And **`uninstall` is left alone**: it already refuses to remove anything that is not a DeepL hook, so the worst it can do at a redirected path is clean up a file this CLI wrote. The containment predicate is now `isWithinDirectory` in `src/utils/paths.ts`, extracted from the copy that was private to `sync-utils.ts` along with `realpathOrAncestor`, so `assertPathWithinRoot` and the hooks check compare paths the same way.
-
-- **config**: **the `0600` mode on the file holding the plaintext API key is now enforced on every load, not just asserted at creation.** `config.json` is created `0600` and its directory `0700`, and neither was ever checked again — so a file restored from a tar or dotfiles backup, copied by `rsync`, or written by hand kept whatever mode it arrived with, forever, and `load()` read it with no `stat`, no repair and no warning while README promised `0600`. Reproduced by execution: a `0777` config directory was still `0777` after `auth set-key`, and a `config.json` chmod'd to `0644` was read by `config list` at exit 0 and left `0644`. A group- or world-reachable config file is now tightened back to `0600` on load, and the run says what it found — `… was mode 0644, which other users on this machine can read. Tightened to 0600. Your API key may already have been read; consider rotating it with: deepl auth set-key` — because a repair says nothing about who read the file before it. The warning is self-extinguishing: the next run finds `0600` and is silent. **The directory is deliberately reported rather than repaired**, which is where the filed remediation had to be rejected after probing it: it proposed `chmod(path.dirname(configPath), 0o700)`, and that dirname is not always a directory the CLI owns — `deepl -c ~/deepl.json` would have chmod'd the user's home directory to `0700`, and this repo's own `ConfigService` unit tests would have chmod'd `/tmp`. A directory that already existed was created by someone else for reasons the CLI cannot know, so it names the mode and the `chmod 700` that would close it and changes nothing. Only the **write** bits are reported (`0o022`): a merely traversable `0755` directory does not let anyone replace the file inside it, and warning about it on every run would be noise nobody reads. **Sticky directories are exempt**, which execution also forced — the first implementation told the user to `chmod 700 /tmp`, advice that would break a shared temp directory, when mode `1777` is exactly the arrangement that makes it safe: only a file's owner can rename or remove it. The cache directory gets the same report, and `cache.db` needed nothing, as it is already `chmod 0600` on every open. Both `mkdir` sites are now unconditional recursive calls rather than `existsSync`-then-create, closing the window where a directory could appear between the two. Nothing refuses to run over a permission: the mode of the file is not a reason to reject the settings in it.
-
-- **logger**: **the credential redactor no longer has two holes that between them defeat its own documented invariant.** It promised that "a dumped axios error (config.headers.Authorization etc.) cannot leak credentials via util.inspect", and neither half of that held. **Hole one: any object that was not a plain object, an array or an `Error` was returned live.** Reproduced by execution — an `Error` whose `config.headers` is an `AxiosHeaders` instance printed `headers: AxiosHeaders { Authorization: 'DeepL-Auth-Key SUPER-SECRET-KEY-FROM-CONFIG' }` verbatim, while the sibling plain-object field on the same error was redacted correctly. `Map` and `Set` leaked the same way and worse, since their contents are not own properties at all: `util.inspect` prints `Map(1) { 'Authorization' => 'DeepL-Auth-Key SECRET' }` and the redactor never saw a string. Every object is now **rebuilt property by property on its own prototype**, so `util.inspect` still names the class (`AxiosHeaders { Authorization: 'DeepL-Auth-Key [REDACTED]' }`) but never receives the original instance, and `Map`/`Set` are rebuilt with their keys and members mapped. Returning a foreign instance untouched was the wrong default for a redactor; the fail-closed one is to copy. Four types are still passed through deliberately — `Date`, `RegExp`, `ArrayBuffer` and its views — because their payload is not in string-keyed own properties, so a rebuilt copy would either lose it (`Date {}` instead of the timestamp) or, for a `Buffer`, enumerate one own property per byte; none of them renders a credential as readable text, since `util.inspect` prints a buffer as hex. Properties are `defineProperty`'d rather than assigned, so an own key named `__proto__` — which `JSON.parse` can produce — lands on the copy instead of reaching the prototype setter. **Hole two: the literal-value backstop read only `process.env`, and the config-file key wins precedence over it.** `src/cli/index.ts` resolves `apiKey ?? envKey`, so with a key in `config.json` and a different one in `DEEPL_API_KEY`, the value on the wire is precisely the one the redactor could not see. Reproduced against a loopback stub: the captured header was `authorization: DeepL-Auth-Key CONFIG-FILE-KEY-WINS:fx` while `Logger.error` redacted only `ENV-KEY-LOSES:fx` and printed the config key in full. A new `Logger.registerSecret()` closes it, called from the **`HttpClient` constructor** — the one place that sees whichever key won precedence, because it is where the key is attached to every request — and from the **`TmsClient` constructor**, which covers a `tms.api_key` or `tms.token` inlined in `.deepl-sync.yaml`. That chokepoint was chosen over the CLI's key-resolution seams because five call sites read `auth.apiKey` and a per-seam fix would go stale on the sixth. Stated honestly, hole one was a protection-mechanism failure rather than a live leak: no current call site hands a raw axios error to the logger. Hole two is reachable today — a server that echoes the key back in its own error body surfaces as `API error: <key>`, which is the path the new E2E test drives, asserting on the bare value rather than the whole `Authorization` header so the pre-existing header pattern cannot mask a missing registration. The env-versus-config precedence itself is left alone: registration makes redaction independent of which side wins. One existing unit test was replaced rather than kept — `should pass non-plain objects through unchanged` asserted the hole, down to a `token=class-secret` inside the instance it expected to pass through.
-
-- **api**: **a `/v2/translate` or `/v2/write` response body of the wrong shape is now refused instead of being carried into output.** The bodies were typed by a TypeScript interface, which asserts nothing at runtime, and checked only for truthiness and a length match. Reproduced by execution, one stub body per case, all at **exit 0** before this change: `{"translations":"notarray"}` printed the literal text **`undefined`** — a string has a truthy `.length`, so the guard and the length comparison both passed and `[0]` yielded nothing, meaning `deepl translate ... > out.txt` wrote the word "undefined" while reporting success; `{"translations":[{"text":12345}]}` printed `12345`; `{"translations":[{"text":{"a":1,"b":[2,3]}}]}` printed `{ a: 1, b: [ 2, 3 ] }`; `{"translations":{"0":{"text":"x"}}}` printed `x`. A body of `null` crashed on a raw `Cannot read properties of null` at exit 1. All six now exit 5 naming the field and the offending type — `Unexpected API response: "translations[0].text" must be a string, got number.` — and the `--output` path can no longer reach `fs.writeFile` with a non-string and die on `ERR_INVALID_ARG_TYPE`. The checks live in a new `src/api/response-shape.ts` following the contract `sanitizePullKeysResponse` already sets for the TMS: reject rather than coerce, and name the type so the endpoint is diagnosable. **The finding scoped this to the translation client; `write`/`correct` had the identical hole** — `mapImprovements` did the same truthiness-and-length check and passed `improvement.text` through unvalidated — so both are fixed together as one defect class, and the response bodies are now requested as `unknown` rather than as an interface that was never enforced. Three deliberate distinctions. **An absent or null `translations`/`improvements` field is not a type error**: it means nothing came back, which the callers' own messages already describe better ("No translation returned from DeepL API"), so it becomes an empty array and falls through to their existing length check — this is why three pre-existing tests that assert those messages still pass unchanged. **In a batch, every element is validated before any is used**, so a bad element late in the array cannot leave earlier translations already written. And the optional metadata fields — `billed_characters`, `detected_source_language`, `model_type_used` — are **dropped when wrong-typed rather than rejecting the response**, because they are not the translation: a bogus `billed_characters` must not be summed into a cost report or written to a lockfile, but it is no reason to discard a translation that has already been billed.
-
-- **cli**: **pointing the CLI at a non-DeepL endpoint is now announced, so the API key no longer travels to an unexpected host in silence.** `isStandardDeepLUrl()` existed solely to detect this case and was consumed by nothing — `grep` returned the definition and one internal precedence test, no warning path. Reproduced against a loopback stub with `DEEPL_API_KEY=SECRET-KEY-1234`: **the key arrived as `authorization: DeepL-Auth-Key SECRET-KEY-1234` and the run printed only the translation, at exit 0.** Adding `-v` did not help — the verbose line was `[verbose] HTTP POST /v2/translate completed in 12ms (status 200)`, method and path only, never the host. The worst of the three cases needed no flag at all: a `config.json` holding `api.baseUrl` redirected every request with nothing on any channel to say so, and the CLI never reported which config file it had loaded either. Now the resolved endpoint is checked and, when it is neither `api.deepl.com` nor `api-free.deepl.com`, an unconditional `Logger.warn` names the **origin** the key is going to and where the redirect came from: `set by --api-url`, or `set by api.baseUrl in /path/to/config.json` — the real path, resolved from the several locations searched and any `-c` override, which is what makes a substituted config visible. Only the origin is rendered, never the path or query, because those are chosen by whatever did the redirecting and echoing them would put attacker-picked text in front of the user; it is terminal-sanitized on the way out. Four scoping decisions. The notice is **not** gated behind `--verbose`, since a user who does not already know their key is being redirected has no reason to pass it; `--quiet` still suppresses it, matching every other warning. It goes to **stderr**, so `deepl translate ... > out.txt` and `$(deepl translate ...)` keep capturing only translation output. **Loopback is not exempt**, consistent with the TMS destination-trust gate — a co-tenant process on `127.0.0.1` receives the key exactly as a remote host does, and that is the shape the reproduction used. And it fires **once per run rather than once per client**, because a single command may build several (translation, usage, glossary) from the same endpoint and the notice is about the destination, not the client. Regional endpoints such as `api-jp.deepl.com` are included: they are not one of the two hosts the key is issued for. Separately, the verbose request line now names the resolved origin (`[verbose] HTTP POST http://127.0.0.1:56295/v2/translate completed in 12ms (status 200)`), and `ConfigService` gained a `configFilePath` accessor so any message about a setting can name the file that supplied it.
-
-- **sync**: **a sync target path can no longer begin with `-`**, closing the defense-in-depth half of the `git add`/`git commit` option-injection fix. The argv side was already fixed — both call sites pass `--` before the pathspec — but `.deepl-sync.yaml` could still name a target that *looks* like an option, and validation accepted it: `target_path_pattern: --pathspec-from-file={locale}` satisfies all four existing checks (a string, contains `{locale}`, no `..`, no `.git`/`.github` segment) and `resolveTargetPath` rendered it verbatim to `--pathspec-from-file=de`. Reproduced by execution, and the finding named only one of **three** routes to a dash-leading target: the literal pattern, a `{basename}` taken from a source file the glob discovered whose own name begins with `-` (`--pathspec-from-file=x.json` + `{basename}.{locale}.json` → `--pathspec-from-file=x.json.de.json`), and the default locale-substitution branch running over a dash-leading source directory (`-o/en.json` → `-o/de.json`), which involves no pattern at all. Rejecting the pattern alone would therefore have left two thirds of the class open. Two tiers, mirroring how `FORBIDDEN_TARGET_SEGMENTS` is already enforced twice: a literal pattern beginning with `-` fails at config load with `ConfigError` (exit 7), and every path `resolveTargetPath` renders is checked again and fails with `ValidationError` (exit 6), which is the only tier the `{basename}` and locale-substitution routes pass through. **Only the first segment** is checked, because the rendered path is one argv entry and a dash later in it is never option-like — `res/values-{locale}/strings.xml`, `locales/zh-Hans.json` and `locales/-legacy/{locale}.json` all still resolve, verified alongside the three refusals.
-
-- **sync**: **a `tms.server` value in the checkout can no longer redirect the operator's environment-held `TMS_API_KEY` to a host of its choosing.** `.deepl-sync.yaml` picks the destination, `TMS_API_KEY`/`TMS_TOKEN` come from the operator's environment, and `createTmsClient` wired the two together with the only destination guard being **scheme, not identity** — `buildUrl` requires `https:` (waived for `localhost`/`127.0.0.1`) and nothing checked *who* was on the other end. Nothing secret had to be in the repo. Reproduced end to end: a hostile checkout with `tms: {enabled: true, server: http://127.0.0.1:<port>, project_id: victim-project}`, an operator with `TMS_API_KEY` exported (normal for cross-project use), `deepl sync push` → **`Pushed 1 translations to TMS`, exit 0**, while the listener captured `PUT /api/projects/victim-project/keys/greeting` with `authorization: ApiKey TMS-SECRET-CREDENTIAL-1234` and the translated string in the body. `resolveTmsCredentials` did warn — but only about credentials *inlined in the YAML*, never about the YAML choosing the *destination*, and the success line named a count and no host. Now a **hybrid allowlist plus trust-on-first-use** gates it, in `createTmsClient` so both `sync push` and `sync pull` are covered by one choke point: the hostname must appear in a new user-level `tms.allowedServers` list, or be approved once at a prompt that names the host and states that the credential and every translated string would go to it. An accepted answer is recorded in **user** config (`~/.config/deepl-cli/config.json`), never in the repository, so it survives a fresh clone and does not travel with the repo. Under `--no-input` or on a non-TTY the run **fails closed with exit 7** naming the host and the exact `deepl config set tms.allowedServers <hosts>` command, with the already-approved hosts preserved in the suggested value so following it is not destructive. Verified under a real pty: declining exits 7 with nothing sent and nothing recorded; accepting exits 0, writes `allowedServers: ['localhost']` to the isolated config dir, and a later non-TTY run proceeds without prompting. Four scoping decisions the finding did not settle. The gate keys on **credential provenance**, not merely on a repo-supplied host: a credential inlined as `tms.api_key`/`tms.token` is not gated, because it belongs to the same file that chose the destination and nothing of the operator's leaks — and provenance is computed for the credential `getAuthHeader` will *actually* attach, which prefers `api_key`, so an env-held token sitting behind a config-held key does not trigger a prompt it could never leak through. Allowlist-only was rejected as it breaks every existing TMS user with no migration path, and TOFU-only was rejected as it leaves `--no-input` CI with no way to pre-approve. Matching is **exact and case-insensitive on the parsed hostname**, ignoring scheme, port and path, so a listed `example.com` does not approve `tms.example.com` and `tms.example.com` does not approve `evil-tms.example.com`; there are no wildcards, and entries carrying a scheme, port, path or `*` are **rejected at `deepl config set`** rather than stored as approval that could never match. And **loopback is not exempt**, unlike in `buildUrl`'s HTTPS check: a co-tenant process listening on `127.0.0.1` is as much an exfiltration sink as a remote host, which is exactly the shape the reproduction used. Independently and unconditionally, both commands now **print the resolved destination origin** on success in text and JSON output (`Pushed 3 translations to TMS at https://tms.example.com`; `"server": "https://tms.example.com"`), so a redirected destination is visible in logs even when the host was already approved — the origin only, never a repo-controlled path or query, and terminal-sanitized.
-
-- **sync**: **an i18n key named `__proto__` is now recorded in the lockfile instead of vanishing from it, so it is no longer re-translated and re-billed on every run, forever.** Every write into the lockfile's entry maps was a plain assignment — `fileEntryMap[diff.key] = {...}` in `sync-process-bucket.ts` and `sync-tms.ts`, `lockFile.entries[filePath][key] = entry` in `sync-lock.ts` — and for that one key name the assignment reaches the prototype setter rather than creating a property. With `locales/en.json` holding `{greeting, __proto__, normal}`, `deepl sync` reported `3/3 keys` and wrote all three translations into `de.json`, but the lockfile came back with two entries and `"total_keys": 2`; each subsequent run diffed the missing key as new, sent it to the API, and was billed for it again, with no run ever converging. The hazard was already documented one file over — `sync-lock.ts` carries a null-prototype comment about exactly this — but only the **serialization** side had been fixed, and by the time serialization runs the key is already gone. The same shape applied to a **source path** named `__proto__`, which fell out of `lockFile.entries` wholesale, taking every key in that file with it. Fixed with three shared accessors in `sync-lock.ts` (`setOwnMember` / `getOwnMember` / `ensureFileEntries`) applied at all fourteen access sites across six files, following the `setOwn` pattern `formats/json.ts` already uses for this hazard on the translation side. The read side needed the same treatment and for a **different** reason the finding did not cover: plain indexing hands back inherited `Object.prototype` members, so keys named `constructor`, `toString`, `valueOf` or `hasOwnProperty` read as an existing lock entry that is missing every field it should have — `computeDiff` classified all four as **stale** rather than new on a first sync (`newKeys: 0, staleKeys: 4` where both should have been 4/0), and one code path would have dereferenced `.translations` on `Object` itself had a hash ever matched. Two sites beyond the fourteen the finding listed also needed it, in `sync-status.ts` and `sync-locale-translator.ts`. Verified end to end against a recording stub: the key is translated once, the lockfile round-trips all three entries with `total_keys: 3`, `de.json` holds the translated value as an own property, and a second sync sends **no** request and reports 3 current keys.
-
-- **api**: **an endpoint that keeps sending is now bounded in both bytes and wall-clock time.** The shared axios instance set `baseURL`, `timeout` and agents but never `maxContentLength` or `maxBodyLength`, which axios defaults to `-1` — unbounded — so a response body was buffered into memory until the process died; all ten API clients inherited that. Worse, `--timeout` did not save the run, because axios delivers it to the socket as an *inactivity* timeout and this client goes out over the follow-redirects transport, where that is the only timeout armed: every arriving chunk reset it, so it never fired. Measured against a stub streaming 1 MiB chunks forever with `timeout: 5000`: **peak RSS 8572 MB and still running, un-aborted, at 20 s — four times past the configured deadline. After: rejected in 24 ms with RSS flat.** A second, nastier shape proves a size cap alone would not have been enough: a stub trickling **one byte per second** stays under any byte cap indefinitely while pinning the process, and also ran past 20 s untouched; it now aborts at 5005 ms, the configured timeout. With retries enabled the whole call is bounded too — 10093 ms for `--max-retries 3`, matching the twice-`--timeout` budget that was already documented but that only held for an endpoint which said nothing at all. Two changes, and the second is the load-bearing one. **A finite response cap of 32 MiB and body cap of 128 MiB on the shared instance**, verified to be enforced by axios on the buffered and `arraybuffer` paths alike, which is every path this repo uses. **An `AbortController` deadline armed per attempt inside the retry loop**, wall-clock and therefore not resettable by the peer. The caps are deliberately **not** the single 32 MiB used by `sync`'s TMS client, which the finding suggested reusing: DeepL accepts documents up to 30 MB and a translated result can exceed its source — `output_format` converts between types — so a 32 MiB response cap would have rejected a legitimate translated document on `deepl translate report.pdf --to de`, at the one endpoint whose result is single-use and deliberately never retried. Rejecting there destroys an already-billed translation permanently, so the cap would have caused the very data loss it was meant to prevent; the document download therefore raises its response cap to 128 MiB per request, riding the same `RequestPolicy` mechanism it already uses to widen `timeout`, while status polling and the other nine clients keep the tighter default. Two smaller consequences of the same work: a deadline abort is restated as the socket timeout it stands in for, because axios surfaces a mid-body cancellation as a `CanceledError` that still carries the 200 response and classification would have reported that as `API error: canceled` rather than a timeout; and a size-cap rejection is **not** retried, since the verdict is deterministic and replaying it only re-downloads bytes that will be discarded again — three extra attempts on a 32 MiB body were 128 MiB of pointless transfer. Both bounds surface as `NetworkError` (exit 5), the size cap naming the limit it hit rather than axios's internal `maxContentLength size of 33554432 exceeded`.
-
-- **cli, sync**: **text the CLI did not author can no longer drive the terminal that renders it.** Translation text went from the API to stdout raw, and i18n keys went from a checkout to stdout raw, so both could carry terminal control sequences. Measured against a stub endpoint with a real pty on stdout: the run emitted **4 raw ESC and 1 BEL before this change — setting the window title via OSC 0 and erasing the line via CSI 2K — and 2 ESC and 0 BEL after, both of them SGR colour**. The key sink needs no API key and no network: an evil checkout plus `deepl sync validate` exits 8 with an OSC 52 clipboard write and a CSI 2J screen erase verbatim in its output, and `hooks install` puts that command in the pre-commit hook, so it fires on every commit. `sanitizeForTerminal` already existed and was applied in ten other files, just not on the primary render paths. Two layers close it. **Untrusted values interpolated into report lines are sanitized at the call site, unconditionally**: the locale, key and message in `sync validate`, and the choice labels in `write --interactive` / `correct --interactive`, where the value handed back to the caller stays raw so only the display is affected. **The logger neutralizes control sequences centrally**, which covers all 111 `Logger.output` call sites, every stderr sink, and future ones by construction — including error paths that echo a hostile value, such as the JSON parser's duplicate-key report. stderr is sanitized whether or not it is a TTY, because a redirected stderr is still rendered by CI log viewers that interpret ANSI. **stdout is sanitized only when it is a terminal**, because redirected stdout is data: `deepl translate ... > out.txt` and `$(deepl translate ...)` must reproduce the API's bytes exactly, and a control sequence can only act on a terminal that interprets one — the same rule `ls` and `git` apply to nonprintables. Colour (SGR) sequences survive, since chalk-formatted strings are passed to the logger already rendered and stripping them would drop all colour; that concedes only text attributes, while the primitives that let injected text take over a session — OSC title and clipboard writes, CSI erase and cursor moves, and the status queries whose reply is typed back on the shell's stdin — are all neutralized. The stream filter is a **separate, narrower function** from `sanitizeForTerminal`, which cannot be used on a whole stream: it replaces newlines and tabs, and replaces U+200B–U+200F, so applying it to translation output would have turned every multi-line result into `?`-separated text and corrupted the ZWNJ, ZWJ and bidi marks that are legitimate content in Persian, Arabic, Devanagari and emoji sequences — silent corruption of the main command's output, in place of the bug being fixed.
-
-- **api**: a batch translation response that returns the submitted texts themselves, rearranged, is now refused instead of written out. `POST /v2/translate` correlates a translation to its request item by position and by nothing else, and the only check on the response was that it had the same number of entries — so an endpoint returning the request's own texts rotated by one wrote each translation under the wrong i18n key at exit 0, reporting full success. `{confirm_delete: 'Delete account permanently', cancel: 'Cancel', save: 'Save changes'}` came back as `{confirm_delete: 'Cancel', cancel: 'Save changes', save: 'Delete account permanently'}`, hiding a destructive action behind the cancel label; the placeholder validator cannot see it, because plain UI strings carry no placeholders to compare. Verified end to end against a rotating stub: exit 5 and no file written, where the same run previously exited 0 with the keys transposed, and an honest endpoint on the same fixture is unaffected. The check requires **both** that the returned texts are a multiset match for the submitted ones and that at least one has moved position, so it cannot fire on a legitimate identity translation (source language equal to target, where nothing moves) or on one item whose translation happens to equal another item's source text, which a partially translated file produces. It is deliberately narrow: this catches the one reordering that is provable from the response alone, and an endpoint returning plausible **translations** in the wrong order remains undetectable, because the protocol carries no per-item identity to verify. It applies to every batch caller — `translate` on all 11 structured i18n formats, plain-text batches, and `sync` — since it sits in the one client method they share.
-
-- **sync, watch**: auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option, and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing: a `target_path_pattern` rendering a leading dash — `--pathspec-from-file={locale}` passes every existing pattern check, since none rejects a leading dash — reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set. `git commit` then ran with no pathspec, so it committed the whole index: a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` are affected; `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
-
-- **cache**: the resolved API base URL is now part of every translation, `write`, and `correct` cache key. One `cache.db` is shared by every endpoint a config directory has ever talked to, and the key hashed 20 request parameters but not who was going to answer them — so a single `deepl translate "hello" --to DE --api-url http://127.0.0.1:18111` served that endpoint's answer back for `api.deepl.com` for the full 30-day TTL, with no network reachable at all. Custom endpoints are a supported feature (proxies, regional endpoints), so this needed nothing the tool discourages: pointing the CLI at a local stub once was enough to make its output the cached truth everywhere. Verified end to end against two stub endpoints returning different text for the same request: each now gets its own row, and neither can answer for the other or for the real API. The endpoint is derived from the same expression the HTTP transport uses (`resolveClientBaseUrl`) rather than a second copy that could drift, and the free and Pro endpoints are keyed apart too. `CACHE_SCHEMA_VERSION` moves to 3, so opening an existing DB drops its `translation:`, `write:`, and `correct:` rows — every one of those keys changed, and retiring them is also what clears any entry a custom endpoint already poisoned. Other namespaces are untouched. Cache **writes** are deliberately still allowed for non-standard endpoints: with the endpoint in the key there is nothing left to cross-contaminate, and disabling them would cost proxy and regional-endpoint users their cache for no gain.
-
-- **sync**: the startup stale-backup sweep no longer writes anything, and no longer takes the whole project as its scope. It restored any **zero-length** file from a `<file>.deepl.bak` sibling, with no check that the sibling was a translation target, was matched by a bucket glob, was tracked, or that the backup came from this tool. A hostile checkout shipping an empty tracked file plus a `.deepl.bak` alongside it — any clone older than five minutes qualifies, since checkout stamps mtimes at clone time — therefore got bytes of its choosing written into that file during sync **startup**, before any translation, at exit 0, with a single `Logger.warn` as the only trace and the `.bak` unlinked immediately after. Because every target write goes through `atomicWriteFile`, which renames a fully-written temp file into place, a crash cannot leave a zero-length target: the restore branch had no legitimate trigger left and is removed, so the sweep only ever unlinks. Separately, a bucket glob beginning with a wildcard (`**/en.json`, `*.json`) has no literal prefix, and the old `path.dirname('')` fallback handed the sweep the entire project root to walk recursively — defeating the scoping the function exists to provide. Such a glob now contributes no sweep root, which means a bucket configured that way gets no stale-backup cleanup and may accumulate inert `.deepl.bak` files; run with `--verbose` to see when this is skipped.
-
-- **sync**: no sync path may resolve into `.git/` or `.github/` any more, closing a gap where the guard that exists to prevent exactly that was enforced on one branch only. `FORBIDDEN_TARGET_SEGMENTS` was checked against a literal `target_path_pattern`, so a bucket that simply omitted the pattern reached the default locale-substitution path unguarded: `buckets.yaml.include: ['.github/workflows/en.yml']` made `deepl sync` write `.github/workflows/de.yml` whose `run:` body was whatever the translation endpoint returned — CI workflow code under the influence of a hostile checkout or a hostile endpoint, at exit 0. The containment check on the project root accepted it, because the path never leaves the root. The check now sits on the resolved path inside `assertPathWithinRoot`, the one boundary every read and write in the pipeline passes through, so both the substitution branch and the multi-locale branch — which writes back to the source path and never calls `resolveTargetPath` at all — inherit it, and a future call site cannot forget it. A bucket rooted in `.github/` now fails at the source-file walk with exit 6 and a message naming the directory, before any translation request is made; the pattern-level check is kept as well, so a bad `target_path_pattern` is still reported at config load. Segments are compared relative to the project root, so a checkout living under a `.github` directory is unaffected, and `.gitlab/`, `.gitignore`, and paths merely containing `github` as a substring are untouched.
-
-- **sync**: glob patterns from `.deepl-sync.yaml` are bounded before they reach fast-glob, so a hostile checkout can no longer end the process with an uncatchable out-of-memory abort. fast-glob expands brace groups through `braces`, a different package from `brace-expansion` despite the name, and `braces` caps only its input length — the expansion it produces is a product with no bound at all. A 1007-byte `include` pattern of 200 `{a,b}` groups therefore killed `deepl sync` and `deepl sync validate` with `FATAL ERROR: Ineffective mark-compacts near heap limit` (SIGABRT, exit 134). An abort is not a JavaScript exception, so the per-bucket error handling could not contain it, and the tool's own generated pre-commit hook and documented CI step were killed the same way. Brace expansion is a product rather than a sum, so this needs very little input: 20 groups is 107 characters and already wedges the run. Every pattern-bearing field is now checked at config load — `buckets.*.include`, `buckets.*.exclude`, top-level `ignore`, and `context.scan_paths` — rejecting anything that expands past 1000 paths or exceeds 4096 characters with a `ConfigError` (exit 7) naming the field. The bound is a conservative over-approximation computed without expanding anything, it counts numeric and alpha ranges (`{1..9}`, `{a..e}`) by cardinality, and it folds unbalanced groups in as if closed so an unclosed `{` cannot smuggle a bomb past it. Neither cap is configurable, since the attacker in this scenario supplies the config; both sit below the point where `braces` itself throws, so its `RangeError` and `SyntaxError` paths are unreachable too. Realistic patterns are nowhere near the cap — `{en,de,fr}/**/*.{json,yaml,yml}` expands to 9.
-
-- **deps**: `brace-expansion` is pinned to `>=5.0.9` through an `overrides` entry, resolving GHSA-rgw5-rvv9-x895 (unbounded intermediate arrays) in the copy reached via `minimatch`. `npm audit --audit-level=moderate --omit=dev` — the gate `security.yml` runs on every push and nightly — was failing. It is an `overrides` entry rather than a dependency because the CLI does not import the package, and declaring it would fail `check-deps`.
-
-- **config**: `ConfigService.save()` writes through an unpredictably named temp file created with an exclusive flag, instead of a fixed `config.json.tmp`. A symlink planted at the predictable path redirected the config — which holds the API key in plaintext — to a path of the planter's choosing, and the subsequent rename left `config.json` as that symlink, so every later write followed it too. The mode is also applied with `chmod` after creation, which the umask cannot widen.
-
-- **tests**: The test suite no longer inherits real credentials or the real config directory. Suites that spawn the bare `deepl` command cannot be intercepted by nock, so they reached the live DeepL API with whatever key was exported and read and wrote the developer's cache database; cached responses matching this suite's fixtures were recovered from a real cache, confirming it had happened. `globalSetup` now clears `DEEPL_API_KEY`, `TMS_API_KEY` and `TMS_TOKEN` and points `DEEPL_CONFIG_DIR` at a temporary directory before workers fork.
-
-- **formats**: The prototype-pollution guard in the JSON parser is now pinned by tests. Replacing `Object.defineProperty` with plain assignment previously left the whole suite green: on a fresh object `obj['__proto__'] = value` retargets that object's prototype rather than `Object.prototype`, so the translation was silently dropped while the negative pollution assertion still passed.
-
-- **ci**: The release workflow refuses to create a GitHub Release when the pushed tag does not match `package.json`. A tag can be pushed at any commit, so without the check a mislabelled tag would mint a Release whose title disagrees with the version it contains.
-
-- **translate/sync**: Placeholder restoration no longer hangs the CLI with unbounded memory growth. `restorePlaceholders` looped `while (restored.includes(placeholder))`, replacing one occurrence per pass — so when the preserved original itself contained the placeholder token, every pass re-inserted it and the guard never went false. Measured before the fix: the input `{__VAR_0__}` grew from 9 to 400,009 bytes across 200,000 iterations without converging, and the real function had to be killed. It needed no attacker and no network: `preserveVariables`' pattern matches `{__VAR_0__}` (underscores and digits are in its character class), variable preservation runs unconditionally, and restoration also runs on **cached** results — so a locale value of that shape hung the process with no API call. Each placeholder is now restored in a single pass, using the function form of the replacement so `$&`/`$1` inside a preserved value stay literal.
-
-- **sync**: Bucket `include` globs can no longer escape the project root, and `--dry-run` no longer modifies the working tree. `include` entries were validated only as non-empty strings, while `target_path_pattern` a few lines later already rejected `..`. The unvalidated glob's literal prefix was resolved and handed to the stale-`.bak` sweep, which recursed with **no containment check** — deleting every old `*.bak` it found and *re-creating* any file whose `.bak` existed while the live file was missing or empty. Verified: `include: "../../../../../../**/*.json"` produced a sweep root of `/var`, an out-of-root `.bak` was deleted and its sibling resurrected with the backup's contents. Two things made it worse: the sweep was gated only on watch runs, so it ran under `--dry-run` — the flag a cautious user reaches for to avoid side effects — and its errors were swallowed entirely, so it was silent. `include` entries are now rejected at config load for traversal segments and absolute paths (the check the `sync init` wizard already applied, which simply did not exist on the load path), the sweep independently refuses any root outside the project and logs the attempt, the sweep is skipped under `--dry-run`, and its failures are reported instead of discarded.
-
-- **deps**: Resolved four production-dependency advisories flagged by `npm audit --omit=dev` via lockfile-only transitive bumps (no `package.json` ranges changed): `brace-expansion` 5.0.5 → 5.0.6 (GHSA-jxxr-4gwj-5jf2, ReDoS), `form-data` → 4.0.6 (GHSA-hmw2-7cc7-3qxx, CRLF injection), and `ws` 8.20.0 → 8.21.0 (GHSA-58qx-3vcg-4xpx and GHSA-96hv-2xvq-fx4p, uninitialized-memory disclosure and memory-exhaustion DoS). Production `npm audit` is back to zero vulnerabilities, unblocking the CI audit gate.
-
-- **deps**: Resolved two further `brace-expansion` denial-of-service advisories disclosed after the bump above: `brace-expansion` 5.0.6 → 5.0.8 (GHSA-3jxr-9vmj-r5cp, exponential-time expansion of consecutive non-expanding `{}` groups; GHSA-mh99-v99m-4gvg, unbounded expansion length causing an out-of-memory crash). Reached in production through `minimatch`, which accepts `^5.0.5`, so this is again a lockfile-only bump with no `package.json` range changes. Dev-tree instances of the same advisories are intentionally left in place: npm's proposed remediation downgrades `jest` 30 → 25 and `ts-jest` 29 → 27, `devDependencies` are not installed by consumers, and the CI audit gate is production-only.
-
-- **formats**: The YAML i18n parser no longer expands aliases at all, structurally removing the denial-of-service vector where documents with exponentially-expanding anchors ("alias bombs") or self-referential anchors hung `deepl sync` indefinitely. Aliased content is extracted and translated only at its anchor site and every alias — including merge keys — round-trips as a reference, so alias bombs now parse in milliseconds as plain references instead of being rejected by the interim expansion budget.
-
-- **formats**: Android XML translations containing `]]>` are refused instead of being written into a CDATA section, where they closed the section and had their remainder parsed as XML — injecting elements into generated resource files. This was reachable without a malicious API response, since a failed translation is written through verbatim and the source file is used as the template for a missing target locale.
-
-- **sync**: Target-path containment is enforced *before* any target file is read or backed up. The check previously ran after the read and the `.bak` copy, so a committed symlink directory plus a crafted `target_path_pattern` could read an out-of-root file into memory and clobber an out-of-root `.bak` sibling before the write was blocked — and the swallowed error made it repeat per locale × file. A containment violation now also aborts the sync instead of being absorbed, and the bucket pre-read loop (which had no containment check at all) now asserts it too.
-
+- **sync**: `deepl sync validate` was inert for PO and XLIFF buckets and reported the opposite of the truth. The gate compares each target value against its source, but for a bilingual format it read the msgid / `<source>` on both sides, so it was comparing the source against itself: a `msgstr` dropping a placeholder its msgid carries **exited 0** reporting `1 warning(s)`, and that warning was `Translation is identical to source text`, a false positive raised against every entry in every PO and XLIFF bucket, correct translations included. It now exits 8 with `ERROR es/Hello {name}: Missing placeholders in translation: {name}`. Anything using this as a CI gate on a PO or XLIFF project was gating on nothing.
+- **sync**: `--force` is refused (exit 6) when there is no terminal to confirm it on, instead of treating "nobody can answer" as yes. The guard threw for `CI=true` and prompted on a TTY with no third branch, so in a git hook, cron job, `make` target, container entrypoint, Jenkins agent or plain `deepl sync --force < /dev/null` the prompt was skipped and the run proceeded — inverting the fail-closed convention the seven other destructive sites inherit, for the single most destructive operation the CLI has, replacing reviewed translations with machine output with no backup surviving. **`--no-input` was ignored on the same path**, though it documents itself as aborting instead of prompting. Both now exit 6 with a message naming `--yes` as the only way to run `--force` unattended; an interactive decline is unchanged at exit 0 and now prints `Aborted.`. The gate is a single `canPrompt()` in `utils/confirm.ts` that `confirm()` itself uses, so the two cannot drift apart.
+- **sync**: A `tms.server` value in the checkout can no longer redirect the operator's environment-held `TMS_API_KEY` / `TMS_TOKEN` to a host of its choosing — `.deepl-sync.yaml` picked the destination and the only guard was scheme, not identity, so a hostile checkout plus `deepl sync push` delivered the credential and every translated string to a listener of its choice at exit 0. A hybrid **allowlist plus trust-on-first-use** now gates `createTmsClient`, so both `push` and `pull` are covered by one choke point: the hostname must appear in a new user-level `tms.allowedServers` list, or be approved once at a prompt that names the host and states that the credential and every translated string would go to it. An accepted answer is recorded in **user** config, never in the repository, so it survives a fresh clone and does not travel with the repo. Under `--no-input` or on a non-TTY the run fails closed at **exit 7**, naming the host and the exact `deepl config set tms.allowedServers <hosts>` command with the already-approved hosts preserved. Matching is exact and case-insensitive on the parsed hostname, ignoring scheme, port and path, with no wildcards, and entries carrying a scheme, port, path or `*` are rejected at `deepl config set` rather than stored as approval that could never match. Loopback is not exempt; a credential inlined as `tms.api_key`/`tms.token` is not gated, since it belongs to the same file that chose the destination. Both commands now also print the resolved destination origin on success, in text and in JSON (`"server"`), so a redirected destination is visible in logs even for an already-approved host.
+- **sync**: `deepl sync push`/`pull` no longer send the TMS credential and translated strings to a host the destination-trust gate never approved. A `tms.server` whose path begins with `//` — `https://approved.example.com//evil.example.com`, or `http://localhost//169.254.169.254` — parses with the approved hostname, which is what the gate and the HTTPS/localhost checks key off, but `buildUrl`'s relative resolution then sent the *request* to the other origin. The resolved request origin is now pinned to the approved one, with a `ConfigError` naming the redirected origin otherwise; a legitimate base path (`https://tms.example.com/tms`) is unaffected. The threat is a maliciously contributed `.deepl-sync.yaml` in a repo whose maintainer runs `deepl sync push`. CWE-918.
+- **cli**: Pointing the CLI at a non-DeepL endpoint is now announced, so the API key no longer travels to an unexpected host in silence. `isStandardDeepLUrl()` existed solely to detect this and was consumed by nothing; a `config.json` holding `api.baseUrl` redirected every request with nothing on any channel to say so, and `-v` printed the method and path but never the host. When the resolved endpoint is neither `api.deepl.com` nor `api-free.deepl.com`, an unconditional warning names the **origin** the key is going to and where the redirect came from — `set by --api-url`, or `set by api.baseUrl in /path/to/config.json`, the real resolved path, which is what makes a substituted config visible. Only the origin is rendered, terminal-sanitized, since the path and query are chosen by whatever did the redirecting. It is not gated behind `--verbose` (though `--quiet` suppresses it, like every other warning), goes to stderr, fires once per run rather than once per client, and exempts neither loopback nor regional endpoints such as `api-jp.deepl.com`. The verbose request line now names the resolved origin, and `ConfigService` gained a `configFilePath` accessor.
+- **api**: An endpoint that keeps sending is now bounded in both bytes and wall-clock time. The shared axios instance never set `maxContentLength` or `maxBodyLength`, which default to unbounded, so a response body was buffered until the process died — and `--timeout` did not save the run, because axios delivers it to the socket as an *inactivity* timeout that every arriving chunk reset. A stub streaming 1 MiB chunks forever reached 8572 MB RSS and was still running, un-aborted, four times past the configured deadline; a stub trickling one byte per second stayed under any byte cap indefinitely while pinning the process. Two changes: a finite 32 MiB response cap and 128 MiB body cap on the shared instance, and an `AbortController` deadline armed per attempt inside the retry loop, which is wall-clock and therefore not resettable by the peer. The document download raises its response cap to 128 MiB, since a converted result can exceed its source and that endpoint is deliberately never retried — rejecting there would destroy an already-billed translation — while status polling and the other nine clients keep the tighter default. Both bounds surface as `NetworkError` (exit 5), the size cap naming the limit it hit, and a size-cap rejection is not retried, since the verdict is deterministic.
+- **api**: A batch translation response that returns the submitted texts themselves, rearranged, is refused instead of written out. `POST /v2/translate` correlates a translation to its request item by position and by nothing else, and the only check was that the counts matched — so an endpoint returning the request's own texts rotated by one wrote each translation under the wrong i18n key at exit 0, hiding a destructive action behind a cancel label, which the placeholder validator cannot see because plain UI strings carry no placeholders to compare. Such a response now exits 5 with nothing written. The check requires **both** a multiset match against the submitted texts and at least one moved position, so it cannot fire on a legitimate identity translation or on one item whose translation equals another item's source text. It sits in the one client method every batch caller shares — `translate` on all 11 structured formats, plain-text batches, and `sync`. An endpoint returning plausible translations in the wrong order remains undetectable, since the protocol carries no per-item identity.
+- **cli, sync**: Text the CLI did not author can no longer drive the terminal that renders it. Translation text went from the API to stdout raw and i18n keys went from a checkout to stdout raw, so both could carry terminal control sequences — and the key sink needs no API key and no network: an evil checkout plus `deepl sync validate` emitted an OSC 52 clipboard write and a CSI 2J screen erase verbatim, and `hooks install` puts that command in the pre-commit hook, so it fires on every commit. Two layers close it. Untrusted values interpolated into report lines are sanitized at the call site, unconditionally — the locale, key and message in `sync validate`, and the choice labels in `write`/`correct --interactive`, where the value handed back to the caller stays raw so only the display is affected. And the logger neutralizes control sequences centrally, covering all 111 `Logger.output` call sites and every stderr sink by construction. stderr is sanitized whether or not it is a TTY, because CI log viewers interpret ANSI; **stdout is sanitized only when it is a terminal**, because redirected stdout is data and `deepl translate ... > out.txt` must reproduce the API's bytes exactly — the same rule `ls` and `git` apply. Colour (SGR) sequences survive, since chalk-formatted strings arrive already rendered, while OSC title and clipboard writes, CSI erase and cursor moves, and the status queries whose reply is typed back on the shell's stdin are all neutralized. The stream filter is a separate, narrower function from `sanitizeForTerminal`, which replaces newlines, tabs and U+200B-U+200F and would therefore have corrupted legitimate content in Persian, Arabic, Devanagari and emoji sequences.
+- **formats**: No writer emits a raw C0 control byte into a repo file. Six of the nine writers escaped only their own quoting characters plus `\n`/`\r`/`\t`, so any other control byte in a translation was written through untouched, putting live terminal-control sequences into source-controlled files where `git diff`, `cat`, `less` and CI log viewers all render them. **No API call is needed to trigger it**: a contributor commits a *valid* `locales/app.de.toml` holding `greeting = "Hola\u001B[2J"` — TOML basic strings legally carry `\uXXXX` and the parser decodes it to a raw ESC — the key is then `current`, so it is never translated and never validated, and the writer put the byte back out raw. That is quieter and worse than the file simply failing later: `deepl sync` exits 0 and says nothing, because the target-file read treats a parse failure as "no existing translations", and `deepl sync status` reports `100% (0 missing, 0 outdated)` for a file it cannot parse. Android XML and XLIFF are worse still, since every C0 byte except tab, LF and CR is outside XML 1.0's `Char` production, so there is no escape and no numeric character reference for it and expat, `aapt2` and every conforming CAT tool reject the written file. One shared rule now lives in `src/formats/util/control-chars.ts` and each writer applies it the way its own format allows: TOML escapes as `\uXXXX` (forcing the double-quoted form where a literal string could not escape, plus U+007F), `.properties` extends its existing `\uXXXX` rule below U+0020, iOS Strings emits `\UXXXX`, which its own reader already decodes, PO gains the missing `\r` escape and refuses the rest with a `ValidationError` naming the entry, and Android XML and XLIFF refuse with a `ValidationError` naming the resource or trans-unit. Each message names the codepoint (`U+001B`) rather than quoting a byte that prints as nothing.
+- **sync**: A source catalog can no longer smuggle one string into another string's key. Five parsers encode hierarchical key identity in-band with no escaping — PO joins `msgctxt` and `msgid` with U+0004, YAML joins path segments with U+0000, and JSON, Laravel PHP and Android XML join with `.` — so a key component holding the separator resolved to the same key as an unrelated entry, and the two control bytes **print as nothing**, so the source diff showed an ordinary string. A PO catalog carrying U+0004 inside one `msgid` extracted the same key as a legitimate `msgctxt`/`msgid` pair, and reconstruct wrote the smuggled entry's translation into that pair's `msgstr`: the attacker picks the source text, DeepL translates it, and the result lands in the victim key's slot in every locale. The stronger case needs no collision at all — one such `msgid` in a catalog with no `msgctxt` anywhere forged a context-qualified entry the source never had, in every target `.po`, which a duplicate-key check alone would have missed. For the `.`-joining formats the damage is a lost or corrupt file rather than a forgery: a flat `"a.b"` beside a nested `a: { b: ... }` rewrote both slots to one translation, an Android `<string name="items.0">` colliding with `<string-array name="items">` was deleted from the output, and the Laravel case emitted PHP the CLI's own parser then refuses. PO and YAML now reject the reserved byte at both key-construction sites (extract, and the target-file read inside reconstruct), quoting it back escaped as `\u0004` / `\u0000` rather than echoing a byte that prints as nothing; JSON, Laravel PHP and Android XML assert their extract output has distinct keys, which for those three is exactly equivalent to detecting a separator collision. `sync` skips the one file with a warning naming the colliding key and finishes the rest of the run at exit 0, following the existing per-file convention, since one hostile file must not discard the lockfile for work already translated and billed. `sync pull` reading a **target** file whose keys collide leaves it untouched and records a `key_collision` skip rather than falling through to the source template, which would have rebuilt the locale down to the single key the export carried. `.properties` and XLIFF are deliberately excluded, since a literally repeated key is legal in both.
+- **sync**: An i18n key named `__proto__` is recorded in the lockfile instead of vanishing from it, so it is no longer re-translated and re-billed on every run, forever — every write into the entry maps was a plain assignment, so for that one name it reached the prototype setter and the run reported `3/3 keys` while the lockfile came back with two entries and `total_keys: 2`, with no run ever converging. The same shape applied to a **source path** named `__proto__`, which fell out of `entries` wholesale and took every key in that file with it. The read side needed the same treatment for a different reason: plain indexing hands back inherited members, so keys named `constructor`, `toString`, `valueOf` or `hasOwnProperty` read as an existing lock entry missing every field it should have, and `computeDiff` classified all four as **stale** rather than new on a first sync. Three shared accessors (`setOwnMember` / `getOwnMember` / `ensureFileEntries`) are applied at every access site across six files, including two in `sync-status.ts` and `sync-locale-translator.ts`, and the key-sorting JSON replacer is fixed the same way.
+- **sync**: A lockfile is checked member by member before sync uses it, instead of being version-checked and then cast. Six shapes from a hostile or merge-mangled repository were reproduced by execution: a missing `stats` crashed at exit 1 **after** the endpoint had been hit and the target file written, leaving the attacker's stub as the lockfile so the next run re-billed everything; an entry with no `translations` container crashed, and took the read-only `sync status` down with it; a per-file map that is a string crashed; `entries` as an array was accepted silently at exit 0, with the run's results written onto array properties and then discarded, so the lockfile recorded `"entries": []` beside `total_keys: 2` and every later run re-billed the project in silence, forever; and a null translation and a string `stats` each crashed one level deeper. Every one of them now exits 0 with a well-formed lockfile. **Malformed members are dropped individually, not by discarding the file** — resetting a whole lockfile over one bad member would hand whoever wrote it a full re-translation of the project — with the count reported at WARN level and the original copied to `.deepl-sync.lock.bak-v1-malformed-<timestamp>`; `entries` that is not a map at all has nothing to salvage and takes the existing full-sync path with its own `-entries-not-a-map` tag. **`stats` is no longer trusted at all**: it is derived from `entries` and recomputed on read and on every write, so its counts can no longer disagree with the entries they describe. The repaired `entries` is rebuilt with `setOwnMember`, so a source path or key named `__proto__` is carried across as an own property.
+- **sync**: `sync pull` no longer records `review_status: human_reviewed` for content it never verified was reviewed. Every key a pull applied was stamped `human_reviewed` in `.deepl-sync.lock` unconditionally, although the documented export contract is a flat map with no per-entry review flag — so a TMS that exports machine-translation drafts had them recorded in a committed file as human-reviewed, and where the `tms.server` in a checkout is not one the operator chose, the endpoint controls the strings *and* the review label attached to them. Pulled entries now record `status: translated` with **no** `review_status`, which is the type's way of saying "unknown"; `human_reviewed` is still honoured when a person or another tool writes it, and `--flag-for-review` still writes `machine_translated`.
+- **translate**: A document upload response can no longer choose where this client sends its own follow-up requests. The `document_id` from `POST /v2/document` was interpolated into the status and result paths with no encoding and no format check, and the endpoint supplying it is redirectable via `--api-url`, `api.baseUrl` or a proxy: against a stub answering a traversal-shaped `document_id`, the client's next two request lines arrived on a completely different route, and the run finished at **exit 0** reporting success after writing the stub's JSON body into the output file as if it were a translated PDF. `document_id` is now checked against `[A-Za-z0-9_-]+` at both interpolation sites, so a redirected first response stops the workflow at exit 5 (`NetworkError`, since nothing the user typed is wrong) with the ID quoted back, nothing further sent and no output file written; a response with no `document_id` at all, which was reaching the wire as the literal path `/v2/document/undefined`, is refused by the same check. The polling loop re-sends the original handle rather than the ID echoed by each status response, so a clean first response cannot be followed by a poisoned second one. This was the last unguarded interpolation of an untrusted value into a URL path in the API layer.
+- **logger**: The credential redactor no longer has two holes that between them defeated its own documented invariant. **Hole one: any object that was not a plain object, an array or an `Error` was returned live** — an `Error` whose `config.headers` is an `AxiosHeaders` instance printed `Authorization: 'DeepL-Auth-Key SUPER-SECRET-KEY-FROM-CONFIG'` verbatim through `util.inspect`, while the sibling plain-object field on the same error was redacted correctly, and `Map`/`Set` leaked worse still, since their contents are not own properties at all. Every object is now rebuilt property by property on its own prototype, so `util.inspect` still names the class while never receiving the original instance, and `Map`/`Set` are rebuilt with their keys and members mapped; `Date`, `RegExp`, `ArrayBuffer` and its views pass through deliberately, since their payload is not in string-keyed own properties and none of them renders a credential as readable text. Properties are `defineProperty`'d, so an own key named `__proto__` lands on the copy instead of reaching the prototype setter. **Hole two: the literal-value backstop read only `process.env`, while a config-file key wins precedence over it** — so with a key in `config.json` and a different one in `DEEPL_API_KEY`, the value actually on the wire was precisely the one the redactor could not see, reproduced against a loopback stub that echoed it back in an error body. A new `Logger.registerSecret()` closes it, called from the `HttpClient` constructor — the one place that sees whichever key won precedence, because it is where the key is attached to every request — and from the `TmsClient` constructor, which covers a `tms.api_key` or `tms.token` inlined in `.deepl-sync.yaml`. Redaction also recurses through objects, arrays and `Error` values with cycle protection rather than applying only to strings.
+- **hooks**: `deepl hooks list` no longer reports attacker-authored content as an installed DeepL hook, and the integrity check it already had is now on a path a user can reach. `isDeepLHook()` fell back to a **bare substring match**, so a file mentioning the marker anywhere, on any line, in any context passed as a hook this CLI installed; and `verifyIntegrity()` — which parses the `# DeepL CLI Hook v1 [sha256:...]` marker, rehashes the body and compares — was referenced by nothing but its own definition and its unit tests, so the recorded hash was never checked outside the test suite. A repository shipping a tracked `.githooks/pre-commit` with a forged marker plus a payload, wired up with `git config core.hooksPath .githooks` (the husky pattern), was reported `✓ pre-commit installed`, with `--format json` saying `true`. `list` now reports one of four states per hook — `installed` (versioned marker present and the body hashes to what it records), `modified`, `unverified` (legacy pre-1.0 marker, no hash to check), `not-installed` — so the forged hook reads `! pre-commit installed, content does not match its recorded hash` and the quoted-marker file reads `not installed`. The legacy marker is now anchored to a whole line the way the versioned one always was. The output states plainly that the hash detects a change made after the marker was written and **cannot establish authorship**, because it is unkeyed — anyone who can write the hook can compute a matching marker — so `modified` renders in yellow and gives both readings rather than accusing, since the README invites customizing an installed hook. Tightening `isDeepLHook` also makes `uninstall` refuse to delete a file whose marker is only quoted, and makes `install` back such a file up instead of overwriting it.
+- **hooks**: `deepl hooks install` no longer writes an executable outside the repository because the repository told it to. `resolveHooksDir` asks `git rev-parse --git-path hooks`, which faithfully honours `core.hooksPath` including an absolute path anywhere on the filesystem, and the install then did an unconditional write plus `chmod 0755` with no containment check — and `core.hooksPath` is repository-local git config, so it travels with a checkout rather than coming from the person running the command: `git config core.hooksPath /outside/dir` followed by `deepl hooks install pre-commit` printed success, exited 0, and left an `0755` script there with nothing on any channel to say the write had left the project. An install whose hooks directory falls outside the working tree now names the configured value and the resolved directory and asks first; declining, or having no terminal to ask on, **exits 6 and writes nothing**, while `-y, --yes` accepts it and still prints the notice to stderr so a scripted install records where the executable went. The refusal lives in `GitHooksService.install`, which needs an explicit `allowExternal` to proceed, so a caller that forgets to prompt cannot skip the gate. Only the **repository-local** setting is consulted — a global `core.hooksPath` is the user's own machine-wide choice — which is also what keeps linked worktrees and submodules quiet; containment is checked **through symlinks**; and `uninstall` is left alone, since it already refuses to remove anything that is not a DeepL hook. The predicate is now `isWithinDirectory` in `src/utils/paths.ts`, shared with `assertPathWithinRoot`.
+- **config**: The `0600` mode on the file holding the plaintext API key is enforced on every load, not just asserted at creation. `config.json` is created `0600` and its directory `0700`, and neither was ever checked again, so a file restored from a tar or dotfiles backup, copied by `rsync`, or written by hand kept whatever mode it arrived with, forever, while `load()` read it with no `stat`, no repair and no warning. A group- or world-reachable config file is now tightened back to `0600` on load and the run says what it found — naming the mode, that other users on the machine can read it, that the key may already have been read, and `deepl auth set-key` to rotate it — and the warning is self-extinguishing, since the next run finds `0600`. **The directory is deliberately reported rather than repaired**: its dirname is not always a directory the CLI owns, and `deepl -c ~/deepl.json` would have chmod'd the user's home directory to `0700`, so it names the mode and the `chmod 700` that would close it and changes nothing. Only the **write** bits are reported, since a merely traversable `0755` directory does not let anyone replace the file inside it; **sticky directories are exempt**, because mode `1777` is exactly the arrangement that makes a shared temp directory safe; and the cache directory gets the same report, while `cache.db` needed nothing, being `0600` on every open. Both `mkdir` sites are now unconditional recursive calls, closing the window where a directory could appear between an `existsSync` and a create. Nothing refuses to run over a permission: the mode of the file is not a reason to reject the settings in it.
+- **config**: `ConfigService.save()` writes through an unpredictably named temp file created with an exclusive flag instead of a fixed `config.json.tmp`, where a planted symlink redirected the config — which holds the API key in plaintext — to a path of the planter's choosing, and the subsequent rename left `config.json` as that symlink so every later write followed it too. The mode is applied with `chmod` after creation, which the umask cannot widen.
+- **config**: `deepl config set` rejects `__proto__`, `constructor` and `prototype` path segments and resolves keys with `Object.hasOwn`, so crafted paths cannot pollute `Object.prototype`.
+- **sync**: A sync target path can no longer begin with `-`, closing the defense-in-depth half of the `git add`/`git commit` option-injection fix. The argv side was already fixed, but `.deepl-sync.yaml` could still name a target that *looks* like an option — `target_path_pattern: --pathspec-from-file={locale}` satisfied all four existing checks (a string, contains `{locale}`, no `..`, no `.git`/`.github` segment) — and there were **three** routes to a dash-leading target: the literal pattern, a `{basename}` taken from a source file whose own name begins with `-`, and the default locale-substitution branch running over a dash-leading source directory, which involves no pattern at all. Two tiers now apply, mirroring how `FORBIDDEN_TARGET_SEGMENTS` is enforced twice: a literal pattern beginning with `-` fails at config load with `ConfigError` (exit 7), and every path `resolveTargetPath` renders is checked again with `ValidationError` (exit 6), which is the only tier the other two routes pass through. **Only the first segment** is checked, since the rendered path is one argv entry and a dash later in it is never option-like, so `res/values-{locale}/strings.xml`, `locales/zh-Hans.json` and `locales/-legacy/{locale}.json` all still resolve.
+- **sync, watch**: Auto-commit passes staged paths after a `--` separator and commits with `--only`, so a translation target path can no longer be read by git as an option and the commit can no longer carry anything else the user had staged. `execFile` prevents shell injection but not git's own option parsing, so a `target_path_pattern` rendering a leading dash reached `git add` as a flag and staged files of the pattern author's choosing, defeating the auto-commit preflight that exists to bound the staged set; `git commit` then ran with no pathspec and committed the whole index, so a separately staged `.env.local` or unfinished work landed in a `chore(i18n)` commit whose message described only the translation. Both `sync --auto-commit` and `watch --auto-commit` were affected — `sync` was partly shielded by its unrelated-modifications preflight, `watch` was not.
+- **cache**: The resolved API base URL is now part of every translation, `write` and `correct` cache key. One `cache.db` is shared by every endpoint a config directory has ever talked to, and the key hashed 20 request parameters but not who was going to answer them — so a single `deepl translate "hello" --to DE --api-url http://127.0.0.1:18111` served that endpoint's answer back for `api.deepl.com` for the full 30-day TTL, with no network reachable at all. Custom endpoints are a supported feature (proxies, regional endpoints), so this needed nothing the tool discourages: pointing the CLI at a local stub once was enough to make its output the cached truth everywhere. The endpoint is derived from the same expression the HTTP transport uses (`resolveClientBaseUrl`) rather than a second copy that could drift, and the free and Pro endpoints are keyed apart. `CACHE_SCHEMA_VERSION` moves to 3, so opening an existing DB drops its `translation:`, `write:` and `correct:` rows — every one of those keys changed, and retiring them also clears any entry a custom endpoint already poisoned. Other namespaces are untouched, and cache **writes** are deliberately still allowed for non-standard endpoints, since with the endpoint in the key there is nothing left to cross-contaminate.
+- **sync**: The startup stale-backup sweep no longer writes anything, and no longer takes the whole project as its scope. It restored any **zero-length** file from a `<file>.deepl.bak` sibling, with no check that the sibling was a translation target, was matched by a bucket glob, was tracked, or came from this tool — so a hostile checkout shipping an empty tracked file plus a `.deepl.bak` alongside it (any clone older than five minutes qualifies, since checkout stamps mtimes at clone time) got bytes of its choosing written into that file during sync **startup**, before any translation, at exit 0, with a single warning as the only trace and the `.bak` unlinked immediately after. Because every target write goes through `atomicWriteFile`, which renames a fully written temp file into place, a crash cannot leave a zero-length target: the restore branch had no legitimate trigger left and is removed, so the sweep only ever unlinks. Separately, a bucket glob beginning with a wildcard (`**/en.json`, `*.json`) has no literal prefix, and the old fallback handed the sweep the entire project root to walk recursively, defeating the scoping the function exists to provide. Such a glob now contributes no sweep root, which means a bucket configured that way gets no stale-backup cleanup and may accumulate inert `.deepl.bak` files; run with `--verbose` to see when this is skipped.
+- **sync**: No sync path may resolve into `.git/` or `.github/`. `FORBIDDEN_TARGET_SEGMENTS` was checked against a literal `target_path_pattern`, so a bucket that simply omitted the pattern reached the default locale-substitution path unguarded: `buckets.yaml.include: ['.github/workflows/en.yml']` made `deepl sync` write `.github/workflows/de.yml` whose `run:` body was whatever the translation endpoint returned — CI workflow code under the influence of a hostile checkout or a hostile endpoint, at exit 0 — and the containment check on the project root accepted it, because the path never leaves the root. The check now sits on the resolved path inside `assertPathWithinRoot`, the one boundary every read and write in the pipeline passes through, so the substitution branch and the multi-locale branch (which writes back to the source path and never calls `resolveTargetPath` at all) both inherit it, and a future call site cannot forget it. A bucket rooted in `.github/` now fails at the source-file walk with exit 6 and a message naming the directory, before any translation request; the pattern-level check is kept as well. Segments are compared relative to the project root, so a checkout living under a `.github` directory is unaffected, and `.gitlab/`, `.gitignore` and paths merely containing `github` as a substring are untouched.
+- **sync**: Glob patterns from `.deepl-sync.yaml` are bounded before they reach fast-glob, so a hostile checkout can no longer end the process with an uncatchable out-of-memory abort. fast-glob expands brace groups through `braces`, which caps only its *input* length while the expansion it produces is a product with no bound at all: a 1007-byte `include` pattern of 200 `{a,b}` groups killed `deepl sync` and `deepl sync validate` with `FATAL ERROR: Ineffective mark-compacts near heap limit` (SIGABRT, exit 134) — and an abort is not a JavaScript exception, so the per-bucket error handling could not contain it, and the tool's own generated pre-commit hook and documented CI step were killed the same way. Because the expansion is a product, this needs very little input: 20 groups is 107 characters and already wedges the run. Every pattern-bearing field is now checked at config load — `buckets.*.include`, `buckets.*.exclude`, top-level `ignore` and `context.scan_paths` — rejecting anything that expands past 1000 paths or exceeds 4096 characters with a `ConfigError` (exit 7) naming the field. The bound is a conservative over-approximation computed without expanding anything, counts numeric and alpha ranges (`{1..9}`, `{a..e}`) by cardinality, and folds unbalanced groups in as if closed so an unclosed `{` cannot smuggle a bomb past it. Neither cap is configurable, since the attacker in this scenario supplies the config, and realistic patterns are nowhere near it (`{en,de,fr}/**/*.{json,yaml,yml}` expands to 9).
+- **sync**: Bucket `include` globs can no longer escape the project root, and `--dry-run` no longer modifies the working tree. `include` entries were validated only as non-empty strings while `target_path_pattern` a few lines later already rejected `..`, and the unvalidated glob's literal prefix was resolved and handed to the stale-`.bak` sweep, which recursed with **no containment check** — deleting every old `*.bak` it found and re-creating any file whose `.bak` existed while the live file was missing or empty. Verified: `include: "../../../../../../**/*.json"` produced a sweep root of `/var`, an out-of-root `.bak` was deleted and its sibling resurrected with the backup's contents. Two things made it worse: the sweep was gated only on watch runs, so it ran under `--dry-run` — the flag a cautious user reaches for to avoid side effects — and its errors were swallowed entirely. `include` entries are now rejected at config load for traversal segments and absolute paths (the check the `sync init` wizard already applied and the load path did not), the sweep independently refuses any root outside the project and logs the attempt, it is skipped under `--dry-run`, and its failures are reported instead of discarded.
+- **sync**: Target-path containment is enforced *before* any target file is read or backed up. The check previously ran after the read and the `.bak` copy, so a committed symlink directory plus a crafted `target_path_pattern` could read an out-of-root file into memory and clobber an out-of-root `.bak` sibling before the write was blocked — and the swallowed error made it repeat per locale × file. A containment violation now aborts the sync instead of being absorbed, and the bucket pre-read loop, which had no containment check at all, asserts it too.
 - **sync**: `source_locale` and `target_locales` are validated against a BCP-47 whitelist at config load (previously a three-substring denylist), and `target_path_pattern` may not contain a `.git` or `.github` path segment — closing a write primitive where a "locale" like `config` plus a pattern like `.git/{locale}` wrote inside `.git/`. **Migration**: underscore-style locale codes (`pt_BR`) are now rejected; use hyphenated BCP-47 (`pt-BR`).
-
 - **sync**: `.deepl-sync.yaml` discovery stops at the repository boundary (the first directory containing `.git`) instead of walking to the filesystem root, so a config planted in an ancestor directory outside the repo is no longer silently adopted as project root.
-
+- **translate/sync**: Placeholder restoration no longer hangs the CLI with unbounded memory growth. `restorePlaceholders` looped `while (restored.includes(placeholder))`, replacing one occurrence per pass, so when the preserved original itself contained the token every pass re-inserted it and the guard never went false — the input `{__VAR_0__}` grew from 9 to 400,009 bytes across 200,000 iterations without converging. It needed no attacker and no network: `preserveVariables`' pattern matches that shape, variable preservation runs unconditionally, and restoration also runs on **cached** results, so a locale value of that shape hung the process with no API call. Each placeholder is now restored in a single pass, using the function form of the replacement so `$&`/`$1` inside a preserved value stay literal.
+- **formats**: A translated Android string can no longer break out of its CDATA section. `escapeForReconstruct` wrapped the translation in a CDATA section with no escaping, so a value containing `]]>` closed the section early and the remainder was parsed as XML, allowing extra `<string>` elements into a generated resource file. This was reachable without a malicious API response, since on translation failure the source string is written through verbatim and the source file is the template when the target locale file does not exist yet. Occurrences of `]]>` are now split across adjacent CDATA sections, which keeps the text literal, and extract concatenates adjacent sections so such values round-trip unchanged.
+- **formats**: The YAML i18n parser no longer expands aliases at all, structurally removing the denial-of-service vector where documents with exponentially expanding anchors ("alias bombs") or self-referential anchors hung `deepl sync` indefinitely. Aliased content is extracted and translated only at its anchor site and every alias, merge keys included, round-trips as a reference, so alias bombs now parse in milliseconds as plain references instead of being rejected by an expansion budget.
+- **tests**: The test suite no longer inherits real credentials or the real config directory. Suites that spawn the bare `deepl` command cannot be intercepted by nock, so they reached the live DeepL API with whatever key was exported and read and wrote the developer's cache database — cached responses matching this suite's fixtures were recovered from a real cache, confirming it had happened. `globalSetup` now clears `DEEPL_API_KEY`, `TMS_API_KEY` and `TMS_TOKEN` and points `DEEPL_CONFIG_DIR` at a temporary directory before workers fork.
 - **init**: `deepl init` masks the API-key prompt instead of echoing the key in cleartext into terminal scrollback.
-
-- **logger**: Credential redaction now recurses through objects, arrays, and `Error` values (with cycle protection) instead of applying only to strings, so a dumped error object can no longer print an `Authorization` header or API key verbatim.
-
-- **glossary**: Server-supplied glossary names are sanitized before terminal display, blocking ANSI escape injection via glossaries shared within a team account. Style-rule names were already sanitized; the two sites now match.
-
-- **config**: `deepl config set` rejects `__proto__`, `constructor`, and `prototype` path segments and resolves keys with `Object.hasOwn`, so crafted paths can no longer pollute `Object.prototype`.
-
-- **batch**: `translate --pattern` values containing `..` can no longer write translated output outside `--output-dir` (the default output branch now enforces the same containment as `--output-pattern`), and directory batch translation no longer follows symlinks out of the input directory.
-
+- **glossary**: Server-supplied glossary names are sanitized before terminal display, blocking ANSI escape injection via glossaries shared within a team account; style-rule names were already sanitized and the two sites now match.
+- **batch**: `translate --pattern` values containing `..` can no longer write translated output outside `--output-dir` — the default output branch now enforces the same containment as `--output-pattern` — and directory batch translation no longer follows symlinks out of the input directory.
+- **deps**: `brace-expansion` is pinned to `>=5.0.9` through an `overrides` entry, resolving GHSA-rgw5-rvv9-x895 (unbounded intermediate arrays) in the copy reached via `minimatch`; it is an `overrides` entry rather than a dependency because the CLI does not import the package and declaring it would fail `check-deps`. Earlier lockfile-only bumps in this release resolved GHSA-jxxr-4gwj-5jf2 (ReDoS), GHSA-3jxr-9vmj-r5cp and GHSA-mh99-v99m-4gvg (exponential-time expansion and unbounded expansion length) in the same package, GHSA-hmw2-7cc7-3qxx in `form-data` (CRLF injection), and GHSA-58qx-3vcg-4xpx / GHSA-96hv-2xvq-fx4p in `ws` (uninitialized-memory disclosure and memory-exhaustion DoS). Production `npm audit` is back to zero vulnerabilities. Dev-tree instances of the brace-expansion advisories are intentionally left in place: npm's proposed remediation downgrades `jest` 30 → 25 and `ts-jest` 29 → 27, `devDependencies` are not installed by consumers, and the CI audit gate is production-only.
 - **ci**: `ci.yml` and `security.yml` explicitly request `contents: read` instead of inheriting the repository default token permissions.
 
 ## [1.2.0] - 2026-04-25

From 7874cf7476f443766d8b44ecfb26996f6db506aa Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:25:48 +0200
Subject: [PATCH 239/256] docs(readme): correct fabricated output, the
 quiet-mode contract and repo links
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Audited every claim against the built CLI. The output samples were the worst of it --
several showed lines the CLI has never printed, and in three cases a correct sample sat
in the same code block as a wrong one.

Measured and corrected: `auth show` prints one masked line, not a `Status: Valid` line
and not an `Account type:` line (neither string exists in src/). `config set` prints
`✓ Set <key> = <raw value>`, echoing the value as typed -- not
`✓ Configuration updated:` with the value re-rendered as a JSON array, while the
`tms.allowedServers` example three lines below already had it right. `glossary create`
prints a fixed success line followed by the full info block, so the name and ID are on
their own lines and `Created:` was missing. `glossary delete` prints
`✓ Glossary deleted successfully` and does not interpolate the name. `detect --format
json` is pretty-printed, not one line.

Two blockers. `--target` is not a flag -- it is `--target-lang`, named correctly in the
adjacent example and twice more, so the two prose mentions were the outliers; the
documented-surface test cannot catch them because it only reads flags off `deepl ` lines.
And the quiet-mode section promised "errors and critical warnings" are always shown while
recommending `--quiet` for CI: `Logger.warn` is gated on quiet exactly like `info`, so
every warning is suppressed -- including the notice that `--api-url` is sending your API
key to a host that is not DeepL. That section also used `API Key: ...` to illustrate what
quiet suppresses, which goes through `Logger.output` and is never suppressed, and showed
the untranslated input as normal mode's output, teaching that quiet mode is what makes
the translation appear.

The Authentication section taught `auth set-key YOUR_API_KEY` as the way to set a key,
which the CLI warns about as deprecated and which Quick Start already flags. It now leads
with `--from-stdin`, documents `--no-verify`, and keeps the argument form with its reason.

Two gaps a script author would hit: `--format table` falls back to plain `[lang] text`
off a TTY, and under `--format json` a failing command writes its error envelope to
stdout -- the v2 change most relevant to the CI gate the README teaches, and absent from
the only place the file shows JSON shapes.

Repo links are now absolute GitHub URLs. npmjs.com resolves relative links against the
registry page, so all 26 `./docs/...`, `./examples/...`, `./CHANGELOG.md` and `./CLAUDE.md`
links 404 on the page a 1.x user lands on after `npm install -g @deepl/cli` -- including
the migration guide inside the "Upgrading from 1.x" section.

Also: the architecture block put TmsClient in the API layer (it is src/sync/tms-client.ts)
and called the cache generically SQLite where the Node 24 floor comes from `node:sqlite`;
TOC nesting put two config sections under Global Options and filed Command Suggestions
under Information; the `correct` flag list read as exhaustive while omitting four flags,
one used in the example above it; watch's nested output layout was undocumented; and the
Homebrew note promised a tap "shortly after the first npm release".

Verified: 125 languages = core 32 + regional 11 + extended 82, the 14 Write languages,
every documented default (timeout 30000, retries 3, concurrency 5, debounce 500ms,
100 KiB, batch 50, 30 MB, glossary max 5), and all 39 TOC anchors.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 136 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 81 insertions(+), 55 deletions(-)

diff --git a/README.md b/README.md
index 1fad9aa1..49afb1dd 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@
 - **🗝️ Admin API** - Organization key management and usage analytics
 - **🔒 Privacy-First** - Local caching, no telemetry, secure key storage
 
-For security policy and vulnerability reporting, see [SECURITY.md](SECURITY.md).
+For security policy and vulnerability reporting, see [SECURITY.md](https://github.com/DeepL/deepl-cli/blob/main/SECURITY.md).
 
 ## 📋 Table of Contents
 
@@ -37,16 +37,15 @@ For security policy and vulnerability reporting, see [SECURITY.md](SECURITY.md).
 - [Global Options](#-global-options)
   - [Verbose Mode](#verbose-mode)
   - [Quiet Mode](#quiet-mode)
+  - [Command Suggestions](#command-suggestions)
   - [Custom Configuration Files](#custom-configuration-files)
   - [Configuration Paths](#configuration-paths)
-    - [Proxy Configuration](#proxy-configuration)
-    - [Retry and Timeout Configuration](#retry-and-timeout-configuration)
 - [Usage](#-usage)
   - **Core Commands:** [Translation](#translation) | [Writing Enhancement](#writing-enhancement) | [Spelling and Grammar Correction](#spelling-and-grammar-correction) | [Voice Translation](#voice-translation)
   - **Resources:** [Glossaries](#glossaries) | [Translation Memories](#translation-memories)
   - **Workflow:** [Continuous Localization (sync)](#continuous-localization-deepl-sync) | [Watch Mode](#watch-mode) | [Git Hooks](#git-hooks)
-  - **Configuration:** [Setup Wizard](#setup-wizard) | [Authentication](#authentication) | [Configure Defaults](#configure-defaults) | [Cache Management](#cache-management) | [Style Rules](#style-rules)
-  - **Information:** [Usage Statistics](#api-usage-statistics) | [Language Detection](#language-detection) | [Languages](#supported-languages) | [Shell Completion](#shell-completion) | [Command Suggestions](#command-suggestions)
+  - **Configuration:** [Setup Wizard](#setup-wizard) | [Authentication](#authentication) | [Configure Defaults](#configure-defaults) | [Proxy Configuration](#proxy-configuration) | [Retry and Timeout Configuration](#retry-and-timeout-configuration) | [Cache Management](#cache-management) | [Style Rules](#style-rules)
+  - **Information:** [Usage Statistics](#api-usage-statistics) | [Language Detection](#language-detection) | [Languages](#supported-languages) | [Shell Completion](#shell-completion)
   - **Administration:** [Admin API](#admin-api)
 - [Development](#-development)
 - [Architecture](#-architecture)
@@ -74,7 +73,7 @@ The package is scoped, but the command is just `deepl`.
 
 ### Homebrew (macOS / Linux)
 
-_Not available yet — the tap ships shortly after the first npm release. Use npm in the meantime._
+_Not available yet. The `deepl/tap` formula is planned; until it exists, install with npm._
 
 ```bash
 brew install deepl/tap/deepl
@@ -107,7 +106,7 @@ deepl --version
 2.0.0 requires Node 24, renames the package to `@deepl/cli`, removes several
 deprecated flags, and changes a number of exit codes and output shapes that scripts
 read. If you have a pipeline built on 1.x, read
-**[docs/MIGRATION.md](./docs/MIGRATION.md)** before upgrading — it lists every
+**[docs/MIGRATION.md](https://github.com/DeepL/deepl-cli/blob/main/docs/MIGRATION.md)** before upgrading — it lists every
 change that needs action, with a before/after for each.
 
 ## 🚀 Quick Start
@@ -179,11 +178,11 @@ $ deepl --verbose translate "Hello" --to es
 The `--quiet` (or `-q`) flag suppresses all non-essential output, showing only errors and essential results. Perfect for scripts, CI/CD pipelines, and automation.
 
 ```bash
-# Normal mode - shows informational messages
+# Normal mode
 $ deepl translate "Hello" --to es
-Hello
+Hola
 
-# Quiet mode - cleaner output
+# Quiet mode - same result, without the status lines on stderr
 $ deepl --quiet translate "Hello" --to es
 Hola
 
@@ -194,16 +193,19 @@ $ deepl --quiet translate docs/ --to es --output docs-es/
 
 **What's suppressed in quiet mode:**
 
-- ❌ Informational messages (`API Key: ...`)
+- ❌ Informational messages (`Note: "zz-zz" is not in the bundled language list; deferring to the API.`)
 - ❌ Success confirmations (`✓ Cache enabled`)
+- ❌ **Warnings** — including the notice that `--api-url` points somewhere that is not a DeepL endpoint, and the `file exceeds 100 KiB, using document API instead` fallback
 - ❌ Progress spinners and status updates
 - ❌ Decorative output
 
 **What's always shown:**
 
-- ✅ Errors and critical warnings
+- ✅ Errors, with their `Suggestion:` line
 - ✅ Essential command output (translation results, JSON data, statistics)
 
+Warnings are suppressed along with everything else, so run a new pipeline once without `--quiet` before trusting it — that is where you would see a misdirected `--api-url` or a silent fallback to the document API.
+
 **Use cases:**
 
 - **CI/CD pipelines**: Clean output for log parsing
@@ -221,7 +223,7 @@ deepl --quiet translate docs/ --to es,fr,de --output i18n/
 # Returns exit code 0 on success, shows only errors if they occur
 ```
 
-See [docs/API.md#global-options](./docs/API.md#global-options) for complete documentation.
+See [docs/API.md#global-options](https://github.com/DeepL/deepl-cli/blob/main/docs/API.md#global-options) for complete documentation.
 
 ### Command Suggestions
 
@@ -273,7 +275,7 @@ The CLI follows the [XDG Base Directory Specification](https://specifications.fr
 
 Existing `~/.deepl-cli/` installations continue to work with no changes needed.
 
-See [docs/API.md#global-options](./docs/API.md#global-options) for more details.
+See [docs/API.md#global-options](https://github.com/DeepL/deepl-cli/blob/main/docs/API.md#global-options) for more details.
 
 ## 📖 Usage
 
@@ -578,6 +580,8 @@ deepl translate complex.xml --to de --tag-handling xml \
   --output complex.de.xml
 ```
 
+`--format table` draws the box only when stdout is a terminal. Redirected or captured (`--format table > out.txt`, `$(…)`), it falls back to plain `[lang] text` lines and says so on stderr, so log scrapers and screen readers get parseable output instead of box-drawing characters. Use `--format json` when a script needs a stable shape.
+
 **XML Tag Handling Use Cases:**
 
 Advanced XML/HTML tag handling is perfect for:
@@ -588,7 +592,7 @@ Advanced XML/HTML tag handling is perfect for:
 - 🔒 Protecting non-translatable content (scripts, styles, code)
 - ✂️ Fine-tuned control over sentence splitting for better context
 
-See [examples/09-xml-tag-handling.sh](./examples/09-xml-tag-handling.sh) for comprehensive XML tag handling examples with real-world scenarios.
+See [examples/09-xml-tag-handling.sh](https://github.com/DeepL/deepl-cli/blob/main/examples/09-xml-tag-handling.sh) for comprehensive XML tag handling examples with real-world scenarios.
 
 **Model Types:**
 
@@ -598,7 +602,7 @@ See [examples/09-xml-tag-handling.sh](./examples/09-xml-tag-handling.sh) for com
 
 There is no CLI default: when `--model-type` is omitted, the API server selects the model.
 
-See [examples/08-model-type-selection.sh](./examples/08-model-type-selection.sh) for a complete example with different model types.
+See [examples/08-model-type-selection.sh](https://github.com/DeepL/deepl-cli/blob/main/examples/08-model-type-selection.sh) for a complete example with different model types.
 
 ### Writing Enhancement
 
@@ -681,6 +685,14 @@ deepl write "This is good." --alternatives --format json
 deepl write "Fresh improvement please." --lang en-us --no-cache
 ```
 
+**Failures under `--format json`.** Every command with a JSON mode writes a single error envelope to **stdout** — not stderr — so one redirection captures both outcomes. Discriminate on `ok`:
+
+```json
+{ "ok": false, "error": { "code": "ValidationError", "message": "…", "suggestion": "…" }, "exitCode": 6 }
+```
+
+The non-zero exit code remains the failure signal, and stderr carries only human-facing warnings. `--check` is not a failure: it emits `ok: true` with a `needsChanges` verdict and exits 0 or 8.
+
 **Supported Languages:**
 
 - German (`de`)
@@ -758,7 +770,7 @@ deepl correct document.txt --diff
 cat notes.txt | deepl correct
 ```
 
-`correct` supports the same languages and workflow flags as `write` (`--check`, `--fix`, `--diff`, `--interactive`, `--output`, `--in-place`, `--format json`), but not `--style`/`--tone`.
+`correct` supports the same languages and workflow flags as `write` — `--check`, `--fix`, `--backup`, `--diff`, `--alternatives`, `--interactive`, `--output`, `--in-place`, `--no-cache`, `--format json`, and `--to` as an alias of `--lang` — but not `--style`/`--tone`.
 
 ### Voice Translation
 
@@ -840,9 +852,9 @@ deepl sync pull
 deepl config set tms.allowedServers tms.example.com
 ```
 
-Because `tms.server` is chosen by `.deepl-sync.yaml` in the checkout while `TMS_API_KEY`/`TMS_TOKEN` come from your environment, `push`/`pull` will not send an environment-supplied credential to a hostname you have not approved: it asks once in a terminal (recording the answer in your **user** config, outside the repo) and fails closed with exit 7 under `--no-input` or in CI. Both commands also print the destination origin on success. See [TMS destination trust](./docs/SYNC.md#tms-destination-trust).
+Because `tms.server` is chosen by `.deepl-sync.yaml` in the checkout while `TMS_API_KEY`/`TMS_TOKEN` come from your environment, `push`/`pull` will not send an environment-supplied credential to a hostname you have not approved: it asks once in a terminal (recording the answer in your **user** config, outside the repo) and fails closed with exit 7 under `--no-input` or in CI. Both commands also print the destination origin on success. See [TMS destination trust](https://github.com/DeepL/deepl-cli/blob/main/docs/SYNC.md#tms-destination-trust).
 
-See **[docs/SYNC.md](./docs/SYNC.md)** for configuration (`.deepl-sync.yaml`), the lockfile model, CI/CD recipes, and the TMS REST contract, and [docs/API.md#sync](./docs/API.md#sync) for the full flag reference.
+See **[docs/SYNC.md](https://github.com/DeepL/deepl-cli/blob/main/docs/SYNC.md)** for configuration (`.deepl-sync.yaml`), the lockfile model, CI/CD recipes, and the TMS REST contract, and [docs/API.md#sync](https://github.com/DeepL/deepl-cli/blob/main/docs/API.md#sync) for the full flag reference.
 
 ### Watch Mode
 
@@ -886,6 +898,7 @@ deepl watch docs/ --to de --formality more --preserve-code
 - 💾 Auto-commit to git (optional)
 - 📌 Git-staged filtering for pre-commit workflows
 - ⚡ Smart debouncing to avoid redundant translations
+- 🗂️ Output mirrors the source tree: a file in a subdirectory of the watched path is written to the matching subdirectory under `--output`, so two same-named files in different directories never overwrite each other
 
 **Example output:**
 
@@ -905,7 +918,7 @@ Pattern: *.md
 Press Ctrl+C to stop
 ```
 
-See [examples/19-watch-mode.sh](./examples/19-watch-mode.sh) for a complete watch mode example with multiple scenarios.
+See [examples/19-watch-mode.sh](https://github.com/DeepL/deepl-cli/blob/main/examples/19-watch-mode.sh) for a complete watch mode example with multiple scenarios.
 
 ### Git Hooks
 
@@ -967,7 +980,7 @@ Every hook this CLI installs carries a marker recording the SHA-256 of its body,
 
 **Note:** The hooks are generated with placeholder validation logic. You can customize them based on your project's translation workflow by editing the hook files directly at `.git/hooks/pre-commit` or `.git/hooks/pre-push`. A customized hook reports as `!` from then on, since its body no longer matches the hash recorded when it was installed.
 
-See [examples/20-git-hooks.sh](./examples/20-git-hooks.sh) for a complete git hooks example demonstrating installation, usage, and management.
+See [examples/20-git-hooks.sh](https://github.com/DeepL/deepl-cli/blob/main/examples/20-git-hooks.sh) for a complete git hooks example demonstrating installation, usage, and management.
 
 ### Configuration
 
@@ -988,15 +1001,21 @@ deepl init
 #### Authentication
 
 ```bash
-# Set API key
-deepl auth set-key YOUR_API_KEY
+# Set the API key (piping keeps it out of process listings and shell history)
+echo "YOUR_API_KEY" | deepl auth set-key --from-stdin
 # ✓ API key saved and validated successfully
-# Account type: DeepL API Free
 
-# Show current API key status
+# Store it without validating against the API (offline or proxied networks)
+echo "YOUR_API_KEY" | deepl auth set-key --from-stdin --no-verify
+# ✓ API key saved without validation
+
+# Passing the key as an argument still works, but is deprecated and warns —
+# other users can read it via `ps`
+deepl auth set-key YOUR_API_KEY
+
+# Show the stored key, masked (does not contact the API)
 deepl auth show
 # API Key: abc1...2def
-# Status: Valid
 
 # Clear API key
 deepl auth clear
@@ -1023,13 +1042,13 @@ deepl usage
 
 **Note:** Usage statistics help you track your DeepL API character quota and avoid exceeding limits.
 
-See [examples/33-usage-monitoring.sh](./examples/33-usage-monitoring.sh) for a complete usage monitoring example.
+See [examples/33-usage-monitoring.sh](https://github.com/DeepL/deepl-cli/blob/main/examples/33-usage-monitoring.sh) for a complete usage monitoring example.
 
 **Cost Transparency:**
 
 For detailed cost tracking per translation, use the `--show-billed-characters` flag with the translate command (see Advanced Translation Options above). This displays the actual billed character count for each translation, helping with budget planning and cost analysis.
 
-See [examples/12-cost-transparency.sh](./examples/12-cost-transparency.sh) for comprehensive cost tracking examples.
+See [examples/12-cost-transparency.sh](https://github.com/DeepL/deepl-cli/blob/main/examples/12-cost-transparency.sh) for comprehensive cost tracking examples.
 
 #### Language Detection
 
@@ -1045,7 +1064,10 @@ echo "こんにちは" | deepl detect
 
 # JSON output for scripting
 deepl detect "Hola mundo" --format json
-# { "detected_language": "es", "language_name": "Spanish" }
+# {
+#   "detected_language": "es",
+#   "language_name": "Spanish"
+# }
 ```
 
 #### Supported Languages
@@ -1113,7 +1135,7 @@ deepl languages
 
 **The API decides what exists.** `GET /v3/languages` is authoritative; the bundled list is a generated snapshot of it (`npm run generate:languages`) so that listing and validating languages works offline. Because a snapshot can lag the API, a well-formed language code it does not list is passed to the API rather than rejected locally — that is why `deepl translate --to de-CH` works even if your copy of the list predates Swiss German. Input that is not shaped like a language tag is still rejected immediately.
 
-See [examples/34-languages.sh](./examples/34-languages.sh) for a complete example.
+See [examples/34-languages.sh](https://github.com/DeepL/deepl-cli/blob/main/examples/34-languages.sh) for a complete example.
 
 #### Configure Defaults
 
@@ -1135,7 +1157,7 @@ deepl config get cache.enabled
 
 # Set a value
 deepl config set defaults.targetLangs es,fr,de
-# ✓ Configuration updated: defaults.targetLangs = ["es","fr","de"]
+# ✓ Set defaults.targetLangs = es,fr,de
 
 # Approve TMS destinations for an environment-supplied TMS_API_KEY / TMS_TOKEN
 deepl config set tms.allowedServers tms.example.com,tms2.example.com
@@ -1143,7 +1165,7 @@ deepl config set tms.allowedServers tms.example.com,tms2.example.com
 
 # Set cache size (in bytes)
 deepl config set cache.maxSize 2147483648
-# ✓ Configuration updated: cache.maxSize = 2147483648
+# ✓ Set cache.maxSize = 2147483648
 
 # Disable caching
 deepl config set cache.enabled false
@@ -1245,11 +1267,14 @@ DeepL glossaries ensure consistent terminology across translations. The v3 Gloss
 # File format: source_term<TAB>target_term per line
 echo -e "API\tAPI\nREST\tREST\nauthentication\tAuthentifizierung" > glossary.tsv
 deepl glossary create tech-terms en de glossary.tsv
-# ✓ Glossary created: tech-terms (ID: abc123...)
+# ✓ Glossary created successfully
+# Name: tech-terms
+# ID: abc123...
 # Source language: en
 # Target languages: de
 # Type: Single target
 # Total entries: 3
+# Created: 2026-08-09T12:34:56.000Z
 
 # List all glossaries
 deepl glossary list
@@ -1264,7 +1289,7 @@ deepl glossary show tech-terms
 # Target languages: de
 # Type: Single target
 # Total entries: 3
-# Created: 2024-10-07T12:34:56Z
+# Created: 2026-08-09T12:34:56.000Z
 
 # Show glossary entries (single-target glossary - no --target flag needed)
 deepl glossary entries tech-terms
@@ -1272,15 +1297,15 @@ deepl glossary entries tech-terms
 # REST → REST
 # authentication → Authentifizierung
 
-# Show entries for multilingual glossary (--target flag required)
+# Show entries for multilingual glossary (--target-lang required)
 deepl glossary entries multilingual-terms --target-lang es
 # API → API
 # cache → caché
 # ...
 
-# Delete glossary
-deepl glossary delete tech-terms
-# ✓ Glossary deleted: tech-terms
+# Delete glossary (prompts for confirmation; --yes to skip)
+deepl glossary delete tech-terms --yes
+# ✓ Glossary deleted successfully
 
 # Preview what would be deleted without performing the operation
 deepl glossary delete tech-terms --dry-run
@@ -1348,7 +1373,7 @@ authentication	Authentifizierung
 - **Single-target glossaries** - One source language → one target language (e.g., en → de)
 - **Multilingual glossaries** - One source language → multiple target languages (e.g., en → es, fr, de)
 - **Direct updates** - v3 API uses PATCH endpoints for efficient updates (no delete+recreate)
-- **Smart defaults** - `--target` flag only required for multilingual glossaries
+- **Smart defaults** - `--target-lang` only required for multilingual glossaries
 - **Visual indicators** - 📖 for single-target, 📚 for multilingual glossaries
 - **Translation integration** - Use `--glossary` flag in translate and watch commands to apply glossary terms (a source language is required, since the API rejects a glossary without one: pass `--from`, or set `defaults.sourceLang`)
 - **Several glossaries at once** - Repeat `--glossary` on `translate` for up to 5 glossaries; entries are merged, and a term defined in more than one is resolved by the API, not by flag order
@@ -1378,7 +1403,7 @@ deepl translate "Hello" --to de --translation-memory brand-terms
 deepl translate "Hello" --to de --translation-memory brand-terms --tm-threshold 90
 ```
 
-For sync runs, configure `translation.translation_memory` (and optionally `translation.translation_memory_threshold`) in `.deepl-sync.yaml` — see [docs/SYNC.md](./docs/SYNC.md).
+For sync runs, configure `translation.translation_memory` (and optionally `translation.translation_memory_threshold`) in `.deepl-sync.yaml` — see [docs/SYNC.md](https://github.com/DeepL/deepl-cli/blob/main/docs/SYNC.md).
 
 ### Style Rules
 
@@ -1417,7 +1442,7 @@ deepl style-rules add-instruction sr-abc123 tone "Be formal"
 deepl translate "Hello" --to de --style-id "abc-123-def-456"
 ```
 
-See [docs/API.md#style-rules](./docs/API.md#style-rules) for the full subcommand reference, including the configured-rules JSON shape.
+See [docs/API.md#style-rules](https://github.com/DeepL/deepl-cli/blob/main/docs/API.md#style-rules) for the full subcommand reference, including the configured-rules JSON shape.
 
 ### Admin API
 
@@ -1577,7 +1602,7 @@ npm run build
 
 ### Development Workflow
 
-See [CLAUDE.md](./CLAUDE.md) for comprehensive development guidelines.
+See [CLAUDE.md](https://github.com/DeepL/deepl-cli/blob/main/CLAUDE.md) for comprehensive development guidelines.
 
 ### Project Structure
 
@@ -1625,12 +1650,13 @@ Service Layer (Translation, Write, Voice, Batch, Watch, Glossary,
                TranslationMemory, StyleRules, Admin, Document,
                GitHooks, Usage, Detect, Languages)
            ↓                         ↓
-Sync Engine (src/sync)        Format Parsers (src/formats — 11 i18n formats)
+Sync Engine (src/sync —        Format Parsers (src/formats — 11 i18n formats)
+  incl. TmsClient)
            ↓                         ↓
 API Client (Translate, Write, Glossary, Document, Voice,
-            StyleRules, Admin, TMS)
+            StyleRules, Admin)
            ↓
-Storage (SQLite Cache, Config) + Static Data (src/data — language registry)
+Storage (node:sqlite Cache, Config) + Static Data (src/data — language registry)
 ```
 
 ### Key Components
@@ -1644,7 +1670,7 @@ Storage (SQLite Cache, Config) + Static Data (src/data — language registry)
 - **Watch Service** — file watching with debouncing
 - **Glossary Service** — glossary management and application
 - **Translation Memory Service** — reuse approved translations (`--translation-memory`)
-- **Cache** — SQLite cache, oldest-entry-first eviction (`src/storage/cache.ts`)
+- **Cache** — `node:sqlite` cache, oldest-entry-first eviction (`src/storage/cache.ts`)
 - **Preservation utilities** — `src/utils/` helpers for code blocks, variables, and ICU MessageFormat
 
 ## 🧪 Testing
@@ -1676,13 +1702,13 @@ npm run examples:fast
 
 ## 📚 Documentation
 
-- **[API Reference](./docs/API.md)** - Complete API reference with all commands, flags, and options
-- **[Migrating from 1.x](./docs/MIGRATION.md)** - Removed flags, changed exit codes, and output that scripts parse
-- **[Sync Guide](./docs/SYNC.md)** - Continuous localization: `.deepl-sync.yaml` configuration, lockfile model, CI/CD recipes, TMS integration
-- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues, solutions, and exit codes reference
-- **[Examples](./examples/README.md)** - Practical usage examples for every feature
-- **[Changelog](./CHANGELOG.md)** - Release history and version notes
-- **[Development Guidelines](./CLAUDE.md)** - TDD workflow and contribution standards
+- **[API Reference](https://github.com/DeepL/deepl-cli/blob/main/docs/API.md)** - Complete API reference with all commands, flags, and options
+- **[Migrating from 1.x](https://github.com/DeepL/deepl-cli/blob/main/docs/MIGRATION.md)** - Removed flags, changed exit codes, and output that scripts parse
+- **[Sync Guide](https://github.com/DeepL/deepl-cli/blob/main/docs/SYNC.md)** - Continuous localization: `.deepl-sync.yaml` configuration, lockfile model, CI/CD recipes, TMS integration
+- **[Troubleshooting](https://github.com/DeepL/deepl-cli/blob/main/docs/TROUBLESHOOTING.md)** - Common issues, solutions, and exit codes reference
+- **[Examples](https://github.com/DeepL/deepl-cli/blob/main/examples/README.md)** - Practical usage examples for every feature
+- **[Changelog](https://github.com/DeepL/deepl-cli/blob/main/CHANGELOG.md)** - Release history and version notes
+- **[Development Guidelines](https://github.com/DeepL/deepl-cli/blob/main/CLAUDE.md)** - TDD workflow and contribution standards
 - **[DeepL API Docs](https://www.deepl.com/docs-api)** - Official API documentation
 - **[CLI Guidelines](https://clig.dev/)** - Command-line best practices
 
@@ -1702,7 +1728,7 @@ npm run examples:fast
 | `FORCE_COLOR`      | Force colored output even when terminal doesn't support it. Useful in CI. `NO_COLOR` takes priority if both are set. |
 | `TERM=dumb`        | Disables colored output and progress spinners. Automatically set by some CI environments and editors.                |
 
-See [docs/API.md#environment-variables](./docs/API.md#environment-variables) for full details.
+See [docs/API.md#environment-variables](https://github.com/DeepL/deepl-cli/blob/main/docs/API.md#environment-variables) for full details.
 
 ## 🔒 Security & Privacy
 
@@ -1715,7 +1741,7 @@ See [docs/API.md#environment-variables](./docs/API.md#environment-variables) for
 
 ## 🤝 Contributing
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow (strict TDD), test requirements, commit conventions, and the pull request process.
+Contributions are welcome! See [CONTRIBUTING.md](https://github.com/DeepL/deepl-cli/blob/main/CONTRIBUTING.md) for the development workflow (strict TDD), test requirements, commit conventions, and the pull request process.
 
 ## 📄 License
 

From 5b118345ad358de1e7143faea0a91ba7dff30510 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:26:12 +0200
Subject: [PATCH 240/256] docs(api): correct the exit-code appendix and the
 sync JSON contracts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The flag surface was clean -- no documented-but-nonexistent flags, and `sync init
--format` was the only undocumented one across all 72 command nodes. The damage was in
the exit-code appendix and in shapes the file labels as stable contracts.

The appendix contradicted itself on voice: exit 6 listed "unsupported plan (pre-flight
check)" while its own section 9 and voice-client.ts:171 both say VoiceError, exit 9. The
exit-6 voice sites are language and content-type validation and the five-target cap.

Exit 8 was wrong in both directions for `sync validate`. It named "unbalanced HTML tags"
as a trigger -- `html-tags` is warn severity, measured: a run whose only issue is a lost
`<b>` exits 0 -- and omitted `icu-brackets` and `icu-structure`, which are error severity
and do exit 8. A CI gate built on that line does not fire on lost markup and fires
unexpectedly on ICU damage. The section also promised a soft exit for both check-style
commands; only `write --check` sets `process.exitCode`, while register-sync-validate.ts:91
calls `process.exit(8)` outright, so cleanup does not run.

Three "stable within a major version" shapes omitted fields the CLI always emits, which
is the worst kind of error in a block a consumer copies to build a parser. `sync status`
was missing `unwritten`, `needsReview` and `unwrittenByLocale` -- contradicted by the
file's own prose 76 lines later. `sync pull` was missing `replaced`, the one number that
says whether the pull overwrote local edits, and `dryRun`. `sync audit` was missing
`missingTargets`, which says which locales were silently excluded from the comparison.

The `sync pull` skip reasons were the wrong set: it listed two push-only reasons and
omitted nothing pull emits, while `push` documented no reasons at all despite its
envelope carrying them -- including `untranslated` and `needs_review`, both new in 2.0.0.
Each command's reasons are now listed separately, since the two sets are disjoint.

`sync validate --format json` had no documented shape at all, though every sibling
subcommand has one and this is the payload behind the exit-8 gate. Added, with the
`passed` semantics spelled out (`totalChecked` minus pairs carrying any issue, so a
warning-only pair is not "passed"), and its fabricated text sample -- per-locale grouping
and ✓/✗ counts the renderer has never produced -- replaced with real output.

Voice accepts a hard-coded allowlist, not the full language set: 39 targets and 30
sources, counted from voice.ts rather than taken on trust, with an unlisted code exiting 6
before any request. Nothing in the reference predicted that a valid `translate` target is
a hard failure on `voice`.

Smaller: the document-glossary note claimed "last-one-wins precedence", which two other
passages and the CLI's own help text explicitly deny; `--show-billed-characters --format
json` on a single target emits no character count at all, whatever the doc said about
metadata becoming JSON fields; the camelCase convention is a sync-section rule that three
commands outside it contradict; `--dry-run` still needs an API key; the exit-6 site list
omitted `--force` without `--yes`; and See Also pointed at neither the migration guide
nor troubleshooting.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/API.md | 112 ++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 87 insertions(+), 25 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index a9749949..8d0ec78d 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1,7 +1,7 @@
 # DeepL CLI - API Reference
 
 **Version**: 2.0.0
-**Last Updated**: July 29, 2026
+**Last Updated**: August 9, 2026
 
 Complete reference for all DeepL CLI commands, options, and configuration.
 
@@ -457,7 +457,7 @@ deepl translate report.docx --from en --to de --output report.de.docx \
 - Large documents may take several seconds to translate
 - Maximum file sizes: 30MB (document API, all formats), 100 KiB (cached text API)
 - **Document minification** (`--enable-minification`): Reduces file size for PPTX and DOCX files only. Useful for large presentations and documents.
-- **Glossaries**: `--glossary` applies to documents and is repeatable up to 5, with the same last-one-wins precedence as text translation. A source language is required — the API rejects a document glossary without one ("source_lang has to be specified in order to use a glossary") — so pass `--from`, or set `defaults.sourceLang` and it is used automatically. Glossary matching is context-dependent exactly as it is for text: a term may be applied in one sentence and left alone in another, and a bare newline-separated word list often gets few terms applied. `--translation-memory` remains unsupported for documents.
+- **Glossaries**: `--glossary` applies to documents and is repeatable up to 5, resolved exactly as for text translation — entries are merged, and when several glossaries define the same source term which mapping wins is the API's choice and does not follow flag order. A source language is required — the API rejects a document glossary without one ("source_lang has to be specified in order to use a glossary") — so pass `--from`, or set `defaults.sourceLang` and it is used automatically. Glossary matching is context-dependent exactly as it is for text: a term may be applied in one sentence and left alone in another, and a bare newline-separated word list often gets few terms applied. `--translation-memory` remains unsupported for documents.
 
 **Directory translation:**
 
@@ -704,7 +704,7 @@ deepl translate "This is a very long sentence that demonstrates word wrapping."
 - Table format is only available when translating to multiple target languages. For single language translations, use default plain text or JSON format.
 - The Characters column is only shown when using `--show-billed-characters` flag.
 - Without `--show-billed-characters`, the Translation column is wider (70 characters vs 60) for better readability.
-- When the API returns metadata (billed characters, model type used), it is appended below the translated text in plain text output and included as fields in JSON output.
+- Model type, when the API reports it, is carried in JSON output as `modelTypeUsed`. Billed characters are **not**: a single-target `--format json` run emits `{text, targetLang, detectedSourceLang?, modelTypeUsed?, cached?}` and no character count, whatever `--show-billed-characters` is set to. Multi-target JSON (`--to es,fr,de --format json`) does carry `billedCharacters` per translation. In plain text output both are appended below the translated text.
 
 ---
 
@@ -1090,6 +1090,14 @@ deepl voice [options] <file>
 
 > **Note:** If the server ends the stream after transcribing the audio but without sending a translation for one of `--to`'s languages, the command fails with exit code 9 and names the languages, rather than printing an empty translation line and exiting 0. Audio containing no speech transcribes to nothing and is translated to nothing, which is not an error and still exits 0.
 
+> **Note:** the Voice API supports a smaller language set than `translate`, and the CLI checks `--to`/`--from` against it locally — an unlisted code exits 6 before any request, naming every valid option.
+>
+> **Targets (39):** `ar`, `bg`, `cs`, `da`, `de`, `el`, `en`, `en-gb`, `en-us`, `es`, `et`, `fi`, `fr`, `he`, `hu`, `id`, `it`, `ja`, `ko`, `lt`, `lv`, `nb`, `nl`, `pl`, `pt`, `pt-br`, `pt-pt`, `ro`, `ru`, `sk`, `sl`, `sv`, `th`, `tr`, `uk`, `vi`, `zh`, `zh-hans`, `zh-hant`
+>
+> **Sources (30):** `ar`, `bg`, `cs`, `da`, `de`, `el`, `en`, `es`, `et`, `fi`, `fr`, `hu`, `id`, `it`, `ja`, `ko`, `lt`, `lv`, `nb`, `nl`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sv`, `tr`, `uk`, `zh`
+>
+> Codes are matched case-insensitively, so the lowercase spelling `deepl languages` prints is accepted; the CLI canonicalizes to the casing the Voice API expects before sending.
+
 #### Supported Audio Formats
 
 | Extension       | Content Type                          |
@@ -1363,6 +1371,7 @@ Interactive setup wizard that creates `.deepl-sync.yaml` by scanning the project
 - `--target-locales CODES` - Target locales (comma-separated)
 - `--file-format TYPE` - File format: `json`, `yaml`, `toml`, `po`, `android_xml`, `ios_strings`, `xcstrings`, `arb`, `xliff`, `properties`, `laravel_php`
 - `--path GLOB` - Source file path or glob pattern
+- `--format FORMAT` - Output format: `text` (default), `json`. Under `json`, success emits the envelope described below and failure emits the shared error envelope, both on stdout
 - `--sync-config PATH` - Path to `.deepl-sync.yaml`
 
 `--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.
@@ -1395,11 +1404,22 @@ Show translation coverage for all target locales.
   "totalKeys": 142,
   "skippedKeys": 1,
   "locales": [
-    { "locale": "de", "complete": 140, "missing": 2, "outdated": 0, "coverage": 98 }
-  ]
+    {
+      "locale": "de",
+      "complete": 140,
+      "missing": 2,
+      "outdated": 0,
+      "unwritten": 0,
+      "needsReview": 0,
+      "coverage": 98
+    }
+  ],
+  "unwrittenByLocale": []
 }
 ```
 
+`unwritten`, `needsReview` and `unwrittenByLocale` are always present, even when zero or empty — see the two paragraphs at the end of this subcommand for what each counts.
+
 `skippedKeys` counts entries the parser tagged as untranslatable and excluded from the translation batch — currently only Laravel pipe-pluralization values (`|{n}`, `|[n,m]`, `|[n,*]`). Included in `totalKeys`.
 
 **stdout/stderr split (stable contract):** The JSON payload — the success result, or the error envelope below when the command fails — is written to **stdout**, so `deepl sync status --format json > status.json` produces a parseable file in both cases. Diagnostic/progress logs and warnings stay on **stderr**, which means stdout parses even when the CLI or the Node runtime had something to say. The same stdout/stderr split applies to `deepl sync --format json`, `deepl sync validate --format json`, and `deepl sync audit --format json`.
@@ -1441,7 +1461,9 @@ The `error.code` field matches the error class name (`ConfigError`, `ValidationE
 }
 ```
 
-**Casing convention:** CLI JSON output uses `camelCase`; the on-disk `.deepl-sync.lock` and `.deepl-sync.yaml` use `snake_case`. The two are deliberately kept separate — JSON output is a consumer contract; the files are authored configuration.
+`keys` is present only when the wizard counted the source strings while scanning; a fully non-interactive `sync init` omits it. Treat it as optional.
+
+**Casing convention:** every `sync` JSON payload uses `camelCase`, while the on-disk `.deepl-sync.lock` and `.deepl-sync.yaml` use `snake_case`. The two are deliberately kept separate — JSON output is a consumer contract; the files are authored configuration. Outside `sync`, commands that pass a DeepL API response straight through keep the API's own `snake_case` (`glossary`, `tm`), as does `detect` (`detected_language`, `language_name`). The two are deliberately kept separate — JSON output is a consumer contract; the files are authored configuration.
 
 **Examples:**
 
@@ -1489,18 +1511,48 @@ deepl sync validate --locale de
 **Sample output:**
 
 ```
-Validation Results:
+$ deepl sync validate
+Checked 4 translations
 
-  de:
-    ✓ 138/140 strings valid
-    ✗ 2 issues found:
-      - messages.welcome: placeholder {name} missing in translation
-      - errors.count: format specifier %d replaced with %s
+  ERROR  de/greeting: Missing placeholders in translation: {name}
+  WARN  de/bye: Translation is identical to source text
 
-  fr:
-    ✓ 142/142 strings valid
+1 error(s), 1 warning(s)
 ```
 
+One line per issue, `ERROR` or `WARN` followed by `<locale>/<key>` and the check's message. A run with no issues prints the header and `All translations passed validation.`
+
+**JSON output contract (stable within a major version):**
+
+```json
+{
+  "totalChecked": 3,
+  "passed": 2,
+  "warnings": 0,
+  "errors": 1,
+  "issues": [
+    {
+      "locale": "de",
+      "file": "locales/de.json",
+      "key": "errors.count",
+      "source": "Hi %s",
+      "translation": "Hi",
+      "severity": "error",
+      "issues": [
+        {
+          "check": "placeholders",
+          "severity": "error",
+          "message": "Missing placeholders in translation: %s",
+          "details": { "expected": ["%s"], "actual": [] }
+        }
+      ]
+    }
+  ]
+}
+```
+
+`totalChecked` counts source/target pairs that were validated; a key absent from the target file is not a pair and is not counted. `passed` is `totalChecked` minus the number of pairs carrying any issue, so a pair with only warnings is not "passed". `errors` is what drives the exit code — see [8 — CheckFailed](#8--checkfailed) for which `check` values are error severity and which are warn-only. A file-level `unusable_target` issue counts toward `errors` but not toward `totalChecked`, and its `key`/`file` are both the target path rather than a translation key.
+
 ##### `audit`
 
 Analyze translation consistency and detect terminology inconsistencies across target locales. "Audit" here means translation-consistency audit (detecting term divergence across locales), not security audit in the `npm audit` sense.
@@ -1524,10 +1576,13 @@ Analyze translation consistency and detect terminology inconsistencies across ta
       "translations": ["Armaturenbrett", "Dashboard"],
       "files": ["locales/en/common.json", "locales/en/admin.json"]
     }
-  ]
+  ],
+  "missingTargets": []
 }
 ```
 
+`missingTargets` lists target files that could not be read or parsed and were therefore excluded from the comparison. A non-empty array means the audit's verdict covers fewer locales than the project has; the text output prints the same list under `N target(s) could not be read and were excluded from the comparison:`.
+
 The `translations` array contains the actual translated strings read from target files. If a target file is missing, the content hash falls back in its place.
 
 ##### `export`
@@ -1595,6 +1650,8 @@ Both commands print the resolved destination origin on success, in text and JSON
 
 **JSON success envelope (stable within a major version):** `{ "ok": true, "pushed": <n>, "skipped": [...], "server": "<origin>" }`
 
+Each `skipped` entry carries a `reason`. `push` emits `untranslated` (the target file lists the key but holds no translation for it — pushing it would upload source text as the locale's approved translation), `needs_review` (the translation is marked as needing review, a gettext `#, fuzzy` msgstr or an XLIFF review `state`, so it is a reviewer's draft rather than an approved translation), `pipe_pluralization` (Laravel pipe-pluralization, never sent to a TMS), and `target_missing` (the target file does not exist yet, common on a first push). `push` never emits `pull`'s reasons and `pull` never emits these.
+
 ##### `pull`
 
 Pull approved translations from a TMS back into local files.
@@ -1619,9 +1676,11 @@ The gate applies only to environment-supplied credentials. A credential inlined
 
 Both commands print the resolved destination origin on success, in text and JSON output, so a redirected destination is visible in logs even when the host was already approved.
 
-**JSON success envelope (stable within a major version):** `{ "ok": true, "pulled": <n>, "skipped": [...], "server": "<origin>" }`
+**JSON success envelope (stable within a major version):** `{ "ok": true, "pulled": <n>, "replaced": <n>, "skipped": [...], "server": "<origin>", "dryRun": <bool> }`
+
+`replaced` counts keys whose existing local translation the pull overwrote with the TMS version — check it before trusting a pull that ran over hand-edited files. `dryRun` is `true` when `--dry-run` was passed, in which case nothing was written and `pulled`/`replaced` are what a real run would do.
 
-Each `skipped` entry carries a `reason`: `target_missing`, `no_matches`, `pipe_pluralization`, `key_collision`, `unusable_target`, `plural_entry`, or `shared_target` — the last for a target file another sync configuration's `.deepl-sync.lock` accounts for keys in, which is left untouched rather than rebuilt from this configuration's keys alone. See [docs/SYNC.md#two-configurations-writing-one-file](./SYNC.md#two-configurations-writing-one-file).
+Each `skipped` entry carries a `reason`. `pull` emits `unusable_target` (the target file could not be read), `key_collision` (the target file's keys collide), `shared_target` (a target file another sync configuration's `.deepl-sync.lock` accounts for keys in, left untouched rather than rebuilt from this configuration's keys alone), `plural_entry` (one exported string cannot fill a gettext `msgstr[N]` or Android `<plurals>` entry's forms, so the entry is carried forward as it stands), and `no_matches` (no matching keys). See [docs/SYNC.md#two-configurations-writing-one-file](./SYNC.md#two-configurations-writing-one-file).
 
 #### Examples
 
@@ -1686,7 +1745,7 @@ No other fields appear in the output. Fields not listed above are internal and m
 #### Notes
 
 - The `--frozen` flag makes no API calls. It compares the lockfile against source files, and each target file against what the lockfile claims about it, and exits with code 10 if any translations are missing, outdated, or recorded as translated while absent from the target file. This is the recommended mode for CI/CD pipelines.
-- The `--dry-run` flag makes no API calls and writes nothing — no target file, no lockfile, no backup. It reads each target file the lockfile claims translations for, so its estimate covers the same work the real run does: keys the lockfile calls translated that the target file no longer holds are **included** (the run re-translates and re-bills them, and `unwrittenKeys` reports the count), and a locale whose target file is on disk and unreadable is **excluded** and named in a warning, because the run refuses that locale, bills nothing for it and exits 12. Reading the target files is what makes the estimate faithful and is the flag's main cost: measured on a 20,000-key, 6-locale project (2.83 MiB source, 17.3 MiB of target files, 24 MiB lockfile), `--dry-run` went from 0.44 s to 0.75 s, alongside 0.77 s for `sync status` and 0.79 s for `sync --frozen`. The read is skipped entirely for a locale the lockfile claims nothing for, so a project mid-first-sync pays nothing.
+- The `--dry-run` flag makes no API calls and writes nothing — no target file, no lockfile, no backup. It still requires an API key, though: the client is constructed before the run decides it has nothing to send, so `deepl sync --dry-run` without a key exits 2. It reads each target file the lockfile claims translations for, so its estimate covers the same work the real run does: keys the lockfile calls translated that the target file no longer holds are **included** (the run re-translates and re-bills them, and `unwrittenKeys` reports the count), and a locale whose target file is on disk and unreadable is **excluded** and named in a warning, because the run refuses that locale, bills nothing for it and exits 12. Reading the target files is what makes the estimate faithful and is the flag's main cost: measured on a 20,000-key, 6-locale project (2.83 MiB source, 17.3 MiB of target files, 24 MiB lockfile), `--dry-run` went from 0.44 s to 0.75 s, alongside 0.77 s for `sync status` and 0.79 s for `sync --frozen`. The read is skipped entirely for a locale the lockfile claims nothing for, so a project mid-first-sync pays nothing.
 - The `sync.max_characters` cost cap quotes from the same estimate as `--dry-run`, so a run the preview prices above the cap is a run the cap refuses. That costs one pass over the target files before the cap decides: on the fixture above, a translating run took 1.54 s with no cap configured and 1.91 s with one. The cap is unaffected for projects that do not set it.
 - The lockfile (`.deepl-sync.lock`) should be committed to version control. It enables incremental sync by tracking content hashes.
 - The `push` and `pull` subcommands require a TMS that implements the REST contract documented in [docs/SYNC.md](./SYNC.md#tms-rest-contract). All other commands work with the standard DeepL Translation API.
@@ -2437,7 +2496,7 @@ Show API usage statistics.
 #### Synopsis
 
 ```bash
-deepl usage
+deepl usage [OPTIONS]
 ```
 
 #### Description
@@ -3471,9 +3530,9 @@ User-supplied input was rejected by client-side validation before any API call.
 
 - `translate`: empty text, missing `--to`, unsupported file format, invalid `--tm-threshold` range, `--tm-threshold` without `--translation-memory`, `--translation-memory` without `--from`, mutually exclusive flags
 - `write`: empty text, `--style` and `--tone` used together, `--fix` without a file path, unsupported language for the Write API
-- `voice`: missing target languages, unsupported plan (pre-flight check), invalid session parameters
+- `voice`: unsupported target or source language code, unsupported `--content-type`, more than 5 target languages. A plan that does not include the Voice API is exit 9, not 6 — see [9 — VoiceError](#9--voiceerror)
 - `glossary`: missing name/entries, entry not found on delete
-- `sync`: `--frozen` combined with `--force`, missing `.deepl-sync.yaml` (before `ConfigError` hands off)
+- `sync`: `--frozen` combined with `--force`, `--watch` combined with `--force`, `--force` without `--yes` anywhere the confirmation prompt cannot be shown (piped stdin, cron, a git hook, `--no-input`, `CI=true`), missing `.deepl-sync.yaml` (before `ConfigError` hands off)
 - `hooks`, `watch`, `detect`, `admin`, `init`, `completion`, `cache`: argument parsing, unknown subcommand, bad path, bad size
 
 Remediation: re-read the command's `--help` and the relevant section of this API reference.
@@ -3494,10 +3553,10 @@ Remediation: run `deepl config get` to inspect the current config, or edit the f
 
 #### 8 — CheckFailed
 
-A check-style command ran successfully but found actionable issues. Exit is *soft* — `process.exitCode` is set so cleanup still runs. Emitted by:
+A check-style command ran successfully but found actionable issues. Emitted by:
 
-- `deepl write --check <text|file>` and `deepl correct --check <text|file>` when the Write API would suggest changes (`needsImprovement === true`). Under `--format json` the same run also emits the `ok: true` check result payload on stdout, so the count and the file are readable without parsing prose
-- `deepl sync validate` when validation surfaces one or more `error`-severity issues (missing placeholders, format-string mismatches, unbalanced HTML tags, or a target file on disk that could not be read — reported under an `unusable_target` check while every other locale is still validated)
+- `deepl write --check <text|file>` and `deepl correct --check <text|file>` when the Write API would suggest changes (`needsImprovement === true`). Under `--format json` the same run also emits the `ok: true` check result payload on stdout, so the count and the file are readable without parsing prose. Exit is *soft* here — `process.exitCode` is set so cleanup still runs
+- `deepl sync validate` when validation surfaces one or more `error`-severity issues: a placeholder present in the source and **missing** from the translation, a mismatched ICU bracket nesting depth (`icu-brackets`), or a translated ICU argument name, format type or selector keyword (`icu-structure`) — plus a target file on disk that could not be read, reported under an `unusable_target` check while every other locale is still validated. Issues the validator raises at `warn` severity never affect the exit code: missing HTML tags (`html-tags`), *extra* placeholders the source does not have, a translation identical to its source (`untranslated`), and an outlying length ratio (`length-ratio`); a run with warnings and no errors exits 0. Exit is *hard* here — `process.exit(8)` is called as soon as the report is written, so do not rely on later cleanup running
 
 This code is specifically designed for CI use: a `check` step can block a merge without requiring try/catch wrappers in the calling script. It does **not** indicate a CLI failure.
 
@@ -3607,10 +3666,13 @@ deepl write --check README.md
 
 ## See Also
 
+- [Migrating from 1.x to 2.0.0](MIGRATION.md) — removed flags, exit codes that moved, output that moved to stdout
+- [Sync configuration reference](SYNC.md)
+- [Troubleshooting](TROUBLESHOOTING.md)
 - [Examples](../examples/)
 - [DeepL API Documentation](https://www.deepl.com/docs-api)
 
 ---
 
-**Last Updated**: July 29, 2026
+**Last Updated**: August 9, 2026
 **DeepL CLI Version**: 2.0.0

From b7bbc39323bdbee2267068fb18b5214c82c63a64 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:26:32 +0200
Subject: [PATCH 241/256] docs(sync): correct validate output, the status
 contract and schema gaps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `sync validate` sample output was fabricated -- per-locale grouping, ✓/✗ marks,
per-locale valid counts and an "N issues across N locales" line, none of which exist in
the renderer. Replaced with measured output: one `ERROR`/`WARN` line per issue carrying
`<locale>/<key>`, then the error and warning counts. A reader writing a log grep against
the old block got nothing.

Corrected two claims about what validate checks. "Key count matches between source and
target files" is not a check and never was -- a target file that lost keys is reported by
`sync status` as `unwritten`, not here. And "HTML/XML tags balanced and matching" overstates
`checkHtmlTags`, which reports source tags absent from the translation at warn severity and
checks neither nesting nor balance, and does not report extra tags at all.

The `sync status --format json` contract omitted `unwritten`, `needsReview` and the
top-level `unwrittenByLocale` array, all always emitted, and gave a coverage formula
missing two of its five denominator terms -- so a consumer written from it mis-derives
coverage and loses two never-complete categories. The progress-bar legend predated both
categories too, contradicting the doc's own example output.

A documented instruction that silently does nothing: translation memory requires
`model_type: quality_optimized`, and the guide said to set it "at the same scope as
`translation_memory`, or the matching per-locale override". The per-locale value is on the
allowlist and validated, then never read -- sync-locale-translator.ts:309 takes the top
level only, while every sibling field on that object does the per-locale fallback. The
guide now says so; the behaviour is filed as cli-mq2y.

The exit-code table jumped 1 to 6, omitting 2, 3 and 5 -- two of which the same document
says sync emits, and the two most common transient failures a `case $?` would need. Every
code it did list was correct and agrees with API.md and exit-codes.ts.

`--break-lock` was explained in prose but absent from all three option tables of the
commands that accept it, and it is new 2.0 surface; `--yes` was only alluded to inside the
`--force` cell. `bak_sweep_max_age_seconds` is live, validated and read in two places but
had no schema row, while its default was documented as prose elsewhere. Two of the nine
push/pull skip reasons -- `no_matches` and `pipe_pluralization` -- appear in CLI output and
were never explained.

Also: `--frozen` is sold as making no API calls, which is true, but it still needs a key
and exits 2 without one -- so the documented pull-request recipe fails on a fork, where
secrets are empty; `sync init --path` metavariable disagreed with the CLI; the removed
`tms.*` note said the keys were "listed in this table" after they were correctly removed
from it; and two `#deepl-sync-lock` anchors never resolved (the heading slug drops the dot).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/SYNC.md | 65 +++++++++++++++++++++++++++++++---------------------
 1 file changed, 39 insertions(+), 26 deletions(-)

diff --git a/docs/SYNC.md b/docs/SYNC.md
index cbd1e7e6..6baaf5f9 100644
--- a/docs/SYNC.md
+++ b/docs/SYNC.md
@@ -367,7 +367,7 @@ Each bucket maps a format name to a set of file patterns. The format name must b
 | `translation_memory_threshold` | `number` | No | `75` | Minimum match score 0–100 (requires `translation_memory`). Non-integer or out-of-range values exit 7 (ConfigError). |
 | `custom_instructions` | `string[]` | No | -- | Custom instructions passed to the DeepL API |
 | `style_id` | `string` | No | -- | Style ID for consistent translation style |
-| `locale_overrides` | `object` | No | -- | Per-locale overrides for `formality`, `glossary`, `translation_memory`, `translation_memory_threshold`, `custom_instructions`, `style_id` |
+| `locale_overrides` | `object` | No | -- | Per-locale overrides for `formality`, `glossary`, `translation_memory`, `translation_memory_threshold`, `custom_instructions`, `style_id`. A `model_type` here is accepted by the schema but not applied to that locale's requests — set `translation.model_type` at the top level instead |
 | `instruction_templates` | `object` | No | -- | Per-element-type instruction templates. Built-in defaults cover 16 element types: `button`, `a`, `h1`-`h6`, `th`, `label`, `option`, `input`, `title`, `summary`, `legend`, `caption`. User-provided templates override defaults. Only effective for locales supporting custom instructions: DE, EN, ES, FR, IT, JA, KO, ZH. See [Translation Strategies](#translation-strategies). |
 | `length_limits.enabled` | `boolean` | No | `false` | Enable length-aware translation instructions. Adds "Keep under N characters" per key based on source text length and locale expansion factors. Only applies to length-constrained element types (button, th, label, option, input, title) for keys sent via per-key API calls. |
 | `length_limits.expansion_factors` | `object` | No | built-in defaults | Per-locale expansion factors relative to English source. Built-in defaults: DE 1.3, FR 1.3, ES 1.25, JA 0.5, KO 0.7, ZH 0.5, etc. Based on industry-standard approximations (IBM, W3C). User-overridable. |
@@ -380,7 +380,7 @@ Setting `translation.glossary: auto` enables automatic project glossaries. Each
 
 Set `translation.translation_memory` to a translation memory name or UUID to reuse approved translations across a sync run. Translation memories are authored and uploaded through the DeepL web UI; the CLI never creates or edits them. Names are resolved to UUIDs once via `GET /v3/translation_memories` and cached for the remainder of the invocation, so a multi-locale sync issues at most one list call per unique name. TM composes with glossary — both `glossary_id` and `translation_memory_id` are sent on the same translate call when both are configured.
 
-Translation memories require `model_type: quality_optimized`. Set `model_type: quality_optimized` at the same scope as `translation_memory` (top-level `translation.model_type`, or the matching per-locale override). Other values are rejected at config load with `ConfigError` (exit 7), before any API call is made. Threshold propagates from YAML into each translate request (default 75, range 0–100); `translation_memory_threshold` without `translation_memory` is inert. Per-locale `locale_overrides.<locale>.translation_memory` takes precedence over the top-level `translation.translation_memory`; `locale_overrides.<locale>.translation_memory_threshold` falls back to the top-level threshold when unset. See [Is translation memory actually being applied?](#is-translation-memory-actually-being-applied) for verification steps.
+Translation memories require `model_type: quality_optimized`. Set it at the **top level** (`translation.model_type: quality_optimized`) — that is the only scope the sync engine reads when it builds a translate request. A `model_type` inside `translation.locale_overrides.<locale>` is accepted and validated by the schema but is **not** applied to that locale's requests. Other values are rejected at config load with `ConfigError` (exit 7), before any API call is made. Threshold propagates from YAML into each translate request (default 75, range 0–100); `translation_memory_threshold` without `translation_memory` is inert. Per-locale `locale_overrides.<locale>.translation_memory` takes precedence over the top-level `translation.translation_memory`; `locale_overrides.<locale>.translation_memory_threshold` falls back to the top-level threshold when unset. See [Is translation memory actually being applied?](#is-translation-memory-actually-being-applied) for verification steps.
 
 #### `context`
 
@@ -487,6 +487,7 @@ output instead, or fix the source string.
 | `max_characters` | `number` | No | -- | Cost cap: abort sync if estimated characters exceed this limit (override with `--force`) |
 | `backup` | `boolean` | No | `true` | Create `.deepl.bak` copies of target files before overwriting; cleaned up after successful sync |
 | `max_scan_files` | `number` | No | `50000` | Hard ceiling on the number of files matched by `context.scan_paths`. Prevents a misconfigured pattern from wedging the CLI on shared CI with huge source trees and slow disks. Exceeding the cap throws `ValidationError` with a suggestion to narrow the pattern. Positive integer. |
+| `bak_sweep_max_age_seconds` | `number` | No | `300` (5 min) | How long a redundant `.deepl.bak` sibling is left on disk before the startup sweep removes it. Only ever applies to a backup whose target already holds the same bytes -- one whose target has diverged is kept however old it is (see [Watch Mode](#watch-mode-deepl-sync---watch)). Positive integer. |
 | `limits.max_entries_per_file` | `number` | No | `25000` | Per-file parser cap on extracted entry count. Files exceeding this are skipped with a warning. Hard ceiling: `100000`. Values above the ceiling fail at config load with `ConfigError` (exit 7). |
 | `limits.max_file_bytes` | `number` | No | `4194304` (4 MiB) | Per-file parser cap on on-disk size, checked via `fs.stat` before read. Files exceeding this are skipped with a warning. Hard ceiling: `10485760` (10 MiB). Values above the ceiling fail at config load with `ConfigError` (exit 7). |
 | `limits.max_depth` | `number` | No | `32` | Per-file parser cap on nesting depth. Protects against stack-overflow on adversarial input. Consumed by the Laravel PHP and JSON parsers (the ones that walk their tree recursively); other formats are bounded by their own parser instead. Files exceeding this are skipped with a warning, and the rest of the run continues. Hard ceiling: `64`. Values above the ceiling fail at config load with `ConfigError` (exit 7). |
@@ -506,7 +507,7 @@ Optional integration with a translation management system (TMS) for collaborativ
 | `timeout_ms` | `number` | No | `30000` | Per-request timeout in milliseconds for TMS HTTP calls (positive integer). Aborts the request via `AbortController` when exceeded. |
 | `push_concurrency` | `number` | No | `10` | Maximum number of in-flight `PUT /keys/{keyPath}` requests during `deepl sync push`. Positive integer. Applied per (file, locale) batch of entries; aborts remaining pushes on first failure. |
 
-**Removed fields.** `auto_push`, `auto_pull` and `require_review` were accepted by the schema and listed in this table, and no code ever read any of them -- a `require_review` a user configured expecting a human gate before pull got no gate and no warning. All three now fail config load with a `ConfigError` (exit 7) naming them, rather than being silently tolerated. Push and pull after or before a sync by running `deepl sync push` / `deepl sync pull` explicitly, which also keeps the credential and destination decision on a command you typed. A review gate cannot be enforced from the CLI side because the export contract below carries no per-entry review flag; use [`deepl sync pull --dry-run`](#deepl-sync-pull) to preview a pull and review the result before committing it.
+**Removed fields.** `auto_push`, `auto_pull` and `require_review` were accepted by the schema through `1.x`, and no code ever read any of them -- a `require_review` a user configured expecting a human gate before pull got no gate and no warning. All three now fail config load with a `ConfigError` (exit 7) naming them, rather than being silently tolerated. Push and pull after or before a sync by running `deepl sync push` / `deepl sync pull` explicitly, which also keeps the credential and destination decision on a command you typed. A review gate cannot be enforced from the CLI side because the export contract below carries no per-entry review flag; use [`deepl sync pull --dry-run`](#deepl-sync-pull) to preview a pull and review the result before committing it.
 
 ##### TMS destination trust
 
@@ -655,6 +656,8 @@ deepl sync [OPTIONS]
 | `--flag-for-review` | Mark translations as `machine_translated` in lock file for human review |
 | `--watch` | Watch source files and auto-sync on changes |
 | `--debounce <ms>` | Debounce delay for watch mode (default: 500ms) |
+| `-y`, `--yes` | Confirm `--force` without a prompt. Required to run `--force` unattended (no terminal, `--no-input`, CI) |
+| `--break-lock` | Take the sync lock even when `.deepl-sync.lock.pidfile` names a process that looks alive. Unsafe if that sync really is running -- see [Concurrent sync](#concurrent-sync) |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 
 **Examples:**
@@ -752,7 +755,7 @@ deepl sync init [OPTIONS]
 | `--source-locale <code>` | Source locale code |
 | `--target-locales <codes>` | Target locales (comma-separated) |
 | `--file-format <type>` | File format (choices: `json`, `yaml`, `toml`, `po`, `android_xml`, `ios_strings`, `xcstrings`, `arb`, `xliff`, `properties`, `laravel_php`) |
-| `--path <glob>` | Source file path or glob pattern |
+| `--path <pattern>` | Source file path or glob pattern |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 
 `--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.
@@ -834,7 +837,7 @@ Source: en (142 keys)
   ja  [##################..]  91%  (12 missing, 0 outdated)
 ```
 
-Each row shows: locale code, a 20-character ASCII progress bar (`#` = translated, `.` = missing/outdated), integer coverage percentage, and a parenthetical with missing and outdated key counts.
+Each row shows: locale code, a 20-character ASCII progress bar (`#` = complete, `.` = anything not complete), integer coverage percentage, and a parenthetical with the missing and outdated counts -- plus `N unwritten` and `N needs review` when either is non-zero.
 
 **JSON output:**
 
@@ -848,15 +851,18 @@ deepl sync status --format json
   "totalKeys": 142,
   "skippedKeys": 1,
   "locales": [
-    { "locale": "de", "complete": 140, "missing": 2, "outdated": 0, "coverage": 98 },
-    { "locale": "fr", "complete": 142, "missing": 0, "outdated": 0, "coverage": 100 },
-    { "locale": "es", "complete": 138, "missing": 4, "outdated": 0, "coverage": 97 },
-    { "locale": "ja", "complete": 130, "missing": 12, "outdated": 0, "coverage": 91 }
-  ]
+    { "locale": "de", "complete": 140, "missing": 2, "outdated": 0, "unwritten": 0, "needsReview": 0, "coverage": 98 },
+    { "locale": "fr", "complete": 142, "missing": 0, "outdated": 0, "unwritten": 0, "needsReview": 0, "coverage": 100 },
+    { "locale": "es", "complete": 138, "missing": 4, "outdated": 0, "unwritten": 0, "needsReview": 0, "coverage": 97 },
+    { "locale": "ja", "complete": 129, "missing": 12, "outdated": 0, "unwritten": 0, "needsReview": 1, "coverage": 90 }
+  ],
+  "unwrittenByLocale": []
 }
 ```
 
-**Per-locale fields:** `complete` — keys with a current translation; `missing` — keys with no translation entry; `outdated` — keys whose source content has changed since the last sync (translation exists but is stale); `coverage` — integer 0–100 computed as `complete / (complete + missing + outdated) * 100`.
+**Per-locale fields:** `complete` — keys with a current translation; `missing` — keys with no translation entry, or one recorded as a failed attempt; `outdated` — keys whose source content has changed since the last sync (translation exists but is stale); `unwritten` — keys the lock file records as translated that the target file does not hold (see [A string added after the first sync](#a-string-added-after-the-first-sync)); `needsReview` — keys whose translation is present but marked as needing review, a gettext `#, fuzzy` msgstr or an XLIFF review `state` (see [Bilingual formats: PO and XLIFF](#bilingual-formats-po-and-xliff)); `coverage` — integer 0–100 computed as `complete / (complete + missing + outdated + unwritten + needsReview) * 100`. Neither `unwritten` nor `needsReview` is ever counted as `complete`.
+
+**`unwrittenByLocale`** is a top-level array carrying the keys behind each locale's `unwritten` count: `{ "locale", "file", "keys": [...] }`, plus an `unusable` field holding the read or parse error when the target file itself could not be read.
 
 **`skippedKeys`** counts entries the parser tagged as untranslatable and excluded from the translation batch — currently only Laravel pipe-pluralization values (`|{n}`, `|[n,m]`, `|[n,*]`). Included in `totalKeys`; round-trip byte-verbatim via reconstruct.
 
@@ -883,29 +889,29 @@ deepl sync validate [OPTIONS]
 **Example output:**
 
 ```
-Validation Results:
+$ deepl sync validate
+Checked 4 translations
 
-  de:
-    ✓ 138/140 strings valid
-    ✗ 2 issues found:
-      - messages.welcome: placeholder {name} missing in translation
-      - errors.count: format specifier %d replaced with %s
+  ERROR  de/greeting: Missing placeholders in translation: {name}
+  WARN  de/bye: Translation is identical to source text
 
-  fr:
-    ✓ 142/142 strings valid
-
-  2 issues found across 1 locale.
+1 error(s), 1 warning(s)
 ```
 
+One line per issue, `ERROR` or `WARN` followed by `<locale>/<key>` and the check's message. A run with no issues prints the header and `All translations passed validation.` Any error-severity issue exits **8** (`CheckFailed`); warnings alone still exit 0.
+
+**JSON output** (`--format json`) carries `totalChecked`, `passed`, `warnings`, `errors`, and an `issues` array whose entries hold `key`, `source`, `translation`, `severity`, `locale`, `file`, and a nested `issues` array of `{ check, severity, message, details }`.
+
 **Checks performed:**
 
 - Named placeholders present in translation (e.g., `{name}`, `{{count}}`, `%{user}`)
 - Format specifiers match source (e.g., `%d`, `%s`, `%@`)
-- HTML/XML tags balanced and matching
+- Every HTML/XML tag in the source is still present in the translation (warning; tag nesting and balance are not checked, and extra tags in the translation are not reported)
 - ICU message syntax valid (plurals, selects)
 - No untranslated strings copied verbatim from source
 - Length ratio warnings (translation >150% of source length)
-- Key count matches between source and target files
+
+Key-level completeness is **not** a validate check: a target file missing keys the lock file claims is reported by `deepl sync status` as `unwritten` (see [A string added after the first sync](#a-string-added-after-the-first-sync)), not here. Validate compares source/translation pairs it can actually see.
 
 ### `deepl sync export`
 
@@ -945,6 +951,7 @@ deepl sync resolve [OPTIONS]
 |------|-------------|
 | `--format <fmt>` | Output format: `text` (default), `json` |
 | `--dry-run` | Print the per-entry decision report without writing the lockfile |
+| `--break-lock` | Take the sync lock even when `.deepl-sync.lock.pidfile` names a process that looks alive. Unsafe if that sync really is running -- see [Concurrent sync](#concurrent-sync) |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 
 **Output.** The resolver now emits a per-entry report: one line per decision, plus a summary. Each line names the file, key, chosen side (`kept ours` / `kept theirs`), and the reason (typically the winning `translated_at` timestamp). Example:
@@ -956,7 +963,7 @@ WARN  locales/de/app.json:<conflict-region> — parse-error fallback used, JSON.
 Resolved 3 conflicts (1 theirs, 1 ours, 1 length-heuristic). Run "deepl sync" to fill any gaps.
 ```
 
-**The tie-break arbitrates a whole translation, never its fields.** A conflicting pair is arbitrated as one unit whenever *either* side looks like a translation, so the resolver cannot emit a translation whose fields come from both sides — the failure the one-line format described under [`.deepl-sync.lock`](#deepl-sync-lock) exists to prevent. That matters because `translated_at` is not guaranteed to be there: nothing validates it on read, and `human_reviewed` is only ever set by hand, so a hand-edited entry can be missing it. Each case is decided explicitly and named in the report:
+**The tie-break arbitrates a whole translation, never its fields.** A conflicting pair is arbitrated as one unit whenever *either* side looks like a translation, so the resolver cannot emit a translation whose fields come from both sides — the failure the one-line format described under [`.deepl-sync.lock`](#deepl-synclock) exists to prevent. That matters because `translated_at` is not guaranteed to be there: nothing validates it on read, and `human_reviewed` is only ever set by hand, so a hand-edited entry can be missing it. Each case is decided explicitly and named in the report:
 
 | Both sides | Kept | Reported as |
 |------------|------|-------------|
@@ -969,7 +976,7 @@ A `translated_at` that is not a string counts as absent rather than being compar
 
 **Region terminators.** A conflict region that sits inside an object is a sequence of members, and unless it is the last one it ends with a comma joining it to the member that follows. The resolver takes that comma off before parsing the region and puts it back afterwards — without this, every region but the last failed to parse and fell to the length heuristic below, so the documented `translated_at` tie-break never ran. When the two sides *disagree* on whether the region ends a member list — one side deleted what the other modified — no terminator can be correct for both, so the region falls to the heuristic rather than risk emitting invalid JSON.
 
-**Canonical output.** Resolving rebuilds each merged region, so the resolved lockfile is written back in the canonical format described under [`.deepl-sync.lock`](#deepl-sync-lock) rather than with the resolver's own indentation. Committing a resolved lockfile therefore cannot leave translations expanded across lines for the next merge to recombine.
+**Canonical output.** Resolving rebuilds each merged region, so the resolved lockfile is written back in the canonical format described under [`.deepl-sync.lock`](#deepl-synclock) rather than with the resolver's own indentation. Committing a resolved lockfile therefore cannot leave translations expanded across lines for the next merge to recombine.
 
 **Fallback behavior.** When `JSON.parse` fails on a conflict fragment (e.g., conflict markers landed mid-entry and split the JSON), the resolver falls back to a length-heuristic: the longer side wins. This is now **loud** — it logs a `WARN` line naming the file + conflict region with the truncated parse error, and the decision is tagged `length-heuristic` in the report. Earlier releases ran this heuristic silently, making auto-resolve a data-loss risk the user could not audit without a diff against git history. Inspect any `length-heuristic` entries and consider resolving them by hand.
 
@@ -1068,6 +1075,8 @@ deepl sync push [OPTIONS]
 
 **A key with no translation yet is not pushed.** Push reads each target file and uploads the translation it holds. A bilingual target file (see [Bilingual formats: PO and XLIFF](#bilingual-formats-po-and-xliff)) lists every key the source has, translated or not, so pushing such a key would upload its source text as the locale's translation and make the TMS the authority for it -- a later `pull` would then write English into the target file. Those keys are skipped and reported under the `untranslated` reason, with the pushed count reflecting only what was actually sent. A PO entry flagged `#, fuzzy`, and an XLIFF unit whose review `state` says the translation is not finished, are skipped too, under `needs_review`: they have a translation, but one their own toolchain will not ship (see [Bilingual formats](#bilingual-formats-po-and-xliff)). For a monolingual format nothing is skipped on this account: every key the target file lists has a value.
 
+Two further reasons can appear in the `(N skipped: …)` summary for either command: `no_matches`, when a bucket's source file yielded no keys for that locale, and `pipe_pluralization`, for Laravel pipe-pluralization values (`|{n}`, `|[n,m]`, `|[n,*]`), which are never sent to a TMS -- one exported string cannot fill their branches, the same reason `plural_entry` exists for gettext and Android plurals.
+
 ### `deepl sync pull`
 
 Pull approved translations from a TMS back into local files.
@@ -1084,6 +1093,7 @@ deepl sync pull [OPTIONS]
 | `--format <fmt>` | Output format: `text` (default), `json` |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 | `--dry-run` | Preview what the pull would change without writing any file |
+| `--break-lock` | Take the sync lock even when `.deepl-sync.lock.pidfile` names a process that looks alive. Unsafe if that sync really is running -- see [Concurrent sync](#concurrent-sync) |
 
 Each target locale's approved dictionary is fetched exactly once per `sync pull` run (one GET per locale from the TMS export endpoint), then applied to every matching source file locally. Projects with many source files per bucket do not multiply wire bytes by the source-file count.
 
@@ -1140,7 +1150,7 @@ jobs:
           DEEPL_API_KEY: ${{ secrets.DEEPL_API_KEY }}
 ```
 
-The `--frozen` flag causes the sync engine to exit with code 10 if any translations are missing or outdated, without making any API calls. This is ideal for pull request checks.
+The `--frozen` flag causes the sync engine to exit with code 10 if any translations are missing or outdated. It performs the drift check entirely from `.deepl-sync.lock` and the target files and issues no API requests, but it still requires a configured API key and exits 2 (`AuthError`) without one — so a fork-originated pull request, where `secrets` are empty, needs either a key available to forks or a job condition that skips the check. This is ideal for same-repository pull request checks.
 
 ### GitHub Actions (auto-sync)
 
@@ -1287,6 +1297,9 @@ Each target locale translates independently. If the API returns a transient erro
 |------|---------|
 | 0 | Success -- all translations up to date |
 | 1 | General error -- unclassified failure (inspect stderr) |
+| 2 | Authentication error -- API key missing or rejected; aborts the whole run, since every locale shares the credential |
+| 3 | Rate limit exceeded -- retryable |
+| 5 | Network error -- DeepL API or TMS unreachable (connection refused, DNS failure, timeout); retryable |
 | 6 | Invalid input -- bad arguments or unsupported format |
 | 7 | Config error -- invalid or missing `.deepl-sync.yaml` |
 | 8 | Validation failed -- `deepl sync validate` found issues |

From 88b16af235f7bab5e6731ede014dd9927dcc4912 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:26:59 +0200
Subject: [PATCH 242/256] docs(troubleshooting): fix the write flag advice,
 exit-8 scope and add sync-lock
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "Style or tone not applied" section troubleshot a `--formality` flag `deepl write`
does not have. It told the reader to "verify you are using valid formality values" and
sent them to `deepl write --help`, which will never list one -- formality belongs to
`translate` and `voice`; on Write the equivalents are `--style` and `--tone`. Rewritten
around the flags that exist, with the `prefer_*` fallback as the actionable remedy.

Exit 8 was scoped to `write --check` alone, in the reference table, the section heading and
the TOC. `correct --check` carries the same flag and `sync validate` exits 8 on any
error-severity issue, so a CI author reading only this file treats an 8 from `sync validate`
as an unrecognised code. Three documents gave three different scopes for the same code.

Added a section for the process lock. `deepl sync`, `sync pull` and `sync resolve` take a
per-project lock and exit 7 while it is held -- new 2.0 behaviour, with `--break-lock` as
the escape -- and the only exit-7 entry here was "invalid config file", whose remedies
(`config list`, delete `config.json`) are all wrong for that cause.

Smaller: "Reset a specific setting" was illustrated with `config set`, the command that
sets one, with no mention of `config reset`; and the supported-format list omitted `.md`,
`.json`, `.yaml` and `.yml`, so a reader whose "unsupported format" error is about a
markdown or JSON file concludes the format is not supported and stops.

Verified while here: no `better-sqlite3`, `NODE_MODULE_VERSION` or `npm rebuild` advice
survives anywhere, the Node-version message quotes node-version-check.ts accurately, and
every other remedy command exists on the real CLI surface.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/TROUBLESHOOTING.md | 37 ++++++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 3dd74858..9a17b496 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -13,6 +13,7 @@ Common issues and solutions when using the DeepL CLI.
 - [Voice API Errors (Exit Code 9)](#voice-api-errors-exit-code-9)
 - [Write API Issues](#write-api-issues)
 - [Configuration Errors (Exit Code 7)](#configuration-errors-exit-code-7)
+  - ["Another sync is already running" (Exit Code 7)](#another-sync-is-already-running-exit-code-7)
 - [Input Validation Errors (Exit Code 6)](#input-validation-errors-exit-code-6)
 - [Cache Issues](#cache-issues)
 - [Document Translation Issues](#document-translation-issues)
@@ -202,6 +203,8 @@ Common issues and solutions when using the DeepL CLI.
 - **Exit 0** — Text is clean, no improvements suggested.
 - **Exit 8** — Improvements were found and suggested.
 
+The same code is returned by `deepl correct --check` and by `deepl sync validate`, which exits 8 when it finds any error-severity issue (a lost placeholder, rewritten ICU structure, or a target file it could not read). Warnings alone leave `sync validate` at exit 0.
+
 This exit code is useful in CI/CD pipelines or scripts to detect when text could be improved:
 
 ```bash
@@ -271,18 +274,18 @@ Supported formats: `audio/ogg`, `audio/webm`, `audio/flac`, `audio/mpeg`, `audio
 
 ### Style or tone not applied
 
-**Cause:** The formality or style parameter may not be supported for the target language, or the text already matches the requested style.
+**Cause:** The requested `--style` or `--tone` may not be supported for the target language, or the text already matches it. `deepl write` has no `--formality` flag — formality is a `deepl translate` / `deepl voice` option; on Write, register is controlled by `--style` (`simple`, `business`, `academic`, `casual`, and their `prefer_*` forms) and `--tone` (`enthusiastic`, `friendly`, `confident`, `diplomatic`, and their `prefer_*` forms).
 
 **Solutions:**
 
-1. Not all languages support formality settings. Check the DeepL API documentation for supported languages.
-
-2. Verify you are using valid formality values:
+1. Check the accepted values:
 
    ```bash
    deepl write --help
    ```
 
+2. Use a `prefer_*` value (e.g. `--style prefer_business`) so the API falls back rather than rejecting the request when the exact style is unavailable for that language.
+
 3. Use `--verbose` to inspect the API response and confirm the style was applied.
 
 ### Empty or unchanged output
@@ -340,10 +343,11 @@ The config file location depends on your setup (see [Configuration Paths](../REA
    deepl config list
    ```
 
-2. Reset a specific setting:
+2. Overwrite a specific setting, or reset the whole config:
 
    ```bash
    deepl config set <key> <value>
+   deepl config reset            # clears every stored setting; add --yes to skip the prompt
    ```
 
 3. If the config file is corrupted, remove it and reconfigure:
@@ -358,6 +362,25 @@ The config file location depends on your setup (see [Configuration Paths](../REA
    export DEEPL_CONFIG_DIR=/path/to/config
    ```
 
+### "Another sync is already running" (Exit Code 7)
+
+**Cause:** `deepl sync`, `deepl sync pull` and `deepl sync resolve` take a per-project lock by writing `.deepl-sync.lock.pidfile`. A second invocation that finds a pidfile naming a live PID exits 7 rather than letting two runs overwrite each other's target files and lockfile.
+
+**Solutions:**
+
+1. Wait for the other run, or find it: the error names the PID and the time it started.
+2. If that sync is definitely not running — a crashed run whose PID has been recycled — take the lock explicitly:
+
+   ```bash
+   deepl sync --break-lock
+   ```
+
+   Deleting `.deepl-sync.lock.pidfile` by hand does the same thing. Both are unsafe if the sync really is running.
+
+3. A pidfile whose PID is simply gone is reclaimed automatically with a warning; no action needed.
+
+See [docs/SYNC.md — Concurrent sync](SYNC.md#concurrent-sync) for the full arbitration rules, and that guide's [Troubleshooting](SYNC.md#troubleshooting) section for sync-specific issues behind exit codes 10, 11 and 12.
+
 ---
 
 ## Input Validation Errors (Exit Code 6)
@@ -451,7 +474,7 @@ deepl translate ./docs --to es --output ./docs-es
 
 ### Unsupported document format
 
-Supported document formats: PDF, DOCX, DOC, PPTX, XLSX, TXT, HTML, HTM, XLF, XLIFF, SRT, JPG, JPEG, PNG. See [docs/API.md](API.md) for the complete list of supported formats.
+Supported: PDF, DOCX, DOC, PPTX, XLSX, JPG, JPEG, PNG (document API); TXT, HTML, HTM, SRT, XLF, XLIFF (routed by size); MD (cached text API); JSON, YAML, YML (structured file API — string values extracted, translated, and reassembled). See [docs/API.md](API.md) for the per-format routing rules and size limits.
 
 ```bash
 deepl translate document.docx --to fr --output translated.docx
@@ -487,7 +510,7 @@ deepl translate document.docx --to fr --output translated.docx
 | 5    | Network error                      | Yes        |
 | 6    | Invalid input                      | No         |
 | 7    | Configuration error                | No         |
-| 8    | Check found issues (write --check) | No         |
+| 8    | Check found issues (`write --check`, `correct --check`, `sync validate`) | No |
 | 9    | Voice API error                    | No         |
 | 10   | Sync drift detected (sync --frozen) | No        |
 | 11   | Sync lockfile conflict             | No         |

From 2a3a78b85b992e831227374940b5f3b02b42d4e8 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:27:00 +0200
Subject: [PATCH 243/256] docs(migration): complete the exit-code table and
 cover config and format changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The guide's own opening says the exit-code section is the change most likely to alter what
a CI pipeline decides, and unlike a removed flag it does not announce itself. The table was
missing the broadest-reach move in the release: every parse error -- unknown subcommand,
unknown option, out-of-range choice, missing argument -- went from 1 to 6. Measured both.
Any wrapper branching on exit 1 as "the CLI crashed" silently changes meaning, and it is
also the code the removed flags above it report, so the table asserted 6 without ever
stating the rule that produces it.

Eight further moves were absent, three of them turning a previous exit 0 into a failure,
plus the Ctrl-C 130 that no document records. The 6 to 5 timeout move needed a row of its
own because it moves a condition into the retriable set: a pipeline that gave up on 6 will
now retry it.

Corrected a row rather than adding to it: `sync validate` was said to exit 8 on a PO or
XLIFF project with untranslated keys. Measured, such a project checks zero pairs and exits
0 -- an empty msgstr is not a source/translation pair, so those keys never reach the checks
at all. The real condition is a translation carrying an error the check previously could not
see, because it compared the source against itself for bilingual formats.

Added the config-validation tightening, which was missing entirely and is a load-time
refusal, so it fails every sync subcommand rather than one run: BCP-47 locale validation,
`.git`/`.github` target segments, target paths beginning with `-`, globs escaping the project
root, and `--locale` values absent from `target_locales`. The nastiest is config discovery
now stopping at the repository boundary -- a monorepo whose config sat one directory above
the repo root gets "no sync config" rather than a validation error.

Added the two format-level refusals that can turn a working project into a refused one: YAML
aliases are no longer expanded, so an anchor-based catalog yields a different key set, and an
Android XML translation containing `]]>` is withheld rather than written into a CDATA section.
And `sync resolve` now applies its documented `translated_at` tie-break, so a team that has
been resolving conflicts under 1.x -- silently always keeping local -- sees the same conflict
resolve the other way.

Also: "Warnings stay on stderr, so a check for the presence of stderr output still works" is
no longer safe advice -- 2.0.0 adds three unconditional warnings 1.x did not emit, the
non-DeepL endpoint notice among them, which is the diagnostic most likely to break a
merged-stream parse. The `WriteLanguage` header said four regional codes above a table of
five, the `tms:` example showed two of the three removed keys under "remove both", and the
CHANGELOG link is now absolute since the changelog is not in the tarball.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/MIGRATION.md | 85 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 73 insertions(+), 12 deletions(-)

diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
index 7ca52aef..2ed343cd 100644
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -75,9 +75,10 @@ tms:
   enabled: true
   server: https://tms.example.com
   auto_push: true
+  auto_pull: true
   require_review: true
 
-# 2.0.0 — remove both; push explicitly instead
+# 2.0.0 — remove all three; push explicitly instead
 tms:
   enabled: true
   server: https://tms.example.com
@@ -87,6 +88,24 @@ Also gone: the `usage` command's "Speech-to-Text Usage" section and
 `speechToTextMilliseconds*` fields, following the API's deprecation of
 `speech_to_text_milliseconds_count`/`_limit`.
 
+### `.deepl-sync.yaml` is validated more strictly
+
+A config 1.x accepted can now be refused at load, which fails every `sync` subcommand
+rather than one run. All of these exit 7 with the offending value named:
+
+| Now refused | Fix |
+| --- | --- |
+| A `source_locale` or `target_locales` entry that is not a BCP-47 tag (1.x checked only three forbidden substrings) | Spell the locale as a language tag: `en`, `pt-BR`, `zh-Hans` |
+| A `target_path_pattern` containing a `.git` or `.github` path segment | Move the target out of those directories |
+| A target path that begins with `-` | Rename it, or prefix the pattern with `./` |
+| A bucket `include` glob that resolves outside the project root | Keep globs inside the repository |
+| `--locale <value>` not listed in `target_locales` | Add it to `target_locales`, or fix the spelling |
+
+**`.deepl-sync.yaml` is discovered only up to the repository boundary.** 1.x walked to the
+filesystem root, so a config in an ancestor directory outside the repo was adopted as
+project root. If yours lived there, `sync` now reports no config at all — move it inside
+the repository.
+
 ## Exit codes that moved
 
 Most of these are conditions that used to exit 0 while losing or skipping work,
@@ -95,12 +114,13 @@ should have accepted. In both directions the old code was the wrong answer.
 
 | Command | Condition | 1.x | 2.0.0 |
 | --- | --- | --- | --- |
+| any command | Unknown subcommand, unknown option, invalid `--choice` value, missing argument | 1 | 6 |
 | `sync` | Target file unreadable or unparseable | 0 | 12 |
 | `sync` | Key could not be written into the target | 0 | 12 |
 | `sync` | Validation error on a translation | 0 | 12 |
 | `sync` | File containing an empty string value | 12, every run | 0 |
 | `sync validate` | Target file cannot be read | 1 | 8 |
-| `sync validate` | PO/XLIFF project with untranslated keys | 0 | 8 |
+| `sync validate` | PO/XLIFF translation with a placeholder or ICU error the check previously could not see | 0 | 8 |
 | `sync push` / `pull` | TMS unreachable | 1 | 5 |
 | `sync --force` | Cannot prompt (piped stdin, cron, hook, `--no-input`) | 0 | 6 |
 | `watch` | Session recorded any failure | 0 | 12 |
@@ -109,8 +129,23 @@ should have accepted. In both directions the old code was the wrong answer.
 | `translate <file>` | File containing an empty string value | 1 | 0 |
 | `translate <file>` | Rate limit part-way through a structured file | 1 | 3 |
 | `write --check --format json` | Text needs no changes | 8, always | 0 |
-
-Three of these deserve a note:
+| `translate <dir>` | Every file in the directory failed | 0 | 12 |
+| `translate <dir>` | Stopped by one request-level rejection | 1 | That rejection's code (2, 4, 6) |
+| `translate <file>` | Structured file above the new size ceiling | 0 | 6 |
+| any command | Client-side timeout, or a response body cut off mid-send | 6 | 5 |
+| `sync` | One locale failed completely while others succeeded | 0 | 12 |
+| `sync` | `--concurrency` value is not a number | 0 | 6 |
+| `sync` | `--locale` value not listed in `target_locales` | 0 | 7 |
+| `voice` | Audio transcribed but a requested `--to` produced no translation | 0 | 9 |
+| any command | Interrupted with Ctrl-C | 0 | 130 |
+
+Four of these deserve a note:
+
+- **Every parse error is now exit 6, not exit 1.** An unknown subcommand, an unknown
+  option, an out-of-range `--choice` value and a missing argument all exited 1 in 1.x,
+  indistinguishable from a crash. Anything branching on exit 1 to mean "the CLI itself
+  failed" must now treat 6 as "I invoked it wrong" and keep 1 for genuinely unclassified
+  failures. This is also the code the removed flags above report.
 
 - **`sync --force` now needs `--yes` anywhere it cannot prompt**, not only under
   `CI=true`. Add `--yes` to any invocation from a git hook, cron job, `make`
@@ -122,8 +157,10 @@ Three of these deserve a note:
 - **`translate` with a lost placeholder now writes nothing and exits 5.** In 1.x
   it wrote output containing the CLI's own internal token, such as `__ Var_0 __`.
 
-Exit 3 and 5 are retriable; 12 is a partial failure with some locales succeeded.
-The full table is in [API.md](./API.md#exit-codes).
+Exit 3 and 5 are retriable; 12 is a partial failure with some locales succeeded; 130 is
+an interrupt, not a failure of the work. A client-side timeout used to report 6, which is
+*not* retriable — so a pipeline that gave up on 6 will now retry it. The full table is in
+[API.md](./API.md#exit-codes).
 
 ## Machine-readable output moved to stdout
 
@@ -140,10 +177,20 @@ deepl translate "hi" --to es --format json > out.json 2> err.txt
 deepl translate "hi" --to es --format json > out.json
 ```
 
-The exit code is still the failure signal. Warnings stay on stderr, so a check for
-*the presence of* stderr output still works; anything **parsing** stderr for the
-reason must switch to stdout. A human reading `--format json` output will see the
-envelope's `message` and `suggestion` fields where a prose sentence used to be.
+The exit code is still the failure signal. Warnings stay on stderr, but 2.0.0 emits
+warnings 1.x did not, so a check that treats *any* stderr output as failure will start
+tripping. Three are new and unconditional:
+
+- **A non-DeepL `--api-url` or `api_url` is announced** before the key is sent, loopback
+  included — so local mocks and self-hosted proxies see it on every run.
+- **A `--lang` shaped like a language tag but absent from the bundled Write list** notes
+  that it is deferring to the API instead of rejecting it.
+- **A `config.json` looser than `0600`** is repaired to `0600` with a note suggesting you
+  rotate the key. The settings in it are still honoured.
+
+Anything **parsing** stderr for a failure reason must switch to stdout. A human reading
+`--format json` output will see the envelope's `message` and `suggestion` fields where a
+prose sentence used to be.
 
 `config get` and `config list` default to `json`, so their failures carry the
 envelope with no flag passed.
@@ -235,6 +282,19 @@ of the watched directory, and a watched path that is a single file, are unchange
 replaced, where it used to leave the old value. A target that carried no `state` is
 written exactly as before.
 
+**`sync resolve` now takes the newer translation, as documented.** 1.x kept the local side
+of every conflict regardless of `translated_at`, so a teammate's newer translation was
+discarded silently. The same conflict may now resolve the other way. If you have been
+relying on resolve-keeps-mine, review the first few resolves after upgrading.
+
+**A YAML source file built on anchors and aliases yields a different key set.** Aliases are
+no longer expanded; aliased content is translated once, at its anchor. If your catalog uses
+`<<:` merges or repeated aliases, re-check `sync status` counts after the first run.
+
+**An Android XML translation containing `]]>` is refused rather than written.** It used to
+land inside a CDATA section, where it closed the section early. The key is withheld and
+counted as failed, so the run reports it.
+
 ## Tagged translation output
 
 **`--tag-handling` now pins `tag_handling_version=v2`** instead of letting the API
@@ -250,7 +310,7 @@ If you import this package's types, two published shapes changed. The `Language`
 union grew from 121 to 125 members with nothing removed, so it needs no action —
 but `WriteLanguage` did lose members.
 
-**`WriteLanguage` members are lowercase.** Four regional codes were re-spelled:
+**`WriteLanguage` members are lowercase.** Five regional codes were re-spelled:
 
 | 1.x | 2.0.0 |
 | --- | --- |
@@ -293,4 +353,5 @@ assigned it *to* a `WriteLanguage` variable needs a check or a cast.
 10. If you import the types, lowercase your `WriteLanguage` literals.
 
 The complete list of changes, including everything fixed that does not require
-action, is in [CHANGELOG.md](../CHANGELOG.md).
+action, is in
+[CHANGELOG.md](https://github.com/DeepL/deepl-cli/blob/main/CHANGELOG.md).

From 30fe0e1d70f762f73bf99f8085599eaf56044e21 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:27:15 +0200
Subject: [PATCH 244/256] fix(examples): pin the CI recipes to Node 24 and
 correct the tag-handling default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three shipped CI recipes could not run. `21-cicd-integration.sh` pinned
`node-version: '20'` and `23-sync-ci.sh` used `image: node:20`, against
`engines.node >= 24.0.0` and a hard startup gate that exits 6 below Node 24 -- so a user
who copies either gets `deepl requires Node.js >= 24` on every invocation. The two GitHub
Actions recipes in `23-sync-ci.sh` had no `setup-node` step at all, so they worked only if
the runner's default Node happened to be new enough. docs/SYNC.md already pinned 24 in the
equivalent recipes; the examples are the copy-paste surface and must not be weaker.

`39-advanced-translate.sh` told the reader v1 is the default tag handling. v2 is:
DEFAULT_TAG_HANDLING_VERSION is 'v2' and is sent on every `--tag-handling` request that does
not name a version. Corrected, and the later summary line now states which is the default
rather than leaving it open. Checked every other script for the same claim stated differently
-- no other script mentions the flag.

Two retired package names: a fixture in `12-cost-transparency.sh` and a prose line in
`36-completion.sh`. The `deepl-cli` occurrences in `28`, `29` and `30` are config and cache
directory paths, which keep that name, and are deliberately left.

Worth noting for later: the docs suite checks every `deepl` invocation in README, API.md,
SYNC.md and TROUBLESHOOTING.md against the real CLI surface, but `examples/*.sh` are outside
its scope -- which is why the tag-handling default drifted here and nothing caught it.
Verified by hand this time: no script uses a removed flag, all 40 are registered in
run-all.sh and examples/README.md, and numbering is contiguous.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 examples/12-cost-transparency.sh  | 2 +-
 examples/21-cicd-integration.sh   | 2 +-
 examples/23-sync-ci.sh            | 8 +++++++-
 examples/36-completion.sh         | 2 +-
 examples/39-advanced-translate.sh | 6 +++---
 5 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/examples/12-cost-transparency.sh b/examples/12-cost-transparency.sh
index bd406f93..97cf5e21 100755
--- a/examples/12-cost-transparency.sh
+++ b/examples/12-cost-transparency.sh
@@ -89,7 +89,7 @@ cat > "$TEMP_DIR/technical.md" << 'EOF'
 Run the following command:
 
 ```bash
-npm install deepl-cli
+npm install -g @deepl/cli
 ```
 
 Then configure your API key: `deepl auth set-key YOUR_KEY`
diff --git a/examples/21-cicd-integration.sh b/examples/21-cicd-integration.sh
index 5865ec4d..0143fb4d 100755
--- a/examples/21-cicd-integration.sh
+++ b/examples/21-cicd-integration.sh
@@ -136,7 +136,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
 
       - name: Install DeepL CLI
         run: npm install -g @deepl/cli
diff --git a/examples/23-sync-ci.sh b/examples/23-sync-ci.sh
index 1025292f..6212eefd 100755
--- a/examples/23-sync-ci.sh
+++ b/examples/23-sync-ci.sh
@@ -117,6 +117,9 @@ cat << 'WORKFLOW'
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
+         - uses: actions/setup-node@v4
+           with:
+             node-version: 24
          - run: npm install -g @deepl/cli
          - name: Check translations are up to date
            run: deepl sync --frozen
@@ -131,7 +134,7 @@ echo
 cat << 'GITLAB'
    i18n-check:
      stage: test
-     image: node:20
+     image: node:24
      script:
        - npm install -g @deepl/cli
        - deepl sync --frozen
@@ -158,6 +161,9 @@ cat << 'AUTOSYNC'
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
+         - uses: actions/setup-node@v4
+           with:
+             node-version: 24
          - run: npm install -g @deepl/cli
          - name: Sync translations
            run: deepl sync --format json
diff --git a/examples/36-completion.sh b/examples/36-completion.sh
index 577e2aa1..6cf56af4 100755
--- a/examples/36-completion.sh
+++ b/examples/36-completion.sh
@@ -46,5 +46,5 @@ echo "=== Shell Completions Examples Complete ==="
 echo
 echo "Tips:"
 echo "  - Completions cover all commands, subcommands, and flags"
-echo "  - Regenerate after upgrading deepl-cli"
+echo "  - Regenerate after upgrading @deepl/cli"
 echo "  - Works without an API key"
diff --git a/examples/39-advanced-translate.sh b/examples/39-advanced-translate.sh
index 8c2d0402..51f0e179 100755
--- a/examples/39-advanced-translate.sh
+++ b/examples/39-advanced-translate.sh
@@ -49,8 +49,8 @@ echo
 echo "✓ Translation with v2 tag handling complete"
 echo
 echo "Tag handling versions:"
-echo "  --tag-handling-version v1   Original tag handling (default)"
-echo "  --tag-handling-version v2   Improved structure handling"
+echo "  --tag-handling-version v2   Improved structure handling (default)"
+echo "  --tag-handling-version v1   Original tag handling (heading for deprecation)"
 echo "  (requires --tag-handling xml or --tag-handling html)"
 echo
 
@@ -157,7 +157,7 @@ echo "=== Advanced Options Summary ==="
 echo
 echo "Tag handling:"
 echo "  --tag-handling <xml|html>          Enable tag handling mode"
-echo "  --tag-handling-version <v1|v2>     Tag handling version (v2 = improved)"
+echo "  --tag-handling-version <v1|v2>     Tag handling version (v2 = improved, default)"
 echo
 echo "API endpoint:"
 echo "  --api-url <url>                    Custom API endpoint URL"

From 596f012969be4c40b91452762389b553166e0b4f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:27:39 +0200
Subject: [PATCH 245/256] docs(contributing): correct the release procedure,
 the CI gate list and the file index
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The release checklist in CLAUDE.md never published the package -- the one thing 2.0.0
exists to do. Its five steps produce a tag and a GitHub Release and stop; release.yml
carries no `npm publish` step or NPM_TOKEN by design, saying publishing happens from
GitLab. So a lead following it verbatim ships a v2.0.0 tag while `npm install -g @deepl/cli`,
the command MIGRATION.md and the README tell every 1.x user to run, keeps 404ing. The
step now says the tag alone does not make the package installable, and names the
verification. It stops short of naming the GitLab job: there is no .gitlab-ci.yml in this
checkout, so that has to be filled in by someone who can read it.

Three other gaps in the same list: nothing refreshed SECURITY.md's supported-versions
table or checked MIGRATION.md against the section just dated, both version-scoped
documents; nothing reviewed the tarball, which is where a `files` mistake surfaces; and
`git push` named no remote in a checkout with three.

Step 1 also justified itself with a false premise -- that a stale Write list breaks
`write`/`correct` because they reject unknown codes locally. They do not: a code shaped
like a language tag but absent from the snapshot is sent to the API with a warning, which
is measurable (`--lang xx-yy` warns and defers; only malformed input is rejected). What
actually goes stale is offline `deepl languages`, the derived tiers, and the bundled-options
list in error messages. Harmless to follow, but the wrong reason, and misleading to whoever
edits that step next.

CONTRIBUTING's "full check suite" named four of the six gates CI runs, omitting
`format:check` and `check-deps`, so a contributor who ran the documented command could still
fail CI. Its PR checklist had rows for CHANGELOG, README, API.md and run-all.sh but none for
docs/MIGRATION.md, now a maintained document any breaking change must touch.

CLAUDE.md's architecture block omitted three services and placed TmsClient in the API layer
-- it is src/sync/tms-client.ts, which the block's own next line puts under the sync engine
-- and Key Project Files listed two of the seven documents a contributor needs, missing the
migration guide on the release whose headline deliverable it is.

The bug-report template offered "source, npm link, other" as install methods, written for a
pre-publish world: the published path is not among them, so every 2.x reporter picks "other"
-- and install method is what tells a maintainer whether a report is a packaging bug.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/ISSUE_TEMPLATE/bug_report.md |  2 +-
 CLAUDE.md                            | 28 +++++++++++++++++++---------
 CONTRIBUTING.md                      |  4 +++-
 3 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 2e8b450a..b93748d8 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -15,7 +15,7 @@ A clear, concise description of the bug.
 - **DeepL CLI version**: (run `deepl --version`)
 - **Node.js version**: (run `node --version`)
 - **Operating system**: (e.g., macOS 14.5, Ubuntu 22.04, Windows 11)
-- **Install method**: (source, npm link, other)
+- **Install method**: (npm global, npx, Homebrew, source checkout, npm link, other)
 
 ## Reproduction Steps
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 32207b01..9a57abd0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,14 +15,16 @@ DeepL CLI is a command-line interface for the DeepL API that integrates translat
 ```
 CLI Commands (translate, write, voice, sync, watch, glossary, tm, …)
            ↓
-Service Layer (Translation, Write, Voice, Batch, Watch, Glossary,
-               TranslationMemory, StyleRules, Admin, Document,
-               GitHooks, Usage, Detect, Languages)
+Service Layer (Translation, Write, Voice, VoiceStreamSession, Batch, Watch,
+               Glossary, TranslationMemory, StyleRules, Admin, Document,
+               FileTranslation, StructuredFileTranslation, GitHooks, Usage,
+               Detect, Languages)
            ↓                         ↓
-Sync Engine (src/sync)        Format Parsers (src/formats — 11 i18n formats)
+Sync Engine (src/sync —        Format Parsers (src/formats — 11 i18n formats)
+  incl. TmsClient)
            ↓                         ↓
 API Client (Translate, Write, Glossary, Document, Voice,
-            StyleRules, Admin, TMS)
+            StyleRules, Admin)
            ↓
 Storage (node:sqlite Cache, Config) + Static Data (src/data — language registry)
 ```
@@ -43,6 +45,11 @@ Storage (node:sqlite Cache, Config) + Static Data (src/data — language registr
 
 - **CHANGELOG.md** - Release history and version notes
 - **docs/API.md** - Complete CLI command reference
+- **docs/MIGRATION.md** - 1.x → 2.0.0 upgrade guide; update it with any breaking change
+- **docs/SYNC.md** - Continuous-localization reference and `.deepl-sync.yaml` schema
+- **docs/TROUBLESHOOTING.md** - Diagnostics for common failures
+- **CONTRIBUTING.md** - Contributor workflow and PR checklist
+- **SECURITY.md** - Supported versions and vulnerability reporting
 
 ## Development Philosophy
 
@@ -77,11 +84,14 @@ Use **Semantic Versioning** with **Conventional Commits**:
 
 ### When Cutting a Release
 
-1. Refresh the bundled language lists: `npm run generate:languages` (needs `DEEPL_API_KEY` and a current build). Commit if changed — `npm run check:languages` reports which list drifted without writing. Both come from `GET /v3/languages`: the translation snapshot (`resource=translate_text`) and the Write target list (`resource=write`). A stale translation snapshot no longer breaks translation, since validation defers to the API, but `deepl languages` offline and the derived tiers do go stale. **A stale Write list does break `write`/`correct`**, which reject unknown codes locally — so this step matters most for that list
+1. Refresh the bundled language lists: `npm run generate:languages` (needs `DEEPL_API_KEY` and a current build). Commit if changed — `npm run check:languages` reports which list drifted without writing. Both come from `GET /v3/languages`: the translation snapshot (`resource=translate_text`) and the Write target list (`resource=write`). Neither list is a hard gate: a well-formed code absent from either defers to the API with a warning, so a language DeepL adds is reachable before a regenerate. What does go stale is `deepl languages` offline, the derived core/regional/extended tiers, and the "Bundled options:" list `write`/`correct` print in their errors. Rebuild after regenerating, since the generator reads the derivation out of `dist/`
 2. Move Unreleased items to `## [X.Y.Z] - YYYY-MM-DD`
-3. Set the version with `npm version X.Y.Z --no-git-tag-version` (updates `package.json` and the lockfile together; the release workflow refuses to publish if the tag and `package.json` disagree)
-4. Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z: <summary>"`
-5. Push: `git push && git push --tags`
+3. For a MAJOR: update the supported-versions table in `SECURITY.md`, and confirm `docs/MIGRATION.md` covers every **Changed**, **Removed** and action-requiring **Security** entry in the section just dated
+4. Set the version with `npm version X.Y.Z --no-git-tag-version` (updates `package.json` and the lockfile together; the release workflow refuses to publish if the tag and `package.json` disagree)
+5. Review the tarball: `npm pack --dry-run` — confirm the file list, the version, and that nothing private is in it
+6. Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z: <summary>"`
+7. Push to `github` only — `origin` (internal GitLab) autosyncs from it: `git push github main && git push github vX.Y.Z`. Pushing the tag triggers `.github/workflows/release.yml`, which records the GitHub Release and nothing more
+8. **Publish to npm separately.** `release.yml` deliberately carries no `npm publish` step or `NPM_TOKEN` — its header says publishing happens from GitLab — so the tag alone does not make the package installable. Run that publish job, then verify from a clean machine: `npm view @deepl/cli version` and `npx @deepl/cli@X.Y.Z --version`
 
 ## Code Style
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2978ad3e..1c9a9e84 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -196,8 +196,9 @@ Contributions must be licensed under the same license as the project:
 2. **Write tests first**, then implement the feature (TDD).
 3. **Run the full check suite** before pushing:
    ```bash
-   npm run test:coverage && npm run lint && npm run type-check && npm run build
+   npm run format:check && npm run lint && npm run type-check && npm run check-deps && npm run build && npm run test:coverage
    ```
+   These are the same six gates CI runs, in the same order.
    `test:coverage` runs the same suite as `npm test` and additionally enforces
    the coverage thresholds, which is what CI gates on.
 4. **Open a PR** with a clear description covering:
@@ -217,6 +218,7 @@ Contributions must be licensed under the same license as the project:
 - [ ] `CHANGELOG.md` updated under **Unreleased** section
 - [ ] `README.md` updated if user-facing feature changed
 - [ ] `docs/API.md` updated if command/flag added or changed
+- [ ] `docs/MIGRATION.md` updated if the change is breaking or requires action from an existing user
 - [ ] Example script added/updated in `examples/` for new features
 - [ ] Added new example script to `examples/run-all.sh` EXAMPLES array (for new CLI commands)
 

From f840f7fee80ea9a6ab653f7a13d2f434a45d8fc0 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:27:55 +0200
Subject: [PATCH 246/256] chore(release): set the version to 2.0.0 and finish
 the publish surface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Set via `npm version 2.0.0 --no-git-tag-version`, so package.json and the lockfile move
together. This was the one hard publish blocker: release.yml refuses to publish when the tag
and package.json disagree, so a v2.0.0 tag hard-failed against 1.2.0 -- and its changelog
extraction matches a `## [X.Y.Z]` heading, which the previous commit supplies. SECURITY.md
and docs/API.md were already written for 2.0.0, so the tree was inconsistent in two
directions until now. Verified: `npm pack --dry-run` reports 2.0.0, and `deepl --version`
agrees.

Ship `docs/` in the tarball. README.md is the npmjs.com landing page and carried 13 relative
links into `docs/`, all of which 404 there, and the file was not in the installed package
either -- so the migration guide a 1.x user is pointed to was unreachable by both routes. The
README links are now absolute (previous commit), which fixes the browser; shipping docs/ fixes
the `node_modules` reader and makes MIGRATION.md available offline. Costs 98 KB packed,
263 to 361 KB. CHANGELOG.md is deliberately not shipped -- 388 KB for a link that the
absolute URL already fixes.

`repository.url` is now npm's canonical `git+https://...git` form. The manifest test pinned the
bare form; its stated guarantee is the DeepL org rather than the URL shape, so it moves to the
canonical value and stays an exact pin rather than being loosened.

The `files` map keeps its three `!dist/**` exclusions even though the build no longer emits
maps or writes tsbuildinfo into dist. They are dead today but cheap insurance against a
tsconfig change re-enabling either, and a test asserts two of them.

Keywords gained the release's headline capabilities -- Write, glossaries, translation memory,
gettext, XLIFF, continuous localization -- none of which were discoverable for a package that
has never been on the registry.

Also corrects the SyncJsonOutput docblock, which promised its fields stable "across 1.x" in the
2.0.0 tree; it is the only package-version reference in src/, and the shape gained fields this
release.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 package-lock.json                   |  4 ++--
 package.json                        | 13 ++++++++++---
 src/cli/commands/sync-command.ts    |  2 +-
 tests/unit/package-manifest.test.ts |  6 +++++-
 4 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 8fe6751d..9cf6a7da 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@deepl/cli",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@deepl/cli",
-      "version": "1.2.0",
+      "version": "2.0.0",
       "license": "MIT",
       "dependencies": {
         "@inquirer/prompts": "^8.5.2",
diff --git a/package.json b/package.json
index 94c2fc82..380b4a8d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepl/cli",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,6 +19,7 @@
     "!dist/**/*.tsbuildinfo",
     "!dist/**/*.js.map",
     "!dist/**/*.d.ts.map",
+    "docs",
     "README.md",
     "LICENSE",
     "SECURITY.md"
@@ -58,7 +59,13 @@
     "localization",
     "translation-tool",
     "command-line",
-    "typescript"
+    "typescript",
+    "deepl-write",
+    "glossary",
+    "translation-memory",
+    "gettext",
+    "xliff",
+    "continuous-localization"
   ],
   "author": "DeepL SE",
   "license": "MIT",
@@ -111,7 +118,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/DeepL/deepl-cli"
+    "url": "git+https://github.com/DeepL/deepl-cli.git"
   },
   "bugs": {
     "url": "https://github.com/DeepL/deepl-cli/issues"
diff --git a/src/cli/commands/sync-command.ts b/src/cli/commands/sync-command.ts
index 4be2fa8a..3fbfc904 100644
--- a/src/cli/commands/sync-command.ts
+++ b/src/cli/commands/sync-command.ts
@@ -232,7 +232,7 @@ function formatCostEstimate(characters: number): string {
 
 /**
  * Stable public shape emitted by `deepl sync --format json`.
- * Every field listed here is guaranteed stable across 1.x.
+ * Every field listed here is guaranteed stable across 2.x.
  * Internal SyncResult fields not listed here are intentionally omitted.
  */
 export interface SyncJsonOutput {
diff --git a/tests/unit/package-manifest.test.ts b/tests/unit/package-manifest.test.ts
index f38ec230..9010cf2e 100644
--- a/tests/unit/package-manifest.test.ts
+++ b/tests/unit/package-manifest.test.ts
@@ -117,7 +117,11 @@ describe('package.json manifest', () => {
     });
 
     it('should point repository metadata at the DeepL org, not the legacy DeepLcom redirect', () => {
-      expect(pkg.repository.url).toBe('https://github.com/DeepL/deepl-cli');
+      // `repository.url` carries npm's canonical `git+….git` form; `bugs` and
+      // `homepage` are plain browsable URLs.
+      expect(pkg.repository.url).toBe(
+        'git+https://github.com/DeepL/deepl-cli.git'
+      );
       expect(pkg.bugs.url).toBe('https://github.com/DeepL/deepl-cli/issues');
       expect(pkg.homepage).toBe('https://github.com/DeepL/deepl-cli#readme');
     });

From dc0467f15074ec302e8ab784882f20b0cd75a649 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 09:28:47 +0200
Subject: [PATCH 247/256] docs(changelog): record the examples CI and
 tag-handling fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The recipe fix is user-facing even though examples/ is not in the tarball: a reader who
copied the GitHub Actions or GitLab CI block got a job that exited 6 on every run. Held to
the same brevity as the rest of the condensed section, and placed under Fixed beside the
existing examples entry.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0bb37853..7a923357 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -256,6 +256,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **docs**: Further corrections. The README's translate examples no longer show a `Translation (XX):` label the CLI never emits, and `--model-type` (no CLI default), `--config` precedence (replaces the config file only; the cache path is unaffected), unknown-command and `deepl detect` sample output, and the nonexistent 10 MB PDF cap (the document limit is 30 MB uniformly) are corrected; the README now covers `deepl sync`, `deepl tm` and all nine `style-rules` subcommands, with dead in-page anchors repaired and `docs/SYNC.md` listed under Documentation. `TROUBLESHOOTING.md`'s exit-code table gains codes 10–12 (SyncDrift, SyncConflict, PartialFailure) and its environment-variable table gains `TMS_API_KEY`, `TMS_TOKEN`, `FORCE_COLOR` and `TERM`; sync JSON-contract stability promises are rescoped from "1.x" to "within a major version"; the GitHub Actions recipes in `docs/SYNC.md` pin Node 24; `CONTRIBUTING.md` no longer cites Zod (validation is commander `Option.choices()` plus hand-written validators); and `examples/README.md` no longer references a nonexistent `sample-files/` directory.
 - **examples**: `examples/03-batch-processing.sh` no longer hides five `--output <dir>` failures behind `2>/dev/null`, `|| true` and a `(cached or completed)` message that reported a cache hit for a call that had errored — so `npm run examples` reported 37/37 passed while this was broken. Section 8's cache comparison now times calls that actually succeed.
 
+- **examples**: The GitHub Actions and GitLab CI recipes in `examples/21-cicd-integration.sh` and `examples/23-sync-ci.sh` target Node 24 and set up Node explicitly. They pinned Node 20, or omitted `setup-node` entirely, so a copied recipe exited 6 on the Node floor. `examples/39-advanced-translate.sh` also no longer calls `--tag-handling-version v1` the default; v2 is.
+
 ### Security
 
 - **sync**: `deepl sync validate` was inert for PO and XLIFF buckets and reported the opposite of the truth. The gate compares each target value against its source, but for a bilingual format it read the msgid / `<source>` on both sides, so it was comparing the source against itself: a `msgstr` dropping a placeholder its msgid carries **exited 0** reporting `1 warning(s)`, and that warning was `Translation is identical to source text`, a false positive raised against every entry in every PO and XLIFF bucket, correct translations included. It now exits 8 with `ERROR es/Hello {name}: Missing placeholders in translation: {name}`. Anything using this as a CI gate on a PO or XLIFF project was gating on nothing.

From 77583a7e58ea5f268272ef4ab36d0094c7373736 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 11:55:12 +0200
Subject: [PATCH 248/256] fix(sync): apply the per-locale model_type override

translation.locale_overrides.<locale>.model_type was on the config allowlist
and validated per locale against translation_memory, but the translator only
ever read the top-level translation.model_type, so the per-locale value was
silently dropped. The validator's own error message named that inert scope as
the remedy, so the CLI walked users into a key with no effect.

A locale configuring translation memory per locale therefore got requests the
TM could not be applied to -- translation memory requires quality_optimized --
silently, and was billed for them.

The override now resolves exactly like every sibling on the same options
object (formality, translation_memory_threshold, custom_instructions,
style_id): the per-locale value wins, otherwise the top-level one applies.
SyncLocaleOverrides declares the field. As with those siblings, a per-locale
override consequently also takes precedence over --model-type, which writes
the top-level setting.

Also closes the mirror-image gap in the pairing check. It only inspected a
model_type written inside the same override, so the opposite inheritance
direction -- translation_memory set per locale, model_type inherited from the
top level -- was accepted and sent to the API with the same hazard. The check
now evaluates the effective value for that locale and names where the
offending one came from, so such a config exits 7 before any API call.
---
 src/sync/sync-config.ts              |  15 +++-
 src/sync/sync-locale-translator.ts   |   2 +-
 src/sync/types.ts                    |   1 +
 tests/unit/sync/sync-config.test.ts  |  36 +++++++++
 tests/unit/sync/sync-service.test.ts | 117 +++++++++++++++++++++++++++
 5 files changed, 166 insertions(+), 5 deletions(-)

diff --git a/src/sync/sync-config.ts b/src/sync/sync-config.ts
index e798db92..fabe55d2 100644
--- a/src/sync/sync-config.ts
+++ b/src/sync/sync-config.ts
@@ -259,14 +259,20 @@ function validateTmThreshold(value: unknown, keyPath: string): void {
 function validateTmModelType(
   translation: Record<string, unknown>,
   keyPath: string,
-  tmInherited: boolean
+  tmInherited: boolean,
+  inheritedModelType?: unknown
 ): void {
   const hasTm = tmInherited || translation['translation_memory'] !== undefined;
   if (!hasTm) return;
-  const mt = translation['model_type'];
+  // Mirrors how the translator resolves the value: a locale override wins, and
+  // otherwise the top-level setting applies to this locale too.
+  const own = translation['model_type'];
+  const mt = own ?? inheritedModelType;
   if (mt !== undefined && mt !== 'quality_optimized') {
+    const source =
+      own !== undefined ? `${keyPath}.model_type` : 'translation.model_type';
     throw new ConfigError(
-      `${keyPath}.model_type must be 'quality_optimized' when translation_memory is set, got: ${String(mt)}`,
+      `${source} must be 'quality_optimized' when translation_memory is set, got: ${String(mt)}`,
       `Set ${keyPath}.model_type: quality_optimized or remove translation_memory.`
     );
   }
@@ -673,7 +679,8 @@ export function validateSyncConfig(raw: unknown): SyncConfig {
         validateTmModelType(
           ov,
           `translation.locale_overrides.${locale}`,
-          topLevelTm
+          topLevelTm,
+          t['model_type']
         );
       }
     }
diff --git a/src/sync/sync-locale-translator.ts b/src/sync/sync-locale-translator.ts
index 3b801aac..f6268a7e 100644
--- a/src/sync/sync-locale-translator.ts
+++ b/src/sync/sync-locale-translator.ts
@@ -306,7 +306,7 @@ export class LocaleTranslator {
       translationMemoryThreshold:
         localeOverrides?.translation_memory_threshold ??
         config.translation?.translation_memory_threshold,
-      modelType: config.translation?.model_type,
+      modelType: localeOverrides?.model_type ?? config.translation?.model_type,
       customInstructions:
         localeOverrides?.custom_instructions ??
         config.translation?.custom_instructions,
diff --git a/src/sync/types.ts b/src/sync/types.ts
index 90f0d0cd..631d3cf3 100644
--- a/src/sync/types.ts
+++ b/src/sync/types.ts
@@ -5,6 +5,7 @@ import type { ModelType } from '../types/api.js';
 
 export interface SyncLocaleOverrides {
   formality?: Formality;
+  model_type?: ModelType;
   glossary?: string;
   translation_memory?: string;
   translation_memory_threshold?: number;
diff --git a/tests/unit/sync/sync-config.test.ts b/tests/unit/sync/sync-config.test.ts
index edb4d388..cc5f22c1 100644
--- a/tests/unit/sync/sync-config.test.ts
+++ b/tests/unit/sync/sync-config.test.ts
@@ -1033,6 +1033,42 @@ describe('sync-config', () => {
         });
         expect(result.translation?.model_type).toBe('latency_optimized');
       });
+
+      // The top-level model_type applies to a locale that does not override it,
+      // so a per-locale TM inherits it and the pairing has to be checked there.
+      it('should reject a per-locale TM that inherits a non-quality top-level model_type', () => {
+        expect(() =>
+          validateSyncConfig({
+            ...baseConfig,
+            translation: {
+              model_type: 'latency_optimized',
+              locale_overrides: {
+                de: { translation_memory: 'de-tm' },
+              },
+            },
+          })
+        ).toThrow(
+          "translation.model_type must be 'quality_optimized' when translation_memory is set, got: latency_optimized"
+        );
+      });
+
+      it('should accept a per-locale TM whose own model_type overrides a non-quality top-level value', () => {
+        const result = validateSyncConfig({
+          ...baseConfig,
+          translation: {
+            model_type: 'latency_optimized',
+            locale_overrides: {
+              de: {
+                translation_memory: 'de-tm',
+                model_type: 'quality_optimized',
+              },
+            },
+          },
+        });
+        expect(result.translation?.locale_overrides?.['de']?.model_type).toBe(
+          'quality_optimized'
+        );
+      });
     });
 
     describe('strict unknown-field rejection', () => {
diff --git a/tests/unit/sync/sync-service.test.ts b/tests/unit/sync/sync-service.test.ts
index b157bfe6..19698073 100644
--- a/tests/unit/sync/sync-service.test.ts
+++ b/tests/unit/sync/sync-service.test.ts
@@ -1982,6 +1982,123 @@ describe('SyncService', () => {
     });
   });
 
+  describe('sync() — per-locale model_type override', () => {
+    const TM_UUID_DE = 'dddddddd-dddd-dddd-dddd-dddddddddddd';
+
+    const modelTypeOf = (calls: unknown[][], locale: string): unknown =>
+      (
+        calls.find(
+          (c) => (c[1] as Record<string, unknown>)['targetLang'] === locale
+        )![1] as Record<string, unknown>
+      )['modelType'];
+
+    it('should prefer the per-locale model_type and leave other locales on the top-level value', async () => {
+      setupLockManager(makeEmptyLockFile());
+      const translateBatch = jest.fn().mockResolvedValue([
+        { text: 'x', billedCharacters: 1 },
+        { text: 'y', billedCharacters: 1 },
+      ]);
+      const { service } = createService({ translateBatch });
+
+      mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
+      mockReadFile.mockImplementation(async (p: unknown) => {
+        if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
+        throw enoent();
+      });
+
+      await service.sync(
+        makeConfig({
+          target_locales: ['de', 'fr'],
+          translation: {
+            model_type: 'latency_optimized',
+            locale_overrides: { de: { model_type: 'quality_optimized' } },
+          },
+        })
+      );
+
+      expect(modelTypeOf(translateBatch.mock.calls, 'de')).toBe(
+        'quality_optimized'
+      );
+      expect(modelTypeOf(translateBatch.mock.calls, 'fr')).toBe(
+        'latency_optimized'
+      );
+    });
+
+    it('should send the per-locale model_type when no top-level model_type is set', async () => {
+      setupLockManager(makeEmptyLockFile());
+      const translateBatch = jest.fn().mockResolvedValue([
+        { text: 'x', billedCharacters: 1 },
+        { text: 'y', billedCharacters: 1 },
+      ]);
+      const { service } = createService({ translateBatch });
+
+      mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
+      mockReadFile.mockImplementation(async (p: unknown) => {
+        if (String(p) === '/test/locales/en.json') return SOURCE_JSON;
+        throw enoent();
+      });
+
+      await service.sync(
+        makeConfig({
+          target_locales: ['de', 'fr'],
+          translation: {
+            locale_overrides: { de: { model_type: 'quality_optimized' } },
+          },
+        })
+      );
+
+      expect(modelTypeOf(translateBatch.mock.calls, 'de')).toBe(
+        'quality_optimized'
+      );
+      expect(modelTypeOf(translateBatch.mock.calls, 'fr')).toBeUndefined();
+    });
+
+    // The billing hazard the validator was guarding against: a per-locale TM is
+    // only honoured by the API under quality_optimized, so the model_type that
+    // sits beside it has to reach the same request.
+    it('should apply a per-locale translation_memory together with its model_type', async () => {
+      setupLockManager(makeEmptyLockFile());
+      const translateBatch = jest.fn().mockResolvedValue([
+        { text: 'x', billedCharacters: 1 },
+        { text: 'y', billedCharacters: 1 },
+      ]);
+      const { service, mockTranslation } = createService({ translateBatch });
+      mockTranslation.listTranslationMemories.mockResolvedValue([
+        {
+          translation_memory_id: TM_UUID_DE,
+          name: 'de-tm',
+          source_language: 'en',
+          target_languages: ['de'],
+        },
+      ]);
+
+      mockFg.mockResolvedValue(['/test/locales/en.json'] as never);
+      mockReadFile.mockResolvedValue(SOURCE_JSON);
+
+      await service.sync(
+        makeConfig({
+          target_locales: ['de'],
+          translation: {
+            locale_overrides: {
+              de: {
+                translation_memory: 'de-tm',
+                model_type: 'quality_optimized',
+              },
+            },
+          },
+        })
+      );
+
+      const deCall = translateBatch.mock.calls.find(
+        (c) => (c[1] as Record<string, unknown>)['targetLang'] === 'de'
+      );
+      expect(deCall![1]).toMatchObject({
+        translationMemoryId: TM_UUID_DE,
+        modelType: 'quality_optimized',
+      });
+    });
+  });
+
   describe('sync() — per-locale glossary override resolution', () => {
     it('should resolve per-locale glossary name via glossaryService', async () => {
       setupLockManager(makeEmptyLockFile());

From a11ab82f50e4bb6200ea0318fb4e5d3fa951b6e1 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 11:55:38 +0200
Subject: [PATCH 249/256] fix(runtime)!: require Node 24.15.0, where
 node:sqlite stops being experimental

engines.node said >=24.0.0 on the claim that Node 24 is the first release where
node:sqlite is non-experimental. Measured across 24.0.0, 24.5.0, 24.9.0,
24.12.0, 24.13.0, 24.14.0, 24.15.0 and 24.18.x: every version below 24.15.0
emits "ExperimentalWarning: SQLite is an experimental feature and might change
at any time". 24.15.0 is the first clean one.

So the declared floor advertised a runtime that writes a warning to stderr on
every cache-backed command. That is not cosmetic: as of 2.0.0 a failing command
under --format json writes its envelope to stdout, and callers that merge
stderr into stdout and parse the result get a stray line.

The startup guard was major-only, so 24.0.0 through 24.14.0 passed it and then
produced exactly the ExperimentalWarning the guard exists to prevent -- its
docstring promised coverage the comparison did not implement. The check is now
major and minor aware, and reports the full minimum version.

Behaviour preserved at the edges: an unparseable version still fails open, and
an older major given without a minor (22) is still rejected rather than falling
through the new minor comparison.

BREAKING CHANGE: engines.node moves from >=24.0.0 to >=24.15.0. Node 24.0.0
through 24.14.0 are no longer supported and now exit 6 at startup.
---
 package.json                              |  2 +-
 src/cli/node-version-check.ts             | 25 ++++++++++--
 tests/unit/cli/node-version-check.test.ts | 49 ++++++++++++++++++++---
 3 files changed, 67 insertions(+), 9 deletions(-)

diff --git a/package.json b/package.json
index 380b4a8d..31696646 100644
--- a/package.json
+++ b/package.json
@@ -70,7 +70,7 @@
   "author": "DeepL SE",
   "license": "MIT",
   "engines": {
-    "node": ">=24.0.0",
+    "node": ">=24.15.0",
     "npm": ">=9.0.0"
   },
   "overrides": {
diff --git a/src/cli/node-version-check.ts b/src/cli/node-version-check.ts
index 52c8cdbc..643318d6 100644
--- a/src/cli/node-version-check.ts
+++ b/src/cli/node-version-check.ts
@@ -2,11 +2,18 @@
  * Startup engine check. Runs before anything that can load node:sqlite so
  * unsupported runtimes get one clear line instead of an ExperimentalWarning
  * or a native-module crash.
+ *
+ * The floor is a minor version, not just a major: node:sqlite stopped emitting
+ * `ExperimentalWarning: SQLite is an experimental feature` only in 24.15.0, and
+ * that warning goes to stderr on every cache-backed command — which breaks
+ * callers that merge stderr into stdout and parse `--format json`.
  */
 
 import { ExitCode } from '../utils/exit-codes.js';
 
 export const MIN_NODE_MAJOR = 24;
+export const MIN_NODE_MINOR = 15;
+export const MIN_NODE_VERSION = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}.0`;
 
 /**
  * Return the error line for an unsupported Node.js version, or null when the
@@ -15,11 +22,23 @@ export const MIN_NODE_MAJOR = 24;
 export function unsupportedNodeVersionMessage(
   version: string = process.versions.node
 ): string | null {
-  const major = Number(version.split('.')[0]);
-  if (!Number.isInteger(major) || major >= MIN_NODE_MAJOR) {
+  const parts = version.split('.');
+  const major = Number(parts[0]);
+  if (!Number.isInteger(major)) {
     return null;
   }
-  return `deepl requires Node.js >= ${MIN_NODE_MAJOR}, you are running v${version}. Upgrade Node.js to use the DeepL CLI.`;
+  if (major !== MIN_NODE_MAJOR) {
+    return major > MIN_NODE_MAJOR ? null : unsupportedMessage(version);
+  }
+  const minor = Number(parts[1]);
+  if (!Number.isInteger(minor) || minor >= MIN_NODE_MINOR) {
+    return null;
+  }
+  return unsupportedMessage(version);
+}
+
+function unsupportedMessage(version: string): string {
+  return `deepl requires Node.js >= ${MIN_NODE_VERSION}, you are running v${version}. Upgrade Node.js to use the DeepL CLI.`;
 }
 
 export function assertSupportedNodeVersion(
diff --git a/tests/unit/cli/node-version-check.test.ts b/tests/unit/cli/node-version-check.test.ts
index 6b59f407..e962a85a 100644
--- a/tests/unit/cli/node-version-check.test.ts
+++ b/tests/unit/cli/node-version-check.test.ts
@@ -1,5 +1,5 @@
 import {
-  MIN_NODE_MAJOR,
+  MIN_NODE_VERSION,
   assertSupportedNodeVersion,
   unsupportedNodeVersionMessage,
 } from '../../../src/cli/node-version-check';
@@ -11,22 +11,45 @@ describe('node-version-check', () => {
       const message = unsupportedNodeVersionMessage('22.17.0');
 
       expect(message).not.toBeNull();
-      expect(message).toContain(`Node.js >= ${MIN_NODE_MAJOR}`);
+      expect(message).toContain(`Node.js >= ${MIN_NODE_VERSION}`);
       expect(message).toContain('v22.17.0');
       expect(message).not.toContain('\n');
     });
 
-    it('should return null for the minimum supported major', () => {
-      expect(unsupportedNodeVersionMessage('24.0.0')).toBeNull();
+    it('should return null for the minimum supported version', () => {
+      expect(unsupportedNodeVersionMessage(MIN_NODE_VERSION)).toBeNull();
+    });
+
+    it('should return null for newer minors within the supported major', () => {
+      expect(unsupportedNodeVersionMessage('24.18.1')).toBeNull();
     });
 
     it('should return null for newer majors', () => {
       expect(unsupportedNodeVersionMessage('25.3.1')).toBeNull();
     });
 
+    // node:sqlite still emits `ExperimentalWarning` on these, so they are not
+    // supported even though the major matches.
+    it.each(['24.0.0', '24.5.0', '24.14.0'])(
+      'should reject %s, where node:sqlite is still experimental',
+      (version) => {
+        expect(unsupportedNodeVersionMessage(version)).toContain(
+          `Node.js >= ${MIN_NODE_VERSION}`
+        );
+      }
+    );
+
     it('should fail open on unparseable versions', () => {
       expect(unsupportedNodeVersionMessage('weird')).toBeNull();
     });
+
+    it('should still reject an older major given without a minor', () => {
+      expect(unsupportedNodeVersionMessage('22')).toContain('v22');
+    });
+
+    it('should fail open on a supported major given without a minor', () => {
+      expect(unsupportedNodeVersionMessage('24')).toBeNull();
+    });
   });
 
   describe('assertSupportedNodeVersion', () => {
@@ -47,13 +70,29 @@ describe('node-version-check', () => {
       errorSpy.mockRestore();
     });
 
-    it('should be a no-op on supported versions', () => {
+    it('should exit on a Node 24 older than the node:sqlite stability floor', () => {
       const exitSpy = jest
         .spyOn(process, 'exit')
         .mockImplementation((() => undefined) as never);
+      const errorSpy = jest
+        .spyOn(console, 'error')
+        .mockImplementation(() => undefined);
 
       assertSupportedNodeVersion('24.5.0');
 
+      expect(exitSpy).toHaveBeenCalledWith(ExitCode.InvalidInput);
+
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    });
+
+    it('should be a no-op on supported versions', () => {
+      const exitSpy = jest
+        .spyOn(process, 'exit')
+        .mockImplementation((() => undefined) as never);
+
+      assertSupportedNodeVersion('24.15.0');
+
       expect(exitSpy).not.toHaveBeenCalled();
       exitSpy.mockRestore();
     });

From f2e9b5b39dde9d35068654f6e594191c541ead22 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 11:55:56 +0200
Subject: [PATCH 250/256] ci: verify the packaged artifact and exercise the
 engines floor

Nothing in CI packed or ran the published artifact. The suites execute from the
working tree, and bin has its own module graph, so a broken programmatic entry
point ships while every test passes -- which is how a package entry that threw
ERR_UNSUPPORTED_DIR_IMPORT reached a release once already.

The new job packs the tarball, installs it globally to run deepl --version,
then installs it into a throwaway consumer package and imports @deepl/cli. The
consumer step is separate because Node does not resolve bare specifiers out of
the global prefix. It asserts the entry exports something rather than merely
resolving, so an empty emitted module fails too.

The matrix also pins 24.15.0 alongside 24. Bare 24 resolves to the latest 24.x,
so the engines.node floor was never exercised.

release.yml gains the direction of the mirror. Its note correctly said
publishing happens from GitLab but not which way the code flows, and the
changelog had it backwards. GitHub is upstream, GitLab pull-mirrors this
repository and publishes from there, so a tag pushed here reaches the pipeline
on its own and nobody should hand-push to GitLab.
---
 .github/workflows/ci.yml      | 54 ++++++++++++++++++++++++++++++++++-
 .github/workflows/release.yml |  4 +++
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 09f6861d..36e95864 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -16,7 +16,10 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [24]
+        # 24.15.0 is the `engines.node` floor — the release where node:sqlite
+        # stopped emitting an ExperimentalWarning. Bare `24` resolves to the
+        # latest 24.x, so without the pin the declared floor is never exercised.
+        node-version: ['24.15.0', '24']
 
     steps:
       - uses: actions/checkout@v7
@@ -36,3 +39,52 @@ jobs:
       - run: npm run check-deps
       - run: npm run build
       - run: npm run test:coverage
+
+  # The suites run from the working tree, so nothing above proves the published
+  # artifact works. `bin` and the package entry have separate module graphs — a
+  # broken entry point ships while the CLI still passes every test.
+  package:
+    name: Packaged artifact
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+
+      - name: Pack
+        id: pack
+        run: echo "tarball=$(npm pack --silent)" >> "$GITHUB_OUTPUT"
+
+      - name: Install globally and run the CLI
+        env:
+          TARBALL: ${{ steps.pack.outputs.tarball }}
+        run: |
+          npm install -g "./$TARBALL"
+          deepl --version
+
+      # From a throwaway consumer package, because Node does not resolve
+      # bare specifiers out of the global prefix.
+      - name: Import the package entry as a dependency
+        env:
+          TARBALL: ${{ steps.pack.outputs.tarball }}
+        run: |
+          tarball_path="$PWD/$TARBALL"
+          consumer="$(mktemp -d)"
+          cd "$consumer"
+          npm init -y >/dev/null
+          npm install "$tarball_path"
+          node --input-type=module -e "
+            const m = await import('@deepl/cli');
+            const keys = Object.keys(m);
+            if (keys.length === 0) {
+              throw new Error('package entry resolved but exported nothing');
+            }
+            console.log('package entry exports:', keys.join(', '));
+          "
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 529896cf..7850a23b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -3,6 +3,10 @@ name: Release
 # This workflow only records the GitHub Release for a tag. Publishing to npm
 # happens from GitLab, so no `npm publish` step or NPM_TOKEN secret belongs in
 # this repository.
+#
+# GitHub is upstream: GitLab pull-mirrors this repository and publishes from
+# there, so a tag pushed here reaches the publish pipeline on its own. Never
+# hand-push to GitLab.
 on:
   push:
     tags:

From 979dacdb958f1f7c27cc75087587f7fb31f526ca Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 11:56:12 +0200
Subject: [PATCH 251/256] docs: record the Node 24.15.0 floor and document the
 shipped install paths

Changelog entries for the per-locale model_type fixes and the packaged-artifact
CI job, and the 2.0.0 heading moves to its actual release date.

The Node requirement is corrected wherever it was stated -- changelog, README,
migration guide, troubleshooting guide and contributor guide -- including why
the floor is a minor rather than a major, since "Node 24 or later" is no longer
sufficient advice. The troubleshooting entry keeps nvm install 24 as the remedy,
which lands past the floor.

Homebrew and npm are now described as available rather than pending, and the
README leads with brew install deepl/tap/deepl: it is the only Node-free path,
because the formula brings its own Node, and it hides the package scope. The
changelog's claim that GitLab mirrors to GitHub is corrected to the actual
direction.
---
 CHANGELOG.md            | 13 ++++++++-----
 CONTRIBUTING.md         |  2 +-
 README.md               | 22 ++++++++++------------
 docs/MIGRATION.md       | 10 ++++++----
 docs/TROUBLESHOOTING.md | 10 +++++-----
 5 files changed, 30 insertions(+), 27 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a923357..26c697e2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,9 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.0.0] - 2026-08-09
+## [2.0.0] - 2026-08-10
 
-**Breaking:** the package is published as **`@deepl/cli`** and requires **Node.js 24 or later**. Several exit codes moved, and under `--format json` a failing command now writes its error envelope to stdout. Every breaking change is covered with before/after examples in **[docs/MIGRATION.md](docs/MIGRATION.md)** — read it before upgrading, starting with [Exit codes that moved](docs/MIGRATION.md#exit-codes-that-moved).
+**Breaking:** the package is published as **`@deepl/cli`** and requires **Node.js 24.15.0 or later**. Several exit codes moved, and under `--format json` a failing command now writes its error envelope to stdout. Every breaking change is covered with before/after examples in **[docs/MIGRATION.md](docs/MIGRATION.md)** — read it before upgrading, starting with [Exit codes that moved](docs/MIGRATION.md#exit-codes-that-moved).
 
 ### Added
 
@@ -25,13 +25,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **http**: `NO_PROXY` / `no_proxy` are honoured with the standard semantics — `*` for everything, a leading dot or `*.` for subdomains, and an optional `host:port` that must agree — so a corporate `HTTPS_PROXY` is no longer applied to a request aimed at localhost.
 - **auth**: `deepl auth set-key --no-verify` stores a key without validating it against the API. Validation ran before persisting, so on a network without proxy configuration both documented setup paths (`auth set-key` and `init`) failed and discarded the key; an unreachable API now also names `DEEPL_API_KEY` as the zero-network alternative.
 - **cli**: `t` and `w` command aliases for `translate` and `write` ([#12](https://github.com/DeepL/deepl-cli/issues/12)), shown in `--help` output and in bash/zsh/fish completions. `w` is deliberately assigned to `write` rather than `watch`.
-- **ci**: Pushing a `v*` tag creates a GitHub Release, with notes extracted from that version's CHANGELOG section and generated notes as a fallback. The tag is checked against `package.json` first, so a mislabelled tag cannot mint a Release whose title disagrees with the version it contains. The workflow does **not** publish to npm — releases are published from GitLab, which mirrors to GitHub.
+- **ci**: Pushing a `v*` tag creates a GitHub Release, with notes extracted from that version's CHANGELOG section and generated notes as a fallback. The tag is checked against `package.json` first, so a mislabelled tag cannot mint a Release whose title disagrees with the version it contains. The workflow does **not** publish to npm: GitHub is upstream, GitLab pull-mirrors this repository, and the publish runs from there — so the tag pushed here reaches the publish pipeline on its own.
+- **ci**: A `Packaged artifact` job packs the tarball, installs it globally to run `deepl --version`, then installs it into a throwaway consumer package and imports `@deepl/cli`, asserting the entry exports something. The suites run from the working tree and `bin` has its own module graph, so a broken programmatic entry point could otherwise ship while every test passed. The test matrix also pins `24.15.0` alongside `24`, so the `engines.node` floor is exercised rather than only the latest 24.x.
 - **ci**: `npm run check-deps` fails the build when a package imported by `src/` is missing from `dependencies`, including one declared only under `devDependencies`. It runs in CI and in the publish job, and matches package names as quoted strings so indirect loads such as `requireModule('php-parser')` count as references.
 
 ### Changed
 
 - **BREAKING — package**: The package is now published as the scoped **`@deepl/cli`** (previously the unpublished working name `deepl-cli`), with `publishConfig.access: "public"` set explicitly. The `bin` name is unchanged — the command is still `deepl` — so scoping changes only the install string (`npm install -g @deepl/cli`). Repository, bugs and homepage metadata now point at `github.com/DeepL/deepl-cli` directly.
-- **BREAKING — cache/runtime**: The translation cache now uses Node's built-in `node:sqlite` instead of the `better-sqlite3` native addon, and the CLI consequently requires **Node.js >= 24** (`engines.node` is now `>=24.0.0`) — Node 24 is the first release where `node:sqlite` is non-experimental. Running under an older Node fails fast with a clear one-line error (exit 6) instead of surfacing a raw `ExperimentalWarning` or crashing later. Existing cache databases are read in place with no migration; the on-disk format is unchanged. **Migration**: upgrade to Node 24, e.g. `nvm install 24`.
+- **BREAKING — cache/runtime**: The translation cache now uses Node's built-in `node:sqlite` instead of the `better-sqlite3` native addon, and the CLI consequently requires **Node.js >= 24.15.0** (`engines.node` is now `>=24.15.0`) — 24.15.0, not 24.0.0, is the release where `node:sqlite` stopped emitting `ExperimentalWarning: SQLite is an experimental feature`. The floor is therefore checked as a major *and* minor at startup: every 24.x below 24.15.0 would otherwise write that warning to stderr on each cache-backed command, which breaks callers that merge stderr into stdout and parse `--format json`. Running under an unsupported Node fails fast with a clear one-line error (exit 6) instead of surfacing the warning or crashing later. Existing cache databases are read in place with no migration; the on-disk format is unchanged. **Migration**: upgrade to a current Node 24, e.g. `nvm install 24`.
 - **BREAKING — cli**: A failing command with `--format json` now writes its `{ ok: false, error: { code, message, suggestion? }, exitCode }` envelope to **stdout** instead of prose on stderr, for every command that has a JSON mode — `translate`, `write`, `correct`, `voice`, `usage`, `languages`, `detect`, `glossary`, `tm`, `cache`, `config`, `hooks`, `admin`, `style-rules` — and for every `sync` subcommand at once, from one shared writer. `> out.json` now captures both the success payload and the failure envelope, and a human reading `--format json` output sees the envelope's `message`/`suggestion` fields where a prose sentence used to be. `config get`/`config list` default to `json`, so their failures carry the envelope with no flag passed. Warnings stay on stderr, exit codes remain the failure signal, and text/table modes are byte-identical. A malformed invocation that commander rejects before the command runs still prints commander's message on stderr at exit 6.
 - **BREAKING — cli**: Language codes are displayed in lowercase everywhere, replacing three mixed casings. `glossary show` now reports `Source language: en` and `en → es: 5 entries`, `tm list` renders `brand-terms (en → de, fr)`, `translate --format table` labels rows `de`, and `write --format json` reports `"language": "en-us"` — so **scripts scraping these values see a casing change**. Input is case-insensitive everywhere, so no command line has to change; `voice` included, which previously demanded the exact mixed-case spelling of a regional code (`--to zh-HANS`) and rejected the lowercase form the rest of the CLI prints. `write`/`correct` also send the lowercase code as `target_lang`, which the Write API canonicalizes server-side. Wire parameters that are not display output are untouched: `translate` and the glossary create endpoint still send uppercase `source_lang`/`target_lang`.
 - **BREAKING — sync**: `deepl sync` now exits **12** where it exited 0 in three cases: a locale whose target file it cannot read or parse (nothing is written for it rather than rebuilding it from the source), a key it could not write into the target file, and a translation that fails validation (the key is withheld and counted failed rather than written corrupt). `sync --frozen` exits 10 and `sync status` counts such keys against the locale; `validation.fail_on_error: true` still promotes a validation error to exit 6, and `SyncResult.success` is `false` for these runs. `deepl sync pull` reports an unreadable target as a new `unusable_target` skip reason at its existing exit code.
@@ -67,7 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **deps**: `commander` 14.0.3 → 15.0.0, which is ESM-only and requires Node >= 22.12.0, so it was unmergeable until the Node 24 baseline landed.
 - **ci**: The test matrix, release workflow and security workflow target Node 24 (previously 20 and 22), and `.nvmrc` pins Node 24 to match — it still read `20`, so `nvm use` handed developers a runtime that cannot load `node:sqlite`.
 - **build**: `npm run build` runs a `clean` step first, removing `dist/` and `tsconfig.tsbuildinfo` before compiling, so a file rename can no longer ship stale artifacts in `npm pack` output.
-- **docs**: The README leads with the npm install path (`npm install -g @deepl/cli`) and documents three install paths — npm, from source, and Homebrew (`brew install deepl/tap/deepl`, marked pending until the tap ships) — with an explicit Node.js 24 prerequisite replacing the `better-sqlite3` native-compilation caveat. Install strings are updated across `docs/SYNC.md`, four example scripts, `examples/README.md` and the git-hook template in `src/services/git-hooks.ts`. `CONTRIBUTING.md` states the Node 24 development prerequisite, `SECURITY.md`'s supported-versions table reflects that only 2.x is a published line, and six stale `DeepLcom` GitHub URLs now point at the `DeepL` org.
+- **docs**: The README documents three install paths — Homebrew (`brew install deepl/tap/deepl`, which brings its own Node), npm (`npm install -g @deepl/cli`) and from source — with an explicit Node.js 24.15.0 prerequisite replacing the `better-sqlite3` native-compilation caveat. Install strings are updated across `docs/SYNC.md`, four example scripts, `examples/README.md` and the git-hook template in `src/services/git-hooks.ts`. `CONTRIBUTING.md` states the Node 24 development prerequisite, `SECURITY.md`'s supported-versions table reflects that only 2.x is a published line, and six stale `DeepLcom` GitHub URLs now point at the `DeepL` org.
 - **tests**: A fast-check property suite (`tests/property/`) enforces round-trip laws across all 11 format parsers — translated values survive reconstruct/extract intact, re-applying the same translations never changes the file, and an identity sync is a fixed point — plus preservation laws for the placeholder and ICU utilities. Runs are seeded-random with 200 cases per law (`FC_NUM_RUNS` overrides; `FC_SEED`/`FC_PATH` replay a recorded counterexample). It found the TOML U+2028 corruption and the `.properties` leading-space loss fixed in this release.
 
 ### Removed
@@ -83,6 +84,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: `translation.locale_overrides.<locale>.model_type` is now applied. The key was on the config allowlist and validated per locale against `translation_memory`, but the translator only ever read the top-level `translation.model_type`, so the per-locale value was silently dropped — and the validator's own error message named that inert scope as the remedy. A locale that configures translation memory per locale therefore got requests the TM could not be applied to, silently, and was billed for them. The override now resolves exactly like its siblings (`formality`, `translation_memory_threshold`, `custom_instructions`, `style_id`): the per-locale value wins, otherwise the top-level one applies. `SyncLocaleOverrides` also declares the field, and — as with those siblings — a per-locale override now takes precedence over `--model-type`.
+- **sync**: A per-locale `translation_memory` that *inherits* a non-`quality_optimized` top-level `model_type` is now rejected at config load (exit 7) instead of being accepted and sent to the API. The pairing check only looked at a `model_type` written inside the same override, so the mirror case — TM set per locale, model type inherited — passed validation and produced the same silent billing hazard. The check now evaluates the effective value for that locale and names where the offending one came from.
 - **sync**: The first `deepl sync` over an already-translated project no longer overwrites every reviewer translation with machine output. The carry-forward that protects a reviewed translation was wired into the `current`-key path only, so with no `.deepl-sync.lock` — first adoption, or any CI checkout where the lockfile is gitignored — every key arrived as `new` and was re-translated, re-billed and written over, dropping `#, fuzzy` and XLIFF `state` markers at exit 0. A `new` key whose target file already holds a translation is now carried forward untouched and recorded in the lockfile. A target value equal to the source, or an empty one, is still translated, and `--force` still re-translates everything.
 - **sync**: A reviewed PO or XLIFF translation is no longer replaced with source text. Both formats are bilingual, and every path that needed "the translation this target file already holds" read the *source* side (`msgid` / `<source>`) — six call sites, including `sync push` and `sync validate`. Parsers may now override the target-side read (`FormatParser.extractTranslations`), PO and XLIFF do, and all six sites go through one helper. An empty `msgstr`, a missing `<target>` and an empty `<target></target>` now read as *untranslated*, so such a key is translated rather than having the source pinned into it; in the monolingual formats an empty value is still a deliberate translation and is preserved. `deepl sync pull` had the same blind spot in its merge base and `deepl sync audit` measured consistency across source strings rather than translations.
 - **sync**: `deepl sync push` no longer uploads the source language as a locale's translation — a `locales/es/app.po` holding `msgstr "Hola amigo"` used to push the English msgid, making the TMS authoritative for the wrong text. `TmsClient.pushEntry` now takes the translation as a required argument rather than reading it off `entry.value`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1c9a9e84..7fd7d6c6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,7 +12,7 @@ project maintainer.
 
 ## Prerequisites
 
-- **Node.js** >= 24.0.0
+- **Node.js** >= 24.15.0 (the release where `node:sqlite` stopped being experimental)
 - **npm** >= 9.0.0
 - A [DeepL API key](https://www.deepl.com/pro-api) (free tier works for development)
 
diff --git a/README.md b/README.md
index 49afb1dd..37f75a20 100644
--- a/README.md
+++ b/README.md
@@ -58,7 +58,15 @@ For security policy and vulnerability reporting, see [SECURITY.md](https://githu
 
 ## 📦 Installation
 
-> **Prerequisite:** Node.js **24 or later**. The cache uses Node's built-in [`node:sqlite`](https://nodejs.org/api/sqlite.html) module — no native compilation, no build toolchain needed.
+> **Prerequisite:** Node.js **24.15.0 or later**. The cache uses Node's built-in [`node:sqlite`](https://nodejs.org/api/sqlite.html) module — no native compilation, no build toolchain needed. 24.15.0 is the release where `node:sqlite` stopped being experimental; Homebrew installs a suitable Node for you.
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew install deepl/tap/deepl
+```
+
+This installs the `deepl` command and everything it needs, including Node.
 
 ### npm
 
@@ -71,16 +79,6 @@ deepl --version
 
 The package is scoped, but the command is just `deepl`.
 
-### Homebrew (macOS / Linux)
-
-_Not available yet. The `deepl/tap` formula is planned; until it exists, install with npm._
-
-```bash
-brew install deepl/tap/deepl
-```
-
-Once available, this installs the `deepl` command and everything it needs, including Node.
-
 ### From Source
 
 ```bash
@@ -103,7 +101,7 @@ deepl --version
 
 ## 🔀 Upgrading from 1.x
 
-2.0.0 requires Node 24, renames the package to `@deepl/cli`, removes several
+2.0.0 requires Node 24.15.0, renames the package to `@deepl/cli`, removes several
 deprecated flags, and changes a number of exit codes and output shapes that scripts
 read. If you have a pipeline built on 1.x, read
 **[docs/MIGRATION.md](https://github.com/DeepL/deepl-cli/blob/main/docs/MIGRATION.md)** before upgrading — it lists every
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
index 2ed343cd..19238503 100644
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -22,11 +22,13 @@ removed flag it does not announce itself.
 
 ## Requirements
 
-**Node.js 24 or later** — up from 20. The cache now uses Node's built-in
+**Node.js 24.15.0 or later** — up from 20. The cache now uses Node's built-in
 `node:sqlite` instead of the `better-sqlite3` native addon, so there is no
 compilation step and no `ERR_DLOPEN_FAILED` after a Node upgrade, but the runtime
-floor is higher. Running under an older Node fails fast with a one-line error and
-exit 6 rather than crashing later.
+floor is higher. 24.15.0 is the release where `node:sqlite` stopped emitting an
+`ExperimentalWarning`, which would otherwise reach stderr on every cache-backed
+command. Running under an older Node fails fast with a one-line error and exit 6
+rather than crashing later.
 
 **The package is published as `@deepl/cli`.** The command is still `deepl`.
 
@@ -337,7 +339,7 @@ assigned it *to* a `WriteLanguage` variable needs a check or a cast.
 
 ## Upgrade checklist
 
-1. Move to Node 24 and reinstall from `@deepl/cli`.
+1. Move to Node 24.15.0 or later and reinstall from `@deepl/cli` (or `brew install deepl/tap/deepl`).
 2. Remove `--enable-beta-languages`; rename `sync init --source-lang`/`--target-langs`.
 3. Delete `tms.auto_push`, `tms.auto_pull` and `tms.require_review` from `.deepl-sync.yaml`.
 4. Add `--yes` to any non-interactive `deepl sync --force`.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 9a17b496..53381849 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -417,11 +417,11 @@ deepl languages --target
 
 ### Unsupported Node.js version
 
-The CLI exits 6 with a single line naming the required and the running version — `requires Node.js >= 24, you are running v22.11.0. Upgrade Node.js to use the DeepL CLI.`
+The CLI exits 6 with a single line naming the required and the running version — `requires Node.js >= 24.15.0, you are running v22.11.0. Upgrade Node.js to use the DeepL CLI.`
 
-**Cause:** The CLI requires Node.js 24 or later and checks the version at startup, before loading anything else, so an unsupported runtime gets that one line instead of an experimental-module warning or a later crash.
+**Cause:** The CLI requires Node.js 24.15.0 or later and checks the version at startup, before loading anything else, so an unsupported runtime gets that one line instead of an experimental-module warning or a later crash. The floor is a minor version because `node:sqlite` emits `ExperimentalWarning` on every earlier 24.x, including 24.0.0 — so a Node that satisfies "24 or later" is not necessarily enough.
 
-**Solution:** upgrade Node.js — e.g. `nvm install 24 && nvm use 24`, or install Node 24 from [nodejs.org](https://nodejs.org/). Confirm with `node --version` that the runtime invoking `deepl` is the upgraded one; a globally linked CLI can otherwise still run under an older default.
+**Solution:** upgrade Node.js — e.g. `nvm install 24 && nvm use 24`, or install Node 24 from [nodejs.org](https://nodejs.org/); both give a current 24.x, which is past the floor. Confirm with `node --version` that the runtime invoking `deepl` is the upgraded one; a globally linked CLI can otherwise still run under an older default.
 
 ---
 
@@ -454,11 +454,11 @@ deepl cache enable
 
 ### "Translation cache backend failed to load"
 
-**Cause:** The cache uses Node's built-in `node:sqlite` module and the runtime could not load it. Running on Node.js older than 24 is reported earlier and separately — see [Unsupported Node.js version](#unsupported-nodejs-version) — so what reaches this message is a runtime that reports version 24 or later but still has no usable `node:sqlite`: a Node built without SQLite support, or a non-Node runtime claiming a compatible version.
+**Cause:** The cache uses Node's built-in `node:sqlite` module and the runtime could not load it. Running on Node.js older than 24.15.0 is reported earlier and separately — see [Unsupported Node.js version](#unsupported-nodejs-version) — so what reaches this message is a runtime that reports a supported version but still has no usable `node:sqlite`: a Node built without SQLite support, or a non-Node runtime claiming a compatible version.
 
 Translation and write commands keep working with caching disabled for the run; your cache database is not modified. `deepl cache` subcommands fail until the module loads.
 
-**Solution:** run the CLI on an official Node.js 24+ build — e.g. `nvm install 24 && nvm use 24`, or install Node 24 from [nodejs.org](https://nodejs.org/). To confirm the module is the problem, check that `node -e "require('node:sqlite')"` succeeds on the same runtime.
+**Solution:** run the CLI on an official Node.js build at 24.15.0 or later — e.g. `nvm install 24 && nvm use 24`, or install Node 24 from [nodejs.org](https://nodejs.org/). To confirm the module is the problem, check that `node -e "require('node:sqlite')"` succeeds on the same runtime.
 
 ---
 

From ba2586f42020ce907019ca16c2f2c619720141d8 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 12:25:51 +0200
Subject: [PATCH 252/256] fix(sync): identify a reclaimed pidfile by payload,
 not inode alone

Reclaiming a pidfile proven stale renames it aside and then confirms the
captured file is the one that was inspected, so a sync whose staleness verdict
was overtaken by a winner puts the winner's live pidfile back instead of
deleting it. That confirmation compared inode and device only.

An inode number is reused once the file holding it is unlinked, and a winner
reclaims the lock by unlinking and re-creating in the same directory. On ext4
the freed inode is handed straight back, so the winner's live pidfile compared
equal to the stale one it replaced and was deleted -- leaving both runs
believing they held the lock, writing the same target files and the same
lockfile. This is the concurrent-writer hazard the lock exists to prevent.

Identity now also requires the recorded pid and startedAt to agree, which a
different holder cannot satisfy, and a null payload can only match a payload
that is still unparseable. The reclaim re-reads through inspectPidFile, so the
payload and identity still come from one descriptor.

Found by CI, not locally: APFS allocates inodes monotonically and never reuses
them, so the existing race test passed on macOS across three full-suite runs
and failed deterministically on both Linux matrix legs. The added test forces
the inode numbers to collide so the payload has to carry the verdict, which
makes the guard testable on any filesystem.
---
 src/sync/sync-process-lock.ts             | 44 +++++++++++++++++------
 tests/unit/sync/sync-process-lock.test.ts | 41 +++++++++++++++++++++
 2 files changed, 74 insertions(+), 11 deletions(-)

diff --git a/src/sync/sync-process-lock.ts b/src/sync/sync-process-lock.ts
index 0c8a0b74..1cbaea38 100644
--- a/src/sync/sync-process-lock.ts
+++ b/src/sync/sync-process-lock.ts
@@ -113,16 +113,42 @@ function inspectPidFile(pidFilePath: string): PidFileInspection | null {
   }
 }
 
+/**
+ * True when a captured file is the very file that was inspected, rather than a
+ * replacement written by a sync that won the race.
+ *
+ * Inode and device alone cannot answer this. An inode number is reused once the
+ * file holding it is unlinked, and a winner reclaims the lock by unlinking and
+ * re-creating in the same directory — on ext4 that hands the freed inode
+ * straight back, so the replacement compares equal. The recorded payload is
+ * what actually distinguishes them: a different holder carries a different
+ * `pid` and `startedAt`. Identity therefore requires both to agree, and content
+ * no sync wrote (a null payload) can only ever be matched by content that is
+ * still unparseable.
+ */
+function isSameFile(
+  captured: PidFileInspection,
+  stale: PidFileInspection
+): boolean {
+  if (captured.ino !== stale.ino || captured.dev !== stale.dev) return false;
+  if (stale.payload === null) return captured.payload === null;
+  if (captured.payload === null) return false;
+  return (
+    captured.payload.pid === stale.payload.pid &&
+    captured.payload.startedAt === stale.payload.startedAt
+  );
+}
+
 /**
  * Removes a pidfile already proven stale, without ever removing one this
  * process has not taken possession of.
  *
  * rename(2) is atomic, so of several syncs racing to break the same stale lock
  * exactly one can move that directory entry aside; the others get ENOENT.
- * Checking the inode *after* the move is what closes the read/unlink race: a
- * process whose staleness verdict has been overtaken by a winner captures the
- * winner's file, sees a different inode, and puts it back instead of deleting a
- * live lock.
+ * Re-reading the captured file *after* the move is what closes the read/unlink
+ * race: a process whose staleness verdict has been overtaken by a winner
+ * captures the winner's file, fails the identity check, and puts it back
+ * instead of deleting a live lock.
  *
  * Returns true when the stale file is gone and the lock is free to retake.
  */
@@ -139,14 +165,10 @@ function reclaimStalePidFile(
     throw err;
   }
 
-  let captured: fs.Stats;
-  try {
-    captured = fs.statSync(capturedPath);
-  } catch {
-    return false;
-  }
+  const captured = inspectPidFile(capturedPath);
+  if (captured === null) return false;
 
-  if (captured.ino !== stale.ino || captured.dev !== stale.dev) {
+  if (!isSameFile(captured, stale)) {
     try {
       fs.renameSync(capturedPath, pidFilePath);
     } catch {
diff --git a/tests/unit/sync/sync-process-lock.test.ts b/tests/unit/sync/sync-process-lock.test.ts
index 30e3d232..726b5eab 100644
--- a/tests/unit/sync/sync-process-lock.test.ts
+++ b/tests/unit/sync/sync-process-lock.test.ts
@@ -463,6 +463,47 @@ describe('acquireSyncProcessLock', () => {
       expect(ownerPid()).toBe(winnerPid);
     });
 
+    /**
+     * The same race, on a filesystem that hands the freed inode straight back to
+     * the winner's replacement file — ext4 does, APFS does not. Identity cannot
+     * rest on the inode, so this forces the numbers to collide and leaves the
+     * recorded payload as the only thing telling the two files apart.
+     */
+    it('leaves a live pidfile alone even when the replacement reuses the inode', () => {
+      const winnerPid = 5555;
+      plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });
+      const staleIdentity = fs.statSync(pidFilePath);
+      const realKill = process.kill.bind(process);
+
+      jest
+        .spyOn(process, 'kill')
+        .mockImplementation((pid: number, signal?: string | number) => {
+          if (pid === 4242) {
+            fs.rmSync(pidFilePath, { force: true });
+            plantPidFile({
+              pid: winnerPid,
+              startedAt: '2026-06-01T00:00:00.000Z',
+            });
+            throw errnoError('ESRCH');
+          }
+          if (pid === winnerPid) return true;
+          return realKill(pid, signal);
+        });
+
+      // Report the stale file's inode for whatever the reclaim captures, so the
+      // cheap identity check passes and the payload has to carry the verdict.
+      const realFstat = fsModule.fstatSync.bind(fsModule);
+      jest.spyOn(fsModule, 'fstatSync').mockImplementation((fd: number) => {
+        const stats = realFstat(fd);
+        stats.ino = staleIdentity.ino;
+        stats.dev = staleIdentity.dev;
+        return stats;
+      });
+
+      expect(() => acquireSyncProcessLock(projectRoot)).toThrow(ConfigError);
+      expect(ownerPid()).toBe(winnerPid);
+    });
+
     it('reports the running sync rather than a raw EEXIST when the freed slot is taken first', () => {
       const winnerPid = 5555;
       plantPidFile({ pid: 4242, startedAt: '2026-01-01T00:00:00.000Z' });

From 4b88ab4bed7dc6809313a57b210750361ad1ee2d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 12:26:05 +0200
Subject: [PATCH 253/256] fix(cli): escape backslashes in fish completion
 descriptions

Inside fish single quotes only \\ and \' carry meaning, but the fish generator
escaped descriptions by replacing ' alone. A description ending in a backslash
therefore escaped its own closing quote and ran the rest of the generated
complete(1) line into the description.

One helper now escapes backslashes first and quotes second, used at all four
fish sites. Escaping in the other order would double the backslashes the first
pass adds. The bash and zsh generators use the POSIX '\'' form and are
unaffected.

Not reachable by untrusted input -- the descriptions are this repo's own
command and option metadata -- so this is a correctness fix for generated
output rather than a security fix. It also clears four CodeQL
js/incomplete-sanitization alerts.
---
 src/cli/commands/completion.ts        | 19 +++++++++++++++----
 tests/unit/completion-command.test.ts | 23 +++++++++++++++++++++++
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/src/cli/commands/completion.ts b/src/cli/commands/completion.ts
index 3a43538e..34dbb87a 100644
--- a/src/cli/commands/completion.ts
+++ b/src/cli/commands/completion.ts
@@ -2,6 +2,17 @@ import type { Command } from 'commander';
 
 export type ShellType = 'bash' | 'zsh' | 'fish';
 
+/**
+ * Escapes text for a fish single-quoted string, where only `\\` and `\'` carry
+ * meaning. Backslashes go first: escaping the quotes first would leave the
+ * backslashes this adds to be doubled by the second pass, and a description
+ * ending in a backslash would otherwise escape the closing quote and run the
+ * rest of the generated line together with it.
+ */
+function escapeFishSingleQuoted(text: string): string {
+  return text.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
 export class CompletionCommand {
   private readonly program: Command;
 
@@ -239,7 +250,7 @@ _deepl "$@"
       const cmd = this.findCommand(cmdName);
       const desc = cmd ? cmd.description() : '';
       lines.push(
-        `complete -c deepl -n '${noSubcmdCondition}' -a '${cmdName}' -d '${desc.replace(/'/g, "\\'")}'`
+        `complete -c deepl -n '${noSubcmdCondition}' -a '${cmdName}' -d '${escapeFishSingleQuoted(desc)}'`
       );
     }
 
@@ -253,7 +264,7 @@ _deepl "$@"
       if (shortFlag) {
         line += ` -s '${shortFlag}'`;
       }
-      line += ` -d '${desc.replace(/'/g, "\\'")}'`;
+      line += ` -d '${escapeFishSingleQuoted(desc)}'`;
       lines.push(line);
     }
 
@@ -273,7 +284,7 @@ _deepl "$@"
       lines.push(`# ${parent} subcommands`);
       if (parentCmd) {
         for (const sub of this.visibleCommands(parentCmd)) {
-          const desc = sub.description().replace(/'/g, "\\'");
+          const desc = escapeFishSingleQuoted(sub.description());
           lines.push(
             `complete -c deepl -n '${seenCondition}${notSeenSub}' -a '${sub.name()}' -d '${desc}'`
           );
@@ -283,7 +294,7 @@ _deepl "$@"
       const cmdOpts = this.getCommandOptions(parent);
       for (const opt of cmdOpts) {
         const optObj = parentCmd?.options.find((o) => o.long === opt);
-        const desc = optObj ? optObj.description.replace(/'/g, "\\'") : '';
+        const desc = optObj ? escapeFishSingleQuoted(optObj.description) : '';
         const longFlag = opt.replace(/^--/, '');
         lines.push(
           `complete -c deepl -n '${seenCondition}' -l '${longFlag}' -d '${desc}'`
diff --git a/tests/unit/completion-command.test.ts b/tests/unit/completion-command.test.ts
index 6d598a74..25f956e2 100644
--- a/tests/unit/completion-command.test.ts
+++ b/tests/unit/completion-command.test.ts
@@ -202,6 +202,29 @@ describe('CompletionCommand', () => {
       const script = completionCommand.generate('fish');
       expect(script).toContain('.config/fish/completions/deepl.fish');
     });
+
+    // Inside fish single quotes only \\ and \' carry meaning, so a backslash has
+    // to be escaped before the quotes are. Escaping quotes alone leaves a
+    // description ending in a backslash escaping its own closing quote, which
+    // runs the rest of the generated line into the description.
+    it('should escape backslashes as well as quotes in descriptions', () => {
+      const prog = new Command();
+      prog.name('deepl');
+      prog
+        .command('quirky')
+        .description("ends with a backslash \\ and has an ' apostrophe");
+
+      const script = new CompletionCommand(prog).generate('fish');
+      const line = script.split('\n').find((l) => l.includes("-a 'quirky'"));
+
+      expect(line).toBeDefined();
+      expect(line).toContain(
+        "-d 'ends with a backslash \\\\ and has an \\' apostrophe'"
+      );
+      // The closing quote survives: an unescaped trailing backslash would make
+      // the description swallow it.
+      expect(line!.endsWith("'")).toBe(true);
+    });
   });
 
   describe('edge cases', () => {

From 3bbef6063173d5ee8ee896b9dfa0a4e6596ff447 Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 12:26:16 +0200
Subject: [PATCH 254/256] docs(changelog): record the pidfile identity and fish
 escaping fixes

Both under 2.0.0 Fixed. The lock entry states the filesystem dependence
explicitly, since the defect is invisible on APFS and deterministic on ext4.
---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26c697e2..5914703c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -84,6 +84,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **sync**: Two concurrent `deepl sync` runs in one directory can no longer both believe they hold the process lock. Reclaiming a pidfile already proven stale renames it aside and then confirms it is the same file before deleting it, but that confirmation compared inode and device only — and an inode number is reused once its file is unlinked, which is exactly what a sync winning the race does when it replaces the pidfile. On ext4 the freed inode comes straight back, so a winner's live pidfile compared equal to the stale one it replaced and was deleted, leaving both runs writing the same target files and the same lockfile. Identity now also requires the recorded `pid` and `startedAt` to match, which a different holder cannot satisfy. The behaviour was filesystem-dependent: APFS never reuses inodes, so this reproduced on Linux only.
+- **cli**: `deepl completion fish` no longer emits a broken line for a command or option whose description contains a backslash. Descriptions were escaped for the surrounding fish single quotes by replacing `'` only, so a trailing backslash escaped the closing quote and ran the rest of the generated line into the description. Backslashes are now escaped first, then quotes. The bash and zsh generators use the POSIX `'\''` form and were unaffected.
 - **sync**: `translation.locale_overrides.<locale>.model_type` is now applied. The key was on the config allowlist and validated per locale against `translation_memory`, but the translator only ever read the top-level `translation.model_type`, so the per-locale value was silently dropped — and the validator's own error message named that inert scope as the remedy. A locale that configures translation memory per locale therefore got requests the TM could not be applied to, silently, and was billed for them. The override now resolves exactly like its siblings (`formality`, `translation_memory_threshold`, `custom_instructions`, `style_id`): the per-locale value wins, otherwise the top-level one applies. `SyncLocaleOverrides` also declares the field, and — as with those siblings — a per-locale override now takes precedence over `--model-type`.
 - **sync**: A per-locale `translation_memory` that *inherits* a non-`quality_optimized` top-level `model_type` is now rejected at config load (exit 7) instead of being accepted and sent to the API. The pairing check only looked at a `model_type` written inside the same override, so the mirror case — TM set per locale, model type inherited — passed validation and produced the same silent billing hazard. The check now evaluates the effective value for that locale and names where the offending one came from.
 - **sync**: The first `deepl sync` over an already-translated project no longer overwrites every reviewer translation with machine output. The carry-forward that protects a reviewed translation was wired into the `current`-key path only, so with no `.deepl-sync.lock` — first adoption, or any CI checkout where the lockfile is gitignored — every key arrived as `new` and was re-translated, re-billed and written over, dropping `#, fuzzy` and XLIFF `state` markers at exit 0. A `new` key whose target file already holds a translation is now carried forward untouched and recorded in the lockfile. A target value equal to the source, or an empty one, is still translated, and `--force` still re-translates everything.

From b0558a0d0c3d07f64b63548f77fdd676d8ab562d Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 13:42:28 +0200
Subject: [PATCH 255/256] docs(ci): drop the release workflow's comments and
 the mirror-direction claim

The header comment asserted that GitHub is upstream and GitLab pull-mirrors from
it. That arrangement is being reworked and is owned outside this repository, so
the claim is not ours to make and would go stale in a public file. The remaining
comments are removed with it rather than left as a partial commentary; the step
names already say what each step does, and the release procedure lives in
CLAUDE.md.

The changelog entry loses the same claim: it now says only that the workflow does
not publish to npm, that publishing runs from a separate GitLab pipeline, and
that a tag records the Release and nothing more -- all of which is true
regardless of how the two copies are kept in sync.

Behaviour is unchanged. Verified the file still parses and keeps its v* tag
trigger, contents: write permission, and all four steps.
---
 .github/workflows/release.yml | 12 ------------
 CHANGELOG.md                  |  2 +-
 2 files changed, 1 insertion(+), 13 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7850a23b..392ab97a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,12 +1,5 @@
 name: Release
 
-# This workflow only records the GitHub Release for a tag. Publishing to npm
-# happens from GitLab, so no `npm publish` step or NPM_TOKEN secret belongs in
-# this repository.
-#
-# GitHub is upstream: GitLab pull-mirrors this repository and publishes from
-# there, so a tag pushed here reaches the publish pipeline on its own. Never
-# hand-push to GitLab.
 on:
   push:
     tags:
@@ -22,8 +15,6 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      # A tag can be pushed at any commit, so a mislabelled tag would otherwise
-      # mint a Release whose title disagrees with the version it contains.
       - name: Verify tag matches package version
         run: |
           tag_version="${GITHUB_REF_NAME#v}"
@@ -33,8 +24,6 @@ jobs:
             exit 1
           fi
 
-      # Release notes come from the tag's CHANGELOG section; releases are
-      # immutable once published, but notes stay editable afterwards.
       - name: Extract changelog section
         id: notes
         run: |
@@ -48,7 +37,6 @@ jobs:
             echo "has_notes=true" >> "$GITHUB_OUTPUT"
           fi
 
-      # Skipped when the release exists, so re-runs are idempotent.
       - name: Create GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5914703c..6db605f4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **http**: `NO_PROXY` / `no_proxy` are honoured with the standard semantics — `*` for everything, a leading dot or `*.` for subdomains, and an optional `host:port` that must agree — so a corporate `HTTPS_PROXY` is no longer applied to a request aimed at localhost.
 - **auth**: `deepl auth set-key --no-verify` stores a key without validating it against the API. Validation ran before persisting, so on a network without proxy configuration both documented setup paths (`auth set-key` and `init`) failed and discarded the key; an unreachable API now also names `DEEPL_API_KEY` as the zero-network alternative.
 - **cli**: `t` and `w` command aliases for `translate` and `write` ([#12](https://github.com/DeepL/deepl-cli/issues/12)), shown in `--help` output and in bash/zsh/fish completions. `w` is deliberately assigned to `write` rather than `watch`.
-- **ci**: Pushing a `v*` tag creates a GitHub Release, with notes extracted from that version's CHANGELOG section and generated notes as a fallback. The tag is checked against `package.json` first, so a mislabelled tag cannot mint a Release whose title disagrees with the version it contains. The workflow does **not** publish to npm: GitHub is upstream, GitLab pull-mirrors this repository, and the publish runs from there — so the tag pushed here reaches the publish pipeline on its own.
+- **ci**: Pushing a `v*` tag creates a GitHub Release, with notes extracted from that version's CHANGELOG section and generated notes as a fallback. The tag is checked against `package.json` first, so a mislabelled tag cannot mint a Release whose title disagrees with the version it contains. The workflow does **not** publish to npm — publishing runs from a separate GitLab pipeline, so a tag pushed here records the Release and nothing more.
 - **ci**: A `Packaged artifact` job packs the tarball, installs it globally to run `deepl --version`, then installs it into a throwaway consumer package and imports `@deepl/cli`, asserting the entry exports something. The suites run from the working tree and `bin` has its own module graph, so a broken programmatic entry point could otherwise ship while every test passed. The test matrix also pins `24.15.0` alongside `24`, so the `engines.node` floor is exercised rather than only the latest 24.x.
 - **ci**: `npm run check-deps` fails the build when a package imported by `src/` is missing from `dependencies`, including one declared only under `devDependencies`. It runs in CI and in the publish job, and matches package names as quoted strings so indirect loads such as `requireModule('php-parser')` count as references.
 

From 0360fade9f21279faf417a1186154bcee73efd8f Mon Sep 17 00:00:00 2001
From: Steven Syrek <steven.syrek@deepl.com>
Date: Mon, 10 Aug 2026 14:03:41 +0200
Subject: [PATCH 256/256] test(cache): drive the fresh-entry eviction test with
 fake timers

The test built a cache with ttl: 40 -- milliseconds -- then asserted, after
writing 'd' and 'e', that reading them back returns a value. Expiry is a
Date.now() comparison made when a row is read, so that assertion required fewer
than 40ms of wall clock to pass between the write and the read. On a CI runner
sharing a machine with three other Jest workers, one scheduler or GC pause
exceeds that and the entry legitimately expires, so the test failed while the
cache behaved correctly. It failed exactly that way on both matrix legs.

This was the only assertion in the suite that needed time NOT to pass. The two
other short-ttl tests assert toBeNull() after a sleep, which a slow runner only
makes more certain.

The cache holds no timers of its own, so fake timers control it exactly:
advanceTimersByTime expires a, b and c on demand, and no time at all passes
between writing d/e and reading them, so they cannot expire. A null there now
means only what the test is named for -- the sweep evicted a fresh row.

Verified the timers are doing the work rather than the assertions being vacuous:
with the advance removed, get('a') returns its stored value instead of null, so
the advance is what expires the rows and no real time is leaking in. Real timers
are restored in a finally block.
---
 tests/unit/cache-size-accounting.test.ts | 52 +++++++++++++++---------
 1 file changed, 33 insertions(+), 19 deletions(-)

diff --git a/tests/unit/cache-size-accounting.test.ts b/tests/unit/cache-size-accounting.test.ts
index dadaf9d3..119496d6 100644
--- a/tests/unit/cache-size-accounting.test.ts
+++ b/tests/unit/cache-size-accounting.test.ts
@@ -68,26 +68,40 @@ describe('CacheService size accounting', () => {
     svc.close();
   });
 
-  it('does not evict fresh entries after expired rows were deleted via get()', async () => {
-    const maxSize = 1500;
-    const svc = new CacheService({ dbPath, maxSize, ttl: 40 });
-
-    for (const key of ['a', 'b', 'c']) {
-      svc.set(key, 'x'.repeat(478)); // 480 bytes each, 1440 total
+  // Expiry is a Date.now() comparison made when a row is read, and the cache
+  // holds no timers of its own, so fake timers drive this exactly. They are also
+  // required rather than tidier: this is the one assertion in the suite that
+  // needs time NOT to pass, and against a real clock a scheduler pause between
+  // writing 'd' and reading it expires the entry and fails the test.
+  it('does not evict fresh entries after expired rows were deleted via get()', () => {
+    jest.useFakeTimers();
+    try {
+      const maxSize = 1500;
+      const ttl = 40;
+      const svc = new CacheService({ dbPath, maxSize, ttl });
+
+      for (const key of ['a', 'b', 'c']) {
+        svc.set(key, 'x'.repeat(478)); // 480 bytes each, 1440 total
+      }
+
+      jest.advanceTimersByTime(ttl * 2);
+
+      expect(svc.get('a')).toBeNull();
+      expect(svc.get('b')).toBeNull();
+      expect(svc.get('c')).toBeNull();
+
+      svc.set('d', 'x'.repeat(98)); // 100 bytes
+      svc.set('e', 'x'.repeat(98)); // 100 bytes; 200 total, far below the cap
+
+      // No time is advanced here, so neither entry can have expired: a null now
+      // means the sweep evicted a fresh row, which is the defect under test.
+      expect(svc.get('d')).not.toBeNull();
+      expect(svc.get('e')).not.toBeNull();
+
+      svc.close();
+    } finally {
+      jest.useRealTimers();
     }
-    await sleep(80);
-
-    expect(svc.get('a')).toBeNull();
-    expect(svc.get('b')).toBeNull();
-    expect(svc.get('c')).toBeNull();
-
-    svc.set('d', 'x'.repeat(98)); // 100 bytes
-    svc.set('e', 'x'.repeat(98)); // 100 bytes; 200 total, far below the cap
-
-    expect(svc.get('d')).not.toBeNull();
-    expect(svc.get('e')).not.toBeNull();
-
-    svc.close();
   });
 
   it('keeps enforcing the cap after sweeping rows another instance wrote', async () => {